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 dependent device and packets are
258 switched to the stack instance of the parent device for the L2
259 processing and routing from that instance will be used before
260 packets are queued on the outbound device. In this mode the
261 dependent devices will not receive nor can send multicast /
262 broadcast traffic. In l3s mode TX processing is very similar to
263 the L3 mode except that iptables (conn-tracking) works in this
264 mode and hence it is L3-symmetric (L3s). This will have
265 slightly less performance but that shouldn't matter since you
266 are choosing this mode over plain-L3 mode to make conn-tracking
267 work. In l2 mode TX processing happens on the stack instance
268 attached to the dependent device and packets are switched and
269 queued to the parent device to send devices out. In this mode
270 the dependent devices will RX/TX multicast and broadcast (if
271 applicable) as well. lxc.net.[i].ipvlan.isolation specifies the
272 isolation mode. The accepted isolation values are bridge, pri‐
273 vate and vepa. It defaults to bridge. In bridge isolation mode
274 dependent devices can cross-talk among themselves apart from
275 talking through the parent device. In private isolation mode
276 the port is set in private mode. i.e. port won't allow cross
277 communication between dependent devices. In vepa isolation mode
278 the port is set in VEPA mode. i.e. port will offload switching
279 functionality to the external entity as described in 802.1Qbg.
280 phys: an already existing interface specified by the
282 lxc.net.[i].link is assigned to the container.
283 lxc.net.[i].flags
285 Specify an action to do for the network.
286 up: activates the interface.
288 lxc.net.[i].link
290 Specify the interface to be used for real network traffic.
291 lxc.net.[i].l2proxy
293 Controls whether layer 2 IP neighbour proxy entries will be
294 added to the lxc.net.[i].link interface for the IP addresses of
295 the container. Can be set to 0 or 1. Defaults to 0. When used
296 with IPv4 addresses, the following sysctl values need to be set:
297 net.ipv4.conf.[link].forwarding=1 When used with IPv6 addresses,
298 the following sysctl values need to be set:
299 net.ipv6.conf.[link].proxy_ndp=1 net.ipv6.conf.[link].forward‐
300 ing=1
301 lxc.net.[i].mtu
303 Specify the maximum transfer unit for this interface.
304 lxc.net.[i].name
306 The interface name is dynamically allocated, but if another name
307 is needed because the configuration files being used by the con‐
308 tainer use a generic name, eg. eth0, this option will rename the
309 interface in the container.
310 lxc.net.[i].hwaddr
312 The interface mac address is dynamically allocated by default to
313 the virtual interface, but in some cases, this is needed to
314 resolve a mac address conflict or to always have the same link-
315 local ipv6 address. Any "x" in address will be replaced by ran‐
316 dom value, this allows setting hwaddr templates.
317 lxc.net.[i].ipv4.address
319 Specify the ipv4 address to assign to the virtualized interface.
320 Several lines specify several ipv4 addresses. The address is in
321 format x.y.z.t/m, eg. 192.168.1.123/24.
322 lxc.net.[i].ipv4.gateway
324 Specify the ipv4 address to use as the gateway inside the con‐
325 tainer. The address is in format x.y.z.t, eg. 192.168.1.123.
326 Can also have the special value auto, which means to take the
327 primary address from the bridge interface (as specified by the
328 lxc.net.[i].link option) and use that as the gateway. auto is
329 only available when using the veth, macvlan and ipvlan network
330 types. Can also have the special value of dev, which means to
331 set the default gateway as a device route. This is primarily
332 for use with layer 3 network modes, such as IPVLAN.
333 lxc.net.[i].ipv6.address
335 Specify the ipv6 address to assign to the virtualized interface.
336 Several lines specify several ipv6 addresses. The address is in
337 format x::y/m, eg. 2003:db8:1:0:214:1234:fe0b:3596/64
338 lxc.net.[i].ipv6.gateway
340 Specify the ipv6 address to use as the gateway inside the con‐
341 tainer. The address is in format x::y, eg. 2003:db8:1:0::1 Can
342 also have the special value auto, which means to take the pri‐
343 mary address from the bridge interface (as specified by the
344 lxc.net.[i].link option) and use that as the gateway. auto is
345 only available when using the veth, macvlan and ipvlan network
346 types. Can also have the special value of dev, which means to
347 set the default gateway as a device route. This is primarily
348 for use with layer 3 network modes, such as IPVLAN.
349 lxc.net.[i].script.up
351 Add a configuration option to specify a script to be executed
352 after creating and configuring the network used from the host
353 side.
354 In addition to the information available to all hooks. The fol‐
356 lowing information is provided to the script:
357 · LXC_HOOK_TYPE: the hook type. This is either 'up' or 'down'.
359 · LXC_HOOK_SECTION: the section type 'net'.
361 · LXC_NET_TYPE: the network type. This is one of the valid net‐
363 work types listed here (e.g. 'vlan', 'macvlan', 'ipvlan',
364 'veth').
365 · LXC_NET_PARENT: the parent device on the host. This is only
367 set for network types 'mavclan', 'veth', 'phys'.
368 · LXC_NET_PEER: the name of the peer device on the host. This is
370 only set for 'veth' network types. Note that this information
371 is only available when lxc.hook.version is set to 1.
372 Whether this information is provided in the form of environment vari‐
374 ables or as arguments to the script depends on the value of
375 lxc.hook.version. If set to 1 then information is provided in the form
376 of environment variables. If set to 0 information is provided as argu‐
377 ments to the script.
378 Standard output from the script is logged at debug level. Standard
380 error is not logged, but can be captured by the hook redirecting its
381 standard error to standard output.
382 lxc.net.[i].script.down
384 Add a configuration option to specify a script to be executed
385 before destroying the network used from the host side.
386 In addition to the information available to all hooks. The fol‐
388 lowing information is provided to the script:
389 · LXC_HOOK_TYPE: the hook type. This is either 'up' or 'down'.
391 · LXC_HOOK_SECTION: the section type 'net'.
393 · LXC_NET_TYPE: the network type. This is one of the valid net‐
395 work types listed here (e.g. 'vlan', 'macvlan', 'ipvlan',
396 'veth').
397 · LXC_NET_PARENT: the parent device on the host. This is only
399 set for network types 'mavclan', 'veth', 'phys'.
400 · LXC_NET_PEER: the name of the peer device on the host. This is
402 only set for 'veth' network types. Note that this information
403 is only available when lxc.hook.version is set to 1.
404 Whether this information is provided in the form of environment vari‐
406 ables or as arguments to the script depends on the value of
407 lxc.hook.version. If set to 1 then information is provided in the form
408 of environment variables. If set to 0 information is provided as argu‐
409 ments to the script.
410 Standard output from the script is logged at debug level. Standard
412 error is not logged, but can be captured by the hook redirecting its
413 standard error to standard output.
414 NEW PSEUDO TTY INSTANCE (DEVPTS)
416 For stricter isolation the container can have its own private instance
417 of the pseudo tty.
418 lxc.pty.max
420 If set, the container will have a new pseudo tty instance, mak‐
421 ing this private to it. The value specifies the maximum number
422 of pseudo ttys allowed for a pty instance (this limitation is
423 not implemented yet).
424 CONTAINER SYSTEM CONSOLE
426 If the container is configured with a root filesystem and the inittab
427 file is setup to use the console, you may want to specify where the
428 output of this console goes.
429 lxc.console.buffer.size
431 Setting this option instructs liblxc to allocate an in-memory
432 ringbuffer. The container's console output will be written to
433 the ringbuffer. Note that ringbuffer must be at least as big as
434 a standard page size. When passed a value smaller than a single
435 page size liblxc will allocate a ringbuffer of a single page
436 size. A page size is usually 4KB. The keyword 'auto' will cause
437 liblxc to allocate a ringbuffer of 128KB. When manually speci‐
438 fying a size for the ringbuffer the value should be a power of 2
439 when converted to bytes. Valid size prefixes are 'KB', 'MB',
440 'GB'. (Note that all conversions are based on multiples of 1024.
441 That means 'KB' == 'KiB', 'MB' == 'MiB', 'GB' == 'GiB'. Addi‐
442 tionally, the case of the suffix is ignored, i.e. 'kB', 'KB' and
443 'Kb' are treated equally.)
444 lxc.console.size
446 Setting this option instructs liblxc to place a limit on the
447 size of the console log file specified in lxc.console.logfile.
448 Note that size of the log file must be at least as big as a
449 standard page size. When passed a value smaller than a single
450 page size liblxc will set the size of log file to a single page
451 size. A page size is usually 4KB. The keyword 'auto' will cause
452 liblxc to place a limit of 128KB on the log file. When manually
453 specifying a size for the log file the value should be a power
454 of 2 when converted to bytes. Valid size prefixes are 'KB',
455 'MB', 'GB'. (Note that all conversions are based on multiples of
456 1024. That means 'KB' == 'KiB', 'MB' == 'MiB', 'GB' == 'GiB'.
457 Additionally, the case of the suffix is ignored, i.e. 'kB', 'KB'
458 and 'Kb' are treated equally.) If users want to mirror the con‐
459 sole ringbuffer on disk they should set lxc.console.size equal
460 to lxc.console.buffer.size.
461 lxc.console.logfile
463 Specify a path to a file where the console output will be writ‐
464 ten. Note that in contrast to the on-disk ringbuffer logfile
465 this file will keep growing potentially filling up the users
466 disks if not rotated and deleted. This problem can also be
467 avoided by using the in-memory ringbuffer options lxc.con‐
468 sole.buffer.size and lxc.console.buffer.logfile.
469 lxc.console.rotate
471 Whether to rotate the console logfile specified in lxc.con‐
472 sole.logfile. Users can send an API request to rotate the log‐
473 file. Note that the old logfile will have the same name as the
474 original with the suffix ".1" appended. Users wishing to pre‐
475 vent the console log file from filling the disk should rotate
476 the logfile and delete it if unneeded. This problem can also be
477 avoided by using the in-memory ringbuffer options lxc.con‐
478 sole.buffer.size and lxc.console.buffer.logfile.
479 lxc.console.path
481 Specify a path to a device to which the console will be
482 attached. The keyword 'none' will simply disable the console.
483 Note, when specifying 'none' and creating a device node for the
484 console in the container at /dev/console or bind-mounting the
485 hosts's /dev/console into the container at /dev/console the con‐
486 tainer will have direct access to the hosts's /dev/console.
487 This is dangerous when the container has write access to the
488 device and should thus be used with caution.
489 CONSOLE THROUGH THE TTYS
491 This option is useful if the container is configured with a root
492 filesystem and the inittab file is setup to launch a getty on the ttys.
493 The option specifies the number of ttys to be available for the con‐
494 tainer. The number of gettys in the inittab file of the container
495 should not be greater than the number of ttys specified in this option,
496 otherwise the excess getty sessions will die and respawn indefinitely
497 giving annoying messages on the console or in /var/log/messages.
498 lxc.tty.max
500 Specify the number of tty to make available to the container.
501 CONSOLE DEVICES LOCATION
503 LXC consoles are provided through Unix98 PTYs created on the host and
504 bind-mounted over the expected devices in the container. By default,
505 they are bind-mounted over /dev/console and /dev/ttyN. This can prevent
506 package upgrades in the guest. Therefore you can specify a directory
507 location (under /dev under which LXC will create the files and bind-
508 mount over them. These will then be symbolically linked to /dev/console
509 and /dev/ttyN. A package upgrade can then succeed as it is able to
510 remove and replace the symbolic links.
511 lxc.tty.dir
513 Specify a directory under /dev under which to create the con‐
514 tainer console devices. Note that LXC will move any bind-mounts
515 or device nodes for /dev/console into this directory.
516 /DEV DIRECTORY
518 By default, lxc creates a few symbolic links (fd,stdin,stdout,stderr)
519 in the container's /dev directory but does not automatically create
520 device node entries. This allows the container's /dev to be set up as
521 needed in the container rootfs. If lxc.autodev is set to 1, then after
522 mounting the container's rootfs LXC will mount a fresh tmpfs under /dev
523 (limited to 500K by default, unless defined in lxc.autodev.tmpfs.size)
524 and fill in a minimal set of initial devices. This is generally
525 required when starting a container containing a "systemd" based "init"
526 but may be optional at other times. Additional devices in the contain‐
527 ers /dev directory may be created through the use of the
528 lxc.hook.autodev hook.
529 lxc.autodev
531 Set this to 0 to stop LXC from mounting and populating a minimal
532 /dev when starting the container.
533 lxc.autodev.tmpfs.size
535 Set this to define the size of the /dev tmpfs. The default
536 value is 500000 (500K). If the parameter is used but without
537 value, the default value is used.
538 MOUNT POINTS
540 The mount points section specifies the different places to be mounted.
541 These mount points will be private to the container and won't be visi‐
542 ble by the processes running outside of the container. This is useful
543 to mount /etc, /var or /home for examples.
544 NOTE - LXC will generally ensure that mount targets and relative bind-
546 mount sources are properly confined under the container root, to avoid
547 attacks involving over-mounting host directories and files. (Symbolic
548 links in absolute mount sources are ignored) However, if the container
549 configuration first mounts a directory which is under the control of
550 the container user, such as /home/joe, into the container at some path,
551 and then mounts under path, then a TOCTTOU attack would be possible
552 where the container user modifies a symbolic link under his home direc‐
553 tory at just the right time.
554 lxc.mount.fstab
556 specify a file location in the fstab format, containing the
557 mount information. The mount target location can and in most
558 cases should be a relative path, which will become relative to
559 the mounted container root. For instance,
560 proc proc proc nodev,noexec,nosuid 0 0
562 Will mount a proc filesystem under the container's /proc,
565 regardless of where the root filesystem comes from. This is
566 resilient to block device backed filesystems as well as con‐
567 tainer cloning.
568 Note that when mounting a filesystem from an image file or block
570 device the third field (fs_vfstype) cannot be auto as with
571 mount(8) but must be explicitly specified.
572 lxc.mount.entry
574 Specify a mount point corresponding to a line in the fstab for‐
575 mat. Moreover lxc supports mount propagation, such as rshared
576 or rprivate, and adds three additional mount options. optional
577 don't fail if mount does not work. create=dir or create=file to
578 create dir (or file) when the point will be mounted. relative
579 source path is taken to be relative to the mounted container
580 root. For instance,
581 dev/null proc/kcore none bind,relative 0 0
583 Will expand dev/null to ${LXC_ROOTFS_MOUNT}/dev/null, and mount
586 it to proc/kcore inside the container.
587 lxc.mount.auto
589 specify which standard kernel file systems should be automati‐
590 cally mounted. This may dramatically simplify the configuration.
591 The file systems are:
592 · proc:mixed (or proc): mount /proc as read-write, but remount
594 /proc/sys and /proc/sysrq-trigger read-only for security /
595 container isolation purposes.
596 · proc:rw: mount /proc as read-write
598 · sys:mixed (or sys): mount /sys as read-only but with
600 /sys/devices/virtual/net writable.
601 · sys:ro: mount /sys as read-only for security / container iso‐
603 lation purposes.
604 · sys:rw: mount /sys as read-write
606 · cgroup:mixed: Mount a tmpfs to /sys/fs/cgroup, create directo‐
608 ries for all hierarchies to which the container is added, cre‐
609 ate subdirectories in those hierarchies with the name of the
610 cgroup, and bind-mount the container's own cgroup into that
611 directory. The container will be able to write to its own
612 cgroup directory, but not the parents, since they will be
613 remounted read-only.
614 · cgroup:mixed:force: The force option will cause LXC to perform
616 the cgroup mounts for the container under all circumstances.
617 Otherwise it is similar to cgroup:mixed. This is mainly use‐
618 ful when the cgroup namespaces are enabled where LXC will nor‐
619 mally leave mounting cgroups to the init binary of the con‐
620 tainer since it is perfectly safe to do so.
621 · cgroup:ro: similar to cgroup:mixed, but everything will be
623 mounted read-only.
624 · cgroup:ro:force: The force option will cause LXC to perform
626 the cgroup mounts for the container under all circumstances.
627 Otherwise it is similar to cgroup:ro. This is mainly useful
628 when the cgroup namespaces are enabled where LXC will normally
629 leave mounting cgroups to the init binary of the container
630 since it is perfectly safe to do so.
631 · cgroup:rw: similar to cgroup:mixed, but everything will be
633 mounted read-write. Note that the paths leading up to the con‐
634 tainer's own cgroup will be writable, but will not be a cgroup
635 filesystem but just part of the tmpfs of /sys/fs/cgroup
636 · cgroup:rw:force: The force option will cause LXC to perform
638 the cgroup mounts for the container under all circumstances.
639 Otherwise it is similar to cgroup:rw. This is mainly useful
640 when the cgroup namespaces are enabled where LXC will normally
641 leave mounting cgroups to the init binary of the container
642 since it is perfectly safe to do so.
643 · cgroup (without specifier): defaults to cgroup:rw if the con‐
645 tainer retains the CAP_SYS_ADMIN capability, cgroup:mixed oth‐
646 erwise.
647 · cgroup-full:mixed: mount a tmpfs to /sys/fs/cgroup, create
649 directories for all hierarchies to which the container is
650 added, bind-mount the hierarchies from the host to the con‐
651 tainer and make everything read-only except the container's
652 own cgroup. Note that compared to cgroup, where all paths
653 leading up to the container's own cgroup are just simple
654 directories in the underlying tmpfs, here
655 /sys/fs/cgroup/$hierarchy will contain the host's full cgroup
656 hierarchy, albeit read-only outside the container's own
657 cgroup. This may leak quite a bit of information into the
658 container.
659 · cgroup-full:mixed:force: The force option will cause LXC to
661 perform the cgroup mounts for the container under all circum‐
662 stances. Otherwise it is similar to cgroup-full:mixed. This
663 is mainly useful when the cgroup namespaces are enabled where
664 LXC will normally leave mounting cgroups to the init binary of
665 the container since it is perfectly safe to do so.
666 · cgroup-full:ro: similar to cgroup-full:mixed, but everything
668 will be mounted read-only.
669 · cgroup-full:ro:force: The force option will cause LXC to per‐
671 form the cgroup mounts for the container under all circum‐
672 stances. Otherwise it is similar to cgroup-full:ro. This is
673 mainly useful when the cgroup namespaces are enabled where LXC
674 will normally leave mounting cgroups to the init binary of the
675 container since it is perfectly safe to do so.
676 · cgroup-full:rw: similar to cgroup-full:mixed, but everything
678 will be mounted read-write. Note that in this case, the con‐
679 tainer may escape its own cgroup. (Note also that if the con‐
680 tainer has CAP_SYS_ADMIN support and can mount the cgroup
681 filesystem itself, it may do so anyway.)
682 · cgroup-full:rw:force: The force option will cause LXC to per‐
684 form the cgroup mounts for the container under all circum‐
685 stances. Otherwise it is similar to cgroup-full:rw. This is
686 mainly useful when the cgroup namespaces are enabled where LXC
687 will normally leave mounting cgroups to the init binary of the
688 container since it is perfectly safe to do so.
689 · cgroup-full (without specifier): defaults to cgroup-full:rw if
691 the container retains the CAP_SYS_ADMIN capability,
692 cgroup-full:mixed otherwise.
693 If cgroup namespaces are enabled, then any cgroup auto-mounting request
695 will be ignored, since the container can mount the filesystems itself,
696 and automounting can confuse the container init.
697 Note that if automatic mounting of the cgroup filesystem is enabled,
699 the tmpfs under /sys/fs/cgroup will always be mounted read-write (but
700 for the :mixed and :ro cases, the individual hierarchies,
701 /sys/fs/cgroup/$hierarchy, will be read-only). This is in order to work
702 around a quirk in Ubuntu's mountall(8) command that will cause contain‐
703 ers to wait for user input at boot if /sys/fs/cgroup is mounted read-
704 only and the container can't remount it read-write due to a lack of
705 CAP_SYS_ADMIN.
706 Examples:
708 lxc.mount.auto = proc sys cgroup
710 lxc.mount.auto = proc:rw sys:rw cgroup-full:rw
711 ROOT FILE SYSTEM
714 The root file system of the container can be different than that of the
715 host system.
716 lxc.rootfs.path
718 specify the root file system for the container. It can be an
719 image file, a directory or a block device. If not specified, the
720 container shares its root file system with the host.
721 For directory or simple block-device backed containers, a path‐
723 name can be used. If the rootfs is backed by a nbd device, then
724 nbd:file:1 specifies that file should be attached to a nbd
725 device, and partition 1 should be mounted as the rootfs.
726 nbd:file specifies that the nbd device itself should be mounted.
727 overlayfs:/lower:/upper specifies that the rootfs should be an
728 overlay with /upper being mounted read-write over a read-only
729 mount of /lower. For overlay multiple /lower directories can be
730 specified. loop:/file tells lxc to attach /file to a loop device
731 and mount the loop device.
732 lxc.rootfs.mount
734 where to recursively bind lxc.rootfs.path before pivoting. This
735 is to ensure success of the pivot_root(8) syscall. Any directory
736 suffices, the default should generally work.
737 lxc.rootfs.options
739 extra mount options to use when mounting the rootfs.
740 lxc.rootfs.managed
742 Set this to 0 to indicate that LXC is not managing the container
743 storage, then LXC will not modify the container storage. The
744 default is 1.
745 CONTROL GROUP
747 The control group section contains the configuration for the different
748 subsystem. lxc does not check the correctness of the subsystem name.
749 This has the disadvantage of not detecting configuration errors until
750 the container is started, but has the advantage of permitting any
751 future subsystem.
752 lxc.cgroup.[controller name]
754 Specify the control group value to be set on a legacy cgroup
755 hierarchy. The controller name is the literal name of the con‐
756 trol group. The permitted names and the syntax of their values
757 is not dictated by LXC, instead it depends on the features of
758 the Linux kernel running at the time the container is started,
759 eg. lxc.cgroup.cpuset.cpus
760 lxc.cgroup2.[controller name]
762 Specify the control group value to be set on the unified cgroup
763 hierarchy. The controller name is the literal name of the con‐
764 trol group. The permitted names and the syntax of their values
765 is not dictated by LXC, instead it depends on the features of
766 the Linux kernel running at the time the container is started,
767 eg. lxc.cgroup2.memory.high
768 lxc.cgroup.dir
770 specify a directory or path in which the container's cgroup will
771 be created. For example, setting lxc.cgroup.dir =
772 my-cgroup/first for a container named "c1" will create the con‐
773 tainer's cgroup as a sub-cgroup of "my-cgroup". For example, if
774 the user's current cgroup "my-user" is located in the root
775 cgroup of the cpuset controller in a cgroup v1 hierarchy this
776 would create the cgroup "/sys/fs/cgroup/cpuset/my-user/my-
777 cgroup/first/c1" for the container. Any missing cgroups will be
778 created by LXC. This presupposes that the user has write access
779 to its current cgroup.
780 lxc.cgroup.relative
782 Set this to 1 to instruct LXC to never escape to the root
783 cgroup. This makes it easy for users to adhere to restrictions
784 enforced by cgroup2 and systemd. Specifically, this makes it
785 possible to run LXC containers as systemd services.
786 CAPABILITIES
788 The capabilities can be dropped in the container if this one is run as
789 root.
790 lxc.cap.drop
792 Specify the capability to be dropped in the container. A single
793 line defining several capabilities with a space separation is
794 allowed. The format is the lower case of the capability defini‐
795 tion without the "CAP_" prefix, eg. CAP_SYS_MODULE should be
796 specified as sys_module. See capabilities(7). If used with no
797 value, lxc will clear any drop capabilities specified up to this
798 point.
799 lxc.cap.keep
801 Specify the capability to be kept in the container. All other
802 capabilities will be dropped. When a special value of "none" is
803 encountered, lxc will clear any keep capabilities specified up
804 to this point. A value of "none" alone can be used to drop all
805 capabilities.
806 NAMESPACES
808 A namespace can be cloned (lxc.namespace.clone), kept (lxc.names‐
809 pace.keep) or shared (lxc.namespace.share.[namespace identifier]).
810 lxc.namespace.clone
812 Specify namespaces which the container is supposed to be created
813 with. The namespaces to create are specified as a space sepa‐
814 rated list. Each namespace must correspond to one of the stan‐
815 dard namespace identifiers as seen in the /proc/PID/ns direc‐
816 tory. When lxc.namespace.clone is not explicitly set all names‐
817 paces supported by the kernel and the current configuration will
818 be used.
819 To create a new mount, net and ipc namespace set lxc.names‐
821 pace.clone=mount net ipc.
822 lxc.namespace.keep
824 Specify namespaces which the container is supposed to inherit
825 from the process that created it. The namespaces to keep are
826 specified as a space separated list. Each namespace must corre‐
827 spond to one of the standard namespace identifiers as seen in
828 the /proc/PID/ns directory. The lxc.namespace.keep is a
829 denylist option, i.e. it is useful when enforcing that contain‐
830 ers must keep a specific set of namespaces.
831 To keep the network, user and ipc namespace set lxc.names‐
833 pace.keep=user net ipc.
834 Note that sharing pid namespaces will likely not work with most
836 init systems.
837 Note that if the container requests a new user namespace and the
839 container wants to inherit the network namespace it needs to
840 inherit the user namespace as well.
841 lxc.namespace.share.[namespace identifier]
843 Specify a namespace to inherit from another container or
844 process. The [namespace identifier] suffix needs to be replaced
845 with one of the namespaces that appear in the /proc/PID/ns
846 directory.
847 To inherit the namespace from another process set the lxc.names‐
849 pace.share.[namespace identifier] to the PID of the process,
850 e.g. lxc.namespace.share.net=42.
851 To inherit the namespace from another container set the
853 lxc.namespace.share.[namespace identifier] to the name of the
854 container, e.g. lxc.namespace.share.pid=c3.
855 To inherit the namespace from another container located in a
857 different path than the standard liblxc path set the lxc.names‐
858 pace.share.[namespace identifier] to the full path to the con‐
859 tainer, e.g. lxc.namespace.share.user=/opt/c3.
860 In order to inherit namespaces the caller needs to have suffi‐
862 cient privilege over the process or container.
863 Note that sharing pid namespaces between system containers will
865 likely not work with most init systems.
866 Note that if two processes are in different user namespaces and
868 one process wants to inherit the other's network namespace it
869 usually needs to inherit the user namespace as well.
870 Note that without careful additional configuration of an LSM,
872 sharing user+pid namespaces with a task may allow that task to
873 escalate privileges to that of the task calling liblxc.
874 RESOURCE LIMITS
876 The soft and hard resource limits for the container can be changed.
877 Unprivileged containers can only lower them. Resources which are not
878 explicitly specified will be inherited.
879 lxc.prlimit.[limit name]
881 Specify the resource limit to be set. A limit is specified as
882 two colon separated values which are either numeric or the word
883 'unlimited'. A single value can be used as a shortcut to set
884 both soft and hard limit to the same value. The permitted names
885 the "RLIMIT_" resource names in lowercase without the "RLIMIT_"
886 prefix, eg. RLIMIT_NOFILE should be specified as "nofile". See
887 setrlimit(2). If used with no value, lxc will clear the
888 resource limit specified up to this point. A resource with no
889 explicitly configured limitation will be inherited from the
890 process starting up the container.
891 SYSCTL
893 Configure kernel parameters for the container.
894 lxc.sysctl.[kernel parameters name]
896 Specify the kernel parameters to be set. The parameters avail‐
897 able are those listed under /proc/sys/. Note that not all
898 sysctls are namespaced. Changing Non-namespaced sysctls will
899 cause the system-wide setting to be modified. sysctl(8). If
900 used with no value, lxc will clear the parameters specified up
901 to this point.
902 APPARMOR PROFILE
904 If lxc was compiled and installed with apparmor support, and the host
905 system has apparmor enabled, then the apparmor profile under which the
906 container should be run can be specified in the container configura‐
907 tion. The default is lxc-container-default-cgns if the host kernel is
908 cgroup namespace aware, or lxc-container-default otherwise.
909 lxc.apparmor.profile
911 Specify the apparmor profile under which the container should be
912 run. To specify that the container should be unconfined, use
913 lxc.apparmor.profile = unconfined
915 If the apparmor profile should remain unchanged (i.e. if you are
917 nesting containers and are already confined), then use
918 lxc.apparmor.profile = unchanged
920 If you instruct LXC to generate the apparmor profile, then use
922 lxc.apparmor.profile = generated
924 lxc.apparmor.allow_incomplete
926 Apparmor profiles are pathname based. Therefore many file
927 restrictions require mount restrictions to be effective against
928 a determined attacker. However, these mount restrictions are not
929 yet implemented in the upstream kernel. Without the mount
930 restrictions, the apparmor profiles still protect against acci‐
931 dental damager.
932 If this flag is 0 (default), then the container will not be
934 started if the kernel lacks the apparmor mount features, so that
935 a regression after a kernel upgrade will be detected. To start
936 the container under partial apparmor protection, set this flag
937 to 1.
938 lxc.apparmor.allow_nesting
940 If set this to 1, causes the following changes. When generated
941 apparmor profiles are used, they will contain the necessary
942 changes to allow creating a nested container. In addition to the
943 usual mount points, /dev/.lxc/proc and /dev/.lxc/sys will con‐
944 tain procfs and sysfs mount points without the lxcfs overlays,
945 which, if generated apparmor profiles are being used, will not
946 be read/writable directly.
947 lxc.apparmor.raw
949 A list of raw AppArmor profile lines to append to the profile.
950 Only valid when using generated profiles.
951 SELINUX CONTEXT
953 If lxc was compiled and installed with SELinux support, and the host
954 system has SELinux enabled, then the SELinux context under which the
955 container should be run can be specified in the container configura‐
956 tion. The default is unconfined_t, which means that lxc will not
957 attempt to change contexts. See /usr/share/lxc/selinux/lxc.te for an
958 example policy and more information.
959 lxc.selinux.context
961 Specify the SELinux context under which the container should be
962 run or unconfined_t. For example
963 lxc.selinux.context = system_u:system_r:lxc_t:s0:c22
965 lxc.selinux.context.keyring
967 Specify the SELinux context under which the container's keyring
968 should be created. By default this the same as lxc.selinux.con‐
969 text, or the context lxc is executed under if lxc.selinux.con‐
970 text has not been set.
971 lxc.selinux.context.keyring = system_u:system_r:lxc_t:s0:c22
973 KERNEL KEYRING
975 The Linux Keyring facility is primarily a way for various kernel compo‐
976 nents to retain or cache security data, authentication keys, encryption
977 keys, and other data in the kernel. By default lxc will create a new
978 session keyring for the started application.
979 lxc.keyring.session
981 Disable the creation of new session keyring by lxc. The started
982 application will then inherit the current session keyring. By
983 default, or when passing the value 1, a new keyring will be cre‐
984 ated.
985 lxc.keyring.session = 0
987 SECCOMP CONFIGURATION
989 A container can be started with a reduced set of available system calls
990 by loading a seccomp profile at startup. The seccomp configuration file
991 must begin with a version number on the first line, a policy type on
992 the second line, followed by the configuration.
993 Versions 1 and 2 are currently supported. In version 1, the policy is a
995 simple allowlist. The second line therefore must read "allowlist", with
996 the rest of the file containing one (numeric) syscall number per line.
997 Each syscall number is allowlisted, while every unlisted number is
998 denylisted for use in the container
999 In version 2, the policy may be denylist or allowlist, supports per-
1001 rule and per-policy default actions, and supports per-architecture sys‐
1002 tem call resolution from textual names.
1003 An example denylist policy, in which all system calls are allowed
1005 except for mknod, which will simply do nothing and return 0 (success),
1006 looks like:
1007 2
1009 denylist
1010 mknod errno 0
1011 ioctl notify
1012 Specifying "errno" as action will cause LXC to register a seccomp fil‐
1015 ter that will cause a specific errno to be returned to the caller. The
1016 errno value can be specified after the "errno" action word.
1017 Specifying "notify" as action will cause LXC to register a seccomp lis‐
1019 tener and retrieve a listener file descriptor from the kernel. When a
1020 syscall is made that is registered as "notify" the kernel will generate
1021 a poll event and send a message over the file descriptor. The caller
1022 can read this message, inspect the syscalls including its arguments.
1023 Based on this information the caller is expected to send back a message
1024 informing the kernel which action to take. Until that message is sent
1025 the kernel will block the calling process. The format of the messages
1026 to read and sent is documented in seccomp itself.
1027 lxc.seccomp.profile
1029 Specify a file containing the seccomp configuration to load
1030 before the container starts.
1031 lxc.seccomp.allow_nesting
1033 If this flag is set to 1, then seccomp filters will be stacked
1034 regardless of whether a seccomp profile is already loaded. This
1035 allows nested containers to load their own seccomp profile. The
1036 default setting is 0.
1037 lxc.seccomp.notify.proxy
1039 Specify a unix socket to which LXC will connect and forward sec‐
1040 comp events to. The path must be in the form
1041 unix:/path/to/socket or unix:@socket. The former specifies a
1042 path-bound unix domain socket while the latter specifies an
1043 abstract unix domain socket.
1044 lxc.seccomp.notify.cookie
1046 An additional string sent along with proxied seccomp notifica‐
1047 tion requests.
1048 PR_SET_NO_NEW_PRIVS
1050 With PR_SET_NO_NEW_PRIVS active execve() promises not to grant privi‐
1051 leges to do anything that could not have been done without the execve()
1052 call (for example, rendering the set-user-ID and set-group-ID mode
1053 bits, and file capabilities non-functional). Once set, this bit cannot
1054 be unset. The setting of this bit is inherited by children created by
1055 fork() and clone(), and preserved across execve(). Note that
1056 PR_SET_NO_NEW_PRIVS is applied after the container has changed into its
1057 intended AppArmor profile or SElinux context.
1058 lxc.no_new_privs
1060 Specify whether the PR_SET_NO_NEW_PRIVS flag should be set for
1061 the container. Set to 1 to activate.
1062 UID MAPPINGS
1064 A container can be started in a private user namespace with user and
1065 group id mappings. For instance, you can map userid 0 in the container
1066 to userid 200000 on the host. The root user in the container will be
1067 privileged in the container, but unprivileged on the host. Normally a
1068 system container will want a range of ids, so you would map, for
1069 instance, user and group ids 0 through 20,000 in the container to the
1070 ids 200,000 through 220,000.
1071 lxc.idmap
1073 Four values must be provided. First a character, either 'u', or
1074 'g', to specify whether user or group ids are being mapped. Next
1075 is the first userid as seen in the user namespace of the con‐
1076 tainer. Next is the userid as seen on the host. Finally, a range
1077 indicating the number of consecutive ids to map.
1078 CONTAINER HOOKS
1080 Container hooks are programs or scripts which can be executed at vari‐
1081 ous times in a container's lifetime.
1082 When a container hook is executed, additional information is passed
1084 along. The lxc.hook.version argument can be used to determine if the
1085 following arguments are passed as command line arguments or through
1086 environment variables. The arguments are:
1087 · Container name.
1089 · Section (always 'lxc').
1091 · The hook type (i.e. 'clone' or 'pre-mount').
1093 · Additional arguments. In the case of the clone hook, any extra argu‐
1095 ments passed will appear as further arguments to the hook. In the
1096 case of the stop hook, paths to filedescriptors for each of the con‐
1097 tainer's namespaces along with their types are passed.
1098 The following environment variables are set:
1100 · LXC_CGNS_AWARE: indicator whether the container is cgroup namespace
1102 aware.
1103 · LXC_CONFIG_FILE: the path to the container configuration file.
1105 · LXC_HOOK_TYPE: the hook type (e.g. 'clone', 'mount', 'pre-mount').
1107 Note that the existence of this environment variable is conditional
1108 on the value of lxc.hook.version. If it is set to 1 then
1109 LXC_HOOK_TYPE will be set.
1110 · LXC_HOOK_SECTION: the section type (e.g. 'lxc', 'net'). Note that the
1112 existence of this environment variable is conditional on the value of
1113 lxc.hook.version. If it is set to 1 then LXC_HOOK_SECTION will be
1114 set.
1115 · LXC_HOOK_VERSION: the version of the hooks. This value is identical
1117 to the value of the container's lxc.hook.version config item. If it
1118 is set to 0 then old-style hooks are used. If it is set to 1 then
1119 new-style hooks are used.
1120 · LXC_LOG_LEVEL: the container's log level.
1122 · LXC_NAME: is the container's name.
1124 · LXC_[NAMESPACE IDENTIFIER]_NS: path under /proc/PID/fd/ to a file
1126 descriptor referring to the container's namespace. For each preserved
1127 namespace type there will be a separate environment variable. These
1128 environment variables will only be set if lxc.hook.version is set to
1129 1.
1130 · LXC_ROOTFS_MOUNT: the path to the mounted root filesystem.
1132 · LXC_ROOTFS_PATH: this is the lxc.rootfs.path entry for the container.
1134 Note this is likely not where the mounted rootfs is to be found, use
1135 LXC_ROOTFS_MOUNT for that.
1136 · LXC_SRC_NAME: in the case of the clone hook, this is the original
1138 container's name.
1139 Standard output from the hooks is logged at debug level. Standard
1141 error is not logged, but can be captured by the hook redirecting its
1142 standard error to standard output.
1143 lxc.hook.version
1145 To pass the arguments in new style via environment variables set
1146 to 1 otherwise set to 0 to pass them as arguments. This setting
1147 affects all hooks arguments that were traditionally passed as
1148 arguments to the script. Specifically, it affects the container
1149 name, section (e.g. 'lxc', 'net') and hook type (e.g. 'clone',
1150 'mount', 'pre-mount') arguments. If new-style hooks are used
1151 then the arguments will be available as environment variables.
1152 The container name will be set in LXC_NAME. (This is set inde‐
1153 pendently of the value used for this config item.) The section
1154 will be set in LXC_HOOK_SECTION and the hook type will be set in
1155 LXC_HOOK_TYPE. It also affects how the paths to file descrip‐
1156 tors referring to the container's namespaces are passed. If set
1157 to 1 then for each namespace a separate environment variable
1158 LXC_[NAMESPACE IDENTIFIER]_NS will be set. If set to 0 then the
1159 paths will be passed as arguments to the stop hook.
1160 lxc.hook.pre-start
1162 A hook to be run in the host's namespace before the container
1163 ttys, consoles, or mounts are up.
1164 lxc.hook.pre-mount
1166 A hook to be run in the container's fs namespace but before the
1167 rootfs has been set up. This allows for manipulation of the
1168 rootfs, i.e. to mount an encrypted filesystem. Mounts done in
1169 this hook will not be reflected on the host (apart from mounts
1170 propagation), so they will be automatically cleaned up when the
1171 container shuts down.
1172 lxc.hook.mount
1174 A hook to be run in the container's namespace after mounting has
1175 been done, but before the pivot_root.
1176 lxc.hook.autodev
1178 A hook to be run in the container's namespace after mounting has
1179 been done and after any mount hooks have run, but before the
1180 pivot_root, if lxc.autodev == 1. The purpose of this hook is to
1181 assist in populating the /dev directory of the container when
1182 using the autodev option for systemd based containers. The con‐
1183 tainer's /dev directory is relative to the ${LXC_ROOTFS_MOUNT}
1184 environment variable available when the hook is run.
1185 lxc.hook.start-host
1187 A hook to be run in the host's namespace after the container has
1188 been setup, and immediately before starting the container init.
1189 lxc.hook.start
1191 A hook to be run in the container's namespace immediately before
1192 executing the container's init. This requires the program to be
1193 available in the container.
1194 lxc.hook.stop
1196 A hook to be run in the host's namespace with references to the
1197 container's namespaces after the container has been shut down.
1198 For each namespace an extra argument is passed to the hook con‐
1199 taining the namespace's type and a filename that can be used to
1200 obtain a file descriptor to the corresponding namespace, sepa‐
1201 rated by a colon. The type is the name as it would appear in the
1202 /proc/PID/ns directory. For instance for the mount namespace
1203 the argument usually looks like mnt:/proc/PID/fd/12.
1204 lxc.hook.post-stop
1206 A hook to be run in the host's namespace after the container has
1207 been shut down.
1208 lxc.hook.clone
1210 A hook to be run when the container is cloned to a new one. See
1211 lxc-clone(1) for more information.
1212 lxc.hook.destroy
1214 A hook to be run when the container is destroyed.
1215 CONTAINER HOOKS ENVIRONMENT VARIABLES
1217 A number of environment variables are made available to the startup
1218 hooks to provide configuration information and assist in the function‐
1219 ing of the hooks. Not all variables are valid in all contexts. In par‐
1220 ticular, all paths are relative to the host system and, as such, not
1221 valid during the lxc.hook.start hook.
1222 LXC_NAME
1224 The LXC name of the container. Useful for logging messages in
1225 common log environments. [-n]
1226 LXC_CONFIG_FILE
1228 Host relative path to the container configuration file. This
1229 gives the container to reference the original, top level, con‐
1230 figuration file for the container in order to locate any addi‐
1231 tional configuration information not otherwise made available.
1232 [-f]
1233 LXC_CONSOLE
1235 The path to the console output of the container if not NULL.
1236 [-c] [lxc.console.path]
1237 LXC_CONSOLE_LOGPATH
1239 The path to the console log output of the container if not NULL.
1240 [-L]
1241 LXC_ROOTFS_MOUNT
1243 The mount location to which the container is initially bound.
1244 This will be the host relative path to the container rootfs for
1245 the container instance being started and is where changes should
1246 be made for that instance. [lxc.rootfs.mount]
1247 LXC_ROOTFS_PATH
1249 The host relative path to the container root which has been
1250 mounted to the rootfs.mount location. [lxc.rootfs.path]
1251 LXC_SRC_NAME
1253 Only for the clone hook. Is set to the original container name.
1254 LXC_TARGET
1256 Only for the stop hook. Is set to "stop" for a container shut‐
1257 down or "reboot" for a container reboot.
1258 LXC_CGNS_AWARE
1260 If unset, then this version of lxc is not aware of cgroup names‐
1261 paces. If set, it will be set to 1, and lxc is aware of cgroup
1262 namespaces. Note this does not guarantee that cgroup namespaces
1263 are enabled in the kernel. This is used by the lxcfs mount hook.
1264 LOGGING
1266 Logging can be configured on a per-container basis. By default, depend‐
1267 ing upon how the lxc package was compiled, container startup is logged
1268 only at the ERROR level, and logged to a file named after the container
1269 (with '.log' appended) either under the container path, or under
1270 /var/log/lxc.
1271 Both the default log level and the log file can be specified in the
1273 container configuration file, overriding the default behavior. Note
1274 that the configuration file entries can in turn be overridden by the
1275 command line options to lxc-start.
1276 lxc.log.level
1278 The level at which to log. The log level is an integer in the
1279 range of 0..8 inclusive, where a lower number means more verbose
1280 debugging. In particular 0 = trace, 1 = debug, 2 = info, 3 =
1281 notice, 4 = warn, 5 = error, 6 = critical, 7 = alert, and 8 =
1282 fatal. If unspecified, the level defaults to 5 (error), so that
1283 only errors and above are logged.
1284 Note that when a script (such as either a hook script or a net‐
1286 work interface up or down script) is called, the script's stan‐
1287 dard output is logged at level 1, debug.
1288 lxc.log.file
1290 The file to which logging info should be written.
1291 lxc.log.syslog
1293 Send logging info to syslog. It respects the log level defined
1294 in lxc.log.level. The argument should be the syslog facility to
1295 use, valid ones are: daemon, local0, local1, local2, local3,
1296 local4, local5, local5, local6, local7.
1297 AUTOSTART
1299 The autostart options support marking which containers should be auto-
1300 started and in what order. These options may be used by LXC tools
1301 directly or by external tooling provided by the distributions.
1302 lxc.start.auto
1304 Whether the container should be auto-started. Valid values are
1305 0 (off) and 1 (on).
1306 lxc.start.delay
1308 How long to wait (in seconds) after the container is started
1309 before starting the next one.
1310 lxc.start.order
1312 An integer used to sort the containers when auto-starting a
1313 series of containers at once. A lower value means an earlier
1314 start.
1315 lxc.monitor.unshare
1317 If not zero the mount namespace will be unshared from the host
1318 before initializing the container (before running any pre-start
1319 hooks). This requires the CAP_SYS_ADMIN capability at startup.
1320 Default is 0.
1321 lxc.monitor.signal.pdeath
1323 Set the signal to be sent to the container's init when the lxc
1324 monitor exits. By default it is set to SIGKILL which will cause
1325 all container processes to be killed when the lxc monitor
1326 process dies. To ensure that containers stay alive even if lxc
1327 monitor dies set this to 0.
1328 lxc.group
1330 A multi-value key (can be used multiple times) to put the con‐
1331 tainer in a container group. Those groups can then be used
1332 (amongst other things) to start a series of related containers.
1333 AUTOSTART AND SYSTEM BOOT
1335 Each container can be part of any number of groups or no group at all.
1336 Two groups are special. One is the NULL group, i.e. the container does
1337 not belong to any group. The other group is the "onboot" group.
1338 When the system boots with the LXC service enabled, it will first
1340 attempt to boot any containers with lxc.start.auto == 1 that is a mem‐
1341 ber of the "onboot" group. The startup will be in order of
1342 lxc.start.order. If an lxc.start.delay has been specified, that delay
1343 will be honored before attempting to start the next container to give
1344 the current container time to begin initialization and reduce overload‐
1345 ing the host system. After starting the members of the "onboot" group,
1346 the LXC system will proceed to boot containers with lxc.start.auto == 1
1347 which are not members of any group (the NULL group) and proceed as with
1348 the onboot group.
1349 CONTAINER ENVIRONMENT
1351 If you want to pass environment variables into the container (that is,
1352 environment variables which will be available to init and all of its
1353 descendents), you can use lxc.environment parameters to do so. Be care‐
1354 ful that you do not pass in anything sensitive; any process in the con‐
1355 tainer which doesn't have its environment scrubbed will have these
1356 variables available to it, and environment variables are always avail‐
1357 able via /proc/PID/environ.
1358 This configuration parameter can be specified multiple times; once for
1360 each environment variable you wish to configure.
1361 lxc.environment
1363 Specify an environment variable to pass into the container.
1364 Example:
1365 lxc.environment = APP_ENV=production
1367 lxc.environment = SYSLOG_SERVER=192.0.2.42
1368 It is possible to inherit host environment variables by setting
1371 the name of the variable without a "=" sign. For example:
1372 lxc.environment = PATH
1374
1377 In addition to the few examples given below, you will find some other
1378 examples of configuration file in /usr/share/doc/lxc/examples
1379 NETWORK
1381 This configuration sets up a container to use a veth pair device with
1382 one side plugged to a bridge br0 (which has been configured before on
1383 the system by the administrator). The virtual network device visible in
1384 the container is renamed to eth0.
1385 lxc.uts.name = myhostname
1387 lxc.net.0.type = veth
1388 lxc.net.0.flags = up
1389 lxc.net.0.link = br0
1390 lxc.net.0.name = eth0
1391 lxc.net.0.hwaddr = 4a:49:43:49:79:bf
1392 lxc.net.0.ipv4.address = 10.2.3.5/24 10.2.3.255
1393 lxc.net.0.ipv6.address = 2003:db8:1:0:214:1234:fe0b:3597
1394 UID/GID MAPPING
1397 This configuration will map both user and group ids in the range 0-9999
1398 in the container to the ids 100000-109999 on the host.
1399 lxc.idmap = u 0 100000 10000
1401 lxc.idmap = g 0 100000 10000
1402 CONTROL GROUP
1405 This configuration will setup several control groups for the applica‐
1406 tion, cpuset.cpus restricts usage of the defined cpu, cpus.share prior‐
1407 itize the control group, devices.allow makes usable the specified
1408 devices.
1409 lxc.cgroup.cpuset.cpus = 0,1
1411 lxc.cgroup.cpu.shares = 1234
1412 lxc.cgroup.devices.deny = a
1413 lxc.cgroup.devices.allow = c 1:3 rw
1414 lxc.cgroup.devices.allow = b 8:0 rw
1415 COMPLEX CONFIGURATION
1418 This example show a complex configuration making a complex network
1419 stack, using the control groups, setting a new hostname, mounting some
1420 locations and a changing root file system.
1421 lxc.uts.name = complex
1423 lxc.net.0.type = veth
1424 lxc.net.0.flags = up
1425 lxc.net.0.link = br0
1426 lxc.net.0.hwaddr = 4a:49:43:49:79:bf
1427 lxc.net.0.ipv4.address = 10.2.3.5/24 10.2.3.255
1428 lxc.net.0.ipv6.address = 2003:db8:1:0:214:1234:fe0b:3597
1429 lxc.net.0.ipv6.address = 2003:db8:1:0:214:5432:feab:3588
1430 lxc.net.1.type = macvlan
1431 lxc.net.1.flags = up
1432 lxc.net.1.link = eth0
1433 lxc.net.1.hwaddr = 4a:49:43:49:79:bd
1434 lxc.net.1.ipv4.address = 10.2.3.4/24
1435 lxc.net.1.ipv4.address = 192.168.10.125/24
1436 lxc.net.1.ipv6.address = 2003:db8:1:0:214:1234:fe0b:3596
1437 lxc.net.2.type = phys
1438 lxc.net.2.flags = up
1439 lxc.net.2.link = dummy0
1440 lxc.net.2.hwaddr = 4a:49:43:49:79:ff
1441 lxc.net.2.ipv4.address = 10.2.3.6/24
1442 lxc.net.2.ipv6.address = 2003:db8:1:0:214:1234:fe0b:3297
1443 lxc.cgroup.cpuset.cpus = 0,1
1444 lxc.cgroup.cpu.shares = 1234
1445 lxc.cgroup.devices.deny = a
1446 lxc.cgroup.devices.allow = c 1:3 rw
1447 lxc.cgroup.devices.allow = b 8:0 rw
1448 lxc.mount.fstab = /etc/fstab.complex
1449 lxc.mount.entry = /lib /root/myrootfs/lib none ro,bind 0 0
1450 lxc.rootfs.path = dir:/mnt/rootfs.complex
1451 lxc.cap.drop = sys_module mknod setuid net_raw
1452 lxc.cap.drop = mac_override
1453
1456 chroot(1), pivot_root(8), fstab(5), capabilities(7)
1457
1459 lxc(7), lxc-create(1), lxc-copy(1), lxc-destroy(1), lxc-start(1), lxc-
1460 stop(1), lxc-execute(1), lxc-console(1), lxc-monitor(1), lxc-wait(1),
1461 lxc-cgroup(1), lxc-ls(1), lxc-info(1), lxc-freeze(1), lxc-unfreeze(1),
1462 lxc-attach(1), lxc.conf(5)
1463
1465 Daniel Lezcano <daniel.lezcano@free.fr>
1466 2021-01-18 lxc.container.conf(5)