<refsynopsisdiv>
<cmdsynopsis>
- <command>systemd-nspawn <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">COMMAND</arg> <arg choice="opt" rep="repeat">ARGS</arg></command>
+ <command>systemd-nspawn</command>
+ <arg choice="opt" rep="repeat">OPTIONS</arg>
+ <arg choice="opt"><replaceable>COMMAND</replaceable>
+ <arg choice="opt" rep="repeat">ARGS</arg>
+ </arg>
+ </cmdsynopsis>
+ <cmdsynopsis>
+ <command>systemd-nspawn</command>
+ <arg choice="plain">-b</arg>
+ <arg choice="opt" rep="repeat">OPTIONS</arg>
+ <arg choice="opt" rep="repeat">ARGS</arg>
</cmdsynopsis>
</refsynopsisdiv>
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.</para>
+ underlying file system. It is however possible to
+ enter an existing container, see
+ <link linkend='example-nsenter'>Example 4</link> below.
+ </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>
<title>Options</title>
- <para>If no arguments are passed the container is set
- up and a shell started in it, otherwise the passed
- command and arguments are executed in it. The
- following options are understood:</para>
+ <para>If option <option>-b</option> is specified, the
+ arguments are used as arguments for the init
+ binary. Otherwise, <replaceable>COMMAND</replaceable>
+ specifies the program to launch in the container, and
+ the remaining arguments are used as arguments for this
+ program. If <option>-b</option> is not used and no
+ arguments are specifed, a shell is launched in the
+ container.</para>
+
+ <para>The following options are understood:</para>
<variablelist>
<varlistentry>
<listitem><para>Automatically search
for an init binary and invoke it
instead of a shell or a user supplied
- program.</para></listitem>
+ program. If this option is used, arguments
+ specified on the command line are used
+ as arguments for the init binary.
+ </para></listitem>
</varlistentry>
<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>
- <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
<listitem><para>Equivalent to
<option>--link-journal=guest</option>.</para></listitem>
</varlistentry>
+
+ <varlistentry>
+ <term><option>--bind=</option></term>
+ <term><option>--bind-ro=</option></term>
+
+ <listitem><para>Bind mount a file or
+ directory from the host into the
+ container. Either takes a path
+ argument -- in which case the
+ specified path will be mounted from
+ the host to the same path in the
+ container --, or a colon-separated
+ pair of paths -- in which case the
+ first specified path is the source in
+ the host, and the second path is the
+ destination in the container. The
+ <option>--bind-ro=</option> option
+ creates read-only bind
+ mount.</para></listitem>
+ </varlistentry>
</variablelist>
</refsect1>
# 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>
distribution into the directory
<filename>~/debian-tree/</filename> and then spawns a
shell in a namespace container in it.</para>
-
</refsect1>
<refsect1>
boots an OS in a namespace container in it.</para>
</refsect1>
+ <refsect1 id='example-nsenter'>
+ <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># nsenter -m -u -i -n -p -t $PID</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>
+ </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>
</para>
</refsect1>