sd_notify.xml revision 6a70f3aa63a3b7a6a30448c48322ad38b719cdce
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering This file is part of systemd.
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering Copyright 2010 Lennart Poettering
f9378423b9758861850748aeb49ae0d3300e56e6Lennart 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
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering (at your option) any later version.
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering systemd is distributed in the hope that it will be useful, but
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering WITHOUT ANY WARRANTY; without even the implied warranty of
f9378423b9758861850748aeb49ae0d3300e56e6Lennart 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
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
6a70f3aa63a3b7a6a30448c48322ad38b719cdceZbigniew Jędrzejewski-Szmek xmlns:xi="http://www.w3.org/2001/XInclude">
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <refentryinfo>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering </authorgroup>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering </refentryinfo>
34511ca7b166b0e89d08ff9870b0cf2624a7815fLennart Poettering <refpurpose>Notify service manager about start-up completion and other daemon status changes</refpurpose>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <refsynopsisdiv>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <funcsynopsis>
a822cbfa2e42d60c3cafe724a8571329ab6c632eLennart Poettering <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <funcprototype>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <funcdef>int <function>sd_notify</function></funcdef>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <paramdef>int <parameter>unset_environment</parameter></paramdef>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <paramdef>const char *<parameter>state</parameter></paramdef>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering </funcprototype>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <funcprototype>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <funcdef>int <function>sd_notifyf</function></funcdef>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <paramdef>int <parameter>unset_environment</parameter></paramdef>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <paramdef>const char *<parameter>format</parameter></paramdef>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering </funcprototype>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering </funcsynopsis>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering </refsynopsisdiv>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <para><function>sd_notify()</function> shall be called
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering by a daemon to notify the init system about status
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering changes. It can be used to send arbitrary information,
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering encoded in an environment-block-like string. Most
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering importantly it can be used for start-up completion
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering notification.</para>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <para>If the <parameter>unset_environment</parameter>
79640424059328268b9fb6c5fa8eb777b27a177eJan Engelhardt parameter is non-zero, <function>sd_notify()</function>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering will unset the <varname>$NOTIFY_SOCKET</varname>
494a66821815e8109afa136bd42818b85da38c09Jan Engelhardt environment variable before returning (regardless of
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering whether the function call itself succeeded or
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering not). Further calls to
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <function>sd_notify()</function> will then fail, but
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering the variable is no longer inherited by child
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering processes.</para>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <para>The <parameter>state</parameter> parameter
bb31a4ac1997c189a344caf554f34c6aabc71aa7Thomas Hindoe Paaboel Andersen should contain a newline-separated list of variable
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering assignments, similar in style to an environment
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering block. A trailing newline is implied if none is
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering specified. The string may contain any kind of variable
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering assignments, but the following shall be considered
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering well-known:</para>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <variablelist>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <varlistentry>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering that daemon startup is finished. This
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering is only used by systemd if the service
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering definition file has Type=notify
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering set. The passed argument is a boolean
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering "1" or "0". Since there is little
bb31a4ac1997c189a344caf554f34c6aabc71aa7Thomas Hindoe Paaboel Andersen value in signaling non-readiness, the
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering only value daemons should send is
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering </varlistentry>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <varlistentry>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering status string back to the init system
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering that describes the daemon state. This
af62c704053b5d34672497eb5bdc4764ebbb5f4fKay Sievers is free-form and can be used for
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering various purposes: general state
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering feedback, fsck-like programs could
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering pass completion percentages and
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering failing programs could pass a human
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering readable error message. Example:
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering "STATUS=Completed 66% of file system
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering </varlistentry>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <varlistentry>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering errno-style error code, formatted as
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering string. Example: "ERRNO=2" for
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering </varlistentry>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <varlistentry>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering D-Bus error-style error code. Example:
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering "BUSERROR=org.freedesktop.DBus.Error.TimedOut"</para></listitem>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering </varlistentry>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <varlistentry>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering daemon, in case the init system did
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering not fork off the process
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering itself. Example:
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering </varlistentry>
a6927d7ffc18c51fbb9940f5f1e89f5c7695ed63Michael Olbrich <varlistentry>
dac051ad6893dcf3e1a69d40eea02682220e71d4Lennart Poettering update the watchdog timestamp. This is
dac051ad6893dcf3e1a69d40eea02682220e71d4Lennart Poettering the keep-alive ping that services need
dac051ad6893dcf3e1a69d40eea02682220e71d4Lennart Poettering to issue in regular intervals if
dac051ad6893dcf3e1a69d40eea02682220e71d4Lennart Poettering enabled for it. See
dac051ad6893dcf3e1a69d40eea02682220e71d4Lennart Poettering <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
dac051ad6893dcf3e1a69d40eea02682220e71d4Lennart Poettering for details. It is recommended to send
dac051ad6893dcf3e1a69d40eea02682220e71d4Lennart Poettering this message if the
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering environment variable has been set to
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering the PID of the service process, in
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering every half the time interval that is
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering specified in the
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering environment variable. See
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
a6927d7ffc18c51fbb9940f5f1e89f5c7695ed63Michael Olbrich </varlistentry>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering </variablelist>
436c44a5d64ef136ead64e9b03c8c05cc573a61bKay Sievers <para>It is recommended to prefix variable names that
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering are not shown in the list above with
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering clashes.</para>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <para>Note that systemd will accept status data sent
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering from a daemon only if the
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <varname>NotifyAccess=</varname> option is correctly
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering set in the service definition file. See
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering for details.</para>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <para><function>sd_notifyf()</function> is similar to
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <function>printf()</function>-like format string plus
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering arguments.</para>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <para>On failure, these calls return a negative
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering errno-style error code. If
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <varname>$NOTIFY_SOCKET</varname> was not set and
af62c704053b5d34672497eb5bdc4764ebbb5f4fKay Sievers hence no status data could be sent, 0 is returned. If
79640424059328268b9fb6c5fa8eb777b27a177eJan Engelhardt the status was sent, these functions return with a
af62c704053b5d34672497eb5bdc4764ebbb5f4fKay Sievers positive return value. In order to support both, init
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering systems that implement this scheme and those which
6b4991cfde6c0a0b62e836ca75ae362779c474d4Jan Engelhardt do not, it is generally recommended to ignore the return
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering value of this call.</para>
6a70f3aa63a3b7a6a30448c48322ad38b719cdceZbigniew Jędrzejewski-Szmek <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <para>Internally, these functions send a single
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering datagram with the state string as payload to the
74d005783e355acc784d123024e33bbb66ef9ef1Zbigniew Jędrzejewski-Szmek <constant>AF_UNIX</constant> socket referenced in the
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <varname>$NOTIFY_SOCKET</varname> environment
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering variable. If the first character of
79640424059328268b9fb6c5fa8eb777b27a177eJan Engelhardt <varname>$NOTIFY_SOCKET</varname> is <literal>@</literal>, the string is
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering understood as Linux abstract namespace socket. The
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering datagram is accompanied by the process credentials of
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering the sending daemon, using SCM_CREDENTIALS.</para>
ccc9a4f9ffdab069b0b785627c48962fdadf6d46Zbigniew Jędrzejewski-Szmek <variablelist class='environment-variables'>
7874bcd6028d1efbb4451c8b5cf5b2ac8d77af74Lennart Poettering <varlistentry>
7874bcd6028d1efbb4451c8b5cf5b2ac8d77af74Lennart Poettering <term><varname>$NOTIFY_SOCKET</varname></term>
7874bcd6028d1efbb4451c8b5cf5b2ac8d77af74Lennart Poettering for supervised processes for status
7874bcd6028d1efbb4451c8b5cf5b2ac8d77af74Lennart Poettering and start-up completion
7874bcd6028d1efbb4451c8b5cf5b2ac8d77af74Lennart Poettering notification. This environment variable
7874bcd6028d1efbb4451c8b5cf5b2ac8d77af74Lennart Poettering specifies the socket
7874bcd6028d1efbb4451c8b5cf5b2ac8d77af74Lennart Poettering to. See above for details.</para></listitem>
7874bcd6028d1efbb4451c8b5cf5b2ac8d77af74Lennart Poettering </varlistentry>
7874bcd6028d1efbb4451c8b5cf5b2ac8d77af74Lennart Poettering </variablelist>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <para>When a daemon finished starting up, it
ad678a066b4ba5d8914dd7d5a4093572841205cfConrad Meyer might issue the following call to notify
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering the init system:</para>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <programlisting>sd_notify(0, "READY=1");</programlisting>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <title>Extended Start-up Notification</title>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <para>A daemon could send the following after
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering completing initialization:</para>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <programlisting>sd_notifyf(0, "READY=1\n"
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering "STATUS=Processing requests...\n"
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering "MAINPID=%lu",
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering (unsigned long) getpid());</programlisting>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <para>A daemon could send the following shortly before exiting, on failure</para>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <programlisting>sd_notifyf(0, "STATUS=Failed to start up: %s\n"
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering strerror(errno),
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering errno);</programlisting>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
cb07866b1b7c11e687a322d70dd9f9d73bbbe488Lennart Poettering <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>