Merge pull request #3796 from poettering/mailmap

documentation, NEWS and mailmap fixes

4 files changed, 111 insertions, 109 deletions

diff --git a/.mailmap b/.mailmap
index c05b3b9540..d56fb67845 100644
--- a/.mailmap
+++ b/.mailmap
@@ -70,3 +70,7 @@ Otto Wallenius <otto_026@hotmail.com>
 Tom Yan <tom.ty89@gmail.com>
 Marty Plummer <ntzrmtthihu777@gmail.com>
 Brian Boylston <brian.boylston@hpe.com>
+Thomas H. P. Andersen <phomes@gmail.com>
+Michael Olbrich <m.olbrich@pengutronix.de>
+Douglas Christman <DouglasChristman@gmail.com>
+Alexander Kuleshov <kuleshovmail@gmail.com> <0xAX@users.noreply.github.com>
diff --git a/NEWS b/NEWS
index 101cd77982..36fb84b26f 100644
--- a/NEWS
+++ b/NEWS
@@ -191,8 +191,19 @@ CHANGES WITH 231:
           can be set to disable parsing of metadata and the creation
           of persistent symlinks for that device.
 
-        * The change to tag framebuffer devices (/dev/fb*) with "uaccess"
-          to make them available to logged in users has been reverted.
+        * The v230 change to tag framebuffer devices (/dev/fb*) with "uaccess"
+          to make them available to logged-in users has been reverted.
+
+        * Much of the common code of the various systemd components is now
+          built into an internal shared library libsystemd-shared-231.so
+          (incorporating the systemd version number in the name, to be updated
+          with future releases) that the components link to. This should
+          decrease systemd footprint both in memory during runtime and on
+          disk. Note that the shared library is not for public use, and is
+          neither API not ABI stable, but is likely to change with every new
+          released version. Packagers need to make sure that any package built
+          from the systemd sources has a strict versioned dependency on the
+          right package for this shared library.
 
         * Configuration for "mkosi" is now part of the systemd
           repository. mkosi is a tool to easily build legacy-free OS images,
@@ -205,12 +216,12 @@ CHANGES WITH 231:
           local changes made to systemd in a pristine, defined environment. See
           HACKING for details.
 
-        Contributions from: Alessandro Puccetti, Alessio Igor Bogani,
-        Alexander Kuleshov, Alexander Kurtz, Alex Gaynor, Andika Triwidada,
-        Andreas Pokorny, Andreas Rammhold, Andrew Jeddeloh, Ansgar Burchardt,
-        Atrotors, Benjamin Drung, Brian Boylston, Christian Hesse, Christian
-        Rebischke, Daniele Medri, Daniel Mack, Dave Reisner, David Herrmann,
-        David Michael, Djalal Harouni, Doug Christman, Elias Probst, Evgeny
+        Contributions from: Alessandro Puccetti, Alessio Igor Bogani, Alexander
+        Kuleshov, Alexander Kurtz, Alex Gaynor, Andika Triwidada, Andreas
+        Pokorny, Andreas Rammhold, Andrew Jeddeloh, Ansgar Burchardt, Atrotors,
+        Benjamin Drung, Brian Boylston, Christian Hesse, Christian Rebischke,
+        Daniele Medri, Daniel Mack, Dave Reisner, David Herrmann, David
+        Michael, Djalal Harouni, Douglas Christman, Elias Probst, Evgeny
         Vereshchagin, Federico Mena Quintero, Felipe Sateler, Franck Bui,
         Harald Hoyer, Ian Lee, Ivan Shapovalov, Jakub Wilk, Jan Janssen,
         Jean-Sébastien Bour, John Paul Adrian Glaubitz, Jouke Witteveen, Kai
diff --git a/man/systemctl.xml b/man/systemctl.xml
index 742da81cfe..c7b830b7fb 100644
--- a/man/systemctl.xml
+++ b/man/systemctl.xml
@@ -973,70 +973,62 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
           <term><command>list-unit-files <optional><replaceable>PATTERN...</replaceable></optional></command></term>
 
           <listitem>
