Pull the empty-key restriction out into its own sentence (instead of
leaving it in the middle of the uniqueness restriction).
Drop the "best practice" portion, because the following line is "Keys
SHOULD be named using a reverse domain notation...", which covers that
idea more explicitly.
Signed-off-by: W. Trevor King <wking@tremily.us>
This restriction originally landed via 02b456e9 (Clarify behavior
around namespaces paths, 2015-09-08, #158). The hostname case landed
via 66a0543e (config: Require a new UTS namespace for config.json's
hostname, 2015-10-05, #214) citing the namespace restriction. The
restriciton extended to runtime namespaces in 01c2d55f (config-linux:
Extend no-tweak requirement to runtime namespaces, 2016-08-24, #538).
There was a proposal in-flight to get config-wide consistency around
the no-tweaking concept [1].
In today's meeting, the maintainer consensus was to strike the
no-tweaking restriction [2], which is what I've done here. I've
removed the ROADMAP entry because this gives folks a way to adjust
existing containers (launch a new container which joins and tweaks the
original).
The hostname entry still mentions the UTS namespace to provide a guard
against accidental foot-gunning. There was no no-tweaking language
for properties related to other namespaces (e.g. 'mounts').
Maybe the other namespaces have more obvious names.
[1]: https://github.com/opencontainers/runtime-spec/pull/540
[2]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2017/opencontainers.2017-01-11-22.04.log.html#l-117
Signed-off-by: W. Trevor King <wking@tremily.us>
This punts the awkward-to-enforce "MUST be available at the given path
inside of the rootfs" to the kernel, which will do a much better job
of enforcing that constraint than runtime code or a static validator.
It also punts most of the semantics to POSIX, which does a better job
than we'll do at specifying this. The extension is necessary because
POSIX allows argv to be empty. In the DESCRIPTION:
The argument arg0 should point to a filename that is associated with
the process being started by one of the exec functions.
And in RATIONALE:
Early proposals required that the value of argc passed to main() be
"one or greater". This was driven by the same requirement in drafts
of the ISO C standard. In fact, historical implementations have
passed a value of zero when no arguments are supplied to the caller
of the exec functions. This requirement was removed from the ISO C
standard and subsequently removed from this volume of IEEE Std
1003.1-2001 as well. The wording, in particular the use of the word
should, requires a Strictly Conforming POSIX Application to pass at
least one argument to the exec function, thus guaranteeing that argc
be one or greater when invoked by such an application. In fact,
this is good practice, since many existing applications reference
argv[0] without first checking the value of argc.
But with an empty 'args' we will have no process to call (since
process lacks an explicit 'file' analog).
I chose the 2001/2004 POSIX spec for consistency with the existing
reference (which landed in 7ac41c69, config.md: reformat into a
standard style, 2015-06-30, which did not motivate it's use of an
older standard). For 2001 vs. 2004, [1] has:
Abstract: The 2004 edition incorporates Technical Corrigendum Number
1 and Technical Corrigendum 2 addressing problems discovered since
the approval of the 2001 edition. These are mainly due to resolving
integration issues raised by the merger of the Base documents.
and the text in the linked pages uses "IEEE Std 1003.1-2001" for
internal linking.
Rob Dolin had suggested "platform-appropriate" wording [2], but it
seems like Visual Studio 2015 supports execvp [3], and providing an
explicit "platform-appropriate" wiggle seems like it's adding useless
complication.
[1]: http://pubs.opengroup.org/onlinepubs/009695399/mindex.html
[2]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2016/opencontainers.2016-05-18-17.01.log.html#l-54
[3]: https://msdn.microsoft.com/en-us/library/3xw6zy53.aspx
Signed-off-by: W. Trevor King <wking@tremily.us>
The uppercase letter / digit / underscore restriction is just for
"variables used by the utilities in the Shell and Utilities volume of
IEEE Std 1003.1-2001".
Copying over some POSIX wording and then linking to POSIX didn't seem
like much gain. Just point people at POSIX and let them read about
the name=value definition, charset suggestions, etc. there.
Also link specifically to chapter 8 section 1 (instead of just chapter
8).
Rob Dolin had suggested "platform-appropriate" wording [1], but it
seems like Visual Studio 2015 supports an environment-variable array
with the same semantics [2], and providing an explicit
"platform-appropriate" wiggle seems like it's adding useless
complication.
[1]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2016/opencontainers.2016-05-18-17.01.log.html#l-54
[2]: https://msdn.microsoft.com/en-us/library/431x4c1w.aspx
Signed-off-by: W. Trevor King <wking@tremily.us>
The shift happened in c35cf573 (config: Replace "optional" with
"OPTIONAL", 2016-09-17, #574) and the 'windows' entry landed in
parallel with dc8f2c2 (Add support for Windows-based containers,
2016-09-16, #573).
Signed-off-by: W. Trevor King <wking@tremily.us>
The note is from 7c9daeba (Introducing Solaris in OCI, 2016-04-25,
#411), but as I pointed out there [1], this is also true for Linux.
08908d6f (config: Explicit container namespace for uid, gid, and
additionalGids, 2016-04-29, #412) landed in parallel with more
explicit namepacing for these fields, so we no longer need the
overly-specific Solaris note.
[1]: https://github.com/opencontainers/runtime-spec/pull/411#r61620322
Signed-off-by: W. Trevor King <wking@tremily.us>
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>
This happened in c35cf573 (config: Replace "optional" with "OPTIONAL",
2016-09-17, #574) but was accidentally rolled back in 52f3cdec
(Clarify wording for terminal setting and /dev/console, 2016-07-18,
#518).
Signed-off-by: W. Trevor King <wking@tremily.us>
'destination' has been the path inside the container since c18c283a
(Change layout of mountpoints and mounts, 2015-09-02, #136). My
personal preference is to have an explicit pivot root and allow paths
relative to the current working directory [1], but that would be a big
shift from the current OCI spec. The only way the current spec lets
you turn off the root pivot is by not setting a mount namespace at all
(and even then, it's not clear if that turns off the pivot). And the
config's root entry is required (despite my attempts to have it made
optional [2]), so it's not really clear how containers that don't set
a mount namespace are supposed to work (if they're supported at all).
You might be able to get away with something like:
When a mount namespace is not set, destination paths are relative to
the runtime's initial working directory (or relative to the
config.json, or whatever). When a mount namespace is set,
destination paths are relative to the mount namespace's root.
but with mount-namespace-less containers already so unclear, it seems
better to just require absolute destinations. If/when we get clearer
support for explicit pivot-root calls or containers that inherit the
host mount namespace (without re-joining it and losing their old
working directory), we can consider lifting the absolute-path
restriction.
[1]: https://github.com/wking/ccon/tree/v0.4.0#mount-namespace
[2]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/6ZKMNWujDhU
Date: Wed, 26 Aug 2015 12:54:47 -0700
Subject: Dropping the rootfs requirement and restoring arbitrary bundle
content
Message-ID: <20150826195447.GX21585@odin.tremily.us>
Signed-off-by: W. Trevor King <wking@tremily.us>
In all of these cases we want to use the RFC 2119 semantics.
Generated with:
$ sed -i 's/required/REQUIRED/g' config*.md
after which I rolled back the change for:
...controllers required to fulfill...
since that was already MUSTed.
Signed-off-by: W. Trevor King <wking@tremily.us>
In all of these cases we want to use the RFC 2119 semantics.
Generated with:
$ sed -i 's/optional/OPTIONAL/g' config*.md
Signed-off-by: W. Trevor King <wking@tremily.us>
There are other APIs described in this specification (e.g. the state
JSON format, and the in-flight command-line API [1]), but this string
covers the configuration file and referenced objects (e.g. the
filesystem at root.path). As additional, backwards compatible
features are added to the spec (leading to 1.1, 1.2, etc. releases)
and supported by runtimes, those runtimes will *still* stupport 1.0
configs. Once a 2.0 spec is cut, runtimes that only support 2.0 (and
nothing in the 1.0 line) will no longer support the 1.0 config.
My preferred approach here would be to use JSON-LD [2,3,4] to
explicitly document the intended semantics for each field, which would
allow us to drop the config-wide version and version each field
independently. That would mean a breaking change on a particular
field would only break compatibility for folks who were using that
field. Unfortunately, I haven't had much luck pushing the consensus
in that direction.
This commit does not add wording about how the runtime and other
consumers should handle an incompatible version. We can address that
once the command-line API lands.
[1]: https://github.com/opencontainers/runtime-spec/pull/513
[2]: https://github.com/opencontainers/runtime-spec/pull/371#issuecomment-209684002
[3]: https://github.com/opencontainers/image-spec/pull/111#discussion_r65619280
[4]: https://github.com/opencontainers/runtime-spec/pull/510#discussion_r68513241
Signed-off-by: W. Trevor King <wking@tremily.us>
There's an outside change that these are intentional, since I pointed
one of these out earlier [1] and it wasn't fixed. But I haven't seen
" : " used intentionally outside of this project, and don't think we
want to break ground in that direction ;).
[1]: https://github.com/opencontainers/runtime-spec/pull/510#discussion_r77291554
Signed-off-by: W. Trevor King <wking@tremily.us>
I've replaced the old OPTIONAL with our usual:
(<type>, <optional|required>)
to get the property name first, since that translates more directly
into a Go comment that godoc will like.
The new Go comment is much shorter, dropping "unstructured" (because
the Markdown says "structured or unstructured") and "set by external
tools..." (because *everything* in the configuration JSON is set by
external-to-the-runtime tools).
Signed-off-by: W. Trevor King <wking@tremily.us>
The new wording isn't particularly close to either of the old
wordings, but it reads more clearly to me. I've also added our usual:
(<type>, <required|optional>)
to the Markdown so folks can see that this is an optional object
(although see [1] for a more complete version).
[1]: https://github.com/opencontainers/runtime-spec/pull/427
Subject: config: Explicitly list 'hooks' as optional
Signed-off-by: W. Trevor King <wking@tremily.us>
I've replaced the old MAY with our usual
(<type>, <optional|required>)
to get the property name first, since that translates more directly
into a Go comment that godoc will like.
Signed-off-by: W. Trevor King <wking@tremily.us>
I've changed the old "as it is accessible to ..." to the more compact
"as seen by ..." language from the old Markdown version, although I
don't think it's strictly necessary. The original "accessbile to"
language is from 77d44b10 (Update runtime.md, 2015-06-16), which
actually looked fairly similar to the language I'm using here. That
commit's "hostname for the container" lanuage went away in 7ac41c69
(config.md: reformat into a standard style, 2015-06-30), although that
commit made too many changes to motivate them all at that level.
I've left that language out of the Go comment, because truncating for
compact Go comments is fine (the Markdown entry is canonical, and the
Go comment is just to provide some minimal context).
Signed-off-by: W. Trevor King <wking@tremily.us>
I've also added our usual:
(<type>, <required|optional>)
to the Markdown so folks can see that this is a required object.
Signed-off-by: W. Trevor King <wking@tremily.us>
I've dropped "main process" because "container process" is currently a
much more popular way of identifying that process in this
specification. Before this commit:
$ git grep -i 'main process' | wc -l
4
$ git grep -i 'container process' | wc -l
13
I've also added our usual:
(<type>, <required|optional>)
to the Markdown so folks can see that this is a required object.
Signed-off-by: W. Trevor King <wking@tremily.us>
Don't mention OS and Arch, since they're covered by the list (in
Markdown) and Platform struct (in Go). This gives us one less place
to update if we ever change the schema for the platform object.
Signed-off-by: W. Trevor King <wking@tremily.us>
Catch up with the spec title from faad7e0f (README: title rename,
2016-04-04, #365).
Also make the Go comment consistent with the Markdown spec (no need to
maintain two phrasings for the same idea). The only difference
between the phrasings is now some shuffling at the beginning to start
off with the property name (to keep godoc happy).
The JSON Schema entry (in defs.json) is different too, because it has
to apply to both the configuration and state JSON, so mentioning
"bundle" makes less sense than mentioning "document".
Signed-off-by: W. Trevor King <wking@tremily.us>
This slipped through the rename in 2a5986f7 (schema/state-schema.json:
Add a JSON Schema for the state JSON, 2016-06-01, #481) and the first
round of fixes in dfb85b16 (schema/README: Fix links to
(config|state)-schema.json, 2016-06-13, #498). Reported by hapnermw
[1].
[1]: https://github.com/opencontainers/runtime-spec/issues/517
Signed-off-by: W. Trevor King <wking@tremily.us>
This reverts commit 0f25f18b9b, #253.
Now that we're on to 1.0, we don't need to talk about 0.x. And the
lack of 0.x backwards compatability is covered by SemVer 2.0 section 4
[1]:
Major version zero (0.y.z) is for initial development. Anything may
change at any time. The public API should not be considered stable.
so removing the echo from our spec doesn't actually change anything.
The conflict is due to 4e63ee0a (config: qualify the name of the
version field, 2016-01-13, #309), and only impacted the context and
line-wrapping around the sentence I'm removing.
Conflicts:
config.md
[1]: http://semver.org/spec/v2.0.0.html
Signed-off-by: W. Trevor King <wking@tremily.us>
W. Trevor King
Mrunal Patel
Ma Shimiao
Qiang Huang
Daniel, Dao Quang Minh
Mrunal Patel
Abhijeeth Nuthan
Vincent Batts
John Howard
Doug Davis
Michael Crosby