]>
Commit | Line | Data |
---|---|---|
514094f9 | 1 | <?xml version='1.0'?> |
3a54a157 | 2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
eea10b26 | 3 | "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> |
db9ecf05 | 4 | <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
f9378423 | 5 | |
6a70f3aa | 6 | <refentry id="sd_notify" |
798d3a52 ZJS |
7 | xmlns:xi="http://www.w3.org/2001/XInclude"> |
8 | ||
9 | <refentryinfo> | |
10 | <title>sd_notify</title> | |
11 | <productname>systemd</productname> | |
798d3a52 ZJS |
12 | </refentryinfo> |
13 | ||
14 | <refmeta> | |
15 | <refentrytitle>sd_notify</refentrytitle> | |
16 | <manvolnum>3</manvolnum> | |
17 | </refmeta> | |
18 | ||
19 | <refnamediv> | |
20 | <refname>sd_notify</refname> | |
21 | <refname>sd_notifyf</refname> | |
22 | <refname>sd_pid_notify</refname> | |
23 | <refname>sd_pid_notifyf</refname> | |
24 | <refname>sd_pid_notify_with_fds</refname> | |
4054d761 | 25 | <refname>sd_pid_notifyf_with_fds</refname> |
4f07ddfa | 26 | <refname>sd_notify_barrier</refname> |
0de34318 | 27 | <refname>sd_pid_notify_barrier</refname> |
798d3a52 ZJS |
28 | <refpurpose>Notify service manager about start-up completion and other service status changes</refpurpose> |
29 | </refnamediv> | |
30 | ||
31 | <refsynopsisdiv> | |
32 | <funcsynopsis> | |
33 | <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo> | |
34 | ||
35 | <funcprototype> | |
36 | <funcdef>int <function>sd_notify</function></funcdef> | |
37 | <paramdef>int <parameter>unset_environment</parameter></paramdef> | |
38 | <paramdef>const char *<parameter>state</parameter></paramdef> | |
39 | </funcprototype> | |
40 | ||
41 | <funcprototype> | |
42 | <funcdef>int <function>sd_notifyf</function></funcdef> | |
43 | <paramdef>int <parameter>unset_environment</parameter></paramdef> | |
44 | <paramdef>const char *<parameter>format</parameter></paramdef> | |
1eecafb8 | 45 | <paramdef>…</paramdef> |
798d3a52 ZJS |
46 | </funcprototype> |
47 | ||
48 | <funcprototype> | |
49 | <funcdef>int <function>sd_pid_notify</function></funcdef> | |
50 | <paramdef>pid_t <parameter>pid</parameter></paramdef> | |
51 | <paramdef>int <parameter>unset_environment</parameter></paramdef> | |
52 | <paramdef>const char *<parameter>state</parameter></paramdef> | |
53 | </funcprototype> | |
54 | ||
55 | <funcprototype> | |
56 | <funcdef>int <function>sd_pid_notifyf</function></funcdef> | |
57 | <paramdef>pid_t <parameter>pid</parameter></paramdef> | |
58 | <paramdef>int <parameter>unset_environment</parameter></paramdef> | |
59 | <paramdef>const char *<parameter>format</parameter></paramdef> | |
1eecafb8 | 60 | <paramdef>…</paramdef> |
798d3a52 ZJS |
61 | </funcprototype> |
62 | ||
63 | <funcprototype> | |
64 | <funcdef>int <function>sd_pid_notify_with_fds</function></funcdef> | |
65 | <paramdef>pid_t <parameter>pid</parameter></paramdef> | |
66 | <paramdef>int <parameter>unset_environment</parameter></paramdef> | |
67 | <paramdef>const char *<parameter>state</parameter></paramdef> | |
68 | <paramdef>const int *<parameter>fds</parameter></paramdef> | |
69 | <paramdef>unsigned <parameter>n_fds</parameter></paramdef> | |
70 | </funcprototype> | |
4f07ddfa | 71 | |
4054d761 LP |
72 | <funcprototype> |
73 | <funcdef>int <function>sd_pid_notifyf_with_fds</function></funcdef> | |
74 | <paramdef>pid_t <parameter>pid</parameter></paramdef> | |
75 | <paramdef>int <parameter>unset_environment</parameter></paramdef> | |
76 | <paramdef>const int *<parameter>fds</parameter></paramdef> | |
77 | <paramdef>size_t <parameter>n_fds</parameter></paramdef> | |
78 | <paramdef>const char *<parameter>format</parameter></paramdef> | |
79 | <paramdef>…</paramdef> | |
80 | </funcprototype> | |
81 | ||
4f07ddfa KKD |
82 | <funcprototype> |
83 | <funcdef>int <function>sd_notify_barrier</function></funcdef> | |
84 | <paramdef>int <parameter>unset_environment</parameter></paramdef> | |
85 | <paramdef>uint64_t <parameter>timeout</parameter></paramdef> | |
86 | </funcprototype> | |
0de34318 LP |
87 | |
88 | <funcprototype> | |
89 | <funcdef>int <function>sd_pid_notify_barrier</function></funcdef> | |
90 | <paramdef>pid_t <parameter>pid</parameter></paramdef> | |
91 | <paramdef>int <parameter>unset_environment</parameter></paramdef> | |
92 | <paramdef>uint64_t <parameter>timeout</parameter></paramdef> | |
93 | </funcprototype> | |
798d3a52 ZJS |
94 | </funcsynopsis> |
95 | </refsynopsisdiv> | |
96 | ||
97 | <refsect1> | |
98 | <title>Description</title> | |
1412ad9a LP |
99 | |
100 | <para><function>sd_notify()</function> may be called by a service to notify the service manager about | |
67da7e9a ZJS |
101 | state changes. It can be used to send arbitrary information, encoded in an environment-block-like string. |
102 | Most importantly, it can be used for start-up or reload completion notifications.</para> | |
1412ad9a LP |
103 | |
104 | <para>If the <parameter>unset_environment</parameter> parameter is non-zero, | |
105 | <function>sd_notify()</function> will unset the <varname>$NOTIFY_SOCKET</varname> environment variable | |
106 | before returning (regardless of whether the function call itself succeeded or not). Further calls to | |
67da7e9a | 107 | <function>sd_notify()</function> will then fail, and the variable is no longer inherited by child |
1412ad9a LP |
108 | processes.</para> |
109 | ||
110 | <para>The <parameter>state</parameter> parameter should contain a newline-separated list of variable | |
111 | assignments, similar in style to an environment block. A trailing newline is implied if none is | |
ef86486a ZJS |
112 | specified. The string may contain any kind of variable assignments, but see the next section |
113 | for a list of assignments understood by the service manager.</para> | |
114 | ||
115 | <para>Note that systemd will accept status data sent from a service only if the | |
116 | <varname>NotifyAccess=</varname> option is correctly set in the service definition file. See | |
117 | <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> for | |
118 | details.</para> | |
119 | ||
120 | <para>Note that <function>sd_notify()</function> notifications may be attributed to units correctly only | |
121 | if either the sending process is still around at the time PID 1 processes the message, or if the sending | |
122 | process is explicitly runtime-tracked by the service manager. The latter is the case if the service | |
123 | manager originally forked off the process, i.e. on all processes that match | |
124 | <varname>NotifyAccess=</varname><option>main</option> or | |
125 | <varname>NotifyAccess=</varname><option>exec</option>. Conversely, if an auxiliary process of the unit | |
126 | sends an <function>sd_notify()</function> message and immediately exits, the service manager might not be | |
127 | able to properly attribute the message to the unit, and thus will ignore it, even if | |
128 | <varname>NotifyAccess=</varname><option>all</option> is set for it.</para> | |
129 | ||
130 | <para>Hence, to eliminate all race conditions involving lookup of the client's unit and attribution of | |
131 | notifications to units correctly, <function>sd_notify_barrier()</function> may be used. This call acts as | |
132 | a synchronization point and ensures all notifications sent before this call have been picked up by the | |
133 | service manager when it returns successfully. Use of <function>sd_notify_barrier()</function> is needed | |
134 | for clients which are not invoked by the service manager, otherwise this synchronization mechanism is | |
135 | unnecessary for attribution of notifications to the unit.</para> | |
136 | ||
137 | <para><function>sd_notifyf()</function> is similar to <function>sd_notify()</function> but takes a | |
138 | <function>printf()</function>-like format string plus arguments.</para> | |
139 | ||
140 | <para><function>sd_pid_notify()</function> and <function>sd_pid_notifyf()</function> are similar to | |
141 | <function>sd_notify()</function> and <function>sd_notifyf()</function> but take a process ID (PID) to use | |
142 | as originating PID for the message as first argument. This is useful to send notification messages on | |
143 | behalf of other processes, provided the appropriate privileges are available. If the PID argument is | |
144 | specified as 0, the process ID of the calling process is used, in which case the calls are fully | |
145 | equivalent to <function>sd_notify()</function> and <function>sd_notifyf()</function>.</para> | |
146 | ||
147 | <para><function>sd_pid_notify_with_fds()</function> is similar to <function>sd_pid_notify()</function> | |
148 | but takes an additional array of file descriptors. These file descriptors are sent along the notification | |
149 | message to the service manager. This is particularly useful for sending <literal>FDSTORE=1</literal> | |
150 | messages, as described above. The additional arguments are a pointer to the file descriptor array plus | |
151 | the number of file descriptors in the array. If the number of file descriptors is passed as 0, the call | |
152 | is fully equivalent to <function>sd_pid_notify()</function>, i.e. no file descriptors are passed. Note | |
153 | that file descriptors sent to the service manager on a message without <literal>FDSTORE=1</literal> are | |
154 | immediately closed on reception.</para> | |
155 | ||
156 | <para><function>sd_pid_notifyf_with_fds()</function> is a combination of | |
157 | <function>sd_pid_notify_with_fds()</function> and <function>sd_notifyf()</function>, i.e. it accepts both | |
158 | a PID and a set of file descriptors as input, and processes a format string to generate the state | |
159 | string.</para> | |
160 | ||
161 | <para><function>sd_notify_barrier()</function> allows the caller to synchronize against reception of | |
162 | previously sent notification messages and uses the <varname>BARRIER=1</varname> command. It takes a | |
163 | relative <varname>timeout</varname> value in microseconds which is passed to | |
164 | <citerefentry><refentrytitle>ppoll</refentrytitle><manvolnum>2</manvolnum> | |
165 | </citerefentry>. A value of UINT64_MAX is interpreted as infinite timeout.</para> | |
166 | ||
167 | <para><function>sd_pid_notify_barrier()</function> is just like <function>sd_notify_barrier()</function>, | |
168 | but allows specifying the originating PID for the notification message.</para> | |
169 | </refsect1> | |
170 | ||
171 | <refsect1> | |
172 | <title>Well-known assignments</title> | |
173 | ||
174 | <para>The following assignments have a defined meaning:</para> | |
798d3a52 ZJS |
175 | |
176 | <variablelist> | |
177 | <varlistentry> | |
178 | <term>READY=1</term> | |
179 | ||
81e19b6f LP |
180 | <listitem><para>Tells the service manager that service startup is finished, or the service finished |
181 | re-loading its configuration. This is only used by systemd if the service definition file has | |
182 | <varname>Type=notify</varname> or <varname>Type=notify-reload</varname> set. Since there is little | |
183 | value in signaling non-readiness, the only value services should send is <literal>READY=1</literal> | |
184 | (i.e. <literal>READY=0</literal> is not defined).</para></listitem> | |
798d3a52 ZJS |
185 | </varlistentry> |
186 | ||
187 | <varlistentry> | |
188 | <term>RELOADING=1</term> | |
189 | ||
ef86486a ZJS |
190 | <listitem><para>Tells the service manager that the service is beginning to reload its configuration. |
191 | This is useful to allow the service manager to track the service's internal state, and present it to | |
192 | the user. Note that a service that sends this notification must also send a | |
81e19b6f LP |
193 | <literal>READY=1</literal> notification when it completed reloading its configuration. Reloads the |
194 | service manager is notified about with this mechanisms are propagated in the same way as they are | |
195 | when originally initiated through the service manager. This message is particularly relevant for | |
196 | <varname>Type=notify-reload</varname> services, to inform the service manager that the request to | |
ec07c3c8 AK |
197 | reload the service has been received and is now being processed.</para> |
198 | ||
199 | <xi:include href="version-info.xml" xpointer="v217"/></listitem> | |
81e19b6f LP |
200 | </varlistentry> |
201 | ||
ef86486a ZJS |
202 | <varlistentry> |
203 | <term>STOPPING=1</term> | |
204 | ||
205 | <listitem><para>Tells the service manager that the service is beginning its shutdown. This is useful | |
206 | to allow the service manager to track the service's internal state, and present it to the user. | |
207 | </para> | |
208 | ||
209 | <xi:include href="version-info.xml" xpointer="v217"/></listitem> | |
210 | </varlistentry> | |
211 | ||
81e19b6f LP |
212 | <varlistentry> |
213 | <term>MONOTONIC_USEC=…</term> | |
214 | ||
215 | <listitem><para>A field carrying the monotonic timestamp (as per | |
e503019b | 216 | <constant>CLOCK_MONOTONIC</constant>) formatted in decimal in μs, when the notification message was |
81e19b6f LP |
217 | generated by the client. This is typically used in combination with <literal>RELOADING=1</literal>, |
218 | to allow the service manager to properly synchronize reload cycles. See | |
219 | <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
ec07c3c8 AK |
220 | for details, specifically <literal>Type=notify-reload</literal>.</para> |
221 | ||
222 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
798d3a52 ZJS |
223 | </varlistentry> |
224 | ||
798d3a52 | 225 | <varlistentry> |
1eecafb8 | 226 | <term>STATUS=…</term> |
798d3a52 | 227 | |
1412ad9a LP |
228 | <listitem><para>Passes a single-line UTF-8 status string back to the service manager that describes |
229 | the service state. This is free-form and can be used for various purposes: general state feedback, | |
230 | fsck-like programs could pass completion percentages and failing programs could pass a human-readable | |
ef86486a | 231 | error message. Example: <literal>STATUS=Completed 66% of file system check…</literal></para> |
ec07c3c8 AK |
232 | |
233 | <xi:include href="version-info.xml" xpointer="v233"/></listitem> | |
798d3a52 ZJS |
234 | </varlistentry> |
235 | ||
19dff691 MY |
236 | <varlistentry> |
237 | <term>NOTIFYACCESS=…</term> | |
238 | ||
1412ad9a LP |
239 | <listitem><para>Reset the access to the service status notification socket during runtime, overriding |
240 | <varname>NotifyAccess=</varname> setting in the service unit file. See | |
241 | <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
ef86486a ZJS |
242 | for details, specifically <literal>NotifyAccess=</literal> for a list of accepted values. |
243 | </para> | |
ec07c3c8 AK |
244 | |
245 | <xi:include href="version-info.xml" xpointer="v254"/></listitem> | |
19dff691 MY |
246 | </varlistentry> |
247 | ||
798d3a52 | 248 | <varlistentry> |
1eecafb8 | 249 | <term>ERRNO=…</term> |
798d3a52 | 250 | |
1412ad9a | 251 | <listitem><para>If a service fails, the errno-style error code, formatted as string. Example: |
ec07c3c8 AK |
252 | <literal>ERRNO=2</literal> for ENOENT.</para> |
253 | ||
254 | <xi:include href="version-info.xml" xpointer="v233"/></listitem> | |
798d3a52 ZJS |
255 | </varlistentry> |
256 | ||
257 | <varlistentry> | |
1eecafb8 | 258 | <term>BUSERROR=…</term> |
798d3a52 | 259 | |
1412ad9a | 260 | <listitem><para>If a service fails, the D-Bus error-style error code. Example: |
bb8a3296 ZJS |
261 | <literal>BUSERROR=org.freedesktop.DBus.Error.TimedOut</literal>. Note that this assignment is |
262 | currently not used by <command>systemd</command>.</para> | |
ec07c3c8 AK |
263 | |
264 | <xi:include href="version-info.xml" xpointer="v233"/></listitem> | |
798d3a52 ZJS |
265 | </varlistentry> |
266 | ||
623a0002 DDM |
267 | <varlistentry> |
268 | <term>EXIT_STATUS=…</term> | |
269 | ||
bb8a3296 ZJS |
270 | <listitem><para>The exit status of a service or the manager itself. Note that |
271 | <command>systemd</command> currently does not consume this value when sent by services, so this | |
272 | assignment is only informational. The manager will send this notification to <emphasis>its</emphasis> | |
273 | notification socket, which may be used to to collect an exit status from the system (a container or | |
274 | VM) as it shuts down. For example, | |
275 | <citerefentry project='debian'><refentrytitle>mkosi</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
276 | makes use of this. The value to return may be set via the | |
277 | <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
278 | <command>exit</command> verb.</para> | |
ec07c3c8 AK |
279 | |
280 | <xi:include href="version-info.xml" xpointer="v254"/></listitem> | |
623a0002 DDM |
281 | </varlistentry> |
282 | ||
798d3a52 | 283 | <varlistentry> |
1eecafb8 | 284 | <term>MAINPID=…</term> |
798d3a52 | 285 | |
1412ad9a | 286 | <listitem><para>The main process ID (PID) of the service, in case the service manager did not fork |
ef86486a | 287 | off the process itself. Example: <literal>MAINPID=4711</literal>.</para> |
ec07c3c8 AK |
288 | |
289 | <xi:include href="version-info.xml" xpointer="v233"/></listitem> | |
798d3a52 ZJS |
290 | </varlistentry> |
291 | ||
292 | <varlistentry> | |
293 | <term>WATCHDOG=1</term> | |
294 | ||
1412ad9a LP |
295 | <listitem><para>Tells the service manager to update the watchdog timestamp. This is the keep-alive |
296 | ping that services need to issue in regular intervals if <varname>WatchdogSec=</varname> is enabled | |
297 | for it. See | |
798d3a52 ZJS |
298 | <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> |
299 | for information how to enable this functionality and | |
300 | <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
1412ad9a | 301 | for the details of how the service can check whether the watchdog is enabled. </para></listitem> |
798d3a52 ZJS |
302 | </varlistentry> |
303 | ||
99b43caf JK |
304 | <varlistentry> |
305 | <term>WATCHDOG=trigger</term> | |
306 | ||
1412ad9a LP |
307 | <listitem><para>Tells the service manager that the service detected an internal error that should be |
308 | handled by the configured watchdog options. This will trigger the same behaviour as if | |
309 | <varname>WatchdogSec=</varname> is enabled and the service did not send <literal>WATCHDOG=1</literal> | |
310 | in time. Note that <varname>WatchdogSec=</varname> does not need to be enabled for | |
311 | <literal>WATCHDOG=trigger</literal> to trigger the watchdog action. See | |
312 | <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
ec07c3c8 AK |
313 | for information about the watchdog behavior. </para> |
314 | ||
315 | <xi:include href="version-info.xml" xpointer="v243"/></listitem> | |
99b43caf JK |
316 | </varlistentry> |
317 | ||
c45d11cb LP |
318 | <varlistentry> |
319 | <term>WATCHDOG_USEC=…</term> | |
320 | ||
1412ad9a LP |
321 | <listitem><para>Reset <varname>watchdog_usec</varname> value during runtime. Notice that this is not |
322 | available when using <function>sd_event_set_watchdog()</function> or | |
323 | <function>sd_watchdog_enabled()</function>. Example : | |
ec07c3c8 AK |
324 | <literal>WATCHDOG_USEC=20000000</literal></para> |
325 | ||
326 | <xi:include href="version-info.xml" xpointer="v233"/></listitem> | |
c45d11cb | 327 | </varlistentry> |
798d3a52 | 328 | |
a327431b DB |
329 | <varlistentry> |
330 | <term>EXTEND_TIMEOUT_USEC=…</term> | |
331 | ||
332 | <listitem><para>Tells the service manager to extend the startup, runtime or shutdown service timeout | |
1412ad9a LP |
333 | corresponding the current state. The value specified is a time in microseconds during which the |
334 | service must send a new message. A service timeout will occur if the message isn't received, but only | |
335 | if the runtime of the current state is beyond the original maximum times of | |
336 | <varname>TimeoutStartSec=</varname>, <varname>RuntimeMaxSec=</varname>, and | |
337 | <varname>TimeoutStopSec=</varname>. See | |
338 | <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
ec07c3c8 AK |
339 | for effects on the service timeouts.</para> |
340 | ||
341 | <xi:include href="version-info.xml" xpointer="v236"/></listitem> | |
a327431b DB |
342 | </varlistentry> |
343 | ||
798d3a52 ZJS |
344 | <varlistentry> |
345 | <term>FDSTORE=1</term> | |
346 | ||
67da7e9a ZJS |
347 | <listitem><para>Store file descriptors in the service manager. File descriptors sent this way will be |
348 | held for the service by the service manager and will later be handed back using the usual file | |
349 | descriptor passing logic at the next start or restart of the service, see | |
75b29fda | 350 | <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>. |
67da7e9a ZJS |
351 | Any open sockets and other file descriptors which should not be closed during a restart may be stored |
352 | this way. When a service is stopped, its file descriptor store is discarded and all file descriptors | |
353 | in it are closed, except when overridden with <varname>FileDescriptorStorePreserve=</varname>, see | |
354 | <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>. | |
355 | </para> | |
356 | ||
357 | <para>The service manager will accept messages for a service only if its | |
3ceb72e5 | 358 | <varname>FileDescriptorStoreMax=</varname> setting is non-zero (defaults to zero, see |
67da7e9a ZJS |
359 | <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>). |
360 | The service manager will set the <varname>$FDSTORE</varname> environment variable for services that | |
361 | have the file descriptor store enabled, see | |
362 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. | |
363 | </para> | |
364 | ||
365 | <para>If <varname>FDPOLL=0</varname> is not set and the file descriptors are pollable (see | |
75b29fda LP |
366 | <citerefentry><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>), then |
367 | any <constant>EPOLLHUP</constant> or <constant>EPOLLERR</constant> event seen on them will result in | |
67da7e9a ZJS |
368 | their automatic removal from the store.</para> |
369 | ||
370 | <para>Multiple sets of file descriptors may be sent in separate messages, in which case the sets are | |
371 | combined. The service manager removes duplicate file descriptors (those pointing to the same object) | |
372 | before passing them to the service.</para> | |
373 | ||
374 | <para>This functionality should be used to implement services that can restart after an explicit | |
375 | request or a crash without losing state. Application state can either be serialized to a file in | |
376 | <filename>/run/</filename>, or better, stored in a | |
377 | <citerefentry><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
378 | memory file descriptor. Use <function>sd_pid_notify_with_fds()</function> to send messages with | |
379 | <literal>FDSTORE=1</literal>. It is recommended to combine <varname>FDSTORE=</varname> with | |
380 | <varname>FDNAME=</varname> to make it easier to manage the stored file descriptors.</para> | |
ec07c3c8 | 381 | |
0959847a LP |
382 | <para>For further information on the file descriptor store see the <ulink |
383 | url="https://systemd.io/FILE_DESCRIPTOR_STORE">File Descriptor Store</ulink> overview.</para> | |
384 | ||
ec07c3c8 | 385 | <xi:include href="version-info.xml" xpointer="v219"/></listitem> |
798d3a52 ZJS |
386 | </varlistentry> |
387 | ||
e78ee06d LP |
388 | <varlistentry> |
389 | <term>FDSTOREREMOVE=1</term> | |
390 | ||
1412ad9a LP |
391 | <listitem><para>Removes file descriptors from the file descriptor store. This field needs to be |
392 | combined with <varname>FDNAME=</varname> to specify the name of the file descriptors to | |
ec07c3c8 AK |
393 | remove.</para> |
394 | ||
395 | <xi:include href="version-info.xml" xpointer="v236"/></listitem> | |
e78ee06d LP |
396 | </varlistentry> |
397 | ||
8dd4c05b | 398 | <varlistentry> |
1eecafb8 | 399 | <term>FDNAME=…</term> |
8dd4c05b | 400 | |
1412ad9a LP |
401 | <listitem><para>When used in combination with <varname>FDSTORE=1</varname>, specifies a name for the |
402 | submitted file descriptors. When used with <varname>FDSTOREREMOVE=1</varname>, specifies the name for | |
403 | the file descriptors to remove. This name is passed to the service during activation, and may be | |
404 | queried using | |
67da7e9a ZJS |
405 | <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>. |
406 | File descriptors submitted without this field will be called <literal>stored</literal>.</para> | |
407 | ||
408 | <para>The name may consist of arbitrary ASCII characters except control characters or | |
409 | <literal>:</literal>. It may not be longer than 255 characters. If a submitted name does not follow | |
410 | these restrictions, it is ignored.</para> | |
411 | ||
412 | <para>Note that if multiple file descriptors are submitted in a single message, the specified name | |
413 | will be used for all of them. In order to assign different names to submitted file descriptors, | |
414 | submit them in separate messages.</para> | |
ec07c3c8 AK |
415 | |
416 | <xi:include href="version-info.xml" xpointer="v233"/></listitem> | |
8dd4c05b LP |
417 | </varlistentry> |
418 | ||
cb5a46b8 KL |
419 | <varlistentry> |
420 | <term>FDPOLL=0</term> | |
421 | ||
1412ad9a LP |
422 | <listitem><para>When used in combination with <varname>FDSTORE=1</varname>, disables polling of the |
423 | stored file descriptors regardless of whether or not they are pollable. As this option disables | |
424 | automatic cleanup of the stored file descriptors on EPOLLERR and EPOLLHUP, care must be taken to | |
425 | ensure proper manual cleanup. Use of this option is not generally recommended except for when | |
426 | automatic cleanup has unwanted behavior such as prematurely discarding file descriptors from the | |
ec07c3c8 AK |
427 | store.</para> |
428 | ||
429 | <xi:include href="version-info.xml" xpointer="v246"/></listitem> | |
cb5a46b8 KL |
430 | </varlistentry> |
431 | ||
4f07ddfa KKD |
432 | <varlistentry> |
433 | <term>BARRIER=1</term> | |
434 | ||
9cfc294f ZJS |
435 | <listitem><para>Tells the service manager that the client is explicitly requesting synchronization by |
436 | means of closing the file descriptor sent with this command. The service manager guarantees that the | |
437 | processing of a <varname>BARRIER=1</varname> command will only happen after all previous notification | |
438 | messages sent before this command have been processed. Hence, this command accompanied with a single | |
439 | file descriptor can be used to synchronize against reception of all previous status messages. Note | |
440 | that this command cannot be mixed with other notifications, and has to be sent in a separate message | |
441 | to the service manager, otherwise all assignments will be ignored. Note that sending 0 or more than 1 | |
ec07c3c8 AK |
442 | file descriptor with this command is a violation of the protocol.</para> |
443 | ||
444 | <xi:include href="version-info.xml" xpointer="v246"/></listitem> | |
4f07ddfa | 445 | </varlistentry> |
798d3a52 ZJS |
446 | </variablelist> |
447 | ||
bb8a3296 ZJS |
448 | <para>The notification messages sent by services are interpreted by the service manager. Unknown |
449 | assignments may be logged, but are otherwise ignored. Thus, it is not useful to send assignments which | |
450 | are not in this list. The service manager also sends some messages to <emphasis>its</emphasis> | |
451 | notification socket, which are then consumed by the machine or container manager.</para> | |
798d3a52 ZJS |
452 | </refsect1> |
453 | ||
454 | <refsect1> | |
455 | <title>Return Value</title> | |
456 | ||
1412ad9a LP |
457 | <para>On failure, these calls return a negative errno-style error code. If |
458 | <varname>$NOTIFY_SOCKET</varname> was not set and hence no status message could be sent, 0 is | |
459 | returned. If the status was sent, these functions return a positive value. In order to support both | |
460 | service managers that implement this scheme and those which do not, it is generally recommended to ignore | |
461 | the return value of this call. Note that the return value simply indicates whether the notification | |
462 | message was enqueued properly, it does not reflect whether the message could be processed | |
3ceb72e5 | 463 | successfully. Specifically, no error is returned when a file descriptor is attempted to be stored using |
1412ad9a LP |
464 | <varname>FDSTORE=1</varname> but the service is not actually configured to permit storing of file |
465 | descriptors (see above).</para> | |
798d3a52 ZJS |
466 | </refsect1> |
467 | ||
468 | <refsect1> | |
469 | <title>Notes</title> | |
470 | ||
471 | <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> | |
8c51e152 | 472 | <xi:include href="threads-aware.xml" xpointer="getenv"/> |
798d3a52 | 473 | |
1412ad9a LP |
474 | <para>These functions send a single datagram with the state string as payload to the socket referenced in |
475 | the <varname>$NOTIFY_SOCKET</varname> environment variable. If the first character of | |
476 | <varname>$NOTIFY_SOCKET</varname> is <literal>/</literal> or <literal>@</literal>, the string is | |
477 | understood as an <constant>AF_UNIX</constant> or Linux abstract namespace socket (respectively), and in | |
478 | both cases the datagram is accompanied by the process credentials of the sending service, using | |
479 | SCM_CREDENTIALS. If the string starts with <literal>vsock:</literal> then the string is understood as an | |
480 | <constant>AF_VSOCK</constant> address, which is useful for hypervisors/VMMs or other processes on the | |
481 | host to receive a notification when a virtual machine has finished booting. Note that in case the | |
482 | hypervisor does not support <constant>SOCK_DGRAM</constant> over <constant>AF_VSOCK</constant>, | |
483 | <constant>SOCK_SEQPACKET</constant> will be used instead. The address should be in the form: | |
484 | <literal>vsock:CID:PORT</literal>. Note that unlike other uses of vsock, the CID is mandatory and cannot | |
485 | be <literal>VMADDR_CID_ANY</literal>. Note that PID1 will send the VSOCK packets from a privileged port | |
486 | (i.e.: lower than 1024), as an attempt to address concerns that unprivileged processes in the guest might | |
487 | try to send malicious notifications to the host, driving it to make destructive decisions based on | |
488 | them.</para> | |
798d3a52 ZJS |
489 | </refsect1> |
490 | ||
491 | <refsect1> | |
492 | <title>Environment</title> | |
493 | ||
494 | <variablelist class='environment-variables'> | |
495 | <varlistentry> | |
496 | <term><varname>$NOTIFY_SOCKET</varname></term> | |
497 | ||
1412ad9a LP |
498 | <listitem><para>Set by the service manager for supervised processes for status and start-up |
499 | completion notification. This environment variable specifies the socket | |
500 | <function>sd_notify()</function> talks to. See above for details.</para></listitem> | |
798d3a52 ZJS |
501 | </varlistentry> |
502 | </variablelist> | |
503 | </refsect1> | |
504 | ||
505 | <refsect1> | |
506 | <title>Examples</title> | |
507 | ||
508 | <example> | |
509 | <title>Start-up Notification</title> | |
510 | ||
1412ad9a LP |
511 | <para>When a service finished starting up, it might issue the following call to notify the service |
512 | manager:</para> | |
798d3a52 ZJS |
513 | |
514 | <programlisting>sd_notify(0, "READY=1");</programlisting> | |
515 | </example> | |
516 | ||
517 | <example> | |
518 | <title>Extended Start-up Notification</title> | |
519 | ||
1412ad9a | 520 | <para>A service could send the following after completing initialization:</para> |
798d3a52 | 521 | |
066991f9 ZJS |
522 | <programlisting> |
523 | sd_notifyf(0, "READY=1\n" | |
524 | "STATUS=Processing requests…\n" | |
525 | "MAINPID=%lu", | |
526 | (unsigned long) getpid());</programlisting> | |
798d3a52 ZJS |
527 | </example> |
528 | ||
529 | <example> | |
530 | <title>Error Cause Notification</title> | |
531 | ||
532 | <para>A service could send the following shortly before exiting, on failure:</para> | |
533 | ||
066991f9 ZJS |
534 | <programlisting> |
535 | sd_notifyf(0, "STATUS=Failed to start up: %s\n" | |
536 | "ERRNO=%i", | |
537 | strerror_r(errnum, (char[1024]){}, 1024), | |
538 | errnum);</programlisting> | |
798d3a52 ZJS |
539 | </example> |
540 | ||
541 | <example> | |
542 | <title>Store a File Descriptor in the Service Manager</title> | |
543 | ||
1412ad9a LP |
544 | <para>To store an open file descriptor in the service manager, in order to continue operation after a |
545 | service restart without losing state, use <literal>FDSTORE=1</literal>:</para> | |
798d3a52 | 546 | |
8dd4c05b | 547 | <programlisting>sd_pid_notify_with_fds(0, 0, "FDSTORE=1\nFDNAME=foobar", &fd, 1);</programlisting> |
798d3a52 | 548 | </example> |
4f07ddfa KKD |
549 | |
550 | <example> | |
551 | <title>Eliminating race conditions</title> | |
552 | ||
1412ad9a LP |
553 | <para>When the client sending the notifications is not spawned by the service manager, it may exit too |
554 | quickly and the service manager may fail to attribute them correctly to the unit. To prevent such | |
555 | races, use <function>sd_notify_barrier()</function> to synchronize against reception of all | |
556 | notifications sent before this call is made.</para> | |
4f07ddfa | 557 | |
066991f9 ZJS |
558 | <programlisting> |
559 | sd_notify(0, "READY=1"); | |
560 | /* set timeout to 5 seconds */ | |
561 | sd_notify_barrier(0, 5 * 1000000); | |
4f07ddfa KKD |
562 | </programlisting> |
563 | </example> | |
798d3a52 ZJS |
564 | </refsect1> |
565 | ||
69106f47 AK |
566 | <refsect1> |
567 | <title>History</title> | |
00f95506 AK |
568 | <para><function>sd_pid_notify()</function>, |
569 | <function>sd_pid_notifyf()</function>, and | |
570 | <function>sd_pid_notify_with_fds()</function> were added in version 219.</para> | |
69106f47 | 571 | <para><function>sd_notify_barrier()</function> was added in version 246.</para> |
00f95506 AK |
572 | <para><function>sd_pid_notifyf_with_fds()</function> and |
573 | <function>sd_pid_notify_barrier()</function> were added in version 254.</para> | |
69106f47 AK |
574 | </refsect1> |
575 | ||
798d3a52 ZJS |
576 | <refsect1> |
577 | <title>See Also</title> | |
13a69c12 DT |
578 | <para><simplelist type="inline"> |
579 | <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
580 | <member><citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry></member> | |
581 | <member><citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry></member> | |
582 | <member><citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry></member> | |
583 | <member><citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry></member> | |
584 | <member><citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry></member> | |
585 | <member><citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry></member> | |
586 | </simplelist></para> | |
798d3a52 | 587 | </refsect1> |
f9378423 LP |
588 | |
589 | </refentry> |