man/systemd-nspawn.xml

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