<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>
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>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
or
- <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>
to set up an OS directory tree suitable as file system
hierarchy for <command>systemd-nspawn</command>
containers.</para>
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>
- <term><option>--help</option></term>
<term><option>-h</option></term>
+ <term><option>--help</option></term>
<listitem><para>Prints a short help
text and exits.</para></listitem>
</varlistentry>
<varlistentry>
- <term><option>--directory=</option></term>
+ <term><option>--version</option></term>
+
+ <listitem><para>Prints a version string
+ and exits.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>-D</option></term>
+ <term><option>--directory=</option></term>
<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>
<varlistentry>
- <term><option>--boot</option></term>
<term><option>-b</option></term>
+ <term><option>--boot</option></term>
<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>
- <term><option>--user=</option></term>
<term><option>-u</option></term>
+ <term><option>--user=</option></term>
<listitem><para>Run the command
under specified user, create home
</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>--controllers=</option></term>
- <term><option>-C</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
- the following capabilities will be
- granted in any way: CAP_CHOWN,
+ following capabilities will be granted
+ in any way: CAP_CHOWN,
CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
CAP_KILL, CAP_LEASE,
CAP_SETUID, CAP_SYS_ADMIN,
CAP_SYS_CHROOT, CAP_SYS_NICE,
CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG,
- CAP_SYS_RESOURCE, CAP_SYS_BOOT.</para></listitem>
+ CAP_SYS_RESOURCE, CAP_SYS_BOOT,
+ CAP_AUDIT_WRITE,
+ CAP_AUDIT_CONTROL.</para></listitem>
</varlistentry>
<varlistentry>
<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
<literal>host</literal>,
<literal>guest</literal>,
<literal>auto</literal>. If
- <literal>no</literal> the journal is
- not linked. If <literal>host</literal>
+ <literal>no</literal>, the journal is
+ not linked. If <literal>host</literal>,
the journal files are stored on the
- host file system (beneath the host's
- <filename>/var/log/journal</filename>)
- and a per-machine subdirectory of this
- directory is created and bind mounted
+ host file system (beneath
+ <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
+ and the subdirectory is bind-mounted
into the container at the same
- location. If <literal>guest</literal>
+ location. If <literal>guest</literal>,
the journal files are stored on the
- guest file system (beneath the guest's
- <filename>/var/log/journal</filename>)
- and a per-machine subdirectory of this
- directory is symlinked into the host
+ guest file system (beneath
+ <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
+ and the subdirectory is symlinked into the host
at the same location. If
- <literal>auto</literal> (the default)
- and the subdirectory of
+ <literal>auto</literal> (the default),
+ and the right subdirectory of
<filename>/var/log/journal</filename>
- exists as directory it is bind mounted
- into the container, but nothing is
- done otherwise. Effectively, booting a
- container once with
+ exists, it will be bind mounted
+ into the container. If the
+ subdirectory does not exist, no
+ linking is performed. Effectively,
+ booting a container once with
<literal>guest</literal> or
<literal>host</literal> will link the
- journal persistantly if further one
+ journal persistently if further on
the default of <literal>auto</literal>
is used.</para></listitem>
</varlistentry>
<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>
<refsect1>
<title>Example 1</title>
- <programlisting># yum --releasever=17 --nogpgcheck --installroot ~/fedora-tree/ install yum passwd vim-minimal rootfiles systemd
-# systemd-nspawn -D ~/fedora-tree /usr/lib/systemd/systemd</programlisting>
+ <programlisting># yum -y --releasever=19 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal
+# systemd-nspawn -bD /srv/mycontainer</programlisting>
<para>This installs a minimal Fedora distribution into
- the directory <filename>~/fedora-tree/</filename>
- and then boots an OS in a namespace container in it,
- with systemd as init system.</para>
+ the directory <filename noindex='true'>/srv/mycontainer/</filename> and
+ then boots an OS in a namespace container in
+ it.</para>
</refsect1>
<refsect1>
distribution into the directory
<filename>~/debian-tree/</filename> and then spawns a
shell in a namespace container in it.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Example 3</title>
+
+ <programlisting># pacstrap -c -d ~/arch-tree/ base
+# systemd-nspawn -bD ~/arch-tree/</programlisting>
+
+ <para>This installs a mimimal Arch Linux distribution into
+ the directory <filename>~/arch-tree/</filename> and then
+ 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>
<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>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>
</para>
</refsect1>
~ianmdlvl / elogind.git / blobdiff