From 7f11bd8531aa7304d41ef8dc8de950ebff4e3fb9 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 8 Feb 2017 15:28:54 -0800 Subject: [PATCH 01/18] README: Update links and text This hadn't been touched since 2015-12-02, and was getting pretty stale ;). Signed-off-by: W. Trevor King --- README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index b345080..62a65c4 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,14 @@ # OCI command-line API -The [OCI Specifications][specs] currently focus on the bundle-author ↔ runtime interface, but there is renewed interest in specifying a command-line API for the runtime-caller ↔ runtime interface. -A common command-line API would make it easier to build higher-level tools that are runtime-agnostic (e.g. conformance testers like [ocitools][ocitools-test]). +The [OCI Runtime Specification][runtime-spec] currently focuses on the bundle-author ↔ runtime interface, but there is renewed interest in specifying a command-line API for the runtime-caller ↔ runtime interface. +A common command-line API would make it easier to build higher-level tools that are runtime-agnostic (e.g. compliance testers like [runtime-tools][runtime-tools-compliance]). This repository contains initial work on that API, with more detailed discussion in [this thread][thread]. The usual [development rules][rules] apply, and the legal stuff is spelled out [here](CONTRIBUTING.md). -The target for the inital design will be to match [the lifecycle pull request][lifecycle], keeping as much similarity with the existing [runC][] command-line as possible. +The target for the inital design will be to match [the specified lifecycle][lifecycle], keeping as much similarity with the existing [runC][] command-line as possible. -[specs]: https://github.com/opencontainers/specs -[ocitools-test]: https://github.com/mrunalp/ocitools#testing-oci-runtimes +[runtime-spec]: https://github.com/opencontainers/runtime-spec +[runtime-tools-compliance]: https://github.com/opencontainers/runtime-tools#testing-oci-runtimes [thread]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/BIxya5eSNLo -[rules]: https://github.com/opencontainers/specs#contributing -[lifecycle]: https://github.com/opencontainers/specs/pull/231 +[rules]: https://github.com/opencontainers/runtime-spec#contributing +[lifecycle]: https://github.com/opencontainers/runtime-spec/blob/master/runtime.md#lifecycle [runC]: https://github.com/opencontainers/runc From 57296956d9ae1e80183db7b13997b9ec7d7d6288 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 8 Feb 2017 15:30:35 -0800 Subject: [PATCH 02/18] *: "OCI Runtime Command Line Interface" Pick a better title. Signed-off-by: W. Trevor King --- README.md | 2 +- runtime.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 62a65c4..e513349 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# OCI command-line API +# OCI Runtime Command Line Interface The [OCI Runtime Specification][runtime-spec] currently focuses on the bundle-author ↔ runtime interface, but there is renewed interest in specifying a command-line API for the runtime-caller ↔ runtime interface. A common command-line API would make it easier to build higher-level tools that are runtime-agnostic (e.g. compliance testers like [runtime-tools][runtime-tools-compliance]). diff --git a/runtime.md b/runtime.md index aeb39e5..1d4c749 100644 --- a/runtime.md +++ b/runtime.md @@ -1,4 +1,4 @@ -# Operations +# OCI Runtime Command Line Interface A conformant runtime MUST provide an executable (called `funC` in the following examples). That executable MUST support commands with the following template: From c44520ec3019e3b9ead682474132a2ce585a9a6a Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 8 Feb 2017 15:35:44 -0800 Subject: [PATCH 03/18] runtime: Semantically version this specification 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]: https://github.com/opencontainers/runtime-spec/pull/513#issuecomment-257204979 [2]: https://github.com/opencontainers/runtime-spec/pull/513#r72818875 [3]: https://github.com/opencontainers/runtime-spec/pull/513#r72866653 [4]: https://github.com/opencontainers/runtime-spec/pull/513#r72868322 [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 --- runtime.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/runtime.md b/runtime.md index 1d4c749..bbe9a6b 100644 --- a/runtime.md +++ b/runtime.md @@ -1,6 +1,16 @@ # OCI Runtime Command Line Interface -A conformant runtime MUST provide an executable (called `funC` in the following examples). +This section defines the OCI Runtime Command Line Interface version 1.0.0. + +## Versioning + +The command line interface is versioned with [SemVer v2.0.0][semver]. +The command line interface version is independent of the OCI Runtime Specification as a whole (which is tied to the [configuration format][runtime-spec-version]. +For example, if a caller is compliant with version 1.1 of the command line interface, they are compatible with all runtimes that support any 1.1 or later release of the command line interface, but are not compatible with a runtime that supports 1.0 and not 1.1. + +## Global usage + +The runtime MUST provide an executable (called `funC` in the following examples). That executable MUST support commands with the following template: ```sh @@ -105,6 +115,8 @@ $ echo $? [posix-encoding]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap06.html#tag_06_02 [posix-lang]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_02 [posix-locale-encoding]: http://www.unicode.org/reports/tr35/#Bundle_vs_Item_Lookup +[semver]: http://semver.org/spec/v2.0.0.html [standard-streams]: https://github.com/opencontainers/specs/blob/v0.1.1/runtime-linux.md#file-descriptors [systemd-listen-fds]: http://www.freedesktop.org/software/systemd/man/sd_listen_fds.html +[runtime-spec-version]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/config.md#specification-version [UTF-8]: http://www.unicode.org/versions/Unicode8.0.0/ch03.pdf From a65fe1e09910803afdfe3943b641e4483af667cd Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 8 Feb 2017 15:42:21 -0800 Subject: [PATCH 04/18] runtime: Drop 'sh' highlighting from fenced code blocks Fix an instance missed by 77045311 (runtime: Drop 'sh' highlighting from fenced code blocks, 2016-06-22, wking/oci-command-line-api#15). Signed-off-by: W. Trevor King --- runtime.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/runtime.md b/runtime.md index bbe9a6b..5bae8ad 100644 --- a/runtime.md +++ b/runtime.md @@ -13,7 +13,7 @@ For example, if a caller is compliant with version 1.1 of the command line inter The runtime MUST provide an executable (called `funC` in the following examples). That executable MUST support commands with the following template: -```sh +``` $ funC [global-options] [command-specific-options] ``` From 5fc039d44d56e74c1fe58640eab05e151a44bc01 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 8 Feb 2017 15:44:43 -0800 Subject: [PATCH 05/18] runtime: Fix "MUST not" -> "MUST NOT" Signed-off-by: W. Trevor King --- runtime.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/runtime.md b/runtime.md index 5bae8ad..db0281f 100644 --- a/runtime.md +++ b/runtime.md @@ -21,7 +21,7 @@ $ funC [global-options] [command-specific-options] ` is unambiguously an invocation of `` (even for commands not specified in this document). If the runtime is invoked with an unrecognized command, it MUST exit with a nonzero exit code and MAY log a warning to stderr. From 5d0e44cff46dc723a2b648876fb3ac3ce885db7f Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 8 Feb 2017 15:46:03 -0800 Subject: [PATCH 06/18] runtime: Address unspecified commands and options 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 --- runtime.md | 1 + 1 file changed, 1 insertion(+) diff --git a/runtime.md b/runtime.md index db0281f..de41471 100644 --- a/runtime.md +++ b/runtime.md @@ -24,6 +24,7 @@ Global options MAY take positional arguments (e.g. `--log-level debug`). Command names MUST NOT start with hyphens. The option parsing MUST be such that `funC ` is unambiguously an invocation of `` (even for commands not specified in this document). If the runtime is invoked with an unrecognized command, it MUST exit with a nonzero exit code and MAY log a warning to stderr. +Beyond the above rules, the behavior of the runtime in the presence of commands and options not specified in this document is unspecified. ## Character encodings From 4c7901cdf3762fe3871fda429da1d593e64b0c33 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 8 Feb 2017 15:52:19 -0800 Subject: [PATCH 07/18] runtime: Drop the 'version' command 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 --- runtime.md | 25 +------------------------ 1 file changed, 1 insertion(+), 24 deletions(-) diff --git a/runtime.md b/runtime.md index de41471..b6d7299 100644 --- a/runtime.md +++ b/runtime.md @@ -29,33 +29,10 @@ Beyond the above rules, the behavior of the runtime in the presence of commands ## Character encodings This API specification does not cover character encodings, but runtimes SHOULD conform to their native operating system. -For example, POSIX systems define [`LANG` and related environment variables][posix-lang] for [declaring][posix-locale-encoding] [locale-specific character encodings][posix-encoding], so a runtime in an `en_US.UTF-8` locale SHOULD write its [version](#version) to stdout in [UTF-8][]. +For example, POSIX systems define [`LANG` and related environment variables][posix-lang] for [declaring][posix-locale-encoding] [locale-specific character encodings][posix-encoding], so a runtime in an `en_US.UTF-8` locale SHOULD write its [state](#state) to stdout in [UTF-8][]. ## Commands -### version - -Print the runtime version and exit. - -* *Options* None are required, but the runtime MAY support options. -* *Standard streams* - * *stdin:* The runtime MUST NOT attempt to read from its stdin. - * *stdout:* The runtime MUST print its name, a space, and its version as the first line to its stdout. - The name MAY contain any Unicode characters, but MUST NOT contain control codes or newlines. - The runtime MAY print additional lines to its stdout, and the format for those lines is not specified in this document. - * *stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document. -* *Exit code:* The runtime MUST exit with zero. - -#### Example - -``` -$ funC version -funC 1.0.0 -Built for x86_64-pc-linux-gnu -$ echo $? -0 -``` - ### start Start a container from a bundle directory. From 6819bc90a3639415ac3ac829dee72f4e6d8321d4 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 8 Feb 2017 15:55:11 -0800 Subject: [PATCH 08/18] runtime: Four-space indents for nested lists 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 --- runtime.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/runtime.md b/runtime.md index b6d7299..83dea6d 100644 --- a/runtime.md +++ b/runtime.md @@ -38,13 +38,13 @@ For example, POSIX systems define [`LANG` and related environment variables][pos Start a container from a bundle directory. * *Options* - * *`--id `* Set the container ID when creating or joining a container. - If not set, the runtime is free to pick any ID that is not already in use. - * *`--bundle `* Override the path to the bundle directory (defaults to the current working directory). + * *`--id `* Set the container ID when creating or joining a container. + If not set, the runtime is free to pick any ID that is not already in use. + * *`--bundle `* Override the path to the bundle directory (defaults to the current working directory). * *Standard streams:* The runtime MUST attach its standard streams directly to the application process without inspection. * *Environment variables* - * *`LISTEN_FDS`:* The number of file descriptors passed. - For example, `LISTEN_FDS=2` would mean that the runtime MUST pass file descriptors 3 and 4 to the application process (in addition to the [standard streams][standard-streams]) to support [socket activation][systemd-listen-fds]. + * *`LISTEN_FDS`:* The number of file descriptors passed. + For example, `LISTEN_FDS=2` would mean that the runtime MUST pass file descriptors 3 and 4 to the application process (in addition to the [standard streams][standard-streams]) to support [socket activation][systemd-listen-fds]. * *Exit code:* The runtime MUST exit with the application process's exit code. #### Example @@ -63,11 +63,11 @@ $ echo $? Request the container state. * *Arguments* - * *``* The container whose state is being requested. + * *``* The container whose state is being requested. * *Standard streams:* - * *stdin:* The runtime MUST NOT attempt to read from its stdin. - * *stdout:* The runtime MUST print the state JSON to its stdout. - * *stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document. + * *stdin:* The runtime MUST NOT attempt to read from its stdin. + * *stdout:* The runtime MUST print the state JSON to its stdout. + * *stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document. * *Exit code:* Zero if the state was successfully written to stdout and non-zero on errors. #### Example From 5c87cc6469f41fdbb5f0d22cdc16f9d585232fbc Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 8 Feb 2017 16:02:01 -0800 Subject: [PATCH 09/18] runtime: Add a 'kill' command Similar to the 'signal' command removed in b9227323 (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: <20160526180329.GL17496@odin.tremily.us> [5]: https://github.com/docker/docker/pull/16997/files#diff-5d0b72cccc4809455d52aadc62329817R230 docker/docker@bc503ca8 (Windows: [TP4] docker kill handling, 2015-10-12, docker/docker#16997) Signed-off-by: W. Trevor King --- runtime.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/runtime.md b/runtime.md index 83dea6d..380ca92 100644 --- a/runtime.md +++ b/runtime.md @@ -90,9 +90,45 @@ $ echo $? 0 ``` +### kill + +[Send a signal][kill] to the container process. + +* *Arguments* + * *``* The container being signaled. +* *Options* + * *`--signal `* The signal to send (defaults to `TERM`). + The runtime MUST support `TERM` and `KILL` signals with [the POSIX semantics][posix-signals]. + The runtime MAY support additional signal names. + On platforms that support [POSIX signals][posix-signals], the runtime MUST implement this command using POSIX signals. + On platforms that do not support POSIX signals, the runtime MAY implement this command with alternative technology as long as `TERM` and `KILL` retain their POSIX semantics. + Runtime authors on non-POSIX platforms SHOULD submit documentation for their TERM implementation to this specificiation, so runtime callers can configure the container process to gracefully handle the signals. +* *Standard streams:* + * *stdin:* The runtime MUST NOT attempt to read from its stdin. + * *stdout:* The handling of stdout is unspecified. + * *stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document. +* *Exit code:* Zero if the signal was successfully sent to the container process and non-zero on errors. + Successfully sent does not mean that the signal was successfully received or handled by the container process. + +#### Example + +``` +# in a bundle directory with a process ignores TERM +$ funC start --id sleeper-1 & +$ funC kill sleeper-1 +$ echo $? +0 +$ funC kill --signal KILL sleeper-1 +$ echo $? +0 +``` + +[kill]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/runtime.md#kill +[kill.2]: http://man7.org/linux/man-pages/man2/kill.2.html [posix-encoding]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap06.html#tag_06_02 [posix-lang]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_02 [posix-locale-encoding]: http://www.unicode.org/reports/tr35/#Bundle_vs_Item_Lookup +[posix-signals]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html#tag_13_42_03 [semver]: http://semver.org/spec/v2.0.0.html [standard-streams]: https://github.com/opencontainers/specs/blob/v0.1.1/runtime-linux.md#file-descriptors [systemd-listen-fds]: http://www.freedesktop.org/software/systemd/man/sd_listen_fds.html From 6375ad0143cc3bb20226ed98f232abcb3f25e75d Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 8 Feb 2017 16:25:45 -0800 Subject: [PATCH 10/18] runtime: Link to the spec's 'bundle' docs Make life easy for folks not familiar with the term. Signed-off-by: W. Trevor King --- runtime.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/runtime.md b/runtime.md index 380ca92..577ebc6 100644 --- a/runtime.md +++ b/runtime.md @@ -35,12 +35,12 @@ For example, POSIX systems define [`LANG` and related environment variables][pos ### start -Start a container from a bundle directory. +Start a container from a [bundle directory][bundle]. * *Options* * *`--id `* Set the container ID when creating or joining a container. If not set, the runtime is free to pick any ID that is not already in use. - * *`--bundle `* Override the path to the bundle directory (defaults to the current working directory). + * *`--bundle `* Override the path to the [bundle directory][bundle] (defaults to the current working directory). * *Standard streams:* The runtime MUST attach its standard streams directly to the application process without inspection. * *Environment variables* * *`LISTEN_FDS`:* The number of file descriptors passed. @@ -123,6 +123,7 @@ $ echo $? 0 ``` +[bundle]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/bundle.md [kill]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/runtime.md#kill [kill.2]: http://man7.org/linux/man-pages/man2/kill.2.html [posix-encoding]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap06.html#tag_06_02 From 3d50871641064c9e850cb6b5fab4255a35b7b693 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 8 Feb 2017 16:27:45 -0800 Subject: [PATCH 11/18] runtime: Move start's --id to a positional parameter I added this as an option in 5033c59d (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]: https://github.com/opencontainers/runc/pull/541 opencontainers/runc@a7278cad (Require container id as arg1, 2016-02-08, opencontainers/runc#541) [2]: https://github.com/opencontainers/runc/pull/827 Summary: Implement create and start Signed-off-by: W. Trevor King --- runtime.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/runtime.md b/runtime.md index 577ebc6..1000249 100644 --- a/runtime.md +++ b/runtime.md @@ -37,9 +37,9 @@ For example, POSIX systems define [`LANG` and related environment variables][pos Start a container from a [bundle directory][bundle]. +* *Arguments* + * *``* Set the container ID to create. * *Options* - * *`--id `* Set the container ID when creating or joining a container. - If not set, the runtime is free to pick any ID that is not already in use. * *`--bundle `* Override the path to the [bundle directory][bundle] (defaults to the current working directory). * *Standard streams:* The runtime MUST attach its standard streams directly to the application process without inspection. * *Environment variables* @@ -51,7 +51,7 @@ Start a container from a [bundle directory][bundle]. ``` # in a bundle directory with a process that echos "hello" and exits 42 -$ funC start --id hello-1 +$ funC start hello-1 hello $ echo $? @@ -74,7 +74,7 @@ Request the container state. ``` # in a bundle directory with a process that sleeps for several seconds -$ funC start --id sleeper-1 & +$ funC start sleeper-1 & $ funC state sleeper-1 { "ociVersion": "1.0.0-rc1", @@ -114,7 +114,7 @@ $ echo $? ``` # in a bundle directory with a process ignores TERM -$ funC start --id sleeper-1 & +$ funC start sleeper-1 & $ funC kill sleeper-1 $ echo $? 0 From 56c906dbeb634c6533c0b6b61a5d22189d8058e7 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 8 Feb 2017 16:35:12 -0800 Subject: [PATCH 12/18] runtime: "application" -> "container" Michael doesn't like "application" [1], and the runtime spec has standardized around "container process". [1]: https://github.com/opencontainers/runtime-spec/pull/107#issuecomment-145615479 Signed-off-by: W. Trevor King --- runtime.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/runtime.md b/runtime.md index 1000249..e4ca399 100644 --- a/runtime.md +++ b/runtime.md @@ -41,11 +41,11 @@ Start a container from a [bundle directory][bundle]. * *``* Set the container ID to create. * *Options* * *`--bundle `* Override the path to the [bundle directory][bundle] (defaults to the current working directory). -* *Standard streams:* The runtime MUST attach its standard streams directly to the application process without inspection. +* *Standard streams:* The runtime MUST attach its standard streams directly to the container process without inspection. * *Environment variables* * *`LISTEN_FDS`:* The number of file descriptors passed. - For example, `LISTEN_FDS=2` would mean that the runtime MUST pass file descriptors 3 and 4 to the application process (in addition to the [standard streams][standard-streams]) to support [socket activation][systemd-listen-fds]. -* *Exit code:* The runtime MUST exit with the application process's exit code. + For example, `LISTEN_FDS=2` would mean that the runtime MUST pass file descriptors 3 and 4 to the container process (in addition to the [standard streams][standard-streams]) to support [socket activation][systemd-listen-fds]. +* *Exit code:* The runtime MUST exit with the container process's exit code. #### Example From 5ace459890aa44c6123a31615d9746e0ddbfd36f Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 8 Feb 2017 16:43:17 -0800 Subject: [PATCH 13/18] runtime: Split 'create' and 'start' (and add 'delete') 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]: https://github.com/opencontainers/runtime-spec/pull/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]: https://github.com/opencontainers/runc/pull/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 --- runtime.md | 86 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 74 insertions(+), 12 deletions(-) diff --git a/runtime.md b/runtime.md index e4ca399..496bf0b 100644 --- a/runtime.md +++ b/runtime.md @@ -33,53 +33,91 @@ For example, POSIX systems define [`LANG` and related environment variables][pos ## Commands -### start +### create -Start a container from a [bundle directory][bundle]. +[Create][create] a container from a [bundle directory][bundle]. * *Arguments* * *``* Set the container ID to create. * *Options* * *`--bundle `* Override the path to the [bundle directory][bundle] (defaults to the current working directory). -* *Standard streams:* The runtime MUST attach its standard streams directly to the container process without inspection. +* *Standard streams:* + * *stdin:* The runtime MUST NOT attempt to read from its stdin. + * *stdout:* The handling of stdout is unspecified. + * *stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document. * *Environment variables* * *`LISTEN_FDS`:* The number of file descriptors passed. For example, `LISTEN_FDS=2` would mean that the runtime MUST pass file descriptors 3 and 4 to the container process (in addition to the [standard streams][standard-streams]) to support [socket activation][systemd-listen-fds]. -* *Exit code:* The runtime MUST exit with the container process's exit code. +* *Exit code:* Zero if the container was successfully created and non-zero on errors. + +Callers MAY block on this command's successful exit to trigger post-create activity. #### Example ``` # in a bundle directory with a process that echos "hello" and exits 42 +$ test -t 1 && echo 'stdout is a terminal' +stdout is a terminal +$ funC create hello-1 <&- >stdout 2>stderr +$ echo $? +0 +$ wc stdout +0 0 0 stdout $ funC start hello-1 +$ echo $? +0 +$ cat stdout hello - +$ block-on-exit-and-collect-exit-code hello-1 $ echo $? 42 +$ funC delete hello-1 +$ echo $? +0 ``` +#### Container process exit + +The [example's](#example) `block-on-exit-and-collect-exit-code` is platform-specific and is not specified in this document. +On Linux, it might involve an ancestor process which had set [`PR_SET_CHILD_SUBREAPER`][prctl.2] and collected the container PID [from the state][state], or a process that was [ptracing][ptrace.2] the container process for [`exit_group`][exit_group.2], although both of those race against the container process exiting before the watcher is monitoring. + +### start + +[Start][start] the user-specified code from [`process`][process]. + +* *Arguments* + * *``* The container to start. +* *Standard streams:* + * *stdin:* The runtime MUST NOT attempt to read from its stdin. + * *stdout:* The handling of stdout is unspecified. + * *stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document. +* *Exit code:* Zero if the container was successfully started and non-zero on errors. + +Callers MAY block on this command's successful exit to trigger post-start activity. + +See [create](#example) for an example. + ### state -Request the container state. +[Request][state-request] the container [state][state]. * *Arguments* * *``* The container whose state is being requested. * *Standard streams:* * *stdin:* The runtime MUST NOT attempt to read from its stdin. - * *stdout:* The runtime MUST print the state JSON to its stdout. + * *stdout:* The runtime MUST print the [state JSON][state] to its stdout. * *stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document. * *Exit code:* Zero if the state was successfully written to stdout and non-zero on errors. #### Example ``` -# in a bundle directory with a process that sleeps for several seconds -$ funC start sleeper-1 & +$ funC create sleeper-1 $ funC state sleeper-1 { "ociVersion": "1.0.0-rc1", "id": "sleeper-1", - "status": "running", + "status": "created", "pid": 4422, "bundlePath": "/containers/sleeper", "annotations" { @@ -113,8 +151,9 @@ $ echo $? #### Example ``` -# in a bundle directory with a process ignores TERM -$ funC start sleeper-1 & +# in a bundle directory where the container process ignores TERM +$ funC create sleeper-1 +$ funC start sleeper-1 $ funC kill sleeper-1 $ echo $? 0 @@ -123,15 +162,38 @@ $ echo $? 0 ``` +### delete + +[Release](#delete) container resources after the container process has exited. + +* *Arguments* + * *``* The container to delete. +* *Standard streams:* + * *stdin:* The runtime MUST NOT attempt to read from its stdin. + * *stdout:* The handling of stdout is unspecified. + * *stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document. +* *Exit code:* Zero if the container was successfully deleted and non-zero on errors. + +See [create](#example) for an example. + [bundle]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/bundle.md +[create]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/runtime.md#create +[delete]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/runtime.md#delete +[exit_group.2]: http://man7.org/linux/man-pages/man2/exit_group.2.html [kill]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/runtime.md#kill [kill.2]: http://man7.org/linux/man-pages/man2/kill.2.html +[process]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/config.md#process [posix-encoding]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap06.html#tag_06_02 [posix-lang]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_02 [posix-locale-encoding]: http://www.unicode.org/reports/tr35/#Bundle_vs_Item_Lookup [posix-signals]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html#tag_13_42_03 +[prctl.2]: http://man7.org/linux/man-pages/man2/prctl.2.html +[ptrace.2]: http://man7.org/linux/man-pages/man2/ptrace.2.html [semver]: http://semver.org/spec/v2.0.0.html [standard-streams]: https://github.com/opencontainers/specs/blob/v0.1.1/runtime-linux.md#file-descriptors +[start]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/runtime.md#start +[state]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/runtime.md#state +[state-request]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/runtime.md#query-state [systemd-listen-fds]: http://www.freedesktop.org/software/systemd/man/sd_listen_fds.html [runtime-spec-version]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/config.md#specification-version [UTF-8]: http://www.unicode.org/versions/Unicode8.0.0/ch03.pdf From 6f5d033a0530a8e9f1a71a7b1c5929e2d914648c Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 8 Feb 2017 16:54:25 -0800 Subject: [PATCH 14/18] runtime: Add --pid-file to 'create' 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]: https://github.com/opencontainers/runtime-spec/pull/511#r70353376 Subject: Add initial pass at a cmd line spec [2]: https://github.com/opencontainers/runtime-spec/pull/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 --- runtime.md | 1 + 1 file changed, 1 insertion(+) diff --git a/runtime.md b/runtime.md index 496bf0b..b1d46b1 100644 --- a/runtime.md +++ b/runtime.md @@ -41,6 +41,7 @@ For example, POSIX systems define [`LANG` and related environment variables][pos * *``* Set the container ID to create. * *Options* * *`--bundle `* Override the path to the [bundle directory][bundle] (defaults to the current working directory). + * *`--pid-file `* The runtime MUST write the container PID to this path. * *Standard streams:* * *stdin:* The runtime MUST NOT attempt to read from its stdin. * *stdout:* The handling of stdout is unspecified. From 394fa4fbd948f529d83105eea1aeb7854bc6764b Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 8 Feb 2017 16:59:37 -0800 Subject: [PATCH 15/18] runtime: Add --console-socket for terminal handling 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 --- runtime.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 55 insertions(+), 4 deletions(-) diff --git a/runtime.md b/runtime.md index b1d46b1..cb60b82 100644 --- a/runtime.md +++ b/runtime.md @@ -42,17 +42,62 @@ For example, POSIX systems define [`LANG` and related environment variables][pos * *Options* * *`--bundle `* Override the path to the [bundle directory][bundle] (defaults to the current working directory). * *`--pid-file `* The runtime MUST write the container PID to this path. + * *`--console-socket `* The runtime MUST pass the [pseudoterminal master][posix_openpt.3] through the socket at ``; the protocol is [described below](#console-socket). * *Standard streams:* - * *stdin:* The runtime MUST NOT attempt to read from its stdin. - * *stdout:* The handling of stdout is unspecified. - * *stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document. + * If [`process.terminal`][process] is true: + * *stdin:* The runtime MUST NOT attempt to read from its stdin. + * *stdout:* The handling of stdout is unspecified. + * *stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document. + * If [`process.terminal`][process] is not true: + * *stdin:* The runtime MUST pass its stdin file descriptor through to the container process without manipulation or modification. + "Without manipulation or modification" means that the runtime MUST not seek on the file descriptor, or close it, or read or write to it, or [`ioctl`][ioctl.3] it, or perform any other action on it besides passing it through to the container process. + * *stdout:* The runtime MUST pass its stdout file descriptor through to the container process without manipulation or modification. + * *stderr:* When `create` exists with a zero code, the runtime MUST pass its stderr file descriptor through to the container process without manipulation or modification. + When `create` exits with a non-zero code, the runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document. * *Environment variables* * *`LISTEN_FDS`:* The number of file descriptors passed. - For example, `LISTEN_FDS=2` would mean that the runtime MUST pass file descriptors 3 and 4 to the container process (in addition to the [standard streams][standard-streams]) to support [socket activation][systemd-listen-fds]. + For example, `LISTEN_FDS=2` would mean that the runtime MUST pass file descriptors 3 and 4 to the container process (in addition to the standard streams) to support [socket activation][systemd-listen-fds]. * *Exit code:* Zero if the container was successfully created and non-zero on errors. Callers MAY block on this command's successful exit to trigger post-create activity. +#### Console socket + +The [`AF_UNIX`][unix-socket] used by [`--console-socket`](#create) handles request and response messages between a runtime and server. +The socket type MUST be [`SOCK_SEQPACKET`][socket-types]. +The server MUST send a single response for each runtime request. +The [normal data][socket-queue] ([`msghdr.msg_iov*`][socket.h]) of all messages MUST be [UTF-8][] [JSON](glossary.md#json). + +There are [JSON Schemas](schema/README.md) and [Go bindings](specs-go/socket/socket.go) for the messages specified in this section. + +##### Requests + +All requests MUST contain a **`type`** property whose value MUST one of the following strings: + +* `terminal`, if the request is passing a [pseudoterminal master][posix_openpt.3]. + When `type` is `terminal`, the request MUST also contain the following properties: + + * **`container`** (string, REQUIRED) The container ID, as set by [create](#create). + + The message's [ancillary data][socket-queue] (`msg_control*`) MUST contain at least one [`cmsghdr`][socket.h]). + The first `cmsghdr` MUST have: + + * `cmsg_type` set to [`SOL_SOCKET`][socket.h], + * `cmsg_level` set to [`SCM_RIGHTS`][socket.h], + * `cmsg_len` greater than or equal to `CMSG_LEN(sizeof(int))`, and + * `((int*)CMSG_DATA(cmsg))[0]` set to the pseudoterminal master file descriptor. + +##### Responses + +All responses MUST contain a **`type`** property whose value MUST be one of the following strings: + +* `success`, if the request was successfully processed. +* `error`, if the request was not successfully processed. + +In addition, responses MAY contain any of the following properties: + +* **`message`** (string, OPTIONAL) A phrase describing the response. + #### Example ``` @@ -181,20 +226,26 @@ See [create](#example) for an example. [create]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/runtime.md#create [delete]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/runtime.md#delete [exit_group.2]: http://man7.org/linux/man-pages/man2/exit_group.2.html +[ioctl.3]: http://pubs.opengroup.org/onlinepubs/9699919799/ [kill]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/runtime.md#kill [kill.2]: http://man7.org/linux/man-pages/man2/kill.2.html [process]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/config.md#process [posix-encoding]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap06.html#tag_06_02 [posix-lang]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_02 [posix-locale-encoding]: http://www.unicode.org/reports/tr35/#Bundle_vs_Item_Lookup +[posix_openpt.3]: http://pubs.opengroup.org/onlinepubs/9699919799/functions/posix_openpt.html [posix-signals]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html#tag_13_42_03 [prctl.2]: http://man7.org/linux/man-pages/man2/prctl.2.html [ptrace.2]: http://man7.org/linux/man-pages/man2/ptrace.2.html [semver]: http://semver.org/spec/v2.0.0.html +[socket-queue]: http://pubs.opengroup.org/onlinepubs/9699919799/functions/V2_chap02.html#tag_15_10_11 +[socket-types]: http://pubs.opengroup.org/onlinepubs/9699919799/functions/V2_chap02.html#tag_15_10_06 +[socket.h]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_socket.h.html [standard-streams]: https://github.com/opencontainers/specs/blob/v0.1.1/runtime-linux.md#file-descriptors [start]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/runtime.md#start [state]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/runtime.md#state [state-request]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/runtime.md#query-state [systemd-listen-fds]: http://www.freedesktop.org/software/systemd/man/sd_listen_fds.html [runtime-spec-version]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/config.md#specification-version +[unix-socket]: http://pubs.opengroup.org/onlinepubs/9699919799/functions/V2_chap02.html#tag_15_10_17 [UTF-8]: http://www.unicode.org/versions/Unicode8.0.0/ch03.pdf From 74ca4036e7b8df85b88e34b8c194963aba36b974 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 8 Feb 2017 20:39:18 -0800 Subject: [PATCH 16/18] runtime: Mention TIOCSTI privilege escalation As requested by Aleksa [1]. [1]: https://github.com/opencontainers/runtime-spec/pull/513#issuecomment-254230937 Signed-off-by: W. Trevor King --- runtime.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/runtime.md b/runtime.md index cb60b82..533f7d4 100644 --- a/runtime.md +++ b/runtime.md @@ -51,6 +51,9 @@ For example, POSIX systems define [`LANG` and related environment variables][pos * If [`process.terminal`][process] is not true: * *stdin:* The runtime MUST pass its stdin file descriptor through to the container process without manipulation or modification. "Without manipulation or modification" means that the runtime MUST not seek on the file descriptor, or close it, or read or write to it, or [`ioctl`][ioctl.3] it, or perform any other action on it besides passing it through to the container process. + + When using a container to drop privileges, note that providing a privileged terminal's file descriptor may allow the container to [execute privileged operations via `TIOCSTI`][TIOCSTI-security] or other [TTY ioctls][tty_ioctl.4]. + On Linux, [`TIOCSTI` requires `CAP_SYS_ADMIN`][capabilities.7] unless the target terminal is the caller's [controlling terminal][controlling-terminal]. * *stdout:* The runtime MUST pass its stdout file descriptor through to the container process without manipulation or modification. * *stderr:* When `create` exists with a zero code, the runtime MUST pass its stderr file descriptor through to the container process without manipulation or modification. When `create` exits with a non-zero code, the runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document. @@ -223,6 +226,8 @@ $ echo $? See [create](#example) for an example. [bundle]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/bundle.md +[capabilities.7]: http://man7.org/linux/man-pages/man7/capabilities.7.html +[controlling-terminal]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap11.html#tag_11_01_03 [create]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/runtime.md#create [delete]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/runtime.md#delete [exit_group.2]: http://man7.org/linux/man-pages/man2/exit_group.2.html @@ -247,5 +252,7 @@ See [create](#example) for an example. [state-request]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/runtime.md#query-state [systemd-listen-fds]: http://www.freedesktop.org/software/systemd/man/sd_listen_fds.html [runtime-spec-version]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/config.md#specification-version +[TIOCSTI-security]: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=628843 +[tty_ioctl.4]: http://man7.org/linux/man-pages/man4/tty_ioctl.4.html [unix-socket]: http://pubs.opengroup.org/onlinepubs/9699919799/functions/V2_chap02.html#tag_15_10_17 [UTF-8]: http://www.unicode.org/versions/Unicode8.0.0/ch03.pdf From a26d73b2f6c36520ee8205b8da42a39b1c186480 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 8 Feb 2017 20:42:43 -0800 Subject: [PATCH 17/18] runtime: Replace '--console-socket PATH' with '$LISTEN_FDS + 3' 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 --- runtime.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/runtime.md b/runtime.md index 533f7d4..e312846 100644 --- a/runtime.md +++ b/runtime.md @@ -42,7 +42,6 @@ For example, POSIX systems define [`LANG` and related environment variables][pos * *Options* * *`--bundle `* Override the path to the [bundle directory][bundle] (defaults to the current working directory). * *`--pid-file `* The runtime MUST write the container PID to this path. - * *`--console-socket `* The runtime MUST pass the [pseudoterminal master][posix_openpt.3] through the socket at ``; the protocol is [described below](#console-socket). * *Standard streams:* * If [`process.terminal`][process] is true: * *stdin:* The runtime MUST NOT attempt to read from its stdin. @@ -60,14 +59,17 @@ For example, POSIX systems define [`LANG` and related environment variables][pos * *Environment variables* * *`LISTEN_FDS`:* The number of file descriptors passed. For example, `LISTEN_FDS=2` would mean that the runtime MUST pass file descriptors 3 and 4 to the container process (in addition to the standard streams) to support [socket activation][systemd-listen-fds]. +* *Additional file descriptors* + * If [`process.terminal`][process] is true, the caller MUST provide an open [`AF_UNIX` socket][unix-socket] on file descriptor `$LISTEN_FDS + 3`. + The runtime MUST pass the [pseudoterminal master][posix_openpt.3] through the socket; the protocol is [described below](#console-socket). * *Exit code:* Zero if the container was successfully created and non-zero on errors. Callers MAY block on this command's successful exit to trigger post-create activity. #### Console socket -The [`AF_UNIX`][unix-socket] used by [`--console-socket`](#create) handles request and response messages between a runtime and server. -The socket type MUST be [`SOCK_SEQPACKET`][socket-types]. +The [`AF_UNIX`][unix-socket] used by the [`$LISTEN_FDS + 3` socket](#create) handles request and response messages between a runtime and server. +The socket type MUST be [`SOCK_SEQPACKET`][socket-types] or [`SOCK_STREAM`][socket-types]. The server MUST send a single response for each runtime request. The [normal data][socket-queue] ([`msghdr.msg_iov*`][socket.h]) of all messages MUST be [UTF-8][] [JSON](glossary.md#json). From 26440a5153a074276d1094764292c6c784333812 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 8 Feb 2017 20:50:09 -0800 Subject: [PATCH 18/18] runtime: Replace '$LISTEN_FDS + 3' with '--console-socket FD' 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 --- runtime.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/runtime.md b/runtime.md index e312846..e637c58 100644 --- a/runtime.md +++ b/runtime.md @@ -41,6 +41,7 @@ For example, POSIX systems define [`LANG` and related environment variables][pos * *``* Set the container ID to create. * *Options* * *`--bundle `* Override the path to the [bundle directory][bundle] (defaults to the current working directory). + * *`--console-socket `* The runtime MUST pass the [pseudoterminal master][posix_openpt.3] through the open socket at file descriptor ``; the protocol is [described below](#console-socket). * *`--pid-file `* The runtime MUST write the container PID to this path. * *Standard streams:* * If [`process.terminal`][process] is true: @@ -59,16 +60,13 @@ For example, POSIX systems define [`LANG` and related environment variables][pos * *Environment variables* * *`LISTEN_FDS`:* The number of file descriptors passed. For example, `LISTEN_FDS=2` would mean that the runtime MUST pass file descriptors 3 and 4 to the container process (in addition to the standard streams) to support [socket activation][systemd-listen-fds]. -* *Additional file descriptors* - * If [`process.terminal`][process] is true, the caller MUST provide an open [`AF_UNIX` socket][unix-socket] on file descriptor `$LISTEN_FDS + 3`. - The runtime MUST pass the [pseudoterminal master][posix_openpt.3] through the socket; the protocol is [described below](#console-socket). * *Exit code:* Zero if the container was successfully created and non-zero on errors. Callers MAY block on this command's successful exit to trigger post-create activity. #### Console socket -The [`AF_UNIX`][unix-socket] used by the [`$LISTEN_FDS + 3` socket](#create) handles request and response messages between a runtime and server. +The [`AF_UNIX`][unix-socket] used by [`--console-socket`](#create) handles request and response messages between a runtime and server. The socket type MUST be [`SOCK_SEQPACKET`][socket-types] or [`SOCK_STREAM`][socket-types]. The server MUST send a single response for each runtime request. The [normal data][socket-queue] ([`msghdr.msg_iov*`][socket.h]) of all messages MUST be [UTF-8][] [JSON](glossary.md#json).