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>. This is only applies if
 301         the machine is run in its own scope unit, i.e. if
 302         <option>--keep-unit</option> is not used.</para>
 303         </listitem>
 304       </varlistentry>
 305
 306       <varlistentry>
 307         <term><option>--property=</option></term>
 308
 309         <listitem><para>Set a unit property on the scope unit to
 310         register for the machine. This only applies if the machine is
 311         run in its own scope unit, i.e. if
 312         <option>--keep-unit</option> is not used. Takes unit property
 313         assignments in the same format as <command>systemctl
 314         set-property</command>. This is useful to set memory limits
 315         and similar for machines.</para>
 316         </listitem>
 317       </varlistentry>
 318
 319       <varlistentry>
 320         <term><option>--private-network</option></term>
 321
 322         <listitem><para>Disconnect networking of the container from
 323         the host. This makes all network interfaces unavailable in the
 324         container, with the exception of the loopback device and those
 325         specified with <option>--network-interface=</option> and
 326         configured with <option>--network-veth</option>. If this
 327         option is specified, the CAP_NET_ADMIN capability will be
 328         added to the set of capabilities the container retains. The
 329         latter may be disabled by using
 330         <option>--drop-capability=</option>.</para></listitem>
 331       </varlistentry>
 332
 333       <varlistentry>
 334         <term><option>--network-interface=</option></term>
 335
 336         <listitem><para>Assign the specified network interface to the
 337         container. This will remove the specified interface from the
 338         calling namespace and place it in the container. When the
 339         container terminates, it is moved back to the host namespace.
 340         Note that <option>--network-interface=</option> implies
 341         <option>--private-network</option>. This option may be used
 342         more than once to add multiple network interfaces to the
 343         container.</para></listitem>
 344       </varlistentry>
 345
 346       <varlistentry>
 347         <term><option>--network-macvlan=</option></term>
 348
 349         <listitem><para>Create a <literal>macvlan</literal> interface
 350         of the specified Ethernet network interface and add it to the
 351         container. A <literal>macvlan</literal> interface is a virtual
 352         interface that adds a second MAC address to an existing
 353         physical Ethernet link. The interface in the container will be
 354         named after the interface on the host, prefixed with
 355         <literal>mv-</literal>. Note that
 356         <option>--network-macvlan=</option> implies
 357         <option>--private-network</option>. This option may be used
 358         more than once to add multiple network interfaces to the
 359         container.</para></listitem>
 360       </varlistentry>
 361
 362       <varlistentry>
 363         <term><option>--network-ipvlan=</option></term>
 364
 365         <listitem><para>Create an <literal>ipvlan</literal> interface
 366         of the specified Ethernet network interface and add it to the
 367         container. An <literal>ipvlan</literal> interface is a virtual
 368         interface, similar to a <literal>macvlan</literal> interface,
 369         which uses the same MAC address as the underlying interface.
 370         The interface in the container will be named after the
 371         interface on the host, prefixed with <literal>iv-</literal>.
 372         Note that <option>--network-ipvlan=</option> implies
 373         <option>--private-network</option>. This option may be used
 374         more than once to add multiple network interfaces to the
 375         container.</para></listitem>
 376       </varlistentry>
 377
 378       <varlistentry>
 379         <term><option>-n</option></term>
 380         <term><option>--network-veth</option></term>
 381
 382         <listitem><para>Create a virtual Ethernet link
 383         (<literal>veth</literal>) between host and container. The host
 384         side of the Ethernet link will be available as a network
 385         interface named after the container's name (as specified with
 386         <option>--machine=</option>), prefixed with
 387         <literal>ve-</literal>. The container side of the Ethernet
 388         link will be named <literal>host0</literal>. Note that
 389         <option>--network-veth</option> implies
 390         <option>--private-network</option>.</para></listitem>
 391       </varlistentry>
 392
 393       <varlistentry>
 394         <term><option>--network-bridge=</option></term>
 395
 396         <listitem><para>Adds the host side of the Ethernet link
 397         created with <option>--network-veth</option> to the specified
 398         bridge. Note that <option>--network-bridge=</option> implies
 399         <option>--network-veth</option>. If this option is used, the
 400         host side of the Ethernet link will use the
 401         <literal>vb-</literal> prefix instead of
 402         <literal>ve-</literal>.</para></listitem>
 403       </varlistentry>
 404
 405       <varlistentry>
 406         <term><option>-p</option></term>
 407         <term><option>--port=</option></term>
 408
 409         <listitem><para>If private networking is enabled, maps an IP
 410         port on the host onto an IP port on the container. Takes a
 411         protocol specifier (either <literal>tcp</literal> or
 412         <literal>udp</literal>), separated by a colon from a host port
 413         number in the range 1 to 65535, separated by a colon from a
 414         container port number in the range from 1 to 65535. The
 415         protocol specifier and its separating colon may be omitted, in
 416         which case <literal>tcp</literal> is assumed. The container
 417         port number and its colon may be ommitted, in which case the
 418         same port as the host port is implied. This option is only
 419         supported if private networking is used, such as
 420         <option>--network-veth</option> or
 421         <option>--network-bridge=</option>.</para></listitem>
 422       </varlistentry>
 423
 424       <varlistentry>
 425         <term><option>-Z</option></term>
 426         <term><option>--selinux-context=</option></term>
 427
 428         <listitem><para>Sets the SELinux security context to be used
 429         to label processes in the container.</para>
 430         </listitem>
 431       </varlistentry>
 432
 433       <varlistentry>
 434         <term><option>-L</option></term>
 435         <term><option>--selinux-apifs-context=</option></term>
 436
 437         <listitem><para>Sets the SELinux security context to be used
 438         to label files in the virtual API file systems in the
 439         container.</para>
 440         </listitem>
 441       </varlistentry>
 442
 443       <varlistentry>
 444         <term><option>--capability=</option></term>
 445
 446         <listitem><para>List one or more additional capabilities to
 447         grant the container. Takes a comma-separated list of
 448         capability names, see
 449         <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 450         for more information. Note that the following capabilities
 451         will be granted in any way: CAP_CHOWN, CAP_DAC_OVERRIDE,
 452         CAP_DAC_READ_SEARCH, CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
 453         CAP_KILL, CAP_LEASE, CAP_LINUX_IMMUTABLE,
 454         CAP_NET_BIND_SERVICE, CAP_NET_BROADCAST, CAP_NET_RAW,
 455         CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP, CAP_SETUID,
 456         CAP_SYS_ADMIN, CAP_SYS_CHROOT, CAP_SYS_NICE, CAP_SYS_PTRACE,
 457         CAP_SYS_TTY_CONFIG, CAP_SYS_RESOURCE, CAP_SYS_BOOT,
 458         CAP_AUDIT_WRITE, CAP_AUDIT_CONTROL. Also CAP_NET_ADMIN is
 459         retained if <option>--private-network</option> is specified.
 460         If the special value <literal>all</literal> is passed, all
 461         capabilities are retained.</para></listitem>
 462       </varlistentry>
 463
 464       <varlistentry>
 465         <term><option>--drop-capability=</option></term>
 466
 467         <listitem><para>Specify one or more additional capabilities to
 468         drop for the container. This allows running the container with
 469         fewer capabilities than the default (see
 470         above).</para></listitem>
 471       </varlistentry>
 472
 473       <varlistentry>
 474         <term><option>--kill-signal=</option></term>
 475
 476         <listitem><para>Specify the process signal to send to the
 477         container's PID 1 when nspawn itself receives SIGTERM, in
 478         order to trigger an orderly shutdown of the
 479         container. Defaults to SIGRTMIN+3 if <option>--boot</option>
 480         is used (on systemd-compatible init systems SIGRTMIN+3
 481         triggers an orderly shutdown). Takes a signal name like
 482         <literal>SIGHUP</literal>, <literal>SIGTERM</literal> or
 483         similar as argument.</para></listitem>
 484       </varlistentry>
 485
 486       <varlistentry>
 487         <term><option>--link-journal=</option></term>
 488
 489         <listitem><para>Control whether the container's journal shall
 490         be made visible to the host system. If enabled, allows viewing
 491         the container's journal files from the host (but not vice
 492         versa). Takes one of <literal>no</literal>,
 493         <literal>host</literal>, <literal>try-host</literal>,
 494         <literal>guest</literal>, <literal>try-guest</literal>,
 495         <literal>auto</literal>. If <literal>no</literal>, the journal
 496         is not linked. If <literal>host</literal>, the journal files
 497         are stored on the host file system (beneath
 498         <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
 499         and the subdirectory is bind-mounted into the container at the
 500         same location. If <literal>guest</literal>, the journal files
 501         are stored on the guest file system (beneath
 502         <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
 503         and the subdirectory is symlinked into the host at the same
 504         location. <literal>try-host</literal> and
 505         <literal>try-guest</literal> do the same but do not fail if
 506         the host does not have persistent journalling enabled. If
 507         <literal>auto</literal> (the default), and the right
 508         subdirectory of <filename>/var/log/journal</filename> exists,
 509         it will be bind mounted into the container. If the
 510         subdirectory does not exist, no linking is performed.
 511         Effectively, booting a container once with
 512         <literal>guest</literal> or <literal>host</literal> will link
 513         the journal persistently if further on the default of
 514         <literal>auto</literal> is used.</para></listitem>
 515       </varlistentry>
 516
 517       <varlistentry>
 518         <term><option>-j</option></term>
 519
 520         <listitem><para>Equivalent to
 521         <option>--link-journal=try-guest</option>.</para></listitem>
 522       </varlistentry>
 523
 524       <varlistentry>
 525         <term><option>--read-only</option></term>
 526
 527         <listitem><para>Mount the root file system read-only for the
 528         container.</para></listitem>
 529       </varlistentry>
 530
 531       <varlistentry>
 532         <term><option>--bind=</option></term>
 533         <term><option>--bind-ro=</option></term>
 534
 535         <listitem><para>Bind mount a file or directory from the host
 536         into the container. Either takes a path argument -- in which
 537         case the specified path will be mounted from the host to the
 538         same path in the container --, or a colon-separated pair of
 539         paths -- in which case the first specified path is the source
 540         in the host, and the second path is the destination in the
 541         container. The <option>--bind-ro=</option> option creates
 542         read-only bind mounts.</para></listitem>
 543       </varlistentry>
 544
 545       <varlistentry>
 546         <term><option>--tmpfs=</option></term>
 547
 548         <listitem><para>Mount a tmpfs file system into the container.
 549         Takes a single absolute path argument that specifies where to
 550         mount the tmpfs instance to (in which case the directory
 551         access mode will be chosen as 0755, owned by root/root), or
 552         optionally a colon-separated pair of path and mount option
 553         string, that is used for mounting (in which case the kernel
 554         default for access mode and owner will be chosen, unless
 555         otherwise specified). This option is particularly useful for
 556         mounting directories such as <filename>/var</filename> as
 557         tmpfs, to allow state-less systems, in particular when
 558         combined with <option>--read-only</option>.</para></listitem>
 559       </varlistentry>
 560
 561       <varlistentry>
 562         <term><option>--setenv=</option></term>
 563
 564         <listitem><para>Specifies an environment variable assignment
 565         to pass to the init process in the container, in the format
 566         <literal>NAME=VALUE</literal>. This may be used to override
 567         the default variables or to set additional variables. This
 568         parameter may be used more than once.</para></listitem>
 569       </varlistentry>
 570
 571       <varlistentry>
 572         <term><option>--share-system</option></term>
 573
 574         <listitem><para>Allows the container to share certain system
 575         facilities with the host. More specifically, this turns off
 576         PID namespacing, UTS namespacing and IPC namespacing, and thus
 577         allows the guest to see and interact more easily with
 578         processes outside of the container. Note that using this
 579         option makes it impossible to start up a full Operating System
 580         in the container, as an init system cannot operate in this
 581         mode. It is only useful to run specific programs or
 582         applications this way, without involving an init system in the
 583         container. This option implies <option>--register=no</option>.
 584         This option may not be combined with
 585         <option>--boot</option>.</para></listitem>
 586       </varlistentry>
 587
 588       <varlistentry>
 589         <term><option>--register=</option></term>
 590
 591         <listitem><para>Controls whether the container is registered
 592         with
 593         <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 594         Takes a boolean argument, defaults to <literal>yes</literal>.
 595         This option should be enabled when the container runs a full
 596         Operating System (more specifically: an init system), and is
 597         useful to ensure that the container is accessible via
 598         <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 599         and shown by tools such as
 600         <citerefentry project='man-pages'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 601         If the container does not run an init system, it is
 602         recommended to set this option to <literal>no</literal>. Note
 603         that <option>--share-system</option> implies
 604         <option>--register=no</option>. </para></listitem>
 605       </varlistentry>
 606
 607       <varlistentry>
 608         <term><option>--keep-unit</option></term>
 609
 610         <listitem><para>Instead of creating a transient scope unit to
 611         run the container in, simply register the service or scope
 612         unit <command>systemd-nspawn</command> has been invoked in
 613         with
 614         <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 615         This has no effect if <option>--register=no</option> is used.
 616         This switch should be used if
 617         <command>systemd-nspawn</command> is invoked from within a
 618         service unit, and the service unit's sole purpose is to run a
 619         single <command>systemd-nspawn</command> container. This
 620         option is not available if run from a user
 621         session.</para></listitem>
 622       </varlistentry>
 623
 624       <varlistentry>
 625         <term><option>--personality=</option></term>
 626
 627         <listitem><para>Control the architecture ("personality")
 628         reported by
 629         <citerefentry project='man-pages'><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 630         in the container. Currently, only <literal>x86</literal> and
 631         <literal>x86-64</literal> are supported. This is useful when
 632         running a 32-bit container on a 64-bit host. If this setting
 633         is not used, the personality reported in the container is the
 634         same as the one reported on the host.</para></listitem>
 635       </varlistentry>
 636
 637       <varlistentry>
 638         <term><option>-q</option></term>
 639         <term><option>--quiet</option></term>
 640
 641         <listitem><para>Turns off any status output by the tool
 642         itself. When this switch is used, the only output from nspawn
 643         will be the console output of the container OS
 644         itself.</para></listitem>
 645       </varlistentry>
 646
 647       <varlistentry>
 648         <term><option>--volatile</option><replaceable>=MODE</replaceable></term>
 649
 650         <listitem><para>Boots the container in volatile mode. When no
 651         mode parameter is passed or when mode is specified as
 652         <literal>yes</literal> full volatile mode is enabled. This
 653         means the root directory is mounted as mostly unpopulated
 654         <literal>tmpfs</literal> instance, and
 655         <filename>/usr</filename> from the OS tree is mounted into it,
 656         read-only (the system thus starts up with read-only OS
 657         resources, but pristine state and configuration, any changes
 658         to the either are lost on shutdown). When the mode parameter
 659         is specified as <literal>state</literal> the OS tree is
 660         mounted read-only, but <filename>/var</filename> is mounted as
 661         <literal>tmpfs</literal> instance into it (the system thus
 662         starts up with read-only OS resources and configuration, but
 663         pristine state, any changes to the latter are lost on
 664         shutdown). When the mode parameter is specified as
 665         <literal>no</literal> (the default) the whole OS tree is made
 666         available writable.</para>
 667
 668         <para>Note that setting this to <literal>yes</literal> or
 669         <literal>state</literal> will only work correctly with
 670         operating systems in the container that can boot up with only
 671         <filename>/usr</filename> mounted, and are able to populate
 672         <filename>/var</filename> automatically, as
 673         needed.</para></listitem>
 674       </varlistentry>
 675
 676       <xi:include href="standard-options.xml" xpointer="help" />
 677       <xi:include href="standard-options.xml" xpointer="version" />
 678     </variablelist>
 679
 680   </refsect1>
 681
 682   <refsect1>
 683     <title>Examples</title>
 684
 685     <example>
 686       <title>Download a Fedora image and start a shell in it</title>
 687
 688       <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
 689 # systemd-nspawn -M Fedora-Cloud-Base-20141203-21</programlisting>
 690
 691       <para>This downloads an image using
 692       <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 693       and opens a shell in it.</para>
 694     </example>
 695
 696     <example>
 697       <title>Build and boot a minimal Fedora distribution in a container</title>
 698
 699       <programlisting># dnf -y --releasever=21 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd dnf fedora-release vim-minimal
 700 # systemd-nspawn -bD /srv/mycontainer</programlisting>
 701
 702       <para>This installs a minimal Fedora distribution into the
 703       directory <filename noindex='true'>/srv/mycontainer/</filename>
 704       and then boots an OS in a namespace container in it.</para>
 705     </example>
 706
 707     <example>
 708       <title>Spawn a shell in a container of a minimal Debian unstable distribution</title>
 709
 710       <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
 711 # systemd-nspawn -D ~/debian-tree/</programlisting>
 712
 713       <para>This installs a minimal Debian unstable distribution into
 714       the directory <filename>~/debian-tree/</filename> and then
 715       spawns a shell in a namespace container in it.</para>
 716     </example>
 717
 718     <example>
 719       <title>Boot a minimal Arch Linux distribution in a container</title>
 720
 721       <programlisting># pacstrap -c -d ~/arch-tree/ base
 722 # systemd-nspawn -bD ~/arch-tree/</programlisting>
 723
 724       <para>This installs a mimimal Arch Linux distribution into the
 725       directory <filename>~/arch-tree/</filename> and then boots an OS
 726       in a namespace container in it.</para>
 727     </example>
 728
 729     <example>
 730       <title>Boot into an ephemeral <literal>btrfs</literal> snapshot of the host system</title>
 731
 732       <programlisting># systemd-nspawn -D / -xb</programlisting>
 733
 734       <para>This runs a copy of the host system in a
 735       <literal>btrfs</literal> snapshot which is removed immediately
 736       when the container exits. All file system changes made during
 737       runtime will be lost on shutdown, hence.</para>
 738     </example>
 739
 740     <example>
 741       <title>Run a container with SELinux sandbox security contexts</title>
 742
 743       <programlisting># chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container
 744 # 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>
 745     </example>
 746   </refsect1>
 747
 748   <refsect1>
 749     <title>Exit status</title>
 750
 751     <para>The exit code of the program executed in the container is
 752     returned.</para>
 753   </refsect1>
 754
 755   <refsect1>
 756     <title>See Also</title>
 757     <para>
 758       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 759       <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 760       <citerefentry project='mankier'><refentrytitle>dnf</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 761       <citerefentry project='die-net'><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 762       <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 763       <citerefentry project='archlinux'><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 764       <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 765       <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 766       <citerefentry project='man-pages'><refentrytitle>btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 767     </para>
 768   </refsect1>
 769
 770 </refentry>