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>,
- <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
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>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>
<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>
host, and is used to initialize the
container's hostname (which the
container can choose to override,
- however). If not specified the last
+ 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>
- <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>
</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>
<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>
<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
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
- 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
<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
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>
boots an OS in a namespace container in it.</para>
</refsect1>
- <refsect1 id='example-nsenter'>
+ <refsect1>
<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>
- <programlisting># nsenter -m -u -i -n -p -t $PID</programlisting>
+ <para>This makes the Arch Linux container part of the
+ <filename>multi-user.target</filename> on the host.
+ </para>
+ </refsect1>
- <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>
+ <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>Exit status</title>
<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>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>