chiark / gitweb /
Update french translation
[elogind.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 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
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 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>
104
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>,
108                 or
109                 <citerefentry project='arch'><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>/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>
146         </refsect1>
147
148         <refsect1>
149                 <title>Options</title>
150
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
158                 container.</para>
159
160                 <para>The following options are understood:</para>
161
162                 <variablelist>
163                         <varlistentry>
164                                 <term><option>-D</option></term>
165                                 <term><option>--directory=</option></term>
166
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>
174                         </varlistentry>
175
176                         <varlistentry>
177                                 <term><option>-i</option></term>
178                                 <term><option>--image=</option></term>
179
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>
201                         </varlistentry>
202
203                         <varlistentry>
204                                 <term><option>-b</option></term>
205                                 <term><option>--boot</option></term>
206
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
214                                 combined with
215                                 <option>--share-system</option>.
216                                 </para></listitem>
217                         </varlistentry>
218
219                         <varlistentry>
220                                 <term><option>-u</option></term>
221                                 <term><option>--user=</option></term>
222
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>
232                         </varlistentry>
233
234                         <varlistentry>
235                                 <term><option>-M</option></term>
236                                 <term><option>--machine=</option></term>
237
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>
247                         </varlistentry>
248
249                         <varlistentry>
250                                 <term><option>--uuid=</option></term>
251
252                                 <listitem><para>Set the specified UUID
253                                 for the container. The init system
254                                 will initialize
255                                 <filename>/etc/machine-id</filename>
256                                 from this if this file is not set yet.
257                                 </para></listitem>
258                         </varlistentry>
259
260                         <varlistentry>
261                                 <term><option>--slice=</option></term>
262
263                                 <listitem><para>Make the container
264                                 part of the specified slice, instead
265                                 of the default
266                                 <filename>machine.slice</filename>.</para>
267                                 </listitem>
268                         </varlistentry>
269
270                         <varlistentry>
271                                 <term><option>--private-network</option></term>
272
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
278                                 those specified with
279                                 <option>--network-interface=</option>
280                                 and configured with
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
286                                 disabled by using
287                                 <option>--drop-capability=</option>.</para></listitem>
288                         </varlistentry>
289
290                         <varlistentry>
291                                 <term><option>--network-interface=</option></term>
292
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>
302                                 implies
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>
307                         </varlistentry>
308
309                         <varlistentry>
310                                 <term><option>--network-macvlan=</option></term>
311
312                                 <listitem><para>Create a
313                                 <literal>macvlan</literal> interface
314                                 of the specified Ethernet network
315                                 interface and add it to the
316                                 container. A
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>
325                                 implies
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>
330                         </varlistentry>
331
332                         <varlistentry>
333                                 <term><option>--network-veth</option></term>
334
335                                 <listitem><para>Create a virtual
336                                 Ethernet link
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
345                                 link will be named
346                                 <literal>host0</literal>. Note that
347                                 <option>--network-veth</option>
348                                 implies
349                                 <option>--private-network</option>.</para></listitem>
350                         </varlistentry>
351
352                         <varlistentry>
353                                 <term><option>--network-bridge=</option></term>
354
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>
360                                 implies
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>
366                         </varlistentry>
367
368                         <varlistentry>
369                                 <term><option>-Z</option></term>
370                                 <term><option>--selinux-context=</option></term>
371
372                                 <listitem><para>Sets the SELinux
373                                 security context to be used to label
374                                 processes in the container.</para>
375                                 </listitem>
376                         </varlistentry>
377
378                         <varlistentry>
379                                 <term><option>-L</option></term>
380                                 <term><option>--selinux-apifs-context=</option></term>
381
382                                 <listitem><para>Sets the SELinux security
383                                 context to be used to label files in
384                                 the virtual API file systems in the
385                                 container.</para>
386                                 </listitem>
387                         </varlistentry>
388
389                         <varlistentry>
390                                 <term><option>--capability=</option></term>
391
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,
402                                 CAP_KILL, CAP_LEASE,
403                                 CAP_LINUX_IMMUTABLE,
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,
411                                 CAP_AUDIT_WRITE,
412                                 CAP_AUDIT_CONTROL. Also CAP_NET_ADMIN
413                                 is retained if
414                                 <option>--private-network</option> is
415                                 specified. If the special value
416                                 <literal>all</literal> is passed, all
417                                 capabilities are
418                                 retained.</para></listitem>
419                         </varlistentry>
420
421                         <varlistentry>
422                                 <term><option>--drop-capability=</option></term>
423
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>
429                         </varlistentry>
430
431                         <varlistentry>
432                                 <term><option>--link-journal=</option></term>
433
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
439                                 versa). Takes one of
440                                 <literal>no</literal>,
441                                 <literal>host</literal>,
442                                 <literal>guest</literal>,
443                                 <literal>auto</literal>. If
444                                 <literal>no</literal>, the journal is
445                                 not linked. If <literal>host</literal>,
446                                 the journal files are stored on the
447                                 host file system (beneath
448                                 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
449                                 and the subdirectory is bind-mounted
450                                 into the container at the same
451                                 location. If <literal>guest</literal>,
452                                 the journal files are stored on the
453                                 guest file system (beneath
454                                 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
455                                 and the subdirectory is symlinked into the host
456                                 at the same location. If
457                                 <literal>auto</literal> (the default),
458                                 and the right subdirectory of
459                                 <filename>/var/log/journal</filename>
460                                 exists, it will be bind mounted
461                                 into the container. If the
462                                 subdirectory does not exist, no
463                                 linking is performed. Effectively,
464                                 booting a container once with
465                                 <literal>guest</literal> or
466                                 <literal>host</literal> will link the
467                                 journal persistently if further on
468                                 the default of <literal>auto</literal>
469                                 is used.</para></listitem>
470                         </varlistentry>
471
472                         <varlistentry>
473                                 <term><option>-j</option></term>
474
475                                 <listitem><para>Equivalent to
476                                 <option>--link-journal=guest</option>.</para></listitem>
477                         </varlistentry>
478
479                         <varlistentry>
480                                 <term><option>--read-only</option></term>
481
482                                 <listitem><para>Mount the root file
483                                 system read-only for the
484                                 container.</para></listitem>
485                         </varlistentry>
486
487                         <varlistentry>
488                                 <term><option>--bind=</option></term>
489                                 <term><option>--bind-ro=</option></term>
490
491                                 <listitem><para>Bind mount a file or
492                                 directory from the host into the
493                                 container. Either takes a path
494                                 argument -- in which case the
495                                 specified path will be mounted from
496                                 the host to the same path in the
497                                 container --, or a colon-separated
498                                 pair of paths -- in which case the
499                                 first specified path is the source in
500                                 the host, and the second path is the
501                                 destination in the container. The
502                                 <option>--bind-ro=</option> option
503                                 creates read-only bind
504                                 mounts.</para></listitem>
505                         </varlistentry>
506
507                         <varlistentry>
508                                 <term><option>--tmpfs=</option></term>
509
510                                 <listitem><para>Mount a tmpfs file
511                                 system into the container. Takes a
512                                 single absolute path argument that
513                                 specifies where to mount the tmpfs
514                                 instance to (in which case the
515                                 directory access mode will be chosen
516                                 as 0755, owned by root/root), or
517                                 optionally a colon-separated pair of
518                                 path and mount option string, that is
519                                 used for mounting (in which case the
520                                 kernel default for access mode and
521                                 owner will be chosen, unless otherwise
522                                 specified). This option is
523                                 particularly useful for mounting
524                                 directories such as
525                                 <filename>/var</filename> as tmpfs, to
526                                 allow state-less systems, in
527                                 particular when combined with
528                                 <option>--read-only</option>.</para></listitem>
529                         </varlistentry>
530
531                         <varlistentry>
532                                 <term><option>--setenv=</option></term>
533
534                                 <listitem><para>Specifies an
535                                 environment variable assignment to
536                                 pass to the init process in the
537                                 container, in the format
538                                 <literal>NAME=VALUE</literal>. This
539                                 may be used to override the default
540                                 variables or to set additional
541                                 variables. This parameter may be used
542                                 more than once.</para></listitem>
543                         </varlistentry>
544
545                         <varlistentry>
546                                 <term><option>--share-system</option></term>
547
548                                 <listitem><para>Allows the container
549                                 to share certain system facilities
550                                 with the host. More specifically, this
551                                 turns off PID namespacing, UTS
552                                 namespacing and IPC namespacing, and
553                                 thus allows the guest to see and
554                                 interact more easily with processes
555                                 outside of the container. Note that
556                                 using this option makes it impossible
557                                 to start up a full Operating System in
558                                 the container, as an init system
559                                 cannot operate in this mode. It is
560                                 only useful to run specific programs
561                                 or applications this way, without
562                                 involving an init system in the
563                                 container. This option implies
564                                 <option>--register=no</option>. This
565                                 option may not be combined with
566                                 <option>--boot</option>.</para></listitem>
567                         </varlistentry>
568
569                         <varlistentry>
570                                 <term><option>--register=</option></term>
571
572                                 <listitem><para>Controls whether the
573                                 container is registered with
574                                 <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Takes
575                                 a boolean argument, defaults to
576                                 <literal>yes</literal>. This option
577                                 should be enabled when the container
578                                 runs a full Operating System (more
579                                 specifically: an init system), and is
580                                 useful to ensure that the container is
581                                 accessible via
582                                 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
583                                 and shown by tools such as
584                                 <citerefentry project='man-pages'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>. If
585                                 the container does not run an init
586                                 system, it is recommended to set this
587                                 option to <literal>no</literal>. Note
588                                 that <option>--share-system</option>
589                                 implies
590                                 <option>--register=no</option>.
591                                 </para></listitem>
592                         </varlistentry>
593
594                         <varlistentry>
595                                 <term><option>--keep-unit</option></term>
596
597                                 <listitem><para>Instead of creating a
598                                 transient scope unit to run the
599                                 container in, simply register the
600                                 service or scope unit
601                                 <command>systemd-nspawn</command> has
602                                 been invoked in with
603                                 <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. This
604                                 has no effect if
605                                 <option>--register=no</option> is
606                                 used. This switch should be used if
607                                 <command>systemd-nspawn</command> is
608                                 invoked from within a service unit,
609                                 and the service unit's sole purpose
610                                 is to run a single
611                                 <command>systemd-nspawn</command>
612                                 container. This option is not
613                                 available if run from a user
614                                 session.</para></listitem>
615                         </varlistentry>
616
617                         <varlistentry>
618                                 <term><option>--personality=</option></term>
619
620                                 <listitem><para>Control the
621                                 architecture ("personality") reported
622                                 by
623                                 <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>
624                                 in the container. Currently, only
625                                 <literal>x86</literal> and
626                                 <literal>x86-64</literal> are
627                                 supported. This is useful when running
628                                 a 32-bit container on a 64-bit
629                                 host. If this setting is not used,
630                                 the personality reported in the
631                                 container is the same as the one
632                                 reported on the
633                                 host.</para></listitem>
634                         </varlistentry>
635
636                         <varlistentry>
637                                 <term><option>-q</option></term>
638                                 <term><option>--quiet</option></term>
639
640                                 <listitem><para>Turns off any status
641                                 output by the tool itself. When this
642                                 switch is used, the only output
643                                 from nspawn will be the console output
644                                 of the container OS itself.</para></listitem>
645                         </varlistentry>
646
647                         <varlistentry>
648                                 <term><option>--volatile</option><replaceable>=MODE</replaceable></term>
649
650                                 <listitem><para>Boots the container in
651                                 volatile (ephemeral) mode. When no
652                                 mode parameter is passed or when mode
653                                 is specified as <literal>yes</literal>
654                                 full volatile mode is enabled. This
655                                 means the root directory is mounted as
656                                 mostly unpopulated
657                                 <literal>tmpfs</literal> instance, and
658                                 <filename>/usr</filename> from the OS
659                                 tree is mounted into it, read-only
660                                 (the system thus starts up with
661                                 read-only OS resources, but pristine
662                                 state and configuration, any changes
663                                 to the either are lost on
664                                 shutdown). When the mode parameter is
665                                 specified as <literal>state</literal>
666                                 the OS tree is mounted read-only, but
667                                 <filename>/var</filename> is mounted
668                                 as <literal>tmpfs</literal> instance
669                                 into it (the system thus starts up
670                                 with read-only OS resources and
671                                 configuration, but prestine state, any
672                                 changes to the latter are lost on
673                                 shutdown). When the mode parameter is
674                                 specified as <literal>no</literal>
675                                 (the default) the whole OS tree is made
676                                 available writable.</para>
677
678                                 <para>Note that setting this to
679                                 <literal>yes</literal> or
680                                 <literal>state</literal> will only
681                                 work correctly with operating systems
682                                 in the container that can boot up with
683                                 only <filename>/usr</filename>
684                                 mounted, and are able to populate
685                                 <filename>/var</filename>
686                                 automatically, as
687                                 needed.</para></listitem>
688                         </varlistentry>
689
690                         <xi:include href="standard-options.xml" xpointer="help" />
691                         <xi:include href="standard-options.xml" xpointer="version" />
692                 </variablelist>
693
694         </refsect1>
695
696         <refsect1>
697                 <title>Example 1</title>
698
699                 <programlisting># yum -y --releasever=19 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal
700 # systemd-nspawn -bD /srv/mycontainer</programlisting>
701
702                 <para>This installs a minimal Fedora distribution into
703                 the directory <filename noindex='true'>/srv/mycontainer/</filename> and
704                 then boots an OS in a namespace container in
705                 it.</para>
706         </refsect1>
707
708         <refsect1>
709                 <title>Example 2</title>
710
711                 <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
712 # systemd-nspawn -D ~/debian-tree/</programlisting>
713
714                 <para>This installs a minimal Debian unstable
715                 distribution into the directory
716                 <filename>~/debian-tree/</filename> and then spawns a
717                 shell in a namespace container in it.</para>
718         </refsect1>
719
720         <refsect1>
721                 <title>Example 3</title>
722
723                 <programlisting># pacstrap -c -d ~/arch-tree/ base
724 # systemd-nspawn -bD ~/arch-tree/</programlisting>
725
726                 <para>This installs a mimimal Arch Linux distribution into
727                 the directory <filename>~/arch-tree/</filename> and then
728                 boots an OS in a namespace container in it.</para>
729         </refsect1>
730
731         <refsect1>
732                 <title>Example 4</title>
733
734                 <programlisting># mv ~/arch-tree /var/lib/container/arch
735 # systemctl enable systemd-nspawn@arch.service
736 # systemctl start systemd-nspawn@arch.service</programlisting>
737
738                 <para>This makes the Arch Linux container part of the
739                 <filename>multi-user.target</filename> on the host.
740                 </para>
741         </refsect1>
742
743         <refsect1>
744                 <title>Example 5</title>
745
746                 <programlisting># btrfs subvolume snapshot / /.tmp
747 # systemd-nspawn --private-network -D /.tmp -b</programlisting>
748
749                 <para>This runs a copy of the host system in a
750                 btrfs snapshot.</para>
751         </refsect1>
752
753         <refsect1>
754                 <title>Example 6</title>
755
756                 <programlisting># chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container
757 # 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>
758
759                 <para>This runs a container with SELinux sandbox security contexts.</para>
760         </refsect1>
761
762         <refsect1>
763                 <title>Exit status</title>
764
765                 <para>The exit code of the program executed in the
766                 container is returned.</para>
767         </refsect1>
768
769         <refsect1>
770                 <title>See Also</title>
771                 <para>
772                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
773                         <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
774                         <citerefentry project='die-net'><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
775                         <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
776                         <citerefentry project='arch'><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
777                         <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
778                         <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
779                 </para>
780         </refsect1>
781
782 </refentry>