1 <?xml version='
1.0'
?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 This file is part of systemd.
8 Copyright 2010 Lennart Poettering
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
24 <refentry id=
"systemd-nspawn">
27 <title>systemd-nspawn
</title>
28 <productname>systemd
</productname>
32 <contrib>Developer
</contrib>
33 <firstname>Lennart
</firstname>
34 <surname>Poettering
</surname>
35 <email>lennart@poettering.net
</email>
41 <refentrytitle>systemd-nspawn
</refentrytitle>
42 <manvolnum>1</manvolnum>
46 <refname>systemd-nspawn
</refname>
47 <refpurpose>Spawn a namespace container for debugging, testing and building
</refpurpose>
52 <command>systemd-nspawn
<arg choice=
"opt" rep=
"repeat">OPTIONS
</arg> <arg choice=
"opt">COMMAND
</arg> <arg choice=
"opt" rep=
"repeat">ARGS
</arg></command>
57 <title>Description
</title>
59 <para><command>systemd-nspawn
</command> may be used to
60 run a command or OS in a light-weight namespace
61 container. In many ways it is similar to
62 <citerefentry><refentrytitle>chroot
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
63 but more powerful since it fully virtualizes the file
64 system hierarchy, as well as the process tree, the
65 various IPC subsystems and the host and domain
68 <para><command>systemd-nspawn
</command> limits access
69 to various kernel interfaces in the container to
70 read-only, such as
<filename>/sys
</filename>,
71 <filename>/proc/sys
</filename> or
72 <filename>/sys/fs/selinux
</filename>. Network
73 interfaces and the system clock may not be changed
74 from within the container. Device nodes may not be
75 created. The host system cannot be rebooted and kernel
76 modules may not be loaded from within the
79 <para>Note that even though these security precautions
80 are taken
<command>systemd-nspawn
</command> is not
81 suitable for secure container setups. Many of the
82 security features may be circumvented and are hence
83 primarily useful to avoid accidental changes to the
84 host system from the container. The intended use of
85 this program is debugging and testing as well as
86 building of packages, distributions and software
87 involved with boot and systems management.
</para>
90 <citerefentry><refentrytitle>chroot
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
91 <command>systemd-nspawn
</command> may be used to boot
92 full Linux-based operating systems in a
96 <citerefentry><refentrytitle>yum
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
98 <citerefentry><refentrytitle>debootstrap
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
99 to set up an OS directory tree suitable as file system
100 hierarchy for
<command>systemd-nspawn
</command>
103 <para>Note that
<command>systemd-nspawn
</command> will
104 mount file systems private to the container to
105 <filename>/dev
</filename>,
106 <filename>/run
</filename> and similar. These will
107 not be visible outside of the container, and their
108 contents will be lost when the container exits.
</para>
110 <para>Note that running two
111 <command>systemd-nspawn
</command> containers from the
112 same directory tree will not make processes in them
113 see each other. The PID namespace separation of the
114 two containers is complete and the containers will
115 share very few runtime objects except for the
116 underlying file system.
</para>
120 <title>Options
</title>
122 <para>If no arguments are passed the container is set
123 up and a shell started in it, otherwise the passed
124 command and arguments are executed in it. The
125 following options are understood:
</para>
129 <term><option>--help
</option></term>
130 <term><option>-h
</option></term>
132 <listitem><para>Prints a short help
133 text and exits.
</para></listitem>
137 <term><option>--directory=
</option></term>
138 <term><option>-D
</option></term>
140 <listitem><para>Directory to use as
141 file system root for the namespace
142 container. If omitted the current
144 used.
</para></listitem>
148 <term><option>--boot
</option></term>
149 <term><option>-b
</option></term>
151 <listitem><para>Automatically search
152 for an init binary and invoke it
153 instead of a shell or a user supplied
154 program.
</para></listitem>
158 <term><option>--user=
</option></term>
159 <term><option>-u
</option></term>
161 <listitem><para>Run the command
162 under specified user, create home
163 directory and cd into it. As rest
164 of systemd-nspawn, this is not
165 the security feature and limits
166 against accidental changes only.
171 <term><option>--uuid=
</option></term>
173 <listitem><para>Set the specified uuid
174 for the container. The init system
176 <filename>/etc/machine-id
</filename>
177 from this if this file is not set yet.
182 <term><option>--controllers=
</option></term>
183 <term><option>-C
</option></term>
185 <listitem><para>Makes the container appear in
186 other hierarchies that the name=systemd:/ one.
187 Takes a comma-separated list of controllers.
192 <term><option>--private-network
</option></term>
194 <listitem><para>Turn off networking in
195 the container. This makes all network
196 interfaces unavailable in the
197 container, with the exception of the
198 loopback device.
</para></listitem>
206 <title>Example
1</title>
208 <programlisting># yum --releasever=
17 --nogpgcheck --installroot ~/fedora-tree/ install yum passwd vim-minimal rootfiles systemd
209 # systemd-nspawn -D ~/fedora-tree /usr/lib/systemd/systemd
</programlisting>
211 <para>This installs a minimal Fedora distribution into
212 the directory
<filename>~/fedora-tree/
</filename>
213 and then boots an OS in a namespace container in it,
214 with systemd as init system.
</para>
218 <title>Example
2</title>
220 <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
221 # systemd-nspawn -D ~/debian-tree/
</programlisting>
223 <para>This installs a minimal Debian unstable
224 distribution into the directory
225 <filename>~/debian-tree/
</filename> and then spawns a
226 shell in a namespace container in it.
</para>
231 <title>Exit status
</title>
233 <para>The exit code of the program executed in the
234 container is returned.
</para>
238 <title>See Also
</title>
240 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
241 <citerefentry><refentrytitle>chroot
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
242 <citerefentry><refentrytitle>yum
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
243 <citerefentry><refentrytitle>debootstrap
</refentrytitle><manvolnum>8</manvolnum></citerefentry>