diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md index 7a478fdccd..e190bbd528 100644 --- a/docs/reference/commandline/run.md +++ b/docs/reference/commandline/run.md @@ -1009,9 +1009,56 @@ $ docker run --restart=always redis This will run the `redis` container with a restart policy of **always** so that if the container exits, Docker restarts it. -You can find more detailed information on restart policies in the -[Restart Policies (--restart)](../run.md#restart-policies---restart) -section of the Docker run reference page. +When a restart policy is active on a container, it shows as either `Up` or +`Restarting` in [`docker ps`](ps.md). It can also be useful to use [`docker +events`](events.md) to see the restart policy in effect. + +An increasing delay (double the previous delay, starting at 100 milliseconds) +is added before each restart to prevent flooding the server. This means the +daemon waits for 100 ms, then 200 ms, 400, 800, 1600, and so on until either +the `on-failure` limit, the maximum delay of 1 minute is hit, or when you +`docker stop` or `docker rm -f` the container. + +If a container is successfully restarted (the container is started and runs +for at least 10 seconds), the delay is reset to its default value of 100 ms. + +#### Specify a limit for restart attempts + +You can specify the maximum amount of times Docker attempts to restart the +container when using the **on-failure** policy. By default, Docker never stops +attempting to restart the container. + +The following example runs the `redis` container with a restart policy of +**on-failure** and a maximum restart count of 10. + +```console +$ docker run --restart=on-failure:10 redis +``` + +If the `redis` container exits with a non-zero exit status more than 10 times +in a row, Docker stops trying to restart the container. Providing a maximum +restart limit is only valid for the **on-failure** policy. + +#### Inspect container restarts + +The number of (attempted) restarts for a container can be obtained using the +[`docker inspect`](commandline/inspect.md) command. For example, to get the +number of restarts for container "my-container"; + +```console +$ docker inspect -f "{{ .RestartCount }}" my-container +2 +``` + +Or, to get the last time the container was (re)started; + +```console +$ docker inspect -f "{{ .State.StartedAt }}" my-container +2015-03-04T23:47:07.691840179Z +``` + +Combining `--restart` (restart policy) with the `--rm` (clean up) flag results +in an error. On container restart, attached clients are disconnected. ### Add entries to container hosts file (--add-host) diff --git a/docs/reference/run.md b/docs/reference/run.md index a4643ac0c8..c8194dc834 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -189,115 +189,6 @@ round-trip min/avg/max = 0.257/0.288/0.326 ms For more information about container networking, see [Networking overview](https://docs.docker.com/network/) -## Restart policies (--restart) - -Using the `--restart` flag on Docker run you can specify a restart policy for -how a container should or should not be restarted on exit. - -When a restart policy is active on a container, it will be shown as either `Up` -or `Restarting` in [`docker ps`](commandline/ps.md). It can also be -useful to use [`docker events`](commandline/events.md) to see the -restart policy in effect. - -Docker supports the following restart policies: - - - - - - - - - - - - - - - - - - - - - - - - - - -
PolicyResult
no - Do not automatically restart the container when it exits. This is the - default. -
- - on-failure[:max-retries] - - - Restart only if the container exits with a non-zero exit status. - Optionally, limit the number of restart retries the Docker - daemon attempts. -
always - Always restart the container regardless of the exit status. - When you specify always, the Docker daemon will try to restart - the container indefinitely. The container will also always start - on daemon startup, regardless of the current state of the container. -
unless-stopped - Always restart the container regardless of the exit status, - including on daemon startup, except if the container was put - into a stopped state before the Docker daemon was stopped. -
- -An increasing delay (double the previous delay, starting at 100 milliseconds) -is added before each restart to prevent flooding the server. -This means the daemon will wait for 100 ms, then 200 ms, 400, 800, 1600, -and so on until either the `on-failure` limit, the maximum delay of 1 minute is -hit, or when you `docker stop` or `docker rm -f` the container. - -If a container is successfully restarted (the container is started and runs -for at least 10 seconds), the delay is reset to its default value of 100 ms. - -You can specify the maximum amount of times Docker will try to restart the -container when using the **on-failure** policy. The default is that Docker -will try forever to restart the container. The number of (attempted) restarts -for a container can be obtained via [`docker inspect`](commandline/inspect.md). For example, to get the number of restarts -for container "my-container"; - -```console -$ docker inspect -f "{{ .RestartCount }}" my-container -# 2 -``` - -Or, to get the last time the container was (re)started; - -```console -$ docker inspect -f "{{ .State.StartedAt }}" my-container -# 2015-03-04T23:47:07.691840179Z -``` - -Combining `--restart` (restart policy) with the `--rm` (clean up) flag results -in an error. On container restart, attached clients are disconnected. See the -examples on using the [`--rm` (clean up)](#clean-up---rm) flag later in this page. - -### Examples - -```console -$ docker run --restart=always redis -``` - -This will run the `redis` container with a restart policy of **always** -so that if the container exits, Docker will restart it. - -```console -$ docker run --restart=on-failure:10 redis -``` - -This will run the `redis` container with a restart policy of **on-failure** -and a maximum restart count of 10. If the `redis` container exits with a -non-zero exit status more than 10 times in a row Docker will abort trying to -restart the container. Providing a maximum restart limit is only valid for the -**on-failure** policy. - ## Exit Status The exit code from `docker run` gives information about why the container