v252 batch up to 7ef330925ab434a64533c5457b2de7d5df66534f

.github/workflows/mkosi.yml

@@ -60,6 +60,9 @@ jobs:
 
     - name: Configure
       run: |
+        # mkosi GHA clones and builds from main but tools are not compatible with this branch, 24.04 ships 255 which is enough
+        sudo apt install --reinstall systemd systemd-container systemd-boot systemd-ukify
+
         tee mkosi.default <<- EOF
         [Distribution]
         Distribution=${{ matrix.distro }}

man/common-variables.xml

@@ -83,17 +83,22 @@
 
     <varlistentry id='pager'>
       <term><varname>$SYSTEMD_PAGER</varname></term>
+      <term><varname>$PAGER</varname></term>
 
-      <listitem><para>Pager to use when <option>--no-pager</option> is not given; overrides
-      <varname>$PAGER</varname>. If neither <varname>$SYSTEMD_PAGER</varname> nor <varname>$PAGER</varname> are set, a
-      set of well-known pager implementations are tried in turn, including
-      <citerefentry project='man-pages'><refentrytitle>less</refentrytitle><manvolnum>1</manvolnum></citerefentry> and
-      <citerefentry project='man-pages'><refentrytitle>more</refentrytitle><manvolnum>1</manvolnum></citerefentry>, until one is found. If
-      no pager implementation is discovered no pager is invoked. Setting this environment variable to an empty string
-      or the value <literal>cat</literal> is equivalent to passing <option>--no-pager</option>.</para>
+      <listitem><para>Pager to use when <option>--no-pager</option> is not given.
+      <varname>$SYSTEMD_PAGER</varname> is used if set; otherwise <varname>$PAGER</varname> is used.
+      If neither <varname>$SYSTEMD_PAGER</varname> nor <varname>$PAGER</varname> are set, a set of well-known
+      pager implementations is tried in turn, including
+      <citerefentry project='man-pages'><refentrytitle>less</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+      and
+      <citerefentry project='man-pages'><refentrytitle>more</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      until one is found. If no pager implementation is discovered, no pager is invoked. Setting those
+      environment variables to an empty string or the value <literal>cat</literal> is equivalent to passing
+      <option>--no-pager</option>.</para>
 
       <para>Note: if <varname>$SYSTEMD_PAGERSECURE</varname> is not set, <varname>$SYSTEMD_PAGER</varname>
-      (as well as <varname>$PAGER</varname>) will be silently ignored.</para></listitem>
+      and <varname>$PAGER</varname> can only be used to disable the pager (with <literal>cat</literal> or
+      <literal></literal>), and are otherwise ignored.</para></listitem>
     </varlistentry>
 
     <varlistentry id='less'>
@@ -150,28 +155,53 @@
     <varlistentry id='lesssecure'>
       <term><varname>$SYSTEMD_PAGERSECURE</varname></term>
 
-      <listitem><para>Takes a boolean argument. When true, the "secure" mode of the pager is enabled; if
-      false, disabled. If <varname>$SYSTEMD_PAGERSECURE</varname> is not set at all, secure mode is enabled
-      if the effective UID is not the same as the owner of the login session, see
-      <citerefentry project='man-pages'><refentrytitle>geteuid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
-      and <citerefentry><refentrytitle>sd_pid_get_owner_uid</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
-      In secure mode, <option>LESSSECURE=1</option> will be set when invoking the pager, and the pager shall
-      disable commands that open or create new files or start new subprocesses. When
-      <varname>$SYSTEMD_PAGERSECURE</varname> is not set at all, pagers which are not known to implement
-      secure mode will not be used. (Currently only
-      <citerefentry project='man-pages'><refentrytitle>less</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-      implements secure mode.)</para>
-
-      <para>Note: when commands are invoked with elevated privileges, for example under <citerefentry
+      <listitem>
+      <para>Common pager commands like <citerefentry
+      project='man-pages'><refentrytitle>less</refentrytitle><manvolnum>1</manvolnum></citerefentry>, in
+      addition to "paging", i.e. scrolling through the output, support opening of or writing to other files
+      and running arbitrary shell commands. When commands are invoked with elevated privileges, for example
+      under <citerefentry
       project='man-pages'><refentrytitle>sudo</refentrytitle><manvolnum>8</manvolnum></citerefentry> or
       <citerefentry
