man/systemd-notify.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   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   This file is part of systemd.
   7
   8   Copyright 2010 Lennart Poettering
   9
  10   systemd is free software; you can redistribute it and/or modify it
  11   under the terms of the GNU Lesser General Public License as published by
  12   the Free Software Foundation; either version 2.1 of the License, or
  13   (at your option) any later version.
  14
  15   systemd is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   Lesser General Public License for more details.
  19
  20   You should have received a copy of the GNU Lesser General Public License
  21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="systemd-notify"
  25     xmlns:xi="http://www.w3.org/2001/XInclude">
  26
  27   <refentryinfo>
  28     <title>systemd-notify</title>
  29     <productname>systemd</productname>
  30
  31     <authorgroup>
  32       <author>
  33         <contrib>Developer</contrib>
  34         <firstname>Lennart</firstname>
  35         <surname>Poettering</surname>
  36         <email>lennart@poettering.net</email>
  37       </author>
  38     </authorgroup>
  39   </refentryinfo>
  40
  41   <refmeta>
  42     <refentrytitle>systemd-notify</refentrytitle>
  43     <manvolnum>1</manvolnum>
  44   </refmeta>
  45
  46   <refnamediv>
  47     <refname>systemd-notify</refname>
  48     <refpurpose>Notify service manager about start-up completion and other daemon status changes</refpurpose>
  49   </refnamediv>
  50
  51   <refsynopsisdiv>
  52     <cmdsynopsis>
  53       <command>systemd-notify <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt" rep="repeat">VARIABLE=VALUE</arg></command>
  54     </cmdsynopsis>
  55   </refsynopsisdiv>
  56
  57   <refsect1>
  58     <title>Description</title>
  59
  60     <para><command>systemd-notify</command> may be called by daemon
  61     scripts to notify the init system about status changes. It can be
  62     used to send arbitrary information, encoded in an
  63     environment-block-like list of strings. Most importantly, it can be
  64     used for start-up completion notification.</para>
  65
  66     <para>This is mostly just a wrapper around
  67     <function>sd_notify()</function> and makes this functionality
  68     available to shell scripts. For details see
  69     <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
  70     </para>
  71
  72     <para>The command line may carry a list of environment variables
  73     to send as part of the status update.</para>
  74
  75     <para>Note that systemd will refuse reception of status updates from this command unless
  76     <varname>NotifyAccess=</varname> is set for the service unit this command is called from.</para>
  77
  78     <para>Note that <function>sd_notify()</function> notifications may be attributed to units correctly only if either
  79     the sending process is still around at the time PID 1 processes the message, or if the sending process is
  80     explicitly runtime-tracked by the service manager. The latter is the case if the service manager originally forked
  81     off the process, i.e. on all processes that match <varname>NotifyAccess=</varname><option>main</option> or
  82     <varname>NotifyAccess=</varname><option>exec</option>. Conversely, if an auxiliary process of the unit sends an
  83     <function>sd_notify()</function> message and immediately exits, the service manager might not be able to properly
  84     attribute the message to the unit, and thus will ignore it, even if
  85     <varname>NotifyAccess=</varname><option>all</option> is set for it.</para>
  86   </refsect1>
  87
  88   <refsect1>
  89     <title>Options</title>
  90
  91     <para>The following options are understood:</para>
  92
  93     <variablelist>
  94       <varlistentry>
  95         <term><option>--ready</option></term>
  96
  97         <listitem><para>Inform the init system about service start-up
  98         completion. This is equivalent to <command>systemd-notify
  99         READY=1</command>. For details about the semantics of this
 100         option see
 101         <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
 102       </varlistentry>
 103
 104       <varlistentry>
 105         <term><option>--pid=</option></term>
 106
 107         <listitem><para>Inform the init system about the main PID of
 108         the daemon. Takes a PID as argument. If the argument is
 109         omitted, the PID of the process that invoked
 110         <command>systemd-notify</command> is used. This is equivalent
 111         to <command>systemd-notify MAINPID=$PID</command>. For details
 112         about the semantics of this option see
 113         <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
 114       </varlistentry>
 115
 116       <varlistentry>
 117         <term><option>--status=</option></term>
 118
 119         <listitem><para>Send a free-form status string for the daemon
 120         to the init systemd. This option takes the status string as
 121         argument. This is equivalent to <command>systemd-notify
 122         STATUS=…</command>. For details about the semantics of this
 123         option see
 124         <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
 125       </varlistentry>
 126
 127       <varlistentry>
 128         <term><option>--booted</option></term>
 129
 130         <listitem><para>Returns 0 if the system was booted up with
 131         systemd, non-zero otherwise. If this option is passed, no
 132         message is sent. This option is hence unrelated to the other
 133         options. For details about the semantics of this option, see
 134         <citerefentry><refentrytitle>sd_booted</refentrytitle><manvolnum>3</manvolnum></citerefentry>. An
 135         alternate way to check for this state is to call
 136         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 137         with the <command>is-system-running</command> command. It will
 138         return <literal>offline</literal> if the system was not booted
 139         with systemd.  </para></listitem>
 140       </varlistentry>
 141
 142       <xi:include href="standard-options.xml" xpointer="help" />
 143       <xi:include href="standard-options.xml" xpointer="version" />
 144     </variablelist>
 145
 146   </refsect1>
 147
 148   <refsect1>
 149     <title>Exit status</title>
 150
 151     <para>On success, 0 is returned, a non-zero failure code
 152     otherwise.</para>
 153   </refsect1>
 154
 155   <refsect1>
 156     <title>Example</title>
 157
 158     <example>
 159       <title>Start-up Notification and Status Updates</title>
 160
 161       <para>A simple shell daemon that sends start-up notifications
 162       after having set up its communication channel. During runtime it
 163       sends further status updates to the init system:</para>
 164
 165       <programlisting>#!/bin/bash
 166
 167 mkfifo /tmp/waldo
 168 systemd-notify --ready --status="Waiting for data…"
 169
 170 while : ; do
 171         read a &lt; /tmp/waldo
 172         systemd-notify --status="Processing $a"
 173
 174         # Do something with $a …
 175
 176         systemd-notify --status="Waiting for data…"
 177 done</programlisting>
 178     </example>
 179   </refsect1>
 180
 181   <refsect1>
 182     <title>See Also</title>
 183     <para>
 184       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 185       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 186       <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 187       <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 188       <citerefentry><refentrytitle>sd_booted</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 189     </para>
 190   </refsect1>
 191
 192 </refentry>