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 project='man-pages'><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 project='man-pages'><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 project='die-net'><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
107 <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
109 <citerefentry project='archlinux'><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>/usr/lib/os-release</filename>
140 or <filename>/etc/os-release</filename> in the
141 container tree before starting the container (see
142 <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>). It
143 might be necessary to add this file to the container
144 tree manually if the OS of the container is too old to
145 contain this file out-of-the-box.</para>
149 <title>Options</title>
151 <para>If option <option>-b</option> is specified, the
152 arguments are used as arguments for the init
153 binary. Otherwise, <replaceable>COMMAND</replaceable>
154 specifies the program to launch in the container, and
155 the remaining arguments are used as arguments for this
156 program. If <option>-b</option> is not used and no
157 arguments are specifed, a shell is launched in the
160 <para>The following options are understood:</para>
164 <term><option>-D</option></term>
165 <term><option>--directory=</option></term>
167 <listitem><para>Directory to use as
168 file system root for the container. If
169 neither <option>--directory=</option>
170 nor <option>--image=</option> are
171 specified, the current directory will
172 be used. May not be specified together with
173 <option>--image=</option>.</para></listitem>
177 <term><option>-i</option></term>
178 <term><option>--image=</option></term>
180 <listitem><para>Disk image to mount
181 the root directory for the container
182 from. Takes a path to a regular file
183 or to a block device node. The file or
184 block device must contain a GUID
185 Partition Table with a root partition
186 which is mounted as the root directory
187 of the container. Optionally, it may
188 contain a home and/or a server data
189 partition which are mounted to the
190 appropriate places in the
191 container. All these partitions must
192 be identified by the partition types
193 defined by the <ulink
194 url="http://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/">Discoverable
195 Partitions Specification</ulink>. Any
196 other partitions, such as foreign
197 partitions, swap partitions or EFI
198 system partitions are not mounted. May
199 not be specified together with
200 <option>--directory=</option>.</para></listitem>
204 <term><option>-b</option></term>
205 <term><option>--boot</option></term>
207 <listitem><para>Automatically search
208 for an init binary and invoke it
209 instead of a shell or a user supplied
210 program. If this option is used,
211 arguments specified on the command
212 line are used as arguments for the
213 init binary. This option may not be
215 <option>--share-system</option>.
220 <term><option>-u</option></term>
221 <term><option>--user=</option></term>
223 <listitem><para>After transitioning
224 into the container, change to the
225 specified user-defined in the
226 container's user database. Like all
227 other systemd-nspawn features, this is
228 not a security feature and provides
229 protection against accidental
230 destructive operations
231 only.</para></listitem>
235 <term><option>-M</option></term>
236 <term><option>--machine=</option></term>
238 <listitem><para>Sets the machine name
239 for this container. This name may be
240 used to identify this container on the
241 host, and is used to initialize the
242 container's hostname (which the
243 container can choose to override,
244 however). If not specified, the last
245 component of the root directory of the
246 container is used.</para></listitem>
250 <term><option>--uuid=</option></term>
252 <listitem><para>Set the specified UUID
253 for the container. The init system
255 <filename>/etc/machine-id</filename>
256 from this if this file is not set yet.
261 <term><option>--slice=</option></term>
263 <listitem><para>Make the container
264 part of the specified slice, instead
266 <filename>machine.slice</filename>.</para>
271 <term><option>--private-network</option></term>
273 <listitem><para>Disconnect networking
274 of the container from the host. This
275 makes all network interfaces
276 unavailable in the container, with the
277 exception of the loopback device and
279 <option>--network-interface=</option>
281 <option>--network-veth</option>. If
282 this option is specified, the
283 CAP_NET_ADMIN capability will be added
284 to the set of capabilities the
285 container retains. The latter may be
287 <option>--drop-capability=</option>.</para></listitem>
291 <term><option>--network-interface=</option></term>
293 <listitem><para>Assign the specified
294 network interface to the
295 container. This will remove the
296 specified interface from the calling
297 namespace and place it in the
298 container. When the container
299 terminates, it is moved back to the
300 host namespace. Note that
301 <option>--network-interface=</option>
303 <option>--private-network</option>. This
304 option may be used more than once to
305 add multiple network interfaces to the
306 container.</para></listitem>
310 <term><option>--network-macvlan=</option></term>
312 <listitem><para>Create a
313 <literal>macvlan</literal> interface
314 of the specified Ethernet network
315 interface and add it to the
317 <literal>macvlan</literal> interface
318 is a virtual interface that adds a
319 second MAC address to an existing
320 physical Ethernet link. The interface
321 in the container will be named after
322 the interface on the host, prefixed
323 with <literal>mv-</literal>. Note that
324 <option>--network-macvlan=</option>
326 <option>--private-network</option>. This
327 option may be used more than once to
328 add multiple network interfaces to the
329 container.</para></listitem>
333 <term><option>--network-veth</option></term>
335 <listitem><para>Create a virtual
337 (<literal>veth</literal>) between host
338 and container. The host side of the
339 Ethernet link will be available as a
340 network interface named after the
341 container's name (as specified with
342 <option>--machine=</option>), prefixed
343 with <literal>ve-</literal>. The
344 container side of the Ethernet
346 <literal>host0</literal>. Note that
347 <option>--network-veth</option>
349 <option>--private-network</option>.</para></listitem>
353 <term><option>--network-bridge=</option></term>
355 <listitem><para>Adds the host side of
356 the Ethernet link created with
357 <option>--network-veth</option> to the
358 specified bridge. Note that
359 <option>--network-bridge=</option>
361 <option>--network-veth</option>. If
362 this option is used, the host side of
363 the Ethernet link will use the
364 <literal>vb-</literal> prefix instead
365 of <literal>ve-</literal>.</para></listitem>
369 <term><option>-Z</option></term>
370 <term><option>--selinux-context=</option></term>
372 <listitem><para>Sets the SELinux
373 security context to be used to label
374 processes in the container.</para>
379 <term><option>-L</option></term>
380 <term><option>--selinux-apifs-context=</option></term>
382 <listitem><para>Sets the SELinux security
383 context to be used to label files in
384 the virtual API file systems in the
390 <term><option>--capability=</option></term>
392 <listitem><para>List one or more
393 additional capabilities to grant the
394 container. Takes a comma-separated
395 list of capability names, see
396 <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
397 for more information. Note that the
398 following capabilities will be granted
399 in any way: CAP_CHOWN,
400 CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
401 CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
404 CAP_NET_BIND_SERVICE,
405 CAP_NET_BROADCAST, CAP_NET_RAW,
406 CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP,
407 CAP_SETUID, CAP_SYS_ADMIN,
408 CAP_SYS_CHROOT, CAP_SYS_NICE,
409 CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG,
410 CAP_SYS_RESOURCE, CAP_SYS_BOOT,
412 CAP_AUDIT_CONTROL. Also CAP_NET_ADMIN
414 <option>--private-network</option> is
415 specified. If the special value
416 <literal>all</literal> is passed, all
418 retained.</para></listitem>
422 <term><option>--drop-capability=</option></term>
424 <listitem><para>Specify one or more
425 additional capabilities to drop for
426 the container. This allows running the
427 container with fewer capabilities than
428 the default (see above).</para></listitem>
432 <term><option>--link-journal=</option></term>
434 <listitem><para>Control whether the
435 container's journal shall be made
436 visible to the host system. If enabled,
437 allows viewing the container's journal
438 files from the host (but not vice
440 <literal>no</literal>,
441 <literal>host</literal>,
442 <literal>try-host</literal>,
443 <literal>guest</literal>,
444 <literal>try-guest</literal>,
445 <literal>auto</literal>. If
446 <literal>no</literal>, the journal is
447 not linked. If <literal>host</literal>,
448 the journal files are stored on the
449 host file system (beneath
450 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
451 and the subdirectory is bind-mounted
452 into the container at the same
453 location. If <literal>guest</literal>,
454 the journal files are stored on the
455 guest file system (beneath
456 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
457 and the subdirectory is symlinked into the host
458 at the same location. <literal>try-host</literal>
459 and <literal>try-guest</literal> do the same
460 but do not fail if the host does not have
461 persistant journalling enabled.
462 If <literal>auto</literal> (the default),
463 and the right subdirectory of
464 <filename>/var/log/journal</filename>
465 exists, it will be bind mounted
466 into the container. If the
467 subdirectory does not exist, no
468 linking is performed. Effectively,
469 booting a container once with
470 <literal>guest</literal> or
471 <literal>host</literal> will link the
472 journal persistently if further on
473 the default of <literal>auto</literal>
474 is used.</para></listitem>
478 <term><option>-j</option></term>
480 <listitem><para>Equivalent to
481 <option>--link-journal=try-guest</option>.</para></listitem>
485 <term><option>--read-only</option></term>
487 <listitem><para>Mount the root file
488 system read-only for the
489 container.</para></listitem>
493 <term><option>--bind=</option></term>
494 <term><option>--bind-ro=</option></term>
496 <listitem><para>Bind mount a file or
497 directory from the host into the
498 container. Either takes a path
499 argument -- in which case the
500 specified path will be mounted from
501 the host to the same path in the
502 container --, or a colon-separated
503 pair of paths -- in which case the
504 first specified path is the source in
505 the host, and the second path is the
506 destination in the container. The
507 <option>--bind-ro=</option> option
508 creates read-only bind
509 mounts.</para></listitem>
513 <term><option>--tmpfs=</option></term>
515 <listitem><para>Mount a tmpfs file
516 system into the container. Takes a
517 single absolute path argument that
518 specifies where to mount the tmpfs
519 instance to (in which case the
520 directory access mode will be chosen
521 as 0755, owned by root/root), or
522 optionally a colon-separated pair of
523 path and mount option string, that is
524 used for mounting (in which case the
525 kernel default for access mode and
526 owner will be chosen, unless otherwise
527 specified). This option is
528 particularly useful for mounting
530 <filename>/var</filename> as tmpfs, to
531 allow state-less systems, in
532 particular when combined with
533 <option>--read-only</option>.</para></listitem>
537 <term><option>--setenv=</option></term>
539 <listitem><para>Specifies an
540 environment variable assignment to
541 pass to the init process in the
542 container, in the format
543 <literal>NAME=VALUE</literal>. This
544 may be used to override the default
545 variables or to set additional
546 variables. This parameter may be used
547 more than once.</para></listitem>
551 <term><option>--share-system</option></term>
553 <listitem><para>Allows the container
554 to share certain system facilities
555 with the host. More specifically, this
556 turns off PID namespacing, UTS
557 namespacing and IPC namespacing, and
558 thus allows the guest to see and
559 interact more easily with processes
560 outside of the container. Note that
561 using this option makes it impossible
562 to start up a full Operating System in
563 the container, as an init system
564 cannot operate in this mode. It is
565 only useful to run specific programs
566 or applications this way, without
567 involving an init system in the
568 container. This option implies
569 <option>--register=no</option>. This
570 option may not be combined with
571 <option>--boot</option>.</para></listitem>
575 <term><option>--register=</option></term>
577 <listitem><para>Controls whether the
578 container is registered with
579 <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Takes
580 a boolean argument, defaults to
581 <literal>yes</literal>. This option
582 should be enabled when the container
583 runs a full Operating System (more
584 specifically: an init system), and is
585 useful to ensure that the container is
587 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
588 and shown by tools such as
589 <citerefentry project='man-pages'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>. If
590 the container does not run an init
591 system, it is recommended to set this
592 option to <literal>no</literal>. Note
593 that <option>--share-system</option>
595 <option>--register=no</option>.
600 <term><option>--keep-unit</option></term>
602 <listitem><para>Instead of creating a
603 transient scope unit to run the
604 container in, simply register the
605 service or scope unit
606 <command>systemd-nspawn</command> has
608 <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. This
610 <option>--register=no</option> is
611 used. This switch should be used if
612 <command>systemd-nspawn</command> is
613 invoked from within a service unit,
614 and the service unit's sole purpose
616 <command>systemd-nspawn</command>
617 container. This option is not
618 available if run from a user
619 session.</para></listitem>
623 <term><option>--personality=</option></term>
625 <listitem><para>Control the
626 architecture ("personality") reported
628 <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>
629 in the container. Currently, only
630 <literal>x86</literal> and
631 <literal>x86-64</literal> are
632 supported. This is useful when running
633 a 32-bit container on a 64-bit
634 host. If this setting is not used,
635 the personality reported in the
636 container is the same as the one
638 host.</para></listitem>
642 <term><option>-q</option></term>
643 <term><option>--quiet</option></term>
645 <listitem><para>Turns off any status
646 output by the tool itself. When this
647 switch is used, the only output
648 from nspawn will be the console output
649 of the container OS itself.</para></listitem>
653 <term><option>--volatile</option><replaceable>=MODE</replaceable></term>
655 <listitem><para>Boots the container in
656 volatile (ephemeral) mode. When no
657 mode parameter is passed or when mode
658 is specified as <literal>yes</literal>
659 full volatile mode is enabled. This
660 means the root directory is mounted as
662 <literal>tmpfs</literal> instance, and
663 <filename>/usr</filename> from the OS
664 tree is mounted into it, read-only
665 (the system thus starts up with
666 read-only OS resources, but pristine
667 state and configuration, any changes
668 to the either are lost on
669 shutdown). When the mode parameter is
670 specified as <literal>state</literal>
671 the OS tree is mounted read-only, but
672 <filename>/var</filename> is mounted
673 as <literal>tmpfs</literal> instance
674 into it (the system thus starts up
675 with read-only OS resources and
676 configuration, but pristine state, any
677 changes to the latter are lost on
678 shutdown). When the mode parameter is
679 specified as <literal>no</literal>
680 (the default) the whole OS tree is made
681 available writable.</para>
683 <para>Note that setting this to
684 <literal>yes</literal> or
685 <literal>state</literal> will only
686 work correctly with operating systems
687 in the container that can boot up with
688 only <filename>/usr</filename>
689 mounted, and are able to populate
690 <filename>/var</filename>
692 needed.</para></listitem>
695 <xi:include href="standard-options.xml" xpointer="help" />
696 <xi:include href="standard-options.xml" xpointer="version" />
702 <title>Examples</title>
704 <title>Boot a minimal Fedora distribution in a container</title>
706 <programlisting># yum -y --releasever=19 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal
707 # systemd-nspawn -bD /srv/mycontainer</programlisting>
709 <para>This installs a minimal Fedora distribution into
710 the directory <filename noindex='true'>/srv/mycontainer/</filename> and
711 then boots an OS in a namespace container in
716 <title>Spawn a shell in a container of a minimal Debian unstable distribution</title>
718 <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
719 # systemd-nspawn -D ~/debian-tree/</programlisting>
721 <para>This installs a minimal Debian unstable
722 distribution into the directory
723 <filename>~/debian-tree/</filename> and then spawns a
724 shell in a namespace container in it.</para>
728 <title>Boot a minimal Arch Linux distribution in a container</title>
730 <programlisting># pacstrap -c -d ~/arch-tree/ base
731 # systemd-nspawn -bD ~/arch-tree/</programlisting>
733 <para>This installs a mimimal Arch Linux distribution into
734 the directory <filename>~/arch-tree/</filename> and then
735 boots an OS in a namespace container in it.</para>
739 <title>Enable Arch Linux container on boot</title>
741 <programlisting># mv ~/arch-tree /var/lib/container/arch
742 # systemctl enable systemd-nspawn@arch.service
743 # systemctl start systemd-nspawn@arch.service</programlisting>
745 <para>This makes the Arch Linux container part of the
746 <filename>multi-user.target</filename> on the host.
751 <title>Boot into a btrfs snapshot of the host system</title>
753 <programlisting># btrfs subvolume snapshot / /.tmp
754 # systemd-nspawn --private-network -D /.tmp -b</programlisting>
756 <para>This runs a copy of the host system in a
757 btrfs snapshot.</para>
761 <title>Run a container with SELinux sandbox security contexts</title>
763 <programlisting># chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container
764 # 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>
769 <title>Exit status</title>
771 <para>The exit code of the program executed in the
772 container is returned.</para>
776 <title>See Also</title>
778 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
779 <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
780 <citerefentry project='die-net'><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
781 <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
782 <citerefentry project='archlinux'><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
783 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
784 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>