Skip to content

Latest commit

 

History

History
260 lines (206 loc) · 12.8 KB

command-line-interface.md

File metadata and controls

260 lines (206 loc) · 12.8 KB
Raw

Runtime Command Line Interface

This section defines the runtime command line interface version 1.0.0. It is one of potentially several runtime APIs defined by this specification.

Versioning

The command line interface is versioned with SemVer v2.0.0. The command line interface version is independent of the OCI Runtime Specification as a whole (which is tied to the configuration format). 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.

Global usage

The runtime MUST provide an executable (called funC in the following examples). That executable MUST support commands with the following template:

$ funC [global-options] <COMMAND> [command-specific-options] <command-specific-arguments>

Global options

None are required, but the runtime MAY support options that start with at least one hyphen. Global options MAY take positional arguments (e.g. --log-level debug). Command names MUST NOT start with hyphens. The option parsing MUST be such that funC <COMMAND> is unambiguously an invocation of <COMMAND> (even for commands not specified in this document). If the runtime is invoked with an unrecognized command, it MUST exit with a nonzero exit code and MAY log a warning to stderr. Beyond the above rules, the behavior of the runtime in the presence of commands and options not specified in this document is unspecified.

Character encodings

This API specification does not cover character encodings, but runtimes SHOULD conform to their native operating system. For example, POSIX systems define LANG and related environment variables for declaring locale-specific character encodings, so a runtime in an en_US.UTF-8 locale SHOULD write its state to stdout in UTF-8.

Commands

create

Create a container from a bundle directory.

  • Arguments
    • <ID> Set the container ID to create.
  • Options
    • --bundle <PATH> Override the path to the bundle directory (defaults to the current working directory).
    • --pid-file <PATH> The runtime MUST write the container PID to this path.
  • Standard streams:
    • If process.terminal is true:
      • stdin: The runtime MUST NOT attempt to read from its stdin.
      • stdout: The handling of stdout is unspecified.
      • stderr: The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document.
    • If process.terminal is not true:

      • stdin: The runtime MUST pass its stdin file descriptor through to the container process without manipulation or modification. "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 it, or perform any other action on it besides passing it through to the container process.

        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 or other TTY ioctls. On Linux, [TIOCSTI requires CAP_SYS_ADMIN][capabilities.7] unless the target terminal is the caller's controlling terminal.

      • stdout: The runtime MUST pass its stdout file descriptor through to the container process without manipulation or modification.

      • 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. 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.

  • Environment variables
    • LISTEN_FDS: The number of file descriptors passed. 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.
  • Additional file descriptors
  • Exit code: Zero if the container was successfully created and non-zero on errors.

Callers MAY block on this command's successful exit to trigger post-create activity.

Console socket

The AF_UNIX used by --console-socket handles request and response messages between a runtime and server. The socket type MUST be SOCK_SEQPACKET or SOCK_STREAM. The server MUST send a single response for each runtime request. The normal data (msghdr.msg_iov*) of all messages MUST be UTF-8 JSON.

There are JSON Schemas and Go bindings for the messages specified in this section.

Requests

All requests MUST contain a type property whose value MUST one of the following strings:

  • terminal, if the request is passing a pseudoterminal master. When type is terminal, the request MUST also contain the following properties:

    • container (string, REQUIRED) The container ID, as set by create.

    The message's ancillary data (msg_control*) MUST contain at least one cmsghdr). The first cmsghdr MUST have:

    • cmsg_type set to SOL_SOCKET,
    • cmsg_level set to SCM_RIGHTS,
    • cmsg_len greater than or equal to CMSG_LEN(sizeof(int)), and
    • ((int*)CMSG_DATA(cmsg))[0] set to the pseudoterminal master file descriptor.
Responses

All responses MUST contain a type property whose value MUST one of the following strings:

  • success, if the request was successfully processed.
  • error, if the request was not successfully processed.

In addition, responses MAY contain any of the following properties:

  • message (string, OPTIONAL) A phrase describing the response.

Example

# in a bundle directory with a process that echos "hello" and exits 42
$ test -t 1 && echo 'stdout is a terminal'
stdout is a terminal
$ funC create hello-1 <&- >stdout 2>stderr
$ echo $?
0
$ wc stdout
0 0 0 stdout
$ funC start hello-1
$ echo $?
0
$ cat stdout
hello
$ block-on-exit-and-collect-exit-code hello-1
$ echo $?
42
$ funC delete hello-1
$ echo $?
0

Container process exit

The example's block-on-exit-and-collect-exit-code is platform-specific and is not specified in this document. On Linux, it might involve an ancestor process which had set PR_SET_CHILD_SUBREAPER and collected the container PID from the state, or a process that was ptracing the container process for exit_group, although both of those race against the container process exiting before the watcher is monitoring.

start

Start the user-specified code from process.

  • Arguments
    • <ID> The container to start.
  • Standard streams:
    • stdin: The runtime MUST NOT attempt to read from its stdin.
    • stdout: The handling of stdout is unspecified.
    • stderr: The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document.
  • Exit code: Zero if the container was successfully started and non-zero on errors.

Callers MAY block on this command's successful exit to trigger post-start activity.

See create for an example.

state

Request the container state.

  • Arguments
    • <ID> The container whose state is being requested.
  • Standard streams:
    • stdin: The runtime MUST NOT attempt to read from its stdin.
    • stdout: The runtime MUST print the state JSON to its stdout.
    • stderr: The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document.
  • Exit code: Zero if the state was successfully written to stdout and non-zero on errors.

Example

# in a bundle directory with a process that sleeps for several seconds
$ funC start --id sleeper-1 &
$ funC state sleeper-1
{
  "ociVersion": "1.0.0-rc1",
  "id": "sleeper-1",
  "status": "running",
  "pid": 4422,
  "bundlePath": "/containers/sleeper",
  "annotations" {
    "myKey": "myValue"
  }
}
$ echo $?
0

kill

Send a signal to the container process.

  • Arguments
    • <ID> The container being signaled.
  • Options
    • --signal <SIGNAL> The signal to send (defaults to TERM). The runtime MUST support TERM and KILL signals with the POSIX semantics. The runtime MAY support additional signal names. On platforms that support POSIX signals, the runtime MUST implement this command using POSIX signals. 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. 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.
  • Standard streams:
    • stdin: The runtime MUST NOT attempt to read from its stdin.
    • stdout: The handling of stdout is unspecified.
    • stderr: The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document.
  • Exit code: Zero if the signal was successfully sent to the container process and non-zero on errors. Successfully sent does not mean that the signal was successfully received or handled by the container process.

Example

# in a bundle directory with a process ignores TERM
$ funC start --id sleeper-1 &
$ funC kill sleeper-1
$ echo $?
0
$ funC kill --signal KILL sleeper-1
$ echo $?
0

delete

Release container resources after the container process has exited.

  • Arguments
    • <ID> The container to delete.
  • Standard streams:
    • stdin: The runtime MUST NOT attempt to read from its stdin.
    • stdout: The handling of stdout is unspecified.
    • stderr: The runtime MAY print diagnostic messages to stderr, and the format for those lines is not specified in this document.
  • Exit code: Zero if the container was successfully deleted and non-zero on errors.

See create for an example.