From 9b186fc8bc039d76d4667f92437d9ff1464d76fe Mon Sep 17 00:00:00 2001
From: Daan De Meyer <daan.j.demeyer@gmail.com>
Date: Tue, 14 Jan 2025 16:05:33 +0100
Subject: [PATCH] man: Clarify systemd-notify and sd_notify() PID documentation

Let's clarify more explicitly that privileged calls to
systemd-notify --pid= and sd_pid_notify() effectively override any
configured NotifyAccess=main|exec for a service.

(cherry picked from commit bbe9e03f8066d1001497494ee862cf45f986b854)
---
 man/sd_notify.xml      |  9 ++++++---
 man/systemd-notify.xml | 15 +++++++++++----
 2 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/man/sd_notify.xml b/man/sd_notify.xml
index 6aaaa64b3f..a465e02f52 100644
--- a/man/sd_notify.xml
+++ b/man/sd_notify.xml
@@ -140,9 +140,12 @@
     <para><function>sd_pid_notify()</function> and <function>sd_pid_notifyf()</function> are similar to
     <function>sd_notify()</function> and <function>sd_notifyf()</function> but take a process ID (PID) to use
     as originating PID for the message as first argument. This is useful to send notification messages on
-    behalf of other processes, provided the appropriate privileges are available. If the PID argument is
-    specified as 0, the process ID of the calling process is used, in which case the calls are fully
-    equivalent to <function>sd_notify()</function> and <function>sd_notifyf()</function>.</para>
+    behalf of other processes, provided the appropriate privileges are available. Effectively, this means
+    that a privileged invocation of <command>sd_pid_notify()</command> may circumvent
+    <varname>NotifyAccess=main</varname> or <varname>NotifyAccess=exec</varname> restrictions enforced for a
+    service. If the PID argument is specified as 0, the process ID of the calling process is used, in which
+    case the calls are fully equivalent to <function>sd_notify()</function> and
+    <function>sd_notifyf()</function>.</para>
 
     <para><function>sd_pid_notify_with_fds()</function> is similar to <function>sd_pid_notify()</function>
     but takes an additional array of file descriptors. These file descriptors are sent along the notification
diff --git a/man/systemd-notify.xml b/man/systemd-notify.xml
index 55bb8c59cf..9a66721a61 100644
--- a/man/systemd-notify.xml
+++ b/man/systemd-notify.xml
@@ -125,12 +125,19 @@
         argument is specified as <literal>self</literal>, the PID of the <command>systemd-notify</command>
         command itself is used, and if <literal>parent</literal> is specified the calling process' PID is
         used — even if it is the service manager. <option>--pid=auto</option> is equivalent to <command>systemd-notify
-        MAINPID=$PID</command>. For details about the semantics of this option see
+        --pid=$PID</command>. For details about the semantics of this option see
         <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 
-        <para>If this switch is used in an <command>systemd-notify</command> invocation from a process that
-        shall become the new main process of a service — and which is not the process forked off by the
-        service manager (or the current main process) —, then it is essential to set
+        <para><command>systemd-notify</command> will first attempt to invoke <function>sd_notify()</function>
+        pretending to have the PID specified with <option>--pid=</option>. This will only succeed when
+        invoked with sufficient privileges. On failure, it will then fall back to invoking it under its own
+        PID. Effectively, this means that a privileged invocation of <command>systemd-notify --pid=</command>
+        may circumvent <varname>NotifyAccess=main</varname> or <varname>NotifyAccess=exec</varname>
+        restrictions enforced for a service.</para>
+
+        <para>If this switch is used in an unprivileged <command>systemd-notify</command> invocation from a
+        process that shall become the new main process of a service — and which is not the process forked off
+        by the service manager (or the current main process) —, then it is essential to set
         <varname>NotifyAccess=all</varname> in the service unit file, or otherwise the notification will be
         ignored for security reasons. See
         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>