nspawn: add new --share-system switch to run a container without PID/UTS/IPC namespacing

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

diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml
index 5721dc15537e9e1901264ccbeccae930d86fe87e..f4caccdd23ada352ab2f8c36c50c888a252aa7cc 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>


@@ -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>
 


@@ -1005,6 +1035,135 @@
                 </variablelist>
         </refsect1>
 
                 </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>
+                                <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>
+
+                <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>
                   <title>See Also</title>
                   <para>
         <refsect1>
                   <title>See Also</title>
                   <para>


@@ -1017,8 +1176,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>