You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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 <wking@tremily.us>
Copy file name to clipboardExpand all lines: runtime.md
+55-4Lines changed: 55 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -42,17 +42,62 @@ For example, POSIX systems define [`LANG` and related environment variables][pos
42
42
**Options*
43
43
**`--bundle <PATH>`* Override the path to the [bundle directory][bundle] (defaults to the current working directory).
44
44
**`--pid-file <PATH>`* The runtime MUST write the container PID to this path.
45
+
**`--console-socket <PATH>`* The runtime MUST pass the [pseudoterminal master][posix_openpt.3] through the socket at `<PATH>`; the protocol is [described below](#console-socket).
45
46
**Standard streams:*
46
-
**stdin:* The runtime MUST NOT attempt to read from its stdin.
47
-
**stdout:* The handling of stdout is unspecified.
48
-
**stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document.
47
+
* If [`process.terminal`][process] is true:
48
+
* *stdin:* The runtime MUST NOT attempt to read from its stdin.
49
+
* *stdout:* The handling of stdout is unspecified.
50
+
* *stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document.
51
+
* If [`process.terminal`][process] is not true:
52
+
**stdin:* The runtime MUST pass its stdin file descriptor through to the container process without manipulation or modification.
53
+
"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.
54
+
**stdout:* The runtime MUST pass its stdout file descriptor through to the container process without manipulation or modification.
55
+
**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.
56
+
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.
49
57
**Environment variables*
50
58
**`LISTEN_FDS`:* The number of file descriptors passed.
51
-
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].
59
+
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].
52
60
**Exit code:* Zero if the container was successfully created and non-zero on errors.
53
61
54
62
Callers MAY block on this command's successful exit to trigger post-create activity.
55
63
64
+
#### Console socket
65
+
66
+
The [`AF_UNIX`][unix-socket] used by [`--console-socket`](#create) handles request and response messages between a runtime and server.
67
+
The socket type MUST be [`SOCK_SEQPACKET`][socket-types].
68
+
The server MUST send a single response for each runtime request.
69
+
The [normal data][socket-queue] ([`msghdr.msg_iov*`][socket.h]) of all messages MUST be [UTF-8][][JSON](glossary.md#json).
70
+
71
+
There are [JSON Schemas](schema/README.md) and [Go bindings](specs-go/socket/socket.go) for the messages specified in this section.
72
+
73
+
##### Requests
74
+
75
+
All requests MUST contain a **`type`** property whose value MUST one of the following strings:
76
+
77
+
*`terminal`, if the request is passing a [pseudoterminal master][posix_openpt.3].
78
+
When `type` is `terminal`, the request MUST also contain the following properties:
79
+
80
+
***`container`** (string, REQUIRED) The container ID, as set by [create](#create).
81
+
82
+
The message's [ancillary data][socket-queue] (`msg_control*`) MUST contain at least one [`cmsghdr`][socket.h]).
83
+
The first `cmsghdr` MUST have:
84
+
85
+
*`cmsg_type` set to [`SOL_SOCKET`][socket.h],
86
+
*`cmsg_level` set to [`SCM_RIGHTS`][socket.h],
87
+
*`cmsg_len` greater than or equal to `CMSG_LEN(sizeof(int))`, and
88
+
*`((int*)CMSG_DATA(cmsg))[0]` set to the pseudoterminal master file descriptor.
89
+
90
+
##### Responses
91
+
92
+
All responses MUST contain a **`type`** property whose value MUST be one of the following strings:
93
+
94
+
*`success`, if the request was successfully processed.
95
+
*`error`, if the request was not successfully processed.
96
+
97
+
In addition, responses MAY contain any of the following properties:
98
+
99
+
***`message`** (string, OPTIONAL) A phrase describing the response.
100
+
56
101
#### Example
57
102
58
103
```
@@ -181,20 +226,26 @@ See [create](#example) for an example.
0 commit comments