along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
-<refentry id="systemd-nspawn">
+<refentry id="systemd-nspawn"
+ xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>systemd-nspawn</title>
<para><command>systemd-nspawn</command> may be used to
run a command or OS in a light-weight namespace
container. In many ways it is similar to
- <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
but more powerful since it fully virtualizes the file
system hierarchy, as well as the process tree, the
various IPC subsystems and the host and domain
involved with boot and systems management.</para>
<para>In contrast to
- <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry> <command>systemd-nspawn</command>
+ <citerefentry project='man-pages'><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 project='die-net'><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+ <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
or
- <citerefentry><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ <citerefentry project='archlinux'><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>
<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
+ existence of <filename>/usr/lib/os-release</filename>
+ or <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
<para>The following options are understood:</para>
<variablelist>
- <varlistentry>
- <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>--version</option></term>
-
- <listitem><para>Prints a version string
- 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>
<listitem><para>Directory to use as
- file system root for the namespace
- container. If omitted, the current
- directory will be
- used.</para></listitem>
+ file system root for the container. If
+ neither <option>--directory=</option>
+ nor <option>--image=</option> are
+ specified, the current directory will
+ be used. May not be specified together with
+ <option>--image=</option>.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-i</option></term>
+ <term><option>--image=</option></term>
+
+ <listitem><para>Disk image to mount
+ the root directory for the container
+ from. Takes a path to a regular file
+ or to a block device node. The file or
+ block device must contain a GUID
+ Partition Table with a root partition
+ which is mounted as the root directory
+ of the container. Optionally, it may
+ contain a home and/or a server data
+ partition which are mounted to the
+ appropriate places in the
+ container. All these partitions must
+ be identified by the partition types
+ defined by the <ulink
+ url="http://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/">Discoverable
+ Partitions Specification</ulink>. Any
+ other partitions, such as foreign
+ partitions, swap partitions or EFI
+ system partitions are not mounted. May
+ not be specified together with
+ <option>--directory=</option>.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-u</option></term>
<term><option>--user=</option></term>
- <listitem><para>Run the command
- under specified user, create home
- directory and cd into it. As rest
- of systemd-nspawn, this is not
- the security feature and limits
- against accidental changes only.
- </para></listitem>
+ <listitem><para>After transitioning
+ into the container, change to the
+ specified user-defined in the
+ container's user database. Like all
+ other systemd-nspawn features, this is
+ not a security feature and provides
+ protection against accidental
+ destructive operations
+ only.</para></listitem>
</varlistentry>
<varlistentry>
<listitem><para>Assign the specified
network interface to the
- container. This will move the
+ container. This will remove the
specified interface from the calling
namespace and place it in the
container. When the container
container.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>--network-macvlan=</option></term>
+
+ <listitem><para>Create a
+ <literal>macvlan</literal> interface
+ of the specified Ethernet network
+ interface and add it to the
+ container. A
+ <literal>macvlan</literal> interface
+ is a virtual interface that adds a
+ second MAC address to an existing
+ physical Ethernet link. The interface
+ in the container will be named after
+ the interface on the host, prefixed
+ with <literal>mv-</literal>. Note that
+ <option>--network-macvlan=</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>
+
<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
+ (<literal>veth</literal>) 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
+ container side of the Ethernet
link will be named
<literal>host0</literal>. Note that
<option>--network-veth</option>
<varlistentry>
<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>
+ <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>
+ <option>--network-veth</option>. If
+ this option is used, the host side of
+ the Ethernet link will use the
+ <literal>vb-</literal> prefix instead
+ of <literal>ve-</literal>.</para></listitem>
</varlistentry>
<varlistentry>
additional capabilities to grant the
container. Takes a comma-separated
list of capability names, see
- <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
for more information. Note that the
following capabilities will be granted
in any way: CAP_CHOWN,
destination in the container. The
<option>--bind-ro=</option> option
creates read-only bind
- mount.</para></listitem>
+ mounts.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--tmpfs=</option></term>
+
+ <listitem><para>Mount a tmpfs file
+ system into the container. Takes a
+ single absolute path argument that
+ specifies where to mount the tmpfs
+ instance to (in which case the
+ directory access mode will be chosen
+ as 0755, owned by root/root), or
+ optionally a colon-separated pair of
+ path and mount option string, that is
+ used for mounting (in which case the
+ kernel default for access mode and
+ owner will be chosen, unless otherwise
+ specified). This option is
+ particularly useful for mounting
+ directories such as
+ <filename>/var</filename> as tmpfs, to
+ allow state-less systems, in
+ particular when combined with
+ <option>--read-only</option>.</para></listitem>
</varlistentry>
<varlistentry>
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
+ <citerefentry project='man-pages'><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
<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
+ a 32-bit container on a 64-bit
+ 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>
+
+ <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>--volatile</option><replaceable>=MODE</replaceable></term>
+
+ <listitem><para>Boots the container in
+ volatile (ephemeral) mode. When no
+ mode parameter is passed or when mode
+ is specified as <literal>yes</literal>
+ full volatile mode is enabled. This
+ means the root directory is mounted as
+ mostly unpopulated
+ <literal>tmpfs</literal> instance, and
+ <filename>/usr</filename> from the OS
+ tree is mounted into it, read-only
+ (the system thus starts up with
+ read-only OS resources, but pristine
+ state and configuration, any changes
+ to the either are lost on
+ shutdown). When the mode parameter is
+ specified as <literal>state</literal>
+ the OS tree is mounted read-only, but
+ <filename>/var</filename> is mounted
+ as <literal>tmpfs</literal> instance
+ into it (the system thus starts up
+ with read-only OS resources and
+ configuration, but pristine state, any
+ changes to the latter are lost on
+ shutdown). When the mode parameter is
+ specified as <literal>no</literal>
+ (the default) the whole OS tree is made
+ available writable.</para>
+
+ <para>Note that setting this to
+ <literal>yes</literal> or
+ <literal>state</literal> will only
+ work correctly with operating systems
+ in the container that can boot up with
+ only <filename>/usr</filename>
+ mounted, and are able to populate
+ <filename>/var</filename>
+ automatically, as
+ needed.</para></listitem>
+ </varlistentry>
+
+ <xi:include href="standard-options.xml" xpointer="help" />
+ <xi:include href="standard-options.xml" xpointer="version" />
</variablelist>
</refsect1>
<refsect1>
- <title>Example 1</title>
+ <title>Examples</title>
+ <example>
+ <title>Boot a minimal Fedora distribution in a container</title>
- <programlisting># yum -y --releasever=19 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal
+
<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 noindex='true'>/srv/mycontainer/</filename> and
- then boots an OS in a namespace container in
- it.</para>
- </refsect1>
+
<para>This installs a minimal Fedora distribution into
+ the directory <filename noindex='true'>/srv/mycontainer/</filename> and
+ then boots an OS in a namespace container in
+ it.</para>
+ </example>
- <refsect1>
- <title>Example 2</title>
+ <example>
+ <title>Spawn a shell in a container of a minimal Debian unstable distribution</title>
- <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
+
<programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
# systemd-nspawn -D ~/debian-tree/</programlisting>
- <para>This installs a minimal Debian unstable
- distribution into the directory
- <filename>~/debian-tree/</filename> and then spawns a
- shell in a namespace container in it.</para>
- </refsect1>
+
<para>This installs a minimal Debian unstable
+ distribution into the directory
+ <filename>~/debian-tree/</filename> and then spawns a
+ shell in a namespace container in it.</para>
+ </example>
- <refsect1>
- <title>Example 3</title>
+ <example>
+ <title>Boot a minimal Arch Linux distribution in a container</title>
- <programlisting># pacstrap -c -d ~/arch-tree/ base
+
<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>
+
<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>
+ </example>
- <refsect1>
- <title>Example 4</title>
+ <example>
+ <title>Enable Arch Linux container on boot</title>
- <programlisting># mv ~/arch-tree /var/lib/container/arch
+
<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>
+
<para>This makes the Arch Linux container part of the
+ <filename>multi-user.target</filename> on the host.
+ </para>
+ </example>
- <refsect1>
- <title>Example 5</title>
+ <example>
+ <title>Boot into a btrfs snapshot of the host system</title>
- <programlisting># btrfs subvolume snapshot / /.tmp
+
<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>
+
<para>This runs a copy of the host system in a
+ btrfs snapshot.</para>
+ </example>
- <refsect1>
- <title>Example 6</title>
+ <example>
+ <title>Run a container with SELinux sandbox security contexts</title>
- <programlisting># chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container
+
<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>This runs a container with SELinux sandbox security contexts.</para>
+ </example>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>chroot</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 project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry project='die-net'><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+ <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+ <citerefentry project='archlinux'><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>
~ianmdlvl / elogind.git / blobdiff