Skip to content

Commit

Permalink
runtime: Add a 'kill' command
Browse files Browse the repository at this point in the history
Similar to the 'signal' command removed in b922732 (Drop exec, pause,
resume, and signal, 2015-12-02, #3).  The
runtime-spec gained a kill operation as part of
opencontainers/runtime-spec@be594153 (Split create and start,
2016-04-01, opencontainers/runtime-spec#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 we're 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 opencontainers/runtime-spec@35b0e9ee (config:
Clarify MUST for platform.os and .arch, 2016-05-19,
opencontainers/runtime-spec#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
     moby/moby@bc503ca8 (Windows: [TP4] docker kill handling,
     2015-10-12, moby/moby#16997)

Signed-off-by: W. Trevor King <wking@tremily.us>
  • Loading branch information
wking committed Feb 9, 2017
1 parent 09c2033 commit ef6a7da
Showing 1 changed file with 36 additions and 0 deletions.
36 changes: 36 additions & 0 deletions runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,9 +90,45 @@ $ echo $?
0
```

### kill

[Send a signal][kill] to the container process.

* *Arguments*
* *`<ID>`* The container being signaled.
* *Options*
* *`--signal <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 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 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
```

[kill]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc4/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
[semver]: http://semver.org/spec/v2.0.0.html
[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
Expand Down

0 comments on commit ef6a7da

Please sign in to comment.