nspawn: add new --personality= switch to make it easier to run 32bit containers on...

[elogind.git] / man / systemd-nspawn.xml

diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml
index 7d450f912c1c617c17d6bd41a32eb0d87374963a..6518eb819e413979e2db86117e8606f61eb56c82 100644 (file)
--- a/man/systemd-nspawn.xml
+++ b/man/systemd-nspawn.xml
@@ -123,10 +123,10 @@
                 see each other. The PID namespace separation of the
                 two containers is complete and the containers will
                 share very few runtime objects except for the
                 see each other. The PID namespace separation of the
                 two containers is complete and the containers will
                 share very few runtime objects except for the

-                underlying file system. It is however possible to
-                enter an existing container, see
-                <link linkend='example-nsenter'>Example 4</link> below.
-                </para>
+                underlying file system. Use
+                <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
+                <command>login</command> command to request an
+                additional login prompt in a running container.</para>

 
                 <para><command>systemd-nspawn</command> implements the
                 <ulink
 
                 <para><command>systemd-nspawn</command> implements the
                 <ulink


@@ -143,19 +143,6 @@
                 contain this file out-of-the-box.</para>
         </refsect1>
 
                 contain this file out-of-the-box.</para>
         </refsect1>
 

-        <refsect1>
-                <title>Incompatibility with Auditing</title>
-
-                <para>Note that the kernel auditing subsystem is
-                currently broken when used together with
-                containers. We hence recommend turning it off entirely
-                by booting with <literal>audit=0</literal> on the
-                kernel command line, or by turning it off at kernel
-                build time. If auditing is enabled in the kernel,
-                operating systems booted in an nspawn container might
-                refuse log-in attempts.</para>
-        </refsect1>
-

         <refsect1>
                 <title>Options</title>
 
         <refsect1>
                 <title>Options</title>
 


@@ -186,6 +173,17 @@
                                 and exits.</para></listitem>
                         </varlistentry>
 
                                 and exits.</para></listitem>
                         </varlistentry>
 

+                        <varlistentry>
+                                <term><option>-q</option></term>
+                                <term><option>--quiet</option></term>
+
+                                <listitem><para>Turns off any status
+                                output by the tool itself. When this
+                                switch is used, the only output
+                                from nspawn will be the console output
+                                of the container OS itself.</para></listitem>
+                        </varlistentry>
+

                         <varlistentry>
                                 <term><option>-D</option></term>
                                 <term><option>--directory=</option></term>
                         <varlistentry>
                                 <term><option>-D</option></term>
                                 <term><option>--directory=</option></term>


@@ -204,9 +202,12 @@
                                 <listitem><para>Automatically search
                                 for an init binary and invoke it
                                 instead of a shell or a user supplied
                                 <listitem><para>Automatically search
                                 for an init binary and invoke it
                                 instead of a shell or a user supplied

-                                program. If this option is used, arguments
-                                specified on the command line are used
-                                as arguments for the init binary.
+                                program. If this option is used,
+                                arguments specified on the command
+                                line are used as arguments for the
+                                init binary. This option may not be
+                                combined with
+                                <option>--share-system</option>.

                                 </para></listitem>
                         </varlistentry>
 
                                 </para></listitem>
                         </varlistentry>
 


@@ -238,43 +239,116 @@
                                 container is used.</para></listitem>
                         </varlistentry>
 
                                 container is used.</para></listitem>
                         </varlistentry>
 

+                        <varlistentry>
+                                <term><option>--uuid=</option></term>
+
+                                <listitem><para>Set the specified UUID
+                                for the container. The init system
+                                will initialize
+                                <filename>/etc/machine-id</filename>
+                                from this if this file is not set yet.
+                                </para></listitem>
+                        </varlistentry>
+

                         <varlistentry>
                                 <term><option>--slice=</option></term>
 
                                 <listitem><para>Make the container
                                 part of the specified slice, instead
                         <varlistentry>
                                 <term><option>--slice=</option></term>
 
                                 <listitem><para>Make the container
                                 part of the specified slice, instead

-                                of the
+                                of the default

                                 <filename>machine.slice</filename>.</para>
                                 </listitem>
                         </varlistentry>
 
                         <varlistentry>
                                 <filename>machine.slice</filename>.</para>
                                 </listitem>
                         </varlistentry>
 
                         <varlistentry>

-                                <term><option>--uuid=</option></term>
+                                <term><option>--private-network</option></term>

 
 

