From: Lennart Poettering <lennart@poettering.net>
Date: Tue, 5 Nov 2024 12:27:23 +0000 (+0100)
Subject: man: highlight the privilege issues around the LogControl1 more
X-Git-Tag: v257-rc1~21^2~7
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=172ac39fc8e8786c6c3bf86daa8fe8798af9540b;p=thirdparty%2Fsystemd.git

man: highlight the privilege issues around the LogControl1 more

Let's emphasize the privilege thing with a <caution> section.

Let's also point out that other D-Bus libraries are less restrictive
than sd-bus by default regarding permission access.

Fixes: #34735
---

diff --git a/man/org.freedesktop.LogControl1.xml b/man/org.freedesktop.LogControl1.xml
index 5738a3dda67..135e8bc8de0 100644
--- a/man/org.freedesktop.LogControl1.xml
+++ b/man/org.freedesktop.LogControl1.xml
@@ -89,7 +89,9 @@ node /org/freedesktop/LogControl1 {
       <citerefentry project="man-pages"><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> call).
       </para>
 
-      <para>Those two properties are writable, so they may be set by sufficiently privileged users.</para>
+      <caution><title>Write Access</title><para>The <varname>LogLevel</varname> and
+      <varname>LogTarget</varname> properties are supposed to be writable. Care should be taken to ensure
+      that only appropriately privileged clients can modify them.</para></caution>
 
       <para><varname>SyslogIdentifier</varname> is a read-only property that shows the "syslog identifier".
       It is a short string that identifies the program that is the source of log messages that is passed to
@@ -127,6 +129,11 @@ node /org/freedesktop/LogControl1 {
       <para>This creates a simple server on the bus. It implements the LogControl1 interface by providing
       the required properties and allowing to set the writable ones. It logs at the configured log level using
       <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+
+      <para>Note that when porting this example to other D-Bus libraries it might be necessary to add manual
+      client privilege checks, as they typically do not default to the restrictive defaults of sd-bus, where
+      unprivileged access to properties is controlled via the <constant>SD_BUS_VTABLE_UNPRIVILEGED</constant>
+      flag that is opt-in rather than opt-out.</para>
     </example>
   </refsect1>