Signed-off-by: Julian Friedman <[email protected]>

To match the specs convention [1].

[1]: https://github.com/opencontainers/specs/blob/v0.1.1/README.md#markdown-style

Signed-off-by: W. Trevor King <[email protected]>

Otherwise they're rendered as a single paragraph.

Signed-off-by: W. Trevor King <[email protected]>

See [1].  'sh' keyword comes from [2], and seemed more explicit to the
POSIX semantics than 'shell'.

[1]: https://help.github.com/articles/github-flavored-markdown/#syntax-highlighting
[2]: https://github.com/github/linguist/blob/master/lib/linguist/languages.yml

Signed-off-by: W. Trevor King <[email protected]>

It's pretty clear that the header describes the rest of the file's
contents without the colon ;).

Signed-off-by: W. Trevor King <[email protected]>

I think that's the possessive form of 'process' ;).

Signed-off-by: W. Trevor King <[email protected]>

To give space for more detail about the streams.

I'm not sure what platform-agnostic language for this should look
like, but on POSIX I'm expecting just exec'ing the application process
and inheriting the file descriptors.

Signed-off-by: W. Trevor King <[email protected]>

Signed-off-by: W. Trevor King <[email protected]>

Catch up with [1].

[1]: opencontainers/runtime-spec#88

Signed-off-by: W. Trevor King <[email protected]>

Use GNU-style long options to avoid ambiguous, one-character options
in the spec, while still allowing the runtime to support one-character
options with packing.

Signed-off-by: W. Trevor King <[email protected]>

Let folks do whatever they want as long as they don't clobber our
command namespace.

Signed-off-by: W. Trevor King <[email protected]>

Make it easy for a caller to report which runtime they're using.

Signed-off-by: W. Trevor King <[email protected]>

Give the user a consistent way to pick their container ID.  For example, they may want to use:

  --id $(dirname "$PWD")

or they may want to use:

  --id $(uuidgen)

or they may want to leave ID generation to the runtime.

Signed-off-by: W. Trevor King <[email protected]>

You shouldn't need these for any other operations.

Signed-off-by: W. Trevor King <[email protected]>

Signed-off-by: W. Trevor King <[email protected]>

Mostly for stopping them, but also useful for any number of signals
(e.g. many applications use HUP to reload their configuration).

Signed-off-by: W. Trevor King <[email protected]>

On IRC just now:

10:56 < crosbymichael> if the main process dies in the container, all other process are killed
...
10:58 < julz> crosbymichael: Im assuming what you mean is you kill everything in the cgroup -> everything in the container dies?
10:58 < crosbymichael> julz: yes, that is how its implemented
...
10:59 < crosbymichael> julz: we actually freeze first, send the KILL, then unfreeze so we don't have races

We don't have lifecycle docs for that yet, but once we do, we can
update this to link to them.

Signed-off-by: W. Trevor King <[email protected]>

These are useful for checkpointing, since getting a consistent
checkpoint of a running container is hard ;).  This doesn't handle the
checkpoints themselves though, which are currently not specified.
Checkpoint behavior will look something like:

  $ funC pause --wait container-id
  $ checkpoint ...
  $ funC resume container-id

Signed-off-by: W. Trevor King <[email protected]>

This landed in runC with [1], but the bundle-author <-> runtime specs
explicitly avoid talking about how this is set (since the
bundle-author doesn't care about the runtime-caller <-> runtime
interface) [2].  However, *this* spec is about the runtime-caller <->
runtime interface, so we need to document it here.

I've left LISTEN_PID [3,4] out, since I don't see how the
runtime-caller would choose anything other than 1 for its value.  It
seems like something that a process would have to set for itself
(because guessing the PID of a child before spawning it seems racy ;).
In any event, the runC implementation seems to set this to 1
regardless of what systemd passes to it [4].

I've borrowed Shishir's wording for the example [4].

[1]: opencontainers/runc#231
[2]: opencontainers/runtime-spec#113 (comment)
[3]: http://www.freedesktop.org/software/systemd/man/sd_listen_fds.html
[4]: opencontainers/runc#231 (comment)

