Debian Codegraph @

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

raw
1 '\" t
2 .TH "SYSTEMD\-NOTIFY" "1" "" "systemd 257.13" "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 .SH "DESCRIPTION"
30 .PP
31 \fBsystemd\-notify\fR
32 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\&.
33 .PP
34 This is mostly just a wrapper around
35 \fBsd_notify()\fR
36 and makes this functionality available to shell scripts\&. For details see
37 \fBsd_notify\fR(3)\&.
38 .PP
39 The command line may carry a list of environment variables to send as part of the status update\&.
40 .PP
41 Note that systemd will refuse reception of status updates from this command unless
42 \fINotifyAccess=\fR
43 is appropriately set for the service unit this command is called from\&. See
44 \fBsystemd.service\fR(5)
45 for details\&.
46 .PP
47 Note that
48 \fBsd_notify()\fR
49 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
50 \fINotifyAccess=\fR\fBmain\fR
51 or
52 \fINotifyAccess=\fR\fBexec\fR\&. Conversely, if an auxiliary process of the unit sends an
53 \fBsd_notify()\fR
54 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
55 \fINotifyAccess=\fR\fBall\fR
56 is set for it\&. To address this
57 \fBsystemd\-notify\fR
58 will wait until the notification message has been processed by the service manager\&. When
59 \fB\-\-no\-block\fR
60 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\&.
61 .PP
62 \fBsystemd\-notify\fR
63 will first attempt to invoke
64 \fBsd_notify()\fR
65 pretending to have the PID of the parent process of
66 \fBsystemd\-notify\fR
67 (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
68 \fBsystemd\-notify\fR
69 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
70 \fINotifyAccess=\fR\fBall\fR\&. Use the
71 \fB\-\-pid=\fR
72 switch to tweak this behaviour\&.
73 .SH "OPTIONS"
74 .PP
75 The following options are understood:
76 .PP
77 \fB\-\-ready\fR
78 .RS 4
79 Inform the invoking service manager about service start\-up or configuration reload completion\&. This is equivalent to
80 \fBsystemd\-notify READY=1\fR\&. For details about the semantics of this option see
81 \fBsd_notify\fR(3)\&.
82 .RE
83 .PP
84 \fB\-\-reloading\fR
85 .RS 4
86 Inform the invoking service manager about the beginning of a configuration reload cycle\&. This is equivalent to
87 \fBsystemd\-notify RELOADING=1\fR
88 (but implicitly also sets a
89 \fIMONOTONIC_USEC=\fR
90 field as required for
91 \fIType=notify\-reload\fR
92 services, see
93 \fBsystemd.service\fR(5)
94 for details)\&. For details about the semantics of this option see
95 \fBsd_notify\fR(3)\&.
96 .sp
97 Added in version 253\&.
98 .RE
99 .PP
100 \fB\-\-stopping\fR
101 .RS 4
102 Inform the invoking service manager about the beginning of the shutdown phase of the service\&. This is equivalent to
103 \fBsystemd\-notify STOPPING=1\fR\&. For details about the semantics of this option see
104 \fBsd_notify\fR(3)\&.
105 .sp
106 Added in version 253\&.
107 .RE
108 .PP
109 \fB\-\-pid=\fR
110 .RS 4
111 Inform the service manager about the main PID of the service\&. Takes a PID as argument\&. If the argument is specified as
112 "auto"
113 or omitted, the PID of the process that invoked
114 \fBsystemd\-notify\fR
115 is used, except if that\*(Aqs the service manager\&. If the argument is specified as
116 "self", the PID of the
117 \fBsystemd\-notify\fR
118 command itself is used, and if
119 "parent"
120 is specified the calling process\*(Aq PID is used \(em even if it is the service manager\&.
121 \fB\-\-pid=auto\fR
122 is equivalent to
123 \fBsystemd\-notify \-\-pid=$PID\fR\&. For details about the semantics of this option see
124 \fBsd_notify\fR(3)\&.
125 .sp
126 \fBsystemd\-notify\fR
127 will first attempt to invoke
128 \fBsd_notify()\fR
129 pretending to have the PID specified with
130 \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
131 \fBsystemd\-notify \-\-pid=\fR
132 may circumvent
133 \fINotifyAccess=main\fR
134 or
135 \fINotifyAccess=exec\fR
136 restrictions enforced for a service\&.
137 .sp
138 If this switch is used in an unprivileged
139 \fBsystemd\-notify\fR
140 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
141 \fINotifyAccess=all\fR
142 in the service unit file, or otherwise the notification will be ignored for security reasons\&. See
143 \fBsystemd.service\fR(5)
144 for details\&.
145 .RE
146 .PP
147 \fB\-\-uid=\fR\fB\fIUSER\fR\fR
148 .RS 4
149 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\&.
150 .sp
151 Added in version 237\&.
152 .RE
153 .PP
154 \fB\-\-status=\fR
155 .RS 4
156 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
157 \fBsystemd\-notify STATUS=\&...\fR\&. For details about the semantics of this option see
158 \fBsd_notify\fR(3)\&. This information is shown in
159 \fBsystemctl\fR(1)\*(Aqs
160 \fBstatus\fR
161 output, among other places\&.
162 .RE
163 .PP
164 \fB\-\-booted\fR
165 .RS 4
166 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
167 \fBsd_booted\fR(3)\&. An alternate way to check for this state is to call
168 \fBsystemctl\fR(1)
169 with the
170 \fBis\-system\-running\fR
171 command\&. It will return
172 "offline"
173 if the system was not booted with systemd\&.
174 .RE
175 .PP
176 \fB\-\-no\-block\fR
177 .RS 4
178 Do not synchronously wait for the requested operation to finish\&. Use of this option is only recommended when
179 \fBsystemd\-notify\fR
180 is spawned by the service manager, or when the invoking process is directly spawned by the service manager and has enough privileges to allow
181 \fBsystemd\-notify\fR
182 to send the notification on its behalf\&. Sending notifications with this option set is prone to race conditions in all other cases\&.
183 .sp
184 Added in version 246\&.
185 .RE
186 .PP
187 \fB\-\-exec\fR
188 .RS 4
189 If specified
190 \fBsystemd\-notify\fR
191 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
192 ";"
193 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\&.
194 .sp
195 Note that many shells interpret
196 ";"
197 as their own separator for command lines, hence when
198 \fBsystemd\-notify\fR
199 is invoked from a shell the semicolon must usually be escaped as
200 "\e;"\&.
201 .sp
202 Added in version 254\&.
203 .RE
204 .PP
205 \fB\-\-fd=\fR
206 .RS 4
207 Send a file descriptor along with the notification message\&. This is useful when invoked in services that have the
208 \fIFileDescriptorStoreMax=\fR
209 setting enabled, see
210 \fBsystemd.service\fR(5)
211 for details\&. The specified file descriptor must be passed to
212 \fBsystemd\-notify\fR
213 when invoked\&. This option may be used multiple times to pass multiple file descriptors in a single notification message\&.
214 .sp
215 To use this functionality from a
216 \fBbash\fR(1)
217 shell, use an expression like the following:
218 .sp
219 .if n \{\
220 .RS 4
221 .\}
222 .nf
223 systemd\-notify \-\-fd=4 \-\-fd=5 4</some/file 5</some/other/file
224 .fi
225 .if n \{\
226 .RE
227 .\}
228 .sp
229 Added in version 254\&.
230 .RE
231 .PP
232 \fB\-\-fdname=\fR
233 .RS 4
234 Set a name to assign to the file descriptors passed via
235 \fB\-\-fd=\fR
236 (see above)\&. This controls the
237 "FDNAME="
238 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\&.
239 .sp
240 Added in version 254\&.
241 .RE
242 .PP
243 \fB\-h\fR, \fB\-\-help\fR
244 .RS 4
245 Print a short help text and exit\&.
246 .RE
247 .PP
248 \fB\-\-version\fR
249 .RS 4
250 Print a short version string and exit\&.
251 .RE
252 .SH "EXIT STATUS"
253 .PP
254 On success, 0 is returned, a non\-zero failure code otherwise\&.
255 .SH "EXAMPLE"
256 .PP
257 \fBExample\ \&1.\ \&Start\-up Notification and Status Updates\fR
258 .PP
259 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:
260 .sp
261 .if n \{\
262 .RS 4
263 .\}
264 .nf
265 #!/bin/sh
266
267 mkfifo /tmp/waldo
268 systemd\-notify \-\-ready \-\-status="Waiting for data\&..."
269
270 while : ; do
271 read \-r a < /tmp/waldo
272 systemd\-notify \-\-status="Processing $a"
273
274 # Do something with $a \&...
275
276 systemd\-notify \-\-status="Waiting for data\&..."
277 done
278 .fi
279 .if n \{\
280 .RE
281 .\}
282 .SH "SEE ALSO"
283 .PP
284 \fBsystemd\fR(1), \fBsystemctl\fR(1), \fBsystemd.unit\fR(5), \fBsystemd.service\fR(5), \fBsd_notify\fR(3), \fBsd_booted\fR(3)