summaryrefslogtreecommitdiff
path: root/man
diff options
context:
space:
mode:
authorLennart Poettering <lennart@poettering.net>2013-01-17 02:27:06 +0100
committerLennart Poettering <lennart@poettering.net>2013-01-17 02:50:05 +0100
commit74051b9b5865586bf4d30b9075649af838fb92bd (patch)
tree1dd547147c395f7e3fec22285da4a83f54644d89 /man
parent4b20075e2fbd99caee8b6a782050969a087a1a21 (diff)
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
Diffstat (limited to 'man')
-rw-r--r--man/systemd.exec.xml190
-rw-r--r--man/systemd.path.xml23
-rw-r--r--man/systemd.service.xml92
-rw-r--r--man/systemd.socket.xml25
-rw-r--r--man/systemd.timer.xml16
-rw-r--r--man/systemd.unit.xml17
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>