config-linux: Clearer punt to kernel for linux.devices

This is a bit awkward, since:

* It's not a direct wrapper around mknod(2) (which, for example, does
  not use the c/b/u/p characters).
* The runtime doesn't have to use mknod, so binding it to mknod(1)-ish
  invocations doesn't make much sense.

Instead, I've bound it to POSIX's stat(3) to show what compliance
testing (and anything else inside the container) can expect the
results (however the runtime accomplishes them) to look like.

The previous wording wasn't clear on whether symlinks were an allowed
approach.  The new wording explicitly allows them by using
stat(1)-like symlink resolution.

I've also clarified relative 'path' handling and explicitly declared
the appropriate mount namespace (impacts 'path') and PID namespace
(impacts 'uid' and 'gid').

Because we're focused on post-create stat calls, I've also added new
wording about handling duplicate 'path' values.

I've used POSIX reference where possible (vs. Linux man pages),
because they contain sufficient detail for this section, have
well-versioned URLs, and are more likely to be portable if this
section ever applies to non-Linux configs (BSD?  Solaris?).

Despite the backticks, I have to escape the pipe in the table header
to get GitHub to render it correctly.  I'm not sure what GitHub uses
to render Markdown, but marked has a similar issue [1].

[1]: markedjs/marked#285

Signed-off-by: W. Trevor King <[email protected]>

Author: wking

config-linux.md

@@ -110,21 +110,37 @@ Note that the number of mapping entries MAY be limited by the [kernel][user-name
 ## <a name="configLinuxDevices" />Devices
 
 **`devices`** (array of objects, OPTIONAL) lists devices that MUST be available in the container.
-The runtime may supply them however it likes (with [mknod][mknod.2], by bind mounting from the runtime mount namespace, etc.).
+The runtime MAY supply them however it likes (with [`mknod(2)`][mknod.2], by bind mounting from the runtime mount namespace, etc.).
 
 Each entry has the following structure:
 
-* **`type`** *(string, REQUIRED)* - type of device: `c`, `b`, `u` or `p`.
-  More info in [mknod(1)][mknod.1].
-* **`path`** *(string, REQUIRED)* - full path to device inside container.
-  If a [file][] already exists at `path` that does not match the requested device, the runtime MUST generate an error.
-* **`major, minor`** *(int64, REQUIRED unless `type` is `p`)* - [major, minor numbers][devices] for the device.
+* **`path`** *(string, REQUIRED)* - full path to device inside container, with relative paths anchored at the container's [root](config.md#root).
+    If a [file][] already exists at `path` that does not match the requested device, the runtime MUST generate an error.
+    For each entry, a [`stat(3)`][stat.3] on `path` executed with `/` as the [working directory][working-directory] in [container's mount and PID namespaces](glossary.md#container-namespace) MUST succeed.
+    For the following properties, `st` refers to the status returned after recursively calling `stat(3)` to traverse any symlinks (where [`.st_mode | S_IFLNK`][sys/stat.h] is set).
+* **`type`** *(string, REQUIRED)* - type of device.
+    This configures the type returned by [`st.st_mode | S_IFMT`][sys/stat.h], which MUST have the following value:
+
+    | Configured value | Stat value              |
+    | ---------------- | ----------------------- |
+    | `c`              | [`S_IFCHR`][sys/stat.h] |
+    | `b`              | [`S_IFBLK`][sys/stat.h] |
+    | `u`              | [`S_IFCHR`][sys/stat.h] |
+    | `p`              | [`S_IFIFO`][sys/stat.h] |
+
+    The configuration MUST use a value from the above table.
+* **`major, minor`** *(int64, OPTIONAL)* - [major, minor numbers][devices] for the device.
+    Calling [`major(3)` or `minor(3)`][major.3] on [`st.st_dev`][sys/stat.h] MUST match the configured value.
 * **`fileMode`** *(uint32, OPTIONAL)* - file mode for the device.
-  You can also control access to devices [with cgroups](#device-whitelist).
-* **`uid`** *(uint32, OPTIONAL)* - id of device owner.
-* **`gid`** *(uint32, OPTIONAL)* - id of device group.
+    [`st.st_mode | 0777`][sys/stat.h] MUST match the configured value.
+    You can also control access to devices [with cgroups](#device-whitelist).
+* **`uid`** *(uint32, OPTIONAL)* - User ID of the device.
+    `st.uid_t` MUST match the configured value.
+* **`gid`** *(uint32, OPTIONAL)* - Group ID for the device.
+    `st.gid_t` MUST match the configured value.
 
 The same `type`, `major` and `minor` SHOULD NOT be used for multiple devices.
+The same `path` SHOULD NOT be used for multiple devices; if it is, only the final entry for a given `path` applies.
 
 ###### Example
 
@@ -667,17 +683,21 @@ The values MUST be absolute paths in the [container namespace](glossary.md#conta
 [procfs]: https://www.kernel.org/doc/Documentation/filesystems/proc.txt
 [seccomp]: https://www.kernel.org/doc/Documentation/prctl/seccomp_filter.txt
 [sharedsubtree]: https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt
+[sys/stat.h]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_stat.h.html
 [sysfs]: https://www.kernel.org/doc/Documentation/filesystems/sysfs.txt
 [tmpfs]: https://www.kernel.org/doc/Documentation/filesystems/tmpfs.txt
+[working-directory]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_447
 
 [console.4]: http://man7.org/linux/man-pages/man4/console.4.html
 [full.4]: http://man7.org/linux/man-pages/man4/full.4.html
+[major.3]: http://man7.org/linux/man-pages/man3/major.3.html
 [mknod.1]: http://man7.org/linux/man-pages/man1/mknod.1.html
 [mknod.2]: http://man7.org/linux/man-pages/man2/mknod.2.html
 [namespaces.7_2]: http://man7.org/linux/man-pages/man7/namespaces.7.html
 [null.4]: http://man7.org/linux/man-pages/man4/null.4.html
 [pts.4]: http://man7.org/linux/man-pages/man4/pts.4.html
 [random.4]: http://man7.org/linux/man-pages/man4/random.4.html
+[stat.3]: http://pubs.opengroup.org/onlinepubs/9699919799/functions/stat.html
 [sysctl.8]: http://man7.org/linux/man-pages/man8/sysctl.8.html
 [tty.4]: http://man7.org/linux/man-pages/man4/tty.4.html
 [zero.4]: http://man7.org/linux/man-pages/man4/zero.4.html