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>
118 <para><command>systemd-nspawn</command> implements the
120 url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container
121 Interface</ulink> specification.</para>
125 <title>Options</title>
127 <para>If no arguments are passed the container is set
128 up and a shell started in it, otherwise the passed
129 command and arguments are executed in it. The
130 following options are understood:</para>
134 <term><option>--help</option></term>
135 <term><option>-h</option></term>
137 <listitem><para>Prints a short help
138 text and exits.</para></listitem>
142 <term><option>--version</option></term>
144 <listitem><para>Prints a version string
145 and exits.</para></listitem>
149 <term><option>--directory=</option></term>
150 <term><option>-D</option></term>
152 <listitem><para>Directory to use as
153 file system root for the namespace
154 container. If omitted the current
156 used.</para></listitem>
160 <term><option>--boot</option></term>
161 <term><option>-b</option></term>
163 <listitem><para>Automatically search
164 for an init binary and invoke it
165 instead of a shell or a user supplied
166 program.</para></listitem>
170 <term><option>--user=</option></term>
171 <term><option>-u</option></term>
173 <listitem><para>Run the command
174 under specified user, create home
175 directory and cd into it. As rest
176 of systemd-nspawn, this is not
177 the security feature and limits
178 against accidental changes only.
183 <term><option>--uuid=</option></term>
185 <listitem><para>Set the specified uuid
186 for the container. The init system
188 <filename>/etc/machine-id</filename>
189 from this if this file is not set yet.
194 <term><option>--controllers=</option></term>
195 <term><option>-C</option></term>
197 <listitem><para>Makes the container appear in
198 other hierarchies than the name=systemd:/ one.
199 Takes a comma-separated list of controllers.
204 <term><option>--private-network</option></term>
206 <listitem><para>Turn off networking in
207 the container. This makes all network
208 interfaces unavailable in the
209 container, with the exception of the
210 loopback device.</para></listitem>
214 <term><option>--read-only</option></term>
216 <listitem><para>Mount the root file
217 system read only for the
218 container.</para></listitem>
222 <term><option>--capability=</option></term>
224 <listitem><para>List one or more
225 additional capabilities to grant the
226 container. Takes a comma separated
227 list of capability names, see
228 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
229 for more information. Note that the
230 following capabilities will be granted
231 in any way: CAP_CHOWN,
232 CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
233 CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
236 CAP_NET_BIND_SERVICE,
237 CAP_NET_BROADCAST, CAP_NET_RAW,
238 CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP,
239 CAP_SETUID, CAP_SYS_ADMIN,
240 CAP_SYS_CHROOT, CAP_SYS_NICE,
241 CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG,
242 CAP_SYS_RESOURCE, CAP_SYS_BOOT,
244 CAP_AUDIT_CONTROL.</para></listitem>
248 <term><option>--link-journal=</option></term>
250 <listitem><para>Control whether the
251 container's journal shall be made
252 visible to the host system. If enabled
253 allows viewing the container's journal
254 files from the host (but not vice
256 <literal>no</literal>,
257 <literal>host</literal>,
258 <literal>guest</literal>,
259 <literal>auto</literal>. If
260 <literal>no</literal>, the journal is
261 not linked. If <literal>host</literal>,
262 the journal files are stored on the
263 host file system (beneath
264 <filename>/var/log/journal/<machine-id></filename>)
265 and the subdirectory is bind-mounted
266 into the container at the same
267 location. If <literal>guest</literal>,
268 the journal files are stored on the
269 guest file system (beneath
270 <filename>/var/log/journal/<machine-id></filename>)
271 and the subdirectory is symlinked into the host
272 at the same location. If
273 <literal>auto</literal> (the default),
274 and the right subdirectory of
275 <filename>/var/log/journal</filename>
276 exists, it will be bind mounted
277 into the container. If the
278 subdirectory doesn't exist, no
279 linking is performed. Effectively,
280 booting a container once with
281 <literal>guest</literal> or
282 <literal>host</literal> will link the
283 journal persistently if further on
284 the default of <literal>auto</literal>
285 is used.</para></listitem>
289 <term><option>-j</option></term>
291 <listitem><para>Equivalent to
292 <option>--link-journal=guest</option>.</para></listitem>
299 <title>Example 1</title>
301 <programlisting># yum -y --releasever=19 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal
302 # systemd-nspawn -bD /srv/mycontainer</programlisting>
304 <para>This installs a minimal Fedora distribution into
305 the directory <filename>/srv/mycontainer/</filename> and
306 then boots an OS in a namespace container in
311 <title>Example 2</title>
313 <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
314 # systemd-nspawn -D ~/debian-tree/</programlisting>
316 <para>This installs a minimal Debian unstable
317 distribution into the directory
318 <filename>~/debian-tree/</filename> and then spawns a
319 shell in a namespace container in it.</para>
324 <title>Exit status</title>
326 <para>The exit code of the program executed in the
327 container is returned.</para>
331 <title>See Also</title>
333 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
334 <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
335 <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
336 <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>