units: for all unit settings that take lists, allow the empty string for resetting the lists

https://bugzilla.redhat.com/show_bug.cgi?id=756787

6 files changed, 247 insertions, 116 deletions

diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml
index 92f59bdfbd..71472b4f5d 100644
--- a/man/systemd.exec.xml
+++ b/man/systemd.exec.xml
@@ -133,10 +133,15 @@
                                 of group names or IDs. This option may
                                 be specified more than once in which
                                 case all listed groups are set as
-                                supplementary groups. This option does
-                                not override but extends the list of
-                                supplementary groups configured in the
-                                system group database for the
+                                supplementary groups. When the empty
+                                string is assigned the list of
+                                supplementary groups is reset, and all
+                                assignments prior to this one will
+                                have no effect. In any way, this
+                                option does not override, but extends
+                                the list of supplementary groups
+                                configured in the system group
+                                database for the
                                 user.</para></listitem>
                         </varlistentry>
 
@@ -244,7 +249,13 @@
                                 <listitem><para>Controls the CPU
                                 affinity of the executed
                                 processes. Takes a space-separated
-                                list of CPU indexes. See
+                                list of CPU indexes. This option may
+                                be specified more than once in which
+                                case the specificed CPU affinity masks
+                                are merged. If the empty string is
+                                assigned the mask is reset, all
+                                assignments prior to this will have no
+                                effect. See
                                 <citerefentry><refentrytitle>sched_setaffinity</refentrytitle><manvolnum>2</manvolnum></citerefentry>
                                 for details.</para></listitem>
                         </varlistentry>
@@ -271,7 +282,11 @@
                                 in which case all listed variables
                                 will be set. If the same variable is
                                 set twice the later setting will
-                                override the earlier setting. See
+                                override the earlier setting. If the
+                                empty string is assigned to this
+                                option the list of environment
+                                variables is reset, all prior
+                                assignments have no effect. See
                                 <citerefentry><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                                 for details.</para></listitem>
                         </varlistentry>
@@ -288,14 +303,22 @@
                                 parser strips leading and
                                 trailing whitespace from the values
                                 of assignments, unless you use
