chiark / gitweb /
nspawn,machined: change default container image location from /var/lib/container...
[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='archlinux'><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.</para>
169
170                                 <para>If neither
171                                 <option>--directory=</option>, nor
172                                 <option>--image=</option> is specified
173                                 the directory is determined as
174                                 <filename>/var/lib/machines/</filename>
175                                 suffixed by the machine name as
176                                 specified with
177                                 <option>--machine=</option>. If
178                                 neither <option>--directory=</option>,
179                                 <option>--image=</option>, nor
180                                 <option>--machine=</option> are
181                                 specified, the current directory will
182                                 be used. May not be specified together
183                                 with
184                                 <option>--image=</option>.</para></listitem>
185                         </varlistentry>
186
187                         <varlistentry>
188                                 <term><option>--template=</option></term>
189
190                                 <listitem><para>Directory or
191                                 <literal>btrfs</literal> subvolume to
192                                 use as template for the container's
193                                 root directory. If this is specified
194                                 and the container's root directory (as
195                                 configured by
196                                 <option>--directory=</option>) does
197                                 not yet exist it is created as
198                                 <literal>btrfs</literal> subvolume and
199                                 populated from this template
200                                 tree. Ideally, the specified template
201                                 path refers to the root of a
202                                 <literal>btrfs</literal> subvolume, in
203                                 which case a simple copy-on-write
204                                 snapshot is taken, and populating the
205                                 root directory is instant. If the
206                                 specified template path does not refer
207                                 to the root of a
208                                 <literal>btrfs</literal> subvolume (or
209                                 not even to a <literal>btrfs</literal>
210                                 file system at all), the tree is
211                                 copied, which can be substantially
212                                 more time-consuming. Note that if this
213                                 option is used the container's root
214                                 directory (in contrast to the template
215                                 directory!) must be located on a
216                                 <literal>btrfs</literal> file system,
217                                 so that the <literal>btrfs</literal>
218                                 subvolume may be created. May not be
219                                 specified together with
220                                 <option>--image=</option> or
221                                 <option>--ephemeral</option>.</para></listitem>
222                         </varlistentry>
223
224                         <varlistentry>
225                                 <term><option>-x</option></term>
226                                 <term><option>--ephemeral</option></term>
227
228                                 <listitem><para>If specified, the
229                                 container is run with a temporary
230                                 <literal>btrfs</literal> snapshot of
231                                 its root directory (as configured with
232                                 <option>--directory=</option>), that
233                                 is removed immediately when the
234                                 container terminates. This option is
235                                 only supported if the root file system
236                                 is <literal>btrfs</literal>. May not
237                                 be specified together with
238                                 <option>--image=</option> or
239                                 <option>--template=</option>.</para></listitem>
240                         </varlistentry>
241
242                         <varlistentry>
243                                 <term><option>-i</option></term>
244                                 <term><option>--image=</option></term>
245
246                                 <listitem><para>Disk image to mount
247                                 the root directory for the container
248                                 from. Takes a path to a regular file
249                                 or to a block device node. The file or
250                                 block device must contain either an
251                                 MBR partition table with a single
252                                 partition of type 0x83 that is marked
253                                 bootable, or a GUID partition table
254                                 with a root partition which is mounted
255                                 as the root directory of the
256                                 container. Optionally, GPT images may
257                                 contain a home and/or a server data
258                                 partition which are mounted to the
259                                 appropriate places in the
260                                 container. All these partitions must
261                                 be identified by the partition types
262                                 defined by the <ulink
263                                 url="http://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/">Discoverable
264                                 Partitions Specification</ulink>. Any
265                                 other partitions, such as foreign
266                                 partitions, swap partitions or EFI
267                                 system partitions are not mounted. May
268                                 not be specified together with
269                                 <option>--directory=</option>,
270                                 <option>--template=</option> or
271                                 <option>--ephemeral</option>.</para></listitem>
272                         </varlistentry>
273
274                         <varlistentry>
275                                 <term><option>-b</option></term>
276                                 <term><option>--boot</option></term>
277
278                                 <listitem><para>Automatically search
279                                 for an init binary and invoke it
280                                 instead of a shell or a user supplied
281                                 program. If this option is used,
282                                 arguments specified on the command
283                                 line are used as arguments for the
284                                 init binary. This option may not be
285                                 combined with
286                                 <option>--share-system</option>.
287                                 </para></listitem>
288                         </varlistentry>
289
290                         <varlistentry>
291                                 <term><option>-u</option></term>
292                                 <term><option>--user=</option></term>
293
294                                 <listitem><para>After transitioning
295                                 into the container, change to the
296                                 specified user-defined in the
297                                 container's user database. Like all
298                                 other systemd-nspawn features, this is
299                                 not a security feature and provides
300                                 protection against accidental
301                                 destructive operations
302                                 only.</para></listitem>
303                         </varlistentry>
304
305                         <varlistentry>
306                                 <term><option>-M</option></term>
307                                 <term><option>--machine=</option></term>
308
309                                 <listitem><para>Sets the machine name
310                                 for this container. This name may be
311                                 used to identify this container during
312                                 its runtime (for example in tools like
313                                 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
314                                 and similar), and is used to
315                                 initialize the container's hostname
316                                 (which the container can choose to
317                                 override, however). If not specified,
318                                 the last component of the root
319                                 directory path of the container is
320                                 used, possibly suffixed with a random
321                                 identifier in case
322                                 <option>--ephemeral</option> mode is
323                                 selected. If the root directory
324                                 selected is the host's root directory
325                                 the host's hostname is used as default
326                                 instead.</para></listitem>
327                         </varlistentry>
328
329                         <varlistentry>
330                                 <term><option>--uuid=</option></term>
331
332                                 <listitem><para>Set the specified UUID
333                                 for the container. The init system
334                                 will initialize
335                                 <filename>/etc/machine-id</filename>
336                                 from this if this file is not set yet.
337                                 </para></listitem>
338                         </varlistentry>
339
340                         <varlistentry>
341                                 <term><option>--slice=</option></term>
342
343                                 <listitem><para>Make the container
344                                 part of the specified slice, instead
345                                 of the default
346                                 <filename>machine.slice</filename>.</para>
347                                 </listitem>
348                         </varlistentry>
349
350                         <varlistentry>
351                                 <term><option>--private-network</option></term>
352
353                                 <listitem><para>Disconnect networking
354                                 of the container from the host. This
355                                 makes all network interfaces
356                                 unavailable in the container, with the
357                                 exception of the loopback device and
358                                 those specified with
359                                 <option>--network-interface=</option>
360                                 and configured with
361                                 <option>--network-veth</option>. If
362                                 this option is specified, the
363                                 CAP_NET_ADMIN capability will be added
364                                 to the set of capabilities the
365                                 container retains. The latter may be
366                                 disabled by using
367                                 <option>--drop-capability=</option>.</para></listitem>
368                         </varlistentry>
369
370                         <varlistentry>
371                                 <term><option>--network-interface=</option></term>
372
373                                 <listitem><para>Assign the specified
374                                 network interface to the
375                                 container. This will remove the
376                                 specified interface from the calling
377                                 namespace and place it in the
378                                 container. When the container
379                                 terminates, it is moved back to the
380                                 host namespace. Note that
381                                 <option>--network-interface=</option>
382                                 implies
383                                 <option>--private-network</option>. This
384                                 option may be used more than once to
385                                 add multiple network interfaces to the
386                                 container.</para></listitem>
387                         </varlistentry>
388
389                         <varlistentry>
390                                 <term><option>--network-macvlan=</option></term>
391
392                                 <listitem><para>Create a
393                                 <literal>macvlan</literal> interface
394                                 of the specified Ethernet network
395                                 interface and add it to the
396                                 container. A
397                                 <literal>macvlan</literal> interface
398                                 is a virtual interface that adds a
399                                 second MAC address to an existing
400                                 physical Ethernet link. The interface
401                                 in the container will be named after
402                                 the interface on the host, prefixed
403                                 with <literal>mv-</literal>. Note that
404                                 <option>--network-macvlan=</option>
405                                 implies
406                                 <option>--private-network</option>. This
407                                 option may be used more than once to
408                                 add multiple network interfaces to the
409                                 container.</para></listitem>
410                         </varlistentry>
411
412                         <varlistentry>
413                                 <term><option>-n</option></term>
414                                 <term><option>--network-veth</option></term>
415
416                                 <listitem><para>Create a virtual
417                                 Ethernet link
418                                 (<literal>veth</literal>) between host
419                                 and container. The host side of the
420                                 Ethernet link will be available as a
421                                 network interface named after the
422                                 container's name (as specified with
423                                 <option>--machine=</option>), prefixed
424                                 with <literal>ve-</literal>. The
425                                 container side of the Ethernet
426                                 link will be named
427                                 <literal>host0</literal>. Note that
428                                 <option>--network-veth</option>
429                                 implies
430                                 <option>--private-network</option>.</para></listitem>
431                         </varlistentry>
432
433                         <varlistentry>
434                                 <term><option>--network-bridge=</option></term>
435
436                                 <listitem><para>Adds the host side of
437                                 the Ethernet link created with
438                                 <option>--network-veth</option> to the
439                                 specified bridge. Note that
440                                 <option>--network-bridge=</option>
441                                 implies
442                                 <option>--network-veth</option>. If
443                                 this option is used, the host side of
444                                 the Ethernet link will use the
445                                 <literal>vb-</literal> prefix instead
446                                 of <literal>ve-</literal>.</para></listitem>
447                         </varlistentry>
448
449                         <varlistentry>
450                                 <term><option>-p</option></term>
451                                 <term><option>--port=</option></term>
452
453                                 <listitem><para>If private networking
454                                 is enabled, maps an IP port on the
455                                 host onto an IP port on the
456                                 container. Takes a protocol specifier
457                                 (either <literal>tcp</literal> or
458                                 <literal>udp</literal>), separated by
459                                 a colon from a host port number in the
460                                 range 1 to 65535, separated by a colon
461                                 from a container port number in the
462                                 range from 1 to 65535. The protocol
463                                 specifier and its separating colon may
464                                 be omitted, in which case
465                                 <literal>tcp</literal> is assumed.
466                                 The container port number and its
467                                 colon may be ommitted, in which case
468                                 the same port as the host port is
469                                 implied. This option is only supported
470                                 if private networking is used, such as
471                                 <option>--network-veth</option> or
472                                 <option>--network-bridge=</option>.</para></listitem>
473                         </varlistentry>
474
475                         <varlistentry>
476                                 <term><option>-Z</option></term>
477                                 <term><option>--selinux-context=</option></term>
478
479                                 <listitem><para>Sets the SELinux
480                                 security context to be used to label
481                                 processes in the container.</para>
482                                 </listitem>
483                         </varlistentry>
484
485                         <varlistentry>
486                                 <term><option>-L</option></term>
487                                 <term><option>--selinux-apifs-context=</option></term>
488
489                                 <listitem><para>Sets the SELinux security
490                                 context to be used to label files in
491                                 the virtual API file systems in the
492                                 container.</para>
493                                 </listitem>
494                         </varlistentry>
495
496                         <varlistentry>
497                                 <term><option>--capability=</option></term>
498
499                                 <listitem><para>List one or more
500                                 additional capabilities to grant the
501                                 container. Takes a comma-separated
502                                 list of capability names, see
503                                 <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
504                                 for more information. Note that the
505                                 following capabilities will be granted
506                                 in any way: CAP_CHOWN,
507                                 CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
508                                 CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
509                                 CAP_KILL, CAP_LEASE,
510                                 CAP_LINUX_IMMUTABLE,
511                                 CAP_NET_BIND_SERVICE,
512                                 CAP_NET_BROADCAST, CAP_NET_RAW,
513                                 CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP,
514                                 CAP_SETUID, CAP_SYS_ADMIN,
515                                 CAP_SYS_CHROOT, CAP_SYS_NICE,
516                                 CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG,
517                                 CAP_SYS_RESOURCE, CAP_SYS_BOOT,
518                                 CAP_AUDIT_WRITE,
519                                 CAP_AUDIT_CONTROL. Also CAP_NET_ADMIN
520                                 is retained if
521                                 <option>--private-network</option> is
522                                 specified. If the special value
523                                 <literal>all</literal> is passed, all
524                                 capabilities are
525                                 retained.</para></listitem>
526                         </varlistentry>
527
528                         <varlistentry>
529                                 <term><option>--drop-capability=</option></term>
530
531                                 <listitem><para>Specify one or more
532                                 additional capabilities to drop for
533                                 the container. This allows running the
534                                 container with fewer capabilities than
535                                 the default (see above).</para></listitem>
536                         </varlistentry>
537
538                         <varlistentry>
539                                 <term><option>--link-journal=</option></term>
540
541                                 <listitem><para>Control whether the
542                                 container's journal shall be made
543                                 visible to the host system. If enabled,
544                                 allows viewing the container's journal
545                                 files from the host (but not vice
546                                 versa). Takes one of
547                                 <literal>no</literal>,
548                                 <literal>host</literal>,
549                                 <literal>try-host</literal>,
550                                 <literal>guest</literal>,
551                                 <literal>try-guest</literal>,
552                                 <literal>auto</literal>. If
553                                 <literal>no</literal>, the journal is
554                                 not linked. If <literal>host</literal>,
555                                 the journal files are stored on the
556                                 host file system (beneath
557                                 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
558                                 and the subdirectory is bind-mounted
559                                 into the container at the same
560                                 location. If <literal>guest</literal>,
561                                 the journal files are stored on the
562                                 guest file system (beneath
563                                 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
564                                 and the subdirectory is symlinked into the host
565                                 at the same location. <literal>try-host</literal>
566                                 and <literal>try-guest</literal> do the same
567                                 but do not fail if the host does not have
568                                 persistent journalling enabled.
569                                 If <literal>auto</literal> (the default),
570                                 and the right subdirectory of
571                                 <filename>/var/log/journal</filename>
572                                 exists, it will be bind mounted
573                                 into the container. If the
574                                 subdirectory does not exist, no
575                                 linking is performed. Effectively,
576                                 booting a container once with
577                                 <literal>guest</literal> or
578                                 <literal>host</literal> will link the
579                                 journal persistently if further on
580                                 the default of <literal>auto</literal>
581                                 is used.</para></listitem>
582                         </varlistentry>
583
584                         <varlistentry>
585                                 <term><option>-j</option></term>
586
587                                 <listitem><para>Equivalent to
588                                 <option>--link-journal=try-guest</option>.</para></listitem>
589                         </varlistentry>
590
591                         <varlistentry>
592                                 <term><option>--read-only</option></term>
593
594                                 <listitem><para>Mount the root file
595                                 system read-only for the
596                                 container.</para></listitem>
597                         </varlistentry>
598
599                         <varlistentry>
600                                 <term><option>--bind=</option></term>
601                                 <term><option>--bind-ro=</option></term>
602
603                                 <listitem><para>Bind mount a file or
604                                 directory from the host into the
605                                 container. Either takes a path
606                                 argument -- in which case the
607                                 specified path will be mounted from
608                                 the host to the same path in the
609                                 container --, or a colon-separated
610                                 pair of paths -- in which case the
611                                 first specified path is the source in
612                                 the host, and the second path is the
613                                 destination in the container. The
614                                 <option>--bind-ro=</option> option
615                                 creates read-only bind
616                                 mounts.</para></listitem>
617                         </varlistentry>
618
619                         <varlistentry>
620                                 <term><option>--tmpfs=</option></term>
621
622                                 <listitem><para>Mount a tmpfs file
623                                 system into the container. Takes a
624                                 single absolute path argument that
625                                 specifies where to mount the tmpfs
626                                 instance to (in which case the
627                                 directory access mode will be chosen
628                                 as 0755, owned by root/root), or
629                                 optionally a colon-separated pair of
630                                 path and mount option string, that is
631                                 used for mounting (in which case the
632                                 kernel default for access mode and
633                                 owner will be chosen, unless otherwise
634                                 specified). This option is
635                                 particularly useful for mounting
636                                 directories such as
637                                 <filename>/var</filename> as tmpfs, to
638                                 allow state-less systems, in
639                                 particular when combined with
640                                 <option>--read-only</option>.</para></listitem>
641                         </varlistentry>
642
643                         <varlistentry>
644                                 <term><option>--setenv=</option></term>
645
646                                 <listitem><para>Specifies an
647                                 environment variable assignment to
648                                 pass to the init process in the
649                                 container, in the format
650                                 <literal>NAME=VALUE</literal>. This
651                                 may be used to override the default
652                                 variables or to set additional
653                                 variables. This parameter may be used
654                                 more than once.</para></listitem>
655                         </varlistentry>
656
657                         <varlistentry>
658                                 <term><option>--share-system</option></term>
659
660                                 <listitem><para>Allows the container
661                                 to share certain system facilities
662                                 with the host. More specifically, this
663                                 turns off PID namespacing, UTS
664                                 namespacing and IPC namespacing, and
665                                 thus allows the guest to see and
666                                 interact more easily with processes
667                                 outside of the container. Note that
668                                 using this option makes it impossible
669                                 to start up a full Operating System in
670                                 the container, as an init system
671                                 cannot operate in this mode. It is
672                                 only useful to run specific programs
673                                 or applications this way, without
674                                 involving an init system in the
675                                 container. This option implies
676                                 <option>--register=no</option>. This
677                                 option may not be combined with
678                                 <option>--boot</option>.</para></listitem>
679                         </varlistentry>
680
681                         <varlistentry>
682                                 <term><option>--register=</option></term>
683
684                                 <listitem><para>Controls whether the
685                                 container is registered with
686                                 <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Takes
687                                 a boolean argument, defaults to
688                                 <literal>yes</literal>. This option
689                                 should be enabled when the container
690                                 runs a full Operating System (more
691                                 specifically: an init system), and is
692                                 useful to ensure that the container is
693                                 accessible via
694                                 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
695                                 and shown by tools such as
696                                 <citerefentry project='man-pages'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>. If
697                                 the container does not run an init
698                                 system, it is recommended to set this
699                                 option to <literal>no</literal>. Note
700                                 that <option>--share-system</option>
701                                 implies
702                                 <option>--register=no</option>.
703                                 </para></listitem>
704                         </varlistentry>
705
706                         <varlistentry>
707                                 <term><option>--keep-unit</option></term>
708
709                                 <listitem><para>Instead of creating a
710                                 transient scope unit to run the
711                                 container in, simply register the
712                                 service or scope unit
713                                 <command>systemd-nspawn</command> has
714                                 been invoked in with
715                                 <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. This
716                                 has no effect if
717                                 <option>--register=no</option> is
718                                 used. This switch should be used if
719                                 <command>systemd-nspawn</command> is
720                                 invoked from within a service unit,
721                                 and the service unit's sole purpose
722                                 is to run a single
723                                 <command>systemd-nspawn</command>
724                                 container. This option is not
725                                 available if run from a user
726                                 session.</para></listitem>
727                         </varlistentry>
728
729                         <varlistentry>
730                                 <term><option>--personality=</option></term>
731
732                                 <listitem><para>Control the
733                                 architecture ("personality") reported
734                                 by
735                                 <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>
736                                 in the container. Currently, only
737                                 <literal>x86</literal> and
738                                 <literal>x86-64</literal> are
739                                 supported. This is useful when running
740                                 a 32-bit container on a 64-bit
741                                 host. If this setting is not used,
742                                 the personality reported in the
743                                 container is the same as the one
744                                 reported on the
745                                 host.</para></listitem>
746                         </varlistentry>
747
748                         <varlistentry>
749                                 <term><option>-q</option></term>
750                                 <term><option>--quiet</option></term>
751
752                                 <listitem><para>Turns off any status
753                                 output by the tool itself. When this
754                                 switch is used, the only output
755                                 from nspawn will be the console output
756                                 of the container OS itself.</para></listitem>
757                         </varlistentry>
758
759                         <varlistentry>
760                                 <term><option>--volatile</option><replaceable>=MODE</replaceable></term>
761
762                                 <listitem><para>Boots the container in
763                                 volatile mode. When no mode parameter
764                                 is passed or when mode is specified as
765                                 <literal>yes</literal> full volatile
766                                 mode is enabled. This means the root
767                                 directory is mounted as mostly
768                                 unpopulated <literal>tmpfs</literal>
769                                 instance, and
770                                 <filename>/usr</filename> from the OS
771                                 tree is mounted into it, read-only
772                                 (the system thus starts up with
773                                 read-only OS resources, but pristine
774                                 state and configuration, any changes
775                                 to the either are lost on
776                                 shutdown). When the mode parameter is
777                                 specified as <literal>state</literal>
778                                 the OS tree is mounted read-only, but
779                                 <filename>/var</filename> is mounted
780                                 as <literal>tmpfs</literal> instance
781                                 into it (the system thus starts up
782                                 with read-only OS resources and
783                                 configuration, but pristine state, any
784                                 changes to the latter are lost on
785                                 shutdown). When the mode parameter is
786                                 specified as <literal>no</literal>
787                                 (the default) the whole OS tree is
788                                 made available writable.</para>
789
790                                 <para>Note that setting this to
791                                 <literal>yes</literal> or
792                                 <literal>state</literal> will only
793                                 work correctly with operating systems
794                                 in the container that can boot up with
795                                 only <filename>/usr</filename>
796                                 mounted, and are able to populate
797                                 <filename>/var</filename>
798                                 automatically, as
799                                 needed.</para></listitem>
800                         </varlistentry>
801
802                         <xi:include href="standard-options.xml" xpointer="help" />
803                         <xi:include href="standard-options.xml" xpointer="version" />
804                 </variablelist>
805
806         </refsect1>
807
808         <refsect1>
809                 <title>Examples</title>
810                 <example>
811                         <title>Boot a minimal Fedora distribution in a container</title>
812
813                         <programlisting># yum -y --releasever=21 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal
814 # systemd-nspawn -bD /srv/mycontainer</programlisting>
815
816                         <para>This installs a minimal Fedora distribution into
817                         the directory <filename noindex='true'>/srv/mycontainer/</filename> and
818                         then boots an OS in a namespace container in
819                         it.</para>
820                 </example>
821
822                 <example>
823                         <title>Spawn a shell in a container of a minimal Debian unstable distribution</title>
824
825                         <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
826 # systemd-nspawn -D ~/debian-tree/</programlisting>
827
828                         <para>This installs a minimal Debian unstable
829                         distribution into the directory
830                         <filename>~/debian-tree/</filename> and then spawns a
831                         shell in a namespace container in it.</para>
832                 </example>
833
834                 <example>
835                         <title>Boot a minimal Arch Linux distribution in a container</title>
836
837                         <programlisting># pacstrap -c -d ~/arch-tree/ base
838 # systemd-nspawn -bD ~/arch-tree/</programlisting>
839
840                         <para>This installs a mimimal Arch Linux distribution into
841                         the directory <filename>~/arch-tree/</filename> and then
842                         boots an OS in a namespace container in it.</para>
843                 </example>
844
845                 <example>
846                         <title>Enable Arch Linux container on boot</title>
847
848                         <programlisting># mv ~/arch-tree /var/lib/machines/arch
849 # systemctl enable systemd-nspawn@arch.service
850 # systemctl start systemd-nspawn@arch.service</programlisting>
851
852                         <para>This makes the Arch Linux container part of the
853                         <filename>multi-user.target</filename> on the host.
854                         </para>
855                 </example>
856
857                 <example>
858                         <title>Boot into an ephemeral <literal>btrfs</literal> snapshot of the host system</title>
859
860                         <programlisting># systemd-nspawn -D / -xb</programlisting>
861
862                         <para>This runs a copy of the host system in a
863                         <literal>btrfs</literal> snapshot which is
864                         removed immediately when the container
865                         exits. All file system changes made during
866                         runtime will be lost on shutdown,
867                         hence.</para>
868                 </example>
869
870                 <example>
871                         <title>Run a container with SELinux sandbox security contexts</title>
872
873                         <programlisting># chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container
874 # 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>
875                 </example>
876         </refsect1>
877
878         <refsect1>
879                 <title>Exit status</title>
880
881                 <para>The exit code of the program executed in the
882                 container is returned.</para>
883         </refsect1>
884
885         <refsect1>
886                 <title>See Also</title>
887                 <para>
888                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
889                         <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
890                         <citerefentry project='die-net'><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
891                         <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
892                         <citerefentry project='archlinux'><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
893                         <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
894                         <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
895                         <citerefentry><refentrytitle>btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
896                 </para>
897         </refsect1>
898
899 </refentry>