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 run a
  71     command or OS in a light-weight namespace container. In many ways
  72     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 system
  75     hierarchy, as well as the process tree, the various IPC subsystems
  76     and the host and domain name.</para>
  77
  78     <para><command>systemd-nspawn</command> limits access to various
  79     kernel interfaces in the container to read-only, such as
  80     <filename>/sys</filename>, <filename>/proc/sys</filename> or
  81     <filename>/sys/fs/selinux</filename>. Network interfaces and the
  82     system clock may not be changed from within the container. Device
  83     nodes may not be created. The host system cannot be rebooted and
  84     kernel modules may not be loaded from within the container.</para>
  85
  86     <para>Note that even though these security precautions are taken
  87     <command>systemd-nspawn</command> is not suitable for secure
  88     container setups. Many of the security features may be
  89     circumvented and are hence primarily useful to avoid accidental
  90     changes to the host system from the container. The intended use of
  91     this program is debugging and testing as well as building of
  92     packages, distributions and software involved with boot and
  93     systems management.</para>
  94
  95     <para>In contrast to
  96     <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry> <command>systemd-nspawn</command>
  97     may be used to boot full Linux-based operating systems in a
  98     container.</para>
  99
 100     <para>Use a tool like
 101     <citerefentry project='mankier'><refentrytitle>dnf</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 102     <citerefentry project='die-net'><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 103     <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 104     or
 105     <citerefentry project='archlinux'><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 106     to set up an OS directory tree suitable as file system hierarchy
 107     for <command>systemd-nspawn</command> containers.</para>
 108
 109     <para>Note that <command>systemd-nspawn</command> will mount file
 110     systems private to the container to <filename>/dev</filename>,
 111     <filename>/run</filename> and similar. These will not be visible
 112     outside of the container, and their contents will be lost when the
 113     container exits.</para>
 114
 115     <para>Note that running two <command>systemd-nspawn</command>
 116     containers from the same directory tree will not make processes in
 117     them see each other. The PID namespace separation of the two
 118     containers is complete and the containers will share very few
 119     runtime objects except for the underlying file system. Use
 120     <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
 121     <command>login</command> command to request an additional login
 122     prompt in a running container.</para>
 123
 124     <para><command>systemd-nspawn</command> implements the
 125     <ulink
 126     url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container
 127     Interface</ulink> specification.</para>
 128
 129     <para>As a safety check <command>systemd-nspawn</command> will
 130     verify the existence of <filename>/usr/lib/os-release</filename>
 131     or <filename>/etc/os-release</filename> in the container tree
 132     before starting the container (see
 133     <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
 134     It might be necessary to add this file to the container tree
 135     manually if the OS of the container is too old to contain this
 136     file out-of-the-box.</para>
 137   </refsect1>
 138
 139   <refsect1>
 140     <title>Options</title>
 141
 142     <para>If option <option>-b</option> is specified, the arguments
 143     are used as arguments for the init binary. Otherwise,
 144     <replaceable>COMMAND</replaceable> specifies the program to launch
 145     in the container, and the remaining arguments are used as
 146     arguments for this program. If <option>-b</option> is not used and
 147     no arguments are specifed, a shell is launched in the
 148     container.</para>
 149
 150     <para>The following options are understood:</para>
 151
 152     <variablelist>
 153       <varlistentry>
 154         <term><option>-D</option></term>
 155         <term><option>--directory=</option></term>
 156
 157         <listitem><para>Directory to use as file system root for the
 158         container.</para>
 159
 160         <para>If neither <option>--directory=</option>, nor
 161         <option>--image=</option> is specified the directory is
 162         determined as <filename>/var/lib/machines/</filename> suffixed
 163         by the machine name as specified with
 164         <option>--machine=</option>. If neither
 165         <option>--directory=</option>, <option>--image=</option>, nor
 166         <option>--machine=</option> are specified, the current
 167         directory will be used. May not be specified together with
 168         <option>--image=</option>.</para></listitem>
 169       </varlistentry>
 170
 171       <varlistentry>
 172         <term><option>--template=</option></term>
 173
 174         <listitem><para>Directory or <literal>btrfs</literal>
 175         subvolume to use as template for the container's root
 176         directory. If this is specified and the container's root
 177         directory (as configured by <option>--directory=</option>)
 178         does not yet exist it is created as <literal>btrfs</literal>
 179         subvolume and populated from this template tree. Ideally, the
 180         specified template path refers to the root of a
 181         <literal>btrfs</literal> subvolume, in which case a simple
 182         copy-on-write snapshot is taken, and populating the root
 183         directory is instant. If the specified template path does not
 184         refer to the root of a <literal>btrfs</literal> subvolume (or
 185         not even to a <literal>btrfs</literal> file system at all),
 186         the tree is copied, which can be substantially more
 187         time-consuming. Note that if this option is used the
 188         container's root directory (in contrast to the template
 189         directory!) must be located on a <literal>btrfs</literal> file
 190         system, so that the <literal>btrfs</literal> subvolume may be
 191         created. May not be specified together with
 192         <option>--image=</option> or
 193         <option>--ephemeral</option>.</para></listitem>
 194       </varlistentry>
 195
 196       <varlistentry>
 197         <term><option>-x</option></term>
 198         <term><option>--ephemeral</option></term>
 199
 200         <listitem><para>If specified, the container is run with a
 201         temporary <literal>btrfs</literal> snapshot of its root
 202         directory (as configured with <option>--directory=</option>),
 203         that is removed immediately when the container terminates.
 204         This option is only supported if the root file system is
 205         <literal>btrfs</literal>. May not be specified together with
 206         <option>--image=</option> or
 207         <option>--template=</option>.</para></listitem>
 208       </varlistentry>
 209
 210       <varlistentry>
 211         <term><option>-i</option></term>
 212         <term><option>--image=</option></term>
 213
 214         <listitem><para>Disk image to mount the root directory for the
 215         container from. Takes a path to a regular file or to a block
 216         device node. The file or block device must contain
 217         either:</para>
 218
 219         <itemizedlist>
 220           <listitem><para>An MBR partition table with a single
 221           partition of type 0x83 that is marked
 222           bootable.</para></listitem>
 223
 224           <listitem><para>A GUID partition table (GPT) with a single
 225           partition of type
 226           0fc63daf-8483-4772-8e79-3d69d8477de4.</para></listitem>
 227
 228           <listitem><para>A GUID partition table (GPT) with a marked
 229           root partition which is mounted as the root directory of the
 230           container. Optionally, GPT images may contain a home and/or
 231           a server data partition which are mounted to the appropriate
 232           places in the container. All these partitions must be
 233           identified by the partition types defined by the <ulink
 234           url="http://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/">Discoverable
 235           Partitions Specification</ulink>.</para></listitem>
 236         </itemizedlist>
 237
 238         <para>Any other partitions, such as foreign partitions, swap
 239         partitions or EFI system partitions are not mounted. May not
 240         be specified together with <option>--directory=</option>,
 241         <option>--template=</option> or
 242         <option>--ephemeral</option>.</para></listitem>
 243       </varlistentry>
 244
 245       <varlistentry>
 246         <term><option>-b</option></term>
 247         <term><option>--boot</option></term>
 248
 249         <listitem><para>Automatically search for an init binary and
 250         invoke it instead of a shell or a user supplied program. If
 251         this option is used, arguments specified on the command line
 252         are used as arguments for the init binary. This option may not
 253         be combined with <option>--share-system</option>.
 254         </para></listitem>
 255       </varlistentry>
 256
 257       <varlistentry>
 258         <term><option>-u</option></term>
 259         <term><option>--user=</option></term>
 260
 261         <listitem><para>After transitioning into the container, change
 262         to the specified user-defined in the container's user
 263         database. Like all other systemd-nspawn features, this is not
 264         a security feature and provides protection against accidental
 265         destructive operations only.</para></listitem>
 266       </varlistentry>
 267
 268       <varlistentry>
 269         <term><option>-M</option></term>
 270         <term><option>--machine=</option></term>
 271
 272         <listitem><para>Sets the machine name for this container. This
 273         name may be used to identify this container during its runtime
 274         (for example in tools like
 275         <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 276         and similar), and is used to initialize the container's
 277         hostname (which the container can choose to override,
 278         however). If not specified, the last component of the root
 279         directory path of the container is used, possibly suffixed
 280         with a random identifier in case <option>--ephemeral</option>
 281         mode is selected. If the root directory selected is the host's
 282         root directory the host's hostname is used as default
 283         instead.</para></listitem>
 284       </varlistentry>
 285
 286       <varlistentry>
 287         <term><option>--uuid=</option></term>
 288
 289         <listitem><para>Set the specified UUID for the container. The
 290         init system will initialize
 291         <filename>/etc/machine-id</filename> from this if this file is
 292         not set yet. </para></listitem>
 293       </varlistentry>
 294
 295       <varlistentry>
 296         <term><option>--slice=</option></term>
 297
 298         <listitem><para>Make the container part of the specified
 299         slice, instead of the default
 300         <filename>machine.slice</filename>.</para>
 301         </listitem>
 302       </varlistentry>
 303
 304       <varlistentry>
 305         <term><option>--private-network</option></term>
 306
 307         <listitem><para>Disconnect networking of the container from
 308         the host. This makes all network interfaces unavailable in the
 309         container, with the exception of the loopback device and those
 310         specified with <option>--network-interface=</option> and
 311         configured with <option>--network-veth</option>. If this
 312         option is specified, the CAP_NET_ADMIN capability will be
 313         added to the set of capabilities the container retains. The
 314         latter may be disabled by using
 315         <option>--drop-capability=</option>.</para></listitem>
 316       </varlistentry>
 317
 318       <varlistentry>
 319         <term><option>--network-interface=</option></term>
 320
 321         <listitem><para>Assign the specified network interface to the
 322         container. This will remove the specified interface from the
 323         calling namespace and place it in the container. When the
 324         container terminates, it is moved back to the host namespace.
 325         Note that <option>--network-interface=</option> implies
 326         <option>--private-network</option>. This option may be used
 327         more than once to add multiple network interfaces to the
 328         container.</para></listitem>
 329       </varlistentry>
 330
 331       <varlistentry>
 332         <term><option>--network-macvlan=</option></term>
 333
 334         <listitem><para>Create a <literal>macvlan</literal> interface
 335         of the specified Ethernet network interface and add it to the
 336         container. A <literal>macvlan</literal> interface is a virtual
 337         interface that adds a second MAC address to an existing
 338         physical Ethernet link. The interface in the container will be
 339         named after the interface on the host, prefixed with
 340         <literal>mv-</literal>. Note that
 341         <option>--network-macvlan=</option> implies
 342         <option>--private-network</option>. This option may be used
 343         more than once to add multiple network interfaces to the
 344         container.</para></listitem>
 345       </varlistentry>
 346
 347       <varlistentry>
 348         <term><option>--network-ipvlan=</option></term>
 349
 350         <listitem><para>Create an <literal>ipvlan</literal> interface
 351         of the specified Ethernet network interface and add it to the
 352         container. An <literal>ipvlan</literal> interface is a virtual
 353         interface, similar to a <literal>macvlan</literal> interface,
 354         which uses the same MAC address as the underlying interface.
 355         The interface in the container will be named after the
 356         interface on the host, prefixed with <literal>iv-</literal>.
 357         Note that <option>--network-ipvlan=</option> implies
 358         <option>--private-network</option>. This option may be used
 359         more than once to add multiple network interfaces to the
 360         container.</para></listitem>
 361       </varlistentry>
 362
 363       <varlistentry>
 364         <term><option>-n</option></term>
 365         <term><option>--network-veth</option></term>
 366
 367         <listitem><para>Create a virtual Ethernet link
 368         (<literal>veth</literal>) between host and container. The host
 369         side of the Ethernet link will be available as a network
 370         interface named after the container's name (as specified with
 371         <option>--machine=</option>), prefixed with
 372         <literal>ve-</literal>. The container side of the Ethernet
 373         link will be named <literal>host0</literal>. Note that
 374         <option>--network-veth</option> implies
 375         <option>--private-network</option>.</para></listitem>
 376       </varlistentry>
 377
 378       <varlistentry>
 379         <term><option>--network-bridge=</option></term>
 380
 381         <listitem><para>Adds the host side of the Ethernet link
 382         created with <option>--network-veth</option> to the specified
 383         bridge. Note that <option>--network-bridge=</option> implies
 384         <option>--network-veth</option>. If this option is used, the
 385         host side of the Ethernet link will use the
 386         <literal>vb-</literal> prefix instead of
 387         <literal>ve-</literal>.</para></listitem>
 388       </varlistentry>
 389
 390       <varlistentry>
 391         <term><option>-p</option></term>
 392         <term><option>--port=</option></term>
 393
 394         <listitem><para>If private networking is enabled, maps an IP
 395         port on the host onto an IP port on the container. Takes a
 396         protocol specifier (either <literal>tcp</literal> or
 397         <literal>udp</literal>), separated by a colon from a host port
 398         number in the range 1 to 65535, separated by a colon from a
 399         container port number in the range from 1 to 65535. The
 400         protocol specifier and its separating colon may be omitted, in
 401         which case <literal>tcp</literal> is assumed. The container
 402         port number and its colon may be ommitted, in which case the
 403         same port as the host port is implied. This option is only
 404         supported if private networking is used, such as
 405         <option>--network-veth</option> or
 406         <option>--network-bridge=</option>.</para></listitem>
 407       </varlistentry>
 408
 409       <varlistentry>
 410         <term><option>-Z</option></term>
 411         <term><option>--selinux-context=</option></term>
 412
 413         <listitem><para>Sets the SELinux security context to be used
 414         to label processes in the container.</para>
 415         </listitem>
 416       </varlistentry>
 417
 418       <varlistentry>
 419         <term><option>-L</option></term>
 420         <term><option>--selinux-apifs-context=</option></term>
 421
 422         <listitem><para>Sets the SELinux security context to be used
 423         to label files in the virtual API file systems in the
 424         container.</para>
 425         </listitem>
 426       </varlistentry>
 427
 428       <varlistentry>
 429         <term><option>--capability=</option></term>
 430
 431         <listitem><para>List one or more additional capabilities to
 432         grant the container. Takes a comma-separated list of
 433         capability names, see
 434         <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 435         for more information. Note that the following capabilities
 436         will be granted in any way: CAP_CHOWN, CAP_DAC_OVERRIDE,
 437         CAP_DAC_READ_SEARCH, CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
 438         CAP_KILL, CAP_LEASE, CAP_LINUX_IMMUTABLE,
 439         CAP_NET_BIND_SERVICE, CAP_NET_BROADCAST, CAP_NET_RAW,
 440         CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP, CAP_SETUID,
 441         CAP_SYS_ADMIN, CAP_SYS_CHROOT, CAP_SYS_NICE, CAP_SYS_PTRACE,
 442         CAP_SYS_TTY_CONFIG, CAP_SYS_RESOURCE, CAP_SYS_BOOT,
 443         CAP_AUDIT_WRITE, CAP_AUDIT_CONTROL. Also CAP_NET_ADMIN is
 444         retained if <option>--private-network</option> is specified.
 445         If the special value <literal>all</literal> is passed, all
 446         capabilities are retained.</para></listitem>
 447       </varlistentry>
 448
 449       <varlistentry>
 450         <term><option>--drop-capability=</option></term>
 451
 452         <listitem><para>Specify one or more additional capabilities to
 453         drop for the container. This allows running the container with
 454         fewer capabilities than the default (see
 455         above).</para></listitem>
 456       </varlistentry>
 457
 458       <varlistentry>
 459         <term><option>--link-journal=</option></term>
 460
 461         <listitem><para>Control whether the container's journal shall
 462         be made visible to the host system. If enabled, allows viewing
 463         the container's journal files from the host (but not vice
 464         versa). Takes one of <literal>no</literal>,
 465         <literal>host</literal>, <literal>try-host</literal>,
 466         <literal>guest</literal>, <literal>try-guest</literal>,
 467         <literal>auto</literal>. If <literal>no</literal>, the journal
 468         is not linked. If <literal>host</literal>, the journal files
 469         are stored on the host file system (beneath
 470         <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
 471         and the subdirectory is bind-mounted into the container at the
 472         same location. If <literal>guest</literal>, the journal files
 473         are stored on the guest file system (beneath
 474         <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
 475         and the subdirectory is symlinked into the host at the same
 476         location. <literal>try-host</literal> and
 477         <literal>try-guest</literal> do the same but do not fail if
 478         the host does not have persistent journalling enabled. If
 479         <literal>auto</literal> (the default), and the right
 480         subdirectory of <filename>/var/log/journal</filename> exists,
 481         it will be bind mounted into the container. If the
 482         subdirectory does not exist, no linking is performed.
 483         Effectively, booting a container once with
 484         <literal>guest</literal> or <literal>host</literal> will link
 485         the journal persistently if further on the default of
 486         <literal>auto</literal> is used.</para></listitem>
 487       </varlistentry>
 488
 489       <varlistentry>
 490         <term><option>-j</option></term>
 491
 492         <listitem><para>Equivalent to
 493         <option>--link-journal=try-guest</option>.</para></listitem>
 494       </varlistentry>
 495
 496       <varlistentry>
 497         <term><option>--read-only</option></term>
 498
 499         <listitem><para>Mount the root file system read-only for the
 500         container.</para></listitem>
 501       </varlistentry>
 502
 503       <varlistentry>
 504         <term><option>--bind=</option></term>
 505         <term><option>--bind-ro=</option></term>
 506
 507         <listitem><para>Bind mount a file or directory from the host
 508         into the container. Either takes a path argument -- in which
 509         case the specified path will be mounted from the host to the
 510         same path in the container --, or a colon-separated pair of
 511         paths -- in which case the first specified path is the source
 512         in the host, and the second path is the destination in the
 513         container. The <option>--bind-ro=</option> option creates
 514         read-only bind mounts.</para></listitem>
 515       </varlistentry>
 516
 517       <varlistentry>
 518         <term><option>--tmpfs=</option></term>
 519
 520         <listitem><para>Mount a tmpfs file system into the container.
 521         Takes a single absolute path argument that specifies where to
 522         mount the tmpfs instance to (in which case the directory
 523         access mode will be chosen as 0755, owned by root/root), or
 524         optionally a colon-separated pair of path and mount option
 525         string, that is used for mounting (in which case the kernel
 526         default for access mode and owner will be chosen, unless
 527         otherwise specified). This option is particularly useful for
 528         mounting directories such as <filename>/var</filename> as
 529         tmpfs, to allow state-less systems, in particular when
 530         combined with <option>--read-only</option>.</para></listitem>
 531       </varlistentry>
 532
 533       <varlistentry>
 534         <term><option>--setenv=</option></term>
 535
 536         <listitem><para>Specifies an environment variable assignment
 537         to pass to the init process in the container, in the format
 538         <literal>NAME=VALUE</literal>. This may be used to override
 539         the default variables or to set additional variables. This
 540         parameter may be used more than once.</para></listitem>
 541       </varlistentry>
 542
 543       <varlistentry>
 544         <term><option>--share-system</option></term>
 545
 546         <listitem><para>Allows the container to share certain system
 547         facilities with the host. More specifically, this turns off
 548         PID namespacing, UTS namespacing and IPC namespacing, and thus
 549         allows the guest to see and interact more easily with
 550         processes outside of the container. Note that using this
 551         option makes it impossible to start up a full Operating System
 552         in the container, as an init system cannot operate in this
 553         mode. It is only useful to run specific programs or
 554         applications this way, without involving an init system in the
 555         container. This option implies <option>--register=no</option>.
 556         This option may not be combined with
 557         <option>--boot</option>.</para></listitem>
 558       </varlistentry>
 559
 560       <varlistentry>
 561         <term><option>--register=</option></term>
 562
 563         <listitem><para>Controls whether the container is registered
 564         with
 565         <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 566         Takes a boolean argument, defaults to <literal>yes</literal>.
 567         This option should be enabled when the container runs a full
 568         Operating System (more specifically: an init system), and is
 569         useful to ensure that the container is accessible via
 570         <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 571         and shown by tools such as
 572         <citerefentry project='man-pages'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 573         If the container does not run an init system, it is
 574         recommended to set this option to <literal>no</literal>. Note
 575         that <option>--share-system</option> implies
 576         <option>--register=no</option>. </para></listitem>
 577       </varlistentry>
 578
 579       <varlistentry>
 580         <term><option>--keep-unit</option></term>
 581
 582         <listitem><para>Instead of creating a transient scope unit to
 583         run the container in, simply register the service or scope
 584         unit <command>systemd-nspawn</command> has been invoked in
 585         with
 586         <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 587         This has no effect if <option>--register=no</option> is used.
 588         This switch should be used if
 589         <command>systemd-nspawn</command> is invoked from within a
 590         service unit, and the service unit's sole purpose is to run a
 591         single <command>systemd-nspawn</command> container. This
 592         option is not available if run from a user
 593         session.</para></listitem>
 594       </varlistentry>
 595
 596       <varlistentry>
 597         <term><option>--personality=</option></term>
 598
 599         <listitem><para>Control the architecture ("personality")
 600         reported by
 601         <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 602         in the container. Currently, only <literal>x86</literal> and
 603         <literal>x86-64</literal> are supported. This is useful when
 604         running a 32-bit container on a 64-bit host. If this setting
 605         is not used, the personality reported in the container is the
 606         same as the one reported on the host.</para></listitem>
 607       </varlistentry>
 608
 609       <varlistentry>
 610         <term><option>-q</option></term>
 611         <term><option>--quiet</option></term>
 612
 613         <listitem><para>Turns off any status output by the tool
 614         itself. When this switch is used, the only output from nspawn
 615         will be the console output of the container OS
 616         itself.</para></listitem>
 617       </varlistentry>
 618
 619       <varlistentry>
 620         <term><option>--volatile</option><replaceable>=MODE</replaceable></term>
 621
 622         <listitem><para>Boots the container in volatile mode. When no
 623         mode parameter is passed or when mode is specified as
 624         <literal>yes</literal> full volatile mode is enabled. This
 625         means the root directory is mounted as mostly unpopulated
 626         <literal>tmpfs</literal> instance, and
 627         <filename>/usr</filename> from the OS tree is mounted into it,
 628         read-only (the system thus starts up with read-only OS
 629         resources, but pristine state and configuration, any changes
 630         to the either are lost on shutdown). When the mode parameter
 631         is specified as <literal>state</literal> the OS tree is
 632         mounted read-only, but <filename>/var</filename> is mounted as
 633         <literal>tmpfs</literal> instance into it (the system thus
 634         starts up with read-only OS resources and configuration, but
 635         pristine state, any changes to the latter are lost on
 636         shutdown). When the mode parameter is specified as
 637         <literal>no</literal> (the default) the whole OS tree is made
 638         available writable.</para>
 639
 640         <para>Note that setting this to <literal>yes</literal> or
 641         <literal>state</literal> will only work correctly with
 642         operating systems in the container that can boot up with only
 643         <filename>/usr</filename> mounted, and are able to populate
 644         <filename>/var</filename> automatically, as
 645         needed.</para></listitem>
 646       </varlistentry>
 647
 648       <xi:include href="standard-options.xml" xpointer="help" />
 649       <xi:include href="standard-options.xml" xpointer="version" />
 650     </variablelist>
 651
 652   </refsect1>
 653
 654   <refsect1>
 655     <title>Examples</title>
 656
 657     <example>
 658       <title>Download a Fedora image and start a shell in it</title>
 659
 660       <programlisting># machinectl pull-raw --verify=no http://ftp.halifax.rwth-aachen.de/fedora/linux/releases/21/Cloud/Images/x86_64/Fedora-Cloud-Base-20141203-21.x86_64.raw.xz
 661 # systemd-nspawn -M Fedora-Cloud-Base-20141203-21</programlisting>
 662
 663       <para>This downloads an image using
 664       <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 665       and opens a shell in it.</para>
 666     </example>
 667
 668     <example>
 669       <title>Build and boot a minimal Fedora distribution in a container</title>
 670
 671       <programlisting># dnf -y --releasever=21 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd dnf fedora-release vim-minimal
 672 # systemd-nspawn -bD /srv/mycontainer</programlisting>
 673
 674       <para>This installs a minimal Fedora distribution into the
 675       directory <filename noindex='true'>/srv/mycontainer/</filename>
 676       and then boots an OS in a namespace container in it.</para>
 677     </example>
 678
 679     <example>
 680       <title>Spawn a shell in a container of a minimal Debian unstable distribution</title>
 681
 682       <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
 683 # systemd-nspawn -D ~/debian-tree/</programlisting>
 684
 685       <para>This installs a minimal Debian unstable distribution into
 686       the directory <filename>~/debian-tree/</filename> and then
 687       spawns a shell in a namespace container in it.</para>
 688     </example>
 689
 690     <example>
 691       <title>Boot a minimal Arch Linux distribution in a container</title>
 692
 693       <programlisting># pacstrap -c -d ~/arch-tree/ base
 694 # systemd-nspawn -bD ~/arch-tree/</programlisting>
 695
 696       <para>This installs a mimimal Arch Linux distribution into the
 697       directory <filename>~/arch-tree/</filename> and then boots an OS
 698       in a namespace container in it.</para>
 699     </example>
 700
 701     <example>
 702       <title>Boot into an ephemeral <literal>btrfs</literal> snapshot of the host system</title>
 703
 704       <programlisting># systemd-nspawn -D / -xb</programlisting>
 705
 706       <para>This runs a copy of the host system in a
 707       <literal>btrfs</literal> snapshot which is removed immediately
 708       when the container exits. All file system changes made during
 709       runtime will be lost on shutdown, hence.</para>
 710     </example>
 711
 712     <example>
 713       <title>Run a container with SELinux sandbox security contexts</title>
 714
 715       <programlisting># chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container
 716 # 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>
 717     </example>
 718   </refsect1>
 719
 720   <refsect1>
 721     <title>Exit status</title>
 722
 723     <para>The exit code of the program executed in the container is
 724     returned.</para>
 725   </refsect1>
 726
 727   <refsect1>
 728     <title>See Also</title>
 729     <para>
 730       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 731       <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 732       <citerefentry project='mankier'><refentrytitle>dnf</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 733       <citerefentry project='die-net'><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 734       <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 735       <citerefentry project='archlinux'><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 736       <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 737       <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 738       <citerefentry><refentrytitle>btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 739     </para>
 740   </refsect1>
 741
 742 </refentry>