-            <para>List unit files installed in the file system and their enablement state
-            (as reported by <command>is-enabled</command>). If one or more
-            <replaceable>PATTERN</replaceable>s are specified, only units whose filename
-            (just the last component of the path) matches one of them are shown.</para>
+            <para>List unit files installed on the system, in combination with their enablement state (as reported by
+            <command>is-enabled</command>). If one or more <replaceable>PATTERN</replaceable>s are specified, only unit
+            files whose name matches one of them are shown (patterns matching unit file system paths are not
+            supported).</para>
           </listitem>
         </varlistentry>
 
         <varlistentry>
           <term><command>enable <replaceable>NAME</replaceable>...</command></term>
+          <term><command>enable <replaceable>PATH</replaceable>...</command></term>
 
           <listitem>
-            <para>Enable one or more unit files or unit file instances,
-            as specified on the command line. This will create a number
-            of symlinks as encoded in the <literal>[Install]</literal>
-            sections of the unit files. After the symlinks have been
-            created, the systemd configuration is reloaded (in a way that
-            is equivalent to <command>daemon-reload</command>) to ensure
-            the changes are taken into account immediately. Note that
-            this does <emphasis>not</emphasis> have the effect of also
-            starting any of the units being enabled. If this
-            is desired, either <option>--now</option> should be used
-            together with this command, or an additional <command>start</command>
-            command must be invoked for the unit. Also note that, in case of
-            instance enablement, symlinks named the same as instances
-            are created in the install location, however they all point to the
-            same template unit file.</para>
-
-            <para>This command will print the actions executed. This
-            output may be suppressed by passing <option>--quiet</option>.
+            <para>Enable one or more units or unit instances. This will create a set of symlinks, as encoded in the
+            <literal>[Install]</literal> sections of the indicated unit files. After the symlinks have been created,
+            the system manager configuration is reloaded (in a way equivalent to <command>daemon-reload</command>), in
+            order to ensure the changes are taken into account immediately. Note that this does
+            <emphasis>not</emphasis> have the effect of also starting any of the units being enabled. If this is
+            desired, combine this command with the <option>--now</option> switch, or invoke <command>start</command>
+            with appropriate arguments later. Note that in case of unit instance enablement (i.e. enablement of units of
+            the form <filename>foo@bar.service</filename>), symlinks named the same as instances are created in the
+            unit configuration diectory, however they point to the single template unit file they are instantiated
+            from.</para>
+
+            <para>This command expects either valid unit names (in which case appropriate unit files for these names
+            are automatically searched in the various unit file directories), or absolute paths to unit files (in which
+            case these files are read directly). If a specified unit file is located outside of the unit file
+            directories searched automatically, an additional symlink is created, linking it into the unit
+            configuration path, thus ensuring it is automatically found when requested by commands such as
+            <command>start</command>.</para>
+
+            <para>This command will print the file system operations executed. This output may be suppressed by passing
+            <option>--quiet</option>.
             </para>
 
-            <para>Note that this operation creates only the suggested
-            symlinks for the units. While this command is the
-            recommended way to manipulate the unit configuration
-            directory, the administrator is free to make additional
-            changes manually by placing or removing symlinks in the
-            directory. This is particularly useful to create
-            configurations that deviate from the suggested default
-            installation. In this case, the administrator must make sure
-            to invoke <command>daemon-reload</command> manually as
-            necessary to ensure the changes are taken into account.
+            <para>Note that this operation creates only the symlinks suggested in the <literal>[Install]</literal>
+            section of the unit files. While this command is the recommended way to manipulate the unit configuration
+            directory, the administrator is free to make additional changes manually by placing or removing symlinks
+            below this directory. This is particularly useful to create configurations that deviate from the suggested
+            default installation. In this case, the administrator must make sure to invoke
+            <command>daemon-reload</command> manually as necessary, in order to ensure the changes are taken into
+            account.
             </para>
 
