From ea67a084fac347a543d86e2c761340dee36d380f Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Sat, 19 Aug 2017 15:37:17 +0000 Subject: Add s6-notifyoncheck --- doc/s6-notifyoncheck.html | 160 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 160 insertions(+) create mode 100644 doc/s6-notifyoncheck.html (limited to 'doc/s6-notifyoncheck.html') diff --git a/doc/s6-notifyoncheck.html b/doc/s6-notifyoncheck.html new file mode 100644 index 0000000..74cb6cd --- /dev/null +++ b/doc/s6-notifyoncheck.html @@ -0,0 +1,160 @@ + + + + + + s6: the s6-notifyoncheck program + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The s6-notifyoncheck program

+ +

+s6-notifyoncheck is a chain-loading program meant to be used +in run scripts, in a service that has been declared to honor +readiness notification. It implements a policy of running a user-provided +executable in the background that polls the service currently being +launched, in order to check when it becomes ready. It feeds the +result of this check into the s6 notification mechanism. +

+ +

+s6-notifyoncheck should only be used with daemons +that can be polled from the outside to check readiness, and that +do not implement readiness notification themselves. +

+ +

Interface

+ +

+     s6-notifyoncheck [ -d ] [ -3 notiffd ] [ -s initialsleep ] [ -T globaltimeout ] [ -t localtimeout ] [ -w waitingtime ] [ -n n ] [ -c checkprog ] prog...
+

+ +

+ s6-notifyoncheck forks and runs as the child; the parent immediately execs into +prog..., the daemon that must be checked for readiness. +

+ +

+ s6-notifyoncheck first waits for a little time, then it spawns the +./data/check executable and waits for it to exit. If ./data/check +exits 0, then s6-notifyoncheck reports that the service is ready, then +exits. If ./data/check exits anything else, s6-notifyoncheck sleeps +for a little time, then spawns ./data/check again. It loops until +./data/check succeeds, or 7 attempts fail, or a certain amount of +time elapses. +

+ +

Exit codes

+ +

+ s6-notifyoncheck can exit before executing into prog: +

+ +

100: wrong usage
111: system call failed

+ +

+ After forking, s6-notifyoncheck (running as the child) can +exit with the following exit codes, but those are meaningless +because no process will, or should, check them. They are only +differentiated for clarity in the code: +

+ +

0: service readiness achieved and notification sent
1: maximum number of attempts reached, all unsuccessful
2: prog died, so s6-notifyoncheck exited early
3: timed out before readiness was achieved
111: system call failed

+ +

Options

+ +

-d : doublefork. s6-notifyoncheck will run as the +grandchild of prog... instead of its direct child. This is useful +if prog... never reaps zombies it does not know it has.
-3 notiffd : use fd as the +file descriptor to send a readiness notification to. By default, this +number is automatically read from the ./notification-fd file.
-s initialsleep : sleep for +initialsleep milliseconds before starting to poll the service +for readiness. Default is 10 milliseconds.
-T globaltimeout : give up (and leave +the service up but not ready if service readiness still +has not been detected after globaltimeout milliseconds. Default +is 0, meaning infinite: s6-notifyoncheck will keep polling until it succeeds.
-t localtimeout : on every attempt, if +./check still has not exited after localtimeout milliseconds, +kill it and declare that attempt failed. Default is 0, meaning infinite: +s6-notifyoncheck will wait forever for ./data/check to exit.
-w waitingtime : sleep for +waitingtime milliseconds between two invocations of ./data/check. +This is basically the polling period. Default is 1000: the service will +be polled every second.
-n n : give up after n +unsuccessful invocations of ./data/check. 0 means infinite, i.e. keep +polling until it succeeds, or times out, or the service dies first.
-c checkprog... : invoke checkprog... +instead of ./data/check. The checkprog string will be parsed by +execlineb, so it +can contain a full command line. This option is mainly useful is the program +used to poll the service is very simple and can be inlined as a simple +command line, to avoid needing to manage a whole script and a ./data/check +file.

+ +

Usage

+ +

+ s6-notifyoncheck is designed to make it possible for services to use the +s6 notification +mechanism even with daemons that do not natively implement the +mechanism of writing a newline to a file descriptor of their choice when +they're ready. +

+ +

+Polling +is evil. Please make sure you really have no other choice before writing a +./data/check program and using s6-notifyoncheck in your run script. +If you have access to the source code of the daemon you want to check for +readiness, consider patching it to add readiness notification support, which +is extremely simple and does not require linking against any s6 library. +

+ +

+ If using a ./data/check program is your only option: +

+ +

Make sure the ./data subdirectory is readable and that +./data/check is executable, exits 0 if the daemon +it checks is ready, and exits nonzero if the daemon is not ready.
Add a ./notification-fd file to your service directory, +which can contain any number that is not 0, 1 or 2, or anything else +explicitly used in your run script. The daemon does not need to care +about that file descriptor; from the daemon's point of view, nothing +changes.
In your run script, insert s6-notifyoncheck in the +command line that will execute into your daemon.
./data/check will run as the same user as s6-notifyoncheck. +If s6-notifyoncheck runs after the run script's process has lost its +root privileges, make sure that ./data/check is accessible +and runnable as that user.

+ + + -- cgit v1.3.1