Skip to content

Commit 7a4cb36

Browse files
wkingMa Shimiao
wking
authored and
Ma Shimiao
committed
docs/command-line-interface: Add Runtime CLI Spec (#321)
docs/command-line-interface: Add Runtime CLI Spec
1 parent c936704 commit 7a4cb36

6 files changed

+368
-0
lines changed

‎api/socket/socket.go

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
package socket
2+
3+
// Message is the normal data for messages passed on the console socket.
4+
type Message struct {
5+
// Type of message being passed
6+
Type string `json:"type"`
7+
}
8+
9+
// TerminalRequest is the normal data for messages passing a pseudoterminal master.
10+
type TerminalRequest struct {
11+
Message
12+
13+
// Container ID for the container whose pseudoterminal master is being set.
14+
Container string `json:"container"`
15+
}
16+
17+
// Response is the normal data for response messages.
18+
type Response struct {
19+
Message
20+
21+
// Message is a phrase describing the response.
22+
Message string `json:"message,omitempty"`
23+
}

‎docs/command-line-interface.md

+274
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,274 @@
1+
# OCI Runtime Command Line Interface
2+
3+
This file defines the OCI Runtime Command Line Interface version 1.0.0.
4+
It is one of potentially several [runtime APIs supported by the runtime compliance test suite](runtime-compliance-testing.md#supported-apis).
5+
6+
## Notation
7+
8+
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119][rfc2119].
9+
10+
The key words "unspecified", "undefined", and "implementation-defined" are to be interpreted as described in the [rationale for the C99 standard][c99-unspecified].
11+
12+
## Compliance
13+
14+
This specification targets compliance criteria according to the role of a participant in runtime invocation.
15+
Requirements are placed on both runtimes and runtime callers, depending on what behavior is being constrained by the requirement.
16+
An implementation is compliant if it satisfies all the applicable MUST, REQUIRED, and SHALL requirements.
17+
An implementation is not compliant if it fails to satisfy one or more of the applicable MUST, REQUIRED, and SHALL requirements.
18+
19+
## Versioning
20+
21+
The command line interface is versioned with [SemVer v2.0.0][semver].
22+
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].
23+
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.
24+
25+
## Global usage
26+
27+
The runtime MUST provide an executable (called `funC` in the following examples).
28+
That executable MUST support commands with the following template:
29+
30+
```
31+
$ funC [global-options] <COMMAND> [command-specific-options] <command-specific-arguments>
32+
```
33+
34+
## Global options
35+
36+
None are required, but the runtime MAY support options that start with at least one hyphen.
37+
Global options MAY take positional arguments (e.g. `--log-level debug`).
38+
Command names MUST NOT start with hyphens.
39+
The option parsing MUST be such that `funC <COMMAND>` is unambiguously an invocation of `<COMMAND>` (even for commands not specified in this document).
40+
If the runtime is invoked with an unrecognized command, it MUST exit with a nonzero exit code and MAY log a warning to stderr.
41+
Beyond the above rules, the behavior of the runtime in the presence of commands and options not specified in this document is unspecified.
42+
43+
## Character encodings
44+
45+
This API specification does not cover character encodings, but runtimes SHOULD conform to their native operating system.
46+
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][].
47+
48+
## Commands
49+
50+
### create
51+
52+
[Create][create] a container from a [bundle directory][bundle].
53+
54+
* *Arguments*
55+
* *`<ID>`* Set the container ID to create.
56+
* *Options*
57+
* *`--bundle <PATH>`* Override the path to the [bundle directory][bundle] (defaults to the current working directory).
58+
* *`--console-socket <FD>`* The runtime MUST pass the [pseudoterminal master][posix_openpt.3] through the open socket at file descriptor `<FD>`; the protocol is [described below](#console-socket).
59+
* *`--pid-file <PATH>`* The runtime MUST write the container PID to this path.
60+
* *Standard streams:*
61+
* If [`process.terminal`][process] is true:
62+
* *stdin:* The runtime MUST NOT attempt to read from its stdin.
63+
* *stdout:* The handling of stdout is unspecified.
64+
* *stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document.
65+
* If [`process.terminal`][process] is not true:
66+
* *stdin:* The runtime MUST pass its stdin file descriptor through to the container process without manipulation or modification.
67+
"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.
68+
69+
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].
70+
On Linux, [`TIOCSTI` requires `CAP_SYS_ADMIN`][capabilities.7] unless the target terminal is the caller's [controlling terminal][controlling-terminal].
71+
* *stdout:* The runtime MUST pass its stdout file descriptor through to the container process without manipulation or modification.
72+
* *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.
73+
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.
74+
* *Environment variables*
75+
* *`LISTEN_FDS`:* The number of file descriptors passed.
76+
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].
77+
* *Exit code:* Zero if the container was successfully created and non-zero on errors.
78+
79+
Callers MAY block on this command's successful exit to trigger post-create activity.
80+
81+
#### Console socket
82+
83+
The [`AF_UNIX`][unix-socket] used by [`--console-socket`](#create) handles request and response messages between a runtime and server.
84+
The socket type MUST be [`SOCK_SEQPACKET`][socket-types] or [`SOCK_STREAM`][socket-types].
85+
The server MUST send a single response for each runtime request.
86+
The [normal data][socket-queue] ([`msghdr.msg_iov*`][socket.h]) of all messages MUST be [UTF-8][] [JSON](glossary.md#json).
87+
88+
There are [JSON Schemas](../schema/README.md#oci-runtime-command-line-interface) and [Go bindings](../api/socket/socket.go) for the messages specified in this section.
89+
90+
##### Requests
91+
92+
All requests MUST contain a **`type`** property whose value MUST one of the following strings:
93+
94+
* `terminal`, if the request is passing a [pseudoterminal master][posix_openpt.3].
95+
When `type` is `terminal`, the request MUST also contain the following properties:
96+
97+
* **`container`** (string, REQUIRED) The container ID, as set by [create](#create).
98+
99+
The message's [ancillary data][socket-queue] (`msg_control*`) MUST contain at least one [`cmsghdr`][socket.h]).
100+
The first `cmsghdr` MUST have:
101+
102+
* `cmsg_type` set to [`SOL_SOCKET`][socket.h],
103+
* `cmsg_level` set to [`SCM_RIGHTS`][socket.h],
104+
* `cmsg_len` greater than or equal to `CMSG_LEN(sizeof(int))`, and
105+
* `((int*)CMSG_DATA(cmsg))[0]` set to the pseudoterminal master file descriptor.
106+
107+
##### Responses
108+
109+
All responses MUST contain a **`type`** property whose value MUST be one of the following strings:
110+
111+
* `success`, if the request was successfully processed.
112+
* `error`, if the request was not successfully processed.
113+
114+
In addition, responses MAY contain any of the following properties:
115+
116+
* **`message`** (string, OPTIONAL) A phrase describing the response.
117+
118+
#### Example
119+
120+
```
121+
# in a bundle directory with a process that echos "hello" and exits 42
122+
$ test -t 1 && echo 'stdout is a terminal'
123+
stdout is a terminal
124+
$ funC create hello-1 <&- >stdout 2>stderr
125+
$ echo $?
126+
0
127+
$ wc stdout
128+
0 0 0 stdout
129+
$ funC start hello-1
130+
$ echo $?
131+
0
132+
$ cat stdout
133+
hello
134+
$ block-on-exit-and-collect-exit-code hello-1
135+
$ echo $?
136+
42
137+
$ funC delete hello-1
138+
$ echo $?
139+
0
140+
```
141+
142+
#### Container process exit
143+
144+
The [example's](#example) `block-on-exit-and-collect-exit-code` is platform-specific and is not specified in this document.
145+
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.
146+
147+
### start
148+
149+
[Start][start] the user-specified code from [`process`][process].
150+
151+
* *Arguments*
152+
* *`<ID>`* The container to start.
153+
* *Standard streams:*
154+
* *stdin:* The runtime MUST NOT attempt to read from its stdin.
155+
* *stdout:* The handling of stdout is unspecified.
156+
* *stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document.
157+
* *Exit code:* Zero if the container was successfully started and non-zero on errors.
158+
159+
Callers MAY block on this command's successful exit to trigger post-start activity.
160+
161+
See [create](#example) for an example.
162+
163+
### state
164+
165+
[Request][state-request] the container [state][state].
166+
167+
* *Arguments*
168+
* *`<ID>`* The container whose state is being requested.
169+
* *Standard streams:*
170+
* *stdin:* The runtime MUST NOT attempt to read from its stdin.
171+
* *stdout:* The runtime MUST print the [state JSON][state] to its stdout.
172+
* *stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document.
173+
* *Exit code:* Zero if the state was successfully written to stdout and non-zero on errors.
174+
175+
#### Example
176+
177+
```
178+
$ funC create sleeper-1
179+
$ funC state sleeper-1
180+
{
181+
"ociVersion": "1.0.0-rc1",
182+
"id": "sleeper-1",
183+
"status": "created",
184+
"pid": 4422,
185+
"bundlePath": "/containers/sleeper",
186+
"annotations" {
187+
"myKey": "myValue"
188+
}
189+
}
190+
$ echo $?
191+
0
192+
```
193+
194+
### kill
195+
196+
[Send a signal][kill] to the container process.
197+
198+
* *Arguments*
199+
* *`<ID>`* The container being signaled.
200+
* *Options*
201+
* *`--signal <SIGNAL>`* The signal to send (defaults to `TERM`).
202+
The runtime MUST support `TERM` and `KILL` signals with [the POSIX semantics][posix-signals].
203+
The runtime MAY support additional signal names.
204+
On platforms that support [POSIX signals][posix-signals], the runtime MUST implement this command using POSIX signals.
205+
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.
206+
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.
207+
* *Standard streams:*
208+
* *stdin:* The runtime MUST NOT attempt to read from its stdin.
209+
* *stdout:* The handling of stdout is unspecified.
210+
* *stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document.
211+
* *Exit code:* Zero if the signal was successfully sent to the container process and non-zero on errors.
212+
Successfully sent does not mean that the signal was successfully received or handled by the container process.
213+
214+
#### Example
215+
216+
```
217+
# in a bundle directory where the container process ignores TERM
218+
$ funC create sleeper-1
219+
$ funC start sleeper-1
220+
$ funC kill sleeper-1
221+
$ echo $?
222+
0
223+
$ funC kill --signal KILL sleeper-1
224+
$ echo $?
225+
0
226+
```
227+
228+
### delete
229+
230+
[Release](#delete) container resources after the container process has exited.
231+
232+
* *Arguments*
233+
* *`<ID>`* The container to delete.
234+
* *Standard streams:*
235+
* *stdin:* The runtime MUST NOT attempt to read from its stdin.
236+
* *stdout:* The handling of stdout is unspecified.
237+
* *stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document.
238+
* *Exit code:* Zero if the container was successfully deleted and non-zero on errors.
239+
240+
See [create](#example) for an example.
241+
242+
[bundle]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/bundle.md
243+
[c99-unspecified]: http://www.open-std.org/jtc1/sc22/wg14/www/C99RationaleV5.10.pdf#page=18
244+
[capabilities.7]: http://man7.org/linux/man-pages/man7/capabilities.7.html
245+
[controlling-terminal]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap11.html#tag_11_01_03
246+
[create]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/runtime.md#create
247+
[delete]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/runtime.md#delete
248+
[exit_group.2]: http://man7.org/linux/man-pages/man2/exit_group.2.html
249+
[ioctl.3]: http://pubs.opengroup.org/onlinepubs/9699919799/
250+
[kill]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/runtime.md#kill
251+
[kill.2]: http://man7.org/linux/man-pages/man2/kill.2.html
252+
[process]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/config.md#process
253+
[posix-encoding]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap06.html#tag_06_02
254+
[posix-lang]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_02
255+
[posix-locale-encoding]: http://www.unicode.org/reports/tr35/#Bundle_vs_Item_Lookup
256+
[posix_openpt.3]: http://pubs.opengroup.org/onlinepubs/9699919799/functions/posix_openpt.html
257+
[posix-signals]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html#tag_13_42_03
258+
[prctl.2]: http://man7.org/linux/man-pages/man2/prctl.2.html
259+
[ptrace.2]: http://man7.org/linux/man-pages/man2/ptrace.2.html
260+
[semver]: http://semver.org/spec/v2.0.0.html
261+
[socket-queue]: http://pubs.opengroup.org/onlinepubs/9699919799/functions/V2_chap02.html#tag_15_10_11
262+
[socket-types]: http://pubs.opengroup.org/onlinepubs/9699919799/functions/V2_chap02.html#tag_15_10_06
263+
[socket.h]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_socket.h.html
264+
[standard-streams]: https://github.com/opencontainers/specs/blob/v0.1.1/runtime-linux.md#file-descriptors
265+
[start]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/runtime.md#start
266+
[state]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/runtime.md#state
267+
[state-request]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/runtime.md#query-state
268+
[systemd-listen-fds]: http://www.freedesktop.org/software/systemd/man/sd_listen_fds.html
269+
[rfc2119]: https://tools.ietf.org/html/rfc2119
270+
[runtime-spec-version]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/config.md#specification-version
271+
[TIOCSTI-security]: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=628843
272+
[tty_ioctl.4]: http://man7.org/linux/man-pages/man4/tty_ioctl.4.html
273+
[unix-socket]: http://pubs.opengroup.org/onlinepubs/9699919799/functions/V2_chap02.html#tag_15_10_17
274+
[UTF-8]: http://www.unicode.org/versions/Unicode8.0.0/ch03.pdf

‎docs/runtime-compliance-testing.md

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Runtime compliance testing
2+
3+
## Supported APIs
4+
5+
In order to be tested for [compliance][], runtimes MUST support at least one of the following APIs:
6+
7+
* Version 1.0.0 of the [OCI Runtime Command Line Interface](command-line-interface.md).
8+
9+
[compliance]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/spec.md#notational-conventions

‎schema/README.md

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# JSON schema
2+
3+
This directory contains [JSON Schema][json-schema] for validating JSON covered by local specifications.
4+
The runtime specification includes [a generic command line tool][validate] which may be used to validate JSON with these schemas.
5+
6+
## OCI Runtime Command Line Interface
7+
8+
The [Runtime Command Line Interface](../docs/command-line-interface.md) defines:
9+
10+
* [Terminal requests](../docs/command-line-interface.md#requests), which may be validated against [`socket-terminal-request.json`](socket-terminal-request.json).
11+
* [Responses](../docs/command-line-interface.md#reqponses), which may be validated against [`socket-response.json`](socket-response.json).
12+
13+
[json-schema]: http://json-schema.org/
14+
[validate]: https://github.com/opencontainers/runtime-spec/tree/v1.0.0-rc5/schema#utility

‎schema/socket-response.json

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
{
2+
"description": "Open Container Runtime Socket Response Schema",
3+
"$schema": "http://json-schema.org/draft-04/schema#",
4+
"id": "https://opencontainers.org/schema/runtime/socket/response",
5+
"type": "object",
6+
"properties": {
7+
"type": {
8+
"id": "https://opencontainers.org/schema/runtime/socket/response/type",
9+
"type": "string",
10+
"enum": [
11+
"success",
12+
"error"
13+
]
14+
},
15+
"message": {
16+
"id": "https://opencontainers.org/schema/runtime/socket/response/message",
17+
"description": "A phrase describing the response.",
18+
"type": "string"
19+
}
20+
},
21+
"required": [
22+
"type"
23+
]
24+
}

‎schema/socket-terminal-request.json

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
{
2+
"description": "Open Container Runtime Socket Terminal Request Schema",
3+
"$schema": "http://json-schema.org/draft-04/schema#",
4+
"id": "https://opencontainers.org/schema/runtime/socket/terminal-request",
5+
"type": "object",
6+
"properties": {
7+
"type": {
8+
"id": "https://opencontainers.org/schema/runtime/socket/terminal/request/type",
9+
"type": "string",
10+
"enum": [
11+
"terminal"
12+
]
13+
},
14+
"container": {
15+
"id": "https://opencontainers.org/schema/runtime/state/id",
16+
"description": "the container's ID",
17+
"type": "string"
18+
}
19+
},
20+
"required": [
21+
"type",
22+
"container"
23+
]
24+
}

0 commit comments

Comments
 (0)