From 74051b9b5865586bf4d30b9075649af838fb92bd Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Thu, 17 Jan 2013 02:27:06 +0100 Subject: 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 --- man/systemd.exec.xml | 190 +++++++++++++++++++++++++++++++++--------------- man/systemd.path.xml | 23 ++++-- man/systemd.service.xml | 92 ++++++++++++++--------- man/systemd.socket.xml | 25 ++++--- man/systemd.timer.xml | 16 +++- man/systemd.unit.xml | 17 ++++- 6 files changed, 247 insertions(+), 116 deletions(-) (limited to 'man') 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. @@ -244,7 +249,13 @@ 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 sched_setaffinity2 for details. @@ -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 environ7 for details. @@ -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 ("). + + 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. + + 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. + earlier setting. @@ -695,8 +718,13 @@ capability bounding set is not modified on process execution, hence no limits on the capabilities of the - process are - enforced. + 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. @@ -710,8 +738,12 @@ , , and/or - . - + . 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. @@ -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 cpu:/foo/bar, - where "cpu" identifies the kernel + where "cpu" indicates the kernel control group controller used, and /foo/bar 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. + + 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 cgroups.txt. + url="http://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt. + + 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. + + Note that the list of control + group assignments of a unit is + extended implicitly based on the + settings of + DefaultControllers= + of + systemd.conf5, + but a unit's + ControlGroup= + setting for a specific controller + takes precedence. @@ -832,8 +884,8 @@ the controller and the default unit cgroup path is implied. Thus, using ControlGroupAttribute= - 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 ControlGroup= are only necessary in case the implied @@ -844,7 +896,23 @@ url="http://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt. This option may appear more than once, in order to set multiple control group - attributes. + 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 + CPUShares=, + MemoryLimit=, + MemorySoftLimit, + DeviceAllow=, + DeviceDeny=, + BlockIOWeight=, + BlockIOReadBandwidth=, + BlockIOWriteBandwidth=. + @@ -988,18 +1056,21 @@ usual file access controls would permit this. Directories listed in InaccessibleDirectories= - 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. + 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. @@ -1131,8 +1202,13 @@ exit_group, exit system calls are implicitly whitelisted and don't - need to be listed - explicitly. + 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. 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. PathChanged= 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. PathModified= - 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. PathModified= + is similar, but additionally it is + activated also on simple writes to the + watched file. DirectoryNotEmpty= may be used to watch a directory and activate the configured unit whenever @@ -148,7 +150,12 @@ Multiple directives may be combined, of the same and of different - types, to watch multiple paths. + 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. 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 .desktop files. - The commands are invoked one by - one sequentially in the order they - appear in the unit file. - When Type is - not , only one + The commands are invoked one by one + sequentially in the order they appear + in the unit file. When + Type is not + , only one command may be given. Lone semicolons may be escaped as - '\;'. + '\;'. 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. Unless Type=forking is @@ -338,23 +342,6 @@ line (i.e. the program to execute) may not include specifiers. - Optionally, if the absolute file - name is prefixed with - '@', the second token - will be passed as - argv[0] to the - executed process, followed by the - further arguments specified. If the - absolute file name is prefixed with - '-' 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 - '-' and - '@' are used they - can appear in either order. - On top of that basic environment variable substitution is supported. Use @@ -376,6 +363,23 @@ literal and absolute path name. + Optionally, if the absolute file + name is prefixed with + '@', the second token + will be passed as + argv[0] to the + executed process, followed by the + further arguments specified. If the + absolute file name is prefixed with + '-' 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 + '-' and + '@' are used they + can appear in either order. + Note that this setting does not directly support shell command lines. If shell command lines are to @@ -616,8 +620,14 @@ SIGKILL", ensures that exit codes 1, 2, 8 and the termination signal SIGKILL are considered clean - service - terminations. + 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. @@ -638,9 +648,16 @@ logic. Example: "RestartPreventExitStatus=1 6 SIGABRT", ensures that exit - codes 1 and 6 and the termination signal - SIGABRT will not result in automatic - service restarting. + 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. @@ -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 Service= setting of .socket units - doesn't have to match the inverse of the - Sockets= setting of - the .service it - refers to. + doesn't have to match the inverse of + the Sockets= + setting of the + .service it + refers to. + + 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. 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 @@ 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. - - 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. + + 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 FreeBind= option described below. 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. OnStartupSec= defines a timer relative to when - systemd was + systemd was first started. OnUnitActiveSec= defines a timer relative to when the unit the timer is activating was last @@ -157,7 +157,13 @@ These are monotonic timers, independent of wall-clock time and timezones. If the computer is temporarily suspended, the - monotonic clock stops too. + monotonic clock stops too. + + 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. @@ -169,8 +175,10 @@ event expressions. See systemd.time7 for more information on the syntax of - calendar event - expressions. + calendar event expressions. Otherwise + the semantics are similar to + OnActiveSec= and + related settings. 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. + 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. @@ -907,8 +912,12 @@ pipe symbol must be passed first, the exclamation second. Except for ConditionPathIsSymbolicLink=, - all path checks follow - symlinks. + 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. -- cgit v1.2.3-54-g00ecf