nspawn: add new --setenv= switch to set an environment variable for the container...

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

diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml
index 8adcd946b0438e6da634576eefc780a99ada068a..bec233c1ca9eb9c056df7dc72a385483b3de8a16 100644 (file)
--- a/man/systemd-nspawn.xml
+++ b/man/systemd-nspawn.xml
@@ -97,14 +97,13 @@
                 involved with boot and systems management.</para>
 
                 <para>In contrast to
                 involved with boot and systems management.</para>
 
                 <para>In contrast to

-                <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-                <command>systemd-nspawn</command> may be used to boot
-                full Linux-based operating systems in a
-                container.</para>
+                <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry> <command>systemd-nspawn</command>
+                may be used to boot full Linux-based operating systems
+                in a container.</para>

 
                 <para>Use a tool like
                 <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 
                 <para>Use a tool like
                 <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,

-                <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+                <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,

                 or
                 <citerefentry><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>
                 to set up an OS directory tree suitable as file system
                 or
                 <citerefentry><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>
                 to set up an OS directory tree suitable as file system


@@ -124,15 +123,37 @@
                 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
                 url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container
                 Interface</ulink> specification.</para>
 
                 <para><command>systemd-nspawn</command> implements the
                 <ulink
                 url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container
                 Interface</ulink> specification.</para>

+
+                <para>As a safety check
+                <command>systemd-nspawn</command> will verify the
+                existence of <filename>/etc/os-release</filename> in
+                the container tree before starting the container (see
+                <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>). It
+                might be necessary to add this file to the container
+                tree manually if the OS of the container is too old to
+                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>
         </refsect1>
 
         <refsect1>


@@ -171,7 +192,7 @@
 
                                 <listitem><para>Directory to use as
                                 file system root for the namespace
 
                                 <listitem><para>Directory to use as
                                 file system root for the namespace

-                                container. If omitted the current
+                                container. If omitted, the current

                                 directory will be
                                 used.</para></listitem>
                         </varlistentry>
                                 directory will be
                                 used.</para></listitem>
                         </varlistentry>


@@ -202,10 +223,35 @@
                                 </para></listitem>
                         </varlistentry>
 
                                 </para></listitem>
                         </varlistentry>
 

+                        <varlistentry>
+                                <term><option>-M</option></term>
+                                <term><option>--machine=</option></term>
+
+                                <listitem><para>Sets the machine name
+                                for this container. This name may be
+                                used to identify this container on the
+                                host, and is used to initialize the
+                                container's hostname (which the
+                                container can choose to override,
+                                however). If not specified, the last
+                                component of the root directory of the
+                                container is used.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><option>--slice=</option></term>
+
+                                <listitem><para>Make the container
+                                part of the specified slice, instead
+                                of the
+                                <filename>machine.slice</filename>.</para>
+                                </listitem>
+                        </varlistentry>
+

                         <varlistentry>
                                 <term><option>--uuid=</option></term>
 
                         <varlistentry>
                                 <term><option>--uuid=</option></term>
 

-                                <listitem><para>Set the specified uuid
+                                <listitem><para>Set the specified UUID

                                 for the container. The init system
                                 will initialize
                                 <filename>/etc/machine-id</filename>
                                 for the container. The init system
                                 will initialize
                                 <filename>/etc/machine-id</filename>


@@ -213,16 +259,6 @@
                                 </para></listitem>
                         </varlistentry>
 
                                 </para></listitem>
                         </varlistentry>
 

-                        <varlistentry>
-                                <term><option>-C</option></term>
-                                <term><option>--controllers=</option></term>
-
-                                <listitem><para>Makes the container appear in
-                                other hierarchies than the name=systemd:/ one.
-                                Takes a comma-separated list of controllers.
-                                </para></listitem>
-                        </varlistentry>
-

                         <varlistentry>
                                 <term><option>--private-network</option></term>
 
                         <varlistentry>
                                 <term><option>--private-network</option></term>
 


@@ -237,7 +273,7 @@
                                 <term><option>--read-only</option></term>
 
                                 <listitem><para>Mount the root file
                                 <term><option>--read-only</option></term>
 
                                 <listitem><para>Mount the root file

-                                system read only for the
+                                system read-only for the

                                 container.</para></listitem>
                         </varlistentry>
 
                                 container.</para></listitem>
                         </varlistentry>
 


@@ -246,7 +282,7 @@
 
                                 <listitem><para>List one or more
                                 additional capabilities to grant the
 
                                 <listitem><para>List one or more
                                 additional capabilities to grant the

-                                container. Takes a comma separated
+                                container. Takes a comma-separated

                                 list of capability names, see
                                 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                                 for more information. Note that the
                                 list of capability names, see
                                 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                                 for more information. Note that the


@@ -267,12 +303,22 @@
                                 CAP_AUDIT_CONTROL.</para></listitem>
                         </varlistentry>
 
                                 CAP_AUDIT_CONTROL.</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>
                                 <term><option>--link-journal=</option></term>
 
                                 <listitem><para>Control whether the
                                 container's journal shall be made
                         <varlistentry>
                                 <term><option>--link-journal=</option></term>
 
                                 <listitem><para>Control whether the
                                 container's journal shall be made

-                                visible to the host system. If enabled
+                                visible to the host system. If enabled,

                                 allows viewing the container's journal
                                 files from the host (but not vice
                                 versa). Takes one of
                                 allows viewing the container's journal
                                 files from the host (but not vice
                                 versa). Takes one of


@@ -298,7 +344,7 @@
                                 <filename>/var/log/journal</filename>
                                 exists, it will be bind mounted
                                 into the container. If the
                                 <filename>/var/log/journal</filename>
                                 exists, it will be bind mounted
                                 into the container. If the

-                                subdirectory doesn't exist, no
+                                subdirectory does not exist, no

                                 linking is performed. Effectively,
                                 booting a container once with
                                 <literal>guest</literal> or
                                 linking is performed. Effectively,
                                 booting a container once with
                                 <literal>guest</literal> or


@@ -334,6 +380,21 @@
                                 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>
+

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


@@ -345,7 +406,7 @@
 # systemd-nspawn -bD /srv/mycontainer</programlisting>
 
                 <para>This installs a minimal Fedora distribution into
 # systemd-nspawn -bD /srv/mycontainer</programlisting>
 
                 <para>This installs a minimal Fedora distribution into

-                the directory <filename>/srv/mycontainer/</filename> and
+                the directory <filename noindex='true'>/srv/mycontainer/</filename> and

                 then boots an OS in a namespace container in
                 it.</para>
         </refsect1>
                 then boots an OS in a namespace container in
                 it.</para>
         </refsect1>


@@ -373,24 +434,29 @@
                 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># nsenter -muinpt $PID</programlisting>
+                <programlisting># btrfs subvolume snapshot / /.tmp
+# systemd-nspawn --private-network -D /.tmp -b</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 copy of the host system in a
+                btrfs snapshot.</para>

         </refsect1>
 
         </refsect1>
 

+

         <refsect1>
                 <title>Exit status</title>
 
         <refsect1>
                 <title>Exit status</title>
 


@@ -403,10 +469,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>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,

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

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