sd_watchdog_enabled.xml revision dc83f27a7cf03757dec11a69ec18504ad4ea8f89
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye This file is part of systemd.
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye Copyright 2013 Lennart Poettering
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye systemd is free software; you can redistribute it and/or modify it
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye under the terms of the GNU Lesser General Public License as published by
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye the Free Software Foundation; either version 2.1 of the License, or
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye (at your option) any later version.
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye systemd is distributed in the hope that it will be useful, but
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye WITHOUT ANY WARRANTY; without even the implied warranty of
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye Lesser General Public License for more details.
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye You should have received a copy of the GNU Lesser General Public License
fe80b749cd764b1f0f72b2f913b1fe10581911c3Knut Anders Hatlen along with systemd; If not, see <http://www.gnu.org/licenses/>.
d4ce228a333ba2daa19ad8b0672a704c8e42a2dcTrond Norbye <refentryinfo>
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye <authorgroup>
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye </authorgroup>
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye </refentryinfo>
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye <refentrytitle>sd_watchdog_enabled</refentrytitle>
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye <refnamediv>
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye <refpurpose>Check whether the service manager expects watchdog keep-alive notifications from a service</refpurpose>
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye </refnamediv>
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye <refsynopsisdiv>
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye <funcsynopsis>
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo>
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye <funcprototype>
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye <funcdef>int <function>sd_watchdog_enabled</function></funcdef>
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye <paramdef>int <parameter>unset_environment</parameter></paramdef>
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye </funcprototype>
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye </funcsynopsis>
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye </refsynopsisdiv>
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye <para><function>sd_watchdog_enabled()</function> may be called by
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye a service to detect whether the service manager expects regular
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye keep-alive watchdog notification events from it, and the timeout
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye after which the manager will act on the service if it did not get
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye such a notification.</para>
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye <para>If the <varname>$WATCHDOG_USEC</varname> environment
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye variable is set, and the <varname>$WATCHDOG_PID</varname> variable
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye is unset or set to the PID of the current process, the service
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye manager expects notifications from this process. The manager will
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye usually terminate a service when it does not get a notification
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye message within the specified time after startup and after each
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye previous message. It is recommended that a daemon sends a
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye keep-alive notification message to the service manager every half
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye of the time returned here. Notification messages may be sent with
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye with a message string of <literal>WATCHDOG=1</literal>.</para>
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye <para>If the <parameter>unset_environment</parameter> parameter is
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye non-zero, <function>sd_watchdog_enabled()</function> will unset
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye <varname>$WATCHDOG_PID</varname> environment variables before
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye returning (regardless of whether the function call itself
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye succeeded or not). Those variables are no longer inherited by
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye child processes. Further calls to
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye <function>sd_watchdog_enabled()</function> will also return with
64b763950bf11e9357facbd2b5666631a895c085Trond Norbye zero.</para>
0a0811923cbbd2976425db6f4c78eed811c2825bKnut Anders Hatlen <para>If the <parameter>usec</parameter> parameter is non-NULL,
653794abf1d9fda5f111e2401d8bd3ead80cfc83Vladimir Kotal <function>sd_watchdog_enabled()</function> will write the timeout
a07b2874263e3c5f0cd2e83441719415d53059c2Knut Anders Hatlen in µs for the watchdog logic to it.</para>
7e33e87b7d6c9a61ff11d23e37c02274b1223ce1Jens Elkner <para>To enable service supervision with the watchdog logic, use
c7eb123c8b2081a261deff3c401fbf92ddba1b58Jorgen Austvik <varname>WatchdogSec=</varname> in service files. See
c7eb123c8b2081a261deff3c401fbf92ddba1b58Jorgen Austvik <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
49f592091468eac515dde6139fbc8efa26056b0aJorgen Austvik for details.</para>
780cc7d1b57609ff15fb283201e93cb501ebe9e6Jorgen Austvik <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
780cc7d1b57609ff15fb283201e93cb501ebe9e6Jorgen Austvik to enable automatic watchdog support in
f754dd2bbc98a89a613ab4f76dad5534dc13e929Vladimir Kotal <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>-based event loops.</para>
7b9f9a1761f76744fc3772181877d5e301f122adKnut Anders Hatlen <para>On failure, this call returns a negative errno-style error
5a0c5ad4116f5a4dd0dd5a0a4e6d02973cd5eef9Lubos Kosco code. If the service manager expects watchdog keep-alive
0466de7c67573e1ce5e0733325c1e5383270f5d5Knut Anders Hatlen notification messages to be sent, > 0 is returned, otherwise 0
0466de7c67573e1ce5e0733325c1e5383270f5d5Knut Anders Hatlen is returned. Only if the return value is > 0, the
0466de7c67573e1ce5e0733325c1e5383270f5d5Knut Anders Hatlen <parameter>usec</parameter> parameter is valid after the
d4ce228a333ba2daa19ad8b0672a704c8e42a2dcTrond Norbye call.</para>
7ecd52b03dc1f0b03ff8f522b4891c8531896c3dJorgen Austvik <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
d4ce228a333ba2daa19ad8b0672a704c8e42a2dcTrond Norbye <para>Internally, this functions parses the
474ac6921d21d2e44cf9c1e91f17d6bcbb15c9e8Lubos Kosco <varname>$WATCHDOG_USEC</varname> environment variable. The call
7ecd52b03dc1f0b03ff8f522b4891c8531896c3dJorgen Austvik will ignore these variables if <varname>$WATCHDOG_PID</varname>
7ecd52b03dc1f0b03ff8f522b4891c8531896c3dJorgen Austvik does not contain the PID of the current process, under the
7ecd52b03dc1f0b03ff8f522b4891c8531896c3dJorgen Austvik assumption that in that case, the variables were set for a
c7eb123c8b2081a261deff3c401fbf92ddba1b58Jorgen Austvik different process further up the process tree.</para>
5a0c5ad4116f5a4dd0dd5a0a4e6d02973cd5eef9Lubos Kosco <varlistentry>
49f592091468eac515dde6139fbc8efa26056b0aJorgen Austvik <term><varname>$WATCHDOG_PID</varname></term>
945f4c3c36a15447913781dfb1894b34f2941c57Jorgen Austvik <listitem><para>Set by the system manager for supervised
945f4c3c36a15447913781dfb1894b34f2941c57Jorgen Austvik process for which watchdog support is enabled, and contains
5a0c5ad4116f5a4dd0dd5a0a4e6d02973cd5eef9Lubos Kosco the PID of that process. See above for
945f4c3c36a15447913781dfb1894b34f2941c57Jorgen Austvik </varlistentry>
b411dcdf67df825303fcb366759169c881936ac9Vladimir Kotal <varlistentry>
b411dcdf67df825303fcb366759169c881936ac9Vladimir Kotal <listitem><para>Set by the system manager for supervised
b411dcdf67df825303fcb366759169c881936ac9Vladimir Kotal process for which watchdog support is enabled, and contains
b411dcdf67df825303fcb366759169c881936ac9Vladimir Kotal the watchdog timeout in µs See above for
b411dcdf67df825303fcb366759169c881936ac9Vladimir Kotal </varlistentry>
b411dcdf67df825303fcb366759169c881936ac9Vladimir Kotal </variablelist>
b411dcdf67df825303fcb366759169c881936ac9Vladimir Kotal <para>The watchdog functionality and the
f9fd2b96d1c5ea62664f74da0e34a04b6511a8ffLubos Kosco <varname>$WATCHDOG_USEC</varname> variable were added in
b411dcdf67df825303fcb366759169c881936ac9Vladimir Kotal systemd-41.</para>
b34561d2c3d92fac37dbced05ba6a8738e3d20e9Lubos Kosco <para><function>sd_watchdog_enabled()</function> function was
474ac6921d21d2e44cf9c1e91f17d6bcbb15c9e8Lubos Kosco added in systemd-209. Since that version, the
474ac6921d21d2e44cf9c1e91f17d6bcbb15c9e8Lubos Kosco <varname>$WATCHDOG_PID</varname> variable is also set.</para>
474ac6921d21d2e44cf9c1e91f17d6bcbb15c9e8Lubos Kosco <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
474ac6921d21d2e44cf9c1e91f17d6bcbb15c9e8Lubos Kosco <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
474ac6921d21d2e44cf9c1e91f17d6bcbb15c9e8Lubos Kosco <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
474ac6921d21d2e44cf9c1e91f17d6bcbb15c9e8Lubos Kosco <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
474ac6921d21d2e44cf9c1e91f17d6bcbb15c9e8Lubos Kosco <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
474ac6921d21d2e44cf9c1e91f17d6bcbb15c9e8Lubos Kosco <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>