mirror of
https://github.com/systemd/systemd.git
synced 2024-12-12 03:33:44 +08:00
471 lines
23 KiB
XML
471 lines
23 KiB
XML
<?xml version='1.0'?>
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
|
|
|
|
<refentry id="sd_notify"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
|
|
<refentryinfo>
|
|
<title>sd_notify</title>
|
|
<productname>systemd</productname>
|
|
</refentryinfo>
|
|
|
|
<refmeta>
|
|
<refentrytitle>sd_notify</refentrytitle>
|
|
<manvolnum>3</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>sd_notify</refname>
|
|
<refname>sd_notifyf</refname>
|
|
<refname>sd_pid_notify</refname>
|
|
<refname>sd_pid_notifyf</refname>
|
|
<refname>sd_pid_notify_with_fds</refname>
|
|
<refname>sd_notify_barrier</refname>
|
|
<refpurpose>Notify service manager about start-up completion and other service status changes</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo>
|
|
|
|
<funcprototype>
|
|
<funcdef>int <function>sd_notify</function></funcdef>
|
|
<paramdef>int <parameter>unset_environment</parameter></paramdef>
|
|
<paramdef>const char *<parameter>state</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>int <function>sd_notifyf</function></funcdef>
|
|
<paramdef>int <parameter>unset_environment</parameter></paramdef>
|
|
<paramdef>const char *<parameter>format</parameter></paramdef>
|
|
<paramdef>…</paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>int <function>sd_pid_notify</function></funcdef>
|
|
<paramdef>pid_t <parameter>pid</parameter></paramdef>
|
|
<paramdef>int <parameter>unset_environment</parameter></paramdef>
|
|
<paramdef>const char *<parameter>state</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>int <function>sd_pid_notifyf</function></funcdef>
|
|
<paramdef>pid_t <parameter>pid</parameter></paramdef>
|
|
<paramdef>int <parameter>unset_environment</parameter></paramdef>
|
|
<paramdef>const char *<parameter>format</parameter></paramdef>
|
|
<paramdef>…</paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>int <function>sd_pid_notify_with_fds</function></funcdef>
|
|
<paramdef>pid_t <parameter>pid</parameter></paramdef>
|
|
<paramdef>int <parameter>unset_environment</parameter></paramdef>
|
|
<paramdef>const char *<parameter>state</parameter></paramdef>
|
|
<paramdef>const int *<parameter>fds</parameter></paramdef>
|
|
<paramdef>unsigned <parameter>n_fds</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>int <function>sd_notify_barrier</function></funcdef>
|
|
<paramdef>int <parameter>unset_environment</parameter></paramdef>
|
|
<paramdef>uint64_t <parameter>timeout</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<para><function>sd_notify()</function> may be called by a service
|
|
to notify the service manager about state changes. It can be used
|
|
to send arbitrary information, encoded in an
|
|
environment-block-like string. Most importantly, it can be used for
|
|
start-up completion notification.</para>
|
|
|
|
<para>If the <parameter>unset_environment</parameter> parameter is
|
|
non-zero, <function>sd_notify()</function> will unset the
|
|
<varname>$NOTIFY_SOCKET</varname> environment variable before
|
|
returning (regardless of whether the function call itself
|
|
succeeded or not). Further calls to
|
|
<function>sd_notify()</function> will then fail, but the variable
|
|
is no longer inherited by child processes.</para>
|
|
|
|
<para>The <parameter>state</parameter> parameter should contain a
|
|
newline-separated list of variable assignments, similar in style
|
|
to an environment block. A trailing newline is implied if none is
|
|
specified. The string may contain any kind of variable
|
|
assignments, but the following shall be considered
|
|
well-known:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>READY=1</term>
|
|
|
|
<listitem><para>Tells the service manager that service startup is finished, or the service finished loading its
|
|
configuration. This is only used by systemd if the service definition file has <varname>Type=notify</varname>
|
|
set. Since there is little value in signaling non-readiness, the only value services should send is
|
|
<literal>READY=1</literal> (i.e. <literal>READY=0</literal> is not defined).</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>RELOADING=1</term>
|
|
|
|
<listitem><para>Tells the service manager that the service is
|
|
reloading its configuration. This is useful to allow the
|
|
service manager to track the service's internal state, and
|
|
present it to the user. Note that a service that sends this
|
|
notification must also send a <literal>READY=1</literal>
|
|
notification when it completed reloading its
|
|
configuration. Reloads are propagated in the same way as they
|
|
are when initiated by the user.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>STOPPING=1</term>
|
|
|
|
<listitem><para>Tells the service manager that the service is
|
|
beginning its shutdown. This is useful to allow the service
|
|
manager to track the service's internal state, and present it
|
|
to the user.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>STATUS=…</term>
|
|
|
|
<listitem><para>Passes a single-line UTF-8 status string back
|
|
to the service manager that describes the service state. This
|
|
is free-form and can be used for various purposes: general
|
|
state feedback, fsck-like programs could pass completion
|
|
percentages and failing programs could pass a human-readable
|
|
error message. Example: <literal>STATUS=Completed 66% of file
|
|
system check…</literal></para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>ERRNO=…</term>
|
|
|
|
<listitem><para>If a service fails, the errno-style error
|
|
code, formatted as string. Example: <literal>ERRNO=2</literal>
|
|
for ENOENT.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>BUSERROR=…</term>
|
|
|
|
<listitem><para>If a service fails, the D-Bus error-style
|
|
error code. Example:
|
|
<literal>BUSERROR=org.freedesktop.DBus.Error.TimedOut</literal></para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>MAINPID=…</term>
|
|
|
|
<listitem><para>The main process ID (PID) of the service, in
|
|
case the service manager did not fork off the process itself.
|
|
Example: <literal>MAINPID=4711</literal></para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>WATCHDOG=1</term>
|
|
|
|
<listitem><para>Tells the service manager to update the
|
|
watchdog timestamp. This is the keep-alive ping that services
|
|
need to issue in regular intervals if
|
|
<varname>WatchdogSec=</varname> is enabled for it. See
|
|
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
|
for information how to enable this functionality and
|
|
<citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
|
for the details of how the service can check whether the
|
|
watchdog is enabled. </para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>WATCHDOG=trigger</term>
|
|
|
|
<listitem><para>Tells the service manager that the service detected an internal error that should be handled by
|
|
the configured watchdog options. This will trigger the same behaviour as if <varname>WatchdogSec=</varname> is
|
|
enabled and the service did not send <literal>WATCHDOG=1</literal> in time. Note that
|
|
<varname>WatchdogSec=</varname> does not need to be enabled for <literal>WATCHDOG=trigger</literal> to trigger
|
|
the watchdog action. See
|
|
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
|
|
information about the watchdog behavior. </para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>WATCHDOG_USEC=…</term>
|
|
|
|
<listitem><para>Reset <varname>watchdog_usec</varname> value during runtime.
|
|
Notice that this is not available when using <function>sd_event_set_watchdog()</function>
|
|
or <function>sd_watchdog_enabled()</function>.
|
|
Example : <literal>WATCHDOG_USEC=20000000</literal></para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>EXTEND_TIMEOUT_USEC=…</term>
|
|
|
|
<listitem><para>Tells the service manager to extend the startup, runtime or shutdown service timeout
|
|
corresponding the current state. The value specified is a time in microseconds during which the service must
|
|
send a new message. A service timeout will occur if the message isn't received, but only if the runtime of the
|
|
current state is beyond the original maximum times of <varname>TimeoutStartSec=</varname>, <varname>RuntimeMaxSec=</varname>,
|
|
and <varname>TimeoutStopSec=</varname>.
|
|
See <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
|
for effects on the service timeouts.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>FDSTORE=1</term>
|
|
|
|
<listitem><para>Stores additional file descriptors in the service manager. File descriptors sent this way will
|
|
be maintained per-service by the service manager and will later be handed back using the usual file descriptor
|
|
passing logic at the next invocation of the service (e.g. when it is restarted), see
|
|
<citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This is
|
|
useful for implementing services that can restart after an explicit request or a crash without losing
|
|
state. Any open sockets and other file descriptors which should not be closed during the restart may be stored
|
|
this way. Application state can either be serialized to a file in <filename>/run/</filename>, or better, stored
|
|
in a <citerefentry><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry> memory
|
|
file descriptor. Note that the service manager will accept messages for a service only if its
|
|
<varname>FileDescriptorStoreMax=</varname> setting is non-zero (defaults to zero, see
|
|
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>). If
|
|
<varname>FDPOLL=0</varname> is not set and the file descriptors sent are pollable (see
|
|
<citerefentry><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>), then any
|
|
<constant>EPOLLHUP</constant> or <constant>EPOLLERR</constant> event seen on them will result in their
|
|
automatic removal from the store. Multiple arrays of file descriptors may be sent in separate messages, in
|
|
which case the arrays are combined. Note that the service manager removes duplicate (pointing to the same
|
|
object) file descriptors before passing them to the service. When a service is stopped, its file descriptor
|
|
store is discarded and all file descriptors in it are closed. Use <function>sd_pid_notify_with_fds()</function>
|
|
to send messages with <literal>FDSTORE=1</literal>, see below.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>FDSTOREREMOVE=1</term>
|
|
|
|
<listitem><para>Removes file descriptors from the file descriptor store. This field needs to be combined with
|
|
<varname>FDNAME=</varname> to specify the name of the file descriptors to remove.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>FDNAME=…</term>
|
|
|
|
<listitem><para>When used in combination with <varname>FDSTORE=1</varname>, specifies a name for the submitted
|
|
file descriptors. When used with <varname>FDSTOREREMOVE=1</varname>, specifies the name for the file
|
|
descriptors to remove. This name is passed to the service during activation, and may be queried using
|
|
<citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>. File
|
|
descriptors submitted without this field set, will implicitly get the name <literal>stored</literal>
|
|
assigned. Note that, if multiple file descriptors are submitted at once, the specified name will be assigned to
|
|
all of them. In order to assign different names to submitted file descriptors, submit them in separate
|
|
invocations of <function>sd_pid_notify_with_fds()</function>. The name may consist of arbitrary ASCII
|
|
characters except control characters or <literal>:</literal>. It may not be longer than 255 characters. If a
|
|
submitted name does not follow these restrictions, it is ignored.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>FDPOLL=0</term>
|
|
|
|
<listitem><para>When used in combination with <varname>FDSTORE=1</varname>, disables polling of the stored
|
|
file descriptors regardless of whether or not they are pollable. As this option disables automatic cleanup
|
|
of the stored file descriptors on EPOLLERR and EPOLLHUP, care must be taken to ensure proper manual cleanup.
|
|
Use of this option is not generally recommended except for when automatic cleanup has unwanted behavior such
|
|
as prematurely discarding file descriptors from the store.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>BARRIER=1</term>
|
|
|
|
<listitem><para>Tells the service manager that the client is explicitly requesting synchronization by means of
|
|
closing the file descriptor sent with this command. The service manager guarantees that the processing of a <varname>
|
|
BARRIER=1</varname> command will only happen after all previous notification messages sent before this command
|
|
have been processed. Hence, this command accompanied with a single file descriptor can be used to synchronize
|
|
against reception of all previous status messages. Note that this command cannot be mixed with other notifications,
|
|
and has to be sent in a separate message to the service manager, otherwise all assignments will be ignored. Note that
|
|
sending 0 or more than 1 file descriptor with this command is a violation of the protocol.</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>It is recommended to prefix variable names that are not
|
|
listed above with <varname>X_</varname> to avoid namespace
|
|
clashes.</para>
|
|
|
|
<para>Note that systemd will accept status data sent from a
|
|
service only if the <varname>NotifyAccess=</varname> option is
|
|
correctly set in the service definition file. See
|
|
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
|
for details.</para>
|
|
|
|
<para>Note that <function>sd_notify()</function> notifications may be attributed to units correctly only if either
|
|
the sending process is still around at the time PID 1 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 <varname>NotifyAccess=</varname><option>main</option> or
|
|
<varname>NotifyAccess=</varname><option>exec</option>. Conversely, if an auxiliary process of the unit sends an
|
|
<function>sd_notify()</function> 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
|
|
<varname>NotifyAccess=</varname><option>all</option> is set for it.</para>
|
|
|
|
<para>Hence, to eliminate all race conditions involving lookup of the client's unit and attribution of notifications
|
|
to units correctly, <function>sd_notify_barrier()</function> may be used. This call acts as a synchronization point
|
|
and ensures all notifications sent before this call have been picked up by the service manager when it returns
|
|
successfully. Use of <function>sd_notify_barrier()</function> is needed for clients which are not invoked by the
|
|
service manager, otherwise this synchronization mechanism is unnecessary for attribution of notifications to the
|
|
unit.</para>
|
|
|
|
<para><function>sd_notifyf()</function> is similar to
|
|
<function>sd_notify()</function> but takes a
|
|
<function>printf()</function>-like format string plus
|
|
arguments.</para>
|
|
|
|
<para><function>sd_pid_notify()</function> and
|
|
<function>sd_pid_notifyf()</function> are similar to
|
|
<function>sd_notify()</function> and
|
|
<function>sd_notifyf()</function> but take a process ID (PID) to
|
|
use as originating PID for the message as first argument. This is
|
|
useful to send notification messages on behalf of other processes,
|
|
provided the appropriate privileges are available. If the PID
|
|
argument is specified as 0, the process ID of the calling process
|
|
is used, in which case the calls are fully equivalent to
|
|
<function>sd_notify()</function> and
|
|
<function>sd_notifyf()</function>.</para>
|
|
|
|
<para><function>sd_pid_notify_with_fds()</function> is similar to
|
|
<function>sd_pid_notify()</function> but takes an additional array
|
|
of file descriptors. These file descriptors are sent along the
|
|
notification message to the service manager. This is particularly
|
|
useful for sending <literal>FDSTORE=1</literal> messages, as
|
|
described above. The additional arguments are a pointer to the
|
|
file descriptor array plus the number of file descriptors in the
|
|
array. If the number of file descriptors is passed as 0, the call
|
|
is fully equivalent to <function>sd_pid_notify()</function>, i.e.
|
|
no file descriptors are passed. Note that sending file descriptors
|
|
to the service manager on messages that do not expect them (i.e.
|
|
without <literal>FDSTORE=1</literal>) they are immediately closed
|
|
on reception.</para>
|
|
|
|
<para><function>sd_notify_barrier()</function> allows the caller to
|
|
synchronize against reception of previously sent notification messages
|
|
and uses the <literal>BARRIER=1</literal> command. It takes a relative
|
|
<varname>timeout</varname> value in microseconds which is passed to
|
|
<citerefentry><refentrytitle>ppoll</refentrytitle><manvolnum>2</manvolnum>
|
|
</citerefentry>. A value of UINT64_MAX is interpreted as infinite timeout.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
|
|
<para>On failure, these calls return a negative errno-style error code. If <varname>$NOTIFY_SOCKET</varname> was
|
|
not set and hence no status message could be sent, 0 is returned. If the status was sent, these functions return a
|
|
positive value. In order to support both service managers that implement this scheme and those which do not, it is
|
|
generally recommended to ignore the return value of this call. Note that the return value simply indicates whether
|
|
the notification message was enqueued properly, it does not reflect whether the message could be processed
|
|
successfully. Specifically, no error is returned when a file descriptor is attempted to be stored using
|
|
<varname>FDSTORE=1</varname> but the service is not actually configured to permit storing of file descriptors (see
|
|
above).</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Notes</title>
|
|
|
|
<xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
|
|
|
|
<para>These functions send a single datagram with the
|
|
state string as payload to the <constant>AF_UNIX</constant> socket
|
|
referenced in the <varname>$NOTIFY_SOCKET</varname> environment
|
|
variable. If the first character of
|
|
<varname>$NOTIFY_SOCKET</varname> is <literal>@</literal>, the
|
|
string is understood as Linux abstract namespace socket. The
|
|
datagram is accompanied by the process credentials of the sending
|
|
service, using SCM_CREDENTIALS.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Environment</title>
|
|
|
|
<variablelist class='environment-variables'>
|
|
<varlistentry>
|
|
<term><varname>$NOTIFY_SOCKET</varname></term>
|
|
|
|
<listitem><para>Set by the service manager for supervised
|
|
processes for status and start-up completion notification.
|
|
This environment variable specifies the socket
|
|
<function>sd_notify()</function> talks to. See above for
|
|
details.</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Examples</title>
|
|
|
|
<example>
|
|
<title>Start-up Notification</title>
|
|
|
|
<para>When a service finished starting up, it might issue the
|
|
following call to notify the service manager:</para>
|
|
|
|
<programlisting>sd_notify(0, "READY=1");</programlisting>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Extended Start-up Notification</title>
|
|
|
|
<para>A service could send the following after completing
|
|
initialization:</para>
|
|
|
|
<programlisting>sd_notifyf(0, "READY=1\n"
|
|
"STATUS=Processing requests…\n"
|
|
"MAINPID=%lu",
|
|
(unsigned long) getpid());</programlisting>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Error Cause Notification</title>
|
|
|
|
<para>A service could send the following shortly before exiting, on failure:</para>
|
|
|
|
<programlisting>sd_notifyf(0, "STATUS=Failed to start up: %s\n"
|
|
"ERRNO=%i",
|
|
strerror(errno),
|
|
errno);</programlisting>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Store a File Descriptor in the Service Manager</title>
|
|
|
|
<para>To store an open file descriptor in the service manager,
|
|
in order to continue operation after a service restart without
|
|
losing state, use <literal>FDSTORE=1</literal>:</para>
|
|
|
|
<programlisting>sd_pid_notify_with_fds(0, 0, "FDSTORE=1\nFDNAME=foobar", &fd, 1);</programlisting>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Eliminating race conditions</title>
|
|
|
|
<para>When the client sending the notifications is not spawned
|
|
by the service manager, it may exit too quickly and the service
|
|
manager may fail to attribute them correctly to the unit. To
|
|
prevent such races, use <function>sd_notify_barrier()</function>
|
|
to synchronize against reception of all notifications sent before
|
|
this call is made.</para>
|
|
|
|
<programlisting>sd_notify(0, "READY=1");
|
|
/* set timeout to 5 seconds */
|
|
sd_notify_barrier(0, 5 * 1000000);
|
|
</programlisting>
|
|
</example>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
<para>
|
|
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|