man/systemd-notify.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="systemd-notify"
   7     xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>systemd-notify</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>systemd-notify</refentrytitle>
  16     <manvolnum>1</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>systemd-notify</refname>
  21     <refpurpose>Notify service manager about start-up completion and other daemon status changes</refpurpose>
  22   </refnamediv>
  23
  24   <refsynopsisdiv>
  25     <cmdsynopsis>
  26       <command>systemd-notify <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt" rep="repeat">VARIABLE=VALUE</arg></command>
  27     </cmdsynopsis>
  28   </refsynopsisdiv>
  29
  30   <refsect1>
  31     <title>Description</title>
  32
  33     <para><command>systemd-notify</command> may be called by service scripts to notify the invoking service
  34     manager about status changes. It can be used to send arbitrary information, encoded in an
  35     environment-block-like list of strings. Most importantly, it can be used for start-up completion
  36     notification.</para>
  37
  38     <para>This is mostly just a wrapper around <function>sd_notify()</function> and makes this functionality
  39     available to shell scripts. For details see
  40     <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
  41     </para>
  42
  43     <para>The command line may carry a list of environment variables to send as part of the status
  44     update.</para>
  45
  46     <para>Note that systemd will refuse reception of status updates from this command unless
  47     <varname>NotifyAccess=</varname> is appropriately set for the service unit this command is called
  48     from. See
  49     <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
  50     details.</para>
  51
  52     <para>Note that <function>sd_notify()</function> notifications may be attributed to units correctly only
  53     if either the sending process is still around at the time the service manager processes the message, or
  54     if the sending process is explicitly runtime-tracked by the service manager. The latter is the case if
  55     the service manager originally forked off the process, i.e. on all processes that match
  56     <varname>NotifyAccess=</varname><option>main</option> or
  57     <varname>NotifyAccess=</varname><option>exec</option>. Conversely, if an auxiliary process of the unit
  58     sends an <function>sd_notify()</function> message and immediately exits, the service manager might not be
  59     able to properly attribute the message to the unit, and thus will ignore it, even if
  60     <varname>NotifyAccess=</varname><option>all</option> is set for it. To address this
  61     <command>systemd-notify</command> will wait until the notification message has been processed by the
  62     service manager. When <option>--no-block</option> is used, this synchronization for reception of
  63     notifications is disabled, and hence the aforementioned race may occur if the invoking process is not the
  64     service manager or spawned by the service manager.</para>
  65
  66     <para><command>systemd-notify</command> will first attempt to invoke <function>sd_notify()</function>
  67     pretending to have the PID of the parent process of <command>systemd-notify</command> (i.e. the invoking
  68     process). This will only succeed when invoked with sufficient privileges.  On failure, it will then fall
  69     back to invoking it under its own PID. This behaviour is useful in order that when the tool is invoked
  70     from a shell script the shell process — and not the <command>systemd-notify</command> process — appears
  71     as sender of the message, which in turn is helpful if the shell process is the main process of a service,
  72     due to the limitations of <varname>NotifyAccess=</varname><option>all</option>. Use the
  73     <option>--pid=</option> switch to tweak this behaviour.</para>
  74   </refsect1>
  75
  76   <refsect1>
  77     <title>Options</title>
  78
  79     <para>The following options are understood:</para>
  80
  81     <variablelist>
  82       <varlistentry>
  83         <term><option>--ready</option></term>
  84
  85         <listitem><para>Inform the invoking service manager about service start-up or configuration reload
  86         completion. This is equivalent to <command>systemd-notify READY=1</command>. For details about the
  87         semantics of this option see
  88         <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
  89       </varlistentry>
  90
  91       <varlistentry>
  92         <term><option>--reloading</option></term>
  93
  94         <listitem><para>Inform the invoking service manager about the beginning of a configuration reload
  95         cycle. This is equivalent to <command>systemd-notify RELOADING=1</command> (but implicitly also sets
  96         a <varname>MONOTONIC_USEC=</varname> field as required for <varname>Type=notify-reload</varname>
  97         services, see
  98         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  99         for details). For details about the semantics of this option see
 100         <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
 101       </varlistentry>
 102
 103       <varlistentry>
 104         <term><option>--stopping</option></term>
 105
 106         <listitem><para>Inform the invoking service manager about the beginning of the shutdown phase of the
 107         service. This is equivalent to <command>systemd-notify STOPPING=1</command>. For details about the
 108         semantics of this option see
 109         <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
 110       </varlistentry>
 111
 112       <varlistentry>
 113         <term><option>--pid=</option></term>
 114
 115         <listitem><para>Inform the service manager about the main PID of the service. Takes a PID as
 116         argument. If the argument is specified as <literal>auto</literal> or omitted, the PID of the process
 117         that invoked <command>systemd-notify</command> is used, except if that's the service manager. If the
 118         argument is specified as <literal>self</literal>, the PID of the <command>systemd-notify</command>
 119         command itself is used, and if <literal>parent</literal> is specified the calling process' PID is
 120         used — even if it is the service manager. The latter is equivalent to <command>systemd-notify
 121         MAINPID=$PID</command>. For details about the semantics of this option see
 122         <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 123
 124         <para>If this switch is used in an <command>systemd-notify</command> invocation from a process that
 125         shall become the new main process of a service — and which is not the process forked off by the
 126         service manager (or the current main process) —, then it is essential to set
 127         <varname>NotifyAccess=all</varname> in the service unit file, or otherwise the notification will be
 128         ignored for security reasons. See
 129         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 130         for details.</para></listitem>
 131       </varlistentry>
 132
 133       <varlistentry>
 134         <term><option>--uid=</option><replaceable>USER</replaceable></term>
 135
 136         <listitem><para>Set the user ID to send the notification from. Takes a UNIX user name or numeric UID. When
 137         specified the notification message will be sent with the specified UID as sender, in place of the user the
 138         command was invoked as. This option requires sufficient privileges in order to be able manipulate the user
 139         identity of the process.</para></listitem>
 140       </varlistentry>
 141
 142       <varlistentry>
 143         <term><option>--status=</option></term>
 144
 145         <listitem><para>Send a free-form human readable status string for the daemon to the service
 146         manager. This option takes the status string as argument. This is equivalent to
 147         <command>systemd-notify STATUS=…</command>. For details about the semantics of this option see
 148         <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This
 149         information is shown in
 150         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
 151         <command>status</command> output, among other places.</para></listitem>
 152       </varlistentry>
 153
 154       <varlistentry>
 155         <term><option>--booted</option></term>
 156
 157         <listitem><para>Returns 0 if the system was booted up with systemd, non-zero otherwise. If this
 158         option is passed, no message is sent. This option is hence unrelated to the other options. For
 159         details about the semantics of this option, see
 160         <citerefentry><refentrytitle>sd_booted</refentrytitle><manvolnum>3</manvolnum></citerefentry>. An
 161         alternate way to check for this state is to call
 162         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> with
 163         the <command>is-system-running</command> command. It will return <literal>offline</literal> if the
 164         system was not booted with systemd.  </para></listitem>
 165       </varlistentry>
 166
 167       <varlistentry>
 168         <term><option>--no-block</option></term>
 169
 170         <listitem><para>Do not synchronously wait for the requested operation to finish.  Use of this option
 171         is only recommended when <command>systemd-notify</command> is spawned by the service manager, or when
 172         the invoking process is directly spawned by the service manager and has enough privileges to allow
 173         <command>systemd-notify</command> to send the notification on its behalf. Sending notifications with
 174         this option set is prone to race conditions in all other cases.</para></listitem>
 175       </varlistentry>
 176
 177       <xi:include href="standard-options.xml" xpointer="help" />
 178       <xi:include href="standard-options.xml" xpointer="version" />
 179     </variablelist>
 180
 181   </refsect1>
 182
 183   <refsect1>
 184     <title>Exit status</title>
 185
 186     <para>On success, 0 is returned, a non-zero failure code
 187     otherwise.</para>
 188   </refsect1>
 189
 190   <refsect1>
 191     <title>Example</title>
 192
 193     <example>
 194       <title>Start-up Notification and Status Updates</title>
 195
 196       <para>A simple shell daemon that sends start-up notifications after having set up its communication
 197       channel. During runtime it sends further status updates to the init system:</para>
 198
 199       <programlisting>#!/bin/sh
 200
 201 mkfifo /tmp/waldo
 202 systemd-notify --ready --status="Waiting for data…"
 203
 204 while : ; do
 205         read -r a &lt; /tmp/waldo
 206         systemd-notify --status="Processing $a"
 207
 208         # Do something with $a …
 209
 210         systemd-notify --status="Waiting for data…"
 211 done</programlisting>
 212     </example>
 213   </refsect1>
 214
 215   <refsect1>
 216     <title>See Also</title>
 217     <para>
 218       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 219       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 220       <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 221       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 222       <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 223       <citerefentry><refentrytitle>sd_booted</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 224     </para>
 225   </refsect1>
 226 </refentry>