From 9458e4e66b775a589b3e881919fe8c7e3db34dc5 Mon Sep 17 00:00:00 2001 From: Joachim Wiberg Date: Sun, 16 Oct 2022 20:36:15 +0200 Subject: [PATCH] Update docs with new readiness notification support Signed-off-by: Joachim Wiberg --- README.md | 4 ++++ doc/config.md | 4 ++-- man/finit.8 | 15 ++++++++++++++- man/finit.conf.5 | 44 ++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 64 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 11a26b59..1d2f4864 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,8 @@ Features include: * Process supervision similar to [systemd][] * Sourcing environment files * Conditions for network/process/custom dependencies + * Readiness notification; PID files (native) for synchronizing system + startup, support for systemd [sd_notify()][], or [s6 style][] too * Pre/Post script actions * Tooling to enable/disable services * Built-in getty @@ -620,6 +622,8 @@ and proposed extensions. [upstart]: https://upstart.ubuntu.com/ [systemd]: https://www.freedesktop.org/wiki/Software/systemd/ [openrc]: https://www.gentoo.org/proj/en/base/openrc/ +[sd_notify()]: https://www.freedesktop.org/software/systemd/man/sd_notify.html +[s6 style]: https://skarnet.org/software/s6/notifywhenup.html [run-parts(8)]: https://manpages.debian.org/cgi-bin/man.cgi?query=run-parts [original finit]: http://helllabs.org/finit/ [EeePC fastinit]: https://web.archive.org/web/20071208212450/http://wiki.eeeuser.com/boot_process:the_boot_process diff --git a/doc/config.md b/doc/config.md index 9b0af3f1..cfa27fbb 100644 --- a/doc/config.md +++ b/doc/config.md @@ -505,8 +505,8 @@ option: service notify:s6 mdevd -C -O 4 -D %n -[sd_notify)]: https://www.freedesktop.org/software/systemd/man/sd_notify.html -[s6 expect]: https://skarnet.org/software/s6/notifywhenup.html +[sd_notify()]: https://www.freedesktop.org/software/systemd/man/sd_notify.html +[s6 expect]: https://skarnet.org/software/s6/notifywhenup.html When a service is ready, either by Finit detecting its PID file, or their respective readiness mechanism has been triggered, Finit creates diff --git a/man/finit.8 b/man/finit.8 index aa3f0c22..fd563e66 100644 --- a/man/finit.8 +++ b/man/finit.8 @@ -45,6 +45,11 @@ Sourcing environment files .It Conditions for network/process/custom dependencies .It +Process readiness notification for synchronizing system startup as well +as reconfiguration at runtime. Natively PID files are used, but systemd +.Cm sd_notify() +and s6 notification is also supported. +.It Pre/Post script actions .It Tooling to enable/disable services @@ -192,7 +197,7 @@ file removed, service B is also stopped. .Pp The following condition families are available today: .Pp -.Bl -tag -width pid -offset indent +.Bl -tag -width service -offset indent .It Cm net Linux netlink events, e.g. net/route/default, net/eth0/up, and net/et0/running @@ -200,6 +205,14 @@ net/et0/running PID files basd on the service declaration .Cm name:id , gives the condition pid/name:id +.It Cm service +Tracks run/task/service state stansitions, including readiness. E.g., +.Cm service/foo/ready +can be used as a condition for service +.Cm bar , +provided +.Cm foo +properly signals its readiness to Finit. .It Cm sys System conditions, e.g. sys/key/ctrlaltdel and sys/pwr/fail .It Cm usr diff --git a/man/finit.conf.5 b/man/finit.conf.5 index 161b8ff5..6ec4c535 100644 --- a/man/finit.conf.5 +++ b/man/finit.conf.5 @@ -275,6 +275,50 @@ can depend on the .Cm condition. .Pp +As an alternative "readiness" notification, Finit supports both systemd +and s6 style notification. This can be enabled by using the `notify` +option: +.Bl -tag -width 1n +.It Cm notify:systemd +tells Finit the service uses the +.Cm sd_notify() +API to signal PID 1 when it has completed its startup and is ready +to service events. This API expects +the environment variable +.Cm NOTIFY_SOCKET +to be set to the socket where the application can send +.Cm "READY=1\n" +when it is starting up or has processed a +.Cm SIGHUP . +For details, see: +.Pp +.Lk https://www.freedesktop.org/software/systemd/man/sd_notify.html +.It Cm notify:s6 +puts Finit in s6 compatibility mode. Compared to the systemd +notification, s6 expect compliant daemons to send +.Cm "\\n" +and then close their socket. For details, see: +.Pp +.Lk https://skarnet.org/software/s6/notifywhenup.html +.Pp +Finit takes care of "hard-wiring" the READY state as long as the +application is running, events across any `SIGHUP`. Since s6 can give +its applications the descriptor number (must be >3) on then command +line, Finit provides the following syntax ( +.Cm %n +is replaced by Finit with then descriptor number): +.Bd -unfilled -offset indent +service notify:s6 mdevd -C -O 4 -D %n +.Ed +.Pp +When a service is ready, either by Finit detecting its PID file, or +their respective readiness mechanism has been triggered, Finit creates +then service's ready condition which other services can depend on: + + $ initctl -v cond get service/mdevd/ready + on +.El +.Pp If a service should not be automatically started, it can be configured as manual with the .Cm manual:yes