diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/index.html | 6 | ||||
| -rw-r--r-- | doc/notifywhenup.html | 6 | ||||
| -rw-r--r-- | doc/s6-notifywhenup.html | 111 | ||||
| -rw-r--r-- | doc/s6-sudod.html | 13 | ||||
| -rw-r--r-- | doc/s6-supervise.html | 22 | ||||
| -rw-r--r-- | doc/s6-svc.html | 28 | ||||
| -rw-r--r-- | doc/s6-svlisten.html | 8 | ||||
| -rw-r--r-- | doc/s6-svlisten1.html | 5 | ||||
| -rw-r--r-- | doc/s6-svstat.html | 6 | ||||
| -rw-r--r-- | doc/s6-svwait.html | 10 | ||||
| -rw-r--r-- | doc/servicedir.html | 6 | ||||
| -rw-r--r-- | doc/upgrade.html | 21 |
12 files changed, 92 insertions, 150 deletions
diff --git a/doc/index.html b/doc/index.html index 87fe66b..0c23ff0 100644 --- a/doc/index.html +++ b/doc/index.html @@ -84,7 +84,7 @@ with s6</a> </li> <li> GNU make, version 4.0 or later. Please be aware that s6 will not build with an earlier version. </li> <li> <a href="http://skarnet.org/software/skalibs/">skalibs</a> version -2.3.5.1 or later. It's a build-time requirement. It's also a run-time +2.3.6.0 or later. It's a build-time requirement. It's also a run-time requirement if you link against the shared version of the skalibs library. </li> <li> <a href="http://skarnet.org/software/execline/">execline</a> version @@ -101,7 +101,7 @@ library. </li> <h3> Download </h3> <ul> - <li> The current released version of s6 is <a href="s6-2.1.6.0.tar.gz">2.1.6.0</a>. </li> + <li> The current released version of s6 is <a href="s6-2.2.0.0.tar.gz">2.2.0.0</a>. </li> <li> Alternatively, you can checkout a copy of the s6 git repository: <pre> git clone git://git.skarnet.org/s6 </pre> </li> <li> There's also a @@ -153,8 +153,6 @@ a user interface to control those processes and monitor service states. <li><a href="s6-svwait.html">The <tt>s6-svwait</tt> program</a></li> <li><a href="s6-svlisten1.html">The <tt>s6-svlisten1</tt> program</a></li> <li><a href="s6-svlisten.html">The <tt>s6-svlisten</tt> program</a></li> -<li><a href="s6-notifywhenup.html">The <tt>s6-notifywhenup</tt> program</a> -<strong>(deprecated)</strong></li> </ul> <h4> Daemontools-like utilities </h4> diff --git a/doc/notifywhenup.html b/doc/notifywhenup.html index 9a288ac..6bc8b99 100644 --- a/doc/notifywhenup.html +++ b/doc/notifywhenup.html @@ -67,16 +67,16 @@ a generic mechanism that some daemons already implement. <a href="servicedir.html">service directory</a> for the daemon contains a valid <tt>notification-fd</tt> file, the daemon's supervisor, i.e. the <a href="s6-supervise.html">s6-supervise</a> program, will properly catch -the daemon's message, update a state file (<tt>supervise/ready</tt>), then +the daemon's message, update the status file (<tt>supervise/status</tt>), then notify all the subscribers -with a 'U' event, meaning that the service is now up and ready. +with a <tt>'U'</tt> event, meaning that the service is now up and ready. </p> <p> This method should really be implemented in every long-running program providing a service. When it is not the case, it's impossible to provide reliable startup notifications, and subscribers should then -be content with the unreliable 'u' events provided by s6-supervise. +be content with the unreliable <tt>'u'</tt> events provided by s6-supervise. </p> </body> diff --git a/doc/s6-notifywhenup.html b/doc/s6-notifywhenup.html deleted file mode 100644 index cdfa693..0000000 --- a/doc/s6-notifywhenup.html +++ /dev/null @@ -1,111 +0,0 @@ -<html> - <head> - <meta name="viewport" content="width=device-width, initial-scale=1.0" /> - <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> - <meta http-equiv="Content-Language" content="en" /> - <title>s6: the s6-notifywhenup program</title> - <meta name="Description" content="s6: the s6-notifywhenup program" /> - <meta name="Keywords" content="s6 command s6-notifywhenup fifodir notification event notifier send service daemon ready" /> - <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> --> - </head> -<body> - -<p> -<a href="index.html">s6</a><br /> -<a href="http://skarnet.org/software/">Software</a><br /> -<a href="http://skarnet.org/">skarnet.org</a> -</p> - -<h1> The s6-notifywhenup program </h1> - -<em> -<p> -Starting with s6-2.1.4.0, the s6-notifywhenup program has been deprecated, -because there was still a case (albeit extremely rare) where a race -condition would occur and readiness would be improperly advertised. -Readiness notification for a service can now be achieved via a -<tt>notification-fd</tt> file in the -<a href="servicedir.html">service directory</a>, containing the -number of the descriptor the service will write its readiness -notification newline to. The notification will directly be picked by -<a href="s6-supervise.html">s6-supervise</a>. <br /> -</p> - -<p> - Quick upgrade recipe: for every service using s6-notifywhenup, -replace the s6-notifywhenup invocation in your run script with -<tt>fdmove 1 3</tt>, then perform <tt>echo 3 > notification-fd</tt>. -Done! -</p> -</em> - -<p> -s6-notifywhenup launches a daemon while listening to a file descriptor, -and sends a 'U' event to a <a href="fifodir.html">fifodir</a> when it -receives something on that file descriptor. -</p> - -<p> -<a href="notifywhenup.html">This page</a> explains why this program is -needed. -</p> - -<h2> Interface </h2> - -<pre> - s6-notifywhenup [ -d <em>fd</em> ] [ -e <em>fifodir</em> ] [ -f ] [ -X ] [ -t <em>timeout</em> ] <em>prog...</em> -</pre> - -<ul> - <li> s6-notifywhenup forks and executes <em>prog...</em> as the -parent, with a pipe from <em>prog...</em>'s stdout to the child. </li> - <li> The child waits for a newline (<tt>\n</tt>) to be written -on the pipe. When it gets it, it creates a -<tt>./supervise/ready</tt> file then sends a 'U' event to the -<tt>./event</tt> fifodir. </li> - <li> The child exits 0. </li> -</ul> - -<h2> Options </h2> - -<ul> - <li> <tt>-d <em>fd</em></tt> : listen to -<em>prog</em>'s output on descriptor <em>fd</em>. The default is 1. </li> - <li> <tt>-e <em>fifodir</em></tt> : send a 'U' event to fifodir -<em>fifodir</em>. Default is <tt>./event</tt>. </li> - <li> <tt>-f</tt> : simple fork. Normally, s6-notifywhenup doubleforks, -in order to accommodate for a -<em>prog</em> that does not expect to have a child and avoid a -pending zombie. This option avoids the doublefork, but it should only be -set if <em>prog</em> reaps even children it doesn't know it has. </li> - <li> <tt>-t <em>timeout</em></tt> : if no EOF has been received -after <em>timeout</em> milliseconds, exit without sending the event. -Default is 0, meaning infinite. </li> - <li> <tt>-X</tt> : fake readiness. s6-notifywhenup will actually send -the newline itself before executing <em>prog</em>. This option should in -principle never be used. </li> -</ul> - -<h2> Notes </h2> - -<ul> - <li> s6-notifywhenup executes <em>prog...</em> as the parent in order -for <em>prog</em> to keep the same pid, which is vital for supervised -processes. </li> - <li> s6-notifywhenup can be used, for instance, with -<a href="s6-ipcserver.html">s6-ipcserver</a> -and its <tt>-1</tt> option, so that reliable startup notification is -achieved. <tt>s6-notifywhenup -f s6-ipcserver -1 <em>args</em></tt> will -send a 'U' event to <tt>./event</tt> when s6-ipcserver is actually -listening to its socket. </li> - <li> The <a href="s6-svwait.html">s6-svwait</a> program can be used -to wait for 'U' events, as well as the -<a href="s6-svlisten1.html">s6-svlisten1</a> and -<a href="s6-svlisten.html">s6-svlisten</a> programs. </li> - <li> The <tt>supervise/ready</tt> file, when created, contains at least -the absolute time when s6-notifywhenup detected service readiness. The -format and contents of this file are subject to change. </li> -</ul> - -</body> -</html> diff --git a/doc/s6-sudod.html b/doc/s6-sudod.html index 2c613da..54e9574 100644 --- a/doc/s6-sudod.html +++ b/doc/s6-sudod.html @@ -91,8 +91,8 @@ will set up a privileged program: <pre> #!/command/execlineb -P fdmove -c 2 1 +fdmove 1 3 s6-envuidgid serveruser -s6-notifywhenup -f s6-ipcserver -U -1 -- serversocket s6-ipcserver-access -v2 -l0 -i rules -- exec -c @@ -106,12 +106,15 @@ sargv executes the script. </li> <li> <a href="http://skarnet.org/software/execline/fdmove.html">fdmove</a> makes sure the script's error messages are sent to the service's logger. </li> + <li> <a href="http://skarnet.org/software/execline/fdmove.html">fdmove</a> +redirects the script's stdout to file descriptor 3. This is useful if +the service directory contains a <tt>notification-fd</tt> file containing +<tt>3</tt>, so the daemon can perform +<a href="notifywhenup.html">readiness notification</a> by writing a +newline to its stdout. (The +<tt>-1</tt> option to s6-ipcserver tells it to do this.) </li> <li> <a href="s6-envuidgid.html">s6-envuidgid</a> sets the UID, GID and GIDLIST environment variables for s6-ipcserver to interpret. </li> - <li> <a href="s6-notifywhenup.html">s6-notifywhenup</a> primes the -service for readiness notification (and the -<tt>-1</tt> option to s6-ipcserver tells the daemon to actually -notify when it's ready). </li> <li> <a href="s6-ipcserver.html">s6-ipcserver</a> binds to <em>serversocket</em>, drops its privileges to those of <em>serveruser</em>, and announces its readiness. Then, for every client connecting to <em>serversocket</em>: diff --git a/doc/s6-supervise.html b/doc/s6-supervise.html index a16e0f5..081aeae 100644 --- a/doc/s6-supervise.html +++ b/doc/s6-supervise.html @@ -44,15 +44,18 @@ If it already exists, it uses it as is, without modifying the subscription right <li> If the default service state is up, s6-supervise spawns <tt>./run</tt>. </li> <li> s6-supervise sends a <tt>'u'</tt> event to <tt>./event</tt> whenever it successfully spawns <tt>./run</tt>. </li> - <li> When <tt>./run</tt> dies, s6-supervise sends a <tt>'d'</tt> event to <tt>./event</tt>. </li> - <li> When <tt>./run</tt> dies, s6-supervise spawns <tt>./finish</tt> if it exists. + <li> When <tt>./run</tt> dies, s6-supervise sends a <tt>'d'</tt> event to <tt>./event</tt>. +It then spawns <tt>./finish</tt> if it exists. <tt>./finish</tt> will have <tt>./run</tt>'s exit code as first argument, or 256 if <tt>./run</tt> was signaled; it will have the number of the signal that killed <tt>./run</tt> as second argument, or an undefined number if <tt>./run</tt> was not signaled. </li> - <li> <tt>./finish</tt> must exit in less than 5 seconds. If it takes more than that, -s6-supervise kills it with a SIGKILL. </li> - <li> When <tt>./finish</tt> dies, s6-supervise restarts <tt>./run</tt> unless it has been -told not to. </li> + <li> By default, <tt>./finish</tt> must exit in less than 5 seconds. If it takes more than that, +s6-supervise kills it with a SIGKILL. This can be configured via the +<tt>./timeout-finish</tt> file, see the description in the +<a href="servicedir.html">service directory page</a>. </li> + <li> When <tt>./finish</tt> dies (or is killed), +s6-supervise sends a <tt>'D'</tt> event to <tt>./event</tt>. Then +it restarts <tt>./run</tt> unless it has been told not to. </li> <li> There is a minimum 1-second delay between two <tt>./run</tt> spawns, to avoid busylooping if <tt>./run</tt> exits too quickly. </li> <li> When killed or asked to exit, it waits for the service to go down one last time, then @@ -78,10 +81,9 @@ what they do, are listed on the <tt>notification-fd</tt> file when the service is started, or restarted, s6-supervise creates and listens to an additional pipe from the service for <a href="notifywhenup.html">readiness notification</a>. When the -notification occurs, s6-supervise creates a <tt>./supervise/ready</tt> -file containing the absolute time when readiness occurred, then sends -a <tt>'U'</tt> event to <tt>./event</tt>. The <tt>./supervise/ready</tt> -file is deleted on service death. +notification occurs, s6-supervise updates the <tt>./supervise/status</tt> +file accordingly, then sends +a <tt>'U'</tt> event to <tt>./event</tt>. </p> <p> diff --git a/doc/s6-svc.html b/doc/s6-svc.html index 2de8ba4..f21847a 100644 --- a/doc/s6-svc.html +++ b/doc/s6-svc.html @@ -28,7 +28,7 @@ knowing their PIDs, and without using horrible hacks such as .pid files. <h2> Interface </h2> <pre> - s6-svc [ -D | -U ] [ -T <em>timeout</em> ] [ -abqhkti12pcoduxO ] <em>servicedir</em> + s6-svc [ -wu | -wU | -wd | -wD ] [ -T <em>timeout</em> ] [ -abqhkti12pcoduxO ] <em>servicedir</em> </pre> <p> @@ -75,13 +75,20 @@ it. </li> (in milliseconds) after which s6-svc will exit 1 with an error message if the service still hasn't reached the desired state. By default, the timeout is 0, which means that s6-svc will block indefinitely. </li> - <li> <tt>-D</tt> : s6-svc will not exit until the service is down. </li> - <li> <tt>-U</tt> : s6-svc will not exit until the service is up and + <li> <tt>-wd</tt> : s6-svc will not exit until the service is down, +i.e. until the <tt>run</tt> process has died. </li> + <li> <tt>-wD</tt> : s6-svc will not exit until the service is down +<em>and</em> ready to be brought up, i.e. a possible <tt>finish</tt> script has +exited. </li> + <li> <tt>-wu</tt> : s6-svc will not exit until the service is up, +i.e. there is a process running the <tt>run</tt> executable. </li> + <li> <tt>-wU</tt> : s6-svc will not exit until the service is up <em>and</em> <a href="notifywhenup.html">ready</a> as notified by the daemon itself. If the <a href="servicedir.html">service directory</a> does not contain a <tt>notification-fd</tt> file to tell <a href="s6-supervise.html">s6-supervise</a> to accept readiness -notification, s6-svc will print a warning and ignore the command. </li> +notification, s6-svc will print a warning and act as if the <tt>-wu</tt> +option had been given instead. </li> </ul> <h2> Usage examples </h2> @@ -100,12 +107,13 @@ the process represented by the <tt>/service/sshd</tt> service directory - typically the sshd server. </p> -<pre> s6-svc -Dd /service/ftpd </pre> +<pre> s6-svc -wD -d /service/ftpd </pre> <p> - Take down the ftpd server and block until the process is really down. + Take down the ftpd server and block until the process is down and +the finish script has completed. </p> -<pre> s6-svc -Uu -T 5000 /service/ftpd </pre> +<pre> s6-svc -wU -T 5000 -u /service/ftpd </pre> <p> Bring up the ftpd server and block until it has sent notification that it is ready. Exit 1 if it is still not ready after 5 seconds. @@ -123,10 +131,10 @@ process is <a href="s6-log.html">s6-log</a>, this triggers a log rotation. <li> s6-svc writes control commands into the <tt><em>servicedir</em>/supervise/control</tt> FIFO. A s6-supervise process running on <em>servicedir</em> will be listening to this FIFO, and will read and interpret those commands. </li> - <li> When invoked with the <tt>-D</tt> or <tt>-U</tt> option, s6-svc executes into + <li> When invoked with one of the <tt>-w</tt> options, s6-svc executes into <a href="s6-svlisten1.html">s6-svlisten1</a>, which will listen to service state -changes and spawn another s6-svc instance (without the <tt>-D</tt> or <tt>-U</tt> -option) that will send the commands to the service. Any error message written during +changes and spawn another s6-svc instance (without the <tt>-w</tt> option) +that will send the commands to the service. Any error message written during the waiting period will mention it is being written by s6-svlisten1; this is normal. </li> </ul> diff --git a/doc/s6-svlisten.html b/doc/s6-svlisten.html index 2316a2b..1db24c0 100644 --- a/doc/s6-svlisten.html +++ b/doc/s6-svlisten.html @@ -34,7 +34,7 @@ a collection of supervised services, and blocks until they all go up, or down. </p> <pre> - s6-svlisten [ -U | -u | -d ] [ -a | -o ] [ -t <em>timeout</em> ] { <em>servicedir</em> <em>servicedir...</em> } <em>prog...</em> + s6-svlisten [ -U | -u | -D | -d ] [ -a | -o ] [ -t <em>timeout</em> ] { <em>servicedir</em> <em>servicedir...</em> } <em>prog...</em> </pre> <p> @@ -42,7 +42,7 @@ a collection of supervised services, and blocks until they all go up, or down. </p> <pre> - s6-svlisten [ -U | -u | -d ] [ -a | -o ] [ -t <em>timeout</em> ] <em>servicedir</em> <em>servicedir...</em> "" <em>prog...</em> + s6-svlisten [ -U | -u | -D | -d ] [ -a | -o ] [ -t <em>timeout</em> ] <em>servicedir</em> <em>servicedir...</em> "" <em>prog...</em> </pre> <ul> @@ -69,6 +69,10 @@ specific support in the service programs, and the use of the <a href="servicedir.html">service directory</a>. See the explanation on <a href="notifywhenup.html">this page</a>. </li> <li> <tt>-d</tt> : down. s6-svlisten will wait until the services are down. </li> + <li> <tt>-D</tt> : really down. s6-svlisten will wait until the +services are down and the cleanup scripts in <tt><em>servicedir</em>/finish</tt> +for every <em>servicedir</em> +have finished executing (or have timed out and been killed). </li> <li> <tt>-o</tt> : or. s6-svlisten will wait until <em>one</em> of the given services comes up or down. </li> <li> <tt>-a</tt> : and. s6-svlisten will wait until <em>all</em> of the diff --git a/doc/s6-svlisten1.html b/doc/s6-svlisten1.html index a9e147a..c3f5ef4 100644 --- a/doc/s6-svlisten1.html +++ b/doc/s6-svlisten1.html @@ -30,7 +30,7 @@ supervised service, and blocks until said service goes up, or down. <h2> Interface </h2> <pre> - s6-svlisten [ -U | -u | -d ] [ -t <em>timeout</em> ] <em>servicedir</em> <em>prog...</em> + s6-svlisten [ -U | -u | -D | -d ] [ -t <em>timeout</em> ] <em>servicedir</em> <em>prog...</em> </pre> <ul> @@ -57,6 +57,9 @@ specific support in the service programs, and the use of the <a href="servicedir.html">service directory</a>. See the explanation on <a href="notifywhenup.html">this page</a>. </li> <li> <tt>-d</tt> : down. s6-svlisten1 will wait until the service is down. </li> + <li> <tt>-D</tt> : really down. s6-svlisten1 will wait until the +service is down and the cleanup script in <tt><em>servicedir</em>/finish</tt> +has finished executing (or has timed out and been killed). </li> <li> <tt>-t <em>timeout</em></tt> : if the requested event has not happened after <em>timeout</em> milliseconds, s6-svlisten1 will print a message to stderr and exit 1. By default, <em>timeout</em> is 0, which means no time diff --git a/doc/s6-svstat.html b/doc/s6-svstat.html index e78c13f..5feef0f 100644 --- a/doc/s6-svstat.html +++ b/doc/s6-svstat.html @@ -46,7 +46,11 @@ signal, if it is down </li> kernel's scheduler picks up s6-supervise </li> <li> whether the service is <a href="notifywhenup.html">ready</a>, as notified by the daemon itself, and -if it is, the number of seconds that it has been. </li> +if it is, the number of seconds that it has been. +A service reported as down and ready simply means that it is ready +to be brought up. A service is down and not ready when it is in the +cleanup phase, i.e. the <tt>./finish</tt> script is still being executed. </li> + </li> </ul> <h2> Options </h2> diff --git a/doc/s6-svwait.html b/doc/s6-svwait.html index de209ea..c3df0fa 100644 --- a/doc/s6-svwait.html +++ b/doc/s6-svwait.html @@ -29,7 +29,7 @@ s6-svwait only waits for notifications; it never polls. <h2> Interface </h2> <pre> - s6-svwait [ -U | -u | -d ] [ -a | -o ] [ -t <em>timeout</em> ] <em>servicedir...</em> + s6-svwait [ -U | -u | -D | -d ] [ -a | -o ] [ -t <em>timeout</em> ] <em>servicedir...</em> </pre> <p> @@ -53,6 +53,11 @@ specific support in the service programs, and the use of the <a href="servicedir.html">service directory</a>. See the explanation on <a href="notifywhenup.html">this page</a>. </li> <li> <tt>-d</tt> : down. s6-svwait will wait until the services are down. </li> + <li> <tt>-D</tt> : really down. s6-svwait will wait until the +services are down and the cleanup scripts in +<tt><em>servicedir</em>/finish</tt> +for every <em>servicedir</em> +have finished executing (or have timed out and been killed). </li> <li> <tt>-o</tt> : or. s6-svwait will wait until <em>one</em> of the given services comes up or down. </li> <li> <tt>-a</tt> : and. s6-svwait will wait until <em>all</em> of the @@ -80,8 +85,7 @@ s6-supervise has not been started yet. </li> <p> s6-svwait spawns a <a href="libs6/s6-ftrigrd.html">s6-ftrigrd</a> child to listen to notifications sent by <a href="s6-supervise.html">s6-supervise</a>. -It also checks <tt>supervise/status</tt> files, as well as the -<tt>supervise/ready</tt> files if necessary, to get the current service +It also checks <tt>supervise/status</tt> files to get the current service states, so it is immune to race conditions. </p> diff --git a/doc/servicedir.html b/doc/servicedir.html index 7cebd53..76a0a11 100644 --- a/doc/servicedir.html +++ b/doc/servicedir.html @@ -117,6 +117,12 @@ notification from the service and broadcast readiness, i.e. any <a href="s6-svlisten1.html">s6-svlisten1 -U</a> or <a href="s6-svlisten.html">s6-svlisten -U</a> processes will be triggered. </li> + <li> An optional regular file named <tt>timeout-finish</tt>. If such a file +exists, it must only contain an unsigned integer, which is the number of +milliseconds after which the <tt>./finish</tt> script, if it exists, will +be killed with a SIGKILL. The default is 5000: finish scripts are killed +if they're still alive after 5 seconds. A value of 0 allows finish scripts +to run forever. </li> <li> A <a href="fifodir.html">fifodir</a> named <tt>event</tt>. It is automatically created by <a href="s6-supervise.html">s6-supervise</a> if it does not exist. <em>foo</em><tt>/event</tt> diff --git a/doc/upgrade.html b/doc/upgrade.html index b6ae2c9..c77992b 100644 --- a/doc/upgrade.html +++ b/doc/upgrade.html @@ -18,6 +18,27 @@ <h1> What has changed in s6 </h1> +<h2> in 2.2.0.0 </h2> + +<ul> + <li> skalibs dependency bumped to 2.3.6.0. </li> + <li> The internals of <a href="s6-supervise.html">s6-supervise</a> have +changed; the <tt>supervise/status</tt> file ABI has changed and is not +compatible with the daemontools/runit <tt>supervise/status</tt> files +anymore. (This should not impact anything.) </li> + <li> <a href="s6-supervise.html">s6-supervise</a> features a +configurable timeout for <tt>./finish</tt> scripts, via the +<a href="servicedir.html"><tt>./timeout-finish</tt></a> file. </li> + <li> <a href="s6-svwait.html">s6-svwait</a>, +<a href="s6-svlisten1.html">s6-svlisten1</a> and +<a href="s6-svlisten.html">s6-svlisten</a> can now wait for a <tt>'D'</tt> +event, which means the <tt>./finish</tt> script has terminated. </li> + <li> The deprecated <tt>s6-notifywhenup</tt> program has been +removed. </li> + <li> The syntax for synchronous <a href="s6-svc.html">s6-svc</a> +waiting has changed. </li> +</ul> + <h2> in 2.1.6.0 </h2> <ul> |