-      project='die-net'><refentrytitle>pkexec</refentrytitle><manvolnum>1</manvolnum></citerefentry>, care
-      must be taken to ensure that unintended interactive features are not enabled. "Secure" mode for the
-      pager may be enabled automatically as describe above. Setting <varname>SYSTEMD_PAGERSECURE=0</varname>
-      or not removing it from the inherited environment allows the user to invoke arbitrary commands. Note
-      that if the <varname>$SYSTEMD_PAGER</varname> or <varname>$PAGER</varname> variables are to be
-      honoured, <varname>$SYSTEMD_PAGERSECURE</varname> must be set too. It might be reasonable to completely
-      disable the pager using <option>--no-pager</option> instead.</para></listitem>
+      project='die-net'><refentrytitle>pkexec</refentrytitle><manvolnum>1</manvolnum></citerefentry>, the
+      pager becomes a security boundary. Care must be taken that only programs with strictly limited
+      functionality are used as pagers, and unintended interactive features like opening or creation of new
+      files or starting of subprocesses are not allowed. "Secure mode" for the pager may be enabled as
+      described below, <emphasis>if the pager supports that</emphasis> (most pagers are not written in a way
+      that takes this into consideration). It is recommended to either explicitly enable "secure mode" or to
+      completely disable the pager using <option>--no-pager</option> or <varname>PAGER=cat</varname> when
+      allowing untrusted users to execute commands with elevated privileges.</para>
+
+      <para>This option takes a boolean argument. When set to true, the "secure mode" of the pager is
+      enabled. In "secure mode", <option>LESSSECURE=1</option> will be set when invoking the pager, which
+      instructs the pager to disable commands that open or create new files or start new subprocesses.
+      Currently only <citerefentry
+      project='man-pages'><refentrytitle>less</refentrytitle><manvolnum>1</manvolnum></citerefentry> is known
+      to understand this variable and implement "secure mode".</para>
+
+      <para>When set to false, no limitation is placed on the pager. Setting
+      <varname>SYSTEMD_PAGERSECURE=0</varname> or not removing it from the inherited environment may allow
+      the user to invoke arbitrary commands.</para>
+
+      <para>When <varname>$SYSTEMD_PAGERSECURE</varname> is not set, systemd tools attempt to automatically
+      figure out if "secure mode" should be enabled and whether the pager supports it. "Secure mode" is
+      enabled if the effective UID is not the same as the owner of the login session, see
+      <citerefentry project='man-pages'><refentrytitle>geteuid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+      and
+      <citerefentry><refentrytitle>sd_pid_get_owner_uid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      or when running under
+      <citerefentry><refentrytitle>sudo</refentrytitle><manvolnum>8</manvolnum></citerefentry> or similar
+      tools (<varname>$SUDO_UID</varname> is set <footnote>
+      <para>It is recommended for other tools to set and check <varname>$SUDO_UID</varname> as appropriate,
+      treating it is a common interface.</para></footnote>). In those cases,
+      <varname>SYSTEMD_PAGERSECURE=1</varname> will be set and pagers which are not known to implement
+      "secure mode" will not be used at all. Note that this autodetection only covers the most common
+      mechanisms to elevate privileges and is intended as convenience. It is recommended to explicitly set
+      <varname>$SYSTEMD_PAGERSECURE</varname> or disable the pager.</para>
+
+      <para>Note that if the <varname>$SYSTEMD_PAGER</varname> or <varname>$PAGER</varname> variables are to
+      be honoured, other than to disable the pager, <varname>$SYSTEMD_PAGERSECURE</varname> must be set
+      too.</para></listitem>
     </varlistentry>
 
     <varlistentry id='colors'>

man/org.freedesktop.systemd1.xml