-                                <listitem><para>Set the specified UUID
-                                for the container. The init system
-                                will initialize
-                                <filename>/etc/machine-id</filename>
-                                from this if this file is not set yet.
-                                </para></listitem>
+                                <listitem><para>Disconnect networking
+                                of the container from the host. This
+                                makes all network interfaces
+                                unavailable in the container, with the
+                                exception of the loopback device and
+                                those specified with
+                                <option>--network-interface=</option>
+                                and configured with
+                                <option>--network-veth</option>. If
+                                this option is specified, the
+                                CAP_NET_ADMIN capability will be added
+                                to the set of capabilities the
+                                container retains. The latter may be
+                                disabled by using
+                                <option>--drop-capability=</option>.</para></listitem>

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

-                                <term><option>--private-network</option></term>
+                                <term><option>--network-interface=</option></term>
+
+                                <listitem><para>Assign the specified
+                                network interface to the
+                                container. This will move the
+                                specified interface from the calling
+                                namespace and place it in the
+                                container. When the container
+                                terminates, it is moved back to the
+                                host namespace. Note that
+                                <option>--network-interface=</option>
+                                implies
+                                <option>--private-network</option>. This
+                                option may be used more than once to
+                                add multiple network interfaces to the
+                                container.</para></listitem>
+                        </varlistentry>

 
 

-                                <listitem><para>Turn off networking in
-                                the container. This makes all network
-                                interfaces unavailable in the
-                                container, with the exception of the
-                                loopback device.</para></listitem>
+                        <varlistentry>
+                                <term><option>--network-veth</option></term>
+
+                                <listitem><para>Create a virtual
+                                Ethernet link between host and
+                                container. The host side of the
+                                Ethernet link will be available as a
+                                network interface named after the
+                                container's name (as specified with
+                                <option>--machine=</option>), prefixed
+                                with <literal>ve-</literal>. The
+                                container side of the the Ethernet
+                                link will be named
+                                <literal>host0</literal>. Note that
+                                <option>--network-veth</option>
+                                implies
+                                <option>--private-network</option>.</para></listitem>

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

-                                <term><option>--read-only</option></term>
+                                <term><option>--network-bridge=</option></term>
+
+                                <listitem><para>Adds the host side of the
+                                Ethernet link created with
+                                <option>--network-veth</option>
+                                to the specified bridge. Note that
+                                <option>--network-bridge</option>
+                                implies
+                                <option>--network-veth</option>.</para></listitem>
+                        </varlistentry>

 
 

-                                <listitem><para>Mount the root file
-                                system read-only for the
-                                container.</para></listitem>
+                        <varlistentry>
+                                <term><option>-Z</option></term>
+                                <term><option>--selinux-context=</option></term>
+
+                                <listitem><para>Sets the SELinux
+                                security context to be used to label
+                                processes in the container.</para>
+                                </listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><option>-L</option></term>
+                                <term><option>--selinux-apifs-context=</option></term>
+
+                                <listitem><para>Sets the SELinux security
+                                context to be used to label files in
+                                the virtual API file systems in the
+                                container.</para>
+                                </listitem>

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


@@ -300,7 +374,23 @@
                                 CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG,
                                 CAP_SYS_RESOURCE, CAP_SYS_BOOT,
                                 CAP_AUDIT_WRITE,
                                 CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG,
                                 CAP_SYS_RESOURCE, CAP_SYS_BOOT,
                                 CAP_AUDIT_WRITE,

-                                CAP_AUDIT_CONTROL.</para></listitem>
+                                CAP_AUDIT_CONTROL. Also CAP_NET_ADMIN
+                                is retained if
+                                <option>--private-network</option> is
+                                specified. If the special value
+                                <literal>all</literal> is passed, all
+                                capabilities are
+                                retained.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><option>--drop-capability=</option></term>
+
+                                <listitem><para>Specify one or more
+                                additional capabilities to drop for
+                                the container. This allows running the
+                                container with fewer capabilities than
+                                the default (see above).</para></listitem>

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


@@ -351,6 +441,14 @@
                                 <option>--link-journal=guest</option>.</para></listitem>
                         </varlistentry>
 
                                 <option>--link-journal=guest</option>.</para></listitem>
                         </varlistentry>
 

+                        <varlistentry>
+                                <term><option>--read-only</option></term>
+
+                                <listitem><para>Mount the root file
+                                system read-only for the
+                                container.</para></listitem>
+                        </varlistentry>
+

                         <varlistentry>
                                 <term><option>--bind=</option></term>
                                 <term><option>--bind-ro=</option></term>
                         <varlistentry>
                                 <term><option>--bind=</option></term>
                                 <term><option>--bind-ro=</option></term>


@@ -370,6 +468,111 @@
                                 creates read-only bind
                                 mount.</para></listitem>
                         </varlistentry>
                                 creates read-only bind
                                 mount.</para></listitem>
                         </varlistentry>

