| <?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"> |
| |
| <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. It is however possible to |
| enter an existing container, see |
| <link linkend='example-nsenter'>Example 4</link> below. |
| </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>Incompatibility with Auditing</title> |
| |
| <para>Note that the kernel auditing subsystem is |
| currently broken when used together with |
| containers. We hence recommend turning it off entirely |
| by booting with <literal>audit=0</literal> on the |
| kernel command line, or by turning it off at kernel |
| build time. If auditing is enabled in the kernel |
| operating systems booted in an nspawn container might |
| refuse log-in attempts.</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>-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>-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> |
| </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. |
| </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> |
| </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>--slice=</option></term> |
| |
| <listitem><para>Make the container |
| part of the specified slice, instead |
| of the |
| <filename>machine.slice</filename>.</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>--private-network</option></term> |
| |
| <listitem><para>Turn off networking in |
| the container. This makes all network |
| interfaces unavailable in the |
| container, with the exception of the |
| loopback device.</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>--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.</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 doesn't 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>--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 |
| mount.</para></listitem> |
| </varlistentry> |
| </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 id='example-nsenter'> |
| <title>Example 4</title> |
| |
| <para>To enter the container, PID of one of the |
| processes sharing the new namespaces must be used. |
| <command>systemd-nspawn</command> prints the PID |
| (as viewed from the outside) of the launched process, |
| and it can be used to enter the container.</para> |
| |
| <programlisting># nsenter -m -u -i -n -p -t $PID</programlisting> |
| |
| <para><citerefentry><refentrytitle>nsenter</refentrytitle><manvolnum>1</manvolnum></citerefentry> |
| is part of |
| <ulink url="https://github.com/karelzak/util-linux">util-linux</ulink>. |
| Kernel support for entering namespaces was added in |
| Linux 3.8.</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>unshare</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> |
| </para> |
| </refsect1> |
| |
| </refentry> |