@@ -8007,7 +8007,7 @@ node /org/freedesktop/systemd1/unit/systemd_2dtmpfiles_2dclean_2etimer {
       elapsation point on the <constant>CLOCK_REALTIME</constant> clock, relative to its epoch.</para>
 
       <para><varname>NextElapseUSecRealtime</varname> contains the next elapsation point on the
-      <constant>CLOCK_REALTIME</constant> clock in miscroseconds since the epoch, or 0 if this timer event
+      <constant>CLOCK_REALTIME</constant> clock in microseconds since the epoch, or 0 if this timer event
       does not include at least one calendar event.</para>
 
       <para>Similarly, <varname>NextElapseUSecMonotonic</varname> contains the next elapsation point on the

man/sd_bus_emit_signal.xml

@@ -67,7 +67,7 @@
         <funcdef>int <function>sd_bus_emit_interfaces_added_strv</function></funcdef>
         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
         <paramdef>const char *<parameter>path</parameter></paramdef>
-        <paramdef>const char **<parameter>interfaces</parameter></paramdef>
+        <paramdef>char **<parameter>interfaces</parameter></paramdef>
       </funcprototype>
 
       <funcprototype>
@@ -82,7 +82,7 @@
         <funcdef>int <function>sd_bus_emit_interfaces_removed_strv</function></funcdef>
         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
         <paramdef>const char *<parameter>path</parameter></paramdef>
-        <paramdef>const char **<parameter>interfaces</parameter></paramdef>
+        <paramdef>char **<parameter>interfaces</parameter></paramdef>
       </funcprototype>
 
       <funcprototype>
@@ -99,7 +99,7 @@
         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
         <paramdef>const char *<parameter>path</parameter></paramdef>
         <paramdef>const char *<parameter>interface</parameter></paramdef>
-        <paramdef>const char **<parameter>names</parameter></paramdef>
+        <paramdef>char **<parameter>names</parameter></paramdef>
       </funcprototype>
 
       <funcprototype>

man/sd_bus_slot_set_floating.xml

@@ -51,8 +51,8 @@
     referenced bus slot object around. The floating state hence controls the direction of referencing between the bus
     object and the bus slot objects: if floating the bus pins the bus slot, and otherwise the bus slot pins the bus
     objects. Use <function>sd_bus_slot_set_floating()</function> to switch between both modes: if the
-    <parameter>b</parameter> parameter is zero, the slot object is considered floating, otherwise it is made a regular
-    (non-floating) slot object.</para>
+    <parameter>b</parameter> parameter is zero, the slot object is made into a regular (non-floating) slot object,
+    otherwise it is made into a floating slot object.</para>
 
     <para>Bus slot objects may be allocated with calls such as
     <citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If the

man/systemctl.xml

@@ -139,10 +139,9 @@ binfmt_misc /proc/sys/fs/binfmt_misc yes     0            proc-sys-fs-binfmt_mis
             shown. Produces output similar to
             <programlisting>
 LISTEN           UNIT                        ACTIVATES
-/dev/initctl     systemd-initctl.socket      systemd-initctl.service
-…
-[::]:22          sshd.socket                 sshd.service
 kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
+/dev/rfkill      systemd-rfkill.socket       systemd-rfkill.service
+…
 
 5 sockets listed.</programlisting>
             Note: because the addresses might contains spaces, this output
@@ -837,7 +836,7 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err
           <term><command>preset <replaceable>UNIT</replaceable>…</command></term>
 
           <listitem>
-            <para>Reset the enable/disable status one or more unit files, as specified on
+            <para>Reset the enable/disable status of one or more unit files, as specified on
             the command line, to the defaults configured in the preset policy files. This
             has the same effect as <command>disable</command> or
             <command>enable</command>, depending how the unit is listed in the preset

man/systemd-networkd.service.xml

@@ -33,12 +33,16 @@
     manages networks. It detects and configures network devices as
     they appear, as well as creating virtual network devices.</para>
 
-    <para>To configure low-level link settings independently of
-    networks, see
-    <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
-
-    <para><command>systemd-networkd</command> will create network devices based
-    on the configuration in
+    <para>Certain low-level settings of physical network devices (e.g. device
+    names and altnames) as well as the creation of SR-IOV virtual functions on
+    physical network interfaces may be managed by
+    <citerefentry><refentrytitle>systemd-udevd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    according to the contents of
+    <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+    files.</para>
+
+    <para><command>systemd-networkd</command> will create "virtual" network
+    devices (e.g. bridges and tunnels) based on the configuration in
     <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry>
     files, respecting the [Match] sections in those files.</para>
 
@@ -47,10 +51,10 @@
     with an appropriate [Match] section, see
     <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
     For those links, it will flush existing network addresses and routes when
-    bringing up the device. Any links not matched by one of the
-    <filename>.network</filename> files will be ignored. It is also possible to
-    explicitly tell <filename>systemd-networkd</filename> to ignore a link by
-    using <varname>Unmanaged=yes</varname> option, see
+    bringing up the device (except when directed not to). Any links not matched
+    by one of the <filename>.network</filename> files will be ignored. It is
+    also possible to explicitly tell <filename>systemd-networkd</filename> to
+    ignore a link by using the <varname>Unmanaged=yes</varname> option, see
     <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
     </para>
 

man/systemd-remount-fs.service.xml

@@ -51,7 +51,7 @@
     <para>Note: <filename>systemd-remount-fs.service</filename> is usually pulled in by
     <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
     hence it is also affected by the kernel command line option <varname>fstab=</varname>, which may be used
-    to disable the generator. It may also pulled in by
+    to disable the generator. It may also be pulled in by
     <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
     which is affected by <varname>systemd.gpt_auto</varname> and other options.</para>
   </refsect1>

man/systemd.link.xml

@@ -32,6 +32,11 @@
     <citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>7</manvolnum></citerefentry> for a
     general description of the syntax.</para>
 
+    <para>Note that some distributions may incorporate <filename>.link</filename> files in their early boot
+    facilities (e.g. by including copies of the <filename>.link</filename> files in initramfs). As such it
+    may be necessary to take manual steps to ensure that any local changes are consistent with early-boot
+    storage facilities. The relevant distribution-specific documentation should be consulted.</para>
+
     <para>The <filename>.link</filename> files are read from the files located in the system network
     directory <filename>/usr/lib/systemd/network</filename> and
     <filename>/usr/local/lib/systemd/network</filename>, the volatile runtime network directory
@@ -1018,11 +1023,18 @@
 
   <refsect1 id='sr-iov'>
     <title>[SR-IOV] Section Options</title>
-    <para>The [SR-IOV] section accepts the following keys. Specify several [SR-IOV] sections to
-    configure several SR-IOVs. SR-IOV provides the ability to partition a single physical PCI resource
-    into virtual PCI functions which can then be injected into a VM. In the case of network VFs, SR-IOV
-    improves north-south network performance (that is, traffic with endpoints outside the host machine)
-    by allowing traffic to bypass the host machine’s network stack.</para>
+    <para>SR-IOV provides the ability to partition a single physical PCI resource into virtual PCI
+    functions which can then be e.g. injected into a VM. In the case of network VFs, SR-IOV reduces
+    latency and CPU utilisation for north-south network traffic (that is, traffic with endpoints
+    outside the host machine), by allowing traffic to bypass the host machine’s network stack.
+    </para>
+
+    <para>The presence of an [SR-IOV] section in a .link file will cause the creation and
+    configuration of the specified virtual function. Within a .network file, the specified virtual
+    function will be configured, but must already exist. Specify several [SR-IOV] sections to
+    configure several SR-IOVs.</para>
+
+    <para>The [SR-IOV] section accepts the following keys.</para>
 
     <variablelist class='network-directives'>
       <varlistentry>

man/systemd.network.xml

@@ -37,6 +37,14 @@
     <para>The main network file must have the extension <filename>.network</filename>; other
     extensions are ignored. Networks are applied to links whenever the links appear.</para>
 
+    <para>Note that not all settings and configurations can be made with <filename>.network</filename>
+    files, and that it may be necessary to use
+    <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>)
+    or
+    <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry>)
+    files in conjuction with <filename>.network</filename> files when working with physical and virtual
+    network devices respectively.</para>
+
     <para>The <filename>.network</filename> files are read from the files located in the system network
     directories <filename>/usr/lib/systemd/network</filename> and
     <filename>/usr/local/lib/systemd/network</filename>, the volatile runtime network directory

