1 <?xml version='
1.0'
?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 SPDX-License-Identifier: LGPL-2.1+
8 This file is part of systemd.
10 Copyright 2010 Lennart Poettering
13 <refentry id=
"sd_notify"
14 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
17 <title>sd_notify
</title>
18 <productname>systemd
</productname>
22 <contrib>Developer
</contrib>
23 <firstname>Lennart
</firstname>
24 <surname>Poettering
</surname>
25 <email>lennart@poettering.net
</email>
31 <refentrytitle>sd_notify
</refentrytitle>
32 <manvolnum>3</manvolnum>
36 <refname>sd_notify
</refname>
37 <refname>sd_notifyf
</refname>
38 <refname>sd_pid_notify
</refname>
39 <refname>sd_pid_notifyf
</refname>
40 <refname>sd_pid_notify_with_fds
</refname>
41 <refpurpose>Notify service manager about start-up completion and other service status changes
</refpurpose>
46 <funcsynopsisinfo>#include
<systemd/sd-daemon.h
></funcsynopsisinfo>
49 <funcdef>int
<function>sd_notify
</function></funcdef>
50 <paramdef>int
<parameter>unset_environment
</parameter></paramdef>
51 <paramdef>const char *
<parameter>state
</parameter></paramdef>
55 <funcdef>int
<function>sd_notifyf
</function></funcdef>
56 <paramdef>int
<parameter>unset_environment
</parameter></paramdef>
57 <paramdef>const char *
<parameter>format
</parameter></paramdef>
58 <paramdef>…
</paramdef>
62 <funcdef>int
<function>sd_pid_notify
</function></funcdef>
63 <paramdef>pid_t
<parameter>pid
</parameter></paramdef>
64 <paramdef>int
<parameter>unset_environment
</parameter></paramdef>
65 <paramdef>const char *
<parameter>state
</parameter></paramdef>
69 <funcdef>int
<function>sd_pid_notifyf
</function></funcdef>
70 <paramdef>pid_t
<parameter>pid
</parameter></paramdef>
71 <paramdef>int
<parameter>unset_environment
</parameter></paramdef>
72 <paramdef>const char *
<parameter>format
</parameter></paramdef>
73 <paramdef>…
</paramdef>
77 <funcdef>int
<function>sd_pid_notify_with_fds
</function></funcdef>
78 <paramdef>pid_t
<parameter>pid
</parameter></paramdef>
79 <paramdef>int
<parameter>unset_environment
</parameter></paramdef>
80 <paramdef>const char *
<parameter>state
</parameter></paramdef>
81 <paramdef>const int *
<parameter>fds
</parameter></paramdef>
82 <paramdef>unsigned
<parameter>n_fds
</parameter></paramdef>
88 <title>Description
</title>
89 <para><function>sd_notify()
</function> may be called by a service
90 to notify the service manager about state changes. It can be used
91 to send arbitrary information, encoded in an
92 environment-block-like string. Most importantly, it can be used for
93 start-up completion notification.
</para>
95 <para>If the
<parameter>unset_environment
</parameter> parameter is
96 non-zero,
<function>sd_notify()
</function> will unset the
97 <varname>$NOTIFY_SOCKET
</varname> environment variable before
98 returning (regardless of whether the function call itself
99 succeeded or not). Further calls to
100 <function>sd_notify()
</function> will then fail, but the variable
101 is no longer inherited by child processes.
</para>
103 <para>The
<parameter>state
</parameter> parameter should contain a
104 newline-separated list of variable assignments, similar in style
105 to an environment block. A trailing newline is implied if none is
106 specified. The string may contain any kind of variable
107 assignments, but the following shall be considered
114 <listitem><para>Tells the service manager that service startup is finished, or the service finished loading its
115 configuration. This is only used by systemd if the service definition file has
<varname>Type=notify
</varname>
116 set. Since there is little value in signaling non-readiness, the only value services should send is
117 <literal>READY=
1</literal> (i.e.
<literal>READY=
0</literal> is not defined).
</para></listitem>
121 <term>RELOADING=
1</term>
123 <listitem><para>Tells the service manager that the service is
124 reloading its configuration. This is useful to allow the
125 service manager to track the service's internal state, and
126 present it to the user. Note that a service that sends this
127 notification must also send a
<literal>READY=
1</literal>
128 notification when it completed reloading its
129 configuration. Reloads are propagated in the same way as they
130 are when initiated by the user.
</para></listitem>
134 <term>STOPPING=
1</term>
136 <listitem><para>Tells the service manager that the service is
137 beginning its shutdown. This is useful to allow the service
138 manager to track the service's internal state, and present it
139 to the user.
</para></listitem>
143 <term>STATUS=…
</term>
145 <listitem><para>Passes a single-line UTF-
8 status string back
146 to the service manager that describes the service state. This
147 is free-form and can be used for various purposes: general
148 state feedback, fsck-like programs could pass completion
149 percentages and failing programs could pass a human-readable
150 error message. Example:
<literal>STATUS=Completed
66% of file
151 system check…
</literal></para></listitem>
157 <listitem><para>If a service fails, the errno-style error
158 code, formatted as string. Example:
<literal>ERRNO=
2</literal>
159 for ENOENT.
</para></listitem>
163 <term>BUSERROR=…
</term>
165 <listitem><para>If a service fails, the D-Bus error-style
167 <literal>BUSERROR=org.freedesktop.DBus.Error.TimedOut
</literal></para></listitem>
171 <term>MAINPID=…
</term>
173 <listitem><para>The main process ID (PID) of the service, in
174 case the service manager did not fork off the process itself.
175 Example:
<literal>MAINPID=
4711</literal></para></listitem>
179 <term>WATCHDOG=
1</term>
181 <listitem><para>Tells the service manager to update the
182 watchdog timestamp. This is the keep-alive ping that services
183 need to issue in regular intervals if
184 <varname>WatchdogSec=
</varname> is enabled for it. See
185 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
186 for information how to enable this functionality and
187 <citerefentry><refentrytitle>sd_watchdog_enabled
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
188 for the details of how the service can check whether the
189 watchdog is enabled.
</para></listitem>
193 <term>WATCHDOG_USEC=…
</term>
195 <listitem><para>Reset
<varname>watchdog_usec
</varname> value during runtime.
196 Notice that this is not available when using
<function>sd_event_set_watchdog()
</function>
197 or
<function>sd_watchdog_enabled()
</function>.
198 Example :
<literal>WATCHDOG_USEC=
20000000</literal></para></listitem>
202 <term>EXTEND_TIMEOUT_USEC=…
</term>
204 <listitem><para>Tells the service manager to extend the startup, runtime or shutdown service timeout
205 corresponding the current state. The value specified is a time in microseconds during which the service must
206 send a new message. A service timeout will occur if the message isn't received, but only if the runtime of the
207 current state is beyond the original maximium times of
<varname>TimeoutStartSec=
</varname>,
<varname>RuntimeMaxSec=
</varname>,
208 and
<varname>TimeoutStopSec=
</varname>.
209 See
<citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
210 for effects on the service timeouts.
</para></listitem>
214 <term>FDSTORE=
1</term>
216 <listitem><para>Stores additional file descriptors in the service manager. File descriptors sent this way will
217 be maintained per-service by the service manager and will later be handed back using the usual file descriptor
218 passing logic at the next invocation of the service, see
219 <citerefentry><refentrytitle>sd_listen_fds
</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This is
220 useful for implementing services that can restart after an explicit request or a crash without losing
221 state. Any open sockets and other file descriptors which should not be closed during the restart may be stored
222 this way. Application state can either be serialized to a file in
<filename>/run
</filename>, or better, stored
223 in a
<citerefentry><refentrytitle>memfd_create
</refentrytitle><manvolnum>2</manvolnum></citerefentry> memory
224 file descriptor. Note that the service manager will accept messages for a service only if its
225 <varname>FileDescriptorStoreMax=
</varname> setting is non-zero (defaults to zero, see
226 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>). If file
227 descriptors sent are pollable (see
228 <citerefentry><refentrytitle>epoll_ctl
</refentrytitle><manvolnum>2</manvolnum></citerefentry>), then any
229 <constant>EPOLLHUP
</constant> or
<constant>EPOLLERR
</constant> event seen on them will result in their
230 automatic removal from the store. Multiple arrays of file descriptors may be sent in separate messages, in
231 which case the arrays are combined. Note that the service manager removes duplicate (pointing to the same
232 object) file descriptors before passing them to the service. Use
<function>sd_pid_notify_with_fds()
</function>
233 to send messages with
<literal>FDSTORE=
1</literal>, see below.
</para></listitem>
237 <term>FDSTOREREMOVE=
1</term>
239 <listitem><para>Removes file descriptors from the file descriptor store. This field needs to be combined with
240 <varname>FDNAME=
</varname> to specify the name of the file descriptors to remove.
</para></listitem>
244 <term>FDNAME=…
</term>
246 <listitem><para>When used in combination with
<varname>FDSTORE=
1</varname>, specifies a name for the submitted
247 file descriptors. When used with
<varname>FDSTOREREMOVE=
1</varname>, specifies the name for the file
248 descriptors to remove. This name is passed to the service during activation, and may be queried using
249 <citerefentry><refentrytitle>sd_listen_fds_with_names
</refentrytitle><manvolnum>3</manvolnum></citerefentry>. File
250 descriptors submitted without this field set, will implicitly get the name
<literal>stored
</literal>
251 assigned. Note that, if multiple file descriptors are submitted at once, the specified name will be assigned to
252 all of them. In order to assign different names to submitted file descriptors, submit them in separate
253 invocations of
<function>sd_pid_notify_with_fds()
</function>. The name may consist of arbitrary ASCII
254 characters except control characters or
<literal>:
</literal>. It may not be longer than
255 characters. If a
255 submitted name does not follow these restrictions, it is ignored.
</para></listitem>
260 <para>It is recommended to prefix variable names that are not
261 listed above with
<varname>X_
</varname> to avoid namespace
264 <para>Note that systemd will accept status data sent from a
265 service only if the
<varname>NotifyAccess=
</varname> option is
266 correctly set in the service definition file. See
267 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
270 <para>Note that
<function>sd_notify()
</function> notifications may be attributed to units correctly only if either
271 the sending process is still around at the time PID
1 processes the message, or if the sending process is
272 explicitly runtime-tracked by the service manager. The latter is the case if the service manager originally forked
273 off the process, i.e. on all processes that match
<varname>NotifyAccess=
</varname><option>main
</option> or
274 <varname>NotifyAccess=
</varname><option>exec
</option>. Conversely, if an auxiliary process of the unit sends an
275 <function>sd_notify()
</function> message and immediately exits, the service manager might not be able to properly
276 attribute the message to the unit, and thus will ignore it, even if
277 <varname>NotifyAccess=
</varname><option>all
</option> is set for it.
</para>
279 <para><function>sd_notifyf()
</function> is similar to
280 <function>sd_notify()
</function> but takes a
281 <function>printf()
</function>-like format string plus
284 <para><function>sd_pid_notify()
</function> and
285 <function>sd_pid_notifyf()
</function> are similar to
286 <function>sd_notify()
</function> and
287 <function>sd_notifyf()
</function> but take a process ID (PID) to
288 use as originating PID for the message as first argument. This is
289 useful to send notification messages on behalf of other processes,
290 provided the appropriate privileges are available. If the PID
291 argument is specified as
0, the process ID of the calling process
292 is used, in which case the calls are fully equivalent to
293 <function>sd_notify()
</function> and
294 <function>sd_notifyf()
</function>.
</para>
296 <para><function>sd_pid_notify_with_fds()
</function> is similar to
297 <function>sd_pid_notify()
</function> but takes an additional array
298 of file descriptors. These file descriptors are sent along the
299 notification message to the service manager. This is particularly
300 useful for sending
<literal>FDSTORE=
1</literal> messages, as
301 described above. The additional arguments are a pointer to the
302 file descriptor array plus the number of file descriptors in the
303 array. If the number of file descriptors is passed as
0, the call
304 is fully equivalent to
<function>sd_pid_notify()
</function>, i.e.
305 no file descriptors are passed. Note that sending file descriptors
306 to the service manager on messages that do not expect them (i.e.
307 without
<literal>FDSTORE=
1</literal>) they are immediately closed
312 <title>Return Value
</title>
314 <para>On failure, these calls return a negative errno-style error code. If
<varname>$NOTIFY_SOCKET
</varname> was
315 not set and hence no status message could be sent,
0 is returned. If the status was sent, these functions return a
316 positive value. In order to support both service managers that implement this scheme and those which do not, it is
317 generally recommended to ignore the return value of this call. Note that the return value simply indicates whether
318 the notification message was enqueued properly, it does not reflect whether the message could be processed
319 successfully. Specifically, no error is returned when a file descriptor is attempted to be stored using
320 <varname>FDSTORE=
1</varname> but the service is not actually configured to permit storing of file descriptors (see
327 <xi:include href=
"libsystemd-pkgconfig.xml" xpointer=
"pkgconfig-text"/>
329 <para>These functions send a single datagram with the
330 state string as payload to the
<constant>AF_UNIX
</constant> socket
331 referenced in the
<varname>$NOTIFY_SOCKET
</varname> environment
332 variable. If the first character of
333 <varname>$NOTIFY_SOCKET
</varname> is
<literal>@
</literal>, the
334 string is understood as Linux abstract namespace socket. The
335 datagram is accompanied by the process credentials of the sending
336 service, using SCM_CREDENTIALS.
</para>
340 <title>Environment
</title>
342 <variablelist class='environment-variables'
>
344 <term><varname>$NOTIFY_SOCKET
</varname></term>
346 <listitem><para>Set by the service manager for supervised
347 processes for status and start-up completion notification.
348 This environment variable specifies the socket
349 <function>sd_notify()
</function> talks to. See above for
350 details.
</para></listitem>
356 <title>Examples
</title>
359 <title>Start-up Notification
</title>
361 <para>When a service finished starting up, it might issue the
362 following call to notify the service manager:
</para>
364 <programlisting>sd_notify(
0,
"READY=1");
</programlisting>
368 <title>Extended Start-up Notification
</title>
370 <para>A service could send the following after completing
371 initialization:
</para>
373 <programlisting>sd_notifyf(
0,
"READY=1\n"
374 "STATUS=Processing requests…\n"
376 (unsigned long) getpid());
</programlisting>
380 <title>Error Cause Notification
</title>
382 <para>A service could send the following shortly before exiting, on failure:
</para>
384 <programlisting>sd_notifyf(
0,
"STATUS=Failed to start up: %s\n"
387 errno);
</programlisting>
391 <title>Store a File Descriptor in the Service Manager
</title>
393 <para>To store an open file descriptor in the service manager,
394 in order to continue operation after a service restart without
395 losing state, use
<literal>FDSTORE=
1</literal>:
</para>
397 <programlisting>sd_pid_notify_with_fds(
0,
0,
"FDSTORE=1\nFDNAME=foobar",
&fd,
1);
</programlisting>
402 <title>See Also
</title>
404 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
405 <citerefentry><refentrytitle>sd-daemon
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
406 <citerefentry><refentrytitle>sd_listen_fds
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
407 <citerefentry><refentrytitle>sd_listen_fds_with_names
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
408 <citerefentry><refentrytitle>sd_watchdog_enabled
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
409 <citerefentry><refentrytitle>daemon
</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
410 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>