From 5a7ee3a48ff17fc46c8556ca28d0c3fa56ca0beb Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Fri, 19 May 2017 12:26:54 -0700 Subject: [PATCH] config-linux: RFC 2119 wording for linux.resources.devices Since ce55de25 (Remove range limit which depend on kernel, 2017-04-26, #780), the spec has been more aggressively punting to the kernel APIs (vs. carrying local versions of kernel limitations). For the properties touched by this commit, a pull request to reflect our old valid values (e.g. requiring 'type' to match ^[acb]$) was rejected as part of this punting approach. However, before this commit, it wasn't clear exactly what kernel interface was being punted to. With this commit, we replace the old inline docs with an explicit punt to the device whitelist controller, listing the exact actions that the runtime MUST take for given config values. This allows for compliance-testing runtimes [2] (ensuring config portability between compliant runtimes) and makes it possible to validate a given config against a given kernel (e.g. Linux 4.11.1 only accepts 'a', 'b', and 'c' as type characters [3]). [1]: https://github.com/opencontainers/runtime-spec/pull/690#issuecomment-282824774 [2]: https://github.com/opencontainers/runtime-spec/issues/746 [3]: https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git/tree/security/device_cgroup.c?h=v4.11.1#n618 Signed-off-by: W. Trevor King --- config-linux.md | 27 +++++++++++++++++++++------ 1 file changed, 21 insertions(+), 6 deletions(-) diff --git a/config-linux.md b/config-linux.md index d457184e4..12761ade4 100644 --- a/config-linux.md +++ b/config-linux.md @@ -211,21 +211,30 @@ Runtimes MAY attach the container process to additional cgroup controllers beyon ### Device whitelist -**`devices`** (array of objects, OPTIONAL) configures the [device whitelist][cgroup-v1-devices]. -The runtime MUST apply entries in the listed order. +**`devices`** (array of objects, OPTIONAL) configures the [device whitelist controller][cgroup-v1-devices] at [`cgroupsPath`](#control-groups). Each entry has the following structure: * **`allow`** *(boolean, REQUIRED)* - whether the entry is allowed or denied. -* **`type`** *(string, OPTIONAL)* - type of device: `a` (all), `c` (char), or `b` (block). - Unset values mean "all", mapping to `a`. + The line for this entry is: + + > {type} {major}:{minor} {access} + + When true, the runtime MUST write that to `devices.allow`. + When false, the runtime MUST write that line to `devices.deny`. +* **`type`** *(string, OPTIONAL)* - type of device. + Defaults to `a`. * **`major, minor`** *(int64, OPTIONAL)* - [major, minor numbers][devices] for the device. - Unset values mean "all", mapping to [`*` in the filesystem API][cgroup-v1-devices]. + Defaults to `*`. * **`access`** *(string, OPTIONAL)* - cgroup permissions for device. - A composition of `r` (read), `w` (write), and `m` (mknod). + Defaults to `rwm`. + +The runtime MUST NOT write any other lines to either `devices.allow` or `devices.deny`. #### Example +The configuration: + ```json "devices": [ { @@ -249,6 +258,12 @@ Each entry has the following structure: ] ``` +would result in the runtime writting the following lines: + +* `a *:* rwm` to `devices.deny` +* `c 10:229 rw` to `devices.allow` +* `b 8:0 r` to `devices.allow` + ### Disable out-of-memory killer `disableOOMKiller` contains a boolean (`true` or `false`) that enables or disables the Out of Memory killer for a cgroup.