1SYSTEMD.NSPAWN(5)               systemd.nspawn               SYSTEMD.NSPAWN(5)
2
3
4

NAME

6       systemd.nspawn - Container settings
7

SYNOPSIS

9       /etc/systemd/nspawn/machine.nspawn
10
11       /run/systemd/nspawn/machine.nspawn
12
13       /var/lib/machines/machine.nspawn
14

DESCRIPTION

16       An nspawn container settings file (suffix .nspawn) encodes additional
17       runtime information about a local container, and is searched, read and
18       used by systemd-nspawn(1) when starting a container. Files of this type
19       are named after the containers they define settings for. They are
20       optional, and only required for containers whose execution environment
21       shall differ from the defaults. Files of this type mostly contain
22       settings that may also be set on the systemd-nspawn command line, and
23       make it easier to persistently attach specific settings to specific
24       containers. The syntax of these files is inspired by .desktop files
25       following the XDG Desktop Entry Specification[1], which in turn are
26       inspired by Microsoft Windows .ini files.
27
28       Boolean arguments used in these settings files can be written in
29       various formats. For positive settings, the strings 1, yes, true and on
30       are equivalent. For negative settings, the strings 0, no, false and off
31       are equivalent.
32
33       Empty lines and lines starting with # or ; are ignored. This may be
34       used for commenting. Lines ending in a backslash are concatenated with
35       the following line while reading and the backslash is replaced by a
36       space character. This may be used to wrap long lines.
37

.NSPAWN FILE DISCOVERY

39       Files are searched by appending the .nspawn suffix to the machine name
40       of the container, as specified with the --machine= switch of
41       systemd-nspawn, or derived from the directory or image file name. This
42       file is first searched in /etc/systemd/nspawn/ and
43       /run/systemd/nspawn/. If found in these directories, its settings are
44       read and all of them take full effect (but are possibly overridden by
45       corresponding command line arguments). If not found, the file will then
46       be searched next to the image file or in the immediate parent of the
47       root directory of the container. If the file is found there, only a
48       subset of the settings will take effect however. All settings that
49       possibly elevate privileges or grant additional access to resources of
50       the host (such as files or directories) are ignored. To which options
51       this applies is documented below.
52
53       Persistent settings files created and maintained by the administrator
54       (and thus trusted) should be placed in /etc/systemd/nspawn/, while
55       automatically downloaded (and thus potentially untrusted) settings
56       files are placed in /var/lib/machines/ instead (next to the container
57       images), where their security impact is limited. In order to add
58       privileged settings to .nspawn files acquired from the image vendor, it
59       is recommended to copy the settings files into /etc/systemd/nspawn/ and
60       edit them there, so that the privileged options become available. The
61       precise algorithm for how the files are searched and interpreted may be
62       configured with systemd-nspawn's --settings= switch, see systemd-
63       nspawn(1) for details.
64

[EXEC] SECTION OPTIONS

