From e8de964c146f67c91acdaff076420282c2d1b217 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Mon, 2 Jan 2023 18:13:27 +0100 Subject: [PATCH] man: document Type=notify-reload (cherry picked from commit 81e19b6f6585d656e972efad73781e184ca0e7a0) Related: RHEL-6090 --- man/sd_notify.xml | 36 ++++-- man/systemd.service.xml | 248 ++++++++++++++++++++++------------------ 2 files changed, 162 insertions(+), 122 deletions(-) diff --git a/man/sd_notify.xml b/man/sd_notify.xml index de402950bb..d2dba00004 100644 --- a/man/sd_notify.xml +++ b/man/sd_notify.xml @@ -102,23 +102,35 @@ 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). + Tells the service manager that service startup is finished, or the service finished + re-loading its configuration. This is only used by systemd if the service definition file has + Type=notify or Type=notify-reload 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. + 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 + Type=notify-reload services, to inform the service manager that the request to + reload the service has been received and is now being processed. + + + + MONOTONIC_USEC=… + + A field carrying the monotonic timestamp (as per + CLOCK_MONOTONIC) formatted in decimal in µs, when the notification message was + generated by the client. This is typically used in combination with RELOADING=1, + to allow the service manager to properly synchronize reload cycles. See + systemd.service5 + for details, specifically Type=notify-reload. diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 1c9e59f722..ae54332440 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -157,7 +157,7 @@ Configures the process start-up type for this service unit. One of , , , , , - or : + , or : If set to (the default if ExecStart= is @@ -216,14 +216,30 @@ logic thus should be prepared to receive a SIGTERM (or whichever signal is configured in KillSignal=) as result. - Behavior of is similar to ; however, it is - expected that the service sends a notification message via - sd_notify3 or an - equivalent call when it has finished starting up. systemd will proceed with starting follow-up units after - this notification message has been sent. If this option is used, NotifyAccess= (see - below) should be set to open access to the notification socket provided by systemd. If - NotifyAccess= is missing or set to , it will be forcibly set to - . + Behavior of is similar to ; however, + it is expected that the service sends a READY=1 notification message via + sd_notify3 or + an equivalent call when it has finished starting up. systemd will proceed with starting follow-up + units after this notification message has been sent. If this option is used, + NotifyAccess= (see below) should be set to open access to the notification + socket provided by systemd. If NotifyAccess= is missing or set to + , it will be forcibly set to . + + Behavior of is identical to + . However, it extends the logic in one way: the + SIGHUP UNIX process signal is sent to the service's main process when the + service is asked to reload. (The signal to send can be tweaked via + ReloadSignal=, see below.). When + initiating the reload process the service is then expected to reply with a notification message + via sd_notify3 + that contains the RELOADING=1 field in combination with + MONOTONIC_USEC= set to the current monotonic time + (i.e. CLOCK_MONOTONIC in + clock_gettime2) + in µs, formatted as decimal string. Once reloading is complete another notification message must + be sent, containing READY=1. Using this service type and implementing this + reload protocol is an efficient alternative to providing an ExecReload= + command for reloading of the service's configuration. Behavior of is very similar to ; however, actual execution of the service program is delayed until all active jobs are dispatched. This may be used @@ -233,25 +249,27 @@ anyway. - It is generally recommended to use Type= for long-running - services whenever possible, as it is the simplest and fastest option. However, as this service type won't - propagate service start-up failures and doesn't allow ordering of other units against completion of - initialization of the service (which for example is useful if clients need to connect to the service through - some form of IPC, and the IPC channel is only established by the service itself — in contrast to doing this - ahead of time through socket or bus activation or similar), it might not be sufficient for many cases. If so, - or (the latter only in case the service provides a D-Bus - interface) are the preferred options as they allow service program code to precisely schedule when to - consider the service started up successfully and when to proceed with follow-up units. The - service type requires explicit support in the service codebase (as - sd_notify() or an equivalent API needs to be invoked by the service at the appropriate - time) — if it's not supported, then is an alternative: it supports the traditional - UNIX service start-up protocol. Finally, might be an option for cases where it is - enough to ensure the service binary is invoked, and where the service binary itself executes no or little - initialization on its own (and its initialization is unlikely to fail). Note that using any type other than - possibly delays the boot process, as the service manager needs to wait for service - initialization to complete. It is hence recommended not to needlessly use any types other than - . (Also note it is generally not recommended to use or - for long-running services.) + It is generally recommended to use Type= for + long-running services whenever possible, as it is the simplest and fastest option. However, as this + service type won't propagate service start-up failures and doesn't allow ordering of other units + against completion of initialization of the service (which for example is useful if clients need to + connect to the service through some form of IPC, and the IPC channel is only established by the + service itself — in contrast to doing this ahead of time through socket or bus activation or + similar), it might not be sufficient for many cases. If so, , + or (the latter only in case the service + provides a D-Bus interface) are the preferred options as they allow service program code to + precisely schedule when to consider the service started up successfully and when to proceed with + follow-up units. The / service types require + explicit support in the service codebase (as sd_notify() or an equivalent API + needs to be invoked by the service at the appropriate time) — if it's not supported, then + is an alternative: it supports the traditional UNIX service start-up + protocol. Finally, might be an option for cases where it is enough to ensure + the service binary is invoked, and where the service binary itself executes no or little + initialization on its own (and its initialization is unlikely to fail). Note that using any type + other than possibly delays the boot process, as the service manager needs + to wait for service initialization to complete. It is hence recommended not to needlessly use any + types other than . (Also note it is generally not recommended to use + or for long-running services.) @@ -319,9 +337,10 @@ the file may not be a symlink to a file owned by a different user (neither directly nor indirectly), and the PID file must refer to a process already belonging to the service. - Note that PID files should be avoided in modern projects. Use or - where possible, which does not require use of PID files to determine the - main process of a service and avoids needless forking. + Note that PID files should be avoided in modern projects. Use , + or where possible, which does not + require use of PID files to determine the main process of a service and avoids needless + forking. @@ -443,12 +462,13 @@ with a - exit successfully. ExecStartPost= commands are only run after the commands specified in - ExecStart= have been invoked successfully, as determined by Type= - (i.e. the process has been started for Type=simple or Type=idle, the last - ExecStart= process exited successfully for Type=oneshot, the initial - process exited successfully for Type=forking, READY=1 is sent for - Type=notify, or the BusName= has been taken for - Type=dbus). + ExecStart= have been invoked successfully, as determined by + Type= (i.e. the process has been started for Type=simple or + Type=idle, the last ExecStart= process exited successfully for + Type=oneshot, the initial process exited successfully for + Type=forking, READY=1 is sent for + Type=notify/Type=notify-reload, or the + BusName= has been taken for Type=dbus). Note that ExecStartPre= may not be used to start long-running processes. All processes forked @@ -487,30 +507,26 @@ ExecReload= - Commands to execute to trigger a configuration - reload in the service. This argument takes multiple command - lines, following the same scheme as described for - ExecStart= above. Use of this setting is - optional. Specifier and environment variable substitution is - supported here following the same scheme as for + + Commands to execute to trigger a configuration reload in the service. This argument + takes multiple command lines, following the same scheme as described for + ExecStart= above. Use of this setting is optional. Specifier and environment + variable substitution is supported here following the same scheme as for ExecStart=. - One additional, special environment variable is set: if - known, $MAINPID is set to the main process - of the daemon, and may be used for command lines like the - following: + One additional, special environment variable is set: if known, $MAINPID is + set to the main process of the daemon, and may be used for command lines like the following: ExecReload=kill -HUP $MAINPID - Note however that reloading a daemon by sending a signal - (as with the example line above) is usually not a good choice, - because this is an asynchronous operation and hence not - suitable to order reloads of multiple services against each - other. It is strongly recommended to set - ExecReload= to a command that not only - triggers a configuration reload of the daemon, but also - synchronously waits for it to complete. For example, - dbus-broker1 + Note however that reloading a daemon by enqueing a signal (as with the example line above) is + usually not a good choice, because this is an asynchronous operation and hence not suitable when + ordering reloads of multiple services against each other. It is thus strongly recommended to either + use Type= in place of + ExecReload=, or to set ExecReload= to a command that not only + triggers a configuration reload of the daemon, but also synchronously waits for it to complete. For + example, dbus-broker1 uses the following: ExecReload=busctl call org.freedesktop.DBus \ @@ -605,12 +621,13 @@ systemd-system.conf5). - If a service of Type=notify sends EXTEND_TIMEOUT_USEC=…, this may cause - the start time to be extended beyond TimeoutStartSec=. The first receipt of this message - must occur before TimeoutStartSec= is exceeded, and once the start time has extended beyond - TimeoutStartSec=, the service manager will allow the service to continue to start, provided - the service repeats EXTEND_TIMEOUT_USEC=… within the interval specified until the service - startup status is finished by READY=1. (see + If a service of Type=notify/Type=notify-reload sends + EXTEND_TIMEOUT_USEC=…, this may cause the start time to be extended beyond + TimeoutStartSec=. The first receipt of this message must occur before + TimeoutStartSec= is exceeded, and once the start time has extended beyond + TimeoutStartSec=, the service manager will allow the service to continue to start, + provided the service repeats EXTEND_TIMEOUT_USEC=… within the interval specified + until the service startup status is finished by READY=1. (see sd_notify3). @@ -633,12 +650,14 @@ systemd-system.conf5). - If a service of Type=notify sends EXTEND_TIMEOUT_USEC=…, this may cause - the stop time to be extended beyond TimeoutStopSec=. The first receipt of this message - must occur before TimeoutStopSec= is exceeded, and once the stop time has extended beyond - TimeoutStopSec=, the service manager will allow the service to continue to stop, provided - the service repeats EXTEND_TIMEOUT_USEC=… within the interval specified, or terminates itself - (see sd_notify3). + If a service of Type=notify/Type=notify-reload sends + EXTEND_TIMEOUT_USEC=…, this may cause the stop time to be extended beyond + TimeoutStopSec=. The first receipt of this message must occur before + TimeoutStopSec= is exceeded, and once the stop time has extended beyond + TimeoutStopSec=, the service manager will allow the service to continue to stop, + provided the service repeats EXTEND_TIMEOUT_USEC=… within the interval specified, + or terminates itself (see + sd_notify3). @@ -661,13 +680,15 @@ systemd-system.conf5). - If a service of Type=notify handles SIGABRT itself (instead of relying - on the kernel to write a core dump) it can send EXTEND_TIMEOUT_USEC=… to - extended the abort time beyond TimeoutAbortSec=. The first receipt of this message - must occur before TimeoutAbortSec= is exceeded, and once the abort time has extended beyond - TimeoutAbortSec=, the service manager will allow the service to continue to abort, provided - the service repeats EXTEND_TIMEOUT_USEC=… within the interval specified, or terminates itself - (see sd_notify3). + If a service of Type=notify/Type=notify-reload handles + SIGABRT itself (instead of relying on the kernel to write a core dump) it can + send EXTEND_TIMEOUT_USEC=… to extended the abort time beyond + TimeoutAbortSec=. The first receipt of this message must occur before + TimeoutAbortSec= is exceeded, and once the abort time has extended beyond + TimeoutAbortSec=, the service manager will allow the service to continue to abort, + provided the service repeats EXTEND_TIMEOUT_USEC=… within the interval specified, + or terminates itself (see + sd_notify3). @@ -710,12 +731,13 @@ activation completed. Pass infinity (the default) to configure no runtime limit. - If a service of Type=notify sends EXTEND_TIMEOUT_USEC=…, this may cause - the runtime to be extended beyond RuntimeMaxSec=. The first receipt of this message - must occur before RuntimeMaxSec= is exceeded, and once the runtime has extended beyond - RuntimeMaxSec=, the service manager will allow the service to continue to run, provided - the service repeats EXTEND_TIMEOUT_USEC=… within the interval specified until the service - shutdown is achieved by STOPPING=1 (or termination). (see + If a service of Type=notify/Type=notify-reload sends + EXTEND_TIMEOUT_USEC=…, this may cause the runtime to be extended beyond + RuntimeMaxSec=. The first receipt of this message must occur before + RuntimeMaxSec= is exceeded, and once the runtime has extended beyond + RuntimeMaxSec=, the service manager will allow the service to continue to run, + provided the service repeats EXTEND_TIMEOUT_USEC=… within the interval specified + until the service shutdown is achieved by STOPPING=1 (or termination). (see sd_notify3). @@ -1023,16 +1045,19 @@ NotifyAccess= Controls access to the service status notification socket, as accessible via the - sd_notify3 call. Takes one - of (the default), , or - . If , no daemon status updates are accepted from the service - processes, all status update messages are ignored. If , only service updates sent from the - main process of the service are accepted. If , only service updates sent from any of the - main or control processes originating from one of the Exec*= commands are accepted. If - , all services updates from all members of the service's control group are accepted. This - option should be set to open access to the notification socket when using Type=notify or - WatchdogSec= (see above). If those options are used but NotifyAccess= is - not configured, it will be implicitly set to . + sd_notify3 + call. Takes one of (the default), , + or . If , no daemon status updates are accepted from the + service processes, all status update messages are ignored. If , only service + updates sent from the main process of the service are accepted. If , only + service updates sent from any of the main or control processes originating from one of the + Exec*= commands are accepted. If , all services updates from + all members of the service's control group are accepted. This option should be set to open access to + the notification socket when using + Type=notify/Type=notify-reload or + WatchdogSec= (see above). If those options are used but + NotifyAccess= is not configured, it will be implicitly set to + . 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 @@ -1156,6 +1181,15 @@ kills, this setting determines the state of the unit after systemd-oomd kills a cgroup associated with it. + + + ReloadSignal= + Configures the UNIX process signal to send to the service's main process when asked + to reload the service's configuration. Defaults to SIGHUP. This option has no + effect unless Type= is used, see + above. + + Check @@ -1319,16 +1353,13 @@ WantedBy=multi-user.target systemd.kill5 for details. - Note that this unit type does not include any type of - notification when a service has completed initialization. For - this, you should use other unit types, such as - Type= if the service - understands systemd's notification protocol, - Type= if the service - can background itself or - Type= if the unit - acquires a DBus name once initialization is complete. See - below. + Note that this unit type does not include any type of notification when a service has completed + initialization. For this, you should use other unit types, such as + Type=/Type= + if the service understands systemd's notification protocol, + Type= if the service can background itself or + Type= if the unit acquires a DBus name once initialization is + complete. See below. @@ -1505,15 +1536,12 @@ SystemdService=simple-dbus-service.service Services that notify systemd about their initialization - Type= services - are really easy to write, but have the major disadvantage of - systemd not being able to tell when initialization of the given - service is complete. For this reason, systemd supports a simple - notification protocol that allows daemons to make systemd aware - that they are done initializing. Use - Type= for this. A - typical service file for such a daemon would look like - this: + Type= services are really easy to write, but have the + major disadvantage of systemd not being able to tell when initialization of the given service is + complete. For this reason, systemd supports a simple notification protocol that allows daemons to make + systemd aware that they are done initializing. Use Type= or + Type= for this. A typical service file for such a + daemon would look like this: [Unit] Description=Simple notifying service