From 99a47ff6006fbc1bd14c4cd8d46fb4eb5babcdff Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Sun, 1 Mar 2015 21:13:33 +0100 Subject: [PATCH] Docs: add restart-policies to 'Run reference' This moves some information on restart-policies from the "command line" page to "run reference". Also fixes some minor typos and adds a "NOTE" about --rm and --restart not allowed to be combined. Also removes inline CSS styles from tables, which will be styled by the stylesheet, and fixes some minor MarkDown errors (`<` -> <) depends on https://github.com/docker/docs-base/pull/1 resolves #11069 Signed-off-by: Sebastiaan van Stijn --- docs/sources/reference/commandline/cli.md | 75 +++++++----- docs/sources/reference/run.md | 132 ++++++++++++++++++---- 2 files changed, 157 insertions(+), 50 deletions(-) diff --git a/docs/sources/reference/commandline/cli.md b/docs/sources/reference/commandline/cli.md index 8ffaa5adc3..da4daec88b 100644 --- a/docs/sources/reference/commandline/cli.md +++ b/docs/sources/reference/commandline/cli.md @@ -1931,41 +1931,56 @@ application change: #### Restart Policies -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. +Use Docker's `--restart` to specify a container's *restart policy*. A restart +policy controls whether the Docker daemon restarts a container after exit. +Docker supports the following restart policies: -An ever increasing delay (double the previous delay, starting at 100 milliseconds) -is added before each restart to prevent flooding the server. This means the daemaon -will wait for 100 mS, then 200 mS, 400, 800, 1600, and so on until either the -`on-failure` limit is hit, or when you `docker stop` or even `docker rm -f` -the container. - -When a restart policy is active on a container, it will be shown in `docker ps` -as either `Up` or `Restarting` in `docker ps`. It can also be useful to use -`docker events` to see the restart policy in effect. - -** no ** - Do not restart the container when it exits. - -** on-failure ** - Restart the container only if it exits with a non zero exit status. - -** always ** - Always restart the container regardless of the exit status. - -You can also 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. + + + + + + + + + + + + + + + + + + + + + +
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. +
$ sudo 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. +This will run the `redis` container with a restart policy of **always** +so that if the container exits, Docker will restart it. - $ sudo 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. +More detailed information on restart policies can be found in the +[Restart Policies (--restart)](/reference/run/#restart-policies-restart) section +of the Docker run reference page. ### Adding entries to a container hosts file diff --git a/docs/sources/reference/run.md b/docs/sources/reference/run.md index 8faf9ad77c..268ade05ee 100644 --- a/docs/sources/reference/run.md +++ b/docs/sources/reference/run.md @@ -52,6 +52,7 @@ following options. - [PID Equivalent](#pid-equivalent) - [IPC Settings](#ipc-settings) - [Network Settings](#network-settings) + - [Restart Policies
(--restart)](#restart-policies-restart) - [Clean Up (--rm)](#clean-up-rm) - [Runtime Constraints on CPU and Memory](#runtime-constraints-on-cpu-and-memory) - [Runtime Privilege, Linux Capabilities, and LXC Configuration](#runtime-privilege-linux-capabilities-and-lxc-configuration) @@ -256,6 +257,99 @@ container itself as well as `localhost` and a few other common things. The ::1 localhost ip6-localhost ip6-loopback 86.75.30.9 db-static +## 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`](/reference/commandline/cli/#ps). It can also be +useful to use [`docker events`](/reference/commandline/cli/#events) 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. +
+ +An ever 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 is hit, or when you `docker stop` +or `docker rm -f` the container. + +If a container is succesfully 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`]( +/reference/commandline/cli/#inspect). For example, to get the number of restarts +for container "my-container"; + + $ sudo docker inspect -f "{{ .RestartCount }}" my-container + # 2 + +Or, to get the last time the container was (re)started; + + $ docker inspect -f "{{ .State.StartedAt }}" my-container + # 2015-03-04T23:47:07.691840179Z + +You cannot set any restart policy in combination with +["clean up (--rm)"](#clean-up-rm). Setting both `--restart` and `--rm` +results in an error. + +###Examples + + $ sudo 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. + + $ sudo 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. + ## Clean up (--rm) By default a container's file system persists even after the container @@ -317,15 +411,15 @@ We have four ways to set memory usage: - memory=inf, memory-swap=inf (not specify any of them) There is no memory limit, you can use as much as you want. - - memory=L - - Variable - Value + + + + - - + - - - + + - - + - - - + + +
VariableValue
HOME + HOME Set based on the value of USER
HOSTNAME +
HOSTNAME The hostname associated with the container
PATH + PATH Includes popular directories, such as :
/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
TERM - xterm if the container is allocated a psuedo-TTY -
TERMxterm if the container is allocated a psuedo-TTY
@@ -619,7 +711,7 @@ container running Redis: # The redis-name container exposed port 6379 $ sudo docker ps - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 4241164edf6f $ dockerfiles/redis:latest /redis-stable/src/re 5 seconds ago Up 4 seconds 6379/tcp redis-name # Note that there are no public ports exposed since we didn᾿t use -p or -P