| <?xml version='1.0'?> <!--*-nxml-*--> |
| <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
| "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> |
| |
| <!-- |
| This file is part of systemd. |
| |
| Copyright 2010 Lennart Poettering |
| |
| systemd is free software; you can redistribute it and/or modify it |
| under the terms of the GNU General Public License as published by |
| the Free Software Foundation; either version 2 of the License, or |
| (at your option) any later version. |
| |
| systemd is distributed in the hope that it will be useful, but |
| WITHOUT ANY WARRANTY; without even the implied warranty of |
| MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| General Public License for more details. |
| |
| You should have received a copy of the GNU General Public License |
| along with systemd; If not, see <http://www.gnu.org/licenses/>. |
| --> |
| |
| <refentry id="systemd-notify"> |
| |
| <refentryinfo> |
| <title>systemd-notify</title> |
| <productname>systemd</productname> |
| |
| <authorgroup> |
| <author> |
| <contrib>Developer</contrib> |
| <firstname>Lennart</firstname> |
| <surname>Poettering</surname> |
| <email>lennart@poettering.net</email> |
| </author> |
| </authorgroup> |
| </refentryinfo> |
| |
| <refmeta> |
| <refentrytitle>systemd-notify</refentrytitle> |
| <manvolnum>1</manvolnum> |
| </refmeta> |
| |
| <refnamediv> |
| <refname>systemd-notify</refname> |
| <refpurpose>Notify init system about start-up completion and other daemon status changes</refpurpose> |
| </refnamediv> |
| |
| <refsynopsisdiv> |
| <cmdsynopsis> |
| <command>systemd-notify <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt" rep="repeat">VARIABLE=VALUE</arg></command> |
| </cmdsynopsis> |
| </refsynopsisdiv> |
| |
| <refsect1> |
| <title>Description</title> |
| |
| <para><command>systemd-notify</command> may be |
| called by daemon scripts to notify the init system |
| about status changes. It can be used to send arbitrary |
| information, encoded in an environment-block-like list |
| of strings. Most importantly it can be used for |
| start-up completion notification.</para> |
| |
| <para>This is mostly just a wrapper around |
| <function>sd_notify()</function> and makes this |
| functionality available to shell scripts. For details |
| see |
| <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> |
| |
| <para>The command line may carry a list of |
| environment variables to send as part of the status |
| update.</para> |
| |
| <para>Note that systemd will refuse reception of |
| status updates from this command unless |
| <varname>NotifyAccess=all</varname> is set for the |
| service unit this command is called from.</para> |
| |
| </refsect1> |
| |
| <refsect1> |
| <title>Options</title> |
| |
| <para>The following options are understood:</para> |
| |
| <variablelist> |
| <varlistentry> |
| <term><option>--h</option></term> |
| <term><option>--help</option></term> |
| |
| <listitem><para>Prints a short help |
| text and exits.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--ready</option></term> |
| |
| <listitem><para>Inform the init system |
| about service start-up |
| completion. This is equivalent to |
| <command>systemd-notify |
| READY=1</command>. For details about |
| the semantics of this option see |
| <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--pid=</option></term> |
| |
| <listitem><para>Inform the init system |
| about the main PID of the |
| daemon. Takes a PID as argument. If |
| the argument is omitted the PID of the |
| process that invoked |
| <command>systemd-notify</command> is |
| used. This is equivalent to |
| <command>systemd-notify |
| MAINPID=$PID</command>. For details |
| about the semantics of this option see |
| <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--status=</option></term> |
| |
| <listitem><para>Send a free-form |
| status string for the daemon to the |
| init systemd. This option takes the |
| status string as argument. This is |
| equivalent to <command>systemd-notify |
| STATUS=...</command>. For details |
| about the semantics of this option see |
| <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--booted</option></term> |
| |
| <listitem><para>Returns 0 if the |
| system was booted up with systemd, |
| non-zero otherwise. If this option is |
| passed no message is sent. This option |
| is hence unrelated to the other |
| options. For details about the |
| semantics of this option see |
| <citerefentry><refentrytitle>sd_booted</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--readahead=</option></term> |
| |
| <listitem><para>Controls disk |
| read-ahead operations. The argument |
| must be a string, and either "cancel", |
| "done" or "noreplay". For details |
| about the semantics of this option see |
| <citerefentry><refentrytitle>sd_readahead</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> |
| </varlistentry> |
| </variablelist> |
| |
| </refsect1> |
| |
| <refsect1> |
| <title>Exit status</title> |
| |
| <para>On success 0 is returned, a non-zero failure |
| code otherwise.</para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Example</title> |
| |
| <example> |
| <title>Start-up Notification and Status Updates</title> |
| |
| <para>A simple shell daemon that sends |
| start-up notifications after having set up its |
| communication channel. During runtime it sends |
| further status updates to the init |
| system:</para> |
| |
| <programlisting>#!/bin/bash |
| |
| mkfifo /tmp/waldo |
| systemd-notify --ready --status="Waiting for data..." |
| |
| while : ; do |
| read a < /tmp/waldo |
| systemd-notify --status="Processing $a" |
| |
| # Do something with $a ... |
| |
| systemd-notify --status="Waiting for data..." |
| done</programlisting> |
| </example> |
| </refsect1> |
| |
| <refsect1> |
| <title>See Also</title> |
| <para> |
| <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>sd_booted</refentrytitle><manvolnum>3</manvolnum></citerefentry> |
| </para> |
| </refsect1> |
| |
| </refentry> |