From b3bb64767abacc5b759255a698c89b3495cd54f4 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Mon, 6 Feb 2017 13:49:44 +0100 Subject: [PATCH] man: document that sd_notify() is racy in some cases --- man/sd_notify.xml | 9 +++++++++ man/systemd-notify.xml | 15 +++++++++++---- man/systemd.service.xml | 40 ++++++++++++++++++++-------------------- 3 files changed, 40 insertions(+), 24 deletions(-) diff --git a/man/sd_notify.xml b/man/sd_notify.xml index 6e98041912d31..4dcefc4bafb8a 100644 --- a/man/sd_notify.xml +++ b/man/sd_notify.xml @@ -268,6 +268,15 @@ systemd.service5 for details. + Note that sd_notify() 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 NotifyAccess= or + NotifyAccess=. Conversely, if an auxiliary process of the unit sends an + sd_notify() 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 + NotifyAccess= is set for it. + sd_notifyf() is similar to sd_notify() but takes a printf()-like format string plus diff --git a/man/systemd-notify.xml b/man/systemd-notify.xml index 4a8e119eb6fb1..9bb35a3a0c75d 100644 --- a/man/systemd-notify.xml +++ b/man/systemd-notify.xml @@ -72,10 +72,17 @@ The command line may carry a list of environment variables to send as part of the status update. - Note that systemd will refuse reception of status updates - from this command unless NotifyAccess=all is - set for the service unit this command is called from. - + Note that systemd will refuse reception of status updates from this command unless + NotifyAccess= is set for the service unit this command is called from. + + Note that sd_notify() 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 NotifyAccess= or + NotifyAccess=. Conversely, if an auxiliary process of the unit sends an + sd_notify() 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 + NotifyAccess= is set for it. diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 522ed5e61e055..420ae4e7b5606 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -792,26 +792,26 @@ NotifyAccess= - Controls access to the service status - notification socket, as accessible via the - sd_notify3 - call. Takes one of (the default), - , or - . If , no daemon status - updates are accepted from the service processes, all status - update messages are ignored. If , only - service updates sent from the main process of the service are - accepted. If , only service updates sent - from any of the control processes originating from one of the - Exec*= commands are accepted. If - , all services updates from all members of - the service's control group are accepted. This option should - be set to open access to the notification socket when using - Type=notify or - WatchdogSec= (see above). If those options - are used but NotifyAccess= is not - configured, it will be implicitly set to - . + Controls access to the service status notification socket, as accessible via the + sd_notify3 call. Takes one + of (the default), , or + . If , no daemon status updates are accepted from the service + processes, all status update messages are ignored. If , only service updates sent from the + main process of the service are accepted. If , only service updates sent from any of the + main or control processes originating from one of the Exec*= commands are accepted. If + , all services updates from all members of the service's control group are accepted. This + option should be set to open access to the notification socket when using Type=notify or + WatchdogSec= (see above). If those options are used but NotifyAccess= is + not configured, it will be implicitly set to . + + Note that sd_notify() 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 or + . Conversely, if an auxiliary process of the unit sends an + sd_notify() 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 + NotifyAccess= is set for it.