1lxc.container.conf(5) lxc.container.conf(5)
2
6 lxc.container.conf - LXC container configuration file
7
9 LXC is the well-known and heavily tested low-level Linux container run‐
10 time. It is in active development since 2008 and has proven itself in
11 critical production environments world-wide. Some of its core contribu‐
12 tors are the same people that helped to implement various well-known
13 containerization features inside the Linux kernel.
14 LXC's main focus is system containers. That is, containers which offer
16 an environment as close as possible as the one you'd get from a VM but
17 without the overhead that comes with running a separate kernel and sim‐
18 ulating all the hardware.
19 This is achieved through a combination of kernel security features such
21 as namespaces, mandatory access control and control groups.
22 LXC has support for unprivileged containers. Unprivileged containers
24 are containers that are run without any privilege. This requires sup‐
25 port for user namespaces in the kernel that the container is run on.
26 LXC was the first runtime to support unprivileged containers after user
27 namespaces were merged into the mainline kernel.
28 In essence, user namespaces isolate given sets of UIDs and GIDs. This
30 is achieved by establishing a mapping between a range of UIDs and GIDs
31 on the host to a different (unprivileged) range of UIDs and GIDs in the
32 container. The kernel will translate this mapping in such a way that
33 inside the container all UIDs and GIDs appear as you would expect from
34 the host whereas on the host these UIDs and GIDs are in fact unprivi‐
35 leged. For example, a process running as UID and GID 0 inside the con‐
36 tainer might appear as UID and GID 100000 on the host. The implementa‐
37 tion and working details can be gathered from the corresponding user
38 namespace man page. UID and GID mappings can be defined with the
39 lxc.idmap key.
40 Linux containers are defined with a simple configuration file. Each
42 option in the configuration file has the form key = value fitting in
43 one line. The "#" character means the line is a comment. List options,
44 like capabilities and cgroups options, can be used with no value to
45 clear any previously defined values of that option.
46 LXC namespaces configuration keys use single dots. This means complex
48 configuration keys such as lxc.net.0 expose various subkeys such as
49 lxc.net.0.type, lxc.net.0.link, lxc.net.0.ipv6.address, and others for
50 even more fine-grained configuration.
51 CONFIGURATION
53 In order to ease administration of multiple related containers, it is
54 possible to have a container configuration file cause another file to
55 be loaded. For instance, network configuration can be defined in one
56 common file which is included by multiple containers. Then, if the con‐
57 tainers are moved to another host, only one file may need to be
58 updated.
59 lxc.include
61 Specify the file to be included. The included file must be in
62 the same valid lxc configuration file format.
63 ARCHITECTURE
65 Allows one to set the architecture for the container. For example, set
66 a 32bits architecture for a container running 32bits binaries on a
67 64bits host. This fixes the container scripts which rely on the archi‐
68 tecture to do some work like downloading the packages.
69 lxc.arch
71 Specify the architecture for the container.
72 Some valid options are x86, i686, x86_64, amd64
74 HOSTNAME
76 The utsname section defines the hostname to be set for the container.
77 That means the container can set its own hostname without changing the
78 one from the system. That makes the hostname private for the container.
79 lxc.uts.name
81 specify the hostname for the container
82 HALT SIGNAL
84 Allows one to specify signal name or number sent to the container's
85 init process to cleanly shutdown the container. Different init systems
86 could use different signals to perform clean shutdown sequence. This
87 option allows the signal to be specified in kill(1) fashion, e.g. SIG‐
88 PWR, SIGRTMIN+14, SIGRTMAX-10 or plain number. The default signal is
89 SIGPWR.
90 lxc.signal.halt
92 specify the signal used to halt the container
93 REBOOT SIGNAL
95 Allows one to specify signal name or number to reboot the container.
96 This option allows signal to be specified in kill(1) fashion, e.g.
97 SIGTERM, SIGRTMIN+14, SIGRTMAX-10 or plain number. The default signal
98 is SIGINT.
99 lxc.signal.reboot
101 specify the signal used to reboot the container
102 STOP SIGNAL
104 Allows one to specify signal name or number to forcibly shutdown the
105 container. This option allows signal to be specified in kill(1) fash‐
106 ion, e.g. SIGKILL, SIGRTMIN+14, SIGRTMAX-10 or plain number. The
107 default signal is SIGKILL.
108 lxc.signal.stop
110 specify the signal used to stop the container
111 INIT COMMAND
113 Sets the command to use as the init system for the containers.
114 lxc.execute.cmd
116 Absolute path from container rootfs to the binary to run by
117 default. This mostly makes sense for lxc-execute.
118 lxc.init.cmd
120 Absolute path from container rootfs to the binary to use as
121 init. This mostly makes sense for lxc-start. Default is
122 /sbin/init.
123 INIT WORKING DIRECTORY
125 Sets the absolute path inside the container as the working directory
126 for the containers. LXC will switch to this directory before executing
127 init.
128 lxc.init.cwd
130 Absolute path inside the container to use as the working direc‐
131 tory.
132 INIT ID
134 Sets the UID/GID to use for the init system, and subsequent commands.
135 Note that using a non-root UID when booting a system container will
136 likely not work due to missing privileges. Setting the UID/GID is
137 mostly useful when running application containers. Defaults to:
138 UID(0), GID(0)
139 lxc.init.uid
141 UID to use for init.
142 lxc.init.gid
144 GID to use for init.
145 PROC
147 Configure proc filesystem for the container.
148 lxc.proc.[proc file name]
150 Specify the proc file name to be set. The file names available
151 are those listed under /proc/PID/. Example:
152 lxc.proc.oom_score_adj = 10
154 EPHEMERAL
157 Allows one to specify whether a container will be destroyed on shut‐
158 down.
159 lxc.ephemeral
161 The only allowed values are 0 and 1. Set this to 1 to destroy a
162 container on shutdown.
163 NETWORK
165 The network section defines how the network is virtualized in the con‐
166 tainer. The network virtualization acts at layer two. In order to use
167 the network virtualization, parameters must be specified to define the
168 network interfaces of the container. Several virtual interfaces can be
169 assigned and used in a container even if the system has only one physi‐
170 cal network interface.
171 lxc.net
173 may be used without a value to clear all previous network
174 options.
175 lxc.net.[i].type
177 specify what kind of network virtualization to be used for the
178 container. Multiple networks can be specified by using an addi‐
179 tional index i after all lxc.net.* keys. For example,
180 lxc.net.0.type = veth and lxc.net.1.type = veth specify two dif‐
181 ferent networks of the same type. All keys sharing the same
182 index i will be treated as belonging to the same network. For
183 example, lxc.net.0.link = br0 will belong to lxc.net.0.type.
184 Currently, the different virtualization types can be:
185 none: will cause the container to share the host's network
187 namespace. This means the host network devices are usable in the
188 container. It also means that if both the container and host
189 have upstart as init, 'halt' in a container (for instance) will
190 shut down the host. Note that unprivileged containers do not
191 work with this setting due to an inability to mount sysfs. An
192 unsafe workaround would be to bind mount the host's sysfs.
193 empty: will create only the loopback interface.
195 veth: a virtual ethernet pair device is created with one side
197 assigned to the container and the other side on the host.
198 lxc.net.[i].veth.mode specifies the mode the veth parent will
199 use on the host. The accepted modes are bridge and router. The
200 mode defaults to bridge if not specified. In bridge mode the
201 host side is attached to a bridge specified by the
202 lxc.net.[i].link option. If the bridge link is not specified,
203 then the veth pair device will be created but not attached to
204 any bridge. Otherwise, the bridge has to be created on the sys‐
205 tem before starting the container. lxc won't handle any config‐
206 uration outside of the container. In router mode static routes
207 are created on the host for the container's IP addresses point‐
208 ing to the host side veth interface. Additionally Proxy ARP and
209 Proxy NDP entries are added on the host side veth interface for
210 the gateway IPs defined in the container to allow the container
211 to reach the host. By default, lxc chooses a name for the net‐
212 work device belonging to the outside of the container, but if
213 you wish to handle this name yourselves, you can tell lxc to set
214 a specific name with the lxc.net.[i].veth.pair option (except
215 for unprivileged containers where this option is ignored for
216 security reasons). Static routes can be added on the host
217 pointing to the container using the lxc.net.[i].veth.ipv4.route
218 and lxc.net.[i].veth.ipv6.route options. Several lines specify
219 several routes. The route is in format x.y.z.t/m, eg.
220 192.168.1.0/24.
221 vlan: a vlan interface is linked with the interface specified by
223 the lxc.net.[i].link and assigned to the container. The vlan
224 identifier is specified with the option lxc.net.[i].vlan.id.
225 macvlan: a macvlan interface is linked with the interface speci‐
227 fied by the lxc.net.[i].link and assigned to the container.
228 lxc.net.[i].macvlan.mode specifies the mode the macvlan will use
229 to communicate between different macvlan on the same upper
230 device. The accepted modes are private, vepa, bridge and
231 passthru. In private mode, the device never communicates with
232 any other device on the same upper_dev (default). In vepa mode,
233 the new Virtual Ethernet Port Aggregator (VEPA) mode, it assumes
234 that the adjacent bridge returns all frames where both source
235 and destination are local to the macvlan port, i.e. the bridge
236 is set up as a reflective relay. Broadcast frames coming in from
237 the upper_dev get flooded to all macvlan interfaces in VEPA
238 mode, local frames are not delivered locally. In bridge mode, it
239 provides the behavior of a simple bridge between different
240 macvlan interfaces on the same port. Frames from one interface
241 to another one get delivered directly and are not sent out
242 externally. Broadcast frames get flooded to all other bridge
243 ports and to the external interface, but when they come back
244 from a reflective relay, we don't deliver them again. Since we
245 know all the MAC addresses, the macvlan bridge mode does not
246 require learning or STP like the bridge module does. In passthru
247 mode, all frames received by the physical interface are for‐
248 warded to the macvlan interface. Only one macvlan interface in
249 passthru mode is possible for one physical interface.
250 ipvlan: an ipvlan interface is linked with the interface speci‐
252 fied by the lxc.net.[i].link and assigned to the container.
253 lxc.net.[i].ipvlan.mode specifies the mode the ipvlan will use
254 to communicate between different ipvlan on the same upper
255 device. The accepted modes are l3, l3s and l2. It defaults to l3
256 mode. In l3 mode TX processing up to L3 happens on the stack
257 instance attached to the slave device and packets are switched
258 to the stack instance of the master device for the L2 processing
259 and routing from that instance will be used before packets are
260 queued on the outbound device. In this mode the slaves will not
261 receive nor can send multicast / broadcast traffic. In l3s mode
262 TX processing is very similar to the L3 mode except that ipta‐
263 bles (conn-tracking) works in this mode and hence it is L3-sym‐
264 metric (L3s). This will have slightly less performance but that
265 shouldn't matter since you are choosing this mode over plain-L3
266 mode to make conn-tracking work. In l2 mode TX processing hap‐
267 pens on the stack instance attached to the slave device and
268 packets are switched and queued to the master device to send
269 out. In this mode the slaves will RX/TX multicast and broadcast
270 (if applicable) as well. lxc.net.[i].ipvlan.isolation specifies
271 the isolation mode. The accepted isolation values are bridge,
272 private and vepa. It defaults to bridge. In bridge isolation
273 mode slaves can cross-talk among themselves apart from talking
274 through the master device. In private isolation mode the port
275 is set in private mode. i.e. port won't allow cross communica‐
276 tion between slaves. In vepa isolation mode the port is set in
277 VEPA mode. i.e. port will offload switching functionality to
278 the external entity as described in 802.1Qbg.
279 phys: an already existing interface specified by the
281 lxc.net.[i].link is assigned to the container.
282 lxc.net.[i].flags
284 Specify an action to do for the network.
285 up: activates the interface.
287 lxc.net.[i].link
289 Specify the interface to be used for real network traffic.
290 lxc.net.[i].l2proxy
292 Controls whether layer 2 IP neighbour proxy entries will be
293 added to the lxc.net.[i].link interface for the IP addresses of
294 the container. Can be set to 0 or 1. Defaults to 0. When used
295 with IPv4 addresses, the following sysctl values need to be set:
296 net.ipv4.conf.[link].forwarding=1 When used with IPv6 addresses,
297 the following sysctl values need to be set:
298 net.ipv6.conf.[link].proxy_ndp=1 net.ipv6.conf.[link].forward‐
299 ing=1
300 lxc.net.[i].mtu
302 Specify the maximum transfer unit for this interface.
303 lxc.net.[i].name
305 The interface name is dynamically allocated, but if another name
306 is needed because the configuration files being used by the con‐
307 tainer use a generic name, eg. eth0, this option will rename the
308 interface in the container.
309 lxc.net.[i].hwaddr
311 The interface mac address is dynamically allocated by default to
312 the virtual interface, but in some cases, this is needed to
313 resolve a mac address conflict or to always have the same link-
314 local ipv6 address. Any "x" in address will be replaced by ran‐
315 dom value, this allows setting hwaddr templates.
316 lxc.net.[i].ipv4.address
318 Specify the ipv4 address to assign to the virtualized interface.
319 Several lines specify several ipv4 addresses. The address is in
320 format x.y.z.t/m, eg. 192.168.1.123/24.
321 lxc.net.[i].ipv4.gateway
323 Specify the ipv4 address to use as the gateway inside the con‐
324 tainer. The address is in format x.y.z.t, eg. 192.168.1.123.
325 Can also have the special value auto, which means to take the
326 primary address from the bridge interface (as specified by the
327 lxc.net.[i].link option) and use that as the gateway. auto is
328 only available when using the veth, macvlan and ipvlan network
329 types. Can also have the special value of dev, which means to
330 set the default gateway as a device route. This is primarily
331 for use with layer 3 network modes, such as IPVLAN.
332 lxc.net.[i].ipv6.address
334 Specify the ipv6 address to assign to the virtualized interface.
335 Several lines specify several ipv6 addresses. The address is in
336 format x::y/m, eg. 2003:db8:1:0:214:1234:fe0b:3596/64
337 lxc.net.[i].ipv6.gateway
339 Specify the ipv6 address to use as the gateway inside the con‐
340 tainer. The address is in format x::y, eg. 2003:db8:1:0::1 Can
341 also have the special value auto, which means to take the pri‐
342 mary address from the bridge interface (as specified by the
343 lxc.net.[i].link option) and use that as the gateway. auto is
344 only available when using the veth, macvlan and ipvlan network
345 types. Can also have the special value of dev, which means to
346 set the default gateway as a device route. This is primarily
347 for use with layer 3 network modes, such as IPVLAN.
348 lxc.net.[i].script.up
350 Add a configuration option to specify a script to be executed
351 after creating and configuring the network used from the host
352 side.
353 In addition to the information available to all hooks. The fol‐
355 lowing information is provided to the script:
356 · LXC_HOOK_TYPE: the hook type. This is either 'up' or 'down'.
358 · LXC_HOOK_SECTION: the section type 'net'.
360 · LXC_NET_TYPE: the network type. This is one of the valid net‐
362 work types listed here (e.g. 'vlan', 'macvlan', 'ipvlan',
363 'veth').
364 · LXC_NET_PARENT: the parent device on the host. This is only
366 set for network types 'mavclan', 'veth', 'phys'.
367 · LXC_NET_PEER: the name of the peer device on the host. This is
369 only set for 'veth' network types. Note that this information
370 is only available when lxc.hook.version is set to 1.
371 Whether this information is provided in the form of environment vari‐
373 ables or as arguments to the script depends on the value of
374 lxc.hook.version. If set to 1 then information is provided in the form
375 of environment variables. If set to 0 information is provided as argu‐
376 ments to the script.
377 Standard output from the script is logged at debug level. Standard
379 error is not logged, but can be captured by the hook redirecting its
380 standard error to standard output.
381 lxc.net.[i].script.down
383 Add a configuration option to specify a script to be executed
384 before destroying the network used from the host side.
385 In addition to the information available to all hooks. The fol‐
387 lowing information is provided to the script:
388 · LXC_HOOK_TYPE: the hook type. This is either 'up' or 'down'.
390 · LXC_HOOK_SECTION: the section type 'net'.
392 · LXC_NET_TYPE: the network type. This is one of the valid net‐
394 work types listed here (e.g. 'vlan', 'macvlan', 'ipvlan',
395 'veth').
396 · LXC_NET_PARENT: the parent device on the host. This is only
398 set for network types 'mavclan', 'veth', 'phys'.
399 · LXC_NET_PEER: the name of the peer device on the host. This is
401 only set for 'veth' network types. Note that this information
402 is only available when lxc.hook.version is set to 1.
403 Whether this information is provided in the form of environment vari‐
405 ables or as arguments to the script depends on the value of
406 lxc.hook.version. If set to 1 then information is provided in the form
407 of environment variables. If set to 0 information is provided as argu‐
408 ments to the script.
409 Standard output from the script is logged at debug level. Standard
411 error is not logged, but can be captured by the hook redirecting its
412 standard error to standard output.
413 NEW PSEUDO TTY INSTANCE (DEVPTS)
415 For stricter isolation the container can have its own private instance
416 of the pseudo tty.
417 lxc.pty.max
419 If set, the container will have a new pseudo tty instance, mak‐
420 ing this private to it. The value specifies the maximum number
421 of pseudo ttys allowed for a pts instance (this limitation is
422 not implemented yet).
423 CONTAINER SYSTEM CONSOLE
425 If the container is configured with a root filesystem and the inittab
426 file is setup to use the console, you may want to specify where the
427 output of this console goes.
428 lxc.console.buffer.size
430 Setting this option instructs liblxc to allocate an in-memory
431 ringbuffer. The container's console output will be written to
432 the ringbuffer. Note that ringbuffer must be at least as big as
433 a standard page size. When passed a value smaller than a single
434 page size liblxc will allocate a ringbuffer of a single page
435 size. A page size is usually 4KB. The keyword 'auto' will cause
436 liblxc to allocate a ringbuffer of 128KB. When manually speci‐
437 fying a size for the ringbuffer the value should be a power of 2
438 when converted to bytes. Valid size prefixes are 'KB', 'MB',
439 'GB'. (Note that all conversions are based on multiples of 1024.
440 That means 'KB' == 'KiB', 'MB' == 'MiB', 'GB' == 'GiB'. Addi‐
441 tionally, the case of the suffix is ignored, i.e. 'kB', 'KB' and
442 'Kb' are treated equally.)
443 lxc.console.size
445 Setting this option instructs liblxc to place a limit on the
446 size of the console log file specified in lxc.console.logfile.
447 Note that size of the log file must be at least as big as a
448 standard page size. When passed a value smaller than a single
449 page size liblxc will set the size of log file to a single page
450 size. A page size is usually 4KB. The keyword 'auto' will cause
451 liblxc to place a limit of 128KB on the log file. When manually
452 specifying a size for the log file the value should be a power
453 of 2 when converted to bytes. Valid size prefixes are 'KB',
454 'MB', 'GB'. (Note that all conversions are based on multiples of
455 1024. That means 'KB' == 'KiB', 'MB' == 'MiB', 'GB' == 'GiB'.
456 Additionally, the case of the suffix is ignored, i.e. 'kB', 'KB'
457 and 'Kb' are treated equally.) If users want to mirror the con‐
458 sole ringbuffer on disk they should set lxc.console.size equal
459 to lxc.console.buffer.size.
460 lxc.console.logfile
462 Specify a path to a file where the console output will be writ‐
463 ten. Note that in contrast to the on-disk ringbuffer logfile
464 this file will keep growing potentially filling up the users
465 disks if not rotated and deleted. This problem can also be
466 avoided by using the in-memory ringbuffer options lxc.con‐
467 sole.buffer.size and lxc.console.buffer.logfile.
468 lxc.console.rotate
470 Whether to rotate the console logfile specified in lxc.con‐
471 sole.logfile. Users can send an API request to rotate the log‐
472 file. Note that the old logfile will have the same name as the
473 original with the suffix ".1" appended. Users wishing to pre‐
474 vent the console log file from filling the disk should rotate
475 the logfile and delete it if unneeded. This problem can also be
476 avoided by using the in-memory ringbuffer options lxc.con‐
477 sole.buffer.size and lxc.console.buffer.logfile.
478 lxc.console.path
480 Specify a path to a device to which the console will be
481 attached. The keyword 'none' will simply disable the console.
482 Note, when specifying 'none' and creating a device node for the
483 console in the container at /dev/console or bind-mounting the
484 hosts's /dev/console into the container at /dev/console the con‐
485 tainer will have direct access to the hosts's /dev/console.
486 This is dangerous when the container has write access to the
487 device and should thus be used with caution.
488 CONSOLE THROUGH THE TTYS
490 This option is useful if the container is configured with a root
491 filesystem and the inittab file is setup to launch a getty on the ttys.
492 The option specifies the number of ttys to be available for the con‐
493 tainer. The number of gettys in the inittab file of the container
494 should not be greater than the number of ttys specified in this option,
495 otherwise the excess getty sessions will die and respawn indefinitely
496 giving annoying messages on the console or in /var/log/messages.
497 lxc.tty.max
499 Specify the number of tty to make available to the container.
500 CONSOLE DEVICES LOCATION
502 LXC consoles are provided through Unix98 PTYs created on the host and
503 bind-mounted over the expected devices in the container. By default,
504 they are bind-mounted over /dev/console and /dev/ttyN. This can prevent
505 package upgrades in the guest. Therefore you can specify a directory
506 location (under /dev under which LXC will create the files and bind-
507 mount over them. These will then be symbolically linked to /dev/console
508 and /dev/ttyN. A package upgrade can then succeed as it is able to
509 remove and replace the symbolic links.
510 lxc.tty.dir
512 Specify a directory under /dev under which to create the con‐
513 tainer console devices. Note that LXC will move any bind-mounts
514 or device nodes for /dev/console into this directory.
515 /DEV DIRECTORY
517 By default, lxc creates a few symbolic links (fd,stdin,stdout,stderr)
518 in the container's /dev directory but does not automatically create
519 device node entries. This allows the container's /dev to be set up as
520 needed in the container rootfs. If lxc.autodev is set to 1, then after
521 mounting the container's rootfs LXC will mount a fresh tmpfs under /dev
522 (limited to 500k) and fill in a minimal set of initial devices. This
523 is generally required when starting a container containing a "systemd"
524 based "init" but may be optional at other times. Additional devices in
525 the containers /dev directory may be created through the use of the
526 lxc.hook.autodev hook.
527 lxc.autodev
529 Set this to 0 to stop LXC from mounting and populating a minimal
530 /dev when starting the container.
531 MOUNT POINTS
533 The mount points section specifies the different places to be mounted.
534 These mount points will be private to the container and won't be visi‐
535 ble by the processes running outside of the container. This is useful
536 to mount /etc, /var or /home for examples.
537 NOTE - LXC will generally ensure that mount targets and relative bind-
539 mount sources are properly confined under the container root, to avoid
540 attacks involving over-mounting host directories and files. (Symbolic
541 links in absolute mount sources are ignored) However, if the container
542 configuration first mounts a directory which is under the control of
543 the container user, such as /home/joe, into the container at some path,
544 and then mounts under path, then a TOCTTOU attack would be possible
545 where the container user modifies a symbolic link under his home direc‐
546 tory at just the right time.
547 lxc.mount.fstab
549 specify a file location in the fstab format, containing the
550 mount information. The mount target location can and in most
551 cases should be a relative path, which will become relative to
552 the mounted container root. For instance,
553 proc proc proc nodev,noexec,nosuid 0 0
555 Will mount a proc filesystem under the container's /proc,
558 regardless of where the root filesystem comes from. This is
559 resilient to block device backed filesystems as well as con‐
560 tainer cloning.
561 Note that when mounting a filesystem from an image file or block
563 device the third field (fs_vfstype) cannot be auto as with
564 mount(8) but must be explicitly specified.
565 lxc.mount.entry
567 Specify a mount point corresponding to a line in the fstab for‐
568 mat. Moreover lxc supports mount propagation, such as rslave or
569 rprivate, and adds three additional mount options. optional
570 don't fail if mount does not work. create=dir or create=file to
571 create dir (or file) when the point will be mounted. relative
572 source path is taken to be relative to the mounted container
573 root. For instance,
574 dev/null proc/kcore none bind,relative 0 0
576 .fi
577 Will expand dev/null to ${LXC_ROOTFS_MOUNT}/dev/null,
579 and mount it to proc/kcore inside the container.
580 lxc.mount.auto
582 specify which standard kernel file systems should be
583 automatically mounted. This may dramatically simplify
584 the configuration. The file systems are:
585 · proc:mixed (or proc):
587 mount /proc as read-write, but
588 remount /proc/sys and
589 /proc/sysrq-trigger read-only
590 for security / container isolation purposes.
591 · proc:rw: mount
593 /proc as read-write
594 · sys:mixed (or sys):
596 mount /sys as read-only but with
597 /sys/devices/virtual/net writable.
598 · sys:ro:
600 mount /sys as read-only
601 for security / container isolation purposes.
602 · sys:rw: mount
604 /sys as read-write
605 · cgroup:mixed:
607 Mount a tmpfs to /sys/fs/cgroup,
608 create directories for all hierarchies to which the container
609 is added, create subdirectories in those hierarchies with the
610 name of the cgroup, and bind-mount the container's own cgroup
611 into that directory. The container will be able to write to
612 its own cgroup directory, but not the parents, since they will
613 be remounted read-only.
614 · cgroup:mixed:force:
616 The force option will cause LXC to perform
617 the cgroup mounts for the container under all circumstances.
618 Otherwise it is similar to cgroup:mixed.
619 This is mainly useful when the cgroup namespaces are enabled
620 where LXC will normally leave mounting cgroups to the init
621 binary of the container since it is perfectly safe to do so.
622 · cgroup:ro:
624 similar to cgroup:mixed, but everything will
625 be mounted read-only.
626 · cgroup:ro:force:
628 The force option will cause LXC to perform
629 the cgroup mounts for the container under all circumstances.
630 Otherwise it is similar to cgroup:ro.
631 This is mainly useful when the cgroup namespaces are enabled
632 where LXC will normally leave mounting cgroups to the init
633 binary of the container since it is perfectly safe to do so.
634 · cgroup:rw: similar to
636 cgroup:mixed, but everything will be mounted
637 read-write. Note that the paths leading up to the container's
638 own cgroup will be writable, but will not be a cgroup
639 filesystem but just part of the tmpfs of
640 /sys/fs/cgroup
641 · cgroup:rw:force:
643 The force option will cause LXC to perform
644 the cgroup mounts for the container under all circumstances.
645 Otherwise it is similar to cgroup:rw.
646 This is mainly useful when the cgroup namespaces are enabled
647 where LXC will normally leave mounting cgroups to the init
648 binary of the container since it is perfectly safe to do so.
649 · cgroup (without specifier):
651 defaults to cgroup:rw if the
652 container retains the CAP_SYS_ADMIN capability,
653 cgroup:mixed otherwise.
654 · cgroup-full:mixed:
656 mount a tmpfs to /sys/fs/cgroup,
657 create directories for all hierarchies to which
658 the container is added, bind-mount the hierarchies
659 from the host to the container and make everything
660 read-only except the container's own cgroup. Note
661 that compared to cgroup, where
662 all paths leading up to the container's own cgroup
663 are just simple directories in the underlying
664 tmpfs, here
665 /sys/fs/cgroup/$hierarchy
666 will contain the host's full cgroup hierarchy,
667 albeit read-only outside the container's own cgroup.
668 This may leak quite a bit of information into the
669 container.
670 · cgroup-full:mixed:force:
672 The force option will cause LXC to perform
673 the cgroup mounts for the container under all circumstances.
674 Otherwise it is similar to cgroup-full:mixed.
675 This is mainly useful when the cgroup namespaces are enabled
676 where LXC will normally leave mounting cgroups to the init
677 binary of the container since it is perfectly safe to do so.
678 · cgroup-full:ro: similar to
680 cgroup-full:mixed, but everything
681 will be mounted read-only.
682 · cgroup-full:ro:force:
684 The force option will cause LXC to perform
685 the cgroup mounts for the container under all circumstances.
686 Otherwise it is similar to cgroup-full:ro.
687 This is mainly useful when the cgroup namespaces are enabled
688 where LXC will normally leave mounting cgroups to the init
689 binary of the container since it is perfectly safe to do so.
690 · cgroup-full:rw: similar to
692 cgroup-full:mixed, but everything
693 will be mounted read-write. Note that in this case,
694 the container may escape its own cgroup. (Note also
695 that if the container has CAP_SYS_ADMIN support
696 and can mount the cgroup filesystem itself, it may
697 do so anyway.)
698 · cgroup-full:rw:force:
700 The force option will cause LXC to perform
701 the cgroup mounts for the container under all circumstances.
702 Otherwise it is similar to cgroup-full:rw.
703 This is mainly useful when the cgroup namespaces are enabled
704 where LXC will normally leave mounting cgroups to the init
705 binary of the container since it is perfectly safe to do so.
706 · cgroup-full (without specifier):
708 defaults to cgroup-full:rw if the
709 container retains the CAP_SYS_ADMIN capability,
710 cgroup-full:mixed otherwise.
711 If cgroup namespaces are enabled, then any cgroup
713 auto-mounting request will be ignored, since the container can
714 mount the filesystems itself, and automounting can confuse the
715 container init.
716 Note that if automatic mounting of the cgroup filesystem
718 is enabled, the tmpfs under
719 /sys/fs/cgroup will always be
720 mounted read-write (but for the :mixed
721 and :ro cases, the individual
722 hierarchies,
723 /sys/fs/cgroup/$hierarchy, will be
724 read-only). This is in order to work around a quirk in
725 Ubuntu's
726 mountall(8)
727 command that will cause containers to wait for user
728 input at boot if
729 /sys/fs/cgroup is mounted read-only
730 and the container can't remount it read-write due to a
731 lack of CAP_SYS_ADMIN.
732 Examples:
734 lxc.mount.auto = proc sys cgroup
736 lxc.mount.auto = proc:rw sys:rw cgroup-full:rw
737 ROOT FILE SYSTEM
740 The root file system of the container can be different than that of the
741 host system.
742 lxc.rootfs.path
744 specify the root file system for the container. It can be an
745 image file, a directory or a block device. If not specified, the
746 container shares its root file system with the host.
747 For directory or simple block-device backed containers, a path‐
749 name can be used. If the rootfs is backed by a nbd device, then
750 nbd:file:1 specifies that file should be attached to a nbd
751 device, and partition 1 should be mounted as the rootfs.
752 nbd:file specifies that the nbd device itself should be mounted.
753 overlayfs:/lower:/upper specifies that the rootfs should be an
754 overlay with /upper being mounted read-write over a read-only
755 mount of /lower. For overlay multiple /lower directories can be
756 specified. loop:/file tells lxc to attach /file to a loop device
757 and mount the loop device.
758 lxc.rootfs.mount
760 where to recursively bind lxc.rootfs.path before pivoting. This
761 is to ensure success of the pivot_root(8) syscall. Any directory
762 suffices, the default should generally work.
763 lxc.rootfs.options
765 extra mount options to use when mounting the rootfs.
766 lxc.rootfs.managed
768 Set this to 0 to indicate that LXC is not managing the container
769 storage, then LXC will not modify the container storage. The
770 default is 1.
771 CONTROL GROUP
773 The control group section contains the configuration for the different
774 subsystem. lxc does not check the correctness of the subsystem name.
775 This has the disadvantage of not detecting configuration errors until
776 the container is started, but has the advantage of permitting any
777 future subsystem.
778 lxc.cgroup.[controller name]
780 Specify the control group value to be set on a legacy cgroup
781 hierarchy. The controller name is the literal name of the con‐
782 trol group. The permitted names and the syntax of their values
783 is not dictated by LXC, instead it depends on the features of
784 the Linux kernel running at the time the container is started,
785 eg. lxc.cgroup.cpuset.cpus
786 lxc.cgroup2.[controller name]
788 Specify the control group value to be set on the unified cgroup
789 hierarchy. The controller name is the literal name of the con‐
790 trol group. The permitted names and the syntax of their values
791 is not dictated by LXC, instead it depends on the features of
792 the Linux kernel running at the time the container is started,
793 eg. lxc.cgroup2.memory.high
794 lxc.cgroup.dir
796 specify a directory or path in which the container's cgroup will
797 be created. For example, setting lxc.cgroup.dir =
798 my-cgroup/first for a container named "c1" will create the con‐
799 tainer's cgroup as a sub-cgroup of "my-cgroup". For example, if
800 the user's current cgroup "my-user" is located in the root
801 cgroup of the cpuset controller in a cgroup v1 hierarchy this
802 would create the cgroup "/sys/fs/cgroup/cpuset/my-user/my-
803 cgroup/first/c1" for the container. Any missing cgroups will be
804 created by LXC. This presupposes that the user has write access
805 to its current cgroup.
806 lxc.cgroup.relative
808 Set this to 1 to instruct LXC to never escape to the root
809 cgroup. This makes it easy for users to adhere to restrictions
810 enforced by cgroup2 and systemd. Specifically, this makes it
811 possible to run LXC containers as systemd services.
812 CAPABILITIES
814 The capabilities can be dropped in the container if this one is run as
815 root.
816 lxc.cap.drop
818 Specify the capability to be dropped in the container. A single
819 line defining several capabilities with a space separation is
820 allowed. The format is the lower case of the capability defini‐
821 tion without the "CAP_" prefix, eg. CAP_SYS_MODULE should be
822 specified as sys_module. See capabilities(7). If used with no
823 value, lxc will clear any drop capabilities specified up to this
824 point.
825 lxc.cap.keep
827 Specify the capability to be kept in the container. All other
828 capabilities will be dropped. When a special value of "none" is
829 encountered, lxc will clear any keep capabilities specified up
830 to this point. A value of "none" alone can be used to drop all
831 capabilities.
832 NAMESPACES
834 A namespace can be cloned (lxc.namespace.clone), kept (lxc.names‐
835 pace.keep) or shared (lxc.namespace.share.[namespace identifier]).
836 lxc.namespace.clone
838 Specify namespaces which the container is supposed to be created
839 with. The namespaces to create are specified as a space sepa‐
840 rated list. Each namespace must correspond to one of the stan‐
841 dard namespace identifiers as seen in the /proc/PID/ns direc‐
842 tory. When lxc.namespace.clone is not explicitly set all names‐
843 paces supported by the kernel and the current configuration will
844 be used.
845 To create a new mount, net and ipc namespace set lxc.names‐
847 pace.clone=mount net ipc.
848 lxc.namespace.keep
850 Specify namespaces which the container is supposed to inherit
851 from the process that created it. The namespaces to keep are
852 specified as a space separated list. Each namespace must corre‐
853 spond to one of the standard namespace identifiers as seen in
854 the /proc/PID/ns directory. The lxc.namespace.keep is a black‐
855 list option, i.e. it is useful when enforcing that containers
856 must keep a specific set of namespaces.
857 To keep the network, user and ipc namespace set lxc.names‐
859 pace.keep=user net ipc.
860 Note that sharing pid namespaces will likely not work with most
862 init systems.
863 Note that if the container requests a new user namespace and the
865 container wants to inherit the network namespace it needs to
866 inherit the user namespace as well.
867 lxc.namespace.share.[namespace identifier]
869 Specify a namespace to inherit from another container or
870 process. The [namespace identifier] suffix needs to be replaced
871 with one of the namespaces that appear in the /proc/PID/ns
872 directory.
873 To inherit the namespace from another process set the lxc.names‐
875 pace.share.[namespace identifier] to the PID of the process,
876 e.g. lxc.namespace.share.net=42.
877 To inherit the namespace from another container set the
879 lxc.namespace.share.[namespace identifier] to the name of the
880 container, e.g. lxc.namespace.share.pid=c3.
881 To inherit the namespace from another container located in a
883 different path than the standard liblxc path set the lxc.names‐
884 pace.share.[namespace identifier] to the full path to the con‐
885 tainer, e.g. lxc.namespace.share.user=/opt/c3.
886 In order to inherit namespaces the caller needs to have suffi‐
888 cient privilege over the process or container.
889 Note that sharing pid namespaces between system containers will
891 likely not work with most init systems.
892 Note that if two processes are in different user namespaces and
894 one process wants to inherit the other's network namespace it
895 usually needs to inherit the user namespace as well.
896 Note that without careful additional configuration of an LSM,
898 sharing user+pid namespaces with a task may allow that task to
899 escalate privileges to that of the task calling liblxc.
900 RESOURCE LIMITS
902 The soft and hard resource limits for the container can be changed.
903 Unprivileged containers can only lower them. Resources which are not
904 explicitly specified will be inherited.
905 lxc.prlimit.[limit name]
907 Specify the resource limit to be set. A limit is specified as
908 two colon separated values which are either numeric or the word
909 'unlimited'. A single value can be used as a shortcut to set
910 both soft and hard limit to the same value. The permitted names
911 the "RLIMIT_" resource names in lowercase without the "RLIMIT_"
912 prefix, eg. RLIMIT_NOFILE should be specified as "nofile". See
913 setrlimit(2). If used with no value, lxc will clear the
914 resource limit specified up to this point. A resource with no
915 explicitly configured limitation will be inherited from the
916 process starting up the container.
917 SYSCTL
919 Configure kernel parameters for the container.
920 lxc.sysctl.[kernel parameters name]
922 Specify the kernel parameters to be set. The parameters avail‐
923 able are those listed under /proc/sys/. Note that not all
924 sysctls are namespaced. Changing Non-namespaced sysctls will
925 cause the system-wide setting to be modified. sysctl(8). If
926 used with no value, lxc will clear the parameters specified up
927 to this point.
928 APPARMOR PROFILE
930 If lxc was compiled and installed with apparmor support, and the host
931 system has apparmor enabled, then the apparmor profile under which the
932 container should be run can be specified in the container configura‐
933 tion. The default is lxc-container-default-cgns if the host kernel is
934 cgroup namespace aware, or lxc-container-default otherwise.
935 lxc.apparmor.profile
937 Specify the apparmor profile under which the container should be
938 run. To specify that the container should be unconfined, use
939 lxc.apparmor.profile = unconfined
941 If the apparmor profile should remain unchanged (i.e. if you are
943 nesting containers and are already confined), then use
944 lxc.apparmor.profile = unchanged
946 If you instruct LXC to generate the apparmor profile, then use
948 lxc.apparmor.profile = generated
950 lxc.apparmor.allow_incomplete
952 Apparmor profiles are pathname based. Therefore many file
953 restrictions require mount restrictions to be effective against
954 a determined attacker. However, these mount restrictions are not
955 yet implemented in the upstream kernel. Without the mount
956 restrictions, the apparmor profiles still protect against acci‐
957 dental damager.
958 If this flag is 0 (default), then the container will not be
960 started if the kernel lacks the apparmor mount features, so that
961 a regression after a kernel upgrade will be detected. To start
962 the container under partial apparmor protection, set this flag
963 to 1.
964 lxc.apparmor.allow_nesting
966 If set this to 1, causes the following changes. When generated
967 apparmor profiles are used, they will contain the necessary
968 changes to allow creating a nested container. In addition to the
969 usual mount points, /dev/.lxc/proc and /dev/.lxc/sys will con‐
970 tain procfs and sysfs mount points without the lxcfs overlays,
971 which, if generated apparmor profiles are being used, will not
972 be read/writable directly.
973 lxc.apparmor.raw
975 A list of raw AppArmor profile lines to append to the profile.
976 Only valid when using generated profiles.
977 SELINUX CONTEXT
979 If lxc was compiled and installed with SELinux support, and the host
980 system has SELinux enabled, then the SELinux context under which the
981 container should be run can be specified in the container configura‐
982 tion. The default is unconfined_t, which means that lxc will not
983 attempt to change contexts. See /usr/share/lxc/selinux/lxc.te for an
984 example policy and more information.
985 lxc.selinux.context
987 Specify the SELinux context under which the container should be
988 run or unconfined_t. For example
989 lxc.selinux.context = system_u:system_r:lxc_t:s0:c22
991 SECCOMP CONFIGURATION
993 A container can be started with a reduced set of available system calls
994 by loading a seccomp profile at startup. The seccomp configuration file
995 must begin with a version number on the first line, a policy type on
996 the second line, followed by the configuration.
997 Versions 1 and 2 are currently supported. In version 1, the policy is a
999 simple whitelist. The second line therefore must read "whitelist", with
1000 the rest of the file containing one (numeric) syscall number per line.
1001 Each syscall number is whitelisted, while every unlisted number is
1002 blacklisted for use in the container
1003 In version 2, the policy may be blacklist or whitelist, supports per-
1005 rule and per-policy default actions, and supports per-architecture sys‐
1006 tem call resolution from textual names.
1007 An example blacklist policy, in which all system calls are allowed
1009 except for mknod, which will simply do nothing and return 0 (success),
1010 looks like:
1011 2
1013 blacklist
1014 mknod errno 0
1015 ioctl notify
1016 Specifying "errno" as action will cause LXC to register a seccomp fil‐
1019 ter that will cause a specific errno to be returned to the caller. The
1020 errno value can be specified after the "errno" action word.
1021 Specifying "notify" as action will cause LXC to register a seccomp lis‐
1023 tener and retrieve a listener file descriptor from the kernel. When a
1024 syscall is made that is registered as "notify" the kernel will generate
1025 a poll event and send a message over the file descriptor. The caller
1026 can read this message, inspect the syscalls including its arguments.
1027 Based on this information the caller is expected to send back a message
1028 informing the kernel which action to take. Until that message is sent
1029 the kernel will block the calling process. The format of the messages
1030 to read and sent is documented in seccomp itself.
1031 lxc.seccomp.profile
1033 Specify a file containing the seccomp configuration to load
1034 before the container starts.
1035 lxc.seccomp.allow_nesting
1037 If this flag is set to 1, then seccomp filters will be stacked
1038 regardless of whether a seccomp profile is already loaded. This
1039 allows nested containers to load their own seccomp profile. The
1040 default setting is 0.
1041 lxc.seccomp.notify.proxy
1043 Specify a unix socket to which LXC will connect and forward sec‐
1044 comp events to. The path must be in the form
1045 unix:/path/to/socket or unix:@socket. The former specifies a
1046 path-bound unix domain socket while the latter specifies an
1047 abstract unix domain socket.
1048 lxc.seccomp.notify.cookie
1050 An additional string sent along with proxied seccomp notifica‐
1051 tion requests.
1052 PR_SET_NO_NEW_PRIVS
1054 With PR_SET_NO_NEW_PRIVS active execve() promises not to grant privi‐
1055 leges to do anything that could not have been done without the execve()
1056 call (for example, rendering the set-user-ID and set-group-ID mode
1057 bits, and file capabilities non-functional). Once set, this bit cannot
1058 be unset. The setting of this bit is inherited by children created by
1059 fork() and clone(), and preserved across execve(). Note that
1060 PR_SET_NO_NEW_PRIVS is applied after the container has changed into its
1061 intended AppArmor profile or SElinux context.
1062 lxc.no_new_privs
1064 Specify whether the PR_SET_NO_NEW_PRIVS flag should be set for
1065 the container. Set to 1 to activate.
1066 UID MAPPINGS
1068 A container can be started in a private user namespace with user and
1069 group id mappings. For instance, you can map userid 0 in the container
1070 to userid 200000 on the host. The root user in the container will be
1071 privileged in the container, but unprivileged on the host. Normally a
1072 system container will want a range of ids, so you would map, for
1073 instance, user and group ids 0 through 20,000 in the container to the
1074 ids 200,000 through 220,000.
1075 lxc.idmap
1077 Four values must be provided. First a character, either 'u', or
1078 'g', to specify whether user or group ids are being mapped. Next
1079 is the first userid as seen in the user namespace of the con‐
1080 tainer. Next is the userid as seen on the host. Finally, a range
1081 indicating the number of consecutive ids to map.
1082 CONTAINER HOOKS
1084 Container hooks are programs or scripts which can be executed at vari‐
1085 ous times in a container's lifetime.
1086 When a container hook is executed, additional information is passed
1088 along. The lxc.hook.version argument can be used to determine if the
1089 following arguments are passed as command line arguments or through
1090 environment variables. The arguments are:
1091 · Container name.
1093 · Section (always 'lxc').
1095 · The hook type (i.e. 'clone' or 'pre-mount').
1097 · Additional arguments. In the case of the clone hook, any extra argu‐
1099 ments passed will appear as further arguments to the hook. In the
1100 case of the stop hook, paths to filedescriptors for each of the con‐
1101 tainer's namespaces along with their types are passed.
1102 The following environment variables are set:
1104 · LXC_CGNS_AWARE: indicator whether the container is cgroup namespace
1106 aware.
1107 · LXC_CONFIG_FILE: the path to the container configuration file.
1109 · LXC_HOOK_TYPE: the hook type (e.g. 'clone', 'mount', 'pre-mount').
1111 Note that the existence of this environment variable is conditional
1112 on the value of lxc.hook.version. If it is set to 1 then
1113 LXC_HOOK_TYPE will be set.
1114 · LXC_HOOK_SECTION: the section type (e.g. 'lxc', 'net'). Note that the
1116 existence of this environment variable is conditional on the value of
1117 lxc.hook.version. If it is set to 1 then LXC_HOOK_SECTION will be
1118 set.
1119 · LXC_HOOK_VERSION: the version of the hooks. This value is identical
1121 to the value of the container's lxc.hook.version config item. If it
1122 is set to 0 then old-style hooks are used. If it is set to 1 then
1123 new-style hooks are used.
1124 · LXC_LOG_LEVEL: the container's log level.
1126 · LXC_NAME: is the container's name.
1128 · LXC_[NAMESPACE IDENTIFIER]_NS: path under /proc/PID/fd/ to a file
1130 descriptor referring to the container's namespace. For each preserved
1131 namespace type there will be a separate environment variable. These
1132 environment variables will only be set if lxc.hook.version is set to
1133 1.
1134 · LXC_ROOTFS_MOUNT: the path to the mounted root filesystem.
1136 · LXC_ROOTFS_PATH: this is the lxc.rootfs.path entry for the container.
1138 Note this is likely not where the mounted rootfs is to be found, use
1139 LXC_ROOTFS_MOUNT for that.
1140 · LXC_SRC_NAME: in the case of the clone hook, this is the original
1142 container's name.
1143 Standard output from the hooks is logged at debug level. Standard
1145 error is not logged, but can be captured by the hook redirecting its
1146 standard error to standard output.
1147 lxc.hook.version
1149 To pass the arguments in new style via environment variables set
1150 to 1 otherwise set to 0 to pass them as arguments. This setting
1151 affects all hooks arguments that were traditionally passed as
1152 arguments to the script. Specifically, it affects the container
1153 name, section (e.g. 'lxc', 'net') and hook type (e.g. 'clone',
1154 'mount', 'pre-mount') arguments. If new-style hooks are used
1155 then the arguments will be available as environment variables.
1156 The container name will be set in LXC_NAME. (This is set inde‐
1157 pendently of the value used for this config item.) The section
1158 will be set in LXC_HOOK_SECTION and the hook type will be set in
1159 LXC_HOOK_TYPE. It also affects how the paths to file descrip‐
1160 tors referring to the container's namespaces are passed. If set
1161 to 1 then for each namespace a separate environment variable
1162 LXC_[NAMESPACE IDENTIFIER]_NS will be set. If set to 0 then the
1163 paths will be passed as arguments to the stop hook.
1164 lxc.hook.pre-start
1166 A hook to be run in the host's namespace before the container
1167 ttys, consoles, or mounts are up.
1168 lxc.hook.pre-mount
1170 A hook to be run in the container's fs namespace but before the
1171 rootfs has been set up. This allows for manipulation of the
1172 rootfs, i.e. to mount an encrypted filesystem. Mounts done in
1173 this hook will not be reflected on the host (apart from mounts
1174 propagation), so they will be automatically cleaned up when the
1175 container shuts down.
1176 lxc.hook.mount
1178 A hook to be run in the container's namespace after mounting has
1179 been done, but before the pivot_root.
1180 lxc.hook.autodev
1182 A hook to be run in the container's namespace after mounting has
1183 been done and after any mount hooks have run, but before the
1184 pivot_root, if lxc.autodev == 1. The purpose of this hook is to
1185 assist in populating the /dev directory of the container when
1186 using the autodev option for systemd based containers. The con‐
1187 tainer's /dev directory is relative to the ${LXC_ROOTFS_MOUNT}
1188 environment variable available when the hook is run.
1189 lxc.hook.start-host
1191 A hook to be run in the host's namespace after the container has
1192 been setup, and immediately before starting the container init.
1193 lxc.hook.start
1195 A hook to be run in the container's namespace immediately before
1196 executing the container's init. This requires the program to be
1197 available in the container.
1198 lxc.hook.stop
1200 A hook to be run in the host's namespace with references to the
1201 container's namespaces after the container has been shut down.
1202 For each namespace an extra argument is passed to the hook con‐
1203 taining the namespace's type and a filename that can be used to
1204 obtain a file descriptor to the corresponding namespace, sepa‐
1205 rated by a colon. The type is the name as it would appear in the
1206 /proc/PID/ns directory. For instance for the mount namespace
1207 the argument usually looks like mnt:/proc/PID/fd/12.
1208 lxc.hook.post-stop
1210 A hook to be run in the host's namespace after the container has
1211 been shut down.
1212 lxc.hook.clone
1214 A hook to be run when the container is cloned to a new one. See
1215 lxc-clone(1) for more information.
1216 lxc.hook.destroy
1218 A hook to be run when the container is destroyed.
1219 CONTAINER HOOKS ENVIRONMENT VARIABLES
1221 A number of environment variables are made available to the startup
1222 hooks to provide configuration information and assist in the function‐
1223 ing of the hooks. Not all variables are valid in all contexts. In par‐
1224 ticular, all paths are relative to the host system and, as such, not
1225 valid during the lxc.hook.start hook.
1226 LXC_NAME
1228 The LXC name of the container. Useful for logging messages in
1229 common log environments. [-n]
1230 LXC_CONFIG_FILE
1232 Host relative path to the container configuration file. This
1233 gives the container to reference the original, top level, con‐
1234 figuration file for the container in order to locate any addi‐
1235 tional configuration information not otherwise made available.
1236 [-f]
1237 LXC_CONSOLE
1239 The path to the console output of the container if not NULL.
1240 [-c] [lxc.console.path]
1241 LXC_CONSOLE_LOGPATH
1243 The path to the console log output of the container if not NULL.
1244 [-L]
1245 LXC_ROOTFS_MOUNT
1247 The mount location to which the container is initially bound.
1248 This will be the host relative path to the container rootfs for
1249 the container instance being started and is where changes should
1250 be made for that instance. [lxc.rootfs.mount]
1251 LXC_ROOTFS_PATH
1253 The host relative path to the container root which has been
1254 mounted to the rootfs.mount location. [lxc.rootfs.path]
1255 LXC_SRC_NAME
1257 Only for the clone hook. Is set to the original container name.
1258 LXC_TARGET
1260 Only for the stop hook. Is set to "stop" for a container shut‐
1261 down or "reboot" for a container reboot.
1262 LXC_CGNS_AWARE
1264 If unset, then this version of lxc is not aware of cgroup names‐
1265 paces. If set, it will be set to 1, and lxc is aware of cgroup
1266 namespaces. Note this does not guarantee that cgroup namespaces
1267 are enabled in the kernel. This is used by the lxcfs mount hook.
1268 LOGGING
1270 Logging can be configured on a per-container basis. By default, depend‐
1271 ing upon how the lxc package was compiled, container startup is logged
1272 only at the ERROR level, and logged to a file named after the container
1273 (with '.log' appended) either under the container path, or under
1274 /var/log/lxc.
1275 Both the default log level and the log file can be specified in the
1277 container configuration file, overriding the default behavior. Note
1278 that the configuration file entries can in turn be overridden by the
1279 command line options to lxc-start.
1280 lxc.log.level
1282 The level at which to log. The log level is an integer in the
1283 range of 0..8 inclusive, where a lower number means more verbose
1284 debugging. In particular 0 = trace, 1 = debug, 2 = info, 3 =
1285 notice, 4 = warn, 5 = error, 6 = critical, 7 = alert, and 8 =
1286 fatal. If unspecified, the level defaults to 5 (error), so that
1287 only errors and above are logged.
1288 Note that when a script (such as either a hook script or a net‐
1290 work interface up or down script) is called, the script's stan‐
1291 dard output is logged at level 1, debug.
1292 lxc.log.file
1294 The file to which logging info should be written.
1295 lxc.log.syslog
1297 Send logging info to syslog. It respects the log level defined
1298 in lxc.log.level. The argument should be the syslog facility to
1299 use, valid ones are: daemon, local0, local1, local2, local3,
1300 local4, local5, local5, local6, local7.
1301 AUTOSTART
1303 The autostart options support marking which containers should be auto-
1304 started and in what order. These options may be used by LXC tools
1305 directly or by external tooling provided by the distributions.
1306 lxc.start.auto
1308 Whether the container should be auto-started. Valid values are
1309 0 (off) and 1 (on).
1310 lxc.start.delay
1312 How long to wait (in seconds) after the container is started
1313 before starting the next one.
1314 lxc.start.order
1316 An integer used to sort the containers when auto-starting a
1317 series of containers at once.
1318 lxc.monitor.unshare
1320 If not zero the mount namespace will be unshared from the host
1321 before initializing the container (before running any pre-start
1322 hooks). This requires the CAP_SYS_ADMIN capability at startup.
1323 Default is 0.
1324 lxc.monitor.signal.pdeath
1326 Set the signal to be sent to the container's init when the lxc
1327 monitor exits. By default it is set to SIGKILL which will cause
1328 all container processes to be killed when the lxc monitor
1329 process dies. To ensure that containers stay alive even if lxc
1330 monitor dies set this to 0.
1331 lxc.group
1333 A multi-value key (can be used multiple times) to put the con‐
1334 tainer in a container group. Those groups can then be used
1335 (amongst other things) to start a series of related containers.
1336 AUTOSTART AND SYSTEM BOOT
1338 Each container can be part of any number of groups or no group at all.
1339 Two groups are special. One is the NULL group, i.e. the container does
1340 not belong to any group. The other group is the "onboot" group.
1341 When the system boots with the LXC service enabled, it will first
1343 attempt to boot any containers with lxc.start.auto == 1 that is a mem‐
1344 ber of the "onboot" group. The startup will be in order of
1345 lxc.start.order. If an lxc.start.delay has been specified, that delay
1346 will be honored before attempting to start the next container to give
1347 the current container time to begin initialization and reduce overload‐
1348 ing the host system. After starting the members of the "onboot" group,
1349 the LXC system will proceed to boot containers with lxc.start.auto == 1
1350 which are not members of any group (the NULL group) and proceed as with
1351 the onboot group.
1352 CONTAINER ENVIRONMENT
1354 If you want to pass environment variables into the container (that is,
1355 environment variables which will be available to init and all of its
1356 descendents), you can use lxc.environment parameters to do so. Be care‐
1357 ful that you do not pass in anything sensitive; any process in the con‐
1358 tainer which doesn't have its environment scrubbed will have these
1359 variables available to it, and environment variables are always avail‐
1360 able via /proc/PID/environ.
1361 This configuration parameter can be specified multiple times; once for
1363 each environment variable you wish to configure.
1364 lxc.environment
1366 Specify an environment variable to pass into the container.
1367 Example:
1368 lxc.environment = APP_ENV=production
1370 lxc.environment = SYSLOG_SERVER=192.0.2.42
1371 It is possible to inherit host environment variables by setting
1374 the name of the variable without a "=" sign. For example:
1375 lxc.environment = PATH
1377
1380 In addition to the few examples given below, you will find some other
1381 examples of configuration file in /usr/share/doc/lxc/examples
1382 NETWORK
1384 This configuration sets up a container to use a veth pair device with
1385 one side plugged to a bridge br0 (which has been configured before on
1386 the system by the administrator). The virtual network device visible in
1387 the container is renamed to eth0.
1388 lxc.uts.name = myhostname
1390 lxc.net.0.type = veth
1391 lxc.net.0.flags = up
1392 lxc.net.0.link = br0
1393 lxc.net.0.name = eth0
1394 lxc.net.0.hwaddr = 4a:49:43:49:79:bf
1395 lxc.net.0.ipv4.address = 10.2.3.5/24 10.2.3.255
1396 lxc.net.0.ipv6.address = 2003:db8:1:0:214:1234:fe0b:3597
1397 UID/GID MAPPING
1400 This configuration will map both user and group ids in the range 0-9999
1401 in the container to the ids 100000-109999 on the host.
1402 lxc.idmap = u 0 100000 10000
1404 lxc.idmap = g 0 100000 10000
1405 CONTROL GROUP
1408 This configuration will setup several control groups for the applica‐
1409 tion, cpuset.cpus restricts usage of the defined cpu, cpus.share prior‐
1410 itize the control group, devices.allow makes usable the specified
1411 devices.
1412 lxc.cgroup.cpuset.cpus = 0,1
1414 lxc.cgroup.cpu.shares = 1234
1415 lxc.cgroup.devices.deny = a
1416 lxc.cgroup.devices.allow = c 1:3 rw
1417 lxc.cgroup.devices.allow = b 8:0 rw
1418 COMPLEX CONFIGURATION
1421 This example show a complex configuration making a complex network
1422 stack, using the control groups, setting a new hostname, mounting some
1423 locations and a changing root file system.
1424 lxc.uts.name = complex
1426 lxc.net.0.type = veth
1427 lxc.net.0.flags = up
1428 lxc.net.0.link = br0
1429 lxc.net.0.hwaddr = 4a:49:43:49:79:bf
1430 lxc.net.0.ipv4.address = 10.2.3.5/24 10.2.3.255
1431 lxc.net.0.ipv6.address = 2003:db8:1:0:214:1234:fe0b:3597
1432 lxc.net.0.ipv6.address = 2003:db8:1:0:214:5432:feab:3588
1433 lxc.net.1.type = macvlan
1434 lxc.net.1.flags = up
1435 lxc.net.1.link = eth0
1436 lxc.net.1.hwaddr = 4a:49:43:49:79:bd
1437 lxc.net.1.ipv4.address = 10.2.3.4/24
1438 lxc.net.1.ipv4.address = 192.168.10.125/24
1439 lxc.net.1.ipv6.address = 2003:db8:1:0:214:1234:fe0b:3596
1440 lxc.net.2.type = phys
1441 lxc.net.2.flags = up
1442 lxc.net.2.link = dummy0
1443 lxc.net.2.hwaddr = 4a:49:43:49:79:ff
1444 lxc.net.2.ipv4.address = 10.2.3.6/24
1445 lxc.net.2.ipv6.address = 2003:db8:1:0:214:1234:fe0b:3297
1446 lxc.cgroup.cpuset.cpus = 0,1
1447 lxc.cgroup.cpu.shares = 1234
1448 lxc.cgroup.devices.deny = a
1449 lxc.cgroup.devices.allow = c 1:3 rw
1450 lxc.cgroup.devices.allow = b 8:0 rw
1451 lxc.mount.fstab = /etc/fstab.complex
1452 lxc.mount.entry = /lib /root/myrootfs/lib none ro,bind 0 0
1453 lxc.rootfs.path = dir:/mnt/rootfs.complex
1454 lxc.cap.drop = sys_module mknod setuid net_raw
1455 lxc.cap.drop = mac_override
1456
1459 chroot(1), pivot_root(8), fstab(5), capabilities(7)
1460
1462 lxc(7), lxc-create(1), lxc-copy(1), lxc-destroy(1), lxc-start(1), lxc-
1463 stop(1), lxc-execute(1), lxc-console(1), lxc-monitor(1), lxc-wait(1),
1464 lxc-cgroup(1), lxc-ls(1), lxc-info(1), lxc-freeze(1), lxc-unfreeze(1),
1465 lxc-attach(1), lxc.conf(5)
1466
1468 Daniel Lezcano <daniel.lezcano@free.fr>
1469 2020-01-29 lxc.container.conf(5)