| <?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><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><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>, |
| or |
| <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> |
| |
| <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>/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. 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>-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 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>--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-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 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>-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><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>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. 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=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>--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><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 32bit container on a 64bit |
| 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> |
| |
| <xi:include href="standard-options.xml" xpointer="help" /> |
| <xi:include href="standard-options.xml" xpointer="version" /> |
| </variablelist> |
| |
| </refsect1> |
| |
| <refsect1> |
| <title>Example 1</title> |
| |
| <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> |
| |
| <refsect1> |
| <title>Example 2</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> |
| </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> |
| <title>Example 4</title> |
| |
| <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> |
| |
| <refsect1> |
| <title>Example 5</title> |
| |
| <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> |
| |
| <refsect1> |
| <title>Example 6</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> |
| |
| <para>This runs a container with SELinux sandbox security contexts.</para> |
| </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><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><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> |
| </para> |
| </refsect1> |
| |
| </refentry> |