diff --git a/man/systemd-notify.xml b/man/systemd-notify.xml index 1327d23155..9479fbd759 100644 --- a/man/systemd-notify.xml +++ b/man/systemd-notify.xml @@ -46,27 +46,33 @@ to send as part of the status update. Note that systemd will refuse reception of status updates from this command unless - NotifyAccess= is set for the service unit this command is called from. + NotifyAccess= is appropriately set for the service unit this command is called + from. 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. When is used, all synchronization for reception of notifications - is disabled, and hence the aforementioned race may occur if the invoking process is not the service manager or spawned - by the service manager. - - Hence, systemd-notify will first attempt to invoke sd_notify() - pretending to have the PID of the invoking process. This will only succeed when invoked with sufficient privileges. - On failure, it will then fall back to invoking it under its own PID. This behaviour is useful in order that when - the tool is invoked from a shell script the shell process — and not the systemd-notify process - — appears as sender of the message, which in turn is helpful if the shell process is the main process of a service, - due to the limitations of NotifyAccess=. Use the - switch to tweak this behaviour. + 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. To address this + systemd-notify will wait until the notification message has been processed by the + service manager. When is used, this synchronization for reception of + notifications is disabled, and hence the aforementioned race may occur if the invoking process is not the + service manager or spawned by the service manager. + systemd-notify will first attempt to invoke sd_notify() + pretending to have the PID of the parent process of systemd-notify (i.e. the invoking + process). This will only succeed when invoked with sufficient privileges. On failure, it will then fall + back to invoking it under its own PID. This behaviour is useful in order that when the tool is invoked + from a shell script the shell process — and not the systemd-notify process — appears + as sender of the message, which in turn is helpful if the shell process is the main process of a service, + due to the limitations of NotifyAccess=. Use the + switch to tweak this behaviour. @@ -95,7 +101,15 @@ command itself is used, and if parent is specified the calling process' PID is used — even if it is the service manager. This is equivalent to systemd-notify MAINPID=$PID. For details about the semantics of this option see - sd_notify3. + sd_notify3. + + If this switch is used in an systemd-notify invocation from a process that + shall become the new main process of a service — and which is not the process forked off by the + service manager (or the current main process) —, then it is essential to set + NotifyAccess=all in the service unit file, or otherwise the notification will be + ignored for security reasons. See + systemd.service5 + for details. @@ -188,6 +202,7 @@ done systemd1, systemctl1, systemd.unit5, + systemd.service5, sd_notify3, sd_booted3