Merge pull request #22663 from keszybz/various-man-page-bits

Various man page bits

man/journalctl.xml

@@ -85,10 +85,10 @@
       <option>--boot</option>, <option>--unit=</option>, etc., to
       further limit what entries will be shown (logical AND).</para>
 
-      <para>Output is interleaved from all accessible journal files,
+      <para>Output is interleaved from all accessible journal files, whether they are rotated or currently
-      whether they are rotated or currently being written, and
+      being written, and regardless of whether they belong to the system itself or are accessible user
-      regardless of whether they belong to the system itself or are
+      journals. The <option>--header</option> option can be used to identify which files
-      accessible user journals.</para>
+      <emphasis>are</emphasis> being shown.</para>
 
       <para>The set of journal files which will be used can be
       modified using the <option>--user</option>,
@@ -794,9 +794,11 @@
       <varlistentry>
         <term><option>--header</option></term>
 
-        <listitem><para>Instead of showing journal contents, show
+        <listitem><para>Instead of showing journal contents, show internal header information of the journal
-        internal header information of the journal fields
+        fields accessed.</para>
-        accessed.</para></listitem>
+
+        <para>This option is particularly useful when trying to identify out-of-order journal entries, as
+        happens for example when the machine is booted with the wrong system time.</para></listitem>
       </varlistentry>
 
       <varlistentry>

man/org.freedesktop.systemd1.xml

@@ -30,23 +30,19 @@
 
     <para>The service manager exposes a number of objects on the bus: one
     <interfacename>Manager</interfacename> object as a central entry point for clients along with individual objects
-    for each unit and for each queued job. The unit objects each implement a generic
+    for each unit and for each queued job. The unit objects implement a generic
     <interfacename>Unit</interfacename> interface as well as a type-specific interface. For example, service units
     implement both <interfacename>org.freedesktop.systemd1.Unit</interfacename> and
     <interfacename>org.freedesktop.system1.Service</interfacename>. The manager object can list
-    unit and job objects or directly convert a unit name or job id into a bus path of the corresponding
+    unit and job objects or directly convert a unit name or job identifier to a bus path of the corresponding
     D-Bus object.</para>
 
-    <para>Properties exposing time values are usually encoded in microseconds (usec) on the bus, even if
+    <para>Properties exposing time values are usually encoded in microseconds (µs) on the bus, even if
     their corresponding settings in the unit files are in seconds.</para>
 
-    <para>In contrast to most of the other services of the systemd suite, PID 1 does not use
+    <para>PID 1 uses <ulink url="https://www.freedesktop.org/software/polkit/docs/latest/">polkit</ulink> to
-    <ulink url="https://www.freedesktop.org/software/polkit/docs/latest/">polkit</ulink>
+    allow access to privileged operations for unprivileged processes. Some operations (such as
-    for controlling access to privileged operations, but relies exclusively on the low-level D-Bus policy
+    shutdown/reboot/suspend) are also available through the D-Bus API of logind, see
-    language. (This is done in order to avoid a cyclic dependency between polkit and systemd/PID 1.) This
-    means that sensitive operations exposed by PID 1 on the bus are generally not available to unprivileged
-    processes directly. However, some operations (such as shutdown/reboot/suspend) are made available through the D-Bus
-    API of logind, see
     <citerefentry><refentrytitle>org.freedesktop.login1</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
     </para>
   </refsect1>

man/rules/meson.build

