From 16466f1ce6b6d27592973c5b94bcc06fa4c88e89 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Sat, 21 Aug 2021 13:50:05 +0200 Subject: [PATCH] docs: rewrite reference docs for --stop-signal and --stop-timeout Signed-off-by: Sebastiaan van Stijn --- docs/reference/builder.md | 11 ++++++++--- docs/reference/commandline/create.md | 2 +- docs/reference/commandline/kill.md | 20 +++++++++++++++----- docs/reference/commandline/run.md | 23 +++++++++++++++++------ man/Dockerfile.5.md | 12 ++++++++++++ man/docker-run.1.md | 22 +++++++++++++++++++--- 6 files changed, 72 insertions(+), 18 deletions(-) diff --git a/docs/reference/builder.md b/docs/reference/builder.md index d243535ed2..cae532a019 100644 --- a/docs/reference/builder.md +++ b/docs/reference/builder.md @@ -2173,9 +2173,14 @@ ONBUILD RUN /usr/local/bin/python-build --dir /app/src STOPSIGNAL signal ``` -The `STOPSIGNAL` instruction sets the system call signal that will be sent to the container to exit. -This signal can be a valid unsigned number that matches a position in the kernel's syscall table, for instance 9, -or a signal name in the format SIGNAME, for instance SIGKILL. +The `STOPSIGNAL` instruction sets the system call signal that will be sent to the +container to exit. This signal can be a signal name in the format `SIG`, +for instance `SIGKILL`, or an unsigned number that matches a position in the +kernel's syscall table, for instance `9`. The default is `SIGTERM` if not +defined. + +The image's default stopsignal can be overridden per container, using the +`--stop-signal` flag on `docker run` and `docker create`. ## HEALTHCHECK diff --git a/docs/reference/commandline/create.md b/docs/reference/commandline/create.md index 0c9a96ee26..94381710b6 100644 --- a/docs/reference/commandline/create.md +++ b/docs/reference/commandline/create.md @@ -109,7 +109,7 @@ Options: Unit is optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes), or `g` (gigabytes). If you omit the unit, the system uses bytes. --stop-signal string Signal to stop a container (default "SIGTERM") - --stop-timeout=10 Timeout (in seconds) to stop a container + --stop-timeout int Timeout (in seconds) to stop a container --storage-opt value Storage driver options for the container (default []) --sysctl value Sysctl options (default map[]) --tmpfs value Mount a tmpfs directory (default []) diff --git a/docs/reference/commandline/kill.md b/docs/reference/commandline/kill.md index 942605ec52..4df13e3411 100644 --- a/docs/reference/commandline/kill.md +++ b/docs/reference/commandline/kill.md @@ -20,8 +20,18 @@ Options: The `docker kill` subcommand kills one or more containers. The main process inside the container is sent `SIGKILL` signal (default), or the signal that is -specified with the `--signal` option. You can kill a container using the -container's ID, ID-prefix, or name. +specified with the `--signal` option. You can reference a container by its +ID, ID-prefix, or name. + +The `--signal` (or `-s` shorthand) flag sets the system call signal that is sent +to the container. This signal can be a signal name in the format `SIG`, for +instance `SIGINT`, or an unsigned number that matches a position in the kernel's +syscall table, for instance `2`. + +While the default (`SIGKILL`) signal will terminate the container, the signal +set through `--signal` may be non-terminal, depending on the container's main +process. For example, the `SIGHUP` signal in most cases will be non-terminal, +and the container will continue running after receiving the signal. > **Note** > @@ -32,16 +42,16 @@ container's ID, ID-prefix, or name. ## Examples -### Send a KILL signal to a container +### Send a KILL signal to a container -The following example sends the default `KILL` signal to the container named +The following example sends the default `SIGKILL` signal to the container named `my_container`: ```bash $ docker kill my_container ``` -### Send a custom signal to a container +### Send a custom signal to a container The following example sends a `SIGHUP` signal to the container named `my_container`: diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md index eef81dd81c..28ba5ef8c6 100644 --- a/docs/reference/commandline/run.md +++ b/docs/reference/commandline/run.md @@ -120,7 +120,7 @@ Options: or `g` (gigabytes). If you omit the unit, the system uses bytes. --sig-proxy Proxy received signals to the process (default true) --stop-signal string Signal to stop a container (default "SIGTERM") - --stop-timeout=10 Timeout (in seconds) to stop a container + --stop-timeout int Timeout (in seconds) to stop a container --storage-opt value Storage driver options for the container (default []) --sysctl value Sysctl options (default map[]) --tmpfs value Mount a tmpfs directory (default []) @@ -745,9 +745,12 @@ the three processes quota set for the `daemon` user. ### Stop container with signal (--stop-signal) -The `--stop-signal` flag sets the system call signal that will be sent to the container to exit. -This signal can be a valid unsigned number that matches a position in the kernel's syscall table, for instance 9, -or a signal name in the format SIGNAME, for instance SIGKILL. +The `--stop-signal` flag sets the system call signal that will be sent to the +container to exit. This signal can be a signal name in the format `SIG`, +for instance `SIGKILL`, or an unsigned number that matches a position in the +kernel's syscall table, for instance `9`. + +The default is `SIGTERM` if not specified. ### Optional security options (--security-opt) @@ -756,8 +759,16 @@ The `credentialspec` must be in the format `file://spec.txt` or `registry://keyn ### Stop container with timeout (--stop-timeout) -The `--stop-timeout` flag sets the timeout (in seconds) that a pre-defined (see `--stop-signal`) system call -signal that will be sent to the container to exit. After timeout elapses the container will be killed with SIGKILL. +The `--stop-timeout` flag sets the number of seconds to wait for the container +to stop after sending the pre-defined (see `--stop-signal`) system call signal. +If the container does not exit after the timeout elapses, it is forcibly killed +with a `SIGKILL` signal. + +If `--stop-timeout` is set to `-1`, no timeout is applied, and the daemon will +wait indefinitely for the container to exit. + +The default is determined by the daemon, and is 10 seconds for Linux containers, +and 30 seconds for Windows containers. ### Specify isolation technology for container (--isolation) diff --git a/man/Dockerfile.5.md b/man/Dockerfile.5.md index cb713b2b82..106b094444 100644 --- a/man/Dockerfile.5.md +++ b/man/Dockerfile.5.md @@ -183,6 +183,18 @@ A Dockerfile is similar to a Makefile. To display an image's labels, use the `docker inspect` command. +**STOPSIGNAL** + + -- `STOPSIGNAL ` + The **STOPSIGNAL** instruction sets the system call signal that will be sent + to the container to exit. This signal can be a signal name in the format + **SIG**, for instance **SIGKILL**, or an unsigned number that matches a + position in the kernel's syscall table, for instance **9**. The default is + **SIGTERM** if not defined. + + The image's default stopsignal can be overridden per container, using the + **--stop-signal** flag on **docker-run(1)** and **docker-create(1)**. + **EXPOSE** -- `EXPOSE [...]` The **EXPOSE** instruction informs Docker that the container listens on the diff --git a/man/docker-run.1.md b/man/docker-run.1.md index c36af33031..46ad4f1cef 100644 --- a/man/docker-run.1.md +++ b/man/docker-run.1.md @@ -622,10 +622,26 @@ incompatible with any restart policy other than `none`. Under these conditions, user can pass any size less than the backing fs size. **--stop-signal**=*SIGTERM* - Signal to stop a container. Default is SIGTERM. + Signal to stop the container. Default is SIGTERM. -**--stop-timeout**=*10* - Timeout (in seconds) to stop a container. Default is 10. + The `--stop-signal` flag sets the system call signal that will be sent to the + container to exit. This signal can be a signal name in the format `SIG`, + for instance `SIGKILL`, or an unsigned number that matches a position in the + kernel's syscall table, for instance `9`. + +**--stop-timeout** + Timeout (in seconds) to stop a container, or **-1** to disable timeout. + + The `--stop-timeout` flag sets the number of seconds to wait for the container + to stop after sending the pre-defined (see `--stop-signal`) system call signal. + If the container does not exit after the timeout elapses, it is forcibly killed + with a `SIGKILL` signal. + + If `--stop-timeout` is set to **-1**, no timeout is applied, and the daemon will + wait indefinitely for the container to exit. + + The default is determined by the daemon, and 10 seconds for Linux containers, + and 30 seconds for Windows containers. **--shm-size**="" Size of `/dev/shm`. The format is ``.