Debian Codegraph @

upstream/debian-unstable/man1/systemd-notify.1

raw
1 '\" t
2 .TH "SYSTEMD\-NOTIFY" "1" "" "systemd 261~rc3" "systemd-notify"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 systemd-notify \- Notify service manager about start\-up completion and other daemon status changes
24 .SH "SYNOPSIS"
25 .HP \w'\fBsystemd\-notify\fR\ 'u
26 \fBsystemd\-notify\fR [OPTIONS...] [VARIABLE=VALUE...]
27 .HP \w'\fBsystemd\-notify\fR\ 'u
28 \fBsystemd\-notify\fR \-\-exec [OPTIONS...] [VARIABLE=VALUE...] ;\ \-\- {CMDLINE...}
29 .HP \w'\fBsystemd\-notify\fR\ 'u
30 \fBsystemd\-notify\fR \-\-fork [OPTIONS...] \-\- {CMDLINE...}
31 .SH "DESCRIPTION"
32 .PP
33 \fBsystemd\-notify\fR
34 may be called by service scripts to notify the invoking service manager 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 used for start\-up completion notification\&.
35 .PP
36 This is mostly just a wrapper around
37 \fBsd_notify()\fR
38 and makes this functionality available to shell scripts\&. For details see
39 \fBsd_notify\fR(3)\&.
40 .PP
41 The command line may carry a list of environment variables to send as part of the status update\&.
42 .PP
43 Note that systemd will refuse reception of status updates from this command unless
44 \fINotifyAccess=\fR
45 is appropriately set for the service unit this command is called from\&. See
46 \fBsystemd.service\fR(5)
47 for details\&.
48 .PP
49 Note that
50 \fBsd_notify()\fR
51 notifications may be attributed to units correctly only if either the sending process is still around at the time the service manager 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
52 \fINotifyAccess=\fR\fBmain\fR
53 or
54 \fINotifyAccess=\fR\fBexec\fR\&. Conversely, if an auxiliary process of the unit sends an
55 \fBsd_notify()\fR
56 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
57 \fINotifyAccess=\fR\fBall\fR
58 is set for it\&. To address this
59 \fBsystemd\-notify\fR
60 will wait until the notification message has been processed by the service manager\&. When
61 \fB\-\-no\-block\fR
62 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\&.
63 .PP
64 \fBsystemd\-notify\fR
65 will first attempt to invoke
66 \fBsd_notify()\fR
67 pretending to have the PID of the parent process of
68 \fBsystemd\-notify\fR
69 (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 \(em and not the
70 \fBsystemd\-notify\fR
71 process \(em 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
72 \fINotifyAccess=\fR\fBall\fR\&. Use the
73 \fB\-\-pid=\fR
74 switch to tweak this behaviour\&.
75 .SH "OPTIONS"
76 .PP
77 The following options are understood:
78 .PP
79 \fB\-\-ready\fR
80 .RS 4
81 Inform the invoking service manager about service start\-up or configuration reload completion\&. This is equivalent to
82 \fBsystemd\-notify READY=1\fR\&. For details about the semantics of this option see
83 \fBsd_notify\fR(3)\&.
84 .RE
85 .PP
86 \fB\-\-reloading\fR
87 .RS 4
88 Inform the invoking service manager about the beginning of a configuration reload cycle\&. This is equivalent to
89 \fBsystemd\-notify RELOADING=1\fR
90 (but implicitly also sets a
91 \fIMONOTONIC_USEC=\fR
92 field as required for
93 \fIType=notify\-reload\fR
94 services, see
95 \fBsystemd.service\fR(5)
96 for details)\&. For details about the semantics of this option see
97 \fBsd_notify\fR(3)\&.
98 .sp
99 Added in version 253\&.
100 .RE
101 .PP
102 \fB\-\-stopping\fR
103 .RS 4
104 Inform the invoking service manager about the beginning of the shutdown phase of the service\&. This is equivalent to
105 \fBsystemd\-notify STOPPING=1\fR\&. For details about the semantics of this option see
106 \fBsd_notify\fR(3)\&.
107 .sp
108 Added in version 253\&.
109 .RE
110 .PP
111 \fB\-\-pid=\fR
112 .RS 4
113 Inform the service manager about the main PID of the service\&. Takes a PID as argument\&. If the argument is specified as
114 "auto"
115 or omitted, the PID of the process that invoked
116 \fBsystemd\-notify\fR
117 is used, except if that\*(Aqs the service manager\&. If the argument is specified as
118 "self", the PID of the
119 \fBsystemd\-notify\fR
120 command itself is used, and if
121 "parent"
122 is specified the calling process\*(Aq PID is used \(em even if it is the service manager\&.
123 \fB\-\-pid=auto\fR
124 is equivalent to
125 \fBsystemd\-notify \-\-pid=$PID\fR\&. For details about the semantics of this option see
126 \fBsd_notify\fR(3)\&.
127 .sp
128 \fBsystemd\-notify\fR
129 will first attempt to invoke
130 \fBsd_notify()\fR
131 pretending to have the PID specified with
132 \fB\-\-pid=\fR\&. This will only succeed when invoked with sufficient privileges\&. On failure, it will then fall back to invoking it under its own PID\&. Effectively, this means that a privileged invocation of
133 \fBsystemd\-notify \-\-pid=\fR
134 may circumvent
135 \fINotifyAccess=main\fR
136 or
137 \fINotifyAccess=exec\fR
138 restrictions enforced for a service\&.
139 .sp
140 If this switch is used in an unprivileged
141 \fBsystemd\-notify\fR
142 invocation from a process that shall become the new main process of a service \(em and which is not the process forked off by the service manager (or the current main process) \(em, then it is essential to set
143 \fINotifyAccess=all\fR
144 in the service unit file, or otherwise the notification will be ignored for security reasons\&. See
145 \fBsystemd.service\fR(5)
146 for details\&.
147 .RE
148 .PP
149 \fB\-\-uid=\fR\fB\fIUSER\fR\fR
150 .RS 4
151 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\&.
152 .sp
153 Added in version 237\&.
154 .RE
155 .PP
156 \fB\-\-status=\fR
157 .RS 4
158 Send a free\-form human\-readable status string for the daemon to the service manager\&. This option takes the status string as argument\&. This is equivalent to
159 \fBsystemd\-notify STATUS=\&...\fR\&. For details about the semantics of this option see
160 \fBsd_notify\fR(3)\&. This information is shown in
161 \fBsystemctl\fR(1)\*(Aqs
162 \fBstatus\fR
163 output, among other places\&.
164 .RE
165 .PP
166 \fB\-\-booted\fR
167 .RS 4
168 Returns 0 if the system was booted up with 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
169 \fBsd_booted\fR(3)\&. An alternate way to check for this state is to call
170 \fBsystemctl\fR(1)
171 with the
172 \fBis\-system\-running\fR
173 command\&. It will output
174 "offline"
175 if the system was not booted with systemd, though the return value has a different meaning\&.
176 .RE
177 .PP
178 \fB\-\-no\-block\fR
179 .RS 4
180 Do not synchronously wait for the requested operation to finish\&. Use of this option is only recommended when
181 \fBsystemd\-notify\fR
182 is spawned by the service manager, or when the invoking process is directly spawned by the service manager and has enough privileges to allow
183 \fBsystemd\-notify\fR
184 to send the notification on its behalf\&. Sending notifications with this option set is prone to race conditions in all other cases\&.
185 .sp
186 Added in version 246\&.
187 .RE
188 .PP
189 \fB\-\-exec\fR
190 .RS 4
191 If specified
192 \fBsystemd\-notify\fR
193 will execute another command line after it completed its operation, replacing its own process\&. If used, the list of assignments to include in the message sent must be followed by a
194 ";"
195 character (as separate argument), followed by the command line to execute\&. This permits "chaining" of commands, i\&.e\&. issuing one operation, followed immediately by another, without changing PIDs\&.
196 .sp
197 Note that many shells interpret
198 ";"
199 as their own separator for command lines, hence when
200 \fBsystemd\-notify\fR
201 is invoked from a shell the semicolon must usually be escaped as
202 "\e;"\&.
203 .sp
204 Added in version 254\&.
205 .RE
206 .PP
207 \fB\-\-fd=\fR
208 .RS 4
209 Send a file descriptor along with the notification message\&. This is useful when invoked in services that have the
210 \fIFileDescriptorStoreMax=\fR
211 setting enabled, see
212 \fBsystemd.service\fR(5)
213 for details\&. The specified file descriptor must be passed to
214 \fBsystemd\-notify\fR
215 when invoked\&. This option may be used multiple times to pass multiple file descriptors in a single notification message\&.
216 .sp
217 To use this functionality from a
218 \fBbash\fR(1)
219 shell, use an expression like the following:
220 .sp
221 .if n \{\
222 .RS 4
223 .\}
224 .nf
225 systemd\-notify \-\-fd=4 \-\-fd=5 4</some/file 5</some/other/file
226 .fi
227 .if n \{\
228 .RE
229 .\}
230 .sp
231 Added in version 254\&.
232 .RE
233 .PP
234 \fB\-\-fdname=\fR
235 .RS 4
236 Set a name to assign to the file descriptors passed via
237 \fB\-\-fd=\fR
238 (see above)\&. This controls the
239 "FDNAME="
240 field\&. This setting may only be specified once, and applies to all file descriptors passed\&. Invoke this tool multiple times in case multiple file descriptors with different file descriptor names shall be submitted\&.
241 .sp
242 Added in version 254\&.
243 .RE
244 .PP
245 \fB\-\-fork\fR
246 .RS 4
247 Instead of sending a notification message, fork off a command line and wait until a
248 "READY=1"
249 message is received from it\&. In other words: this makes
250 \fBsystemd\-notify\fR
251 the receiver of notification messages instead of the sender, swapping roles\&. This is useful to quickly fork off a process that implements the
252 \fBsd_notify()\fR
253 protocol from a shell script\&. The invoked command line will have standard input and standard output connected to
254 /dev/null, but standard error will be inherited from the invoking process\&. The numeric process ID is written to standard output by
255 \fBsystemd\-notify\fR
256 (unless
257 \fB\-\-quiet\fR
258 is specified), which may be used to later terminate the forked off process\&.
259 .sp
260 Note that processes forked off like this will likely remain running after
261 \fBsystemd\-notify\fR
262 already returned, which hence will result in them being reparented to the closest process reaper process, i\&.e\&. typically the per\-user or system service manager\&.
263 .sp
264 Note that this option should not be used to invoke full services ad\-hoc, use
265 \fBsystemd\-run\fR
266 for that\&.
267 .sp
268 Also note that when invoked with this switch
269 \fBsystemd\-notify\fR
270 will exit successfully under two distinction conditions:
271 .sp
272 .RS 4
273 .ie n \{\
274 \h'-04' 1.\h'+01'\c
275 .\}
276 .el \{\
277 .sp -1
278 .IP " 1." 4.2
279 .\}
280 \fBsystemd\-notify\fR
281 received a
282 "READY=1"
283 notification from the child it just forked off\&.
284 .RE
285 .sp
286 .RS 4
287 .ie n \{\
288 \h'-04' 2.\h'+01'\c
289 .\}
290 .el \{\
291 .sp -1
292 .IP " 2." 4.2
293 .\}
294 The child process exited cleanly (with exit status zero) before sending
295 "READY=1"\&.
296 .RE
297 .sp
298 Example use:
299 .sp
300 .if n \{\
301 .RS 4
302 .\}
303 .nf
304 # PID=$(systemd\-notify \-\-fork \-\- mycommand)
305 \&...
306 kill "$PID"
307 unset PID
308 .fi
309 .if n \{\
310 .RE
311 .\}
312 .sp
313 Added in version 258\&.
314 .RE
315 .PP
316 \fB\-\-quiet\fR, \fB\-q\fR
317 .RS 4
318 Turn off output of the numeric process ID when
319 \fB\-\-fork\fR
320 is used\&.
321 .sp
322 Added in version 258\&.
323 .RE
324 .PP
325 \fB\-h\fR, \fB\-\-help\fR
326 .RS 4
327 Print a short help text and exit\&.
328 .RE
329 .PP
330 \fB\-\-version\fR
331 .RS 4
332 Print a short version string and exit\&.
333 .RE
334 .SH "EXIT STATUS"
335 .PP
336 On success, 0 is returned, a non\-zero failure code otherwise\&.
337 .SH "EXAMPLE"
338 .PP
339 \fBExample\ \&1.\ \&Start\-up Notification and Status Updates\fR
340 .PP
341 A simple shell daemon that sends start\-up notifications after having set up its communication channel\&. During runtime it sends further status updates to the init system:
342 .sp
343 .if n \{\
344 .RS 4
345 .\}
346 .nf
347 #!/bin/sh
348
349 mkfifo /tmp/waldo
350 systemd\-notify \-\-ready \-\-status="Waiting for data\&..."
351
352 while : ; do
353 read \-r a < /tmp/waldo
354 systemd\-notify \-\-status="Processing $a"
355
356 # Do something with $a \&...
357
358 systemd\-notify \-\-status="Waiting for data\&..."
359 done
360 .fi
361 .if n \{\
362 .RE
363 .\}
364 .SH "SEE ALSO"
365 .PP
366 \fBsystemd\fR(1), \fBsystemctl\fR(1), \fBsystemd.unit\fR(5), \fBsystemd.service\fR(5), \fBsd_notify\fR(3), \fBsd_booted\fR(3)