| <?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 <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">COMMAND</arg> <arg choice="opt" rep="repeat">ARGS</arg></command> |
| </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> |
| or |
| <citerefentry><refentrytitle>debootstrap</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.</para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Options</title> |
| |
| <para>If no arguments are passed the container is set |
| up and a shell started in it, otherwise the passed |
| command and arguments are executed in it. The |
| following options are understood:</para> |
| |
| <variablelist> |
| <varlistentry> |
| <term><option>--help</option></term> |
| <term><option>-h</option></term> |
| |
| <listitem><para>Prints a short help |
| text and exits.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--directory=</option></term> |
| <term><option>-D</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>--boot</option></term> |
| <term><option>-b</option></term> |
| |
| <listitem><para>Automatically search |
| for an init binary and invoke it |
| instead of a shell or a user supplied |
| program.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--user=</option></term> |
| <term><option>-u</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>--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>--controllers=</option></term> |
| <term><option>-C</option></term> |
| |
| <listitem><para>Makes the container appear in |
| other hierarchies that the name=systemd:/ one. |
| Takes a comma-separated list of controllers. |
| </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> |
| |
| </variablelist> |
| |
| </refsect1> |
| |
| <refsect1> |
| <title>Example 1</title> |
| |
| <programlisting># yum --releasever=17 --nogpgcheck --installroot ~/fedora-tree/ install yum passwd vim-minimal rootfiles systemd |
| # systemd-nspawn -D ~/fedora-tree /usr/lib/systemd/systemd</programlisting> |
| |
| <para>This installs a minimal Fedora distribution into |
| the directory <filename>~/fedora-tree/</filename> |
| and then boots an OS in a namespace container in it, |
| with systemd as init system.</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>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> |
| </para> |
| </refsect1> |
| |
| </refentry> |