09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering This file is part of systemd.
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering Copyright 2013 Lennart Poettering
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering systemd is free software; you can redistribute it and/or modify it
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering under the terms of the GNU Lesser General Public License as published by
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering the Free Software Foundation; either version 2.1 of the License, or
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering (at your option) any later version.
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering systemd is distributed in the hope that it will be useful, but
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering WITHOUT ANY WARRANTY; without even the implied warranty of
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering Lesser General Public License for more details.
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering You should have received a copy of the GNU Lesser General Public License
09812eb764b440651f3ff4cb5d37bd343f800560Lennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
6a70f3aa63a3b7a6a30448c48322ad38b719cdceZbigniew Jędrzejewski-Szmek<refentry id="sd_watchdog_enabled"
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek xmlns:xi="http://www.w3.org/2001/XInclude">
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <title>sd_watchdog_enabled</title>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <productname>systemd</productname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <email>lennart@poettering.net</email>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refentrytitle>sd_watchdog_enabled</refentrytitle>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refname>sd_watchdog_enabled</refname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refpurpose>Check whether the service manager expects watchdog keep-alive notifications from a service</refpurpose>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refsynopsisdiv>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <funcdef>int <function>sd_watchdog_enabled</function></funcdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>int <parameter>unset_environment</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </funcprototype>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </refsynopsisdiv>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para><function>sd_watchdog_enabled()</function> may be called by
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek a service to detect whether the service manager expects regular
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek keep-alive watchdog notification events from it, and the timeout
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek after which the manager will act on the service if it did not get
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek such a notification.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>If the <varname>$WATCHDOG_USEC</varname> environment
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek variable is set, and the <varname>$WATCHDOG_PID</varname> variable
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek is unset or set to the PID of the current process, the service
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek manager expects notifications from this process. The manager will
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek usually terminate a service when it does not get a notification
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek message within the specified time after startup and after each
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek previous message. It is recommended that a daemon sends a
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek keep-alive notification message to the service manager every half
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek of the time returned here. Notification messages may be sent with
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek with a message string of <literal>WATCHDOG=1</literal>.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>If the <parameter>unset_environment</parameter> parameter is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek non-zero, <function>sd_watchdog_enabled()</function> will unset
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the <varname>$WATCHDOG_USEC</varname> and
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <varname>$WATCHDOG_PID</varname> environment variables before
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek returning (regardless of whether the function call itself
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek succeeded or not). Those variables are no longer inherited by
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek child processes. Further calls to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <function>sd_watchdog_enabled()</function> will also return with
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>If the <parameter>usec</parameter> parameter is non-NULL,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <function>sd_watchdog_enabled()</function> will write the timeout
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek in µs for the watchdog logic to it.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>To enable service supervision with the watchdog logic, use
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <varname>WatchdogSec=</varname> in service files. See
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek for details.</para>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering to enable automatic watchdog support in
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>-based event loops.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>On failure, this call returns a negative errno-style error
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek code. If the service manager expects watchdog keep-alive
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek notification messages to be sent, > 0 is returned, otherwise 0
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek is returned. Only if the return value is > 0, the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <parameter>usec</parameter> parameter is valid after the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Internally, this functions parses the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <varname>$WATCHDOG_PID</varname> and
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <varname>$WATCHDOG_USEC</varname> environment variable. The call
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek will ignore these variables if <varname>$WATCHDOG_PID</varname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek does not contain the PID of the current process, under the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek assumption that in that case, the variables were set for a
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek different process further up the process tree.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <variablelist class='environment-variables'>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><varname>$WATCHDOG_PID</varname></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Set by the system manager for supervised
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek process for which watchdog support is enabled, and contains
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the PID of that process. See above for
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><varname>$WATCHDOG_USEC</varname></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Set by the system manager for supervised
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek process for which watchdog support is enabled, and contains
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the watchdog timeout in µs See above for
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>The watchdog functionality and the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <varname>$WATCHDOG_USEC</varname> variable were added in
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek systemd-41.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para><function>sd_watchdog_enabled()</function> function was
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt added in systemd-209. Since that version, the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <varname>$WATCHDOG_PID</varname> variable is also set.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>