]> git.ipfire.org Git - thirdparty/systemd.git/blob - man/systemd.nspawn.xml
doc: document the `architecture` setting
[thirdparty/systemd.git] / man / systemd.nspawn.xml
1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4 <!ENTITY % entities SYSTEM "custom-entities.ent" >
5 %entities;
6 ]>
7
8 <!--
9 SPDX-License-Identifier: LGPL-2.1+
10 -->
11
12 <refentry id="systemd.nspawn">
13
14 <refentryinfo>
15 <title>systemd.nspawn</title>
16 <productname>systemd</productname>
17 </refentryinfo>
18
19 <refmeta>
20 <refentrytitle>systemd.nspawn</refentrytitle>
21 <manvolnum>5</manvolnum>
22 </refmeta>
23
24 <refnamediv>
25 <refname>systemd.nspawn</refname>
26 <refpurpose>Container settings</refpurpose>
27 </refnamediv>
28
29 <refsynopsisdiv>
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>
33 </refsynopsisdiv>
34
35 <refsect1>
36 <title>Description</title>
37
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
41 used by
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>
54
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
61 equivalent.</para>
62
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>
68
69 </refsect1>
70
71 <refsect1>
72 <title><filename>.nspawn</filename> File Discovery</title>
73
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>
90
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>
104 switch, see
105 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
106 for details.</para>
107 </refsect1>
108
109 <refsect1>
110 <title>[Exec] Section Options</title>
111
112 <para>Settings files may include an <literal>[Exec]</literal>
113 section, which carries various execution parameters:</para>
114
115 <variablelist>
116
117 <varlistentry>
118 <term><varname>Boot=</varname></term>
119
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>
127 </varlistentry>
128
129 <varlistentry>
130 <term><varname>ProcessTwo=</varname></term>
131
132 <listitem><para>Takes a boolean argument, which defaults to off. If enabled, the specified program is run as
133 PID 2. A stub init process is run as PID 1. This setting corresponds to the <option>--as-pid2</option> switch
134 on the <command>systemd-nspawn</command> command line. This option may not be combined with
135 <varname>Boot=yes</varname>.</para></listitem>
136 </varlistentry>
137
138 <varlistentry>
139 <term><varname>Parameters=</varname></term>
140
141 <listitem><para>Takes a space-separated list of
142 arguments. This is either a command line, beginning with the
143 binary name to execute, or – if <varname>Boot=</varname> is
144 enabled – the list of arguments to pass to the init
145 process. This setting corresponds to the command line
146 parameters passed on the <command>systemd-nspawn</command>
147 command line.</para></listitem>
148 </varlistentry>
149
150 <varlistentry>
151 <term><varname>Environment=</varname></term>
152
153 <listitem><para>Takes an environment variable assignment
154 consisting of key and value, separated by
155 <literal>=</literal>. Sets an environment variable for the
156 main process invoked in the container. This setting may be
157 used multiple times to set multiple environment variables. It
158 corresponds to the <option>--setenv=</option> command line
159 switch.</para></listitem>
160 </varlistentry>
161
162 <varlistentry>
163 <term><varname>User=</varname></term>
164
165 <listitem><para>Takes a UNIX user name. Specifies the user
166 name to invoke the main process of the container as. This user
167 must be known in the container's user database. This
168 corresponds to the <option>--user=</option> command line
169 switch.</para></listitem>
170 </varlistentry>
171
172 <varlistentry>
173 <term><varname>WorkingDirectory=</varname></term>
174
175 <listitem><para>Selects the working directory for the process invoked in the container. Expects an absolute
176 path in the container's file system namespace. This corresponds to the <option>--chdir=</option> command line
177 switch.</para></listitem>
178 </varlistentry>
179
180 <varlistentry>
181 <term><varname>PivotRoot=</varname></term>
182
183 <listitem><para>Selects a directory to pivot to <filename>/</filename> inside the container when starting up.
184 Takes a single path, or a pair of two paths separated by a colon. Both paths must be absolute, and are resolved
185 in the container's file system namespace. This corresponds to the <option>--pivot-root=</option> command line
186 switch.</para></listitem>
187 </varlistentry>
188
189 <varlistentry>
190 <term><varname>Capability=</varname></term>
191 <term><varname>DropCapability=</varname></term>
192
193 <listitem><para>Takes a space-separated list of Linux process
194 capabilities (see
195 <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
196 for details). The <varname>Capability=</varname> setting
197 specifies additional capabilities to pass on top of the
198 default set of capabilities. The
199 <varname>DropCapability=</varname> setting specifies
200 capabilities to drop from the default set. These settings
201 correspond to the <option>--capability=</option> and
202 <option>--drop-capability=</option> command line
203 switches. Note that <varname>Capability=</varname> is a
204 privileged setting, and only takes effect in
205 <filename>.nspawn</filename> files in
206 <filename>/etc/systemd/nspawn/</filename> and
207 <filename>/run/system/nspawn/</filename> (see above). On the
208 other hand, <varname>DropCapability=</varname> takes effect in
209 all cases.</para></listitem>
210 </varlistentry>
211
212 <varlistentry>
213 <term><varname>NoNewPrivileges=</varname></term>
214
215 <listitem><para>Takes a boolean argument that controls the <constant>PR_SET_NO_NEW_PRIVS</constant> flag for
216 the container payload. This is equivalent to the
217 <option>--no-new-privileges=</option> command line switch. See
218 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
219 details.</para>
220 </listitem>
221 </varlistentry>
222
223 <varlistentry>
224 <term><varname>KillSignal=</varname></term>
225
226 <listitem><para>Specify the process signal to send to the
227 container's PID 1 when nspawn itself receives SIGTERM, in
228 order to trigger an orderly shutdown of the container.
229 Defaults to SIGRTMIN+3 if <option>Boot=</option> is used
230 (on systemd-compatible init systems SIGRTMIN+3 triggers an
231 orderly shutdown). For a list of valid signals, see
232 <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para></listitem>
233 </varlistentry>
234
235 <varlistentry>
236 <term><varname>Personality=</varname></term>
237
238 <listitem><para>Configures the kernel personality for the
239 container. This is equivalent to the
240 <option>--personality=</option> switch.</para></listitem>
241 </varlistentry>
242
243 <varlistentry>
244 <term><varname>MachineID=</varname></term>
245
246 <listitem><para>Configures the 128-bit machine ID (UUID) to pass to
247 the container. This is equivalent to the
248 <option>--uuid=</option> command line switch. This option is
249 privileged (see above). </para></listitem>
250 </varlistentry>
251
252 <varlistentry>
253 <term><varname>PrivateUsers=</varname></term>
254
255 <listitem><para>Configures support for usernamespacing. This is equivalent to the
256 <option>--private-users=</option> command line switch, and takes the same options. This option is privileged
257 (see above). This option is the default if the <filename>systemd-nspawn@.service</filename> template unit file
258 is used.</para></listitem>
259 </varlistentry>
260
261 <varlistentry>
262 <term><varname>NotifyReady=</varname></term>
263
264 <listitem><para>Configures support for notifications from the container's init process. This is equivalent to
265 the <option>--notify-ready=</option> command line switch, and takes the same parameters. See
266 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> for details
267 about the specific options supported.</para></listitem>
268 </varlistentry>
269
270 <varlistentry>
271 <term><varname>SystemCallFilter=</varname></term>
272
273 <listitem><para>Configures the system call filter applied to containers. This is equivalent to the
274 <option>--system-call-filter=</option> command line switch, and takes the same list parameter. See
275 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
276 details.</para></listitem>
277 </varlistentry>
278
279 <varlistentry>
280 <term><varname>LimitCPU=</varname></term>
281 <term><varname>LimitFSIZE=</varname></term>
282 <term><varname>LimitDATA=</varname></term>
283 <term><varname>LimitSTACK=</varname></term>
284 <term><varname>LimitCORE=</varname></term>
285 <term><varname>LimitRSS=</varname></term>
286 <term><varname>LimitNOFILE=</varname></term>
287 <term><varname>LimitAS=</varname></term>
288 <term><varname>LimitNPROC=</varname></term>
289 <term><varname>LimitMEMLOCK=</varname></term>
290 <term><varname>LimitLOCKS=</varname></term>
291 <term><varname>LimitSIGPENDING=</varname></term>
292 <term><varname>LimitMSGQUEUE=</varname></term>
293 <term><varname>LimitNICE=</varname></term>
294 <term><varname>LimitRTPRIO=</varname></term>
295 <term><varname>LimitRTTIME=</varname></term>
296
297 <listitem><para>Configures various types of resource limits applied to containers. This is equivalent to the
298 <option>--rlimit=</option> command line switch, and takes the same arguments. See
299 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
300 details.</para></listitem>
301 </varlistentry>
302
303 <varlistentry>
304 <term><varname>OOMScoreAdjust=</varname></term>
305
306 <listitem><para>Configures the OOM score adjustment value. This is equivalent to the
307 <option>--oom-score-adjust=</option> command line switch, and takes the same argument. See
308 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
309 details.</para></listitem>
310 </varlistentry>
311
312 <varlistentry>
313 <term><varname>CPUAffinity=</varname></term>
314
315 <listitem><para>Configures the CPU affinity. This is equivalent to the <option>--cpu-affinity=</option> command
316 line switch, and takes the same argument. See
317 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
318 details.</para></listitem>
319 </varlistentry>
320
321 <varlistentry>
322 <term><varname>Hostname=</varname></term>
323
324 <listitem><para>Configures the kernel hostname set for the container. This is equivalent to the
325 <option>--hostname=</option> command line switch, and takes the same argument. See
326 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
327 details.</para></listitem>
328 </varlistentry>
329
330 <varlistentry>
331 <term><varname>ResolvConf=</varname></term>
332
333 <listitem><para>Configures how <filename>/etc/resolv.conf</filename> in the container shall be handled. This is
334 equivalent to the <option>--resolv-conf=</option> command line switch, and takes the same argument. See
335 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
336 details.</para></listitem>
337 </varlistentry>
338
339 <varlistentry>
340 <term><varname>Timezone=</varname></term>
341
342 <listitem><para>Configures how <filename>/etc/localtime</filename> in the container shall be handled. This is
343 equivalent to the <option>--localtime=</option> command line switch, and takes the same argument. See
344 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
345 details.</para></listitem>
346 </varlistentry>
347
348 <varlistentry>
349 <term><varname>LinkJournal=</varname></term>
350
351 <listitem><para>Configures how to link host and container journal setups. This is equivalent to the
352 <option>--link-journal=</option> command line switch, and takes the same parameter. See
353 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
354 details.</para></listitem>
355 </varlistentry>
356
357 </variablelist>
358 </refsect1>
359
360 <refsect1>
361 <title>[Files] Section Options</title>
362
363 <para>Settings files may include a <literal>[Files]</literal>
364 section, which carries various parameters configuring the file
365 system of the container:</para>
366
367 <variablelist>
368
369 <varlistentry>
370 <term><varname>ReadOnly=</varname></term>
371
372 <listitem><para>Takes a boolean argument, which defaults to off. If
373 specified, the container will be run with a read-only file
374 system. This setting corresponds to the
375 <option>--read-only</option> command line
376 switch.</para></listitem>
377 </varlistentry>
378
379 <varlistentry>
380 <term><varname>Volatile=</varname></term>
381
382 <listitem><para>Takes a boolean argument, or the special value
383 <literal>state</literal>. This configures whether to run the
384 container with volatile state and/or configuration. This
385 option is equivalent to <option>--volatile=</option>, see
386 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
387 for details about the specific options
388 supported.</para></listitem>
389 </varlistentry>
390
391 <varlistentry>
392 <term><varname>Bind=</varname></term>
393 <term><varname>BindReadOnly=</varname></term>
394
395 <listitem><para>Adds a bind mount from the host into the
396 container. Takes a single path, a pair of two paths separated
397 by a colon, or a triplet of two paths plus an option string
398 separated by colons. This option may be used multiple times to
399 configure multiple bind mounts. This option is equivalent to
400 the command line switches <option>--bind=</option> and
401 <option>--bind-ro=</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>
405 </varlistentry>
406
407 <varlistentry>
408 <term><varname>TemporaryFileSystem=</varname></term>
409
410 <listitem><para>Adds a <literal>tmpfs</literal> mount to the
411 container. Takes a path or a pair of path and option string,
412 separated by a colon. This option may be used multiple times to
413 configure multiple <literal>tmpfs</literal> mounts. This
414 option is equivalent to the command line switch
415 <option>--tmpfs=</option>, see
416 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
417 for details about the specific options supported. This setting
418 is privileged (see above).</para></listitem>
419 </varlistentry>
420
421 <varlistentry>
422 <term><varname>Overlay=</varname></term>
423 <term><varname>OverlayReadOnly=</varname></term>
424
425 <listitem><para>Adds an overlay mount point. Takes a colon-separated list of paths. This option may be used
426 multiple times to configure multiple overlay mounts. This option is equivalent to the command line switches
427 <option>--overlay=</option> and <option>--overlay-ro=</option>, see
428 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> for details
429 about the specific options supported. This setting is privileged (see above).</para></listitem>
430 </varlistentry>
431
432 <varlistentry>
433 <term><varname>PrivateUsersChown=</varname></term>
434
435 <listitem><para>Configures whether the ownership of the files and directories in the container tree shall be
436 adjusted to the UID/GID range used, if necessary and user namespacing is enabled. This is equivalent to the
437 <option>--private-users-chown</option> command line switch. This option is privileged (see
438 above). </para></listitem>
439 </varlistentry>
440
441 </variablelist>
442 </refsect1>
443
444 <refsect1>
445 <title>[Network] Section Options</title>
446
447 <para>Settings files may include a <literal>[Network]</literal>
448 section, which carries various parameters configuring the network
449 connectivity of the container:</para>
450
451 <variablelist>
452
453 <varlistentry>
454 <term><varname>Private=</varname></term>
455
456 <listitem><para>Takes a boolean argument, which defaults to off. If
457 enabled, the container will run in its own network namespace
458 and not share network interfaces and configuration with the
459 host. This setting corresponds to the
460 <option>--private-network</option> command line
461 switch.</para></listitem>
462 </varlistentry>
463
464 <varlistentry>
465 <term><varname>VirtualEthernet=</varname></term>
466
467 <listitem><para>Takes a boolean argument. Configures whether to create a virtual Ethernet connection
468 (<literal>veth</literal>) between host and the container. This setting implies
469 <varname>Private=yes</varname>. This setting corresponds to the <option>--network-veth</option> command line
470 switch. This option is privileged (see above). This option is the default if the
471 <filename>systemd-nspawn@.service</filename> template unit file is used.</para></listitem>
472 </varlistentry>
473
474 <varlistentry>
475 <term><varname>VirtualEthernetExtra=</varname></term>
476
477 <listitem><para>Takes a colon-separated pair of interface
478 names. Configures an additional virtual Ethernet connection
479 (<literal>veth</literal>) between host and the container. The
480 first specified name is the interface name on the host, the
481 second the interface name in the container. The latter may be
482 omitted in which case it is set to the same name as the host
483 side interface. This setting implies
484 <varname>Private=yes</varname>. This setting corresponds to
485 the <option>--network-veth-extra=</option> command line
486 switch, and maybe be used multiple times. It is independent of
487 <varname>VirtualEthernet=</varname>. This option is privileged
488 (see above).</para></listitem>
489 </varlistentry>
490
491 <varlistentry>
492 <term><varname>Interface=</varname></term>
493
494 <listitem><para>Takes a space-separated list of interfaces to
495 add to the container. This option corresponds to the
496 <option>--network-interface=</option> command line switch and
497 implies <varname>Private=yes</varname>. This option is
498 privileged (see above).</para></listitem>
499 </varlistentry>
500
501 <varlistentry>
502 <term><varname>MACVLAN=</varname></term>
503 <term><varname>IPVLAN=</varname></term>
504
505 <listitem><para>Takes a space-separated list of interfaces to
506 add MACLVAN or IPVLAN interfaces to, which are then added to
507 the container. These options correspond to the
508 <option>--network-macvlan=</option> and
509 <option>--network-ipvlan=</option> command line switches and
510 imply <varname>Private=yes</varname>. These options are
511 privileged (see above).</para></listitem>
512 </varlistentry>
513
514 <varlistentry>
515 <term><varname>Bridge=</varname></term>
516
517 <listitem><para>Takes an interface name. This setting implies
518 <varname>VirtualEthernet=yes</varname> and
519 <varname>Private=yes</varname> and has the effect that the
520 host side of the created virtual Ethernet link is connected to
521 the specified bridge interface. This option corresponds to the
522 <option>--network-bridge=</option> command line switch. This
523 option is privileged (see above).</para></listitem>
524 </varlistentry>
525
526 <varlistentry>
527 <term><varname>Zone=</varname></term>
528
529 <listitem><para>Takes a network zone name. This setting implies <varname>VirtualEthernet=yes</varname> and
530 <varname>Private=yes</varname> and has the effect that the host side of the created virtual Ethernet link is
531 connected to an automatically managed bridge interface named after the passed argument, prefixed with
532 <literal>vz-</literal>. This option corresponds to the <option>--network-zone=</option> command line
533 switch. This option is privileged (see above).</para></listitem>
534 </varlistentry>
535
536 <varlistentry>
537 <term><varname>Port=</varname></term>
538
539 <listitem><para>Exposes a TCP or UDP port of the container on
540 the host. This option corresponds to the
541 <option>--port=</option> command line switch, see
542 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
543 for the precise syntax of the argument this option takes. This
544 option is privileged (see above).</para></listitem>
545 </varlistentry>
546 </variablelist>
547 </refsect1>
548
549 <refsect1>
550 <title>See Also</title>
551 <para>
552 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
553 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
554 <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
555 </para>
556 </refsect1>
557
558 </refentry>