From b750101eb236130cf056c675997decbac904cc49 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 17:35:18 +0200 Subject: Adding upstream version 252.22. Signed-off-by: Daniel Baumann --- man/sd_notify.xml | 471 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 471 insertions(+) create mode 100644 man/sd_notify.xml (limited to 'man/sd_notify.xml') diff --git a/man/sd_notify.xml b/man/sd_notify.xml new file mode 100644 index 0000000..de40295 --- /dev/null +++ b/man/sd_notify.xml @@ -0,0 +1,471 @@ + + + + + + + + sd_notify + systemd + + + + sd_notify + 3 + + + + sd_notify + sd_notifyf + sd_pid_notify + sd_pid_notifyf + sd_pid_notify_with_fds + sd_notify_barrier + Notify service manager about start-up completion and other service status changes + + + + + #include <systemd/sd-daemon.h> + + + int sd_notify + int unset_environment + const char *state + + + + int sd_notifyf + int unset_environment + const char *format + … + + + + int sd_pid_notify + pid_t pid + int unset_environment + const char *state + + + + int sd_pid_notifyf + pid_t pid + int unset_environment + const char *format + … + + + + int sd_pid_notify_with_fds + pid_t pid + int unset_environment + const char *state + const int *fds + unsigned n_fds + + + + int sd_notify_barrier + int unset_environment + uint64_t timeout + + + + + + Description + sd_notify() may be called by a service + to notify the service manager about state changes. It can be used + to send arbitrary information, encoded in an + environment-block-like string. Most importantly, it can be used for + start-up completion notification. + + If the unset_environment parameter is + non-zero, sd_notify() will unset the + $NOTIFY_SOCKET environment variable before + returning (regardless of whether the function call itself + succeeded or not). Further calls to + sd_notify() will then fail, but the variable + is no longer inherited by child processes. + + The state parameter should contain a + newline-separated list of variable assignments, similar in style + to an environment block. A trailing newline is implied if none is + specified. The string may contain any kind of variable + assignments, but the following shall be considered + well-known: + + + + READY=1 + + Tells the service manager that service startup is finished, or the service finished loading its + configuration. This is only used by systemd if the service definition file has Type=notify + set. Since there is little value in signaling non-readiness, the only value services should send is + READY=1 (i.e. READY=0 is not defined). + + + + RELOADING=1 + + Tells the service manager that the service is + reloading its configuration. This is useful to allow the + service manager to track the service's internal state, and + present it to the user. Note that a service that sends this + notification must also send a READY=1 + notification when it completed reloading its + configuration. Reloads are propagated in the same way as they + are when initiated by the user. + + + + STOPPING=1 + + Tells the service manager that the service is + beginning its shutdown. This is useful to allow the service + manager to track the service's internal state, and present it + to the user. + + + + STATUS=… + + Passes a single-line UTF-8 status string back + to the service manager that describes the service state. This + is free-form and can be used for various purposes: general + state feedback, fsck-like programs could pass completion + percentages and failing programs could pass a human-readable + error message. Example: STATUS=Completed 66% of file + system check… + + + + ERRNO=… + + If a service fails, the errno-style error + code, formatted as string. Example: ERRNO=2 + for ENOENT. + + + + BUSERROR=… + + If a service fails, the D-Bus error-style + error code. Example: + BUSERROR=org.freedesktop.DBus.Error.TimedOut + + + + MAINPID=… + + The main process ID (PID) of the service, in + case the service manager did not fork off the process itself. + Example: MAINPID=4711 + + + + WATCHDOG=1 + + Tells the service manager to update the + watchdog timestamp. This is the keep-alive ping that services + need to issue in regular intervals if + WatchdogSec= is enabled for it. See + systemd.service5 + for information how to enable this functionality and + sd_watchdog_enabled3 + for the details of how the service can check whether the + watchdog is enabled. + + + + WATCHDOG=trigger + + Tells the service manager that the service detected an internal error that should be handled by + the configured watchdog options. This will trigger the same behaviour as if WatchdogSec= is + enabled and the service did not send WATCHDOG=1 in time. Note that + WatchdogSec= does not need to be enabled for WATCHDOG=trigger to trigger + the watchdog action. See + systemd.service5 for + information about the watchdog behavior. + + + + WATCHDOG_USEC=… + + Reset watchdog_usec value during runtime. + Notice that this is not available when using sd_event_set_watchdog() + or sd_watchdog_enabled(). + Example : WATCHDOG_USEC=20000000 + + + + EXTEND_TIMEOUT_USEC=… + + Tells the service manager to extend the startup, runtime or shutdown service timeout + corresponding the current state. The value specified is a time in microseconds during which the service must + send a new message. A service timeout will occur if the message isn't received, but only if the runtime of the + current state is beyond the original maximum times of TimeoutStartSec=, RuntimeMaxSec=, + and TimeoutStopSec=. + See systemd.service5 + for effects on the service timeouts. + + + + FDSTORE=1 + + Stores additional file descriptors in the service manager. File descriptors sent this way will + be maintained per-service by the service manager and will later be handed back using the usual file descriptor + passing logic at the next invocation of the service (e.g. when it is restarted), see + sd_listen_fds3. This is + useful for implementing services that can restart after an explicit request or a crash without losing + state. Any open sockets and other file descriptors which should not be closed during the restart may be stored + this way. Application state can either be serialized to a file in /run/, or better, stored + in a memfd_create2 memory + file descriptor. Note that the service manager will accept messages for a service only if its + FileDescriptorStoreMax= setting is non-zero (defaults to zero, see + systemd.service5). If + FDPOLL=0 is not set and the file descriptors sent are pollable (see + epoll_ctl2), then any + EPOLLHUP or EPOLLERR event seen on them will result in their + automatic removal from the store. Multiple arrays of file descriptors may be sent in separate messages, in + which case the arrays are combined. Note that the service manager removes duplicate (pointing to the same + object) file descriptors before passing them to the service. When a service is stopped, its file descriptor + store is discarded and all file descriptors in it are closed. Use sd_pid_notify_with_fds() + to send messages with FDSTORE=1, see below. + + + + FDSTOREREMOVE=1 + + Removes file descriptors from the file descriptor store. This field needs to be combined with + FDNAME= to specify the name of the file descriptors to remove. + + + + FDNAME=… + + When used in combination with FDSTORE=1, specifies a name for the submitted + file descriptors. When used with FDSTOREREMOVE=1, specifies the name for the file + descriptors to remove. This name is passed to the service during activation, and may be queried using + sd_listen_fds_with_names3. File + descriptors submitted without this field set, will implicitly get the name stored + assigned. Note that, if multiple file descriptors are submitted at once, the specified name will be assigned to + all of them. In order to assign different names to submitted file descriptors, submit them in separate + invocations of sd_pid_notify_with_fds(). The name may consist of arbitrary ASCII + characters except control characters or :. It may not be longer than 255 characters. If a + submitted name does not follow these restrictions, it is ignored. + + + + FDPOLL=0 + + When used in combination with FDSTORE=1, disables polling of the stored + file descriptors regardless of whether or not they are pollable. As this option disables automatic cleanup + of the stored file descriptors on EPOLLERR and EPOLLHUP, care must be taken to ensure proper manual cleanup. + Use of this option is not generally recommended except for when automatic cleanup has unwanted behavior such + as prematurely discarding file descriptors from the store. + + + + BARRIER=1 + + Tells the service manager that the client is explicitly requesting synchronization by + means of closing the file descriptor sent with this command. The service manager guarantees that the + processing of a BARRIER=1 command will only happen after all previous notification + messages sent before this command have been processed. Hence, this command accompanied with a single + file descriptor can be used to synchronize against reception of all previous status messages. Note + that this command cannot be mixed with other notifications, and has to be sent in a separate message + to the service manager, otherwise all assignments will be ignored. Note that sending 0 or more than 1 + file descriptor with this command is a violation of the protocol. + + + + It is recommended to prefix variable names that are not + listed above with X_ to avoid namespace + clashes. + + Note that systemd will accept status data sent from a + service only if the NotifyAccess= option is + correctly set in the service definition file. See + systemd.service5 + for details. + + Note that sd_notify() notifications may be attributed to units correctly only if either + the sending process is still around at the time PID 1 processes the message, or if the sending process is + explicitly runtime-tracked by the service manager. The latter is the case if the service manager originally forked + off the process, i.e. on all processes that match NotifyAccess= or + NotifyAccess=. Conversely, if an auxiliary process of the unit sends an + sd_notify() message and immediately exits, the service manager might not be able to properly + attribute the message to the unit, and thus will ignore it, even if + NotifyAccess= is set for it. + + Hence, to eliminate all race conditions involving lookup of the client's unit and attribution of notifications + to units correctly, sd_notify_barrier() may be used. This call acts as a synchronization point + and ensures all notifications sent before this call have been picked up by the service manager when it returns + successfully. Use of sd_notify_barrier() is needed for clients which are not invoked by the + service manager, otherwise this synchronization mechanism is unnecessary for attribution of notifications to the + unit. + + sd_notifyf() is similar to + sd_notify() but takes a + printf()-like format string plus + arguments. + + sd_pid_notify() and + sd_pid_notifyf() are similar to + sd_notify() and + sd_notifyf() but take a process ID (PID) to + use as originating PID for the message as first argument. This is + useful to send notification messages on behalf of other processes, + provided the appropriate privileges are available. If the PID + argument is specified as 0, the process ID of the calling process + is used, in which case the calls are fully equivalent to + sd_notify() and + sd_notifyf(). + + sd_pid_notify_with_fds() is similar to + sd_pid_notify() but takes an additional array + of file descriptors. These file descriptors are sent along the + notification message to the service manager. This is particularly + useful for sending FDSTORE=1 messages, as + described above. The additional arguments are a pointer to the + file descriptor array plus the number of file descriptors in the + array. If the number of file descriptors is passed as 0, the call + is fully equivalent to sd_pid_notify(), i.e. + no file descriptors are passed. Note that sending file descriptors + to the service manager on messages that do not expect them (i.e. + without FDSTORE=1) they are immediately closed + on reception. + + sd_notify_barrier() allows the caller to + synchronize against reception of previously sent notification messages + and uses the BARRIER=1 command. It takes a relative + timeout value in microseconds which is passed to + ppoll2 + . A value of UINT64_MAX is interpreted as infinite timeout. + + + + + Return Value + + On failure, these calls return a negative errno-style error code. If $NOTIFY_SOCKET was + not set and hence no status message could be sent, 0 is returned. If the status was sent, these functions return a + positive value. In order to support both service managers that implement this scheme and those which do not, it is + generally recommended to ignore the return value of this call. Note that the return value simply indicates whether + the notification message was enqueued properly, it does not reflect whether the message could be processed + successfully. Specifically, no error is returned when a file descriptor is attempted to be stored using + FDSTORE=1 but the service is not actually configured to permit storing of file descriptors (see + above). + + + + Notes + + + + These functions send a single datagram with the + state string as payload to the AF_UNIX socket + referenced in the $NOTIFY_SOCKET environment + variable. If the first character of + $NOTIFY_SOCKET is @, the + string is understood as Linux abstract namespace socket. The + datagram is accompanied by the process credentials of the sending + service, using SCM_CREDENTIALS. + + + + Environment + + + + $NOTIFY_SOCKET + + Set by the service manager for supervised + processes for status and start-up completion notification. + This environment variable specifies the socket + sd_notify() talks to. See above for + details. + + + + + + Examples + + + Start-up Notification + + When a service finished starting up, it might issue the + following call to notify the service manager: + + sd_notify(0, "READY=1"); + + + + Extended Start-up Notification + + A service could send the following after completing + initialization: + + sd_notifyf(0, "READY=1\n" + "STATUS=Processing requests…\n" + "MAINPID=%lu", + (unsigned long) getpid()); + + + + Error Cause Notification + + A service could send the following shortly before exiting, on failure: + + sd_notifyf(0, "STATUS=Failed to start up: %s\n" + "ERRNO=%i", + strerror_r(errnum, (char[1024]){}, 1024), + errnum); + + + + Store a File Descriptor in the Service Manager + + To store an open file descriptor in the service manager, + in order to continue operation after a service restart without + losing state, use FDSTORE=1: + + sd_pid_notify_with_fds(0, 0, "FDSTORE=1\nFDNAME=foobar", &fd, 1); + + + + Eliminating race conditions + + When the client sending the notifications is not spawned + by the service manager, it may exit too quickly and the service + manager may fail to attribute them correctly to the unit. To + prevent such races, use sd_notify_barrier() + to synchronize against reception of all notifications sent before + this call is made. + + sd_notify(0, "READY=1"); + /* set timeout to 5 seconds */ + sd_notify_barrier(0, 5 * 1000000); + + + + + + See Also + + systemd1, + sd-daemon3, + sd_listen_fds3, + sd_listen_fds_with_names3, + sd_watchdog_enabled3, + daemon7, + systemd.service5 + + + + -- cgit v1.2.3