Skip to content

runtime.md

Latest commit

 

History

History
77 lines (60 loc) · 3.51 KB

runtime.md

File metadata and controls

77 lines (60 loc) · 3.51 KB

Operations

A conformant runtime should provide an executable (called funC in the following examples). The template for supported commands is:

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

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][posix-locale-encoding] locale-specific character encodings, so a runtime in an en_US.UTF-8 locale should write its version to stdout in [UTF-8][].

Commands

version

Print the runtime version and exit.

  • Options None are required, but the runtime may support options.
  • Standard streams
    • stdin: The runtime may not attempt to read from its stdin.
    • stdout: The runtime must print its name, a space, and its version as the first line to its stdout. The name may contain any Unicode characters except a control codes and newlines. The runtime may print additional lines its stdout, and the format for those lines is not specified in this document.
    • stderr: The runtime may print diagnostic messages to stderr, and the format for those lines is not specified in this document.
  • Exit code: The runtime must exit with zero.

Example:

$ funC version
funC 1.0.0
Built for x86_64-pc-linux-gnu
$ echo $?
0

start

Start a container from a bundle directory.

  • Options
    • --id <ID> Set the container ID when creating or joining a container. If not set, the runtime is free to pick any ID that is not already in use.
    • --config <PATH> Override config.json with an alternative path. The path may not support seeking (e.g. /dev/fd/3).
    • --runtime <PATH> Override runtime.json with an alternative path. The path may not support seeking (e.g. /dev/fd/3).
  • Standard streams: The runtime must attach its standard streams directly to the application process without inspection.
  • Environment variables
    • LISTEN_FDS: The number of file descriptors passed. For example, LISTEN_FDS=2 would mean passing 3 and 4 (in addition to the [standard streams][standard-streams]) to support [socket activation][systemd-listen-fds].
  • Exit code: The runtime must exit with the application process's exit code.

Example:

# in a bundle directory with a process that echos "hello" and exits 42
$ funC start --id hello-1
hello

$ echo $?
42

[posix-locale-encoding: http://www.unicode.org/reports/tr35/#Bundle_vs_Item_Lookup [standard-streams]: https://github.com/opencontainers/specs/blob/v0.1.1/runtime-linux.md#file-descriptors [systemd-listen-fds]: http://www.freedesktop.org/software/systemd/man/sd_listen_fds.html [UTF-8]: http://www.unicode.org/versions/Unicode8.0.0/ch03.pdf