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

Various man page bits
journalctl: advertise --header a bit more
2026-04-22 06:54:51 +02:00 · 2022-03-04 18:16:46 +01:00 · 2022-03-04 16:44:02 +01:00 · 2022-03-04 16:44:02 +01:00 · 2022-03-04 16:07:19 +01:00 · 2022-03-04 15:43:18 +01:00
8 changed files with 117 additions and 67 deletions
--- a/man/journalctl.xml
+++ b/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,
-      whether they are rotated or currently being written, and
-      regardless of whether they belong to the system itself or are
-      accessible user journals.</para>
+      <para>Output is interleaved from all accessible journal files, whether they are rotated or currently
+      being written, and regardless of whether they belong to the system itself or are accessible user
+      journals. The <option>--header</option> option can be used to identify which files
+      <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
-        internal header information of the journal fields
-        accessed.</para></listitem>
+        <listitem><para>Instead of showing journal contents, show internal header information of the journal
+        fields accessed.</para>
+
+        <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>
--- a/man/org.freedesktop.systemd1.xml
+++ b/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
-    <ulink url="https://www.freedesktop.org/software/polkit/docs/latest/">polkit</ulink>
-    for controlling access to privileged operations, but relies exclusively on the low-level D-Bus policy
-    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
+    <para>PID 1 uses <ulink url="https://www.freedesktop.org/software/polkit/docs/latest/">polkit</ulink> to
+    allow access to privileged operations for unprivileged processes. Some operations (such as
+    shutdown/reboot/suspend) are also available through the D-Bus API of logind, see
    <citerefentry><refentrytitle>org.freedesktop.login1</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
    </para>
  </refsect1>
