jasder
/
runc
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
runc/config-linux.md

593 lines
21 KiB
Markdown
Raw Normal View History

*.md: update TOC and links Some of the docs were not even linked to, and did not have a logic outline for their grouping. Signed-off-by: Vincent Batts <vbatts@hashbangbash.com>
2015-09-11 02:36:13 +08:00
# Linux-specific Container Configuration
*: re-org the spec We had an in-person spec discussion, lets separate the spec into some high-level sections to clarify future discussion. Crosby agreed to let me merge to master :)
2015-06-25 08:15:48 +08:00
config: Split platform-specific configuration into its own section (#414) To make it clear that the whole 'linux' section is optional. Signed-off-by: W. Trevor King <wking@tremily.us>
2016-05-03 02:04:39 +08:00
This document describes the schema for the [Linux-specific section](config.md#platform-specific-configuration) of the [container configuration](config.md).
*.md: markdown formatting Closes https://github.com/opencontainers/specs/issues/83 Signed-off-by: Vincent Batts <vbatts@hashbangbash.com>
2015-09-09 22:17:06 +08:00
The Linux container specification uses various kernel features like namespaces, cgroups, capabilities, LSM, and file system jails to fulfill the spec.
Add linux spec description Signed-off-by: Michael Crosby <crosbymichael@gmail.com>
2015-07-01 06:18:40 +08:00
runtime-config-linux: Separate mknod from cgroups 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]: https://github.com/opencontainers/specs/pull/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]: https://github.com/opencontainers/specs/pull/101 [5]: https://github.com/opencontainers/specs/pull/171#discussion_r41190655 [6]: http://man7.org/linux/man-pages/man2/mknod.2.html#DESCRIPTION [7]: https://github.com/opencontainers/specs/pull/298/files#r51053835 [8]: https://github.com/opencontainers/specs/pull/285#issuecomment-167823651 [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>
2015-08-07 02:27:50 +08:00
## Default File Systems
config-linux: specify the default devices/filesystems available Fixes #95 Signed-off-by: Brandon Philips <brandon.philips@coreos.com>
2015-09-10 00:36:30 +08:00
The Linux ABI includes both syscalls and several special file paths.
Applications expecting a Linux environment will very likely expect these files paths to be setup correctly.
runtime-config-linux: Separate mknod from cgroups 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]: https://github.com/opencontainers/specs/pull/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]: https://github.com/opencontainers/specs/pull/101 [5]: https://github.com/opencontainers/specs/pull/171#discussion_r41190655 [6]: http://man7.org/linux/man-pages/man2/mknod.2.html#DESCRIPTION [7]: https://github.com/opencontainers/specs/pull/298/files#r51053835 [8]: https://github.com/opencontainers/specs/pull/285#issuecomment-167823651 [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>
2015-08-07 02:27:50 +08:00
The following filesystems MUST be made available in each application's filesystem
| Path | Type |
| -------- | ------ |
| /proc | [procfs](https://www.kernel.org/doc/Documentation/filesystems/proc.txt) |
| /sys | [sysfs](https://www.kernel.org/doc/Documentation/filesystems/sysfs.txt) |
| /dev/pts | [devpts](https://www.kernel.org/doc/Documentation/filesystems/devpts.txt) |
| /dev/shm | [tmpfs](https://www.kernel.org/doc/Documentation/filesystems/tmpfs.txt) |
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
## Namespaces
A namespace wraps a global system resource in an abstraction that makes it appear to the processes within the namespace that they have their own isolated instance of the global resource.
Changes to the global resource are visible to other processes that are members of the namespace, but are invisible to other processes.
For more information, see [the man page](http://man7.org/linux/man-pages/man7/namespaces.7.html).
Namespaces are specified as an array of entries inside the `namespaces` root field.
The following parameters can be specified to setup namespaces:
* **`type`** *(string, required)* - namespace type. The following namespaces types are supported:
*: add support for cgroup namespace The cgroup namespace is a new kernel feature available in 4.6+ that allows a container to isolate its cgroup hierarchy. This currently only allows for hiding information from /proc/self/cgroup, and mounting cgroupfs as an unprivileged user. In the future, this namespace may allow for subtree management by a container. Signed-off-by: Aleksa Sarai <asarai@suse.de>
2016-05-28 13:02:35 +08:00
* **`pid`** processes inside the container will only be able to see other processes inside the same container.
* **`network`** the container will have its own network stack.
* **`mount`** the container will have an isolated mount table.
* **`ipc`** processes inside the container will only be able to communicate to other processes inside the same container via system level IPC.
* **`uts`** the container will be able to have its own hostname and domain name.
* **`user`** the container will be able to remap user and group IDs from the host to local users and groups within the container.
* **`cgroup`** the container will have an isolated view of the cgroup hierarchy.
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
config-linux: Specify host mount namespace for namespace paths Avoid trouble with situations like: # mount --bind /mnt/test /mnt/test # mount --make-rprivate /mnt/test # touch /mnt/test/mnt /mnt/test/user # mount --bind /proc/123/ns/mnt /mnt/test/mnt # mount --bind /proc/123/ns/user /mnt/test/user # nsenter --mount=/proc/123/ns/mnt --user /proc/123/ns/user sh which uses the required private mount for binding mount namespace references [1,2,3]. We want to avoid: 1. Runtime opens /mnt/test/mnt as fd 3. 2. Runtime joins the mount namespace referenced by fd 3. 3. Runtime fails to open /mnt/test/user, because /mnt/test is not visible in the current mount namespace. and instead get runtime authors to setup flows like: 1. Runtime opens /mnt/test/mnt as fd 3. 2. Runtime opens /mnt/test/user as fd 4. 3. Runtime joins the mount namespace referenced by fd 3. 4. Runtime joins the user namespace referenced by fd 4. This also applies to new namespace creation. We want to avoid: 1. Runtime clones a container process with a new mount namespace. 2c. Container process fails to open /mnt/test/user, because /mnt/test is not visible in the current mount namespace. in favor of something like: 1. Runtime opens /mnt/test/user as fd 3. 2. Runtime clones a container process with a new mount namespace. 3h. Host process closes unneeded fd 3. 3c. Container process joins the user namespace referenced by fd 3. I also define runtime and container namespaces, so we have consistent terminology. I prefer: * host namespace: a namespace you are in when you invoke the runtime * host process: the runtime process invoked by the user * container process: the process created by a clone call in the host process which will eventually execute the user-configured process. Both the host and container processes are running runtime code (although the container process eventually transitions to user-configured code), so I find "runtime process", "runtime namespace", etc. to be imprecise. However, the maintainer consensus is for "runtime namespace" [4,5], so that's what we're going with here. [1]: http://karelzak.blogspot.com/2015/04/persistent-namespaces.html [2]: https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=4ce5d2b1a8fde84c0eebe70652cf28b9beda6b4e [3]: http://mid.gmane.org/87haeahkzc.fsf@xmission.com [4]: https://github.com/opencontainers/specs/pull/275#discussion_r48057211 [5]: https://github.com/opencontainers/specs/pull/275#discussion_r48324264 Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-19 02:42:33 +08:00
* **`path`** *(string, optional)* - path to namespace file in the [runtime mount namespace](glossary.md#runtime-namespace)
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
If a path is specified, that particular file is used to join that type of namespace.
Also, when a path is specified, a runtime MUST assume that the setup for that particular namespace has already been done and error out if the config specifies anything else related to that namespace.
###### Example
```json
"namespaces": [
{
"type": "pid",
"path": "/proc/1234/ns/pid"
},
{
"type": "network",
"path": "/var/run/netns/neta"
},
{
"type": "mount"
},
{
"type": "ipc"
},
{
"type": "uts"
},
{
"type": "user"
*: add support for cgroup namespace The cgroup namespace is a new kernel feature available in 4.6+ that allows a container to isolate its cgroup hierarchy. This currently only allows for hiding information from /proc/self/cgroup, and mounting cgroupfs as an unprivileged user. In the future, this namespace may allow for subtree management by a container. Signed-off-by: Aleksa Sarai <asarai@suse.de>
2016-05-28 13:02:35 +08:00
},
{
"type": "cgroup"
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
}
]
```
## User namespace mappings
###### Example
```json
"uidMappings": [
{
"hostID": 1000,
"containerID": 0,
"size": 10
}
],
"gidMappings": [
{
"hostID": 1000,
"containerID": 0,
"size": 10
}
]
```
uid/gid mappings describe the user namespace mappings from the host to the container.
config-linux: Make "don't modify filesystem permissions" generic The user-namespace restriction isn't about the root filesystem in particular. For example, if you bind mount in a second filesystem, the runtime shouldn't adjust ownership on that filesystem either. I've also adjusted the old "permissions" to "ownership", since that more clearly reflects the fields (user and group) that you would modify if you wanted to adjust for user namespacing. Signed-off-by: W. Trevor King <wking@tremily.us>
2016-05-04 11:30:30 +08:00
The runtime SHOULD NOT modify the ownership of referenced filesystems to realize the mapping.
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
*hostID* is the starting uid/gid on the host to be mapped to *containerID* which is the starting uid/gid in the container and *size* refers to the number of ids to be mapped.
There is a limit of 5 mappings which is the Linux kernel hard limit.
## Devices
runtime-config-linux: Separate mknod from cgroups 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]: https://github.com/opencontainers/specs/pull/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]: https://github.com/opencontainers/specs/pull/101 [5]: https://github.com/opencontainers/specs/pull/171#discussion_r41190655 [6]: http://man7.org/linux/man-pages/man2/mknod.2.html#DESCRIPTION [7]: https://github.com/opencontainers/specs/pull/298/files#r51053835 [8]: https://github.com/opencontainers/specs/pull/285#issuecomment-167823651 [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>
2015-08-07 02:27:50 +08:00
`devices` is an array specifying the list of 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.).
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
The following parameters can be specified:
Fix type of devices type Fixes: opencontainers/runc#566 For type rune, we can assign char as 'c' in struct, but after marshal, it'll be presented as int32. So in json config it needs to be presented as a number which is not friendly to be identified. Change it to string so that you can actually write "b", "c" in json spec and you can easily know what type of device it is. Signed-off-by: Qiang Huang <h.huangqiang@huawei.com>
2016-02-23 13:33:57 +08:00
* **`type`** *(string, required)* - type of device: `c`, `b`, `u` or `p`.
runtime-config-linux: Separate mknod from cgroups 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]: https://github.com/opencontainers/specs/pull/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]: https://github.com/opencontainers/specs/pull/101 [5]: https://github.com/opencontainers/specs/pull/171#discussion_r41190655 [6]: http://man7.org/linux/man-pages/man2/mknod.2.html#DESCRIPTION [7]: https://github.com/opencontainers/specs/pull/298/files#r51053835 [8]: https://github.com/opencontainers/specs/pull/285#issuecomment-167823651 [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>
2015-08-07 02:27:50 +08:00
More info in [mknod(1)][mknod.1].
* **`path`** *(string, required)* - full path to device inside container.
* **`major, minor`** *(int64, required unless **`type`** is `p`)* - [major, minor numbers][devices] for the device.
* **`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.
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
###### Example
```json
"devices": [
{
runtime-config-linux: Separate mknod from cgroups 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]: https://github.com/opencontainers/specs/pull/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]: https://github.com/opencontainers/specs/pull/101 [5]: https://github.com/opencontainers/specs/pull/171#discussion_r41190655 [6]: http://man7.org/linux/man-pages/man2/mknod.2.html#DESCRIPTION [7]: https://github.com/opencontainers/specs/pull/298/files#r51053835 [8]: https://github.com/opencontainers/specs/pull/285#issuecomment-167823651 [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>
2015-08-07 02:27:50 +08:00
"path": "/dev/fuse",
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
"type": "c",
runtime-config-linux: Separate mknod from cgroups 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]: https://github.com/opencontainers/specs/pull/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]: https://github.com/opencontainers/specs/pull/101 [5]: https://github.com/opencontainers/specs/pull/171#discussion_r41190655 [6]: http://man7.org/linux/man-pages/man2/mknod.2.html#DESCRIPTION [7]: https://github.com/opencontainers/specs/pull/298/files#r51053835 [8]: https://github.com/opencontainers/specs/pull/285#issuecomment-167823651 [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>
2015-08-07 02:27:50 +08:00
"major": 10,
"minor": 229,
Fix fileMode json example In json, os.FileMode would be presented as a uint32, which is decimal. Otherwise we'll get error: `invalid character '6' after object key:value pair` when unmarshal the json file. Signed-off-by: Qiang Huang <h.huangqiang@huawei.com>
2016-02-23 08:22:27 +08:00
"fileMode": 438,
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
"uid": 0,
"gid": 0
},
{
runtime-config-linux: Separate mknod from cgroups 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]: https://github.com/opencontainers/specs/pull/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]: https://github.com/opencontainers/specs/pull/101 [5]: https://github.com/opencontainers/specs/pull/171#discussion_r41190655 [6]: http://man7.org/linux/man-pages/man2/mknod.2.html#DESCRIPTION [7]: https://github.com/opencontainers/specs/pull/298/files#r51053835 [8]: https://github.com/opencontainers/specs/pull/285#issuecomment-167823651 [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>
2015-08-07 02:27:50 +08:00
"path": "/dev/sda",
"type": "b",
"major": 8,
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
"minor": 0,
Fix fileMode json example In json, os.FileMode would be presented as a uint32, which is decimal. Otherwise we'll get error: `invalid character '6' after object key:value pair` when unmarshal the json file. Signed-off-by: Qiang Huang <h.huangqiang@huawei.com>
2016-02-23 08:22:27 +08:00
"fileMode": 432,
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
"uid": 0,
"gid": 0
}
]
```
runtime-config-linux: Separate mknod from cgroups 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]: https://github.com/opencontainers/specs/pull/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]: https://github.com/opencontainers/specs/pull/101 [5]: https://github.com/opencontainers/specs/pull/171#discussion_r41190655 [6]: http://man7.org/linux/man-pages/man2/mknod.2.html#DESCRIPTION [7]: https://github.com/opencontainers/specs/pull/298/files#r51053835 [8]: https://github.com/opencontainers/specs/pull/285#issuecomment-167823651 [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>
2015-08-07 02:27:50 +08:00
###### Default Devices
In addition to any devices configured with this setting, the runtime MUST also supply:
* [`/dev/null`][null.4]
* [`/dev/zero`][zero.4]
* [`/dev/full`][full.4]
* [`/dev/random`][random.4]
* [`/dev/urandom`][random.4]
* [`/dev/tty`][tty.4]
* [`/dev/console`][console.4]
* [`/dev/ptmx`][pts.4].
A [bind-mount or symlink of the container's `/dev/pts/ptmx`][devpts].
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
## Control groups
Also known as cgroups, they are used to restrict resource usage for a container and handle device access.
config-linux: cleanup cgroup wording Some of the wording was a bit clumsy (and incorrect, by conflating different concepts in control groups as "cgroups"). Signed-off-by: Aleksa Sarai <asarai@suse.de>
2016-06-10 22:42:53 +08:00
cgroups provide controls (through controllers) to restrict cpu, memory, IO, pids and network for the container.
config-linux: Update links to cgroups documentation With 34a9304a (Merge branch 'for-4.5' of git://git.kernel.org/pub/scm/linux/kernel/git/tj/cgroup, 2016-01-13, [1]), Linux restructured their cgroups documentation. This updated all of our Documentation/cgroups references to match the new layout, using reference-style links [2] which let us collect link label definitions at the bottom of the file. That makes the spec source easier to read (no distracting URLs in the middle of a sentence) and makes the URLs easier to update (only one place to check / fix). [1]: https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=34a9304a96d6351c2d35dcdc9293258378fc0bd8 [2]: http://daringfireball.net/projects/markdown/syntax#link Signed-off-by: W. Trevor King <wking@tremily.us>
2016-01-28 04:32:13 +08:00
For more information, see the [kernel cgroups documentation][cgroup-v1].
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
The path to the cgroups can be specified in the Spec via `cgroupsPath`.
config-linux: cleanup cgroup wording Some of the wording was a bit clumsy (and incorrect, by conflating different concepts in control groups as "cgroups"). Signed-off-by: Aleksa Sarai <asarai@suse.de>
2016-06-10 22:42:53 +08:00
`cgroupsPath` can be used to either control the cgroup hierarchy for containers or to run a new process in an existing container.
config-linux: clarify cgroupsPath Clarify some of the confusion with cgroupsPath. Due to systemd, we cannot require that relative paths be treated in any specific way. In addition, add a line stating that not all values of cgroupsPath are required to be valid (and that runtimes must error out if they have an invalid cgroup path). However, any given value of cgroupsPath should provide consistent results. Signed-off-by: Aleksa Sarai <asarai@suse.de>
2016-06-08 20:54:18 +08:00
If `cgroupsPath` is:
* ... an absolute path (starting with `/`), the runtime MUST take the path to be relative to the cgroup mount point.
* ... a relative path (not starting with `/`), the runtime MAY interpret the path relative to a runtime-determined location in the cgroup hierarchy.
* ... not specified, the runtime MAY define the default cgroup path.
Runtimes MAY consider certain `cgroupsPath` values to be invalid, and MUST generate an error if this is the case.
If a `cgroupsPath` value is specified, the runtime MUST consistently attach to the same place in the cgroup hierarchy given the same value of `cgroupsPath`.
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
Implementations of the Spec can choose to name cgroups in any manner.
The Spec does not include naming schema for cgroups.
config-linux: cleanup cgroup wording Some of the wording was a bit clumsy (and incorrect, by conflating different concepts in control groups as "cgroups"). Signed-off-by: Aleksa Sarai <asarai@suse.de>
2016-06-10 22:42:53 +08:00
The Spec does not support per-controller paths for the reasons discussed in the [cgroupv2 documentation][cgroup-v2].
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
The cgroups will be created if they don't exist.
config-linux: cleanup cgroup wording Some of the wording was a bit clumsy (and incorrect, by conflating different concepts in control groups as "cgroups"). Signed-off-by: Aleksa Sarai <asarai@suse.de>
2016-06-10 22:42:53 +08:00
You can configure a container's cgroups via the `resources` field of the Linux configuration.
Do not specify `resources` unless limits have to be updated.
For example, to run a new process in an existing container without updating limits, `resources` need not be specified.
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
###### Example
```json
"cgroupsPath": "/myRuntime/myContainer"
```
runtime-config-linux: Separate mknod from cgroups 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]: https://github.com/opencontainers/specs/pull/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]: https://github.com/opencontainers/specs/pull/101 [5]: https://github.com/opencontainers/specs/pull/171#discussion_r41190655 [6]: http://man7.org/linux/man-pages/man2/mknod.2.html#DESCRIPTION [7]: https://github.com/opencontainers/specs/pull/298/files#r51053835 [8]: https://github.com/opencontainers/specs/pull/285#issuecomment-167823651 [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>
2015-08-07 02:27:50 +08:00
#### Device whitelist
config-linux: Update links to cgroups documentation With 34a9304a (Merge branch 'for-4.5' of git://git.kernel.org/pub/scm/linux/kernel/git/tj/cgroup, 2016-01-13, [1]), Linux restructured their cgroups documentation. This updated all of our Documentation/cgroups references to match the new layout, using reference-style links [2] which let us collect link label definitions at the bottom of the file. That makes the spec source easier to read (no distracting URLs in the middle of a sentence) and makes the URLs easier to update (only one place to check / fix). [1]: https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=34a9304a96d6351c2d35dcdc9293258378fc0bd8 [2]: http://daringfireball.net/projects/markdown/syntax#link Signed-off-by: W. Trevor King <wking@tremily.us>
2016-01-28 04:32:13 +08:00
`devices` is an array of entries to control the [device whitelist][cgroup-v1-devices].
runtime-config-linux: Separate mknod from cgroups 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]: https://github.com/opencontainers/specs/pull/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]: https://github.com/opencontainers/specs/pull/101 [5]: https://github.com/opencontainers/specs/pull/171#discussion_r41190655 [6]: http://man7.org/linux/man-pages/man2/mknod.2.html#DESCRIPTION [7]: https://github.com/opencontainers/specs/pull/298/files#r51053835 [8]: https://github.com/opencontainers/specs/pull/285#issuecomment-167823651 [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>
2015-08-07 02:27:50 +08:00
The runtime MUST apply entries in the listed order.
The following parameters can be specified:
* **`allow`** *(boolean, required)* - whether the entry is allowed or denied.
Fix type of devices type Fixes: opencontainers/runc#566 For type rune, we can assign char as 'c' in struct, but after marshal, it'll be presented as int32. So in json config it needs to be presented as a number which is not friendly to be identified. Change it to string so that you can actually write "b", "c" in json spec and you can easily know what type of device it is. Signed-off-by: Qiang Huang <h.huangqiang@huawei.com>
2016-02-23 13:33:57 +08:00
* **`type`** *(string, optional)* - type of device: `a` (all), `c` (char), or `b` (block).
runtime-config-linux: Separate mknod from cgroups 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]: https://github.com/opencontainers/specs/pull/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]: https://github.com/opencontainers/specs/pull/101 [5]: https://github.com/opencontainers/specs/pull/171#discussion_r41190655 [6]: http://man7.org/linux/man-pages/man2/mknod.2.html#DESCRIPTION [7]: https://github.com/opencontainers/specs/pull/298/files#r51053835 [8]: https://github.com/opencontainers/specs/pull/285#issuecomment-167823651 [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>
2015-08-07 02:27:50 +08:00
`null` or unset values mean "all", mapping to `a`.
* **`major, minor`** *(int64, optional)* - [major, minor numbers][devices] for the device.
config-linux: Update links to cgroups documentation With 34a9304a (Merge branch 'for-4.5' of git://git.kernel.org/pub/scm/linux/kernel/git/tj/cgroup, 2016-01-13, [1]), Linux restructured their cgroups documentation. This updated all of our Documentation/cgroups references to match the new layout, using reference-style links [2] which let us collect link label definitions at the bottom of the file. That makes the spec source easier to read (no distracting URLs in the middle of a sentence) and makes the URLs easier to update (only one place to check / fix). [1]: https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=34a9304a96d6351c2d35dcdc9293258378fc0bd8 [2]: http://daringfireball.net/projects/markdown/syntax#link Signed-off-by: W. Trevor King <wking@tremily.us>
2016-01-28 04:32:13 +08:00
`null` or unset values mean "all", mapping to [`*` in the filesystem API][cgroup-v1-devices].
runtime-config-linux: Separate mknod from cgroups 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]: https://github.com/opencontainers/specs/pull/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]: https://github.com/opencontainers/specs/pull/101 [5]: https://github.com/opencontainers/specs/pull/171#discussion_r41190655 [6]: http://man7.org/linux/man-pages/man2/mknod.2.html#DESCRIPTION [7]: https://github.com/opencontainers/specs/pull/298/files#r51053835 [8]: https://github.com/opencontainers/specs/pull/285#issuecomment-167823651 [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>
2015-08-07 02:27:50 +08:00
* **`access`** *(string, optional)* - cgroup permissions for device.
A composition of `r` (read), `w` (write), and `m` (mknod).
###### Example
```json
"devices": [
{
"allow": false,
"access": "rwm"
},
{
"allow": true,
"type": "c",
"major": 10,
"minor": 229,
"access": "rw"
},
{
"allow": true,
"type": "b",
"major": 8,
"minor": 0,
"access": "r"
}
]
```
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
#### Disable out-of-memory killer
`disableOOMKiller` contains a boolean (`true` or `false`) that enables or disables the Out of Memory killer for a cgroup.
If enabled (`false`), tasks that attempt to consume more memory than they are allowed are immediately killed by the OOM killer.
The OOM killer is enabled by default in every cgroup using the `memory` subsystem.
To disable it, specify a value of `true`.
config-linux: Update links to cgroups documentation With 34a9304a (Merge branch 'for-4.5' of git://git.kernel.org/pub/scm/linux/kernel/git/tj/cgroup, 2016-01-13, [1]), Linux restructured their cgroups documentation. This updated all of our Documentation/cgroups references to match the new layout, using reference-style links [2] which let us collect link label definitions at the bottom of the file. That makes the spec source easier to read (no distracting URLs in the middle of a sentence) and makes the URLs easier to update (only one place to check / fix). [1]: https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=34a9304a96d6351c2d35dcdc9293258378fc0bd8 [2]: http://daringfireball.net/projects/markdown/syntax#link Signed-off-by: W. Trevor King <wking@tremily.us>
2016-01-28 04:32:13 +08:00
For more information, see [the memory cgroup man page][cgroup-v1-memory].
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
* **`disableOOMKiller`** *(bool, optional)* - enables or disables the OOM killer
###### Example
```json
"disableOOMKiller": false
```
#### Set oom_score_adj
`oomScoreAdj` sets heuristic regarding how the process is evaluated by the kernel during memory pressure.
For more information, see [the proc filesystem documentation section 3.1](https://www.kernel.org/doc/Documentation/filesystems/proc.txt).
This is a kernel/system level setting, where as `disableOOMKiller` is scoped for a memory cgroup.
config-linux: Update links to cgroups documentation With 34a9304a (Merge branch 'for-4.5' of git://git.kernel.org/pub/scm/linux/kernel/git/tj/cgroup, 2016-01-13, [1]), Linux restructured their cgroups documentation. This updated all of our Documentation/cgroups references to match the new layout, using reference-style links [2] which let us collect link label definitions at the bottom of the file. That makes the spec source easier to read (no distracting URLs in the middle of a sentence) and makes the URLs easier to update (only one place to check / fix). [1]: https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=34a9304a96d6351c2d35dcdc9293258378fc0bd8 [2]: http://daringfireball.net/projects/markdown/syntax#link Signed-off-by: W. Trevor King <wking@tremily.us>
2016-01-28 04:32:13 +08:00
For more information on how these two settings work together, see [the memory cgroup documentation section 10. OOM Contol][cgroup-v1-memory].
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
* **`oomScoreAdj`** *(int, optional)* - adjust the oom-killer score
###### Example
```json
config: JSON examples * "complete" JSON example * fix a couple of values * fix a missing comma Signed-off-by: Vincent Batts <vbatts@hashbangbash.com>
2016-04-07 05:07:17 +08:00
"oomScoreAdj": 100
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
```
#### Memory
`memory` represents the cgroup subsystem `memory` and it's used to set limits on the container's memory usage.
config-linux: Update links to cgroups documentation With 34a9304a (Merge branch 'for-4.5' of git://git.kernel.org/pub/scm/linux/kernel/git/tj/cgroup, 2016-01-13, [1]), Linux restructured their cgroups documentation. This updated all of our Documentation/cgroups references to match the new layout, using reference-style links [2] which let us collect link label definitions at the bottom of the file. That makes the spec source easier to read (no distracting URLs in the middle of a sentence) and makes the URLs easier to update (only one place to check / fix). [1]: https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=34a9304a96d6351c2d35dcdc9293258378fc0bd8 [2]: http://daringfireball.net/projects/markdown/syntax#link Signed-off-by: W. Trevor King <wking@tremily.us>
2016-01-28 04:32:13 +08:00
For more information, see [the memory cgroup man page][cgroup-v1-memory].
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
The following parameters can be specified to setup the controller:
config: JSON examples * "complete" JSON example * fix a couple of values * fix a missing comma Signed-off-by: Vincent Batts <vbatts@hashbangbash.com>
2016-04-07 05:07:17 +08:00
* **`limit`** *(uint64, optional)* - sets limit of memory usage in bytes
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
config: JSON examples * "complete" JSON example * fix a couple of values * fix a missing comma Signed-off-by: Vincent Batts <vbatts@hashbangbash.com>
2016-04-07 05:07:17 +08:00
* **`reservation`** *(uint64, optional)* - sets soft limit of memory usage in bytes
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
* **`swap`** *(uint64, optional)* - sets limit of memory+Swap usage
* **`kernel`** *(uint64, optional)* - sets hard limit for kernel memory
config-linux.md: Reword kernelTCP docs and mention bytes Avoid the dangling 'using' from e9a6d948 (cgroup: Add support for memory.kmem.tcp.limit_in_bytes, 2015-10-26, #235). I've tried to echo the kernel docs by mentioning buffer memory [1]. I'd personally prefer linking to the kernel docs and mentioning memory.kmem.tcp.limit_in_bytes, but that seemed like too big of a break from the existing style for this commit. [1]: https://kernel.org/doc/Documentation/cgroup-v1/memory.txt Signed-off-by: W. Trevor King <wking@tremily.us>
2016-04-12 07:03:39 +08:00
* **`kernelTCP`** *(uint64, optional)* - sets hard limit in bytes for kernel TCP buffer memory
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
* **`swappiness`** *(uint64, optional)* - sets swappiness parameter of vmscan (See sysctl's vm.swappiness)
###### Example
```json
"memory": {
config: JSON examples * "complete" JSON example * fix a couple of values * fix a missing comma Signed-off-by: Vincent Batts <vbatts@hashbangbash.com>
2016-04-07 05:07:17 +08:00
"limit": 536870912,
"reservation": 536870912,
"swap": 536870912,
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
"kernel": 0,
"kernelTCP": 0,
"swappiness": 0
}
```
#### CPU
`cpu` represents the cgroup subsystems `cpu` and `cpusets`.
config-linux: Update links to cgroups documentation With 34a9304a (Merge branch 'for-4.5' of git://git.kernel.org/pub/scm/linux/kernel/git/tj/cgroup, 2016-01-13, [1]), Linux restructured their cgroups documentation. This updated all of our Documentation/cgroups references to match the new layout, using reference-style links [2] which let us collect link label definitions at the bottom of the file. That makes the spec source easier to read (no distracting URLs in the middle of a sentence) and makes the URLs easier to update (only one place to check / fix). [1]: https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=34a9304a96d6351c2d35dcdc9293258378fc0bd8 [2]: http://daringfireball.net/projects/markdown/syntax#link Signed-off-by: W. Trevor King <wking@tremily.us>
2016-01-28 04:32:13 +08:00
For more information, see [the cpusets cgroup man page][cgroup-v1-cpusets].
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
The following parameters can be specified to setup the controller:
* **`shares`** *(uint64, optional)* - specifies a relative share of CPU time available to the tasks in a cgroup
* **`quota`** *(uint64, optional)* - specifies the total amount of time in microseconds for which all tasks in a cgroup can run during one period (as defined by **`period`** below)
* **`period`** *(uint64, optional)* - specifies a period of time in microseconds for how regularly a cgroup's access to CPU resources should be reallocated (CFS scheduler only)
* **`realtimeRuntime`** *(uint64, optional)* - specifies a period of time in microseconds for the longest continuous period in which the tasks in a cgroup have access to CPU resources
* **`realtimePeriod`** *(uint64, optional)* - same as **`period`** but applies to realtime scheduler only
* **`cpus`** *(string, optional)* - list of CPUs the container will run in
* **`mems`** *(string, optional)* - list of Memory Nodes the container will run in
###### Example
```json
"cpu": {
config: JSON examples * "complete" JSON example * fix a couple of values * fix a missing comma Signed-off-by: Vincent Batts <vbatts@hashbangbash.com>
2016-04-07 05:07:17 +08:00
"shares": 1024,
"quota": 1000000,
"period": 500000,
"realtimeRuntime": 950000,
"realtimePeriod": 1000000,
"cpus": "2-3",
"mems": "0-7"
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
}
```
#### Block IO Controller
`blockIO` represents the cgroup subsystem `blkio` which implements the block io controller.
config-linux: Update links to cgroups documentation With 34a9304a (Merge branch 'for-4.5' of git://git.kernel.org/pub/scm/linux/kernel/git/tj/cgroup, 2016-01-13, [1]), Linux restructured their cgroups documentation. This updated all of our Documentation/cgroups references to match the new layout, using reference-style links [2] which let us collect link label definitions at the bottom of the file. That makes the spec source easier to read (no distracting URLs in the middle of a sentence) and makes the URLs easier to update (only one place to check / fix). [1]: https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=34a9304a96d6351c2d35dcdc9293258378fc0bd8 [2]: http://daringfireball.net/projects/markdown/syntax#link Signed-off-by: W. Trevor King <wking@tremily.us>
2016-01-28 04:32:13 +08:00
For more information, see [the kernel cgroups documentation about blkio][cgroup-v1-blkio].
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
The following parameters can be specified to setup the controller:
* **`blkioWeight`** *(uint16, optional)* - specifies per-cgroup weight. This is default weight of the group on all devices until and unless overridden by per-device rules. The range is from 10 to 1000.
* **`blkioLeafWeight`** *(uint16, optional)* - equivalents of `blkioWeight` for the purpose of deciding how much weight tasks in the given cgroup has while competing with the cgroup's child cgroups. The range is from 10 to 1000.
* **`blkioWeightDevice`** *(array, optional)* - specifies the list of devices which will be bandwidth rate limited. The following parameters can be specified per-device:
* **`major, minor`** *(int64, required)* - major, minor numbers for device. More info in `man mknod`.
* **`weight`** *(uint16, optional)* - bandwidth rate for the device, range is from 10 to 1000
* **`leafWeight`** *(uint16, optional)* - bandwidth rate for the device while competing with the cgroup's child cgroups, range is from 10 to 1000, CFQ scheduler only
You must specify at least one of `weight` or `leafWeight` in a given entry, and can specify both.
* **`blkioThrottleReadBpsDevice`**, **`blkioThrottleWriteBpsDevice`**, **`blkioThrottleReadIOPSDevice`**, **`blkioThrottleWriteIOPSDevice`** *(array, optional)* - specify the list of devices which will be IO rate limited. The following parameters can be specified per-device:
* **`major, minor`** *(int64, required)* - major, minor numbers for device. More info in `man mknod`.
* **`rate`** *(uint64, required)* - IO rate limit for the device
###### Example
```json
"blockIO": {
config: JSON examples * "complete" JSON example * fix a couple of values * fix a missing comma Signed-off-by: Vincent Batts <vbatts@hashbangbash.com>
2016-04-07 05:07:17 +08:00
"blkioWeight": 10,
"blkioLeafWeight": 10,
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
"blkioWeightDevice": [
{
"major": 8,
"minor": 0,
"weight": 500,
"leafWeight": 300
},
{
"major": 8,
"minor": 16,
"weight": 500
}
],
"blkioThrottleReadBpsDevice": [
{
"major": 8,
"minor": 0,
"rate": 600
}
],
"blkioThrottleWriteIOPSDevice": [
{
"major": 8,
"minor": 16,
"rate": 300
}
]
}
```
#### Huge page limits
`hugepageLimits` represents the `hugetlb` controller which allows to limit the
HugeTLB usage per control group and enforces the controller limit during page fault.
config-linux: Update links to cgroups documentation With 34a9304a (Merge branch 'for-4.5' of git://git.kernel.org/pub/scm/linux/kernel/git/tj/cgroup, 2016-01-13, [1]), Linux restructured their cgroups documentation. This updated all of our Documentation/cgroups references to match the new layout, using reference-style links [2] which let us collect link label definitions at the bottom of the file. That makes the spec source easier to read (no distracting URLs in the middle of a sentence) and makes the URLs easier to update (only one place to check / fix). [1]: https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=34a9304a96d6351c2d35dcdc9293258378fc0bd8 [2]: http://daringfireball.net/projects/markdown/syntax#link Signed-off-by: W. Trevor King <wking@tremily.us>
2016-01-28 04:32:13 +08:00
For more information, see the [kernel cgroups documentation about HugeTLB][cgroup-v1-hugetlb].
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
`hugepageLimits` is an array of entries, each having the following structure:
* **`pageSize`** *(string, required)* - hugepage size
* **`limit`** *(uint64, required)* - limit in bytes of *hugepagesize* HugeTLB usage
###### Example
```json
"hugepageLimits": [
{
"pageSize": "2MB",
"limit": 9223372036854771712
}
]
```
#### Network
`network` represents the cgroup subsystems `net_cls` and `net_prio`.
config-linux: Update links to cgroups documentation With 34a9304a (Merge branch 'for-4.5' of git://git.kernel.org/pub/scm/linux/kernel/git/tj/cgroup, 2016-01-13, [1]), Linux restructured their cgroups documentation. This updated all of our Documentation/cgroups references to match the new layout, using reference-style links [2] which let us collect link label definitions at the bottom of the file. That makes the spec source easier to read (no distracting URLs in the middle of a sentence) and makes the URLs easier to update (only one place to check / fix). [1]: https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=34a9304a96d6351c2d35dcdc9293258378fc0bd8 [2]: http://daringfireball.net/projects/markdown/syntax#link Signed-off-by: W. Trevor King <wking@tremily.us>
2016-01-28 04:32:13 +08:00
For more information, see [the net\_cls cgroup man page][cgroup-v1-net-cls] and [the net\_prio cgroup man page][cgroup-v1-net-prio].
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
The following parameters can be specified to setup these cgroup controllers:
* **`classID`** *(uint32, optional)* - is the network class identifier the cgroup's network packets will be tagged with
* **`priorities`** *(array, optional)* - specifies a list of objects of the priorities assigned to traffic originating from
processes in the group and egressing the system on various interfaces. The following parameters can be specified per-priority:
* **`name`** *(string, required)* - interface name
* **`priority`** *(uint32, required)* - priority applied to the interface
###### Example
```json
"network": {
"classID": 1048577,
"priorities": [
{
"name": "eth0",
"priority": 500
},
{
"name": "eth1",
"priority": 1000
}
]
}
```
#### PIDs
`pids` represents the cgroup subsystem `pids`.
config-linux: Update links to cgroups documentation With 34a9304a (Merge branch 'for-4.5' of git://git.kernel.org/pub/scm/linux/kernel/git/tj/cgroup, 2016-01-13, [1]), Linux restructured their cgroups documentation. This updated all of our Documentation/cgroups references to match the new layout, using reference-style links [2] which let us collect link label definitions at the bottom of the file. That makes the spec source easier to read (no distracting URLs in the middle of a sentence) and makes the URLs easier to update (only one place to check / fix). [1]: https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=34a9304a96d6351c2d35dcdc9293258378fc0bd8 [2]: http://daringfireball.net/projects/markdown/syntax#link Signed-off-by: W. Trevor King <wking@tremily.us>
2016-01-28 04:32:13 +08:00
For more information, see [the pids cgroup man page][cgroup-v1-pids].
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
*: fix typos Signed-off-by: Antonio Murdaca <runcom@redhat.com>
2016-03-21 18:51:19 +08:00
The following parameters can be specified to setup the controller:
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
* **`limit`** *(int64, required)* - specifies the maximum number of tasks in the cgroup
###### Example
```json
"pids": {
"limit": 32771
}
```
## Sysctl
Add masked and readonly paths Fixes #320 This adds the maskedPaths and readonlyPaths fields to the spec so that proper masking and setting of files in /proc can be configured. Signed-off-by: Michael Crosby <crosbymichael@gmail.com>
2016-04-01 08:14:44 +08:00
`sysctl` allows kernel parameters to be modified at runtime for the container.
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
For more information, see [the man page](http://man7.org/linux/man-pages/man8/sysctl.8.html)
###### Example
```json
"sysctl": {
"net.ipv4.ip_forward": "1",
"net.core.somaxconn": "256"
}
```
## seccomp
Seccomp provides application sandboxing mechanism in the Linux kernel.
Seccomp configuration allows one to configure actions to take for matched syscalls and furthermore also allows matching on values passed as arguments to syscalls.
For more information about Seccomp, see [Seccomp kernel documentation](https://www.kernel.org/doc/Documentation/prctl/seccomp_filter.txt)
The actions, architectures, and operators are strings that match the definitions in seccomp.h from [libseccomp](https://github.com/seccomp/libseccomp) and are translated to corresponding values.
Add new architectures from libseccomp 2.3.0 Signed-off-by: Phil Estes <estesp@gmail.com>
2016-06-23 01:53:32 +08:00
A valid list of constants as of libseccomp v2.3.0 is shown below.
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
Architecture Constants
* `SCMP_ARCH_X86`
* `SCMP_ARCH_X86_64`
* `SCMP_ARCH_X32`
* `SCMP_ARCH_ARM`
* `SCMP_ARCH_AARCH64`
* `SCMP_ARCH_MIPS`
* `SCMP_ARCH_MIPS64`
* `SCMP_ARCH_MIPS64N32`
* `SCMP_ARCH_MIPSEL`
* `SCMP_ARCH_MIPSEL64`
* `SCMP_ARCH_MIPSEL64N32`
Add new architectures from libseccomp 2.3.0 Signed-off-by: Phil Estes <estesp@gmail.com>
2016-06-23 01:53:32 +08:00
* `SCMP_ARCH_PPC`
* `SCMP_ARCH_PPC64`
* `SCMP_ARCH_PPC64LE`
* `SCMP_ARCH_S390`
* `SCMP_ARCH_S390X`
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
Action Constants:
* `SCMP_ACT_KILL`
* `SCMP_ACT_TRAP`
* `SCMP_ACT_ERRNO`
* `SCMP_ACT_TRACE`
* `SCMP_ACT_ALLOW`
Operator Constants:
* `SCMP_CMP_NE`
* `SCMP_CMP_LT`
* `SCMP_CMP_LE`
* `SCMP_CMP_EQ`
* `SCMP_CMP_GE`
* `SCMP_CMP_GT`
* `SCMP_CMP_MASKED_EQ`
###### Example
```json
"seccomp": {
"defaultAction": "SCMP_ACT_ALLOW",
"architectures": [
"SCMP_ARCH_X86"
],
"syscalls": [
{
"name": "getcwd",
"action": "SCMP_ACT_ERRNO"
}
]
}
```
## Rootfs Mount Propagation
Add masked and readonly paths Fixes #320 This adds the maskedPaths and readonlyPaths fields to the spec so that proper masking and setting of files in /proc can be configured. Signed-off-by: Michael Crosby <crosbymichael@gmail.com>
2016-04-01 08:14:44 +08:00
`rootfsPropagation` sets the rootfs's mount propagation.
config: Single, unified config file Reverting 7232e4b1 (specs: introduce the concept of a runtime.json, 2015-07-30, #88) after discussion on the mailing list [1]. The main reason is that it's hard to draw a clear line around "inherently runtime-specific" or "non-portable", so we shouldn't try to do that in the spec. Folks who want to flag settings as non-portable for their own system are welcome to do so (e.g. "we will clobber 'hooks' in bundles we run") are welcome to do so, but we don't have to have to split the config into multiple files to do that. There have been a number of additional changes since #88, so this isn't a pure Git reversion. Besides copy-pasting and the associated link-target updates, I've: * Restored path -> destination, now that the mount type contains both source and target paths again. I'd prefer 'target' to 'destination' to match mount(2), but the pre-7232e4b1 phrasing was 'destination' (possibly due to Windows using 'target' for the source?). * Restored the Windows mount example to its pre-7232e4b1 content. * Removed required mounts from the config example (requirements landed in 3848a238, config-linux: specify the default devices/filesystems available, 2015-09-09, #164), because specifying those mounts in the config is now redundant. * Used headers (vs. bold paragraphs) to set off mount examples so we get link anchors in the rendered Markdown. * Replaced references to runtime.json with references to config.json. [1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY Subject: Single, unified config file (i.e. rolling back specs#88) Date: Wed, 4 Nov 2015 09:53:20 -0800 Message-ID: <20151104175320.GC24652@odin.tremily.us> Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
Its value is either slave, private, or shared.
[The kernel doc](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt) has more information about mount propagation.
###### Example
```json
"rootfsPropagation": "slave",
```
Add masked and readonly paths Fixes #320 This adds the maskedPaths and readonlyPaths fields to the spec so that proper masking and setting of files in /proc can be configured. Signed-off-by: Michael Crosby <crosbymichael@gmail.com>
2016-04-01 08:14:44 +08:00
## Masked Paths
`maskedPaths` will mask over the provided paths inside the container so that they cannot be read.
###### Example
```json
"maskedPaths": [
"/proc/kcore"
]
```
## Readonly Paths
`readonlyPaths` will set the provided paths as readonly inside the container.
###### Example
```json
"readonlyPaths": [
"/proc/sys"
]
```
Add support for Selinux mount context labels Signed-off-by: Mrunal Patel <mrunalp@gmail.com>
2016-04-22 05:01:40 +08:00
## Mount Label
`mountLabel` will set the Selinux context for the mounts in the container.
###### Example
```json
"mountLabel": "system_u:object_r:svirt_sandbox_file_t:s0:c715,c811"
```
config-linux: Update links to cgroups documentation With 34a9304a (Merge branch 'for-4.5' of git://git.kernel.org/pub/scm/linux/kernel/git/tj/cgroup, 2016-01-13, [1]), Linux restructured their cgroups documentation. This updated all of our Documentation/cgroups references to match the new layout, using reference-style links [2] which let us collect link label definitions at the bottom of the file. That makes the spec source easier to read (no distracting URLs in the middle of a sentence) and makes the URLs easier to update (only one place to check / fix). [1]: https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=34a9304a96d6351c2d35dcdc9293258378fc0bd8 [2]: http://daringfireball.net/projects/markdown/syntax#link Signed-off-by: W. Trevor King <wking@tremily.us>
2016-01-28 04:32:13 +08:00
[cgroup-v1]: https://www.kernel.org/doc/Documentation/cgroup-v1/cgroups.txt
[cgroup-v1-blkio]: https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt
[cgroup-v1-cpusets]: https://www.kernel.org/doc/Documentation/cgroup-v1/cpusets.txt
[cgroup-v1-devices]: https://www.kernel.org/doc/Documentation/cgroup-v1/devices.txt
[cgroup-v1-hugetlb]: https://www.kernel.org/doc/Documentation/cgroup-v1/hugetlb.txt
[cgroup-v1-memory]: https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt
[cgroup-v1-net-cls]: https://www.kernel.org/doc/Documentation/cgroup-v1/net_cls.txt
[cgroup-v1-net-prio]: https://www.kernel.org/doc/Documentation/cgroup-v1/net_prio.txt
[cgroup-v1-pids]: https://www.kernel.org/doc/Documentation/cgroup-v1/pids.txt
[cgroup-v2]: https://www.kernel.org/doc/Documentation/cgroup-v2.txt
runtime-config-linux: Separate mknod from cgroups 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]: https://github.com/opencontainers/specs/pull/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]: https://github.com/opencontainers/specs/pull/101 [5]: https://github.com/opencontainers/specs/pull/171#discussion_r41190655 [6]: http://man7.org/linux/man-pages/man2/mknod.2.html#DESCRIPTION [7]: https://github.com/opencontainers/specs/pull/298/files#r51053835 [8]: https://github.com/opencontainers/specs/pull/285#issuecomment-167823651 [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>
2015-08-07 02:27:50 +08:00
[devices]: https://www.kernel.org/doc/Documentation/devices.txt
[devpts]: https://www.kernel.org/doc/Documentation/filesystems/devpts.txt
[mknod.1]: http://man7.org/linux/man-pages/man1/mknod.1.html
[mknod.2]: http://man7.org/linux/man-pages/man2/mknod.2.html
[console.4]: http://man7.org/linux/man-pages/man4/console.4.html
[full.4]: http://man7.org/linux/man-pages/man4/full.4.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
[tty.4]: http://man7.org/linux/man-pages/man4/tty.4.html
[zero.4]: http://man7.org/linux/man-pages/man4/zero.4.html