sd_notify.xml revision 5430f7f2bc7330f3088b894166bf3524a067e3d8
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/>.
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <refentryinfo>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering </authorgroup>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering </refentryinfo>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <refpurpose>Notify init system 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>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering parameter is non-zero <function>sd_notify()</function>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering will unset the <varname>$NOTIFY_SOCKET</varname>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering environment variable before returning (regardless
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
96d4ce01103ebebe9335fb321667043bb620c06bMichael Biebl should contain an 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
af62c704053b5d34672497eb5bdc4764ebbb5f4fKay Sievers value in signalling 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>
a6927d7ffc18c51fbb9940f5f1e89f5c7695ed63Michael Olbrich update the watchdog timestamp.
a6927d7ffc18c51fbb9940f5f1e89f5c7695ed63Michael Olbrich Services using this feature should do
a6927d7ffc18c51fbb9940f5f1e89f5c7695ed63Michael Olbrich this in regular intervals. A watchdog
a6927d7ffc18c51fbb9940f5f1e89f5c7695ed63Michael Olbrich framework can use the timestamps to
a6927d7ffc18c51fbb9940f5f1e89f5c7695ed63Michael Olbrich detect failed
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
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering 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
af62c704053b5d34672497eb5bdc4764ebbb5f4fKay Sievers don't, it is generally recommended to ignore the return
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering value of this call.</para>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <para>These functions are provided by the reference
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering implementation of APIs for new-style daemons and
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering distributed with the systemd package. The algorithms
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering they implement are simple, and can easily be
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering reimplemented in daemons if it is important to support
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering this interface without using the reference
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering implementation.</para>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <para>Internally, these functions send a single
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering datagram with the state string as payload to the
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering AF_UNIX socket referenced in the
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <varname>$NOTIFY_SOCKET</varname> environment
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering variable. If the first character of
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <varname>$NOTIFY_SOCKET</varname> is @ 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>
71e6c1cf47c35cc5a58cefaabe4f6848d6f09501Lennart Poettering <para>For details about the algorithms check the
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering liberally licensed reference implementation sources:
a26c9cc60477acacf3a147009894bd837353ed6cMichael Biebl <ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/sd-daemon.c"/>
a26c9cc60477acacf3a147009894bd837353ed6cMichael Biebl url="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h"/></para>
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <para><function>sd_notify()</function> and
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <function>sd_notifyf()</function> are implemented in
71e6c1cf47c35cc5a58cefaabe4f6848d6f09501Lennart Poettering the reference implementation's
71e6c1cf47c35cc5a58cefaabe4f6848d6f09501Lennart Poettering <filename>sd-daemon.h</filename> files. These
71e6c1cf47c35cc5a58cefaabe4f6848d6f09501Lennart Poettering interfaces are available as shared library, which can
71e6c1cf47c35cc5a58cefaabe4f6848d6f09501Lennart Poettering be compiled and linked to with the
71e6c1cf47c35cc5a58cefaabe4f6848d6f09501Lennart Poettering <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
71e6c1cf47c35cc5a58cefaabe4f6848d6f09501Lennart Poettering file. Alternatively, applications consuming these APIs
71e6c1cf47c35cc5a58cefaabe4f6848d6f09501Lennart Poettering may copy the implementation into their source tree. For
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering more details about the reference implementation see
71e6c1cf47c35cc5a58cefaabe4f6848d6f09501Lennart Poettering <citerefentry><refentrytitle>sd_daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
71e6c1cf47c35cc5a58cefaabe4f6848d6f09501Lennart Poettering <para>If the reference implementation is used as
71e6c1cf47c35cc5a58cefaabe4f6848d6f09501Lennart Poettering drop-in files and -DDISABLE_SYSTEMD is set during
71e6c1cf47c35cc5a58cefaabe4f6848d6f09501Lennart Poettering compilation these functions will always return 0 and
71e6c1cf47c35cc5a58cefaabe4f6848d6f09501Lennart Poettering otherwise become a NOP.</para>
7874bcd6028d1efbb4451c8b5cf5b2ac8d77af74Lennart Poettering <variablelist>
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>,
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <citerefentry><refentrytitle>sd_daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
f9378423b9758861850748aeb49ae0d3300e56e6Lennart Poettering <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>