Merge pull request #14590 from poettering/doc-fixlets

A bunch of documentation fixes

docs/BOOT_LOADER_SPECIFICATION.md

@@ -91,6 +91,20 @@ from the user. Only entries matching the feature set of boot loader and system
 shall be considered and displayed. This allows image builders to put together
 images that transparently support multiple different architectures.
 
+Note that the `$BOOT` partition is not supposed to be exclusive territory of
+this specification. This specification only defines semantics of the `/loader/`
+directory inside the file system (see below), but it doesn't intend to define
+ownership of the whole file system exclusively. Boot loaders, firmware, and
+other software implementating this specification may choose to place other
+files and directories in the same file system. For example, boot loaders that
+implement this specification might install their own boot code into the `$BOOT`
+partition. On systems where `$BOOT` is the ESP this is a particularly common
+setup. Implementations of this specification must be able to operate correctly
+if files or directories other than `/loader/` are found in the top level
+directory. Implementations that add their own files or directories to the file
+systems should use well-named directories, to make name collisions between
+multiple users of the file system unlikely.
+
 ### Type #1 Boot Loader Specification Entries
 
 We define two directories below `$BOOT`:

docs/PORTABILITY_AND_STABILITY.md

@@ -4,7 +4,7 @@ category: Interfaces
 layout: default
 ---
 
-# Interface Stability Promise
+# Interface Portability and Stability Promise
 
 systemd provides various interfaces developers and programs might rely on. Starting with version 26 (the first version released with Fedora 15) we promise to keep a number of them stable and compatible for the future.
 
@@ -41,7 +41,7 @@ What does this mean for you? When developing with systemd, don't use any of the
 Note that this is a promise, not an eternal guarantee. These are our intentions, but if in the future there are very good reasons to change or get rid of an interface we have listed above as stable, then we might take the liberty to do so, despite this promise. However, if we do this, then we'll do our best to provide a smooth and reasonably long transition phase.
 
 
-# Interface Portability And Stability Chart
+## Interface Portability And Stability Chart
 
 systemd provides a number of APIs to applications. Below you'll find a table detailing which APIs are considered stable and how portable they are.
 
@@ -72,11 +72,9 @@ A number of systemd's APIs expose Linux or systemd-specific features that cannot
 Note that not all of these interfaces are our invention (but most), we just adopted them in systemd to make them more prominently implemented. For example, we adopted many Debian facilities in systemd to push it into the other distributions as well.
 
 
-
 ---
 
 
-
 And now, here's the list of (hopefully) all APIs that we have introduced with systemd:
 
 | API  | Type | Covered by Interface Stability Promise | Fully documented | Known External Consumers | Reimplementable Independently | Known Other Implementations | systemd Implementation portable to other OSes or non-systemd distributions |
@@ -136,7 +134,7 @@ This is not an attempt to comprehensively list all users of these APIs. We are j
 
 Of course, one last thing I can't make myself not ask you before we finish here, and before you start reimplementing these APIs in your distribution: are you sure it's time well spent if you work on reimplementing all this code instead of just spending it on adopting systemd on your distro as well?
 
