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 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   5 %entities;
   6 ]>
   7
   8 <!--
   9   This file is part of systemd.
  10
  11   Copyright 2015 Lennart Poettering
  12
  13   systemd is free software; you can redistribute it and/or modify it
  14   under the terms of the GNU Lesser General Public License as published by
  15   the Free Software Foundation; either version 2.1 of the License, or
  16   (at your option) any later version.
  17
  18   systemd is distributed in the hope that it will be useful, but
  19   WITHOUT ANY WARRANTY; without even the implied warranty of
  20   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  21   Lesser General Public License for more details.
  22
  23   You should have received a copy of the GNU Lesser General Public License
  24   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  25 -->
  26
  27 <refentry id="systemd.nspawn">
  28
  29   <refentryinfo>
  30     <title>systemd.nspawn</title>
  31     <productname>systemd</productname>
  32
  33     <authorgroup>
  34       <author>
  35         <contrib>Developer</contrib>
  36         <firstname>Lennart</firstname>
  37         <surname>Poettering</surname>
  38         <email>lennart@poettering.net</email>
  39       </author>
  40     </authorgroup>
  41   </refentryinfo>
  42
  43   <refmeta>
  44     <refentrytitle>systemd.nspawn</refentrytitle>
  45     <manvolnum>5</manvolnum>
  46   </refmeta>
  47
  48   <refnamediv>
  49     <refname>systemd.nspawn</refname>
  50     <refpurpose>Container settings</refpurpose>
  51   </refnamediv>
  52
  53   <refsynopsisdiv>
  54     <para><filename>/etc/systemd/nspawn/<replaceable>machine</replaceable>.nspawn</filename></para>
  55     <para><filename>/run/systemd/nspawn/<replaceable>machine</replaceable>.nspawn</filename></para>
  56     <para><filename>/var/lib/machines/<replaceable>machine</replaceable>.nspawn</filename></para>
  57   </refsynopsisdiv>
  58
  59   <refsect1>
  60     <title>Description</title>
  61
  62     <para>An nspawn container settings file (suffix
  63     <filename>.nspawn</filename>) encodes additional runtime
  64     information about a local container, and is searched, read and
  65     used by
  66     <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  67     when starting a container. Files of this type are named after the
  68     containers they define settings for. They are optional, and only
  69     required for containers whose execution environment shall differ
  70     from the defaults. Files of this type mostly contain settings that
  71     may also be set on the <command>systemd-nspawn</command> command
  72     line, and make it easier to persistently attach specific settings
  73     to specific containers. The syntax of these files is inspired by
  74     <filename>.desktop</filename> files following the <ulink
  75     url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG
  76     Desktop Entry Specification</ulink>, which in turn are inspired by
  77     Microsoft Windows <filename>.ini</filename> files.</para>
  78
  79     <para>Boolean arguments used in these settings files can be
  80     written in various formats. For positive settings, the strings
  81     <option>1</option>, <option>yes</option>, <option>true</option>
  82     and <option>on</option> are equivalent. For negative settings, the
  83     strings <option>0</option>, <option>no</option>,
  84     <option>false</option> and <option>off</option> are
  85     equivalent.</para>
  86
  87     <para>Empty lines and lines starting with # or ; are
  88     ignored. This may be used for commenting. Lines ending
  89     in a backslash are concatenated with the following
  90     line while reading and the backslash is replaced by a
  91     space character. This may be used to wrap long lines.</para>
  92
  93   </refsect1>
  94
  95   <refsect1>
  96     <title><filename>.nspawn</filename> File Discovery</title>
  97
  98     <para>Files are searched by appending the
  99     <filename>.nspawn</filename> suffix to the machine name of the
 100     container, as specified with the <option>--machine=</option>
 101     switch of <command>systemd-nspawn</command>, or derived from the
 102     directory or image file name. This file is first searched in
 103     <filename>/etc/systemd/nspawn/</filename> and
 104     <filename>/run/systemd/nspawn/</filename>. If found in these
 105     directories, its settings are read and all of them take full effect
 106     (but are possibly overridden by corresponding command line
 107     arguments). If not found, the file will then be searched next to
 108     the image file or in the immediate parent of the root directory of
 109     the container. If the file is found there, only a subset of the
 110     settings will take effect however. All settings that possibly
 111     elevate privileges or grant additional access to resources of the
 112     host (such as files or directories) are ignored. To which options
 113     this applies is documented below.</para>
 114
 115     <para>Persistent settings files created and maintained by the
 116     administrator (and thus trusted) should be placed in
 117     <filename>/etc/systemd/nspawn/</filename>, while automatically
 118     downloaded (and thus potentially untrusted) settings files are
 119     placed in <filename>/var/lib/machines/</filename> instead (next to
 120     the container images), where their security impact is limited. In
 121     order to add privileged settings to <filename>.nspawn</filename>
 122     files acquired from the image vendor, it is recommended to copy the
 123     settings files into <filename>/etc/systemd/nspawn/</filename> and
 124     edit them there, so that the privileged options become
 125     available. The precise algorithm for how the files are searched and
 126     interpreted may be configured with
 127     <command>systemd-nspawn</command>'s <option>--settings=</option>
 128     switch, see
 129     <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 130     for details.</para>
 131   </refsect1>
 132
 133   <refsect1>
 134     <title>[Exec] Section Options</title>
 135
 136     <para>Settings files may include an <literal>[Exec]</literal>
 137     section, which carries various execution parameters:</para>
 138
 139     <variablelist>
 140
 141       <varlistentry>
 142         <term><varname>Boot=</varname></term>
 143
 144         <listitem><para>Takes a boolean argument, which defaults to off. If enabled, <command>systemd-nspawn</command>
 145         will automatically search for an <filename>init</filename> executable and invoke it. In this case, the
 146         specified parameters using <varname>Parameters=</varname> are passed as additional arguments to the
 147         <filename>init</filename> process. This setting corresponds to the <option>--boot</option> switch on the
 148         <command>systemd-nspawn</command> command line. This option may not be combined with
 149         <varname>ProcessTwo=yes</varname>. This option is the default if the
 150         <filename>systemd-nspawn@.service</filename> template unit file is used.</para></listitem>
 151       </varlistentry>
 152
 153       <varlistentry>
 154         <term><varname>ProcessTwo=</varname></term>
 155
 156         <listitem><para>Takes a boolean argument, which defaults to off. If enabled, the specified program is run as
 157         PID 2. A stub init process is run as PID 1. This setting corresponds to the <option>--as-pid2</option> switch
 158         on the <command>systemd-nspawn</command> command line. This option may not be combined with
 159         <varname>Boot=yes</varname>.</para></listitem>
 160       </varlistentry>
 161
 162       <varlistentry>
 163         <term><varname>Parameters=</varname></term>
 164
 165         <listitem><para>Takes a space-separated list of
 166         arguments. This is either a command line, beginning with the
 167         binary name to execute, or – if <varname>Boot=</varname> is
 168         enabled – the list of arguments to pass to the init
 169         process. This setting corresponds to the command line
 170         parameters passed on the <command>systemd-nspawn</command>
 171         command line.</para></listitem>
 172       </varlistentry>
 173
 174       <varlistentry>
 175         <term><varname>Environment=</varname></term>
 176
 177         <listitem><para>Takes an environment variable assignment
 178         consisting of key and value, separated by
 179         <literal>=</literal>. Sets an environment variable for the
 180         main process invoked in the container. This setting may be
 181         used multiple times to set multiple environment variables. It
 182         corresponds to the <option>--setenv=</option> command line
 183         switch.</para></listitem>
 184       </varlistentry>
 185
 186       <varlistentry>
 187         <term><varname>User=</varname></term>
 188
 189         <listitem><para>Takes a UNIX user name. Specifies the user
 190         name to invoke the main process of the container as. This user
 191         must be known in the container's user database. This
 192         corresponds to the <option>--user=</option> command line
 193         switch.</para></listitem>
 194       </varlistentry>
 195
 196       <varlistentry>
 197         <term><varname>WorkingDirectory=</varname></term>
 198
 199         <listitem><para>Selects the working directory for the process invoked in the container. Expects an absolute
 200         path in the container's file system namespace. This corresponds to the <option>--chdir=</option> command line
 201         switch.</para></listitem>
 202       </varlistentry>
 203
 204       <varlistentry>
 205         <term><varname>PivotRoot=</varname></term>
 206
 207         <listitem><para>Selects a directory to pivot to <filename>/</filename> inside the container when starting up.
 208         Takes a single path, or a pair of two paths separated by a colon. Both paths must be absolute, and are resolved
 209         in the container's file system namespace. This corresponds to the <option>--pivot-root=</option> command line
 210         switch.</para></listitem>
 211       </varlistentry>
 212
 213       <varlistentry>
 214         <term><varname>Capability=</varname></term>
 215         <term><varname>DropCapability=</varname></term>
 216
 217         <listitem><para>Takes a space-separated list of Linux process
 218         capabilities (see
 219         <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 220         for details). The <varname>Capability=</varname> setting
 221         specifies additional capabilities to pass on top of the
 222         default set of capabilities. The
 223         <varname>DropCapability=</varname> setting specifies
 224         capabilities to drop from the default set. These settings
 225         correspond to the <option>--capability=</option> and
 226         <option>--drop-capability=</option> command line
 227         switches. Note that <varname>Capability=</varname> is a
 228         privileged setting, and only takes effect in
 229         <filename>.nspawn</filename> files in
 230         <filename>/etc/systemd/nspawn/</filename> and
 231         <filename>/run/system/nspawn/</filename> (see above). On the
 232         other hand, <varname>DropCapability=</varname> takes effect in
 233         all cases.</para></listitem>
 234       </varlistentry>
 235
 236       <varlistentry>
 237         <term><varname>KillSignal=</varname></term>
 238
 239         <listitem><para>Specify the process signal to send to the
 240         container's PID 1 when nspawn itself receives SIGTERM, in
 241         order to trigger an orderly shutdown of the container.
 242         Defaults to SIGRTMIN+3 if <option>Boot=</option> is used
 243         (on systemd-compatible init systems SIGRTMIN+3 triggers an
 244         orderly shutdown). For a list of valid signals, see
 245         <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para></listitem>
 246       </varlistentry>
 247
 248       <varlistentry>
 249         <term><varname>Personality=</varname></term>
 250
 251         <listitem><para>Configures the kernel personality for the
 252         container. This is equivalent to the
 253         <option>--personality=</option> switch.</para></listitem>
 254       </varlistentry>
 255
 256       <varlistentry>
 257         <term><varname>MachineID=</varname></term>
 258
 259         <listitem><para>Configures the 128-bit machine ID (UUID) to pass to
 260         the container. This is equivalent to the
 261         <option>--uuid=</option> command line switch. This option is
 262         privileged (see above). </para></listitem>
 263       </varlistentry>
 264
 265       <varlistentry>
 266         <term><varname>PrivateUsers=</varname></term>
 267
 268         <listitem><para>Configures support for usernamespacing. This is equivalent to the
 269         <option>--private-users=</option> command line switch, and takes the same options. This option is privileged
 270         (see above). This option is the default if the <filename>systemd-nspawn@.service</filename> template unit file
 271         is used.</para></listitem>
 272       </varlistentry>
 273
 274       <varlistentry>
 275         <term><varname>NotifyReady=</varname></term>
 276
 277         <listitem><para>Configures support for notifications from the container's init process.  This is equivalent to
 278         the <option>--notify-ready=</option> command line switch, and takes the same paramaters. See
 279         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> for details
 280         about the specific options supported.</para></listitem>
 281       </varlistentry>
 282
 283       <varlistentry>
 284         <term><varname>SystemCallFilter=</varname></term>
 285
 286         <listitem><para>Configures the system call filter applied to containers. This is equivalent to the
 287         <option>--system-call-filter=</option> command line switch, and takes the same list parameter. See
 288         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
 289         details.</para></listitem>
 290       </varlistentry>
 291
 292     </variablelist>
 293   </refsect1>
 294
 295   <refsect1>
 296     <title>[Files] Section Options</title>
 297
 298     <para>Settings files may include a <literal>[Files]</literal>
 299     section, which carries various parameters configuring the file
 300     system of the container:</para>
 301
 302     <variablelist>
 303
 304       <varlistentry>
 305         <term><varname>ReadOnly=</varname></term>
 306
 307         <listitem><para>Takes a boolean argument, which defaults to off. If
 308         specified, the container will be run with a read-only file
 309         system. This setting corresponds to the
 310         <option>--read-only</option> command line
 311         switch.</para></listitem>
 312       </varlistentry>
 313
 314       <varlistentry>
 315         <term><varname>Volatile=</varname></term>
 316
 317         <listitem><para>Takes a boolean argument, or the special value
 318         <literal>state</literal>. This configures whether to run the
 319         container with volatile state and/or configuration. This
 320         option is equivalent to <option>--volatile=</option>, see
 321         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 322         for details about the specific options
 323         supported.</para></listitem>
 324       </varlistentry>
 325
 326       <varlistentry>
 327         <term><varname>Bind=</varname></term>
 328         <term><varname>BindReadOnly=</varname></term>
 329
 330         <listitem><para>Adds a bind mount from the host into the
 331         container. Takes a single path, a pair of two paths separated
 332         by a colon, or a triplet of two paths plus an option string
 333         separated by colons. This option may be used multiple times to
 334         configure multiple bind mounts. This option is equivalent to
 335         the command line switches <option>--bind=</option> and
 336         <option>--bind-ro=</option>, see
 337         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 338         for details about the specific options supported. This setting
 339         is privileged (see above).</para></listitem>
 340       </varlistentry>
 341
 342       <varlistentry>
 343         <term><varname>TemporaryFileSystem=</varname></term>
 344
 345         <listitem><para>Adds a <literal>tmpfs</literal> mount to the
 346         container. Takes a path or a pair of path and option string,
 347         separated by a colon. This option may be used multiple times to
 348         configure multiple <literal>tmpfs</literal> mounts. This
 349         option is equivalent to the command line switch
 350         <option>--tmpfs=</option>, see
 351         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 352         for details about the specific options supported. This setting
 353         is privileged (see above).</para></listitem>
 354       </varlistentry>
 355
 356       <varlistentry>
 357         <term><varname>Overlay=</varname></term>
 358         <term><varname>OverlayReadOnly=</varname></term>
 359
 360         <listitem><para>Adds an overlay mount point. Takes a colon-separated list of paths.  This option may be used
 361         multiple times to configure multiple overlay mounts. This option is equivalent to the command line switches
 362         <option>--overlay=</option> and <option>--overlay-ro=</option>, see
 363         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> for details
 364         about the specific options supported. This setting is privileged (see above).</para></listitem>
 365       </varlistentry>
 366
 367       <varlistentry>
 368         <term><varname>PrivateUsersChown=</varname></term>
 369
 370         <listitem><para>Configures whether the ownership of the files and directories in the container tree shall be
 371         adjusted to the UID/GID range used, if necessary and user namespacing is enabled. This is equivalent to the
 372         <option>--private-users-chown</option> command line switch. This option is privileged (see
 373         above). </para></listitem>
 374       </varlistentry>
 375
 376     </variablelist>
 377   </refsect1>
 378
 379   <refsect1>
 380     <title>[Network] Section Options</title>
 381
 382     <para>Settings files may include a <literal>[Network]</literal>
 383     section, which carries various parameters configuring the network
 384     connectivity of the container:</para>
 385
 386     <variablelist>
 387
 388       <varlistentry>
 389         <term><varname>Private=</varname></term>
 390
 391         <listitem><para>Takes a boolean argument, which defaults to off. If
 392         enabled, the container will run in its own network namespace
 393         and not share network interfaces and configuration with the
 394         host. This setting corresponds to the
 395         <option>--private-network</option> command line
 396         switch.</para></listitem>
 397       </varlistentry>
 398
 399       <varlistentry>
 400         <term><varname>VirtualEthernet=</varname></term>
 401
 402         <listitem><para>Takes a boolean argument. Configures whether to create a virtual Ethernet connection
 403         (<literal>veth</literal>) between host and the container. This setting implies
 404         <varname>Private=yes</varname>. This setting corresponds to the <option>--network-veth</option> command line
 405         switch. This option is privileged (see above). This option is the default if the
 406         <filename>systemd-nspawn@.service</filename> template unit file is used.</para></listitem>
 407       </varlistentry>
 408
 409       <varlistentry>
 410         <term><varname>VirtualEthernetExtra=</varname></term>
 411
 412         <listitem><para>Takes a colon-separated pair of interface
 413         names. Configures an additional virtual Ethernet connection
 414         (<literal>veth</literal>) between host and the container. The
 415         first specified name is the interface name on the host, the
 416         second the interface name in the container. The latter may be
 417         omitted in which case it is set to the same name as the host
 418         side interface. This setting implies
 419         <varname>Private=yes</varname>. This setting corresponds to
 420         the <option>--network-veth-extra=</option> command line
 421         switch, and maybe be used multiple times. It is independent of
 422         <varname>VirtualEthernet=</varname>. This option is privileged
 423         (see above).</para></listitem>
 424       </varlistentry>
 425
 426       <varlistentry>
 427         <term><varname>Interface=</varname></term>
 428
 429         <listitem><para>Takes a space-separated list of interfaces to
 430         add to the container. This option corresponds to the
 431         <option>--network-interface=</option> command line switch and
 432         implies <varname>Private=yes</varname>. This option is
 433         privileged (see above).</para></listitem>
 434       </varlistentry>
 435
 436       <varlistentry>
 437         <term><varname>MACVLAN=</varname></term>
 438         <term><varname>IPVLAN=</varname></term>
 439
 440         <listitem><para>Takes a space-separated list of interfaces to
 441         add MACLVAN or IPVLAN interfaces to, which are then added to
 442         the container. These options correspond to the
 443         <option>--network-macvlan=</option> and
 444         <option>--network-ipvlan=</option> command line switches and
 445         imply <varname>Private=yes</varname>. These options are
 446         privileged (see above).</para></listitem>
 447       </varlistentry>
 448
 449       <varlistentry>
 450         <term><varname>Bridge=</varname></term>
 451
 452         <listitem><para>Takes an interface name. This setting implies
 453         <varname>VirtualEthernet=yes</varname> and
 454         <varname>Private=yes</varname> and has the effect that the
 455         host side of the created virtual Ethernet link is connected to
 456         the specified bridge interface. This option corresponds to the
 457         <option>--network-bridge=</option> command line switch. This
 458         option is privileged (see above).</para></listitem>
 459       </varlistentry>
 460
 461       <varlistentry>
 462         <term><varname>Zone=</varname></term>
 463
 464         <listitem><para>Takes a network zone name. This setting implies <varname>VirtualEthernet=yes</varname> and
 465         <varname>Private=yes</varname> and has the effect that the host side of the created virtual Ethernet link is
 466         connected to an automatically managed bridge interface named after the passed argument, prefixed with
 467         <literal>vz-</literal>. This option corresponds to the <option>--network-zone=</option> command line
 468         switch. This option is privileged (see above).</para></listitem>
 469       </varlistentry>
 470
 471       <varlistentry>
 472         <term><varname>Port=</varname></term>
 473
 474         <listitem><para>Exposes a TCP or UDP port of the container on
 475         the host. This option corresponds to the
 476         <option>--port=</option> command line switch, see
 477         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 478         for the precise syntax of the argument this option takes. This
 479         option is privileged (see above).</para></listitem>
 480       </varlistentry>
 481     </variablelist>
 482   </refsect1>
 483
 484   <refsect1>
 485     <title>See Also</title>
 486     <para>
 487       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 488       <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 489       <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 490     </para>
 491   </refsect1>
 492
 493 </refentry>