From 6075303483f632f301e36c9dab3679949948df52 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Thu, 26 Sep 2024 22:41:44 +0200 Subject: [PATCH] docs/reference: stop, restart: add flag descriptions Signed-off-by: Sebastiaan van Stijn --- .../commandline/container_restart.md | 39 ++++++++++++++++-- docs/reference/commandline/container_stop.md | 40 ++++++++++++++++--- 2 files changed, 70 insertions(+), 9 deletions(-) diff --git a/docs/reference/commandline/container_restart.md b/docs/reference/commandline/container_restart.md index 7eb5b033dcfa..804fa072bfba 100644 --- a/docs/reference/commandline/container_restart.md +++ b/docs/reference/commandline/container_restart.md @@ -9,10 +9,10 @@ Restart one or more containers ### Options -| Name | Type | Default | Description | -|:-----------------|:---------|:--------|:---------------------------------------------| -| `-s`, `--signal` | `string` | | Signal to send to the container | -| `-t`, `--time` | `int` | `0` | Seconds to wait before killing the container | +| Name | Type | Default | Description | +|:---------------------------------------|:---------|:--------|:---------------------------------------------| +| [`-s`](#signal), [`--signal`](#signal) | `string` | | Signal to send to the container | +| [`-t`](#time), [`--time`](#time) | `int` | `0` | Seconds to wait before killing the container | @@ -22,3 +22,34 @@ Restart one or more containers ```console $ docker restart my_container ``` + + +### Stop container with signal (-s, --signal) + +The `--signal` flag sends the system call signal 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`. Refer to [signal(7)](https://man7.org/linux/man-pages/man7/signal.7.html) +for available signals. + +The default signal to use is defined by the image's [`StopSignal`](https://github.com/opencontainers/image-spec/blob/v1.1.0/config.md), +which can be set through the [`STOPSIGNAL`](https://docs.docker.com/reference/dockerfile/#stopsignal) +Dockerfile instruction when building the image, or configured using the +[`--stop-signal`](https://docs.docker.com/reference/cli/docker/container/run/#stop-signal) +option when creating the container. If no signal is configured for the +container, `SIGTERM` is used as default. + +### Stop container with timeout (-t, --timeout) + +The `--time` flag sets the number of seconds to wait for the container +to stop after sending the pre-defined (see [`--signal`]{#signal)) system call signal. +If the container does not exit after the timeout elapses, it's forcibly killed +with a `SIGKILL` signal. + +If you set `--time` to `-1`, no timeout is applied, and the daemon +waits indefinitely for the container to exit. + +The default timeout can be specified using the [`--stop-timeout`](https://docs.docker.com/reference/cli/docker/container/run/#stop-timeout) +option when creating the container. If no default is configured for the container, +the Daemon determines the default, and is 10 seconds for Linux containers, and +30 seconds for Windows containers. diff --git a/docs/reference/commandline/container_stop.md b/docs/reference/commandline/container_stop.md index d46148356ba5..78f03253810c 100644 --- a/docs/reference/commandline/container_stop.md +++ b/docs/reference/commandline/container_stop.md @@ -9,10 +9,10 @@ Stop one or more running containers ### Options -| Name | Type | Default | Description | -|:-----------------|:---------|:--------|:---------------------------------------------| -| `-s`, `--signal` | `string` | | Signal to send to the container | -| `-t`, `--time` | `int` | `0` | Seconds to wait before killing the container | +| Name | Type | Default | Description | +|:---------------------------------------|:---------|:--------|:---------------------------------------------| +| [`-s`](#signal), [`--signal`](#signal) | `string` | | Signal to send to the container | +| [`-t`](#time), [`--time`](#time) | `int` | `0` | Seconds to wait before killing the container | @@ -22,10 +22,40 @@ Stop one or more running containers The main process inside the container will receive `SIGTERM`, and after a grace period, `SIGKILL`. The first signal can be changed with the `STOPSIGNAL` instruction in the container's Dockerfile, or the `--stop-signal` option to -`docker run`. +`docker run` and `docker create`. ## Examples ```console $ docker stop my_container ``` + +### Stop container with signal (-s, --signal) + +The `--signal` flag sends the system call signal 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`. Refer to [signal(7)](https://man7.org/linux/man-pages/man7/signal.7.html) +for available signals. + +The default signal to use is defined by the image's [`StopSignal`](https://github.com/opencontainers/image-spec/blob/v1.1.0/config.md), +which can be set through the [`STOPSIGNAL`](https://docs.docker.com/reference/dockerfile/#stopsignal) +Dockerfile instruction when building the image, or configured using the +[`--stop-signal`](https://docs.docker.com/reference/cli/docker/container/run/#stop-signal) +option when creating the container. If no signal is configured for the +container, `SIGTERM` is used as default. + +### Stop container with timeout (-t, --timeout) + +The `--time` flag sets the number of seconds to wait for the container +to stop after sending the pre-defined (see [`--signal`]{#signal)) system call signal. +If the container does not exit after the timeout elapses, it's forcibly killed +with a `SIGKILL` signal. + +If you set `--time` to `-1`, no timeout is applied, and the daemon +waits indefinitely for the container to exit. + +The default timeout can be specified using the [`--stop-timeout`](https://docs.docker.com/reference/cli/docker/container/run/#stop-timeout) +option when creating the container. If no default is configured for the container, +the Daemon determines the default, and is 10 seconds for Linux containers, and +30 seconds for Windows containers.