-## Independent operation of systemd programs
+## Independent Operation of systemd Programs
 
 Some programs in the systemd suite are indended to operate independently of the
 running init process (or even without an init process, for example when

man/halt.xml

@@ -41,9 +41,8 @@
   <refsect1>
     <title>Description</title>
 
-    <para><command>halt</command>, <command>poweroff</command>,
-    <command>reboot</command> may be used to halt, power-off or reboot
-    the machine.</para>
+    <para><command>halt</command>, <command>poweroff</command>, <command>reboot</command> may be used to
+    halt, power-off, or reboot the machine. All three commands take the same options.</para>
 
   </refsect1>
 
@@ -137,12 +136,15 @@
   <refsect1>
     <title>Notes</title>
 
-    <para>These commands are implemented in a way that preserves compatibility with
-    the original SysV commands.
-    <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-    verbs <command>halt</command>, <command>poweroff</command>,
-    <command>reboot</command> provide the same functionality with some additional
-    features.</para>
+    <para>These commands are implemented in a way that preserves basic compatibility with the original SysV
+    commands.  <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+    verbs <command>halt</command>, <command>poweroff</command>, <command>reboot</command> provide the same
+    functionality with some additional features.</para>
+
+    <para>Note that on many SysV systems <command>halt</command> used to be synonymous to
+    <command>poweroff</command>, i.e. both commands would equally result in powering the machine off. systemd
+    is more accurate here, and <command>halt</command> results in halting the machine only (leaving power
+    on), and <command>poweroff</command> is required to actually power it off.</para>
   </refsect1>
 
   <refsect1>

man/systemd-fstab-generator.xml

@@ -98,9 +98,13 @@
       <varlistentry>
         <term><varname>rootflags=</varname></term>
 
-        <listitem><para>Takes the root filesystem mount options to
-        use. <varname>rootflags=</varname> is honored by the
-        initrd.</para></listitem>
+        <listitem><para>Takes the root filesystem mount options to use. <varname>rootflags=</varname> is
+        honored by the initrd.</para>
+
+        <para>Note that unlike most kernel command line options this setting does not override settings made
+        in configuration files (specifically: the mount option string in
+        <filename>/etc/fstab</filename>). See
+        <citerefentry><refentrytitle>systemd-remount-fs.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para></listitem>
       </varlistentry>
 
       <varlistentry>

man/systemd-system.conf.xml

@@ -382,30 +382,14 @@
         <term><varname>DefaultLimitRTPRIO=</varname></term>
         <term><varname>DefaultLimitRTTIME=</varname></term>
 
-        <listitem><para>These settings control various default
-        resource limits for units. See
-        <citerefentry><refentrytitle>setrlimit</refentrytitle><manvolnum>2</manvolnum></citerefentry>
-        for details. The resource limit is possible to specify in two formats,
-        <option>value</option> to set soft and hard limits to the same value,
-        or <option>soft:hard</option> to set both limits individually (e.g. DefaultLimitAS=4G:16G).
-        Use the string <varname>infinity</varname> to
-        configure no limit on a specific resource. The multiplicative
-        suffixes K (=1024), M (=1024*1024) and so on for G, T, P and E
-        may be used for resource limits measured in bytes
-        (e.g. DefaultLimitAS=16G). For the limits referring to time values,
-        the usual time units ms, s, min, h and so on may be used (see
-        <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>
-        for details). Note that if no time unit is specified for
-        <varname>DefaultLimitCPU=</varname> the default unit of seconds is
-        implied, while for <varname>DefaultLimitRTTIME=</varname> the default
-        unit of microseconds is implied. Also, note that the effective
-        granularity of the limits might influence their
-        enforcement. For example, time limits specified for
-        <varname>DefaultLimitCPU=</varname> will be rounded up implicitly to
-        multiples of 1s. These  settings may be overridden in individual units
-        using the corresponding LimitXXX= directives. Note that these resource
-        limits are only defaults for units, they are not applied to PID 1
-        itself.</para></listitem>
+        <listitem><para>These settings control various default resource limits for processes executed by
+        units. See
+        <citerefentry><refentrytitle>setrlimit</refentrytitle><manvolnum>2</manvolnum></citerefentry> for
+        details. These settings may be overridden in individual units using the corresponding
+        <varname>LimitXXX=</varname> directives, see
+        <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, for
+        details, and they accept the same parameter syntax. Note that these resource limits are only defaults
+        for units, they are not applied to the service manager process (i.e. PID 1) itself.</para></listitem>
       </varlistentry>
 
       <varlistentry>

man/systemd.exec.xml

@@ -221,12 +221,13 @@
         Linux systems.</para>
 
         <para>When used in conjunction with <varname>DynamicUser=</varname> the user/group name specified is
-        dynamically allocated at the time the service is started, and released at the time the service is stopped —
-        unless it is already allocated statically (see below). If <varname>DynamicUser=</varname> is not used the
-        specified user and group must have been created statically in the user database no later than the moment the
-        service is started, for example using the
-        <citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> facility, which
-        is applied at boot or package install time.</para>
+        dynamically allocated at the time the service is started, and released at the time the service is
+        stopped — unless it is already allocated statically (see below). If <varname>DynamicUser=</varname>
+        is not used the specified user and group must have been created statically in the user database no
+        later than the moment the service is started, for example using the
+        <citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+        facility, which is applied at boot or package install time. If the user does not exist by then
+        program invocation will fail.</para>
 
         <para>If the <varname>User=</varname> setting is used the supplementary group list is initialized
         from the specified user's default group list, as defined in the system's user and group
@@ -497,42 +498,51 @@ CapabilityBoundingSet=~CAP_B CAP_C</programlisting>
         <term><varname>LimitRTTIME=</varname></term>
 
         <listitem><para>Set soft and hard limits on various resources for executed processes. See
-        <citerefentry><refentrytitle>setrlimit</refentrytitle><manvolnum>2</manvolnum></citerefentry> for details on
-        the resource limit concept. Resource limits may be specified in two formats: either as single value to set a
-        specific soft and hard limit to the same value, or as colon-separated pair <option>soft:hard</option> to set
-        both limits individually (e.g. <literal>LimitAS=4G:16G</literal>).  Use the string <option>infinity</option> to
-        configure no limit on a specific resource. The multiplicative suffixes K, M, G, T, P and E (to the base 1024)
-        may be used for resource limits measured in bytes (e.g. LimitAS=16G). For the limits referring to time values,
-        the usual time units ms, s, min, h and so on may be used (see
+        <citerefentry><refentrytitle>setrlimit</refentrytitle><manvolnum>2</manvolnum></citerefentry> for
+        details on the resource limit concept. Resource limits may be specified in two formats: either as
+        single value to set a specific soft and hard limit to the same value, or as colon-separated pair
+        <option>soft:hard</option> to set both limits individually (e.g. <literal>LimitAS=4G:16G</literal>).
+        Use the string <option>infinity</option> to configure no limit on a specific resource. The
+        multiplicative suffixes K, M, G, T, P and E (to the base 1024) may be used for resource limits
+        measured in bytes (e.g. <literal>LimitAS=16G</literal>). For the limits referring to time values, the
+        usual time units ms, s, min, h and so on may be used (see
         <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
-        details). Note that if no time unit is specified for <varname>LimitCPU=</varname> the default unit of seconds
-        is implied, while for <varname>LimitRTTIME=</varname> the default unit of microseconds is implied. Also, note
-        that the effective granularity of the limits might influence their enforcement. For example, time limits
-        specified for <varname>LimitCPU=</varname> will be rounded up implicitly to multiples of 1s. For
-        <varname>LimitNICE=</varname> the value may be specified in two syntaxes: if prefixed with <literal>+</literal>
-        or <literal>-</literal>, the value is understood as regular Linux nice value in the range -20..19. If not
-        prefixed like this the value is understood as raw resource limit parameter in the range 0..40 (with 0 being
-        equivalent to 1).</para>
+        details). Note that if no time unit is specified for <varname>LimitCPU=</varname> the default unit of
+        seconds is implied, while for <varname>LimitRTTIME=</varname> the default unit of microseconds is
+        implied. Also, note that the effective granularity of the limits might influence their
+        enforcement. For example, time limits specified for <varname>LimitCPU=</varname> will be rounded up
+        implicitly to multiples of 1s. For <varname>LimitNICE=</varname> the value may be specified in two
+        syntaxes: if prefixed with <literal>+</literal> or <literal>-</literal>, the value is understood as
+        regular Linux nice value in the range -20..19. If not prefixed like this the value is understood as
+        raw resource limit parameter in the range 0..40 (with 0 being equivalent to 1).</para>
 
-        <para>Note that most process resource limits configured with these options are per-process, and processes may
-        fork in order to acquire a new set of resources that are accounted independently of the original process, and
-        may thus escape limits set. Also note that <varname>LimitRSS=</varname> is not implemented on Linux, and
-        setting it has no effect. Often it is advisable to prefer the resource controls listed in
+        <para>Note that most process resource limits configured with these options are per-process, and
+        processes may fork in order to acquire a new set of resources that are accounted independently of the
+        original process, and may thus escape limits set. Also note that <varname>LimitRSS=</varname> is not
+        implemented on Linux, and setting it has no effect. Often it is advisable to prefer the resource
+        controls listed in
         <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
-        over these per-process limits, as they apply to services as a whole, may be altered dynamically at runtime, and
-        are generally more expressive. For example, <varname>MemoryLimit=</varname> is a more powerful (and working)
-        replacement for <varname>LimitRSS=</varname>.</para>
-
-        <para>For system units these resource limits may be chosen freely. For user units however (i.e. units run by a
-        per-user instance of
-        <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>), these limits are
-        bound by (possibly more restrictive) per-user limits enforced by the OS.</para>
+        over these per-process limits, as they apply to services as a whole, may be altered dynamically at
+        runtime, and are generally more expressive. For example, <varname>MemoryMax=</varname> is a more
+        powerful (and working) replacement for <varname>LimitRSS=</varname>.</para>
 
         <para>Resource limits not configured explicitly for a unit default to the value configured in the various
         <varname>DefaultLimitCPU=</varname>, <varname>DefaultLimitFSIZE=</varname>, … options available in
         <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, and –
         if not configured there – the kernel or per-user defaults, as defined by the OS (the latter only for user
-        services, see above).</para>
+        services, see below).</para>
+
+        <para>For system units these resource limits may be chosen freely. When these settings are configured
+        in a user service (i.e. a service run by the per-user instance of the service manager) they cannot be
+        used to raise the limits above those set for the user manager itself when it was first invoked, as
+        the user's service manager generally lacks the privileges to do so. In user context these
+        configuration options are hence only useful to lower the limits passed in or to raise the soft limit
+        to the maximum of the hard limit as configured for the user. To raise the user's limits further, the
+        available configuration mechanisms differ between operating systems, but typically require
+        privileges. In most cases it is possible to configure higher per-user resource limits via PAM or by
+        setting limits on the system service encapsulating the user's service manager, i.e. the user's
+        instance of <filename>user@.service</filename>. After making such changes, make sure to restart the
+        user's service manager.</para>
 
         <table>
           <title>Resource limit directives, their equivalent <command>ulimit</command> shell commands and the unit used</title>

