From 394fa4fbd948f529d83105eea1aeb7854bc6764b Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 8 Feb 2017 16:59:37 -0800 Subject: [PATCH] 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