man/systemd.swap.xml

@@ -72,7 +72,7 @@
 
       <itemizedlist>
         <listitem><para>All swap units automatically get the
-        <varname>BindsTo=</varname> and <varname>After=</varname>
+        <varname>Requires=</varname> and <varname>After=</varname>
         dependencies on the device units or the mount units of the files
         they are activated from.</para></listitem>
       </itemizedlist>

man/systemd.xml

@@ -976,12 +976,9 @@
         <term><varname>5</varname></term>
 
         <listitem><para>Boot into the specified legacy SysV runlevel.
-        These are equivalent to
-        <varname>systemd.unit=runlevel2.target</varname>,
-        <varname>systemd.unit=runlevel3.target</varname>,
-        <varname>systemd.unit=runlevel4.target</varname>, and
-        <varname>systemd.unit=runlevel5.target</varname>,
-        respectively, and provided for compatibility reasons and to be
+        <varname>2</varname>, <varname>3</varname>, and <varname>4</varname> are equivalent to
+        <varname>systemd.unit=multi-user.target</varname>; and <varname>5</varname> is equivalent to
+        <varname>systemd.unit=graphical.target</varname>, and provided for compatibility reasons and to be
         easier to type.</para></listitem>
       </varlistentry>
 

shell-completion/zsh/_systemctl.in

@@ -408,7 +408,7 @@ for fun in set-environment unset-environment ; do
             suf='-S='
         fi
         _wanted systemd-environment expl 'environment variable' \
-                compadd "$@" ${suf} - ${${(f)"$(systemctl show-environment)"}%%=*}
+                compadd "$@" ${suf} - ${${(f)"$(systemctl "$_sys_service_mgr" show-environment)"}%%=*}
     }
 done