jasder
/
runc
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
runc/glossary.md

37 lines
1.4 KiB
Markdown
Raw Normal View History

glossary: Provide a quick overview of important terms And link them to the more detailed specification. Subsection titles for the entries will be obnoxiously spacious, but the other alternatives seem worse: a. An HTML definition list (<dl>) would have nice default styling, but it's annoying to write raw HTML. And we would have needed something like: <dt name="bundle">Bundle</dt> <dd> A [directory structure](bundle.md) that is... </dd> to get Markdown-style links in the defintion itself. b. A Markdown list (* ...) would have reasonable default styling, but there's no Markdown syntax for adding anchors to the entries. And a glossary is much less useful if you can't link to a specific entry. Signed-off-by: W. Trevor King <wking@tremily.us>
2015-08-12 01:15:20 +08:00
# Glossary
## Bundle
A [directory structure](bundle.md) that is written ahead of time, distributed, and used to seed the runtime for creating a [container](#container) and launching a process within it.
## Configuration
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 [`config.json`](config.md) file in a [bundle](#bundle) which defines the intended [container](#container) and container process.
glossary: Provide a quick overview of important terms And link them to the more detailed specification. Subsection titles for the entries will be obnoxiously spacious, but the other alternatives seem worse: a. An HTML definition list (<dl>) would have nice default styling, but it's annoying to write raw HTML. And we would have needed something like: <dt name="bundle">Bundle</dt> <dd> A [directory structure](bundle.md) that is... </dd> to get Markdown-style links in the defintion itself. b. A Markdown list (* ...) would have reasonable default styling, but there's no Markdown syntax for adding anchors to the entries. And a glossary is much less useful if you can't link to a specific entry. Signed-off-by: W. Trevor King <wking@tremily.us>
2015-08-12 01:15:20 +08:00
## Container
An environment for executing processes with configurable isolation and resource limitations.
For example, namespaces, resource limits, and mounts are all part of the container environment.
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
## Container namespace
On Linux, a leaf in the [namespace][namespaces.7] hierarchy in which the [configured process](config.md#process-configuration) executes.
glossary: Specify UTF-8 for all our JSON I wish there was a cleaner reference for what UTF-8 was. But [1] seems too glib, and I can't find a more targetted link than just dropping folks into a Unicode chapter (which is what [1] does): The Unicode Standard, Version 6.0, §3.9 D92, §3.10 D95 (2011) With the current v8.0 (2015-06-17), it's still §3.9 D92 and §3.10 D95. I'd rather put this normative requirement in the configuration-spec files, but maintainer consensus was to put it in the glossary [2,3]. [1]: https://en.wikipedia.org/wiki/UTF-8 [2]: https://github.com/opencontainers/specs/pull/146#issuecomment-138970417 [3]: https://github.com/opencontainers/specs/pull/146#issuecomment-143348788 Signed-off-by: W. Trevor King <wking@tremily.us>
2015-09-26 06:09:03 +08:00
## JSON
All configuration [JSON][] MUST be encoded in [UTF-8][].
glossary: Provide a quick overview of important terms And link them to the more detailed specification. Subsection titles for the entries will be obnoxiously spacious, but the other alternatives seem worse: a. An HTML definition list (<dl>) would have nice default styling, but it's annoying to write raw HTML. And we would have needed something like: <dt name="bundle">Bundle</dt> <dd> A [directory structure](bundle.md) that is... </dd> to get Markdown-style links in the defintion itself. b. A Markdown list (* ...) would have reasonable default styling, but there's no Markdown syntax for adding anchors to the entries. And a glossary is much less useful if you can't link to a specific entry. Signed-off-by: W. Trevor King <wking@tremily.us>
2015-08-12 01:15:20 +08:00
## Runtime
An implementation of this specification.
It reads the [configuration files](#configuration) from a [bundle](#bundle), uses that information to create a [container](#container), launches a process inside the container, and performs other [lifecycle actions](runtime.md).
glossary: Specify UTF-8 for all our JSON I wish there was a cleaner reference for what UTF-8 was. But [1] seems too glib, and I can't find a more targetted link than just dropping folks into a Unicode chapter (which is what [1] does): The Unicode Standard, Version 6.0, §3.9 D92, §3.10 D95 (2011) With the current v8.0 (2015-06-17), it's still §3.9 D92 and §3.10 D95. I'd rather put this normative requirement in the configuration-spec files, but maintainer consensus was to put it in the glossary [2,3]. [1]: https://en.wikipedia.org/wiki/UTF-8 [2]: https://github.com/opencontainers/specs/pull/146#issuecomment-138970417 [3]: https://github.com/opencontainers/specs/pull/146#issuecomment-143348788 Signed-off-by: W. Trevor King <wking@tremily.us>
2015-09-26 06:09:03 +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
## Runtime namespace
On Linux, a leaf in the [namespace][namespaces.7] hierarchy from which the [runtime](#runtime) process is executed.
New container namespaces will be created as children of the runtime namespaces.
glossary: Specify UTF-8 for all our JSON I wish there was a cleaner reference for what UTF-8 was. But [1] seems too glib, and I can't find a more targetted link than just dropping folks into a Unicode chapter (which is what [1] does): The Unicode Standard, Version 6.0, §3.9 D92, §3.10 D95 (2011) With the current v8.0 (2015-06-17), it's still §3.9 D92 and §3.10 D95. I'd rather put this normative requirement in the configuration-spec files, but maintainer consensus was to put it in the glossary [2,3]. [1]: https://en.wikipedia.org/wiki/UTF-8 [2]: https://github.com/opencontainers/specs/pull/146#issuecomment-138970417 [3]: https://github.com/opencontainers/specs/pull/146#issuecomment-143348788 Signed-off-by: W. Trevor King <wking@tremily.us>
2015-09-26 06:09:03 +08:00
[JSON]: http://json.org/
[UTF-8]: http://www.unicode.org/versions/Unicode8.0.0/ch03.pdf
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
[namespaces.7]: http://man7.org/linux/man-pages/man7/namespaces.7.html