s6-instance-maker.html (8940B)
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-instance-maker program</title> 7 <meta name="Description" content="s6: the s6-instance-maker program" /> 8 <meta name="Keywords" content="s6 command s6-instance-maker instance dynamic instantiation instanced services" /> 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-instance-maker program </h1> 20 21 <p> 22 s6-instance-maker creates a <a href="servicedir.html">service directory</a> 23 implementing an <a href="instances.html">instanced service</a>. Give it a 24 templated service directory describing how to run an instance of a service, 25 and it will create a different service directory that can launch and 26 manage several instances; each of these instances will be running a 27 copy of the service directory you gave. 28 </p> 29 30 <p> 31 Alternatively, s6-instance-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-instance-maker \ 39 [ -c <em>maxinstances</em> ] \ 40 [ -r <em>service</em>[/<em>logger</em>[/<em>pipeline</em>]] ] \ 41 [ -u <em>user</em> ] \ 42 [ -l <em>loguser</em> ] \ 43 [ -L <em>logdir</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 template dir 50 </pre> 51 52 <p> 53 s6-instance-maker creates a service directory in <em>dir</em> (which must 54 not already exist). The created service will be a supervisor for a set of 55 instances — initially empty — 56 each running a copy of the service directory given in <em>template</em>. 57 </p> 58 59 <p> 60 s6-instance-maker is an <em>offline</em> tool: it is run before you need 61 instances. Once the created service directory is live, i.e. there is a 62 supervisor running on it, then you can create and delete individual instances via the 63 <a href="s6-instance-create.html">s6-instance-create</a> and 64 <a href="s6-instance-delete.html">s6-instance-delete</a> 65 <em>online</em> tools, that work with active services. 66 </p> 67 68 <h2> Exit codes </h2> 69 70 <ul> 71 <li> 0: success </li> 72 <li> 100: wrong usage </li> 73 <li> 111: system call failed </li> 74 </ul> 75 76 <h2> Options </h2> 77 78 <ul> 79 <li> <tt>-c</tt> <em>max</em> : Plan for a maximum of <em>max</em> 80 instances. Default is <strong>500</strong>. You can't set it lower than 2 or 81 higher than 90000. If your template service directory is logged, it's unadvisable 82 to set this above the default. </li> <br> 83 84 <li> <tt>-r</tt> <em>service</em>[/<em>logger</em>[/<em>pipeline</em>]] : 85 create <a href="//skarnet.org/software/s6-rc">s6-rc</a> source definition directories. 86 When this option is given, <em>dir</em> is not created as a service directory, but 87 as a directory containing at least one service: <em>dir</em>/<em>service</em>. 88 <em>dir</em> is suitable as a source argument to 89 <a href="//skarnet.org/software/s6-rc/s6-rc-compile.html">s6-rc-compile</a>. If 90 a <em>logger</em> part is given, then a second service, <em>dir</em>/<em>logger</em>, 91 is also created, as a consumer for <em>dir</em>/<em>service</em>, and the <tt>-L</tt> 92 option must also be used, to provide a directory to store the logs into. If the 93 <tt>/</tt><em>pipeline</em> part is also given, <em>pipeline</em> 94 is used as a name for a bundle containing both <em>service</em> and <em>logger</em>. 95 When the <tt>-r</tt> option is not given at all, <em>dir</em> is a regular service 96 directory for direct inclusion (or linking) in a host 97 <a href="scandir.html">scan directory</a>, and if the <tt>-L</tt> option is given 98 then the logger for the instance supervisor and all its instances is declared in 99 <em>dir</em><tt>/log</tt>. </li> <br> 100 101 <li> <tt>-u</tt> <em>user</em> : run the instance supervisor, and all 102 of the instances, as user <em>user</em>. This option should only be used when the 103 supervision tree that will host the instanced service is run as root. The default 104 is that the service runs as the same user as the host supervision tree. </li> <br> 105 106 <li> <tt>-l</tt> <em>loguser</em> : run the logger of the instance 107 supervisor, if any (see <tt>-L</tt> below) as user <em>loguser</em>. This option 108 should only be used when the 109 supervision tree that will host the instanced service is run as root. The default 110 is that the logger runs as the same user as the host supervision tree. </li> <br> 111 112 <li> <tt>-L</tt> <em>logdir</em> : make the service logged via 113 <a href="s6-log.html">s6-log</a>, and ensure its log messages go into <em>logdir</em>. 114 Error messages from the instance supervisor as well as from every instance will 115 be logged to <em>logdir</em>. If this option is not given, these error messages 116 will fall through to the host supervision tree's catch-all logger, if any, 117 or standard error otherwise. <br> 118 The options listed below are only used to configured the logger and are meaningless 119 if <tt>-L</tt> is not given. </li> <br> 120 121 <li> <tt>-t</tt> <em>stamptype</em> : how 122 logs are timestamped in <em>logdir</em>. 0 means no timestamp, 1 means 123 <a href="https://cr.yp.to/libtai/tai64.html">external TAI64N format</a>, 124 2 means 125 <a href="https://www.iso.org/iso/home/standards/iso8601.htm">ISO 8601 format</a>, 126 and 3 means both. Default is <strong><tt>1</tt></strong>. </li> <br> 127 128 <li> <tt>-n</tt> <em>nfiles</em> : maximum number of archive files 129 in <em>logdir</em>. Default is <strong><tt>10</tt></strong>. </li> <br> 130 131 <li> <tt>-s</tt> <em>filesize</em> : maximum size of the <tt>current</tt> 132 file (and archive files) in <em>logdir</em>. Default is <strong><tt>1000000</tt></strong>. </li> <br> 133 134 <li> <tt>-S</tt> <em>maxsize</em> : maximum total size of the 135 archives in <em>logdir</em>. Default is <strong><tt>0</tt></strong>, 136 meaning no limits apart from those enforced by the <tt>-n</tt> and 137 <tt>-s</tt> options. </li> <br> 138 139 <li> <tt>-P</tt> <em>prefix</em> : when logging to <em>logdir</em>, 140 prefix logged lines with the <em>prefix</em> string. Default is no prefix. </li> 141 </ul> 142 143 <h2> The templated service directory </h2> 144 145 <p> 146 <em>template</em> should be a directory that looks exactly like a service 147 directory. It will not be live, i.e. at no point will <em>template</em> 148 itself be supervised; instead, a copy of it is stored under <em>dir</em> 149 (and a copy of that copy will be used for every instance of the service). 150 You can safely move or delete <em>template</em> after running 151 s6-instance-maker. 152 </p> 153 154 <p> 155 To differentiate between instances, the <tt>run</tt> and <tt>finish</tt> 156 script in <em>template</em> should take one additional argument (the 157 first argument for <tt>run</tt> and the third argument for <tt>finish</tt>). 158 This argument will be the name of the instance, as provided by the 159 <a href="s6-instance-create.html">s6-instance-create</a> invocation. 160 </p> 161 162 <h2> Logging </h2> 163 164 <p> 165 The service is logged: its stderr and stdout are piped to an 166 <a href="s6-log.html">s6-log</a> process running as <em>loguser</em> and 167 writing to the <em>logdir</em> directory. This logger is the catch-all logger 168 for all the instances and the supervision tree hosting them. If <em>user</em> 169 and <em>loguser</em> are provided, it is recommended to make them distinct 170 from each other. 171 </p> 172 173 <p> 174 Additionally, if <em>template</em> has a <em>log</em> subdirectory, then each instance 175 will have its own dedicated logger. The <tt>run</tt> and <tt>finish</tt> 176 scripts for the logger of an instance named <em>name</em> will be called 177 with an additional argument of <tt><em>name</em>/log</tt>. They should 178 make use of this, to ensure loggers are properly differentiated between 179 instances: for example, it is not possible to run several 180 <a href="s6-log.html">s6-log</a> processes on the same log directory, 181 so an instance logger script containing an invocation of s6-log on a fixed 182 logdir will fail as soon as there are 2 instances. 183 </p> 184 185 <h2> Notes </h2> 186 187 <ul> 188 <li> s6-instance-maker makes use of the fact that 189 <a href="//skarnet.org/software/execline/">execline</a> scripts are much 190 easier to generate programmatically and to harden than shell scripts, so it is only 191 built if s6 is built with <a href="//skarnet.org/software/execline/">execline</a> 192 support - i.e. the <tt>--disable-execline</tt> switch has <em>not</em> been given 193 to configure. </li> 194 <li> If s6-instance-maker encounters failure (and exits 111), it does not clean up 195 the directories it created. Make sure to always test s6-instance-maker's return code 196 and clean up after it if needed. </li> 197 </ul> 198 199 </body> 200 </html>