c5abba08873903d80a2dcdd46aace959fcae1b0fLennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
c5abba08873903d80a2dcdd46aace959fcae1b0fLennart Poettering This file is part of systemd.
c5abba08873903d80a2dcdd46aace959fcae1b0fLennart Poettering Copyright 2010 Lennart Poettering
c5abba08873903d80a2dcdd46aace959fcae1b0fLennart Poettering systemd is free software; you can redistribute it and/or modify it
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering under the terms of the GNU Lesser General Public License as published by
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering the Free Software Foundation; either version 2.1 of the License, or
c5abba08873903d80a2dcdd46aace959fcae1b0fLennart Poettering (at your option) any later version.
c5abba08873903d80a2dcdd46aace959fcae1b0fLennart Poettering systemd is distributed in the hope that it will be useful, but
c5abba08873903d80a2dcdd46aace959fcae1b0fLennart Poettering WITHOUT ANY WARRANTY; without even the implied warranty of
c5abba08873903d80a2dcdd46aace959fcae1b0fLennart Poettering MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering Lesser General Public License for more details.
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering You should have received a copy of the GNU Lesser General Public License
c5abba08873903d80a2dcdd46aace959fcae1b0fLennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek xmlns:xi="http://www.w3.org/2001/XInclude">
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <productname>systemd</productname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <email>lennart@poettering.net</email>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refentrytitle>systemd-notify</refentrytitle>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refname>systemd-notify</refname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refpurpose>Notify service manager about start-up completion and other daemon status changes</refpurpose>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refsynopsisdiv>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <command>systemd-notify <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt" rep="repeat">VARIABLE=VALUE</arg></command>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </refsynopsisdiv>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para><command>systemd-notify</command> may be called by daemon
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek scripts to notify the init system about status changes. It can be
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek used to send arbitrary information, encoded in an
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt environment-block-like list of strings. Most importantly, it can be
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek used for start-up completion notification.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>This is mostly just a wrapper around
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <function>sd_notify()</function> and makes this functionality
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek available to shell scripts. For details see
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>The command line may carry a list of environment variables
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek to send as part of the status update.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Note that systemd will refuse reception of status updates
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek from this command unless <varname>NotifyAccess=all</varname> is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek set for the service unit this command is called from.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>The following options are understood:</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--ready</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Inform the init system about service start-up
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek completion. This is equivalent to <command>systemd-notify
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek READY=1</command>. For details about the semantics of this
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--pid=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Inform the init system about the main PID of
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the daemon. Takes a PID as argument. If the argument is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek omitted, the PID of the process that invoked
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <command>systemd-notify</command> is used. This is equivalent
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek to <command>systemd-notify MAINPID=$PID</command>. For details
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek about the semantics of this option see
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--status=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Send a free-form status string for the daemon
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek to the init systemd. This option takes the status string as
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek argument. This is equivalent to <command>systemd-notify
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek STATUS=...</command>. For details about the semantics of this
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--booted</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Returns 0 if the system was booted up with
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek systemd, non-zero otherwise. If this option is passed, no
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek message is sent. This option is hence unrelated to the other
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek options. For details about the semantics of this option, see
94f099d8132da7987a5dbe930dadf31aaded9a11Lennart Poettering <citerefentry><refentrytitle>sd_booted</refentrytitle><manvolnum>3</manvolnum></citerefentry>. An
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt alternate way to check for this state is to call
94f099d8132da7987a5dbe930dadf31aaded9a11Lennart Poettering <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
94f099d8132da7987a5dbe930dadf31aaded9a11Lennart Poettering with the <command>is-system-running</command> command. It will
94f099d8132da7987a5dbe930dadf31aaded9a11Lennart Poettering return <literal>offline</literal> if the system was not booted
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <xi:include href="standard-options.xml" xpointer="help" />
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <xi:include href="standard-options.xml" xpointer="version" />
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>On success, 0 is returned, a non-zero failure code
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek otherwise.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <title>Start-up Notification and Status Updates</title>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>A simple shell daemon that sends start-up notifications
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek after having set up its communication channel. During runtime it
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek sends further status updates to the init system:</para>
c61fbdfcb9bcd405c5a0a9b5f7050a58a871db6eLennart Poetteringsystemd-notify --ready --status="Waiting for data..."
0521e286fc34d1ab58edc1a3fab7b8285c4b36e5Lennart Poettering systemd-notify --status="Processing $a"
0521e286fc34d1ab58edc1a3fab7b8285c4b36e5Lennart Poettering # Do something with $a ...
0521e286fc34d1ab58edc1a3fab7b8285c4b36e5Lennart Poettering systemd-notify --status="Waiting for data..."
c61fbdfcb9bcd405c5a0a9b5f7050a58a871db6eLennart Poetteringdone</programlisting>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_booted</refentrytitle><manvolnum>3</manvolnum></citerefentry>