mirror of
https://github.com/systemd/systemd.git
synced 2024-11-23 18:23:32 +08:00
941 lines
51 KiB
XML
941 lines
51 KiB
XML
<?xml version='1.0'?> <!--*-nxml-*-->
|
||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
||
|
||
<!--
|
||
This file is part of systemd.
|
||
|
||
Copyright 2010 Lennart Poettering
|
||
|
||
systemd is free software; you can redistribute it and/or modify it
|
||
under the terms of the GNU Lesser General Public License as published by
|
||
the Free Software Foundation; either version 2.1 of the License, or
|
||
(at your option) any later version.
|
||
|
||
systemd is distributed in the hope that it will be useful, but
|
||
WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
||
Lesser General Public License for more details.
|
||
|
||
You should have received a copy of the GNU Lesser General Public License
|
||
along with systemd; If not, see <http://www.gnu.org/licenses/>.
|
||
-->
|
||
|
||
<refentry id="systemd-nspawn"
|
||
xmlns:xi="http://www.w3.org/2001/XInclude">
|
||
|
||
<refentryinfo>
|
||
<title>systemd-nspawn</title>
|
||
<productname>systemd</productname>
|
||
|
||
<authorgroup>
|
||
<author>
|
||
<contrib>Developer</contrib>
|
||
<firstname>Lennart</firstname>
|
||
<surname>Poettering</surname>
|
||
<email>lennart@poettering.net</email>
|
||
</author>
|
||
</authorgroup>
|
||
</refentryinfo>
|
||
|
||
<refmeta>
|
||
<refentrytitle>systemd-nspawn</refentrytitle>
|
||
<manvolnum>1</manvolnum>
|
||
</refmeta>
|
||
|
||
<refnamediv>
|
||
<refname>systemd-nspawn</refname>
|
||
<refpurpose>Spawn a namespace container for debugging, testing and building</refpurpose>
|
||
</refnamediv>
|
||
|
||
<refsynopsisdiv>
|
||
<cmdsynopsis>
|
||
<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>
|
||
|
||
<refsect1>
|
||
<title>Description</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 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
|
||
name.</para>
|
||
|
||
<para><command>systemd-nspawn</command> limits access
|
||
to various kernel interfaces in the container to
|
||
read-only, such as <filename>/sys</filename>,
|
||
<filename>/proc/sys</filename> or
|
||
<filename>/sys/fs/selinux</filename>. Network
|
||
interfaces and the system clock may not be changed
|
||
from within the container. Device nodes may not be
|
||
created. The host system cannot be rebooted and kernel
|
||
modules may not be loaded from within the
|
||
container.</para>
|
||
|
||
<para>Note that even though these security precautions
|
||
are taken <command>systemd-nspawn</command> is not
|
||
suitable for secure container setups. Many of the
|
||
security features may be circumvented and are hence
|
||
primarily useful to avoid accidental changes to the
|
||
host system from the container. The intended use of
|
||
this program is debugging and testing as well as
|
||
building of packages, distributions and software
|
||
involved with boot and systems management.</para>
|
||
|
||
<para>In contrast to
|
||
<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 project='mankier'><refentrytitle>dnf</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 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>Note that <command>systemd-nspawn</command> will
|
||
mount file systems private to the container to
|
||
<filename>/dev</filename>,
|
||
<filename>/run</filename> and similar. These will
|
||
not be visible outside of the container, and their
|
||
contents will be lost when the container exits.</para>
|
||
|
||
<para>Note that running two
|
||
<command>systemd-nspawn</command> containers from the
|
||
same directory tree will not make processes in them
|
||
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. Use
|
||
<citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
|
||
<command>login</command> command to request an
|
||
additional login prompt in a running container.</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>/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
|
||
contain this file out-of-the-box.</para>
|
||
</refsect1>
|
||
|
||
<refsect1>
|
||
<title>Options</title>
|
||
|
||
<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>-D</option></term>
|
||
<term><option>--directory=</option></term>
|
||
|
||
<listitem><para>Directory to use as
|
||
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/machines/</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 either:</para>
|
||
|
||
<itemizedlist>
|
||
<listitem><para>An MBR
|
||
partition table with a single
|
||
partition of type 0x83 that is
|
||
marked
|
||
bootable.</para></listitem>
|
||
|
||
<listitem><para>A GUID
|
||
partition table (GPT) with a single
|
||
partition of type
|
||
0fc63daf-8483-4772-8e79-3d69d8477de4.</para></listitem>
|
||
|
||
<listitem><para>A GUID
|
||
partition table (GPT) with a
|
||
marked root partition which is
|
||
mounted as the root directory
|
||
of the container. Optionally,
|
||
GPT images 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>.</para></listitem>
|
||
</itemizedlist>
|
||
|
||
<para>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>-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. If this option is used,
|
||
arguments specified on the command
|
||
line are used as arguments for the
|
||
init binary. This option may not be
|
||
combined with
|
||
<option>--share-system</option>.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><option>-u</option></term>
|
||
<term><option>--user=</option></term>
|
||
|
||
<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>
|
||
<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 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>
|
||
<term><option>--uuid=</option></term>
|
||
|
||
<listitem><para>Set the specified UUID
|
||
for the container. The init system
|
||
will initialize
|
||
<filename>/etc/machine-id</filename>
|
||
from this if this file is not set yet.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><option>--slice=</option></term>
|
||
|
||
<listitem><para>Make the container
|
||
part of the specified slice, instead
|
||
of the default
|
||
<filename>machine.slice</filename>.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><option>--private-network</option></term>
|
||
|
||
<listitem><para>Disconnect networking
|
||
of the container from the host. This
|
||
makes all network interfaces
|
||
unavailable in the container, with the
|
||
exception of the loopback device and
|
||
those specified with
|
||
<option>--network-interface=</option>
|
||
and configured with
|
||
<option>--network-veth</option>. If
|
||
this option is specified, the
|
||
CAP_NET_ADMIN capability will be added
|
||
to the set of capabilities the
|
||
container retains. The latter may be
|
||
disabled by using
|
||
<option>--drop-capability=</option>.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><option>--network-interface=</option></term>
|
||
|
||
<listitem><para>Assign the specified
|
||
network interface to 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
|
||
host namespace. Note that
|
||
<option>--network-interface=</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-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-ipvlan=</option></term>
|
||
|
||
<listitem><para>Create an
|
||
<literal>ipvlan</literal> interface
|
||
of the specified Ethernet network
|
||
interface and add it to the
|
||
container. An
|
||
<literal>ipvlan</literal> interface
|
||
is a virtual interface, similar to a
|
||
<literal>macvlan</literal> interface, which
|
||
uses the same MAC address as the underlying
|
||
interface. The interface
|
||
in the container will be named after
|
||
the interface on the host, prefixed
|
||
with <literal>iv-</literal>. Note that
|
||
<option>--network-ipvlan=</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>-n</option></term>
|
||
<term><option>--network-veth</option></term>
|
||
|
||
<listitem><para>Create a virtual
|
||
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 Ethernet
|
||
link will be named
|
||
<literal>host0</literal>. Note that
|
||
<option>--network-veth</option>
|
||
implies
|
||
<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>-p</option></term>
|
||
<term><option>--port=</option></term>
|
||
|
||
<listitem><para>If private networking
|
||
is enabled, maps an IP port on the
|
||
host onto an IP port on the
|
||
container. Takes a protocol specifier
|
||
(either <literal>tcp</literal> or
|
||
<literal>udp</literal>), separated by
|
||
a colon from a host port number in the
|
||
range 1 to 65535, separated by a colon
|
||
from a container port number in the
|
||
range from 1 to 65535. The protocol
|
||
specifier and its separating colon may
|
||
be omitted, in which case
|
||
<literal>tcp</literal> is assumed.
|
||
The container port number and its
|
||
colon may be ommitted, in which case
|
||
the same port as the host port is
|
||
implied. This option is only supported
|
||
if private networking is used, such as
|
||
<option>--network-veth</option> or
|
||
<option>--network-bridge=</option>.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><option>-Z</option></term>
|
||
<term><option>--selinux-context=</option></term>
|
||
|
||
<listitem><para>Sets the SELinux
|
||
security context to be used to label
|
||
processes in the container.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><option>-L</option></term>
|
||
<term><option>--selinux-apifs-context=</option></term>
|
||
|
||
<listitem><para>Sets the SELinux security
|
||
context to be used to label files in
|
||
the virtual API file systems in the
|
||
container.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><option>--capability=</option></term>
|
||
|
||
<listitem><para>List one or more
|
||
additional capabilities to grant the
|
||
container. Takes a comma-separated
|
||
list of capability names, see
|
||
<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,
|
||
CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
|
||
CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
|
||
CAP_KILL, CAP_LEASE,
|
||
CAP_LINUX_IMMUTABLE,
|
||
CAP_NET_BIND_SERVICE,
|
||
CAP_NET_BROADCAST, CAP_NET_RAW,
|
||
CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP,
|
||
CAP_SETUID, CAP_SYS_ADMIN,
|
||
CAP_SYS_CHROOT, CAP_SYS_NICE,
|
||
CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG,
|
||
CAP_SYS_RESOURCE, CAP_SYS_BOOT,
|
||
CAP_AUDIT_WRITE,
|
||
CAP_AUDIT_CONTROL. Also CAP_NET_ADMIN
|
||
is retained if
|
||
<option>--private-network</option> is
|
||
specified. If the special value
|
||
<literal>all</literal> is passed, all
|
||
capabilities are
|
||
retained.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><option>--drop-capability=</option></term>
|
||
|
||
<listitem><para>Specify one or more
|
||
additional capabilities to drop for
|
||
the container. This allows running the
|
||
container with fewer capabilities than
|
||
the default (see above).</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><option>--link-journal=</option></term>
|
||
|
||
<listitem><para>Control whether the
|
||
container's journal shall be made
|
||
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>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>,
|
||
the journal files are stored on the
|
||
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>,
|
||
the journal files are stored on the
|
||
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. <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
|
||
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 persistently if further on
|
||
the default of <literal>auto</literal>
|
||
is used.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><option>-j</option></term>
|
||
|
||
<listitem><para>Equivalent to
|
||
<option>--link-journal=try-guest</option>.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><option>--read-only</option></term>
|
||
|
||
<listitem><para>Mount the root file
|
||
system read-only for the
|
||
container.</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
|
||
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>
|
||
|
||
<listitem><para>Specifies an
|
||
environment variable assignment to
|
||
pass to the init process in the
|
||
container, in the format
|
||
<literal>NAME=VALUE</literal>. This
|
||
may be used to override the default
|
||
variables or to set additional
|
||
variables. This parameter may be used
|
||
more than once.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><option>--share-system</option></term>
|
||
|
||
<listitem><para>Allows the container
|
||
to share certain system facilities
|
||
with the host. More specifically, this
|
||
turns off PID namespacing, UTS
|
||
namespacing and IPC namespacing, and
|
||
thus allows the guest to see and
|
||
interact more easily with processes
|
||
outside of the container. Note that
|
||
using this option makes it impossible
|
||
to start up a full Operating System in
|
||
the container, as an init system
|
||
cannot operate in this mode. It is
|
||
only useful to run specific programs
|
||
or applications this way, without
|
||
involving an init system in the
|
||
container. This option implies
|
||
<option>--register=no</option>. This
|
||
option may not be combined with
|
||
<option>--boot</option>.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><option>--register=</option></term>
|
||
|
||
<listitem><para>Controls whether the
|
||
container is registered with
|
||
<citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Takes
|
||
a boolean argument, defaults to
|
||
<literal>yes</literal>. This option
|
||
should be enabled when the container
|
||
runs a full Operating System (more
|
||
specifically: an init system), and is
|
||
useful to ensure that the container is
|
||
accessible via
|
||
<citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
||
and shown by tools such as
|
||
<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
|
||
that <option>--share-system</option>
|
||
implies
|
||
<option>--register=no</option>.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><option>--keep-unit</option></term>
|
||
|
||
<listitem><para>Instead of creating a
|
||
transient scope unit to run the
|
||
container in, simply register the
|
||
service or scope unit
|
||
<command>systemd-nspawn</command> has
|
||
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 a service unit,
|
||
and the service unit's sole purpose
|
||
is to run a single
|
||
<command>systemd-nspawn</command>
|
||
container. This option is not
|
||
available if run from a user
|
||
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 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>Examples</title>
|
||
|
||
<example>
|
||
<title>Download a Fedora image and start a shell in it</title>
|
||
|
||
<programlisting># machinectl pull-raw --verify=no http://ftp.halifax.rwth-aachen.de/fedora/linux/releases/21/Cloud/Images/x86_64/Fedora-Cloud-Base-20141203-21.x86_64.raw.xz
|
||
# systemd-nspawn -M Fedora-Cloud-Base-20141203-21</programlisting>
|
||
|
||
<para>This downloads an image using <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> and opens a shell in it.</para>
|
||
</example>
|
||
|
||
<example>
|
||
<title>Build and boot a minimal Fedora distribution in a container</title>
|
||
|
||
<programlisting># dnf -y --releasever=21 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd dnf 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>
|
||
</example>
|
||
|
||
<example>
|
||
<title>Spawn a shell in a container of a minimal Debian unstable distribution</title>
|
||
|
||
<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>
|
||
</example>
|
||
|
||
<example>
|
||
<title>Boot a minimal Arch Linux distribution in a container</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>
|
||
</example>
|
||
|
||
<example>
|
||
<title>Boot into an ephemeral <literal>btrfs</literal> snapshot of the host system</title>
|
||
|
||
<programlisting># systemd-nspawn -D / -xb</programlisting>
|
||
|
||
<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>
|
||
|
||
<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
|
||
# 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>
|
||
</example>
|
||
</refsect1>
|
||
|
||
<refsect1>
|
||
<title>Exit status</title>
|
||
|
||
<para>The exit code of the program executed in the
|
||
container is returned.</para>
|
||
</refsect1>
|
||
|
||
<refsect1>
|
||
<title>See Also</title>
|
||
<para>
|
||
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
||
<citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
||
<citerefentry project='mankier'><refentrytitle>dnf</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>,
|
||
<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>btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
||
</para>
|
||
</refsect1>
|
||
|
||
</refentry>
|