You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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?).
Related to recent discussion around punting to the kernel [1,2],
although in this case we're not changing the JSON Schema because the
existing local validation (valid 'type' characters and the 'fileMode'
range) both feed into a single mode_t integer in the stat(3) and
mknod(2) APIs. For a cleaner kernel punt, we could drop 'type', lift
the range limit on 'fileMode', and map it directly to st.st_mode. But
that seemed like a big backwards-compat shift for this commit.
[1]: #780
[2]: #690 (comment)
Signed-off-by: W. Trevor King <[email protected]>
Copy file name to clipboardExpand all lines: config-linux.md
+27-7Lines changed: 27 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -110,21 +110,37 @@ Note that the number of mapping entries MAY be limited by the [kernel][user-name
110
110
## <aname="configLinuxDevices" />Devices
111
111
112
112
**`devices`** (array of objects, OPTIONAL) lists devices that MUST be available in the container.
113
-
The runtime may supply them however it likes (with [mknod][mknod.2], by bind mounting from the runtime mount namespace, etc.).
113
+
The runtime MAY supply them however it likes (with [`mknod(2)`][mknod.2], by bind mounting from the runtime mount namespace, etc.).
114
114
115
115
Each entry has the following structure:
116
116
117
-
***`type`***(string, REQUIRED)* - type of device: `c`, `b`, `u` or `p`.
118
-
More info in [mknod(1)][mknod.1].
119
-
***`path`***(string, REQUIRED)* - full path to device inside container.
117
+
***`path`***(string, REQUIRED)* - full path to device inside container, with relative paths anchored at the container's [root](config.md#root).
120
118
If a [file][] already exists at `path` that does not match the requested device, the runtime MUST generate an error.
121
-
***`major, minor`***(int64, REQUIRED unless `type` is `p`)* - [major, minor numbers][devices] for the device.
119
+
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.
120
+
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).
121
+
***`type`***(string, REQUIRED)* - type of device.
122
+
This configures the type returned by [`st.st_mode | S_IFMT`][sys/stat.h], which MUST have the following value:
123
+
124
+
| Configured value | Stat value |
125
+
| ---------------- | ----------------------- |
126
+
|`c`|[`S_IFCHR`][sys/stat.h]|
127
+
|`b`|[`S_IFBLK`][sys/stat.h]|
128
+
|`u`|[`S_IFCHR`][sys/stat.h]|
129
+
|`p`|[`S_IFIFO`][sys/stat.h]|
130
+
131
+
The configuration MUST use a value from the above table.
132
+
***`major, minor`***(int64, OPTIONAL)* - [major, minor numbers][devices] for the device.
133
+
Calling [`major(3)` or `minor(3)`][major.3] on [`st.st_dev`][sys/stat.h] MUST match the configured value.
122
134
***`fileMode`***(uint32, OPTIONAL)* - file mode for the device.
135
+
[`st.st_mode | 0777`][sys/stat.h] MUST match the configured value.
123
136
You can also control access to devices [with cgroups](#device-whitelist).
124
-
***`uid`***(uint32, OPTIONAL)* - id of device owner.
125
-
***`gid`***(uint32, OPTIONAL)* - id of device group.
137
+
***`uid`***(uint32, OPTIONAL)* - User ID of the device.
138
+
`st.uid_t` MUST match the configured value.
139
+
***`gid`***(uint32, OPTIONAL)* - Group ID for the device.
140
+
`st.gid_t` MUST match the configured value.
126
141
127
142
The same `type`, `major` and `minor` SHOULD NOT be used for multiple devices.
143
+
The same `path` SHOULD NOT be used for multiple devices; if it is, only the final entry for a given `path` applies.
128
144
129
145
### Example
130
146
@@ -648,17 +664,21 @@ The following parameters can be specified to set up seccomp:
0 commit comments