conf: add cgroup2, cgroup2:ro, cgroup2:force, cgroup2:ro:force options

[mirror_lxc.git] / doc / api-extensions.md

diff --git a/doc/api-extensions.md b/doc/api-extensions.md
index 89909228a8202a66cf4cc58d95ec1a0c92d12316..0e9c724e82a58426ff3bbf32de0a4ba0a6850233 100644 (file)
--- a/doc/api-extensions.md
+++ b/doc/api-extensions.md
@@ -96,28 +96,67 @@ This is primarily intended for use with layer 3 networking devices, such as IPVL
 This introduces the ability to specify a custom MTU for `phys` and `macvlan` devices using the
 `lxc.net.[i].mtu` property.
 
-# network\_veth\_router
+## network\_veth\_router
 
-This introduces the ability to specify a `lxc.net.[i].veth.mode` setting, which takes a value of
-"bridge" or "router". This defaults to "bridge".
+This introduces the ability to specify a `lxc.net.[i].veth.mode` setting, which takes a value of "bridge" or "router". This defaults to "bridge".
 
-In "router" mode static routes are created on the host for the container's IP addresses pointing to
-the host side veth interface. In addition to the routes, a static IP neighbour proxy is added to
-the host side veth interface for the IPv4 and IPv6 gateway IPs.
+In "router" mode static routes are created on the host for the container's IP addresses pointing to the host side veth interface. In addition to the routes, a static IP neighbour proxy is added to the host side veth interface for the IPv4 and IPv6 gateway IPs.
 
 
-# cgroup2\_devices
+## cgroup2\_devices
 
 This enables `LXC` to make use of the new devices controller in the unified cgroup hierarchy. `LXC` will now create, load, and attach bpf program to the cgroup of the container when the controller is available.
 
-# cgroup2
+## cgroup2
 
 This enables `LXC` to make complete use of the unified cgroup hierarchy. With this extension it is possible to run `LXC` containers on systems that use a pure unified cgroup layout.
 
-# init\_pidfd
+## init\_pidfd
 
-This adds a new API function `init_pidfd()` which allows to retrieve a pidfd for the container's init process allowing process management interactions such as sending signal to be completely reliable and rac-e free.
+This adds a new API function `init_pidfd()` which allows one to retrieve a pidfd for the container's init process allowing process management interactions such as sending signals to be completely reliable and race free.
 
-# pidfd
+## pidfd
 
 When running on kernels that support pidfds LXC will rely on them for most operations. This makes interacting with containers not just more reliable it also makes it significantly safer and eliminates various races inherent to PID-based kernel APIs. LXC will require that the running kernel at least support `pidfd_send_signal()`, `CLONE_PIDFD`, `P_PIDFD`, and pidfd polling support. Any kernel starting with `Linux 5.4` should have full support for pidfds.
+
+## cgroup\_advanced\_isolation
+
+Privileged containers will usually be able to override the cgroup limits given to them. This introduces three new configuration keys `lxc.cgroup.dir.monitor`, `lxc.cgroup.dir.container`, and `lxc.cgroup.dir.container.inner`. The `lxc.cgroup.dir.monitor` and `lxc.cgroup.dir.container` keys can be used to set to place the `monitor` and the `container` into different cgroups. The `lxc.cgroup.dir.container.inner` key can be set to a cgroup that is concatenated with `lxc.cgroup.dir.container`. When `lxc.cgroup.dir.container.inner` is set the container will be placed into the `lxc.cgroup.dir.container.inner` cgroup but the limits will be set in the `lxc.cgroup.dir.container` cgroup. This way privileged containers cannot escape their cgroup limits.
+
+
+## time\_namespace
+
+This adds time namespace support to LXC.
+
+## seccomp\_allow\_deny\_syntax
+
+This adds the ability to use "denylist" and "allowlist" in seccomp v2 policies.
+
+## devpts\_fd
+
+This adds the ability to allocate a file descriptor for the devpts instance of
+the container.
+
+## seccomp\_notify\_fd\_active
+
+Retrieve the seccomp notifier fd from a running container.
+
+## seccomp\_proxy\_send\_notify\_fd
+
+Whether the seccomp notify proxy sends a long a notify fd file descriptor.
+
+## idmapped\_mounts
+
+Whether this LXC instance can handle idmapped mounts for the rootfs.
+
+## idmapped\_mounts\_v2
+
+Whether this LXC instance can handle idmapped mounts for lxc.mount.entry
+entries.
+
+## cgroup2\_auto_mounting
+
+This adds the new options `cgroup2`, `cgroup2:ro`, `cgroup2:force`,
+`cgroup2:ro:force` for the `lxc.mount.auto` configuration key. For example, if
+a user specifies `cgroup2:force` LXC will pre-mount a pure `cgroup2` layout for
+the container even if the host is running with a hybrid layout.