From 68850e7b08512fa2c7f0a131eb6e89b748eef3ba Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Thu, 17 Sep 2015 09:29:06 -0700 Subject: [PATCH] Document LISTEN_FDS for passing open file descriptors This landed in runC with [1], but the bundle-author <-> runtime specs explicitly avoid talking about how this is set (since the bundle-author doesn't care about the runtime-caller <-> runtime interface) [2]. However, *this* spec is about the runtime-caller <-> runtime interface, so we need to document it here. I've left LISTEN_PID [3,4] out, since I don't see how the runtime-caller would choose anything other than 1 for its value. It seems like something that a process would have to set for itself (because guessing the PID of a child before spawning it seems racy ;). In any event, the runC implementation seems to set this to 1 regardless of what systemd passes to it [4]. I've borrowed Shishir's wording for the example [4]. [1]: https://github.com/opencontainers/runc/pull/231 [2]: https://github.com/opencontainers/specs/pull/113#issuecomment-135857404 [3]: http://www.freedesktop.org/software/systemd/man/sd_listen_fds.html [4]: https://github.com/opencontainers/runc/pull/231#issuecomment-135469477 Signed-off-by: W. Trevor King --- runtime.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/runtime.md b/runtime.md index a0a95e9..c6b7f70 100644 --- a/runtime.md +++ b/runtime.md @@ -48,6 +48,9 @@ It operates by default on the `config.json` and `runtime.json` in the current di * *`--config `* Override `config.json` with an alternative path. The path may not support seeking (e.g. `/dev/fd/3`). * *`--runtime `* 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: @@ -137,3 +140,6 @@ $ funC signal --signal KILL hello-1 $ echo $? 0 ``` + +[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