From f481d14e9d9c5b2d57995aa0d9094500676e013e Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Thu, 7 Jan 2021 23:14:17 +0000 Subject: Add s6-usertree-maker --- doc/s6-usertree-maker.html | 240 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 240 insertions(+) create mode 100644 doc/s6-usertree-maker.html (limited to 'doc/s6-usertree-maker.html') diff --git a/doc/s6-usertree-maker.html b/doc/s6-usertree-maker.html new file mode 100644 index 0000000..4756006 --- /dev/null +++ b/doc/s6-usertree-maker.html @@ -0,0 +1,240 @@ + + + + + + s6: the s6-usertree-maker program + + + + + + +

+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. +

+ +

Example

+ +
+     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. +

+ +

Notes

+ + + + + -- cgit v1.2.3