systemd-nspawn.xml revision a41fe3a29372f8e6c4e7733bf85940a023811301
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering This file is part of systemd.
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering Copyright 2010 Lennart Poettering
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering systemd is free software; you can redistribute it and/or modify it
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering under the terms of the GNU General Public License as published by
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering the Free Software Foundation; either version 2 of the License, or
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering (at your option) any later version.
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering systemd is distributed in the hope that it will be useful, but
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering WITHOUT ANY WARRANTY; without even the implied warranty of
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering General Public License for more details.
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering You should have received a copy of the GNU General Public License
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <refentryinfo>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering </authorgroup>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering </refentryinfo>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <refentrytitle>systemd-nspawn</refentrytitle>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <refpurpose>Spawn a namespace container for debugging, testing and building</refpurpose>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <refsynopsisdiv>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <command>systemd-nspawn <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">COMMAND</arg> <arg choice="opt" rep="repeat">ARGS</arg></command>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering </cmdsynopsis>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering </refsynopsisdiv>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <para><command>systemd-nspawn</command> may be used to
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering run a command or OS in a light-weight namespace
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering container. In many ways it is similar to
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering but more powerful since it fully virtualizes the file
9f7dad774ebfad23269800b7096eaad087481debVille Skyttä system hierarchy, as well as the process tree, the
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering various IPC subsystems and the host and domain
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <para><command>systemd-nspawn</command> limits access
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering to various kernel interfaces in the container to
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering read-only, such as <filename>/sys</filename>,
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <filename>/selinux</filename>. Network interfaces and
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering the system clock may not be changed from within the
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering container. Device nodes may not be created. The host
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering system cannot be rebooted and kernel modules may not
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering be loaded from within the container.</para>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <para>Note that even though these security precautions
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering are taken <command>systemd-nspawn</command> is not
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering suitable for secure container setups. Many of the
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering security features may be circumvented and are hence
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering primarily useful to avoid accidental changes to the
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering host system from the container. The intended use of
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering this program is debugging and testing as well as
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering building of packages, distributions and software
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering involved with boot and systems management.</para>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <para>In contrast to
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <command>systemd-nspawn</command> may be used to boot
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering full Linux-based operating systems in a
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering container.</para>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <para>Use a tool like
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry> or <citerefentry><refentrytitle>mock</refentrytitle><manvolnum>1</manvolnum></citerefentry>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering to set up an OS directory tree suitable as file system
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering hierarchy for <command>systemd-nspawn</command> containers.</para>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <para>Note that <command>systemd-nspawn</command> will
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering mount file systems private to the container to
2b583ce6576d4a074ce6f1570b3e60b65c64ae7dKay Sievers <filename>/run</filename> and similar. These will
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering not be visible outside of the container, and their
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering contents will be lost when the container exits.</para>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <para>Note that running two
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <command>systemd-nspawn</command> containers from the
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering same directory tree will not make processes in them
9f7dad774ebfad23269800b7096eaad087481debVille Skyttä see each other. The PID namespace separation of the
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering two containers is complete and the containers will
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering share very few runtime objects except for the
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering underlying file system.</para>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <para>If no arguments are passed the container is set
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering up and a shell started in it, otherwise the passed
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering command and arguments are executed in it. The
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering following options are understood:</para>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <variablelist>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <varlistentry>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering </varlistentry>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <varlistentry>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <term><option>--directory=</option></term>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering file system root for the namespace
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering container. If omitted the current
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering directory will be
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering </varlistentry>
687d0825a4636b1841dc0c01fbcbf3160dddab74Michal Vyskocil <varlistentry>
687d0825a4636b1841dc0c01fbcbf3160dddab74Michal Vyskocil under specified user, create home
687d0825a4636b1841dc0c01fbcbf3160dddab74Michal Vyskocil directory and cd into it. As rest
687d0825a4636b1841dc0c01fbcbf3160dddab74Michal Vyskocil of systemd-nspawn, this is not
687d0825a4636b1841dc0c01fbcbf3160dddab74Michal Vyskocil the security feature and limits
687d0825a4636b1841dc0c01fbcbf3160dddab74Michal Vyskocil against accidental changes only.
687d0825a4636b1841dc0c01fbcbf3160dddab74Michal Vyskocil </varlistentry>
a41fe3a29372f8e6c4e7733bf85940a023811301Lennart Poettering <varlistentry>
a41fe3a29372f8e6c4e7733bf85940a023811301Lennart Poettering the container. This makes all network
a41fe3a29372f8e6c4e7733bf85940a023811301Lennart Poettering interfaces unavailable in the
a41fe3a29372f8e6c4e7733bf85940a023811301Lennart Poettering container, with the exception of the
a41fe3a29372f8e6c4e7733bf85940a023811301Lennart Poettering </varlistentry>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering </variablelist>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <programlisting># debootstrap --arch=amd64 unstable debian-tree/
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering# systemd-nspawn -D debian-tree/</programlisting>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <para>This installs a minimal Debian unstable
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering distribution into the directory
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <filename>debian-tree/</filename> and then spawns a
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering shell in a namespace container in it.</para>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <programlisting># mock --init
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering# systemd-nspawn -D /var/lib/mock/fedora-rawhide-x86_64/root/ /bin/systemd systemd.log_level=debug</programlisting>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <para>This installs a minimal Fedora distribution into
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering a subdirectory of <filename>/var/lib/mock/</filename>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering and then boots an OS in a namespace container in it,
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering with systemd as init system, configured for debug
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering logging.</para>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <para>The exit code of the program executed in the
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering container is returned.</para>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <citerefentry><refentrytitle>mock</refentrytitle><manvolnum>1</manvolnum></citerefentry>