--- a/man/rules/meson.build
+++ b/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',
--- a/man/sd_bus_add_object.xml
+++ b/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(
-        <replaceable>member</replaceable>,
+        <constant>SD_BUS_METHOD_WITH_ARGS_OFFSET(<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(
-        <replaceable>member</replaceable>,
+        <constant>SD_BUS_METHOD_WITH_ARGS(<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(
-        <replaceable>member</replaceable>,
+        <constant>SD_BUS_METHOD_WITH_NAMES_OFFSET(<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(
-        <replaceable>member</replaceable>,
+        <constant>SD_BUS_METHOD_WITH_NAMES(<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(
-        <replaceable>member</replaceable>,
+        <constant>SD_BUS_METHOD_WITH_OFFSET(<replaceable>member</replaceable>,
        <replaceable>signature</replaceable>,
        <replaceable>result</replaceable>,
        <replaceable>handler</replaceable>,
@ -180,8 +180,7 @@
        </constant>
      </para>
      <para>
-        <constant>SD_BUS_METHOD(
-        <replaceable>member</replaceable>,
+        <constant>SD_BUS_METHOD(<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(
-        <replaceable>member</replaceable>,
+        <constant>SD_BUS_SIGNAL_WITH_ARGS(<replaceable>member</replaceable>,
        <replaceable>args</replaceable>,
        <replaceable>flags</replaceable>)
        </constant>
      </para>
      <para>
-        <constant>SD_BUS_SIGNAL_WITH_NAMES(
-        <replaceable>member</replaceable>,
+        <constant>SD_BUS_SIGNAL_WITH_NAMES(<replaceable>member</replaceable>,
        <replaceable>signature</replaceable>,
        <replaceable>names</replaceable>,
        <replaceable>flags</replaceable>)
        </constant>
      </para>
      <para>
-        <constant>SD_BUS_SIGNAL(
-        <replaceable>member</replaceable>,
+        <constant>SD_BUS_SIGNAL(<replaceable>member</replaceable>,
        <replaceable>signature</replaceable>,
        <replaceable>flags</replaceable>)
        </constant>
      </para>
      <para>
-        <constant>SD_BUS_WRITABLE_PROPERTY(
-        <replaceable>member</replaceable>,
+        <constant>SD_BUS_WRITABLE_PROPERTY(<replaceable>member</replaceable>,
        <replaceable>signature</replaceable>,
        <replaceable>get</replaceable>,
        <replaceable>set</replaceable>,
@ -221,8 +216,7 @@
        </constant>
      </para>
      <para>
-        <constant>SD_BUS_PROPERTY(
-        <replaceable>member</replaceable>,
+        <constant>SD_BUS_PROPERTY(<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>
--- a/man/systemd.journal-fields.xml
+++ b/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>

--- a/man/systemd.mount.xml
+++ b/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
-        mounted automatically during boot, unless it is pulled in by some other unit. The <option>auto</option> option
-        has the opposite meaning and is the default. Note that the <option>noauto</option> option has an effect on the
-        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>
+        <filename>local-fs.target</filename> or <filename>remote-fs.target</filename>. This means that it
+        will not be mounted automatically during boot, unless it is pulled in by some other unit. The
+        <option>auto</option> option has the opposite meaning and is the default.</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>

--- a/man/systemd.unit.xml
+++ b/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
-    listed here. If systemd encounters an unknown option, it will
-    write a warning log message but continue loading the unit. If an
-    option or section name is prefixed with <option>X-</option>, it is
-    ignored completely by systemd. Options within an ignored section
-    do not need the prefix. Applications may use this to include
-    additional information in the unit files.</para>
+    <para>Unit files may contain additional options on top of those listed here. If systemd encounters an
+    unknown option, it will write a warning log message but continue loading the unit. If an option or
+    section name is prefixed with <option>X-</option>, it is ignored completely by systemd. Options within an
+    ignored section do not need the prefix. Applications may use this to include additional information in
+    the unit files. To access those options, applications need to parse the unit files on their own.</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>
--- a/src/libsystemd/sd-bus/bus-objects.c
+++ b/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
-         * set. Note that the flags value contains the capability
-         * number plus one, which we need to subtract here. We do this
-         * so that we have 0 as special value for "default
-         * capability". */
+        /* Check that the caller has the requested capability set. Note that the flags value contains the
+         * capability number plus one, which we need to subtract here. We do this so that we have 0 as
+         * special value for the default. */
        cap = CAPABILITY_SHIFT(c->vtable->flags);
        if (cap == 0)
                cap = CAPABILITY_SHIFT(c->parent->vtable[0].flags);
Author	SHA1	Message	Date
Zbigniew Jędrzejewski-Szmek	af5e1c5bd1	Merge pull request #22663 from keszybz/various-man-page-bits Various man page bits	2022-03-04 18:16:46 +01:00
Zbigniew Jędrzejewski-Szmek	367a5e8a67	journalctl: advertise --header a bit more Fixes #2738.	2022-03-04 16:44:02 +01:00
Zbigniew Jędrzejewski-Szmek	c1d1742a7f	man: describe UNIT=/USER_UNIT= Fixes 17538.	2022-03-04 16:44:02 +01:00
Zbigniew Jędrzejewski-Szmek	55fabe92e2	man: tweak description of auto/noauto I think the current behaviour is stupid: 'x-systemd.automount,noauto' should mean that we create the units, but don't add .mount or .automount to any targets. Instead, we completely ignore 'noauto'. But let's at least describe the implementation. Text suggested by dpartrid in the bug. Fixes #21040.	2022-03-04 16:07:19 +01:00
Zbigniew Jędrzejewski-Szmek	b4e7d7555e	man: describe capability checks on the bus A description of SD_BUS_VTABLE_CAPABILITY is added, and the discussion on SD_BUS_VTABLE_UNPRIVILEGED in expanded. I think it would be nice to add longer description of how access is checked (maybe in sd-bus(3)), but I'm leaving that for later. I think the text that was added here describes everything, even if tersely. Fixes #21882.	2022-03-04 15:43:18 +01:00
Zbigniew Jędrzejewski-Szmek	3c080282e9	man: fix formatting of macros in sd_bus_add_object docbook would convert the newline to a space before the first argument: SD_BUS_METHOD_WITH_ARGS( member, args, result, handler) And we need each item in a separate <para>, otherwise they'll all be in one line.	2022-03-04 15:23:17 +01:00
Zbigniew Jędrzejewski-Szmek	382586894b	man: say that we ignore ignored options Fixes #22057.	2022-03-04 14:13:56 +01:00
Zbigniew Jędrzejewski-Szmek	46d362f406	man: drop outdated info about polkit in pid1 Fixes #22648.	2022-03-04 14:03:50 +01:00