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"
25 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
28 <title>systemd-nspawn
</title>
29 <productname>systemd
</productname>
33 <contrib>Developer
</contrib>
34 <firstname>Lennart
</firstname>
35 <surname>Poettering
</surname>
36 <email>lennart@poettering.net
</email>
42 <refentrytitle>systemd-nspawn
</refentrytitle>
43 <manvolnum>1</manvolnum>
47 <refname>systemd-nspawn
</refname>
48 <refpurpose>Spawn a namespace container for debugging, testing and building
</refpurpose>
53 <command>systemd-nspawn
</command>
54 <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>
55 <arg choice=
"opt"><replaceable>COMMAND
</replaceable>
56 <arg choice=
"opt" rep=
"repeat">ARGS
</arg>
60 <command>systemd-nspawn
</command>
61 <arg choice=
"plain">-b
</arg>
62 <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>
63 <arg choice=
"opt" rep=
"repeat">ARGS
</arg>
68 <title>Description
</title>
70 <para><command>systemd-nspawn
</command> may be used to
71 run a command or OS in a light-weight namespace
72 container. In many ways it is similar to
73 <citerefentry><refentrytitle>chroot
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
74 but more powerful since it fully virtualizes the file
75 system hierarchy, as well as the process tree, the
76 various IPC subsystems and the host and domain
79 <para><command>systemd-nspawn
</command> limits access
80 to various kernel interfaces in the container to
81 read-only, such as
<filename>/sys
</filename>,
82 <filename>/proc/sys
</filename> or
83 <filename>/sys/fs/selinux
</filename>. Network
84 interfaces and the system clock may not be changed
85 from within the container. Device nodes may not be
86 created. The host system cannot be rebooted and kernel
87 modules may not be loaded from within the
90 <para>Note that even though these security precautions
91 are taken
<command>systemd-nspawn
</command> is not
92 suitable for secure container setups. Many of the
93 security features may be circumvented and are hence
94 primarily useful to avoid accidental changes to the
95 host system from the container. The intended use of
96 this program is debugging and testing as well as
97 building of packages, distributions and software
98 involved with boot and systems management.
</para>
101 <citerefentry><refentrytitle>chroot
</refentrytitle><manvolnum>1</manvolnum></citerefentry> <command>systemd-nspawn
</command>
102 may be used to boot full Linux-based operating systems
103 in a container.
</para>
105 <para>Use a tool like
106 <citerefentry><refentrytitle>yum
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
107 <citerefentry><refentrytitle>debootstrap
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
109 <citerefentry><refentrytitle>pacman
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
110 to set up an OS directory tree suitable as file system
111 hierarchy for
<command>systemd-nspawn
</command>
114 <para>Note that
<command>systemd-nspawn
</command> will
115 mount file systems private to the container to
116 <filename>/dev
</filename>,
117 <filename>/run
</filename> and similar. These will
118 not be visible outside of the container, and their
119 contents will be lost when the container exits.
</para>
121 <para>Note that running two
122 <command>systemd-nspawn
</command> containers from the
123 same directory tree will not make processes in them
124 see each other. The PID namespace separation of the
125 two containers is complete and the containers will
126 share very few runtime objects except for the
127 underlying file system. Use
128 <citerefentry><refentrytitle>machinectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
129 <command>login
</command> command to request an
130 additional login prompt in a running container.
</para>
132 <para><command>systemd-nspawn
</command> implements the
134 url=
"http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container
135 Interface
</ulink> specification.
</para>
137 <para>As a safety check
138 <command>systemd-nspawn
</command> will verify the
139 existence of
<filename>/etc/os-release
</filename> in
140 the container tree before starting the container (see
141 <citerefentry><refentrytitle>os-release
</refentrytitle><manvolnum>5</manvolnum></citerefentry>). It
142 might be necessary to add this file to the container
143 tree manually if the OS of the container is too old to
144 contain this file out-of-the-box.
</para>
148 <title>Options
</title>
150 <para>If option
<option>-b
</option> is specified, the
151 arguments are used as arguments for the init
152 binary. Otherwise,
<replaceable>COMMAND
</replaceable>
153 specifies the program to launch in the container, and
154 the remaining arguments are used as arguments for this
155 program. If
<option>-b
</option> is not used and no
156 arguments are specifed, a shell is launched in the
159 <para>The following options are understood:
</para>
163 <term><option>-D
</option></term>
164 <term><option>--directory=
</option></term>
166 <listitem><para>Directory to use as
167 file system root for the namespace
168 container. If omitted, the current
170 used.
</para></listitem>
174 <term><option>-b
</option></term>
175 <term><option>--boot
</option></term>
177 <listitem><para>Automatically search
178 for an init binary and invoke it
179 instead of a shell or a user supplied
180 program. If this option is used,
181 arguments specified on the command
182 line are used as arguments for the
183 init binary. This option may not be
185 <option>--share-system
</option>.
190 <term><option>-u
</option></term>
191 <term><option>--user=
</option></term>
193 <listitem><para>Run the command
194 under specified user, create home
195 directory and cd into it. As rest
196 of systemd-nspawn, this is not
197 the security feature and limits
198 against accidental changes only.
203 <term><option>-M
</option></term>
204 <term><option>--machine=
</option></term>
206 <listitem><para>Sets the machine name
207 for this container. This name may be
208 used to identify this container on the
209 host, and is used to initialize the
210 container's hostname (which the
211 container can choose to override,
212 however). If not specified, the last
213 component of the root directory of the
214 container is used.
</para></listitem>
218 <term><option>--uuid=
</option></term>
220 <listitem><para>Set the specified UUID
221 for the container. The init system
223 <filename>/etc/machine-id
</filename>
224 from this if this file is not set yet.
229 <term><option>--slice=
</option></term>
231 <listitem><para>Make the container
232 part of the specified slice, instead
234 <filename>machine.slice
</filename>.
</para>
239 <term><option>--private-network
</option></term>
241 <listitem><para>Disconnect networking
242 of the container from the host. This
243 makes all network interfaces
244 unavailable in the container, with the
245 exception of the loopback device and
247 <option>--network-interface=
</option>
249 <option>--network-veth
</option>. If
250 this option is specified, the
251 CAP_NET_ADMIN capability will be added
252 to the set of capabilities the
253 container retains. The latter may be
255 <option>--drop-capability=
</option>.
</para></listitem>
259 <term><option>--network-interface=
</option></term>
261 <listitem><para>Assign the specified
262 network interface to the
263 container. This will move the
264 specified interface from the calling
265 namespace and place it in the
266 container. When the container
267 terminates, it is moved back to the
268 host namespace. Note that
269 <option>--network-interface=
</option>
271 <option>--private-network
</option>. This
272 option may be used more than once to
273 add multiple network interfaces to the
274 container.
</para></listitem>
278 <term><option>--network-veth
</option></term>
280 <listitem><para>Create a virtual
281 Ethernet link between host and
282 container. The host side of the
283 Ethernet link will be available as a
284 network interface named after the
285 container's name (as specified with
286 <option>--machine=
</option>), prefixed
287 with
<literal>ve-
</literal>. The
288 container side of the the Ethernet
290 <literal>host0
</literal>. Note that
291 <option>--network-veth
</option>
293 <option>--private-network
</option>.
</para></listitem>
297 <term><option>--network-bridge=
</option></term>
299 <listitem><para>Adds the host side of
300 the Ethernet link created with
301 <option>--network-veth
</option> to the
302 specified bridge. Note that
303 <option>--network-bridge=
</option>
305 <option>--network-veth
</option>. If
306 this option is used the host side of
307 the Ethernet link will use the
308 <literal>vb-
</literal> prefix instead
309 of
<literal>ve-
</literal>.
</para></listitem>
313 <term><option>-Z
</option></term>
314 <term><option>--selinux-context=
</option></term>
316 <listitem><para>Sets the SELinux
317 security context to be used to label
318 processes in the container.
</para>
323 <term><option>-L
</option></term>
324 <term><option>--selinux-apifs-context=
</option></term>
326 <listitem><para>Sets the SELinux security
327 context to be used to label files in
328 the virtual API file systems in the
334 <term><option>--capability=
</option></term>
336 <listitem><para>List one or more
337 additional capabilities to grant the
338 container. Takes a comma-separated
339 list of capability names, see
340 <citerefentry><refentrytitle>capabilities
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
341 for more information. Note that the
342 following capabilities will be granted
343 in any way: CAP_CHOWN,
344 CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
345 CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
348 CAP_NET_BIND_SERVICE,
349 CAP_NET_BROADCAST, CAP_NET_RAW,
350 CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP,
351 CAP_SETUID, CAP_SYS_ADMIN,
352 CAP_SYS_CHROOT, CAP_SYS_NICE,
353 CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG,
354 CAP_SYS_RESOURCE, CAP_SYS_BOOT,
356 CAP_AUDIT_CONTROL. Also CAP_NET_ADMIN
358 <option>--private-network
</option> is
359 specified. If the special value
360 <literal>all
</literal> is passed, all
362 retained.
</para></listitem>
366 <term><option>--drop-capability=
</option></term>
368 <listitem><para>Specify one or more
369 additional capabilities to drop for
370 the container. This allows running the
371 container with fewer capabilities than
372 the default (see above).
</para></listitem>
376 <term><option>--link-journal=
</option></term>
378 <listitem><para>Control whether the
379 container's journal shall be made
380 visible to the host system. If enabled,
381 allows viewing the container's journal
382 files from the host (but not vice
384 <literal>no
</literal>,
385 <literal>host
</literal>,
386 <literal>guest
</literal>,
387 <literal>auto
</literal>. If
388 <literal>no
</literal>, the journal is
389 not linked. If
<literal>host
</literal>,
390 the journal files are stored on the
391 host file system (beneath
392 <filename>/var/log/journal/
<replaceable>machine-id
</replaceable></filename>)
393 and the subdirectory is bind-mounted
394 into the container at the same
395 location. If
<literal>guest
</literal>,
396 the journal files are stored on the
397 guest file system (beneath
398 <filename>/var/log/journal/
<replaceable>machine-id
</replaceable></filename>)
399 and the subdirectory is symlinked into the host
400 at the same location. If
401 <literal>auto
</literal> (the default),
402 and the right subdirectory of
403 <filename>/var/log/journal
</filename>
404 exists, it will be bind mounted
405 into the container. If the
406 subdirectory does not exist, no
407 linking is performed. Effectively,
408 booting a container once with
409 <literal>guest
</literal> or
410 <literal>host
</literal> will link the
411 journal persistently if further on
412 the default of
<literal>auto
</literal>
413 is used.
</para></listitem>
417 <term><option>-j
</option></term>
419 <listitem><para>Equivalent to
420 <option>--link-journal=guest
</option>.
</para></listitem>
424 <term><option>--read-only
</option></term>
426 <listitem><para>Mount the root file
427 system read-only for the
428 container.
</para></listitem>
432 <term><option>--bind=
</option></term>
433 <term><option>--bind-ro=
</option></term>
435 <listitem><para>Bind mount a file or
436 directory from the host into the
437 container. Either takes a path
438 argument -- in which case the
439 specified path will be mounted from
440 the host to the same path in the
441 container --, or a colon-separated
442 pair of paths -- in which case the
443 first specified path is the source in
444 the host, and the second path is the
445 destination in the container. The
446 <option>--bind-ro=
</option> option
447 creates read-only bind
448 mounts.
</para></listitem>
452 <term><option>--setenv=
</option></term>
454 <listitem><para>Specifies an
455 environment variable assignment to
456 pass to the init process in the
457 container, in the format
458 <literal>NAME=VALUE
</literal>. This
459 may be used to override the default
460 variables or to set additional
461 variables. This parameter may be used
462 more than once.
</para></listitem>
466 <term><option>--share-system
</option></term>
468 <listitem><para>Allows the container
469 to share certain system facilities
470 with the host. More specifically, this
471 turns off PID namespacing, UTS
472 namespacing and IPC namespacing, and
473 thus allows the guest to see and
474 interact more easily with processes
475 outside of the container. Note that
476 using this option makes it impossible
477 to start up a full Operating System in
478 the container, as an init system
479 cannot operate in this mode. It is
480 only useful to run specific programs
481 or applications this way, without
482 involving an init system in the
483 container. This option implies
484 <option>--register=no
</option>. This
485 option may not be combined with
486 <option>--boot
</option>.
</para></listitem>
490 <term><option>--register=
</option></term>
492 <listitem><para>Controls whether the
493 container is registered with
494 <citerefentry><refentrytitle>systemd-machined
</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Takes
495 a boolean argument, defaults to
496 <literal>yes
</literal>. This option
497 should be enabled when the container
498 runs a full Operating System (more
499 specifically: an init system), and is
500 useful to ensure that the container is
502 <citerefentry><refentrytitle>machinectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
503 and shown by tools such as
504 <citerefentry><refentrytitle>ps
</refentrytitle><manvolnum>1</manvolnum></citerefentry>. If
505 the container does not run an init
506 system, it is recommended to set this
507 option to
<literal>no
</literal>. Note
508 that
<option>--share-system
</option>
510 <option>--register=no
</option>.
515 <term><option>--keep-unit
</option></term>
517 <listitem><para>Instead of creating a
518 transient scope unit to run the
519 container in, simply register the
520 service or scope unit
521 <command>systemd-nspawn
</command> has
523 <citerefentry><refentrytitle>systemd-machined
</refentrytitle><manvolnum>8</manvolnum></citerefentry>. This
525 <option>--register=no
</option> is
526 used. This switch should be used if
527 <command>systemd-nspawn
</command> is
528 invoked from within a service unit,
529 and the service unit's sole purpose
531 <command>systemd-nspawn
</command>
532 container. This option is not
533 available if run from a user
534 session.
</para></listitem>
538 <term><option>--personality=
</option></term>
540 <listitem><para>Control the
541 architecture (
"personality") reported
543 <citerefentry><refentrytitle>uname
</refentrytitle><manvolnum>2</manvolnum></citerefentry>
544 in the container. Currently, only
545 <literal>x86
</literal> and
546 <literal>x86-
64</literal> are
547 supported. This is useful when running
548 a
32bit container on a
64bit
549 host. If this setting is not used
550 the personality reported in the
551 container is the same as the one
553 host.
</para></listitem>
557 <term><option>-q
</option></term>
558 <term><option>--quiet
</option></term>
560 <listitem><para>Turns off any status
561 output by the tool itself. When this
562 switch is used, the only output
563 from nspawn will be the console output
564 of the container OS itself.
</para></listitem>
567 <xi:include href=
"standard-options.xml" xpointer=
"help" />
568 <xi:include href=
"standard-options.xml" xpointer=
"version" />
574 <title>Example
1</title>
576 <programlisting># yum -y --releasever=
19 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal
577 # systemd-nspawn -bD /srv/mycontainer
</programlisting>
579 <para>This installs a minimal Fedora distribution into
580 the directory
<filename noindex='true'
>/srv/mycontainer/
</filename> and
581 then boots an OS in a namespace container in
586 <title>Example
2</title>
588 <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
589 # systemd-nspawn -D ~/debian-tree/
</programlisting>
591 <para>This installs a minimal Debian unstable
592 distribution into the directory
593 <filename>~/debian-tree/
</filename> and then spawns a
594 shell in a namespace container in it.
</para>
598 <title>Example
3</title>
600 <programlisting># pacstrap -c -d ~/arch-tree/ base
601 # systemd-nspawn -bD ~/arch-tree/
</programlisting>
603 <para>This installs a mimimal Arch Linux distribution into
604 the directory
<filename>~/arch-tree/
</filename> and then
605 boots an OS in a namespace container in it.
</para>
609 <title>Example
4</title>
611 <programlisting># mv ~/arch-tree /var/lib/container/arch
612 # systemctl enable systemd-nspawn@arch.service
613 # systemctl start systemd-nspawn@arch.service
</programlisting>
615 <para>This makes the Arch Linux container part of the
616 <filename>multi-user.target
</filename> on the host.
621 <title>Example
5</title>
623 <programlisting># btrfs subvolume snapshot / /.tmp
624 # systemd-nspawn --private-network -D /.tmp -b
</programlisting>
626 <para>This runs a copy of the host system in a
627 btrfs snapshot.
</para>
631 <title>Example
6</title>
633 <programlisting># chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container
634 # 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>
636 <para>This runs a container with SELinux sandbox security contexts.
</para>
640 <title>Exit status
</title>
642 <para>The exit code of the program executed in the
643 container is returned.
</para>
647 <title>See Also
</title>
649 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
650 <citerefentry><refentrytitle>chroot
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
651 <citerefentry><refentrytitle>yum
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
652 <citerefentry><refentrytitle>debootstrap
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
653 <citerefentry><refentrytitle>pacman
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
654 <citerefentry><refentrytitle>systemd.slice
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
655 <citerefentry><refentrytitle>machinectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>