From a3cdeecf0033919e3b5a79c17c19b5ac98719256 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Mon, 20 Jul 2015 20:20:54 +0000 Subject: - Add timeout-finish support and "down-readiness" - LOTS of refactoring to make this work - Remove s6-notifywhenup - s6-supervise now rocks the casbah - rc for 2.2.0.0 --- doc/index.html | 6 +-- doc/notifywhenup.html | 6 +-- doc/s6-notifywhenup.html | 111 ----------------------------------------------- doc/s6-sudod.html | 13 +++--- doc/s6-supervise.html | 22 +++++----- doc/s6-svc.html | 28 +++++++----- doc/s6-svlisten.html | 8 +++- doc/s6-svlisten1.html | 5 ++- doc/s6-svstat.html | 6 ++- doc/s6-svwait.html | 10 +++-- doc/servicedir.html | 6 +++ doc/upgrade.html | 21 +++++++++ 12 files changed, 92 insertions(+), 150 deletions(-) delete mode 100644 doc/s6-notifywhenup.html (limited to 'doc') 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
  • GNU make, version 4.0 or later. Please be aware that s6 will not build with an earlier version.
  • skalibs 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.
  • execline version @@ -101,7 +101,7 @@ library.

    • Download

    Daemontools-like utilities

    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. service directory for the daemon contains a valid notification-fd file, the daemon's supervisor, i.e. the s6-supervise program, will properly catch -the daemon's message, update a state file (supervise/ready), then +the daemon's message, update the status file (supervise/status), then notify all the subscribers -with a 'U' event, meaning that the service is now up and ready. +with a 'U' event, meaning that the service is now up and ready.

    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 'u' events provided by s6-supervise.

    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 @@ - - - - - - s6: the s6-notifywhenup program - - - - - - -

    -s6
    -Software
    -skarnet.org -

    - -

    The s6-notifywhenup program

    - - -

    -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 -notification-fd file in the -service directory, containing the -number of the descriptor the service will write its readiness -notification newline to. The notification will directly be picked by -s6-supervise.
    -

    - -

    - Quick upgrade recipe: for every service using s6-notifywhenup, -replace the s6-notifywhenup invocation in your run script with -fdmove 1 3, then perform echo 3 > notification-fd. -Done! -

    -     - -

    -s6-notifywhenup launches a daemon while listening to a file descriptor, -and sends a 'U' event to a fifodir when it -receives something on that file descriptor. -

    - -

    -This page explains why this program is -needed. -

    - -

    Interface

    - -
    -     s6-notifywhenup [ -d fd ] [ -e fifodir ] [ -f ] [ -X ] [ -t timeout ] prog...
-
    - - - -

    Options

    - - - -

    Notes

    - - - - - 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: 
     #!/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. 
  
  •  fdmove makes
 sure the script's error messages are sent to the service's logger. 
    • 
+ 
  •  fdmove
+redirects the script's stdout to file descriptor 3. This is useful if
+the service directory contains a notification-fd file containing
+3, so the daemon can perform
+readiness notification by writing a
+newline to its stdout. (The
+-1 option to s6-ipcserver tells it to do this.) 
    • 
  
  •  s6-envuidgid
 sets the UID, GID and GIDLIST environment variables for s6-ipcserver to interpret. 
    • 
- 
  •  s6-notifywhenup primes the
