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" >
9 SPDX-License-Identifier: LGPL-2.1+
12 <refentry id=
"systemd.nspawn">
15 <title>systemd.nspawn
</title>
16 <productname>systemd
</productname>
20 <refentrytitle>systemd.nspawn
</refentrytitle>
21 <manvolnum>5</manvolnum>
25 <refname>systemd.nspawn
</refname>
26 <refpurpose>Container settings
</refpurpose>
30 <para><filename>/etc/systemd/nspawn/
<replaceable>machine
</replaceable>.nspawn
</filename></para>
31 <para><filename>/run/systemd/nspawn/
<replaceable>machine
</replaceable>.nspawn
</filename></para>
32 <para><filename>/var/lib/machines/
<replaceable>machine
</replaceable>.nspawn
</filename></para>
36 <title>Description
</title>
38 <para>An nspawn container settings file (suffix
39 <filename>.nspawn
</filename>) encodes additional runtime
40 information about a local container, and is searched, read and
42 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
43 when starting a container. Files of this type are named after the
44 containers they define settings for. They are optional, and only
45 required for containers whose execution environment shall differ
46 from the defaults. Files of this type mostly contain settings that
47 may also be set on the
<command>systemd-nspawn
</command> command
48 line, and make it easier to persistently attach specific settings
49 to specific containers. The syntax of these files is inspired by
50 <filename>.desktop
</filename> files following the
<ulink
51 url=
"http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG
52 Desktop Entry Specification
</ulink>, which in turn are inspired by
53 Microsoft Windows
<filename>.ini
</filename> files.
</para>
55 <para>Boolean arguments used in these settings files can be
56 written in various formats. For positive settings, the strings
57 <option>1</option>,
<option>yes
</option>,
<option>true
</option>
58 and
<option>on
</option> are equivalent. For negative settings, the
59 strings
<option>0</option>,
<option>no
</option>,
60 <option>false
</option> and
<option>off
</option> are
63 <para>Empty lines and lines starting with # or ; are
64 ignored. This may be used for commenting. Lines ending
65 in a backslash are concatenated with the following
66 line while reading and the backslash is replaced by a
67 space character. This may be used to wrap long lines.
</para>
72 <title><filename>.nspawn
</filename> File Discovery
</title>
74 <para>Files are searched by appending the
75 <filename>.nspawn
</filename> suffix to the machine name of the
76 container, as specified with the
<option>--machine=
</option>
77 switch of
<command>systemd-nspawn
</command>, or derived from the
78 directory or image file name. This file is first searched in
79 <filename>/etc/systemd/nspawn/
</filename> and
80 <filename>/run/systemd/nspawn/
</filename>. If found in these
81 directories, its settings are read and all of them take full effect
82 (but are possibly overridden by corresponding command line
83 arguments). If not found, the file will then be searched next to
84 the image file or in the immediate parent of the root directory of
85 the container. If the file is found there, only a subset of the
86 settings will take effect however. All settings that possibly
87 elevate privileges or grant additional access to resources of the
88 host (such as files or directories) are ignored. To which options
89 this applies is documented below.
</para>
91 <para>Persistent settings files created and maintained by the
92 administrator (and thus trusted) should be placed in
93 <filename>/etc/systemd/nspawn/
</filename>, while automatically
94 downloaded (and thus potentially untrusted) settings files are
95 placed in
<filename>/var/lib/machines/
</filename> instead (next to
96 the container images), where their security impact is limited. In
97 order to add privileged settings to
<filename>.nspawn
</filename>
98 files acquired from the image vendor, it is recommended to copy the
99 settings files into
<filename>/etc/systemd/nspawn/
</filename> and
100 edit them there, so that the privileged options become
101 available. The precise algorithm for how the files are searched and
102 interpreted may be configured with
103 <command>systemd-nspawn
</command>'s
<option>--settings=
</option>
105 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
110 <title>[Exec] Section Options
</title>
112 <para>Settings files may include an
<literal>[Exec]
</literal>
113 section, which carries various execution parameters:
</para>
118 <term><varname>Boot=
</varname></term>
120 <listitem><para>Takes a boolean argument, which defaults to off. If enabled,
<command>systemd-nspawn
</command>
121 will automatically search for an
<filename>init
</filename> executable and invoke it. In this case, the
122 specified parameters using
<varname>Parameters=
</varname> are passed as additional arguments to the
123 <filename>init
</filename> process. This setting corresponds to the
<option>--boot
</option> switch on the
124 <command>systemd-nspawn
</command> command line. This option may not be combined with
125 <varname>ProcessTwo=yes
</varname>. This option is the default if the
126 <filename>systemd-nspawn@.service
</filename> template unit file is used.
</para></listitem>
130 <term><varname>Ephemeral=
</varname></term>
132 <listitem><para>Takes a boolean argument, which defaults to off, If enabled, the container is run with
133 a temporary snapshot of its file system that is removed immediately when the container terminates.
134 This is equivalent to the
<option>--ephemeral
</option> command line switch. See
135 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for details
136 about the specific options supported.
</para></listitem>
140 <term><varname>ProcessTwo=
</varname></term>
142 <listitem><para>Takes a boolean argument, which defaults to off. If enabled, the specified program is run as
143 PID
2. A stub init process is run as PID
1. This setting corresponds to the
<option>--as-pid2
</option> switch
144 on the
<command>systemd-nspawn
</command> command line. This option may not be combined with
145 <varname>Boot=yes
</varname>.
</para></listitem>
149 <term><varname>Parameters=
</varname></term>
151 <listitem><para>Takes a space-separated list of
152 arguments. This is either a command line, beginning with the
153 binary name to execute, or – if
<varname>Boot=
</varname> is
154 enabled – the list of arguments to pass to the init
155 process. This setting corresponds to the command line
156 parameters passed on the
<command>systemd-nspawn
</command>
157 command line.
</para></listitem>
161 <term><varname>Environment=
</varname></term>
163 <listitem><para>Takes an environment variable assignment
164 consisting of key and value, separated by
165 <literal>=
</literal>. Sets an environment variable for the
166 main process invoked in the container. This setting may be
167 used multiple times to set multiple environment variables. It
168 corresponds to the
<option>--setenv=
</option> command line
169 switch.
</para></listitem>
173 <term><varname>User=
</varname></term>
175 <listitem><para>Takes a UNIX user name. Specifies the user
176 name to invoke the main process of the container as. This user
177 must be known in the container's user database. This
178 corresponds to the
<option>--user=
</option> command line
179 switch.
</para></listitem>
183 <term><varname>WorkingDirectory=
</varname></term>
185 <listitem><para>Selects the working directory for the process invoked in the container. Expects an absolute
186 path in the container's file system namespace. This corresponds to the
<option>--chdir=
</option> command line
187 switch.
</para></listitem>
191 <term><varname>PivotRoot=
</varname></term>
193 <listitem><para>Selects a directory to pivot to
<filename>/
</filename> inside the container when starting up.
194 Takes a single path, or a pair of two paths separated by a colon. Both paths must be absolute, and are resolved
195 in the container's file system namespace. This corresponds to the
<option>--pivot-root=
</option> command line
196 switch.
</para></listitem>
200 <term><varname>Capability=
</varname></term>
201 <term><varname>DropCapability=
</varname></term>
203 <listitem><para>Takes a space-separated list of Linux process
205 <citerefentry project='man-pages'
><refentrytitle>capabilities
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
206 for details). The
<varname>Capability=
</varname> setting
207 specifies additional capabilities to pass on top of the
208 default set of capabilities. The
209 <varname>DropCapability=
</varname> setting specifies
210 capabilities to drop from the default set. These settings
211 correspond to the
<option>--capability=
</option> and
212 <option>--drop-capability=
</option> command line
213 switches. Note that
<varname>Capability=
</varname> is a
214 privileged setting, and only takes effect in
215 <filename>.nspawn
</filename> files in
216 <filename>/etc/systemd/nspawn/
</filename> and
217 <filename>/run/system/nspawn/
</filename> (see above). On the
218 other hand,
<varname>DropCapability=
</varname> takes effect in
219 all cases.
</para></listitem>
223 <term><varname>NoNewPrivileges=
</varname></term>
225 <listitem><para>Takes a boolean argument that controls the
<constant>PR_SET_NO_NEW_PRIVS
</constant> flag for
226 the container payload. This is equivalent to the
227 <option>--no-new-privileges=
</option> command line switch. See
228 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
234 <term><varname>KillSignal=
</varname></term>
236 <listitem><para>Specify the process signal to send to the
237 container's PID
1 when nspawn itself receives SIGTERM, in
238 order to trigger an orderly shutdown of the container.
239 Defaults to SIGRTMIN+
3 if
<option>Boot=
</option> is used
240 (on systemd-compatible init systems SIGRTMIN+
3 triggers an
241 orderly shutdown). For a list of valid signals, see
242 <citerefentry project='man-pages'
><refentrytitle>signal
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
</para></listitem>
246 <term><varname>Personality=
</varname></term>
248 <listitem><para>Configures the kernel personality for the
249 container. This is equivalent to the
250 <option>--personality=
</option> switch.
</para></listitem>
254 <term><varname>MachineID=
</varname></term>
256 <listitem><para>Configures the
128-bit machine ID (UUID) to pass to
257 the container. This is equivalent to the
258 <option>--uuid=
</option> command line switch. This option is
259 privileged (see above).
</para></listitem>
263 <term><varname>PrivateUsers=
</varname></term>
265 <listitem><para>Configures support for usernamespacing. This is equivalent to the
266 <option>--private-users=
</option> command line switch, and takes the same options. This option is privileged
267 (see above). This option is the default if the
<filename>systemd-nspawn@.service
</filename> template unit file
268 is used.
</para></listitem>
272 <term><varname>NotifyReady=
</varname></term>
274 <listitem><para>Configures support for notifications from the container's init process. This is equivalent to
275 the
<option>--notify-ready=
</option> command line switch, and takes the same parameters. See
276 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for details
277 about the specific options supported.
</para></listitem>
281 <term><varname>SystemCallFilter=
</varname></term>
283 <listitem><para>Configures the system call filter applied to containers. This is equivalent to the
284 <option>--system-call-filter=
</option> command line switch, and takes the same list parameter. See
285 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
286 details.
</para></listitem>
290 <term><varname>LimitCPU=
</varname></term>
291 <term><varname>LimitFSIZE=
</varname></term>
292 <term><varname>LimitDATA=
</varname></term>
293 <term><varname>LimitSTACK=
</varname></term>
294 <term><varname>LimitCORE=
</varname></term>
295 <term><varname>LimitRSS=
</varname></term>
296 <term><varname>LimitNOFILE=
</varname></term>
297 <term><varname>LimitAS=
</varname></term>
298 <term><varname>LimitNPROC=
</varname></term>
299 <term><varname>LimitMEMLOCK=
</varname></term>
300 <term><varname>LimitLOCKS=
</varname></term>
301 <term><varname>LimitSIGPENDING=
</varname></term>
302 <term><varname>LimitMSGQUEUE=
</varname></term>
303 <term><varname>LimitNICE=
</varname></term>
304 <term><varname>LimitRTPRIO=
</varname></term>
305 <term><varname>LimitRTTIME=
</varname></term>
307 <listitem><para>Configures various types of resource limits applied to containers. This is equivalent to the
308 <option>--rlimit=
</option> command line switch, and takes the same arguments. See
309 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
310 details.
</para></listitem>
314 <term><varname>OOMScoreAdjust=
</varname></term>
316 <listitem><para>Configures the OOM score adjustment value. This is equivalent to the
317 <option>--oom-score-adjust=
</option> command line switch, and takes the same argument. See
318 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
319 details.
</para></listitem>
323 <term><varname>CPUAffinity=
</varname></term>
325 <listitem><para>Configures the CPU affinity. This is equivalent to the
<option>--cpu-affinity=
</option> command
326 line switch, and takes the same argument. See
327 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
328 details.
</para></listitem>
332 <term><varname>Hostname=
</varname></term>
334 <listitem><para>Configures the kernel hostname set for the container. This is equivalent to the
335 <option>--hostname=
</option> command line switch, and takes the same argument. See
336 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
337 details.
</para></listitem>
341 <term><varname>ResolvConf=
</varname></term>
343 <listitem><para>Configures how
<filename>/etc/resolv.conf
</filename> in the container shall be handled. This is
344 equivalent to the
<option>--resolv-conf=
</option> command line switch, and takes the same argument. See
345 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
346 details.
</para></listitem>
350 <term><varname>Timezone=
</varname></term>
352 <listitem><para>Configures how
<filename>/etc/localtime
</filename> in the container shall be handled. This is
353 equivalent to the
<option>--timezone=
</option> command line switch, and takes the same argument. See
354 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
355 details.
</para></listitem>
359 <term><varname>LinkJournal=
</varname></term>
361 <listitem><para>Configures how to link host and container journal setups. This is equivalent to the
362 <option>--link-journal=
</option> command line switch, and takes the same parameter. See
363 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
364 details.
</para></listitem>
371 <title>[Files] Section Options
</title>
373 <para>Settings files may include a
<literal>[Files]
</literal>
374 section, which carries various parameters configuring the file
375 system of the container:
</para>
380 <term><varname>ReadOnly=
</varname></term>
382 <listitem><para>Takes a boolean argument, which defaults to off. If
383 specified, the container will be run with a read-only file
384 system. This setting corresponds to the
385 <option>--read-only
</option> command line
386 switch.
</para></listitem>
390 <term><varname>Volatile=
</varname></term>
392 <listitem><para>Takes a boolean argument, or the special value
393 <literal>state
</literal>. This configures whether to run the
394 container with volatile state and/or configuration. This
395 option is equivalent to
<option>--volatile=
</option>, see
396 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
397 for details about the specific options
398 supported.
</para></listitem>
402 <term><varname>Bind=
</varname></term>
403 <term><varname>BindReadOnly=
</varname></term>
405 <listitem><para>Adds a bind mount from the host into the
406 container. Takes a single path, a pair of two paths separated
407 by a colon, or a triplet of two paths plus an option string
408 separated by colons. This option may be used multiple times to
409 configure multiple bind mounts. This option is equivalent to
410 the command line switches
<option>--bind=
</option> and
411 <option>--bind-ro=
</option>, see
412 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
413 for details about the specific options supported. This setting
414 is privileged (see above).
</para></listitem>
418 <term><varname>TemporaryFileSystem=
</varname></term>
420 <listitem><para>Adds a
<literal>tmpfs
</literal> mount to the
421 container. Takes a path or a pair of path and option string,
422 separated by a colon. This option may be used multiple times to
423 configure multiple
<literal>tmpfs
</literal> mounts. This
424 option is equivalent to the command line switch
425 <option>--tmpfs=
</option>, see
426 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
427 for details about the specific options supported. This setting
428 is privileged (see above).
</para></listitem>
432 <term><varname>Overlay=
</varname></term>
433 <term><varname>OverlayReadOnly=
</varname></term>
435 <listitem><para>Adds an overlay mount point. Takes a colon-separated list of paths. This option may be used
436 multiple times to configure multiple overlay mounts. This option is equivalent to the command line switches
437 <option>--overlay=
</option> and
<option>--overlay-ro=
</option>, see
438 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for details
439 about the specific options supported. This setting is privileged (see above).
</para></listitem>
443 <term><varname>PrivateUsersChown=
</varname></term>
445 <listitem><para>Configures whether the ownership of the files and directories in the container tree shall be
446 adjusted to the UID/GID range used, if necessary and user namespacing is enabled. This is equivalent to the
447 <option>--private-users-chown
</option> command line switch. This option is privileged (see
448 above).
</para></listitem>
455 <title>[Network] Section Options
</title>
457 <para>Settings files may include a
<literal>[Network]
</literal>
458 section, which carries various parameters configuring the network
459 connectivity of the container:
</para>
464 <term><varname>Private=
</varname></term>
466 <listitem><para>Takes a boolean argument, which defaults to off. If
467 enabled, the container will run in its own network namespace
468 and not share network interfaces and configuration with the
469 host. This setting corresponds to the
470 <option>--private-network
</option> command line
471 switch.
</para></listitem>
475 <term><varname>VirtualEthernet=
</varname></term>
477 <listitem><para>Takes a boolean argument. Configures whether to create a virtual Ethernet connection
478 (
<literal>veth
</literal>) between host and the container. This setting implies
479 <varname>Private=yes
</varname>. This setting corresponds to the
<option>--network-veth
</option> command line
480 switch. This option is privileged (see above). This option is the default if the
481 <filename>systemd-nspawn@.service
</filename> template unit file is used.
</para></listitem>
485 <term><varname>VirtualEthernetExtra=
</varname></term>
487 <listitem><para>Takes a colon-separated pair of interface
488 names. Configures an additional virtual Ethernet connection
489 (
<literal>veth
</literal>) between host and the container. The
490 first specified name is the interface name on the host, the
491 second the interface name in the container. The latter may be
492 omitted in which case it is set to the same name as the host
493 side interface. This setting implies
494 <varname>Private=yes
</varname>. This setting corresponds to
495 the
<option>--network-veth-extra=
</option> command line
496 switch, and maybe be used multiple times. It is independent of
497 <varname>VirtualEthernet=
</varname>. This option is privileged
498 (see above).
</para></listitem>
502 <term><varname>Interface=
</varname></term>
504 <listitem><para>Takes a space-separated list of interfaces to
505 add to the container. This option corresponds to the
506 <option>--network-interface=
</option> command line switch and
507 implies
<varname>Private=yes
</varname>. This option is
508 privileged (see above).
</para></listitem>
512 <term><varname>MACVLAN=
</varname></term>
513 <term><varname>IPVLAN=
</varname></term>
515 <listitem><para>Takes a space-separated list of interfaces to
516 add MACLVAN or IPVLAN interfaces to, which are then added to
517 the container. These options correspond to the
518 <option>--network-macvlan=
</option> and
519 <option>--network-ipvlan=
</option> command line switches and
520 imply
<varname>Private=yes
</varname>. These options are
521 privileged (see above).
</para></listitem>
525 <term><varname>Bridge=
</varname></term>
527 <listitem><para>Takes an interface name. This setting implies
528 <varname>VirtualEthernet=yes
</varname> and
529 <varname>Private=yes
</varname> and has the effect that the
530 host side of the created virtual Ethernet link is connected to
531 the specified bridge interface. This option corresponds to the
532 <option>--network-bridge=
</option> command line switch. This
533 option is privileged (see above).
</para></listitem>
537 <term><varname>Zone=
</varname></term>
539 <listitem><para>Takes a network zone name. This setting implies
<varname>VirtualEthernet=yes
</varname> and
540 <varname>Private=yes
</varname> and has the effect that the host side of the created virtual Ethernet link is
541 connected to an automatically managed bridge interface named after the passed argument, prefixed with
542 <literal>vz-
</literal>. This option corresponds to the
<option>--network-zone=
</option> command line
543 switch. This option is privileged (see above).
</para></listitem>
547 <term><varname>Port=
</varname></term>
549 <listitem><para>Exposes a TCP or UDP port of the container on
550 the host. This option corresponds to the
551 <option>--port=
</option> command line switch, see
552 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
553 for the precise syntax of the argument this option takes. This
554 option is privileged (see above).
</para></listitem>
560 <title>See Also
</title>
562 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
563 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
564 <citerefentry><refentrytitle>systemd.directives
</refentrytitle><manvolnum>7</manvolnum></citerefentry>