From 8a5a621baa9e756b34c507c3d8e2119dabe7f630 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Thu, 9 Apr 2026 02:31:43 +0000 Subject: Add s6-notify-fd-from-socket and s6-notify-socket-from-fd Also add .gitkeep files, remove old include-local/s6lockd.h, update a little bit of doc, make s6-ftrigrd pipe-only --- doc/index.html | 58 +++++++++-------- doc/s6-notify-fd-from-socket.html | 110 ++++++++++++++++++++++++++++++++ doc/s6-notify-socket-from-fd.html | 129 ++++++++++++++++++++++++++++++++++++++ doc/upgrade.html | 3 + 4 files changed, 275 insertions(+), 25 deletions(-) create mode 100644 doc/s6-notify-fd-from-socket.html create mode 100644 doc/s6-notify-socket-from-fd.html (limited to 'doc') diff --git a/doc/index.html b/doc/index.html index 721c5f1..bb1d762 100644 --- a/doc/index.html +++ b/doc/index.html @@ -162,7 +162,7 @@ ports the s6 documentation to a set of man pages. Short-lived commands exit 0 on success.

Supervision system

s6-svscan and s6-supervise @@ -180,17 +180,24 @@ a user interface to control those processes and monitor service states.

The s6-svperms program

The s6-svlink program

The s6-svunlink program

The s6-svwait program

The s6-svlisten1 program

The s6-svlisten program

The s6-notifyoncheck program

The s6-svdt program

The s6-svdt-clear program

The s6-permafailon program

The s6-background-watch program

Daemontools-like utilities

Readiness notification for supervised services

+ +

Misc utilities for run scripts

These programs are a rewrite of the corresponding utilities from @@ -211,14 +218,13 @@ a few extras.

The s6-tai64nlocal program

Fifodir management, notification and subscription

-These programs are a clean rewrite of the obsolete "pipe-tools" package; they -are now based on a properly designed notification library. -They provide a command-line interface to +These programs provide a command-line interface to inter-process notification and -synchronization. +synchronization. They're a generalized interface to the same +mechanisms used by tools like s6-svwait.

The s6-ftrigrd internal program

Local service management and access control

Management of dynamic instances

An overview of dynamic instantiation in s6
The s6-instance-list program

fd-holding, a.k.a. the sensible part of socket activation

The s6-fdholder-daemon program

s6 manual pages

flexibeast is doing the ungrateful -but valuable work of -providing the s6 documentation -as a set of man pages.
Lennart Jablonka is doing the ungrateful +but valuable work of providing the s6 documentation +as a set of man pages.

Other components for s6-based init systems

s6-linux-init is a package to help you create a /sbin/init binary booting a Linux system with s6-svscan as process 1.
s6-overlay -is a project that automates integration of s6 into Docker images.
s6-rc is a dependency-based service manager for s6.
s6-frontend is +a friendlier user interface to address the complete s6 ecosystem (this +package, s6-linux-init and s6-rc).
s6-overlay +is a project that automates integration of s6 into Docker images.
anopa is another dependency-based service manager for s6.
66 is another @@ -362,8 +370,8 @@ service manager working on top of s6.

s6 is discussed on the supervision mailing-list.
There is a #s6 IRC channel on OFTC. Sometimes people are there -and answer questions.
There is a #s6 IRC channel on OFTC. It hosts most discussions +around supervision topics, and skaware in general.

Similar work

s6: the s6-notify-fd-from-socket program

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

s6: the s6-notify-socket-from-fd program

+s6
+Software
+skarnet.org +

The s6-notify-socket-from-fd program

+s6-notify-socket-from-fd is different from other chainloading +tools in s6, in as 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
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

This program was previously available on skarnet.org outside of any +package, 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.

The API of the ftrigr library is somewhat different.

New binaries: +s6-notify-fd-from-socket, +s6-notify-socket-from-fd.

-- cgit v1.3.1

Supervision system

Supervision system

Daemontools-like utilities

Readiness notification for supervised services

Misc utilities for run scripts

Fifodir management, notification and subscription

Fifodir management, notification and subscription

Local service management and access control

Unix domain super-server, local service management and access control

suidless privilege gain

suidless privilege gain

Logging

Logging

Management of user supervision trees

Management of user supervision trees

Management of dynamic instances

Management of dynamic instances

fd-holding, a.k.a. the sensible part of socket activation

fd-holding, a.k.a. the sensible part of socket activation

s6 manual pages

Other components for s6-based init systems

Similar work

The s6-notify-fd-from-socket

Interface

Exit codes

Options

Notes

The s6-notify-socket-from-fd program

Interface

Exit codes

Options

Notes