From b1b5cca013c200014799953dd40d0b9e2ea88e63 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Wed, 22 Oct 2025 03:03:53 +0000 Subject: Add some doc, improve s6-background-watch --- doc/s6-background-watch.html | 128 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 doc/s6-background-watch.html (limited to 'doc/s6-background-watch.html') diff --git a/doc/s6-background-watch.html b/doc/s6-background-watch.html new file mode 100644 index 0000000..45248ce --- /dev/null +++ b/doc/s6-background-watch.html @@ -0,0 +1,128 @@ + + + + + + s6: the s6-background-watch program + + + + + + +

+s6
+Software
+skarnet.org +

+ +

The s6-background-watch program

+ +

+ s6-background-watch spawns an auto-backgrounding daemon that writes a pidfile. +It reads the pidfile then transmits the signals it receives to the corresponding +process. It dies when the corresponding process dies, with an +approximation of +its exit code. +

+ +

+ s6-background-watch is meant as a workaround to auto-backgrounding +daemons. (Not a solution, because the solution is to fix +the daemon so it runs without backgrounding itself!) It should be run on the +command line of a run script, right before the invocation of the auto-backgrounding +daemon. +

+ +

+ s6-background-watch only works on Linux (or any systems implementing +PR_SET_CHILD_SUBREAPER) +and the BSDs (or any system implementing +kevent +with the EVFILT_PROC filter and the NOTE_EXIT fflag). Most modern systems will +implement one of these. +

+ +

Interface

+ +

+     s6-background-watch [ -t timeout ] [ -d notif ] pidfile prog...
+

+ +

s6-background-watch spawns prog... as a child.
prog... is expected to fork. The child process is supposed to be +long-lived, i.e. the child the daemon that is to be supervised.
The parent is expected to write the child's pid to the pidfile file.
The parent is expected to exit 0 when the child is ready.
Once the parent has exited, s6-background-watch reads pidfile to get +the pid of the daemon.
s6-background-watch transmits all the signals it receives to the daemon. +Non-catchable signals, such as SIGKILL, will obviously not work, so, don't do this.
s6-background-watch exits when the daemon exits, with an +approximation of the +daemon's exit code. (In most cases it will be the exact same exit code.)

+ +

Options

+ +

-t timeout, --timeout-ready=timeout: If the parent daemon has not exited after timeout milliseconds, +kill it and exit. By default, there is no timeout, s6-background-watch will wait as +long as needed.
-d notif, --notification-fd=notif: Write a newline to file descriptor notif when the parent has +exited 0 and s6-background-watch has successfully read pidfile. This +is useful when the daemon follows the convention that the child is ready when +the parent exits: use the -d option in conjunction with the +notification-fd file, and s6-supervise +will accurately report the daemon's readiness.

+ +

Exit codes

+ +

100: Bad usage.
111: System call failed. This is generally a temporary error, +or indicates a problem with the underlying system.
112: Functionality not supported. You cannot run +s6-background-watch on this OS, because it lacks the necessary features. +
128+n: The parent daemon was killed with signal n. +In particular, 137 can happen if the -t option has been given and +the parent daemon times out: s6-background-watch kills it with SIGKILL.
n: The child daemon exited with code n.

+ +

Notes

+ +

+ s6-background-watch acts as a proxy between s6-supervise +and the forking daemon. It stays in the foreground, keeping s6-supervise happy; and it +keeps track of the daemon as best as it can, transmitting it signals. It is a better +iteration of s6-fghack, which is obsolescent. However, it +is not perfect, because it cannot be: +

+ +

s6-svc -k, i.e. SIGKILL, is very bad. +It will kill s6-background-watch without killing the backgrounded daemon, and +all links to the daemon are lost. If the service restarts, it will probably fail, +because the previous instance of the daemon is still alive. You may be able to +mitigate that with the use of a lock-fd file.
The race condition inherent to pidfiles is there: between the moment +the daemon writes its pidfile and the moment s6-background-watch reads it and +attempts to track it, the daemon could have died and another pid taken its place. +The design of s6-background-watch makes this race window minimal (the system has +to loop over the whole pid space between the moment the pidfile is written and +the moment s6-background-watch reads it, which is right afterwards, so +it's not as bad as most uses of pidfiles, but the race theoretically still exists.
In order to detect the death of a process that isn't a direct child, +which isn't a functionality guaranteed by POSIX, OS-specific mechanisms have to +be used, and not all the supported OSes have such mechanisms. If the OS has no usable +mechanism for this, s6-background-watch will immediately exit with an error message. +

+ + + + -- cgit v1.3.1