| <?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> |
| |
| <para><command>systemd-nspawn</command> implements the |
| <ulink |
| url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container |
| Interface</ulink> specification.</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 than 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> |
| |
| <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 |
| 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.</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 the host's |
| <filename>/var/log/journal</filename>) |
| and a per-machine subdirectory of this |
| directory is created and bind mounted |
| into the container at the same |
| location. If <literal>guest</literal> |
| the journal files are stored on the |
| guest file system (beneath the guest's |
| <filename>/var/log/journal</filename>) |
| and a per-machine subdirectory of this |
| directory is symlinked into the host |
| at the same location. If |
| <literal>auto</literal> (the default) |
| and the subdirectory of |
| <filename>/var/log/journal</filename> |
| exists as directory it is bind mounted |
| into the container, but nothing is |
| done otherwise. Effectively, booting a |
| container once with |
| <literal>guest</literal> or |
| <literal>host</literal> will link the |
| journal persistantly if further one |
| 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> |
| </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> |