systemd-nspawn.xml revision 88d04e31ce0837ebf937ab46c3c39a0d93ab4c7c
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
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering under the terms of the GNU Lesser General Public License as published by
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering the Free Software Foundation; either version 2.1 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
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering Lesser General Public License for more details.
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering You should have received a copy of the GNU Lesser 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>
1fd961211df69ce672252d543bf4777738647048Zbigniew Jędrzejewski-Szmek </refsynopsisdiv>
870c4365cf3d407270788abe14d216a636ecf6c3Zbigniew Jędrzejewski-Szmek <para><command>systemd-nspawn</command> may be used to
870c4365cf3d407270788abe14d216a636ecf6c3Zbigniew Jędrzejewski-Szmek run a command or OS in a light-weight namespace
870c4365cf3d407270788abe14d216a636ecf6c3Zbigniew Jędrzejewski-Szmek container. In many ways it is similar to
870c4365cf3d407270788abe14d216a636ecf6c3Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1fd961211df69ce672252d543bf4777738647048Zbigniew Jędrzejewski-Szmek but more powerful since it fully virtualizes the file
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering 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>/sys/fs/selinux</filename>. Network
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering interfaces and the system clock may not be changed
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering from within the container. Device nodes may not be
9f7dad774ebfad23269800b7096eaad087481debVille Skyttä created. The host system cannot be rebooted and kernel
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering modules may not be loaded from within the
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering 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
4f755fc6ab8b75f89ed84c93cd5c3fac2a448b16Lennart Poettering primarily useful to avoid accidental changes to the
4f755fc6ab8b75f89ed84c93cd5c3fac2a448b16Lennart Poettering host system from the container. The intended use of
4f755fc6ab8b75f89ed84c93cd5c3fac2a448b16Lennart Poettering this program is debugging and testing as well as
4f755fc6ab8b75f89ed84c93cd5c3fac2a448b16Lennart Poettering building of packages, distributions and software
4f755fc6ab8b75f89ed84c93cd5c3fac2a448b16Lennart 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>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering to set up an OS directory tree suitable as file system
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering hierarchy for <command>systemd-nspawn</command>
04ac799283f517672a5424e7c5bf066cfa4ca020Zbigniew Jędrzejewski-Szmek containers.</para>
04ac799283f517672a5424e7c5bf066cfa4ca020Zbigniew Jędrzejewski-Szmek <para>Note that <command>systemd-nspawn</command> will
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering mount file systems private to the container to
4d62fb4298a5904a53f484636c91540d08f68765Lennart Poettering <filename>/run</filename> and similar. These will
04ac799283f517672a5424e7c5bf066cfa4ca020Zbigniew Jędrzejewski-Szmek not be visible outside of the container, and their
4d62fb4298a5904a53f484636c91540d08f68765Lennart Poettering contents will be lost when the container exits.</para>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <para>Note that running two
25f5971b5e0b3ab5b91a7d0359cd7f5a5094c1d0Lennart Poettering <command>systemd-nspawn</command> containers from the
25f5971b5e0b3ab5b91a7d0359cd7f5a5094c1d0Lennart Poettering same directory tree will not make processes in them
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering 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><command>systemd-nspawn</command> implements the
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container
04d39279245834494baccfdb9349db8bf80abd13Lennart Poettering <para>If no arguments are passed the container is set
04d39279245834494baccfdb9349db8bf80abd13Lennart Poettering up and a shell started in it, otherwise the passed
04d39279245834494baccfdb9349db8bf80abd13Lennart Poettering command and arguments are executed in it. The
04d39279245834494baccfdb9349db8bf80abd13Lennart Poettering following options are understood:</para>
9980033377c105d2cd6539c9d73ee61d4c2263b0Lennart Poettering <variablelist>
9980033377c105d2cd6539c9d73ee61d4c2263b0Lennart Poettering <varlistentry>
fb69ed55e5f8e82145440ba15075e8db807bf7faMichael Biebl </varlistentry>
f8964235e69f58225dec378437b1789744cd22a9Lennart Poettering <varlistentry>
77b6e19458f37cfde127ec6aa9494c0ac45ad890Lennart Poettering </varlistentry>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <varlistentry>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <term><option>--directory=</option></term>
870c4365cf3d407270788abe14d216a636ecf6c3Zbigniew Jędrzejewski-Szmek <term><option>-D</option></term>
870c4365cf3d407270788abe14d216a636ecf6c3Zbigniew Jędrzejewski-Szmek <listitem><para>Directory to use as
870c4365cf3d407270788abe14d216a636ecf6c3Zbigniew Jędrzejewski-Szmek file system root for the namespace
870c4365cf3d407270788abe14d216a636ecf6c3Zbigniew Jędrzejewski-Szmek container. If omitted the current
870c4365cf3d407270788abe14d216a636ecf6c3Zbigniew Jędrzejewski-Szmek directory will be
a7f5bb1eafadbb08c8528baae588bbe773a37e79William Giokas for an init binary and invoke it
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering instead of a shell or a user supplied
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering </varlistentry>
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering <varlistentry>
0f0dbc46ccf5aaaf3131446d0a4d78bc97a37295Lennart Poettering under specified user, create home
a7f5bb1eafadbb08c8528baae588bbe773a37e79William Giokas directory and cd into it. As rest
0f0dbc46ccf5aaaf3131446d0a4d78bc97a37295Lennart Poettering of systemd-nspawn, this is not
0f0dbc46ccf5aaaf3131446d0a4d78bc97a37295Lennart Poettering the security feature and limits
0f0dbc46ccf5aaaf3131446d0a4d78bc97a37295Lennart Poettering against accidental changes only.
eb91eb187b7491e05fb95215b77cb62061f41d08Lennart Poettering </varlistentry>
eb91eb187b7491e05fb95215b77cb62061f41d08Lennart Poettering <varlistentry>
870c4365cf3d407270788abe14d216a636ecf6c3Zbigniew Jędrzejewski-Szmek for the container. The init system
0f0dbc46ccf5aaaf3131446d0a4d78bc97a37295Lennart Poettering will initialize
687d0825a4636b1841dc0c01fbcbf3160dddab74Michal Vyskocil from this if this file is not set yet.
a7f5bb1eafadbb08c8528baae588bbe773a37e79William Giokas </varlistentry>
687d0825a4636b1841dc0c01fbcbf3160dddab74Michal Vyskocil <varlistentry>
687d0825a4636b1841dc0c01fbcbf3160dddab74Michal Vyskocil <term><option>--controllers=</option></term>
687d0825a4636b1841dc0c01fbcbf3160dddab74Michal Vyskocil <listitem><para>Makes the container appear in
687d0825a4636b1841dc0c01fbcbf3160dddab74Michal Vyskocil other hierarchies than the name=systemd:/ one.
687d0825a4636b1841dc0c01fbcbf3160dddab74Michal Vyskocil Takes a comma-separated list of controllers.
687d0825a4636b1841dc0c01fbcbf3160dddab74Michal Vyskocil </varlistentry>
7027ff61a34a12487712b382a061c654acc3a679Lennart Poettering <varlistentry>
7027ff61a34a12487712b382a061c654acc3a679Lennart Poettering <term><option>--private-network</option></term>
7027ff61a34a12487712b382a061c654acc3a679Lennart Poettering the container. This makes all network
7027ff61a34a12487712b382a061c654acc3a679Lennart Poettering interfaces unavailable in the
7027ff61a34a12487712b382a061c654acc3a679Lennart Poettering container, with the exception of the
7027ff61a34a12487712b382a061c654acc3a679Lennart Poettering </varlistentry>
7027ff61a34a12487712b382a061c654acc3a679Lennart Poettering <varlistentry>
7027ff61a34a12487712b382a061c654acc3a679Lennart Poettering <term><option>--read-only</option></term>
144f0fc0c8a5e2f6b72179e2b5fb992474da24adLennart Poettering system read only for the
144f0fc0c8a5e2f6b72179e2b5fb992474da24adLennart Poettering </varlistentry>
144f0fc0c8a5e2f6b72179e2b5fb992474da24adLennart Poettering <varlistentry>
144f0fc0c8a5e2f6b72179e2b5fb992474da24adLennart Poettering <term><option>--capability=</option></term>
144f0fc0c8a5e2f6b72179e2b5fb992474da24adLennart Poettering additional capabilities to grant the
144f0fc0c8a5e2f6b72179e2b5fb992474da24adLennart Poettering container. Takes a comma separated
144f0fc0c8a5e2f6b72179e2b5fb992474da24adLennart Poettering list of capability names, see
69c79d3c32ff4d6a572ee1cdec248b27df1fb6caLennart Poettering <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
69c79d3c32ff4d6a572ee1cdec248b27df1fb6caLennart Poettering for more information. Note that the
69c79d3c32ff4d6a572ee1cdec248b27df1fb6caLennart Poettering following capabilities will be granted
69c79d3c32ff4d6a572ee1cdec248b27df1fb6caLennart Poettering in any way: CAP_CHOWN,
69c79d3c32ff4d6a572ee1cdec248b27df1fb6caLennart Poettering CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
69c79d3c32ff4d6a572ee1cdec248b27df1fb6caLennart Poettering CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
69c79d3c32ff4d6a572ee1cdec248b27df1fb6caLennart Poettering CAP_KILL, CAP_LEASE,
69c79d3c32ff4d6a572ee1cdec248b27df1fb6caLennart Poettering CAP_LINUX_IMMUTABLE,
69c79d3c32ff4d6a572ee1cdec248b27df1fb6caLennart Poettering CAP_NET_BIND_SERVICE,
69c79d3c32ff4d6a572ee1cdec248b27df1fb6caLennart Poettering CAP_NET_BROADCAST, CAP_NET_RAW,
a41fe3a29372f8e6c4e7733bf85940a023811301Lennart Poettering CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP,
ff01d048b4c1455241c894cf7982662c9d28fd34Lennart Poettering CAP_SETUID, CAP_SYS_ADMIN,
a41fe3a29372f8e6c4e7733bf85940a023811301Lennart Poettering CAP_SYS_CHROOT, CAP_SYS_NICE,
69c79d3c32ff4d6a572ee1cdec248b27df1fb6caLennart Poettering CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG,
69c79d3c32ff4d6a572ee1cdec248b27df1fb6caLennart Poettering CAP_SYS_RESOURCE, CAP_SYS_BOOT,
69c79d3c32ff4d6a572ee1cdec248b27df1fb6caLennart Poettering CAP_AUDIT_WRITE,
69c79d3c32ff4d6a572ee1cdec248b27df1fb6caLennart Poettering </varlistentry>
69c79d3c32ff4d6a572ee1cdec248b27df1fb6caLennart Poettering <varlistentry>
a42c8b54b1619078c02f5e439bd2564c6d0f901fLennart Poettering container's journal shall be made
a42c8b54b1619078c02f5e439bd2564c6d0f901fLennart Poettering visible to the host system. If enabled
a42c8b54b1619078c02f5e439bd2564c6d0f901fLennart Poettering allows viewing the container's journal
a42c8b54b1619078c02f5e439bd2564c6d0f901fLennart Poettering files from the host (but not vice
a42c8b54b1619078c02f5e439bd2564c6d0f901fLennart Poettering versa). Takes one of
aa28aefe61c5406c5cb631f3e82457b6d1bcc967Lennart Poettering the journal files are stored on the
c74e630d0ce4b1ace116e8211f3b6eb472efa7e3Lennart Poettering host file system (beneath
aa28aefe61c5406c5cb631f3e82457b6d1bcc967Lennart Poettering <filename>/var/log/journal/<machine-id></filename>)
aa28aefe61c5406c5cb631f3e82457b6d1bcc967Lennart Poettering and the subdirectory is bind-mounted
aa28aefe61c5406c5cb631f3e82457b6d1bcc967Lennart Poettering into the container at the same
a42c8b54b1619078c02f5e439bd2564c6d0f901fLennart Poettering the journal files are stored on the
a42c8b54b1619078c02f5e439bd2564c6d0f901fLennart Poettering guest file system (beneath
a42c8b54b1619078c02f5e439bd2564c6d0f901fLennart Poettering <filename>/var/log/journal/<machine-id></filename>)
a42c8b54b1619078c02f5e439bd2564c6d0f901fLennart Poettering and the subdirectory is symlinked into the host
a42c8b54b1619078c02f5e439bd2564c6d0f901fLennart Poettering at the same location. If
a42c8b54b1619078c02f5e439bd2564c6d0f901fLennart Poettering and the right subdirectory of
aa28aefe61c5406c5cb631f3e82457b6d1bcc967Lennart Poettering exists, it will be bind mounted
c74e630d0ce4b1ace116e8211f3b6eb472efa7e3Lennart Poettering into the container. If the
c74e630d0ce4b1ace116e8211f3b6eb472efa7e3Lennart Poettering subdirectory doesn't exist, no
c74e630d0ce4b1ace116e8211f3b6eb472efa7e3Lennart Poettering linking is performed. Effectively,
c74e630d0ce4b1ace116e8211f3b6eb472efa7e3Lennart Poettering booting a container once with
c74e630d0ce4b1ace116e8211f3b6eb472efa7e3Lennart Poettering journal persistently if further on
c74e630d0ce4b1ace116e8211f3b6eb472efa7e3Lennart Poettering </varlistentry>
c74e630d0ce4b1ace116e8211f3b6eb472efa7e3Lennart Poettering <varlistentry>
c74e630d0ce4b1ace116e8211f3b6eb472efa7e3Lennart Poettering <option>--link-journal=guest</option>.</para></listitem>
c74e630d0ce4b1ace116e8211f3b6eb472efa7e3Lennart Poettering </varlistentry>
c74e630d0ce4b1ace116e8211f3b6eb472efa7e3Lennart Poettering </variablelist>
69c79d3c32ff4d6a572ee1cdec248b27df1fb6caLennart Poettering <programlisting># yum --releasever=17 --nogpgcheck --installroot ~/fedora-tree/ install yum passwd vim-minimal rootfiles systemd
69c79d3c32ff4d6a572ee1cdec248b27df1fb6caLennart Poettering# systemd-nspawn -D ~/fedora-tree /usr/lib/systemd/systemd</programlisting>
c74e630d0ce4b1ace116e8211f3b6eb472efa7e3Lennart Poettering <para>This installs a minimal Fedora distribution into
c74e630d0ce4b1ace116e8211f3b6eb472efa7e3Lennart Poettering the directory <filename>~/fedora-tree/</filename>
c74e630d0ce4b1ace116e8211f3b6eb472efa7e3Lennart Poettering and then boots an OS in a namespace container in it,
66f756d437658cc464bfb5647c97efd0cf77f933Jan Engelhardt with systemd as init system.</para>
69c79d3c32ff4d6a572ee1cdec248b27df1fb6caLennart Poettering <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
69c79d3c32ff4d6a572ee1cdec248b27df1fb6caLennart Poettering# systemd-nspawn -D ~/debian-tree/</programlisting>
69c79d3c32ff4d6a572ee1cdec248b27df1fb6caLennart Poettering <para>This installs a minimal Debian unstable
69c79d3c32ff4d6a572ee1cdec248b27df1fb6caLennart Poettering distribution into the directory
69c79d3c32ff4d6a572ee1cdec248b27df1fb6caLennart Poettering <filename>~/debian-tree/</filename> and then spawns a
bc2f673ec24b59948fcfc35b3077fda0314e69d8Lennart Poettering shell in a namespace container in it.</para>
08af0da26935e827b58809ff1946e2f7d496e666Lennart Poettering <para>The exit code of the program executed in the
08af0da26935e827b58809ff1946e2f7d496e666Lennart Poettering container is returned.</para>
08af0da26935e827b58809ff1946e2f7d496e666Lennart Poettering <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
ab046dde6f355f4a8b07ff6120a7ef51f5d49fc9Tom Gundersen <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
ab046dde6f355f4a8b07ff6120a7ef51f5d49fc9Tom Gundersen <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
69c79d3c32ff4d6a572ee1cdec248b27df1fb6caLennart Poettering <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>