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='arch'><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, then the only output
- by 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>
exception of the loopback device and
those specified with
<option>--network-interface=</option>
- and configured ith
+ and configured with
<option>--network-veth</option>. If
- this option is specified the
+ this option is specified, the
CAP_NET_ADMIN capability will be added
to the set of capabilities the
container retains. The latter may be
<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
- terminates it is moved back to the
+ terminates, it is moved back to the
host namespace. Note that
<option>--network-interface=</option>
implies
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 will be available as
+ 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>
<option>--private-network</option>.</para></listitem>
</varlistentry>
+ <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>
+ implies
+ <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>
<term><option>-Z</option></term>
<term><option>--selinux-context=</option></term>
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,
is retained if
<option>--private-network</option> is
specified. If the special value
- <literal>all</literal> is passed all
+ <literal>all</literal> is passed, all
capabilities are
retained.</para></listitem>
</varlistentry>
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
+ system, it is recommended to set this
option to <literal>no</literal>. Note
that <option>--share-system</option>
implies
container in, simply register the
service or scope unit
<command>systemd-nspawn</command> has
- been invoked in in
+ been invoked in with
<citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. This
has no effect if
<option>--register=no</option> is
used. This switch should be used if
<command>systemd-nspawn</command> is
- invoked from within an a service unit,
+ invoked from within a service unit,
and the service unit's sole purpose
is to run a single
<command>systemd-nspawn</command>
session.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>--personality=</option></term>
+
+ <listitem><para>Control the
+ architecture ("personality") reported
+ by
+ <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ in the container. Currently, only
+ <literal>x86</literal> and
+ <literal>x86-64</literal> are
+ supported. This is useful when running
+ 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>
<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='arch'><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