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
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
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.
4
-
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]).
3
+
The [OCI Runtime Specification][specs] 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.
4
+
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]).
5
5
This repository contains initial work on that API, with more detailed discussion in [this thread][thread].
6
6
The usual [development rules][rules] apply, and the legal stuff is spelled out [here](CONTRIBUTING.md).
7
-
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.
7
+
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.
A conformant runtime MUST provide an executable (called `funC` in the following examples).
3
+
This section defines the OCI Runtime Command Line Interface version 1.0.0.
4
+
5
+
## Versioning
6
+
7
+
The command line interface is versioned with [SemVer v2.0.0][semver].
8
+
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].
9
+
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.
10
+
11
+
## Global usage
12
+
13
+
The runtime MUST provide an executable (called `funC` in the following examples).
4
14
That executable MUST support commands with the following template:
None are required, but the runtime MAY support options that start with at least one hyphen.
13
23
Global options MAY take positional arguments (e.g. `--log-level debug`).
14
-
Command names MUST not start with hyphens.
24
+
Command names MUST NOT start with hyphens.
15
25
The option parsing MUST be such that `funC <COMMAND>` is unambiguously an invocation of `<COMMAND>` (even for commands not specified in this document).
16
26
If the runtime is invoked with an unrecognized command, it MUST exit with a nonzero exit code and MAY log a warning to stderr.
27
+
Beyond the above rules, the behavior of the runtime in the presence of commands and options not specified in this document is unspecified.
17
28
18
29
## Character encodings
19
30
20
31
This API specification does not cover character encodings, but runtimes SHOULD conform to their native operating system.
21
-
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][].
32
+
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][].
22
33
23
34
## Commands
24
35
25
-
### version
36
+
### create
26
37
27
-
Print the runtime version and exit.
38
+
[Create][create] a container from a [bundle directory][bundle].
28
39
29
-
**Options* None are required, but the runtime MAY support options.
30
-
**Standard streams*
31
-
**stdin:* The runtime MUST NOT attempt to read from its stdin.
32
-
**stdout:* The runtime MUST print its name, a space, and its version as the first line to its stdout.
33
-
The name MAY contain any Unicode characters, but MUST NOT contain control codes or newlines.
34
-
The runtime MAY print additional lines to its stdout, and the format for those lines is not specified in this document.
35
-
**stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document.
36
-
**Exit code:* The runtime MUST exit with zero.
40
+
**Arguments*
41
+
**`<ID>`* Set the container ID to create.
42
+
**Options*
43
+
**`--bundle <PATH>`* Override the path to the [bundle directory][bundle] (defaults to the current working directory).
44
+
**`--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).
45
+
**`--pid-file <PATH>`* The runtime MUST write the container PID to this path.
46
+
**Standard streams:*
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.
37
54
38
-
#### Example
55
+
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].
56
+
On Linux, [`TIOCSTI` requires `CAP_SYS_ADMIN`][capabilities.7] unless the target terminal is the caller's [controlling terminal][controlling-terminal].
57
+
**stdout:* The runtime MUST pass its stdout file descriptor through to the container process without manipulation or modification.
58
+
**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.
59
+
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.
60
+
**Environment variables*
61
+
**`LISTEN_FDS`:* The number of file descriptors passed.
62
+
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].
63
+
**Exit code:* Zero if the container was successfully created and non-zero on errors.
39
64
40
-
```
41
-
$ funC version
42
-
funC 1.0.0
43
-
Built for x86_64-pc-linux-gnu
44
-
$ echo $?
45
-
0
46
-
```
65
+
Callers MAY block on this command's successful exit to trigger post-create activity.
47
66
48
-
###start
67
+
#### Console socket
49
68
50
-
Start a container from a bundle directory.
69
+
The [`AF_UNIX`][unix-socket] used by [`--console-socket`](#create) handles request and response messages between a runtime and server.
70
+
The socket type MUST be [`SOCK_SEQPACKET`][socket-types] or [`SOCK_STREAM`][socket-types].
71
+
The server MUST send a single response for each runtime request.
72
+
The [normal data][socket-queue] ([`msghdr.msg_iov*`][socket.h]) of all messages MUST be [UTF-8][][JSON](glossary.md#json).
51
73
52
-
**Options*
53
-
**`--id <ID>`* Set the container ID when creating or joining a container.
54
-
If not set, the runtime is free to pick any ID that is not already in use.
55
-
**`--bundle <PATH>`* Override the path to the bundle directory (defaults to the current working directory).
56
-
**Standard streams:* The runtime MUST attach its standard streams directly to the application process without inspection.
57
-
**Environment variables*
58
-
**`LISTEN_FDS`:* The number of file descriptors passed.
59
-
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].
60
-
**Exit code:* The runtime MUST exit with the application process's exit code.
74
+
There are [JSON Schemas](schema/README.md) and [Go bindings](specs-go/socket/socket.go) for the messages specified in this section.
75
+
76
+
##### Requests
77
+
78
+
All requests MUST contain a **`type`** property whose value MUST one of the following strings:
79
+
80
+
*`terminal`, if the request is passing a [pseudoterminal master][posix_openpt.3].
81
+
When `type` is `terminal`, the request MUST also contain the following properties:
82
+
83
+
***`container`** (string, REQUIRED) The container ID, as set by [create](#create).
84
+
85
+
The message's [ancillary data][socket-queue] (`msg_control*`) MUST contain at least one [`cmsghdr`][socket.h]).
86
+
The first `cmsghdr` MUST have:
87
+
88
+
*`cmsg_type` set to [`SOL_SOCKET`][socket.h],
89
+
*`cmsg_level` set to [`SCM_RIGHTS`][socket.h],
90
+
*`cmsg_len` greater than or equal to `CMSG_LEN(sizeof(int))`, and
91
+
*`((int*)CMSG_DATA(cmsg))[0]` set to the pseudoterminal master file descriptor.
92
+
93
+
##### Responses
94
+
95
+
All responses MUST contain a **`type`** property whose value MUST be one of the following strings:
96
+
97
+
*`success`, if the request was successfully processed.
98
+
*`error`, if the request was not successfully processed.
99
+
100
+
In addition, responses MAY contain any of the following properties:
101
+
102
+
***`message`** (string, OPTIONAL) A phrase describing the response.
61
103
62
104
#### Example
63
105
64
106
```
65
107
# in a bundle directory with a process that echos "hello" and exits 42
66
-
$ funC start --id hello-1
108
+
$ test -t 1 && echo 'stdout is a terminal'
109
+
stdout is a terminal
110
+
$ funC create hello-1 <&- >stdout 2>stderr
111
+
$ echo $?
112
+
0
113
+
$ wc stdout
114
+
0 0 0 stdout
115
+
$ funC start hello-1
116
+
$ echo $?
117
+
0
118
+
$ cat stdout
67
119
hello
68
-
120
+
$ block-on-exit-and-collect-exit-code hello-1
69
121
$ echo $?
70
122
42
123
+
$ funC delete hello-1
124
+
$ echo $?
125
+
0
71
126
```
72
127
128
+
#### Container process exit
129
+
130
+
The [example's](#example)`block-on-exit-and-collect-exit-code` is platform-specific and is not specified in this document.
131
+
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.
132
+
133
+
### start
134
+
135
+
[Start][start] the user-specified code from [`process`][process].
136
+
137
+
**Arguments*
138
+
**`<ID>`* The container to start.
139
+
**Standard streams:*
140
+
**stdin:* The runtime MUST NOT attempt to read from its stdin.
141
+
**stdout:* The handling of stdout is unspecified.
142
+
**stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document.
143
+
**Exit code:* Zero if the container was successfully started and non-zero on errors.
144
+
145
+
Callers MAY block on this command's successful exit to trigger post-start activity.
146
+
147
+
See [create](#example) for an example.
148
+
73
149
### state
74
150
75
-
Request the container state.
151
+
[Request][state-request] the container [state][state].
76
152
77
153
**Arguments*
78
-
**`<ID>`* The container whose state is being requested.
154
+
**`<ID>`* The container whose state is being requested.
79
155
**Standard streams:*
80
-
**stdin:* The runtime MUST NOT attempt to read from its stdin.
81
-
**stdout:* The runtime MUST print the state JSON to its stdout.
82
-
**stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document.
156
+
**stdin:* The runtime MUST NOT attempt to read from its stdin.
157
+
**stdout:* The runtime MUST print the [state JSON][state] to its stdout.
158
+
**stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document.
83
159
**Exit code:* Zero if the state was successfully written to stdout and non-zero on errors.
84
160
85
161
#### Example
86
162
87
163
```
88
-
# in a bundle directory with a process that sleeps for several seconds
89
-
$ funC start --id sleeper-1 &
164
+
$ funC create sleeper-1
90
165
$ funC state sleeper-1
91
166
{
92
167
"ociVersion": "1.0.0-rc1",
93
168
"id": "sleeper-1",
94
-
"status": "running",
169
+
"status": "created",
95
170
"pid": 4422,
96
171
"bundlePath": "/containers/sleeper",
97
172
"annotations" {
@@ -102,9 +177,82 @@ $ echo $?
102
177
0
103
178
```
104
179
180
+
### kill
181
+
182
+
[Send a signal][kill] to the container process.
183
+
184
+
**Arguments*
185
+
**`<ID>`* The container being signaled.
186
+
**Options*
187
+
**`--signal <SIGNAL>`* The signal to send (defaults to `TERM`).
188
+
The runtime MUST support `TERM` and `KILL` signals with [the POSIX semantics][posix-signals].
189
+
The runtime MAY support additional signal names.
190
+
On platforms that support [POSIX signals][posix-signals], the runtime MUST implement this command using POSIX signals.
191
+
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.
192
+
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.
193
+
**Standard streams:*
194
+
**stdin:* The runtime MUST NOT attempt to read from its stdin.
195
+
**stdout:* The handling of stdout is unspecified.
196
+
**stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document.
197
+
**Exit code:* Zero if the signal was successfully sent to the container process and non-zero on errors.
198
+
Successfully sent does not mean that the signal was successfully received or handled by the container process.
199
+
200
+
#### Example
201
+
202
+
```
203
+
# in a bundle directory where the container process ignores TERM
204
+
$ funC create sleeper-1
205
+
$ funC start sleeper-1
206
+
$ funC kill sleeper-1
207
+
$ echo $?
208
+
0
209
+
$ funC kill --signal KILL sleeper-1
210
+
$ echo $?
211
+
0
212
+
```
213
+
214
+
### delete
215
+
216
+
[Release](#delete) container resources after the container process has exited.
217
+
218
+
**Arguments*
219
+
**`<ID>`* The container to delete.
220
+
**Standard streams:*
221
+
**stdin:* The runtime MUST NOT attempt to read from its stdin.
222
+
**stdout:* The handling of stdout is unspecified.
223
+
**stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document.
224
+
**Exit code:* Zero if the container was successfully deleted and non-zero on errors.
0 commit comments