-            <para>Enabling units should not be confused with starting
-            (activating) units, as done by the <command>start</command>
-            command. Enabling and starting units is orthogonal: units
-            may be enabled without being started and started without
-            being enabled. Enabling simply hooks the unit into various
-            suggested places (for example, so that the unit is
-            automatically started on boot or when a particular kind of
-            hardware is plugged in). Starting actually spawns the daemon
-            process (in case of service units), or binds the socket (in
-            case of socket units), and so on.</para>
-
-            <para>Depending on whether <option>--system</option>,
-            <option>--user</option>, <option>--runtime</option>,
-            or <option>--global</option> is specified, this enables the unit
-            for the system, for the calling user only, for only this boot of
-            the system, or for all future logins of all users, or only this
-            boot.  Note that in the last case, no systemd daemon
-            configuration is reloaded.</para>
-
-            <para>Using <command>enable</command> on masked units
-            results in an error.</para>
+            <para>Enabling units should not be confused with starting (activating) units, as done by the
+            <command>start</command> command. Enabling and starting units is orthogonal: units may be enabled without
+            being started and started without being enabled. Enabling simply hooks the unit into various suggested
+            places (for example, so that the unit is automatically started on boot or when a particular kind of
+            hardware is plugged in). Starting actually spawns the daemon process (in case of service units), or binds
+            the socket (in case of socket units), and so on.</para>
+
+            <para>Depending on whether <option>--system</option>, <option>--user</option>, <option>--runtime</option>,
+            or <option>--global</option> is specified, this enables the unit for the system, for the calling user only,
+            for only this boot of the system, or for all future logins of all users, or only this boot.  Note that in
+            the last case, no systemd daemon configuration is reloaded.</para>
+
+            <para>Using <command>enable</command> on masked units is not supported and results in an error.</para>
           </listitem>
         </varlistentry>
 
@@ -1044,28 +1036,31 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
           <term><command>disable <replaceable>NAME</replaceable>...</command></term>
 
           <listitem>
-            <para>Disables one or more units. This removes all symlinks
-            to the specified unit files from the unit configuration
-            directory, and hence undoes the changes made by
-            <command>enable</command>. Note however that this removes
-            all symlinks to the unit files (i.e. including manual
-            additions), not just those actually created by
-            <command>enable</command>. This call implicitly reloads the
-            systemd daemon configuration after completing the disabling
-            of the units. Note that this command does not implicitly
-            stop the units that are being disabled. If this is desired, either
-            <option>--now</option> should be used together with this command, or
-            an additional <command>stop</command> command should be executed
-            afterwards.</para>
-
-            <para>This command will print the actions executed. This
-            output may be suppressed by passing <option>--quiet</option>.
+            <para>Disables one or more units. This removes all symlinks to the unit files backing the specified units
+            from the unit configuration directory, and hence undoes any changes made by <command>enable</command> or
+            <command>link</command>. Note that this removes <emphasis>all</emphasis> symlinks to matching unit files,
+            including manually created symlinks, and not just those actually created by <command>enable</command> or
+            <command>link</command>. Note that while <command>disable</command> undoes the effect of
+            <command>enable</command>, the two commands are otherwise not symmetric, as <command>disable</command> may
+            remove more symlinks than a prior <command>enable</command> invocation of the same unit created.</para>
+
+            <para>This command expects valid unit names only, it does not accept paths to unit files.</para>
+
+            <para>In addition to the units specified as arguments, all units are disabled that are listed in the
+            <varname>Also=</varname> setting contained in the <literal>[Install]</literal> section of any of the unit
+            files being operated on.</para>
+
+            <para>This command implicitly reloads the system manager configuration after completing the operation. Note
+            that this command does not implicitly stop the units that are being disabled. If this is desired, either
+            combine this command with the <option>--now</option> switch, or invoke the <command>stop</command> command
+            with appropriate arguments later.</para>
+
+            <para>This command will print information about the file system operations (symlink removals)
+            executed. This output may be suppressed by passing <option>--quiet</option>.
             </para>
 
-            <para>This command honors <option>--system</option>,
-            <option>--user</option>, <option>--runtime</option> and
-            <option>--global</option> in a similar way as
-            <command>enable</command>.</para>
+            <para>This command honors <option>--system</option>, <option>--user</option>, <option>--runtime</option>
+            and <option>--global</option> in a similar way as <command>enable</command>.</para>
           </listitem>
         </varlistentry>
 
