Skip to content

Commit

Permalink
runtime: Replace '$LISTEN_FDS + 3' with '--console-socket FD'
Browse files Browse the repository at this point in the history
This bridges the gap between my original '--console-socket PATH'
proposal from 15350b3 (runtime: Add --console-socket for terminal
handling, 2017-02-08) and Michael's approach from baa2412 (runtime:
Replace '--console-socket PATH' with '$LISTEN_FDS + 3', 2017-02-08).
All of the benefits of not needing an on-disk socket, and none of the
magic of overloading $LISTEN_FDS.  I don't know why Michael didn't
like this approach as much [1], but it feels a lot better to me.

[1]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2016/opencontainers.2016-10-19-21.00.log.html#l-31

Signed-off-by: W. Trevor King <wking@tremily.us>
  • Loading branch information
wking committed Feb 9, 2017
1 parent a26d73b commit 26440a5
Showing 1 changed file with 2 additions and 4 deletions.
6 changes: 2 additions & 4 deletions runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@ For example, POSIX systems define [`LANG` and related environment variables][pos
* *`<ID>`* Set the container ID to create.
* *Options*
* *`--bundle <PATH>`* Override the path to the [bundle directory][bundle] (defaults to the current working directory).
* *`--console-socket <FD>`* The runtime MUST pass the [pseudoterminal master][posix_openpt.3] through the open socket at file descriptor `<FD>`; the protocol is [described below](#console-socket).
* *`--pid-file <PATH>`* The runtime MUST write the container PID to this path.
* *Standard streams:*
* If [`process.terminal`][process] is true:
Expand All @@ -59,16 +60,13 @@ For example, POSIX systems define [`LANG` and related environment variables][pos
* *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][systemd-listen-fds].
* *Additional file descriptors*
* If [`process.terminal`][process] is true, the caller MUST provide an open [`AF_UNIX` socket][unix-socket] on file descriptor `$LISTEN_FDS + 3`.
The runtime MUST pass the [pseudoterminal master][posix_openpt.3] through the socket; the protocol is [described below](#console-socket).
* *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`][unix-socket] used by the [`$LISTEN_FDS + 3` socket](#create) handles request and response messages between a runtime and server.
The [`AF_UNIX`][unix-socket] used by [`--console-socket`](#create) handles request and response messages between a runtime and server.
The socket type MUST be [`SOCK_SEQPACKET`][socket-types] or [`SOCK_STREAM`][socket-types].
The server MUST send a single response for each runtime request.
The [normal data][socket-queue] ([`msghdr.msg_iov*`][socket.h]) of all messages MUST be [UTF-8][] [JSON](glossary.md#json).
Expand Down

0 comments on commit 26440a5

Please sign in to comment.