|
| 1 | +# Operations |
| 2 | + |
| 3 | +The [runtime][] MUST provide an executable (called `funC` in the following examples). |
| 4 | +That executable MUST support commands with the following template: |
| 5 | + |
| 6 | +``` |
| 7 | +$ funC [global-options] <COMMAND> [command-specific-options] <command-specific-arguments> |
| 8 | +``` |
| 9 | + |
| 10 | +## Global options |
| 11 | + |
| 12 | +None are required, but the runtime MAY support options that start with at least one hyphen. |
| 13 | +Global options MAY take positional arguments (e.g. `--log-level debug`). |
| 14 | +Command names MUST NOT start with hyphens. |
| 15 | +The option parsing MUST be such that `funC <COMMAND>` is unambiguously an invocation of `<COMMAND>` (even for commands not specified in this document). |
| 16 | +If the runtime is invoked with an unrecognized command, it MUST exit with a nonzero exit code and MAY log a warning to stderr. |
| 17 | +Beyond the above rules, the behavior of the runtime in the presence of commands and options not specified in this document is unspecified. |
| 18 | + |
| 19 | +## Character encodings |
| 20 | + |
| 21 | +This API specification does not cover character encodings, but runtimes SHOULD conform to their native operating system. |
| 22 | +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][]. |
| 23 | + |
| 24 | +## Commands |
| 25 | + |
| 26 | +### create |
| 27 | + |
| 28 | +[Create][create] a container from a [bundle directory][bundle]. |
| 29 | + |
| 30 | +* *Arguments* |
| 31 | + * *`<ID>`* Set the container ID to create. |
| 32 | +* *Options* |
| 33 | + * *`--bundle <PATH>`* Override the path to the [bundle directory][bundle] (defaults to the current working directory). |
| 34 | + * *`--pid-file <PATH>`* The runtime MUST write the container PID to this path. |
| 35 | + * *`--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). |
| 36 | + `--console-socket` MUST be set when [`process.terminal`][process] is true and MUST NOT be set when [`process.terminal`][process] is not true. |
| 37 | +* *Standard streams:* |
| 38 | + * If [`process.terminal`][process] is true: |
| 39 | + * *stdin:* The runtime MUST NOT attempt to read from its stdin. |
| 40 | + * *stdout:* The handling of stdout is unspecified. |
| 41 | + * *stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document. |
| 42 | + * If [`process.terminal`][process] is not true: |
| 43 | + * *stdin:* The runtime MUST attach its stdin directly to the container process without reading from it. |
| 44 | + * *stdout:* The runtime MUST attach its stdout directly to the container process without writing to it. |
| 45 | + * *stderr:* The runtime MUST attach its stderr to the container process, and MUST not write to it unless it exits with a non-zero code. |
| 46 | +* *Environment variables* |
| 47 | + * *`LISTEN_FDS`:* The number of file descriptors passed. |
| 48 | + 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]. |
| 49 | +* *Exit code:* Zero if the container was successfully created and non-zero on errors. |
| 50 | + |
| 51 | +Callers MAY block on this command's successful exit to trigger post-create activity. |
| 52 | + |
| 53 | +#### Console socket |
| 54 | + |
| 55 | +The [`AF_UNIX`][unix-socket] [`SOCK_SEQPACKET`][socket-types] used by [`--console-socket`](#create) handles request and response messages between a client and server. |
| 56 | +The server MUST send a single response for each client request. |
| 57 | +The [normal data][socket-queue] ([`msghdr.msg_iov*`][socket.h]) of all messages MUST be [UTF-8][] [JSON](glossary.md#json). |
| 58 | + |
| 59 | +There are [JSON Schemas](schema/README.md) and [Go bindings](specs-go/socket/socket.go) for the messages specified in this section. |
| 60 | + |
| 61 | +##### Requests |
| 62 | + |
| 63 | +All requests MUST contain a **`type`** property whose value MUST one of the following strings: |
| 64 | + |
| 65 | +* `terminal`, if the request is passing a [pseudoterminal master][posix_openpt.3]. |
| 66 | + When `type` is `terminal`, the request MUST also contain the following properties: |
| 67 | + |
| 68 | + * **`container`** (string, REQUIRED) The container ID, as set by [create](#create). |
| 69 | + |
| 70 | + The message's [ancillary data][socket-queue] (`msg_control*`) MUST contain a single [`cmsghdr`][socket.h]) with: |
| 71 | + |
| 72 | + * `cmsg_type` set to [`SOL_SOCKET`][socket.h], |
| 73 | + * `cmsg_level` set to [`SCM_RIGHTS`][socket.h], |
| 74 | + * `cmsg_len` set to `CMSG_LEN(sizeof(int))`, and |
| 75 | + * `*CMSG_DATA(cmsg)` set to the pseudoterminal master file descriptor. |
| 76 | + |
| 77 | +##### Responses |
| 78 | + |
| 79 | +All responses MUST contain a **`type`** property whose value MUST one of the following strings: |
| 80 | + |
| 81 | +* `success`, if the request was successfully processed. |
| 82 | +* `error`, if the request was not successfully processed. |
| 83 | + |
| 84 | +In addition, responses MAY contain any of the following properties: |
| 85 | + |
| 86 | +* **`message`** (string, OPTIONAL) A phrase describing the response. |
| 87 | + |
| 88 | +#### Example |
| 89 | + |
| 90 | +``` |
| 91 | +# in a bundle directory with a process that echos "hello" and exits 42 |
| 92 | +$ test -t 1 && echo 'stdout is a terminal' |
| 93 | +stdout is a terminal |
| 94 | +$ funC create hello-1 |
| 95 | +$ echo $? |
| 96 | +0 |
| 97 | +$ funC start hello-1 |
| 98 | +hello |
| 99 | +$ echo $? |
| 100 | +0 |
| 101 | +$ block-on-exit-and-collect-exit-code hello-1 |
| 102 | +$ echo $? |
| 103 | +42 |
| 104 | +$ funC delete hello-1 |
| 105 | +$ echo $? |
| 106 | +0 |
| 107 | +``` |
| 108 | + |
| 109 | +`hello` shows up in the terminal after `start`, because `start` happens to be called from the same shell session (using the same terminal) as `create`, and the container process inherited its standard streams from `create`. |
| 110 | +If you call `start` from a shell using a separate terminal, the container output would still have appeared in the `create` terminal. |
| 111 | + |
| 112 | +#### Container process exit |
| 113 | + |
| 114 | +The [example's](#example) `block-on-exit-and-collect-exit-code` is platform-specific magic that is not specified in this document. |
| 115 | +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. |
| 116 | + |
| 117 | +### start |
| 118 | + |
| 119 | +[Start][start] the user-specified code from [`process`][process]. |
| 120 | + |
| 121 | +* *Arguments* |
| 122 | + * *`<ID>`* Set the container ID to start. |
| 123 | +* *Standard streams:* |
| 124 | + * *stdin:* The runtime MUST NOT attempt to read from its stdin. |
| 125 | + * *stdout:* The handling of stdout is unspecified. |
| 126 | + * *stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document. |
| 127 | +* *Exit code:* Zero if the container was successfully started and non-zero on errors. |
| 128 | + |
| 129 | +Callers MAY block on this command's successful exit to trigger post-start activity. |
| 130 | + |
| 131 | +See [create](#example) for an example. |
| 132 | + |
| 133 | +### state |
| 134 | + |
| 135 | +[Request][state-request] the container [state][state]. |
| 136 | + |
| 137 | +* *Arguments* |
| 138 | + * *`<ID>`* The container whose state is being requested. |
| 139 | +* *Standard streams:* |
| 140 | + * *stdin:* The runtime MUST NOT attempt to read from its stdin. |
| 141 | + * *stdout:* The runtime MUST print the [state JSON][state] to its stdout. |
| 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 state was successfully written to stdout and non-zero on errors. |
| 144 | + |
| 145 | +#### Example |
| 146 | + |
| 147 | +``` |
| 148 | +# in a bundle directory with a process that sleeps for several seconds |
| 149 | +$ funC start --id sleeper-1 & |
| 150 | +$ funC state sleeper-1 |
| 151 | +{ |
| 152 | + "ociVersion": "1.0.0-rc1", |
| 153 | + "id": "sleeper-1", |
| 154 | + "status": "running", |
| 155 | + "pid": 4422, |
| 156 | + "bundlePath": "/containers/sleeper", |
| 157 | + "annotations" { |
| 158 | + "myKey": "myValue" |
| 159 | + } |
| 160 | +} |
| 161 | +$ echo $? |
| 162 | +0 |
| 163 | +``` |
| 164 | + |
| 165 | +### kill |
| 166 | + |
| 167 | +[Send a signal][kill] to the container process. |
| 168 | + |
| 169 | +* *Arguments* |
| 170 | + * *`<ID>`* The container being signaled. |
| 171 | +* *Options* |
| 172 | + * *`--signal <SIGNAL>`* The signal to send (defaults to `TERM`). |
| 173 | + The runtime MUST support `TERM` and `KILL` signals with [the POSIX semantics][posix-signals]. |
| 174 | + The runtime MAY support additional signal names. |
| 175 | + On platforms that support [POSIX signals][posix-signals], the runtime MUST implement this command using POSIX signals. |
| 176 | + 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. |
| 177 | + 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. |
| 178 | +* *Standard streams:* |
| 179 | + * *stdin:* The runtime MUST NOT attempt to read from its stdin. |
| 180 | + * *stdout:* The runtime MAY print diagnostic messaged to stdout, and the format for those lines is not specified in this document. |
| 181 | + * *stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document. |
| 182 | +* *Exit code:* Zero if the signal was successfully sent to the container process and non-zero on errors. |
| 183 | + Successfully sent does not mean that the signal was successfully received or handled by the container process. |
| 184 | + |
| 185 | +#### Example |
| 186 | + |
| 187 | +``` |
| 188 | +# in a bundle directory with a process ignores TERM |
| 189 | +$ funC start --id sleeper-1 & |
| 190 | +$ funC kill sleeper-1 |
| 191 | +$ echo $? |
| 192 | +0 |
| 193 | +$ funC kill --signal KILL sleeper-1 |
| 194 | +$ echo $? |
| 195 | +0 |
| 196 | +``` |
| 197 | + |
| 198 | +### delete |
| 199 | + |
| 200 | +[Release](#delete) container resources after the container process has exited. |
| 201 | + |
| 202 | +* *Arguments* |
| 203 | + * *`<ID>`* Set the container ID to delete. |
| 204 | +* *Standard streams:* |
| 205 | + * *stdin:* The runtime MUST NOT attempt to read from its stdin. |
| 206 | + * *stdout:* The handling of stdout is unspecified. |
| 207 | + * *stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document. |
| 208 | +* *Exit code:* Zero if the container was successfully deleted and non-zero on errors. |
| 209 | + |
| 210 | +See [create](#example) for an example. |
| 211 | + |
| 212 | +[bundle]: bundle.md |
| 213 | +[create]: runtime.md#create |
| 214 | +[delete]: runtime.md#delete |
| 215 | +[exit_group.2]: http://man7.org/linux/man-pages/man2/exit_group.2.html |
| 216 | +[kill]: runtime.md#kill |
| 217 | +[kill.2]: http://man7.org/linux/man-pages/man2/kill.2.html |
| 218 | +[process]: config.md#process-configuration |
| 219 | +[posix-encoding]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap06.html#tag_06_02 |
| 220 | +[posix-lang]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_02 |
| 221 | +[posix-locale-encoding]: http://www.unicode.org/reports/tr35/#Bundle_vs_Item_Lookup |
| 222 | +[posix_openpt.3]: http://pubs.opengroup.org/onlinepubs/9699919799/functions/posix_openpt.html |
| 223 | +[posix-signals]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html#tag_13_42_03 |
| 224 | +[prctl.2]: http://man7.org/linux/man-pages/man2/prctl.2.html |
| 225 | +[ptrace.2]: http://man7.org/linux/man-pages/man2/ptrace.2.html |
| 226 | +[runtime]: glossary.md#runtime |
| 227 | +[socket-queue]: http://pubs.opengroup.org/onlinepubs/9699919799/functions/V2_chap02.html#tag_15_10_11 |
| 228 | +[socket-types]: http://pubs.opengroup.org/onlinepubs/9699919799/functions/V2_chap02.html#tag_15_10_06 |
| 229 | +[socket.h]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_socket.h.html |
| 230 | +[standard-streams]: https://github.com/opencontainers/specs/blob/v0.1.1/runtime-linux.md#file-descriptors |
| 231 | +[start]: runtime.md#start |
| 232 | +[state]: runtime.md#state |
| 233 | +[state-request]: runtime.md#query-state |
| 234 | +[systemd-listen-fds]: http://www.freedesktop.org/software/systemd/man/sd_listen_fds.html |
| 235 | +[unix-socket]: http://pubs.opengroup.org/onlinepubs/9699919799/functions/V2_chap02.html#tag_15_10_17 |
| 236 | +[UTF-8]: http://www.unicode.org/versions/Unicode8.0.0/ch03.pdf |
0 commit comments