Commit Graph

8 Commits

Author SHA1 Message Date
Jesse Butler f9dc90b05a make link usage consistent across the specification
Signed-off-by: Jesse Butler <jesse.butler@oracle.com>
2017-03-03 14:43:09 -05:00
Rob Dolin (MSFT) 1be56db14c [Glossary] Add anchor tags for headings
Signed-off-by: Rob Dolin <robdolin@microsoft.com>
2016-11-30 16:33:27 -08:00
W. Trevor King bf9694db6e config: Change "Process configuration" -> "Process" header
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>
2016-11-10 20:43:51 -08:00
W. Trevor King eeaccfabf9 glossary: Make objects explicitly unordered and forbid duplicate names
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>
2016-09-27 09:23:17 -07:00
W. Trevor King 5dad125595 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>
2016-03-16 14:47:29 -07:00
W. Trevor King cb2da5430a 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>
2016-01-27 09:51:54 -08:00
W. Trevor King 0f9ec22bd4 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-12-23 09:27:30 -08:00
W. Trevor King 18734986bc 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-12-23 09:27:30 -08:00