command-line-interface: Split create and start

Catch up with be59415 (Split create and start, 2016-04-01, opencontainers#384).

I'm not a big fan of this early-exit 'create', which requires
platform-specific magic to collect the container process's exit code.

I have a proposal for an 'event' operation [1] which would provide a
convenient created trigger.  With 'event' in place, we don't need the
'create' process exit to serve as that trigger, and could have a
long-running 'create' that collects the container process exit code
using the portable waitid() family.  But the consensus after this
week's meeting was to table that while we land docs for the runC API
[2].

The "SHOULD exit as quickly as possible after ..." wording is going to
be hard to enforce (which is why it's not MUST), but with the runC
model, clients rely on the command exits to trigger post-create and
post-start activity.  The longer the runtime hangs around after
completing its action, the laggier those triggers will be.

The 'create' ID argument is required (while the old 'start' ID
argument was optional) because the runC approach requires an explicit
'delete' call to cleanup the container.  With a long-running 'create'
that could automatically cleanup, you could have an optional ID to
support users that don't care what ID is used (because they know they
won't be calling 'state', 'start', etc.).

One benefit of the early-exit 'create' is that the exit code does not
conflate container process exits with "failed to setup the sandbox"
exits.  We can take advantage of that and use non-zero 'create' exits
to allow stderr writing (so the runtime can log errors while dying
without having to successfully connect to syslog or some such).

The "MUST NOT attempt to read from its stdin" means a generic caller
can safely exec the command with a closed or null stdin, and not have
to worry about the command blocking or crashing because of that.  The
stdout spec for start/delete is more lenient, because runtimes are
unlikely to change their behavior because they are unable to write to
stdout.  If this assumption proves troublesome, we may have to tighten
it up later.

The ptrace idea is from Mrunal [3].

[1]: opencontainers#508
[2]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2016/opencontainers.2016-07-13-17.03.log.html#l-15
[3]: http://ircbot.wl.linuxfoundation.org/eavesdrop/%23opencontainers/%23opencontainers.2016-07-13.log.html#t2016-07-13T18:58:54

Signed-off-by: W. Trevor King <[email protected]>

Author: wking

command-line-interface.md

@@ -45,31 +45,68 @@ $ echo $?
 0
 ```
 
-### start
+### create
 
-[Start][start] a container from a [bundle directory][bundle].
+[Create][create] a container from a [bundle directory][bundle].
+This command SHOULD exit as quickly as possible after creating the container, without waiting for the container process to exit.
 
+* *Arguments*
+    * *`<ID>`* Set the container ID to create.
 * *Options*
-    * *`--id <ID>`* Set the container ID when creating a container.
-      If not set, the runtime is free to pick any ID that is not already in use.
     * *`--bundle <PATH>`* Override the path to the [bundle directory][bundle] (defaults to the current working directory).
-* *Standard streams:* The runtime MUST attach its standard streams directly to the container process without inspection.
+* *Standard streams:*
+    * *stdin:* The runtime MUST attach its stdin directly to the container process without reading from it.
+    * *stdout:* The runtime MUST attach its stdout directly to the container process without writing to it.
+    * *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.
 * *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].
-* *Exit code:* The runtime MUST exit with the container process's exit code.
+* *Exit code:* Zero if the container was successfully created and non-zero on errors.
 
 #### Example
 
 ```
 # in a bundle directory with a process that echos "hello" and exits 42
-$ funC start --id hello-1
+$ test -t 1 && echo 'stdout is a terminal'
+stdout is a terminal
+$ funC create hello-1
+$ echo $?
+0
+$ funC start hello-1
 hello
-
+$ echo $?
+0
+$ block-on-exit-and-collect-exit-code hello-1
 $ echo $?
 42
+$ funC delete hello-1
+$ echo $?
+0
 ```
 
+`hello` shows up on 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`.
+If you call `start` from a shell using a separate terminal, the container output would still have appeared in the `create` terminal.
+
+#### Container process exit
+
+The [example's](#example-1) `block-on-exit-and-collect-exit-code` is platform-specific magic that is not specified in this document.
+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.
+
+### start
+
+[Start][start] the user-specified code from [`process`][process].
+This command SHOULD exit as quickly as possible after triggering the execution, without waiting for the container process to exit.
+
+* *Arguments*
+    * *`<ID>`* Set the container ID 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.
+
+See [create](#example-1) for an example.
+
 ### state
 
 [Request][state-request] the container [state][state].
@@ -135,14 +172,35 @@ $ echo $?
 0
 ```
 
+### delete
+
+[Release](#delete) container resources after the container process has exited.
+
+* *Arguments*
+    * *`<ID>`* Set the container ID 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](#example-1) for an example.
+
 [bundle]: bundle.md
+[create]: runtime.md#create
+[delete]: runtime.md#delete
+[exit_group.2]: http://man7.org/linux/man-pages/man2/exit_group.2.html
 [kill]: runtime.md#kill
 [kill.2]: http://man7.org/linux/man-pages/man2/kill.2.html
+[process]: config.md#process-configuration
 [posix-encoding]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap06.html#tag_06_02
 [posix-lang]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_02
 [posix-locale-encoding]: http://www.unicode.org/reports/tr35/#Bundle_vs_Item_Lookup
 [posix-signals]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html#tag_13_42_03
+[prctl.2]: http://man7.org/linux/man-pages/man2/prctl.2.html
+[ptrace.2]: http://man7.org/linux/man-pages/man2/ptrace.2.html
 [runtime]: glossary.md#runtime
+[standard-streams]: https://github.com/opencontainers/specs/blob/v0.1.1/runtime-linux.md#file-descriptors
 [start]: runtime.md#start
 [state]: runtime.md#state
 [state-request]: runtime.md#query-state