config-linux: RFC 2119 wording for linux.resources.devices

Since ce55de2 (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]: #690 (comment)
[2]: #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 <[email protected]>

Author: wking

config-linux.md

@@ -211,21 +211,30 @@ Runtimes MAY attach the container process to additional cgroup controllers beyon
 
 ### <a name="configLinuxDeviceWhitelist" />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`
+
 ### <a name="configLinuxDisableOutOfMemoryKiller" />Disable out-of-memory killer
 
 `disableOOMKiller` contains a boolean (`true` or `false`) that enables or disables the Out of Memory killer for a cgroup.