man/systemd.path.xml

@@ -52,6 +52,15 @@
     limitations as inotify, and for example cannot be used to monitor
     files or directories changed by other machines on remote NFS file
     systems.</para>
+
+    <para>When a service unit triggered by a path unit terminates (regardless whether it exited successfully
+    or failed), monitored paths are checked immediately again, and the service accordingly restarted
+    instantly. As protection against busy looping in this trigger/start cycle, a start rate limit is enforced
+    on the service unit, see <varname>StartLimitIntervalSec=</varname> and
+    <varname>StartLimitBurst=</varname> in
+    <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Unlike
+    other service failures, the error condition that the start rate limit is hit is propagated from the
+    service unit to the path unit and causes the path unit to fail as well, thus ending the loop.</para>
   </refsect1>
 
   <refsect1>

man/systemd.resource-control.xml

@@ -462,6 +462,14 @@
 
           <para>This setting replaces <varname>BlockIODeviceWeight=</varname> and disables settings prefixed with
           <varname>BlockIO</varname> or <varname>StartupBlockIO</varname>.</para>
+
+          <para>The specified device node should reference a block device that has an I/O scheduler
+          associated, i.e. should not refer to partition or loopback block devices, but to the originating,
+          physical device. When a path to a regular file or directory is specified it is attempted to
+          discover the correct originating device backing the file system of the specified path. This works
+          correctly only for simpler cases, where the file system is directly placed on a partition or
+          physical block device, or where simple 1:1 encryption using dm-crypt/LUKS is used. This discovery
+          does not cover complex storage and in particular RAID and volume management storage devices.</para>
         </listitem>
       </varlistentry>
 
