Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs/reference: stop, restart: add flag descriptions #5484

Merged
merged 1 commit into from
Sep 27, 2024
Merged

docs/reference: stop, restart: add flag descriptions #5484

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 35 additions & 4 deletions docs/reference/commandline/container_restart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |


<!---MARKER_GEN_END-->
Expand All @@ -22,3 +22,34 @@ Restart one or more containers
```console
$ docker restart my_container
```


### <a name="signal"></a> 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<NAME>`, 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.

### <a name="time"></a> 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.
Comment on lines +52 to +55
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TBH; not super happy with these sections; we should probably have a look at better descriptions for these (we have this in some other places as well).

It's a bit complicated to explain these bits

  • container inherits default from image (which can be set through dockerfile)
  • or overridden at runtime (docker create / docker run)
  • or overridden when invoking these commands
  • or otherwise use the daemon default (which can differ per platform)

Some of that could become more transparent if we had better separation between "desired config" and "actual config" (in which case we could make defaults visible in inspect output), but we don't have that.

40 changes: 35 additions & 5 deletions docs/reference/commandline/container_stop.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |


<!---MARKER_GEN_END-->
Expand All @@ -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
```

### <a name="signal"></a> 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<NAME>`, 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.

### <a name="time"></a> 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.
Loading