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>
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>
In the degenerate case where the container does not create a user
namespace, the "container namespace" distinction is unimportant, but
the phrasing is still accurate (the container and runtime namespaces
are the same).
Signed-off-by: W. Trevor King <wking@tremily.us>
The old platform.os text had two MUST conditions. The first could
have been read "the runtime MUST generate an error if invoked with a
config.json whose platform.os is incompatible with the host platform"
(which is the direction I'm going with this commit). However, it
could also have been read "the bundle-validator MUST generate an error
if platform.os is incompatible with the content the bundle's other
content (e.g. 'linux' in platform.os, but only Windows binaries in the
bundle's rootfs).
For the second MUST, I doubt we want to require a compliant runtime
support all Go architectures itself. And there is a benefit to
pointing runtime/bundle authors at the Go set, but not much benefit in
making that a hard limit [1,2]. The rewording here follows [2] in
acknowledging that process.arch-matching is something that the config
author and runtime caller have to sort out between themselves and
pointing them at the Go docs and a registration process to avoid
fragmenting the community.
[1]: https://github.com/opencontainers/image-spec/pull/29
[2]: https://github.com/opencontainers/image-spec/pull/60
Signed-off-by: W. Trevor King <wking@tremily.us>
This was raised during reviews with folks working on Windows Containers.
This squashes commits from PR #433
Signed-off-by: Rob Dolin <RobDolin@microsoft.com>
This should have been part of 759ee79c (config: Add
platform-specific entry for 'solaris', 2016-05-06, #431), since
the example has platform.os set to 'linux'.
There was some (brief) discussion of this point before the 'solaris'
section landed [1], but the "should only be set if" wording landed in
parallel via b373a15 (config: Split platform-specific configuration
into its own section, 2016-05-02, #414), and I'd forgotten to go back
and apply that logic to #411.
Having a full Solaris example would be useful, but I think it should
be a separate, Solaris-only example.
[1]: https://github.com/opencontainers/runtime-spec/pull/411#discussion_r61621001
Signed-off-by: W. Trevor King <wking@tremily.us>
W. Trevor King
Qiang Huang
Daniel, Dao Quang Minh
Mrunal Patel
Mrunal Patel
Abhijeeth Nuthan
Vincent Batts
John Howard
Ma Shimiao
Doug Davis
Michael Crosby
Aleksa Sarai
Rob Dolin (MSFT)