Signed-off-by: W. Trevor King <[email protected]>

Signed-off-by: Michael Crosby <[email protected]>

Cherry-picked from [1].

[1]: opencontainers/runtime-spec@84707b0

Signed-off-by: W. Trevor King <[email protected]>

See https://github.com/blog/1184-contributing-guidelines

Also strip some trailing whitespace.

Signed-off-by: W. Trevor King <[email protected]>

Signed-off-by: W. Trevor King <[email protected]>

Without this, "may contain any Unicode characters" seemed too
ambiguous.

I wish there were cleaner references for the {language}.{encoding}
locales like en_US.UTF-8 and UTF-8.  But [1,2] seems too glib, and I
can't find a more targetted UTF-8 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.

The TR35 link is for:

  In addition, POSIX locales may also specify the character encoding,
  which requires the data to be transformed into that target encoding.

and the POSIX §6.2 link is for:

  In other locales, the presence, meaning, and representation of any
  additional characters are locale-specific.

[1]: https://en.wikipedia.org/wiki/UTF-8
[2]: https://en.wikipedia.org/wiki/Locale#POSIX_platforms

Signed-off-by: W. Trevor King <[email protected]>
Reviewed-by: Jesse Butler <[email protected]>

The other commands have the following layout:

  ### {command name}

  {one-line description}

  * *Options:* ...
  ...
  * *Exit code:* ...

  {additional notes}

  {example}

so its good to follow that pattern for 'version'.

This commit also removes a dangling "The version" which snuck in with
ffa124c (Add a 'version' command, 2015-09-14).

Signed-off-by: W. Trevor King <[email protected]>
Reviewed-by: Mike Brown <[email protected]>

With:

  $ sed -i 's/[[:space:]]*$//' *

Signed-off-by: W. Trevor King <[email protected]>
Reviewed-by: Mike Brown <[email protected]>

All of these require state information to be shared between funC
invocations (to map from a container ID to the
cgroups/namespaces/etc.), and after today's meeting we may be backing
away from that [1,2].  Even if we keep a requirement for sharing state
between funC invocations, we don't want to specify these IPC-requiring
commands until we have more clarity on that requirement in the spec.

