From 7090c875823e47fca8674d886de8cbf6d685f7a0 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Fri, 7 Aug 2015 09:23:43 -0700 Subject: [PATCH 1/5] config-linux: Replace 'Next' with 'The following' for device parameters I think this reads more clearly. Signed-off-by: W. Trevor King --- config-linux.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config-linux.md b/config-linux.md index bc1924824..7576b0ea7 100644 --- a/config-linux.md +++ b/config-linux.md @@ -56,7 +56,7 @@ within the container. ### Access to devices Devices is an array specifying the list of devices to be created in the container. -Next parameters can be specified: +The following parameters can be specified: * type - type of device: 'c', 'b', 'u' or 'p'. More info in `man mknod` * path - full path to device inside container From 171bb170e0a6160bee1a7b5c35a8a7ea31894a03 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Fri, 7 Aug 2015 09:26:56 -0700 Subject: [PATCH 2/5] config-linux: Replace 'man mknod' references with links to mknod(1) These are easier to follow, since folks viewing the spec in a browser won't need to open a terminal. It also makes the man-page section explicit (there are also mknod pages in sections 2 [1] and 3p [2]). [1]: http://man7.org/linux/man-pages/man2/mknod.2.html [2]: https://www.kernel.org/pub/linux/docs/man-pages/man-pages-posix/man-pages-posix-2013-a.tar.xz Signed-off-by: W. Trevor King --- config-linux.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/config-linux.md b/config-linux.md index 7576b0ea7..daeabef13 100644 --- a/config-linux.md +++ b/config-linux.md @@ -58,9 +58,9 @@ within the container. Devices is an array specifying the list of devices to be created in the container. The following parameters can be specified: -* type - type of device: 'c', 'b', 'u' or 'p'. More info in `man mknod` +* type - type of device: 'c', 'b', 'u' or 'p'. More info in [mknod(1)][] * path - full path to device inside container -* major, minor - major, minor numbers for device. More info in `man mknod`. +* major, minor - major, minor numbers for device. More info in [mknod(1)][]. There is special value: `-1`, which means `*` for `device` cgroup setup. * permissions - cgroup permissions for device. A composition of 'r' @@ -212,3 +212,4 @@ rootfsPropagation sets the rootfs's mount propagation. Its value is either slave **TODO:** security profiles +[mknod(1)]: http://man7.org/linux/man-pages/man1/mknod.1.html From 5d90eec4e2c9a5c817606209b3e787c1cad123bb Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Fri, 7 Aug 2015 09:54:12 -0700 Subject: [PATCH 3/5] config-linux: Re-wrap device parameter list with one sentence per-line To match README.md#markdown-style. Signed-off-by: W. Trevor King --- config-linux.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/config-linux.md b/config-linux.md index daeabef13..0abbe65b4 100644 --- a/config-linux.md +++ b/config-linux.md @@ -58,13 +58,14 @@ within the container. Devices is an array specifying the list of devices to be created in the container. The following parameters can be specified: -* type - type of device: 'c', 'b', 'u' or 'p'. More info in [mknod(1)][] +* type - type of device: 'c', 'b', 'u' or 'p'. + More info in [mknod(1)][] * path - full path to device inside container -* major, minor - major, minor numbers for device. More info in [mknod(1)][]. - There is special value: `-1`, which means `*` for `device` - cgroup setup. -* permissions - cgroup permissions for device. A composition of 'r' - (read), 'w' (write), and 'm' (mknod). +* major, minor - major, minor numbers for device. + More info in [mknod(1)][]. + There is special value: `-1`, which means `*` for `device` cgroup setup. +* permissions - cgroup permissions for device. + A composition of 'r' (read), 'w' (write), and 'm' (mknod). * fileMode - file mode for device file * uid - uid of device owner * gid - gid of device owner From 4b7a061735e01efde37a4ae1fa5213b6f6505f28 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Fri, 7 Aug 2015 09:40:57 -0700 Subject: [PATCH 4/5] config-linux: Reorder device types (b, c, u, p) This groups the two character devices (c and u) together, and matches the order in which mknod(1) lists them. Signed-off-by: W. Trevor King --- config-linux.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config-linux.md b/config-linux.md index 0abbe65b4..f8d067934 100644 --- a/config-linux.md +++ b/config-linux.md @@ -58,7 +58,7 @@ within the container. Devices is an array specifying the list of devices to be created in the container. The following parameters can be specified: -* type - type of device: 'c', 'b', 'u' or 'p'. +* type - type of device: 'b', 'c', 'u' or 'p'. More info in [mknod(1)][] * path - full path to device inside container * major, minor - major, minor numbers for device. From 3236c2698d53387a692f542e0952b6de0c3c5b68 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Fri, 7 Aug 2015 10:08:28 -0700 Subject: [PATCH 5/5] config-linux: Explicitly document mknod/cgroups overloading I'd prefer to handle mknod and device cgroups independently [1,2], to avoid all this "If path is given..." and "If parameters is given..." special casing. But the overloaded approach has landed [3], so this commit documents the indended semantics [4]. I'm not sure how bundle authors are supposed to register deny cgroups rules [5]. [1]: https://github.com/opencontainers/specs/pull/98 [2]: https://github.com/opencontainers/specs/pull/99 [3]: https://github.com/opencontainers/specs/pull/94#event-375826110 [4]: https://github.com/opencontainers/specs/pull/94#issuecomment-128548345 [5]: https://github.com/opencontainers/specs/pull/94#issuecomment-128760375 Signed-off-by: W. Trevor King --- config-linux.md | 42 +++++++++++++++++++++++++++--------------- 1 file changed, 27 insertions(+), 15 deletions(-) diff --git a/config-linux.md b/config-linux.md index f8d067934..3e93fc787 100644 --- a/config-linux.md +++ b/config-linux.md @@ -55,29 +55,45 @@ within the container. ### Access to devices -Devices is an array specifying the list of devices to be created in the container. +Devices is an array specifying both devices to be created in the container, and any device control group rules that should be applied. The following parameters can be specified: -* type - type of device: 'b', 'c', 'u' or 'p'. - More info in [mknod(1)][] -* path - full path to device inside container +* type - type of device: 'a', 'b', 'c', 'u' or 'p'. + Required. + If path is given, only 'b', 'c', 'u', and 'p' are allowed (more info in [mknod(1)][]). + If permissions is given, only 'a', 'b', and 'c' are allowed (more info in the [cgroups devices documentation][cgroups-devices]). +* path - full path to device inside container. + Optional. + If not given, the entry only creates a cgroups allow rule. * major, minor - major, minor numbers for device. More info in [mknod(1)][]. - There is special value: `-1`, which means `*` for `device` cgroup setup. + There is special value: `-1`, which uses the wildcard `*` for the cgroups rule. + If `-1` is used, path, uid, fileMode, uid, and gid are not allowed. + Required. * permissions - cgroup permissions for device. - A composition of 'r' (read), 'w' (write), and 'm' (mknod). -* fileMode - file mode for device file -* uid - uid of device owner -* gid - gid of device owner + A composition of 'r' (read), 'w' (write), and 'm' (mknod) (more info in the [cgroups devices documentation][cgroups-devices]). + Optional. + If not given, the entry only creates the device node with mknod. +* fileMode - file mode for device file. + Required if path is given, otherwise not allowed. +* uid - uid of device owner. + Required if path is given, otherwise not allowed. +* gid - gid of device owner. + Required if path is given, otherwise not allowed. ```json "devices": [ + { + "type": "a", + "major": -1, + "minor": -1, + "permissions": "rwm", + }, { "path": "/dev/random", "type": "c", "major": 1, "minor": 8, - "permissions": "rwm", "fileMode": 0666, "uid": 0, "gid": 0 @@ -87,7 +103,6 @@ The following parameters can be specified: "type": "c", "major": 1, "minor": 9, - "permissions": "rwm", "fileMode": 0666, "uid": 0, "gid": 0 @@ -97,7 +112,6 @@ The following parameters can be specified: "type": "c", "major": 1, "minor": 3, - "permissions": "rwm", "fileMode": 0666, "uid": 0, "gid": 0 @@ -107,7 +121,6 @@ The following parameters can be specified: "type": "c", "major": 1, "minor": 5, - "permissions": "rwm", "fileMode": 0666, "uid": 0, "gid": 0 @@ -117,7 +130,6 @@ The following parameters can be specified: "type": "c", "major": 5, "minor": 0, - "permissions": "rwm", "fileMode": 0666, "uid": 0, "gid": 0 @@ -127,7 +139,6 @@ The following parameters can be specified: "type": "c", "major": 1, "minor": 7, - "permissions": "rwm", "fileMode": 0666, "uid": 0, "gid": 0 @@ -214,3 +225,4 @@ rootfsPropagation sets the rootfs's mount propagation. Its value is either slave **TODO:** security profiles [mknod(1)]: http://man7.org/linux/man-pages/man1/mknod.1.html +[cgroups-devices]: https://www.kernel.org/doc/Documentation/cgroups/devices.txt