From 383917ac67570e2dccd558bcde3910a686b9f077 Mon Sep 17 00:00:00 2001 From: Luca Boccassi Date: Sun, 31 Mar 2024 23:18:09 +0100 Subject: [PATCH] man: add self-contained example of notify protocol We are saying in public that the protocl is stable and can be easily reimplemented, so provide an example doing so in the documentation, license as MIT-0 so that it can be copied and pasted at will. --- docs/PORTABILITY_AND_STABILITY.md | 6 +- man/notify-selfcontained-example.c | 173 +++++++++++++++++++++++++++++ man/sd_notify.xml | 5 + man/systemd.service.xml | 12 +- 4 files changed, 194 insertions(+), 2 deletions(-) create mode 100644 man/notify-selfcontained-example.c diff --git a/docs/PORTABILITY_AND_STABILITY.md b/docs/PORTABILITY_AND_STABILITY.md index abdc3dc6580..fda42c84c05 100644 --- a/docs/PORTABILITY_AND_STABILITY.md +++ b/docs/PORTABILITY_AND_STABILITY.md @@ -15,7 +15,11 @@ The stable interfaces are: * **The command line interface** of `systemd`, `systemctl`, `loginctl`, `journalctl`, and all other command line utilities installed in `$PATH` and documented in a man page. We will make sure that scripts invoking these commands will continue to work with future versions of systemd. Note however that the output generated by these commands is generally not included in the promise, unless it is documented in the man page. Example: the output of `systemctl status` is not stable, but that of `systemctl show` is, because the former is intended to be human readable and the latter computer readable, and this is documented in the man page. -* **The protocol spoken on the socket referred to by `$NOTIFY_SOCKET`**, as documented in [sd_notify(3)](https://www.freedesktop.org/software/systemd/man/sd_notify.html). +* **The protocol spoken on the socket referred to by `$NOTIFY_SOCKET`**, as documented in + [sd_notify(3)](https://www.freedesktop.org/software/systemd/man/sd_notify.html). Note that, although using + libsystemd is a good choice, this protocol can also be reimplemented without external dependencies, as + demonstrated in the example listed in + [systemd.service(5)](https://www.freedesktop.org/software/systemd/man/systemd.service.html) * Some of the **"special" unit names** and their semantics. To be precise the ones that are necessary for normal services, and not those required only for early boot and late shutdown, with very few exceptions. To list them here: `basic.target`, `shutdown.target`, `sockets.target`, `network.target`, `getty.target`, `graphical.target`, `multi-user.target`, `rescue.target`, `emergency.target`, `poweroff.target`, `reboot.target`, `halt.target`, `runlevel[1-5].target`. diff --git a/man/notify-selfcontained-example.c b/man/notify-selfcontained-example.c new file mode 100644 index 00000000000..9a7553e3013 --- /dev/null +++ b/man/notify-selfcontained-example.c @@ -0,0 +1,173 @@ +/* SPDX-License-Identifier: MIT-0 */ + +/* Implement the systemd notify protocol without external dependencies. + * Supports both readiness notification on startup and on reloading, + * according to the protocol defined at: + * https://www.freedesktop.org/software/systemd/man/latest/sd_notify.html + * This protocol is guaranteed to be stable as per: + * https://systemd.io/PORTABILITY_AND_STABILITY/ */ + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#define _cleanup_(f) __attribute__((cleanup(f))) + +static void closep(int *fd) { + if (!fd || *fd < 0) + return; + + close(*fd); + *fd = -1; +} + +static int notify(const char *message) { + union sockaddr_union { + struct sockaddr sa; + struct sockaddr_un sun; + } socket_addr = { + .sun.sun_family = AF_UNIX, + }; + size_t path_length, message_length; + _cleanup_(closep) int fd = -1; + const char *socket_path; + + socket_path = getenv("NOTIFY_SOCKET"); + if (!socket_path) + return 0; /* Not running under systemd? Nothing to do */ + + if (!message) + return -EINVAL; + + message_length = strlen(message); + if (message_length == 0) + return -EINVAL; + + /* Only AF_UNIX is supported, with path or abstract sockets */ + if (socket_path[0] != '/' && socket_path[0] != '@') + return -EAFNOSUPPORT; + + path_length = strlen(socket_path); + /* Ensure there is room for NUL byte */ + if (path_length >= sizeof(socket_addr.sun.sun_path)) + return -E2BIG; + + memcpy(socket_addr.sun.sun_path, socket_path, path_length); + + /* Support for abstract socket */ + if (socket_addr.sun.sun_path[0] == '@') + socket_addr.sun.sun_path[0] = 0; + + fd = socket(AF_UNIX, SOCK_DGRAM|SOCK_CLOEXEC, 0); + if (fd < 0) + return -errno; + + if (connect(fd, &socket_addr.sa, offsetof(struct sockaddr_un, sun_path) + path_length) != 0) + return -errno; + + ssize_t written = write(fd, message, message_length); + if (written != (ssize_t) message_length) + return written < 0 ? -errno : -EPROTO; + + return 1; /* Notified! */ +} + +static int notify_ready(void) { + return notify("READY=1"); +} + +static int notify_reloading(void) { + /* A buffer with length sufficient to format the maximum UINT64 value. */ + char reload_message[sizeof("RELOADING=1\nMONOTONIC_USEC=18446744073709551615")]; + struct timespec ts; + uint64_t now; + + /* Notify systemd that we are reloading, including a CLOCK_MONOTONIC timestamp in usec + * so that the program is compatible with a Type=notify-reload service. */ + + if (clock_gettime(CLOCK_MONOTONIC, &ts) < 0) + return -errno; + + if (ts.tv_sec < 0 || ts.tv_nsec < 0 || + (uint64_t) ts.tv_sec > (UINT64_MAX - (ts.tv_nsec / 1000ULL)) / 1000000ULL) + return -EINVAL; + + now = (uint64_t) ts.tv_sec * 1000000ULL + (uint64_t) ts.tv_nsec / 1000ULL; + + if (snprintf(reload_message, sizeof(reload_message), "RELOADING=1\nMONOTONIC_USEC=%" PRIu64, now) < 0) + return -EINVAL; + + return notify(reload_message); +} + +static volatile sig_atomic_t reloading = 0; +static volatile sig_atomic_t terminating = 0; + +static void signal_handler(int sig) { + if (sig == SIGHUP) + reloading = 1; + else if (sig == SIGINT || sig == SIGTERM) + terminating = 1; +} + +int main(int argc, char **argv) { + struct sigaction sa = { + .sa_handler = signal_handler, + .sa_flags = SA_RESTART, + }; + int r; + + /* Setup signal handlers */ + sigemptyset(&sa.sa_mask); + sigaction(SIGHUP, &sa, NULL); + sigaction(SIGINT, &sa, NULL); + sigaction(SIGTERM, &sa, NULL); + + /* Do more service initialization work here … */ + + /* Now that all the preparations steps are done, signal readiness */ + + r = notify_ready(); + if (r < 0) { + fprintf(stderr, "Failed to notify readiness to $NOTIFY_SOCKET: %s\n", strerror(-r)); + return EXIT_FAILURE; + } + + while (!terminating) { + if (reloading) { + reloading = false; + + /* As a separate but related feature, we can also notify the manager + * when reloading configuration. This allows accurate state-tracking, + * and also automated hook-in of 'systemctl reload' without having to + * specify manually an ExecReload= line in the unit file. */ + + r = notify_reloading(); + if (r < 0) { + fprintf(stderr, "Failed to notify reloading to $NOTIFY_SOCKET: %s\n", strerror(-r)); + return EXIT_FAILURE; + } + + /* Do some reconfiguration work here … */ + + r = notify_ready(); + if (r < 0) { + fprintf(stderr, "Failed to notify readiness to $NOTIFY_SOCKET: %s\n", strerror(-r)); + return EXIT_FAILURE; + } + } + + /* Do some daemon work here … */ + sleep(5); + } + + return EXIT_SUCCESS; +} diff --git a/man/sd_notify.xml b/man/sd_notify.xml index 1e611fe6d86..22b351cad31 100644 --- a/man/sd_notify.xml +++ b/man/sd_notify.xml @@ -493,6 +493,11 @@ privileged port (i.e.: lower than 1024), as an attempt to address concerns that unprivileged processes in the guest might try to send malicious notifications to the host, driving it to make destructive decisions based on them. + + Note that, while using this library should be preferred in order to avoid code duplication, it is + also possible to reimplement the simple readiness notification protocol without external dependencies, + as demonstrated in the following self-contained example: + diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 67a3930a28a..9a0c8166eff 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -1728,7 +1728,7 @@ SystemdService=simple-dbus-service.service Description=Simple notifying service [Service] -Type=notify +Type=notify-reload ExecStart=/usr/sbin/simple-notifying-service [Install] @@ -1746,6 +1746,16 @@ WantedBy=multi-user.target systemd.kill5 for details on how you can influence the way systemd terminates the service. + + To avoid code duplication, it is preferable to use + sd_notify3 + when possible, especially when other APIs provided by + libsystemd3 are + also used, but note that the notification protocol is very simple and guaranteed to be stable as per + the Interface Portability and Stability + Promise, so it can be reimplemented by services with no external dependencies. For a + self-contained example, see + sd_notify3. -- 2.39.5