|
| 1 | +# Operations |
| 2 | + |
| 3 | +A conformant [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 | +* *Standard streams:* |
| 36 | + * *stdin:* The runtime MUST attach its stdin directly to the container process without reading from it. |
| 37 | + * *stdout:* The runtime MUST attach its stdout directly to the container process without writing to it. |
| 38 | + * *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. |
| 39 | +* *Environment variables* |
| 40 | + * *`LISTEN_FDS`:* The number of file descriptors passed. |
| 41 | + 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]. |
| 42 | +* *Exit code:* Zero if the container was successfully created and non-zero on errors. |
| 43 | + |
| 44 | +Callers MAY block on this command's successful exit to trigger post-create activity. |
| 45 | + |
| 46 | +#### Example |
| 47 | + |
| 48 | +``` |
| 49 | +# in a bundle directory with a process that echos "hello" and exits 42 |
| 50 | +$ test -t 1 && echo 'stdout is a terminal' |
| 51 | +stdout is a terminal |
| 52 | +$ funC create hello-1 |
| 53 | +$ echo $? |
| 54 | +0 |
| 55 | +$ funC start hello-1 |
| 56 | +hello |
| 57 | +$ echo $? |
| 58 | +0 |
| 59 | +$ block-on-exit-and-collect-exit-code hello-1 |
| 60 | +$ echo $? |
| 61 | +42 |
| 62 | +$ funC delete hello-1 |
| 63 | +$ echo $? |
| 64 | +0 |
| 65 | +``` |
| 66 | + |
| 67 | +`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`. |
| 68 | +If you call `start` from a shell using a separate terminal, the container output would still have appeared in the `create` terminal. |
| 69 | + |
| 70 | +#### Container process exit |
| 71 | + |
| 72 | +The [example's](#example) `block-on-exit-and-collect-exit-code` is platform-specific magic that is not specified in this document. |
| 73 | +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. |
| 74 | + |
| 75 | +### start |
| 76 | + |
| 77 | +[Start][start] the user-specified code from [`process`][process]. |
| 78 | + |
| 79 | +* *Arguments* |
| 80 | + * *`<ID>`* Set the container ID to start. |
| 81 | +* *Standard streams:* |
| 82 | + * *stdin:* The runtime MUST NOT attempt to read from its stdin. |
| 83 | + * *stdout:* The handling of stdout is unspecified. |
| 84 | + * *stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document. |
| 85 | +* *Exit code:* Zero if the container was successfully started and non-zero on errors. |
| 86 | + |
| 87 | +Callers MAY block on this command's successful exit to trigger post-start activity. |
| 88 | + |
| 89 | +See [create](#example) for an example. |
| 90 | + |
| 91 | +### state |
| 92 | + |
| 93 | +[Request][state-request] the container [state][state]. |
| 94 | + |
| 95 | +* *Arguments* |
| 96 | + * *`<ID>`* The container whose state is being requested. |
| 97 | +* *Standard streams:* |
| 98 | + * *stdin:* The runtime MUST NOT attempt to read from its stdin. |
| 99 | + * *stdout:* The runtime MUST print the [state JSON][state] to its stdout. |
| 100 | + * *stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document. |
| 101 | +* *Exit code:* Zero if the state was successfully written to stdout and non-zero on errors. |
| 102 | + |
| 103 | +#### Example |
| 104 | + |
| 105 | +``` |
| 106 | +# in a bundle directory with a process that sleeps for several seconds |
| 107 | +$ funC start --id sleeper-1 & |
| 108 | +$ funC state sleeper-1 |
| 109 | +{ |
| 110 | + "ociVersion": "1.0.0-rc1", |
| 111 | + "id": "sleeper-1", |
| 112 | + "status": "running", |
| 113 | + "pid": 4422, |
| 114 | + "bundlePath": "/containers/sleeper", |
| 115 | + "annotations" { |
| 116 | + "myKey": "myValue" |
| 117 | + } |
| 118 | +} |
| 119 | +$ echo $? |
| 120 | +0 |
| 121 | +``` |
| 122 | + |
| 123 | +### kill |
| 124 | + |
| 125 | +[Send a signal][kill] to the container process. |
| 126 | + |
| 127 | +* *Arguments* |
| 128 | + * *`<ID>`* The container being signaled. |
| 129 | +* *Options* |
| 130 | + * *`--signal <SIGNAL>`* The signal to send (defaults to `TERM`). |
| 131 | + The runtime MUST support `TERM` and `KILL` signals with [the POSIX semantics][posix-signals]. |
| 132 | + The runtime MAY support additional signal names. |
| 133 | + On platforms that support [POSIX signals][posix-signals], the runtime MUST implement this command using POSIX signals. |
| 134 | + 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. |
| 135 | + 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. |
| 136 | +* *Standard streams:* |
| 137 | + * *stdin:* The runtime MUST NOT attempt to read from its stdin. |
| 138 | + * *stdout:* The runtime MAY print diagnostic messaged to stdout, and the format for those lines is not specified in this document. |
| 139 | + * *stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document. |
| 140 | +* *Exit code:* Zero if the signal was successfully sent to the container process and non-zero on errors. |
| 141 | + Successfully sent does not mean that the signal was successfully received or handled by the container process. |
| 142 | + |
| 143 | +#### Example |
| 144 | + |
| 145 | +``` |
| 146 | +# in a bundle directory with a process ignores TERM |
| 147 | +$ funC start --id sleeper-1 & |
| 148 | +$ funC kill sleeper-1 |
| 149 | +$ echo $? |
| 150 | +0 |
| 151 | +$ funC kill --signal KILL sleeper-1 |
| 152 | +$ echo $? |
| 153 | +0 |
| 154 | +``` |
| 155 | + |
| 156 | +### delete |
| 157 | + |
| 158 | +[Release](#delete) container resources after the container process has exited. |
| 159 | + |
| 160 | +* *Arguments* |
| 161 | + * *`<ID>`* Set the container ID to delete. |
| 162 | +* *Standard streams:* |
| 163 | + * *stdin:* The runtime MUST NOT attempt to read from its stdin. |
| 164 | + * *stdout:* The handling of stdout is unspecified. |
| 165 | + * *stderr:* The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document. |
| 166 | +* *Exit code:* Zero if the container was successfully deleted and non-zero on errors. |
| 167 | + |
| 168 | +See [create](#example) for an example. |
| 169 | + |
| 170 | +[bundle]: bundle.md |
| 171 | +[create]: runtime.md#create |
| 172 | +[delete]: runtime.md#delete |
| 173 | +[exit_group.2]: http://man7.org/linux/man-pages/man2/exit_group.2.html |
| 174 | +[kill]: runtime.md#kill |
| 175 | +[kill.2]: http://man7.org/linux/man-pages/man2/kill.2.html |
| 176 | +[process]: config.md#process-configuration |
| 177 | +[posix-encoding]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap06.html#tag_06_02 |
| 178 | +[posix-lang]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_02 |
| 179 | +[posix-locale-encoding]: http://www.unicode.org/reports/tr35/#Bundle_vs_Item_Lookup |
| 180 | +[posix-signals]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html#tag_13_42_03 |
| 181 | +[prctl.2]: http://man7.org/linux/man-pages/man2/prctl.2.html |
| 182 | +[ptrace.2]: http://man7.org/linux/man-pages/man2/ptrace.2.html |
| 183 | +[runtime]: glossary.md#runtime |
| 184 | +[standard-streams]: https://github.com/opencontainers/specs/blob/v0.1.1/runtime-linux.md#file-descriptors |
| 185 | +[start]: runtime.md#start |
| 186 | +[state]: runtime.md#state |
| 187 | +[state-request]: runtime.md#query-state |
| 188 | +[systemd-listen-fds]: http://www.freedesktop.org/software/systemd/man/sd_listen_fds.html |
| 189 | +[UTF-8]: http://www.unicode.org/versions/Unicode8.0.0/ch03.pdf |
0 commit comments