66       Settings files may include an "[Exec]" section, which carries various
67       execution parameters:
68
69       Boot=
70           Takes a boolean argument, which defaults to off. If enabled,
71           systemd-nspawn will automatically search for an init executable and
72           invoke it. In this case, the specified parameters using Parameters=
73           are passed as additional arguments to the init process. This
74           setting corresponds to the --boot switch on the systemd-nspawn
75           command line. This option may not be combined with ProcessTwo=yes.
76           This option is the default if the systemd-nspawn@.service template
77           unit file is used.
78
79       ProcessTwo=
80           Takes a boolean argument, which defaults to off. If enabled, the
81           specified program is run as PID 2. A stub init process is run as
82           PID 1. This setting corresponds to the --as-pid2 switch on the
83           systemd-nspawn command line. This option may not be combined with
84           Boot=yes.
85
86       Parameters=
87           Takes a space-separated list of arguments. This is either a command
88           line, beginning with the binary name to execute, or – if Boot= is
89           enabled – the list of arguments to pass to the init process. This
90           setting corresponds to the command line parameters passed on the
91           systemd-nspawn command line.
92
93       Environment=
94           Takes an environment variable assignment consisting of key and
95           value, separated by "=". Sets an environment variable for the main
96           process invoked in the container. This setting may be used multiple
97           times to set multiple environment variables. It corresponds to the
98           --setenv= command line switch.
99
100       User=
101           Takes a UNIX user name. Specifies the user name to invoke the main
102           process of the container as. This user must be known in the
103           container's user database. This corresponds to the --user= command
104           line switch.
105
106       WorkingDirectory=
107           Selects the working directory for the process invoked in the
108           container. Expects an absolute path in the container's file system
109           namespace. This corresponds to the --chdir= command line switch.
110
111       PivotRoot=
112           Selects a directory to pivot to / inside the container when
113           starting up. Takes a single path, or a pair of two paths separated
114           by a colon. Both paths must be absolute, and are resolved in the
115           container's file system namespace. This corresponds to the
116           --pivot-root= command line switch.
117
118       Capability=, DropCapability=
119           Takes a space-separated list of Linux process capabilities (see
120           capabilities(7) for details). The Capability= setting specifies
121           additional capabilities to pass on top of the default set of
122           capabilities. The DropCapability= setting specifies capabilities to
123           drop from the default set. These settings correspond to the
124           --capability= and --drop-capability= command line switches. Note
125           that Capability= is a privileged setting, and only takes effect in
126           .nspawn files in /etc/systemd/nspawn/ and /run/system/nspawn/ (see
127           above). On the other hand, DropCapability= takes effect in all
128           cases.
129
130       NoNewPrivileges=
131           Takes a boolean argument that controls the PR_SET_NO_NEW_PRIVS flag
132           for the container payload. This is equivalent to the
133           --no-new-privileges= command line switch. See systemd-nspawn(1) for
134           details.
135
136       KillSignal=
137           Specify the process signal to send to the container's PID 1 when
138           nspawn itself receives SIGTERM, in order to trigger an orderly
139           shutdown of the container. Defaults to SIGRTMIN+3 if Boot= is used
140           (on systemd-compatible init systems SIGRTMIN+3 triggers an orderly
141           shutdown). For a list of valid signals, see signal(7).
142
143       Personality=
144           Configures the kernel personality for the container. This is
145           equivalent to the --personality= switch.
146
147       MachineID=
148           Configures the 128-bit machine ID (UUID) to pass to the container.
149           This is equivalent to the --uuid= command line switch. This option
150           is privileged (see above).
151
152       PrivateUsers=
153           Configures support for usernamespacing. This is equivalent to the
154           --private-users= command line switch, and takes the same options.
155           This option is privileged (see above). This option is the default
156           if the systemd-nspawn@.service template unit file is used.
157
158       NotifyReady=
159           Configures support for notifications from the container's init
160           process. This is equivalent to the --notify-ready= command line
161           switch, and takes the same parameters. See systemd-nspawn(1) for
162           details about the specific options supported.
163
164       SystemCallFilter=
165           Configures the system call filter applied to containers. This is
166           equivalent to the --system-call-filter= command line switch, and
167           takes the same list parameter. See systemd-nspawn(1) for details.
168
169       LimitCPU=, LimitFSIZE=, LimitDATA=, LimitSTACK=, LimitCORE=, LimitRSS=,
170       LimitNOFILE=, LimitAS=, LimitNPROC=, LimitMEMLOCK=, LimitLOCKS=,
171       LimitSIGPENDING=, LimitMSGQUEUE=, LimitNICE=, LimitRTPRIO=,
172       LimitRTTIME=
173           Configures various types of resource limits applied to containers.
174           This is equivalent to the --rlimit= command line switch, and takes
175           the same arguments. See systemd-nspawn(1) for details.
176
177       OOMScoreAdjust=
178           Configures the OOM score adjustment value. This is equivalent to
179           the --oom-score-adjust= command line switch, and takes the same
180           argument. See systemd-nspawn(1) for details.
181
182       CPUAffinity=
183           Configures the CPU affinity. This is equivalent to the
184           --cpu-affinity= command line switch, and takes the same argument.
185           See systemd-nspawn(1) for details.
186
187       Hostname=
188           Configures the kernel hostname set for the container. This is
189           equivalent to the --hostname= command line switch, and takes the
190           same argument. See systemd-nspawn(1) for details.
191
192       ResolvConf=
193           Configures how /etc/resolv.conf in the container shall be handled.
194           This is equivalent to the --resolv-conf= command line switch, and
195           takes the same argument. See systemd-nspawn(1) for details.
196
197       Timezone=
198           Configures how /etc/localtime in the container shall be handled.
199           This is equivalent to the --localtime= command line switch, and
200           takes the same argument. See systemd-nspawn(1) for details.
201
202       LinkJournal=
203           Configures how to link host and container journal setups. This is
204           equivalent to the --link-journal= command line switch, and takes
205           the same parameter. See systemd-nspawn(1) for details.
206

[FILES] SECTION OPTIONS

