From 242461848017886b07882643dca099bc74b5dbf7 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 6 Jul 2016 21:16:59 -0700 Subject: [PATCH] command-line-interface: Add a 'kill' command Partially catch up with be594153 (Split create and start, 2016-04-01, #384). The interface is based on POSIX [1], util-linux [2], and GNU coreutils [3]. The TERM/KILL requirement is a minimum portability requirement for soft/hard stops. Windows lacks POSIX signals [4], and currently supports soft stops in Docker with whatever is behind hcsshim.ShutdownComputeSystem [5]. The docs I'm landing here explicitly allow that sort of substitution, because we need to have soft/hard stop on those platforms but *can't* use POSIX signals. They borrow wording from 35b0e9ee (config: Clarify MUST for platform.os and .arch, 2016-05-19, #441) to recommend runtime authors document the alternative technology so bundle-authors can prepare (e.g. by installing the equivalent to a SIGTERM signal handler). [1]: http://pubs.opengroup.org/onlinepubs/9699919799/utilities/kill.html [2]: http://man7.org/linux/man-pages/man1/kill.1.html [3]: http://www.gnu.org/software/coreutils/manual/html_node/kill-invocation.html [4]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/PlGKu7QUwLE Subject: Fwd: Windows support for OCI stop/signal/kill (runtime-spec#356) Date: Thu, 26 May 2016 11:03:29 -0700 Message-ID: <20160526180329.GL17496@odin.tremily.us> [5]: https://github.com/docker/docker/pull/16997/files#diff-5d0b72cccc4809455d52aadc62329817R230 Signed-off-by: W. Trevor King --- command-line-interface.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/command-line-interface.md b/command-line-interface.md index c0f8a2833..b42c56bda 100644 --- a/command-line-interface.md +++ b/command-line-interface.md @@ -102,10 +102,46 @@ $ echo $? 0 ``` +### kill + +[Send a signal][kill] to the container process. + +* *Arguments* + * *``* The container being signaled. +* *Options* + * *`--signal `* The signal to send (defaults to `TERM`). + The runtime MUST support `TERM` and `KILL` signals with [the POSIX semantics][posix-signals]. + The runtime MAY support additional signal names. + On platforms that support [POSIX signals][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 runtime MAY print diagnostic messaged to 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:* 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 +``` + [bundle]: bundle.md +[kill]: runtime.md#kill +[kill.2]: http://man7.org/linux/man-pages/man2/kill.2.html [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 [runtime]: glossary.md#runtime [start]: runtime.md#start [state]: runtime.md#state