s6-svscan.html (12666B)
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-svscan program</title> 7 <meta name="Description" content="s6: the s6-svscan program" /> 8 <meta name="Keywords" content="s6 command s6-svscan scandir supervision supervise svscan monitoring collection" /> 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/">www.skarnet.org</a> 17 </p> 18 19 <h1> The s6-svscan program </h1> 20 21 <p> 22 s6-svscan starts and monitors a collection of <a href="s6-supervise.html">s6-supervise</a> 23 processes, each of these processes monitoring a single service. It is designed to be either 24 the root or a branch of a <em>supervision tree</em>. 25 </p> 26 27 <h2> Interface </h2> 28 29 <pre> 30 s6-svscan [ -d <em>notif</em> ] [ -X <em>consoleholder</em> ] [ -c max | -C services_max ] [ -L name_max ] [ -t <em>rescan</em> ] [ <em>scandir</em> ] 31 </pre> 32 33 <ul> 34 <li> If given a <em>scandir</em> argument, s6-svscan switches to it. Else it uses 35 its current directory as the <a href="scandir.html">scan directory</a>. </li> 36 <li> It exits 100 if another s6-svscan process is already monitoring this 37 <a href="scandir.html">scan directory</a>. </li> 38 <li> If the <tt>./.s6-svscan</tt> control directory does not exist, 39 s6-svscan creates it. However, it is recommended to already have a <tt>.s6-svscan</tt> 40 subdirectory in your scan directory, because it is used to configure s6-svscan 41 operation, see below. 42 <li> From this point on, s6-svscan never dies. It tries its best to keep 43 control of what's happening. In case of a major system call failure, which means 44 that the kernel or hardware is broken in some fashion, it executes into the 45 <tt>.s6-svscan/crash</tt> program. (But if that execution fails, s6-svscan exits 46 111.) </li> 47 <li> s6-svscan performs an initial <em>scan</em> of its scan directory. </li> 48 <li> s6-svscan then occasionally runs <em>scans</em> or <em>reaps</em>, 49 see below. </li> 50 <li> s6-svscan runs until it is told to stop via <a href="s6-svscanctl.html"> 51 s6-svscanctl</a>, or an appropriate signal (see below). 52 Then it executes into the <tt>.s6-svscan/finish</tt> program, if present; if 53 not, it exits 0. 54 </ul> 55 56 <h2> Options </h2> 57 58 <ul> 59 <li> <tt>-d <em>notif</em></tt> : notify readiness on file descriptor 60 <em>notif</em>. When s6-svscan is ready to accept commands from 61 <a href="s6-svscanctl.html">s6-svscanctl</a>, it will write a newline to <em>notif</em>. 62 <em>notif</em> cannot be lesser than 3. By default, no notification is sent. Please 63 note that using this option signals <em>shallow readiness</em>: s6-svscan being 64 "ready" only means that it is ready to accept commands. It <em>does not mean</em> 65 that all the services it launches at start are themselves ready, or even started, or 66 even that the relevant <a href="s6-supervise.html">s6-supervise</a> processes have 67 been started. If you need to test for <em>deep readiness</em>, meaning that all the 68 services in the supervision tree have been started and are ready, you cannot rely 69 on this option. </li> 70 71 <li> <tt>-X <em>consoleholder</em></tt> : assume the output console is available 72 on descriptor <em>consoleholder</em>. If this option is given, and a <tt>s6-svscan-log</tt> 73 service exists, the <a href="s6-supervise.html">s6-supervise</a> process for that service 74 will be run with <em>consoleholder</em> as its standard error. This is mainly useful 75 for a setup done via <a href="//skarnet.org/software/s6-linux-init/">s6-linux-init</a>, 76 where all error messages go to the <tt>s6-svscan-log</tt> catch-all logger service by 77 default, except messages from this service itself, which fall back to <em>consoleholder</em>. 78 If you're not sure what to use this option for, or how, you don't need it. </li> 79 80 <li> <tt>-C <em>services_max</em></tt> : maintain services for up to <em>services_max</em> 81 service directories, including loggers. Default is 1000. Lower limit is 4. Upper limit is 160000. If 82 you're increasing this value from the default, please note that: 83 <ul> 84 <li> The higher <em>max</em> is, the more stack memory s6-svscan will use, 85 up to 200 bytes per service, also depending on the value of <em>name_max</em>. </li> 86 <li> s6-svscan uses 2 file descriptors per logged service. </li> 87 </ul> 88 It is the admin's responsibility to make sure that s6-svscan has enough available 89 descriptors to function properly and does not exceed its stack limit. The default 90 of 1000 is safe and provides enough room for every reasonable system. </li> 91 92 <li> <tt>-c <em>max</em></tt> : a deprecated way of setting <em>services_max</em>. 93 If the <tt>-c</tt> option is given, the value of <em>max</em> is doubled, and the result 94 is used as <em>services_max</em>. The reason for the change is that previous versions 95 of s6-svscan handled services+loggers as a single entity; but this version of s6-svscan 96 handles services and loggers in the same way, so with the default values it's now possible 97 to handle e.g. 600 unlogged services, whereas previously you were limited to 500 because 98 s6-svscan was reserving room for the loggers. </li> 99 100 <li> <tt>-L <em>name_max</em></tt> : the maximum length of a name in the 101 scan directory. Names longer than <em>name_max</em> won't be taken into account. 102 Default is 251. It cannot be set lower than 11 or higher than 1019. </li> 103 104 <li> <tt>-t <em>rescan</em></tt> : perform a scan every <em>rescan</em> 105 milliseconds. If <em>rescan</em> is 0 (the default), automatic scans are never performed after 106 the first one and s6-svscan will only detect new services when told to via a 107 <a href="s6-svscanctl.html">s6-svscanctl -a</a> command. Use of this option is 108 discouraged; it should only be given to emulate the behaviour of other supervision 109 suites. (<tt>-t5000</tt> for daemontools' svscan, <tt>-t14000</tt> for runit's 110 runsvdir.) </li> 111 </ul> 112 113 <h2> Signals </h2> 114 115 <p> 116 s6-svscan has special handling for the following signals: 117 </p> 118 119 <ul> 120 <li> SIGCHLD </li> 121 <li> SIGALRM </li> 122 <li> SIGABRT </li> 123 <li> SIGHUP </li> 124 <li> SIGINT </li> 125 <li> SIGTERM </li> 126 <li> SIGQUIT </li> 127 <li> SIGUSR1 </li> 128 <li> SIGUSR2 </li> 129 <li> SIGPWR (on systems that support it)</li> 130 <li> SIGWINCH (on systems that support it)</li> 131 </ul> 132 133 <p> 134 Signals that are not in the above list are not caught by s6-svscan and will 135 have the system's default effect. 136 </p> 137 138 <p> 139 The behaviour for the first three signals in the list is always fixed: 140 </p> 141 142 <ul> 143 <li> SIGCHLD : trigger the reaper. </li> 144 <li> SIGALRM : trigger the scanner. </li> 145 <li> SIGABRT : immediately exec into <tt>.s6-svscan/finish</tt> (or exit 0 if that script does not exist), without waiting for any processes to die </li> 146 </ul> 147 148 <p> 149 The behaviour for the rest of the list is configurable: on receipt of a 150 <tt>SIG<em>FOO</em></tt>, 151 s6-svscan will try to run an executable <tt>.s6-svscan/SIG<em>FOO</em></tt> file. For 152 instance, a <tt>.s6-svscan/SIGTERM</tt> executable script will be run on receipt of 153 a SIGTERM. If the file cannot be found, or cannot be executed for any reason, the 154 default behaviour for the signal will be applied. Default behaviours are: 155 </p> 156 157 <ul> 158 <li> SIGHUP : rescan and prune the supervision tree, i.e. make sure that new 159 service directories visible from the scan directory have a 160 <a href="s6-supervise.html">s6-supervise</a> process running on them, and instruct 161 <a href="s6-supervise.html">s6-supervise</a> processes running on service directories 162 that have become invisible from the scan directory to stop their service and exit. 163 This behaviour can also be achieved via the 164 <tt>s6-svscanctl -an <em>scandir</em> </tt> command. This is the closest that s6-svscan 165 can get to the traditional "reload your configuration" behaviour. </li> 166 <li> SIGINT : same as SIGTERM below. </li> 167 <li> SIGTERM : Instruct all the <a href="s6-supervise.html">s6-supervise</a> processes 168 to stop their service and exit; wait for the whole supervision tree to die, without 169 losing any logs; then exec into <tt>.s6-svscan/finish</tt> or exit 0. This behaviour 170 can also be achieved via the <tt>s6-svscanctl -t <em>scandir</em></tt> command. </li> 171 <li> SIGQUIT : same as SIGTERM above, except that if a service is logged 172 (i.e. there is a <em>foo</em> service <em>and</em> a <em>foo</em>/log service) 173 then the logging service will also be killed, instead of being allowed to exit 174 naturally after its producer has flushed its output and died. This can solve 175 problems with badly written logging programs, but it can also cause loss of logs 176 since the logger may die before the producer has finished flushing everything. The 177 behaviour can also be achieved via the <tt>s6-svscanctl -q <em>scandir</em></tt> command; 178 you should only use this if SIGTERM/<tt>-t</tt> fails to properly tear down the 179 supervision tree. </li> 180 <li> Others: no effect if an appropriate executable file in <tt>.s6-svscan/</tt> 181 cannot be run. </li> 182 </ul> 183 184 <h2> The reaper </h2> 185 186 <p> 187 Upon receipt of a SIGCHLD, or an <a href="s6-svscanctl.html">s6-svscanctl -z</a> 188 command, s6-svscan runs a <em>reaper</em> routine. 189 </p> 190 191 <p> 192 The reaper acknowledges (via some 193 <a href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/wait.html">wait()</a> 194 function), without blocking, every terminated child of s6-svscan, even ones it does not 195 know it has. This is especially important when <a href="s6-svscan-1.html">s6-svscan is 196 run as process 1</a>. 197 </p> 198 199 <p> 200 If the dead child is an <a href="s6-supervise.html">s6-supervise</a> process watched 201 by s6-svscan, and the last scan flagged that process as active, then it is restarted 202 one second later. 203 </p> 204 205 <h2> The scanner </h2> 206 207 <p> 208 Upon receipt of a SIGALRM or a 209 <a href="s6-svscanctl.html">s6-svscanctl -a</a> command, s6-svscan runs a 210 <em>scanner</em> routine. (It also runs it every <em>rescan</em> milliseconds 211 if the <tt>-t</tt> option has been given.) 212 </p> 213 214 <p> 215 The scanner scans the current directory for subdirectories (or symbolic links 216 to directories), which must be <a href="servicedir.html">service directories</a>. 217 It skips names starting with dots. It will not create services for more than 218 <em>max</em> subdirectories. 219 </p> 220 221 <p> 222 For every new subdirectory <em>dir</em> it finds, the scanner spawns a 223 <a href="s6-supervise.html">s6-supervise</a> process on it. If 224 <em>dir</em><tt>/log</tt> exists, it spawns an s6-supervise process on 225 both <em>dir</em> and <em>dir</em><tt>/log</tt>, and maintains a 226 never-closing pipe from the service's stdout to the logger's stdin. 227 This is <em>starting the service</em>, with or without a corresponding 228 logger. 229 Every service the scanner finds is flagged as "active". 230 </p> 231 232 <p> 233 The scanner remembers the services it found. If a service has been 234 started in an earlier scan, but the current scan can't find the corresponding 235 directory, the service is then flagged as inactive. No command is sent 236 to stop inactive s6-supervise processes (unless the administrator 237 uses <a href="s6-svscanctl.html">s6-svscanctl -n</a> or a SIGHUP), but 238 inactive s6-supervise processes will not be restarted if they die. 239 </p> 240 241 <h2> Notes </h2> 242 243 <ul> 244 <li> s6-svscan is designed to run until the machine is shut down. It is 245 also designed as a suitable candidate for 246 <a href="s6-svscan-1.html">process 1</a>. So, it goes out of its way to 247 stay alive, even in dire situations. When it encounters a fatal situation, 248 something it really cannot handle, it executes into <tt>.s6-svscan/crash</tt> 249 instead of dying; when it is told to exit, it executes into 250 <tt>.s6-svscan/finish</tt>. Administrators should make sure to design 251 appropriate <tt>crash</tt> and <tt>finish</tt> routines. </li> 252 <li> s6-svscan is a fully asynchronous state machine. It will read and 253 process commands at any time, even when the computer is in trouble. </li> 254 <li> s6-svscan <em>does not use malloc()</em>. That means it will <em>never leak 255 memory</em>. <small>However, s6-svscan uses opendir(), and most opendir() 256 implementations internally use heap memory - so unfortunately, it's impossible 257 to guarantee that s6-svscan does not use heap memory at all.</small> </li> 258 <li> Unless run with a nonzero <tt>-t</tt> option, which is only a legacy 259 feature used to emulate other supervision suites such as daemontools or runit, 260 s6-svscan <em>never polls</em>; it only wakes up on notifications. 261 The s6 supervision tree can be used in energy-critical environments. </li> 262 </ul> 263 264 </body> 265 </html>