doc: detail what "UID" is

[elogind.git] / man / systemd.exec.xml

diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml
index 5721dc15537e9e1901264ccbeccae930d86fe87e..a9e54cb03b1d573368dc3feb371212238a5c00d7 100644 (file)
--- a/man/systemd.exec.xml
+++ b/man/systemd.exec.xml
@@ -57,7 +57,7 @@
                 <title>Description</title>
 
                 <para>Unit configuration files for services, sockets,
                 <title>Description</title>
 
                 <para>Unit configuration files for services, sockets,

-                mount points and swap devices share a subset of
+                mount points, and swap devices share a subset of

                 configuration options which define the execution
                 environment of spawned processes.</para>
 
                 configuration options which define the execution
                 environment of spawned processes.</para>
 


@@ -76,27 +76,6 @@
                 configuration options are configured in the [Service],
                 [Socket], [Mount], or [Swap] sections, depending on the unit
                 type.</para>
                 configuration options are configured in the [Service],
                 [Socket], [Mount], or [Swap] sections, depending on the unit
                 type.</para>

-
-                <para>Processes started by the system systemd instance
-                are executed in a clean environment in which only the
-                <varname>$PATH</varname> and <varname>$LANG</varname>
-                variables are set by default. In order to add
-                additional variables, see the
-                <varname>Environment=</varname> and
-                <varname>EnvironmentFile=</varname> options below. To
-                specify variables globally, see
-                <varname>DefaultEnvironment=</varname> in
-                <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
-                or the kernel option
-                <varname>systemd.setenv=</varname> in
-                <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. Processes
-                started by the user systemd instances inherit all
-                environment variables from the user systemd instance,
-                and have <varname>$HOME</varname>,
-                <varname>$USER</varname>,
-                <varname>$XDG_RUNTIME_DIR</varname> defined, among
-                others. In addition, <varname>$MANAGERPID</varname>
-                contains the PID of the user systemd instance.</para>

         </refsect1>
 
         <refsect1>
         </refsect1>
 
         <refsect1>


@@ -316,9 +295,11 @@
                                 for the assignment.</para>
 
                                 <para>Example:
                                 for the assignment.</para>
 
                                 <para>Example:

-                                <programlisting>Environment="VAR1=word1 word2" VAR2=word3 "VAR3=word 5 6"</programlisting>
+                                <programlisting>Environment="VAR1=word1 word2" VAR2=word3 "VAR3=$word 5 6"</programlisting>

                                 gives three variables <literal>VAR1</literal>,
                                 gives three variables <literal>VAR1</literal>,

-                                <literal>VAR2</literal>, <literal>VAR3</literal>.
+                                <literal>VAR2</literal>, <literal>VAR3</literal>
+                                with the values <literal>word1 word2</literal>,
+                                <literal>word3</literal>, <literal>$word 5 6</literal>.

                                 </para>
 
                                 <para>
                                 </para>
 
                                 <para>


@@ -491,9 +472,9 @@
                         <varlistentry>
                                 <term><varname>StandardError=</varname></term>
                                 <listitem><para>Controls where file
                         <varlistentry>
                                 <term><varname>StandardError=</varname></term>
                                 <listitem><para>Controls where file

-                                descriptor 2 (STDERR) of the executed
-                                processes is connected to. The
-                                available options are identical to
+                                descriptor 2 (standard error) of the
+                                executed processes is connected to.
+                                The available options are identical to

                                 those of
                                 <varname>StandardOutput=</varname>,
                                 with one exception: if set to
                                 those of
                                 <varname>StandardOutput=</varname>,
                                 with one exception: if set to


@@ -510,8 +491,8 @@
                         <varlistentry>
                                 <term><varname>TTYPath=</varname></term>
                                 <listitem><para>Sets the terminal
                         <varlistentry>
                                 <term><varname>TTYPath=</varname></term>
                                 <listitem><para>Sets the terminal

