All of these sections are about configuration, and we don't usually
use "{Whatever} configuration" in the headers.
Signed-off-by: W. Trevor King <wking@tremily.us>
Pin down our JSON definition to a particular RFC (which we can
explicitly bump if neccessary), instead of referencing the floating
JSON homepage.
Explicitly make objects unordered and forbid duplicate names to avoid
relying on unportable behavior. RFC 7159 is a bit more relaxed [1]:
The names within an object SHOULD be unique.
but warns [1]:
An object whose names are all unique is interoperable in the sense
that all software implementations receiving that object will agree
on the name-value mappings. When the names within an object are not
unique, the behavior of software that receives such an object is
unpredictable. Many implementations report the last name/value pair
only. Other implementations report an error or fail to parse the
object, and some implementations report all of the name/value pairs,
including duplicates.
The RFC also warns about order portability [1]:
JSON parsing libraries have been observed to differ as to whether or
not they make the ordering of object members visible to calling
software. Implementations whose behavior does not depend on member
ordering will be interoperable in the sense that they will not be
affected by these differences.
And has some (informative?) language about entries being unordered
[2]:
An object is an unordered collection of zero or more name/value
pairs...
[1]: https://tools.ietf.org/html/rfc7159#section-4
[2]: https://tools.ietf.org/html/rfc7159#section-1
Signed-off-by: W. Trevor King <wking@tremily.us>
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>
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>
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>