1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 This file is part of systemd.
8 Copyright 2010 Lennart Poettering
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
24 <refentry id="systemd-notify"
25 xmlns:xi="http://www.w3.org/2001/XInclude">
28 <title>systemd-notify</title>
29 <productname>systemd</productname>
33 <contrib>Developer</contrib>
34 <firstname>Lennart</firstname>
35 <surname>Poettering</surname>
36 <email>lennart@poettering.net</email>
42 <refentrytitle>systemd-notify</refentrytitle>
43 <manvolnum>1</manvolnum>
47 <refname>systemd-notify</refname>
48 <refpurpose>Notify service manager about start-up completion and other daemon status changes</refpurpose>
53 <command>systemd-notify <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt" rep="repeat">VARIABLE=VALUE</arg></command>
58 <title>Description</title>
60 <para><command>systemd-notify</command> may be
61 called by daemon scripts to notify the init system
62 about status changes. It can be used to send arbitrary
63 information, encoded in an environment-block-like list
64 of strings. Most importantly it can be used for
65 start-up completion notification.</para>
67 <para>This is mostly just a wrapper around
68 <function>sd_notify()</function> and makes this
69 functionality available to shell scripts. For details
71 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
73 <para>The command line may carry a list of
74 environment variables to send as part of the status
77 <para>Note that systemd will refuse reception of
78 status updates from this command unless
79 <varname>NotifyAccess=all</varname> is set for the
80 service unit this command is called from.</para>
85 <title>Options</title>
87 <para>The following options are understood:</para>
91 <term><option>--ready</option></term>
93 <listitem><para>Inform the init system
94 about service start-up
95 completion. This is equivalent to
96 <command>systemd-notify
97 READY=1</command>. For details about
98 the semantics of this option see
99 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
103 <term><option>--pid=</option></term>
105 <listitem><para>Inform the init system
106 about the main PID of the
107 daemon. Takes a PID as argument. If
108 the argument is omitted, the PID of the
110 <command>systemd-notify</command> is
111 used. This is equivalent to
112 <command>systemd-notify
113 MAINPID=$PID</command>. For details
114 about the semantics of this option see
115 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
119 <term><option>--status=</option></term>
121 <listitem><para>Send a free-form
122 status string for the daemon to the
123 init systemd. This option takes the
124 status string as argument. This is
125 equivalent to <command>systemd-notify
126 STATUS=...</command>. For details
127 about the semantics of this option see
128 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
132 <term><option>--booted</option></term>
134 <listitem><para>Returns 0 if the
135 system was booted up with systemd,
136 non-zero otherwise. If this option is
137 passed, no message is sent. This option
138 is hence unrelated to the other
139 options. For details about the
140 semantics of this option, see
141 <citerefentry><refentrytitle>sd_booted</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
145 <term><option>--readahead=</option></term>
147 <listitem><para>Controls disk
148 read-ahead operations. The argument
149 must be a string, and either "cancel",
150 "done" or "noreplay". For details
151 about the semantics of this option see
152 <citerefentry><refentrytitle>sd_readahead</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
155 <xi:include href="standard-options.xml" xpointer="help" />
156 <xi:include href="standard-options.xml" xpointer="version" />
162 <title>Exit status</title>
164 <para>On success, 0 is returned, a non-zero failure
165 code otherwise.</para>
169 <title>Example</title>
172 <title>Start-up Notification and Status Updates</title>
174 <para>A simple shell daemon that sends
175 start-up notifications after having set up its
176 communication channel. During runtime it sends
177 further status updates to the init
180 <programlisting>#!/bin/bash
183 systemd-notify --ready --status="Waiting for data..."
186 read a < /tmp/waldo
187 systemd-notify --status="Processing $a"
189 # Do something with $a ...
191 systemd-notify --status="Waiting for data..."
192 done</programlisting>
197 <title>See Also</title>
199 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
200 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
201 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
202 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
203 <citerefentry><refentrytitle>sd_booted</refentrytitle><manvolnum>3</manvolnum></citerefentry>