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). For a list of valid signals, see
 599         <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para></listitem>
 600       </varlistentry>
 601
 602       <varlistentry>
 603         <term><option>--link-journal=</option></term>
 604
 605         <listitem><para>Control whether the container's journal shall
 606         be made visible to the host system. If enabled, allows viewing
 607         the container's journal files from the host (but not vice
 608         versa). Takes one of <literal>no</literal>,
 609         <literal>host</literal>, <literal>try-host</literal>,
 610         <literal>guest</literal>, <literal>try-guest</literal>,
 611         <literal>auto</literal>. If <literal>no</literal>, the journal
 612         is not linked. If <literal>host</literal>, the journal files
 613         are stored on the host file system (beneath
 614         <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
 615         and the subdirectory is bind-mounted into the container at the
 616         same location. If <literal>guest</literal>, the journal files
 617         are stored on the guest file system (beneath
 618         <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
 619         and the subdirectory is symlinked into the host at the same
 620         location. <literal>try-host</literal> and
 621         <literal>try-guest</literal> do the same but do not fail if
 622         the host does not have persistent journalling enabled. If
 623         <literal>auto</literal> (the default), and the right
 624         subdirectory of <filename>/var/log/journal</filename> exists,
 625         it will be bind mounted into the container. If the
 626         subdirectory does not exist, no linking is performed.
 627         Effectively, booting a container once with
 628         <literal>guest</literal> or <literal>host</literal> will link
 629         the journal persistently if further on the default of
 630         <literal>auto</literal> is used.</para></listitem>
 631       </varlistentry>
 632
 633       <varlistentry>
 634         <term><option>-j</option></term>
 635
 636         <listitem><para>Equivalent to
 637         <option>--link-journal=try-guest</option>.</para></listitem>
 638       </varlistentry>
 639
 640       <varlistentry>
 641         <term><option>--read-only</option></term>
 642
 643         <listitem><para>Mount the root file system read-only for the
 644         container.</para></listitem>
 645       </varlistentry>
 646
 647       <varlistentry>
 648         <term><option>--bind=</option></term>
 649         <term><option>--bind-ro=</option></term>
 650
 651         <listitem><para>Bind mount a file or directory from the host
 652         into the container. Takes one of: a path argument — in which
 653         case the specified path will be mounted from the host to the
 654         same path in the container —, or a colon-separated pair of
 655         paths — in which case the first specified path is the source
 656         in the host, and the second path is the destination in the
 657         container —, or a colon-separated triple of source path,
 658         destination path and mount options. Mount options are
 659         comma-separated and currently, only "rbind" and "norbind"
 660         are allowed. Defaults to "rbind". Backslash escapes are interpreted, so
 661         <literal>\:</literal> may be used to embed colons in either path.
 662         This option may be specified multiple times for
 663         creating multiple independent bind mount points. The
 664         <option>--bind-ro=</option> option creates read-only bind
 665         mounts.</para></listitem>
 666       </varlistentry>
 667
 668       <varlistentry>
 669         <term><option>--tmpfs=</option></term>
 670
 671         <listitem><para>Mount a tmpfs file system into the container.
 672         Takes a single absolute path argument that specifies where to
 673         mount the tmpfs instance to (in which case the directory
 674         access mode will be chosen as 0755, owned by root/root), or
 675         optionally a colon-separated pair of path and mount option
 676         string that is used for mounting (in which case the kernel
 677         default for access mode and owner will be chosen, unless
 678         otherwise specified). This option is particularly useful for
 679         mounting directories such as <filename>/var</filename> as
 680         tmpfs, to allow state-less systems, in particular when
 681         combined with <option>--read-only</option>.
 682         Backslash escapes are interpreted in the path, so
 683         <literal>\:</literal> may be used to embed colons in the path.
 684         </para></listitem>
 685       </varlistentry>
 686
 687       <varlistentry>
 688         <term><option>--overlay=</option></term>
 689         <term><option>--overlay-ro=</option></term>
 690
 691         <listitem><para>Combine multiple directory trees into one
 692         overlay file system and mount it into the container. Takes a
 693         list of colon-separated paths to the directory trees to
 694         combine and the destination mount point.</para>
 695
 696         <para>Backslash escapes are interpreted in the paths, so
 697         <literal>\:</literal> may be used to embed colons in the paths.
 698         </para>
 699
 700         <para>If three or more paths are specified, then the last
 701         specified path is the destination mount point in the
 702         container, all paths specified before refer to directory trees
 703         on the host and are combined in the specified order into one
 704         overlay file system. The left-most path is hence the lowest
 705         directory tree, the second-to-last path the highest directory
 706         tree in the stacking order. If <option>--overlay-ro=</option>
 707         is used instead of <option>--overlay=</option>, a read-only
 708         overlay file system is created. If a writable overlay file
 709         system is created, all changes made to it are written to the
 710         highest directory tree in the stacking order, i.e. the
 711         second-to-last specified.</para>
 712
 713         <para>If only two paths are specified, then the second
 714         specified path is used both as the top-level directory tree in
 715         the stacking order as seen from the host, as well as the mount
 716         point for the overlay file system in the container. At least
 717         two paths have to be specified.</para>
 718
 719         <para>For details about overlay file systems, see <ulink
 720         url="https://www.kernel.org/doc/Documentation/filesystems/overlayfs.txt">overlayfs.txt</ulink>. Note
 721         that the semantics of overlay file systems are substantially
 722         different from normal file systems, in particular regarding
 723         reported device and inode information. Device and inode
 724         information may change for a file while it is being written
 725         to, and processes might see out-of-date versions of files at
 726         times. Note that this switch automatically derives the
 727         <literal>workdir=</literal> mount option for the overlay file
 728         system from the top-level directory tree, making it a sibling
 729         of it. It is hence essential that the top-level directory tree
 730         is not a mount point itself (since the working directory must
 731         be on the same file system as the top-most directory
 732         tree). Also note that the <literal>lowerdir=</literal> mount
 733         option receives the paths to stack in the opposite order of
 734         this switch.</para></listitem>
 735       </varlistentry>
 736
 737       <varlistentry>
 738         <term><option>--setenv=</option></term>
 739
 740         <listitem><para>Specifies an environment variable assignment
 741         to pass to the init process in the container, in the format
 742         <literal>NAME=VALUE</literal>. This may be used to override
 743         the default variables or to set additional variables. This
 744         parameter may be used more than once.</para></listitem>
 745       </varlistentry>
 746
 747       <varlistentry>
 748         <term><option>--share-system</option></term>
 749
 750         <listitem><para>Allows the container to share certain system
 751         facilities with the host. More specifically, this turns off
 752         PID namespacing, UTS namespacing and IPC namespacing, and thus
 753         allows the guest to see and interact more easily with
 754         processes outside of the container. Note that using this
 755         option makes it impossible to start up a full Operating System
 756         in the container, as an init system cannot operate in this
 757         mode. It is only useful to run specific programs or
 758         applications this way, without involving an init system in the
 759         container. This option implies <option>--register=no</option>.
 760         This option may not be combined with
 761         <option>--boot</option>.</para></listitem>
 762       </varlistentry>
 763
 764       <varlistentry>
 765         <term><option>--register=</option></term>
 766
 767         <listitem><para>Controls whether the container is registered
 768         with
 769         <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 770         Takes a boolean argument, which defaults to <literal>yes</literal>.
 771         This option should be enabled when the container runs a full
 772         Operating System (more specifically: an init system), and is
 773         useful to ensure that the container is accessible via
 774         <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 775         and shown by tools such as
 776         <citerefentry project='man-pages'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 777         If the container does not run an init system, it is
 778         recommended to set this option to <literal>no</literal>. Note
 779         that <option>--share-system</option> implies
 780         <option>--register=no</option>. </para></listitem>
 781       </varlistentry>
 782
 783       <varlistentry>
 784         <term><option>--keep-unit</option></term>
 785
 786         <listitem><para>Instead of creating a transient scope unit to
 787         run the container in, simply register the service or scope
 788         unit <command>systemd-nspawn</command> has been invoked in
 789         with
 790         <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 791         This has no effect if <option>--register=no</option> is used.
 792         This switch should be used if
 793         <command>systemd-nspawn</command> is invoked from within a
 794         service unit, and the service unit's sole purpose is to run a
 795         single <command>systemd-nspawn</command> container. This
 796         option is not available if run from a user
 797         session.</para></listitem>
 798       </varlistentry>
 799
 800       <varlistentry>
 801         <term><option>--personality=</option></term>
 802
 803         <listitem><para>Control the architecture ("personality")
 804         reported by
 805         <citerefentry project='man-pages'><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 806         in the container. Currently, only <literal>x86</literal> and
 807         <literal>x86-64</literal> are supported. This is useful when
 808         running a 32-bit container on a 64-bit host. If this setting
 809         is not used, the personality reported in the container is the
 810         same as the one reported on the host.</para></listitem>
 811       </varlistentry>
 812
 813       <varlistentry>
 814         <term><option>-q</option></term>
 815         <term><option>--quiet</option></term>
 816
 817         <listitem><para>Turns off any status output by the tool
 818         itself. When this switch is used, the only output from nspawn
 819         will be the console output of the container OS
 820         itself.</para></listitem>
 821       </varlistentry>
 822
 823       <varlistentry>
 824         <term><option>--volatile</option></term>
 825         <term><option>--volatile=</option><replaceable>MODE</replaceable></term>
 826
 827         <listitem><para>Boots the container in volatile mode. When no
 828         mode parameter is passed or when mode is specified as
 829         <option>yes</option>, full volatile mode is enabled. This
 830         means the root directory is mounted as a mostly unpopulated
 831         <literal>tmpfs</literal> instance, and
 832         <filename>/usr</filename> from the OS tree is mounted into it
 833         in read-only mode (the system thus starts up with read-only OS
 834         resources, but pristine state and configuration, any changes
 835         to the either are lost on shutdown). When the mode parameter
 836         is specified as <option>state</option>, the OS tree is
 837         mounted read-only, but <filename>/var</filename> is mounted as
 838         a <literal>tmpfs</literal> instance into it (the system thus
 839         starts up with read-only OS resources and configuration, but
 840         pristine state, and any changes to the latter are lost on
 841         shutdown). When the mode parameter is specified as
 842         <option>no</option> (the default), the whole OS tree is made
 843         available writable.</para>
 844
 845         <para>Note that setting this to <option>yes</option> or
 846         <option>state</option> will only work correctly with
 847         operating systems in the container that can boot up with only
 848         <filename>/usr</filename> mounted, and are able to populate
 849         <filename>/var</filename> automatically, as
 850         needed.</para></listitem>
 851       </varlistentry>
 852
 853       <varlistentry>
 854         <term><option>--settings=</option><replaceable>MODE</replaceable></term>
 855
 856         <listitem><para>Controls whether
 857         <command>systemd-nspawn</command> shall search for and use
 858         additional per-container settings from
 859         <filename>.nspawn</filename> files. Takes a boolean or the
 860         special values <option>override</option> or
 861         <option>trusted</option>.</para>
 862
 863         <para>If enabled (the default), a settings file named after the
 864         machine (as specified with the <option>--machine=</option>
 865         setting, or derived from the directory or image file name)
 866         with the suffix <filename>.nspawn</filename> is searched in
 867         <filename>/etc/systemd/nspawn/</filename> and
 868         <filename>/run/systemd/nspawn/</filename>. If it is found
 869         there, its settings are read and used. If it is not found
 870         there, it is subsequently searched in the same directory as the
 871         image file or in the immediate parent of the root directory of
 872         the container. In this case, if the file is found, its settings
 873         will be also read and used, but potentially unsafe settings
 874         are ignored. Note that in both these cases, settings on the
 875         command line take precedence over the corresponding settings
 876         from loaded <filename>.nspawn</filename> files, if both are
 877         specified. Unsafe settings are considered all settings that
 878         elevate the container's privileges or grant access to
 879         additional resources such as files or directories of the
 880         host. For details about the format and contents of
 881         <filename>.nspawn</filename> files, consult
 882         <citerefentry><refentrytitle>systemd.nspawn</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 883
 884         <para>If this option is set to <option>override</option>, the
 885         file is searched, read and used the same way, however, the order of
 886         precedence is reversed: settings read from the
 887         <filename>.nspawn</filename> file will take precedence over
 888         the corresponding command line options, if both are
 889         specified.</para>
 890
 891         <para>If this option is set to <option>trusted</option>, the
 892         file is searched, read and used the same way, but regardless
 893         of being found in <filename>/etc/systemd/nspawn/</filename>,
 894         <filename>/run/systemd/nspawn/</filename> or next to the image
 895         file or container root directory, all settings will take
 896         effect, however, command line arguments still take precedence
 897         over corresponding settings.</para>
 898
 899         <para>If disabled, no <filename>.nspawn</filename> file is read
 900         and no settings except the ones on the command line are in
 901         effect.</para></listitem>
 902       </varlistentry>
 903
 904       <xi:include href="standard-options.xml" xpointer="help" />
 905       <xi:include href="standard-options.xml" xpointer="version" />
 906     </variablelist>
 907
 908   </refsect1>
 909
 910   <refsect1>
 911     <title>Examples</title>
 912
 913     <example>
 914       <title>Download a Fedora image and start a shell in it</title>
 915
 916       <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
 917 # systemd-nspawn -M Fedora-Cloud-Base-20141203-21</programlisting>
 918
 919       <para>This downloads an image using
 920       <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 921       and opens a shell in it.</para>
 922     </example>
 923
 924     <example>
 925       <title>Build and boot a minimal Fedora distribution in a container</title>
 926
 927       <programlisting># dnf -y --releasever=23 --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora --enablerepo=updates install systemd passwd dnf fedora-release vim-minimal
 928 # systemd-nspawn -bD /srv/mycontainer</programlisting>
 929
 930       <para>This installs a minimal Fedora distribution into the
 931       directory <filename noindex='true'>/srv/mycontainer/</filename>
 932       and then boots an OS in a namespace container in it.</para>
 933     </example>
 934
 935     <example>
 936       <title>Spawn a shell in a container of a minimal Debian unstable distribution</title>
 937
 938       <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
 939 # systemd-nspawn -D ~/debian-tree/</programlisting>
 940
 941       <para>This installs a minimal Debian unstable distribution into
 942       the directory <filename>~/debian-tree/</filename> and then
 943       spawns a shell in a namespace container in it.</para>
 944     </example>
 945
 946     <example>
 947       <title>Boot a minimal Arch Linux distribution in a container</title>
 948
 949       <programlisting># pacstrap -c -d ~/arch-tree/ base
 950 # systemd-nspawn -bD ~/arch-tree/</programlisting>
 951
 952       <para>This installs a minimal Arch Linux distribution into the
 953       directory <filename>~/arch-tree/</filename> and then boots an OS
 954       in a namespace container in it.</para>
 955     </example>
 956
 957     <example>
 958       <title>Boot into an ephemeral <literal>btrfs</literal> snapshot of the host system</title>
 959
 960       <programlisting># systemd-nspawn -D / -xb</programlisting>
 961
 962       <para>This runs a copy of the host system in a
 963       <literal>btrfs</literal> snapshot which is removed immediately
 964       when the container exits. All file system changes made during
 965       runtime will be lost on shutdown, hence.</para>
 966     </example>
 967
 968     <example>
 969       <title>Run a container with SELinux sandbox security contexts</title>
 970
 971       <programlisting># chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container
 972 # 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>
 973     </example>
 974   </refsect1>
 975
 976   <refsect1>
 977     <title>Exit status</title>
 978
 979     <para>The exit code of the program executed in the container is
 980     returned.</para>
 981   </refsect1>
 982
 983   <refsect1>
 984     <title>See Also</title>
 985     <para>
 986       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 987       <citerefentry><refentrytitle>systemd.nspawn</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 988       <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 989       <citerefentry project='mankier'><refentrytitle>dnf</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 990       <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 991       <citerefentry project='archlinux'><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 992       <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 993       <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 994       <citerefentry project='man-pages'><refentrytitle>btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 995     </para>
 996   </refsect1>
 997
 998 </refentry>