-                                device node to use if standard input,
-                                output or stderr are connected to a
+                                device node to use if standard input, output,
+                                or error are connected to a

                                 TTY (see above). Defaults to
                                 <filename>/dev/console</filename>.</para></listitem>
                         </varlistentry>
                                 TTY (see above). Defaults to
                                 <filename>/dev/console</filename>.</para></listitem>
                         </varlistentry>


@@ -867,9 +848,9 @@
                                 system namespace for the executed
                                 processes and mounts private
                                 <filename>/tmp</filename> and
                                 system namespace for the executed
                                 processes and mounts private
                                 <filename>/tmp</filename> and

-                                <filename>/var/tmp</filename> directories
-                                inside it, that are not shared by
-                                processes outside of the
+                                <filename>/var/tmp</filename>
+                                directories inside it that is not
+                                shared by processes outside of the

                                 namespace. This is useful to secure
                                 access to temporary files of the
                                 process, but makes sharing between
                                 namespace. This is useful to secure
                                 access to temporary files of the
                                 process, but makes sharing between


@@ -877,9 +858,17 @@
                                 <filename>/tmp</filename> or
                                 <filename>/var/tmp</filename>
                                 impossible. All temporary data created
                                 <filename>/tmp</filename> or
                                 <filename>/var/tmp</filename>
                                 impossible. All temporary data created

-                                by service will be removed after service
-                                is stopped. Defaults to
-                                false.</para></listitem>
+                                by service will be removed after
+                                the service is stopped. Defaults to
+                                false. Note that it is possible to run
+                                two or more units within the same
+                                private <filename>/tmp</filename> and
+                                <filename>/var/tmp</filename>
+                                namespace by using the
+                                <varname>JoinsNamespaceOf=</varname>
+                                directive, see
+                                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                                for details.</para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>


@@ -895,6 +884,30 @@
                                 available to the executed process.
                                 This is useful to securely turn off
                                 network access by the executed
                                 available to the executed process.
                                 This is useful to securely turn off
                                 network access by the executed

+                                process. Defaults to false. Note that
+                                it is possible to run two or more
+                                units within the same private network
+                                namespace by using the
+                                <varname>JoinsNamespaceOf=</varname>
+                                directive, see
+                                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                                for details.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>PrivateDevices=</varname></term>
+
+                                <listitem><para>Takes a boolean
+                                argument. If true, sets up a new /dev
+                                namespace for the executed processes
+                                and only adds API pseudo devices such
+                                as <filename>/dev/null</filename>,
+                                <filename>/dev/zero</filename> or
+                                <filename>/dev/random</filename> to
+                                it, but no physical devices such as
+                                <filename>/dev/sda</filename>. This is
+                                useful to securely turn off physical
+                                device access by the executed

                                 process. Defaults to
                                 false.</para></listitem>
                         </varlistentry>
                                 process. Defaults to
                                 false.</para></listitem>
                         </varlistentry>


@@ -937,6 +950,23 @@
                                 this service.</para></listitem>
                         </varlistentry>
 
                                 this service.</para></listitem>
                         </varlistentry>
 

+                        <varlistentry>
+                                <term><varname>SELinuxContext=</varname></term>
+
+                                <listitem><para>Set the SELinux
+                                security context of the executed
+                                process. If set, this will override
+                                the automated domain
+                                transition. However, the policy still
+                                needs to autorize the transition. This
+                                directive is ignored if SELinux is
+                                disabled. If prefixed by
+                                <literal>-</literal>, all errors will
+                                be ignored. See
+                                <citerefentry><refentrytitle>setexeccon</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+                                for details.</para></listitem>
+                        </varlistentry>
+

                         <varlistentry>
                                 <term><varname>IgnoreSIGPIPE=</varname></term>
 
                         <varlistentry>
                                 <term><varname>IgnoreSIGPIPE=</varname></term>
 