@@ -486,6 +494,8 @@
           <para>These settings replace <varname>BlockIOReadBandwidth=</varname> and
           <varname>BlockIOWriteBandwidth=</varname> and disable settings prefixed with <varname>BlockIO</varname> or
           <varname>StartupBlockIO</varname>.</para>
+
+          <para>Similar restrictions on block device discovery as for <varname>IODeviceWeight=</varname> apply, see above.</para>
         </listitem>
       </varlistentry>
 
@@ -509,6 +519,8 @@
 
           <para>These settings are supported only if the unified control group hierarchy is used and disable settings
           prefixed with <varname>BlockIO</varname> or <varname>StartupBlockIO</varname>.</para>
+
+          <para>Similar restrictions on block device discovery as for <varname>IODeviceWeight=</varname> apply, see above.</para>
         </listitem>
       </varlistentry>
 
@@ -528,6 +540,8 @@
           <para>Implies <literal>IOAccounting=yes</literal>.</para>
 
           <para>These settings are supported only if the unified control group hierarchy is used.</para>
+
+          <para>Similar restrictions on block device discovery as for <varname>IODeviceWeight=</varname> apply, see above.</para>
         </listitem>
       </varlistentry>
 

man/systemd.timer.xml

@@ -163,7 +163,10 @@
         timers defined in the other directives.</para>
 
         <para>These are monotonic timers, independent of wall-clock time and timezones. If the computer is
