]> git.ipfire.org Git - thirdparty/systemd.git/blob - man/systemd-nspawn.xml
projects / thirdparty / systemd.git / blob
? search:
summary | shortlog | log | commit | commitdiff | tree
history | raw | HEAD
condense assignment and path_kill_slashes calls
[thirdparty/systemd.git] / man / systemd-nspawn.xml
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">
4
5 <!--
6 This file is part of systemd.
7
8 Copyright 2010 Lennart Poettering
9
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.
14
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.
19
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/>.
22 -->
23
24 <refentry id="systemd-nspawn"
25 xmlns:xi="http://www.w3.org/2001/XInclude">
26
27 <refentryinfo>
28 <title>systemd-nspawn</title>
29 <productname>systemd</productname>
30
31 <authorgroup>
32 <author>
33 <contrib>Developer</contrib>
34 <firstname>Lennart</firstname>
35 <surname>Poettering</surname>
36 <email>lennart@poettering.net</email>
37 </author>
38 </authorgroup>
39 </refentryinfo>
40
41 <refmeta>
42 <refentrytitle>systemd-nspawn</refentrytitle>
43 <manvolnum>1</manvolnum>
44 </refmeta>
45
46 <refnamediv>
47 <refname>systemd-nspawn</refname>
48 <refpurpose>Spawn a namespace container for debugging, testing and building</refpurpose>
49 </refnamediv>
50
51 <refsynopsisdiv>
52 <cmdsynopsis>
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>
57 </arg>
58 </cmdsynopsis>
59 <cmdsynopsis>
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>
64 </cmdsynopsis>
65 </refsynopsisdiv>
66
67 <refsect1>
68 <title>Description</title>
69
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
77 name.</para>
78
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
88 container.</para>
89
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>
99
100 <para>In contrast to
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>
104
105 <para>Use a tool like
106 <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
107 <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
108 or
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>
112 containers.</para>
113
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>
120
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>
131
132 <para><command>systemd-nspawn</command> implements the
133 <ulink
134 url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container
135 Interface</ulink> specification.</para>
136
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>
145 </refsect1>
146
147 <refsect1>
148 <title>Options</title>
149
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
157 container.</para>
158
159 <para>The following options are understood:</para>
160
161 <variablelist>
162 <varlistentry>
163 <term><option>-D</option></term>
164 <term><option>--directory=</option></term>
165
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>
173 </varlistentry>
174
175 <varlistentry>
176 <term><option>-i</option></term>
177 <term><option>--image=</option></term>
178
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>
200 </varlistentry>
201
202 <varlistentry>
203 <term><option>-b</option></term>
204 <term><option>--boot</option></term>
205
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
213 combined with
214 <option>--share-system</option>.
215 </para></listitem>
216 </varlistentry>
217
218 <varlistentry>
219 <term><option>-u</option></term>
220 <term><option>--user=</option></term>
221
222 <listitem><para>After transitioning
223 into the container, change to the
224 specified user defined in the
225 container's user database. Like all
226 other systemd-nspawn features, this is
227 not a security feature and provides
228 protection against accidental
229 destructive operations
230 only.</para></listitem>
231 </varlistentry>
232
233 <varlistentry>
234 <term><option>-M</option></term>
235 <term><option>--machine=</option></term>
236
237 <listitem><para>Sets the machine name
238 for this container. This name may be
239 used to identify this container on the
240 host, and is used to initialize the
241 container's hostname (which the
242 container can choose to override,
243 however). If not specified, the last
244 component of the root directory of the
245 container is used.</para></listitem>
246 </varlistentry>
247
248 <varlistentry>
249 <term><option>--uuid=</option></term>
250
251 <listitem><para>Set the specified UUID
252 for the container. The init system
253 will initialize
254 <filename>/etc/machine-id</filename>
255 from this if this file is not set yet.
256 </para></listitem>
257 </varlistentry>
258
259 <varlistentry>
260 <term><option>--slice=</option></term>
261
262 <listitem><para>Make the container
263 part of the specified slice, instead
264 of the default
265 <filename>machine.slice</filename>.</para>
266 </listitem>
267 </varlistentry>
268
269 <varlistentry>
270 <term><option>--private-network</option></term>
271
272 <listitem><para>Disconnect networking
273 of the container from the host. This
274 makes all network interfaces
275 unavailable in the container, with the
276 exception of the loopback device and
277 those specified with
278 <option>--network-interface=</option>
279 and configured with
280 <option>--network-veth</option>. If
281 this option is specified, the
282 CAP_NET_ADMIN capability will be added
283 to the set of capabilities the
284 container retains. The latter may be
285 disabled by using
286 <option>--drop-capability=</option>.</para></listitem>
287 </varlistentry>
288
289 <varlistentry>
290 <term><option>--network-interface=</option></term>
291
292 <listitem><para>Assign the specified
293 network interface to the
294 container. This will remove the
295 specified interface from the calling
296 namespace and place it in the
297 container. When the container
298 terminates, it is moved back to the
299 host namespace. Note that
300 <option>--network-interface=</option>
301 implies
302 <option>--private-network</option>. This
303 option may be used more than once to
304 add multiple network interfaces to the
305 container.</para></listitem>
306 </varlistentry>
307
308 <varlistentry>
309 <term><option>--network-macvlan=</option></term>
310
311 <listitem><para>Create a
312 <literal>macvlan</literal> interface
313 of the specified Ethernet network
314 interface and add it to the
315 container. A
316 <literal>macvlan</literal> interface
317 is a virtual interface that adds a
318 second MAC address to an existing
319 physical Ethernet link. The interface
320 in the container will be named after
321 the interface on the host, prefixed
322 with <literal>mv-</literal>. Note that
323 <option>--network-macvlan=</option>
324 implies
325 <option>--private-network</option>. This
326 option may be used more than once to
327 add multiple network interfaces to the
328 container.</para></listitem>
329 </varlistentry>
330
331 <varlistentry>
332 <term><option>--network-veth</option></term>
333
334 <listitem><para>Create a virtual
335 Ethernet link
336 (<literal>veth</literal>) between host
337 and container. The host side of the
338 Ethernet link will be available as a
339 network interface named after the
340 container's name (as specified with
341 <option>--machine=</option>), prefixed
342 with <literal>ve-</literal>. The
343 container side of the the Ethernet
344 link will be named
345 <literal>host0</literal>. Note that
346 <option>--network-veth</option>
347 implies
348 <option>--private-network</option>.</para></listitem>
349 </varlistentry>
350
351 <varlistentry>
352 <term><option>--network-bridge=</option></term>
353
354 <listitem><para>Adds the host side of
355 the Ethernet link created with
356 <option>--network-veth</option> to the
357 specified bridge. Note that
358 <option>--network-bridge=</option>
359 implies
360 <option>--network-veth</option>. If
361 this option is used the host side of
362 the Ethernet link will use the
363 <literal>vb-</literal> prefix instead
364 of <literal>ve-</literal>.</para></listitem>
365 </varlistentry>
366
367 <varlistentry>
368 <term><option>-Z</option></term>
369 <term><option>--selinux-context=</option></term>
370
371 <listitem><para>Sets the SELinux
372 security context to be used to label
373 processes in the container.</para>
374 </listitem>
375 </varlistentry>
376
377 <varlistentry>
378 <term><option>-L</option></term>
379 <term><option>--selinux-apifs-context=</option></term>
380
381 <listitem><para>Sets the SELinux security
382 context to be used to label files in
383 the virtual API file systems in the
384 container.</para>
385 </listitem>
386 </varlistentry>
387
388 <varlistentry>
389 <term><option>--capability=</option></term>
390
391 <listitem><para>List one or more
392 additional capabilities to grant the
393 container. Takes a comma-separated
394 list of capability names, see
395 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
396 for more information. Note that the
397 following capabilities will be granted
398 in any way: CAP_CHOWN,
399 CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
400 CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
401 CAP_KILL, CAP_LEASE,
402 CAP_LINUX_IMMUTABLE,
403 CAP_NET_BIND_SERVICE,
404 CAP_NET_BROADCAST, CAP_NET_RAW,
405 CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP,
406 CAP_SETUID, CAP_SYS_ADMIN,
407 CAP_SYS_CHROOT, CAP_SYS_NICE,
408 CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG,
409 CAP_SYS_RESOURCE, CAP_SYS_BOOT,
410 CAP_AUDIT_WRITE,
411 CAP_AUDIT_CONTROL. Also CAP_NET_ADMIN
412 is retained if
413 <option>--private-network</option> is
414 specified. If the special value
415 <literal>all</literal> is passed, all
416 capabilities are
417 retained.</para></listitem>
418 </varlistentry>
419
420 <varlistentry>
421 <term><option>--drop-capability=</option></term>
422
423 <listitem><para>Specify one or more
424 additional capabilities to drop for
425 the container. This allows running the
426 container with fewer capabilities than
427 the default (see above).</para></listitem>
428 </varlistentry>
429
430 <varlistentry>
431 <term><option>--link-journal=</option></term>
432
433 <listitem><para>Control whether the
434 container's journal shall be made
435 visible to the host system. If enabled,
436 allows viewing the container's journal
437 files from the host (but not vice
438 versa). Takes one of
439 <literal>no</literal>,
440 <literal>host</literal>,
441 <literal>guest</literal>,
442 <literal>auto</literal>. If
443 <literal>no</literal>, the journal is
444 not linked. If <literal>host</literal>,
445 the journal files are stored on the
446 host file system (beneath
447 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
448 and the subdirectory is bind-mounted
449 into the container at the same
450 location. If <literal>guest</literal>,
451 the journal files are stored on the
452 guest file system (beneath
453 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
454 and the subdirectory is symlinked into the host
455 at the same location. If
456 <literal>auto</literal> (the default),
457 and the right subdirectory of
458 <filename>/var/log/journal</filename>
459 exists, it will be bind mounted
460 into the container. If the
461 subdirectory does not exist, no
462 linking is performed. Effectively,
463 booting a container once with
464 <literal>guest</literal> or
465 <literal>host</literal> will link the
466 journal persistently if further on
467 the default of <literal>auto</literal>
468 is used.</para></listitem>
469 </varlistentry>
470
471 <varlistentry>
472 <term><option>-j</option></term>
473
474 <listitem><para>Equivalent to
475 <option>--link-journal=guest</option>.</para></listitem>
476 </varlistentry>
477
478 <varlistentry>
479 <term><option>--read-only</option></term>
480
481 <listitem><para>Mount the root file
482 system read-only for the
483 container.</para></listitem>
484 </varlistentry>
485
486 <varlistentry>
487 <term><option>--bind=</option></term>
488 <term><option>--bind-ro=</option></term>
489
490 <listitem><para>Bind mount a file or
491 directory from the host into the
492 container. Either takes a path
493 argument -- in which case the
494 specified path will be mounted from
495 the host to the same path in the
496 container --, or a colon-separated
497 pair of paths -- in which case the
498 first specified path is the source in
499 the host, and the second path is the
500 destination in the container. The
501 <option>--bind-ro=</option> option
502 creates read-only bind
503 mounts.</para></listitem>
504 </varlistentry>
505
506 <varlistentry>
507 <term><option>--setenv=</option></term>
508
509 <listitem><para>Specifies an
510 environment variable assignment to
511 pass to the init process in the
512 container, in the format
513 <literal>NAME=VALUE</literal>. This
514 may be used to override the default
515 variables or to set additional
516 variables. This parameter may be used
517 more than once.</para></listitem>
518 </varlistentry>
519
520 <varlistentry>
521 <term><option>--share-system</option></term>
522
523 <listitem><para>Allows the container
524 to share certain system facilities
525 with the host. More specifically, this
526 turns off PID namespacing, UTS
527 namespacing and IPC namespacing, and
528 thus allows the guest to see and
529 interact more easily with processes
530 outside of the container. Note that
531 using this option makes it impossible
532 to start up a full Operating System in
533 the container, as an init system
534 cannot operate in this mode. It is
535 only useful to run specific programs
536 or applications this way, without
537 involving an init system in the
538 container. This option implies
539 <option>--register=no</option>. This
540 option may not be combined with
541 <option>--boot</option>.</para></listitem>
542 </varlistentry>
543
544 <varlistentry>
545 <term><option>--register=</option></term>
546
547 <listitem><para>Controls whether the
548 container is registered with
549 <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Takes
550 a boolean argument, defaults to
551 <literal>yes</literal>. This option
552 should be enabled when the container
553 runs a full Operating System (more
554 specifically: an init system), and is
555 useful to ensure that the container is
556 accessible via
557 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
558 and shown by tools such as
559 <citerefentry><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>. If
560 the container does not run an init
561 system, it is recommended to set this
562 option to <literal>no</literal>. Note
563 that <option>--share-system</option>
564 implies
565 <option>--register=no</option>.
566 </para></listitem>
567 </varlistentry>
568
569 <varlistentry>
570 <term><option>--keep-unit</option></term>
571
572 <listitem><para>Instead of creating a
573 transient scope unit to run the
574 container in, simply register the
575 service or scope unit
576 <command>systemd-nspawn</command> has
577 been invoked in with
578 <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. This
579 has no effect if
580 <option>--register=no</option> is
581 used. This switch should be used if
582 <command>systemd-nspawn</command> is
583 invoked from within a service unit,
584 and the service unit's sole purpose
585 is to run a single
586 <command>systemd-nspawn</command>
587 container. This option is not
588 available if run from a user
589 session.</para></listitem>
590 </varlistentry>
591
592 <varlistentry>
593 <term><option>--personality=</option></term>
594
595 <listitem><para>Control the
596 architecture ("personality") reported
597 by
598 <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>
599 in the container. Currently, only
600 <literal>x86</literal> and
601 <literal>x86-64</literal> are
602 supported. This is useful when running
603 a 32bit container on a 64bit
604 host. If this setting is not used
605 the personality reported in the
606 container is the same as the one
607 reported on the
608 host.</para></listitem>
609 </varlistentry>
610
611 <varlistentry>
612 <term><option>-q</option></term>
613 <term><option>--quiet</option></term>
614
615 <listitem><para>Turns off any status
616 output by the tool itself. When this
617 switch is used, the only output
618 from nspawn will be the console output
619 of the container OS itself.</para></listitem>
620 </varlistentry>
621
622 <xi:include href="standard-options.xml" xpointer="help" />
623 <xi:include href="standard-options.xml" xpointer="version" />
624 </variablelist>
625
626 </refsect1>
627
628 <refsect1>
629 <title>Example 1</title>
630
631 <programlisting># yum -y --releasever=19 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal
632 # systemd-nspawn -bD /srv/mycontainer</programlisting>
633
634 <para>This installs a minimal Fedora distribution into
635 the directory <filename noindex='true'>/srv/mycontainer/</filename> and
636 then boots an OS in a namespace container in
637 it.</para>
638 </refsect1>
639
640 <refsect1>
641 <title>Example 2</title>
642
643 <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
644 # systemd-nspawn -D ~/debian-tree/</programlisting>
645
646 <para>This installs a minimal Debian unstable
647 distribution into the directory
648 <filename>~/debian-tree/</filename> and then spawns a
649 shell in a namespace container in it.</para>
650 </refsect1>
651
652 <refsect1>
653 <title>Example 3</title>
654
655 <programlisting># pacstrap -c -d ~/arch-tree/ base
656 # systemd-nspawn -bD ~/arch-tree/</programlisting>
657
658 <para>This installs a mimimal Arch Linux distribution into
659 the directory <filename>~/arch-tree/</filename> and then
660 boots an OS in a namespace container in it.</para>
661 </refsect1>
662
663 <refsect1>
664 <title>Example 4</title>
665
666 <programlisting># mv ~/arch-tree /var/lib/container/arch
667 # systemctl enable systemd-nspawn@arch.service
668 # systemctl start systemd-nspawn@arch.service</programlisting>
669
670 <para>This makes the Arch Linux container part of the
671 <filename>multi-user.target</filename> on the host.
672 </para>
673 </refsect1>
674
675 <refsect1>
676 <title>Example 5</title>
677
678 <programlisting># btrfs subvolume snapshot / /.tmp
679 # systemd-nspawn --private-network -D /.tmp -b</programlisting>
680
681 <para>This runs a copy of the host system in a
682 btrfs snapshot.</para>
683 </refsect1>
684
685 <refsect1>
686 <title>Example 6</title>
687
688 <programlisting># chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container
689 # 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>
690
691 <para>This runs a container with SELinux sandbox security contexts.</para>
692 </refsect1>
693
694 <refsect1>
695 <title>Exit status</title>
696
697 <para>The exit code of the program executed in the
698 container is returned.</para>
699 </refsect1>
700
701 <refsect1>
702 <title>See Also</title>
703 <para>
704 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
705 <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
706 <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
707 <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
708 <citerefentry><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
709 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
710 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
711 </para>
712 </refsect1>
713
714 </refentry>
Unnamed repository; edit this file 'description' to name the repository.