man/sd_notify.xml

   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">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7 -->
   8
   9 <refentry id="sd_notify"
  10   xmlns:xi="http://www.w3.org/2001/XInclude">
  11
  12   <refentryinfo>
  13     <title>sd_notify</title>
  14     <productname>elogind</productname>
  15   </refentryinfo>
  16
  17   <refmeta>
  18     <refentrytitle>sd_notify</refentrytitle>
  19     <manvolnum>3</manvolnum>
  20   </refmeta>
  21
  22   <refnamediv>
  23     <refname>sd_notify</refname>
  24     <refname>sd_notifyf</refname>
  25     <refname>sd_pid_notify</refname>
  26     <refname>sd_pid_notifyf</refname>
  27     <refname>sd_pid_notify_with_fds</refname>
  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 &lt;elogind/sd-daemon.h&gt;</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>
  45         <paramdef>…</paramdef>
  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>
  60         <paramdef>…</paramdef>
  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>
  71     </funcsynopsis>
  72   </refsynopsisdiv>
  73
  74   <refsect1>
  75     <title>Description</title>
  76     <para><function>sd_notify()</function> may be called by a service
  77     to notify the service manager about state changes. It can be used
  78     to send arbitrary information, encoded in an
  79     environment-block-like string. Most importantly, it can be used for
  80     start-up completion notification.</para>
  81
  82     <para>If the <parameter>unset_environment</parameter> parameter is
  83     non-zero, <function>sd_notify()</function> will unset the
  84     <varname>$NOTIFY_SOCKET</varname> environment variable before
  85     returning (regardless of whether the function call itself
  86     succeeded or not). Further calls to
  87     <function>sd_notify()</function> will then fail, but the variable
  88     is no longer inherited by child processes.</para>
  89
  90     <para>The <parameter>state</parameter> parameter should contain a
  91     newline-separated list of variable assignments, similar in style
  92     to an environment block. A trailing newline is implied if none is
  93     specified. The string may contain any kind of variable
  94     assignments, but the following shall be considered
  95     well-known:</para>
  96
  97     <variablelist>
  98       <varlistentry>
  99         <term>READY=1</term>
 100
 101         <listitem><para>Tells the service manager that service startup is finished, or the service finished loading its
 102         configuration. This is only used by elogind if the service definition file has <varname>Type=notify</varname>
 103         set. Since there is little value in signaling non-readiness, the only value services should send is
 104         <literal>READY=1</literal> (i.e.  <literal>READY=0</literal> is not defined).</para></listitem>
 105       </varlistentry>
 106
 107       <varlistentry>
 108         <term>RELOADING=1</term>
 109
 110         <listitem><para>Tells the service manager that the service is
 111         reloading its configuration. This is useful to allow the
 112         service manager to track the service's internal state, and
 113         present it to the user. Note that a service that sends this
 114         notification must also send a <literal>READY=1</literal>
 115         notification when it completed reloading its
 116         configuration. Reloads are propagated in the same way as they
 117         are when initiated by the user.</para></listitem>
 118       </varlistentry>
 119
 120       <varlistentry>
 121         <term>STOPPING=1</term>
 122
 123         <listitem><para>Tells the service manager that the service is
 124         beginning its shutdown. This is useful to allow the service
 125         manager to track the service's internal state, and present it
 126         to the user.</para></listitem>
 127       </varlistentry>
 128
 129       <varlistentry>
 130         <term>STATUS=…</term>
 131
 132         <listitem><para>Passes a single-line UTF-8 status string back
 133         to the service manager that describes the service state. This
 134         is free-form and can be used for various purposes: general
 135         state feedback, fsck-like programs could pass completion
 136         percentages and failing programs could pass a human-readable
 137         error message. Example: <literal>STATUS=Completed 66% of file
 138         system check…</literal></para></listitem>
 139       </varlistentry>
 140
 141       <varlistentry>
 142         <term>ERRNO=…</term>
 143
 144         <listitem><para>If a service fails, the errno-style error
 145         code, formatted as string. Example: <literal>ERRNO=2</literal>
 146         for ENOENT.</para></listitem>
 147       </varlistentry>
 148
 149       <varlistentry>
 150         <term>BUSERROR=…</term>
 151
 152         <listitem><para>If a service fails, the D-Bus error-style
 153         error code. Example:
 154         <literal>BUSERROR=org.freedesktop.DBus.Error.TimedOut</literal></para></listitem>
 155       </varlistentry>
 156
 157       <varlistentry>
 158         <term>MAINPID=…</term>
 159
 160         <listitem><para>The main process ID (PID) of the service, in
 161         case the service manager did not fork off the process itself.
 162         Example: <literal>MAINPID=4711</literal></para></listitem>
 163       </varlistentry>
 164
 165       <varlistentry>
 166         <term>WATCHDOG=1</term>
 167
 168         <listitem><para>Tells the service manager to update the
 169         watchdog timestamp. This is the keep-alive ping that services
 170         need to issue in regular intervals if
 171         <varname>WatchdogSec=</varname> is enabled for it. See
 172         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 173         for information how to enable this functionality and
 174         <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 175         for the details of how the service can check whether the
 176         watchdog is enabled. </para></listitem>
 177       </varlistentry>
 178
 179       <varlistentry>
 180         <term>WATCHDOG_USEC=…</term>
 181
 182         <listitem><para>Reset <varname>watchdog_usec</varname> value during runtime.
 183         Notice that this is not available when using <function>sd_event_set_watchdog()</function>
 184         or <function>sd_watchdog_enabled()</function>.
 185         Example : <literal>WATCHDOG_USEC=20000000</literal></para></listitem>
 186       </varlistentry>
 187
 188       <varlistentry>
 189         <term>EXTEND_TIMEOUT_USEC=…</term>
 190
 191         <listitem><para>Tells the service manager to extend the startup, runtime or shutdown service timeout
 192         corresponding the current state. The value specified is a time in microseconds during which the service must
 193         send a new message. A service timeout will occur if the message isn't received, but only if the runtime of the
 194         current state is beyond the original maximium times of <varname>TimeoutStartSec=</varname>, <varname>RuntimeMaxSec=</varname>,
 195         and <varname>TimeoutStopSec=</varname>.
 196         See <citerefentry><refentrytitle>elogind.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 197         for effects on the service timeouts.</para></listitem>
 198       </varlistentry>
 199
 200       <varlistentry>
 201         <term>FDSTORE=1</term>
 202
 203         <listitem><para>Stores additional file descriptors in the service manager. File descriptors sent this way will
 204         be maintained per-service by the service manager and will later be handed back using the usual file descriptor
 205         passing logic at the next invocation of the service, see
 206         <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>.  This is
 207         useful for implementing services that can restart after an explicit request or a crash without losing
 208         state. Any open sockets and other file descriptors which should not be closed during the restart may be stored
 209         this way. Application state can either be serialized to a file in <filename>/run</filename>, or better, stored
 210         in a <citerefentry><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry> memory
 211         file descriptor. Note that the service manager will accept messages for a service only if its
 212         <varname>FileDescriptorStoreMax=</varname> setting is non-zero (defaults to zero, see
 213         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>). If file
 214         descriptors sent are pollable (see
 215         <citerefentry><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>), then any
 216         <constant>EPOLLHUP</constant> or <constant>EPOLLERR</constant> event seen on them will result in their
 217         automatic removal from the store. Multiple arrays of file descriptors may be sent in separate messages, in
 218         which case the arrays are combined. Note that the service manager removes duplicate (pointing to the same
 219         object) file descriptors before passing them to the service. Use <function>sd_pid_notify_with_fds()</function>
 220         to send messages with <literal>FDSTORE=1</literal>, see below.</para></listitem>
 221       </varlistentry>
 222
 223       <varlistentry>
 224         <term>FDSTOREREMOVE=1</term>
 225
 226         <listitem><para>Removes file descriptors from the file descriptor store. This field needs to be combined with
 227         <varname>FDNAME=</varname> to specify the name of the file descriptors to remove.</para></listitem>
 228       </varlistentry>
 229
 230       <varlistentry>
 231         <term>FDNAME=…</term>
 232
 233         <listitem><para>When used in combination with <varname>FDSTORE=1</varname>, specifies a name for the submitted
 234         file descriptors. When used with <varname>FDSTOREREMOVE=1</varname>, specifies the name for the file
 235         descriptors to remove. This name is passed to the service during activation, and may be queried using
 236         <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>. File
 237         descriptors submitted without this field set, will implicitly get the name <literal>stored</literal>
 238         assigned. Note that, if multiple file descriptors are submitted at once, the specified name will be assigned to
 239         all of them. In order to assign different names to submitted file descriptors, submit them in separate
 240         invocations of <function>sd_pid_notify_with_fds()</function>. The name may consist of arbitrary ASCII
 241         characters except control characters or <literal>:</literal>. It may not be longer than 255 characters. If a
 242         submitted name does not follow these restrictions, it is ignored.</para></listitem>
 243       </varlistentry>
 244
 245     </variablelist>
 246
 247     <para>It is recommended to prefix variable names that are not
 248     listed above with <varname>X_</varname> to avoid namespace
 249     clashes.</para>
 250
 251     <para>Note that elogind will accept status data sent from a
 252     service only if the <varname>NotifyAccess=</varname> option is
 253     correctly set in the service definition file. See
 254     <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 255     for details.</para>
 256
 257     <para>Note that <function>sd_notify()</function> notifications may be attributed to units correctly only if either
 258     the sending process is still around at the time PID 1 processes the message, or if the sending process is
 259     explicitly runtime-tracked by the service manager. The latter is the case if the service manager originally forked
 260     off the process, i.e. on all processes that match <varname>NotifyAccess=</varname><option>main</option> or
 261     <varname>NotifyAccess=</varname><option>exec</option>. Conversely, if an auxiliary process of the unit sends an
 262     <function>sd_notify()</function> message and immediately exits, the service manager might not be able to properly
 263     attribute the message to the unit, and thus will ignore it, even if
 264     <varname>NotifyAccess=</varname><option>all</option> is set for it.</para>
 265
 266     <para><function>sd_notifyf()</function> is similar to
 267     <function>sd_notify()</function> but takes a
 268     <function>printf()</function>-like format string plus
 269     arguments.</para>
 270
 271     <para><function>sd_pid_notify()</function> and
 272     <function>sd_pid_notifyf()</function> are similar to
 273     <function>sd_notify()</function> and
 274     <function>sd_notifyf()</function> but take a process ID (PID) to
 275     use as originating PID for the message as first argument. This is
 276     useful to send notification messages on behalf of other processes,
 277     provided the appropriate privileges are available. If the PID
 278     argument is specified as 0, the process ID of the calling process
 279     is used, in which case the calls are fully equivalent to
 280     <function>sd_notify()</function> and
 281     <function>sd_notifyf()</function>.</para>
 282
 283     <para><function>sd_pid_notify_with_fds()</function> is similar to
 284     <function>sd_pid_notify()</function> but takes an additional array
 285     of file descriptors. These file descriptors are sent along the
 286     notification message to the service manager. This is particularly
 287     useful for sending <literal>FDSTORE=1</literal> messages, as
 288     described above. The additional arguments are a pointer to the
 289     file descriptor array plus the number of file descriptors in the
 290     array. If the number of file descriptors is passed as 0, the call
 291     is fully equivalent to <function>sd_pid_notify()</function>, i.e.
 292     no file descriptors are passed. Note that sending file descriptors
 293     to the service manager on messages that do not expect them (i.e.
 294     without <literal>FDSTORE=1</literal>) they are immediately closed
 295     on reception.</para>
 296   </refsect1>
 297
 298   <refsect1>
 299     <title>Return Value</title>
 300
 301     <para>On failure, these calls return a negative errno-style error code. If <varname>$NOTIFY_SOCKET</varname> was
 302     not set and hence no status message could be sent, 0 is returned. If the status was sent, these functions return a
 303     positive value. In order to support both service managers that implement this scheme and those which do not, it is
 304     generally recommended to ignore the return value of this call. Note that the return value simply indicates whether
 305     the notification message was enqueued properly, it does not reflect whether the message could be processed
 306     successfully. Specifically, no error is returned when a file descriptor is attempted to be stored using
 307     <varname>FDSTORE=1</varname> but the service is not actually configured to permit storing of file descriptors (see
 308     above).</para>
 309   </refsect1>
 310
 311   <refsect1>
 312     <title>Notes</title>
 313
 314     <xi:include href="libelogind-pkgconfig.xml" xpointer="pkgconfig-text"/>
 315
 316     <para>These functions send a single datagram with the
 317     state string as payload to the <constant>AF_UNIX</constant> socket
 318     referenced in the <varname>$NOTIFY_SOCKET</varname> environment
 319     variable. If the first character of
 320     <varname>$NOTIFY_SOCKET</varname> is <literal>@</literal>, the
 321     string is understood as Linux abstract namespace socket. The
 322     datagram is accompanied by the process credentials of the sending
 323     service, using SCM_CREDENTIALS.</para>
 324   </refsect1>
 325
 326   <refsect1>
 327     <title>Environment</title>
 328
 329     <variablelist class='environment-variables'>
 330       <varlistentry>
 331         <term><varname>$NOTIFY_SOCKET</varname></term>
 332
 333         <listitem><para>Set by the service manager for supervised
 334         processes for status and start-up completion notification.
 335         This environment variable specifies the socket
 336         <function>sd_notify()</function> talks to. See above for
 337         details.</para></listitem>
 338       </varlistentry>
 339     </variablelist>
 340   </refsect1>
 341
 342   <refsect1>
 343     <title>Examples</title>
 344
 345     <example>
 346       <title>Start-up Notification</title>
 347
 348       <para>When a service finished starting up, it might issue the
 349       following call to notify the service manager:</para>
 350
 351       <programlisting>sd_notify(0, "READY=1");</programlisting>
 352     </example>
 353
 354     <example>
 355       <title>Extended Start-up Notification</title>
 356
 357       <para>A service could send the following after completing
 358       initialization:</para>
 359
 360       <programlisting>sd_notifyf(0, "READY=1\n"
 361         "STATUS=Processing requests…\n"
 362         "MAINPID=%lu",
 363         (unsigned long) getpid());</programlisting>
 364     </example>
 365
 366     <example>
 367       <title>Error Cause Notification</title>
 368
 369       <para>A service could send the following shortly before exiting, on failure:</para>
 370
 371       <programlisting>sd_notifyf(0, "STATUS=Failed to start up: %s\n"
 372         "ERRNO=%i",
 373         strerror(errno),
 374         errno);</programlisting>
 375     </example>
 376
 377     <example>
 378       <title>Store a File Descriptor in the Service Manager</title>
 379
 380       <para>To store an open file descriptor in the service manager,
 381       in order to continue operation after a service restart without
 382       losing state, use <literal>FDSTORE=1</literal>:</para>
 383
 384       <programlisting>sd_pid_notify_with_fds(0, 0, "FDSTORE=1\nFDNAME=foobar", &amp;fd, 1);</programlisting>
 385     </example>
 386   </refsect1>
 387
 388   <refsect1>
 389     <title>See Also</title>
 390     <para>
 391       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 392       <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 393       <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 394       <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 395       <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 396       <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 397       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 398     </para>
 399   </refsect1>
 400
 401 </refentry>