+
+                        <varlistentry>
+                                <term><option>--setenv=</option></term>
+
+                                <listitem><para>Specifies an
+                                environment variable assignment to
+                                pass to the init process in the
+                                container, in the format
+                                <literal>NAME=VALUE</literal>. This
+                                may be used to override the default
+                                variables or to set additional
+                                variables. This parameter may be used
+                                more than once.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><option>--share-system</option></term>
+
+                                <listitem><para>Allows the container
+                                to share certain system facilities
+                                with the host. More specifically, this
+                                turns off PID namespacing, UTS
+                                namespacing and IPC namespacing, and
+                                thus allows the guest to see and
+                                interact more easily with processes
+                                outside of the container. Note that
+                                using this option makes it impossible
+                                to start up a full Operating System in
+                                the container, as an init system
+                                cannot operate in this mode. It is
+                                only useful to run specific programs
+                                or applications this way, without
+                                involving an init system in the
+                                container. This option implies
+                                <option>--register=no</option>. This
+                                option may not be combined with
+                                <option>--boot</option>.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><option>--register=</option></term>
+
+                                <listitem><para>Controls whether the
+                                container is registered with
+                                <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Takes
+                                a boolean argument, defaults to
+                                <literal>yes</literal>. This option
+                                should be enabled when the container
+                                runs a full Operating System (more
+                                specifically: an init system), and is
+                                useful to ensure that the container is
+                                accessible via
+                                <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+                                and shown by tools such as
+                                <citerefentry><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>. If
+                                the container does not run an init
+                                system, it is recommended to set this
+                                option to <literal>no</literal>. Note
+                                that <option>--share-system</option>
+                                implies
+                                <option>--register=no</option>.
+                                </para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><option>--keep-unit</option></term>
+
+                                <listitem><para>Instead of creating a
+                                transient scope unit to run the
+                                container in, simply register the
+                                service or scope unit
+                                <command>systemd-nspawn</command> has
+                                been invoked in with
+                                <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. This
+                                has no effect if
+                                <option>--register=no</option> is
+                                used. This switch should be used if
+                                <command>systemd-nspawn</command> is
+                                invoked from within a service unit,
+                                and the service unit's sole purpose
+                                is to run a single
+                                <command>systemd-nspawn</command>
+                                container. This option is not
+                                available if run from a user
+                                session.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><option>--personality=</option></term>
+
+                                <listitem><para>Control the
+                                architecture ("personality") reported
+                                by
+                                <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+                                in the container. Currently, only
+                                <literal>x86</literal> and
+                                <literal>x86-64</literal> are
+                                supported. This is useful when running
+                                a 32bit container on a 64bit
+                                host. If this setting is not used
+                                the personality reported in the
+                                container is the same as the one
+                                reported on the
+                                host.</para></listitem>
+                        </varlistentry>

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


@@ -409,22 +612,35 @@
                 boots an OS in a namespace container in it.</para>
         </refsect1>
 
                 boots an OS in a namespace container in it.</para>
         </refsect1>
 

-        <refsect1 id='example-nsenter'>
+        <refsect1>

                 <title>Example 4</title>
 
                 <title>Example 4</title>
 

-                <para>To enter the container, PID of one of the
-                processes sharing the new namespaces must be used.
-                <command>systemd-nspawn</command> prints the PID
-                (as viewed from the outside) of the launched process,
-                and it can be used to enter the container.</para>
+                <programlisting># mv ~/arch-tree /var/lib/container/arch
+# systemctl enable systemd-nspawn@arch.service
+# systemctl start systemd-nspawn@arch.service</programlisting>
+
+                <para>This makes the Arch Linux container part of the
+                <filename>multi-user.target</filename> on the host.
+                </para>
+        </refsect1>
+
+        <refsect1>
+                <title>Example 5</title>
+
+                <programlisting># btrfs subvolume snapshot / /.tmp
+# systemd-nspawn --private-network -D /.tmp -b</programlisting>
+
+                <para>This runs a copy of the host system in a
+                btrfs snapshot.</para>
+        </refsect1>
+
+        <refsect1>
+                <title>Example 6</title>

 
 

-                <programlisting># nsenter -m -u -i -n -p -t $PID</programlisting>
+                <programlisting># chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container
+# systemd-nspawn -L system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -Z system_u:system_r:svirt_lxc_net_t:s0:c0,c1 -D /srv/container /bin/sh</programlisting>

 
 

-                <para><citerefentry><refentrytitle>nsenter</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-                is part of
-                <ulink url="https://github.com/karelzak/util-linux">util-linux</ulink>.
-                Kernel support for entering namespaces was added in
-                Linux 3.8.</para>
+                <para>This runs a container with SELinux sandbox security contexts.</para>

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


@@ -439,11 +655,11 @@
                 <para>
                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                 <para>
                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

-                        <citerefentry><refentrytitle>unshare</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

                         <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>,

-                        <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                        <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>

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