X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.exec.xml;h=5721dc15537e9e1901264ccbeccae930d86fe87e;hp=c7da8e312e674e2c46211a350a7026aa6a294267;hb=79640424059328268b9fb6c5fa8eb777b27a177e;hpb=346bce1f4cff0096177c613987cdc80fa4ec134e diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index c7da8e312..5721dc155 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -1,4 +1,3 @@ - @@ -9,16 +8,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,14 +43,14 @@ 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 @@ -69,28 +68,53 @@ files, and systemd.service5, systemd.socket5, - systemd.swap5 + systemd.swap5, and systemd.mount5 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. + + Processes started by the system systemd instance + are executed in a clean environment in which only the + $PATH and $LANG + variables are set by default. In order to add + additional variables, see the + Environment= and + EnvironmentFile= options below. To + specify variables globally, see + DefaultEnvironment= in + systemd-system.conf5 + or the kernel option + systemd.setenv= in + systemd1. Processes + started by the user systemd instances inherit all + environment variables from the user systemd instance, + and have $HOME, + $USER, + $XDG_RUNTIME_DIR defined, among + others. In addition, $MANAGERPID + contains the PID of the user systemd instance. 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. @@ -101,7 +125,7 @@ directory for executed processes, with the chroot2 - system call. If this is used it must + system call. If this is used, it must be ensured that the process and all its auxiliary files are available in the chroot() @@ -113,10 +137,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. @@ -125,14 +149,19 @@ Sets the supplementary Unix groups the processes are executed - as. This takes a space separated list + as. This takes a space-separated list 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. @@ -158,7 +187,7 @@ for this process) and 1000 (to make killing of this process under memory pressure very likely). See proc.txt + url="https://www.kernel.org/doc/Documentation/filesystems/proc.txt">proc.txt for details. @@ -210,20 +239,22 @@ 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. + CPUSchedulingResetOnFork= Takes a boolean - argument. If true elevated CPU + argument. If true, elevated CPU scheduling priorities and policies will be reset when the executed processes fork, and can hence not leak @@ -238,7 +269,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. @@ -264,10 +301,30 @@ option may be specified more than once 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 + set twice, the later setting will + 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, however, specifier + expansion is possible. The $ character 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= @@ -275,26 +332,42 @@ Environment= but reads the environment variables from a text file. The text file should - contain new-line separated variable + 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 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 + 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 filename or wildcard + expression, optionally prefixed with + -, which indicates + that if the file does not exist, it + will not be read and no 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 with Environment=. If the same variable is set twice from - these files the files will be read in + these files, the files will be read in the order they are specified and the later setting will override the - earlier setting. + earlier setting. @@ -307,19 +380,19 @@ , or . If - is selected + is selected, standard input will be connected to /dev/null, i.e. all read attempts by the process will result in immediate EOF. If - is selected + is selected, standard input is connected to a TTY (as configured by TTYPath=, see below) and the executed process becomes the controlling process of the terminal. If the terminal is already - being controlled by another process the + being controlled by another process, the executed process waits until the current controlling process releases the terminal. @@ -341,7 +414,7 @@ file (see systemd.socket5 for details) specifies a single socket - only. If this option is set standard + only. If this option is set, standard input will be connected to the socket the service was activated from, which is primarily useful for compatibility @@ -361,22 +434,24 @@ , , , + , + , , - or + or . If set to - the file + , the file descriptor of standard input is duplicated for standard output. If set - to standard + to , standard output will be connected to /dev/null, i.e. everything written to it will be - lost. If set to + lost. If set to , standard output will be connected to a tty (as configured via TTYPath=, see below). If the TTY is used for output - only the executed process will not + only, the executed process will not become the controlling process of the terminal, and will not fail or wait for other processes to release the @@ -387,8 +462,17 @@ 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 @@ -396,8 +480,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= @@ -411,7 +500,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 . @@ -442,10 +535,10 @@ TTYVTDisallocate= - If the the terminal + If the terminal device specified with TTYPath= is a - virtual console terminal try to + virtual console terminal, try to deallocate the TTY before and after execution. This ensures that the screen and scrollback buffer is @@ -456,7 +549,7 @@ SyslogIdentifier= Sets the process name to prefix log lines sent to syslog or - the kernel log buffer with. If not set + the kernel log buffer with. If not set, defaults to the process name of the executed process. This option is only useful when @@ -526,7 +619,7 @@ prefixes may be disabled with SyslogLevelPrefix=, see below. For details see - sd-daemon7. + sd-daemon3. Defaults to . @@ -538,8 +631,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 @@ -548,7 +642,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. @@ -556,16 +650,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. @@ -598,13 +693,13 @@ PAMName= Sets the PAM service - name to set up a session as. If set + name to set up a session as. If set, the executed process will be registered as a PAM session under the specified service name. This is only useful in conjunction with the User= setting. If - not set no PAM session will be opened + not set, no PAM session will be opened for the executed processes. See pam8 for details. @@ -613,21 +708,26 @@ TCPWrapName= If this is a - socket-activated service this sets the + socket-activated service, this sets the tcpwrap service name to check the permission for the current connection with. This is only useful in 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 + 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. @@ -638,27 +738,40 @@ capability bounding set for the executed process. See capabilities7 - for details. Takes a whitespace - separated list of capability names as - read by - cap_from_name3. + for details. Takes a whitespace-separated + list of capability names as read by + 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 the 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. @@ -672,8 +785,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. @@ -694,234 +811,16 @@ setting. - - ControlGroup= - - Controls the control - groups the executed processes shall be - made members of. Takes a - space-separated list of cgroup - identifiers. A cgroup identifier has a - format like - cpu:/foo/bar, - where "cpu" identifies 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 - 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 - recommended to manipulate the service - control group path in the systemd - named hierarchy. For details about - control groups see cgroups.txt. - - - - 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. - - - - ControlGroupAttribute= - - Set a specific control - group attribute for executed - processes, and (if needed) add the 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 case 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. - - - - 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, - resp. Terabytes (to the base - 1024). 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 resp. - creating of the specific device node - by the unit. 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 bandwith limit for - the executed processes. Takes a space - separated pair of a file path and a - bandwith 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 bandwith is suffixed with K, M, - G, or T the specified bandwith is - parsed as Kilobytes, Megabytes, - Gigabytes, resp. Terabytes (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 bandwith - limits for multiple devices. For - details about these control group - attributes see blkio-controller.txt. - - ReadWriteDirectories= ReadOnlyDirectories= InaccessibleDirectories= Sets up a new - file-system name space for executed + file system namespace for executed processes. These options may be used to limit access a process might have - to the main file-system + to the main file system hierarchy. Each setting takes a space-separated list of absolute directory paths. Directories listed in @@ -935,36 +834,51 @@ 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. + Paths in + ReadOnlyDirectories= + and + InaccessibleDirectories= + may be prefixed with + -, in which case + they will be ignored when they do not + exist. PrivateTmp= Takes a boolean - argument. If true sets up a new file + argument. If true, sets up a new file system namespace for the executed - processes and mounts a private - /tmp directory - inside it, that is not shared by + 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 + /tmp or + /var/tmp + impossible. All temporary data created + by service will be removed after service + is stopped. Defaults to false. @@ -972,7 +886,7 @@ PrivateNetwork= Takes a boolean - argument. If true sets up a new + argument. If true, sets up a new network namespace for the executed processes and configures only the loopback network device @@ -993,26 +907,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 @@ -1021,7 +928,7 @@ entries must be created and cleared before and after execution. If the configured string is longer than four - characters it is truncated and the + characters, it is truncated and the terminal four characters are used. This setting interprets %I style string replacements. This setting is @@ -1030,6 +937,71 @@ this service. + + IgnoreSIGPIPE= + + Takes a boolean + argument. If true, causes SIGPIPE to be + ignored in the executed + process. Defaults to true because + 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 do not + 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. + + @@ -1038,11 +1010,15 @@ systemd1, systemctl8, + journalctl8, systemd.unit5, systemd.service5, systemd.socket5, systemd.swap5, - systemd.mount5 + systemd.mount5, + systemd.kill5, + systemd.cgroup5, + systemd.directives7