man/systemd-nspawn.xml

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