]> git.ipfire.org Git - thirdparty/systemd.git/blob - man/systemd-nspawn.xml
projects / thirdparty / systemd.git / blob
? search:


5bddd895036d6be33a2e8c87e53216435b4953dd
[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
26 <refentryinfo>
27 <title>systemd-nspawn</title>
28 <productname>systemd</productname>
29
30 <authorgroup>
31 <author>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
36 </author>
37 </authorgroup>
38 </refentryinfo>
39
40 <refmeta>
41 <refentrytitle>systemd-nspawn</refentrytitle>
42 <manvolnum>1</manvolnum>
43 </refmeta>
44
45 <refnamediv>
46 <refname>systemd-nspawn</refname>
47 <refpurpose>Spawn a namespace container for debugging, testing and building</refpurpose>
48 </refnamediv>
49
50 <refsynopsisdiv>
51 <cmdsynopsis>
52 <command>systemd-nspawn</command>
53 <arg choice="opt" rep="repeat">OPTIONS</arg>
54 <arg choice="opt"><replaceable>COMMAND</replaceable>
55 <arg choice="opt" rep="repeat">ARGS</arg>
56 </arg>
57 </cmdsynopsis>
58 <cmdsynopsis>
59 <command>systemd-nspawn</command>
60 <arg choice="plain">-b</arg>
61 <arg choice="opt" rep="repeat">OPTIONS</arg>
62 <arg choice="opt" rep="repeat">ARGS</arg>
63 </cmdsynopsis>
64 </refsynopsisdiv>
65
66 <refsect1>
67 <title>Description</title>
68
69 <para><command>systemd-nspawn</command> may be used to
70 run a command or OS in a light-weight namespace
71 container. In many ways it is similar to
72 <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
73 but more powerful since it fully virtualizes the file
74 system hierarchy, as well as the process tree, the
75 various IPC subsystems and the host and domain
76 name.</para>
77
78 <para><command>systemd-nspawn</command> limits access
79 to various kernel interfaces in the container to
80 read-only, such as <filename>/sys</filename>,
81 <filename>/proc/sys</filename> or
82 <filename>/sys/fs/selinux</filename>. Network
83 interfaces and the system clock may not be changed
84 from within the container. Device nodes may not be
85 created. The host system cannot be rebooted and kernel
86 modules may not be loaded from within the
87 container.</para>
88
89 <para>Note that even though these security precautions
90 are taken <command>systemd-nspawn</command> is not
91 suitable for secure container setups. Many of the
92 security features may be circumvented and are hence
93 primarily useful to avoid accidental changes to the
94 host system from the container. The intended use of
95 this program is debugging and testing as well as
96 building of packages, distributions and software
97 involved with boot and systems management.</para>
98
99 <para>In contrast to
100 <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry> <command>systemd-nspawn</command>
101 may be used to boot full Linux-based operating systems
102 in a container.</para>
103
104 <para>Use a tool like
105 <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
106 <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
107 or
108 <citerefentry><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>
109 to set up an OS directory tree suitable as file system
110 hierarchy for <command>systemd-nspawn</command>
111 containers.</para>
112
113 <para>Note that <command>systemd-nspawn</command> will
114 mount file systems private to the container to
115 <filename>/dev</filename>,
116 <filename>/run</filename> and similar. These will
117 not be visible outside of the container, and their
118 contents will be lost when the container exits.</para>
119
120 <para>Note that running two
121 <command>systemd-nspawn</command> containers from the
122 same directory tree will not make processes in them
123 see each other. The PID namespace separation of the
124 two containers is complete and the containers will
125 share very few runtime objects except for the
126 underlying file system. Use
127 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
128 <command>login</command> command to request an
129 additional login prompt in a running container.</para>
130
131 <para><command>systemd-nspawn</command> implements the
132 <ulink
133 url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container
134 Interface</ulink> specification.</para>
135
136 <para>As a safety check
137 <command>systemd-nspawn</command> will verify the
138 existence of <filename>/etc/os-release</filename> in
139 the container tree before starting the container (see
140 <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>). It
141 might be necessary to add this file to the container
142 tree manually if the OS of the container is too old to
143 contain this file out-of-the-box.</para>
144 </refsect1>
145
146 <refsect1>
147 <title>Options</title>
148
149 <para>If option <option>-b</option> is specified, the
150 arguments are used as arguments for the init
151 binary. Otherwise, <replaceable>COMMAND</replaceable>
152 specifies the program to launch in the container, and
153 the remaining arguments are used as arguments for this
154 program. If <option>-b</option> is not used and no
155 arguments are specifed, a shell is launched in the
156 container.</para>
157
158 <para>The following options are understood:</para>
159
160 <variablelist>
161 <varlistentry>
162 <term><option>-h</option></term>
163 <term><option>--help</option></term>
164
165 <listitem><para>Prints a short help
166 text and exits.</para></listitem>
167 </varlistentry>
168
169 <varlistentry>
170 <term><option>--version</option></term>
171
172 <listitem><para>Prints a version string
173 and exits.</para></listitem>
174 </varlistentry>
175
176 <varlistentry>
177 <term><option>-q</option></term>
178 <term><option>--quiet</option></term>
179
180 <listitem><para>Turns off any status
181 output by the tool itself. When this
182 switch is used, then the only output
183 by nspawn will be the console output
184 of the container OS itself.</para></listitem>
185 </varlistentry>
186
187 <varlistentry>
188 <term><option>-D</option></term>
189 <term><option>--directory=</option></term>
190
191 <listitem><para>Directory to use as
192 file system root for the namespace
193 container. If omitted, the current
194 directory will be
195 used.</para></listitem>
196 </varlistentry>
197
198 <varlistentry>
199 <term><option>-b</option></term>
200 <term><option>--boot</option></term>
201
202 <listitem><para>Automatically search
203 for an init binary and invoke it
204 instead of a shell or a user supplied
205 program. If this option is used,
206 arguments specified on the command
207 line are used as arguments for the
208 init binary. This option may not be
209 combined with
210 <option>--share-system</option>.
211 </para></listitem>
212 </varlistentry>
213
214 <varlistentry>
215 <term><option>-u</option></term>
216 <term><option>--user=</option></term>
217
218 <listitem><para>Run the command
219 under specified user, create home
220 directory and cd into it. As rest
221 of systemd-nspawn, this is not
222 the security feature and limits
223 against accidental changes only.
224 </para></listitem>
225 </varlistentry>
226
227 <varlistentry>
228 <term><option>-M</option></term>
229 <term><option>--machine=</option></term>
230
231 <listitem><para>Sets the machine name
232 for this container. This name may be
233 used to identify this container on the
234 host, and is used to initialize the
235 container's hostname (which the
236 container can choose to override,
237 however). If not specified, the last
238 component of the root directory of the
239 container is used.</para></listitem>
240 </varlistentry>
241
242 <varlistentry>
243 <term><option>--uuid=</option></term>
244
245 <listitem><para>Set the specified UUID
246 for the container. The init system
247 will initialize
248 <filename>/etc/machine-id</filename>
249 from this if this file is not set yet.
250 </para></listitem>
251 </varlistentry>
252
253 <varlistentry>
254 <term><option>--slice=</option></term>
255
256 <listitem><para>Make the container
257 part of the specified slice, instead
258 of the default
259 <filename>machine.slice</filename>.</para>
260 </listitem>
261 </varlistentry>
262
263 <varlistentry>
264 <term><option>--private-network</option></term>
265
266 <listitem><para>Disconnect networking
267 of the container from the host. This
268 makes all network interfaces
269 unavailable in the container, with the
270 exception of the loopback device and
271 those specified with
272 <option>--network-interface=</option>
273 and configured with
274 <option>--network-veth</option>. If
275 this option is specified, the
276 CAP_NET_ADMIN capability will be added
277 to the set of capabilities the
278 container retains. The latter may be
279 disabled by using
280 <option>--drop-capability=</option>.</para></listitem>
281 </varlistentry>
282
283 <varlistentry>
284 <term><option>--network-interface=</option></term>
285
286 <listitem><para>Assign the specified
287 network interface to the
288 container. This will move the
289 specified interface from the calling
290 namespace and place it in the
291 container. When the container
292 terminates, it is moved back to the
293 host namespace. Note that
294 <option>--network-interface=</option>
295 implies
296 <option>--private-network</option>. This
297 option may be used more than once to
298 add multiple network interfaces to the
299 container.</para></listitem>
300 </varlistentry>
301
302 <varlistentry>
303 <term><option>--network-veth</option></term>
304
305 <listitem><para>Create a virtual
306 ethernet link between host and
307 container. The host side of the
308 ethernet link will be available as
309 network interface named after the
310 container's name (as specified with
311 <option>--machine=</option>), prefixed
312 with <literal>ve-</literal>. The
313 container side of the the ethernet
314 link will be named
315 <literal>host0</literal>. Note that
316 <option>--network-veth</option>
317 implies
318 <option>--private-network</option>.</para></listitem>
319 </varlistentry>
320
321 <varlistentry>
322 <term><option>--network-bridge=</option></term>
323
324 <listitem><para>Adds the host side of the
325 ethernet link created with
326 <option>--network-veth</option>
327 to the specified bridge. Note that
328 <option>--network-bridge</option>
329 implies
330 <option>--network-veth</option>.</para></listitem>
331 </varlistentry>
332
333 <varlistentry>
334 <term><option>-Z</option></term>
335 <term><option>--selinux-context=</option></term>
336
337 <listitem><para>Sets the SELinux
338 security context to be used to label
339 processes in the container.</para>
340 </listitem>
341 </varlistentry>
342
343 <varlistentry>
344 <term><option>-L</option></term>
345 <term><option>--selinux-apifs-context=</option></term>
346
347 <listitem><para>Sets the SELinux security
348 context to be used to label files in
349 the virtual API file systems in the
350 container.</para>
351 </listitem>
352 </varlistentry>
353
354 <varlistentry>
355 <term><option>--capability=</option></term>
356
357 <listitem><para>List one or more
358 additional capabilities to grant the
359 container. Takes a comma-separated
360 list of capability names, see
361 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
362 for more information. Note that the
363 following capabilities will be granted
364 in any way: CAP_CHOWN,
365 CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
366 CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
367 CAP_KILL, CAP_LEASE,
368 CAP_LINUX_IMMUTABLE,
369 CAP_NET_BIND_SERVICE,
370 CAP_NET_BROADCAST, CAP_NET_RAW,
371 CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP,
372 CAP_SETUID, CAP_SYS_ADMIN,
373 CAP_SYS_CHROOT, CAP_SYS_NICE,
374 CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG,
375 CAP_SYS_RESOURCE, CAP_SYS_BOOT,
376 CAP_AUDIT_WRITE,
377 CAP_AUDIT_CONTROL. Also CAP_NET_ADMIN
378 is retained if
379 <option>--private-network</option> is
380 specified. If the special value
381 <literal>all</literal> is passed, all
382 capabilities are
383 retained.</para></listitem>
384 </varlistentry>
385
386 <varlistentry>
387 <term><option>--drop-capability=</option></term>
388
389 <listitem><para>Specify one or more
390 additional capabilities to drop for
391 the container. This allows running the
392 container with fewer capabilities than
393 the default (see above).</para></listitem>
394 </varlistentry>
395
396 <varlistentry>
397 <term><option>--link-journal=</option></term>
398
399 <listitem><para>Control whether the
400 container's journal shall be made
401 visible to the host system. If enabled,
402 allows viewing the container's journal
403 files from the host (but not vice
404 versa). Takes one of
405 <literal>no</literal>,
406 <literal>host</literal>,
407 <literal>guest</literal>,
408 <literal>auto</literal>. If
409 <literal>no</literal>, the journal is
410 not linked. If <literal>host</literal>,
411 the journal files are stored on the
412 host file system (beneath
413 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
414 and the subdirectory is bind-mounted
415 into the container at the same
416 location. If <literal>guest</literal>,
417 the journal files are stored on the
418 guest file system (beneath
419 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
420 and the subdirectory is symlinked into the host
421 at the same location. If
422 <literal>auto</literal> (the default),
423 and the right subdirectory of
424 <filename>/var/log/journal</filename>
425 exists, it will be bind mounted
426 into the container. If the
427 subdirectory does not exist, no
428 linking is performed. Effectively,
429 booting a container once with
430 <literal>guest</literal> or
431 <literal>host</literal> will link the
432 journal persistently if further on
433 the default of <literal>auto</literal>
434 is used.</para></listitem>
435 </varlistentry>
436
437 <varlistentry>
438 <term><option>-j</option></term>
439
440 <listitem><para>Equivalent to
441 <option>--link-journal=guest</option>.</para></listitem>
442 </varlistentry>
443
444 <varlistentry>
445 <term><option>--read-only</option></term>
446
447 <listitem><para>Mount the root file
448 system read-only for the
449 container.</para></listitem>
450 </varlistentry>
451
452 <varlistentry>
453 <term><option>--bind=</option></term>
454 <term><option>--bind-ro=</option></term>
455
456 <listitem><para>Bind mount a file or
457 directory from the host into the
458 container. Either takes a path
459 argument -- in which case the
460 specified path will be mounted from
461 the host to the same path in the
462 container --, or a colon-separated
463 pair of paths -- in which case the
464 first specified path is the source in
465 the host, and the second path is the
466 destination in the container. The
467 <option>--bind-ro=</option> option
468 creates read-only bind
469 mount.</para></listitem>
470 </varlistentry>
471
472 <varlistentry>
473 <term><option>--setenv=</option></term>
474
475 <listitem><para>Specifies an
476 environment variable assignment to
477 pass to the init process in the
478 container, in the format
479 <literal>NAME=VALUE</literal>. This
480 may be used to override the default
481 variables or to set additional
482 variables. This parameter may be used
483 more than once.</para></listitem>
484 </varlistentry>
485
486 <varlistentry>
487 <term><option>--share-system</option></term>
488
489 <listitem><para>Allows the container
490 to share certain system facilities
491 with the host. More specifically, this
492 turns off PID namespacing, UTS
493 namespacing and IPC namespacing, and
494 thus allows the guest to see and
495 interact more easily with processes
496 outside of the container. Note that
497 using this option makes it impossible
498 to start up a full Operating System in
499 the container, as an init system
500 cannot operate in this mode. It is
501 only useful to run specific programs
502 or applications this way, without
503 involving an init system in the
504 container. This option implies
505 <option>--register=no</option>. This
506 option may not be combined with
507 <option>--boot</option>.</para></listitem>
508 </varlistentry>
509
510 <varlistentry>
511 <term><option>--register=</option></term>
512
513 <listitem><para>Controls whether the
514 container is registered with
515 <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Takes
516 a boolean argument, defaults to
517 <literal>yes</literal>. This option
518 should be enabled when the container
519 runs a full Operating System (more
520 specifically: an init system), and is
521 useful to ensure that the container is
522 accessible via
523 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
524 and shown by tools such as
525 <citerefentry><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>. If
526 the container does not run an init
527 system, it is recommended to set this
528 option to <literal>no</literal>. Note
529 that <option>--share-system</option>
530 implies
531 <option>--register=no</option>.
532 </para></listitem>
533 </varlistentry>
534
535 <varlistentry>
536 <term><option>--keep-unit</option></term>
537
538 <listitem><para>Instead of creating a
539 transient scope unit to run the
540 container in, simply register the
541 service or scope unit
542 <command>systemd-nspawn</command> has
543 been invoked in in
544 <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. This
545 has no effect if
546 <option>--register=no</option> is
547 used. This switch should be used if
548 <command>systemd-nspawn</command> is
549 invoked from within an a service unit,
550 and the service unit's sole purpose
551 is to run a single
552 <command>systemd-nspawn</command>
553 container. This option is not
554 available if run from a user
555 session.</para></listitem>
556 </varlistentry>
557
558 </variablelist>
559
560 </refsect1>
561
562 <refsect1>
563 <title>Example 1</title>
564
565 <programlisting># yum -y --releasever=19 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal
566 # systemd-nspawn -bD /srv/mycontainer</programlisting>
567
568 <para>This installs a minimal Fedora distribution into
569 the directory <filename noindex='true'>/srv/mycontainer/</filename> and
570 then boots an OS in a namespace container in
571 it.</para>
572 </refsect1>
573
574 <refsect1>
575 <title>Example 2</title>
576
577 <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
578 # systemd-nspawn -D ~/debian-tree/</programlisting>
579
580 <para>This installs a minimal Debian unstable
581 distribution into the directory
582 <filename>~/debian-tree/</filename> and then spawns a
583 shell in a namespace container in it.</para>
584 </refsect1>
585
586 <refsect1>
587 <title>Example 3</title>
588
589 <programlisting># pacstrap -c -d ~/arch-tree/ base
590 # systemd-nspawn -bD ~/arch-tree/</programlisting>
591
592 <para>This installs a mimimal Arch Linux distribution into
593 the directory <filename>~/arch-tree/</filename> and then
594 boots an OS in a namespace container in it.</para>
595 </refsect1>
596
597 <refsect1>
598 <title>Example 4</title>
599
600 <programlisting># mv ~/arch-tree /var/lib/container/arch
601 # systemctl enable systemd-nspawn@arch.service
602 # systemctl start systemd-nspawn@arch.service</programlisting>
603
604 <para>This makes the Arch Linux container part of the
605 <filename>multi-user.target</filename> on the host.
606 </para>
607 </refsect1>
608
609 <refsect1>
610 <title>Example 5</title>
611
612 <programlisting># btrfs subvolume snapshot / /.tmp
613 # systemd-nspawn --private-network -D /.tmp -b</programlisting>
614
615 <para>This runs a copy of the host system in a
616 btrfs snapshot.</para>
617 </refsect1>
618
619 <refsect1>
620 <title>Example 6</title>
621
622 <programlisting># chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container
623 # 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>
624
625 <para>This runs a container with SELinux sandbox security contexts.</para>
626 </refsect1>
627
628 <refsect1>
629 <title>Exit status</title>
630
631 <para>The exit code of the program executed in the
632 container is returned.</para>
633 </refsect1>
634
635 <refsect1>
636 <title>See Also</title>
637 <para>
638 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
639 <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
640 <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
641 <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
642 <citerefentry><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
643 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
644 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
645 </para>
646 </refsect1>
647
648 </refentry>
Unnamed repository; edit this file 'description' to name the repository.