man/systemd.nspawn.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
   4 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   5 %entities;
   6 ]>
   7 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   8
   9 <refentry id="systemd.nspawn" xmlns:xi="http://www.w3.org/2001/XInclude">
  10
  11   <refentryinfo>
  12     <title>systemd.nspawn</title>
  13     <productname>systemd</productname>
  14   </refentryinfo>
  15
  16   <refmeta>
  17     <refentrytitle>systemd.nspawn</refentrytitle>
  18     <manvolnum>5</manvolnum>
  19   </refmeta>
  20
  21   <refnamediv>
  22     <refname>systemd.nspawn</refname>
  23     <refpurpose>Container settings</refpurpose>
  24   </refnamediv>
  25
  26   <refsynopsisdiv>
  27     <para><simplelist>
  28       <member><filename>/etc/systemd/nspawn/<replaceable>machine</replaceable>.nspawn</filename></member>
  29       <member><filename>/run/systemd/nspawn/<replaceable>machine</replaceable>.nspawn</filename></member>
  30       <member><filename>/var/lib/machines/<replaceable>machine</replaceable>.nspawn</filename></member>
  31     </simplelist></para>
  32   </refsynopsisdiv>
  33
  34   <refsect1>
  35     <title>Description</title>
  36
  37     <para>An nspawn container settings file (suffix <filename>.nspawn</filename>) contains runtime
  38     configuration for a local container, and is used by
  39     <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
  40     Files of this type are named after the containers they define settings for. They are optional, and only
  41     required for containers whose execution environment shall differ from the defaults. Files of this type
  42     mostly contain settings that may also be set on the <command>systemd-nspawn</command> command line, and
  43     make it easier to persistently attach specific settings to specific containers. The syntax of these files
  44     is inspired by <filename>.desktop</filename> files, similarly to other configuration files supported by
  45     the systemd project. See
  46     <citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>7</manvolnum></citerefentry> for an
  47     overview.</para>
  48   </refsect1>
  49
  50   <refsect1>
  51     <title><filename>.nspawn</filename> File Discovery</title>
  52
  53     <para>Files are searched for by appending the <filename>.nspawn</filename> suffix to the machine name of
  54     the container, as specified with the <option>--machine=</option> switch of
  55     <command>systemd-nspawn</command>, or derived from the directory or image file name. This file is first
  56     searched for in <filename>/etc/systemd/nspawn/</filename> and
  57     <filename>/run/systemd/nspawn/</filename>. If found there, the settings are read and all of them take
  58     full effect (but may still be overridden by corresponding command line arguments). Otherwise, the file
  59     will then be searched for next to the image file or in the immediate parent of the root directory of the
  60     container. If the file is found there, only a subset of the settings will take effect however. All
  61     settings that possibly elevate privileges or grant additional access to resources of the host (such as
  62     files or directories) are ignored. To which options this applies is documented below.</para>
  63
  64     <para>Persistent settings files created and maintained by the
  65     administrator (and thus trusted) should be placed in
  66     <filename>/etc/systemd/nspawn/</filename>, while automatically
  67     downloaded (and thus potentially untrusted) settings files are
  68     placed in <filename>/var/lib/machines/</filename> instead (next to
  69     the container images), where their security impact is limited. In
  70     order to add privileged settings to <filename>.nspawn</filename>
  71     files acquired from the image vendor, it is recommended to copy the
  72     settings files into <filename>/etc/systemd/nspawn/</filename> and
  73     edit them there, so that the privileged options become
  74     available. The precise algorithm for how the files are searched and
  75     interpreted may be configured with
  76     <command>systemd-nspawn</command>'s <option>--settings=</option>
  77     switch, see
  78     <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  79     for details.</para>
  80   </refsect1>
  81
  82   <refsect1>
  83     <title>[Exec] Section Options</title>
  84
  85     <para>Settings files may include an [Exec]
  86     section, which carries various execution parameters:</para>
  87
  88     <variablelist class='nspawn-directives'>
  89
  90       <varlistentry>
  91         <term><varname>Boot=</varname></term>
  92
  93         <listitem><para>Takes a boolean argument, which defaults to off. If enabled, <command>systemd-nspawn</command>
  94         will automatically search for an <filename>init</filename> executable and invoke it. In this case, the
  95         specified parameters using <varname>Parameters=</varname> are passed as additional arguments to the
  96         <filename>init</filename> process. This setting corresponds to the <option>--boot</option> switch on the
  97         <command>systemd-nspawn</command> command line. This option may not be combined with
  98         <varname>ProcessTwo=yes</varname>. This option is specified by default in the
  99         <filename>systemd-nspawn@.service</filename> template unit.</para>
 100
 101         <xi:include href="version-info.xml" xpointer="v226"/></listitem>
 102       </varlistentry>
 103
 104       <varlistentry>
 105         <term><varname>Ephemeral=</varname></term>
 106
 107         <listitem><para>Takes a boolean argument, which defaults to off, If enabled, the container is run with
 108         a temporary snapshot of its file system that is removed immediately when the container terminates.
 109         This is equivalent to the <option>--ephemeral</option> command line switch. See
 110         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> for details
 111         about the specific options supported.</para>
 112
 113         <xi:include href="version-info.xml" xpointer="v240"/></listitem>
 114       </varlistentry>
 115
 116       <varlistentry>
 117         <term><varname>ProcessTwo=</varname></term>
 118
 119         <listitem><para>Takes a boolean argument, which defaults to off. If enabled, the specified program is run as
 120         PID 2. A stub init process is run as PID 1. This setting corresponds to the <option>--as-pid2</option> switch
 121         on the <command>systemd-nspawn</command> command line. This option may not be combined with
 122         <varname>Boot=yes</varname>.</para>
 123
 124         <xi:include href="version-info.xml" xpointer="v229"/></listitem>
 125       </varlistentry>
 126
 127       <varlistentry>
 128         <term><varname>Parameters=</varname></term>
 129
 130         <listitem><para>Takes a whitespace-separated list of arguments. Single (<literal>'</literal>) and
 131         double (<literal>"</literal>) quotes may be used around arguments with whitespace. This is either a
 132         command line, beginning with the binary name to execute, or – if <varname>Boot=</varname> is enabled
 133         – the list of arguments to pass to the init process. This setting corresponds to the command line
 134         parameters passed on the <command>systemd-nspawn</command> command line.</para>
 135
 136         <para>Note: <option>Boot=no</option>, <option>Parameters=a b "c c"</option> is the same as
 137         <command>systemd-nspawn a b "c c"</command>, and <option>Boot=yes</option>, <option>Parameters=b 'c c'</option>
 138         is the same as <command>systemd-nspawn --boot b 'c c'</command>.</para>
 139
 140         <xi:include href="version-info.xml" xpointer="v226"/></listitem>
 141       </varlistentry>
 142
 143       <varlistentry>
 144         <term><varname>Environment=</varname></term>
 145
 146         <listitem><para>Takes an environment variable assignment
 147         consisting of key and value, separated by
 148         <literal>=</literal>. Sets an environment variable for the
 149         main process invoked in the container. This setting may be
 150         used multiple times to set multiple environment variables. It
 151         corresponds to the <option>--setenv=</option> command line
 152         switch.</para>
 153
 154         <xi:include href="version-info.xml" xpointer="v226"/></listitem>
 155       </varlistentry>
 156
 157       <varlistentry>
 158         <term><varname>User=</varname></term>
 159
 160         <listitem><para>Takes a UNIX user name. Specifies the user
 161         name to invoke the main process of the container as. This user
 162         must be known in the container's user database. This
 163         corresponds to the <option>--user=</option> command line
 164         switch.</para>
 165
 166         <xi:include href="version-info.xml" xpointer="v226"/></listitem>
 167       </varlistentry>
 168
 169       <varlistentry>
 170         <term><varname>WorkingDirectory=</varname></term>
 171
 172         <listitem><para>Selects the working directory for the process invoked in the container. Expects an absolute
 173         path in the container's file system namespace. This corresponds to the <option>--chdir=</option> command line
 174         switch.</para>
 175
 176         <xi:include href="version-info.xml" xpointer="v229"/></listitem>
 177       </varlistentry>
 178
 179       <varlistentry>
 180         <term><varname>PivotRoot=</varname></term>
 181
 182         <listitem><para>Selects a directory to pivot to <filename>/</filename> inside the container when starting up.
 183         Takes a single path, or a pair of two paths separated by a colon. Both paths must be absolute, and are resolved
 184         in the container's file system namespace. This corresponds to the <option>--pivot-root=</option> command line
 185         switch.</para>
 186
 187         <xi:include href="version-info.xml" xpointer="v233"/></listitem>
 188       </varlistentry>
 189
 190       <varlistentry>
 191         <term><varname>Capability=</varname></term>
 192         <term><varname>DropCapability=</varname></term>
 193
 194         <listitem><para>Takes a space-separated list of Linux process
 195         capabilities (see
 196         <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 197         for details). The <varname>Capability=</varname> setting
 198         specifies additional capabilities to pass on top of the
 199         default set of capabilities. The
 200         <varname>DropCapability=</varname> setting specifies
 201         capabilities to drop from the default set. These settings
 202         correspond to the <option>--capability=</option> and
 203         <option>--drop-capability=</option> command line
 204         switches. Note that <varname>Capability=</varname> is a
 205         privileged setting, and only takes effect in
 206         <filename>.nspawn</filename> files in
 207         <filename>/etc/systemd/nspawn/</filename> and
 208         <filename>/run/system/nspawn/</filename> (see above). On the
 209         other hand, <varname>DropCapability=</varname> takes effect in
 210         all cases. If the special value <literal>all</literal> is passed, all
 211         capabilities are retained (or dropped).</para>
 212         <para>These settings change the bounding set of capabilities which
 213         also limits the ambient capabilities as given with the
 214         <varname>AmbientCapability=</varname>.</para>
 215
 216         <xi:include href="version-info.xml" xpointer="v226"/></listitem>
 217       </varlistentry>
 218
 219       <varlistentry>
 220         <term><varname>AmbientCapability=</varname></term>
 221         <listitem><para>Takes a space-separated list of Linux process
 222         capabilities (see
 223         <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 224         for details). The <varname>AmbientCapability=</varname> setting
 225         specifies capabilities which will be passed to the started program
 226         in the inheritable and ambient capability sets. This will grant
 227         these capabilities to this process. This setting correspond to
 228         the <option>--ambient-capability=</option> command line switch.
 229         </para>
 230
 231         <para>The value <literal>all</literal> is not supported for this
 232         setting.</para>
 233
 234         <para>The setting of <varname>AmbientCapability=</varname> must
 235         be covered by the bounding set settings which were established by
 236         <varname>Capability=</varname> and <varname>DropCapability=</varname>.
 237         </para>
 238
 239         <para>Note that <varname>AmbientCapability=</varname> is a privileged
 240         setting (see above).</para>
 241
 242         <xi:include href="version-info.xml" xpointer="v248"/></listitem>
 243       </varlistentry>
 244
 245       <varlistentry>
 246         <term><varname>NoNewPrivileges=</varname></term>
 247
 248         <listitem><para>Takes a boolean argument that controls the <constant>PR_SET_NO_NEW_PRIVS</constant> flag for
 249         the container payload. This is equivalent to the
 250         <option>--no-new-privileges=</option> command line switch. See
 251         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
 252         details.</para>
 253
 254         <xi:include href="version-info.xml" xpointer="v239"/>
 255         </listitem>
 256       </varlistentry>
 257
 258       <varlistentry>
 259         <term><varname>KillSignal=</varname></term>
 260
 261         <listitem><para>Specify the process signal to send to the
 262         container's PID 1 when nspawn itself receives SIGTERM, in
 263         order to trigger an orderly shutdown of the container.
 264         Defaults to SIGRTMIN+3 if <option>Boot=</option> is used
 265         (on systemd-compatible init systems SIGRTMIN+3 triggers an
 266         orderly shutdown). For a list of valid signals, see
 267         <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
 268
 269         <xi:include href="version-info.xml" xpointer="v230"/></listitem>
 270       </varlistentry>
 271
 272       <varlistentry>
 273         <term><varname>Personality=</varname></term>
 274
 275         <listitem><para>Configures the kernel personality for the
 276         container. This is equivalent to the
 277         <option>--personality=</option> switch.</para>
 278
 279         <xi:include href="version-info.xml" xpointer="v226"/></listitem>
 280       </varlistentry>
 281
 282       <varlistentry>
 283         <term><varname>MachineID=</varname></term>
 284
 285         <listitem><para>Configures the 128-bit machine ID (UUID) to pass to
 286         the container. This is equivalent to the
 287         <option>--uuid=</option> command line switch. This option is
 288         privileged (see above). </para>
 289
 290         <xi:include href="version-info.xml" xpointer="v226"/></listitem>
 291       </varlistentry>
 292
 293       <varlistentry>
 294         <term><varname>PrivateUsers=</varname></term>
 295
 296         <listitem><para>Configures support for usernamespacing. This is equivalent to the
 297         <option>--private-users=</option> command line switch, and takes the same options. This option is privileged
 298         (see above). This option is the default if the <filename>systemd-nspawn@.service</filename> template unit file
 299         is used.</para>
 300
 301         <xi:include href="version-info.xml" xpointer="v230"/></listitem>
 302       </varlistentry>
 303
 304       <varlistentry>
 305         <term><varname>NotifyReady=</varname></term>
 306
 307         <listitem><para>Configures support for notifications from the container's init process.  This is equivalent to
 308         the <option>--notify-ready=</option> command line switch, and takes the same parameters. See
 309         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> for details
 310         about the specific options supported.</para>
 311
 312         <xi:include href="version-info.xml" xpointer="v231"/></listitem>
 313       </varlistentry>
 314
 315       <varlistentry>
 316         <term><varname>SystemCallFilter=</varname></term>
 317
 318         <listitem><para>Configures the system call filter applied to containers. This is equivalent to the
 319         <option>--system-call-filter=</option> command line switch, and takes the same list parameter. See
 320         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
 321         details.</para>
 322
 323         <xi:include href="version-info.xml" xpointer="v235"/></listitem>
 324       </varlistentry>
 325
 326       <varlistentry>
 327         <term><varname>LimitCPU=</varname></term>
 328         <term><varname>LimitFSIZE=</varname></term>
 329         <term><varname>LimitDATA=</varname></term>
 330         <term><varname>LimitSTACK=</varname></term>
 331         <term><varname>LimitCORE=</varname></term>
 332         <term><varname>LimitRSS=</varname></term>
 333         <term><varname>LimitNOFILE=</varname></term>
 334         <term><varname>LimitAS=</varname></term>
 335         <term><varname>LimitNPROC=</varname></term>
 336         <term><varname>LimitMEMLOCK=</varname></term>
 337         <term><varname>LimitLOCKS=</varname></term>
 338         <term><varname>LimitSIGPENDING=</varname></term>
 339         <term><varname>LimitMSGQUEUE=</varname></term>
 340         <term><varname>LimitNICE=</varname></term>
 341         <term><varname>LimitRTPRIO=</varname></term>
 342         <term><varname>LimitRTTIME=</varname></term>
 343
 344         <listitem><para>Configures various types of resource limits applied to containers. This is equivalent to the
 345         <option>--rlimit=</option> command line switch, and takes the same arguments. See
 346         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
 347         details.</para>
 348
 349         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 350       </varlistentry>
 351
 352       <varlistentry>
 353         <term><varname>OOMScoreAdjust=</varname></term>
 354
 355         <listitem><para>Configures the OOM score adjustment value. This is equivalent to the
 356         <option>--oom-score-adjust=</option> command line switch, and takes the same argument. See
 357         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
 358         details.</para>
 359
 360         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 361       </varlistentry>
 362
 363       <varlistentry>
 364         <term><varname>CPUAffinity=</varname></term>
 365
 366         <listitem><para>Configures the CPU affinity. This is equivalent to the <option>--cpu-affinity=</option> command
 367         line switch, and takes the same argument. See
 368         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
 369         details.</para>
 370
 371         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 372       </varlistentry>
 373
 374       <varlistentry>
 375         <term><varname>Hostname=</varname></term>
 376
 377         <listitem><para>Configures the kernel hostname set for the container. This is equivalent to the
 378         <option>--hostname=</option> command line switch, and takes the same argument. See
 379         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
 380         details.</para>
 381
 382         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 383       </varlistentry>
 384
 385       <varlistentry>
 386         <term><varname>ResolvConf=</varname></term>
 387
 388         <listitem><para>Configures how <filename>/etc/resolv.conf</filename> in the container shall be handled. This is
 389         equivalent to the <option>--resolv-conf=</option> command line switch, and takes the same argument. See
 390         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
 391         details.</para>
 392
 393         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 394       </varlistentry>
 395
 396       <varlistentry>
 397         <term><varname>Timezone=</varname></term>
 398
 399         <listitem><para>Configures how <filename>/etc/localtime</filename> in the container shall be handled. This is
 400         equivalent to the <option>--timezone=</option> command line switch, and takes the same argument. See
 401         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
 402         details.</para>
 403
 404         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 405       </varlistentry>
 406
 407       <varlistentry>
 408         <term><varname>LinkJournal=</varname></term>
 409
 410         <listitem><para>Configures how to link host and container journal setups. This is equivalent to the
 411         <option>--link-journal=</option> command line switch, and takes the same parameter. See
 412         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
 413         details.</para>
 414
 415         <xi:include href="version-info.xml" xpointer="v239"/></listitem>
 416       </varlistentry>
 417
 418       <varlistentry>
 419         <term><varname>SuppressSync=</varname></term>
 420
 421         <listitem><para>Configures whether to suppress disk synchronization for the container payload. This
 422         is equivalent to the <option>--suppress-sync=</option> command line switch, and takes the same
 423         parameter. See
 424         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 425         for details.</para>
 426
 427         <xi:include href="version-info.xml" xpointer="v250"/></listitem>
 428       </varlistentry>
 429
 430     </variablelist>
 431   </refsect1>
 432
 433   <refsect1>
 434     <title>[Files] Section Options</title>
 435
 436     <para>Settings files may include a [Files]
 437     section, which carries various parameters configuring the file
 438     system of the container:</para>
 439
 440     <variablelist class='nspawn-directives'>
 441
 442       <varlistentry>
 443         <term><varname>ReadOnly=</varname></term>
 444
 445         <listitem><para>Takes a boolean argument, which defaults to off. If
 446         specified, the container will be run with a read-only file
 447         system. This setting corresponds to the
 448         <option>--read-only</option> command line
 449         switch.</para>
 450
 451         <xi:include href="version-info.xml" xpointer="v226"/></listitem>
 452       </varlistentry>
 453
 454       <varlistentry>
 455         <term><varname>Volatile=</varname></term>
 456
 457         <listitem><para>Takes a boolean argument, or the special value
 458         <literal>state</literal>. This configures whether to run the
 459         container with volatile state and/or configuration. This
 460         option is equivalent to <option>--volatile=</option>, see
 461         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 462         for details about the specific options
 463         supported.</para>
 464
 465         <xi:include href="version-info.xml" xpointer="v226"/></listitem>
 466       </varlistentry>
 467
 468       <varlistentry>
 469         <term><varname>Bind=</varname></term>
 470         <term><varname>BindReadOnly=</varname></term>
 471
 472         <listitem><para>Adds a bind mount from the host into the
 473         container. Takes a single path, a pair of two paths separated
 474         by a colon, or a triplet of two paths plus an option string
 475         separated by colons. This option may be used multiple times to
 476         configure multiple bind mounts. This option is equivalent to
 477         the command line switches <option>--bind=</option> and
 478         <option>--bind-ro=</option>, see
 479         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 480         for details about the specific options supported. This setting
 481         is privileged (see above).</para>
 482
 483         <xi:include href="version-info.xml" xpointer="v226"/></listitem>
 484       </varlistentry>
 485
 486       <varlistentry>
 487         <term><varname>BindUser=</varname></term>
 488
 489         <listitem><para>Binds a user from the host into the container. This option is equivalent to the
 490         command line switch <option>--bind-user=</option>, see
 491         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 492         for details about the specific options supported. This setting is privileged (see
 493         above).</para>
 494
 495         <xi:include href="version-info.xml" xpointer="v249"/></listitem>
 496       </varlistentry>
 497
 498       <varlistentry>
 499         <term><varname>TemporaryFileSystem=</varname></term>
 500
 501         <listitem><para>Adds a <literal>tmpfs</literal> mount to the
 502         container. Takes a path or a pair of path and option string,
 503         separated by a colon. This option may be used multiple times to
 504         configure multiple <literal>tmpfs</literal> mounts. This
 505         option is equivalent to the command line switch
 506         <option>--tmpfs=</option>, see
 507         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 508         for details about the specific options supported. This setting
 509         is privileged (see above).</para>
 510
 511         <xi:include href="version-info.xml" xpointer="v226"/></listitem>
 512       </varlistentry>
 513
 514       <varlistentry>
 515         <term><varname>Inaccessible=</varname></term>
 516
 517         <listitem><para>Masks the specified file or directory in the container, by over-mounting it with an empty file
 518         node of the same type with the most restrictive access mode. Takes a file system path as argument. This option
 519         may be used multiple times to mask multiple files or directories. This option is equivalent to the command line
 520         switch <option>--inaccessible=</option>, see
 521         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> for details
 522         about the specific options supported. This setting is privileged (see above).</para>
 523
 524         <xi:include href="version-info.xml" xpointer="v242"/></listitem>
 525       </varlistentry>
 526
 527       <varlistentry>
 528         <term><varname>Overlay=</varname></term>
 529         <term><varname>OverlayReadOnly=</varname></term>
 530
 531         <listitem><para>Adds an overlay mount point. Takes a colon-separated list of paths.  This option may be used
 532         multiple times to configure multiple overlay mounts. This option is equivalent to the command line switches
 533         <option>--overlay=</option> and <option>--overlay-ro=</option>, see
 534         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> for details
 535         about the specific options supported. This setting is privileged (see above).</para>
 536
 537         <xi:include href="version-info.xml" xpointer="v233"/></listitem>
 538       </varlistentry>
 539
 540       <varlistentry>
 541         <term><varname>PrivateUsersOwnership=</varname></term>
 542
 543         <listitem><para>Configures whether the ownership of the files and directories in the container tree
 544         shall be adjusted to the UID/GID range used, if necessary and user namespacing is enabled. This is
 545         equivalent to the <option>--private-users-ownership=</option> command line switch. This option is
 546         privileged (see above).</para>
 547
 548         <xi:include href="version-info.xml" xpointer="v249"/></listitem>
 549       </varlistentry>
 550
 551     </variablelist>
 552   </refsect1>
 553
 554   <refsect1>
 555     <title>[Network] Section Options</title>
 556
 557     <para>Settings files may include a [Network]
 558     section, which carries various parameters configuring the network
 559     connectivity of the container:</para>
 560
 561     <variablelist class='nspawn-directives'>
 562
 563       <varlistentry>
 564         <term><varname>Private=</varname></term>
 565
 566         <listitem><para>Takes a boolean argument, which defaults to off. If
 567         enabled, the container will run in its own network namespace
 568         and not share network interfaces and configuration with the
 569         host. This setting corresponds to the
 570         <option>--private-network</option> command line
 571         switch.</para>
 572
 573         <xi:include href="version-info.xml" xpointer="v226"/></listitem>
 574       </varlistentry>
 575
 576       <varlistentry>
 577         <term><varname>VirtualEthernet=</varname></term>
 578
 579         <listitem><para>Takes a boolean argument. Configures whether to create a virtual Ethernet connection
 580         (<literal>veth</literal>) between host and the container. This setting implies
 581         <varname>Private=yes</varname>. This setting corresponds to the <option>--network-veth</option> command line
 582         switch. This option is privileged (see above). This option is the default if the
 583         <filename>systemd-nspawn@.service</filename> template unit file is used.</para>
 584
 585         <xi:include href="version-info.xml" xpointer="v226"/></listitem>
 586       </varlistentry>
 587
 588       <varlistentry>
 589         <term><varname>VirtualEthernetExtra=</varname></term>
 590
 591         <listitem><para>Takes a colon-separated pair of interface names. Configures an additional virtual
 592         Ethernet connection (<literal>veth</literal>) between host and the container. The first specified
 593         name is the interface name on the host, the second the interface name in the container. The latter
 594         may be omitted in which case it is set to the same name as the host side interface. This setting
 595         implies <varname>Private=yes</varname>. This setting corresponds to the
 596         <option>--network-veth-extra=</option> command line switch, and may be used multiple times. It is
 597         independent of <varname>VirtualEthernet=</varname>. Note that this option is unrelated to the
 598         <varname>Bridge=</varname> setting below, and thus any connections created this way are not
 599         automatically added to any bridge device on the host side. This option is privileged (see
 600         above).</para>
 601
 602         <xi:include href="version-info.xml" xpointer="v228"/></listitem>
 603       </varlistentry>
 604
 605       <varlistentry>
 606         <term><varname>Interface=</varname></term>
 607
 608         <listitem><para>Takes a space-separated list of interfaces to add to the container.
 609         The interface object is defined either by a single interface name, referencing the name on the host,
 610         or a colon-separated pair of interfaces, in which case the first one references the name on the host,
 611         and the second one the name in the container.
 612         This option corresponds to the
 613         <option>--network-interface=</option> command line switch and
 614         implies <varname>Private=yes</varname>. This option is
 615         privileged (see above).</para>
 616
 617         <xi:include href="version-info.xml" xpointer="v226"/></listitem>
 618       </varlistentry>
 619
 620       <varlistentry>
 621         <term><varname>MACVLAN=</varname></term>
 622         <term><varname>IPVLAN=</varname></term>
 623
 624         <listitem><para>Takes a space-separated list of interfaces to
 625         add MACLVAN or IPVLAN interfaces to, which are then added to
 626         the container. The interface object is defined either by a single interface name, referencing the name
 627         on the host, or a colon-separated pair of interfaces, in which case the first one references the name
 628         on the host, and the second one the name in the container. These options correspond to the
 629         <option>--network-macvlan=</option> and
 630         <option>--network-ipvlan=</option> command line switches and
 631         imply <varname>Private=yes</varname>. These options are
 632         privileged (see above).</para>
 633
 634         <xi:include href="version-info.xml" xpointer="v226"/></listitem>
 635       </varlistentry>
 636
 637       <varlistentry>
 638         <term><varname>Bridge=</varname></term>
 639
 640         <listitem><para>Takes an interface name. This setting implies
 641         <varname>VirtualEthernet=yes</varname> and
 642         <varname>Private=yes</varname> and has the effect that the
 643         host side of the created virtual Ethernet link is connected to
 644         the specified bridge interface. This option corresponds to the
 645         <option>--network-bridge=</option> command line switch. This
 646         option is privileged (see above).</para>
 647
 648         <xi:include href="version-info.xml" xpointer="v226"/></listitem>
 649       </varlistentry>
 650
 651       <varlistentry>
 652         <term><varname>Zone=</varname></term>
 653
 654         <listitem><para>Takes a network zone name. This setting implies <varname>VirtualEthernet=yes</varname> and
 655         <varname>Private=yes</varname> and has the effect that the host side of the created virtual Ethernet link is
 656         connected to an automatically managed bridge interface named after the passed argument, prefixed with
 657         <literal>vz-</literal>. This option corresponds to the <option>--network-zone=</option> command line
 658         switch. This option is privileged (see above).</para>
 659
 660         <xi:include href="version-info.xml" xpointer="v230"/></listitem>
 661       </varlistentry>
 662
 663       <varlistentry>
 664         <term><varname>Port=</varname></term>
 665
 666         <listitem><para>Exposes a TCP or UDP port of the container on
 667         the host. This option corresponds to the
 668         <option>--port=</option> command line switch, see
 669         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 670         for the precise syntax of the argument this option takes. This
 671         option is privileged (see above).</para>
 672
 673         <xi:include href="version-info.xml" xpointer="v226"/></listitem>
 674       </varlistentry>
 675     </variablelist>
 676   </refsect1>
 677
 678   <refsect1>
 679     <title>See Also</title>
 680     <para>
 681       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 682       <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 683       <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 684     </para>
 685   </refsect1>
 686
 687 </refentry>