]>
Commit | Line | Data |
---|---|---|
55fc19a1 SG |
1 | <!-- |
2 | ||
3 | lxc: linux Container library | |
4 | ||
5 | (C) Copyright IBM Corp. 2007, 2008 | |
6 | ||
7 | Authors: | |
8 | Daniel Lezcano <daniel.lezcano at free.fr> | |
9 | ||
10 | This library is free software; you can redistribute it and/or | |
11 | modify it under the terms of the GNU Lesser General Public | |
12 | License as published by the Free Software Foundation; either | |
13 | version 2.1 of the License, or (at your option) any later version. | |
14 | ||
15 | This library is distributed in the hope that it will be useful, | |
16 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
17 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
18 | Lesser General Public License for more details. | |
19 | ||
20 | You should have received a copy of the GNU Lesser General Public | |
21 | License along with this library; if not, write to the Free Software | |
22 | Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | |
23 | ||
24 | --> | |
25 | ||
26 | <!DOCTYPE refentry PUBLIC @docdtd@ [ | |
27 | ||
28 | <!ENTITY seealso SYSTEM "@builddir@/see_also.sgml"> | |
29 | ]> | |
30 | ||
31 | <refentry> | |
32 | ||
33 | <docinfo><date>@LXC_GENERATE_DATE@</date></docinfo> | |
34 | ||
35 | <refmeta> | |
36 | <refentrytitle>lxc.container.conf</refentrytitle> | |
37 | <manvolnum>5</manvolnum> | |
38 | </refmeta> | |
39 | ||
40 | <refnamediv> | |
41 | <refname>lxc.container.conf</refname> | |
42 | ||
43 | <refpurpose> | |
44 | LXC container configuration file | |
45 | </refpurpose> | |
46 | </refnamediv> | |
47 | ||
48 | <refsect1> | |
49 | <title>Description</title> | |
50 | ||
51 | <para> | |
b9986e43 CB |
52 | LXC is the well-known and heavily tested low-level Linux container |
53 | runtime. It is in active development since 2008 and has proven itself in | |
54 | critical production environments world-wide. Some of its core contributors | |
55 | are the same people that helped to implement various well-known | |
56 | containerization features inside the Linux kernel. | |
55fc19a1 SG |
57 | </para> |
58 | ||
59 | <para> | |
b9986e43 CB |
60 | LXC's main focus is system containers. That is, containers which offer an |
61 | environment as close as possible as the one you'd get from a VM but | |
62 | without the overhead that comes with running a separate kernel and | |
63 | simulating all the hardware. | |
55fc19a1 SG |
64 | </para> |
65 | ||
66 | <para> | |
b9986e43 CB |
67 | This is achieved through a combination of kernel security features such as |
68 | namespaces, mandatory access control and control groups. | |
69 | </para> | |
70 | ||
71 | <para> | |
eb4225a0 | 72 | LXC has support for unprivileged containers. Unprivileged containers are |
b9986e43 CB |
73 | containers that are run without any privilege. This requires support for |
74 | user namespaces in the kernel that the container is run on. LXC was the | |
75 | first runtime to support unprivileged containers after user namespaces | |
76 | were merged into the mainline kernel. | |
77 | </para> | |
78 | ||
79 | <para> | |
80 | In essence, user namespaces isolate given sets of UIDs and GIDs. This is | |
81 | achieved by establishing a mapping between a range of UIDs and GIDs on the | |
82 | host to a different (unprivileged) range of UIDs and GIDs in the | |
83 | container. The kernel will translate this mapping in such a way that | |
84 | inside the container all UIDs and GIDs appear as you would expect from the | |
85 | host whereas on the host these UIDs and GIDs are in fact unprivileged. For | |
86 | example, a process running as UID and GID 0 inside the container might | |
87 | appear as UID and GID 100000 on the host. The implementation and working | |
88 | details can be gathered from the corresponding user namespace man page. | |
bdcbb6b3 | 89 | UID and GID mappings can be defined with the <option>lxc.idmap</option> |
b9986e43 CB |
90 | key. |
91 | </para> | |
92 | ||
93 | <para> | |
94 | Linux containers are defined with a simple configuration file. Each | |
95 | option in the configuration file has the form <command>key = | |
96 | value</command> fitting in one line. The "#" character means the line is a | |
97 | comment. List options, like capabilities and cgroups options, can be used | |
98 | with no value to clear any previously defined values of that option. | |
99 | </para> | |
100 | ||
101 | <para> | |
eb4225a0 | 102 | LXC namespaces configuration keys use single dots. This means complex |
7fa3f2e9 | 103 | configuration keys such as <option>lxc.net.0</option> expose various |
104 | subkeys such as <option>lxc.net.0.type</option>, | |
2e44ae28 | 105 | <option>lxc.net.0.link</option>, <option>lxc.net.0.ipv6.address</option>, and |
b9986e43 | 106 | others for even more fine-grained configuration. |
55fc19a1 SG |
107 | </para> |
108 | ||
109 | <refsect2> | |
110 | <title>Configuration</title> | |
111 | <para> | |
b9986e43 CB |
112 | In order to ease administration of multiple related containers, it is |
113 | possible to have a container configuration file cause another file to be | |
114 | loaded. For instance, network configuration can be defined in one common | |
115 | file which is included by multiple containers. Then, if the containers | |
116 | are moved to another host, only one file may need to be updated. | |
55fc19a1 SG |
117 | </para> |
118 | ||
119 | <variablelist> | |
c464fd7e SG |
120 | <varlistentry> |
121 | <term> | |
122 | <option>lxc.include</option> | |
123 | </term> | |
124 | <listitem> | |
125 | <para> | |
126 | Specify the file to be included. The included file must be | |
127 | in the same valid lxc configuration file format. | |
128 | </para> | |
129 | </listitem> | |
130 | </varlistentry> | |
55fc19a1 SG |
131 | </variablelist> |
132 | </refsect2> | |
133 | ||
134 | <refsect2> | |
135 | <title>Architecture</title> | |
136 | <para> | |
b9986e43 CB |
137 | Allows one to set the architecture for the container. For example, set a |
138 | 32bits architecture for a container running 32bits binaries on a 64bits | |
139 | host. This fixes the container scripts which rely on the architecture to | |
140 | do some work like downloading the packages. | |
55fc19a1 SG |
141 | </para> |
142 | ||
143 | <variablelist> | |
c464fd7e SG |
144 | <varlistentry> |
145 | <term> | |
146 | <option>lxc.arch</option> | |
147 | </term> | |
148 | <listitem> | |
149 | <para> | |
150 | Specify the architecture for the container. | |
151 | </para> | |
152 | <para> | |
b9986e43 | 153 | Some valid options are |
c464fd7e SG |
154 | <option>x86</option>, |
155 | <option>i686</option>, | |
156 | <option>x86_64</option>, | |
157 | <option>amd64</option> | |
158 | </para> | |
159 | </listitem> | |
160 | </varlistentry> | |
55fc19a1 SG |
161 | </variablelist> |
162 | ||
163 | </refsect2> | |
164 | ||
165 | <refsect2> | |
166 | <title>Hostname</title> | |
167 | <para> | |
b9986e43 CB |
168 | The utsname section defines the hostname to be set for the container. |
169 | That means the container can set its own hostname without changing the | |
170 | one from the system. That makes the hostname private for the container. | |
55fc19a1 SG |
171 | </para> |
172 | <variablelist> | |
c464fd7e SG |
173 | <varlistentry> |
174 | <term> | |
b67771bc | 175 | <option>lxc.uts.name</option> |
c464fd7e SG |
176 | </term> |
177 | <listitem> | |
178 | <para> | |
179 | specify the hostname for the container | |
180 | </para> | |
181 | </listitem> | |
182 | </varlistentry> | |
55fc19a1 SG |
183 | </variablelist> |
184 | </refsect2> | |
185 | ||
186 | <refsect2> | |
187 | <title>Halt signal</title> | |
188 | <para> | |
b9986e43 CB |
189 | Allows one to specify signal name or number sent to the container's |
190 | init process to cleanly shutdown the container. Different init systems | |
191 | could use different signals to perform clean shutdown sequence. This | |
192 | option allows the signal to be specified in kill(1) fashion, e.g. | |
193 | SIGPWR, SIGRTMIN+14, SIGRTMAX-10 or plain number. The default signal is | |
194 | SIGPWR. | |
55fc19a1 SG |
195 | </para> |
196 | <variablelist> | |
936762f3 BP |
197 | <varlistentry> |
198 | <term> | |
55c84efc | 199 | <option>lxc.signal.halt</option> |
936762f3 BP |
200 | </term> |
201 | <listitem> | |
202 | <para> | |
203 | specify the signal used to halt the container | |
204 | </para> | |
205 | </listitem> | |
206 | </varlistentry> | |
207 | </variablelist> | |
208 | </refsect2> | |
209 | ||
210 | <refsect2> | |
211 | <title>Reboot signal</title> | |
212 | <para> | |
b9986e43 CB |
213 | Allows one to specify signal name or number to reboot the container. |
214 | This option allows signal to be specified in kill(1) fashion, e.g. | |
215 | SIGTERM, SIGRTMIN+14, SIGRTMAX-10 or plain number. The default signal | |
216 | is SIGINT. | |
936762f3 BP |
217 | </para> |
218 | <variablelist> | |
219 | <varlistentry> | |
220 | <term> | |
55c84efc | 221 | <option>lxc.signal.reboot</option> |
936762f3 BP |
222 | </term> |
223 | <listitem> | |
224 | <para> | |
225 | specify the signal used to reboot the container | |
226 | </para> | |
227 | </listitem> | |
228 | </varlistentry> | |
55fc19a1 SG |
229 | </variablelist> |
230 | </refsect2> | |
231 | ||
232 | <refsect2> | |
233 | <title>Stop signal</title> | |
234 | <para> | |
b9986e43 CB |
235 | Allows one to specify signal name or number to forcibly shutdown the |
236 | container. This option allows signal to be specified in kill(1) fashion, | |
237 | e.g. SIGKILL, SIGRTMIN+14, SIGRTMAX-10 or plain number. The default | |
238 | signal is SIGKILL. | |
936762f3 BP |
239 | </para> |
240 | <variablelist> | |
241 | <varlistentry> | |
242 | <term> | |
55c84efc | 243 | <option>lxc.signal.stop</option> |
936762f3 BP |
244 | </term> |
245 | <listitem> | |
246 | <para> | |
247 | specify the signal used to stop the container | |
248 | </para> | |
249 | </listitem> | |
250 | </varlistentry> | |
55fc19a1 SG |
251 | </variablelist> |
252 | </refsect2> | |
253 | ||
67c660d0 SG |
254 | <refsect2> |
255 | <title>Init command</title> | |
256 | <para> | |
257 | Sets the command to use as the init system for the containers. | |
67c660d0 | 258 | </para> |
5cda27c1 SH |
259 | <variablelist> |
260 | <varlistentry> | |
261 | <term> | |
262 | <option>lxc.execute.cmd</option> | |
263 | </term> | |
264 | <listitem> | |
265 | <para> | |
266 | Absolute path from container rootfs to the binary to run by default. This | |
fcd95ae9 | 267 | mostly makes sense for <command>lxc-execute</command>. |
5cda27c1 SH |
268 | </para> |
269 | </listitem> | |
270 | </varlistentry> | |
271 | </variablelist> | |
67c660d0 | 272 | <variablelist> |
936762f3 BP |
273 | <varlistentry> |
274 | <term> | |
9dcf7b4d | 275 | <option>lxc.init.cmd</option> |
936762f3 BP |
276 | </term> |
277 | <listitem> | |
278 | <para> | |
fcd95ae9 KY |
279 | Absolute path from container rootfs to the binary to use as init. This |
280 | mostly makes sense for <command>lxc-start</command>. Default is <command>/sbin/init</command>. | |
936762f3 BP |
281 | </para> |
282 | </listitem> | |
283 | </varlistentry> | |
67c660d0 SG |
284 | </variablelist> |
285 | </refsect2> | |
286 | ||
3c491553 L |
287 | <refsect2> |
288 | <title>Init working directory</title> | |
289 | <para> | |
290 | Sets the absolute path inside the container as the working directory for the containers. | |
291 | LXC will switch to this directory before executing init. | |
292 | </para> | |
293 | <variablelist> | |
294 | <varlistentry> | |
295 | <term> | |
296 | <option>lxc.init.cwd</option> | |
297 | </term> | |
298 | <listitem> | |
299 | <para> | |
300 | Absolute path inside the container to use as the working directory. | |
301 | </para> | |
302 | </listitem> | |
303 | </varlistentry> | |
304 | </variablelist> | |
305 | </refsect2> | |
306 | ||
dbca9237 PT |
307 | <refsect2> |
308 | <title>Init ID</title> | |
309 | <para> | |
b9986e43 | 310 | Sets the UID/GID to use for the init system, and subsequent commands. |
14a7b0f9 | 311 | Note that using a non-root UID when booting a system container will |
b9986e43 | 312 | likely not work due to missing privileges. Setting the UID/GID is mostly |
14a7b0f9 | 313 | useful when running application containers. |
dbca9237 PT |
314 | |
315 | Defaults to: UID(0), GID(0) | |
316 | </para> | |
317 | <variablelist> | |
318 | <varlistentry> | |
319 | <term> | |
9dcf7b4d | 320 | <option>lxc.init.uid</option> |
dbca9237 PT |
321 | </term> |
322 | <listitem> | |
323 | <para> | |
b9986e43 | 324 | UID to use for init. |
dbca9237 PT |
325 | </para> |
326 | </listitem> | |
327 | </varlistentry> | |
328 | <varlistentry> | |
329 | <term> | |
9dcf7b4d | 330 | <option>lxc.init.gid</option> |
dbca9237 PT |
331 | </term> |
332 | <listitem> | |
333 | <para> | |
b9986e43 | 334 | GID to use for init. |
dbca9237 PT |
335 | </para> |
336 | </listitem> | |
337 | </varlistentry> | |
338 | </variablelist> | |
339 | </refsect2> | |
340 | ||
61d7a733 YT |
341 | <refsect2> |
342 | <title>Proc</title> | |
343 | <para> | |
344 | Configure proc filesystem for the container. | |
345 | </para> | |
346 | <variablelist> | |
347 | <varlistentry> | |
348 | <term> | |
349 | <option>lxc.proc.[proc file name]</option> | |
350 | </term> | |
351 | <listitem> | |
352 | <para> | |
eb4225a0 | 353 | Specify the proc file name to be set. The file names available |
61d7a733 YT |
354 | are those listed under /proc/PID/. |
355 | Example: | |
356 | </para> | |
357 | <programlisting> | |
358 | lxc.proc.oom_score_adj = 10 | |
359 | </programlisting> | |
360 | </listitem> | |
361 | </varlistentry> | |
362 | </variablelist> | |
363 | </refsect2> | |
364 | ||
4e6eb26b CB |
365 | <refsect2> |
366 | <title>Ephemeral</title> | |
367 | <para> | |
368 | Allows one to specify whether a container will be destroyed on shutdown. | |
369 | </para> | |
370 | <variablelist> | |
371 | <varlistentry> | |
372 | <term> | |
373 | <option>lxc.ephemeral</option> | |
374 | </term> | |
375 | <listitem> | |
376 | <para> | |
377 | The only allowed values are 0 and 1. Set this to 1 to destroy a | |
d4a7da46 | 378 | container on shutdown. |
4e6eb26b CB |
379 | </para> |
380 | </listitem> | |
381 | </varlistentry> | |
382 | </variablelist> | |
383 | </refsect2> | |
384 | ||
55fc19a1 SG |
385 | <refsect2> |
386 | <title>Network</title> | |
387 | <para> | |
c464fd7e SG |
388 | The network section defines how the network is virtualized in |
389 | the container. The network virtualization acts at layer | |
390 | two. In order to use the network virtualization, parameters | |
391 | must be specified to define the network interfaces of the | |
392 | container. Several virtual interfaces can be assigned and used | |
393 | in a container even if the system has only one physical | |
394 | network interface. | |
55fc19a1 SG |
395 | </para> |
396 | <variablelist> | |
020104c3 MH |
397 | <varlistentry> |
398 | <term> | |
7fa3f2e9 | 399 | <option>lxc.net</option> |
020104c3 MH |
400 | </term> |
401 | <listitem> | |
402 | <para> | |
403 | may be used without a value to clear all previous network options. | |
404 | </para> | |
405 | </listitem> | |
406 | </varlistentry> | |
c464fd7e SG |
407 | <varlistentry> |
408 | <term> | |
7fa3f2e9 | 409 | <option>lxc.net.[i].type</option> |
c464fd7e SG |
410 | </term> |
411 | <listitem> | |
412 | <para> | |
413 | specify what kind of network virtualization to be used | |
b9986e43 | 414 | for the container. |
320061b3 | 415 | Must be specified before any other option(s) on the net device. |
b9986e43 CB |
416 | Multiple networks can be specified by using an additional index |
417 | <option>i</option> | |
7fa3f2e9 | 418 | after all <option>lxc.net.*</option> keys. For example, |
419 | <option>lxc.net.0.type = veth</option> and | |
420 | <option>lxc.net.1.type = veth</option> specify two different | |
b9986e43 CB |
421 | networks of the same type. All keys sharing the same index |
422 | <option>i</option> will be treated as belonging to the same | |
7fa3f2e9 | 423 | network. For example, <option>lxc.net.0.link = br0</option> |
424 | will belong to <option>lxc.net.0.type</option>. | |
b9986e43 | 425 | Currently, the different virtualization types can be: |
c464fd7e SG |
426 | </para> |
427 | ||
428 | <para> | |
429 | <option>none:</option> will cause the container to share | |
430 | the host's network namespace. This means the host | |
431 | network devices are usable in the container. It also | |
432 | means that if both the container and host have upstart as | |
433 | init, 'halt' in a container (for instance) will shut down the | |
e4b3e369 AK |
434 | host. Note that unprivileged containers do not work with this |
435 | setting due to an inability to mount sysfs. An unsafe workaround | |
436 | would be to bind mount the host's sysfs. | |
c464fd7e SG |
437 | </para> |
438 | ||
439 | <para> | |
440 | <option>empty:</option> will create only the loopback | |
441 | interface. | |
442 | </para> | |
443 | ||
444 | <para> | |
38005c54 MA |
445 | <option>veth:</option> a virtual ethernet pair |
446 | device is created with one side assigned to the container | |
3e5c2e69 | 447 | and the other side on the host. |
448 | <option>lxc.net.[i].veth.mode</option> specifies the | |
449 | mode the veth parent will use on the host. | |
450 | The accepted modes are <option>bridge</option> and <option>router</option>. | |
451 | The mode defaults to bridge if not specified. | |
452 | In <option>bridge</option> mode the host side is attached to a bridge specified by | |
7fa3f2e9 | 453 | the <option>lxc.net.[i].link</option> option. |
3e5c2e69 | 454 | If the bridge link is not specified, then the veth pair device |
38005c54 MA |
455 | will be created but not attached to any bridge. |
456 | Otherwise, the bridge has to be created on the system | |
457 | before starting the container. | |
458 | <command>lxc</command> won't handle any | |
459 | configuration outside of the container. | |
3e5c2e69 | 460 | In <option>router</option> mode static routes are created on the host for the |
461 | container's IP addresses pointing to the host side veth interface. | |
462 | Additionally Proxy ARP and Proxy NDP entries are added on the host side veth interface | |
463 | for the gateway IPs defined in the container to allow the container to reach the host. | |
38005c54 | 464 | By default, <command>lxc</command> chooses a name for the |
c464fd7e | 465 | network device belonging to the outside of the |
38005c54 MA |
466 | container, but if you wish to handle |
467 | this name yourselves, you can tell <command>lxc</command> | |
c464fd7e | 468 | to set a specific name with |
7fa3f2e9 | 469 | the <option>lxc.net.[i].veth.pair</option> option (except for |
c464fd7e SG |
470 | unprivileged containers where this option is ignored for security |
471 | reasons). | |
d4a7da46 | 472 | |
473 | Static routes can be added on the host pointing to the container using the | |
474 | <option>lxc.net.[i].veth.ipv4.route</option> and | |
475 | <option>lxc.net.[i].veth.ipv6.route</option> options. | |
476 | Several lines specify several routes. | |
477 | The route is in format x.y.z.t/m, eg. 192.168.1.0/24. | |
a789ca4c TP |
478 | |
479 | In <option>bridge</option> mode untagged VLAN membership can be set with the | |
480 | <option>lxc.net.[i].veth.vlan.id</option> option. It accepts a special value of 'none' indicating | |
481 | that the container port should be removed from the bridge's default untagged VLAN. | |
482 | The <option>lxc.net.[i].veth.vlan.tagged.id</option> option can be specified multiple times to set | |
483 | the container's bridge port membership to one or more tagged VLANs. | |
c464fd7e SG |
484 | </para> |
485 | ||
486 | <para> | |
487 | <option>vlan:</option> a vlan interface is linked with | |
488 | the interface specified by | |
7fa3f2e9 | 489 | the <option>lxc.net.[i].link</option> and assigned to |
c464fd7e | 490 | the container. The vlan identifier is specified with the |
7fa3f2e9 | 491 | option <option>lxc.net.[i].vlan.id</option>. |
c464fd7e SG |
492 | </para> |
493 | ||
494 | <para> | |
495 | <option>macvlan:</option> a macvlan interface is linked | |
496 | with the interface specified by | |
7fa3f2e9 | 497 | the <option>lxc.net.[i].link</option> and assigned to |
c464fd7e | 498 | the container. |
7fa3f2e9 | 499 | <option>lxc.net.[i].macvlan.mode</option> specifies the |
c464fd7e SG |
500 | mode the macvlan will use to communicate between |
501 | different macvlan on the same upper device. The accepted | |
c15ea607 EL |
502 | modes are <option>private</option>, <option>vepa</option>, |
503 | <option>bridge</option> and <option>passthru</option>. | |
c9f52382 | 504 | In <option>private</option> mode, the device never |
c15ea607 EL |
505 | communicates with any other device on the same upper_dev (default). |
506 | In <option>vepa</option> mode, the new Virtual Ethernet Port | |
c464fd7e SG |
507 | Aggregator (VEPA) mode, it assumes that the adjacent |
508 | bridge returns all frames where both source and | |
509 | destination are local to the macvlan port, i.e. the | |
510 | bridge is set up as a reflective relay. Broadcast | |
511 | frames coming in from the upper_dev get flooded to all | |
512 | macvlan interfaces in VEPA mode, local frames are not | |
c15ea607 | 513 | delivered locally. In <option>bridge</option> mode, it |
c464fd7e SG |
514 | provides the behavior of a simple bridge between |
515 | different macvlan interfaces on the same port. Frames | |
516 | from one interface to another one get delivered directly | |
517 | and are not sent out externally. Broadcast frames get | |
518 | flooded to all other bridge ports and to the external | |
519 | interface, but when they come back from a reflective | |
520 | relay, we don't deliver them again. Since we know all | |
521 | the MAC addresses, the macvlan bridge mode does not | |
c15ea607 EL |
522 | require learning or STP like the bridge module does. In |
523 | <option>passthru</option> mode, all frames received by | |
524 | the physical interface are forwarded to the macvlan | |
525 | interface. Only one macvlan interface in <option>passthru</option> | |
526 | mode is possible for one physical interface. | |
c464fd7e SG |
527 | </para> |
528 | ||
c9f52382 | 529 | <para> |
530 | <option>ipvlan:</option> an ipvlan interface is linked | |
531 | with the interface specified by | |
532 | the <option>lxc.net.[i].link</option> and assigned to | |
533 | the container. | |
534 | <option>lxc.net.[i].ipvlan.mode</option> specifies the | |
535 | mode the ipvlan will use to communicate between | |
536 | different ipvlan on the same upper device. The accepted | |
537 | modes are <option>l3</option>, <option>l3s</option> and | |
538 | <option>l2</option>. It defaults to <option>l3</option> mode. | |
539 | In <option>l3</option> mode TX processing up to L3 happens on the stack instance | |
f1d358b0 CB |
540 | attached to the dependent device and packets are switched to the stack instance of the |
541 | parent device for the L2 processing and routing from that instance will be | |
542 | used before packets are queued on the outbound device. In this mode the dependent devices | |
c9f52382 | 543 | will not receive nor can send multicast / broadcast traffic. |
544 | In <option>l3s</option> mode TX processing is very similar to the L3 mode except that | |
545 | iptables (conn-tracking) works in this mode and hence it is L3-symmetric (L3s). | |
546 | This will have slightly less performance but that shouldn't matter since you are | |
547 | choosing this mode over plain-L3 mode to make conn-tracking work. | |
548 | In <option>l2</option> mode TX processing happens on the stack instance attached to | |
f1d358b0 CB |
549 | the dependent device and packets are switched and queued to the parent device to send devices |
550 | out. In this mode the dependent devices will RX/TX multicast and broadcast (if applicable) as well. | |
c9f52382 | 551 | <option>lxc.net.[i].ipvlan.isolation</option> specifies the isolation mode. |
552 | The accepted isolation values are <option>bridge</option>, | |
553 | <option>private</option> and <option>vepa</option>. | |
554 | It defaults to <option>bridge</option>. | |
f1d358b0 CB |
555 | In <option>bridge</option> isolation mode dependent devices can cross-talk among themselves |
556 | apart from talking through the parent device. | |
c9f52382 | 557 | In <option>private</option> isolation mode the port is set in private mode. |
f1d358b0 | 558 | i.e. port won't allow cross communication between dependent devices. |
c9f52382 | 559 | In <option>vepa</option> isolation mode the port is set in VEPA mode. |
560 | i.e. port will offload switching functionality to the external entity as | |
561 | described in 802.1Qbg. | |
562 | </para> | |
563 | ||
c464fd7e SG |
564 | <para> |
565 | <option>phys:</option> an already existing interface | |
7fa3f2e9 | 566 | specified by the <option>lxc.net.[i].link</option> is |
c464fd7e SG |
567 | assigned to the container. |
568 | </para> | |
569 | </listitem> | |
570 | </varlistentry> | |
571 | ||
572 | <varlistentry> | |
573 | <term> | |
7fa3f2e9 | 574 | <option>lxc.net.[i].flags</option> |
c464fd7e SG |
575 | </term> |
576 | <listitem> | |
577 | <para> | |
b9986e43 | 578 | Specify an action to do for the network. |
c464fd7e SG |
579 | </para> |
580 | ||
581 | <para><option>up:</option> activates the interface. | |
582 | </para> | |
583 | </listitem> | |
584 | </varlistentry> | |
585 | ||
586 | <varlistentry> | |
587 | <term> | |
7fa3f2e9 | 588 | <option>lxc.net.[i].link</option> |
c464fd7e SG |
589 | </term> |
590 | <listitem> | |
591 | <para> | |
b9986e43 CB |
592 | Specify the interface to be used for real network traffic. |
593 | </para> | |
c464fd7e SG |
594 | </listitem> |
595 | </varlistentry> | |
596 | ||
6509154d | 597 | <varlistentry> |
598 | <term> | |
599 | <option>lxc.net.[i].l2proxy</option> | |
600 | </term> | |
601 | <listitem> | |
602 | <para> | |
603 | Controls whether layer 2 IP neighbour proxy entries will be added to the | |
604 | lxc.net.[i].link interface for the IP addresses of the container. | |
605 | Can be set to 0 or 1. Defaults to 0. | |
606 | When used with IPv4 addresses, the following sysctl values need to be set: | |
607 | net.ipv4.conf.[link].forwarding=1 | |
608 | When used with IPv6 addresses, the following sysctl values need to be set: | |
609 | net.ipv6.conf.[link].proxy_ndp=1 | |
610 | net.ipv6.conf.[link].forwarding=1 | |
611 | </para> | |
612 | </listitem> | |
613 | </varlistentry> | |
614 | ||
c464fd7e SG |
615 | <varlistentry> |
616 | <term> | |
7fa3f2e9 | 617 | <option>lxc.net.[i].mtu</option> |
c464fd7e SG |
618 | </term> |
619 | <listitem> | |
620 | <para> | |
b9986e43 | 621 | Specify the maximum transfer unit for this interface. |
c464fd7e SG |
622 | </para> |
623 | </listitem> | |
624 | </varlistentry> | |
625 | ||
626 | <varlistentry> | |
627 | <term> | |
7fa3f2e9 | 628 | <option>lxc.net.[i].name</option> |
c464fd7e SG |
629 | </term> |
630 | <listitem> | |
631 | <para> | |
b9986e43 CB |
632 | The interface name is dynamically allocated, but if another name |
633 | is needed because the configuration files being used by the | |
634 | container use a generic name, eg. eth0, this option will rename | |
635 | the interface in the container. | |
c464fd7e SG |
636 | </para> |
637 | </listitem> | |
638 | </varlistentry> | |
639 | ||
640 | <varlistentry> | |
641 | <term> | |
7fa3f2e9 | 642 | <option>lxc.net.[i].hwaddr</option> |
c464fd7e SG |
643 | </term> |
644 | <listitem> | |
645 | <para> | |
b9986e43 CB |
646 | The interface mac address is dynamically allocated by default to |
647 | the virtual interface, but in some cases, this is needed to | |
648 | resolve a mac address conflict or to always have the same | |
649 | link-local ipv6 address. Any "x" in address will be replaced by | |
650 | random value, this allows setting hwaddr templates. | |
c464fd7e SG |
651 | </para> |
652 | </listitem> | |
653 | </varlistentry> | |
654 | ||
655 | <varlistentry> | |
656 | <term> | |
9ff60df2 | 657 | <option>lxc.net.[i].ipv4.address</option> |
c464fd7e SG |
658 | </term> |
659 | <listitem> | |
660 | <para> | |
b9986e43 CB |
661 | Specify the ipv4 address to assign to the virtualized interface. |
662 | Several lines specify several ipv4 addresses. The address is in | |
663 | format x.y.z.t/m, eg. 192.168.1.123/24. | |
c464fd7e SG |
664 | </para> |
665 | </listitem> | |
666 | </varlistentry> | |
667 | ||
668 | <varlistentry> | |
669 | <term> | |
7fa3f2e9 | 670 | <option>lxc.net.[i].ipv4.gateway</option> |
c464fd7e SG |
671 | </term> |
672 | <listitem> | |
673 | <para> | |
b9986e43 CB |
674 | Specify the ipv4 address to use as the gateway inside the |
675 | container. The address is in format x.y.z.t, eg. 192.168.1.123. | |
c464fd7e SG |
676 | |
677 | Can also have the special value <option>auto</option>, | |
678 | which means to take the primary address from the bridge | |
679 | interface (as specified by the | |
7fa3f2e9 | 680 | <option>lxc.net.[i].link</option> option) and use that as |
c464fd7e | 681 | the gateway. <option>auto</option> is only available when |
6509154d | 682 | using the <option>veth</option>, |
c9f52382 | 683 | <option>macvlan</option> and <option>ipvlan</option> network types. |
a2f9a670 | 684 | Can also have the special value of <option>dev</option>, |
685 | which means to set the default gateway as a device route. | |
686 | This is primarily for use with layer 3 network modes, such as IPVLAN. | |
c464fd7e SG |
687 | </para> |
688 | </listitem> | |
689 | </varlistentry> | |
690 | ||
c464fd7e SG |
691 | <varlistentry> |
692 | <term> | |
2e44ae28 | 693 | <option>lxc.net.[i].ipv6.address</option> |
c464fd7e SG |
694 | </term> |
695 | <listitem> | |
696 | <para> | |
b9986e43 CB |
697 | Specify the ipv6 address to assign to the virtualized |
698 | interface. Several lines specify several ipv6 addresses. The | |
699 | address is in format x::y/m, eg. | |
700 | 2003:db8:1:0:214:1234:fe0b:3596/64 | |
c464fd7e SG |
701 | </para> |
702 | </listitem> | |
703 | </varlistentry> | |
704 | ||
705 | <varlistentry> | |
706 | <term> | |
7fa3f2e9 | 707 | <option>lxc.net.[i].ipv6.gateway</option> |
c464fd7e SG |
708 | </term> |
709 | <listitem> | |
710 | <para> | |
b9986e43 CB |
711 | Specify the ipv6 address to use as the gateway inside the |
712 | container. The address is in format x::y, eg. 2003:db8:1:0::1 | |
c464fd7e SG |
713 | |
714 | Can also have the special value <option>auto</option>, | |
715 | which means to take the primary address from the bridge | |
716 | interface (as specified by the | |
7fa3f2e9 | 717 | <option>lxc.net.[i].link</option> option) and use that as |
c464fd7e | 718 | the gateway. <option>auto</option> is only available when |
c9f52382 | 719 | using the <option>veth</option>, |
720 | <option>macvlan</option> and <option>ipvlan</option> network types. | |
a2f9a670 | 721 | Can also have the special value of <option>dev</option>, |
722 | which means to set the default gateway as a device route. | |
723 | This is primarily for use with layer 3 network modes, such as IPVLAN. | |
c464fd7e SG |
724 | </para> |
725 | </listitem> | |
726 | </varlistentry> | |
727 | ||
728 | <varlistentry> | |
729 | <term> | |
7fa3f2e9 | 730 | <option>lxc.net.[i].script.up</option> |
c464fd7e SG |
731 | </term> |
732 | <listitem> | |
733 | <para> | |
b9986e43 | 734 | Add a configuration option to specify a script to be |
c464fd7e | 735 | executed after creating and configuring the network used |
14a7b0f9 CB |
736 | from the host side. |
737 | </para> | |
738 | ||
739 | <para> | |
740 | In addition to the information available to all hooks. The | |
741 | following information is provided to the script: | |
742 | <itemizedlist> | |
743 | <listitem> | |
744 | <para> | |
745 | LXC_HOOK_TYPE: the hook type. This is either 'up' or 'down'. | |
746 | </para> | |
747 | </listitem> | |
748 | ||
749 | <listitem> | |
750 | <para> | |
751 | LXC_HOOK_SECTION: the section type 'net'. | |
752 | </para> | |
753 | </listitem> | |
754 | ||
755 | <listitem> | |
756 | <para> | |
757 | LXC_NET_TYPE: the network type. This is one of the valid | |
c9f52382 | 758 | network types listed here (e.g. 'vlan', 'macvlan', 'ipvlan', 'veth'). |
14a7b0f9 CB |
759 | </para> |
760 | </listitem> | |
761 | ||
762 | <listitem> | |
763 | <para> | |
764 | LXC_NET_PARENT: the parent device on the host. This is only | |
765 | set for network types 'mavclan', 'veth', 'phys'. | |
766 | </para> | |
767 | </listitem> | |
768 | ||
769 | <listitem> | |
770 | <para> | |
771 | LXC_NET_PEER: the name of the peer device on the host. This is | |
772 | only set for 'veth' network types. Note that this information | |
773 | is only available when <option>lxc.hook.version</option> is set | |
774 | to 1. | |
775 | </para> | |
776 | </listitem> | |
777 | </itemizedlist> | |
778 | ||
779 | Whether this information is provided in the form of environment | |
780 | variables or as arguments to the script depends on the value of | |
781 | <option>lxc.hook.version</option>. If set to 1 then information is | |
782 | provided in the form of environment variables. If set to 0 | |
783 | information is provided as arguments to the script. | |
c464fd7e | 784 | </para> |
14a7b0f9 | 785 | |
c464fd7e SG |
786 | <para> |
787 | Standard output from the script is logged at debug level. | |
788 | Standard error is not logged, but can be captured by the | |
789 | hook redirecting its standard error to standard output. | |
790 | </para> | |
791 | </listitem> | |
792 | </varlistentry> | |
793 | ||
794 | <varlistentry> | |
795 | <term> | |
7fa3f2e9 | 796 | <option>lxc.net.[i].script.down</option> |
c464fd7e SG |
797 | </term> |
798 | <listitem> | |
799 | <para> | |
b9986e43 | 800 | Add a configuration option to specify a script to be |
c464fd7e | 801 | executed before destroying the network used from the |
14a7b0f9 CB |
802 | host side. |
803 | </para> | |
804 | ||
805 | <para> | |
806 | In addition to the information available to all hooks. The | |
807 | following information is provided to the script: | |
808 | <itemizedlist> | |
809 | <listitem> | |
810 | <para> | |
811 | LXC_HOOK_TYPE: the hook type. This is either 'up' or 'down'. | |
812 | </para> | |
813 | </listitem> | |
814 | ||
815 | <listitem> | |
816 | <para> | |
817 | LXC_HOOK_SECTION: the section type 'net'. | |
818 | </para> | |
819 | </listitem> | |
820 | ||
821 | <listitem> | |
822 | <para> | |
823 | LXC_NET_TYPE: the network type. This is one of the valid | |
c9f52382 | 824 | network types listed here (e.g. 'vlan', 'macvlan', 'ipvlan', 'veth'). |
14a7b0f9 CB |
825 | </para> |
826 | </listitem> | |
827 | ||
828 | <listitem> | |
829 | <para> | |
830 | LXC_NET_PARENT: the parent device on the host. This is only | |
831 | set for network types 'mavclan', 'veth', 'phys'. | |
832 | </para> | |
833 | </listitem> | |
834 | ||
835 | <listitem> | |
836 | <para> | |
837 | LXC_NET_PEER: the name of the peer device on the host. This is | |
838 | only set for 'veth' network types. Note that this information | |
839 | is only available when <option>lxc.hook.version</option> is set | |
840 | to 1. | |
841 | </para> | |
842 | </listitem> | |
843 | </itemizedlist> | |
844 | ||
845 | Whether this information is provided in the form of environment | |
846 | variables or as arguments to the script depends on the value of | |
847 | <option>lxc.hook.version</option>. If set to 1 then information is | |
848 | provided in the form of environment variables. If set to 0 | |
849 | information is provided as arguments to the script. | |
c464fd7e | 850 | </para> |
14a7b0f9 | 851 | |
c464fd7e SG |
852 | <para> |
853 | Standard output from the script is logged at debug level. | |
854 | Standard error is not logged, but can be captured by the | |
855 | hook redirecting its standard error to standard output. | |
856 | </para> | |
857 | </listitem> | |
858 | </varlistentry> | |
55fc19a1 SG |
859 | </variablelist> |
860 | </refsect2> | |
861 | ||
862 | <refsect2> | |
863 | <title>New pseudo tty instance (devpts)</title> | |
864 | <para> | |
c464fd7e SG |
865 | For stricter isolation the container can have its own private |
866 | instance of the pseudo tty. | |
55fc19a1 SG |
867 | </para> |
868 | <variablelist> | |
c464fd7e SG |
869 | <varlistentry> |
870 | <term> | |
232763d6 | 871 | <option>lxc.pty.max</option> |
c464fd7e SG |
872 | </term> |
873 | <listitem> | |
874 | <para> | |
875 | If set, the container will have a new pseudo tty | |
876 | instance, making this private to it. The value specifies | |
41808e20 | 877 | the maximum number of pseudo ttys allowed for a pty |
55fc19a1 | 878 | instance (this limitation is not implemented yet). |
c464fd7e SG |
879 | </para> |
880 | </listitem> | |
881 | </varlistentry> | |
55fc19a1 SG |
882 | </variablelist> |
883 | </refsect2> | |
884 | ||
885 | <refsect2> | |
886 | <title>Container system console</title> | |
887 | <para> | |
c464fd7e SG |
888 | If the container is configured with a root filesystem and the |
889 | inittab file is setup to use the console, you may want to specify | |
890 | where the output of this console goes. | |
55fc19a1 SG |
891 | </para> |
892 | <variablelist> | |
28f3b1cd CB |
893 | |
894 | <varlistentry> | |
895 | <term> | |
896 | <option>lxc.console.buffer.size</option> | |
897 | </term> | |
898 | <listitem> | |
899 | <para> | |
900 | Setting this option instructs liblxc to allocate an in-memory | |
901 | ringbuffer. The container's console output will be written to the | |
902 | ringbuffer. Note that ringbuffer must be at least as big as a | |
903 | standard page size. When passed a value smaller than a single page | |
904 | size liblxc will allocate a ringbuffer of a single page size. A page | |
39ebeb72 | 905 | size is usually 4KB. |
28f3b1cd CB |
906 | |
907 | The keyword 'auto' will cause liblxc to allocate a ringbuffer of | |
39ebeb72 | 908 | 128KB. |
28f3b1cd CB |
909 | |
910 | When manually specifying a size for the ringbuffer the value should | |
911 | be a power of 2 when converted to bytes. Valid size prefixes are | |
39ebeb72 | 912 | 'KB', 'MB', 'GB'. (Note that all conversions are based on multiples |
913 | of 1024. That means 'KB' == 'KiB', 'MB' == 'MiB', 'GB' == 'GiB'. | |
6d276edc CB |
914 | Additionally, the case of the suffix is ignored, i.e. 'kB', 'KB' and |
915 | 'Kb' are treated equally.) | |
28f3b1cd CB |
916 | </para> |
917 | </listitem> | |
918 | </varlistentry> | |
919 | ||
861813e5 CB |
920 | <varlistentry> |
921 | <term> | |
922 | <option>lxc.console.size</option> | |
923 | </term> | |
924 | <listitem> | |
925 | <para> | |
926 | Setting this option instructs liblxc to place a limit on the size of | |
927 | the console log file specified in | |
928 | <option>lxc.console.logfile</option>. Note that size of the log file | |
929 | must be at least as big as a standard page size. When passed a value | |
930 | smaller than a single page size liblxc will set the size of log file | |
39ebeb72 | 931 | to a single page size. A page size is usually 4KB. |
861813e5 | 932 | |
39ebeb72 | 933 | The keyword 'auto' will cause liblxc to place a limit of 128KB on |
861813e5 CB |
934 | the log file. |
935 | ||
936 | When manually specifying a size for the log file the value should | |
937 | be a power of 2 when converted to bytes. Valid size prefixes are | |
39ebeb72 | 938 | 'KB', 'MB', 'GB'. (Note that all conversions are based on multiples |
d4a7da46 | 939 | of 1024. That means 'KB' == 'KiB', 'MB' == 'MiB', 'GB' == 'GiB'. |
6d276edc CB |
940 | Additionally, the case of the suffix is ignored, i.e. 'kB', 'KB' and |
941 | 'Kb' are treated equally.) | |
861813e5 CB |
942 | |
943 | If users want to mirror the console ringbuffer on disk they should set | |
944 | <option>lxc.console.size</option> equal to | |
945 | <option>lxc.console.buffer.size</option>. | |
946 | </para> | |
947 | </listitem> | |
948 | </varlistentry> | |
949 | ||
c464fd7e SG |
950 | <varlistentry> |
951 | <term> | |
952 | <option>lxc.console.logfile</option> | |
953 | </term> | |
954 | <listitem> | |
955 | <para> | |
d91adfa6 CB |
956 | Specify a path to a file where the console output will be written. |
957 | Note that in contrast to the on-disk ringbuffer logfile this file | |
958 | will keep growing potentially filling up the users disks if not | |
959 | rotated and deleted. This problem can also be avoided by using the | |
960 | in-memory ringbuffer options | |
961 | <option>lxc.console.buffer.size</option> and | |
962 | <option>lxc.console.buffer.logfile</option>. | |
c464fd7e SG |
963 | </para> |
964 | </listitem> | |
965 | </varlistentry> | |
d91adfa6 CB |
966 | |
967 | <varlistentry> | |
968 | <term> | |
969 | <option>lxc.console.rotate</option> | |
970 | </term> | |
971 | <listitem> | |
972 | <para> | |
973 | Whether to rotate the console logfile specified in | |
974 | <option>lxc.console.logfile</option>. Users can send an API | |
975 | request to rotate the logfile. Note that the old logfile will have | |
976 | the same name as the original with the suffix ".1" appended. | |
977 | ||
978 | Users wishing to prevent the console log file from filling the | |
979 | disk should rotate the logfile and delete it if unneeded. This | |
980 | problem can also be avoided by using the in-memory ringbuffer | |
981 | options <option>lxc.console.buffer.size</option> and | |
982 | <option>lxc.console.buffer.logfile</option>. | |
983 | </para> | |
984 | </listitem> | |
985 | </varlistentry> | |
986 | ||
c464fd7e SG |
987 | <varlistentry> |
988 | <term> | |
3aed4934 | 989 | <option>lxc.console.path</option> |
c464fd7e SG |
990 | </term> |
991 | <listitem> | |
992 | <para> | |
993 | Specify a path to a device to which the console will be | |
6e3bb289 CB |
994 | attached. The keyword 'none' will simply disable the |
995 | console. Note, when specifying 'none' and creating a device node | |
996 | for the console in the container at /dev/console or bind-mounting | |
997 | the hosts's /dev/console into the container at /dev/console the | |
998 | container will have direct access to the hosts's /dev/console. | |
999 | This is dangerous when the container has write access to the | |
1000 | device and should thus be used with caution. | |
c464fd7e SG |
1001 | </para> |
1002 | </listitem> | |
1003 | </varlistentry> | |
55fc19a1 SG |
1004 | </variablelist> |
1005 | </refsect2> | |
1006 | ||
1007 | <refsect2> | |
1008 | <title>Console through the ttys</title> | |
1009 | <para> | |
c464fd7e SG |
1010 | This option is useful if the container is configured with a root |
1011 | filesystem and the inittab file is setup to launch a getty on the | |
1012 | ttys. The option specifies the number of ttys to be available for | |
1013 | the container. The number of gettys in the inittab file of the | |
1014 | container should not be greater than the number of ttys specified | |
1015 | in this option, otherwise the excess getty sessions will die and | |
1016 | respawn indefinitely giving annoying messages on the console or in | |
1017 | <filename>/var/log/messages</filename>. | |
55fc19a1 SG |
1018 | </para> |
1019 | <variablelist> | |
c464fd7e SG |
1020 | <varlistentry> |
1021 | <term> | |
fe1c5887 | 1022 | <option>lxc.tty.max</option> |
c464fd7e SG |
1023 | </term> |
1024 | <listitem> | |
1025 | <para> | |
1026 | Specify the number of tty to make available to the | |
1027 | container. | |
1028 | </para> | |
1029 | </listitem> | |
1030 | </varlistentry> | |
55fc19a1 SG |
1031 | </variablelist> |
1032 | </refsect2> | |
1033 | ||
1034 | <refsect2> | |
1035 | <title>Console devices location</title> | |
1036 | <para> | |
1037 | LXC consoles are provided through Unix98 PTYs created on the | |
c464fd7e SG |
1038 | host and bind-mounted over the expected devices in the container. |
1039 | By default, they are bind-mounted over <filename>/dev/console</filename> | |
1040 | and <filename>/dev/ttyN</filename>. This can prevent package upgrades | |
1041 | in the guest. Therefore you can specify a directory location (under | |
1042 | <filename>/dev</filename> under which LXC will create the files and | |
1043 | bind-mount over them. These will then be symbolically linked to | |
1044 | <filename>/dev/console</filename> and <filename>/dev/ttyN</filename>. | |
1045 | A package upgrade can then succeed as it is able to remove and replace | |
1046 | the symbolic links. | |
55fc19a1 SG |
1047 | </para> |
1048 | <variablelist> | |
c464fd7e SG |
1049 | <varlistentry> |
1050 | <term> | |
fe1c5887 | 1051 | <option>lxc.tty.dir</option> |
c464fd7e SG |
1052 | </term> |
1053 | <listitem> | |
1054 | <para> | |
1055 | Specify a directory under <filename>/dev</filename> | |
6e3bb289 CB |
1056 | under which to create the container console devices. Note that LXC |
1057 | will move any bind-mounts or device nodes for /dev/console into | |
1058 | this directory. | |
c464fd7e SG |
1059 | </para> |
1060 | </listitem> | |
1061 | </varlistentry> | |
55fc19a1 SG |
1062 | </variablelist> |
1063 | </refsect2> | |
1064 | ||
1065 | <refsect2> | |
1066 | <title>/dev directory</title> | |
1067 | <para> | |
c464fd7e SG |
1068 | By default, lxc creates a few symbolic links (fd,stdin,stdout,stderr) |
1069 | in the container's <filename>/dev</filename> directory but does not | |
1070 | automatically create device node entries. This allows the container's | |
1071 | <filename>/dev</filename> to be set up as needed in the container | |
1072 | rootfs. If lxc.autodev is set to 1, then after mounting the container's | |
1073 | rootfs LXC will mount a fresh tmpfs under <filename>/dev</filename> | |
63012bdd CK |
1074 | (limited to 500K by default, unless defined in lxc.autodev.tmpfs.size) |
1075 | and fill in a minimal set of initial devices. | |
55fc19a1 SG |
1076 | This is generally required when starting a container containing |
1077 | a "systemd" based "init" but may be optional at other times. Additional | |
1078 | devices in the containers /dev directory may be created through the | |
1079 | use of the <option>lxc.hook.autodev</option> hook. | |
1080 | </para> | |
1081 | <variablelist> | |
c464fd7e SG |
1082 | <varlistentry> |
1083 | <term> | |
1084 | <option>lxc.autodev</option> | |
1085 | </term> | |
1086 | <listitem> | |
1087 | <para> | |
124fa0a8 | 1088 | Set this to 0 to stop LXC from mounting and populating a minimal |
c464fd7e SG |
1089 | <filename>/dev</filename> when starting the container. |
1090 | </para> | |
1091 | </listitem> | |
1092 | </varlistentry> | |
63012bdd CK |
1093 | |
1094 | <varlistentry> | |
1095 | <term> | |
1096 | <option>lxc.autodev.tmpfs.size</option> | |
1097 | </term> | |
1098 | <listitem> | |
1099 | <para> | |
1100 | Set this to define the size of the /dev tmpfs. | |
1101 | The default value is 500000 (500K). If the parameter is used | |
1102 | but without value, the default value is used. | |
1103 | </para> | |
1104 | </listitem> | |
1105 | </varlistentry> | |
55fc19a1 | 1106 | </variablelist> |
55fc19a1 SG |
1107 | </refsect2> |
1108 | ||
1109 | <refsect2> | |
1110 | <title>Mount points</title> | |
1111 | <para> | |
c464fd7e SG |
1112 | The mount points section specifies the different places to be |
1113 | mounted. These mount points will be private to the container | |
1114 | and won't be visible by the processes running outside of the | |
1115 | container. This is useful to mount /etc, /var or /home for | |
1116 | examples. | |
55fc19a1 | 1117 | </para> |
592fd47a SH |
1118 | <para> |
1119 | NOTE - LXC will generally ensure that mount targets and relative | |
1120 | bind-mount sources are properly confined under the container | |
1121 | root, to avoid attacks involving over-mounting host directories | |
1122 | and files. (Symbolic links in absolute mount sources are ignored) | |
1123 | However, if the container configuration first mounts a directory which | |
1124 | is under the control of the container user, such as /home/joe, into | |
1125 | the container at some <filename>path</filename>, and then mounts | |
1126 | under <filename>path</filename>, then a TOCTTOU attack would be | |
1127 | possible where the container user modifies a symbolic link under | |
f48e8071 | 1128 | their home directory at just the right time. |
592fd47a | 1129 | </para> |
55fc19a1 | 1130 | <variablelist> |
c464fd7e SG |
1131 | <varlistentry> |
1132 | <term> | |
47148e96 | 1133 | <option>lxc.mount.fstab</option> |
c464fd7e SG |
1134 | </term> |
1135 | <listitem> | |
1136 | <para> | |
1137 | specify a file location in | |
1138 | the <filename>fstab</filename> format, containing the | |
1139 | mount information. The mount target location can and in | |
1140 | most cases should be a relative path, which will become | |
1141 | relative to the mounted container root. For instance, | |
1142 | </para> | |
b9986e43 CB |
1143 | <programlisting> |
1144 | proc proc proc nodev,noexec,nosuid 0 0 | |
1145 | </programlisting> | |
c464fd7e SG |
1146 | <para> |
1147 | Will mount a proc filesystem under the container's /proc, | |
1148 | regardless of where the root filesystem comes from. This | |
1149 | is resilient to block device backed filesystems as well as | |
1150 | container cloning. | |
1151 | </para> | |
1152 | <para> | |
1153 | Note that when mounting a filesystem from an | |
1154 | image file or block device the third field (fs_vfstype) | |
1155 | cannot be auto as with | |
55fc19a1 | 1156 | <citerefentry> |
c464fd7e | 1157 | <refentrytitle>mount</refentrytitle> |
55fc19a1 SG |
1158 | <manvolnum>8</manvolnum> |
1159 | </citerefentry> | |
1160 | but must be explicitly specified. | |
c464fd7e SG |
1161 | </para> |
1162 | </listitem> | |
1163 | </varlistentry> | |
1164 | ||
1165 | <varlistentry> | |
1166 | <term> | |
1167 | <option>lxc.mount.entry</option> | |
1168 | </term> | |
1169 | <listitem> | |
1170 | <para> | |
d840039e | 1171 | Specify a mount point corresponding to a line in the |
c464fd7e | 1172 | fstab format. |
f5b67b36 | 1173 | |
f1d358b0 | 1174 | Moreover lxc supports mount propagation, such as rshared or |
d840039e | 1175 | rprivate, and adds three additional mount options. |
f5b67b36 NC |
1176 | <option>optional</option> don't fail if mount does not work. |
1177 | <option>create=dir</option> or <option>create=file</option> | |
1178 | to create dir (or file) when the point will be mounted. | |
181437fd YT |
1179 | <option>relative</option> source path is taken to be relative to |
1180 | the mounted container root. For instance, | |
1181 | </para> | |
767bd70a RK |
1182 | <programlisting> |
1183 | dev/null proc/kcore none bind,relative 0 0 | |
1184 | </programlisting> | |
181437fd YT |
1185 | <para> |
1186 | Will expand dev/null to ${<option>LXC_ROOTFS_MOUNT</option>}/dev/null, | |
1187 | and mount it to proc/kcore inside the container. | |
1188 | </para> | |
c464fd7e SG |
1189 | </listitem> |
1190 | </varlistentry> | |
1191 | ||
1192 | <varlistentry> | |
1193 | <term> | |
1194 | <option>lxc.mount.auto</option> | |
1195 | </term> | |
1196 | <listitem> | |
1197 | <para> | |
1198 | specify which standard kernel file systems should be | |
1199 | automatically mounted. This may dramatically simplify | |
1200 | the configuration. The file systems are: | |
1201 | </para> | |
1202 | <itemizedlist> | |
1203 | <listitem> | |
1204 | <para> | |
1205 | <option>proc:mixed</option> (or <option>proc</option>): | |
1206 | mount <filename>/proc</filename> as read-write, but | |
1207 | remount <filename>/proc/sys</filename> and | |
1208 | <filename>/proc/sysrq-trigger</filename> read-only | |
1209 | for security / container isolation purposes. | |
1210 | </para> | |
1211 | </listitem> | |
1212 | <listitem> | |
1213 | <para> | |
1214 | <option>proc:rw</option>: mount | |
1215 | <filename>/proc</filename> as read-write | |
1216 | </para> | |
1217 | </listitem> | |
1218 | <listitem> | |
1219 | <para> | |
f24a52d5 SG |
1220 | <option>sys:mixed</option> (or <option>sys</option>): |
1221 | mount <filename>/sys</filename> as read-only but with | |
1222 | /sys/devices/virtual/net writable. | |
1223 | </para> | |
1224 | </listitem> | |
1225 | <listitem> | |
1226 | <para> | |
1227 | <option>sys:ro</option>: | |
c464fd7e SG |
1228 | mount <filename>/sys</filename> as read-only |
1229 | for security / container isolation purposes. | |
1230 | </para> | |
1231 | </listitem> | |
1232 | <listitem> | |
1233 | <para> | |
1234 | <option>sys:rw</option>: mount | |
1235 | <filename>/sys</filename> as read-write | |
1236 | </para> | |
1237 | </listitem> | |
3f69fb12 | 1238 | |
c464fd7e SG |
1239 | <listitem> |
1240 | <para> | |
1241 | <option>cgroup:mixed</option>: | |
3f69fb12 SY |
1242 | Mount a tmpfs to <filename>/sys/fs/cgroup</filename>, |
1243 | create directories for all hierarchies to which the container | |
1244 | is added, create subdirectories in those hierarchies with the | |
1245 | name of the cgroup, and bind-mount the container's own cgroup | |
1246 | into that directory. The container will be able to write to | |
1247 | its own cgroup directory, but not the parents, since they will | |
1248 | be remounted read-only. | |
c464fd7e SG |
1249 | </para> |
1250 | </listitem> | |
3f69fb12 | 1251 | |
c464fd7e SG |
1252 | <listitem> |
1253 | <para> | |
3f69fb12 SY |
1254 | <option>cgroup:mixed:force</option>: |
1255 | The <option>force</option> option will cause LXC to perform | |
1256 | the cgroup mounts for the container under all circumstances. | |
1257 | Otherwise it is similar to <option>cgroup:mixed</option>. | |
1258 | This is mainly useful when the cgroup namespaces are enabled | |
1259 | where LXC will normally leave mounting cgroups to the init | |
1260 | binary of the container since it is perfectly safe to do so. | |
c464fd7e SG |
1261 | </para> |
1262 | </listitem> | |
3f69fb12 SY |
1263 | |
1264 | <listitem> | |
1265 | <para> | |
1266 | <option>cgroup:ro</option>: | |
1267 | similar to <option>cgroup:mixed</option>, but everything will | |
1268 | be mounted read-only. | |
1269 | </para> | |
1270 | </listitem> | |
1271 | ||
1272 | <listitem> | |
1273 | <para> | |
1274 | <option>cgroup:ro:force</option>: | |
1275 | The <option>force</option> option will cause LXC to perform | |
1276 | the cgroup mounts for the container under all circumstances. | |
1277 | Otherwise it is similar to <option>cgroup:ro</option>. | |
1278 | This is mainly useful when the cgroup namespaces are enabled | |
1279 | where LXC will normally leave mounting cgroups to the init | |
1280 | binary of the container since it is perfectly safe to do so. | |
1281 | </para> | |
1282 | </listitem> | |
1283 | ||
c464fd7e SG |
1284 | <listitem> |
1285 | <para> | |
1286 | <option>cgroup:rw</option>: similar to | |
3f69fb12 SY |
1287 | <option>cgroup:mixed</option>, but everything will be mounted |
1288 | read-write. Note that the paths leading up to the container's | |
1289 | own cgroup will be writable, but will not be a cgroup | |
1290 | filesystem but just part of the tmpfs of | |
1291 | <filename>/sys/fs/cgroup</filename> | |
1292 | </para> | |
1293 | </listitem> | |
1294 | ||
1295 | <listitem> | |
1296 | <para> | |
1297 | <option>cgroup:rw:force</option>: | |
1298 | The <option>force</option> option will cause LXC to perform | |
1299 | the cgroup mounts for the container under all circumstances. | |
1300 | Otherwise it is similar to <option>cgroup:rw</option>. | |
1301 | This is mainly useful when the cgroup namespaces are enabled | |
1302 | where LXC will normally leave mounting cgroups to the init | |
1303 | binary of the container since it is perfectly safe to do so. | |
c464fd7e SG |
1304 | </para> |
1305 | </listitem> | |
3f69fb12 | 1306 | |
c464fd7e SG |
1307 | <listitem> |
1308 | <para> | |
1309 | <option>cgroup</option> (without specifier): | |
1310 | defaults to <option>cgroup:rw</option> if the | |
1311 | container retains the CAP_SYS_ADMIN capability, | |
1312 | <option>cgroup:mixed</option> otherwise. | |
1313 | </para> | |
1314 | </listitem> | |
e7806b2e | 1315 | |
c464fd7e SG |
1316 | <listitem> |
1317 | <para> | |
1318 | <option>cgroup-full:mixed</option>: | |
1319 | mount a tmpfs to <filename>/sys/fs/cgroup</filename>, | |
1320 | create directories for all hierarchies to which | |
1321 | the container is added, bind-mount the hierarchies | |
1322 | from the host to the container and make everything | |
1323 | read-only except the container's own cgroup. Note | |
1324 | that compared to <option>cgroup</option>, where | |
1325 | all paths leading up to the container's own cgroup | |
1326 | are just simple directories in the underlying | |
1327 | tmpfs, here | |
1328 | <filename>/sys/fs/cgroup/$hierarchy</filename> | |
1329 | will contain the host's full cgroup hierarchy, | |
1330 | albeit read-only outside the container's own cgroup. | |
1331 | This may leak quite a bit of information into the | |
1332 | container. | |
1333 | </para> | |
1334 | </listitem> | |
e7806b2e CB |
1335 | |
1336 | <listitem> | |
1337 | <para> | |
1338 | <option>cgroup-full:mixed:force</option>: | |
1339 | The <option>force</option> option will cause LXC to perform | |
1340 | the cgroup mounts for the container under all circumstances. | |
1341 | Otherwise it is similar to <option>cgroup-full:mixed</option>. | |
1342 | This is mainly useful when the cgroup namespaces are enabled | |
1343 | where LXC will normally leave mounting cgroups to the init | |
1344 | binary of the container since it is perfectly safe to do so. | |
1345 | </para> | |
1346 | </listitem> | |
1347 | ||
c464fd7e SG |
1348 | <listitem> |
1349 | <para> | |
1350 | <option>cgroup-full:ro</option>: similar to | |
1351 | <option>cgroup-full:mixed</option>, but everything | |
1352 | will be mounted read-only. | |
1353 | </para> | |
1354 | </listitem> | |
e7806b2e CB |
1355 | |
1356 | <listitem> | |
1357 | <para> | |
1358 | <option>cgroup-full:ro:force</option>: | |
1359 | The <option>force</option> option will cause LXC to perform | |
1360 | the cgroup mounts for the container under all circumstances. | |
1361 | Otherwise it is similar to <option>cgroup-full:ro</option>. | |
1362 | This is mainly useful when the cgroup namespaces are enabled | |
1363 | where LXC will normally leave mounting cgroups to the init | |
1364 | binary of the container since it is perfectly safe to do so. | |
1365 | </para> | |
1366 | </listitem> | |
1367 | ||
c464fd7e SG |
1368 | <listitem> |
1369 | <para> | |
1370 | <option>cgroup-full:rw</option>: similar to | |
1371 | <option>cgroup-full:mixed</option>, but everything | |
1372 | will be mounted read-write. Note that in this case, | |
1373 | the container may escape its own cgroup. (Note also | |
1374 | that if the container has CAP_SYS_ADMIN support | |
1375 | and can mount the cgroup filesystem itself, it may | |
1376 | do so anyway.) | |
1377 | </para> | |
1378 | </listitem> | |
e7806b2e CB |
1379 | |
1380 | <listitem> | |
1381 | <para> | |
1382 | <option>cgroup-full:rw:force</option>: | |
1383 | The <option>force</option> option will cause LXC to perform | |
1384 | the cgroup mounts for the container under all circumstances. | |
1385 | Otherwise it is similar to <option>cgroup-full:rw</option>. | |
1386 | This is mainly useful when the cgroup namespaces are enabled | |
1387 | where LXC will normally leave mounting cgroups to the init | |
1388 | binary of the container since it is perfectly safe to do so. | |
1389 | </para> | |
1390 | </listitem> | |
1391 | ||
c464fd7e SG |
1392 | <listitem> |
1393 | <para> | |
1394 | <option>cgroup-full</option> (without specifier): | |
1395 | defaults to <option>cgroup-full:rw</option> if the | |
1396 | container retains the CAP_SYS_ADMIN capability, | |
1397 | <option>cgroup-full:mixed</option> otherwise. | |
1398 | </para> | |
1399 | </listitem> | |
e7806b2e | 1400 | |
c464fd7e | 1401 | </itemizedlist> |
4608594e SH |
1402 | <para> |
1403 | If cgroup namespaces are enabled, then any <option>cgroup</option> | |
1404 | auto-mounting request will be ignored, since the container can | |
1405 | mount the filesystems itself, and automounting can confuse the | |
1406 | container init. | |
1407 | </para> | |
c464fd7e SG |
1408 | <para> |
1409 | Note that if automatic mounting of the cgroup filesystem | |
1410 | is enabled, the tmpfs under | |
1411 | <filename>/sys/fs/cgroup</filename> will always be | |
1412 | mounted read-write (but for the <option>:mixed</option> | |
1413 | and <option>:ro</option> cases, the individual | |
1414 | hierarchies, | |
1415 | <filename>/sys/fs/cgroup/$hierarchy</filename>, will be | |
1416 | read-only). This is in order to work around a quirk in | |
1417 | Ubuntu's | |
b46f0553 | 1418 | <citerefentry> |
c464fd7e | 1419 | <refentrytitle>mountall</refentrytitle> |
b46f0553 CS |
1420 | <manvolnum>8</manvolnum> |
1421 | </citerefentry> | |
c464fd7e SG |
1422 | command that will cause containers to wait for user |
1423 | input at boot if | |
1424 | <filename>/sys/fs/cgroup</filename> is mounted read-only | |
1425 | and the container can't remount it read-write due to a | |
1426 | lack of CAP_SYS_ADMIN. | |
1427 | </para> | |
1428 | <para> | |
1429 | Examples: | |
1430 | </para> | |
1431 | <programlisting> | |
1432 | lxc.mount.auto = proc sys cgroup | |
1433 | lxc.mount.auto = proc:rw sys:rw cgroup-full:rw | |
1434 | </programlisting> | |
1435 | </listitem> | |
1436 | </varlistentry> | |
55fc19a1 SG |
1437 | |
1438 | </variablelist> | |
1439 | </refsect2> | |
1440 | ||
1441 | <refsect2> | |
1442 | <title>Root file system</title> | |
1443 | <para> | |
c464fd7e SG |
1444 | The root file system of the container can be different than that |
1445 | of the host system. | |
55fc19a1 SG |
1446 | </para> |
1447 | <variablelist> | |
c464fd7e SG |
1448 | <varlistentry> |
1449 | <term> | |
7a96a068 | 1450 | <option>lxc.rootfs.path</option> |
c464fd7e SG |
1451 | </term> |
1452 | <listitem> | |
1453 | <para> | |
1454 | specify the root file system for the container. It can | |
1455 | be an image file, a directory or a block device. If not | |
1456 | specified, the container shares its root file system | |
1457 | with the host. | |
1458 | </para> | |
1459 | <para> | |
f1c26f2c SH |
1460 | For directory or simple block-device backed containers, |
1461 | a pathname can be used. If the rootfs is backed by a nbd | |
1462 | device, then <filename>nbd:file:1</filename> specifies that | |
1463 | <filename>file</filename> should be attached to a nbd device, | |
1464 | and partition 1 should be mounted as the rootfs. | |
1465 | <filename>nbd:file</filename> specifies that the nbd device | |
1466 | itself should be mounted. <filename>overlayfs:/lower:/upper</filename> | |
1467 | specifies that the rootfs should be an overlay with <filename>/upper</filename> | |
1468 | being mounted read-write over a read-only mount of <filename>/lower</filename>. | |
12e6ab5d | 1469 | For <filename>overlay</filename> multiple <filename>/lower</filename> |
280d2379 | 1470 | directories can be specified. <filename>loop:/file</filename> tells lxc to attach |
f1c26f2c | 1471 | <filename>/file</filename> to a loop device and mount the loop device. |
c464fd7e SG |
1472 | </para> |
1473 | </listitem> | |
1474 | </varlistentry> | |
1475 | ||
1476 | <varlistentry> | |
1477 | <term> | |
1478 | <option>lxc.rootfs.mount</option> | |
1479 | </term> | |
1480 | <listitem> | |
1481 | <para> | |
7a96a068 | 1482 | where to recursively bind <option>lxc.rootfs.path</option> |
c464fd7e SG |
1483 | before pivoting. This is to ensure success of the |
1484 | <citerefentry> | |
1485 | <refentrytitle><command>pivot_root</command></refentrytitle> | |
1486 | <manvolnum>8</manvolnum> | |
1487 | </citerefentry> | |
1488 | syscall. Any directory suffices, the default should | |
1489 | generally work. | |
1490 | </para> | |
1491 | </listitem> | |
1492 | </varlistentry> | |
1493 | ||
1494 | <varlistentry> | |
1495 | <term> | |
1496 | <option>lxc.rootfs.options</option> | |
1497 | </term> | |
1498 | <listitem> | |
1499 | <para> | |
1852be90 CB |
1500 | Specify extra mount options to use when mounting the rootfs. |
1501 | The format of the mount options corresponds to the | |
1502 | format used in fstab. In addition, LXC supports the custom | |
1503 | <option>idmap=</option> mount option. This option can be used | |
1504 | to tell LXC to create an idmapped mount for the container's | |
1505 | rootfs. This is useful when the user doesn't want to recursively | |
1506 | chown the rootfs of the container to match the idmapping of the | |
1507 | user namespace the container is going to use. Instead an | |
1508 | idmapped mount can be used to handle this. | |
1509 | The argument for | |
1510 | <option>idmap=</option> | |
1511 | can either be a path pointing to a user namespace file that | |
1512 | LXC will open and use to idmap the rootfs or the special value | |
1513 | "container" which will instruct LXC to use | |
1514 | the container's user namespace to idmap the rootfs. | |
c464fd7e SG |
1515 | </para> |
1516 | </listitem> | |
1517 | </varlistentry> | |
a17b1e65 | 1518 | |
e3136289 KY |
1519 | <varlistentry> |
1520 | <term> | |
1521 | <option>lxc.rootfs.managed</option> | |
1522 | </term> | |
1523 | <listitem> | |
1524 | <para> | |
1525 | Set this to 0 to indicate that LXC is not managing the | |
1526 | container storage, then LXC will not modify the | |
1527 | container storage. The default is 1. | |
1528 | </para> | |
1529 | </listitem> | |
1530 | </varlistentry> | |
1531 | ||
55fc19a1 SG |
1532 | </variablelist> |
1533 | </refsect2> | |
1534 | ||
1535 | <refsect2> | |
54dbe498 | 1536 | <title>Control groups ("cgroups")</title> |
55fc19a1 | 1537 | <para> |
c464fd7e SG |
1538 | The control group section contains the configuration for the |
1539 | different subsystem. <command>lxc</command> does not check the | |
1540 | correctness of the subsystem name. This has the disadvantage | |
1541 | of not detecting configuration errors until the container is | |
1542 | started, but has the advantage of permitting any future | |
1543 | subsystem. | |
55fc19a1 | 1544 | </para> |
5025f3a6 CB |
1545 | |
1546 | <para> | |
1547 | The kernel implementation of cgroups has changed significantly over the | |
1548 | years. With Linux 4.5 support for a new cgroup filesystem was added | |
1549 | usually referred to as "cgroup2" or "unified hierarchy". Since then the | |
1550 | old cgroup filesystem is usually referred to as "cgroup1" or the | |
1551 | "legacy hierarchies". Please see the cgroups manual page for a detailed | |
1552 | explanation of the differences between the two versions. | |
1553 | </para> | |
1554 | ||
1555 | <para> | |
1556 | LXC distinguishes settings for the legacy and the unified hierarchy by | |
1557 | using different configuration key prefixes. To alter settings for | |
1558 | controllers in a legacy hierarchy the key prefix | |
1559 | <option>lxc.cgroup.</option> must be used and in order to alter the | |
1560 | settings for a controller in the unified hierarchy the | |
1561 | <option>lxc.cgroup2.</option> key must be used. Note that LXC will | |
1562 | ignore <option>lxc.cgroup.</option> settings on systems that only use | |
1563 | the unified hierarchy. Conversely, it will ignore | |
1564 | <option>lxc.cgroup2.</option> options on systems that only use legacy | |
1565 | hierachies. | |
1566 | </para> | |
1567 | ||
1568 | <para> | |
1569 | At its core a cgroup hierarchy is a way to hierarchically organize | |
1570 | processes. Usually a cgroup hierarchy will have one or more | |
1571 | "controllers" enabled. A "controller" in a cgroup hierarchy is usually | |
1572 | responsible for distributing a specific type of system resource along | |
1573 | the hierarchy. Controllers include the "pids" controller, the "cpu" | |
1574 | controller, the "memory" controller and others. Some controllers | |
1575 | however do not fall into the category of distributing a system | |
1576 | resource, instead they are often referred to as "utility" controllers. | |
1577 | One utility controller is the device controller. Instead of | |
1578 | distributing a system resource it allows to manage device access. | |
1579 | </para> | |
1580 | ||
1581 | <para> | |
1582 | In the legacy hierarchy the device controller was implemented like most | |
1583 | other controllers as a set of files that could be written to. These | |
1584 | files where named "devices.allow" and "devices.deny". The legacy device | |
1585 | controller allowed the implementation of both "allowlists" and | |
1586 | "denylists". | |
1587 | </para> | |
1588 | ||
1589 | <para> | |
1590 | An allowlist is a device program that by default blocks access to all | |
1591 | devices. In order to access specific devices "allow rules" for | |
1592 | particular devices or device classes must be specified. In contrast, a | |
1593 | denylist is a device program that by default allows access to all | |
1594 | devices. In order to restrict access to specific devices "deny rules" | |
1595 | for particular devices or device classes must be specified. | |
1596 | </para> | |
1597 | ||
1598 | <para> | |
1599 | In the unified cgroup hierarchy the implementation of the device | |
1600 | controller has completely changed. Instead of files to read from and | |
1601 | write to a eBPF program of | |
1602 | <option>BPF_PROG_TYPE_CGROUP_DEVICE</option> can be attached to a | |
1603 | cgroup. Even though the kernel implementation has changed completely | |
1604 | LXC tries to allow for the same semantics to be followed in the legacy | |
1605 | device cgroup and the unified eBPF-based device controller. The | |
1606 | following paragraphs explain the semantics for the unified eBPF-based | |
1607 | device controller. | |
1608 | </para> | |
1609 | ||
1610 | <para> | |
1611 | As mentioned the format for specifying device rules for the unified | |
1612 | eBPF-based device controller is the same as for the legacy cgroup | |
1613 | device controller; only the configuration key prefix has changed. | |
1614 | Specifically, device rules for the legacy cgroup device controller are | |
1615 | specified via <option>lxc.cgroup.devices.allow</option> and | |
1616 | <option>lxc.cgroup.devices.deny</option> whereas for the | |
1617 | cgroup2 eBPF-based device controller | |
1618 | <option>lxc.cgroup.devices.allow</option> and | |
1619 | <option>lxc.cgroup.devices.deny</option> must be used. | |
1620 | </para> | |
1621 | <para> | |
1622 | <itemizedlist> | |
1623 | <listitem> | |
1624 | <para> | |
1625 | A allowlist device rule | |
1626 | <programlisting> | |
1627 | lxc.cgroup2.devices.deny = a | |
1628 | </programlisting> | |
1629 | will cause LXC to instruct the kernel to block access to all | |
1630 | devices by default. To grant access to devices allow device rules | |
1631 | must be added via the <option>lxc.cgroup2.devices.allow</option> | |
1632 | key. This is referred to as a "allowlist" device program. | |
1633 | </para> | |
1634 | </listitem> | |
1635 | ||
1636 | <listitem> | |
1637 | <para> | |
1638 | A denylist device rule | |
1639 | <programlisting> | |
1640 | lxc.cgroup2.devices.allow = a | |
1641 | </programlisting> | |
1642 | will cause LXC to instruct the kernel to allow access to all | |
1643 | devices by default. To deny access to devices deny device rules | |
1644 | must be added via <option>lxc.cgroup2.devices.deny</option> key. | |
1645 | This is referred to as a "denylist" device program. | |
1646 | </para> | |
1647 | </listitem> | |
1648 | ||
1649 | <listitem> | |
1650 | <para> | |
1651 | Specifying any of the aformentioned two rules will cause all | |
1652 | previous rules to be cleared, i.e. the device list will be reset. | |
1653 | </para> | |
1654 | </listitem> | |
1655 | ||
1656 | <listitem> | |
1657 | <para> | |
1658 | When an allowlist program is requested, i.e. access to all devices | |
1659 | is blocked by default, specific deny rules for individual devices | |
1660 | or device classes are ignored. | |
1661 | </para> | |
1662 | </listitem> | |
1663 | ||
1664 | <listitem> | |
1665 | <para> | |
1666 | When a denylist program is requested, i.e. access to all devices | |
1667 | is allowed by default, specific allow rules for individual devices | |
1668 | or device classes are ignored. | |
1669 | </para> | |
1670 | </listitem> | |
1671 | </itemizedlist> | |
1672 | </para> | |
1673 | ||
1674 | <para> | |
1675 | For example the set of rules: | |
1676 | <programlisting> | |
1677 | lxc.cgroup2.devices.deny = a | |
1678 | lxc.cgroup2.devices.allow = c *:* m | |
1679 | lxc.cgroup2.devices.allow = b *:* m | |
1680 | lxc.cgroup2.devices.allow = c 1:3 rwm | |
1681 | </programlisting> | |
1682 | implements an allowlist device program, i.e. the kernel will block | |
1683 | access to all devices not specifically allowed in this list. This | |
1684 | particular program states that all character and block devices may be | |
1685 | created but only /dev/null might be read or written. | |
1686 | </para> | |
1687 | ||
1688 | <para> | |
1689 | If we instead switch to the following set of rules: | |
1690 | <programlisting> | |
1691 | lxc.cgroup2.devices.allow = a | |
1692 | lxc.cgroup2.devices.deny = c *:* m | |
1693 | lxc.cgroup2.devices.deny = b *:* m | |
1694 | lxc.cgroup2.devices.deny = c 1:3 rwm | |
1695 | </programlisting> | |
1696 | then LXC would instruct the kernel to implement a denylist, i.e. the | |
1697 | kernel will allow access to all devices not specifically denied in | |
1698 | this list. This particular program states that no character devices or | |
1699 | block devices might be created and that /dev/null is not allow allowed | |
1700 | to be read, written, or created. | |
1701 | </para> | |
1702 | ||
1703 | <para> | |
1704 | Now consider the same program but followed by a "global rule" | |
1705 | which determines the type of device program (allowlist or | |
1706 | denylist) as explained above: | |
1707 | <programlisting> | |
1708 | lxc.cgroup2.devices.allow = a | |
1709 | lxc.cgroup2.devices.deny = c *:* m | |
1710 | lxc.cgroup2.devices.deny = b *:* m | |
1711 | lxc.cgroup2.devices.deny = c 1:3 rwm | |
1712 | lxc.cgroup2.devices.allow = a | |
1713 | </programlisting> | |
1714 | The last line will cause LXC to reset the device list without changing | |
1715 | the type of device program. | |
1716 | </para> | |
1717 | ||
1718 | <para> | |
1719 | If we specify: | |
1720 | <programlisting> | |
1721 | lxc.cgroup2.devices.allow = a | |
1722 | lxc.cgroup2.devices.deny = c *:* m | |
1723 | lxc.cgroup2.devices.deny = b *:* m | |
1724 | lxc.cgroup2.devices.deny = c 1:3 rwm | |
1725 | lxc.cgroup2.devices.deny = a | |
1726 | </programlisting> | |
1727 | instead then the last line will cause LXC to reset the device list and | |
1728 | switch from a allowlist program to a denylist program. | |
1729 | </para> | |
55fc19a1 | 1730 | <variablelist> |
c464fd7e SG |
1731 | <varlistentry> |
1732 | <term> | |
e9b3d28d | 1733 | <option>lxc.cgroup.[controller name].[controller file]</option> |
c464fd7e SG |
1734 | </term> |
1735 | <listitem> | |
1736 | <para> | |
54860ed0 CB |
1737 | Specify the control group value to be set on a legacy cgroup |
1738 | hierarchy. The controller name is the literal name of the control | |
1739 | group. The permitted names and the syntax of their values is not | |
1740 | dictated by LXC, instead it depends on the features of the Linux | |
1741 | kernel running at the time the container is started, eg. | |
1742 | <option>lxc.cgroup.cpuset.cpus</option> | |
1743 | </para> | |
1744 | </listitem> | |
1745 | </varlistentry> | |
1746 | <varlistentry> | |
1747 | <term> | |
e9b3d28d | 1748 | <option>lxc.cgroup2.[controller name].[controller file]</option> |
54860ed0 CB |
1749 | </term> |
1750 | <listitem> | |
1751 | <para> | |
1752 | Specify the control group value to be set on the unified cgroup | |
d0d68468 | 1753 | hierarchy. The controller name is the literal name of the control |
54860ed0 CB |
1754 | group. The permitted names and the syntax of their values is not |
1755 | dictated by LXC, instead it depends on the features of the Linux | |
1756 | kernel running at the time the container is started, eg. | |
1757 | <option>lxc.cgroup2.memory.high</option> | |
c464fd7e SG |
1758 | </para> |
1759 | </listitem> | |
1760 | </varlistentry> | |
bdcbb6b3 CB |
1761 | <varlistentry> |
1762 | <term> | |
1763 | <option>lxc.cgroup.dir</option> | |
1764 | </term> | |
1765 | <listitem> | |
1766 | <para> | |
1767 | specify a directory or path in which the container's cgroup will | |
1768 | be created. For example, setting | |
1769 | <option>lxc.cgroup.dir = my-cgroup/first</option> for a container | |
1770 | named "c1" will create the container's cgroup as a sub-cgroup of | |
1771 | "my-cgroup". For example, if the user's current cgroup "my-user" | |
78be8d75 | 1772 | is located in the root cgroup of the cpuset controller in a |
bdcbb6b3 CB |
1773 | cgroup v1 hierarchy this would create the cgroup |
1774 | "/sys/fs/cgroup/cpuset/my-user/my-cgroup/first/c1" for the | |
1775 | container. Any missing cgroups will be created by LXC. This | |
1776 | presupposes that the user has write access to its current cgroup. | |
1777 | </para> | |
1778 | </listitem> | |
1779 | </varlistentry> | |
a900cbaf WB |
1780 | <varlistentry> |
1781 | <term> | |
1782 | <option>lxc.cgroup.dir.container</option> | |
1783 | </term> | |
1784 | <listitem> | |
1785 | <para> | |
1786 | This is similar to <option>lxc.cgroup.dir</option>, but must be | |
1787 | used together with <option>lxc.cgroup.dir.monitor</option> and | |
1788 | affects only the container's cgroup path. This option is mutually | |
1789 | exclusive with <option>lxc.cgroup.dir</option>. | |
1790 | Note that the final path the container attaches to may be | |
1791 | extended further by the | |
51b07b70 | 1792 | <option>lxc.cgroup.dir.container.inner</option> option. |
a900cbaf WB |
1793 | </para> |
1794 | </listitem> | |
1795 | </varlistentry> | |
1796 | <varlistentry> | |
1797 | <term> | |
1798 | <option>lxc.cgroup.dir.monitor</option> | |
1799 | </term> | |
1800 | <listitem> | |
1801 | <para> | |
1802 | This is the monitor process counterpart to | |
1803 | <option>lxc.cgroup.dir.container</option>. | |
1804 | </para> | |
1805 | </listitem> | |
1806 | </varlistentry> | |
7696c1f9 RJ |
1807 | <varlistentry> |
1808 | <term> | |
1809 | <option>lxc.cgroup.dir.monitor.pivot</option> | |
1810 | </term> | |
1811 | <listitem> | |
1812 | <para> | |
1813 | On container termination the PID of the monitor process is attached to this cgroup. | |
1814 | This path should not be a subpath of any other configured cgroup dir to ensure | |
1815 | proper removal of other cgroup paths on container termination. | |
1816 | </para> | |
1817 | </listitem> | |
1818 | </varlistentry> | |
a900cbaf WB |
1819 | <varlistentry> |
1820 | <term> | |
51b07b70 | 1821 | <option>lxc.cgroup.dir.container.inner</option> |
a900cbaf WB |
1822 | </term> |
1823 | <listitem> | |
1824 | <para> | |
1825 | Specify an additional subdirectory where the cgroup namespace | |
1826 | will be created. With this option, the cgroup limits will be | |
1827 | applied to the outer path specified in | |
1828 | <option>lxc.cgroup.dir.container</option>, which is not accessible | |
1829 | from within the container, making it possible to better enforce | |
1830 | limits for privileged containers in a way they cannot override | |
1831 | them. | |
1832 | This only works in conjunction with the | |
1833 | <option>lxc.cgroup.dir.container</option> and | |
1834 | <option>lxc.cgroup.dir.monitor</option> options and has otherwise | |
1835 | no effect. | |
1836 | </para> | |
1837 | </listitem> | |
1838 | </varlistentry> | |
c3b7fd80 KY |
1839 | <varlistentry> |
1840 | <term> | |
1841 | <option>lxc.cgroup.relative</option> | |
1842 | </term> | |
1843 | <listitem> | |
1844 | <para> | |
1845 | Set this to 1 to instruct LXC to never escape to the | |
1846 | root cgroup. This makes it easy for users to adhere to | |
1847 | restrictions enforced by cgroup2 and | |
1848 | systemd. Specifically, this makes it possible to run LXC | |
1849 | containers as systemd services. | |
1850 | </para> | |
1851 | </listitem> | |
1852 | </varlistentry> | |
55fc19a1 SG |
1853 | </variablelist> |
1854 | </refsect2> | |
1855 | ||
1856 | <refsect2> | |
1857 | <title>Capabilities</title> | |
1858 | <para> | |
c464fd7e SG |
1859 | The capabilities can be dropped in the container if this one |
1860 | is run as root. | |
55fc19a1 SG |
1861 | </para> |
1862 | <variablelist> | |
c464fd7e SG |
1863 | <varlistentry> |
1864 | <term> | |
1865 | <option>lxc.cap.drop</option> | |
1866 | </term> | |
1867 | <listitem> | |
1868 | <para> | |
1869 | Specify the capability to be dropped in the container. A | |
1870 | single line defining several capabilities with a space | |
1871 | separation is allowed. The format is the lower case of | |
1872 | the capability definition without the "CAP_" prefix, | |
1873 | eg. CAP_SYS_MODULE should be specified as | |
1874 | sys_module. See | |
1875 | <citerefentry> | |
1876 | <refentrytitle><command>capabilities</command></refentrytitle> | |
1877 | <manvolnum>7</manvolnum> | |
7eff30fd MH |
1878 | </citerefentry>. |
1879 | If used with no value, lxc will clear any drop capabilities | |
1880 | specified up to this point. | |
c464fd7e SG |
1881 | </para> |
1882 | </listitem> | |
1883 | </varlistentry> | |
1884 | <varlistentry> | |
1885 | <term> | |
1886 | <option>lxc.cap.keep</option> | |
1887 | </term> | |
1888 | <listitem> | |
1889 | <para> | |
1890 | Specify the capability to be kept in the container. All other | |
1891 | capabilities will be dropped. When a special value of "none" is | |
1892 | encountered, lxc will clear any keep capabilities specified up | |
1893 | to this point. A value of "none" alone can be used to drop all | |
1894 | capabilities. | |
1895 | </para> | |
1896 | </listitem> | |
1897 | </varlistentry> | |
55fc19a1 SG |
1898 | </variablelist> |
1899 | </refsect2> | |
1900 | ||
f3c9f122 | 1901 | <refsect2> |
46186acd | 1902 | <title>Namespaces</title> |
f3c9f122 | 1903 | <para> |
46186acd CB |
1904 | A namespace can be cloned (<option>lxc.namespace.clone</option>), |
1905 | kept (<option>lxc.namespace.keep</option>) or shared | |
1906 | (<option>lxc.namespace.share.[namespace identifier]</option>). | |
f3c9f122 CB |
1907 | </para> |
1908 | <variablelist> | |
46186acd CB |
1909 | <varlistentry> |
1910 | <term> | |
1911 | <option>lxc.namespace.clone</option> | |
1912 | </term> | |
1913 | <listitem> | |
1914 | <para> | |
1915 | Specify namespaces which the container is supposed to be created | |
1916 | with. The namespaces to create are specified as a space separated | |
1917 | list. Each namespace must correspond to one of the standard | |
1918 | namespace identifiers as seen in the | |
1919 | <filename>/proc/PID/ns</filename> directory. | |
1920 | When <option>lxc.namespace.clone</option> is not explicitly set all | |
1921 | namespaces supported by the kernel and the current configuration | |
1922 | will be used. | |
1923 | </para> | |
1924 | ||
1925 | <para> | |
1926 | To create a new mount, net and ipc namespace set | |
1927 | <option>lxc.namespace.clone=mount net ipc</option>. | |
1928 | </para> | |
1929 | </listitem> | |
1930 | </varlistentry> | |
1931 | ||
1932 | <varlistentry> | |
1933 | <term> | |
1934 | <option>lxc.namespace.keep</option> | |
1935 | </term> | |
1936 | <listitem> | |
1937 | <para> | |
1938 | Specify namespaces which the container is supposed to inherit from | |
1939 | the process that created it. The namespaces to keep are specified as | |
1940 | a space separated list. Each namespace must correspond to one of the | |
1941 | standard namespace identifiers as seen in the | |
1942 | <filename>/proc/PID/ns</filename> directory. | |
1943 | The <option>lxc.namespace.keep</option> is a | |
78522aa9 | 1944 | denylist option, i.e. it is useful when enforcing that containers |
46186acd CB |
1945 | must keep a specific set of namespaces. |
1946 | </para> | |
1947 | ||
1948 | <para> | |
1949 | To keep the network, user and ipc namespace set | |
1950 | <option>lxc.namespace.keep=user net ipc</option>. | |
1951 | </para> | |
1952 | ||
1953 | <para> | |
1954 | Note that sharing pid namespaces will likely not work with most init | |
1955 | systems. | |
1956 | </para> | |
1957 | ||
1958 | <para> | |
1959 | Note that if the container requests a new user namespace and the | |
1960 | container wants to inherit the network namespace it needs to inherit | |
1961 | the user namespace as well. | |
1962 | </para> | |
1963 | </listitem> | |
1964 | </varlistentry> | |
1965 | ||
f3c9f122 CB |
1966 | <varlistentry> |
1967 | <term> | |
b074bbf1 | 1968 | <option>lxc.namespace.share.[namespace identifier]</option> |
f3c9f122 CB |
1969 | </term> |
1970 | <listitem> | |
1971 | <para> | |
1972 | Specify a namespace to inherit from another container or process. | |
1973 | The <option>[namespace identifier]</option> suffix needs to be | |
1974 | replaced with one of the namespaces that appear in the | |
1975 | <filename>/proc/PID/ns</filename> directory. | |
1976 | </para> | |
1977 | ||
1978 | <para> | |
1979 | To inherit the namespace from another process set the | |
b074bbf1 CB |
1980 | <option>lxc.namespace.share.[namespace identifier]</option> to the PID of |
1981 | the process, e.g. <option>lxc.namespace.share.net=42</option>. | |
f3c9f122 CB |
1982 | </para> |
1983 | ||
1984 | <para> | |
d4a7da46 | 1985 | To inherit the namespace from another container set the |
b074bbf1 CB |
1986 | <option>lxc.namespace.share.[namespace identifier]</option> to the name of |
1987 | the container, e.g. <option>lxc.namespace.share.pid=c3</option>. | |
f3c9f122 CB |
1988 | </para> |
1989 | ||
1990 | <para> | |
1991 | To inherit the namespace from another container located in a | |
1992 | different path than the standard liblxc path set the | |
b074bbf1 | 1993 | <option>lxc.namespace.share.[namespace identifier]</option> to the full |
f3c9f122 | 1994 | path to the container, e.g. |
b074bbf1 | 1995 | <option>lxc.namespace.share.user=/opt/c3</option>. |
f3c9f122 CB |
1996 | </para> |
1997 | ||
1998 | <para> | |
1999 | In order to inherit namespaces the caller needs to have sufficient | |
2000 | privilege over the process or container. | |
2001 | </para> | |
2002 | ||
2003 | <para> | |
2004 | Note that sharing pid namespaces between system containers will | |
2005 | likely not work with most init systems. | |
2006 | </para> | |
2007 | ||
2008 | <para> | |
2009 | Note that if two processes are in different user namespaces and one | |
2010 | process wants to inherit the other's network namespace it usually | |
2011 | needs to inherit the user namespace as well. | |
2012 | </para> | |
8de90384 TA |
2013 | |
2014 | <para> | |
2015 | Note that without careful additional configuration of an LSM, | |
2016 | sharing user+pid namespaces with a task may allow that task to | |
2017 | escalate privileges to that of the task calling liblxc. | |
2018 | </para> | |
f3c9f122 CB |
2019 | </listitem> |
2020 | </varlistentry> | |
7fb5a8df CB |
2021 | |
2022 | <varlistentry> | |
2023 | <term> | |
2024 | <option>lxc.time.offset.boot</option> | |
2025 | </term> | |
2026 | <listitem> | |
2027 | <para> | |
2028 | Specify a positive or negative offset for the boottime clock. The | |
2029 | format accepts hours (h), minutes (m), seconds (s), | |
2030 | milliseconds (ms), microseconds (us), and nanoseconds (ns). | |
2031 | </para> | |
2032 | </listitem> | |
2033 | </varlistentry> | |
2034 | ||
2035 | <varlistentry> | |
2036 | <term> | |
2037 | <option>lxc.time.offset.monotonic</option> | |
2038 | </term> | |
2039 | <listitem> | |
2040 | <para> | |
bb144af2 | 2041 | Specify a positive or negative offset for the monotonic clock. The |
7fb5a8df CB |
2042 | format accepts hours (h), minutes (m), seconds (s), |
2043 | milliseconds (ms), microseconds (us), and nanoseconds (ns). | |
2044 | </para> | |
2045 | </listitem> | |
2046 | </varlistentry> | |
2047 | ||
f3c9f122 CB |
2048 | </variablelist> |
2049 | </refsect2> | |
2050 | ||
93f9e90d WB |
2051 | <refsect2> |
2052 | <title>Resource limits</title> | |
2053 | <para> | |
2054 | The soft and hard resource limits for the container can be changed. | |
2055 | Unprivileged containers can only lower them. Resources which are not | |
2056 | explicitly specified will be inherited. | |
2057 | </para> | |
2058 | <variablelist> | |
2059 | <varlistentry> | |
2060 | <term> | |
240d4b74 | 2061 | <option>lxc.prlimit.[limit name]</option> |
93f9e90d WB |
2062 | </term> |
2063 | <listitem> | |
2064 | <para> | |
2065 | Specify the resource limit to be set. A limit is specified as two | |
2066 | colon separated values which are either numeric or the word | |
2067 | 'unlimited'. A single value can be used as a shortcut to set both | |
2068 | soft and hard limit to the same value. The permitted names the | |
2069 | "RLIMIT_" resource names in lowercase without the "RLIMIT_" | |
2070 | prefix, eg. RLIMIT_NOFILE should be specified as "nofile". See | |
2071 | <citerefentry> | |
2072 | <refentrytitle><command>setrlimit</command></refentrytitle> | |
2073 | <manvolnum>2</manvolnum> | |
2074 | </citerefentry>. | |
2075 | If used with no value, lxc will clear the resource limit | |
2076 | specified up to this point. A resource with no explicitly | |
2077 | configured limitation will be inherited from the process starting | |
2078 | up the container. | |
2079 | </para> | |
2080 | </listitem> | |
2081 | </varlistentry> | |
2082 | </variablelist> | |
2083 | </refsect2> | |
2084 | ||
7edd0540 L |
2085 | <refsect2> |
2086 | <title>Sysctl</title> | |
2087 | <para> | |
2088 | Configure kernel parameters for the container. | |
2089 | </para> | |
2090 | <variablelist> | |
2091 | <varlistentry> | |
2092 | <term> | |
2093 | <option>lxc.sysctl.[kernel parameters name]</option> | |
2094 | </term> | |
2095 | <listitem> | |
2096 | <para> | |
d4a7da46 | 2097 | Specify the kernel parameters to be set. The parameters available |
7edd0540 | 2098 | are those listed under /proc/sys/. |
e409b214 | 2099 | Note that not all sysctls are namespaced. Changing Non-namespaced |
7edd0540 L |
2100 | sysctls will cause the system-wide setting to be modified. |
2101 | <citerefentry> | |
2102 | <refentrytitle><command>sysctl</command></refentrytitle> | |
2103 | <manvolnum>8</manvolnum> | |
2104 | </citerefentry>. | |
d4a7da46 | 2105 | If used with no value, lxc will clear the parameters specified up |
7edd0540 L |
2106 | to this point. |
2107 | </para> | |
2108 | </listitem> | |
2109 | </varlistentry> | |
2110 | </variablelist> | |
2111 | </refsect2> | |
2112 | ||
55fc19a1 SG |
2113 | <refsect2> |
2114 | <title>Apparmor profile</title> | |
2115 | <para> | |
c464fd7e SG |
2116 | If lxc was compiled and installed with apparmor support, and the host |
2117 | system has apparmor enabled, then the apparmor profile under which the | |
2118 | container should be run can be specified in the container | |
7a126ae1 SH |
2119 | configuration. The default is <command>lxc-container-default-cgns</command> |
2120 | if the host kernel is cgroup namespace aware, or | |
69e3b3be | 2121 | <command>lxc-container-default</command> otherwise. |
55fc19a1 SG |
2122 | </para> |
2123 | <variablelist> | |
c464fd7e SG |
2124 | <varlistentry> |
2125 | <term> | |
a1d5fdfd | 2126 | <option>lxc.apparmor.profile</option> |
c464fd7e SG |
2127 | </term> |
2128 | <listitem> | |
2129 | <para> | |
2130 | Specify the apparmor profile under which the container should | |
2131 | be run. To specify that the container should be unconfined, | |
2132 | use | |
2133 | </para> | |
a1d5fdfd | 2134 | <programlisting>lxc.apparmor.profile = unconfined</programlisting> |
7a126ae1 SH |
2135 | <para> |
2136 | If the apparmor profile should remain unchanged (i.e. if you | |
2137 | are nesting containers and are already confined), then use | |
2138 | </para> | |
a1d5fdfd | 2139 | <programlisting>lxc.apparmor.profile = unchanged</programlisting> |
8dca2bd3 KY |
2140 | <para> |
2141 | If you instruct LXC to generate the apparmor profile, | |
2142 | then use | |
2143 | </para> | |
2144 | <programlisting>lxc.apparmor.profile = generated</programlisting> | |
c464fd7e SG |
2145 | </listitem> |
2146 | </varlistentry> | |
2147 | <varlistentry> | |
2148 | <term> | |
69e38e00 | 2149 | <option>lxc.apparmor.allow_incomplete</option> |
c464fd7e SG |
2150 | </term> |
2151 | <listitem> | |
2152 | <para> | |
2153 | Apparmor profiles are pathname based. Therefore many file | |
2154 | restrictions require mount restrictions to be effective against | |
2155 | a determined attacker. However, these mount restrictions are not | |
2156 | yet implemented in the upstream kernel. Without the mount | |
2157 | restrictions, the apparmor profiles still protect against accidental | |
2158 | damager. | |
2159 | </para> | |
2160 | <para> | |
2161 | If this flag is 0 (default), then the container will not be | |
2162 | started if the kernel lacks the apparmor mount features, so that a | |
2163 | regression after a kernel upgrade will be detected. To start the | |
2164 | container under partial apparmor protection, set this flag to 1. | |
2165 | </para> | |
2166 | </listitem> | |
2167 | </varlistentry> | |
8dca2bd3 KY |
2168 | |
2169 | <varlistentry> | |
2170 | <term> | |
2171 | <option>lxc.apparmor.allow_nesting</option> | |
2172 | </term> | |
2173 | <listitem> | |
2174 | <para> | |
2175 | If set this to 1, causes the following changes. When | |
2176 | generated apparmor profiles are used, they will contain | |
2177 | the necessary changes to allow creating a nested | |
2178 | container. In addition to the usual mount points, | |
2179 | <filename>/dev/.lxc/proc</filename> | |
2180 | and <filename>/dev/.lxc/sys</filename> will contain | |
2181 | procfs and sysfs mount points without the lxcfs | |
2182 | overlays, which, if generated apparmor profiles are | |
2183 | being used, will not be read/writable directly. | |
2184 | </para> | |
2185 | </listitem> | |
2186 | </varlistentry> | |
2187 | ||
2188 | <varlistentry> | |
2189 | <term> | |
2190 | <option>lxc.apparmor.raw</option> | |
2191 | </term> | |
2192 | <listitem> | |
2193 | <para> | |
2194 | A list of raw AppArmor profile lines to append to the | |
2195 | profile. Only valid when using generated profiles. | |
2196 | </para> | |
2197 | </listitem> | |
2198 | </varlistentry> | |
2199 | ||
55fc19a1 SG |
2200 | </variablelist> |
2201 | </refsect2> | |
2202 | ||
2203 | <refsect2> | |
2204 | <title>SELinux context</title> | |
2205 | <para> | |
c464fd7e SG |
2206 | If lxc was compiled and installed with SELinux support, and the host |
2207 | system has SELinux enabled, then the SELinux context under which the | |
2208 | container should be run can be specified in the container | |
2209 | configuration. The default is <command>unconfined_t</command>, | |
2210 | which means that lxc will not attempt to change contexts. | |
2211 | See @DATADIR@/lxc/selinux/lxc.te for an example policy and more | |
2212 | information. | |
55fc19a1 SG |
2213 | </para> |
2214 | <variablelist> | |
c464fd7e SG |
2215 | <varlistentry> |
2216 | <term> | |
b84702ab | 2217 | <option>lxc.selinux.context</option> |
c464fd7e SG |
2218 | </term> |
2219 | <listitem> | |
2220 | <para> | |
2221 | Specify the SELinux context under which the container should | |
2222 | be run or <command>unconfined_t</command>. For example | |
2223 | </para> | |
b84702ab | 2224 | <programlisting>lxc.selinux.context = system_u:system_r:lxc_t:s0:c22</programlisting> |
c464fd7e SG |
2225 | </listitem> |
2226 | </varlistentry> | |
ad36e96a MB |
2227 | <varlistentry> |
2228 | <term> | |
2229 | <option>lxc.selinux.context.keyring</option> | |
2230 | </term> | |
2231 | <listitem> | |
2232 | <para> | |
2233 | Specify the SELinux context under which the container's keyring | |
2234 | should be created. By default this the same as lxc.selinux.context, or | |
48e3c95a | 2235 | the context lxc is executed under if lxc.selinux.context has not been set. |
ad36e96a MB |
2236 | </para> |
2237 | <programlisting>lxc.selinux.context.keyring = system_u:system_r:lxc_t:s0:c22</programlisting> | |
2238 | </listitem> | |
2239 | </varlistentry> | |
2240 | </variablelist> | |
2241 | </refsect2> | |
2242 | ||
2243 | <refsect2> | |
2244 | <title>Kernel Keyring</title> | |
2245 | <para> | |
2246 | The Linux Keyring facility is primarily a way for various | |
2247 | kernel components to retain or cache security data, authentication | |
2248 | keys, encryption keys, and other data in the kernel. By default lxc | |
2249 | will create a new session keyring for the started application. | |
2250 | </para> | |
2251 | <variablelist> | |
2252 | <varlistentry> | |
2253 | <term> | |
2254 | <option>lxc.keyring.session</option> | |
2255 | </term> | |
2256 | <listitem> | |
2257 | <para> | |
2258 | Disable the creation of new session keyring by lxc. The started | |
2259 | application will then inherit the current session keyring. | |
2260 | By default, or when passing the value 1, a new keyring will be created. | |
2261 | </para> | |
2262 | <programlisting>lxc.keyring.session = 0</programlisting> | |
2263 | </listitem> | |
2264 | </varlistentry> | |
55fc19a1 SG |
2265 | </variablelist> |
2266 | </refsect2> | |
2267 | ||
2268 | <refsect2> | |
2269 | <title>Seccomp configuration</title> | |
2270 | <para> | |
2271 | A container can be started with a reduced set of available | |
c464fd7e SG |
2272 | system calls by loading a seccomp profile at startup. The |
2273 | seccomp configuration file must begin with a version number | |
2274 | on the first line, a policy type on the second line, followed | |
2275 | by the configuration. | |
55fc19a1 | 2276 | </para> |
a7c27357 SH |
2277 | <para> |
2278 | Versions 1 and 2 are currently supported. In version 1, the | |
78522aa9 CB |
2279 | policy is a simple allowlist. The second line therefore must |
2280 | read "allowlist", with the rest of the file containing one (numeric) | |
2281 | syscall number per line. Each syscall number is allowlisted, | |
2282 | while every unlisted number is denylisted for use in the container | |
a7c27357 SH |
2283 | </para> |
2284 | ||
2285 | <para> | |
78522aa9 | 2286 | In version 2, the policy may be denylist or allowlist, |
a7c27357 SH |
2287 | supports per-rule and per-policy default actions, and supports |
2288 | per-architecture system call resolution from textual names. | |
2289 | </para> | |
2290 | <para> | |
78522aa9 | 2291 | An example denylist policy, in which all system calls are |
a7c27357 SH |
2292 | allowed except for mknod, which will simply do nothing and |
2293 | return 0 (success), looks like: | |
2294 | </para> | |
b9986e43 CB |
2295 | |
2296 | <programlisting> | |
2297 | 2 | |
78522aa9 | 2298 | denylist |
b9986e43 | 2299 | mknod errno 0 |
8a643759 | 2300 | ioctl notify |
b9986e43 CB |
2301 | </programlisting> |
2302 | ||
8a643759 CB |
2303 | <para> |
2304 | Specifying "errno" as action will cause LXC to register a seccomp filter | |
7dd6ead9 | 2305 | that will cause a specific errno to be returned to the caller. The errno |
8a643759 CB |
2306 | value can be specified after the "errno" action word. |
2307 | </para> | |
2308 | ||
2309 | <para> | |
2310 | Specifying "notify" as action will cause LXC to register a seccomp | |
2311 | listener and retrieve a listener file descriptor from the kernel. When a | |
2312 | syscall is made that is registered as "notify" the kernel will generate a | |
2313 | poll event and send a message over the file descriptor. The caller can | |
2314 | read this message, inspect the syscalls including its arguments. Based on | |
2315 | this information the caller is expected to send back a message informing | |
2316 | the kernel which action to take. Until that message is sent the kernel | |
2317 | will block the calling process. The format of the messages to read and | |
2318 | sent is documented in seccomp itself. | |
2319 | </para> | |
2320 | ||
55fc19a1 | 2321 | <variablelist> |
c464fd7e SG |
2322 | <varlistentry> |
2323 | <term> | |
0b427da0 | 2324 | <option>lxc.seccomp.profile</option> |
c464fd7e SG |
2325 | </term> |
2326 | <listitem> | |
2327 | <para> | |
2328 | Specify a file containing the seccomp configuration to | |
2329 | load before the container starts. | |
2330 | </para> | |
2331 | </listitem> | |
2332 | </varlistentry> | |
50d86993 CB |
2333 | <varlistentry> |
2334 | <term> | |
2335 | <option>lxc.seccomp.allow_nesting</option> | |
2336 | </term> | |
2337 | <listitem> | |
2338 | <para> | |
2339 | If this flag is set to 1, then seccomp filters will be stacked | |
2340 | regardless of whether a seccomp profile is already loaded. | |
2341 | This allows nested containers to load their own seccomp profile. | |
2342 | The default setting is 0. | |
2343 | </para> | |
2344 | </listitem> | |
2345 | </varlistentry> | |
8a643759 CB |
2346 | <varlistentry> |
2347 | <term> | |
2348 | <option>lxc.seccomp.notify.proxy</option> | |
2349 | </term> | |
2350 | <listitem> | |
2351 | <para> | |
2352 | Specify a unix socket to which LXC will connect and forward | |
214008ee | 2353 | seccomp events to. The path must be in the form |
8a643759 CB |
2354 | unix:/path/to/socket or unix:@socket. The former specifies a |
2355 | path-bound unix domain socket while the latter specifies an | |
2356 | abstract unix domain socket. | |
214008ee WB |
2357 | </para> |
2358 | </listitem> | |
2359 | </varlistentry> | |
2360 | <varlistentry> | |
2361 | <term> | |
2362 | <option>lxc.seccomp.notify.cookie</option> | |
2363 | </term> | |
2364 | <listitem> | |
2365 | <para> | |
2366 | An additional string sent along with proxied seccomp notification | |
2367 | requests. | |
2368 | </para> | |
8a643759 CB |
2369 | </listitem> |
2370 | </varlistentry> | |
55fc19a1 SG |
2371 | </variablelist> |
2372 | </refsect2> | |
2373 | ||
222ddc91 CB |
2374 | <refsect2> |
2375 | <title>PR_SET_NO_NEW_PRIVS</title> | |
2376 | <para> | |
2377 | With PR_SET_NO_NEW_PRIVS active execve() promises not to grant | |
2378 | privileges to do anything that could not have been done without | |
2379 | the execve() call (for example, rendering the set-user-ID and | |
2380 | set-group-ID mode bits, and file capabilities non-functional). | |
2381 | Once set, this bit cannot be unset. The setting of this bit is | |
2382 | inherited by children created by fork() and clone(), and preserved | |
2383 | across execve(). | |
2384 | Note that PR_SET_NO_NEW_PRIVS is applied after the container has | |
2385 | changed into its intended AppArmor profile or SElinux context. | |
2386 | </para> | |
2387 | <variablelist> | |
2388 | <varlistentry> | |
2389 | <term> | |
2390 | <option>lxc.no_new_privs</option> | |
2391 | </term> | |
2392 | <listitem> | |
2393 | <para> | |
2394 | Specify whether the PR_SET_NO_NEW_PRIVS flag should be set for the | |
2395 | container. Set to 1 to activate. | |
2396 | </para> | |
2397 | </listitem> | |
2398 | </varlistentry> | |
2399 | </variablelist> | |
2400 | </refsect2> | |
2401 | ||
55fc19a1 SG |
2402 | <refsect2> |
2403 | <title>UID mappings</title> | |
2404 | <para> | |
2405 | A container can be started in a private user namespace with | |
c464fd7e SG |
2406 | user and group id mappings. For instance, you can map userid |
2407 | 0 in the container to userid 200000 on the host. The root | |
2408 | user in the container will be privileged in the container, | |
2409 | but unprivileged on the host. Normally a system container | |
2410 | will want a range of ids, so you would map, for instance, | |
2411 | user and group ids 0 through 20,000 in the container to the | |
2412 | ids 200,000 through 220,000. | |
55fc19a1 SG |
2413 | </para> |
2414 | <variablelist> | |
c464fd7e SG |
2415 | <varlistentry> |
2416 | <term> | |
bdcbb6b3 | 2417 | <option>lxc.idmap</option> |
c464fd7e SG |
2418 | </term> |
2419 | <listitem> | |
2420 | <para> | |
2421 | Four values must be provided. First a character, either | |
2422 | 'u', or 'g', to specify whether user or group ids are | |
2423 | being mapped. Next is the first userid as seen in the | |
2424 | user namespace of the container. Next is the userid as | |
2425 | seen on the host. Finally, a range indicating the number | |
2426 | of consecutive ids to map. | |
2427 | </para> | |
2428 | </listitem> | |
2429 | </varlistentry> | |
55fc19a1 SG |
2430 | </variablelist> |
2431 | </refsect2> | |
2432 | ||
2433 | <refsect2> | |
2434 | <title>Container hooks</title> | |
2435 | <para> | |
2436 | Container hooks are programs or scripts which can be executed | |
c464fd7e | 2437 | at various times in a container's lifetime. |
55fc19a1 SG |
2438 | </para> |
2439 | <para> | |
44ae0fb6 CB |
2440 | When a container hook is executed, additional information is passed |
2441 | along. The <option>lxc.hook.version</option> argument can be used to | |
2442 | determine if the following arguments are passed as command line | |
2443 | arguments or through environment variables. The arguments are: | |
c464fd7e SG |
2444 | <itemizedlist> |
2445 | <listitem><para> Container name. </para></listitem> | |
2446 | <listitem><para> Section (always 'lxc'). </para></listitem> | |
2447 | <listitem><para> The hook type (i.e. 'clone' or 'pre-mount'). </para></listitem> | |
0a2b5ab1 | 2448 | <listitem><para> Additional arguments. In the |
a9145d62 CB |
2449 | case of the clone hook, any extra arguments passed will appear as |
2450 | further arguments to the hook. In the case of the stop hook, paths to | |
2451 | filedescriptors for each of the container's namespaces along with | |
2452 | their types are passed. </para></listitem> | |
c464fd7e SG |
2453 | </itemizedlist> |
2454 | The following environment variables are set: | |
2455 | <itemizedlist> | |
44ae0fb6 CB |
2456 | <listitem><para> LXC_CGNS_AWARE: indicator whether the container is |
2457 | cgroup namespace aware. </para></listitem> | |
2458 | <listitem><para> LXC_CONFIG_FILE: the path to the container | |
2459 | configuration file. </para></listitem> | |
2460 | <listitem><para> LXC_HOOK_TYPE: the hook type (e.g. 'clone', 'mount', | |
2461 | 'pre-mount'). Note that the existence of this environment variable is | |
2462 | conditional on the value of <option>lxc.hook.version</option>. If it | |
2463 | is set to 1 then LXC_HOOK_TYPE will be set. | |
2464 | </para></listitem> | |
2465 | <listitem><para> LXC_HOOK_SECTION: the section type (e.g. 'lxc', | |
2466 | 'net'). Note that the existence of this environment variable is | |
2467 | conditional on the value of <option>lxc.hook.version</option>. If it | |
2468 | is set to 1 then LXC_HOOK_SECTION will be set. | |
2469 | </para></listitem> | |
a2c09be0 CB |
2470 | <listitem><para> LXC_HOOK_VERSION: the version of the hooks. This |
2471 | value is identical to the value of the container's | |
2472 | <option>lxc.hook.version</option> config item. If it is set to 0 then | |
2473 | old-style hooks are used. If it is set to 1 then new-style hooks are | |
2474 | used. </para></listitem> | |
44ae0fb6 | 2475 | <listitem><para> LXC_LOG_LEVEL: the container's log level. </para></listitem> |
c464fd7e | 2476 | <listitem><para> LXC_NAME: is the container's name. </para></listitem> |
18b3b9c1 CB |
2477 | <listitem><para> LXC_[NAMESPACE IDENTIFIER]_NS: path under |
2478 | /proc/PID/fd/ to a file descriptor referring to the container's | |
2479 | namespace. For each preserved namespace type there will be a separate | |
2480 | environment variable. These environment variables will only be set if | |
2481 | <option>lxc.hook.version</option> is set to 1. </para></listitem> | |
c464fd7e | 2482 | <listitem><para> LXC_ROOTFS_MOUNT: the path to the mounted root filesystem. </para></listitem> |
44ae0fb6 CB |
2483 | <listitem><para> LXC_ROOTFS_PATH: this is the lxc.rootfs.path entry |
2484 | for the container. Note this is likely not where the mounted rootfs is | |
2485 | to be found, use LXC_ROOTFS_MOUNT for that. </para></listitem> | |
2486 | <listitem><para> LXC_SRC_NAME: in the case of the clone hook, this is | |
2487 | the original container's name. </para></listitem> | |
c464fd7e | 2488 | </itemizedlist> |
55fc19a1 SG |
2489 | </para> |
2490 | <para> | |
2491 | Standard output from the hooks is logged at debug level. | |
2492 | Standard error is not logged, but can be captured by the | |
2493 | hook redirecting its standard error to standard output. | |
2494 | </para> | |
2495 | <variablelist> | |
44ae0fb6 CB |
2496 | <varlistentry> |
2497 | <term> | |
2498 | <option>lxc.hook.version</option> | |
2499 | </term> | |
2500 | <listitem> | |
2501 | <para> | |
2502 | To pass the arguments in new style via environment variables set to | |
2503 | 1 otherwise set to 0 to pass them as arguments. | |
2504 | This setting affects all hooks arguments that were traditionally | |
2505 | passed as arguments to the script. Specifically, it affects the | |
2506 | container name, section (e.g. 'lxc', 'net') and hook type (e.g. | |
2507 | 'clone', 'mount', 'pre-mount') arguments. If new-style hooks are | |
2508 | used then the arguments will be available as environment variables. | |
2509 | The container name will be set in LXC_NAME. (This is set | |
2510 | independently of the value used for this config item.) The section | |
2511 | will be set in LXC_HOOK_SECTION and the hook type will be set in | |
2512 | LXC_HOOK_TYPE. | |
18b3b9c1 CB |
2513 | It also affects how the paths to file descriptors referring to the |
2514 | container's namespaces are passed. If set to 1 then for each | |
2515 | namespace a separate environment variable LXC_[NAMESPACE | |
2516 | IDENTIFIER]_NS will be set. If set to 0 then the paths will be | |
2517 | passed as arguments to the stop hook. | |
44ae0fb6 CB |
2518 | </para> |
2519 | </listitem> | |
2520 | </varlistentry> | |
2521 | </variablelist> | |
2522 | <variablelist> | |
c464fd7e SG |
2523 | <varlistentry> |
2524 | <term> | |
2525 | <option>lxc.hook.pre-start</option> | |
2526 | </term> | |
2527 | <listitem> | |
2528 | <para> | |
2529 | A hook to be run in the host's namespace before the | |
2530 | container ttys, consoles, or mounts are up. | |
2531 | </para> | |
2532 | </listitem> | |
2533 | </varlistentry> | |
55fc19a1 SG |
2534 | </variablelist> |
2535 | <variablelist> | |
c464fd7e SG |
2536 | <varlistentry> |
2537 | <term> | |
2538 | <option>lxc.hook.pre-mount</option> | |
2539 | </term> | |
2540 | <listitem> | |
2541 | <para> | |
2542 | A hook to be run in the container's fs namespace but before | |
2543 | the rootfs has been set up. This allows for manipulation | |
2544 | of the rootfs, i.e. to mount an encrypted filesystem. Mounts | |
2545 | done in this hook will not be reflected on the host (apart from | |
2546 | mounts propagation), so they will be automatically cleaned up | |
2547 | when the container shuts down. | |
2548 | </para> | |
2549 | </listitem> | |
2550 | </varlistentry> | |
55fc19a1 SG |
2551 | </variablelist> |
2552 | <variablelist> | |
c464fd7e SG |
2553 | <varlistentry> |
2554 | <term> | |
2555 | <option>lxc.hook.mount</option> | |
2556 | </term> | |
2557 | <listitem> | |
2558 | <para> | |
2559 | A hook to be run in the container's namespace after | |
2560 | mounting has been done, but before the pivot_root. | |
2561 | </para> | |
2562 | </listitem> | |
2563 | </varlistentry> | |
55fc19a1 SG |
2564 | </variablelist> |
2565 | <variablelist> | |
c464fd7e SG |
2566 | <varlistentry> |
2567 | <term> | |
2568 | <option>lxc.hook.autodev</option> | |
2569 | </term> | |
2570 | <listitem> | |
2571 | <para> | |
2572 | A hook to be run in the container's namespace after | |
2573 | mounting has been done and after any mount hooks have | |
2574 | run, but before the pivot_root, if | |
2575 | <option>lxc.autodev</option> == 1. | |
2576 | The purpose of this hook is to assist in populating the | |
2577 | /dev directory of the container when using the autodev | |
2578 | option for systemd based containers. The container's /dev | |
2579 | directory is relative to the | |
2580 | ${<option>LXC_ROOTFS_MOUNT</option>} environment | |
2581 | variable available when the hook is run. | |
2582 | </para> | |
2583 | </listitem> | |
2584 | </varlistentry> | |
55fc19a1 | 2585 | </variablelist> |
08dd2805 SH |
2586 | <variablelist> |
2587 | <varlistentry> | |
2588 | <term> | |
2589 | <option>lxc.hook.start-host</option> | |
2590 | </term> | |
2591 | <listitem> | |
2592 | <para> | |
2593 | A hook to be run in the host's namespace after the | |
2594 | container has been setup, and immediately before starting | |
2595 | the container init. | |
2596 | </para> | |
2597 | </listitem> | |
2598 | </varlistentry> | |
2599 | </variablelist> | |
55fc19a1 | 2600 | <variablelist> |
c464fd7e SG |
2601 | <varlistentry> |
2602 | <term> | |
2603 | <option>lxc.hook.start</option> | |
2604 | </term> | |
2605 | <listitem> | |
2606 | <para> | |
2607 | A hook to be run in the container's namespace immediately | |
2608 | before executing the container's init. This requires the | |
2609 | program to be available in the container. | |
2610 | </para> | |
2611 | </listitem> | |
2612 | </varlistentry> | |
55fc19a1 | 2613 | </variablelist> |
0a2b5ab1 WB |
2614 | <variablelist> |
2615 | <varlistentry> | |
2616 | <term> | |
2617 | <option>lxc.hook.stop</option> | |
2618 | </term> | |
2619 | <listitem> | |
2620 | <para> | |
2621 | A hook to be run in the host's namespace with references | |
2622 | to the container's namespaces after the container has been shut | |
2623 | down. For each namespace an extra argument is passed to the hook | |
2624 | containing the namespace's type and a filename that can be used to | |
2625 | obtain a file descriptor to the corresponding namespace, separated | |
2626 | by a colon. The type is the name as it would appear in the | |
2627 | <filename>/proc/PID/ns</filename> directory. | |
2628 | For instance for the mount namespace the argument usually looks | |
2629 | like <filename>mnt:/proc/PID/fd/12</filename>. | |
2630 | </para> | |
2631 | </listitem> | |
2632 | </varlistentry> | |
2633 | </variablelist> | |
55fc19a1 | 2634 | <variablelist> |
c464fd7e SG |
2635 | <varlistentry> |
2636 | <term> | |
2637 | <option>lxc.hook.post-stop</option> | |
2638 | </term> | |
2639 | <listitem> | |
2640 | <para> | |
2641 | A hook to be run in the host's namespace after the | |
2642 | container has been shut down. | |
2643 | </para> | |
2644 | </listitem> | |
2645 | </varlistentry> | |
55fc19a1 SG |
2646 | </variablelist> |
2647 | <variablelist> | |
c464fd7e SG |
2648 | <varlistentry> |
2649 | <term> | |
2650 | <option>lxc.hook.clone</option> | |
2651 | </term> | |
2652 | <listitem> | |
2653 | <para> | |
2654 | A hook to be run when the container is cloned to a new one. | |
2655 | See <citerefentry><refentrytitle><command>lxc-clone</command></refentrytitle> | |
2656 | <manvolnum>1</manvolnum></citerefentry> for more information. | |
2657 | </para> | |
2658 | </listitem> | |
2659 | </varlistentry> | |
55fc19a1 | 2660 | </variablelist> |
37cf711b SY |
2661 | <variablelist> |
2662 | <varlistentry> | |
2663 | <term> | |
2664 | <option>lxc.hook.destroy</option> | |
2665 | </term> | |
2666 | <listitem> | |
2667 | <para> | |
2668 | A hook to be run when the container is destroyed. | |
2669 | </para> | |
2670 | </listitem> | |
2671 | </varlistentry> | |
2672 | </variablelist> | |
55fc19a1 SG |
2673 | </refsect2> |
2674 | ||
2675 | <refsect2> | |
2676 | <title>Container hooks Environment Variables</title> | |
2677 | <para> | |
2678 | A number of environment variables are made available to the startup | |
2679 | hooks to provide configuration information and assist in the | |
2680 | functioning of the hooks. Not all variables are valid in all | |
2681 | contexts. In particular, all paths are relative to the host system | |
2682 | and, as such, not valid during the <option>lxc.hook.start</option> hook. | |
2683 | </para> | |
2684 | <variablelist> | |
c464fd7e SG |
2685 | <varlistentry> |
2686 | <term> | |
2687 | <option>LXC_NAME</option> | |
2688 | </term> | |
2689 | <listitem> | |
2690 | <para> | |
2691 | The LXC name of the container. Useful for logging messages | |
2692 | in common log environments. [<option>-n</option>] | |
2693 | </para> | |
2694 | </listitem> | |
2695 | </varlistentry> | |
55fc19a1 SG |
2696 | </variablelist> |
2697 | <variablelist> | |
c464fd7e SG |
2698 | <varlistentry> |
2699 | <term> | |
2700 | <option>LXC_CONFIG_FILE</option> | |
2701 | </term> | |
2702 | <listitem> | |
2703 | <para> | |
2704 | Host relative path to the container configuration file. This | |
2705 | gives the container to reference the original, top level, | |
2706 | configuration file for the container in order to locate any | |
2707 | additional configuration information not otherwise made | |
2708 | available. [<option>-f</option>] | |
2709 | </para> | |
2710 | </listitem> | |
2711 | </varlistentry> | |
55fc19a1 SG |
2712 | </variablelist> |
2713 | <variablelist> | |
c464fd7e SG |
2714 | <varlistentry> |
2715 | <term> | |
2716 | <option>LXC_CONSOLE</option> | |
2717 | </term> | |
2718 | <listitem> | |
2719 | <para> | |
2720 | The path to the console output of the container if not NULL. | |
3aed4934 | 2721 | [<option>-c</option>] [<option>lxc.console.path</option>] |
c464fd7e SG |
2722 | </para> |
2723 | </listitem> | |
2724 | </varlistentry> | |
55fc19a1 SG |
2725 | </variablelist> |
2726 | <variablelist> | |
c464fd7e SG |
2727 | <varlistentry> |
2728 | <term> | |
2729 | <option>LXC_CONSOLE_LOGPATH</option> | |
2730 | </term> | |
2731 | <listitem> | |
2732 | <para> | |
2733 | The path to the console log output of the container if not NULL. | |
2734 | [<option>-L</option>] | |
2735 | </para> | |
2736 | </listitem> | |
2737 | </varlistentry> | |
55fc19a1 SG |
2738 | </variablelist> |
2739 | <variablelist> | |
c464fd7e SG |
2740 | <varlistentry> |
2741 | <term> | |
2742 | <option>LXC_ROOTFS_MOUNT</option> | |
2743 | </term> | |
2744 | <listitem> | |
2745 | <para> | |
2746 | The mount location to which the container is initially bound. | |
2747 | This will be the host relative path to the container rootfs | |
2748 | for the container instance being started and is where changes | |
2749 | should be made for that instance. | |
2750 | [<option>lxc.rootfs.mount</option>] | |
2751 | </para> | |
2752 | </listitem> | |
2753 | </varlistentry> | |
55fc19a1 SG |
2754 | </variablelist> |
2755 | <variablelist> | |
c464fd7e SG |
2756 | <varlistentry> |
2757 | <term> | |
2758 | <option>LXC_ROOTFS_PATH</option> | |
2759 | </term> | |
2760 | <listitem> | |
2761 | <para> | |
2762 | The host relative path to the container root which has been | |
2763 | mounted to the rootfs.mount location. | |
7a96a068 | 2764 | [<option>lxc.rootfs.path</option>] |
c464fd7e SG |
2765 | </para> |
2766 | </listitem> | |
2767 | </varlistentry> | |
55fc19a1 | 2768 | </variablelist> |
07945418 KY |
2769 | <variablelist> |
2770 | <varlistentry> | |
2771 | <term> | |
2772 | <option>LXC_SRC_NAME</option> | |
2773 | </term> | |
2774 | <listitem> | |
2775 | <para> | |
2776 | Only for the clone hook. Is set to the original container name. | |
2777 | </para> | |
2778 | </listitem> | |
2779 | </varlistentry> | |
2780 | </variablelist> | |
c154af98 SG |
2781 | <variablelist> |
2782 | <varlistentry> | |
2783 | <term> | |
2784 | <option>LXC_TARGET</option> | |
2785 | </term> | |
2786 | <listitem> | |
2787 | <para> | |
2788 | Only for the stop hook. Is set to "stop" for a container | |
2789 | shutdown or "reboot" for a container reboot. | |
2790 | </para> | |
2791 | </listitem> | |
2792 | </varlistentry> | |
c4cafa08 SH |
2793 | </variablelist> |
2794 | <variablelist> | |
2795 | <varlistentry> | |
2796 | <term> | |
2797 | <option>LXC_CGNS_AWARE</option> | |
2798 | </term> | |
2799 | <listitem> | |
2800 | <para> | |
2801 | If unset, then this version of lxc is not aware of cgroup | |
2802 | namespaces. If set, it will be set to 1, and lxc is aware | |
2803 | of cgroup namespaces. Note this does not guarantee that | |
2804 | cgroup namespaces are enabled in the kernel. This is used | |
2805 | by the lxcfs mount hook. | |
2806 | </para> | |
2807 | </listitem> | |
2808 | </varlistentry> | |
c154af98 | 2809 | </variablelist> |
55fc19a1 SG |
2810 | </refsect2> |
2811 | <refsect2> | |
2812 | <title>Logging</title> | |
2813 | <para> | |
2814 | Logging can be configured on a per-container basis. By default, | |
2815 | depending upon how the lxc package was compiled, container startup | |
2816 | is logged only at the ERROR level, and logged to a file named after | |
2817 | the container (with '.log' appended) either under the container path, | |
2818 | or under @LOGPATH@. | |
2819 | </para> | |
2820 | <para> | |
2821 | Both the default log level and the log file can be specified in the | |
2822 | container configuration file, overriding the default behavior. Note | |
2823 | that the configuration file entries can in turn be overridden by the | |
2824 | command line options to <command>lxc-start</command>. | |
2825 | </para> | |
2826 | <variablelist> | |
c464fd7e SG |
2827 | <varlistentry> |
2828 | <term> | |
46cc906d | 2829 | <option>lxc.log.level</option> |
c464fd7e SG |
2830 | </term> |
2831 | <listitem> | |
2832 | <para> | |
2833 | The level at which to log. The log level is an integer in | |
2834 | the range of 0..8 inclusive, where a lower number means more | |
2835 | verbose debugging. In particular 0 = trace, 1 = debug, 2 = | |
2836 | info, 3 = notice, 4 = warn, 5 = error, 6 = critical, 7 = | |
2837 | alert, and 8 = fatal. If unspecified, the level defaults | |
2838 | to 5 (error), so that only errors and above are logged. | |
2839 | </para> | |
2840 | <para> | |
2841 | Note that when a script (such as either a hook script or a | |
2842 | network interface up or down script) is called, the script's | |
2843 | standard output is logged at level 1, debug. | |
2844 | </para> | |
2845 | </listitem> | |
2846 | </varlistentry> | |
2847 | <varlistentry> | |
2848 | <term> | |
5757588f | 2849 | <option>lxc.log.file</option> |
c464fd7e SG |
2850 | </term> |
2851 | <listitem> | |
2852 | <para> | |
2853 | The file to which logging info should be written. | |
2854 | </para> | |
2855 | </listitem> | |
2856 | </varlistentry> | |
204dfdf2 BD |
2857 | <varlistentry> |
2858 | <term> | |
46cc906d | 2859 | <option>lxc.log.syslog</option> |
204dfdf2 BD |
2860 | </term> |
2861 | <listitem> | |
2862 | <para> | |
2863 | Send logging info to syslog. It respects the log level defined in | |
46cc906d | 2864 | <command>lxc.log.level</command>. The argument should be the syslog |
204dfdf2 | 2865 | facility to use, valid ones are: daemon, local0, local1, local2, |
917420dd | 2866 | local3, local4, local5, local5, local6, local7. |
204dfdf2 BD |
2867 | </para> |
2868 | </listitem> | |
2869 | </varlistentry> | |
55fc19a1 SG |
2870 | </variablelist> |
2871 | </refsect2> | |
2872 | ||
2873 | <refsect2> | |
2874 | <title>Autostart</title> | |
2875 | <para> | |
2876 | The autostart options support marking which containers should be | |
2877 | auto-started and in what order. These options may be used by LXC tools | |
2878 | directly or by external tooling provided by the distributions. | |
2879 | </para> | |
2880 | ||
2881 | <variablelist> | |
2882 | <varlistentry> | |
2883 | <term> | |
2884 | <option>lxc.start.auto</option> | |
2885 | </term> | |
2886 | <listitem> | |
2887 | <para> | |
2888 | Whether the container should be auto-started. | |
2889 | Valid values are 0 (off) and 1 (on). | |
2890 | </para> | |
2891 | </listitem> | |
2892 | </varlistentry> | |
2893 | <varlistentry> | |
2894 | <term> | |
2895 | <option>lxc.start.delay</option> | |
2896 | </term> | |
2897 | <listitem> | |
2898 | <para> | |
2899 | How long to wait (in seconds) after the container is | |
2900 | started before starting the next one. | |
2901 | </para> | |
2902 | </listitem> | |
2903 | </varlistentry> | |
2904 | <varlistentry> | |
2905 | <term> | |
2906 | <option>lxc.start.order</option> | |
2907 | </term> | |
2908 | <listitem> | |
2909 | <para> | |
2910 | An integer used to sort the containers when auto-starting | |
0684250f LJ |
2911 | a series of containers at once. A lower value means an |
2912 | earlier start. | |
55fc19a1 SG |
2913 | </para> |
2914 | </listitem> | |
2915 | </varlistentry> | |
a8dfe4e0 WB |
2916 | <varlistentry> |
2917 | <term> | |
2918 | <option>lxc.monitor.unshare</option> | |
2919 | </term> | |
2920 | <listitem> | |
2921 | <para> | |
2922 | If not zero the mount namespace will be unshared from the host | |
2923 | before initializing the container (before running any pre-start | |
6039eaa2 WB |
2924 | hooks). This requires the CAP_SYS_ADMIN capability at startup. |
2925 | Default is 0. | |
a8dfe4e0 WB |
2926 | </para> |
2927 | </listitem> | |
2928 | </varlistentry> | |
258f8051 CB |
2929 | <varlistentry> |
2930 | <term> | |
2931 | <option>lxc.monitor.signal.pdeath</option> | |
2932 | </term> | |
2933 | <listitem> | |
2934 | <para> | |
2935 | Set the signal to be sent to the container's init when the lxc | |
2936 | monitor exits. By default it is set to SIGKILL which will cause | |
2937 | all container processes to be killed when the lxc monitor process | |
2938 | dies. | |
2939 | To ensure that containers stay alive even if lxc monitor dies set | |
2940 | this to 0. | |
2941 | </para> | |
2942 | </listitem> | |
2943 | </varlistentry> | |
55fc19a1 SG |
2944 | <varlistentry> |
2945 | <term> | |
2946 | <option>lxc.group</option> | |
2947 | </term> | |
2948 | <listitem> | |
2949 | <para> | |
2950 | A multi-value key (can be used multiple times) to put the | |
2951 | container in a container group. Those groups can then be | |
2952 | used (amongst other things) to start a series of related | |
2953 | containers. | |
2954 | </para> | |
2955 | </listitem> | |
2956 | </varlistentry> | |
2957 | </variablelist> | |
2958 | </refsect2> | |
015f0dd7 MW |
2959 | |
2960 | <refsect2> | |
2961 | <title>Autostart and System Boot</title> | |
2962 | <para> | |
2963 | Each container can be part of any number of groups or no group at all. | |
2964 | Two groups are special. One is the NULL group, i.e. the container does | |
2965 | not belong to any group. The other group is the "onboot" group. | |
2966 | </para> | |
2967 | ||
2968 | <para> | |
2969 | When the system boots with the LXC service enabled, it will first | |
2970 | attempt to boot any containers with lxc.start.auto == 1 that is a member | |
2971 | of the "onboot" group. The startup will be in order of lxc.start.order. | |
2972 | If an lxc.start.delay has been specified, that delay will be honored | |
2973 | before attempting to start the next container to give the current | |
2974 | container time to begin initialization and reduce overloading the host | |
2975 | system. After starting the members of the "onboot" group, the LXC system | |
2976 | will proceed to boot containers with lxc.start.auto == 1 which are not | |
2977 | members of any group (the NULL group) and proceed as with the onboot | |
2978 | group. | |
2979 | </para> | |
2980 | ||
2981 | </refsect2> | |
7c661726 MP |
2982 | |
2983 | <refsect2> | |
2984 | <title>Container Environment</title> | |
2985 | <para> | |
c464fd7e SG |
2986 | If you want to pass environment variables into the container (that |
2987 | is, environment variables which will be available to init and all of | |
2988 | its descendents), you can use <command>lxc.environment</command> | |
2989 | parameters to do so. Be careful that you do not pass in anything | |
2990 | sensitive; any process in the container which doesn't have its | |
2991 | environment scrubbed will have these variables available to it, and | |
2992 | environment variables are always available via | |
2993 | <command>/proc/PID/environ</command>. | |
7c661726 MP |
2994 | </para> |
2995 | ||
2996 | <para> | |
2997 | This configuration parameter can be specified multiple times; once | |
2998 | for each environment variable you wish to configure. | |
2999 | </para> | |
3000 | ||
3001 | <variablelist> | |
c464fd7e SG |
3002 | <varlistentry> |
3003 | <term> | |
3004 | <option>lxc.environment</option> | |
3005 | </term> | |
3006 | <listitem> | |
3007 | <para> | |
3008 | Specify an environment variable to pass into the container. | |
3009 | Example: | |
3010 | </para> | |
3011 | <programlisting> | |
3012 | lxc.environment = APP_ENV=production | |
3013 | lxc.environment = SYSLOG_SERVER=192.0.2.42 | |
3014 | </programlisting> | |
5eab47bc CB |
3015 | <para> |
3016 | It is possible to inherit host environment variables by setting the | |
3017 | name of the variable without a "=" sign. For example: | |
3018 | </para> | |
3019 | <programlisting> | |
3020 | lxc.environment = PATH | |
3021 | </programlisting> | |
c464fd7e SG |
3022 | </listitem> |
3023 | </varlistentry> | |
7c661726 MP |
3024 | </variablelist> |
3025 | </refsect2> | |
3026 | ||
55fc19a1 SG |
3027 | </refsect1> |
3028 | ||
3029 | <refsect1> | |
3030 | <title>Examples</title> | |
3031 | <para> | |
c464fd7e SG |
3032 | In addition to the few examples given below, you will find |
3033 | some other examples of configuration file in @DOCDIR@/examples | |
55fc19a1 SG |
3034 | </para> |
3035 | <refsect2> | |
3036 | <title>Network</title> | |
3037 | <para>This configuration sets up a container to use a veth pair | |
c464fd7e SG |
3038 | device with one side plugged to a bridge br0 (which has been |
3039 | configured before on the system by the administrator). The | |
3040 | virtual network device visible in the container is renamed to | |
3041 | eth0.</para> | |
55fc19a1 | 3042 | <programlisting> |
b67771bc | 3043 | lxc.uts.name = myhostname |
7fa3f2e9 | 3044 | lxc.net.0.type = veth |
3045 | lxc.net.0.flags = up | |
3046 | lxc.net.0.link = br0 | |
3047 | lxc.net.0.name = eth0 | |
3048 | lxc.net.0.hwaddr = 4a:49:43:49:79:bf | |
9ff60df2 | 3049 | lxc.net.0.ipv4.address = 10.2.3.5/24 10.2.3.255 |
2e44ae28 | 3050 | lxc.net.0.ipv6.address = 2003:db8:1:0:214:1234:fe0b:3597 |
55fc19a1 SG |
3051 | </programlisting> |
3052 | </refsect2> | |
3053 | ||
3054 | <refsect2> | |
3055 | <title>UID/GID mapping</title> | |
3056 | <para>This configuration will map both user and group ids in the | |
3057 | range 0-9999 in the container to the ids 100000-109999 on the host. | |
3058 | </para> | |
3059 | <programlisting> | |
bdcbb6b3 CB |
3060 | lxc.idmap = u 0 100000 10000 |
3061 | lxc.idmap = g 0 100000 10000 | |
55fc19a1 SG |
3062 | </programlisting> |
3063 | </refsect2> | |
3064 | ||
3065 | <refsect2> | |
3066 | <title>Control group</title> | |
3067 | <para>This configuration will setup several control groups for | |
3068 | the application, cpuset.cpus restricts usage of the defined cpu, | |
3069 | cpus.share prioritize the control group, devices.allow makes | |
3070 | usable the specified devices.</para> | |
3071 | <programlisting> | |
c464fd7e SG |
3072 | lxc.cgroup.cpuset.cpus = 0,1 |
3073 | lxc.cgroup.cpu.shares = 1234 | |
3074 | lxc.cgroup.devices.deny = a | |
3075 | lxc.cgroup.devices.allow = c 1:3 rw | |
3076 | lxc.cgroup.devices.allow = b 8:0 rw | |
55fc19a1 SG |
3077 | </programlisting> |
3078 | </refsect2> | |
3079 | ||
3080 | <refsect2> | |
3081 | <title>Complex configuration</title> | |
3082 | <para>This example show a complex configuration making a complex | |
3083 | network stack, using the control groups, setting a new hostname, | |
3084 | mounting some locations and a changing root file system.</para> | |
3085 | <programlisting> | |
b67771bc | 3086 | lxc.uts.name = complex |
7fa3f2e9 | 3087 | lxc.net.0.type = veth |
3088 | lxc.net.0.flags = up | |
3089 | lxc.net.0.link = br0 | |
3090 | lxc.net.0.hwaddr = 4a:49:43:49:79:bf | |
9ff60df2 | 3091 | lxc.net.0.ipv4.address = 10.2.3.5/24 10.2.3.255 |
2e44ae28 CB |
3092 | lxc.net.0.ipv6.address = 2003:db8:1:0:214:1234:fe0b:3597 |
3093 | lxc.net.0.ipv6.address = 2003:db8:1:0:214:5432:feab:3588 | |
7fa3f2e9 | 3094 | lxc.net.1.type = macvlan |
3095 | lxc.net.1.flags = up | |
3096 | lxc.net.1.link = eth0 | |
3097 | lxc.net.1.hwaddr = 4a:49:43:49:79:bd | |
9ff60df2 CB |
3098 | lxc.net.1.ipv4.address = 10.2.3.4/24 |
3099 | lxc.net.1.ipv4.address = 192.168.10.125/24 | |
2e44ae28 | 3100 | lxc.net.1.ipv6.address = 2003:db8:1:0:214:1234:fe0b:3596 |
7fa3f2e9 | 3101 | lxc.net.2.type = phys |
3102 | lxc.net.2.flags = up | |
3103 | lxc.net.2.link = dummy0 | |
3104 | lxc.net.2.hwaddr = 4a:49:43:49:79:ff | |
9ff60df2 | 3105 | lxc.net.2.ipv4.address = 10.2.3.6/24 |
2e44ae28 | 3106 | lxc.net.2.ipv6.address = 2003:db8:1:0:214:1234:fe0b:3297 |
c464fd7e SG |
3107 | lxc.cgroup.cpuset.cpus = 0,1 |
3108 | lxc.cgroup.cpu.shares = 1234 | |
3109 | lxc.cgroup.devices.deny = a | |
3110 | lxc.cgroup.devices.allow = c 1:3 rw | |
3111 | lxc.cgroup.devices.allow = b 8:0 rw | |
47148e96 | 3112 | lxc.mount.fstab = /etc/fstab.complex |
c464fd7e | 3113 | lxc.mount.entry = /lib /root/myrootfs/lib none ro,bind 0 0 |
7a96a068 | 3114 | lxc.rootfs.path = dir:/mnt/rootfs.complex |
1852be90 | 3115 | lxc.rootfs.options = idmap=container |
c464fd7e SG |
3116 | lxc.cap.drop = sys_module mknod setuid net_raw |
3117 | lxc.cap.drop = mac_override | |
55fc19a1 SG |
3118 | </programlisting> |
3119 | </refsect2> | |
3120 | ||
3121 | </refsect1> | |
3122 | ||
3123 | <refsect1> | |
3124 | <title>See Also</title> | |
3125 | <simpara> | |
3126 | <citerefentry> | |
c464fd7e SG |
3127 | <refentrytitle><command>chroot</command></refentrytitle> |
3128 | <manvolnum>1</manvolnum> | |
55fc19a1 SG |
3129 | </citerefentry>, |
3130 | ||
3131 | <citerefentry> | |
c464fd7e SG |
3132 | <refentrytitle><command>pivot_root</command></refentrytitle> |
3133 | <manvolnum>8</manvolnum> | |
55fc19a1 SG |
3134 | </citerefentry>, |
3135 | ||
3136 | <citerefentry> | |
c464fd7e SG |
3137 | <refentrytitle><filename>fstab</filename></refentrytitle> |
3138 | <manvolnum>5</manvolnum> | |
55fc19a1 SG |
3139 | </citerefentry>, |
3140 | ||
3141 | <citerefentry> | |
c464fd7e SG |
3142 | <refentrytitle><filename>capabilities</filename></refentrytitle> |
3143 | <manvolnum>7</manvolnum> | |
55fc19a1 SG |
3144 | </citerefentry> |
3145 | </simpara> | |
3146 | </refsect1> | |
3147 | ||
3148 | &seealso; | |
3149 | ||
3150 | <refsect1> | |
3151 | <title>Author</title> | |
3152 | <para>Daniel Lezcano <email>daniel.lezcano@free.fr</email></para> | |
3153 | </refsect1> | |
3154 | ||
3155 | </refentry> | |
3156 | ||
3157 | <!-- Keep this comment at the end of the file | |
3158 | Local variables: | |
3159 | mode: sgml | |
3160 | sgml-omittag:t | |
3161 | sgml-shorttag:t | |
3162 | sgml-minimize-attributes:nil | |
3163 | sgml-always-quote-attributes:t | |
3164 | sgml-indent-step:2 | |
3165 | sgml-indent-data:t | |
3166 | sgml-parent-document:nil | |
3167 | sgml-default-dtd-file:nil | |
3168 | sgml-exposed-tags:nil | |
3169 | sgml-local-catalogs:nil | |
3170 | sgml-local-ecat-files:nil | |
3171 | End: | |
3172 | --> |