On systems like Solaris, the kernel maintains a registry of container
IDs directly, so they don't need an external registry [3].  But
without a consensus around the minimal amount of inter-process state
sharing, we don't want to require container ID → state lookups in the
command-line spec.  Once we have more clarity on a minimal required
mechanism (e.g. Julz's --state-file [4,5,6]), we can add them back in
with an API that all runtimes can easily support (although runtimes
are of course free to provide more convenient APIs as additional
extensions).

Pause, resume, and signal are still in the current lifecycle pull
request [7], but I've requested they be removed until we have more
clarity around the basic lifecycle [8].

[1]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2015/opencontainers.2015-12-02-18.01.html
[2]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2015/opencontainers.2015-12-02-18.01.log.html#l-79
[3]: wking/oci-command-line-api#3 (comment)
[4]: wking/oci-command-line-api#3 (comment)
[5]: wking/oci-command-line-api#3 (comment)
[6]: wking/oci-command-line-api#3 (comment)
[7]: mrunalp/specs@bd549a2#diff-b84a8d65d8ed53f4794cd2db7e8ea731R48
[8]: https://github.com/opencontainers/specs/pull/231/files#r45532412

Signed-off-by: W. Trevor King <[email protected]>
Reviewed-by: Mike Brown <[email protected]>
Reviewed-by: Jesse Butler <[email protected]>
Reviewed-by: Julian Friedman <[email protected]>

This makes everything consistent with the version command's:

  Print the runtime version and exit.

And follows the practice recommended by Python's PEP 257 [1]:

  The docstring is a phrase ending in a period. It prescribes the
  function or method's effect as a command ("Do this", "Return that"),
  not as a description; e.g. don't write "Returns the pathname ...".

[1]: https://www.python.org/dev/peps/pep-0257/#one-line-docstrings

Signed-off-by: W. Trevor King <[email protected]>
Reviewed-by: Mike Brown <[email protected]>

The reference landed in the initial 3f0aafb (Add initial command line
spec, 2015-09-02) in the operations section.  In f3a1c08 (Shift
config.json and runtime.json into the 'start' section, 2015-09-15)
they moved to the 'start' command section, because other commands
don't need them.  But we talk about them in start's options section
since 9d97d39 (Add --config and --runtime options, 2015-09-14), so
there's no need for this command-scoped reference.

Signed-off-by: W. Trevor King <[email protected]>
Reviewed-by: Mike Brown <[email protected]>

While reviewing the `global options` section in `runtime.md`, it seemed additional clarity
was needed for the `command` and `global options` requirements.

Discussed and worked on wording with @wking via private IRC.

Also adds uppercase RFC 2119 words for this section.

With regard to the statement `Command names MUST not start with hyphens,` the rationale
behind this decision is to "distinguish unrecognized commands from unrecognized options,
and because we are "requiring runtimes to fail-fast for unrecognized commands" [1,2].

`[1]` https://github.com/wking/oci-command-line-api/pull/8/files#r46898167
`[2]` wking/oci-command-line-api@527f3c6#commitcomment-14835617

Signed-off-by: Mike Brown <[email protected]>
Reviewed-by: W. Trevor King <[email protected]>

Personally I prefer a single config file [1].  I want folks to be able
to pipe their config into the 'funC start' command (e.g. via a
/dev/fd/3 pseudo-filesystem path) [2], and I have a working example
that supports this without difficulty [3].  But since [4] landed on
2015-11-16, runC has replaced their --config-file and --runtime-file
flags with --bundle, and the current goal of this repository is
"keeping as much similarity with the existing runC command-line as
possible", not "makes sense to Trevor" ;).

[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: <[email protected]>
[2]: opencontainers/runc#202
[3]: https://github.com/wking/ccon/tree/8ab5b535b5eca1a62e12b5e865735e24f1e1666d#configuration
[4]: opencontainers/runc#373

Signed-off-by: W. Trevor King <[email protected]>
Reviewed-by: Mike Brown <[email protected]>

This approach has landed in opencontainers/specs [1,2].  You can find
the RFC here [3].

[1]: opencontainers/runtime-spec#256
[2]: opencontainers/runtime-spec#260
[3]: http://tools.ietf.org/html/rfc2119

Signed-off-by: W. Trevor King <[email protected]>
Reviewed-by: Mike Brown <[email protected]>

Fix a typo from 3606bcf (Punt to the operating system for character
encodings, 2015-12-02).

Signed-off-by: W. Trevor King <[email protected]>

Because these are shell sessions, not scripts (e.g. we don't want
'for' in the version output highlighted as a keyword).  Rolls back
4dfe30b ('sh' syntax highlighting for fenced code blocks,
2015-09-14).

Signed-off-by: W. Trevor King <[email protected]>

To provide anchors for linking [1].

[1]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc1/style.md#anchoring

Signed-off-by: W. Trevor King <[email protected]>

Partially catch up with opencontainers/runtime-spec@7117ede7 (Expand
on the definition of our ops, 2015-10-13,
opencontainers/runtime-spec#225, v0.4.0).  The state example is
adapted from the current release [1], but we defer the actual
definition of that JSON to runtime-spec.

The encoding for the output JSON (and all standard-stream activity) is
covered by the "Character encodings" section.  In cases where the
runtime ignores the SHOULD (still technically compliant), RFC 7159
makes encoding detection reasonably straightforward [2].  The obsolete
RFC 4627 has some hints as well [3] (although these were dropped in
RFC 7518 [4], probably as a result of removing the constraint that
"JSON text" be an object or array [4]).  The hints should still apply
to the state output, because we know it will be an object.  If that
ends up being too dicey and we want to certify runtimes that do not
respect their operating-system conventions, we can add an --encoding
option later.

[1]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc1/runtime.md#state
[2]: https://tools.ietf.org/html/rfc7159#section-8.1
[3]: https://tools.ietf.org/html/rfc4627#section-3
[4]: https://tools.ietf.org/html/rfc7158#appendix-A
     Which is currently identical to 7519.

Signed-off-by: W. Trevor King <[email protected]>

These slipped through e41ffc1 (Use RFC 2119's keywords (MUST, MAY,
...), 2015-12-02, opencontainers#9).

Signed-off-by: W. Trevor King <[email protected]>

This hadn't been touched since 2015-12-02, and was getting pretty
stale ;).

Signed-off-by: W. Trevor King <[email protected]>

Pick a better title.

Signed-off-by: W. Trevor King <[email protected]>

The command-line interface is largely orthogonal to the config format,
and config authors and runtime callers may be entirely different sets
of people.  Zhang Wei called for more explicit versioning for the CLI
[1].

Wedging multiple, independently versioned entities into a single
repository can be awkward, but earlier proposals to put the CLI in its
own repository [2] were unsuccessful because compliance testing
requires both a CLI and a config specification [3].  I don't think
that's a solid reason [4], but discussion along that line stalled out,
before being revived in today's meeting.  Unfortunately, now this CLI
spec is destined for runtime-tools [5], so we may still have multiple,
independently versioned entities in a single repository.  Wherever
this lands up, it's useful for this CLI spec to be clear about it's
own versioning.

[1]: opencontainers/runtime-spec#513 (comment)
[2]: opencontainers/runtime-spec#513 (comment)
[3]: opencontainers/runtime-spec#513 (comment)
[4]: opencontainers/runtime-spec#513 (comment)
[5]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2017/opencontainers.2017-02-08-22.00.log.html#l-125

Signed-off-by: W. Trevor King <[email protected]>

Fix an instance missed by 7704531 (runtime: Drop 'sh' highlighting
from fenced code blocks, 2016-06-22, wking/oci-command-line-api#15).

Signed-off-by: W. Trevor King <[email protected]>

Signed-off-by: W. Trevor King <[email protected]>

Make it clear that runtimes are free to add additional commands and
options as they see fit (although namespacing to avoid collision with
future versions of this specification would be wise).

Signed-off-by: W. Trevor King <[email protected]>

Having a 'version' command to make it easy for a caller to report
which runtime they're using.  But we don't have a use-case that makes
it strictly necessary for interop, so we're leaving it out for now
[1].

[1]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2016/opencontainers.2016-07-20-21.03.log.html#l-75

Signed-off-by: W. Trevor King <[email protected]>

Following opencontainers/runtime-spec@7795661 (runtime.md: Fix
sub-bullet indentation, 2016-06-08, opencontainers/runtime-spec#495).
From [1]:

  List items may consist of multiple paragraphs.  Each subsequent
  paragraph in a list item must be indented by either 4 spaces or one
  tab...

I expect that's intended to be read with "block element" instead
of "paragraph", in which case it applies to nested lists too.

And while GitHub supports two-space indents [2]:

  You can create nested lists by indenting lines by two spaces.

it seems that pandoc does not.

[1]: http://daringfireball.net/projects/markdown/syntax#list
[2]: https://help.github.com/articles/basic-writing-and-formatting-syntax/#lists

Signed-off-by: W. Trevor King <[email protected]>

Similar to the 'signal' command removed in b922732 (Drop exec, pause,
resume, and signal, 2015-12-02, wking/oci-command-line-api#3).  The
runtime-spec gained a kill operation as part of
opencontainers/runtime-spec@be594153 (Split create and start,
2016-04-01, opencontainers/runtime-spec#384).  The interface is based
on POSIX [1], util-linux [2], and GNU coreutils [3].

The TERM/KILL requirement is a minimum portability requirement for
soft/hard stops.  Windows lacks POSIX signals [4], and currently
supports soft stops in Docker with whatever is behind
hcsshim.ShutdownComputeSystem [5].  The docs we're landing here
explicitly allow that sort of substitution, because we need to have
soft/hard stop on those platforms but *can't* use POSIX signals.  They
borrow wording from opencontainers/runtime-spec@35b0e9ee (config:
Clarify MUST for platform.os and .arch, 2016-05-19,
opencontainers/runtime-spec#441) to recommend runtime authors document
the alternative technology so bundle-authors can prepare (e.g. by
installing the equivalent to a SIGTERM signal handler).

[1]: http://pubs.opengroup.org/onlinepubs/9699919799/utilities/kill.html
[2]: http://man7.org/linux/man-pages/man1/kill.1.html
[3]: http://www.gnu.org/software/coreutils/manual/html_node/kill-invocation.html
[4]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/PlGKu7QUwLE
     Subject: Fwd: Windows support for OCI stop/signal/kill (runtime-spec#356)
     Date: Thu, 26 May 2016 11:03:29 -0700
     Message-ID: <[email protected]>
[5]: https://github.com/docker/docker/pull/16997/files#diff-5d0b72cccc4809455d52aadc62329817R230
     moby/moby@bc503ca8 (Windows: [TP4] docker kill handling,
     2015-10-12, moby/moby#16997)

Signed-off-by: W. Trevor King <[email protected]>

Make life easy for folks not familiar with the term.

Signed-off-by: W. Trevor King <[email protected]>

I added this as an option in 5033c59 (Add an --id option to 'start',
2015-09-15), because some callers might want to leave ID generation to
the runtime.  When there is a long-running host process waiting on the
container process to perform cleanup, the runtime-caller may not need
to know the container ID.  However, runC has been requiring a
user-specified ID since [1], and the coming create/start split will
follow the early-exit 'create' from [2], so require an ID here.  We
can revisit this if we regain a long-running 'create' process.

You can create a config that adds no isolation vs. the runtime
namespace or completely joins another set of existing namespaces.  It
seems odd to call that a new "container", but the ID is really more of
a process ID, and less of a container ID.  The "container" phrasing is
just a useful hint that there might be some isolation going on.  And
we're always creating a new "container process" with 'start' (which
will become 'create').

[1]: opencontainers/runc#541
     opencontainers/runc@a7278cad (Require container id as arg1,
     2016-02-08, opencontainers/runc#541)
[2]: opencontainers/runc#827
     Summary: Implement create and start

Signed-off-by: W. Trevor King <[email protected]>

Michael doesn't like "application" [1], and the runtime spec has
standardized around "container process".

[1]: opencontainers/runtime-spec#107 (comment)

Signed-off-by: W. Trevor King <[email protected]>

Catch up with opencontainers/runtime-spec@be594153 (Split create and
start, 2016-04-01, opencontainers/runtime-spec#384).

One benefit of the early-exit 'create' is that the exit code does not
conflate container process exits with "failed to setup the sandbox"
exits.  We can take advantage of that and use non-zero 'create' exits
to allow stderr writing (so the runtime can log errors while dying
without having to successfully connect to syslog or some such).

I still likes the long-running 'create' API because it makes
collecting the exit code easier.  I've proposed an 'event' operation
[1] which would provide a convenient created trigger.  With 'event' in
place, we don't need the 'create' process exit to serve as that
trigger, and could have a long-running 'create' that collects the
container process exit code using the portable waitid() family.  But
the consensus after the 2016-07-13 meeting was to table that while we
land docs for the runC API [2], and runC has an early-exit create [3].

The "Callers MAY block..." wording is going to be hard to enforce, but
with the runC model, clients rely on the command exits to trigger
post-create and post-start activity.  The longer the runtime hangs
around after completing its action, the laggier those triggers will
be.

The "MUST NOT attempt to read from its stdin" means a generic caller
can safely exec the command with a closed or null stdin, and not have
to worry about the command blocking or crashing because of that.  The
stdout spec for start/delete is more lenient, because runtimes are
unlikely to change their behavior because they are unable to write to
stdout.  If this assumption proves troublesome, we may have to tighten
it up later.

The ptrace idea in this commit is from Mrunal [4].

[1]: opencontainers/runtime-spec#508
     Subject: runtime: Add an 'event' operation for subscribing to pushes
[2]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2016/opencontainers.2016-07-13-17.03.log.html#l-15
[3]: opencontainers/runc#827
     Summary: Implement create and start
[4]: http://ircbot.wl.linuxfoundation.org/eavesdrop/%23opencontainers/%23opencontainers.2016-07-13.log.html#t2016-07-13T18:58:54

Signed-off-by: W. Trevor King <[email protected]>

You can get the PID by calling 'state' [1], and container PIDs may not
be portable [2].  But it's a common way for interfacing with init
systems like systemd [3], and for this first pass at the command line
API folks are ok with some Linux-centrism [4].

[1]: opencontainers/runtime-spec#511 (comment)
     Subject: Add initial pass at a cmd line spec
[2]: opencontainers/runtime-spec#459
     Subject: [ Runtime ] Allow for excluding pid from state
[3]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2016/opencontainers.2016-07-20-21.03.log.html#l-69
[4]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2016/opencontainers.2016-07-13-17.03.log.html#l-39

Signed-off-by: W. Trevor King <[email protected]>

Based on work by Aleksa in opencontainers/runc#1018, this commit makes
the following choices:

* SOCK_SEQPACKET instead of SOCK_STREAM, because this is a
  message-based protocol, so it seems more natural to use a
  message-oriented socket type.

* A string 'type' field for all messages, so we can add additional
  message types in the future without breaking backwards compatibility
  (new console-socket servers will still support old clients).  Aleksa
  favored splitting this identifier into an integer 'type' and
  'version' fields [runc-socket-type-version], but I don't see the
  point if they're both opaque integers without internal structure.
  And I expect this protocol to be stable enough that it's not worth
  involving SemVer and its structured versioning.

* Response messages, so the client can tell whether the request was
  received and processed successfully or not.  That gives the client a
  way to bail out if, for example, the server does not support the
  'terminal' message type.

Signed-off-by: W. Trevor King <[email protected]>

As requested by Aleksa [1].

[1]: opencontainers/runtime-spec#513 (comment)

Signed-off-by: W. Trevor King <[email protected]>

As Michael requested [1].  The upsides of this approach are:

* No need to drop the console onto the filesystem.  You can use
  socketpair(2) in the runtime caller and be done with it.
* No need for the runtime to connect (since the connection is already
  open when 'create' is invoked).  This allows you to use
  SOCK_SEQPACKET or SOCK_STREAM as you see fit.

The downsides are:

* Overloading $LISTEN_FDS.  Using a positional-argument approach to
  pass the FD number would feel less magical and make me much happier.

[1]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2016/opencontainers.2016-10-19-21.00.log.html#l-30

Signed-off-by: W. Trevor King <[email protected]>

This bridges the gap between my original '--console-socket PATH'
proposal from 15350b31 (runtime: Add --console-socket for terminal
handling, 2017-02-08) and Michael's approach from baa24120 (runtime:
Replace '--console-socket PATH' with '$LISTEN_FDS + 3', 2017-02-08).
All of the benefits of not needing an on-disk socket, and none of the
magic of overloading $LISTEN_FDS.  I don't know why Michael didn't
like this approach as much [1], but it feels a lot better to me.

[1]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2016/opencontainers.2016-10-19-21.00.log.html#l-31

Signed-off-by: W. Trevor King <[email protected]>

The command line API covered here spent the bulk of a year as a
runtime-spec PR [1], before the maintainers descided today that it
would be better off in runtime-tools [2] (or at least, not in
runtime-spec).  While it was in-flight for runtime-spec, I'd squashed
it down to one unweildy commit, following requests by Doug [3] and
Vincent [4].  Now that the eventual location of the API spec is less
clear (and there are calls for further review [5]), I've split the
semantic changes back out into individual commits to make the
motivation more obvious.  It also makes it easier for folks to PR
their recommendations directly, since review in the runtime-spec PR
was getting unweildy at 250-odd comments.

[1]: opencontainers/runtime-spec#513
[2]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2017/opencontainers.2017-02-08-22.00.log.html#l-125
[3]: opencontainers/runtime-spec#513 (comment)
[4]: opencontainers/runtime-spec#513 (comment)
[5]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2017/opencontainers.2017-02-08-22.00.log.html#l-113

* runtime-spec-513:
  runtime: Replace '$LISTEN_FDS + 3' with '--console-socket FD'
  runtime: Replace '--console-socket PATH' with '$LISTEN_FDS + 3'
  runtime: Mention TIOCSTI privilege escalation
  runtime: Add --console-socket for terminal handling
  runtime: Add --pid-file to 'create'
  runtime: Split 'create' and 'start' (and add 'delete')
  runtime: "application" -> "container"
  runtime: Move start's --id to a positional parameter
  runtime: Link to the spec's 'bundle' docs
  runtime: Add a 'kill' command
  runtime: Four-space indents for nested lists
  runtime: Drop the 'version' command
  runtime: Address unspecified commands and options
  runtime: Fix "MUST not" -> "MUST NOT"
  runtime: Drop 'sh' highlighting from fenced code blocks
  runtime: Semantically version this specification
  *: "OCI Runtime Command Line Interface"
  README: Update links and text

Signed-off-by: W. Trevor King <[email protected]>

Using the RFC's recommended wording [1].

[1]: https://tools.ietf.org/html/rfc2119

Signed-off-by: W. Trevor King <[email protected]>

I had been unaware of formal distinctions between these terms until
Stephen Walli called it out [1] in the context of his suggestion to
use "implementation defined" for uploading
application/vnd.oci.image.layer.nondistributable.tar+gzip [2].  I
couldn't find anything as compact as RFC 2119 around this idea, but
linking to a section of the C99 rationale seems reasonable enough.
The PDF I'm linking is "Rationale for International Standard -
Programming Languages - C Revision 5.10 April-2003" and the referenced
content appears in section 3:

  The terms *unspecified behavior*, *undefined behavior*, and
  *implementation-defined behavior* are used to categorize the result
  of writing programs whose properties the Standard does not, or
  cannot, completely describe.  The goal of adopting this
  categorization is to allow a certain variety among implementations
  which permits *quality of implementation* to be an active force in
  the marketplace as well as to allow certain popular extensions,
  without removing the cachet of *conformance to the Standard*.
  Informative Annex J of the Standard catalogs those behaviors which
  fall into one of these three categories.

  *Unspecified behavior* gives the implementor some latitude in
  translating programs.  This latitude does not extend as far as
  failing to translate the program, however, because all possible
  behaviors are "correct" in the sense that they don't cause undefined
  behavior in *any* implementation.

  *Undefined behavior* gives the implementor license not to catch
  certain program errors that are difficult to diagnose.  It also
  identifies areas of possible conforming language extension: the
  implementor may augment the language by providing a definition of
  the officially undefined behavior.
  *Implementation-defined behavior* gives an implementor the freedom
  to choose the appropriate approach, but requires that this choice be
  explained to the user.  Behaviors designated as
  implementation-defined are generally those in which a user could
  make meaningful coding decisions based on the implementation's
  definition.  Implementors should bear in mind this criterion when
  deciding how extensive an implementation definition ought to be.  As
  with unspecified behavior, simply failing to translate the source
  containing the implementation-defined behavior is not an adequate
  response.

The "rationale for the C99 standard" link text seems pretty informal,
but that's what WG14 uses to refer to the document [3].  And I've got
the full title, revision, date, and referenced text in here in case
the link dies and there is any ambiguity about the particular revision
intended ;).

[1]: opencontainers/image-spec#233 (comment)
[2]: opencontainers/image-spec#233 (comment)
[3]: http://www.open-std.org/jtc1/sc22/wg14/

Signed-off-by: W. Trevor King <[email protected]>

This language is based on existing language in RFC 2616 [1], RFC 7230
[2], and the runtime spec [3].

By defining both "compliant" and "not compliant" we leave the door
open for a third case where an implementation (which can be a runtime
or a runtime caller) does not violate any MUST-level requirements but
does not allow some MUST-level requirements to be tested.  For
example, a runtime whose 'create' always exited with a non-zero exit
code would not allow for testing the output of 'state' calls, because
the test suite would have no valid container ID to use in the 'state'
calls.  Such a runtime would be neither compliant nor non-compliant.

[1]: https://tools.ietf.org/html/rfc2616#section-1.2
[2]: https://tools.ietf.org/html/rfc7230#section-2.5
[3]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/spec.md#notational-conventions

Signed-off-by: W. Trevor King <[email protected]>

runtime-spec already has a runtime.md talking about operations at an
interface-agnostic level.  Rename this file so that it's clearly
limited to the CLI.  runtime-tools doesn't have a runtime.md, but the
more-specific command-line-interface.md will make rebasing a merge
into runtime-tools easier if runtime-tools happens to grow a
runtime.md in the meantime.

Signed-off-by: W. Trevor King <[email protected]>

These were useful when oci-command-line-api was an independent
project, but are not longer needed now that we're folding it into
runtime-tools.

Signed-off-by: W. Trevor King <[email protected]>

…ne-api

* 'runtime-tools' of git://github.com/wking/oci-command-line-api: (59 commits)
  Remove files that duplicate runtime-spec content (LICENSE, etc.)
  command-line-interface: Rename from runtime.md to avoid collisions
  runtime: Add compliance language
  runtime: Define "unspecified", "undefined", and "implementation-defined"
  runtime: Document RFC 2119 wording
  runtime: Replace '$LISTEN_FDS + 3' with '--console-socket FD'
  runtime: Replace '--console-socket PATH' with '$LISTEN_FDS + 3'
  runtime: Mention TIOCSTI privilege escalation
  runtime: Add --console-socket for terminal handling
  runtime: Add --pid-file to 'create'
  runtime: Split 'create' and 'start' (and add 'delete')
  runtime: "application" -> "container"
  runtime: Move start's --id to a positional parameter
  runtime: Link to the spec's 'bundle' docs
  runtime: Add a 'kill' command
  runtime: Four-space indents for nested lists
  runtime: Drop the 'version' command
  runtime: Address unspecified commands and options
  runtime: Fix "MUST not" -> "MUST NOT"
  runtime: Drop 'sh' highlighting from fenced code blocks
  ...

Signed-off-by: W. Trevor King <[email protected]>

With the position requested by Mrunal [1,2].

[1]: http://ircbot.wl.linuxfoundation.org/eavesdrop/%23opencontainers/%23opencontainers.2017-02-09.log.html#t2017-02-09T22:21:59
[2]: http://ircbot.wl.linuxfoundation.org/eavesdrop/%23opencontainers/%23opencontainers.2017-02-10.log.html#t2017-02-10T00:03:25

Signed-off-by: W. Trevor King <[email protected]>

Currently just the command line API, but the test suite might add
support for more APIs in the future.  The command line API itself is
independent of whether the test suite supports additional APIs, so I
put the list of supported APIs in a new file.

Signed-off-by: W. Trevor King <[email protected]>

…ket messages

Even though there aren't many new types, these are fairly different
from the rest of the runtime-tools code, and a separate package lets
folks pull in only the code they need (assuming they are sophisticated
enough to grab only a subset of the Git repository).

Mrunal approved the JSON Schema landing under schema/ [1].

[1]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2017/opencontainers.2017-03-15-21.02.log.html#l-122

Signed-off-by: W. Trevor King <[email protected]>

Catching up with erratum 499 [1].

[1]: https://www.rfc-editor.org/errata_search.php?rfc=2119&eid=499

Signed-off-by: W. Trevor King <[email protected]>