X-Git-Url: http://git.ipfire.org/?a=blobdiff_plain;f=man%2Fsystemd-notify.xml;h=6d583003baca6c1e531da3e91011f17ac0b446f7;hb=6b222c4b0227f9914446ac54754aea867f742be4;hp=11584731178ed134336735e2a96c030443879972;hpb=681eb9cf2b831293a4f3d4c48a748d2e4a25d69e;p=thirdparty%2Fsystemd.git diff --git a/man/systemd-notify.xml b/man/systemd-notify.xml index 11584731178..6d583003bac 100644 --- a/man/systemd-notify.xml +++ b/man/systemd-notify.xml @@ -1,28 +1,7 @@ - -%entities; -]> - - + + @@ -30,15 +9,6 @@ systemd-notify systemd - - - - Developer - Lennart - Poettering - lennart@poettering.net - - @@ -63,7 +33,7 @@ systemd-notify may be called by daemon scripts to notify the init system about status changes. It can be used to send arbitrary information, encoded in an - environment-block-like list of strings. Most importantly it can be + environment-block-like list of strings. Most importantly, it can be used for start-up completion notification. This is mostly just a wrapper around @@ -75,9 +45,27 @@ The command line may carry a list of environment variables to send as part of the status update. - Note that systemd will refuse reception of status updates - from this command unless NotifyAccess=all is - set for the service unit this command is called from. + 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. + + 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. @@ -100,22 +88,32 @@ - Inform the init system about the main PID of - the daemon. Takes a PID as argument. If the argument is - omitted, the PID of the process that invoked - systemd-notify is used. This is equivalent - to systemd-notify MAINPID=$PID. For details - about the semantics of this option see + Inform the service manager about the main PID of the daemon. Takes a PID as + argument. If the argument is specified as auto or omitted, the PID of the process + that invoked systemd-notify is used, except if that's the service manager. If the + argument is specified as self, the PID of the systemd-notify + 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. + + USER + + Set the user ID to send the notification from. Takes a UNIX user name or numeric UID. When + specified the notification message will be sent with the specified UID as sender, in place of the user the + command was invoked as. This option requires sufficient privileges in order to be able manipulate the user + identity of the process. + + Send a free-form status string for the daemon to the init systemd. This option takes the status string as argument. This is equivalent to systemd-notify - STATUS=.... For details about the semantics of this + STATUS=…. For details about the semantics of this option see sd_notify3. @@ -127,7 +125,23 @@ systemd, non-zero otherwise. If this option is passed, no message is sent. This option is hence unrelated to the other options. For details about the semantics of this option, see - sd_booted3. + sd_booted3. An + alternate way to check for this state is to call + systemctl1 + with the is-system-running command. It will + return offline if the system was not booted + with systemd. + + + + + + Do not synchronously wait for the requested operation to finish. + Use of this option is only recommended when systemd-notify + is spawned by the service manager, or when the invoking process is directly spawned + by the service manager and has enough privileges to allow systemd-notify + to send the notification on its behalf. Sending notifications with + this option set is prone to race conditions in all other cases. @@ -156,15 +170,15 @@ #!/bin/bash mkfifo /tmp/waldo -systemd-notify --ready --status="Waiting for data..." +systemd-notify --ready --status="Waiting for data…" while : ; do - read a < /tmp/waldo - systemd-notify --status="Processing $a" + read a < /tmp/waldo + systemd-notify --status="Processing $a" - # Do something with $a ... + # Do something with $a … - systemd-notify --status="Waiting for data..." + systemd-notify --status="Waiting for data…" done