@@ -1073,12 +1068,10 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
           <term><command>reenable <replaceable>NAME</replaceable>...</command></term>
 
           <listitem>
-            <para>Reenable one or more unit files, as specified on the
-            command line. This is a combination of
-            <command>disable</command> and <command>enable</command> and
-            is useful to reset the symlinks a unit is enabled with to
-            the defaults configured in the <literal>[Install]</literal>
-            section of the unit file.</para>
+            <para>Reenable one or more units, as specified on the command line. This is a combination of
+            <command>disable</command> and <command>enable</command> and is useful to reset the symlinks a unit file is
+            enabled with to the defaults configured in its <literal>[Install]</literal> section. This commands expects
+            a unit uname only, it does not accept paths to unit files.</para>
           </listitem>
         </varlistentry>
 
@@ -1209,16 +1202,13 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
           <term><command>mask <replaceable>NAME</replaceable>...</command></term>
 
           <listitem>
-            <para>Mask one or more unit files, as specified on the
-            command line. This will link these units to
-            <filename>/dev/null</filename>, making it impossible to
-            start them. This is a stronger version of
-            <command>disable</command>, since it prohibits all kinds of
-            activation of the unit, including enablement and manual
-            activation. Use this option with care. This honors the
-            <option>--runtime</option> option to only mask temporarily
-            until the next reboot of the system. The <option>--now</option>
-            option can be used to ensure that the units are also stopped.</para>
+            <para>Mask one or more units, as specified on the command line. This will link these unit files to
+            <filename>/dev/null</filename>, making it impossible to start them. This is a stronger version of
+            <command>disable</command>, since it prohibits all kinds of activation of the unit, including enablement
+            and manual activation. Use this option with care. This honors the <option>--runtime</option> option to only
+            mask temporarily until the next reboot of the system. The <option>--now</option> option may be used to
+            ensure that the units are also stopped. This command expects valid unit names only, it does not accept unit
+            file paths.</para>
           </listitem>
         </varlistentry>
 
@@ -1226,23 +1216,20 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
           <term><command>unmask <replaceable>NAME</replaceable>...</command></term>
 
           <listitem>
-            <para>Unmask one or more unit files, as specified on the
-            command line. This will undo the effect of
-            <command>mask</command>.</para>
+            <para>Unmask one or more unit files, as specified on the command line. This will undo the effect of
+            <command>mask</command>. This command expects valid unit names only, it does not accept unit file
+            paths.</para>
           </listitem>
         </varlistentry>
 
         <varlistentry>
-          <term><command>link <replaceable>FILENAME</replaceable>...</command></term>
+          <term><command>link <replaceable>PATH</replaceable>...</command></term>
 
           <listitem>
-            <para>Link a unit file that is not in the unit file search
-            paths into the unit file search path. This requires an
-            absolute path to a unit file. The effect of this can be
-            undone with <command>disable</command>. The effect of this
-            command is that a unit file is available for
-            <command>start</command> and other commands although it
-            is not installed directly in the unit search path.</para>
+            <para>Link a unit file that is not in the unit file search paths into the unit file search path. This
+            command expects an absolute path to a unit file. The effect of this may be undone with
+            <command>disable</command>. The effect of this command is that a unit file is made available for commands
+            such as <command>start</command>, even though it is not installed directly in the unit search path.</para>
           </listitem>
         </varlistentry>
 
diff --git a/src/systemctl/systemctl.c b/src/systemctl/systemctl.c
index 5298fcfb9c..bfd770e4df 100644
--- a/src/systemctl/systemctl.c
+++ b/src/systemctl/systemctl.c
@@ -6533,7 +6533,7 @@ static void systemctl_help(void) {
                "                                  unit is required or wanted\n\n"
                "Unit File Commands:\n"
                "  list-unit-files [PATTERN...]    List installed unit files\n"
-               "  enable NAME...                  Enable one or more unit files\n"
+               "  enable [NAME...|PATH...]        Enable one or more unit files\n"
                "  disable NAME...                 Disable one or more unit files\n"
                "  reenable NAME...                Reenable one or more unit files\n"
                "  preset NAME...                  Enable/disable one or more unit files\n"