<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
<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.</para>
+
+ <para>If neither
+ <option>--directory=</option>, nor
+ <option>--image=</option> is specified
+ the directory is determined as
+ <filename>/var/lib/container/</filename>
+ suffixed by the machine name as
+ specified with
+ <option>--machine=</option>. If
+ neither <option>--directory=</option>,
+ <option>--image=</option>, nor
+ <option>--machine=</option> are
+ specified, the current directory will
+ be used. May not be specified together
+ with
+ <option>--image=</option>.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--template=</option></term>
+
+ <listitem><para>Directory or
+ <literal>btrfs</literal> subvolume to
+ use as template for the container's
+ root directory. If this is specified
+ and the container's root directory (as
+ configured by
+ <option>--directory=</option>) does
+ not yet exist it is created as
+ <literal>btrfs</literal> subvolume and
+ populated from this template
+ tree. Ideally, the specified template
+ path refers to the root of a
+ <literal>btrfs</literal> subvolume, in
+ which case a simple copy-on-write
+ snapshot is taken, and populating the
+ root directory is instant. If the
+ specified template path does not refer
+ to the root of a
+ <literal>btrfs</literal> subvolume (or
+ not even to a <literal>btrfs</literal>
+ file system at all), the tree is
+ copied, which can be substantially
+ more time-consuming. Note that if this
+ option is used the container's root
+ directory (in contrast to the template
+ directory!) must be located on a
+ <literal>btrfs</literal> file system,
+ so that the <literal>btrfs</literal>
+ subvolume may be created. May not be
+ specified together with
+ <option>--image=</option> or
+ <option>--ephemeral</option>.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-x</option></term>
+ <term><option>--ephemeral</option></term>
+
+ <listitem><para>If specified, the
+ container is run with a temporary
+ <literal>btrfs</literal> snapshot of
+ its root directory (as configured with
+ <option>--directory=</option>), that
+ is removed immediately when the
+ container terminates. This option is
+ only supported if the root file system
+ is <literal>btrfs</literal>. May not
+ be specified together with
+ <option>--image=</option> or
+ <option>--template=</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>,
+ <option>--template=</option> or
+ <option>--ephemeral</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>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>
+ used to identify this container during
+ its runtime (for example in tools like
+ <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ and similar), 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 path of the container is
+ used, possibly suffixed with a random
+ identifier in case
+ <option>--ephemeral</option> mode is
+ selected. If the root directory
+ selected is the host's root directory
+ the host's hostname is used as default
+ instead.</para></listitem>
</varlistentry>
<varlistentry>
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>
<option>--network-bridge=</option>
implies
<option>--network-veth</option>. If
- this option is used the host side of
+ 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>
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,
versa). Takes one of
<literal>no</literal>,
<literal>host</literal>,
+ <literal>try-host</literal>,
<literal>guest</literal>,
+ <literal>try-guest</literal>,
<literal>auto</literal>. If
<literal>no</literal>, the journal is
not linked. If <literal>host</literal>,
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),
+ at the same location. <literal>try-host</literal>
+ and <literal>try-guest</literal> do the same
+ but do not fail if the host does not have
+ persistent journalling enabled.
+ If <literal>auto</literal> (the default),
and the right subdirectory of
<filename>/var/log/journal</filename>
exists, it will be bind mounted
<term><option>-j</option></term>
<listitem><para>Equivalent to
- <option>--link-journal=guest</option>.</para></listitem>
+ <option>--link-journal=try-guest</option>.</para></listitem>
</varlistentry>
<varlistentry>
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>
<term><option>--setenv=</option></term>
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
of the container OS itself.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>--volatile</option><replaceable>=MODE</replaceable></term>
+
+ <listitem><para>Boots the container in
+ volatile 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=21 --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 an ephemeral <literal>btrfs</literal> snapshot of the host system</title>
- <programlisting># btrfs subvolume snapshot / /.tmp
-# systemd-nspawn --private-network -D /.tmp -b</programlisting>
+ <programlisting># systemd-nspawn -D / -xb</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
+ <literal>btrfs</literal> snapshot which is
+ removed immediately when the container
+ exits. All file system changes made during
+ runtime will be lost on shutdown,
+ hence.</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>
+ <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
</para>
</refsect1>
~ianmdlvl / elogind.git / blobdiff