X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.exec.xml;h=69ee4fc5e88c71b4168711d4350d6534f5a296b7;hp=fb8496f54ac825e4e7f42438fed4417c6108cf6d;hb=d91c34f21ff7445dcee3efe2368aebe2d6c266db;hpb=260abb780a135e4cae8c10715c7e85675efc345a diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index fb8496f54..69ee4fc5e 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -9,16 +9,16 @@ Copyright 2010 Lennart Poettering systemd is free software; you can redistribute it and/or modify it - under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. systemd is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. + Lesser General Public License for more details. - You should have received a copy of the GNU General Public License + You should have received a copy of the GNU Lesser General Public License along with systemd; If not, see . --> @@ -44,26 +44,26 @@ systemd.exec - systemd execution environment configuration + Execution environment configuration - systemd.service, - systemd.socket, - systemd.mount, - systemd.swap + service.service, + socket.socket, + mount.mount, + swap.swap Description - Unit configuration files for services, sockets + Unit configuration files for services, sockets, mount points and swap devices share a subset of configuration options which define the execution environment of spawned processes. This man page lists the configuration options - shared by these three unit types. See + shared by these four unit types. See systemd.unit5 for the common options of all unit configuration files, and @@ -75,22 +75,26 @@ for more information on the specific unit configuration files. The execution specific configuration options are configured in the [Service], - [Socket], [Mount] resp. [Swap] section, depending on the unit + [Socket], [Mount], or [Swap] sections, depending on the unit type. Options - + WorkingDirectory= Takes an absolute directory path. Sets the working - directory for executed - processes. + directory for executed processes. If + not set defaults to the root directory + when systemd is running as a system + instance and the respective user's + home directory if run as + user. @@ -113,10 +117,10 @@ Group= Sets the Unix user - resp. group the processes are executed - as. Takes a single user resp. group + or group that the processes are executed + as, respectively. Takes a single user or group name or ID as argument. If no group is - set the default group of the user is + set, the default group of the user is chosen. @@ -129,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. @@ -210,13 +219,15 @@ Sets the CPU scheduling priority for executed - processes. Takes an integer between 1 - (lowest priority) and 99 (highest - priority). The available priority + processes. The available priority range depends on the selected CPU - scheduling policy (see above). See - sched_setscheduler2 - for details. + scheduling policy (see above). For + real-time scheduling policies an + integer between 1 (lowest priority) + and 99 (highest priority) can be used. + See sched_setscheduler2 + for details. + @@ -238,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. @@ -251,7 +268,7 @@ octal notation. See umask2 for details. Defaults to - 0002. + 0022. @@ -265,9 +282,28 @@ 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. + Variable expansion is not performed + inside the strings, and $ has no special + meaning. + If you need to assign a value containing spaces + to a variable, use double quotes (") + for the assignment. + + Example: + Environment="VAR1=word1 word2" VAR2=word3 "VAR3=word 5 6" + gives three variables VAR1, + VAR2, VAR3. + + + + See environ7 - for details. + for details about environment variables. EnvironmentFile= @@ -278,13 +314,28 @@ contain new-line separated variable assignments. Empty lines and lines starting with ; or # will be ignored, - which may be used for commenting. The - argument passed should be an absolute - file name, optionally prefixed with + which may be used for commenting. A line + ending with a backslash will be concatenated + with the following one, allowing multiline variable + definitions. The 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 "-", 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 @@ -294,7 +345,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. @@ -361,8 +412,10 @@ , , , + , + , , - or + or . If set to the file descriptor of standard input is @@ -383,11 +436,21 @@ terminal. connects standard output to the syslog3 - system logger. + system syslog + service. connects it with the kernel log buffer which is accessible via - dmesg1. - and work + dmesg1. + connects it with the journal which is + accessible via + journalctl1 + (Note that everything that is written + to syslog or kmsg is implicitly stored + in the journal as well, those options + are hence supersets of this + one). , + and + work similarly but copy the output to the system console as well. connects @@ -395,8 +458,13 @@ socket activation, semantics are similar to the respective option of StandardInput=. - This setting defaults to - . + This setting defaults to the value set + with + + in + systemd-system.conf5, + which defaults to + . StandardError= @@ -410,7 +478,11 @@ the file descriptor used for standard output is duplicated for standard error. This - setting defaults to + setting defaults to the value set with + + in + systemd-system.conf5, + which defaults to . @@ -421,6 +493,36 @@ TTY (see above). Defaults to /dev/console. + + TTYReset= + Reset the terminal + device specified with + TTYPath= before and + after execution. Defaults to + no. + + + TTYVHangup= + Disconnect all clients + which have opened the terminal device + specified with + TTYPath= + before and after execution. Defaults + to + no. + + + TTYVTDisallocate= + If the terminal + device specified with + TTYPath= is a + virtual console terminal try to + deallocate the TTY before and after + execution. This ensures that the + screen and scrollback buffer is + cleared. Defaults to + no. + SyslogIdentifier= Sets the process name @@ -495,7 +597,7 @@ prefixes may be disabled with SyslogLevelPrefix=, see below. For details see - sd-daemon7. + sd-daemon3. Defaults to . @@ -507,8 +609,9 @@ argument. If true and StandardOutput= or StandardError= are - set to or - log lines + set to , + or + , log lines written by the executed process that are prefixed with a log level will be passed on to syslog with this log @@ -517,7 +620,7 @@ these prefixes is disabled and the logged lines are passed on as-is. For details about this prefixing see - sd-daemon7. + sd-daemon3. Defaults to true. @@ -525,16 +628,17 @@ TimerSlackNSec= Sets the timer slack in nanoseconds for the executed - processes. The timer slack controls the - accuracy of wake-ups triggered by + processes. The timer slack controls + the accuracy of wake-ups triggered by timers. See prctl2 for more information. Note that in contrast to most other time span definitions this parameter takes an - integer value in nano-seconds and does - not understand any other - units. + integer value in nano-seconds if no + unit is specified. The usual time + units are understood + too. @@ -558,7 +662,10 @@ various resource limits for executed processes. See setrlimit2 - for details. + for details. Use the string + infinity to + configure no limit on a specific + resource. @@ -586,14 +693,19 @@ conjunction with socket-activated services, and stream sockets (TCP) in particular. It has no effect on other - socket types (e.g. datagram/UDP) and on processes - unrelated to socket-based + socket types (e.g. datagram/UDP) and + on processes unrelated to socket-based activation. If the tcpwrap verification fails daemon start-up will fail and the connection is terminated. See tcpd8 - for details. + for details. Note that this option may + be used to do access control checks + only. Shell commands and commands + described in + hosts_options5 + are not supported. @@ -605,26 +717,40 @@ executed process. See capabilities7 for details. Takes a whitespace - seperated list of capability names as + separated list of capability names as read by - cap_from_name3. + cap_from_name3, + e.g. CAP_SYS_ADMIN + CAP_DAC_OVERRIDE + CAP_SYS_PTRACE. Capabilities listed will be included in the bounding set, all others are removed. If the list of capabilities - is prefixed with ~ all but the listed - capabilities will be included, the - effect of this assignment - inverted. Note that this option does - not actually set or unset any + is prefixed with ~ + all but the listed capabilities will + be included, the effect of the + assignment inverted. Note that this + option also affects the respective capabilities in the effective, - permitted or inherited capability - sets. That's what - Capabilities= is - for. If this option is not used the + permitted and inheritable capability + sets, on top of what + Capabilities= + does. If this option is not used the 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 to + the empty capability set, and all + prior settings have no effect. If set + to ~ (without any + further argument) the bounding set is + reset to the full set of available + capabilities, also undoing any + previous settings. @@ -637,9 +763,13 @@ , , , - and/or - . - + 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. @@ -667,34 +797,266 @@ 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 name - and ":" may be omitted in which case - the named systemd control group + control group path. The controller + name and ":" may be omitted in which + case the named systemd control group 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 hierachies -- 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. For details about control - groups see cgroups.txt. + 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. + + 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-system.conf5, + but a unit's + ControlGroup= + setting for a specific controller + takes precedence. + + + + ControlGroupModify= + Takes a boolean + argument. If true, the control groups + created for this unit will be owned by + the user specified with + User= (and the + appropriate group), and he/she can create + subgroups as well as add processes to + the group. + + + + ControlGroupPersistent= + Takes a boolean + argument. If true, the control groups + created for this unit will be marked + to be persistent, i.e. systemd will + not remove them when stopping the + unit. The default is false, meaning + that the control groups will be + removed when the unit is stopped. For + details about the semantics of this + logic see PaxControlGroups. + + + + ControlGroupAttribute= + + Set a specific control + group attribute for executed + processes, and (if needed) add the + executed processes to a cgroup in the + hierarchy of the controller the + attribute belongs to. Takes two + space-separated arguments: the + attribute name (syntax is + cpu.shares where + cpu refers to a + specific controller and + shares to the + attribute name), and the attribute + value. Example: + ControlGroupAttribute=cpu.shares + 512. If this option is used + for an attribute that belongs to a + kernel controller hierarchy the unit + is not already configured to be added + to (for example via the + ControlGroup= + option) then the unit will be added to + the controller and the default unit + cgroup path is implied. Thus, using + ControlGroupAttribute= + is in most cases sufficient to make + use of control group enforcements, + explicit + ControlGroup= are + only necessary in case the implied + default control group path for a + service is not desirable. For details + about control group attributes see + cgroups.txt. This + option may appear more than once, in + order to set multiple control group + 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=. + + + + + CPUShares= + + Assign the specified + overall CPU time shares to the + processes executed. Takes an integer + value. This controls the + cpu.shares control + group attribute, which defaults to + 1024. For details about this control + group attribute see sched-design-CFS.txt. + + + + MemoryLimit= + MemorySoftLimit= + + Limit the overall memory usage + of the executed processes to a certain + size. Takes a memory size in bytes. If + the value is suffixed with K, M, G or + T the specified memory size is parsed + as Kilobytes, Megabytes, Gigabytes, + or Terabytes (to the base + 1024), respectively. This controls the + memory.limit_in_bytes + and + memory.soft_limit_in_bytes + control group attributes. For details + about these control group attributes + see memory.txt. + + + + DeviceAllow= + DeviceDeny= + + Control access to + specific device nodes by the executed processes. Takes two + space separated strings: a device node + path (such as + /dev/null) + followed by a combination of r, w, m + to control reading, writing, or + creating of the specific device node + by the unit, respectively. This controls the + devices.allow + and + devices.deny + control group attributes. For details + about these control group attributes + see devices.txt. + + + + BlockIOWeight= + + Set the default or + per-device overall block IO weight + value for the executed + processes. Takes either a single + weight value (between 10 and 1000) to + set the default block IO weight, or a + space separated pair of a file path + and a weight value to specify the + device specific weight value (Example: + "/dev/sda 500"). The file path may be + specified as path to a block device + node or as any other file in which + case the backing block device of the + file system of the file is + determined. This controls the + blkio.weight and + blkio.weight_device + control group attributes, which + default to 1000. Use this option + multiple times to set weights for + multiple devices. For details about + these control group attributes see + blkio-controller.txt. + + + + BlockIOReadBandwidth= + BlockIOWriteBandwidth= + + Set the per-device + overall block IO bandwidth limit for + the executed processes. Takes a space + separated pair of a file path and a + bandwidth value (in bytes per second) + to specify the device specific + bandwidth. The file path may be + specified as path to a block device + node or as any other file in which + case the backing block device of the + file system of the file is determined. + If the bandwidth is suffixed with K, M, + G, or T the specified bandwidth is + parsed as Kilobytes, Megabytes, + Gigabytes, or Terabytes, respectively (Example: + "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 + 5M"). This controls the + blkio.read_bps_device + and + blkio.write_bps_device + control group attributes. Use this + option multiple times to set bandwidth + limits for multiple devices. For + details about these control group + attributes see blkio-controller.txt. @@ -720,36 +1082,61 @@ usual file access controls would permit this. Directories listed in InaccessibleDirectories= - will be made inaccesible 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. PrivateTmp= Takes a boolean - argument. If true sets up a new - namespace for the executed processes - and mounts a private - /tmp directory - inside it, that is not shared by + argument. If true sets up a new file + system namespace for the executed + processes and mounts private + /tmp and + /var/tmp directories + inside it, that are not shared by processes outside of the namespace. This is useful to secure access to temporary files of the process, but makes sharing between processes via - /tmp - impossible. Defaults to false. + /tmp or + /var/tmp + impossible. All temporary data created + by service will be removed after service + is stopped. Defaults to + false. + + + + PrivateNetwork= + + Takes a boolean + argument. If true sets up a new + network namespace for the executed + processes and configures only the + loopback network device + lo inside it. No + other network devices will be + available to the executed process. + This is useful to securely turn off + network access by the executed + process. Defaults to + false. @@ -760,26 +1147,19 @@ , or , which - control whether namespaces set up with - ReadWriteDirectories=, - ReadOnlyDirectories= - and - InaccessibleDirectories= - receive or propagate new mounts - from/to the main namespace. See - mount1 - for details. Defaults to - , i.e. the new - namespace will both receive new mount - points from the main namespace as well - as propagate new mounts to - it. + control whether the file system + namespace set up for this unit's + processes will receive or propagate + new mounts. See + mount2 + for details. Default to + . UtmpIdentifier= - Takes a a four + Takes a four character identifier string for an utmp/wtmp entry for this service. This should only be set for services such @@ -797,6 +1177,70 @@ this service. + + IgnoreSIGPIPE= + + Takes a boolean + argument. If true causes SIGPIPE to be + ignored in the executed + process. Defaults to true, since + SIGPIPE generally is useful only in + shell pipelines. + + + + NoNewPrivileges= + + Takes a boolean + argument. If true ensures that the + service process and all its children + can never gain new privileges. This + option is more powerful than the respective + secure bits flags (see above), as it + also prohibits UID changes of any + kind. This is the simplest, most + effective way to ensure that a process + and its children can never elevate + privileges again. + + + + SystemCallFilter= + + Takes a space + separated list of system call + names. If this setting is used all + system calls executed by the unit + process except for the listed ones + will result in immediate process + termination with the SIGSYS signal + (whitelisting). If the first character + of the list is ~ + the effect is inverted: only the + listed system calls will result in + immediate process termination + (blacklisting). If this option is used + NoNewPrivileges=yes + is implied. This feature makes use of + the Secure Computing Mode 2 interfaces + of the kernel ('seccomp filtering') + and is useful for enforcing a minimal + sandboxing environment. Note that the + execve, + rt_sigreturn, + sigreturn, + exit_group, + exit system calls + are implicitly whitelisted and don't + 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. + + @@ -805,11 +1249,14 @@ systemd1, systemctl8, + journalctl8, systemd.unit5, systemd.service5, systemd.socket5, systemd.swap5, - systemd.mount5 + systemd.mount5, + systemd.kill5, + systemd.directives7