-        temporarily suspended, the monotonic clock pauses, too.</para>
+        temporarily suspended, the monotonic clock generally pauses, too. Note that if
+        <varname>WakeSystem=</varname> is used, a different monotonic clock is selected that continues to
+        advance while the system is suspended and thus can be used as the trigger to resume the
+        system.</para>
 
         <para>If the empty string is assigned to any of these options, the list of timers is reset (both
         monotonic timers and <varname>OnCalendar=</varname> timers, see below), and all prior assignments
@@ -225,7 +228,13 @@
         <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
         for details. To optimize power consumption, make sure to set
         this value as high as possible and as low as
-        necessary.</para></listitem>
+        necessary.</para>
+
+        <para>Note that this setting is primarily a power saving option that allows coalescing CPU
+        wake-ups. It should not be confused with <varname>RandomizedDelaySec=</varname> (see below) which
+        adds a random value to the time the timer shall elapse next and whose purpose is the opposite: to
+        stretch elapsing of timer events over a longer period to reduce workload spikes. For further details
+        and explanations and how both settings play together, see below.</para></listitem>
       </varlistentry>
 
       <varlistentry>
@@ -310,7 +319,16 @@
         <varname>false</varname>.</para>
 
         <para>Note that this functionality requires privileges and is thus generally only available in the
-        system service manager.</para></listitem>
+        system service manager.</para>
+
+        <para>Note that behaviour of monotonic clock timers (as configured with
+        <varname>OnActiveSec=</varname>, <varname>OnBootSec=</varname>, <varname>OnStartupSec=</varname>,
+        <varname>OnUnitActiveSec=</varname>, <varname>OnUnitInactiveSec=</varname>, see above) is altered
+        depending on this option. If false, a monotonic clock is used that is paused during system suspend
+        (<constant>CLOCK_MONOTONIC</constant>), if true a different monotonic clock is used that continues
+        advancing during system suspend (<constant>CLOCK_BOOTTIME</constant>), see
+        <citerefentry><refentrytitle>clock_getres</refentrytitle><manvolnum>2</manvolnum></citerefentry> for
+        details.</para></listitem>
       </varlistentry>
 
       <varlistentry>

man/systemd.unit.xml

@@ -756,7 +756,11 @@
         configured by <varname>Requires=</varname>, <varname>Wants=</varname>, <varname>Requisite=</varname>,
         or <varname>BindsTo=</varname>. It is a common pattern to include a unit name in both the
         <varname>After=</varname> and <varname>Wants=</varname> options, in which case the unit listed will
-        be started before the unit that is configured with these options.</para></listitem>
+        be started before the unit that is configured with these options.</para>
+
+        <para>Note that <varname>Before=</varname> dependencies on device units have no effect and are not
+        supported.  Devices generally become available as a result of an external hotplug event, and systemd
+        creates the corresponding device unit without delay.</para></listitem>
       </varlistentry>
 
       <varlistentry>

man/udev.xml

@@ -465,6 +465,10 @@
             that is enforced on <filename>systemd-udevd.service</filename>.</para>
             <para>Please also note that <literal>:=</literal> and <literal>=</literal> are clearing
             both, program and builtin commands.</para>
+            <para>In order to activate long-running processes from udev rules, provide a service unit, and
+            pull it in from a udev device using the <varname>SYSTEMD_WANTS</varname> device property. See
+            <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+            for details.</para>
           </listitem>
         </varlistentry>