1SYSTEMD-NOTIFY(1) systemd-notify SYSTEMD-NOTIFY(1)
2
6 systemd-notify - Notify service manager about start-up completion and
7 other daemon status changes
8
10 systemd-notify [OPTIONS...] [VARIABLE=VALUE...]
11
13 systemd-notify may be called by daemon scripts to notify the init
14 system about status changes. It can be used to send arbitrary
15 information, encoded in an environment-block-like list of strings. Most
16 importantly, it can be used for start-up completion notification.
17 This is mostly just a wrapper around sd_notify() and makes this
19 functionality available to shell scripts. For details see sd_notify(3).
20 The command line may carry a list of environment variables to send as
22 part of the status update.
23 Note that systemd will refuse reception of status updates from this
25 command unless NotifyAccess= is set for the service unit this command
26 is called from.
27 Note that sd_notify() notifications may be attributed to units
29 correctly only if either the sending process is still around at the
30 time PID 1 processes the message, or if the sending process is
31 explicitly runtime-tracked by the service manager. The latter is the
32 case if the service manager originally forked off the process, i.e. on
33 all processes that match NotifyAccess=main or NotifyAccess=exec.
34 Conversely, if an auxiliary process of the unit sends an sd_notify()
35 message and immediately exits, the service manager might not be able to
36 properly attribute the message to the unit, and thus will ignore it,
37 even if NotifyAccess=all is set for it. When --no-block is used, all
38 synchronization for reception of notifications is disabled, and hence
39 the aforementioned race may occur if the invoking process is not the
40 service manager or spawned by the service manager.
41 Hence, systemd-notify will first attempt to invoke sd_notify()
43 pretending to have the PID of the invoking process. This will only
44 succeed when invoked with sufficient privileges. On failure, it will
45 then fall back to invoking it under its own PID. This behaviour is
46 useful in order that when the tool is invoked from a shell script the
47 shell process — and not the systemd-notify process — appears as sender
48 of the message, which in turn is helpful if the shell process is the
49 main process of a service, due to the limitations of NotifyAccess=all.
50 Use the --pid= switch to tweak this behaviour.
51
53 The following options are understood:
54 --ready
56 Inform the init system about service start-up completion. This is
57 equivalent to systemd-notify READY=1. For details about the
58 semantics of this option see sd_notify(3).
59 --pid=
61 Inform the service manager about the main PID of the daemon. Takes
62 a PID as argument. If the argument is specified as "auto" or
63 omitted, the PID of the process that invoked systemd-notify is
64 used, except if that's the service manager. If the argument is
65 specified as "self", the PID of the systemd-notify command itself
66 is used, and if "parent" is specified the calling process' PID is
67 used — even if it is the service manager. This is equivalent to
68 systemd-notify MAINPID=$PID. For details about the semantics of
69 this option see sd_notify(3).
70 --uid=USER
72 Set the user ID to send the notification from. Takes a UNIX user
73 name or numeric UID. When specified the notification message will
74 be sent with the specified UID as sender, in place of the user the
75 command was invoked as. This option requires sufficient privileges
76 in order to be able manipulate the user identity of the process.
77 --status=
79 Send a free-form status string for the daemon to the init systemd.
80 This option takes the status string as argument. This is equivalent
81 to systemd-notify STATUS=.... For details about the semantics of
82 this option see sd_notify(3).
83 --booted
85 Returns 0 if the system was booted up with systemd, non-zero
86 otherwise. If this option is passed, no message is sent. This
87 option is hence unrelated to the other options. For details about
88 the semantics of this option, see sd_booted(3). An alternate way to
89 check for this state is to call systemctl(1) with the
90 is-system-running command. It will return "offline" if the system
91 was not booted with systemd.
92 --no-block
94 Do not synchronously wait for the requested operation to finish.
95 Use of this option is only recommended when systemd-notify is
96 spawned by the service manager, or when the invoking process is
97 directly spawned by the service manager and has enough privileges
98 to allow systemd-notify to send the notification on its behalf.
99 Sending notifications with this option set is prone to race
100 conditions in all other cases.
101 -h, --help
103 Print a short help text and exit.
104 --version
106 Print a short version string and exit.
107
109 On success, 0 is returned, a non-zero failure code otherwise.
110
112 Example 1. Start-up Notification and Status Updates
113 A simple shell daemon that sends start-up notifications after having
115 set up its communication channel. During runtime it sends further
116 status updates to the init system:
117 #!/bin/bash
119 mkfifo /tmp/waldo
121 systemd-notify --ready --status="Waiting for data..."
122 while : ; do
124 read a < /tmp/waldo
125 systemd-notify --status="Processing $a"
126 # Do something with $a ...
128 systemd-notify --status="Waiting for data..."
130 done
131
133 systemd(1), systemctl(1), systemd.unit(5), sd_notify(3), sd_booted(3)
134systemd 248 SYSTEMD-NOTIFY(1)