-                                double quotes (").
-                                The
-                                argument passed should be an absolute
-                                file name or wildcard expression, optionally prefixed with
+                                double quotes (").</para>
+
+                                <para>The argument passed should be an
+                                absolute file name or wildcard
+                                expression, optionally prefixed with
                                 "-", which indicates that if the file
                                 does not exist it won't be read and no
-                                error or warning message is
-                                logged. The files listed with this
+                                error or warning message is logged.
+                                This option may be specified more than
+                                once in which case all specified files
+                                are read. If the empty string is
+                                assigned to this option the list of
+                                file to read is reset, all prior
+                                assignments have no effect.</para>
+
+                                <para>The files listed with this
                                 directive will be read shortly before
                                 the process is executed. Settings from
                                 these files override settings made
@@ -305,7 +328,7 @@
                                 these files the files will be read in
                                 the order they are specified and the
                                 later setting will override the
-                                earlier setting. </para></listitem>
+                                earlier setting.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
@@ -695,8 +718,13 @@
                                 capability bounding set is not
                                 modified on process execution, hence
                                 no limits on the capabilities of the
-                                process are
-                                enforced.</para></listitem>
+                                process are enforced. This option may
+                                appear more than once in which case
+                                the bounding sets are merged. If the empty
+                                string is assigned to this option the
+                                bounding set is reset, and all prior
+                                settings have no
+                                effect.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
@@ -710,8 +738,12 @@
                                 <option>no-setuid-fixup</option>,
                                 <option>no-setuid-fixup-locked</option>,
                                 <option>noroot</option> and/or
-                                <option>noroot-locked</option>.
-                                </para></listitem>
+                                <option>noroot-locked</option>. This
+                                option may appear more than once in
+                                which case the secure bits are
+                                ORed. If the empty string is assigned
+                                to this option the bits are reset to
+                                0.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
@@ -739,10 +771,10 @@
                                 groups the executed processes shall be
                                 made members of. Takes a
                                 space-separated list of cgroup
-                                identifiers. A cgroup identifier has a
-                                format like
+                                identifiers. A cgroup identifier is
+                                formatted like
                                 <filename>cpu:/foo/bar</filename>,
-                                where "cpu" identifies the kernel
+                                where "cpu" indicates the kernel
                                 control group controller used, and
                                 <filename>/foo/bar</filename> is the
                                 control group path. The controller
@@ -751,30 +783,50 @@
                                 hierarchy is implied. Alternatively,
                                 the path and ":" may be omitted, in
                                 which case the default control group
-                                path for this unit is implied. This
-                                option may be used to place executed
-                                processes in arbitrary groups in
-                                arbitrary hierarchies -- which can be
-                                configured externally with additional
-                                execution limits. By default systemd
-                                will place all executed processes in
-                                separate per-unit control groups
-                                (named after the unit) in the systemd
-                                named hierarchy. Since every process
-                                can be in one group per hierarchy only
-                                overriding the control group path in
-                                the named systemd hierarchy will
-                                disable automatic placement in the
-                                default group. This option is
-                                primarily intended to place executed
-                                processes in specific paths in
-                                specific kernel controller
-                                hierarchies. It is however not
+                                path for this unit is implied.</para>
+
+                                <para>This option may be used to place
+                                executed processes in arbitrary groups
+                                in arbitrary hierarchies -- which may
+                                then be externally configured with
+                                additional execution limits. By
+                                default systemd will place all
+                                executed processes in separate
+                                per-unit control groups (named after
+                                the unit) in the systemd named
+                                hierarchy. This option is primarily
+                                intended to place executed processes
+                                in specific paths in specific kernel
+                                controller hierarchies. It is not
                                 recommended to manipulate the service
                                 control group path in the systemd
                                 named hierarchy. For details about
                                 control groups see <ulink
-                                url="http://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink>.</para></listitem>
+                                url="http://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink>.</para>
+
+                                <para>This option may appear more than
+                                once, in which case the list of
+                                control group assignments is
+                                merged. If the same hierarchy gets two
+                                different paths assigned only the
+                                later setting will take effect. If the
+                                empty string is assigned to this
+                                option the list of control group
+                                assignments is reset, all previous
+                                assignments will have no
+                                effect.</para>
+
+                                <para>Note that the list of control
+                                group assignments of a unit is
+                                extended implicitly based on the
+                                settings of
+                                <varname>DefaultControllers=</varname>
+                                of
+                                <citerefentry><refentrytitle>systemd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+                                but a unit's
+                                <varname>ControlGroup=</varname>
+                                setting for a specific controller
+                                takes precedence.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
@@ -832,8 +884,8 @@
                                 the controller and the default unit
                                 cgroup path is implied. Thus, using
                                 <varname>ControlGroupAttribute=</varname>
-                                is in most case sufficient to make use
-                                of control group enforcements,
+                                is in most cases sufficient to make
+                                use of control group enforcements,
                                 explicit
                                 <varname>ControlGroup=</varname> are
                                 only necessary in case the implied
@@ -844,7 +896,23 @@
                                 url="http://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink>. This
                                 option may appear more than once, in
                                 order to set multiple control group
-                                attributes.</para></listitem>
+                                attributes. If this option is used
+                                multiple times for the same cgroup
+                                attribute only the later setting takes
+                                effect. If the empty string is
+                                assigned to this option the list of
+                                attributes is reset, all previous
+                                cgroup attribute settings have no
+                                effect, including those done with
+                                <varname>CPUShares=</varname>,
+                                <varname>MemoryLimit=</varname>,
+                                <varname>MemorySoftLimit</varname>,
+                                <varname>DeviceAllow=</varname>,
+                                <varname>DeviceDeny=</varname>,
+                                <varname>BlockIOWeight=</varname>,
+                                <varname>BlockIOReadBandwidth=</varname>,
+                                <varname>BlockIOWriteBandwidth=</varname>.
+                                </para></listitem>
                         </varlistentry>
 
                         <varlistentry>
@@ -988,18 +1056,21 @@
                                 usual file access controls would
                                 permit this. Directories listed in
                                 <varname>InaccessibleDirectories=</varname>
-                                will be made inaccessible for processes
-                                inside the namespace. Note that
-                                restricting access with these options
-                                does not extend to submounts of a
-                                directory. You must list submounts
-                                separately in these settings to
-                                ensure the same limited access. These
-                                options may be specified more than
-                                once in which case all directories
-                                listed will have limited access from
-                                within the
-                                namespace.</para></listitem>
+                                will be made inaccessible for
+                                processes inside the namespace. Note
+                                that restricting access with these
+                                options does not extend to submounts
+                                of a directory. You must list
+                                submounts separately in these settings
+                                to ensure the same limited
+                                access. These options may be specified
+                                more than once in which case all
+                                directories listed will have limited
+                                access from within the namespace. If
+                                the empty string is assigned to this
+                                option the specific list is reset, and
+                                all prior assignments have no
+                                effect.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
@@ -1131,8 +1202,13 @@
                                 <function>exit_group</function>,
                                 <function>exit</function> system calls
                                 are implicitly whitelisted and don't
-                                need to be listed
-                                explicitly.</para></listitem>
+                                need to be listed explicitly. This
+                                option may be specified more than once
+                                in which case the filter masks are
+                                merged. If the empty string is
+                                assigned the filter is reset, all
+                                prior assignments will have no
+                                effect.</para></listitem>
                         </varlistentry>
 
                 </variablelist>
diff --git a/man/systemd.path.xml b/man/systemd.path.xml
index 70a89b7a47..a602caab13 100644
--- a/man/systemd.path.xml
+++ b/man/systemd.path.xml
@@ -130,13 +130,15 @@
                                 specified. <varname>PathChanged=</varname>
                                 may be used to watch a file or
                                 directory and activate the configured
-                                unit whenever it changes. It is not activated
-                                on every write to the watched file but it is
-                                activated if the file which was open for writing
-                                gets closed. <varname>PathModified=</varname>
-                                is similar, but additionally it is activated
-                                also on simple writes to the watched file.
-
+                                unit whenever it changes. It is not
+                                activated on every write to the
+                                watched file but it is activated if
+                                the file which was open for writing
+                                gets
+                                closed. <varname>PathModified=</varname>
+                                is similar, but additionally it is
+                                activated also on simple writes to the
+                                watched file.
                                 <varname>DirectoryNotEmpty=</varname>
                                 may be used to watch a directory and
                                 activate the configured unit whenever
@@ -148,7 +150,12 @@
 
                                 <para>Multiple directives may be
                                 combined, of the same and of different
-                                types, to watch multiple paths.</para>
+                                types, to watch multiple paths. If the
+                                empty string is assigned to any of
+                                these options the list of paths to
+                                watch is reset, and any prior
+                                assignments of these options will not
+                                have any effect.</para>
 
                                 <para>If a path is already existing
                                 (in case of
diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 63e5b16e53..f7cbbb489c 100644
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -315,14 +315,18 @@
                                 for compatibility with parsers
                                 suitable for XDG
                                 <filename>.desktop</filename> files.
-                                The commands are invoked one by
-                                one sequentially in the order they
-                                appear in the unit file.
-                                When <varname>Type</varname> is
-                                not <option>oneshot</option>, only one
+                                The commands are invoked one by one
+                                sequentially in the order they appear
+                                in the unit file.  When
+                                <varname>Type</varname> is not
+                                <option>oneshot</option>, only one
                                 command may be given. Lone semicolons
                                 may be escaped as
-                                '<literal>\;</literal>'.</para>
+                                '<literal>\;</literal>'. If the empty
+                                string is assigned to this option the
+                                list of commands to start is reset,
+                                prior assignments of this option will
+                                have no effect.</para>
 
                                 <para>Unless
                                 <varname>Type=forking</varname> is
@@ -338,23 +342,6 @@
                                 line (i.e. the program to execute) may
                                 not include specifiers.</para>
 
-                                <para>Optionally, if the absolute file
-                                name is prefixed with
-                                '<literal>@</literal>', the second token
-                                will be passed as
-                                <literal>argv[0]</literal> to the
-                                executed process, followed by the
-                                further arguments specified. If the
-                                absolute file name is prefixed with
-                                '<literal>-</literal>' an exit code of
-                                the command normally considered a
-                                failure (i.e. non-zero exit status or
-                                abnormal exit due to signal) is ignored
-                                and considered success. If both
-                                '<literal>-</literal>' and
-                                '<literal>@</literal>' are used they
-                                can appear in either order.</para>
-
                                 <para>On top of that basic environment
                                 variable substitution is
                                 supported. Use
@@ -376,6 +363,23 @@
                                 literal and absolute path
                                 name.</para>
 
+                                <para>Optionally, if the absolute file
+                                name is prefixed with
+                                '<literal>@</literal>', the second token
+                                will be passed as
+                                <literal>argv[0]</literal> to the
+                                executed process, followed by the
+                                further arguments specified. If the
+                                absolute file name is prefixed with
+                                '<literal>-</literal>' an exit code of
+                                the command normally considered a
+                                failure (i.e. non-zero exit status or
+                                abnormal exit due to signal) is ignored
+                                and considered success. If both
+                                '<literal>-</literal>' and
+                                '<literal>@</literal>' are used they
+                                can appear in either order.</para>
+
                                 <para>Note that this setting does not
                                 directly support shell command
                                 lines. If shell command lines are to
@@ -616,8 +620,14 @@
                                 SIGKILL</literal>", ensures that exit
                                 codes 1, 2, 8 and the termination
                                 signal SIGKILL are considered clean
-                                service
-                                terminations.</para></listitem>
+                                service terminations. This option may
+                                appear more than once in which case
+                                the list of successful exit statuses
+                                is merged. If the empty string is
+                                assigned to this option the list is
+                                reset, all prior assignments of this
+                                option will have no
+                                effect.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
@@ -638,9 +648,16 @@
                                 logic. Example:
                                 "<literal>RestartPreventExitStatus=1 6
                                 SIGABRT</literal>", ensures that exit
-                                codes 1 and 6 and the termination signal
-                                SIGABRT will not result in automatic
-                                service restarting.</para></listitem>
+                                codes 1 and 6 and the termination
+                                signal SIGABRT will not result in
+                                automatic service restarting. This
+                                option may appear more than once in
+                                which case the list of restart preventing
+                                statuses is merged. If the empty
+                                string is assigned to this option the
+                                list is reset, all prior assignments
+                                of this option will have no
+                                effect.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
@@ -754,13 +771,22 @@
                                 same time. Also note that a different
                                 service may be activated on incoming
                                 traffic than inherits the sockets. Or
-                                in other words: The
+                                in other words: the
                                 <varname>Service=</varname> setting of
                                 <filename>.socket</filename> units
-                                doesn't have to match the inverse of the
-                                <varname>Sockets=</varname> setting of
-                                the <filename>.service</filename> it
-                                refers to.</para></listitem>
+                                doesn't have to match the inverse of
+                                the <varname>Sockets=</varname>
+                                setting of the
+                                <filename>.service</filename> it
+                                refers to.</para>
+
+                                <para>This option may appear more than
+                                once, in which case the list of socket
+                                units is merged. If the empty string
+                                is assigned to this option the list of
+                                sockets is reset, all prior uses of
+                                this setting will have no
+                                effect.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml
index 88cdaca00f..7ba8bdc85b 100644
--- a/man/systemd.socket.xml
+++ b/man/systemd.socket.xml
@@ -205,19 +205,24 @@
 
                                 <para>These options may be specified
                                 more than once in which case incoming
-                                traffic on any of the sockets will trigger
-                                service activation, and all listed
-                                sockets will be passed to the service,
-                                regardless whether there is incoming
-                                traffic on them or not.</para>
-
-                                <para>If an IP address is used here, it
-                                is often desirable to listen on it
+                                traffic on any of the sockets will
+                                trigger service activation, and all
+                                listed sockets will be passed to the
+                                service, regardless whether there is
+                                incoming traffic on them or not. If
+                                the empty string is assigned to any of
+                                these options, the list of addresses
+                                to listen on is reset, all prior uses
+                                of any of these options will have no
+                                effect.</para>
+
+                                <para>If an IP address is used here,
+                                it is often desirable to listen on it
                                 before the interface it is configured
                                 on is up and running, and even
                                 regardless whether it will be up and
-                                running ever at all. To deal with this it is
-                                recommended to set the
+                                running ever at all. To deal with this
+                                it is recommended to set the
                                 <varname>FreeBind=</varname> option
                                 described below.</para></listitem>
                         </varlistentry>
diff --git a/man/systemd.timer.xml b/man/systemd.timer.xml
index e08e200212..8682643349 100644
--- a/man/systemd.timer.xml
+++ b/man/systemd.timer.xml
@@ -115,7 +115,7 @@
                                 machine was booted
                                 up. <varname>OnStartupSec=</varname>
                                 defines a timer relative to when
-                                systemd was
+                                systemd was first
                                 started. <varname>OnUnitActiveSec=</varname>
                                 defines a timer relative to when the
                                 unit the timer is activating was last
@@ -157,7 +157,13 @@
                                 <para>These are monotonic timers,
                                 independent of wall-clock time and timezones. If the
                                 computer is temporarily suspended, the
-                                monotonic clock stops too.</para></listitem>
+                                monotonic clock stops too.</para>
+
+                                <para>If the empty string is assigned
+                                to any of these options the list of
+                                timers is reset, and all prior
+                                assignments will have no
+                                effect.</para></listitem>
 
                         </varlistentry>
 
@@ -169,8 +175,10 @@
                                 event expressions. See
                                 <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                                 for more information on the syntax of
-                                calendar event
-                                expressions.</para></listitem>
+                                calendar event expressions. Otherwise
+                                the semantics are similar to
+                                <varname>OnActiveSec=</varname> and
+                                related settings.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index d43f288b81..953a2897ad 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -254,8 +254,13 @@
                                 reference documentation that explains
                                 what the unit's purpose is, followed
                                 by how it is configured, followed by
-                                any other related
-                                documentation.</para></listitem>
+                                any other related documentation. This
+                                option may be specified more than once
+                                in which case the specified list of
+                                URIs is merged. If the empty string is
+                                assigned to this option the list is
+                                reset and all prior assignments will
+                                have no effect.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
@@ -907,8 +912,12 @@
                                 pipe symbol must be passed first, the
                                 exclamation second. Except for
                                 <varname>ConditionPathIsSymbolicLink=</varname>,
-                                all path checks follow
-                                symlinks.</para></listitem>
+                                all path checks follow symlinks. If
+                                any of these options is assigned the
+                                empty string the list of conditions is
+                                reset completely, all previous
+                                condition settings (of any kind) will
+                                have no effect.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>