208       Settings files may include a "[Files]" section, which carries various
209       parameters configuring the file system of the container:
210
211       ReadOnly=
212           Takes a boolean argument, which defaults to off. If specified, the
213           container will be run with a read-only file system. This setting
214           corresponds to the --read-only command line switch.
215
216       Volatile=
217           Takes a boolean argument, or the special value "state". This
218           configures whether to run the container with volatile state and/or
219           configuration. This option is equivalent to --volatile=, see
220           systemd-nspawn(1) for details about the specific options supported.
221
222       Bind=, BindReadOnly=
223           Adds a bind mount from the host into the container. Takes a single
224           path, a pair of two paths separated by a colon, or a triplet of two
225           paths plus an option string separated by colons. This option may be
226           used multiple times to configure multiple bind mounts. This option
227           is equivalent to the command line switches --bind= and --bind-ro=,
228           see systemd-nspawn(1) for details about the specific options
229           supported. This setting is privileged (see above).
230
231       TemporaryFileSystem=
232           Adds a "tmpfs" mount to the container. Takes a path or a pair of
233           path and option string, separated by a colon. This option may be
234           used multiple times to configure multiple "tmpfs" mounts. This
235           option is equivalent to the command line switch --tmpfs=, see
236           systemd-nspawn(1) for details about the specific options supported.
237           This setting is privileged (see above).
238
239       Overlay=, OverlayReadOnly=
240           Adds an overlay mount point. Takes a colon-separated list of paths.
241           This option may be used multiple times to configure multiple
242           overlay mounts. This option is equivalent to the command line
243           switches --overlay= and --overlay-ro=, see systemd-nspawn(1) for
244           details about the specific options supported. This setting is
245           privileged (see above).
246
247       PrivateUsersChown=
248           Configures whether the ownership of the files and directories in
249           the container tree shall be adjusted to the UID/GID range used, if
250           necessary and user namespacing is enabled. This is equivalent to
251           the --private-users-chown command line switch. This option is
252           privileged (see above).
253

[NETWORK] SECTION OPTIONS

255       Settings files may include a "[Network]" section, which carries various
256       parameters configuring the network connectivity of the container:
257
258       Private=
259           Takes a boolean argument, which defaults to off. If enabled, the
260           container will run in its own network namespace and not share
261           network interfaces and configuration with the host. This setting
262           corresponds to the --private-network command line switch.
263
264       VirtualEthernet=
265           Takes a boolean argument. Configures whether to create a virtual
266           Ethernet connection ("veth") between host and the container. This
267           setting implies Private=yes. This setting corresponds to the
268           --network-veth command line switch. This option is privileged (see
269           above). This option is the default if the systemd-nspawn@.service
270           template unit file is used.
271
272       VirtualEthernetExtra=
273           Takes a colon-separated pair of interface names. Configures an
274           additional virtual Ethernet connection ("veth") between host and
275           the container. The first specified name is the interface name on
276           the host, the second the interface name in the container. The
277           latter may be omitted in which case it is set to the same name as
278           the host side interface. This setting implies Private=yes. This
279           setting corresponds to the --network-veth-extra= command line
280           switch, and maybe be used multiple times. It is independent of
281           VirtualEthernet=. This option is privileged (see above).
282
283       Interface=
284           Takes a space-separated list of interfaces to add to the container.
285           This option corresponds to the --network-interface= command line
286           switch and implies Private=yes. This option is privileged (see
287           above).
288
289       MACVLAN=, IPVLAN=
290           Takes a space-separated list of interfaces to add MACLVAN or IPVLAN
291           interfaces to, which are then added to the container. These options
292           correspond to the --network-macvlan= and --network-ipvlan= command
293           line switches and imply Private=yes. These options are privileged
294           (see above).
295
296       Bridge=
297           Takes an interface name. This setting implies VirtualEthernet=yes
298           and Private=yes and has the effect that the host side of the
299           created virtual Ethernet link is connected to the specified bridge
300           interface. This option corresponds to the --network-bridge= command
301           line switch. This option is privileged (see above).
302
303       Zone=
304           Takes a network zone name. This setting implies VirtualEthernet=yes
305           and Private=yes and has the effect that the host side of the
306           created virtual Ethernet link is connected to an automatically
307           managed bridge interface named after the passed argument, prefixed
308           with "vz-". This option corresponds to the --network-zone= command
309           line switch. This option is privileged (see above).
310
311       Port=
312           Exposes a TCP or UDP port of the container on the host. This option
313           corresponds to the --port= command line switch, see systemd-
314           nspawn(1) for the precise syntax of the argument this option takes.
315           This option is privileged (see above).
316

SEE ALSO

318       systemd(1), systemd-nspawn(1), systemd.directives(7)
319

NOTES

321        1. XDG Desktop Entry Specification
322           http://standards.freedesktop.org/desktop-entry-spec/latest/
323
324
325
326systemd 239                                                  SYSTEMD.NSPAWN(5)
Impressum