s6
Software
skarnet.org

# The `s6-svperms` program

`s6-svperms` allows the user to see, or modify, for a given list of services: who can read their states, who can send them control commands, and who can subscribe to up/down events for those services.

## Interface

         s6-svperms [ -v ] [ -u | -g group | -G group | -o | -O group ] [ -e | -E group ] servicedirs...

Without options, or with only the `-v` option, `s6-svperms` prints 3 lines to stdout for every service directory listed in servicedirs. Every line contains the name of the service directory, then the following information:

- `status:` - indicates who is allowed to read status information on the service, with commands such as s6-svstat or s6-svdt. The values can be `owner`, for only the owner of the service; `group: name`, for the owner and members of group name; or `public`, for all users.
- `control:` - indicates who is allowed to send control commands to the service, with commands such as s6-svc. The values can be `owner`, for only the owner of the service; or `group: name`, for the owner and members of group name.
- `events:` - indicates who is allowed to subscribed to events sent by s6-supervise for this service, with commands such as s6-svwait or s6-svlisten1. The values can be `group: name`, for the owner and members of group name, or `public`, for all users.

If something goes wrong while reading a part of the configuration of a service directory, `s6-svperms` does not print the corresponding line to stdout; instead, it prints a warning message to stderr.

When invoked with other options, `s6-svperms` modifies the permissions of the service directories listed in servicedirs... as specified by the options. The same permissions will be applied to all the services listed in servicedirs....

## Options

- `-v` : re-read the permissions after writing them, and print them to stdout.
- `-u` : restrict the `status:` and `control:` permissions to `owner`: only the owner of a service directory will be able to read its state or control the service. This is the default when s6-supervise starts a service for the first time.
- `-g group` : allow members of group group to read the status of the service, but not to control it - control will be restricted to the owner.
- `-G group` : allow members of group group to read and control the service.
- `-o` : allow everyone to read the status of the service, but restrict `control:` to the owner.
- `-O group` : allow everyone to read the status, and allow members of group group to control the service.
- `-e` : allow everyone to subscribe to events.
- `-E group` : only allow members of group group to subscribe to events. This is the default when s6-supervise starts a service for the first time, with group being the primary group of the s6-supervise process (most likely `root`).

group is normally a group name that will be searched in the group database. But if it starts with a colon (`:`), the rest of group will be interpreted as a numerical gid, and the group database will not be read.

## Exit codes

- 0: success
- 1: something went wrong when reading permissions in one of the service directories
- 100: wrong usage
- 111: system call failed

## Notes

- The default (restrictive) permissions are safe.
- Unless operation of a service is restricted information, it is also safe to make `status:` more permissive.
- Opening `control:` to a group can be useful for instance in a shared administration situation when individual administrators are not given full root powers.
- Making `events:` public bears a small risk of a local DoS attack preventing more subscriptions to events, so it is not recommended for supervision trees where such subscriptions are critical to operations - such as a set of root services managed by s6-rc.