s6: the s6-notify-fd-from-socket program
Keywords: s6 command s6-notify-fd-from-socket NOTIFY_SOCKET systemd notification service check

s6
Software
skarnet.org

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