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 container. If
168 neither <option>--directory=</option>
169 nor <option>--image=</option> are
170 specified, the current directory will
171 be used. May not be specified together with
172 <option>--image=</option>.</para></listitem>
176 <term><option>-i</option></term>
177 <term><option>--image=</option></term>
179 <listitem><para>Disk image to mount
180 the root directory for the container
181 from. Takes a path to a regular file
182 or to a block device node. The file or
183 block device must contain a GUID
184 Partition Table with a root partition
185 which is mounted as the root directory
186 of the container. Optionally, it may
187 contain a home and/or a server data
188 partition which are mounted to the
189 appropriate places in the
190 container. All these partitions must
191 be identified by the partition types
192 defined by the <ulink
193 url="http://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/">Discoverable
194 Partitions Specification</ulink>. Any
195 other partitions, such as foreign
196 partitions, swap partitions or EFI
197 system partitions are not mounted. May
198 not be specified together with
199 <option>--directory=</option>.</para></listitem>
203 <term><option>-b</option></term>
204 <term><option>--boot</option></term>
206 <listitem><para>Automatically search
207 for an init binary and invoke it
208 instead of a shell or a user supplied
209 program. If this option is used,
210 arguments specified on the command
211 line are used as arguments for the
212 init binary. This option may not be
214 <option>--share-system</option>.
219 <term><option>-u</option></term>
220 <term><option>--user=</option></term>
222 <listitem><para>Run the command
223 under specified user, create home
224 directory and cd into it. As rest
225 of systemd-nspawn, this is not
226 the security feature and limits
227 against accidental changes only.
232 <term><option>-M</option></term>
233 <term><option>--machine=</option></term>
235 <listitem><para>Sets the machine name
236 for this container. This name may be
237 used to identify this container on the
238 host, and is used to initialize the
239 container's hostname (which the
240 container can choose to override,
241 however). If not specified, the last
242 component of the root directory of the
243 container is used.</para></listitem>
247 <term><option>--uuid=</option></term>
249 <listitem><para>Set the specified UUID
250 for the container. The init system
252 <filename>/etc/machine-id</filename>
253 from this if this file is not set yet.
258 <term><option>--slice=</option></term>
260 <listitem><para>Make the container
261 part of the specified slice, instead
263 <filename>machine.slice</filename>.</para>
268 <term><option>--private-network</option></term>
270 <listitem><para>Disconnect networking
271 of the container from the host. This
272 makes all network interfaces
273 unavailable in the container, with the
274 exception of the loopback device and
276 <option>--network-interface=</option>
278 <option>--network-veth</option>. If
279 this option is specified, the
280 CAP_NET_ADMIN capability will be added
281 to the set of capabilities the
282 container retains. The latter may be
284 <option>--drop-capability=</option>.</para></listitem>
288 <term><option>--network-interface=</option></term>
290 <listitem><para>Assign the specified
291 network interface to the
292 container. This will remove the
293 specified interface from the calling
294 namespace and place it in the
295 container. When the container
296 terminates, it is moved back to the
297 host namespace. Note that
298 <option>--network-interface=</option>
300 <option>--private-network</option>. This
301 option may be used more than once to
302 add multiple network interfaces to the
303 container.</para></listitem>
307 <term><option>--network-macvlan=</option></term>
309 <listitem><para>Create a
310 <literal>macvlan</literal> interface
311 of the specified Ethernet network
312 interface and add it to the
314 <literal>macvlan</literal> interface
315 is a virtual interface that adds a
316 second MAC address to an existing
317 physical Ethernet link. The interface
318 in the container will be named after
319 the interface on the host, prefixed
320 with <literal>mv-</literal>. Note that
321 <option>--network-macvlan=</option>
323 <option>--private-network</option>. This
324 option may be used more than once to
325 add multiple network interfaces to the
326 container.</para></listitem>
330 <term><option>--network-veth</option></term>
332 <listitem><para>Create a virtual
334 (<literal>veth</literal>) between host
335 and container. The host side of the
336 Ethernet link will be available as a
337 network interface named after the
338 container's name (as specified with
339 <option>--machine=</option>), prefixed
340 with <literal>ve-</literal>. The
341 container side of the the Ethernet
343 <literal>host0</literal>. Note that
344 <option>--network-veth</option>
346 <option>--private-network</option>.</para></listitem>
350 <term><option>--network-bridge=</option></term>
352 <listitem><para>Adds the host side of
353 the Ethernet link created with
354 <option>--network-veth</option> to the
355 specified bridge. Note that
356 <option>--network-bridge=</option>
358 <option>--network-veth</option>. If
359 this option is used the host side of
360 the Ethernet link will use the
361 <literal>vb-</literal> prefix instead
362 of <literal>ve-</literal>.</para></listitem>
366 <term><option>-Z</option></term>
367 <term><option>--selinux-context=</option></term>
369 <listitem><para>Sets the SELinux
370 security context to be used to label
371 processes in the container.</para>
376 <term><option>-L</option></term>
377 <term><option>--selinux-apifs-context=</option></term>
379 <listitem><para>Sets the SELinux security
380 context to be used to label files in
381 the virtual API file systems in the
387 <term><option>--capability=</option></term>
389 <listitem><para>List one or more
390 additional capabilities to grant the
391 container. Takes a comma-separated
392 list of capability names, see
393 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
394 for more information. Note that the
395 following capabilities will be granted
396 in any way: CAP_CHOWN,
397 CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
398 CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
401 CAP_NET_BIND_SERVICE,
402 CAP_NET_BROADCAST, CAP_NET_RAW,
403 CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP,
404 CAP_SETUID, CAP_SYS_ADMIN,
405 CAP_SYS_CHROOT, CAP_SYS_NICE,
406 CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG,
407 CAP_SYS_RESOURCE, CAP_SYS_BOOT,
409 CAP_AUDIT_CONTROL. Also CAP_NET_ADMIN
411 <option>--private-network</option> is
412 specified. If the special value
413 <literal>all</literal> is passed, all
415 retained.</para></listitem>
419 <term><option>--drop-capability=</option></term>
421 <listitem><para>Specify one or more
422 additional capabilities to drop for
423 the container. This allows running the
424 container with fewer capabilities than
425 the default (see above).</para></listitem>
429 <term><option>--link-journal=</option></term>
431 <listitem><para>Control whether the
432 container's journal shall be made
433 visible to the host system. If enabled,
434 allows viewing the container's journal
435 files from the host (but not vice
437 <literal>no</literal>,
438 <literal>host</literal>,
439 <literal>guest</literal>,
440 <literal>auto</literal>. If
441 <literal>no</literal>, the journal is
442 not linked. If <literal>host</literal>,
443 the journal files are stored on the
444 host file system (beneath
445 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
446 and the subdirectory is bind-mounted
447 into the container at the same
448 location. If <literal>guest</literal>,
449 the journal files are stored on the
450 guest file system (beneath
451 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
452 and the subdirectory is symlinked into the host
453 at the same location. If
454 <literal>auto</literal> (the default),
455 and the right subdirectory of
456 <filename>/var/log/journal</filename>
457 exists, it will be bind mounted
458 into the container. If the
459 subdirectory does not exist, no
460 linking is performed. Effectively,
461 booting a container once with
462 <literal>guest</literal> or
463 <literal>host</literal> will link the
464 journal persistently if further on
465 the default of <literal>auto</literal>
466 is used.</para></listitem>
470 <term><option>-j</option></term>
472 <listitem><para>Equivalent to
473 <option>--link-journal=guest</option>.</para></listitem>
477 <term><option>--read-only</option></term>
479 <listitem><para>Mount the root file
480 system read-only for the
481 container.</para></listitem>
485 <term><option>--bind=</option></term>
486 <term><option>--bind-ro=</option></term>
488 <listitem><para>Bind mount a file or
489 directory from the host into the
490 container. Either takes a path
491 argument -- in which case the
492 specified path will be mounted from
493 the host to the same path in the
494 container --, or a colon-separated
495 pair of paths -- in which case the
496 first specified path is the source in
497 the host, and the second path is the
498 destination in the container. The
499 <option>--bind-ro=</option> option
500 creates read-only bind
501 mounts.</para></listitem>
505 <term><option>--setenv=</option></term>
507 <listitem><para>Specifies an
508 environment variable assignment to
509 pass to the init process in the
510 container, in the format
511 <literal>NAME=VALUE</literal>. This
512 may be used to override the default
513 variables or to set additional
514 variables. This parameter may be used
515 more than once.</para></listitem>
519 <term><option>--share-system</option></term>
521 <listitem><para>Allows the container
522 to share certain system facilities
523 with the host. More specifically, this
524 turns off PID namespacing, UTS
525 namespacing and IPC namespacing, and
526 thus allows the guest to see and
527 interact more easily with processes
528 outside of the container. Note that
529 using this option makes it impossible
530 to start up a full Operating System in
531 the container, as an init system
532 cannot operate in this mode. It is
533 only useful to run specific programs
534 or applications this way, without
535 involving an init system in the
536 container. This option implies
537 <option>--register=no</option>. This
538 option may not be combined with
539 <option>--boot</option>.</para></listitem>
543 <term><option>--register=</option></term>
545 <listitem><para>Controls whether the
546 container is registered with
547 <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Takes
548 a boolean argument, defaults to
549 <literal>yes</literal>. This option
550 should be enabled when the container
551 runs a full Operating System (more
552 specifically: an init system), and is
553 useful to ensure that the container is
555 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
556 and shown by tools such as
557 <citerefentry><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>. If
558 the container does not run an init
559 system, it is recommended to set this
560 option to <literal>no</literal>. Note
561 that <option>--share-system</option>
563 <option>--register=no</option>.
568 <term><option>--keep-unit</option></term>
570 <listitem><para>Instead of creating a
571 transient scope unit to run the
572 container in, simply register the
573 service or scope unit
574 <command>systemd-nspawn</command> has
576 <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. This
578 <option>--register=no</option> is
579 used. This switch should be used if
580 <command>systemd-nspawn</command> is
581 invoked from within a service unit,
582 and the service unit's sole purpose
584 <command>systemd-nspawn</command>
585 container. This option is not
586 available if run from a user
587 session.</para></listitem>
591 <term><option>--personality=</option></term>
593 <listitem><para>Control the
594 architecture ("personality") reported
596 <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>
597 in the container. Currently, only
598 <literal>x86</literal> and
599 <literal>x86-64</literal> are
600 supported. This is useful when running
601 a 32bit container on a 64bit
602 host. If this setting is not used
603 the personality reported in the
604 container is the same as the one
606 host.</para></listitem>
610 <term><option>-q</option></term>
611 <term><option>--quiet</option></term>
613 <listitem><para>Turns off any status
614 output by the tool itself. When this
615 switch is used, the only output
616 from nspawn will be the console output
617 of the container OS itself.</para></listitem>
620 <xi:include href="standard-options.xml" xpointer="help" />
621 <xi:include href="standard-options.xml" xpointer="version" />
627 <title>Example 1</title>
629 <programlisting># yum -y --releasever=19 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal
630 # systemd-nspawn -bD /srv/mycontainer</programlisting>
632 <para>This installs a minimal Fedora distribution into
633 the directory <filename noindex='true'>/srv/mycontainer/</filename> and
634 then boots an OS in a namespace container in
639 <title>Example 2</title>
641 <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
642 # systemd-nspawn -D ~/debian-tree/</programlisting>
644 <para>This installs a minimal Debian unstable
645 distribution into the directory
646 <filename>~/debian-tree/</filename> and then spawns a
647 shell in a namespace container in it.</para>
651 <title>Example 3</title>
653 <programlisting># pacstrap -c -d ~/arch-tree/ base
654 # systemd-nspawn -bD ~/arch-tree/</programlisting>
656 <para>This installs a mimimal Arch Linux distribution into
657 the directory <filename>~/arch-tree/</filename> and then
658 boots an OS in a namespace container in it.</para>
662 <title>Example 4</title>
664 <programlisting># mv ~/arch-tree /var/lib/container/arch
665 # systemctl enable systemd-nspawn@arch.service
666 # systemctl start systemd-nspawn@arch.service</programlisting>
668 <para>This makes the Arch Linux container part of the
669 <filename>multi-user.target</filename> on the host.
674 <title>Example 5</title>
676 <programlisting># btrfs subvolume snapshot / /.tmp
677 # systemd-nspawn --private-network -D /.tmp -b</programlisting>
679 <para>This runs a copy of the host system in a
680 btrfs snapshot.</para>
684 <title>Example 6</title>
686 <programlisting># chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container
687 # 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>
689 <para>This runs a container with SELinux sandbox security contexts.</para>
693 <title>Exit status</title>
695 <para>The exit code of the program executed in the
696 container is returned.</para>
700 <title>See Also</title>
702 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
703 <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
704 <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
705 <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
706 <citerefentry><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
707 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
708 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>