Debian Codegraph @

doc/lxc.container.conf.sgml.in

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