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 remove 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-macvlan=</option></term>
280 <listitem><para>Create a
281 <literal>macvlan</literal> interface
282 of the specified Ethernet network
283 interface and add it to the
285 <literal>macvlan</literal> interface
286 is a virtual interface that adds a
287 second MAC address to an existing
288 physical Ethernet link. The interface
289 in the container will be named after
290 the interface on the host, prefixed
291 with <literal>mv-</literal>. Note that
292 <option>--network-macvlan=</option>
294 <option>--private-network</option>. This
295 option may be used more than once to
296 add multiple network interfaces to the
297 container.</para></listitem>
301 <term><option>--network-veth</option></term>
303 <listitem><para>Create a virtual
305 (<literal>veth</literal>) between host
306 and container. The host side of the
307 Ethernet link will be available as a
308 network interface named after the
309 container's name (as specified with
310 <option>--machine=</option>), prefixed
311 with <literal>ve-</literal>. The
312 container side of the the Ethernet
314 <literal>host0</literal>. Note that
315 <option>--network-veth</option>
317 <option>--private-network</option>.</para></listitem>
321 <term><option>--network-bridge=</option></term>
323 <listitem><para>Adds the host side of
324 the Ethernet link created with
325 <option>--network-veth</option> to the
326 specified bridge. Note that
327 <option>--network-bridge=</option>
329 <option>--network-veth</option>. If
330 this option is used the host side of
331 the Ethernet link will use the
332 <literal>vb-</literal> prefix instead
333 of <literal>ve-</literal>.</para></listitem>
337 <term><option>-Z</option></term>
338 <term><option>--selinux-context=</option></term>
340 <listitem><para>Sets the SELinux
341 security context to be used to label
342 processes in the container.</para>
347 <term><option>-L</option></term>
348 <term><option>--selinux-apifs-context=</option></term>
350 <listitem><para>Sets the SELinux security
351 context to be used to label files in
352 the virtual API file systems in the
358 <term><option>--capability=</option></term>
360 <listitem><para>List one or more
361 additional capabilities to grant the
362 container. Takes a comma-separated
363 list of capability names, see
364 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
365 for more information. Note that the
366 following capabilities will be granted
367 in any way: CAP_CHOWN,
368 CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
369 CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
372 CAP_NET_BIND_SERVICE,
373 CAP_NET_BROADCAST, CAP_NET_RAW,
374 CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP,
375 CAP_SETUID, CAP_SYS_ADMIN,
376 CAP_SYS_CHROOT, CAP_SYS_NICE,
377 CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG,
378 CAP_SYS_RESOURCE, CAP_SYS_BOOT,
380 CAP_AUDIT_CONTROL. Also CAP_NET_ADMIN
382 <option>--private-network</option> is
383 specified. If the special value
384 <literal>all</literal> is passed, all
386 retained.</para></listitem>
390 <term><option>--drop-capability=</option></term>
392 <listitem><para>Specify one or more
393 additional capabilities to drop for
394 the container. This allows running the
395 container with fewer capabilities than
396 the default (see above).</para></listitem>
400 <term><option>--link-journal=</option></term>
402 <listitem><para>Control whether the
403 container's journal shall be made
404 visible to the host system. If enabled,
405 allows viewing the container's journal
406 files from the host (but not vice
408 <literal>no</literal>,
409 <literal>host</literal>,
410 <literal>guest</literal>,
411 <literal>auto</literal>. If
412 <literal>no</literal>, the journal is
413 not linked. If <literal>host</literal>,
414 the journal files are stored on the
415 host file system (beneath
416 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
417 and the subdirectory is bind-mounted
418 into the container at the same
419 location. If <literal>guest</literal>,
420 the journal files are stored on the
421 guest file system (beneath
422 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
423 and the subdirectory is symlinked into the host
424 at the same location. If
425 <literal>auto</literal> (the default),
426 and the right subdirectory of
427 <filename>/var/log/journal</filename>
428 exists, it will be bind mounted
429 into the container. If the
430 subdirectory does not exist, no
431 linking is performed. Effectively,
432 booting a container once with
433 <literal>guest</literal> or
434 <literal>host</literal> will link the
435 journal persistently if further on
436 the default of <literal>auto</literal>
437 is used.</para></listitem>
441 <term><option>-j</option></term>
443 <listitem><para>Equivalent to
444 <option>--link-journal=guest</option>.</para></listitem>
448 <term><option>--read-only</option></term>
450 <listitem><para>Mount the root file
451 system read-only for the
452 container.</para></listitem>
456 <term><option>--bind=</option></term>
457 <term><option>--bind-ro=</option></term>
459 <listitem><para>Bind mount a file or
460 directory from the host into the
461 container. Either takes a path
462 argument -- in which case the
463 specified path will be mounted from
464 the host to the same path in the
465 container --, or a colon-separated
466 pair of paths -- in which case the
467 first specified path is the source in
468 the host, and the second path is the
469 destination in the container. The
470 <option>--bind-ro=</option> option
471 creates read-only bind
472 mounts.</para></listitem>
476 <term><option>--setenv=</option></term>
478 <listitem><para>Specifies an
479 environment variable assignment to
480 pass to the init process in the
481 container, in the format
482 <literal>NAME=VALUE</literal>. This
483 may be used to override the default
484 variables or to set additional
485 variables. This parameter may be used
486 more than once.</para></listitem>
490 <term><option>--share-system</option></term>
492 <listitem><para>Allows the container
493 to share certain system facilities
494 with the host. More specifically, this
495 turns off PID namespacing, UTS
496 namespacing and IPC namespacing, and
497 thus allows the guest to see and
498 interact more easily with processes
499 outside of the container. Note that
500 using this option makes it impossible
501 to start up a full Operating System in
502 the container, as an init system
503 cannot operate in this mode. It is
504 only useful to run specific programs
505 or applications this way, without
506 involving an init system in the
507 container. This option implies
508 <option>--register=no</option>. This
509 option may not be combined with
510 <option>--boot</option>.</para></listitem>
514 <term><option>--register=</option></term>
516 <listitem><para>Controls whether the
517 container is registered with
518 <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Takes
519 a boolean argument, defaults to
520 <literal>yes</literal>. This option
521 should be enabled when the container
522 runs a full Operating System (more
523 specifically: an init system), and is
524 useful to ensure that the container is
526 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
527 and shown by tools such as
528 <citerefentry><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>. If
529 the container does not run an init
530 system, it is recommended to set this
531 option to <literal>no</literal>. Note
532 that <option>--share-system</option>
534 <option>--register=no</option>.
539 <term><option>--keep-unit</option></term>
541 <listitem><para>Instead of creating a
542 transient scope unit to run the
543 container in, simply register the
544 service or scope unit
545 <command>systemd-nspawn</command> has
547 <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. This
549 <option>--register=no</option> is
550 used. This switch should be used if
551 <command>systemd-nspawn</command> is
552 invoked from within a service unit,
553 and the service unit's sole purpose
555 <command>systemd-nspawn</command>
556 container. This option is not
557 available if run from a user
558 session.</para></listitem>
562 <term><option>--personality=</option></term>
564 <listitem><para>Control the
565 architecture ("personality") reported
567 <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>
568 in the container. Currently, only
569 <literal>x86</literal> and
570 <literal>x86-64</literal> are
571 supported. This is useful when running
572 a 32bit container on a 64bit
573 host. If this setting is not used
574 the personality reported in the
575 container is the same as the one
577 host.</para></listitem>
581 <term><option>-q</option></term>
582 <term><option>--quiet</option></term>
584 <listitem><para>Turns off any status
585 output by the tool itself. When this
586 switch is used, the only output
587 from nspawn will be the console output
588 of the container OS itself.</para></listitem>
591 <xi:include href="standard-options.xml" xpointer="help" />
592 <xi:include href="standard-options.xml" xpointer="version" />
598 <title>Example 1</title>
600 <programlisting># yum -y --releasever=19 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal
601 # systemd-nspawn -bD /srv/mycontainer</programlisting>
603 <para>This installs a minimal Fedora distribution into
604 the directory <filename noindex='true'>/srv/mycontainer/</filename> and
605 then boots an OS in a namespace container in
610 <title>Example 2</title>
612 <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
613 # systemd-nspawn -D ~/debian-tree/</programlisting>
615 <para>This installs a minimal Debian unstable
616 distribution into the directory
617 <filename>~/debian-tree/</filename> and then spawns a
618 shell in a namespace container in it.</para>
622 <title>Example 3</title>
624 <programlisting># pacstrap -c -d ~/arch-tree/ base
625 # systemd-nspawn -bD ~/arch-tree/</programlisting>
627 <para>This installs a mimimal Arch Linux distribution into
628 the directory <filename>~/arch-tree/</filename> and then
629 boots an OS in a namespace container in it.</para>
633 <title>Example 4</title>
635 <programlisting># mv ~/arch-tree /var/lib/container/arch
636 # systemctl enable systemd-nspawn@arch.service
637 # systemctl start systemd-nspawn@arch.service</programlisting>
639 <para>This makes the Arch Linux container part of the
640 <filename>multi-user.target</filename> on the host.
645 <title>Example 5</title>
647 <programlisting># btrfs subvolume snapshot / /.tmp
648 # systemd-nspawn --private-network -D /.tmp -b</programlisting>
650 <para>This runs a copy of the host system in a
651 btrfs snapshot.</para>
655 <title>Example 6</title>
657 <programlisting># chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container
658 # 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>
660 <para>This runs a container with SELinux sandbox security contexts.</para>
664 <title>Exit status</title>
666 <para>The exit code of the program executed in the
667 container is returned.</para>
671 <title>See Also</title>
673 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
674 <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
675 <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
676 <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
677 <citerefentry><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
678 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
679 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>