-service for readiness notification (and the
--1 option to s6-ipcserver tells the daemon to actually
-notify when it's ready). 
    • 
  
  •  s6-ipcserver binds to serversocket,
 drops its privileges to those of serveruser, and announces its
 readiness. Then, for every client connecting to serversocket:
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
  
  •  If the default service state is up, s6-supervise spawns ./run. 
    • 
  
  •  s6-supervise sends a 'u' event to ./event whenever it
 successfully spawns ./run. 
    • 
- 
  •  When ./run dies, s6-supervise sends a 'd' event to ./event. 
    • 
- 
  •  When ./run dies, s6-supervise spawns ./finish if it exists.
+ 
  •  When ./run dies, s6-supervise sends a 'd' event to ./event.
+It then spawns ./finish if it exists.
 ./finish will have ./run's exit code as first argument, or 256 if
 ./run was signaled; it will have the number of the signal that killed ./run
 as second argument, or an undefined number if ./run was not signaled. 
    • 
- 
  •  ./finish must exit in less than 5 seconds. If it takes more than that,
-s6-supervise kills it with a SIGKILL. 
    • 
- 
  •  When ./finish dies, s6-supervise restarts ./run unless it has been
-told not to. 
    • 
+ 
  •  By default, ./finish 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
+./timeout-finish file, see the description in the
+service directory page. 
    • 
+ 
  •  When ./finish dies (or is killed),
+s6-supervise sends a 'D' event to ./event. Then
+it restarts ./run unless it has been told not to. 
    • 
  
  •  There is a minimum 1-second delay between two ./run spawns, to avoid busylooping
 if ./run exits too quickly. 
    • 
  
  •  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
 notification-fd file when the service is started, or restarted,
 s6-supervise creates and listens to an additional pipe from the service
 for readiness notification. When the
-notification occurs, s6-supervise creates a ./supervise/ready
-file containing the absolute time when readiness occurred, then sends
-a 'U' event to ./event. The ./supervise/ready
-file is deleted on service death.
+notification occurs, s6-supervise updates the ./supervise/status
+file accordingly, then sends
+a 'U' event to ./event.
 
    
 
 
    
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.
 
     Interface 
    
 
 
    -     s6-svc [ -D | -U ] [ -T timeout ] [ -abqhkti12pcoduxO ] servicedir
+     s6-svc [ -wu | -wU | -wd | -wD ] [ -T timeout ] [ -abqhkti12pcoduxO ] servicedir
 
    
 
 
    
@@ -75,13 +75,20 @@ it. 
    • 
 (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. 
- 
  •  -D : s6-svc will not exit until the service is down. 
    • 
- 
  •  -U : s6-svc will not exit until the service is up and
+ 
  •  -wd : s6-svc will not exit until the service is down,
+i.e. until the run process has died. 
    • 
+ 
  •  -wD : s6-svc will not exit until the service is down
+and ready to be brought up, i.e. a possible finish script has
+exited. 
    • 
+ 
  •  -wu : s6-svc will not exit until the service is up,
+i.e. there is a process running the run executable. 
    • 
+ 
  •  -wU : s6-svc will not exit until the service is up and
 ready as notified by the daemon itself.
 If the service directory does not contain
 a notification-fd file to tell
 s6-supervise to accept readiness
-notification, s6-svc will print a warning and ignore the command. 
    • 
+notification, s6-svc will print a warning and act as if the -wu
+option had been given instead. 
 
 
 
     Usage examples 
    
@@ -100,12 +107,13 @@ the process represented by the /service/sshd service directory -
 typically the sshd server.
 
    
 
-
     s6-svc -Dd /service/ftpd 
    
+
     s6-svc -wD -d /service/ftpd 
    
 
    
- 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.
 
    
 
-
     s6-svc -Uu -T 5000 /service/ftpd 
    
+
     s6-svc -wU -T 5000 -u /service/ftpd 
    
 
    
  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 s6-log, this triggers a log rotation.
  
  •  s6-svc writes control commands into the servicedir/supervise/control
 FIFO. A s6-supervise process running on servicedir will be listening to this FIFO,
 and will read and interpret those commands. 
    • 
- 
  •  When invoked with the -D or -U option, s6-svc executes into
+ 
  •  When invoked with one of the -w options, s6-svc executes into
 s6-svlisten1, which will listen to service state
-changes and spawn another s6-svc instance (without the -D or -U
-option) that will send the commands to the service. Any error message written during
+changes and spawn another s6-svc instance (without the -w 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. 
    • 
 
 
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.
 
    
 
 
    -     s6-svlisten [ -U | -u | -d ] [ -a | -o ] [ -t timeout ] { servicedir servicedir... } prog...
+     s6-svlisten [ -U | -u | -D | -d ] [ -a | -o ] [ -t timeout ] { servicedir servicedir... } prog...
 
    
 
 
    
@@ -42,7 +42,7 @@ a collection of supervised services, and blocks until they all go up, or down.
 
    
 
 
    -     s6-svlisten [ -U | -u | -d ] [ -a | -o ] [ -t timeout ] servicedir servicedir... "" prog...
+     s6-svlisten [ -U | -u | -D | -d ] [ -a | -o ] [ -t timeout ] servicedir servicedir... "" prog...