Additional documentation for overloaded mknod / cgroups in linux.devices #101
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
I think this reads more clearly. Signed-off-by: W. Trevor King <wking@tremily.us>
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 <wking@tremily.us>
To match README.md#markdown-style. Signed-off-by: W. Trevor King <wking@tremily.us>
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 <wking@tremily.us>
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]: opencontainers#98 [2]: opencontainers#99 [3]: opencontainers#94 (comment) [4]: opencontainers#94 (comment) [5]: opencontainers#94 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>
Contributor
Author
|
Discussing this with @LK4D4 on IRC, I think if we want full cgroups handling here, we'll want to add a new {"type": "a", "allow": false, "major": -1, "minor": -1, "permissions": "rwm"}to block all devices. @LK4D4 also prefers blocking all devices by default, but the above rule is easy enough to write that I'd prefer the default to be “don't touch device cgroups”. |
Contributor
Author
|
Oh, and this PR doesn't touch the Go type comments and whatnot. It's just for discussing the Markdown documentation. Once we reach a consensus there, I'll go back and update the Go comments. |
2 tasks
This was referenced Sep 6, 2015
Member
There was a problem hiding this comment.
why did u delete these lines?
Contributor
Author
There was a problem hiding this comment.
On Mon, Oct 05, 2015 at 11:09:18AM -0700, Michael Crosby wrote:
"path": "/dev/random", "type": "c", "major": 1, "minor": 8,
"permissions": "rwm",why did u delete these lines?
My first device entry set rwm permissions for all major/minor types,
so there's no need to repeat that in the later entries.
Member
|
Lets not make any additional changes if the real issues that people are having are with the creation and permissions being in one field. This was split before and added alot of verbosity but we can revisit a better way if it's an issue. Lets discuss on the mailing list. |
Contributor
Author
|
On Mon, Oct 05, 2015 at 11:46:54AM -0700, Michael Crosby wrote:
Spun off into https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/y_Fsa2_jJaM |
wking
added a commit
to wking/opencontainer-runtime-spec
that referenced
this pull request
Jan 12, 2016
With mknod entries in linux.devices and cgroups entries in linux.resources.devices. For specifying device cgroups independent of device creation. This makes it easy to distinguish between configs that call for cgroup adjustments (which have linux.resources entries) from those that don't. Without this split, folks interested in making that distinction would have to parse the device section to determine if it included cgroup changes. Using seperate sections for mknod and cgroups also allows us to avoid the complicated validation rules needed for the combined format mknod/cgroup [1]. Now that there is a section specific to supplying devices, I shifted the default device listing over from config-linux. The /dev/ptmx entry is a bit awkward, since it's not a device, but it seemed to fit better over here. But I would also be fine leaving it with the other mounts in config-linux. The reference links are sorted into two blocks, with kernel-doc links sorted alphabetically followed by man pages sorted alphabetically by section. [1]: opencontainers#101 Signed-off-by: W. Trevor King <wking@tremily.us>
wking
added a commit
to wking/opencontainer-runtime-spec
that referenced
this pull request
Jan 12, 2016
With mknod entries in linux.devices and cgroups entries in linux.resources.devices. For specifying device cgroups independent of device creation. This makes it easy to distinguish between configs that call for cgroup adjustments (which have linux.resources entries) from those that don't. Without this split, folks interested in making that distinction would have to parse the device section to determine if it included cgroup changes. Using seperate sections for mknod and cgroups also allows us to avoid the complicated validation rules needed for the combined format mknod/cgroup [1]. Now that there is a section specific to supplying devices, I shifted the default device listing over from config-linux. The /dev/ptmx entry is a bit awkward, since it's not a device, but it seemed to fit better over here. But I would also be fine leaving it with the other mounts in config-linux. The reference links are sorted into two blocks, with kernel-doc links sorted alphabetically followed by man pages sorted alphabetically by section. [1]: opencontainers#101 Signed-off-by: W. Trevor King <wking@tremily.us>
wking
added a commit
to wking/opencontainer-runtime-spec
that referenced
this pull request
Jan 12, 2016
With mknod entries in linux.devices and cgroups entries in linux.resources.devices. For specifying device cgroups independent of device creation. This makes it easy to distinguish between configs that call for cgroup adjustments (which have linux.resources entries) from those that don't. Without this split, folks interested in making that distinction would have to parse the device section to determine if it included cgroup changes. Using seperate sections for mknod and cgroups also allows us to avoid the complicated validation rules needed for the combined format mknod/cgroup [1]. Now that there is a section specific to supplying devices, I shifted the default device listing over from config-linux. The /dev/ptmx entry is a bit awkward, since it's not a device, but it seemed to fit better over here. But I would also be fine leaving it with the other mounts in config-linux. The reference links are sorted into two blocks, with kernel-doc links sorted alphabetically followed by man pages sorted alphabetically by section. [1]: opencontainers#101 Signed-off-by: W. Trevor King <wking@tremily.us>
wking
added a commit
to wking/opencontainer-runtime-spec
that referenced
this pull request
Jan 12, 2016
With mknod entries in linux.devices and cgroups entries in linux.resources.devices. Background discussion in [1]. For specifying device cgroups independent of device creation. This makes it easy to distinguish between configs that call for cgroup adjustments (which have linux.resources entries) from those that don't. Without this split, folks interested in making that distinction would have to parse the device section to determine if it included cgroup changes. This will also make it easy to drop either portion (mknod [2] or cgroups [3]) independently of the other if the project decides to do so. Using seperate sections for mknod and cgroups also allows us to avoid the complicated validation rules needed for the combined format mknod/cgroup [4]. Now that there is a section specific to supplying devices, I shifted the default device listing over from config-linux [5]. The /dev/ptmx entry is a bit awkward, since it's not a device, but it seemed to fit better over here. But I would also be fine leaving it with the other mounts in config-linux. The reference links are sorted into two blocks, with kernel-doc links sorted alphabetically followed by man pages sorted alphabetically by section. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/y_Fsa2_jJaM Subject: Separate config entries for device mknod and cgroups? Date: Mon, 5 Oct 2015 12:46:55 -0700 Message-ID: <20151005194655.GN28418@odin.tremily.us> [2]: opencontainers#98 [3]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/qWHoKs8Fsrk Subject: removal of cgroups from the OCI Linux spec Date: Wed, 28 Oct 2015 17:01:59 +0000 Message-ID: <CAD2oYtO1RMCcUp52w-xXemzDTs+J6t4hS5Mm4mX+uBnVONGDfA@mail.gmail.com> [4]: opencontainers#101 [5]: opencontainers#171 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>
wking
added a commit
to wking/opencontainer-runtime-spec
that referenced
this pull request
Jan 20, 2016
With mknod entries in linux.devices and cgroups entries in linux.resources.devices. Background discussion in [1]. For specifying device cgroups independent of device creation. This makes it easy to distinguish between configs that call for cgroup adjustments (which have linux.resources entries) from those that don't. Without this split, folks interested in making that distinction would have to parse the device section to determine if it included cgroup changes. This will also make it easy to drop either portion (mknod [2] or cgroups [3]) independently of the other if the project decides to do so. Using seperate sections for mknod and cgroups also allows us to avoid the complicated validation rules needed for the combined format mknod/cgroup [4]. Now that there is a section specific to supplying devices, I shifted the default device listing over from config-linux [5]. The /dev/ptmx entry is a bit awkward, since it's not a device, but it seemed to fit better over here. But I would also be fine leaving it with the other mounts in config-linux. The reference links are sorted into two blocks, with kernel-doc links sorted alphabetically followed by man pages sorted alphabetically by section. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/y_Fsa2_jJaM Subject: Separate config entries for device mknod and cgroups? Date: Mon, 5 Oct 2015 12:46:55 -0700 Message-ID: <20151005194655.GN28418@odin.tremily.us> [2]: opencontainers#98 [3]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/qWHoKs8Fsrk Subject: removal of cgroups from the OCI Linux spec Date: Wed, 28 Oct 2015 17:01:59 +0000 Message-ID: <CAD2oYtO1RMCcUp52w-xXemzDTs+J6t4hS5Mm4mX+uBnVONGDfA@mail.gmail.com> [4]: opencontainers#101 [5]: opencontainers#171 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>
wking
added a commit
to wking/opencontainer-runtime-spec
that referenced
this pull request
Jan 27, 2016
With mknod entries in linux.devices and cgroups entries in linux.resources.devices. Background discussion in [1]. For specifying device cgroups independent of device creation. This makes it easy to distinguish between configs that call for cgroup adjustments (which have linux.resources entries) from those that don't. Without this split, folks interested in making that distinction would have to parse the device section to determine if it included cgroup changes. This will also make it easy to drop either portion (mknod [2] or cgroups [3]) independently of the other if the project decides to do so. Using seperate sections for mknod and cgroups also allows us to avoid the complicated validation rules needed for the combined format mknod/cgroup [4]. Now that there is a section specific to supplying devices, I shifted the default device listing over from config-linux [5]. The /dev/ptmx entry is a bit awkward, since it's not a device, but it seemed to fit better over here. But I would also be fine leaving it with the other mounts in config-linux. The reference links are sorted into two blocks, with kernel-doc links sorted alphabetically followed by man pages sorted alphabetically by section. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/y_Fsa2_jJaM Subject: Separate config entries for device mknod and cgroups? Date: Mon, 5 Oct 2015 12:46:55 -0700 Message-ID: <20151005194655.GN28418@odin.tremily.us> [2]: opencontainers#98 [3]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/qWHoKs8Fsrk Subject: removal of cgroups from the OCI Linux spec Date: Wed, 28 Oct 2015 17:01:59 +0000 Message-ID: <CAD2oYtO1RMCcUp52w-xXemzDTs+J6t4hS5Mm4mX+uBnVONGDfA@mail.gmail.com> [4]: opencontainers#101 [5]: opencontainers#171 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>
wking
added a commit
to wking/opencontainer-runtime-spec
that referenced
this pull request
Jan 27, 2016
With mknod entries in linux.devices and cgroups entries in linux.resources.devices. Background discussion in [1]. For specifying device cgroups independent of device creation. This makes it easy to distinguish between configs that call for cgroup adjustments (which have linux.resources entries) from those that don't. Without this split, folks interested in making that distinction would have to parse the device section to determine if it included cgroup changes. This will also make it easy to drop either portion (mknod [2] or cgroups [3]) independently of the other if the project decides to do so. Using seperate sections for mknod and cgroups also allows us to avoid the complicated validation rules needed for the combined format mknod/cgroup [4]. Now that there is a section specific to supplying devices, I shifted the default device listing over from config-linux [5]. The /dev/ptmx entry is a bit awkward, since it's not a device, but it seemed to fit better over here. But I would also be fine leaving it with the other mounts in config-linux. The reference links are sorted into two blocks, with kernel-doc links sorted alphabetically followed by man pages sorted alphabetically by section. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/y_Fsa2_jJaM Subject: Separate config entries for device mknod and cgroups? Date: Mon, 5 Oct 2015 12:46:55 -0700 Message-ID: <20151005194655.GN28418@odin.tremily.us> [2]: opencontainers#98 [3]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/qWHoKs8Fsrk Subject: removal of cgroups from the OCI Linux spec Date: Wed, 28 Oct 2015 17:01:59 +0000 Message-ID: <CAD2oYtO1RMCcUp52w-xXemzDTs+J6t4hS5Mm4mX+uBnVONGDfA@mail.gmail.com> [4]: opencontainers#101 [5]: opencontainers#171 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>
wking
added a commit
to wking/opencontainer-runtime-spec
that referenced
this pull request
Jan 27, 2016
With mknod entries in linux.devices and cgroups entries in linux.resources.devices. Background discussion in [1]. For specifying device cgroups independent of device creation. This makes it easy to distinguish between configs that call for cgroup adjustments (which have linux.resources entries) from those that don't. Without this split, folks interested in making that distinction would have to parse the device section to determine if it included cgroup changes. This will also make it easy to drop either portion (mknod [2] or cgroups [3]) independently of the other if the project decides to do so. Using seperate sections for mknod and cgroups also allows us to avoid the complicated validation rules needed for the combined format mknod/cgroup [4]. Now that there is a section specific to supplying devices, I shifted the default device listing over from config-linux [5]. The /dev/ptmx entry is a bit awkward, since it's not a device, but it seemed to fit better over here. But I would also be fine leaving it with the other mounts in config-linux. The reference links are sorted into two blocks, with kernel-doc links sorted alphabetically followed by man pages sorted alphabetically by section. The cgroup link is new since 2016-01-13 [6]. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/y_Fsa2_jJaM Subject: Separate config entries for device mknod and cgroups? Date: Mon, 5 Oct 2015 12:46:55 -0700 Message-ID: <20151005194655.GN28418@odin.tremily.us> [2]: opencontainers#98 [3]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/qWHoKs8Fsrk Subject: removal of cgroups from the OCI Linux spec Date: Wed, 28 Oct 2015 17:01:59 +0000 Message-ID: <CAD2oYtO1RMCcUp52w-xXemzDTs+J6t4hS5Mm4mX+uBnVONGDfA@mail.gmail.com> [4]: opencontainers#101 [5]: opencontainers#171 (comment) [6]: https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=34a9304a96d6351c2d35dcdc9293258378fc0bd8 Signed-off-by: W. Trevor King <wking@tremily.us>
wking
added a commit
to wking/opencontainer-runtime-spec
that referenced
this pull request
Jan 27, 2016
With mknod entries in linux.devices and cgroups entries in linux.resources.devices. Background discussion in [1]. For specifying device cgroups independent of device creation. This makes it easy to distinguish between configs that call for cgroup adjustments (which have linux.resources entries) from those that don't. Without this split, folks interested in making that distinction would have to parse the device section to determine if it included cgroup changes. This will also make it easy to drop either portion (mknod [2] or cgroups [3]) independently of the other if the project decides to do so. Using seperate sections for mknod and cgroups also allows us to avoid the complicated validation rules needed for the combined format mknod/cgroup [4]. Now that there is a section specific to supplying devices, I shifted the default device listing over from config-linux [5]. The /dev/ptmx entry is a bit awkward, since it's not a device, but it seemed to fit better over here. But I would also be fine leaving it with the other mounts in config-linux. fileMode, uid, and gid are optional, because mknod(2) doesn't need them and specifies the handling when they aren't set [6,7]. Similarly, major/minor numbers are only required for S_IFCHR and S_IFBLK [6]. I've left off wording about required runtime behavior for unset values, because I'd rather address that with a blanket rule [8]. For the cgroup, access is optional because the kernel docs show an example that doesn't write an access field to the devices.deny file [9]. The current kernel docs don't go into much detail on this behavior (I expect unset and 'rwm' are equivalent), but if the kernel doesn't need a value written, the spec should get out of the way and allow users to not specify a value. The reference links are sorted into two blocks, with kernel-doc links sorted alphabetically followed by man pages sorted alphabetically by section. The cgroup link is new since 2016-01-13 [10]. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/y_Fsa2_jJaM Subject: Separate config entries for device mknod and cgroups? Date: Mon, 5 Oct 2015 12:46:55 -0700 Message-ID: <20151005194655.GN28418@odin.tremily.us> [2]: opencontainers#98 [3]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/qWHoKs8Fsrk Subject: removal of cgroups from the OCI Linux spec Date: Wed, 28 Oct 2015 17:01:59 +0000 Message-ID: <CAD2oYtO1RMCcUp52w-xXemzDTs+J6t4hS5Mm4mX+uBnVONGDfA@mail.gmail.com> [4]: opencontainers#101 [5]: opencontainers#171 (comment) [6]: http://man7.org/linux/man-pages/man2/mknod.2.html#DESCRIPTION [7]: https://github.com/opencontainers/specs/pull/298/files#r51053835 [8]: opencontainers#285 (comment) [9]: https://kernel.org/doc/Documentation/cgroup-v1/devices.txt [10]: https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=34a9304a96d6351c2d35dcdc9293258378fc0bd8 Signed-off-by: W. Trevor King <wking@tremily.us>
Mashimiao
pushed a commit
to Mashimiao/specs
that referenced
this pull request
Aug 19, 2016
With mknod entries in linux.devices and cgroups entries in linux.resources.devices. Background discussion in [1]. For specifying device cgroups independent of device creation. This makes it easy to distinguish between configs that call for cgroup adjustments (which have linux.resources entries) from those that don't. Without this split, folks interested in making that distinction would have to parse the device section to determine if it included cgroup changes. This will also make it easy to drop either portion (mknod [2] or cgroups [3]) independently of the other if the project decides to do so. Using seperate sections for mknod and cgroups also allows us to avoid the complicated validation rules needed for the combined format mknod/cgroup [4]. Now that there is a section specific to supplying devices, I shifted the default device listing over from config-linux [5]. The /dev/ptmx entry is a bit awkward, since it's not a device, but it seemed to fit better over here. But I would also be fine leaving it with the other mounts in config-linux. fileMode, uid, and gid are optional, because mknod(2) doesn't need them and specifies the handling when they aren't set [6,7]. Similarly, major/minor numbers are only required for S_IFCHR and S_IFBLK [6]. I've left off wording about required runtime behavior for unset values, because I'd rather address that with a blanket rule [8]. For the cgroup, access is optional because the kernel docs show an example that doesn't write an access field to the devices.deny file [9]. The current kernel docs don't go into much detail on this behavior (I expect unset and 'rwm' are equivalent), but if the kernel doesn't need a value written, the spec should get out of the way and allow users to not specify a value. The reference links are sorted into two blocks, with kernel-doc links sorted alphabetically followed by man pages sorted alphabetically by section. The cgroup link is new since 2016-01-13 [10]. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/y_Fsa2_jJaM Subject: Separate config entries for device mknod and cgroups? Date: Mon, 5 Oct 2015 12:46:55 -0700 Message-ID: <20151005194655.GN28418@odin.tremily.us> [2]: opencontainers#98 [3]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/qWHoKs8Fsrk Subject: removal of cgroups from the OCI Linux spec Date: Wed, 28 Oct 2015 17:01:59 +0000 Message-ID: <CAD2oYtO1RMCcUp52w-xXemzDTs+J6t4hS5Mm4mX+uBnVONGDfA@mail.gmail.com> [4]: opencontainers#101 [5]: opencontainers#171 (comment) [6]: http://man7.org/linux/man-pages/man2/mknod.2.html#DESCRIPTION [7]: https://github.com/opencontainers/specs/pull/298/files#r51053835 [8]: opencontainers#285 (comment) [9]: https://kernel.org/doc/Documentation/cgroup-v1/devices.txt [10]: https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=34a9304a96d6351c2d35dcdc9293258378fc0bd8 Signed-off-by: W. Trevor King <wking@tremily.us>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Building on #94, although I still prefer handling these features
independently (possible specs for that are in #98 and #99).
I'm still not clear on allow vs. deny for cgroups rules, but there's
some discussion after this comment.