@@ -158,6 +158,7 @@ manpages = [
    'SD_BUS_PROPERTY',
    'SD_BUS_SIGNAL',
    'SD_BUS_SIGNAL_WITH_NAMES',
+   'SD_BUS_VTABLE_CAPABILITY',
    'SD_BUS_VTABLE_END',
    'SD_BUS_VTABLE_START',
    'SD_BUS_WRITABLE_PROPERTY',

man/sd_bus_add_object.xml

@@ -22,6 +22,7 @@
     <refname>sd_bus_add_object_vtable</refname>
     <refname>sd_bus_add_fallback_vtable</refname>
     <refname>sd_bus_add_filter</refname>
+    <refname>SD_BUS_VTABLE_CAPABILITY</refname>
     <refname>SD_BUS_VTABLE_START</refname>
     <refname>SD_BUS_VTABLE_END</refname>
     <refname>SD_BUS_METHOD_WITH_NAMES_OFFSET</refname>
@@ -121,6 +122,10 @@
         <paramdef>void *<parameter>userdata</parameter></paramdef>
       </funcprototype>
 
+      <para>
+        <constant>SD_BUS_VTABLE_CAPABILITY(<replaceable>capability</replaceable>)</constant>
+      </para>
+
       <para>
         <constant>SD_BUS_VTABLE_START(<replaceable>flags</replaceable>)</constant>
       </para>
@@ -128,8 +133,7 @@
         <constant>SD_BUS_VTABLE_END</constant>
       </para>
       <para>
-        <constant>SD_BUS_METHOD_WITH_ARGS_OFFSET(
+        <constant>SD_BUS_METHOD_WITH_ARGS_OFFSET(<replaceable>member</replaceable>,
-        <replaceable>member</replaceable>,
         <replaceable>args</replaceable>,
         <replaceable>result</replaceable>,
         <replaceable>handler</replaceable>,
@@ -138,8 +142,7 @@
         </constant>
       </para>
       <para>
-        <constant>SD_BUS_METHOD_WITH_ARGS(
+        <constant>SD_BUS_METHOD_WITH_ARGS(<replaceable>member</replaceable>,
-        <replaceable>member</replaceable>,
         <replaceable>args</replaceable>,
         <replaceable>result</replaceable>,
         <replaceable>handler</replaceable>,
@@ -147,8 +150,7 @@
         </constant>
       </para>
       <para>
-        <constant>SD_BUS_METHOD_WITH_NAMES_OFFSET(
+        <constant>SD_BUS_METHOD_WITH_NAMES_OFFSET(<replaceable>member</replaceable>,
-        <replaceable>member</replaceable>,
         <replaceable>signature</replaceable>,
         <replaceable>in_names</replaceable>,
         <replaceable>result</replaceable>,
@@ -159,8 +161,7 @@
         </constant>
       </para>
       <para>
-        <constant>SD_BUS_METHOD_WITH_NAMES(
+        <constant>SD_BUS_METHOD_WITH_NAMES(<replaceable>member</replaceable>,
-        <replaceable>member</replaceable>,
         <replaceable>signature</replaceable>,
         <replaceable>in_names</replaceable>,
         <replaceable>result</replaceable>,
@@ -170,8 +171,7 @@
         </constant>
       </para>
       <para>
-        <constant>SD_BUS_METHOD_WITH_OFFSET(
+        <constant>SD_BUS_METHOD_WITH_OFFSET(<replaceable>member</replaceable>,
-        <replaceable>member</replaceable>,
         <replaceable>signature</replaceable>,
         <replaceable>result</replaceable>,
         <replaceable>handler</replaceable>,
@@ -180,8 +180,7 @@
         </constant>
       </para>
       <para>
-        <constant>SD_BUS_METHOD(
+        <constant>SD_BUS_METHOD(<replaceable>member</replaceable>,
-        <replaceable>member</replaceable>,
         <replaceable>signature</replaceable>,
         <replaceable>result</replaceable>,
         <replaceable>handler</replaceable>,
@@ -189,30 +188,26 @@
         </constant>
       </para>
       <para>
-        <constant>SD_BUS_SIGNAL_WITH_ARGS(
+        <constant>SD_BUS_SIGNAL_WITH_ARGS(<replaceable>member</replaceable>,
-        <replaceable>member</replaceable>,
         <replaceable>args</replaceable>,
         <replaceable>flags</replaceable>)
         </constant>
       </para>
       <para>
-        <constant>SD_BUS_SIGNAL_WITH_NAMES(
+        <constant>SD_BUS_SIGNAL_WITH_NAMES(<replaceable>member</replaceable>,
-        <replaceable>member</replaceable>,
         <replaceable>signature</replaceable>,
         <replaceable>names</replaceable>,
         <replaceable>flags</replaceable>)
         </constant>
       </para>
       <para>
-        <constant>SD_BUS_SIGNAL(
+        <constant>SD_BUS_SIGNAL(<replaceable>member</replaceable>,
-        <replaceable>member</replaceable>,
         <replaceable>signature</replaceable>,
         <replaceable>flags</replaceable>)
         </constant>
       </para>
       <para>
-        <constant>SD_BUS_WRITABLE_PROPERTY(
+        <constant>SD_BUS_WRITABLE_PROPERTY(<replaceable>member</replaceable>,
-        <replaceable>member</replaceable>,
         <replaceable>signature</replaceable>,
         <replaceable>get</replaceable>,
         <replaceable>set</replaceable>,
@@ -221,8 +216,7 @@
         </constant>
       </para>
       <para>
-        <constant>SD_BUS_PROPERTY(
+        <constant>SD_BUS_PROPERTY(<replaceable>member</replaceable>,
-        <replaceable>member</replaceable>,
         <replaceable>signature</replaceable>,
         <replaceable>get</replaceable>,
         <replaceable>offset</replaceable>,
@@ -231,9 +225,17 @@
       </para>
       <para>
         <constant>SD_BUS_PARAM(<replaceable>name</replaceable>)</constant>
+      </para>
+      <para>
         <constant>SD_BUS_ARGS(<replaceable>...</replaceable>)</constant>
+      </para>
+      <para>
         <constant>SD_BUS_RESULT(<replaceable>...</replaceable>)</constant>
+      </para>
+      <para>
         <constant>SD_BUS_NO_ARGS</constant>
+      </para>
+      <para>
         <constant>SD_BUS_NO_RESULT</constant>
       </para>
     </funcsynopsis>
@@ -337,10 +339,12 @@
 
       <variablelist>
         <varlistentry>
-          <term><constant>SD_BUS_VTABLE_START()</constant></term>
+          <term><constant>SD_BUS_VTABLE_START(<replaceable>flags</replaceable>)</constant></term>
           <term><constant>SD_BUS_VTABLE_END</constant></term>
 
-          <listitem><para>Those must always be the first and last element.</para></listitem>
+          <listitem><para>Those must always be the first and last element. The
+          <replaceable>flags</replaceable> parameter can be used to set attributes that apply to the whole
+          array; see the "Flags" section below.</para></listitem>
         </varlistentry>
 
         <varlistentry>
@@ -497,14 +501,6 @@
           hidden.</para></listitem>
         </varlistentry>
 
-        <varlistentry>
-          <term><constant>SD_BUS_VTABLE_UNPRIVILEGED</constant></term>
-
-          <listitem><para>Mark this vtable entry as unprivileged. If not specified, the
-          <constant>org.freedesktop.systemd1.Privileged</constant> annotation with value
-          <literal>true</literal> will be shown in introspection data.</para></listitem>
-        </varlistentry>
-
         <varlistentry>
           <term><constant>SD_BUS_VTABLE_METHOD_NO_REPLY</constant></term>
 
@@ -561,6 +557,48 @@
           passed directly, converted to a pointer, without taking the user data pointer specified during
           vtable registration into account.</para></listitem>
         </varlistentry>
+
+        <varlistentry>
+          <term><constant>SD_BUS_VTABLE_CAPABILITY(<replaceable>capability</replaceable>)</constant></term>
+
+          <listitem><para>Access to this vtable entry will be allowed if the calling proccess has the
+          capability <replaceable>capability</replaceable>, as described in
+          <citerefentry><refentrytitle>sd_bus_query_sender_privilege</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+          If used for <constant>SD_BUS_VTABLE_START()</constant>, provides a default for all entries in the
+          array. If not specified, either for an individual entry or the whole array,
+          <constant>CAP_SYS_ADMIN</constant> is checked by default. See <citerefentry
+          project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+          for information about capabilities.</para>
+
+          <para>Note that vtable entries may be marked as unprivileged and the whole bus may be marked as
+          trusted, see the discussion of <constant>SD_BUS_VTABLE_UNPRIVILEGED</constant> below.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><constant>SD_BUS_VTABLE_UNPRIVILEGED</constant></term>
+
+          <listitem><para>Mark this vtable entry as unprivileged. Access to privileged entries is limited to
+          users with appropriate capabilities as described above. In practice many vtable entries are marked
+          as unprivileged, and either are open to everyone, or the decision whether to allow access is taken
+          later, e.g. by delegating to <ulink
+          url="https://www.freedesktop.org/software/polkit/docs/latest/">polkit</ulink>.</para>
+
+          <para>The whole bus may be marked as trusted, in which case annotations at the entry level are
+          ignored, see
+          <citerefentry><refentrytitle>sd_bus_set_trusted</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+          </para>
+
+          <para>When <emphasis>not</emphasis> specified, the
+          <constant>org.freedesktop.systemd1.Privileged</constant> annotation with value
+          <literal>true</literal> will be shown in introspection data.</para>
+
+          <para>Note that this page describes checks implemented in the D-Bus client. The D-Bus server has an
+          additional policy that may permit or deny connections, see
+          "CONFIGURATION FILE" in
+          <citerefentry project='man-pages'><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+          </para></listitem>
+        </varlistentry>
       </variablelist>
     </refsect2>
   </refsect1>

man/systemd.journal-fields.xml

@@ -145,7 +145,7 @@
         <listitem>
           <para>A documentation URL with further information about the topic of the log message. Tools such
           as <command>journalctl</command> will include a hyperlink to an URL specified this way in their
-          output. Should be a <literal>http://</literal>, <literal>https://</literal>,
+          output. Should be an <literal>http://</literal>, <literal>https://</literal>,
           <literal>file:/</literal>, <literal>man:</literal> or <literal>info:</literal> URL.</para>
         </listitem>
       </varlistentry>
@@ -156,6 +156,21 @@
           <para>The numeric thread ID (TID) the log message originates from.</para>
         </listitem>
       </varlistentry>
+
+      <varlistentry>
+        <term><varname>UNIT=</varname></term>
+        <term><varname>USER_UNIT=</varname></term>
+        <listitem>
+          <para>The name of a unit. Used by the system and user managers when logging about specific
+          units.</para>
+
+          <para>When <option>--unit=<replaceable>name</replaceable></option> or
+          <option>--user-unit=<replaceable>name</replaceable></option> are used with
+          <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, a
+          match pattern that includes <literal>UNIT=<replaceable>name</replaceable>.service</literal> or
+          <literal>USER_UNIT=<replaceable>name</replaceable>.service</literal> will be generated.</para>
+        </listitem>
+      </varlistentry>
     </variablelist>
   </refsect1>
 

man/systemd.mount.xml

@@ -399,11 +399,13 @@
         <term><option>auto</option></term>
 
         <listitem><para>With <option>noauto</option>, the mount unit will not be added as a dependency for
-        <filename>local-fs.target</filename> or <filename>remote-fs.target</filename>. This means that it will not be
+        <filename>local-fs.target</filename> or <filename>remote-fs.target</filename>. This means that it
-        mounted automatically during boot, unless it is pulled in by some other unit. The <option>auto</option> option
+        will not be mounted automatically during boot, unless it is pulled in by some other unit. The
-        has the opposite meaning and is the default. Note that the <option>noauto</option> option has an effect on the
+        <option>auto</option> option has the opposite meaning and is the default.</para>
-        mount unit itself only — if <option>x-systemd.automount</option> is used (see above), then the matching
+
-        automount unit will still be pulled in by these targets.</para>
+        <para>Note that if <option>x-systemd.automount</option> (see above) is used, neither
+        <option>auto</option> nor <option>noauto</option> have any effect. The matching automount unit will
+        be added as a dependency to the appropriate target.</para>
         </listitem>
       </varlistentry>
 

man/systemd.unit.xml

@@ -126,13 +126,11 @@
     <literal>@</literal> and the unit type suffix. In the unit file itself, the instance parameter may be
     referred to using <literal>%i</literal> and other specifiers, see below.</para>
 
-    <para>Unit files may contain additional options on top of those
+    <para>Unit files may contain additional options on top of those listed here. If systemd encounters an
-    listed here. If systemd encounters an unknown option, it will
+    unknown option, it will write a warning log message but continue loading the unit. If an option or
-    write a warning log message but continue loading the unit. If an
+    section name is prefixed with <option>X-</option>, it is ignored completely by systemd. Options within an
-    option or section name is prefixed with <option>X-</option>, it is
+    ignored section do not need the prefix. Applications may use this to include additional information in
-    ignored completely by systemd. Options within an ignored section
+    the unit files. To access those options, applications need to parse the unit files on their own.</para>
-    do not need the prefix. Applications may use this to include
-    additional information in the unit files.</para>
 
     <para>Units can be aliased (have an alternative name), by creating a symlink from the new name to the
     existing name in one of the unit search paths. For example, <filename>systemd-networkd.service</filename>

src/libsystemd/sd-bus/bus-objects.c

@@ -315,11 +315,9 @@ static int check_access(sd_bus *bus, sd_bus_message *m, struct vtable_member *c,
         if (c->vtable->flags & SD_BUS_VTABLE_UNPRIVILEGED)
                 return 0;
 
-        /* Check have the caller has the requested capability
+        /* Check that the caller has the requested capability set. Note that the flags value contains the
-         * set. Note that the flags value contains the capability
+         * capability number plus one, which we need to subtract here. We do this so that we have 0 as
-         * number plus one, which we need to subtract here. We do this
+         * special value for the default. */
-         * so that we have 0 as special value for "default
-         * capability". */
         cap = CAPABILITY_SHIFT(c->vtable->flags);
         if (cap == 0)
                 cap = CAPABILITY_SHIFT(c->parent->vtable[0].flags);