The s6-notify-fd-from-socket
s6-notify-fd-from-socket is meant to be used in a run script, when you want to use s6 to supervise a program that follows systemd's NOTIFY_SOCKET protocol. It converts a readiness notification sent via that protocol into s6's native format.
Interface
s6-notify-fd-from-socket [ -3 fd ] [ -f ] [ -t timeout ] prog...
- s6-notify-fd-from-socket doubleforks and runs as the grandchild; the parent immediately execs into prog..., which is expected to use the NOTIFY_SOCKET protocol.
- If prog dies before sending its notification, or if the timeout (if any) expires, s6-notify-fd-from-socket just exits.
- If prog notifies readiness, s6-notify-fd-from-socket writes a newline to the file descriptor configured for the service, then it exits.
Exit codes
s6-notify-fd-from-socket can exit before executing into prog:
- 100: wrong usage
- 111: system call failed
After forking, s6-notify-fd-from-socket (running as a child or grandchild) 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 source code:
- 0: service readiness achieved and notification sent
- 99: timed out before readiness was achieved
- 111: system call failed
Options
- -3 fd, --notification-fd=fd
- Force writing the readiness notification to descriptor fd. By default, the notification is sent to the descriptor written in the notification-fd file of the service directory, and it is an error if this file does not exist (because the supervisor needs to be prepared to receive the notification).
- -t timeout, --timeout=timeout
- Exit without notifying the supervisor if prog hasn't notified readiness after timeout milliseconds. Default is 0, meaning infinite: s6-notify-fd-from-socket will wait forever for a notification, up to when prog exits.
- -f, --no-doublefork
- Make s6-notify-fd-from-socket live as a direct child of prog rather than doubleforking. It is less costly (it might save a millisecond), but it will leave a zombie around if prog does not know how to reap its bastards (children it doesn't know it has). If prog reaps everything, you can safely use this option; otherwise, leave it alone.
Notes
- s6-notify-fd-from-socket only understands the READY=1 line of the NOTIFY_SOCKET protocol. It will ignore any other line, and extensions will not be added. It will only work for readiness notification, and not for generic communication with the supervisor, fd transmission, or anything of the kind. There is a way to store file descriptors with s6: s6-fdholder-store, which can be used in a run script, and is entirely independent from the readiness notification protocol.
- s6-notify-fd-from-socket is for daemons using the systemd protocol that you want to run under s6. If you want to do the opposite, i.e. run under systemd a daemon that uses the s6 notification protocol, use the s6-notify-socket-from-fd program instead.
- Despite building on every OS supported by s6, s6-notify-fd-from-socket will only work on systems implementing abstract sockets with autobind, which in practice means Linux 2.3.15 and later. Other systems do not have systemd anyway, so services should choose other notification mechanisms.