@@ -971,7 +1001,7 @@
                                 list of system call
                                 names. If this setting is used, all
                                 system calls executed by the unit
                                 list of system call
                                 names. If this setting is used, all
                                 system calls executed by the unit

-                                process except for the listed ones
+                                processes except for the listed ones

                                 will result in immediate process
                                 termination with the
                                 <constant>SIGSYS</constant> signal
                                 will result in immediate process
                                 termination with the
                                 <constant>SIGSYS</constant> signal


@@ -999,10 +1029,229 @@
                                 merged. If the empty string is
                                 assigned, the filter is reset, all
                                 prior assignments will have no
                                 merged. If the empty string is
                                 assigned, the filter is reset, all
                                 prior assignments will have no

-                                effect.</para></listitem>
+                                effect.</para>
+
+                                <para>If you specify both types of
+                                this option (i.e. whitelisting and
+                                blacklisting) the first encountered
+                                will take precedence and will dictate
+                                the default action (termination or
+                                approval of a system call). Then the
+                                next occurrences of this option will
+                                add or delete the listed system calls
+                                from the set of the filtered system
+                                calls, depending of its type and the
+                                default action (e.g. You have started
+                                with a whitelisting of
+                                <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>
+
+                                <para>Note that setting
+                                <varname>SystemCallFilter=</varname>
+                                implies a
+                                <varname>SystemCallArchitectures=</varname>
+                                setting of <literal>native</literal>
+                                (see below), unless that option is
+                                configured otherwise.</para>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>SystemCallErrorNumber=</varname></term>
+
+                                <listitem><para>Takes an
+                                <literal>errno</literal> error number
+                                name to return when the system call
+                                filter configured with
+                                <varname>SystemCallFilter=</varname>
+                                is triggered, instead of terminating
+                                the process immediately. Takes an
+                                error name such as
+                                <literal>EPERM</literal>,
+                                <literal>EACCES</literal> or
+                                <literal>EUCLEAN</literal>. When this
+                                setting is not used, or when the empty
+                                string is assigned the process will be
+                                terminated immediately when the filter
+                                is triggered.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>SystemCallArchitectures=</varname></term>
+
+                                <listitem><para>Takes a space
+                                separated list of architecture
+                                identifiers to include in the system
+                                call filter. The known architecture
+                                identifiers are
+                                <literal>x86</literal>,
+                                <literal>x86-64</literal>,
+                                <literal>x32</literal>,
+                                <literal>arm</literal> as well as the
+                                special identifier
+                                <literal>native</literal>. Only system
+                                calls of the specified architectures
+                                will be permitted to processes of this
+                                unit. This is an effective way to
+                                disable compatibility with non-native
+                                architectures for processes, for
+                                example to prohibit execution of 32bit
+                                x86 binaries on 64bit x86-64
+                                systems. The special
+                                <literal>native</literal> identifier
+                                implicitly maps to the native
+                                architecture of the system (or more
+                                strictly: to the architecture the
+                                system manager is compiled for). Note
+                                that setting this option to a
+                                non-empty list implies that
+                                <literal>native</literal> is included
+                                too. By default this option is set to
+                                the empty list, i.e. no architecture
+                                system call filtering is applied. Note
+                                that configuring a system call filter
+                                with
+                                <varname>SystemCallFilter=</varname>
+                                (above) implies a
+                                <literal>native</literal> architecture
+                                list, unless configured
+                                otherwise.</para></listitem>
+                        </varlistentry>
+
+                </variablelist>
+        </refsect1>
+
+        <refsect1>
+                <title>Environment variables in spawned processes</title>
+
+                <para>Processes started by the system are executed in
+                a clean environment in which select variables
+                listed below are set. System processes started by systemd
+                do not inherit variables from PID 1, but processes
+                started by user systemd instances inherit all
+                environment variables from the user systemd instance.
+                </para>
+
+                <variablelist class='environment-variables'>
+                        <varlistentry>
+                                <term><varname>$PATH</varname></term>
+
+                                <listitem><para>Colon-separated list
+                                of directiories to use when launching
+                                executables. Systemd uses a fixed
+                                value of
+                                <filename>/usr/local/sbin</filename>:<filename>/usr/local/bin</filename>:<filename>/usr/sbin</filename>:<filename>/usr/bin</filename>:<filename>/sbin</filename>:<filename>/bin</filename>.
+                                </para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>$LANG</varname></term>
+
+                                <listitem><para>Locale. Can be set in
+                                <citerefentry><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                                or on the kernel command line (see
+                                <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+                                and
+                                <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
+                                </para></listitem>

                         </varlistentry>
 
                         </varlistentry>
 

+                        <varlistentry>
+                                <term><varname>$USER</varname></term>
+                                <term><varname>$LOGNAME</varname></term>
+                                <term><varname>$HOME</varname></term>
+                                <term><varname>$SHELL</varname></term>
+
+                                <listitem><para>User name (twice), home
+                                directory, and the login shell.
+                                The variables are set for the units that
+                                have <varname>User=</varname> set,
+                                which includes user
+                                <command>systemd</command> instances.
+                                See
+                                <citerefentry><refentrytitle>passwd</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+                                </para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>$XDG_RUNTIME_DIR</varname></term>
+
+                                <listitem><para>The directory for volatile
+                                state. Set for the user <command>systemd</command>
+                                instance, and also in user sessions.
+                                See
+                                <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
+                                </para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>$XDG_SESSION_ID</varname></term>
+                                <term><varname>$XDG_SEAT</varname></term>
+                                <term><varname>$XDG_VTNR</varname></term>
+
+                                <listitem><para>The identifier of the
+                                session, the seat name, and
+                                virtual terminal of the session. Set
+                                by
+                                <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+                                for login sessions.
+                                <varname>$XDG_SEAT</varname> and
+                                <varname>$XDG_VTNR</varname> will
+                                only be set when attached to a seat and a
+                                tty.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>$MANAGERPID</varname></term>
+
+                                <listitem><para>The PID of the user
+                                <command>systemd</command> instance,
+                                set for processes spawned by it.
+                                </para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>$LISTEN_FDS</varname></term>
+                                <term><varname>$LISTEN_PID</varname></term>
+
+                                <listitem><para>Information about file
+                                descriptors passed to a service for
+                                socket activation.  See
+                                <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+                                </para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>$TERM</varname></term>
+
+                                <listitem><para>Terminal type, set
+                                only for units connected to a terminal
+                                (<varname>StandardInput=tty</varname>,
+                                <varname>StandardOutput=tty</varname>,
+                                or
+                                <varname>StandardError=tty</varname>).
+                                See
+                                <citerefentry><refentrytitle>termcap</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+                                </para></listitem>
+                        </varlistentry>

                 </variablelist>
                 </variablelist>

+
+                <para>Additional variables may be configured by the
+                following means: for processes spawned in specific
+                units, use the <varname>Environment=</varname> and
+                <varname>EnvironmentFile=</varname> options above; to
+                specify variables globally, use
+                <varname>DefaultEnvironment=</varname> (see
+                <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>)
+                or the kernel option
+                <varname>systemd.setenv=</varname> (see
+                <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>). Additional
+                variables may also be set through PAM,
+                c.f. <citerefentry><refentrytitle>pam_env</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>

         </refsect1>
 
         <refsect1>
         </refsect1>
 
         <refsect1>


@@ -1017,8 +1266,9 @@
                           <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

-                          <citerefentry><refentrytitle>systemd.cgroup</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-                          <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+                          <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+                          <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+                          <citerefentry><refentrytitle>exec</refentrytitle><manvolnum>3</manvolnum></citerefentry>

                   </para>
         </refsect1>
 
                   </para>
         </refsect1>