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

s6
Software
skarnet.org

# The s6-notify-socket-from-fd program

`s6-notify-socket-from-fd` is different from other chainloading tools in s6: it's not meant to be used in s6 run scripts. Instead, it's meant to be used when you're not using s6, but another service manager that does not support the s6 readiness notification protocol, but supports the NOTIFY_SOCKET protocol.

Typically, you would use it if you have a daemon `foobard` that uses the s6 readiness notification protocol, but need to run that daemon under systemd. Instead of running it with `ExecStart=foobard` and having to use `Type=main`, losing the benefit of notification, you can use `ExecStart="s6-notify-socket-from-fd foobard"` and `Type=notify`, and systemd will handle readiness correctly.

## Interface

         s6-notify-socket-from-fd [ -d fd ] [ -f ] [ -t timeout ] [ -k ] prog...

- If the `NOTIFY_SOCKET` environment variable isn't defined, it means that `s6-notify-socket-from-fd` is not running under a supervisor expecting a systemd-style readiness notification. So it does nothing and just execs into prog.... If the variable is defined, the following points apply.
- `s6-notify-socket-from-fd` doubleforks and runs as the grandchild; the parent immediately execs into prog..., which is expected to use the s6 readiness notification protocol.
- If prog dies before sending its notification, or if the timeout (if any) expires, `s6-notify-socket-from-fd` just exits.
- If prog notifies readiness, `s6-notify-socket-from-fd` sends a systemd-style notification to the supervisor listening to the socket given in `NOTIFY_SOCKET`, then it exits.

## Exit codes

`s6-notify-socket-from-fd` can exit before executing into prog:

- 100: wrong usage
- 111: system call failed

After forking, `s6-notify-socket-from-fd` (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
- 1: service exited before becoming ready
- 99: timed out before readiness was achieved
- 111: system call failed

## Options

`-d fd`, `--notification-fd=fd`
  Expect prog... to send its notification on descriptor fd. Default is 1.
`-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-socket-from-fd` will wait forever for a notification, up to when prog exits.
`-f`, `--no-doublefork`
  Make `s6-notify-socket-from-fd` 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.
`-k`, `--keep-environment`
  Keep the `NOTIFY_SOCKET` environment variable in prog's environment. By default, the variable is removed from it, because prog, not using the systemd notification protocol, normally has no use for it.

## Notes

- `s6-notify-socket-from-fd` sends its notification as a subprocess with a different pid from prog, so the unit file running the service needs the `NotifyAccess=all` directive.
- An early version of this program was previously available on skarnet.org, unpackaged, under the name `sdnotify-wrapper`.
- `s6-notify-socket-from-fd` is for s6-style daemons that you want to run under systemd. If you want to do the opposite, i.e. run under s6 a daemon that uses the systemd protocol, use the s6-notify-fd-from-socket program instead.