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" >
9 SPDX-License-Identifier: LGPL-2.1+
11 This file is part of systemd.
13 Copyright 2015 Lennart Poettering
16 <refentry id=
"systemd.nspawn">
19 <title>systemd.nspawn
</title>
20 <productname>systemd
</productname>
24 <contrib>Developer
</contrib>
25 <firstname>Lennart
</firstname>
26 <surname>Poettering
</surname>
27 <email>lennart@poettering.net
</email>
33 <refentrytitle>systemd.nspawn
</refentrytitle>
34 <manvolnum>5</manvolnum>
38 <refname>systemd.nspawn
</refname>
39 <refpurpose>Container settings
</refpurpose>
43 <para><filename>/etc/systemd/nspawn/
<replaceable>machine
</replaceable>.nspawn
</filename></para>
44 <para><filename>/run/systemd/nspawn/
<replaceable>machine
</replaceable>.nspawn
</filename></para>
45 <para><filename>/var/lib/machines/
<replaceable>machine
</replaceable>.nspawn
</filename></para>
49 <title>Description
</title>
51 <para>An nspawn container settings file (suffix
52 <filename>.nspawn
</filename>) encodes additional runtime
53 information about a local container, and is searched, read and
55 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
56 when starting a container. Files of this type are named after the
57 containers they define settings for. They are optional, and only
58 required for containers whose execution environment shall differ
59 from the defaults. Files of this type mostly contain settings that
60 may also be set on the
<command>systemd-nspawn
</command> command
61 line, and make it easier to persistently attach specific settings
62 to specific containers. The syntax of these files is inspired by
63 <filename>.desktop
</filename> files following the
<ulink
64 url=
"http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG
65 Desktop Entry Specification
</ulink>, which in turn are inspired by
66 Microsoft Windows
<filename>.ini
</filename> files.
</para>
68 <para>Boolean arguments used in these settings files can be
69 written in various formats. For positive settings, the strings
70 <option>1</option>,
<option>yes
</option>,
<option>true
</option>
71 and
<option>on
</option> are equivalent. For negative settings, the
72 strings
<option>0</option>,
<option>no
</option>,
73 <option>false
</option> and
<option>off
</option> are
76 <para>Empty lines and lines starting with # or ; are
77 ignored. This may be used for commenting. Lines ending
78 in a backslash are concatenated with the following
79 line while reading and the backslash is replaced by a
80 space character. This may be used to wrap long lines.
</para>
85 <title><filename>.nspawn
</filename> File Discovery
</title>
87 <para>Files are searched by appending the
88 <filename>.nspawn
</filename> suffix to the machine name of the
89 container, as specified with the
<option>--machine=
</option>
90 switch of
<command>systemd-nspawn
</command>, or derived from the
91 directory or image file name. This file is first searched in
92 <filename>/etc/systemd/nspawn/
</filename> and
93 <filename>/run/systemd/nspawn/
</filename>. If found in these
94 directories, its settings are read and all of them take full effect
95 (but are possibly overridden by corresponding command line
96 arguments). If not found, the file will then be searched next to
97 the image file or in the immediate parent of the root directory of
98 the container. If the file is found there, only a subset of the
99 settings will take effect however. All settings that possibly
100 elevate privileges or grant additional access to resources of the
101 host (such as files or directories) are ignored. To which options
102 this applies is documented below.
</para>
104 <para>Persistent settings files created and maintained by the
105 administrator (and thus trusted) should be placed in
106 <filename>/etc/systemd/nspawn/
</filename>, while automatically
107 downloaded (and thus potentially untrusted) settings files are
108 placed in
<filename>/var/lib/machines/
</filename> instead (next to
109 the container images), where their security impact is limited. In
110 order to add privileged settings to
<filename>.nspawn
</filename>
111 files acquired from the image vendor, it is recommended to copy the
112 settings files into
<filename>/etc/systemd/nspawn/
</filename> and
113 edit them there, so that the privileged options become
114 available. The precise algorithm for how the files are searched and
115 interpreted may be configured with
116 <command>systemd-nspawn
</command>'s
<option>--settings=
</option>
118 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
123 <title>[Exec] Section Options
</title>
125 <para>Settings files may include an
<literal>[Exec]
</literal>
126 section, which carries various execution parameters:
</para>
131 <term><varname>Boot=
</varname></term>
133 <listitem><para>Takes a boolean argument, which defaults to off. If enabled,
<command>systemd-nspawn
</command>
134 will automatically search for an
<filename>init
</filename> executable and invoke it. In this case, the
135 specified parameters using
<varname>Parameters=
</varname> are passed as additional arguments to the
136 <filename>init
</filename> process. This setting corresponds to the
<option>--boot
</option> switch on the
137 <command>systemd-nspawn
</command> command line. This option may not be combined with
138 <varname>ProcessTwo=yes
</varname>. This option is the default if the
139 <filename>systemd-nspawn@.service
</filename> template unit file is used.
</para></listitem>
143 <term><varname>ProcessTwo=
</varname></term>
145 <listitem><para>Takes a boolean argument, which defaults to off. If enabled, the specified program is run as
146 PID
2. A stub init process is run as PID
1. This setting corresponds to the
<option>--as-pid2
</option> switch
147 on the
<command>systemd-nspawn
</command> command line. This option may not be combined with
148 <varname>Boot=yes
</varname>.
</para></listitem>
152 <term><varname>Parameters=
</varname></term>
154 <listitem><para>Takes a space-separated list of
155 arguments. This is either a command line, beginning with the
156 binary name to execute, or – if
<varname>Boot=
</varname> is
157 enabled – the list of arguments to pass to the init
158 process. This setting corresponds to the command line
159 parameters passed on the
<command>systemd-nspawn
</command>
160 command line.
</para></listitem>
164 <term><varname>Environment=
</varname></term>
166 <listitem><para>Takes an environment variable assignment
167 consisting of key and value, separated by
168 <literal>=
</literal>. Sets an environment variable for the
169 main process invoked in the container. This setting may be
170 used multiple times to set multiple environment variables. It
171 corresponds to the
<option>--setenv=
</option> command line
172 switch.
</para></listitem>
176 <term><varname>User=
</varname></term>
178 <listitem><para>Takes a UNIX user name. Specifies the user
179 name to invoke the main process of the container as. This user
180 must be known in the container's user database. This
181 corresponds to the
<option>--user=
</option> command line
182 switch.
</para></listitem>
186 <term><varname>WorkingDirectory=
</varname></term>
188 <listitem><para>Selects the working directory for the process invoked in the container. Expects an absolute
189 path in the container's file system namespace. This corresponds to the
<option>--chdir=
</option> command line
190 switch.
</para></listitem>
194 <term><varname>PivotRoot=
</varname></term>
196 <listitem><para>Selects a directory to pivot to
<filename>/
</filename> inside the container when starting up.
197 Takes a single path, or a pair of two paths separated by a colon. Both paths must be absolute, and are resolved
198 in the container's file system namespace. This corresponds to the
<option>--pivot-root=
</option> command line
199 switch.
</para></listitem>
203 <term><varname>Capability=
</varname></term>
204 <term><varname>DropCapability=
</varname></term>
206 <listitem><para>Takes a space-separated list of Linux process
208 <citerefentry project='man-pages'
><refentrytitle>capabilities
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
209 for details). The
<varname>Capability=
</varname> setting
210 specifies additional capabilities to pass on top of the
211 default set of capabilities. The
212 <varname>DropCapability=
</varname> setting specifies
213 capabilities to drop from the default set. These settings
214 correspond to the
<option>--capability=
</option> and
215 <option>--drop-capability=
</option> command line
216 switches. Note that
<varname>Capability=
</varname> is a
217 privileged setting, and only takes effect in
218 <filename>.nspawn
</filename> files in
219 <filename>/etc/systemd/nspawn/
</filename> and
220 <filename>/run/system/nspawn/
</filename> (see above). On the
221 other hand,
<varname>DropCapability=
</varname> takes effect in
222 all cases.
</para></listitem>
226 <term><varname>NoNewPrivileges=
</varname></term>
228 <listitem><para>Takes a boolean argument that controls the
<constant>PR_SET_NO_NEW_PRIVS
</constant> flag for
229 the container payload. This is equivalent to the
230 <option>--no-new-privileges=
</option> command line switch. See
231 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
237 <term><varname>KillSignal=
</varname></term>
239 <listitem><para>Specify the process signal to send to the
240 container's PID
1 when nspawn itself receives SIGTERM, in
241 order to trigger an orderly shutdown of the container.
242 Defaults to SIGRTMIN+
3 if
<option>Boot=
</option> is used
243 (on systemd-compatible init systems SIGRTMIN+
3 triggers an
244 orderly shutdown). For a list of valid signals, see
245 <citerefentry project='man-pages'
><refentrytitle>signal
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
</para></listitem>
249 <term><varname>Personality=
</varname></term>
251 <listitem><para>Configures the kernel personality for the
252 container. This is equivalent to the
253 <option>--personality=
</option> switch.
</para></listitem>
257 <term><varname>MachineID=
</varname></term>
259 <listitem><para>Configures the
128-bit machine ID (UUID) to pass to
260 the container. This is equivalent to the
261 <option>--uuid=
</option> command line switch. This option is
262 privileged (see above).
</para></listitem>
266 <term><varname>PrivateUsers=
</varname></term>
268 <listitem><para>Configures support for usernamespacing. This is equivalent to the
269 <option>--private-users=
</option> command line switch, and takes the same options. This option is privileged
270 (see above). This option is the default if the
<filename>systemd-nspawn@.service
</filename> template unit file
271 is used.
</para></listitem>
275 <term><varname>NotifyReady=
</varname></term>
277 <listitem><para>Configures support for notifications from the container's init process. This is equivalent to
278 the
<option>--notify-ready=
</option> command line switch, and takes the same parameters. See
279 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for details
280 about the specific options supported.
</para></listitem>
284 <term><varname>SystemCallFilter=
</varname></term>
286 <listitem><para>Configures the system call filter applied to containers. This is equivalent to the
287 <option>--system-call-filter=
</option> command line switch, and takes the same list parameter. See
288 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
289 details.
</para></listitem>
293 <term><varname>LimitCPU=
</varname></term>
294 <term><varname>LimitFSIZE=
</varname></term>
295 <term><varname>LimitDATA=
</varname></term>
296 <term><varname>LimitSTACK=
</varname></term>
297 <term><varname>LimitCORE=
</varname></term>
298 <term><varname>LimitRSS=
</varname></term>
299 <term><varname>LimitNOFILE=
</varname></term>
300 <term><varname>LimitAS=
</varname></term>
301 <term><varname>LimitNPROC=
</varname></term>
302 <term><varname>LimitMEMLOCK=
</varname></term>
303 <term><varname>LimitLOCKS=
</varname></term>
304 <term><varname>LimitSIGPENDING=
</varname></term>
305 <term><varname>LimitMSGQUEUE=
</varname></term>
306 <term><varname>LimitNICE=
</varname></term>
307 <term><varname>LimitRTPRIO=
</varname></term>
308 <term><varname>LimitRTTIME=
</varname></term>
310 <listitem><para>Configures various types of resource limits applied to containers. This is equivalent to the
311 <option>--rlimit=
</option> command line switch, and takes the same arguments. See
312 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
313 details.
</para></listitem>
317 <term><varname>OOMScoreAdjust=
</varname></term>
319 <listitem><para>Configures the OOM score adjustment value. This is equivalent to the
320 <option>--oom-score-adjust=
</option> command line switch, and takes the same argument. See
321 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
322 details.
</para></listitem>
326 <term><varname>CPUAffinity=
</varname></term>
328 <listitem><para>Configures the CPU affinity. This is equivalent to the
<option>--cpu-affinity=
</option> command
329 line switch, and takes the same argument. See
330 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
331 details.
</para></listitem>
335 <term><varname>Hostname=
</varname></term>
337 <listitem><para>Configures the kernel hostname set for the container. This is equivalent to the
338 <option>--hostname=
</option> command line switch, and takes the same argument. See
339 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
340 details.
</para></listitem>
347 <title>[Files] Section Options
</title>
349 <para>Settings files may include a
<literal>[Files]
</literal>
350 section, which carries various parameters configuring the file
351 system of the container:
</para>
356 <term><varname>ReadOnly=
</varname></term>
358 <listitem><para>Takes a boolean argument, which defaults to off. If
359 specified, the container will be run with a read-only file
360 system. This setting corresponds to the
361 <option>--read-only
</option> command line
362 switch.
</para></listitem>
366 <term><varname>Volatile=
</varname></term>
368 <listitem><para>Takes a boolean argument, or the special value
369 <literal>state
</literal>. This configures whether to run the
370 container with volatile state and/or configuration. This
371 option is equivalent to
<option>--volatile=
</option>, see
372 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
373 for details about the specific options
374 supported.
</para></listitem>
378 <term><varname>Bind=
</varname></term>
379 <term><varname>BindReadOnly=
</varname></term>
381 <listitem><para>Adds a bind mount from the host into the
382 container. Takes a single path, a pair of two paths separated
383 by a colon, or a triplet of two paths plus an option string
384 separated by colons. This option may be used multiple times to
385 configure multiple bind mounts. This option is equivalent to
386 the command line switches
<option>--bind=
</option> and
387 <option>--bind-ro=
</option>, see
388 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
389 for details about the specific options supported. This setting
390 is privileged (see above).
</para></listitem>
394 <term><varname>TemporaryFileSystem=
</varname></term>
396 <listitem><para>Adds a
<literal>tmpfs
</literal> mount to the
397 container. Takes a path or a pair of path and option string,
398 separated by a colon. This option may be used multiple times to
399 configure multiple
<literal>tmpfs
</literal> mounts. This
400 option is equivalent to the command line switch
401 <option>--tmpfs=
</option>, see
402 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
403 for details about the specific options supported. This setting
404 is privileged (see above).
</para></listitem>
408 <term><varname>Overlay=
</varname></term>
409 <term><varname>OverlayReadOnly=
</varname></term>
411 <listitem><para>Adds an overlay mount point. Takes a colon-separated list of paths. This option may be used
412 multiple times to configure multiple overlay mounts. This option is equivalent to the command line switches
413 <option>--overlay=
</option> and
<option>--overlay-ro=
</option>, see
414 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for details
415 about the specific options supported. This setting is privileged (see above).
</para></listitem>
419 <term><varname>PrivateUsersChown=
</varname></term>
421 <listitem><para>Configures whether the ownership of the files and directories in the container tree shall be
422 adjusted to the UID/GID range used, if necessary and user namespacing is enabled. This is equivalent to the
423 <option>--private-users-chown
</option> command line switch. This option is privileged (see
424 above).
</para></listitem>
431 <title>[Network] Section Options
</title>
433 <para>Settings files may include a
<literal>[Network]
</literal>
434 section, which carries various parameters configuring the network
435 connectivity of the container:
</para>
440 <term><varname>Private=
</varname></term>
442 <listitem><para>Takes a boolean argument, which defaults to off. If
443 enabled, the container will run in its own network namespace
444 and not share network interfaces and configuration with the
445 host. This setting corresponds to the
446 <option>--private-network
</option> command line
447 switch.
</para></listitem>
451 <term><varname>VirtualEthernet=
</varname></term>
453 <listitem><para>Takes a boolean argument. Configures whether to create a virtual Ethernet connection
454 (
<literal>veth
</literal>) between host and the container. This setting implies
455 <varname>Private=yes
</varname>. This setting corresponds to the
<option>--network-veth
</option> command line
456 switch. This option is privileged (see above). This option is the default if the
457 <filename>systemd-nspawn@.service
</filename> template unit file is used.
</para></listitem>
461 <term><varname>VirtualEthernetExtra=
</varname></term>
463 <listitem><para>Takes a colon-separated pair of interface
464 names. Configures an additional virtual Ethernet connection
465 (
<literal>veth
</literal>) between host and the container. The
466 first specified name is the interface name on the host, the
467 second the interface name in the container. The latter may be
468 omitted in which case it is set to the same name as the host
469 side interface. This setting implies
470 <varname>Private=yes
</varname>. This setting corresponds to
471 the
<option>--network-veth-extra=
</option> command line
472 switch, and maybe be used multiple times. It is independent of
473 <varname>VirtualEthernet=
</varname>. This option is privileged
474 (see above).
</para></listitem>
478 <term><varname>Interface=
</varname></term>
480 <listitem><para>Takes a space-separated list of interfaces to
481 add to the container. This option corresponds to the
482 <option>--network-interface=
</option> command line switch and
483 implies
<varname>Private=yes
</varname>. This option is
484 privileged (see above).
</para></listitem>
488 <term><varname>MACVLAN=
</varname></term>
489 <term><varname>IPVLAN=
</varname></term>
491 <listitem><para>Takes a space-separated list of interfaces to
492 add MACLVAN or IPVLAN interfaces to, which are then added to
493 the container. These options correspond to the
494 <option>--network-macvlan=
</option> and
495 <option>--network-ipvlan=
</option> command line switches and
496 imply
<varname>Private=yes
</varname>. These options are
497 privileged (see above).
</para></listitem>
501 <term><varname>Bridge=
</varname></term>
503 <listitem><para>Takes an interface name. This setting implies
504 <varname>VirtualEthernet=yes
</varname> and
505 <varname>Private=yes
</varname> and has the effect that the
506 host side of the created virtual Ethernet link is connected to
507 the specified bridge interface. This option corresponds to the
508 <option>--network-bridge=
</option> command line switch. This
509 option is privileged (see above).
</para></listitem>
513 <term><varname>Zone=
</varname></term>
515 <listitem><para>Takes a network zone name. This setting implies
<varname>VirtualEthernet=yes
</varname> and
516 <varname>Private=yes
</varname> and has the effect that the host side of the created virtual Ethernet link is
517 connected to an automatically managed bridge interface named after the passed argument, prefixed with
518 <literal>vz-
</literal>. This option corresponds to the
<option>--network-zone=
</option> command line
519 switch. This option is privileged (see above).
</para></listitem>
523 <term><varname>Port=
</varname></term>
525 <listitem><para>Exposes a TCP or UDP port of the container on
526 the host. This option corresponds to the
527 <option>--port=
</option> command line switch, see
528 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
529 for the precise syntax of the argument this option takes. This
530 option is privileged (see above).
</para></listitem>
536 <title>See Also
</title>
538 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
539 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
540 <citerefentry><refentrytitle>systemd.directives
</refentrytitle><manvolnum>7</manvolnum></citerefentry>