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