s6-usertree-maker.html (12523B)
1 <html> 2 <head> 3 <meta name="viewport" content="width=device-width, initial-scale=1.0" /> 4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 5 <meta http-equiv="Content-Language" content="en" /> 6 <title>s6: the s6-usertree-maker program</title> 7 <meta name="Description" content="s6: the s6-usertree-maker program" /> 8 <meta name="Keywords" content="s6 command s6-usertree-maker user supervision tree s6-svscan" /> 9 <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> 10 </head> 11 <body> 12 13 <p> 14 <a href="index.html">s6</a><br /> 15 <a href="//skarnet.org/software/">Software</a><br /> 16 <a href="//skarnet.org/">skarnet.org</a> 17 </p> 18 19 <h1> The s6-usertree-maker program </h1> 20 21 <p> 22 s6-usertree-maker creates a <a href="servicedir.html">service directory</a> 23 implementing a service that runs an <a href="s6-svscan.html">s6-svscan</a> 24 process owned by a given user, on a <a href="scandir.html">scan directory</a> 25 belonging to that user. It is meant to help admins deploy systems where 26 each user has their own supervision subtree, rooted in the main supervision 27 tree owned by root. 28 </p> 29 30 <p> 31 Alternatively, s6-usertree-maker can create source definition directories 32 for the <a href="//skarnet.org/software/s6-rc/">s6-rc</a> service manager. 33 </p> 34 35 <h2> Interface </h2> 36 37 <pre> 38 s6-usertree-maker \ 39 [ -d <em>userscandir</em> ] \ 40 [ -p <em>path</em> ] \ 41 [ -E <em>envdir</em> [ -e <em>var</em> -e <em>var</em> ... ] ] \ 42 [ -r <em>service</em>/<em>logger</em>[/<em>pipeline</em>] ] \ 43 [ -l <em>loguser</em> ] \ 44 [ -t <em>stamptype</em> ] \ 45 [ -n <em>nfiles</em> ] \ 46 [ -s <em>filesize</em> ] \ 47 [ -S <em>maxsize</em> ] \ 48 [ -P <em>prefix</em> ] \ 49 user logdir dir 50 </pre> 51 52 <p> 53 s6-usertree-maker creates a service directory in <em>dir</em>, that launches 54 a supervision tree as user <em>user</em> on scan directory <em>userscandir</em>, 55 with a catch-all logger logging the tree's output via 56 <a href="s6-log.html">s6-log</a> to the <em>logdir</em> directory. 57 </p> 58 59 <h2> Exit codes </h2> 60 61 <ul> 62 <li> 0: success </li> 63 <li> 100: wrong usage </li> 64 <li> 111: system call failed </li> 65 </ul> 66 67 <h2> Options </h2> 68 69 <ul> 70 <li> <tt>-d</tt> <em>userscandir</em> : the supervision tree will be run 71 on the <em>userscandir</em> directory. <em>userscandir</em> is subject to variable 72 substitution (see below). Default is <strong><tt>${HOME}/service</tt></strong>. </li> <br /> 73 74 <li> <tt>-p</tt> <em>path</em> : the supervision tree will be run with a 75 PATH environment variable set to <em>path</em>. <em>path</em> is subject to variable 76 substitution. Default is <strong><tt>/usr/bin:/bin</tt></strong>, or whatever has been 77 given to the <tt>--with-default-path</tt> option to skalibs' configure script. </li> <br /> 78 79 <li> <tt>-E</tt> <em>envdir</em> : the supervision tree will be run with 80 the environment variables defined in the directory <em>envdir</em>, which will be 81 read via <a href="s6-envdir.html">s6-envdir</a> without options. By default, no 82 envdir is defined and the supervision tree will only be run with the basic 83 environment variables listed below. </li> <br /> 84 85 <li> <tt>-e</tt> <em>var</em> : Perform variable substitution on <em>var</em>. 86 This option is repeatable, and only makes sense when the <tt>-E</tt> option is also 87 given. For every <em>var</em> listed via a <tt>-e</tt> option, the contents of 88 <em>var</em> will be subjected to variable substitution before the supervision tree 89 is run. This is only useful if <em>var</em> is defined in <em>envdir</em>, as a 90 template, that is then instanced for <em>user</em> when the service is run. By 91 default, only the PATH environment variable, customizable via <tt>-p</tt>, is 92 subjected to variable substitution. </li> <br /> 93 94 <li> <tt>-r</tt> <em>service</em>/<em>logger</em>/<em>pipeline</em> : 95 create <a href="//skarnet.org/software/s6-rc">s6-rc</a> source definition directories. 96 When this option is given, <em>dir</em> is not created as a service directory, but 97 as a directory containing two services: <em>dir</em>/<em>service</em> and 98 <em>dir</em>/<em>logger</em>, and <em>dir</em> is suitable as a source argument to 99 <a href="//skarnet.org/software/s6-rc/s6-rc-compile.html">s6-rc-compile</a>. The 100 <tt>/</tt><em>pipeline</em> part can be omitted, but if it is present, <em>pipeline</em> 101 is used as a name for a bundle containing both <em>service</em> and <em>logger</em>. 102 When this option is not given, <em>dir</em> is a regular service directory for direct 103 inclusion (or linking) in the parent scan directory (and the catch-all logger for 104 the user subtree is declared in <em>dir</em><tt>/log</tt>). </li> <br /> 105 106 <li> <tt>-l</tt> <em>loguser</em> : run the catch-all logger of the user 107 subdirectory as user <em>loguser</em>. Default is <strong><tt>root</tt></strong>. </li> <br /> 108 109 <li> <tt>-t</tt> <em>stamptype</em> : how 110 logs are timestamped by the catch-all logger. 0 means no 111 timestamp, 1 means 112 <a href="https://cr.yp.to/libtai/tai64.html">external TAI64N format</a>, 113 2 means 114 <a href="https://www.iso.org/iso/home/standards/iso8601.htm">ISO 8601 format</a>, 115 and 3 means both. Default is <strong><tt>1</tt></strong>. </li> <br /> 116 117 <li> <tt>-n</tt> <em>nfiles</em> : maximum number of archive files 118 in <em>logdir</em>. Default is <strong><tt>10</tt></strong>. </li> <br /> 119 120 <li> <tt>-s</tt> <em>filesize</em> : maximum size of the <tt>current</tt> 121 file (and archive files) in <em>logdir</em>. Default is <strong><tt>1000000</tt></strong>. </li> <br /> 122 123 <li> <tt>-S</tt> <em>maxsize</em> : maximum total size of the 124 archives in the <em>logdir</em>. Default is <strong><tt>0</tt></strong>, 125 meaning no limits apart from those enforced by the <tt>-n</tt> and 126 <tt>-s</tt> options. </li> <br /> 127 128 <li> <tt>-P</tt> <em>prefix</em> : when logging to <em>logdir</em>, 129 prefix logged lines with the <em>prefix</em> string. </li> <br /> 130 </ul> 131 132 <h2> Operation of the service </h2> 133 134 <p> 135 When the service is started, its run script will execute the following 136 operations: 137 </p> 138 139 <ul> 140 <li> Clear all its environment variables, except PATH. This prevents 141 any data leak from the parent supervision tree into the user subtree. </li> 142 <li> Fill its environment with data related to <em>user</em>: 143 <ul> 144 <li> USER is set to <em>user</em> </li> 145 <li> HOME is set to <em>user</em>'s home directory </li> 146 <li> UID is set to <em>user</em>'s uid </li> 147 <li> GID is set to <em>user</em>'s primary gid </li> 148 <li> GIDLIST is set to <em>user</em>'s supplementary groups list </li> 149 </ul> </li> 150 <li> If the service has been created with the <tt>-E</tt> option to s6-usertree-maker: 151 <ul> 152 <li> Add all the variables defined in <em>envdir</em> to its environment </li> 153 <li> For every variable <em>var</em> given via a <tt>-e</tt> option, subject 154 <em>var</em> to substitution with the USER, HOME, UID, GID and GIDLIST variables 155 (see below). </li> 156 </ul> </li> 157 <li> Set the PATH environment variable to <em>path</em>, subjected to 158 variable substitution. </li> 159 <li> Execute into <a href="s6-svscan.html">s6-svscan</a>, running in 160 <em>userscandir</em> (which is first subjected to variable substitution). </li> 161 </ul> 162 163 <p> 164 The service is logged: its stderr and stdout are piped to an 165 <a href="s6-log.html">s6-log</a> process running as <em>loguser</em> and 166 writing to the <em>logdir</em> directory. This logger is the catch-all logger 167 for the supervision tree owned by <em>user</em>; it is recommended to make 168 <em>loguser</em> distinct from <em>user</em>, and to have <em>logdir</em> 169 in a place that is <strong>not</strong> under the control of <em>user</em>. 170 If <em>user</em> wants to keep control of their logs, they can declare a 171 logger for each of their services. 172 </p> 173 174 <h2> Variable substitution </h2> 175 176 <p> 177 When the service starts, the USER, HOME, UID, GID and GIDLIST 178 environment variables are deduced from <em>user</em>'s identity. 179 The value of those variables may be used in a few configuration 180 knobs: 181 </p> 182 183 <ul> 184 <li> The value of <em>userscandir</em>: it is likely that the 185 scan directory belonging to <em>user</em> resides under <em>user</em>'s 186 home directory. Or under <tt>/run/user/${UID}</tt>, or some similar 187 scheme. </li> 188 <li> The PATH environment variable, declared in <em>path</em>: it is 189 often useful to prepend the default system PATH with a user-specific 190 directory that hosts that user's binaries. For instance, you may want 191 the PATH to be set as something like <tt>${HOME}/bin:/usr/bin:/bin</tt>. </li> 192 <li> Any variable declared in <em>envdir</em> and given as an argument 193 to a <tt>-e</tt> option to s6-usertree-maker. If <em>envdir</em> is a 194 template valid for all users, it may contain variables that depends on 195 user-specific data: for instance, the XDG_CONFIG_HOME variable may be 196 set to <tt>${HOME}/.config</tt>. </li> 197 </ul> 198 199 <p> 200 When the strings <tt>${USER}</tt>, <tt>${HOME}</tt>, <tt>${UID}</tt>, 201 <tt>${GID}</tt>, or <tt>${GIDLIST}</tt> appear in the value for 202 <em>userscandir</em>, <em>path</em>, or any of the <em>var</em> 203 variables, they are substituted with the corresponding value of the USER, 204 HOME, UID, GID, or GIDLIST environment variable instead. 205 </p> 206 207 <p> 208 For instance, if no <tt>-d</tt> option is provided, the default value 209 for <em>userscandir</em> is <tt>${HOME}/service</tt>. If the provided 210 <em>user</em> is <tt>ska</tt> and ska's home directory is <tt>/home/ska</tt>, 211 then <a href="s6-svscan.html">s6-svscan</a> will be run on 212 <tt>/home/ska/service</tt>. 213 </p> 214 215 <h2> Examples </h2> 216 217 <pre> 218 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 219 </pre> 220 221 <p> 222 creates a service directory in <tt>usertree-ska</tt> declaring a service that 223 starts a supervision tree on <tt>/run/user/1000/service</tt> if ska has uid 1000, 224 with <tt>/home/ska/bin:/usr/bin/bin</tt> as its PATH if ska's home directory is 225 <tt>/home/ska</tt>, and with all the environment variables declared in 226 <tt>/etc/user-env</tt>, among which the XDG_CONFIG_HOME variable is processed 227 for variable substitution. The supervision tree has a catch-all logger running 228 as user catchlog, and storing its data in the <tt>/var/log/usertree/ska</tt> 229 directory. 230 </p> 231 232 <p> 233 Note that simple quotes are used here to prevent the shell from 234 interpreting <tt>${UID}</tt> and <tt>${HOME}</tt>. 235 </p> 236 237 <pre> 238 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 239 </pre> 240 241 <p> 242 Same as above, except it does not create a service directory — instead, it 243 creates a <tt>usertree</tt> directory containing two subdirectories: <tt>usertree-ska</tt>, the 244 <a href="//skarnet.org/software/s6-rc/">s6-rc</a> source definition directory 245 for the service, and <tt>usertree-ska-log</tt>, the source definition directory 246 for its logger. It also creates an implicit <tt>usertree-ska-pipeline</tt> bundle 247 containing both the service and the logger. 248 </p> 249 250 <h2> Notes </h2> 251 252 <ul> 253 <li> s6-usertree-maker makes use of the fact that 254 <a href="//skarnet.org/software/execline/">execline</a> scripts are much 255 easier to generate programmatically and to harden than shell scripts, so it is only 256 built if s6 is built with <a href="//skarnet.org/software/execline/">execline</a> 257 support - i.e. the <tt>--disable-execline</tt> switch has <em>not</em> been given 258 to configure. </li> 259 <li> For the admin who wants to automate user tree management, s6-usertree-maker 260 is a <em>building block</em> meant to be used in scripts, not a complete turnkey 261 solution. For instance, s6-usertree-maker does not create <em>userscandir</em> for 262 a user: it assumes that that scandir is already in place. It does not create 263 <em>logdir</em> either: <em>logdir</em>, or at least its parent directory, must 264 already exist before the logger is run, else <a href="s6-log.html">s6-log</a> will 265 fail repeatedly. Make sure that all the data and metadata referenced by the service's 266 and the logger's run scripts are actually present and valid before starting the 267 service. </li> 268 <li> If s6-usertree-maker encounters failure (and exits 111), it does not clean up 269 the directories it created. Make sure to always test s6-usertree-maker's return code 270 and clean up after it if needed. </li> 271 </ul> 272 273 </body> 274 </html>