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/container/</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. May not be
 235                                 specified together with
 236                                 <option>--image=</option> or
 237                                 <option>--template=</option>.</para></listitem>
 238                         </varlistentry>
 239
 240                         <varlistentry>
 241                                 <term><option>-i</option></term>
 242                                 <term><option>--image=</option></term>
 243
 244                                 <listitem><para>Disk image to mount
 245                                 the root directory for the container
 246                                 from. Takes a path to a regular file
 247                                 or to a block device node. The file or
 248                                 block device must contain a GUID
 249                                 Partition Table with a root partition
 250                                 which is mounted as the root directory
 251                                 of the container. Optionally, it may
 252                                 contain a home and/or a server data
 253                                 partition which are mounted to the
 254                                 appropriate places in the
 255                                 container. All these partitions must
 256                                 be identified by the partition types
 257                                 defined by the <ulink
 258                                 url="http://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/">Discoverable
 259                                 Partitions Specification</ulink>. Any
 260                                 other partitions, such as foreign
 261                                 partitions, swap partitions or EFI
 262                                 system partitions are not mounted. May
 263                                 not be specified together with
 264                                 <option>--directory=</option>,
 265                                 <option>--template=</option> or
 266                                 <option>--ephemeral</option>.</para></listitem>
 267                         </varlistentry>
 268
 269                         <varlistentry>
 270                                 <term><option>-b</option></term>
 271                                 <term><option>--boot</option></term>
 272
 273                                 <listitem><para>Automatically search
 274                                 for an init binary and invoke it
 275                                 instead of a shell or a user supplied
 276                                 program. If this option is used,
 277                                 arguments specified on the command
 278                                 line are used as arguments for the
 279                                 init binary. This option may not be
 280                                 combined with
 281                                 <option>--share-system</option>.
 282                                 </para></listitem>
 283                         </varlistentry>
 284
 285                         <varlistentry>
 286                                 <term><option>-u</option></term>
 287                                 <term><option>--user=</option></term>
 288
 289                                 <listitem><para>After transitioning
 290                                 into the container, change to the
 291                                 specified user-defined in the
 292                                 container's user database. Like all
 293                                 other systemd-nspawn features, this is
 294                                 not a security feature and provides
 295                                 protection against accidental
 296                                 destructive operations
 297                                 only.</para></listitem>
 298                         </varlistentry>
 299
 300                         <varlistentry>
 301                                 <term><option>-M</option></term>
 302                                 <term><option>--machine=</option></term>
 303
 304                                 <listitem><para>Sets the machine name
 305                                 for this container. This name may be
 306                                 used to identify this container on the
 307                                 host, and is used to initialize the
 308                                 container's hostname (which the
 309                                 container can choose to override,
 310                                 however). If not specified, the last
 311                                 component of the root directory of the
 312                                 container is used.</para></listitem>
 313                         </varlistentry>
 314
 315                         <varlistentry>
 316                                 <term><option>--uuid=</option></term>
 317
 318                                 <listitem><para>Set the specified UUID
 319                                 for the container. The init system
 320                                 will initialize
 321                                 <filename>/etc/machine-id</filename>
 322                                 from this if this file is not set yet.
 323                                 </para></listitem>
 324                         </varlistentry>
 325
 326                         <varlistentry>
 327                                 <term><option>--slice=</option></term>
 328
 329                                 <listitem><para>Make the container
 330                                 part of the specified slice, instead
 331                                 of the default
 332                                 <filename>machine.slice</filename>.</para>
 333                                 </listitem>
 334                         </varlistentry>
 335
 336                         <varlistentry>
 337                                 <term><option>--private-network</option></term>
 338
 339                                 <listitem><para>Disconnect networking
 340                                 of the container from the host. This
 341                                 makes all network interfaces
 342                                 unavailable in the container, with the
 343                                 exception of the loopback device and
 344                                 those specified with
 345                                 <option>--network-interface=</option>
 346                                 and configured with
 347                                 <option>--network-veth</option>. If
 348                                 this option is specified, the
 349                                 CAP_NET_ADMIN capability will be added
 350                                 to the set of capabilities the
 351                                 container retains. The latter may be
 352                                 disabled by using
 353                                 <option>--drop-capability=</option>.</para></listitem>
 354                         </varlistentry>
 355
 356                         <varlistentry>
 357                                 <term><option>--network-interface=</option></term>
 358
 359                                 <listitem><para>Assign the specified
 360                                 network interface to the
 361                                 container. This will remove the
 362                                 specified interface from the calling
 363                                 namespace and place it in the
 364                                 container. When the container
 365                                 terminates, it is moved back to the
 366                                 host namespace. Note that
 367                                 <option>--network-interface=</option>
 368                                 implies
 369                                 <option>--private-network</option>. This
 370                                 option may be used more than once to
 371                                 add multiple network interfaces to the
 372                                 container.</para></listitem>
 373                         </varlistentry>
 374
 375                         <varlistentry>
 376                                 <term><option>--network-macvlan=</option></term>
 377
 378                                 <listitem><para>Create a
 379                                 <literal>macvlan</literal> interface
 380                                 of the specified Ethernet network
 381                                 interface and add it to the
 382                                 container. A
 383                                 <literal>macvlan</literal> interface
 384                                 is a virtual interface that adds a
 385                                 second MAC address to an existing
 386                                 physical Ethernet link. The interface
 387                                 in the container will be named after
 388                                 the interface on the host, prefixed
 389                                 with <literal>mv-</literal>. Note that
 390                                 <option>--network-macvlan=</option>
 391                                 implies
 392                                 <option>--private-network</option>. This
 393                                 option may be used more than once to
 394                                 add multiple network interfaces to the
 395                                 container.</para></listitem>
 396                         </varlistentry>
 397
 398                         <varlistentry>
 399                                 <term><option>--network-veth</option></term>
 400
 401                                 <listitem><para>Create a virtual
 402                                 Ethernet link
 403                                 (<literal>veth</literal>) between host
 404                                 and container. The host side of the
 405                                 Ethernet link will be available as a
 406                                 network interface named after the
 407                                 container's name (as specified with
 408                                 <option>--machine=</option>), prefixed
 409                                 with <literal>ve-</literal>. The
 410                                 container side of the Ethernet
 411                                 link will be named
 412                                 <literal>host0</literal>. Note that
 413                                 <option>--network-veth</option>
 414                                 implies
 415                                 <option>--private-network</option>.</para></listitem>
 416                         </varlistentry>
 417
 418                         <varlistentry>
 419                                 <term><option>--network-bridge=</option></term>
 420
 421                                 <listitem><para>Adds the host side of
 422                                 the Ethernet link created with
 423                                 <option>--network-veth</option> to the
 424                                 specified bridge. Note that
 425                                 <option>--network-bridge=</option>
 426                                 implies
 427                                 <option>--network-veth</option>. If
 428                                 this option is used, the host side of
 429                                 the Ethernet link will use the
 430                                 <literal>vb-</literal> prefix instead
 431                                 of <literal>ve-</literal>.</para></listitem>
 432                         </varlistentry>
 433
 434                         <varlistentry>
 435                                 <term><option>-Z</option></term>
 436                                 <term><option>--selinux-context=</option></term>
 437
 438                                 <listitem><para>Sets the SELinux
 439                                 security context to be used to label
 440                                 processes in the container.</para>
 441                                 </listitem>
 442                         </varlistentry>
 443
 444                         <varlistentry>
 445                                 <term><option>-L</option></term>
 446                                 <term><option>--selinux-apifs-context=</option></term>
 447
 448                                 <listitem><para>Sets the SELinux security
 449                                 context to be used to label files in
 450                                 the virtual API file systems in the
 451                                 container.</para>
 452                                 </listitem>
 453                         </varlistentry>
 454
 455                         <varlistentry>
 456                                 <term><option>--capability=</option></term>
 457
 458                                 <listitem><para>List one or more
 459                                 additional capabilities to grant the
 460                                 container. Takes a comma-separated
 461                                 list of capability names, see
 462                                 <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 463                                 for more information. Note that the
 464                                 following capabilities will be granted
 465                                 in any way: CAP_CHOWN,
 466                                 CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
 467                                 CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
 468                                 CAP_KILL, CAP_LEASE,
 469                                 CAP_LINUX_IMMUTABLE,
 470                                 CAP_NET_BIND_SERVICE,
 471                                 CAP_NET_BROADCAST, CAP_NET_RAW,
 472                                 CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP,
 473                                 CAP_SETUID, CAP_SYS_ADMIN,
 474                                 CAP_SYS_CHROOT, CAP_SYS_NICE,
 475                                 CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG,
 476                                 CAP_SYS_RESOURCE, CAP_SYS_BOOT,
 477                                 CAP_AUDIT_WRITE,
 478                                 CAP_AUDIT_CONTROL. Also CAP_NET_ADMIN
 479                                 is retained if
 480                                 <option>--private-network</option> is
 481                                 specified. If the special value
 482                                 <literal>all</literal> is passed, all
 483                                 capabilities are
 484                                 retained.</para></listitem>
 485                         </varlistentry>
 486
 487                         <varlistentry>
 488                                 <term><option>--drop-capability=</option></term>
 489
 490                                 <listitem><para>Specify one or more
 491                                 additional capabilities to drop for
 492                                 the container. This allows running the
 493                                 container with fewer capabilities than
 494                                 the default (see above).</para></listitem>
 495                         </varlistentry>
 496
 497                         <varlistentry>
 498                                 <term><option>--link-journal=</option></term>
 499
 500                                 <listitem><para>Control whether the
 501                                 container's journal shall be made
 502                                 visible to the host system. If enabled,
 503                                 allows viewing the container's journal
 504                                 files from the host (but not vice
 505                                 versa). Takes one of
 506                                 <literal>no</literal>,
 507                                 <literal>host</literal>,
 508                                 <literal>try-host</literal>,
 509                                 <literal>guest</literal>,
 510                                 <literal>try-guest</literal>,
 511                                 <literal>auto</literal>. If
 512                                 <literal>no</literal>, the journal is
 513                                 not linked. If <literal>host</literal>,
 514                                 the journal files are stored on the
 515                                 host file system (beneath
 516                                 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
 517                                 and the subdirectory is bind-mounted
 518                                 into the container at the same
 519                                 location. If <literal>guest</literal>,
 520                                 the journal files are stored on the
 521                                 guest file system (beneath
 522                                 <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
 523                                 and the subdirectory is symlinked into the host
 524                                 at the same location. <literal>try-host</literal>
 525                                 and <literal>try-guest</literal> do the same
 526                                 but do not fail if the host does not have
 527                                 persistant journalling enabled.
 528                                 If <literal>auto</literal> (the default),
 529                                 and the right subdirectory of
 530                                 <filename>/var/log/journal</filename>
 531                                 exists, it will be bind mounted
 532                                 into the container. If the
 533                                 subdirectory does not exist, no
 534                                 linking is performed. Effectively,
 535                                 booting a container once with
 536                                 <literal>guest</literal> or
 537                                 <literal>host</literal> will link the
 538                                 journal persistently if further on
 539                                 the default of <literal>auto</literal>
 540                                 is used.</para></listitem>
 541                         </varlistentry>
 542
 543                         <varlistentry>
 544                                 <term><option>-j</option></term>
 545
 546                                 <listitem><para>Equivalent to
 547                                 <option>--link-journal=try-guest</option>.</para></listitem>
 548                         </varlistentry>
 549
 550                         <varlistentry>
 551                                 <term><option>--read-only</option></term>
 552
 553                                 <listitem><para>Mount the root file
 554                                 system read-only for the
 555                                 container.</para></listitem>
 556                         </varlistentry>
 557
 558                         <varlistentry>
 559                                 <term><option>--bind=</option></term>
 560                                 <term><option>--bind-ro=</option></term>
 561
 562                                 <listitem><para>Bind mount a file or
 563                                 directory from the host into the
 564                                 container. Either takes a path
 565                                 argument -- in which case the
 566                                 specified path will be mounted from
 567                                 the host to the same path in the
 568                                 container --, or a colon-separated
 569                                 pair of paths -- in which case the
 570                                 first specified path is the source in
 571                                 the host, and the second path is the
 572                                 destination in the container. The
 573                                 <option>--bind-ro=</option> option
 574                                 creates read-only bind
 575                                 mounts.</para></listitem>
 576                         </varlistentry>
 577
 578                         <varlistentry>
 579                                 <term><option>--tmpfs=</option></term>
 580
 581                                 <listitem><para>Mount a tmpfs file
 582                                 system into the container. Takes a
 583                                 single absolute path argument that
 584                                 specifies where to mount the tmpfs
 585                                 instance to (in which case the
 586                                 directory access mode will be chosen
 587                                 as 0755, owned by root/root), or
 588                                 optionally a colon-separated pair of
 589                                 path and mount option string, that is
 590                                 used for mounting (in which case the
 591                                 kernel default for access mode and
 592                                 owner will be chosen, unless otherwise
 593                                 specified). This option is
 594                                 particularly useful for mounting
 595                                 directories such as
 596                                 <filename>/var</filename> as tmpfs, to
 597                                 allow state-less systems, in
 598                                 particular when combined with
 599                                 <option>--read-only</option>.</para></listitem>
 600                         </varlistentry>
 601
 602                         <varlistentry>
 603                                 <term><option>--setenv=</option></term>
 604
 605                                 <listitem><para>Specifies an
 606                                 environment variable assignment to
 607                                 pass to the init process in the
 608                                 container, in the format
 609                                 <literal>NAME=VALUE</literal>. This
 610                                 may be used to override the default
 611                                 variables or to set additional
 612                                 variables. This parameter may be used
 613                                 more than once.</para></listitem>
 614                         </varlistentry>
 615
 616                         <varlistentry>
 617                                 <term><option>--share-system</option></term>
 618
 619                                 <listitem><para>Allows the container
 620                                 to share certain system facilities
 621                                 with the host. More specifically, this
 622                                 turns off PID namespacing, UTS
 623                                 namespacing and IPC namespacing, and
 624                                 thus allows the guest to see and
 625                                 interact more easily with processes
 626                                 outside of the container. Note that
 627                                 using this option makes it impossible
 628                                 to start up a full Operating System in
 629                                 the container, as an init system
 630                                 cannot operate in this mode. It is
 631                                 only useful to run specific programs
 632                                 or applications this way, without
 633                                 involving an init system in the
 634                                 container. This option implies
 635                                 <option>--register=no</option>. This
 636                                 option may not be combined with
 637                                 <option>--boot</option>.</para></listitem>
 638                         </varlistentry>
 639
 640                         <varlistentry>
 641                                 <term><option>--register=</option></term>
 642
 643                                 <listitem><para>Controls whether the
 644                                 container is registered with
 645                                 <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Takes
 646                                 a boolean argument, defaults to
 647                                 <literal>yes</literal>. This option
 648                                 should be enabled when the container
 649                                 runs a full Operating System (more
 650                                 specifically: an init system), and is
 651                                 useful to ensure that the container is
 652                                 accessible via
 653                                 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 654                                 and shown by tools such as
 655                                 <citerefentry project='man-pages'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>. If
 656                                 the container does not run an init
 657                                 system, it is recommended to set this
 658                                 option to <literal>no</literal>. Note
 659                                 that <option>--share-system</option>
 660                                 implies
 661                                 <option>--register=no</option>.
 662                                 </para></listitem>
 663                         </varlistentry>
 664
 665                         <varlistentry>
 666                                 <term><option>--keep-unit</option></term>
 667
 668                                 <listitem><para>Instead of creating a
 669                                 transient scope unit to run the
 670                                 container in, simply register the
 671                                 service or scope unit
 672                                 <command>systemd-nspawn</command> has
 673                                 been invoked in with
 674                                 <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. This
 675                                 has no effect if
 676                                 <option>--register=no</option> is
 677                                 used. This switch should be used if
 678                                 <command>systemd-nspawn</command> is
 679                                 invoked from within a service unit,
 680                                 and the service unit's sole purpose
 681                                 is to run a single
 682                                 <command>systemd-nspawn</command>
 683                                 container. This option is not
 684                                 available if run from a user
 685                                 session.</para></listitem>
 686                         </varlistentry>
 687
 688                         <varlistentry>
 689                                 <term><option>--personality=</option></term>
 690
 691                                 <listitem><para>Control the
 692                                 architecture ("personality") reported
 693                                 by
 694                                 <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 695                                 in the container. Currently, only
 696                                 <literal>x86</literal> and
 697                                 <literal>x86-64</literal> are
 698                                 supported. This is useful when running
 699                                 a 32-bit container on a 64-bit
 700                                 host. If this setting is not used,
 701                                 the personality reported in the
 702                                 container is the same as the one
 703                                 reported on the
 704                                 host.</para></listitem>
 705                         </varlistentry>
 706
 707                         <varlistentry>
 708                                 <term><option>-q</option></term>
 709                                 <term><option>--quiet</option></term>
 710
 711                                 <listitem><para>Turns off any status
 712                                 output by the tool itself. When this
 713                                 switch is used, the only output
 714                                 from nspawn will be the console output
 715                                 of the container OS itself.</para></listitem>
 716                         </varlistentry>
 717
 718                         <varlistentry>
 719                                 <term><option>--volatile</option><replaceable>=MODE</replaceable></term>
 720
 721                                 <listitem><para>Boots the container in
 722                                 volatile mode. When no mode parameter
 723                                 is passed or when mode is specified as
 724                                 <literal>yes</literal> full volatile
 725                                 mode is enabled. This means the root
 726                                 directory is mounted as mostly
 727                                 unpopulated <literal>tmpfs</literal>
 728                                 instance, and
 729                                 <filename>/usr</filename> from the OS
 730                                 tree is mounted into it, read-only
 731                                 (the system thus starts up with
 732                                 read-only OS resources, but pristine
 733                                 state and configuration, any changes
 734                                 to the either are lost on
 735                                 shutdown). When the mode parameter is
 736                                 specified as <literal>state</literal>
 737                                 the OS tree is mounted read-only, but
 738                                 <filename>/var</filename> is mounted
 739                                 as <literal>tmpfs</literal> instance
 740                                 into it (the system thus starts up
 741                                 with read-only OS resources and
 742                                 configuration, but pristine state, any
 743                                 changes to the latter are lost on
 744                                 shutdown). When the mode parameter is
 745                                 specified as <literal>no</literal>
 746                                 (the default) the whole OS tree is
 747                                 made available writable.</para>
 748
 749                                 <para>Note that setting this to
 750                                 <literal>yes</literal> or
 751                                 <literal>state</literal> will only
 752                                 work correctly with operating systems
 753                                 in the container that can boot up with
 754                                 only <filename>/usr</filename>
 755                                 mounted, and are able to populate
 756                                 <filename>/var</filename>
 757                                 automatically, as
 758                                 needed.</para></listitem>
 759                         </varlistentry>
 760
 761                         <xi:include href="standard-options.xml" xpointer="help" />
 762                         <xi:include href="standard-options.xml" xpointer="version" />
 763                 </variablelist>
 764
 765         </refsect1>
 766
 767         <refsect1>
 768                 <title>Examples</title>
 769                 <example>
 770                         <title>Boot a minimal Fedora distribution in a container</title>
 771
 772                         <programlisting># yum -y --releasever=19 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal
 773 # systemd-nspawn -bD /srv/mycontainer</programlisting>
 774
 775                         <para>This installs a minimal Fedora distribution into
 776                         the directory <filename noindex='true'>/srv/mycontainer/</filename> and
 777                         then boots an OS in a namespace container in
 778                         it.</para>
 779                 </example>
 780
 781                 <example>
 782                         <title>Spawn a shell in a container of a minimal Debian unstable distribution</title>
 783
 784                         <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
 785 # systemd-nspawn -D ~/debian-tree/</programlisting>
 786
 787                         <para>This installs a minimal Debian unstable
 788                         distribution into the directory
 789                         <filename>~/debian-tree/</filename> and then spawns a
 790                         shell in a namespace container in it.</para>
 791                 </example>
 792
 793                 <example>
 794                         <title>Boot a minimal Arch Linux distribution in a container</title>
 795
 796                         <programlisting># pacstrap -c -d ~/arch-tree/ base
 797 # systemd-nspawn -bD ~/arch-tree/</programlisting>
 798
 799                         <para>This installs a mimimal Arch Linux distribution into
 800                         the directory <filename>~/arch-tree/</filename> and then
 801                         boots an OS in a namespace container in it.</para>
 802                 </example>
 803
 804                 <example>
 805                         <title>Enable Arch Linux container on boot</title>
 806
 807                         <programlisting># mv ~/arch-tree /var/lib/container/arch
 808 # systemctl enable systemd-nspawn@arch.service
 809 # systemctl start systemd-nspawn@arch.service</programlisting>
 810
 811                         <para>This makes the Arch Linux container part of the
 812                         <filename>multi-user.target</filename> on the host.
 813                         </para>
 814                 </example>
 815
 816                 <example>
 817                         <title>Boot into a <literal>btrfs</literal> snapshot of the host system</title>
 818
 819                         <programlisting># btrfs subvolume snapshot / /.tmp
 820 # systemd-nspawn --private-network -D /.tmp -b</programlisting>
 821
 822                         <para>This runs a copy of the host system in a
 823                         <literal>btrfs</literal> snapshot.</para>
 824                 </example>
 825
 826                 <example>
 827                         <title>Run a container with SELinux sandbox security contexts</title>
 828
 829                         <programlisting># chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container
 830 # 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>
 831                 </example>
 832         </refsect1>
 833
 834         <refsect1>
 835                 <title>Exit status</title>
 836
 837                 <para>The exit code of the program executed in the
 838                 container is returned.</para>
 839         </refsect1>
 840
 841         <refsect1>
 842                 <title>See Also</title>
 843                 <para>
 844                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 845                         <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 846                         <citerefentry project='die-net'><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 847                         <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 848                         <citerefentry project='archlinux'><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 849                         <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 850                         <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 851                 </para>
 852         </refsect1>
 853
 854 </refentry>