diff --git a/man/daemon.xml b/man/daemon.xml index f2b3f6fa29..8fa2506198 100644 --- a/man/daemon.xml +++ b/man/daemon.xml @@ -146,13 +146,11 @@ new-style daemons. This makes it easier to supervise and control them at runtime and simplifies their implementation. - For developing a new-style daemon, none of the - initialization steps recommended for SysV daemons need to be - implemented. New-style init systems such as systemd make all of - them redundant. Moreover, since some of these steps interfere - with process monitoring, file descriptor passing and other - functionality of the init system, it is recommended not to - execute them when run as new-style service. + For developing a new-style daemon, none of the initialization steps recommended for SysV daemons + need to be implemented. New-style init systems such as systemd make all of them redundant. Moreover, + since some of these steps interfere with process monitoring, file descriptor passing, and other + functionality of the service manager, it is recommended not to execute them when run as new-style + service. Note that new-style init systems guarantee execution of daemon processes in a clean process context: it is guaranteed that the environment block is sanitized, that the signal handlers and mask is reset and that no @@ -166,20 +164,28 @@ following: - If SIGTERM is received, - shut down the daemon and exit cleanly. + If applicable, the daemon should notify the service manager about startup completion + or status updates via the + sd_notify3 + interface, in particular READY=1 and STATUS=…. + - If SIGHUP is received, - reload the configuration files, if this - applies. + If SIGTERM is received, shut down the daemon and exit cleanly. + A STOPPING=1 notification should be sent via + sd_notify3. + - Provide a correct exit code from the main - daemon process, as this is used by the init system to detect - service errors and problems. It is recommended to follow the - exit code scheme as defined in the If SIGHUP is received, reload the configuration files, if this + applies. This should be combined with notifications via + sd_notify3: + RELOADING=1 and READY=1. + + + Provide a correct exit code from the main daemon process, as this is used by the + service manager to detect service errors and problems. It is recommended to follow the exit code + scheme as defined in the LSB - recommendations for SysV init - scripts. + recommendations for SysV init scripts. If possible and applicable, expose the daemon's control interface via the D-Bus IPC system and grab a @@ -192,15 +198,12 @@ systemd.service5 for details. - As much as possible, rely on the init system's - functionality to limit the access of the daemon to files, - services and other resources, i.e. in the case of systemd, - rely on systemd's resource limit control instead of - implementing your own, rely on systemd's privilege dropping - code instead of implementing it in the daemon, and similar. - See - systemd.exec5 - for the available controls. + As much as possible, rely on the service manager's functionality to limit the access + of the daemon to files, services, and other resources, i.e. in the case of systemd, rely on systemd's + resource limit control instead of implementing your own, rely on systemd's privilege dropping code + instead of implementing it in the daemon, and so on. See + systemd.exec5 for + the available controls. If D-Bus is used, make your daemon bus-activatable by supplying a D-Bus service activation @@ -222,29 +225,25 @@ can be restarted without losing a single request. See below for details. - If applicable, a daemon should notify the init - system about startup completion or status updates via the - sd_notify3 - interface. + If the service opens sockets or other files on it own, and those file descriptors + shall survive a restart, the daemon should store them in the service manager via + sd_notify3 with + FDSTORE=1.. - Instead of using the - syslog() call to log directly to the - system syslog service, a new-style daemon may choose to simply - log to standard error via fprintf(), - which is then forwarded to syslog by the init system. If log - levels are necessary, these can be encoded by prefixing - individual log lines with strings like - <4> (for log level 4 "WARNING" in the - syslog priority scheme), following a similar style as the - Linux kernel's printk() level system. For - details, see - sd-daemon3 - and + Instead of using the syslog() call to log directly to the system + syslog service, a new-style daemon may choose to simply log to standard error via + fprintf(), which is then forwarded to syslog. If log levels are necessary, these + can be encoded by prefixing individual log lines with strings like <4> (for + log level 4 "WARNING" in the syslog priority scheme), following a similar style as the Linux kernel's + printk() level system. For details, see + sd-daemon3 and systemd.exec5. As new-style daemons are invoked without a controlling TTY (but as their own session - leaders) care should be taken to always specify `O_NOCTTY` on `open()` calls that possibly reference - a TTY device node, so that no controlling TTY is accidentally acquired. + leaders) care should be taken to always specify O_NOCTTY on + open2 + calls that possibly reference a TTY device node, so that no controlling TTY is accidentally + acquired. @@ -282,17 +281,14 @@ Activation on Boot - Old-style daemons are usually activated exclusively on - boot (and manually by the administrator) via SysV init scripts, - as detailed in the Old-style daemons are usually activated exclusively on boot (and manually by the administrator) + via SysV init scripts, as detailed in the LSB - Linux Standard Base Core Specification. This method of - activation is supported ubiquitously on Linux init systems, both - old-style and new-style systems. Among other issues, SysV init - scripts have the disadvantage of involving shell scripts in the - boot process. New-style init systems generally employ updated - versions of activation, both during boot-up and during runtime - and using more minimal service description files. + Linux Standard Base Core Specification. This method of activation is supported ubiquitously on + Linux init systems, both old-style and new-style systems. Among other issues, SysV init scripts have + the disadvantage of involving shell scripts in the boot process. New-style init systems generally use + updated versions of activation, both during boot-up and during runtime and using more minimal service + description files. In systemd, if the developer or administrator wants to make sure that a service or other unit is activated @@ -312,42 +308,29 @@ Socket-Based Activation - In order to maximize the possible parallelization and - robustness and simplify configuration and development, it is - recommended for all new-style daemons that communicate via - listening sockets to employ socket-based activation. In a - socket-based activation scheme, the creation and binding of the - listening socket as primary communication channel of daemons to - local (and sometimes remote) clients is moved out of the daemon - code and into the init system. Based on per-daemon - configuration, the init system installs the sockets and then - hands them off to the spawned process as soon as the respective - daemon is to be started. Optionally, activation of the service - can be delayed until the first inbound traffic arrives at the - socket to implement on-demand activation of daemons. However, - the primary advantage of this scheme is that all providers and - all consumers of the sockets can be started in parallel as soon - as all sockets are established. In addition to that, daemons can - be restarted with losing only a minimal number of client - transactions, or even any client request at all (the latter is - particularly true for state-less protocols, such as DNS or - syslog), because the socket stays bound and accessible during - the restart, and all requests are queued while the daemon cannot - process them. + In order to maximize the possible parallelization and robustness and simplify configuration and + development, it is recommended for all new-style daemons that communicate via listening sockets to use + socket-based activation. In a socket-based activation scheme, the creation and binding of the listening + socket as primary communication channel of daemons to local (and sometimes remote) clients is moved out + of the daemon code and into the service manager. Based on per-daemon configuration, the service manager + installs the sockets and then hands them off to the spawned process as soon as the respective daemon is + to be started. Optionally, activation of the service can be delayed until the first inbound traffic + arrives at the socket to implement on-demand activation of daemons. However, the primary advantage of + this scheme is that all providers and all consumers of the sockets can be started in parallel as soon + as all sockets are established. In addition to that, daemons can be restarted with losing only a + minimal number of client transactions, or even any client request at all (the latter is particularly + true for state-less protocols, such as DNS or syslog), because the socket stays bound and accessible + during the restart, and all requests are queued while the daemon cannot process them. - New-style daemons which support socket activation must be - able to receive their sockets from the init system instead of - creating and binding them themselves. For details about the - programming interfaces for this scheme provided by systemd, see - sd_listen_fds3 - and - sd-daemon3. - For details about porting existing daemons to socket-based - activation, see below. With minimal effort, it is possible to - implement socket-based activation in addition to traditional - internal socket creation in the same codebase in order to - support both new-style and old-style init systems from the same - daemon binary. + New-style daemons which support socket activation must be able to receive their sockets from the + service manager instead of creating and binding them themselves. For details about the programming + interfaces for this scheme provided by systemd, see + sd_listen_fds3 and + sd-daemon3. For + details about porting existing daemons to socket-based activation, see below. With minimal effort, it + is possible to implement socket-based activation in addition to traditional internal socket creation in + the same codebase in order to support both new-style and old-style init systems from the same daemon + binary. systemd implements socket-based activation via .socket units, which are described in @@ -373,23 +356,16 @@ Bus-Based Activation - When the D-Bus IPC system is used for communication with - clients, new-style daemons should employ bus activation so that - they are automatically activated when a client application - accesses their IPC interfaces. This is configured in D-Bus - service files (not to be confused with systemd service unit - files!). To ensure that D-Bus uses systemd to start-up and - maintain the daemon, use the SystemdService= - directive in these service files to configure the matching - systemd service for a D-Bus service. e.g.: For a D-Bus service - whose D-Bus activation file is named - org.freedesktop.RealtimeKit.service, make - sure to set - SystemdService=rtkit-daemon.service in that - file to bind it to the systemd service - rtkit-daemon.service. This is needed to - make sure that the daemon is started in a race-free fashion when - activated via multiple mechanisms simultaneously. + When the D-Bus IPC system is used for communication with clients, new-style daemons should use + bus activation so that they are automatically activated when a client application accesses their IPC + interfaces. This is configured in D-Bus service files (not to be confused with systemd service unit + files!). To ensure that D-Bus uses systemd to start-up and maintain the daemon, use the + SystemdService= directive in these service files to configure the matching systemd + service for a D-Bus service. e.g.: For a D-Bus service whose D-Bus activation file is named + org.freedesktop.RealtimeKit.service, make sure to set + SystemdService=rtkit-daemon.service in that file to bind it to the systemd service + rtkit-daemon.service. This is needed to make sure that the daemon is started in a + race-free fashion when activated via multiple mechanisms simultaneously. @@ -449,10 +425,10 @@ Other Forms of Activation Other forms of activation have been suggested and implemented in some systems. However, there are - often simpler or better alternatives, or they can be put together of combinations of the schemes - above. Example: Sometimes, it appears useful to start daemons or .socket units - when a specific IP address is configured on a network interface, because network sockets shall be bound - to the address. However, an alternative to implement this is by utilizing the Linux + often simpler or better alternatives, or they can be put together of combinations of the schemes above. + Example: Sometimes, it appears useful to start daemons or .socket units when a + specific IP address is configured on a network interface, because network sockets shall be bound to the + address. However, an alternative to implement this is by utilizing the Linux IP_FREEBIND/IPV6_FREEBIND socket option, as accessible via FreeBind=yes in systemd socket files (see systemd.socket5 for @@ -460,15 +436,14 @@ address, and hence allows bindings to a particular IP address before it actually becomes available, making such an explicit dependency to the configured address redundant. Another often suggested trigger for service activation is low system load. However, here too, a more convincing approach might be to - make proper use of features of the operating system, in particular, the CPU or I/O scheduler of - Linux. Instead of scheduling jobs from userspace based on monitoring the OS scheduler, it is advisable - to leave the scheduling of processes to the OS scheduler itself. systemd provides fine-grained access - to the CPU and I/O schedulers. If a process executed by the init system shall not negatively impact the - amount of CPU or I/O bandwidth available to other processes, it should be configured with - CPUSchedulingPolicy=idle and/or - IOSchedulingClass=idle. Optionally, this may be combined with timer-based activation - to schedule background jobs during runtime and with minimal impact on the system, and remove it from - the boot phase itself. + make proper use of features of the operating system, in particular, the CPU or I/O scheduler of Linux. + Instead of scheduling jobs from userspace based on monitoring the OS scheduler, it is advisable to + leave the scheduling of processes to the OS scheduler itself. systemd provides fine-grained access to + the CPU and I/O schedulers. If a process executed by the service manager shall not negatively impact + the amount of CPU or I/O bandwidth available to other processes, it should be configured with + CPUSchedulingPolicy=idle and/or IOSchedulingClass=idle. + Optionally, this may be combined with timer-based activation to schedule background jobs during runtime + and with minimal impact on the system, and remove it from the boot phase itself. @@ -675,26 +650,20 @@ fi is useful not only for using the daemon in new-style init systems, but also to ease debugging. - If the daemon offers interfaces to other - software running on the local system via local - AF_UNIX sockets, consider implementing - socket-based activation (see above). Usually, a minimal patch is - sufficient to implement this: Extend the socket creation in the - daemon code so that - sd_listen_fds3 - is checked for already passed sockets first. If sockets are - passed (i.e. when sd_listen_fds() returns a - positive value), skip the socket creation step and use the - passed sockets. Secondly, ensure that the file system socket - nodes for local AF_UNIX sockets used in the - socket-based activation are not removed when the daemon shuts - down, if sockets have been passed. Third, if the daemon normally - closes all remaining open file descriptors as part of its - initialization, the sockets passed from the init system must be - spared. Since new-style init systems guarantee that no left-over - file descriptors are passed to executed processes, it might be a - good choice to simply skip the closing of all remaining open - file descriptors if sockets are passed. + If the daemon offers interfaces to other software running on the local system via local + AF_UNIX sockets, consider implementing socket-based activation (see above). + Usually, a minimal patch is sufficient to implement this: Extend the socket creation in the daemon code + so that + sd_listen_fds3 is + checked for already passed sockets first. If sockets are passed (i.e. when + sd_listen_fds() returns a positive value), skip the socket creation step and use + the passed sockets. Secondly, ensure that the file system socket nodes for local + AF_UNIX sockets used in the socket-based activation are not removed when the + daemon shuts down, if sockets have been passed. Third, if the daemon normally closes all remaining open + file descriptors as part of its initialization, the sockets passed from the service manager must be + spared. Since new-style init systems guarantee that no left-over file descriptors are passed to + executed processes, it might be a good choice to simply skip the closing of all remaining open file + descriptors if sockets are passed. Write and install a systemd unit file for the service (and the sockets if socket-based activation is used, as diff --git a/man/kernel-install.xml b/man/kernel-install.xml index 797e78f291..9a21fd65e8 100644 --- a/man/kernel-install.xml +++ b/man/kernel-install.xml @@ -78,23 +78,32 @@ The following commands are understood: - add KERNEL-VERSION KERNEL-IMAGE [INITRD-FILE ...] + + add + KERNEL-VERSION + KERNEL-IMAGE [INITRD-FILE ...] + + This command expects a kernel version string and a path to a kernel image file as arguments. Optionally, one or more initrd images may be specified as well (note that plugins might generate - additional ones). kernel-install calls the executable files from - /usr/lib/kernel/install.d/*.install and - /etc/kernel/install.d/*.install (i.e. the plugins) with the following - arguments: + additional ones). - add KERNEL-VERSION $BOOT/ENTRY-TOKEN/KERNEL-VERSION/ KERNEL-IMAGE [INITRD-FILE ...] + The executable files from /usr/lib/kernel/install.d/*.install and + /etc/kernel/install.d/*.install (i.e. the plugins) are called with the + following arguments: + + add KERNEL-VERSION $BOOT/ENTRY-TOKEN/KERNEL-VERSION/ KERNEL-IMAGE \ + [INITRD-FILE ...] The third argument directly refers to the path where to place kernel images, initrd - images and other resources for Boot + images and other resources for + Boot Loader Specification Type #1 entries (the "entry directory"). If other boot loader schemes - are used the parameter may be ignored. The ENTRY-TOKEN string is - typically the machine ID and is supposed to identify the local installation on the system. For - details see below. + are used the parameter may be ignored. + + The ENTRY-TOKEN string is typically the machine ID and is supposed + to identify the local installation on the system. For details see below. Two default plugins execute the following operations in this case: @@ -136,10 +145,11 @@ remove KERNEL-VERSION - This command expects a kernel version string as single argument. This calls executables from - /usr/lib/kernel/install.d/*.install and - /etc/kernel/install.d/*.install with the following arguments: - + This command expects a kernel version string as single argument. + + The executable files from /usr/lib/kernel/install.d/*.install and + /etc/kernel/install.d/*.install (i.e. the plugins) are called with the + following arguments: remove KERNEL-VERSION $BOOT/ENTRY-TOKEN/KERNEL-VERSION/ @@ -150,13 +160,16 @@ Two default plugins execute the following operations in this case: - 50-depmod.install removes the files generated by depmod for this kernel again. + 50-depmod.install removes the files generated by + depmod for this kernel again. 90-loaderentry.install removes the file - $BOOT/loader/entries/ENTRY-TOKEN-KERNEL-VERSION.conf. + $BOOT/loader/entries/ENTRY-TOKEN-KERNEL-VERSION.conf. + 90-uki-copy.install removes the file - $BOOT/EFI/Linux/ENTRY-TOKEN-KERNEL-VERSION.efi. + $BOOT/EFI/Linux/ENTRY-TOKEN-KERNEL-VERSION.efi. + @@ -518,11 +531,16 @@ /etc/kernel/uki.conf - Ini-style configuration file for ukify1 which is only effective when $KERNEL_INSTALL_LAYOUT or layout= in install.conf is set to and $KERNEL_INSTALL_UKI_GENERATOR or uki_generator= in install.conf is set to . + Ini-style configuration file for + ukify1 which + is only effective when $KERNEL_INSTALL_LAYOUT or layout= in + install.conf is set to and + $KERNEL_INSTALL_UKI_GENERATOR or uki_generator= in + install.conf is set to . $KERNEL_INSTALL_CONF_ROOT may be used to override the path. - + diff --git a/man/sd_notify.xml b/man/sd_notify.xml index b75bf05808..0476c579e7 100644 --- a/man/sd_notify.xml +++ b/man/sd_notify.xml @@ -98,19 +98,80 @@ 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. + 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 or reload completion notifications. 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 + sd_notify() will then fail, and 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: + specified. The string may contain any kind of variable assignments, but see the next section + for a list of assignments understood by the service manager. + + 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 file descriptors sent to the service manager on a message without FDSTORE=1 are + immediately closed on reception. + + sd_pid_notifyf_with_fds() is a combination of + sd_pid_notify_with_fds() and sd_notifyf(), i.e. it accepts both + a PID and a set of file descriptors as input, and processes a format string to generate the state + string. + + 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. + + sd_pid_notify_barrier() is just like sd_notify_barrier(), + but allows specifying the originating PID for the notification message. + + + + Well-known assignments + + The following assignments have a defined meaning: @@ -126,9 +187,9 @@ RELOADING=1 - Tells the service manager that the service is beginning to reload 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 + Tells the service manager that the service is beginning to reload 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 the service manager is notified about with this mechanisms are propagated in the same way as they are when originally initiated through the service manager. This message is particularly relevant for @@ -138,6 +199,16 @@ + + 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. + + + + + MONOTONIC_USEC=… @@ -151,24 +222,13 @@ - - 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… + error message. Example: STATUS=Completed 66% of file system check… @@ -179,8 +239,8 @@ Reset the access to the service status notification socket during runtime, overriding NotifyAccess= setting in the service unit file. See systemd.service5 - for details, specifically NotifyAccess= for a list of accepted - values. + for details, specifically NotifyAccess= for a list of accepted values. + @@ -198,7 +258,8 @@ BUSERROR=… If a service fails, the D-Bus error-style error code. Example: - BUSERROR=org.freedesktop.DBus.Error.TimedOut + BUSERROR=org.freedesktop.DBus.Error.TimedOut. Note that this assignment is + currently not used by systemd. @@ -206,8 +267,15 @@ EXIT_STATUS=… - If a service exits, the return value of its main() function. - + The exit status of a service or the manager itself. Note that + systemd currently does not consume this value when sent by services, so this + assignment is only informational. The manager will send this notification to its + notification socket, which may be used to to collect an exit status from the system (a container or + VM) as it shuts down. For example, + mkosi1 + makes use of this. The value to return may be set via the + systemctl1 + exit verb. @@ -216,7 +284,7 @@ MAINPID=… The main process ID (PID) of the service, in case the service manager did not fork - off the process itself. Example: MAINPID=4711 + off the process itself. Example: MAINPID=4711. @@ -276,29 +344,40 @@ 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 + Store file descriptors in the service manager. File descriptors sent this way will be + held for the service by the service manager and will later be handed back using the usual file + descriptor passing logic at the next start or restart of the service, 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 + Any open sockets and other file descriptors which should not be closed during a restart may be stored + this way. When a service is stopped, its file descriptor store is discarded and all file descriptors + in it are closed, except when overridden with FileDescriptorStorePreserve=, see + systemd.service5. + + + 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 + systemd.service5). + The service manager will set the $FDSTORE environment variable for services that + have the file descriptor store enabled, see + systemd.exec5. + + + If FDPOLL=0 is not set and the file descriptors 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. The service manager will set the $FDSTORE environment variable for services - that have the file descriptor store enabled. + their automatic removal from the store. + + Multiple sets of file descriptors may be sent in separate messages, in which case the sets are + combined. The service manager removes duplicate file descriptors (those pointing to the same object) + before passing them to the service. + + This functionality should be used to implement services that can restart after an explicit + request or a crash without losing state. Application state can either be serialized to a file in + /run/, or better, stored in a + memfd_create2 + memory file descriptor. Use sd_pid_notify_with_fds() to send messages with + FDSTORE=1. It is recommended to combine FDSTORE= with + FDNAME= to make it easier to manage the stored file descriptors. For further information on the file descriptor store see the File Descriptor Store overview. @@ -323,14 +402,16 @@ 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. + sd_listen_fds_with_names3. + File descriptors submitted without this field will be called stored. + + 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. + + Note that if multiple file descriptors are submitted in a single message, the specified name + will be used for all of them. In order to assign different names to submitted file descriptors, + submit them in separate messages. @@ -364,63 +445,10 @@ - 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 file descriptors sent to the service manager on a message without FDSTORE=1 are - immediately closed on reception. - - sd_pid_notifyf_with_fds() is a combination of - sd_pid_notify_with_fds() and sd_notifyf(), i.e. it accepts both - a PID and a set of file descriptors as input, and processes a format string to generate the state - string. - - 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. - - sd_pid_notify_barrier() is just like sd_notify_barrier(), - but allows specifying the originating PID for the notification message. + The notification messages sent by services are interpreted by the service manager. Unknown + assignments may be logged, but are otherwise ignored. Thus, it is not useful to send assignments which + are not in this list. The service manager also sends some messages to its + notification socket, which are then consumed by the machine or container manager. diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index 18928a4e85..1521dfd763 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -3998,12 +3998,12 @@ StandardInputData=V2XigLJyZSBubyBzdHJhbmdlcnMgdG8gbG92ZQpZb3Uga25vdyB0aGUgcnVsZX $FDSTORE - If the file descriptor store is enabled for a service - (i.e. FileDescriptorStoreMax= is set to a non-zero value, see + The maximum number of file descriptors that may be stored in the manager for the + service. This variable is set when the file descriptor store is enabled for the service, i.e. + FileDescriptorStoreMax= is set to a non-zero value (see systemd.service5 - for details), this environment variable will be set to the maximum number of permitted entries, as - per the setting. Applications may check this environment variable before sending file descriptors - to the service manager via sd_pid_notify_with_fds() (see + for details). Applications may check this environment variable before sending file descriptors to + the service manager via sd_pid_notify_with_fds() (see sd_notify3 for details).