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-applyuidgid.html | 2 +- doc/s6-background-watch.html | 128 +++++++++++++++++++++++++++++++++++++++++++ doc/servicedir.html | 28 +++++++++- 3 files changed, 155 insertions(+), 3 deletions(-) create mode 100644 doc/s6-background-watch.html (limited to 'doc') diff --git a/doc/s6-applyuidgid.html b/doc/s6-applyuidgid.html index c532d30..9502ca6 100644 --- a/doc/s6-applyuidgid.html +++ b/doc/s6-applyuidgid.html @@ -48,7 +48,7 @@ value overrides the environment variable.

-z : unexport. The UID, GID and GIDLIST variables will be removed from the process environment.

- +

Notes

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. +

s6-svc -u

An optional regular file named notification-fd. If such a file exists, it means that the service supports readiness notification. The file must only - contain an unsigned integer, which is the number of the file descriptor that + contain a nonzero unsigned integer, which is the number of the file descriptor that the service writes its readiness notification to. (For instance, it should be 1 if the daemon is s6-ipcserverd run with the -1 option.) @@ -164,7 +164,7 @@ notification from the service and broadcast readiness, i.e. any triggered.
An optional regular file named lock-fd. If such a file -exists, it must contain an unsigned integer, representing a file descriptor that +exists, it must contain a nonzero unsigned integer, representing a file descriptor that will be open in the service. The service should not write to that descriptor and should not close it. In other words, it should totally ignore it. That file descriptor holds a lock, that will naturally be released when the service dies. @@ -221,6 +221,30 @@ be very bad.)

An optional regular file named pidfile. +Creating such a file is not recommended, but is a workaround — and only +a workaround — for daemons that background themselves. If this file +exists, it must contain the path (either absolute or relative to the service +directory) to a pid file, followed by a newline; the path must be shorter than +512 bytes. The following behaviour is then expected: +

On startup, the daemon must fork.
The child then becomes the long-running process.
The parent must write the pid of the child, followed by a newline, to the +pid file whose path is written in the pidfile file in the service +directory. For instance, if the daemon writes its pid to /var/run/foo.pid, +then you would configure s6-supervise with echo /var/run/foo.pid +> pidfile.
After writing the pid file, the parent must exit 0.
If the notification-fd file is present in the service directory, +s6-supervise will report the daemon to be ready +once the parent has exited.
s6-supervise will then supervise the child +as if it had not forked.

+If the file does not exist, s6-supervise only +supervises daemons that do not background themselves, which is the normal case.

A fifodir named event. It is automatically created by s6-supervise if it does not exist. foo/event -- cgit v1.3.1