diff options
Diffstat (limited to 'man/systemd.exec.xml')
| -rw-r--r-- | man/systemd.exec.xml | 213 |
1 files changed, 175 insertions, 38 deletions
diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index 3cf6de8256..41ae6e76de 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -107,7 +107,8 @@ <varlistentry> <term><varname>WorkingDirectory=</varname></term> - <listitem><para>Takes an absolute directory path, or the + <listitem><para>Takes a directory path relative to the service's root + directory specified by <varname>RootDirectory=</varname>, or the special value <literal>~</literal>. Sets the working directory for executed processes. If set to <literal>~</literal>, the home directory of the user specified in @@ -116,7 +117,10 @@ and the respective user's home directory if run as user. If the setting is prefixed with the <literal>-</literal> character, a missing working directory is not considered - fatal. Note that setting this parameter might result in + fatal. If <varname>RootDirectory=</varname> is not set, then + <varname>WorkingDirectory=</varname> is relative to the root of + the system running the service manager. + Note that setting this parameter might result in additional dependencies to be added to the unit (see above).</para></listitem> </varlistentry> @@ -124,7 +128,8 @@ <varlistentry> <term><varname>RootDirectory=</varname></term> - <listitem><para>Takes an absolute directory path. Sets the + <listitem><para>Takes a directory path relative to the host's root directory + (i.e. the root of the system running the service manager). Sets the root directory for executed processes, with the <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call. If this is used, it must be ensured that the @@ -141,7 +146,7 @@ <listitem><para>Sets the Unix user 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 chosen.</para></listitem> + of the user is chosen. These do not affect commands prefixed with <literal>+</literal>.</para></listitem> </varlistentry> <varlistentry> @@ -156,7 +161,7 @@ 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> + user. This does not affect commands prefixed with <literal>+</literal>.</para></listitem> </varlistentry> <varlistentry> @@ -790,7 +795,8 @@ 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 <literal>~</literal> (without any further argument), the bounding set is - reset to the full set of available capabilities, also undoing any previous settings.</para></listitem> + reset to the full set of available capabilities, also undoing any previous settings. This does not affect + commands prefixed with <literal>+</literal>.</para></listitem> </varlistentry> <varlistentry> @@ -819,7 +825,8 @@ as a non-privileged user but still want to give it some capabilities. Note that in this case option <constant>keep-caps</constant> is automatically added to <varname>SecureBits=</varname> to retain the - capabilities over the user change.</para></listitem> + capabilities over the user change. <varname>AmbientCapabilities=</varname> does not affect + commands prefixed with <literal>+</literal>.</para></listitem> </varlistentry> <varlistentry> @@ -835,43 +842,46 @@ <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. See - <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> + the bits are reset to 0. This does not affect commands prefixed with <literal>+</literal>. + See <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details.</para></listitem> </varlistentry> <varlistentry> - <term><varname>ReadWriteDirectories=</varname></term> - <term><varname>ReadOnlyDirectories=</varname></term> - <term><varname>InaccessibleDirectories=</varname></term> + <term><varname>ReadWritePaths=</varname></term> + <term><varname>ReadOnlyPaths=</varname></term> + <term><varname>InaccessiblePaths=</varname></term> <listitem><para>Sets up a new file system namespace for executed processes. These options may be used to limit access a process might have to the main file system hierarchy. Each - setting takes a space-separated list of absolute directory - paths. Directories listed in - <varname>ReadWriteDirectories=</varname> are accessible from + setting takes a space-separated list of paths relative to + the host's root directory (i.e. the system running the service manager). + Note that if entries contain symlinks, they are resolved from the host's root directory as well. + Entries (files or directories) listed in + <varname>ReadWritePaths=</varname> are accessible from within the namespace with the same access rights as from - outside. Directories listed in - <varname>ReadOnlyDirectories=</varname> are accessible for + outside. Entries listed in + <varname>ReadOnlyPaths=</varname> are accessible for reading only, writing will be refused even if the usual file - access controls would permit this. Directories listed in - <varname>InaccessibleDirectories=</varname> will be made + access controls would permit this. Entries listed in + <varname>InaccessiblePaths=</varname> will be made inaccessible for processes inside the namespace, and may not countain any other mountpoints, including those specified by - <varname>ReadWriteDirectories=</varname> or - <varname>ReadOnlyDirectories=</varname>. + <varname>ReadWritePaths=</varname> or + <varname>ReadOnlyPaths=</varname>. Note that restricting access with these options does not extend - to submounts of a directory that are created later on. These + to submounts of a directory that are created later on. + Non-directory paths can be specified as well. These options may be specified more than once, in which case all - directories listed will have limited access from within the + paths 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> <para>Paths in - <varname>ReadOnlyDirectories=</varname> + <varname>ReadOnlyPaths=</varname> and - <varname>InaccessibleDirectories=</varname> + <varname>InaccessiblePaths=</varname> may be prefixed with <literal>-</literal>, in which case they will be ignored when they do not @@ -1026,9 +1036,9 @@ <varname>PrivateDevices=</varname>, <varname>ProtectSystem=</varname>, <varname>ProtectHome=</varname>, - <varname>ReadOnlyDirectories=</varname>, - <varname>InaccessibleDirectories=</varname> and - <varname>ReadWriteDirectories=</varname>) require that mount + <varname>ReadOnlyPaths=</varname>, + <varname>InaccessiblePaths=</varname> and + <varname>ReadWritePaths=</varname>) require that mount and unmount propagation from the unit's file system namespace is disabled, and hence downgrade <option>shared</option> to <option>slave</option>. </para></listitem> @@ -1091,8 +1101,8 @@ domain transition. However, the policy still needs to authorize the transition. This directive is ignored if SELinux is disabled. If prefixed by <literal>-</literal>, all errors - will be ignored. See - <citerefentry project='die-net'><refentrytitle>setexeccon</refentrytitle><manvolnum>3</manvolnum></citerefentry> + will be ignored. This does not affect commands prefixed with <literal>+</literal>. + See <citerefentry project='die-net'><refentrytitle>setexeccon</refentrytitle><manvolnum>3</manvolnum></citerefentry> for details.</para></listitem> </varlistentry> @@ -1104,7 +1114,7 @@ Profiles must already be loaded in the kernel, or the unit will fail. This result in a non operation if AppArmor is not enabled. If prefixed by <literal>-</literal>, all errors will - be ignored. </para></listitem> + be ignored. This does not affect commands prefixed with <literal>+</literal>.</para></listitem> </varlistentry> <varlistentry> @@ -1123,7 +1133,8 @@ <para>The value may be prefixed by <literal>-</literal>, in which case all errors will be ignored. An empty value may be - specified to unset previous assignments.</para> + specified to unset previous assignments. This does not affect + commands prefixed with <literal>+</literal>.</para> </listitem> </varlistentry> @@ -1160,7 +1171,7 @@ effect is inverted: only the listed system calls will result in immediate process termination (blacklisting). If running in user mode, or in system mode, but without the - <constant>CAP_SYS_ADMIN</constant> capabiblity (e.g. setting + <constant>CAP_SYS_ADMIN</constant> capability (e.g. setting <varname>User=nobody</varname>), <varname>NoNewPrivileges=yes</varname> is implied. This feature makes use of the Secure Computing Mode 2 interfaces of @@ -1174,7 +1185,7 @@ 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> + have no effect. This does not affect commands prefixed with <literal>+</literal>.</para> <para>If you specify both types of this option (i.e. whitelisting and blacklisting), the first encountered will @@ -1187,7 +1198,84 @@ <function>read</function> and <function>write</function>, and right after it add a blacklisting of <function>write</function>, then <function>write</function> - will be removed from the set.) </para></listitem> + will be removed from the set.)</para> + + <para>As the number of possible system + calls is large, predefined sets of system calls are provided. + A set starts with <literal>@</literal> character, followed by + name of the set. + + <table> + <title>Currently predefined system call sets</title> + + <tgroup cols='2'> + <colspec colname='set' /> + <colspec colname='description' /> + <thead> + <row> + <entry>Set</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>@clock</entry> + <entry>System calls for changing the system clock (<citerefentry project='man-pages'><refentrytitle>adjtimex</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>settimeofday</refentrytitle><manvolnum>2</manvolnum></citerefentry>, and related calls)</entry> + </row> + <row> + <entry>@cpu-emulation</entry> + <entry>System calls for CPU emulation functionality (<citerefentry project='man-pages'><refentrytitle>vm86</refentrytitle><manvolnum>2</manvolnum></citerefentry> and related calls)</entry> + </row> + <row> + <entry>@debug</entry> + <entry>Debugging, performance monitoring and tracing functionality (<citerefentry project='man-pages'><refentrytitle>ptrace</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>perf_event_open</refentrytitle><manvolnum>2</manvolnum></citerefentry> and related calls)</entry> + </row> + <row> + <entry>@io-event</entry> + <entry>Event loop system calls (<citerefentry project='man-pages'><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>select</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>eventfd</refentrytitle><manvolnum>2</manvolnum></citerefentry> and related calls)</entry> + </row> + <row> + <entry>@ipc</entry> + <entry>SysV IPC, POSIX Message Queues or other IPC (<citerefentry project='man-pages'><refentrytitle>mq_overview</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>svipc</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> + </row> + <row> + <entry>@keyring</entry> + <entry>Kernel keyring access (<citerefentry project='man-pages'><refentrytitle>keyctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> and related calls)</entry> + </row> + <row> + <entry>@module</entry> + <entry>Kernel module control (<citerefentry project='man-pages'><refentrytitle>init_module</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>delete_module</refentrytitle><manvolnum>2</manvolnum></citerefentry> and related calls)</entry> + </row> + <row> + <entry>@mount</entry> + <entry>File system mounting and unmounting (<citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry>, and related calls)</entry> + </row> + <row> + <entry>@network-io</entry> + <entry>Socket I/O (including local AF_UNIX): <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry></entry> + </row> + <row> + <entry>@obsolete</entry> + <entry>Unusual, obsolete or unimplemented (<citerefentry project='man-pages'><refentrytitle>create_module</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>gtty</refentrytitle><manvolnum>2</manvolnum></citerefentry>, …)</entry> + </row> + <row> + <entry>@privileged</entry> + <entry>All system calls which need super-user capabilities (<citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> + </row> + <row> + <entry>@process</entry> + <entry>Process control, execution, namespaces (<citerefentry project='man-pages'><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>namespaces</refentrytitle><manvolnum>7</manvolnum></citerefentry>, …</entry> + </row> + <row> + <entry>@raw-io</entry> + <entry>Raw I/O port access (<citerefentry project='man-pages'><refentrytitle>ioperm</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>iopl</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <function>pciconfig_read()</function>, …</entry> + </row> + </tbody> + </tgroup> + </table> + + Note, that as new system calls are added to the kernel, additional system calls might be added to the groups + above, so the contents of the sets may change between systemd versions.</para></listitem> </varlistentry> <varlistentry> @@ -1222,7 +1310,7 @@ more strictly: to the architecture the system manager is compiled for). If running in user mode, or in system mode, but without the <constant>CAP_SYS_ADMIN</constant> - capabiblity (e.g. setting <varname>User=nobody</varname>), + capability (e.g. setting <varname>User=nobody</varname>), <varname>NoNewPrivileges=yes</varname> is implied. Note that setting this option to a non-empty list implies that <constant>native</constant> is included too. By default, this @@ -1254,7 +1342,7 @@ has no effect on 32-bit x86 and is ignored (but works correctly on x86-64). If running in user mode, or in system mode, but without the <constant>CAP_SYS_ADMIN</constant> - capabiblity (e.g. setting <varname>User=nobody</varname>), + capability (e.g. setting <varname>User=nobody</varname>), <varname>NoNewPrivileges=yes</varname> is implied. By default, no restriction applies, all address families are accessible to processes. If assigned the empty string, any @@ -1266,7 +1354,7 @@ family should be included in the configured whitelist as it is frequently used for local communication, including for <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>2</manvolnum></citerefentry> - logging.</para></listitem> + logging. This does not affect commands prefixed with <literal>+</literal>.</para></listitem> </varlistentry> <varlistentry> @@ -1311,6 +1399,35 @@ <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> </varlistentry> + <varlistentry> + <term><varname>MemoryDenyWriteExecute=</varname></term> + + <listitem><para>Takes a boolean argument. If set, attempts to create memory mappings that are writable and + executable at the same time, or to change existing memory mappings to become executable are prohibited. + Specifically, a system call filter is added that rejects + <citerefentry><refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum></citerefentry> + system calls with both <constant>PROT_EXEC</constant> and <constant>PROT_WRITE</constant> set + and <citerefentry><refentrytitle>mprotect</refentrytitle><manvolnum>2</manvolnum></citerefentry> + system calls with <constant>PROT_EXEC</constant> set. Note that this option is incompatible with programs + that generate program code dynamically at runtime, such as JIT execution engines, or programs compiled making + use of the code "trampoline" feature of various C compilers. This option improves service security, as it makes + harder for software exploits to change running code dynamically. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RestrictRealtime=</varname></term> + + <listitem><para>Takes a boolean argument. If set, any attempts to enable realtime scheduling in a process of + the unit are refused. This restricts access to realtime task scheduling policies such as + <constant>SCHED_FIFO</constant>, <constant>SCHED_RR</constant> or <constant>SCHED_DEADLINE</constant>. See + <citerefentry><refentrytitle>sched</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details about + these scheduling policies. Realtime scheduling policies may be used to monopolize CPU time for longer periods + of time, and may hence be used to lock up or otherwise trigger Denial-of-Service situations on the system. It + is hence recommended to restrict access to realtime scheduling to the few programs that actually require + them. Defaults to off.</para></listitem> + </varlistentry> + </variablelist> </refsect1> @@ -1437,6 +1554,26 @@ <citerefentry project='man-pages'><refentrytitle>termcap</refentrytitle><manvolnum>5</manvolnum></citerefentry>. </para></listitem> </varlistentry> + + <varlistentry> + <term><varname>$JOURNAL_STREAM</varname></term> + + <listitem><para>If the standard output or standard error output of the executed processes are connected to the + journal (for example, by setting <varname>StandardError=journal</varname>) <varname>$JOURNAL_STREAM</varname> + contains the device and inode numbers of the connection file descriptor, formatted in decimal, separated by a + colon (<literal>:</literal>). This permits invoked processes to safely detect whether their standard output or + standard error output are connected to the journal. The device and inode numbers of the file descriptors should + be compared with the values set in the environment variable to determine whether the process output is still + connected to the journal. Note that it is generally not sufficient to only check whether + <varname>$JOURNAL_STREAM</varname> is set at all as services might invoke external processes replacing their + standard output or standard error output, without unsetting the environment variable.</para> + + <para>This environment variable is primarily useful to allow services to optionally upgrade their used log + protocol to the native journal protocol (using + <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry> and other + functions) if their standard output or standard error output is connected to the journal anyway, thus enabling + delivery of structured metadata along with logged messages.</para></listitem> + </varlistentry> </variablelist> <para>Additional variables may be configured by the following |