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" >
7 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
9 <refentry id=
"systemd.nspawn">
12 <title>systemd.nspawn
</title>
13 <productname>systemd
</productname>
17 <refentrytitle>systemd.nspawn
</refentrytitle>
18 <manvolnum>5</manvolnum>
22 <refname>systemd.nspawn
</refname>
23 <refpurpose>Container settings
</refpurpose>
27 <para><filename>/etc/systemd/nspawn/
<replaceable>machine
</replaceable>.nspawn
</filename></para>
28 <para><filename>/run/systemd/nspawn/
<replaceable>machine
</replaceable>.nspawn
</filename></para>
29 <para><filename>/var/lib/machines/
<replaceable>machine
</replaceable>.nspawn
</filename></para>
33 <title>Description
</title>
35 <para>An nspawn container settings file (suffix
36 <filename>.nspawn
</filename>) encodes additional runtime
37 information about a local container, and is searched, read and
39 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
40 when starting a container. Files of this type are named after the
41 containers they define settings for. They are optional, and only
42 required for containers whose execution environment shall differ
43 from the defaults. Files of this type mostly contain settings that
44 may also be set on the
<command>systemd-nspawn
</command> command
45 line, and make it easier to persistently attach specific settings
46 to specific containers. The syntax of these files is inspired by
47 <filename>.desktop
</filename> files following the
<ulink
48 url=
"http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG
49 Desktop Entry Specification
</ulink>, which in turn are inspired by
50 Microsoft Windows
<filename>.ini
</filename> files.
</para>
52 <para>Boolean arguments used in these settings files can be
53 written in various formats. For positive settings, the strings
54 <option>1</option>,
<option>yes
</option>,
<option>true
</option>
55 and
<option>on
</option> are equivalent. For negative settings, the
56 strings
<option>0</option>,
<option>no
</option>,
57 <option>false
</option> and
<option>off
</option> are
60 <para>Empty lines and lines starting with # or ; are
61 ignored. This may be used for commenting. Lines ending
62 in a backslash are concatenated with the following
63 line while reading and the backslash is replaced by a
64 space character. This may be used to wrap long lines.
</para>
69 <title><filename>.nspawn
</filename> File Discovery
</title>
71 <para>Files are searched by appending the
72 <filename>.nspawn
</filename> suffix to the machine name of the
73 container, as specified with the
<option>--machine=
</option>
74 switch of
<command>systemd-nspawn
</command>, or derived from the
75 directory or image file name. This file is first searched in
76 <filename>/etc/systemd/nspawn/
</filename> and
77 <filename>/run/systemd/nspawn/
</filename>. If found in these
78 directories, its settings are read and all of them take full effect
79 (but are possibly overridden by corresponding command line
80 arguments). If not found, the file will then be searched next to
81 the image file or in the immediate parent of the root directory of
82 the container. If the file is found there, only a subset of the
83 settings will take effect however. All settings that possibly
84 elevate privileges or grant additional access to resources of the
85 host (such as files or directories) are ignored. To which options
86 this applies is documented below.
</para>
88 <para>Persistent settings files created and maintained by the
89 administrator (and thus trusted) should be placed in
90 <filename>/etc/systemd/nspawn/
</filename>, while automatically
91 downloaded (and thus potentially untrusted) settings files are
92 placed in
<filename>/var/lib/machines/
</filename> instead (next to
93 the container images), where their security impact is limited. In
94 order to add privileged settings to
<filename>.nspawn
</filename>
95 files acquired from the image vendor, it is recommended to copy the
96 settings files into
<filename>/etc/systemd/nspawn/
</filename> and
97 edit them there, so that the privileged options become
98 available. The precise algorithm for how the files are searched and
99 interpreted may be configured with
100 <command>systemd-nspawn
</command>'s
<option>--settings=
</option>
102 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
107 <title>[Exec] Section Options
</title>
109 <para>Settings files may include an
<literal>[Exec]
</literal>
110 section, which carries various execution parameters:
</para>
112 <variablelist class='nspawn-directives'
>
115 <term><varname>Boot=
</varname></term>
117 <listitem><para>Takes a boolean argument, which defaults to off. If enabled,
<command>systemd-nspawn
</command>
118 will automatically search for an
<filename>init
</filename> executable and invoke it. In this case, the
119 specified parameters using
<varname>Parameters=
</varname> are passed as additional arguments to the
120 <filename>init
</filename> process. This setting corresponds to the
<option>--boot
</option> switch on the
121 <command>systemd-nspawn
</command> command line. This option may not be combined with
122 <varname>ProcessTwo=yes
</varname>. This option is the default if the
123 <filename>systemd-nspawn@.service
</filename> template unit file is used.
</para></listitem>
127 <term><varname>Ephemeral=
</varname></term>
129 <listitem><para>Takes a boolean argument, which defaults to off, If enabled, the container is run with
130 a temporary snapshot of its file system that is removed immediately when the container terminates.
131 This is equivalent to the
<option>--ephemeral
</option> command line switch. See
132 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for details
133 about the specific options supported.
</para></listitem>
137 <term><varname>ProcessTwo=
</varname></term>
139 <listitem><para>Takes a boolean argument, which defaults to off. If enabled, the specified program is run as
140 PID
2. A stub init process is run as PID
1. This setting corresponds to the
<option>--as-pid2
</option> switch
141 on the
<command>systemd-nspawn
</command> command line. This option may not be combined with
142 <varname>Boot=yes
</varname>.
</para></listitem>
146 <term><varname>Parameters=
</varname></term>
148 <listitem><para>Takes a space-separated list of
149 arguments. This is either a command line, beginning with the
150 binary name to execute, or – if
<varname>Boot=
</varname> is
151 enabled – the list of arguments to pass to the init
152 process. This setting corresponds to the command line
153 parameters passed on the
<command>systemd-nspawn
</command>
154 command line.
</para></listitem>
158 <term><varname>Environment=
</varname></term>
160 <listitem><para>Takes an environment variable assignment
161 consisting of key and value, separated by
162 <literal>=
</literal>. Sets an environment variable for the
163 main process invoked in the container. This setting may be
164 used multiple times to set multiple environment variables. It
165 corresponds to the
<option>--setenv=
</option> command line
166 switch.
</para></listitem>
170 <term><varname>User=
</varname></term>
172 <listitem><para>Takes a UNIX user name. Specifies the user
173 name to invoke the main process of the container as. This user
174 must be known in the container's user database. This
175 corresponds to the
<option>--user=
</option> command line
176 switch.
</para></listitem>
180 <term><varname>WorkingDirectory=
</varname></term>
182 <listitem><para>Selects the working directory for the process invoked in the container. Expects an absolute
183 path in the container's file system namespace. This corresponds to the
<option>--chdir=
</option> command line
184 switch.
</para></listitem>
188 <term><varname>PivotRoot=
</varname></term>
190 <listitem><para>Selects a directory to pivot to
<filename>/
</filename> inside the container when starting up.
191 Takes a single path, or a pair of two paths separated by a colon. Both paths must be absolute, and are resolved
192 in the container's file system namespace. This corresponds to the
<option>--pivot-root=
</option> command line
193 switch.
</para></listitem>
197 <term><varname>Capability=
</varname></term>
198 <term><varname>DropCapability=
</varname></term>
200 <listitem><para>Takes a space-separated list of Linux process
202 <citerefentry project='man-pages'
><refentrytitle>capabilities
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
203 for details). The
<varname>Capability=
</varname> setting
204 specifies additional capabilities to pass on top of the
205 default set of capabilities. The
206 <varname>DropCapability=
</varname> setting specifies
207 capabilities to drop from the default set. These settings
208 correspond to the
<option>--capability=
</option> and
209 <option>--drop-capability=
</option> command line
210 switches. Note that
<varname>Capability=
</varname> is a
211 privileged setting, and only takes effect in
212 <filename>.nspawn
</filename> files in
213 <filename>/etc/systemd/nspawn/
</filename> and
214 <filename>/run/system/nspawn/
</filename> (see above). On the
215 other hand,
<varname>DropCapability=
</varname> takes effect in
216 all cases.
</para></listitem>
220 <term><varname>NoNewPrivileges=
</varname></term>
222 <listitem><para>Takes a boolean argument that controls the
<constant>PR_SET_NO_NEW_PRIVS
</constant> flag for
223 the container payload. This is equivalent to the
224 <option>--no-new-privileges=
</option> command line switch. See
225 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
231 <term><varname>KillSignal=
</varname></term>
233 <listitem><para>Specify the process signal to send to the
234 container's PID
1 when nspawn itself receives SIGTERM, in
235 order to trigger an orderly shutdown of the container.
236 Defaults to SIGRTMIN+
3 if
<option>Boot=
</option> is used
237 (on systemd-compatible init systems SIGRTMIN+
3 triggers an
238 orderly shutdown). For a list of valid signals, see
239 <citerefentry project='man-pages'
><refentrytitle>signal
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
</para></listitem>
243 <term><varname>Personality=
</varname></term>
245 <listitem><para>Configures the kernel personality for the
246 container. This is equivalent to the
247 <option>--personality=
</option> switch.
</para></listitem>
251 <term><varname>MachineID=
</varname></term>
253 <listitem><para>Configures the
128-bit machine ID (UUID) to pass to
254 the container. This is equivalent to the
255 <option>--uuid=
</option> command line switch. This option is
256 privileged (see above).
</para></listitem>
260 <term><varname>PrivateUsers=
</varname></term>
262 <listitem><para>Configures support for usernamespacing. This is equivalent to the
263 <option>--private-users=
</option> command line switch, and takes the same options. This option is privileged
264 (see above). This option is the default if the
<filename>systemd-nspawn@.service
</filename> template unit file
265 is used.
</para></listitem>
269 <term><varname>NotifyReady=
</varname></term>
271 <listitem><para>Configures support for notifications from the container's init process. This is equivalent to
272 the
<option>--notify-ready=
</option> command line switch, and takes the same parameters. See
273 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for details
274 about the specific options supported.
</para></listitem>
278 <term><varname>SystemCallFilter=
</varname></term>
280 <listitem><para>Configures the system call filter applied to containers. This is equivalent to the
281 <option>--system-call-filter=
</option> command line switch, and takes the same list parameter. See
282 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
283 details.
</para></listitem>
287 <term><varname>LimitCPU=
</varname></term>
288 <term><varname>LimitFSIZE=
</varname></term>
289 <term><varname>LimitDATA=
</varname></term>
290 <term><varname>LimitSTACK=
</varname></term>
291 <term><varname>LimitCORE=
</varname></term>
292 <term><varname>LimitRSS=
</varname></term>
293 <term><varname>LimitNOFILE=
</varname></term>
294 <term><varname>LimitAS=
</varname></term>
295 <term><varname>LimitNPROC=
</varname></term>
296 <term><varname>LimitMEMLOCK=
</varname></term>
297 <term><varname>LimitLOCKS=
</varname></term>
298 <term><varname>LimitSIGPENDING=
</varname></term>
299 <term><varname>LimitMSGQUEUE=
</varname></term>
300 <term><varname>LimitNICE=
</varname></term>
301 <term><varname>LimitRTPRIO=
</varname></term>
302 <term><varname>LimitRTTIME=
</varname></term>
304 <listitem><para>Configures various types of resource limits applied to containers. This is equivalent to the
305 <option>--rlimit=
</option> command line switch, and takes the same arguments. See
306 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
307 details.
</para></listitem>
311 <term><varname>OOMScoreAdjust=
</varname></term>
313 <listitem><para>Configures the OOM score adjustment value. This is equivalent to the
314 <option>--oom-score-adjust=
</option> command line switch, and takes the same argument. See
315 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
316 details.
</para></listitem>
320 <term><varname>CPUAffinity=
</varname></term>
322 <listitem><para>Configures the CPU affinity. This is equivalent to the
<option>--cpu-affinity=
</option> command
323 line switch, and takes the same argument. See
324 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
325 details.
</para></listitem>
329 <term><varname>Hostname=
</varname></term>
331 <listitem><para>Configures the kernel hostname set for the container. This is equivalent to the
332 <option>--hostname=
</option> command line switch, and takes the same argument. See
333 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
334 details.
</para></listitem>
338 <term><varname>ResolvConf=
</varname></term>
340 <listitem><para>Configures how
<filename>/etc/resolv.conf
</filename> in the container shall be handled. This is
341 equivalent to the
<option>--resolv-conf=
</option> command line switch, and takes the same argument. See
342 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
343 details.
</para></listitem>
347 <term><varname>Timezone=
</varname></term>
349 <listitem><para>Configures how
<filename>/etc/localtime
</filename> in the container shall be handled. This is
350 equivalent to the
<option>--timezone=
</option> command line switch, and takes the same argument. See
351 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
352 details.
</para></listitem>
356 <term><varname>LinkJournal=
</varname></term>
358 <listitem><para>Configures how to link host and container journal setups. This is equivalent to the
359 <option>--link-journal=
</option> command line switch, and takes the same parameter. See
360 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
361 details.
</para></listitem>
368 <title>[Files] Section Options
</title>
370 <para>Settings files may include a
<literal>[Files]
</literal>
371 section, which carries various parameters configuring the file
372 system of the container:
</para>
374 <variablelist class='nspawn-directives'
>
377 <term><varname>ReadOnly=
</varname></term>
379 <listitem><para>Takes a boolean argument, which defaults to off. If
380 specified, the container will be run with a read-only file
381 system. This setting corresponds to the
382 <option>--read-only
</option> command line
383 switch.
</para></listitem>
387 <term><varname>Volatile=
</varname></term>
389 <listitem><para>Takes a boolean argument, or the special value
390 <literal>state
</literal>. This configures whether to run the
391 container with volatile state and/or configuration. This
392 option is equivalent to
<option>--volatile=
</option>, see
393 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
394 for details about the specific options
395 supported.
</para></listitem>
399 <term><varname>Bind=
</varname></term>
400 <term><varname>BindReadOnly=
</varname></term>
402 <listitem><para>Adds a bind mount from the host into the
403 container. Takes a single path, a pair of two paths separated
404 by a colon, or a triplet of two paths plus an option string
405 separated by colons. This option may be used multiple times to
406 configure multiple bind mounts. This option is equivalent to
407 the command line switches
<option>--bind=
</option> and
408 <option>--bind-ro=
</option>, see
409 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
410 for details about the specific options supported. This setting
411 is privileged (see above).
</para></listitem>
415 <term><varname>TemporaryFileSystem=
</varname></term>
417 <listitem><para>Adds a
<literal>tmpfs
</literal> mount to the
418 container. Takes a path or a pair of path and option string,
419 separated by a colon. This option may be used multiple times to
420 configure multiple
<literal>tmpfs
</literal> mounts. This
421 option is equivalent to the command line switch
422 <option>--tmpfs=
</option>, see
423 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
424 for details about the specific options supported. This setting
425 is privileged (see above).
</para></listitem>
429 <term><varname>Overlay=
</varname></term>
430 <term><varname>OverlayReadOnly=
</varname></term>
432 <listitem><para>Adds an overlay mount point. Takes a colon-separated list of paths. This option may be used
433 multiple times to configure multiple overlay mounts. This option is equivalent to the command line switches
434 <option>--overlay=
</option> and
<option>--overlay-ro=
</option>, see
435 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for details
436 about the specific options supported. This setting is privileged (see above).
</para></listitem>
440 <term><varname>PrivateUsersChown=
</varname></term>
442 <listitem><para>Configures whether the ownership of the files and directories in the container tree shall be
443 adjusted to the UID/GID range used, if necessary and user namespacing is enabled. This is equivalent to the
444 <option>--private-users-chown
</option> command line switch. This option is privileged (see
445 above).
</para></listitem>
452 <title>[Network] Section Options
</title>
454 <para>Settings files may include a
<literal>[Network]
</literal>
455 section, which carries various parameters configuring the network
456 connectivity of the container:
</para>
458 <variablelist class='nspawn-directives'
>
461 <term><varname>Private=
</varname></term>
463 <listitem><para>Takes a boolean argument, which defaults to off. If
464 enabled, the container will run in its own network namespace
465 and not share network interfaces and configuration with the
466 host. This setting corresponds to the
467 <option>--private-network
</option> command line
468 switch.
</para></listitem>
472 <term><varname>VirtualEthernet=
</varname></term>
474 <listitem><para>Takes a boolean argument. Configures whether to create a virtual Ethernet connection
475 (
<literal>veth
</literal>) between host and the container. This setting implies
476 <varname>Private=yes
</varname>. This setting corresponds to the
<option>--network-veth
</option> command line
477 switch. This option is privileged (see above). This option is the default if the
478 <filename>systemd-nspawn@.service
</filename> template unit file is used.
</para></listitem>
482 <term><varname>VirtualEthernetExtra=
</varname></term>
484 <listitem><para>Takes a colon-separated pair of interface
485 names. Configures an additional virtual Ethernet connection
486 (
<literal>veth
</literal>) between host and the container. The
487 first specified name is the interface name on the host, the
488 second the interface name in the container. The latter may be
489 omitted in which case it is set to the same name as the host
490 side interface. This setting implies
491 <varname>Private=yes
</varname>. This setting corresponds to
492 the
<option>--network-veth-extra=
</option> command line
493 switch, and maybe be used multiple times. It is independent of
494 <varname>VirtualEthernet=
</varname>. This option is privileged
495 (see above).
</para></listitem>
499 <term><varname>Interface=
</varname></term>
501 <listitem><para>Takes a space-separated list of interfaces to
502 add to the container. This option corresponds to the
503 <option>--network-interface=
</option> command line switch and
504 implies
<varname>Private=yes
</varname>. This option is
505 privileged (see above).
</para></listitem>
509 <term><varname>MACVLAN=
</varname></term>
510 <term><varname>IPVLAN=
</varname></term>
512 <listitem><para>Takes a space-separated list of interfaces to
513 add MACLVAN or IPVLAN interfaces to, which are then added to
514 the container. These options correspond to the
515 <option>--network-macvlan=
</option> and
516 <option>--network-ipvlan=
</option> command line switches and
517 imply
<varname>Private=yes
</varname>. These options are
518 privileged (see above).
</para></listitem>
522 <term><varname>Bridge=
</varname></term>
524 <listitem><para>Takes an interface name. This setting implies
525 <varname>VirtualEthernet=yes
</varname> and
526 <varname>Private=yes
</varname> and has the effect that the
527 host side of the created virtual Ethernet link is connected to
528 the specified bridge interface. This option corresponds to the
529 <option>--network-bridge=
</option> command line switch. This
530 option is privileged (see above).
</para></listitem>
534 <term><varname>Zone=
</varname></term>
536 <listitem><para>Takes a network zone name. This setting implies
<varname>VirtualEthernet=yes
</varname> and
537 <varname>Private=yes
</varname> and has the effect that the host side of the created virtual Ethernet link is
538 connected to an automatically managed bridge interface named after the passed argument, prefixed with
539 <literal>vz-
</literal>. This option corresponds to the
<option>--network-zone=
</option> command line
540 switch. This option is privileged (see above).
</para></listitem>
544 <term><varname>Port=
</varname></term>
546 <listitem><para>Exposes a TCP or UDP port of the container on
547 the host. This option corresponds to the
548 <option>--port=
</option> command line switch, see
549 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
550 for the precise syntax of the argument this option takes. This
551 option is privileged (see above).
</para></listitem>
557 <title>See Also
</title>
559 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
560 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
561 <citerefentry><refentrytitle>systemd.directives
</refentrytitle><manvolnum>7</manvolnum></citerefentry>