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