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</command>
53 <arg choice="opt" rep="repeat">OPTIONS</arg>
54 <arg choice="opt"><replaceable>COMMAND</replaceable>
55 <arg choice="opt" rep="repeat">ARGS</arg>
59 <command>systemd-nspawn</command>
60 <arg choice="plain">-b</arg>
61 <arg choice="opt" rep="repeat">OPTIONS</arg>
62 <arg choice="opt" rep="repeat">ARGS</arg>
67 <title>Description</title>
69 <para><command>systemd-nspawn</command> may be used to
70 run a command or OS in a light-weight namespace
71 container. In many ways it is similar to
72 <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
73 but more powerful since it fully virtualizes the file
74 system hierarchy, as well as the process tree, the
75 various IPC subsystems and the host and domain
78 <para><command>systemd-nspawn</command> limits access
79 to various kernel interfaces in the container to
80 read-only, such as <filename>/sys</filename>,
81 <filename>/proc/sys</filename> or
82 <filename>/sys/fs/selinux</filename>. Network
83 interfaces and the system clock may not be changed
84 from within the container. Device nodes may not be
85 created. The host system cannot be rebooted and kernel
86 modules may not be loaded from within the
89 <para>Note that even though these security precautions
90 are taken <command>systemd-nspawn</command> is not
91 suitable for secure container setups. Many of the
92 security features may be circumvented and are hence
93 primarily useful to avoid accidental changes to the
94 host system from the container. The intended use of
95 this program is debugging and testing as well as
96 building of packages, distributions and software
97 involved with boot and systems management.</para>
100 <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry> <command>systemd-nspawn</command>
101 may be used to boot full Linux-based operating systems
102 in a container.</para>
104 <para>Use a tool like
105 <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
106 <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
108 <citerefentry><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>
109 to set up an OS directory tree suitable as file system
110 hierarchy for <command>systemd-nspawn</command>
113 <para>Note that <command>systemd-nspawn</command> will
114 mount file systems private to the container to
115 <filename>/dev</filename>,
116 <filename>/run</filename> and similar. These will
117 not be visible outside of the container, and their
118 contents will be lost when the container exits.</para>
120 <para>Note that running two
121 <command>systemd-nspawn</command> containers from the
122 same directory tree will not make processes in them
123 see each other. The PID namespace separation of the
124 two containers is complete and the containers will
125 share very few runtime objects except for the
126 underlying file system. Use
127 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
128 <command>login</command> command to request an
129 additional login prompt in a running container.</para>
131 <para><command>systemd-nspawn</command> implements the
133 url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container
134 Interface</ulink> specification.</para>
136 <para>As a safety check
137 <command>systemd-nspawn</command> will verify the
138 existence of <filename>/etc/os-release</filename> in
139 the container tree before starting the container (see
140 <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>). It
141 might be necessary to add this file to the container
142 tree manually if the OS of the container is too old to
143 contain this file out-of-the-box.</para>
147 <title>Incompatibility with Auditing</title>
149 <para>Note that the kernel auditing subsystem is
150 currently broken when used together with
151 containers. We hence recommend turning it off entirely
152 by booting with <literal>audit=0</literal> on the
153 kernel command line, or by turning it off at kernel
154 build time. If auditing is enabled in the kernel,
155 operating systems booted in an nspawn container might
156 refuse log-in attempts.</para>
160 <title>Options</title>
162 <para>If option <option>-b</option> is specified, the
163 arguments are used as arguments for the init
164 binary. Otherwise, <replaceable>COMMAND</replaceable>
165 specifies the program to launch in the container, and
166 the remaining arguments are used as arguments for this
167 program. If <option>-b</option> is not used and no
168 arguments are specifed, a shell is launched in the
171 <para>The following options are understood:</para>
175 <term><option>-h</option></term>
176 <term><option>--help</option></term>
178 <listitem><para>Prints a short help
179 text and exits.</para></listitem>
183 <term><option>--version</option></term>
185 <listitem><para>Prints a version string
186 and exits.</para></listitem>
190 <term><option>-D</option></term>
191 <term><option>--directory=</option></term>
193 <listitem><para>Directory to use as
194 file system root for the namespace
195 container. If omitted, the current
197 used.</para></listitem>
201 <term><option>-b</option></term>
202 <term><option>--boot</option></term>
204 <listitem><para>Automatically search
205 for an init binary and invoke it
206 instead of a shell or a user supplied
207 program. If this option is used, arguments
208 specified on the command line are used
209 as arguments for the init binary.
214 <term><option>-u</option></term>
215 <term><option>--user=</option></term>
217 <listitem><para>Run the command
218 under specified user, create home
219 directory and cd into it. As rest
220 of systemd-nspawn, this is not
221 the security feature and limits
222 against accidental changes only.
227 <term><option>-M</option></term>
228 <term><option>--machine=</option></term>
230 <listitem><para>Sets the machine name
231 for this container. This name may be
232 used to identify this container on the
233 host, and is used to initialize the
234 container's hostname (which the
235 container can choose to override,
236 however). If not specified, the last
237 component of the root directory of the
238 container is used.</para></listitem>
242 <term><option>--slice=</option></term>
244 <listitem><para>Make the container
245 part of the specified slice, instead
247 <filename>machine.slice</filename>.</para>
252 <term><option>-L</option></term>
253 <term><option>--file-label=</option></term>
255 <listitem><para>Sets the mandatory
256 access control (MAC/SELinux) file
257 label to be used by virtual API file
258 systems in the container.</para>
263 <term><option>-Z</option></term>
264 <term><option>--process-label=</option></term>
266 <listitem><para>Sets the mandatory
267 access control (MAC/SELinux) label to be used by
268 processes in the container.</para>
273 <term><option>--uuid=</option></term>
275 <listitem><para>Set the specified UUID
276 for the container. The init system
278 <filename>/etc/machine-id</filename>
279 from this if this file is not set yet.
284 <term><option>--private-network</option></term>
286 <listitem><para>Turn off networking in
287 the container. This makes all network
288 interfaces unavailable in the
289 container, with the exception of the
290 loopback device.</para></listitem>
294 <term><option>--read-only</option></term>
296 <listitem><para>Mount the root file
297 system read-only for the
298 container.</para></listitem>
302 <term><option>--capability=</option></term>
304 <listitem><para>List one or more
305 additional capabilities to grant the
306 container. Takes a comma-separated
307 list of capability names, see
308 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
309 for more information. Note that the
310 following capabilities will be granted
311 in any way: CAP_CHOWN,
312 CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
313 CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
316 CAP_NET_BIND_SERVICE,
317 CAP_NET_BROADCAST, CAP_NET_RAW,
318 CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP,
319 CAP_SETUID, CAP_SYS_ADMIN,
320 CAP_SYS_CHROOT, CAP_SYS_NICE,
321 CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG,
322 CAP_SYS_RESOURCE, CAP_SYS_BOOT,
324 CAP_AUDIT_CONTROL.</para></listitem>
328 <term><option>--drop-capability=</option></term>
330 <listitem><para>Specify one or more
331 additional capabilities to drop for
332 the container. This allows running the
333 container with fewer capabilities than
334 the default (see above).</para></listitem>
338 <term><option>--link-journal=</option></term>
340 <listitem><para>Control whether the
341 container's journal shall be made
342 visible to the host system. If enabled,
343 allows viewing the container's journal
344 files from the host (but not vice
346 <literal>no</literal>,
347 <literal>host</literal>,
348 <literal>guest</literal>,
349 <literal>auto</literal>. If
350 <literal>no</literal>, the journal is
351 not linked. If <literal>host</literal>,
352 the journal files are stored on the
353 host file system (beneath
354 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
355 and the subdirectory is bind-mounted
356 into the container at the same
357 location. If <literal>guest</literal>,
358 the journal files are stored on the
359 guest file system (beneath
360 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
361 and the subdirectory is symlinked into the host
362 at the same location. If
363 <literal>auto</literal> (the default),
364 and the right subdirectory of
365 <filename>/var/log/journal</filename>
366 exists, it will be bind mounted
367 into the container. If the
368 subdirectory does not exist, no
369 linking is performed. Effectively,
370 booting a container once with
371 <literal>guest</literal> or
372 <literal>host</literal> will link the
373 journal persistently if further on
374 the default of <literal>auto</literal>
375 is used.</para></listitem>
379 <term><option>-j</option></term>
381 <listitem><para>Equivalent to
382 <option>--link-journal=guest</option>.</para></listitem>
386 <term><option>--bind=</option></term>
387 <term><option>--bind-ro=</option></term>
389 <listitem><para>Bind mount a file or
390 directory from the host into the
391 container. Either takes a path
392 argument -- in which case the
393 specified path will be mounted from
394 the host to the same path in the
395 container --, or a colon-separated
396 pair of paths -- in which case the
397 first specified path is the source in
398 the host, and the second path is the
399 destination in the container. The
400 <option>--bind-ro=</option> option
401 creates read-only bind
402 mount.</para></listitem>
406 <term><option>--setenv=</option></term>
408 <listitem><para>Specifies an
409 environment variable assignment to
410 pass to the init process in the
411 container, in the format
412 <literal>NAME=VALUE</literal>. This
413 may be used to override the default
414 variables or to set additional
415 variables. This parameter may be used
416 more than once.</para></listitem>
420 <term><option>-q</option></term>
421 <term><option>--quiet</option></term>
423 <listitem><para>Turns off any status
424 output by the tool itself. When this
425 switch is used, then the only output
426 by nspawn will be the console output
428 itself.</para></listitem>
436 <title>Example 1</title>
438 <programlisting># yum -y --releasever=19 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal
439 # systemd-nspawn -bD /srv/mycontainer</programlisting>
441 <para>This installs a minimal Fedora distribution into
442 the directory <filename noindex='true'>/srv/mycontainer/</filename> and
443 then boots an OS in a namespace container in
448 <title>Example 2</title>
450 <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
451 # systemd-nspawn -D ~/debian-tree/</programlisting>
453 <para>This installs a minimal Debian unstable
454 distribution into the directory
455 <filename>~/debian-tree/</filename> and then spawns a
456 shell in a namespace container in it.</para>
460 <title>Example 3</title>
462 <programlisting># pacstrap -c -d ~/arch-tree/ base
463 # systemd-nspawn -bD ~/arch-tree/</programlisting>
465 <para>This installs a mimimal Arch Linux distribution into
466 the directory <filename>~/arch-tree/</filename> and then
467 boots an OS in a namespace container in it.</para>
471 <title>Example 4</title>
473 <programlisting># mv ~/arch-tree /var/lib/container/arch
474 # systemctl enable systemd-nspawn@arch.service
475 # systemctl start systemd-nspawn@arch.service</programlisting>
477 <para>This makes the Arch Linux container part of the
478 <filename>multi-user.target</filename> on the host.
483 <title>Example 5</title>
485 <programlisting># btrfs subvolume snapshot / /.tmp
486 # systemd-nspawn --private-network -D /.tmp -b</programlisting>
488 <para>This runs a copy of the host system in a
489 btrfs snapshot.</para>
493 <title>Example 6</title>
495 <programlisting># chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container
496 # systemd-nspawn -L system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -Z system_u:system_r:svirt_lxc_net_t:s0:c0,c1 -D /srv/container /bin/sh</programlisting>
498 <para>This runs a container with SELinux sandbox labels.</para>
502 <title>Exit status</title>
504 <para>The exit code of the program executed in the
505 container is returned.</para>
509 <title>See Also</title>
511 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
512 <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
513 <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
514 <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
515 <citerefentry><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
516 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
517 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>