1<?xml version='1.0'?> 2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 4<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> 5 6<refentry id="sd_notify" 7 xmlns:xi="http://www.w3.org/2001/XInclude"> 8 9 <refentryinfo> 10 <title>sd_notify</title> 11 <productname>systemd</productname> 12 </refentryinfo> 13 14 <refmeta> 15 <refentrytitle>sd_notify</refentrytitle> 16 <manvolnum>3</manvolnum> 17 </refmeta> 18 19 <refnamediv> 20 <refname>sd_notify</refname> 21 <refname>sd_notifyf</refname> 22 <refname>sd_pid_notify</refname> 23 <refname>sd_pid_notifyf</refname> 24 <refname>sd_pid_notify_with_fds</refname> 25 <refname>sd_notify_barrier</refname> 26 <refpurpose>Notify service manager about start-up completion and other service status changes</refpurpose> 27 </refnamediv> 28 29 <refsynopsisdiv> 30 <funcsynopsis> 31 <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo> 32 33 <funcprototype> 34 <funcdef>int <function>sd_notify</function></funcdef> 35 <paramdef>int <parameter>unset_environment</parameter></paramdef> 36 <paramdef>const char *<parameter>state</parameter></paramdef> 37 </funcprototype> 38 39 <funcprototype> 40 <funcdef>int <function>sd_notifyf</function></funcdef> 41 <paramdef>int <parameter>unset_environment</parameter></paramdef> 42 <paramdef>const char *<parameter>format</parameter></paramdef> 43 <paramdef>…</paramdef> 44 </funcprototype> 45 46 <funcprototype> 47 <funcdef>int <function>sd_pid_notify</function></funcdef> 48 <paramdef>pid_t <parameter>pid</parameter></paramdef> 49 <paramdef>int <parameter>unset_environment</parameter></paramdef> 50 <paramdef>const char *<parameter>state</parameter></paramdef> 51 </funcprototype> 52 53 <funcprototype> 54 <funcdef>int <function>sd_pid_notifyf</function></funcdef> 55 <paramdef>pid_t <parameter>pid</parameter></paramdef> 56 <paramdef>int <parameter>unset_environment</parameter></paramdef> 57 <paramdef>const char *<parameter>format</parameter></paramdef> 58 <paramdef>…</paramdef> 59 </funcprototype> 60 61 <funcprototype> 62 <funcdef>int <function>sd_pid_notify_with_fds</function></funcdef> 63 <paramdef>pid_t <parameter>pid</parameter></paramdef> 64 <paramdef>int <parameter>unset_environment</parameter></paramdef> 65 <paramdef>const char *<parameter>state</parameter></paramdef> 66 <paramdef>const int *<parameter>fds</parameter></paramdef> 67 <paramdef>unsigned <parameter>n_fds</parameter></paramdef> 68 </funcprototype> 69 70 <funcprototype> 71 <funcdef>int <function>sd_notify_barrier</function></funcdef> 72 <paramdef>int <parameter>unset_environment</parameter></paramdef> 73 <paramdef>uint64_t <parameter>timeout</parameter></paramdef> 74 </funcprototype> 75 </funcsynopsis> 76 </refsynopsisdiv> 77 78 <refsect1> 79 <title>Description</title> 80 <para><function>sd_notify()</function> may be called by a service 81 to notify the service manager about state changes. It can be used 82 to send arbitrary information, encoded in an 83 environment-block-like string. Most importantly, it can be used for 84 start-up completion notification.</para> 85 86 <para>If the <parameter>unset_environment</parameter> parameter is 87 non-zero, <function>sd_notify()</function> will unset the 88 <varname>$NOTIFY_SOCKET</varname> environment variable before 89 returning (regardless of whether the function call itself 90 succeeded or not). Further calls to 91 <function>sd_notify()</function> will then fail, but the variable 92 is no longer inherited by child processes.</para> 93 94 <para>The <parameter>state</parameter> parameter should contain a 95 newline-separated list of variable assignments, similar in style 96 to an environment block. A trailing newline is implied if none is 97 specified. The string may contain any kind of variable 98 assignments, but the following shall be considered 99 well-known:</para> 100 101 <variablelist> 102 <varlistentry> 103 <term>READY=1</term> 104 105 <listitem><para>Tells the service manager that service startup is finished, or the service finished loading its 106 configuration. This is only used by systemd if the service definition file has <varname>Type=notify</varname> 107 set. Since there is little value in signaling non-readiness, the only value services should send is 108 <literal>READY=1</literal> (i.e. <literal>READY=0</literal> is not defined).</para></listitem> 109 </varlistentry> 110 111 <varlistentry> 112 <term>RELOADING=1</term> 113 114 <listitem><para>Tells the service manager that the service is 115 reloading its configuration. This is useful to allow the 116 service manager to track the service's internal state, and 117 present it to the user. Note that a service that sends this 118 notification must also send a <literal>READY=1</literal> 119 notification when it completed reloading its 120 configuration. Reloads are propagated in the same way as they 121 are when initiated by the user.</para></listitem> 122 </varlistentry> 123 124 <varlistentry> 125 <term>STOPPING=1</term> 126 127 <listitem><para>Tells the service manager that the service is 128 beginning its shutdown. This is useful to allow the service 129 manager to track the service's internal state, and present it 130 to the user.</para></listitem> 131 </varlistentry> 132 133 <varlistentry> 134 <term>STATUS=…</term> 135 136 <listitem><para>Passes a single-line UTF-8 status string back 137 to the service manager that describes the service state. This 138 is free-form and can be used for various purposes: general 139 state feedback, fsck-like programs could pass completion 140 percentages and failing programs could pass a human-readable 141 error message. Example: <literal>STATUS=Completed 66% of file 142 system check…</literal></para></listitem> 143 </varlistentry> 144 145 <varlistentry> 146 <term>ERRNO=…</term> 147 148 <listitem><para>If a service fails, the errno-style error 149 code, formatted as string. Example: <literal>ERRNO=2</literal> 150 for ENOENT.</para></listitem> 151 </varlistentry> 152 153 <varlistentry> 154 <term>BUSERROR=…</term> 155 156 <listitem><para>If a service fails, the D-Bus error-style 157 error code. Example: 158 <literal>BUSERROR=org.freedesktop.DBus.Error.TimedOut</literal></para></listitem> 159 </varlistentry> 160 161 <varlistentry> 162 <term>MAINPID=…</term> 163 164 <listitem><para>The main process ID (PID) of the service, in 165 case the service manager did not fork off the process itself. 166 Example: <literal>MAINPID=4711</literal></para></listitem> 167 </varlistentry> 168 169 <varlistentry> 170 <term>WATCHDOG=1</term> 171 172 <listitem><para>Tells the service manager to update the 173 watchdog timestamp. This is the keep-alive ping that services 174 need to issue in regular intervals if 175 <varname>WatchdogSec=</varname> is enabled for it. See 176 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> 177 for information how to enable this functionality and 178 <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> 179 for the details of how the service can check whether the 180 watchdog is enabled. </para></listitem> 181 </varlistentry> 182 183 <varlistentry> 184 <term>WATCHDOG=trigger</term> 185 186 <listitem><para>Tells the service manager that the service detected an internal error that should be handled by 187 the configured watchdog options. This will trigger the same behaviour as if <varname>WatchdogSec=</varname> is 188 enabled and the service did not send <literal>WATCHDOG=1</literal> in time. Note that 189 <varname>WatchdogSec=</varname> does not need to be enabled for <literal>WATCHDOG=trigger</literal> to trigger 190 the watchdog action. See 191 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> for 192 information about the watchdog behavior. </para></listitem> 193 </varlistentry> 194 195 <varlistentry> 196 <term>WATCHDOG_USEC=…</term> 197 198 <listitem><para>Reset <varname>watchdog_usec</varname> value during runtime. 199 Notice that this is not available when using <function>sd_event_set_watchdog()</function> 200 or <function>sd_watchdog_enabled()</function>. 201 Example : <literal>WATCHDOG_USEC=20000000</literal></para></listitem> 202 </varlistentry> 203 204 <varlistentry> 205 <term>EXTEND_TIMEOUT_USEC=…</term> 206 207 <listitem><para>Tells the service manager to extend the startup, runtime or shutdown service timeout 208 corresponding the current state. The value specified is a time in microseconds during which the service must 209 send a new message. A service timeout will occur if the message isn't received, but only if the runtime of the 210 current state is beyond the original maximum times of <varname>TimeoutStartSec=</varname>, <varname>RuntimeMaxSec=</varname>, 211 and <varname>TimeoutStopSec=</varname>. 212 See <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> 213 for effects on the service timeouts.</para></listitem> 214 </varlistentry> 215 216 <varlistentry> 217 <term>FDSTORE=1</term> 218 219 <listitem><para>Stores additional file descriptors in the service manager. File descriptors sent this way will 220 be maintained per-service by the service manager and will later be handed back using the usual file descriptor 221 passing logic at the next invocation of the service (e.g. when it is restarted), see 222 <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This is 223 useful for implementing services that can restart after an explicit request or a crash without losing 224 state. Any open sockets and other file descriptors which should not be closed during the restart may be stored 225 this way. Application state can either be serialized to a file in <filename>/run/</filename>, or better, stored 226 in a <citerefentry><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry> memory 227 file descriptor. Note that the service manager will accept messages for a service only if its 228 <varname>FileDescriptorStoreMax=</varname> setting is non-zero (defaults to zero, see 229 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>). If 230 <varname>FDPOLL=0</varname> is not set and the file descriptors sent are pollable (see 231 <citerefentry><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>), then any 232 <constant>EPOLLHUP</constant> or <constant>EPOLLERR</constant> event seen on them will result in their 233 automatic removal from the store. Multiple arrays of file descriptors may be sent in separate messages, in 234 which case the arrays are combined. Note that the service manager removes duplicate (pointing to the same 235 object) file descriptors before passing them to the service. When a service is stopped, its file descriptor 236 store is discarded and all file descriptors in it are closed. Use <function>sd_pid_notify_with_fds()</function> 237 to send messages with <literal>FDSTORE=1</literal>, see below.</para></listitem> 238 </varlistentry> 239 240 <varlistentry> 241 <term>FDSTOREREMOVE=1</term> 242 243 <listitem><para>Removes file descriptors from the file descriptor store. This field needs to be combined with 244 <varname>FDNAME=</varname> to specify the name of the file descriptors to remove.</para></listitem> 245 </varlistentry> 246 247 <varlistentry> 248 <term>FDNAME=…</term> 249 250 <listitem><para>When used in combination with <varname>FDSTORE=1</varname>, specifies a name for the submitted 251 file descriptors. When used with <varname>FDSTOREREMOVE=1</varname>, specifies the name for the file 252 descriptors to remove. This name is passed to the service during activation, and may be queried using 253 <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>. File 254 descriptors submitted without this field set, will implicitly get the name <literal>stored</literal> 255 assigned. Note that, if multiple file descriptors are submitted at once, the specified name will be assigned to 256 all of them. In order to assign different names to submitted file descriptors, submit them in separate 257 invocations of <function>sd_pid_notify_with_fds()</function>. The name may consist of arbitrary ASCII 258 characters except control characters or <literal>:</literal>. It may not be longer than 255 characters. If a 259 submitted name does not follow these restrictions, it is ignored.</para></listitem> 260 </varlistentry> 261 262 <varlistentry> 263 <term>FDPOLL=0</term> 264 265 <listitem><para>When used in combination with <varname>FDSTORE=1</varname>, disables polling of the stored 266 file descriptors regardless of whether or not they are pollable. As this option disables automatic cleanup 267 of the stored file descriptors on EPOLLERR and EPOLLHUP, care must be taken to ensure proper manual cleanup. 268 Use of this option is not generally recommended except for when automatic cleanup has unwanted behavior such 269 as prematurely discarding file descriptors from the store.</para></listitem> 270 </varlistentry> 271 272 <varlistentry> 273 <term>BARRIER=1</term> 274 275 <listitem><para>Tells the service manager that the client is explicitly requesting synchronization by means of 276 closing the file descriptor sent with this command. The service manager guarantees that the processing of a <varname> 277 BARRIER=1</varname> command will only happen after all previous notification messages sent before this command 278 have been processed. Hence, this command accompanied with a single file descriptor can be used to synchronize 279 against reception of all previous status messages. Note that this command cannot be mixed with other notifications, 280 and has to be sent in a separate message to the service manager, otherwise all assignments will be ignored. Note that 281 sending 0 or more than 1 file descriptor with this command is a violation of the protocol.</para></listitem> 282 </varlistentry> 283 </variablelist> 284 285 <para>It is recommended to prefix variable names that are not 286 listed above with <varname>X_</varname> to avoid namespace 287 clashes.</para> 288 289 <para>Note that systemd will accept status data sent from a 290 service only if the <varname>NotifyAccess=</varname> option is 291 correctly set in the service definition file. See 292 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> 293 for details.</para> 294 295 <para>Note that <function>sd_notify()</function> notifications may be attributed to units correctly only if either 296 the sending process is still around at the time PID 1 processes the message, or if the sending process is 297 explicitly runtime-tracked by the service manager. The latter is the case if the service manager originally forked 298 off the process, i.e. on all processes that match <varname>NotifyAccess=</varname><option>main</option> or 299 <varname>NotifyAccess=</varname><option>exec</option>. Conversely, if an auxiliary process of the unit sends an 300 <function>sd_notify()</function> message and immediately exits, the service manager might not be able to properly 301 attribute the message to the unit, and thus will ignore it, even if 302 <varname>NotifyAccess=</varname><option>all</option> is set for it.</para> 303 304 <para>Hence, to eliminate all race conditions involving lookup of the client's unit and attribution of notifications 305 to units correctly, <function>sd_notify_barrier()</function> may be used. This call acts as a synchronization point 306 and ensures all notifications sent before this call have been picked up by the service manager when it returns 307 successfully. Use of <function>sd_notify_barrier()</function> is needed for clients which are not invoked by the 308 service manager, otherwise this synchronization mechanism is unnecessary for attribution of notifications to the 309 unit.</para> 310 311 <para><function>sd_notifyf()</function> is similar to 312 <function>sd_notify()</function> but takes a 313 <function>printf()</function>-like format string plus 314 arguments.</para> 315 316 <para><function>sd_pid_notify()</function> and 317 <function>sd_pid_notifyf()</function> are similar to 318 <function>sd_notify()</function> and 319 <function>sd_notifyf()</function> but take a process ID (PID) to 320 use as originating PID for the message as first argument. This is 321 useful to send notification messages on behalf of other processes, 322 provided the appropriate privileges are available. If the PID 323 argument is specified as 0, the process ID of the calling process 324 is used, in which case the calls are fully equivalent to 325 <function>sd_notify()</function> and 326 <function>sd_notifyf()</function>.</para> 327 328 <para><function>sd_pid_notify_with_fds()</function> is similar to 329 <function>sd_pid_notify()</function> but takes an additional array 330 of file descriptors. These file descriptors are sent along the 331 notification message to the service manager. This is particularly 332 useful for sending <literal>FDSTORE=1</literal> messages, as 333 described above. The additional arguments are a pointer to the 334 file descriptor array plus the number of file descriptors in the 335 array. If the number of file descriptors is passed as 0, the call 336 is fully equivalent to <function>sd_pid_notify()</function>, i.e. 337 no file descriptors are passed. Note that sending file descriptors 338 to the service manager on messages that do not expect them (i.e. 339 without <literal>FDSTORE=1</literal>) they are immediately closed 340 on reception.</para> 341 342 <para><function>sd_notify_barrier()</function> allows the caller to 343 synchronize against reception of previously sent notification messages 344 and uses the <literal>BARRIER=1</literal> command. It takes a relative 345 <varname>timeout</varname> value in microseconds which is passed to 346 <citerefentry><refentrytitle>ppoll</refentrytitle><manvolnum>2</manvolnum> 347 </citerefentry>. A value of UINT64_MAX is interpreted as infinite timeout. 348 </para> 349 </refsect1> 350 351 <refsect1> 352 <title>Return Value</title> 353 354 <para>On failure, these calls return a negative errno-style error code. If <varname>$NOTIFY_SOCKET</varname> was 355 not set and hence no status message could be sent, 0 is returned. If the status was sent, these functions return a 356 positive value. In order to support both service managers that implement this scheme and those which do not, it is 357 generally recommended to ignore the return value of this call. Note that the return value simply indicates whether 358 the notification message was enqueued properly, it does not reflect whether the message could be processed 359 successfully. Specifically, no error is returned when a file descriptor is attempted to be stored using 360 <varname>FDSTORE=1</varname> but the service is not actually configured to permit storing of file descriptors (see 361 above).</para> 362 </refsect1> 363 364 <refsect1> 365 <title>Notes</title> 366 367 <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> 368 369 <para>These functions send a single datagram with the 370 state string as payload to the <constant>AF_UNIX</constant> socket 371 referenced in the <varname>$NOTIFY_SOCKET</varname> environment 372 variable. If the first character of 373 <varname>$NOTIFY_SOCKET</varname> is <literal>@</literal>, the 374 string is understood as Linux abstract namespace socket. The 375 datagram is accompanied by the process credentials of the sending 376 service, using SCM_CREDENTIALS.</para> 377 </refsect1> 378 379 <refsect1> 380 <title>Environment</title> 381 382 <variablelist class='environment-variables'> 383 <varlistentry> 384 <term><varname>$NOTIFY_SOCKET</varname></term> 385 386 <listitem><para>Set by the service manager for supervised 387 processes for status and start-up completion notification. 388 This environment variable specifies the socket 389 <function>sd_notify()</function> talks to. See above for 390 details.</para></listitem> 391 </varlistentry> 392 </variablelist> 393 </refsect1> 394 395 <refsect1> 396 <title>Examples</title> 397 398 <example> 399 <title>Start-up Notification</title> 400 401 <para>When a service finished starting up, it might issue the 402 following call to notify the service manager:</para> 403 404 <programlisting>sd_notify(0, "READY=1");</programlisting> 405 </example> 406 407 <example> 408 <title>Extended Start-up Notification</title> 409 410 <para>A service could send the following after completing 411 initialization:</para> 412 413 <programlisting>sd_notifyf(0, "READY=1\n" 414 "STATUS=Processing requests…\n" 415 "MAINPID=%lu", 416 (unsigned long) getpid());</programlisting> 417 </example> 418 419 <example> 420 <title>Error Cause Notification</title> 421 422 <para>A service could send the following shortly before exiting, on failure:</para> 423 424 <programlisting>sd_notifyf(0, "STATUS=Failed to start up: %s\n" 425 "ERRNO=%i", 426 strerror(errno), 427 errno);</programlisting> 428 </example> 429 430 <example> 431 <title>Store a File Descriptor in the Service Manager</title> 432 433 <para>To store an open file descriptor in the service manager, 434 in order to continue operation after a service restart without 435 losing state, use <literal>FDSTORE=1</literal>:</para> 436 437 <programlisting>sd_pid_notify_with_fds(0, 0, "FDSTORE=1\nFDNAME=foobar", &fd, 1);</programlisting> 438 </example> 439 440 <example> 441 <title>Eliminating race conditions</title> 442 443 <para>When the client sending the notifications is not spawned 444 by the service manager, it may exit too quickly and the service 445 manager may fail to attribute them correctly to the unit. To 446 prevent such races, use <function>sd_notify_barrier()</function> 447 to synchronize against reception of all notifications sent before 448 this call is made.</para> 449 450 <programlisting>sd_notify(0, "READY=1"); 451 /* set timeout to 5 seconds */ 452 sd_notify_barrier(0, 5 * 1000000); 453 </programlisting> 454 </example> 455 </refsect1> 456 457 <refsect1> 458 <title>See Also</title> 459 <para> 460 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 461 <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 462 <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 463 <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 464 <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 465 <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, 466 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> 467 </para> 468 </refsect1> 469 470</refentry> 471