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. 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>try-host</literal>,
 443                                 <literal>guest</literal>,
 444                                 <literal>try-guest</literal>,
 445                                 <literal>auto</literal>. If
 446                                 <literal>no</literal>, the journal is
 447                                 not linked. If <literal>host</literal>,
 448                                 the journal files are stored on the
 449                                 host file system (beneath
 450                                 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
 451                                 and the subdirectory is bind-mounted
 452                                 into the container at the same
 453                                 location. If <literal>guest</literal>,
 454                                 the journal files are stored on the
 455                                 guest file system (beneath
 456                                 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
 457                                 and the subdirectory is symlinked into the host
 458                                 at the same location. <literal>try-host</literal>
 459                                 and <literal>try-guest</literal> do the same
 460                                 but do not fail if the host does not have
 461                                 persistant journalling enabled.
 462                                 If <literal>auto</literal> (the default),
 463                                 and the right subdirectory of
 464                                 <filename>/var/log/journal</filename>
 465                                 exists, it will be bind mounted
 466                                 into the container. If the
 467                                 subdirectory does not exist, no
 468                                 linking is performed. Effectively,
 469                                 booting a container once with
 470                                 <literal>guest</literal> or
 471                                 <literal>host</literal> will link the
 472                                 journal persistently if further on
 473                                 the default of <literal>auto</literal>
 474                                 is used.</para></listitem>
 475                         </varlistentry>
 476
 477                         <varlistentry>
 478                                 <term><option>-j</option></term>
 479
 480                                 <listitem><para>Equivalent to
 481                                 <option>--link-journal=try-guest</option>.</para></listitem>
 482                         </varlistentry>
 483
 484                         <varlistentry>
 485                                 <term><option>--read-only</option></term>
 486
 487                                 <listitem><para>Mount the root file
 488                                 system read-only for the
 489                                 container.</para></listitem>
 490                         </varlistentry>
 491
 492                         <varlistentry>
 493                                 <term><option>--bind=</option></term>
 494                                 <term><option>--bind-ro=</option></term>
 495
 496                                 <listitem><para>Bind mount a file or
 497                                 directory from the host into the
 498                                 container. Either takes a path
 499                                 argument -- in which case the
 500                                 specified path will be mounted from
 501                                 the host to the same path in the
 502                                 container --, or a colon-separated
 503                                 pair of paths -- in which case the
 504                                 first specified path is the source in
 505                                 the host, and the second path is the
 506                                 destination in the container. The
 507                                 <option>--bind-ro=</option> option
 508                                 creates read-only bind
 509                                 mounts.</para></listitem>
 510                         </varlistentry>
 511
 512                         <varlistentry>
 513                                 <term><option>--tmpfs=</option></term>
 514
 515                                 <listitem><para>Mount a tmpfs file
 516                                 system into the container. Takes a
 517                                 single absolute path argument that
 518                                 specifies where to mount the tmpfs
 519                                 instance to (in which case the
 520                                 directory access mode will be chosen
 521                                 as 0755, owned by root/root), or
 522                                 optionally a colon-separated pair of
 523                                 path and mount option string, that is
 524                                 used for mounting (in which case the
 525                                 kernel default for access mode and
 526                                 owner will be chosen, unless otherwise
 527                                 specified). This option is
 528                                 particularly useful for mounting
 529                                 directories such as
 530                                 <filename>/var</filename> as tmpfs, to
 531                                 allow state-less systems, in
 532                                 particular when combined with
 533                                 <option>--read-only</option>.</para></listitem>
 534                         </varlistentry>
 535
 536                         <varlistentry>
 537                                 <term><option>--setenv=</option></term>
 538
 539                                 <listitem><para>Specifies an
 540                                 environment variable assignment to
 541                                 pass to the init process in the
 542                                 container, in the format
 543                                 <literal>NAME=VALUE</literal>. This
 544                                 may be used to override the default
 545                                 variables or to set additional
 546                                 variables. This parameter may be used
 547                                 more than once.</para></listitem>
 548                         </varlistentry>
 549
 550                         <varlistentry>
 551                                 <term><option>--share-system</option></term>
 552
 553                                 <listitem><para>Allows the container
 554                                 to share certain system facilities
 555                                 with the host. More specifically, this
 556                                 turns off PID namespacing, UTS
 557                                 namespacing and IPC namespacing, and
 558                                 thus allows the guest to see and
 559                                 interact more easily with processes
 560                                 outside of the container. Note that
 561                                 using this option makes it impossible
 562                                 to start up a full Operating System in
 563                                 the container, as an init system
 564                                 cannot operate in this mode. It is
 565                                 only useful to run specific programs
 566                                 or applications this way, without
 567                                 involving an init system in the
 568                                 container. This option implies
 569                                 <option>--register=no</option>. This
 570                                 option may not be combined with
 571                                 <option>--boot</option>.</para></listitem>
 572                         </varlistentry>
 573
 574                         <varlistentry>
 575                                 <term><option>--register=</option></term>
 576
 577                                 <listitem><para>Controls whether the
 578                                 container is registered with
 579                                 <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Takes
 580                                 a boolean argument, defaults to
 581                                 <literal>yes</literal>. This option
 582                                 should be enabled when the container
 583                                 runs a full Operating System (more
 584                                 specifically: an init system), and is
 585                                 useful to ensure that the container is
 586                                 accessible via
 587                                 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 588                                 and shown by tools such as
 589                                 <citerefentry project='man-pages'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>. If
 590                                 the container does not run an init
 591                                 system, it is recommended to set this
 592                                 option to <literal>no</literal>. Note
 593                                 that <option>--share-system</option>
 594                                 implies
 595                                 <option>--register=no</option>.
 596                                 </para></listitem>
 597                         </varlistentry>
 598
 599                         <varlistentry>
 600                                 <term><option>--keep-unit</option></term>
 601
 602                                 <listitem><para>Instead of creating a
 603                                 transient scope unit to run the
 604                                 container in, simply register the
 605                                 service or scope unit
 606                                 <command>systemd-nspawn</command> has
 607                                 been invoked in with
 608                                 <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. This
 609                                 has no effect if
 610                                 <option>--register=no</option> is
 611                                 used. This switch should be used if
 612                                 <command>systemd-nspawn</command> is
 613                                 invoked from within a service unit,
 614                                 and the service unit's sole purpose
 615                                 is to run a single
 616                                 <command>systemd-nspawn</command>
 617                                 container. This option is not
 618                                 available if run from a user
 619                                 session.</para></listitem>
 620                         </varlistentry>
 621
 622                         <varlistentry>
 623                                 <term><option>--personality=</option></term>
 624
 625                                 <listitem><para>Control the
 626                                 architecture ("personality") reported
 627                                 by
 628                                 <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 629                                 in the container. Currently, only
 630                                 <literal>x86</literal> and
 631                                 <literal>x86-64</literal> are
 632                                 supported. This is useful when running
 633                                 a 32-bit container on a 64-bit
 634                                 host. If this setting is not used,
 635                                 the personality reported in the
 636                                 container is the same as the one
 637                                 reported on the
 638                                 host.</para></listitem>
 639                         </varlistentry>
 640
 641                         <varlistentry>
 642                                 <term><option>-q</option></term>
 643                                 <term><option>--quiet</option></term>
 644
 645                                 <listitem><para>Turns off any status
 646                                 output by the tool itself. When this
 647                                 switch is used, the only output
 648                                 from nspawn will be the console output
 649                                 of the container OS itself.</para></listitem>
 650                         </varlistentry>
 651
 652                         <varlistentry>
 653                                 <term><option>--volatile</option><replaceable>=MODE</replaceable></term>
 654
 655                                 <listitem><para>Boots the container in
 656                                 volatile (ephemeral) mode. When no
 657                                 mode parameter is passed or when mode
 658                                 is specified as <literal>yes</literal>
 659                                 full volatile mode is enabled. This
 660                                 means the root directory is mounted as
 661                                 mostly unpopulated
 662                                 <literal>tmpfs</literal> instance, and
 663                                 <filename>/usr</filename> from the OS
 664                                 tree is mounted into it, read-only
 665                                 (the system thus starts up with
 666                                 read-only OS resources, but pristine
 667                                 state and configuration, any changes
 668                                 to the either are lost on
 669                                 shutdown). When the mode parameter is
 670                                 specified as <literal>state</literal>
 671                                 the OS tree is mounted read-only, but
 672                                 <filename>/var</filename> is mounted
 673                                 as <literal>tmpfs</literal> instance
 674                                 into it (the system thus starts up
 675                                 with read-only OS resources and
 676                                 configuration, but pristine state, any
 677                                 changes to the latter are lost on
 678                                 shutdown). When the mode parameter is
 679                                 specified as <literal>no</literal>
 680                                 (the default) the whole OS tree is made
 681                                 available writable.</para>
 682
 683                                 <para>Note that setting this to
 684                                 <literal>yes</literal> or
 685                                 <literal>state</literal> will only
 686                                 work correctly with operating systems
 687                                 in the container that can boot up with
 688                                 only <filename>/usr</filename>
 689                                 mounted, and are able to populate
 690                                 <filename>/var</filename>
 691                                 automatically, as
 692                                 needed.</para></listitem>
 693                         </varlistentry>
 694
 695                         <xi:include href="standard-options.xml" xpointer="help" />
 696                         <xi:include href="standard-options.xml" xpointer="version" />
 697                 </variablelist>
 698
 699         </refsect1>
 700
 701         <refsect1>
 702                 <title>Examples</title>
 703                 <example>
 704                         <title>Boot a minimal Fedora distribution in a container</title>
 705
 706                         <programlisting># yum -y --releasever=19 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal
 707 # systemd-nspawn -bD /srv/mycontainer</programlisting>
 708
 709                         <para>This installs a minimal Fedora distribution into
 710                         the directory <filename noindex='true'>/srv/mycontainer/</filename> and
 711                         then boots an OS in a namespace container in
 712                         it.</para>
 713                 </example>
 714
 715                 <example>
 716                         <title>Spawn a shell in a container of a minimal Debian unstable distribution</title>
 717
 718                         <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
 719 # systemd-nspawn -D ~/debian-tree/</programlisting>
 720
 721                         <para>This installs a minimal Debian unstable
 722                         distribution into the directory
 723                         <filename>~/debian-tree/</filename> and then spawns a
 724                         shell in a namespace container in it.</para>
 725                 </example>
 726
 727                 <example>
 728                         <title>Boot a minimal Arch Linux distribution in a container</title>
 729
 730                         <programlisting># pacstrap -c -d ~/arch-tree/ base
 731 # systemd-nspawn -bD ~/arch-tree/</programlisting>
 732
 733                         <para>This installs a mimimal Arch Linux distribution into
 734                         the directory <filename>~/arch-tree/</filename> and then
 735                         boots an OS in a namespace container in it.</para>
 736                 </example>
 737
 738                 <example>
 739                         <title>Enable Arch Linux container on boot</title>
 740
 741                         <programlisting># mv ~/arch-tree /var/lib/container/arch
 742 # systemctl enable systemd-nspawn@arch.service
 743 # systemctl start systemd-nspawn@arch.service</programlisting>
 744
 745                         <para>This makes the Arch Linux container part of the
 746                         <filename>multi-user.target</filename> on the host.
 747                         </para>
 748                 </example>
 749
 750                 <example>
 751                         <title>Boot into a btrfs snapshot of the host system</title>
 752
 753                         <programlisting># btrfs subvolume snapshot / /.tmp
 754 # systemd-nspawn --private-network -D /.tmp -b</programlisting>
 755
 756                         <para>This runs a copy of the host system in a
 757                         btrfs snapshot.</para>
 758                 </example>
 759
 760                 <example>
 761                         <title>Run a container with SELinux sandbox security contexts</title>
 762
 763                         <programlisting># chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container
 764 # 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>
 765                 </example>
 766         </refsect1>
 767
 768         <refsect1>
 769                 <title>Exit status</title>
 770
 771                 <para>The exit code of the program executed in the
 772                 container is returned.</para>
 773         </refsect1>
 774
 775         <refsect1>
 776                 <title>See Also</title>
 777                 <para>
 778                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 779                         <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 780                         <citerefentry project='die-net'><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 781                         <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 782                         <citerefentry project='archlinux'><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 783                         <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 784                         <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 785                 </para>
 786         </refsect1>
 787
 788 </refentry>