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