]>
Commit | Line | Data |
---|---|---|
f757855e LP |
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 | This file is part of systemd. | |
10 | ||
11 | Copyright 2015 Lennart Poettering | |
12 | ||
13 | systemd is free software; you can redistribute it and/or modify it | |
14 | under the terms of the GNU Lesser General Public License as published by | |
15 | the Free Software Foundation; either version 2.1 of the License, or | |
16 | (at your option) any later version. | |
17 | ||
18 | systemd is distributed in the hope that it will be useful, but | |
19 | WITHOUT ANY WARRANTY; without even the implied warranty of | |
20 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
21 | Lesser General Public License for more details. | |
22 | ||
23 | You should have received a copy of the GNU Lesser General Public License | |
24 | along with systemd; If not, see <http://www.gnu.org/licenses/>. | |
25 | --> | |
26 | ||
27 | <refentry id="systemd.nspawn"> | |
28 | ||
29 | <refentryinfo> | |
30 | <title>systemd.nspawn</title> | |
31 | <productname>systemd</productname> | |
32 | ||
33 | <authorgroup> | |
34 | <author> | |
35 | <contrib>Developer</contrib> | |
36 | <firstname>Lennart</firstname> | |
37 | <surname>Poettering</surname> | |
38 | <email>lennart@poettering.net</email> | |
39 | </author> | |
40 | </authorgroup> | |
41 | </refentryinfo> | |
42 | ||
43 | <refmeta> | |
44 | <refentrytitle>systemd.nspawn</refentrytitle> | |
45 | <manvolnum>5</manvolnum> | |
46 | </refmeta> | |
47 | ||
48 | <refnamediv> | |
49 | <refname>systemd.nspawn</refname> | |
50 | <refpurpose>Container settings</refpurpose> | |
51 | </refnamediv> | |
52 | ||
53 | <refsynopsisdiv> | |
54 | <para><filename>/etc/systemd/nspawn/<replaceable>machine</replaceable>.nspawn</filename></para> | |
55 | <para><filename>/run/systemd/nspawn/<replaceable>machine</replaceable>.nspawn</filename></para> | |
56 | <para><filename>/var/lib/machines/<replaceable>machine</replaceable>.nspawn</filename></para> | |
57 | </refsynopsisdiv> | |
58 | ||
59 | <refsect1> | |
60 | <title>Description</title> | |
61 | ||
62 | <para>An nspawn container settings file (suffix | |
63 | <filename>.nspawn</filename>) encodes additional runtime | |
64 | information about a local container, and is searched, read and | |
65 | used by | |
66 | <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
67 | when starting a container. Files of this type are named after the | |
68 | containers they define settings for. They are optional, and only | |
69 | required for containers whose execution environment shall differ | |
70 | from the defaults. Files of this type mostly contain settings that | |
71 | may also be set on the <command>systemd-nspawn</command> command | |
72 | line, and make it easier to persistently attach specific settings | |
73 | to specific containers. The syntax of these files is inspired by | |
74 | <filename>.desktop</filename> files following the <ulink | |
75 | url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG | |
a8eaaee7 | 76 | Desktop Entry Specification</ulink>, which in turn are inspired by |
f757855e LP |
77 | Microsoft Windows <filename>.ini</filename> files.</para> |
78 | ||
79 | <para>Boolean arguments used in these settings files can be | |
b938cb90 | 80 | written in various formats. For positive settings, the strings |
f757855e LP |
81 | <option>1</option>, <option>yes</option>, <option>true</option> |
82 | and <option>on</option> are equivalent. For negative settings, the | |
83 | strings <option>0</option>, <option>no</option>, | |
84 | <option>false</option> and <option>off</option> are | |
85 | equivalent.</para> | |
86 | ||
87 | <para>Empty lines and lines starting with # or ; are | |
88 | ignored. This may be used for commenting. Lines ending | |
89 | in a backslash are concatenated with the following | |
90 | line while reading and the backslash is replaced by a | |
91 | space character. This may be used to wrap long lines.</para> | |
92 | ||
93 | </refsect1> | |
94 | ||
95 | <refsect1> | |
96 | <title><filename>.nspawn</filename> File Discovery</title> | |
97 | ||
98 | <para>Files are searched by appending the | |
99 | <filename>.nspawn</filename> suffix to the machine name of the | |
100 | container, as specified with the <option>--machine=</option> | |
101 | switch of <command>systemd-nspawn</command>, or derived from the | |
102 | directory or image file name. This file is first searched in | |
103 | <filename>/etc/systemd/nspawn/</filename> and | |
104 | <filename>/run/systemd/nspawn/</filename>. If found in these | |
b938cb90 | 105 | directories, its settings are read and all of them take full effect |
4f76ef04 | 106 | (but are possibly overridden by corresponding command line |
b938cb90 | 107 | arguments). If not found, the file will then be searched next to |
f757855e | 108 | the image file or in the immediate parent of the root directory of |
b938cb90 | 109 | the container. If the file is found there, only a subset of the |
f757855e LP |
110 | settings will take effect however. All settings that possibly |
111 | elevate privileges or grant additional access to resources of the | |
112 | host (such as files or directories) are ignored. To which options | |
113 | this applies is documented below.</para> | |
114 | ||
a8eaaee7 | 115 | <para>Persistent settings files created and maintained by the |
f757855e LP |
116 | administrator (and thus trusted) should be placed in |
117 | <filename>/etc/systemd/nspawn/</filename>, while automatically | |
118 | downloaded (and thus potentially untrusted) settings files are | |
119 | placed in <filename>/var/lib/machines/</filename> instead (next to | |
120 | the container images), where their security impact is limited. In | |
121 | order to add privileged settings to <filename>.nspawn</filename> | |
b938cb90 | 122 | files acquired from the image vendor, it is recommended to copy the |
f757855e LP |
123 | settings files into <filename>/etc/systemd/nspawn/</filename> and |
124 | edit them there, so that the privileged options become | |
a8eaaee7 | 125 | available. The precise algorithm for how the files are searched and |
f757855e LP |
126 | interpreted may be configured with |
127 | <command>systemd-nspawn</command>'s <option>--settings=</option> | |
128 | switch, see | |
129 | <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
130 | for details.</para> | |
131 | </refsect1> | |
132 | ||
133 | <refsect1> | |
134 | <title>[Exec] Section Options</title> | |
135 | ||
136 | <para>Settings files may include an <literal>[Exec]</literal> | |
137 | section, which carries various execution parameters:</para> | |
138 | ||
139 | <variablelist> | |
140 | ||
141 | <varlistentry> | |
142 | <term><varname>Boot=</varname></term> | |
143 | ||
a8eaaee7 | 144 | <listitem><para>Takes a boolean argument, which defaults to off. If |
b938cb90 | 145 | enabled, <command>systemd-nspawn</command> will automatically |
f757855e | 146 | search for an <filename>init</filename> executable and invoke |
b938cb90 | 147 | it. In this case, the specified parameters using |
f757855e LP |
148 | <varname>Parameters=</varname> are passed as additional |
149 | arguments to the <filename>init</filename> process. This | |
150 | setting corresponds to the <option>--boot</option> switch on | |
151 | the <command>systemd-nspawn</command> command | |
152 | line. </para></listitem> | |
153 | </varlistentry> | |
154 | ||
155 | <varlistentry> | |
156 | <term><varname>Parameters=</varname></term> | |
157 | ||
b938cb90 | 158 | <listitem><para>Takes a space-separated list of |
f757855e LP |
159 | arguments. This is either a command line, beginning with the |
160 | binary name to execute, or – if <varname>Boot=</varname> is | |
161 | enabled – the list of arguments to pass to the init | |
162 | process. This setting corresponds to the command line | |
163 | parameters passed on the <command>systemd-nspawn</command> | |
164 | command line.</para></listitem> | |
165 | </varlistentry> | |
166 | ||
167 | <varlistentry> | |
168 | <term><varname>Environment=</varname></term> | |
169 | ||
170 | <listitem><para>Takes an environment variable assignment | |
171 | consisting of key and value, separated by | |
172 | <literal>=</literal>. Sets an environment variable for the | |
173 | main process invoked in the container. This setting may be | |
174 | used multiple times to set multiple environment variables. It | |
175 | corresponds to the <option>--setenv=</option> command line | |
176 | switch.</para></listitem> | |
177 | </varlistentry> | |
178 | ||
179 | <varlistentry> | |
180 | <term><varname>User=</varname></term> | |
181 | ||
182 | <listitem><para>Takes a UNIX user name. Specifies the user | |
183 | name to invoke the main process of the container as. This user | |
184 | must be known in the container's user database. This | |
185 | corresponds to the <option>--user=</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 | ||
b938cb90 | 193 | <listitem><para>Takes a space-separated list of Linux process |
f757855e LP |
194 | capabilities (see |
195 | <citerefentry><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 | |
4f76ef04 | 198 | default set of capabilities. The |
f757855e LP |
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 | |
b938cb90 | 208 | other hand, <varname>DropCapability=</varname> takes effect in |
f757855e LP |
209 | all cases.</para></listitem> |
210 | </varlistentry> | |
211 | ||
212 | <varlistentry> | |
213 | <term><varname>Personality=</varname></term> | |
214 | ||
215 | <listitem><para>Configures the kernel personality for the | |
216 | container. This is equivalent to the | |
217 | <option>--personality=</option> switch.</para></listitem> | |
218 | </varlistentry> | |
219 | ||
220 | <varlistentry> | |
221 | <term><varname>MachineID=</varname></term> | |
222 | ||
b938cb90 | 223 | <listitem><para>Configures the 128-bit machine ID (UUID) to pass to |
f757855e LP |
224 | the container. This is equivalent to the |
225 | <option>--uuid=</option> command line switch. This option is | |
226 | privileged (see above). </para></listitem> | |
227 | </varlistentry> | |
228 | </variablelist> | |
229 | </refsect1> | |
230 | ||
231 | <refsect1> | |
232 | <title>[Files] Section Options</title> | |
233 | ||
234 | <para>Settings files may include a <literal>[Files]</literal> | |
235 | section, which carries various parameters configuring the file | |
236 | system of the container:</para> | |
237 | ||
238 | <variablelist> | |
239 | ||
240 | <varlistentry> | |
241 | <term><varname>ReadOnly=</varname></term> | |
242 | ||
a8eaaee7 | 243 | <listitem><para>Takes a boolean argument, which defaults to off. If |
b938cb90 | 244 | specified, the container will be run with a read-only file |
f757855e LP |
245 | system. This setting corresponds to the |
246 | <option>--read-only</option> command line | |
247 | switch.</para></listitem> | |
248 | </varlistentry> | |
249 | ||
250 | <varlistentry> | |
251 | <term><varname>Volatile=</varname></term> | |
252 | ||
253 | <listitem><para>Takes a boolean argument, or the special value | |
254 | <literal>state</literal>. This configures whether to run the | |
255 | container with volatile state and/or configuration. This | |
256 | option is equivalent to <option>--volatile=</option>, see | |
257 | <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
258 | for details about the specific options | |
259 | supported.</para></listitem> | |
260 | </varlistentry> | |
261 | ||
262 | <varlistentry> | |
263 | <term><varname>Bind=</varname></term> | |
264 | <term><varname>BindReadOnly=</varname></term> | |
265 | ||
266 | <listitem><para>Adds a bind mount from the host into the | |
267 | container. Takes a single path, a pair of two paths separated | |
268 | by a colon, or a triplet of two paths plus an option string | |
269 | separated by colons. This option may be used multiple times to | |
270 | configure multiple bind mounts. This option is equivalent to | |
271 | the command line switches <option>--bind=</option> and | |
272 | <option>--bind-ro=</option>, see | |
273 | <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
274 | for details about the specific options supported. This setting | |
275 | is privileged (see above).</para></listitem> | |
276 | </varlistentry> | |
277 | ||
278 | <varlistentry> | |
279 | <term><varname>TemporaryFileSystem=</varname></term> | |
280 | ||
281 | <listitem><para>Adds a <literal>tmpfs</literal> mount to the | |
282 | container. Takes a path or a pair of path and option string, | |
4f76ef04 | 283 | separated by a colon. This option may be used multiple times to |
f757855e LP |
284 | configure multiple <literal>tmpfs</literal> mounts. This |
285 | option is equivalent to the command line switch | |
286 | <option>--tmpfs=</option>, see | |
287 | <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
288 | for details about the specific options supported. This setting | |
289 | is privileged (see above).</para></listitem> | |
290 | </varlistentry> | |
291 | </variablelist> | |
292 | </refsect1> | |
293 | ||
294 | <refsect1> | |
295 | <title>[Network] Section Options</title> | |
296 | ||
297 | <para>Settings files may include a <literal>[Network]</literal> | |
298 | section, which carries various parameters configuring the network | |
299 | connectivity of the container:</para> | |
300 | ||
301 | <variablelist> | |
302 | ||
303 | <varlistentry> | |
304 | <term><varname>Private=</varname></term> | |
305 | ||
a8eaaee7 | 306 | <listitem><para>Takes a boolean argument, which defaults to off. If |
b938cb90 | 307 | enabled, the container will run in its own network namespace |
f757855e LP |
308 | and not share network interfaces and configuration with the |
309 | host. This setting corresponds to the | |
310 | <option>--private-network</option> command line | |
311 | switch.</para></listitem> | |
312 | </varlistentry> | |
313 | ||
314 | <varlistentry> | |
315 | <term><varname>VirtualEthernet=</varname></term> | |
316 | ||
317 | <listitem><para>Takes a boolean argument. Configures whether | |
a8eaaee7 | 318 | to create a virtual Ethernet connection |
f757855e LP |
319 | (<literal>veth</literal>) between host and the container. This |
320 | setting implies <varname>Private=yes</varname>. This setting | |
321 | corresponds to the <option>--network-veth</option> command | |
322 | line switch. This option is privileged (see | |
323 | above).</para></listitem> | |
324 | </varlistentry> | |
325 | ||
326 | <varlistentry> | |
327 | <term><varname>Interface=</varname></term> | |
328 | ||
b938cb90 | 329 | <listitem><para>Takes a space-separated list of interfaces to |
f757855e LP |
330 | add to the container. This option corresponds to the |
331 | <option>--network-interface=</option> command line switch and | |
332 | implies <varname>Private=yes</varname>. This option is | |
333 | privileged (see above).</para></listitem> | |
334 | </varlistentry> | |
335 | ||
336 | <varlistentry> | |
337 | <term><varname>MACVLAN=</varname></term> | |
338 | <term><varname>IPVLAN=</varname></term> | |
339 | ||
b938cb90 | 340 | <listitem><para>Takes a space-separated list of interfaces to |
f757855e LP |
341 | add MACLVAN or IPVLAN interfaces to, which are then added to |
342 | the container. These options correspond to the | |
343 | <option>--network-macvlan=</option> and | |
344 | <option>--network-ipvlan=</option> command line switches and | |
345 | imply <varname>Private=yes</varname>. These options are | |
346 | privileged (see above).</para></listitem> | |
347 | </varlistentry> | |
348 | ||
349 | <varlistentry> | |
350 | <term><varname>Bridge=</varname></term> | |
351 | ||
352 | <listitem><para>Takes an interface name. This setting implies | |
353 | <varname>VirtualEthernet=yes</varname> and | |
354 | <varname>Private=yes</varname> and has the effect that the | |
355 | host side of the created virtual Ethernet link is connected to | |
356 | the specified bridge interface. This option corresponds to the | |
357 | <option>--network-bridge=</option> command line switch. This | |
358 | option is privileged (see above).</para></listitem> | |
359 | </varlistentry> | |
360 | ||
361 | <varlistentry> | |
362 | <term><varname>Port=</varname></term> | |
363 | ||
364 | <listitem><para>Exposes a TCP or UDP port of the container on | |
365 | the host. This option corresponds to the | |
366 | <option>--port=</option> command line switch, see | |
367 | <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
368 | for the precise syntax of the argument this option takes. This | |
369 | option is privileged (see above).</para></listitem> | |
370 | </varlistentry> | |
371 | </variablelist> | |
372 | </refsect1> | |
373 | ||
374 | <refsect1> | |
375 | <title>See Also</title> | |
376 | <para> | |
377 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
378 | <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
379 | <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> | |
380 | </para> | |
381 | </refsect1> | |
382 | ||
383 | </refentry> |