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