s6
Software
skarnet.org

The s6-usertree-maker program

s6-usertree-maker creates a service directory implementing a service that runs a s6-svscan instance owned by a given user, on a scan directory belonging to that user. It is meant to help admins deploy systems where each user has their own supervision subtree, rooted in the main supervision tree owned by root.

Alternatively, s6-usertree-maker can create source definition directories for the s6-rc service manager.

Interface 

     s6-usertree-maker \
       [ -d userscandir ] \
       [ -p path ] \
       [ -E envdir [ -e var -e var ... ] ] \
       [ -r service/logger[/pipeline] ] \
       [ -l loguser ] \
       [ -t stamptype ] \
       [ -n nfiles ] \
       [ -s filesize ] \
       [ -S maxsize ] \
       user logdir dir

s6-usertree-maker creates a service directory in dir, that launches a supervision tree as user user on scan directory userscandir, with a catch-all logger logging the tree's output via s6-log to the logdir directory.

Exit codes

Options

Operation of the service

When the service is started, its run script will execute the following operations:

The service is logged: its stderr and stdout are piped to a s6-log process running as loguser and writing to the logdir directory. This logger is the catch-all logger for the supervision tree owned by user; it is recommended to make loguser distinct from user, and to have logdir in a place that is not under the control of user. If user wants to keep control of their logs, they can declare a logger for each of their services.

Variable substitution

When the service starts, the USER, HOME, UID, GID and GIDLIST environment variables are deduced from user's identity. The value of those variables may be used in a few configuration knobs:

When the strings ${USER}, ${HOME}, ${UID}, ${GID}, or ${GIDLIST} appear in the value for userscandir, path, or any of the var variables, they are substituted with the corresponding value of the USER, HOME, UID, GID, or GIDLIST environment variable instead.

For instance, if no -d option is provided, the default value for userscandir is ${HOME}/service. If the provided user is ska and ska's home directory is /home/ska, then s6-svscan will be run on /home/ska/service.

Examples 

     s6-usertree-maker -d '/run/user/${UID}/service' -p '${HOME}/bin:/usr/bin:/bin' -E /etc/user-env -e XDG_CONFIG_HOME -l catchlog ska /var/log/usertree/ska usertree-ska

creates a service directory in usertree-ska declaring a service that starts a supervision tree on /run/user/1000/service if ska has uid 1000, with /home/ska/bin:/usr/bin/bin as its PATH if ska's home directory is /home/ska, and with all the environment variables declared in /etc/user-env, among which the XDG_CONFIG_HOME variable is processed for variable substitution. The supervision tree has a catch-all logger running as user catchlog, and storing its data in the /var/log/usertree/ska directory.

Note that simple quotes are used here to prevent the shell from interpreting ${UID} and ${HOME}. 

     s6-usertree-maker -d '/run/user/${UID}/service' -p '${HOME}/bin:/usr/bin:/bin' -E /etc/user-env -e XDG_CONFIG_HOME -l catchlog -r usertree-ska/usertree-ska-log/usertree-ska-pipeline ska /var/log/usertree/ska usertree

Same as above, except it does not create a service directory — instead, it creates a usertree directory containing two subdirectories: usertree-ska, the s6-rc source definition directory for the service, and usertree-ska-log, the source definition directory for its logger. It also creates an implicit usertree-ska-pipeline bundle containing both the service and the logger.

Notes