'\" t
.TH "SYSTEMD\-NOTIFY" "1" "" "systemd 247" "systemd-notify"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
systemd-notify \- Notify service manager about start\-up completion and other daemon status changes
.SH "SYNOPSIS"
.HP \w'\fBsystemd\-notify\ \fR\fB[OPTIONS...]\fR\fB\ \fR\fB[VARIABLE=VALUE...]\fR\ 'u
\fBsystemd\-notify \fR\fB[OPTIONS...]\fR\fB \fR\fB[VARIABLE=VALUE...]\fR
.SH "DESCRIPTION"
.PP
\fBsystemd\-notify\fR
may be called by daemon scripts to notify the init system about status changes\&. It can be used to send arbitrary information, encoded in an environment\-block\-like list of strings\&. Most importantly, it can be used for start\-up completion notification\&.
.PP
This is mostly just a wrapper around
\fBsd_notify()\fR
and makes this functionality available to shell scripts\&. For details see
\fBsd_notify\fR(3)\&.
.PP
The command line may carry a list of environment variables to send as part of the status update\&.
.PP
Note that systemd will refuse reception of status updates from this command unless
\fINotifyAccess=\fR
is set for the service unit this command is called from\&.
.PP
Note that
\fBsd_notify()\fR
notifications may be attributed to units correctly only if either the sending process is still around at the time PID 1 processes the message, or if the sending process is explicitly runtime\-tracked by the service manager\&. The latter is the case if the service manager originally forked off the process, i\&.e\&. on all processes that match
\fINotifyAccess=\fR\fBmain\fR
or
\fINotifyAccess=\fR\fBexec\fR\&. Conversely, if an auxiliary process of the unit sends an
\fBsd_notify()\fR
message and immediately exits, the service manager might not be able to properly attribute the message to the unit, and thus will ignore it, even if
\fINotifyAccess=\fR\fBall \fR
is set for it\&. When
\fB\-\-no\-block\fR
is used, all synchronization for reception of notifications is disabled, and hence the aforementioned race may occur if the invoking process is not the service manager or spawned by the service manager\&.
.PP
Hence,
\fBsystemd\-notify\fR
will first attempt to invoke
\fBsd_notify()\fR
pretending to have the PID of the invoking process\&. This will only succeed when invoked with sufficient privileges\&. On failure, it will then fall back to invoking it under its own PID\&. This behaviour is useful in order that when the tool is invoked from a shell script the shell process \(em and not the
\fBsystemd\-notify\fR
process \(em appears as sender of the message, which in turn is helpful if the shell process is the main process of a service, due to the limitations of
\fINotifyAccess=\fR\fBall\fR\&. Use the
\fB\-\-pid=\fR
switch to tweak this behaviour\&.
.SH "OPTIONS"
.PP
The following options are understood:
.PP
\fB\-\-ready\fR
.RS 4
Inform the init system about service start\-up completion\&. This is equivalent to
\fBsystemd\-notify READY=1\fR\&. For details about the semantics of this option see
\fBsd_notify\fR(3)\&.
.RE
.PP
\fB\-\-pid=\fR
.RS 4
Inform the service manager about the main PID of the daemon\&. Takes a PID as argument\&. If the argument is specified as
"auto"
or omitted, the PID of the process that invoked
\fBsystemd\-notify\fR
is used, except if that\*(Aqs the service manager\&. If the argument is specified as
"self", the PID of the
\fBsystemd\-notify\fR
command itself is used, and if
"parent"
is specified the calling process\*(Aq PID is used \(em even if it is the service manager\&. This is equivalent to
\fBsystemd\-notify MAINPID=$PID\fR\&. For details about the semantics of this option see
\fBsd_notify\fR(3)\&.
.RE
.PP
\fB\-\-uid=\fR\fIUSER\fR
.RS 4
Set the user ID to send the notification from\&. Takes a UNIX user name or numeric UID\&. When specified the notification message will be sent with the specified UID as sender, in place of the user the command was invoked as\&. This option requires sufficient privileges in order to be able manipulate the user identity of the process\&.
.RE
.PP
\fB\-\-status=\fR
.RS 4
Send a free\-form status string for the daemon to the init systemd\&. This option takes the status string as argument\&. This is equivalent to
\fBsystemd\-notify STATUS=\&...\fR\&. For details about the semantics of this option see
\fBsd_notify\fR(3)\&.
.RE
.PP
\fB\-\-booted\fR
.RS 4
Returns 0 if the system was booted up with systemd, non\-zero otherwise\&. If this option is passed, no message is sent\&. This option is hence unrelated to the other options\&. For details about the semantics of this option, see
\fBsd_booted\fR(3)\&. An alternate way to check for this state is to call
\fBsystemctl\fR(1)
with the
\fBis\-system\-running\fR
command\&. It will return
"offline"
if the system was not booted with systemd\&.
.RE
.PP
\fB\-\-no\-block\fR
.RS 4
Do not synchronously wait for the requested operation to finish\&. Use of this option is only recommended when
\fBsystemd\-notify\fR
is spawned by the service manager, or when the invoking process is directly spawned by the service manager and has enough privileges to allow
\fBsystemd\-notify\fR
to send the notification on its behalf\&. Sending notifications with this option set is prone to race conditions in all other cases\&.
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Print a short help text and exit\&.
.RE
.PP
\fB\-\-version\fR
.RS 4
Print a short version string and exit\&.
.RE
.SH "EXIT STATUS"
.PP
On success, 0 is returned, a non\-zero failure code otherwise\&.
.SH "EXAMPLE"
.PP
\fBExample\ \&1.\ \&Start\-up Notification and Status Updates\fR
.PP
A simple shell daemon that sends start\-up notifications after having set up its communication channel\&. During runtime it sends further status updates to the init system:
.sp
.if n \{\
.RS 4
.\}
.nf
#!/bin/bash

mkfifo /tmp/waldo
systemd\-notify \-\-ready \-\-status="Waiting for data\&..."

while : ; do
        read a < /tmp/waldo
        systemd\-notify \-\-status="Processing $a"

        # Do something with $a \&...

        systemd\-notify \-\-status="Waiting for data\&..."
done
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1),
\fBsystemctl\fR(1),
\fBsystemd.unit\fR(5),
\fBsd_notify\fR(3),
\fBsd_booted\fR(3)