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 service scripts to notify the invoking
14 service manager 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 appropriately set for the service unit
26 this command is called from. See systemd.service(5) for details.
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 the service manager processes the message, or if the sending
31 process is explicitly runtime-tracked by the service manager. The
32 latter is the case if the service manager originally forked off the
33 process, i.e. on all processes that match NotifyAccess=main or
34 NotifyAccess=exec. Conversely, if an auxiliary process of the unit
35 sends an sd_notify() message and immediately exits, the service manager
36 might not be able to properly attribute the message to the unit, and
37 thus will ignore it, even if NotifyAccess=all is set for it. To address
38 this systemd-notify will wait until the notification message has been
39 processed by the service manager. When --no-block is used, this
40 synchronization for reception of notifications is disabled, and hence
41 the aforementioned race may occur if the invoking process is not the
42 service manager or spawned by the service manager.
43 systemd-notify will first attempt to invoke sd_notify() pretending to
45 have the PID of the parent process of systemd-notify (i.e. the invoking
46 process). This will only succeed when invoked with sufficient
47 privileges. On failure, it will then fall back to invoking it under its
48 own PID. This behaviour is useful in order that when the tool is
49 invoked from a shell script the shell process — and not the
50 systemd-notify process — appears as sender of the message, which in
51 turn is helpful if the shell process is the main process of a service,
52 due to the limitations of NotifyAccess=all. Use the --pid= switch to
53 tweak this behaviour.
54
56 The following options are understood:
57 --ready
59 Inform the invoking service manager about service start-up or
60 configuration reload completion. This is equivalent to
61 systemd-notify READY=1. For details about the semantics of this
62 option see sd_notify(3).
63 --reloading
65 Inform the invoking service manager about the beginning of a
66 configuration reload cycle. This is equivalent to systemd-notify
67 RELOADING=1 (but implicitly also sets a MONOTONIC_USEC= field as
68 required for Type=notify-reload services, see systemd.service(5)
69 for details). For details about the semantics of this option see
70 sd_notify(3).
71 --stopping
73 Inform the invoking service manager about the beginning of the
74 shutdown phase of the service. This is equivalent to systemd-notify
75 STOPPING=1. For details about the semantics of this option see
76 sd_notify(3).
77 --pid=
79 Inform the service manager about the main PID of the service. Takes
80 a PID as argument. If the argument is specified as "auto" or
81 omitted, the PID of the process that invoked systemd-notify is
82 used, except if that's the service manager. If the argument is
83 specified as "self", the PID of the systemd-notify command itself
84 is used, and if "parent" is specified the calling process' PID is
85 used — even if it is the service manager. The latter is equivalent
86 to systemd-notify MAINPID=$PID. For details about the semantics of
87 this option see sd_notify(3).
88 If this switch is used in an systemd-notify invocation from a
90 process that shall become the new main process of a service — and
91 which is not the process forked off by the service manager (or the
92 current main process) —, then it is essential to set
93 NotifyAccess=all in the service unit file, or otherwise the
94 notification will be ignored for security reasons. See
95 systemd.service(5) for details.
96 --uid=USER
98 Set the user ID to send the notification from. Takes a UNIX user
99 name or numeric UID. When specified the notification message will
100 be sent with the specified UID as sender, in place of the user the
101 command was invoked as. This option requires sufficient privileges
102 in order to be able manipulate the user identity of the process.
103 --status=
105 Send a free-form human readable status string for the daemon to the
106 service manager. This option takes the status string as argument.
107 This is equivalent to systemd-notify STATUS=.... For details about
108 the semantics of this option see sd_notify(3). This information is
109 shown in systemctl(1)'s status output, among other places.
110 --booted
112 Returns 0 if the system was booted up with systemd, non-zero
113 otherwise. If this option is passed, no message is sent. This
114 option is hence unrelated to the other options. For details about
115 the semantics of this option, see sd_booted(3). An alternate way to
116 check for this state is to call systemctl(1) with the
117 is-system-running command. It will return "offline" if the system
118 was not booted with systemd.
119 --no-block
121 Do not synchronously wait for the requested operation to finish.
122 Use of this option is only recommended when systemd-notify is
123 spawned by the service manager, or when the invoking process is
124 directly spawned by the service manager and has enough privileges
125 to allow systemd-notify to send the notification on its behalf.
126 Sending notifications with this option set is prone to race
127 conditions in all other cases.
128 -h, --help
130 Print a short help text and exit.
131 --version
133 Print a short version string and exit.
134
136 On success, 0 is returned, a non-zero failure code otherwise.
137
139 Example 1. Start-up Notification and Status Updates
140 A simple shell daemon that sends start-up notifications after having
142 set up its communication channel. During runtime it sends further
143 status updates to the init system:
144 #!/bin/sh
146 mkfifo /tmp/waldo
148 systemd-notify --ready --status="Waiting for data..."
149 while : ; do
151 read -r a < /tmp/waldo
152 systemd-notify --status="Processing $a"
153 # Do something with $a ...
155 systemd-notify --status="Waiting for data..."
157 done
158
160 systemd(1), systemctl(1), systemd.unit(5), systemd.service(5),
161 sd_notify(3), sd_booted(3)
162systemd 253 SYSTEMD-NOTIFY(1)