From cbd07495a3c5b49a47ea288a9e6ee9b24800cace Mon Sep 17 00:00:00 2001 From: Charles Smith Date: Mon, 18 Jul 2016 21:40:07 -0700 Subject: [PATCH] add doc for live-restore setting and daemonless containers, fix admin guide menu Signed-off-by: Charles Smith --- docs/admin/ambassador_pattern_linking.md | 2 +- docs/admin/chef.md | 1 + docs/admin/configuring.md | 293 ----------------------- docs/admin/dsc.md | 1 + docs/admin/formatting.md | 2 +- docs/admin/host_integration.md | 1 + docs/admin/index.md | 286 +++++++++++++++++++++- docs/admin/live-restore.md | 80 +++++++ docs/admin/logging/index.md | 2 +- docs/admin/menu.md | 27 +++ docs/admin/puppet.md | 1 + docs/admin/runmetrics.md | 28 +-- docs/admin/systemd.md | 1 + docs/admin/using_supervisord.md | 1 + docs/reference/commandline/dockerd.md | 15 +- 15 files changed, 418 insertions(+), 323 deletions(-) delete mode 100644 docs/admin/configuring.md create mode 100644 docs/admin/live-restore.md create mode 100644 docs/admin/menu.md diff --git a/docs/admin/ambassador_pattern_linking.md b/docs/admin/ambassador_pattern_linking.md index b5c3041129..772142e258 100644 --- a/docs/admin/ambassador_pattern_linking.md +++ b/docs/admin/ambassador_pattern_linking.md @@ -6,7 +6,7 @@ description = "Using the Ambassador pattern to abstract (network) services" keywords = ["Examples, Usage, links, docker, documentation, examples, names, name, container naming"] [menu.main] parent = "engine_admin" -weight = 6 +weight = 15 +++ diff --git a/docs/admin/chef.md b/docs/admin/chef.md index ba2f680919..523e71782d 100644 --- a/docs/admin/chef.md +++ b/docs/admin/chef.md @@ -6,6 +6,7 @@ description = "Installation and using Docker via Chef" keywords = ["chef, installation, usage, docker, documentation"] [menu.main] parent = "engine_admin" +weight="11" +++ diff --git a/docs/admin/configuring.md b/docs/admin/configuring.md deleted file mode 100644 index b5ad0e04d4..0000000000 --- a/docs/admin/configuring.md +++ /dev/null @@ -1,293 +0,0 @@ - - -# Configuring and running Docker on various distributions - -After successfully installing Docker, the `docker` daemon runs with its default -configuration. - -In a production environment, system administrators typically configure the -`docker` daemon to start and stop according to an organization's requirements. In most -cases, the system administrator configures a process manager such as `SysVinit`, `Upstart`, -or `systemd` to manage the `docker` daemon's start and stop. - -### Running the docker daemon directly - -The `docker` daemon can be run directly using the `dockerd` command. By default it listens on -the Unix socket `unix:///var/run/docker.sock` - - $ dockerd - - INFO[0000] +job init_networkdriver() - INFO[0000] +job serveapi(unix:///var/run/docker.sock) - INFO[0000] Listening for HTTP on unix (/var/run/docker.sock) - ... - ... - -### Configuring the docker daemon directly - -If you're running the `docker` daemon directly by running `docker daemon` instead -of using a process manager, you can append the configuration options to the `docker` run -command directly. Other options can be passed to the `docker` daemon to configure it. - -Some of the daemon's options are: - -| Flag | Description | -|-----------------------|-----------------------------------------------------------| -| `-D`, `--debug=false` | Enable or disable debug mode. By default, this is false. | -| `-H`,`--host=[]` | Daemon socket(s) to connect to. | -| `--tls=false` | Enable or disable TLS. By default, this is false. | - - -Here is an example of running the `docker` daemon with configuration options: - - $ dockerd -D --tls=true --tlscert=/var/docker/server.pem --tlskey=/var/docker/serverkey.pem -H tcp://192.168.59.3:2376 - -These options : - -- Enable `-D` (debug) mode -- Set `tls` to true with the server certificate and key specified using `--tlscert` and `--tlskey` respectively -- Listen for connections on `tcp://192.168.59.3:2376` - -The command line reference has the [complete list of daemon flags](../reference/commandline/dockerd.md) -with explanations. - -### Daemon debugging - -As noted above, setting the log level of the daemon to "debug" or enabling debug mode -with `-D` allows the administrator or operator to gain much more knowledge about the -runtime activity of the daemon. If faced with a non-responsive daemon, the administrator -can force a full stack trace of all threads to be added to the daemon log by sending the -`SIGUSR1` signal to the Docker daemon. A common way to send this signal is using the `kill` -command on Linux systems. For example, `kill -USR1 ` sends the `SIGUSR1` -signal to the daemon process, causing the stack dump to be added to the daemon log. - -> **Note:** The log level setting of the daemon must be at least "info" level and above for -> the stack trace to be saved to the logfile. By default the daemon's log level is set to -> "info". - -The daemon will continue operating after handling the `SIGUSR1` signal and dumping the stack -traces to the log. The stack traces can be used to determine the state of all goroutines and -threads within the daemon. - -## Ubuntu - -As of `14.04`, Ubuntu uses Upstart as a process manager. By default, Upstart jobs -are located in `/etc/init` and the `docker` Upstart job can be found at `/etc/init/docker.conf`. - -After successfully [installing Docker for Ubuntu](../installation/linux/ubuntulinux.md), -you can check the running status using Upstart in this way: - - $ sudo status docker - - docker start/running, process 989 - -### Running Docker - -You can start/stop/restart the `docker` daemon using - - $ sudo start docker - - $ sudo stop docker - - $ sudo restart docker - - -### Configuring Docker - -The instructions below depict configuring Docker on a system that uses `upstart` -as the process manager. As of Ubuntu 15.04, Ubuntu uses `systemd` as its process -manager. For Ubuntu 15.04 and higher, refer to [control and configure Docker with systemd](systemd.md). - -You configure the `docker` daemon in the `/etc/default/docker` file on your -system. You do this by specifying values in a `DOCKER_OPTS` variable. - -To configure Docker options: - -1. Log into your host as a user with `sudo` or `root` privileges. - -2. If you don't have one, create the `/etc/default/docker` file on your host. Depending on how -you installed Docker, you may already have this file. - -3. Open the file with your favorite editor. - - ``` - $ sudo vi /etc/default/docker - ``` - -4. Add a `DOCKER_OPTS` variable with the following options. These options are appended to the -`docker` daemon's run command. - -``` - DOCKER_OPTS="-D --tls=true --tlscert=/var/docker/server.pem --tlskey=/var/docker/serverkey.pem -H tcp://192.168.59.3:2376" -``` - -These options : - -- Enable `-D` (debug) mode -- Set `tls` to true with the server certificate and key specified using `--tlscert` and `--tlskey` respectively -- Listen for connections on `tcp://192.168.59.3:2376` - -The command line reference has the [complete list of daemon flags](../reference/commandline/dockerd.md) -with explanations. - - -5. Save and close the file. - -6. Restart the `docker` daemon. - - ``` - $ sudo restart docker - ``` - -7. Verify that the `docker` daemon is running as specified with the `ps` command. - - ``` - $ ps aux | grep docker | grep -v grep - ``` - -### Logs - -By default logs for Upstart jobs are located in `/var/log/upstart` and the logs for `docker` daemon -can be located at `/var/log/upstart/docker.log` - - $ tail -f /var/log/upstart/docker.log - INFO[0000] Loading containers: done. - INFO[0000] Docker daemon commit=1b09a95-unsupported graphdriver=aufs version=1.11.0-dev - INFO[0000] +job acceptconnections() - INFO[0000] -job acceptconnections() = OK (0) - INFO[0000] Daemon has completed initialization - - -## CentOS / Red Hat Enterprise Linux / Fedora - -As of `7.x`, CentOS and RHEL use `systemd` as the process manager. As of `21`, Fedora uses -`systemd` as its process manager. - -After successfully installing Docker for [CentOS](../installation/linux/centos.md)/[Red Hat Enterprise Linux](../installation/linux/rhel.md)/[Fedora](../installation/linux/fedora.md), you can check the running status in this way: - - $ sudo systemctl status docker - -### Running Docker - -You can start/stop/restart the `docker` daemon using - - $ sudo systemctl start docker - - $ sudo systemctl stop docker - - $ sudo systemctl restart docker - -If you want Docker to start at boot, you should also: - - $ sudo systemctl enable docker - -### Configuring Docker - -For CentOS 7.x and RHEL 7.x you can [control and configure Docker with systemd](systemd.md). - -Previously, for CentOS 6.x and RHEL 6.x you would configure the `docker` daemon in -the `/etc/sysconfig/docker` file on your system. You would do this by specifying -values in a `other_args` variable. For a short time in CentOS 7.x and RHEL 7.x you -would specify values in a `OPTIONS` variable. This is no longer recommended in favor -of using systemd directly. - -For this section, we will use CentOS 7.x as an example to configure the `docker` daemon. - -To configure Docker options: - -1. Log into your host as a user with `sudo` or `root` privileges. - -2. Create the `/etc/systemd/system/docker.service.d` directory. - - ``` - $ sudo mkdir /etc/systemd/system/docker.service.d - ``` - -3. Create a `/etc/systemd/system/docker.service.d/docker.conf` file. - -4. Open the file with your favorite editor. - - ``` - $ sudo vi /etc/systemd/system/docker.service.d/docker.conf - ``` - -5. Override the `ExecStart` configuration from your `docker.service` file to customize -the `docker` daemon. To modify the `ExecStart` configuration you have to specify -an empty configuration followed by a new one as follows: - -``` -[Service] -ExecStart= -ExecStart=/usr/bin/dockerd -H fd:// -D --tls=true --tlscert=/var/docker/server.pem --tlskey=/var/docker/serverkey.pem -H tcp://192.168.59.3:2376 -``` - -These options : - -- Enable `-D` (debug) mode -- Set `tls` to true with the server certificate and key specified using `--tlscert` and `--tlskey` respectively -- Listen for connections on `tcp://192.168.59.3:2376` - -The command line reference has the [complete list of daemon flags](../reference/commandline/dockerd.md) -with explanations. - -6. Save and close the file. - -7. Flush changes. - - ``` - $ sudo systemctl daemon-reload - ``` - -8. Restart the `docker` daemon. - - ``` - $ sudo systemctl restart docker - ``` - -9. Verify that the `docker` daemon is running as specified with the `ps` command. - - ``` - $ ps aux | grep docker | grep -v grep - ``` - -### Logs - -systemd has its own logging system called the journal. The logs for the `docker` daemon can -be viewed using `journalctl -u docker` - - $ sudo journalctl -u docker - May 06 00:22:05 localhost.localdomain systemd[1]: Starting Docker Application Container Engine... - May 06 00:22:05 localhost.localdomain docker[2495]: time="2015-05-06T00:22:05Z" level="info" msg="+job serveapi(unix:///var/run/docker.sock)" - May 06 00:22:05 localhost.localdomain docker[2495]: time="2015-05-06T00:22:05Z" level="info" msg="Listening for HTTP on unix (/var/run/docker.sock)" - May 06 00:22:06 localhost.localdomain docker[2495]: time="2015-05-06T00:22:06Z" level="info" msg="+job init_networkdriver()" - May 06 00:22:06 localhost.localdomain docker[2495]: time="2015-05-06T00:22:06Z" level="info" msg="-job init_networkdriver() = OK (0)" - May 06 00:22:06 localhost.localdomain docker[2495]: time="2015-05-06T00:22:06Z" level="info" msg="Loading containers: start." - May 06 00:22:06 localhost.localdomain docker[2495]: time="2015-05-06T00:22:06Z" level="info" msg="Loading containers: done." - May 06 00:22:06 localhost.localdomain docker[2495]: time="2015-05-06T00:22:06Z" level="info" msg="Docker daemon commit=1b09a95-unsupported graphdriver=aufs version=1.11.0-dev" - May 06 00:22:06 localhost.localdomain docker[2495]: time="2015-05-06T00:22:06Z" level="info" msg="+job acceptconnections()" - May 06 00:22:06 localhost.localdomain docker[2495]: time="2015-05-06T00:22:06Z" level="info" msg="-job acceptconnections() = OK (0)" - -_Note: Using and configuring journal is an advanced topic and is beyond the scope of this article._ - - -### Daemonless Containers - -Starting with Docker 1.12 containers can run without Docker or containerd running. This allows the -Docker daemon to exit, be upgraded, or recover from a crash without affecting running containers -on the system. To enable this functionality you need to add the `--live-restore` flag when -launching `dockerd`. This will ensure that Docker does not kill containers on graceful shutdown or -on restart leaving the containers running. - -While the Docker daemon is down logging will still be captured, however, it will be capped at the kernel's pipe buffer size before the buffer fills up, blocking the process. -Docker will need to be restarted to flush these buffers. -You can modify the kernel's buffer size by changing `/proc/sys/fs/pipe-max-size`. diff --git a/docs/admin/dsc.md b/docs/admin/dsc.md index 84bd1d4f9e..1200211447 100644 --- a/docs/admin/dsc.md +++ b/docs/admin/dsc.md @@ -6,6 +6,7 @@ description = "Using DSC to configure a new Docker host" keywords = ["powershell, dsc, installation, usage, docker, documentation"] [menu.main] parent = "engine_admin" +weight="10" +++ diff --git a/docs/admin/formatting.md b/docs/admin/formatting.md index 4da2671b6f..60f28803aa 100644 --- a/docs/admin/formatting.md +++ b/docs/admin/formatting.md @@ -5,7 +5,7 @@ description = "CLI and log output formatting reference" keywords = ["format, formatting, output, templates, log"] [menu.main] parent = "engine_admin" -weight=-90 +weight=7 +++ diff --git a/docs/admin/host_integration.md b/docs/admin/host_integration.md index f3dde2e251..57de24dd9e 100644 --- a/docs/admin/host_integration.md +++ b/docs/admin/host_integration.md @@ -6,6 +6,7 @@ description = "How to generate scripts for upstart, systemd, etc." keywords = ["systemd, upstart, supervisor, docker, documentation, host integration"] [menu.main] parent = "engine_admin" +weight="5" +++ diff --git a/docs/admin/index.md b/docs/admin/index.md index 0f0ab7d430..5b4017187d 100644 --- a/docs/admin/index.md +++ b/docs/admin/index.md @@ -1,11 +1,283 @@ - + +# Configuring and running Docker on various distributions + +After successfully installing Docker, the `docker` daemon runs with its default +configuration. + +In a production environment, system administrators typically configure the +`docker` daemon to start and stop according to an organization's requirements. In most +cases, the system administrator configures a process manager such as `SysVinit`, `Upstart`, +or `systemd` to manage the `docker` daemon's start and stop. + +### Running the docker daemon directly + +The `docker` daemon can be run directly using the `dockerd` command. By default it listens on +the Unix socket `unix:///var/run/docker.sock` + + $ dockerd + + INFO[0000] +job init_networkdriver() + INFO[0000] +job serveapi(unix:///var/run/docker.sock) + INFO[0000] Listening for HTTP on unix (/var/run/docker.sock) + ... + ... + +### Configuring the docker daemon directly + +If you're running the `docker` daemon directly by running `docker daemon` instead +of using a process manager, you can append the configuration options to the `docker` run +command directly. Other options can be passed to the `docker` daemon to configure it. + +Some of the daemon's options are: + +| Flag | Description | +|-----------------------|-----------------------------------------------------------| +| `-D`, `--debug=false` | Enable or disable debug mode. By default, this is false. | +| `-H`,`--host=[]` | Daemon socket(s) to connect to. | +| `--tls=false` | Enable or disable TLS. By default, this is false. | + + +Here is an example of running the `docker` daemon with configuration options: + + $ dockerd -D --tls=true --tlscert=/var/docker/server.pem --tlskey=/var/docker/serverkey.pem -H tcp://192.168.59.3:2376 + +These options : + +- Enable `-D` (debug) mode +- Set `tls` to true with the server certificate and key specified using `--tlscert` and `--tlskey` respectively +- Listen for connections on `tcp://192.168.59.3:2376` + +The command line reference has the [complete list of daemon flags](../reference/commandline/dockerd.md) +with explanations. + +### Daemon debugging + +As noted above, setting the log level of the daemon to "debug" or enabling debug mode +with `-D` allows the administrator or operator to gain much more knowledge about the +runtime activity of the daemon. If faced with a non-responsive daemon, the administrator +can force a full stack trace of all threads to be added to the daemon log by sending the +`SIGUSR1` signal to the Docker daemon. A common way to send this signal is using the `kill` +command on Linux systems. For example, `kill -USR1 ` sends the `SIGUSR1` +signal to the daemon process, causing the stack dump to be added to the daemon log. + +> **Note:** The log level setting of the daemon must be at least "info" level and above for +> the stack trace to be saved to the logfile. By default the daemon's log level is set to +> "info". + +The daemon will continue operating after handling the `SIGUSR1` signal and dumping the stack +traces to the log. The stack traces can be used to determine the state of all goroutines and +threads within the daemon. + +## Ubuntu + +As of `14.04`, Ubuntu uses Upstart as a process manager. By default, Upstart jobs +are located in `/etc/init` and the `docker` Upstart job can be found at `/etc/init/docker.conf`. + +After successfully [installing Docker for Ubuntu](../installation/linux/ubuntulinux.md), +you can check the running status using Upstart in this way: + + $ sudo status docker + + docker start/running, process 989 + +### Running Docker + +You can start/stop/restart the `docker` daemon using + + $ sudo start docker + + $ sudo stop docker + + $ sudo restart docker + + +### Configuring Docker + +The instructions below depict configuring Docker on a system that uses `upstart` +as the process manager. As of Ubuntu 15.04, Ubuntu uses `systemd` as its process +manager. For Ubuntu 15.04 and higher, refer to [control and configure Docker with systemd](systemd.md). + +You configure the `docker` daemon in the `/etc/default/docker` file on your +system. You do this by specifying values in a `DOCKER_OPTS` variable. + +To configure Docker options: + +1. Log into your host as a user with `sudo` or `root` privileges. + +2. If you don't have one, create the `/etc/default/docker` file on your host. Depending on how +you installed Docker, you may already have this file. + +3. Open the file with your favorite editor. + + ``` + $ sudo vi /etc/default/docker + ``` + +4. Add a `DOCKER_OPTS` variable with the following options. These options are appended to the +`docker` daemon's run command. + +``` + DOCKER_OPTS="-D --tls=true --tlscert=/var/docker/server.pem --tlskey=/var/docker/serverkey.pem -H tcp://192.168.59.3:2376" +``` + +These options : + +- Enable `-D` (debug) mode +- Set `tls` to true with the server certificate and key specified using `--tlscert` and `--tlskey` respectively +- Listen for connections on `tcp://192.168.59.3:2376` + +The command line reference has the [complete list of daemon flags](../reference/commandline/dockerd.md) +with explanations. + + +5. Save and close the file. + +6. Restart the `docker` daemon. + + ``` + $ sudo restart docker + ``` + +7. Verify that the `docker` daemon is running as specified with the `ps` command. + + ``` + $ ps aux | grep docker | grep -v grep + ``` + +### Logs + +By default logs for Upstart jobs are located in `/var/log/upstart` and the logs for `docker` daemon +can be located at `/var/log/upstart/docker.log` + + $ tail -f /var/log/upstart/docker.log + INFO[0000] Loading containers: done. + INFO[0000] Docker daemon commit=1b09a95-unsupported graphdriver=aufs version=1.11.0-dev + INFO[0000] +job acceptconnections() + INFO[0000] -job acceptconnections() = OK (0) + INFO[0000] Daemon has completed initialization + + +## CentOS / Red Hat Enterprise Linux / Fedora + +As of `7.x`, CentOS and RHEL use `systemd` as the process manager. As of `21`, Fedora uses +`systemd` as its process manager. + +After successfully installing Docker for [CentOS](../installation/linux/centos.md)/[Red Hat Enterprise Linux](../installation/linux/rhel.md)/[Fedora](../installation/linux/fedora.md), you can check the running status in this way: + + $ sudo systemctl status docker + +### Running Docker + +You can start/stop/restart the `docker` daemon using + + $ sudo systemctl start docker + + $ sudo systemctl stop docker + + $ sudo systemctl restart docker + +If you want Docker to start at boot, you should also: + + $ sudo systemctl enable docker + +### Configuring Docker + +For CentOS 7.x and RHEL 7.x you can [control and configure Docker with systemd](systemd.md). + +Previously, for CentOS 6.x and RHEL 6.x you would configure the `docker` daemon in +the `/etc/sysconfig/docker` file on your system. You would do this by specifying +values in a `other_args` variable. For a short time in CentOS 7.x and RHEL 7.x you +would specify values in a `OPTIONS` variable. This is no longer recommended in favor +of using systemd directly. + +For this section, we will use CentOS 7.x as an example to configure the `docker` daemon. + +To configure Docker options: + +1. Log into your host as a user with `sudo` or `root` privileges. + +2. Create the `/etc/systemd/system/docker.service.d` directory. + + ``` + $ sudo mkdir /etc/systemd/system/docker.service.d + ``` + +3. Create a `/etc/systemd/system/docker.service.d/docker.conf` file. + +4. Open the file with your favorite editor. + + ``` + $ sudo vi /etc/systemd/system/docker.service.d/docker.conf + ``` + +5. Override the `ExecStart` configuration from your `docker.service` file to customize +the `docker` daemon. To modify the `ExecStart` configuration you have to specify +an empty configuration followed by a new one as follows: + +``` +[Service] +ExecStart= +ExecStart=/usr/bin/dockerd -H fd:// -D --tls=true --tlscert=/var/docker/server.pem --tlskey=/var/docker/serverkey.pem -H tcp://192.168.59.3:2376 +``` + +These options : + +- Enable `-D` (debug) mode +- Set `tls` to true with the server certificate and key specified using `--tlscert` and `--tlskey` respectively +- Listen for connections on `tcp://192.168.59.3:2376` + +The command line reference has the [complete list of daemon flags](../reference/commandline/dockerd.md) +with explanations. + +6. Save and close the file. + +7. Flush changes. + + ``` + $ sudo systemctl daemon-reload + ``` + +8. Restart the `docker` daemon. + + ``` + $ sudo systemctl restart docker + ``` + +9. Verify that the `docker` daemon is running as specified with the `ps` command. + + ``` + $ ps aux | grep docker | grep -v grep + ``` + +### Logs + +systemd has its own logging system called the journal. The logs for the `docker` daemon can +be viewed using `journalctl -u docker` + + $ sudo journalctl -u docker + May 06 00:22:05 localhost.localdomain systemd[1]: Starting Docker Application Container Engine... + May 06 00:22:05 localhost.localdomain docker[2495]: time="2015-05-06T00:22:05Z" level="info" msg="+job serveapi(unix:///var/run/docker.sock)" + May 06 00:22:05 localhost.localdomain docker[2495]: time="2015-05-06T00:22:05Z" level="info" msg="Listening for HTTP on unix (/var/run/docker.sock)" + May 06 00:22:06 localhost.localdomain docker[2495]: time="2015-05-06T00:22:06Z" level="info" msg="+job init_networkdriver()" + May 06 00:22:06 localhost.localdomain docker[2495]: time="2015-05-06T00:22:06Z" level="info" msg="-job init_networkdriver() = OK (0)" + May 06 00:22:06 localhost.localdomain docker[2495]: time="2015-05-06T00:22:06Z" level="info" msg="Loading containers: start." + May 06 00:22:06 localhost.localdomain docker[2495]: time="2015-05-06T00:22:06Z" level="info" msg="Loading containers: done." + May 06 00:22:06 localhost.localdomain docker[2495]: time="2015-05-06T00:22:06Z" level="info" msg="Docker daemon commit=1b09a95-unsupported graphdriver=aufs version=1.11.0-dev" + May 06 00:22:06 localhost.localdomain docker[2495]: time="2015-05-06T00:22:06Z" level="info" msg="+job acceptconnections()" + May 06 00:22:06 localhost.localdomain docker[2495]: time="2015-05-06T00:22:06Z" level="info" msg="-job acceptconnections() = OK (0)" + +_Note: Using and configuring journal is an advanced topic and is beyond the scope of this article._ diff --git a/docs/admin/live-restore.md b/docs/admin/live-restore.md new file mode 100644 index 0000000000..117d804ae8 --- /dev/null +++ b/docs/admin/live-restore.md @@ -0,0 +1,80 @@ + + +# Keep containers alive during daemon downtime + +By default, when the Docker daemon terminates, it shuts down running containers. +Starting with Docker Engine 1.12, you can configure the daemon so that containers remain +running if the daemon becomes unavailable. The live restore option helps reduce +container downtime due to daemon crashes, planned outages, or upgrades. + +## Enable the live restore option + +There are two ways to enable the live restore setting to keep containers alive +when the daemon becomes unavailable: + +* If the daemon is already running and you don't want to stop it, you can add +the configuration to the daemon configuration file. For example, on a linux +system the default configuration file is `/etc/docker/daemon.json`. + +Use your favorite editor to enable the `live-restore` option in the +`daemon.json`. + +```bash +{ +"live-restore": true +} +``` + +You have to send a `SIGHUP` signal to the daemon process for it to reload the +configuration. For more information on how to configure the Docker daemon using +config.json, see [daemon configuration file](../reference/commandline/dockerd.md#daemon-configuration-file) + +* When you start the Docker daemon, pass the `--live-restore` flag: + + ```bash + $ sudo dockerd --live-restore + ``` + +## Live restore during upgrades + +The live restore feature supports restoring containers to the daemon for +upgrades from one minor release to the next. For example from Docker Engine +1.12.1 to 1.13.2. + +If you skip releases during an upgrade, the daemon may not restore connection +the containers. If the daemon is unable restore connection, it ignores the +running containers and you must manage them manually. The daemon won't shut down +the disconnected containers. + +## Live restore upon restart + +The live restore option only works to restore the same set of daemon options +as the daemon had before it stopped. For example, live restore may not work if +the daemon restarts with a different bridge IP or a different graphdriver. + +## Impact of live restore on running containers + +A lengthy absence of the daemon can impact running containers. The containers +process writes to FIFO logs for daemon consumption. If the daemon is unavailable +to consume the output, the buffer will fill up and block further writes to the +log. A full log blocks the process until further space is available. The default +buffer size is typically 64K. + +You must restart Docker to flush the buffers. + +You can modify the kernel's buffer size by changing `/proc/sys/fs/pipe-max-size`. + +## Live restore and swarm mode + +The live restore option is not compatible with Docker Engine swarm mode. When +the Docker Engine runs in swarm mode, the orchestration feature manages tasks +and keeps containers running according to a service specification. diff --git a/docs/admin/logging/index.md b/docs/admin/logging/index.md index 4300565e8f..b47686bf8a 100644 --- a/docs/admin/logging/index.md +++ b/docs/admin/logging/index.md @@ -7,7 +7,7 @@ keywords = [" docker, logging, driver"] [menu.main] parent = "engine_admin" identifier = "smn_logging" -weight=8 +weight=9 +++ diff --git a/docs/admin/menu.md b/docs/admin/menu.md new file mode 100644 index 0000000000..103b67b7e7 --- /dev/null +++ b/docs/admin/menu.md @@ -0,0 +1,27 @@ + + +# Admin Topics + +* [Configuring and running Docker](index.md) +* [Automatically start containers](host_integration.md) +* [Keep containers alive during daemon downtime](live-restore.md) +* [Control and configure Docker with systemd](systemd.md) +* [Format command and log output](formatting.md) +* [Run a local registry mirror](registry_mirror.md) +* [PowerShell DSC Usage](dsc.md) +* [Using Chef](chef.md) +* [Using Puppet](puppet.md) +* [Using Supervisor with Docker](using_supervisord.md) +* [Runtime metrics](runmetrics.md) +* [Link via an ambassador container](ambassador_pattern_linking.md) diff --git a/docs/admin/puppet.md b/docs/admin/puppet.md index d03200f898..dba779b4d8 100644 --- a/docs/admin/puppet.md +++ b/docs/admin/puppet.md @@ -6,6 +6,7 @@ description = "Installing and using Puppet" keywords = ["puppet, installation, usage, docker, documentation"] [menu.main] parent = "engine_admin" +weight="12" +++ diff --git a/docs/admin/runmetrics.md b/docs/admin/runmetrics.md index 8df2e4859b..9abd151ce6 100644 --- a/docs/admin/runmetrics.md +++ b/docs/admin/runmetrics.md @@ -6,7 +6,7 @@ description = "Measure the behavior of running containers" keywords = ["docker, metrics, CPU, memory, disk, IO, run, runtime, stats"] [menu.main] parent = "engine_admin" -weight = 4 +weight = 14 +++ @@ -139,7 +139,7 @@ indicates the number of page faults which happened since the creation of the cgroup; this number can never decrease). - - **cache:** + - **cache:** the amount of memory used by the processes of this control group that can be associated precisely with a block on a block device. When you read from and write to files on disk, this amount will @@ -149,16 +149,16 @@ the cgroup; this number can never decrease). `mmap`). It also accounts for the memory used by `tmpfs` mounts, though the reasons are unclear. - - **rss:** + - **rss:** the amount of memory that *doesn't* correspond to anything on disk: stacks, heaps, and anonymous memory maps. - - **mapped_file:** + - **mapped_file:** indicates the amount of memory mapped by the processes in the control group. It doesn't give you information about *how much* memory is used; it rather tells you *how* it is used. - - **pgfault and pgmajfault:** + - **pgfault and pgmajfault:** indicate the number of times that a process of the cgroup triggered a "page fault" and a "major fault", respectively. A page fault happens when a process accesses a part of its virtual memory space @@ -177,10 +177,10 @@ the cgroup; this number can never decrease). it just has to duplicate an existing page, or allocate an empty page, it's a regular (or "minor") fault. - - **swap:** + - **swap:** the amount of swap currently used by the processes in this cgroup. - - **active_anon and inactive_anon:** + - **active_anon and inactive_anon:** the amount of *anonymous* memory that has been identified has respectively *active* and *inactive* by the kernel. "Anonymous" memory is the memory that is *not* linked to disk pages. In other @@ -195,7 +195,7 @@ the cgroup; this number can never decrease). retagged "active". When the kernel is almost out of memory, and time comes to swap out to disk, the kernel will swap "inactive" pages. - - **active_file and inactive_file:** + - **active_file and inactive_file:** cache memory, with *active* and *inactive* similar to the *anon* memory above. The exact formula is cache = **active_file** + **inactive_file** + **tmpfs**. The exact rules used by the kernel @@ -206,14 +206,14 @@ the cgroup; this number can never decrease). since it can be reclaimed immediately (while anonymous pages and dirty/modified pages have to be written to disk first). - - **unevictable:** + - **unevictable:** the amount of memory that cannot be reclaimed; generally, it will account for memory that has been "locked" with `mlock`. It is often used by crypto frameworks to make sure that secret keys and other sensitive material never gets swapped out to disk. - - **memory and memsw limits:** + - **memory and memsw limits:** These are not really metrics, but a reminder of the limits applied to this cgroup. The first one indicates the maximum amount of physical memory that can be used by the processes of this control @@ -261,21 +261,21 @@ file in the kernel documentation, here is a short list of the most relevant ones: - - **blkio.sectors:** + - **blkio.sectors:** contain the number of 512-bytes sectors read and written by the processes member of the cgroup, device by device. Reads and writes are merged in a single counter. - - **blkio.io_service_bytes:** + - **blkio.io_service_bytes:** indicates the number of bytes read and written by the cgroup. It has 4 counters per device, because for each device, it differentiates between synchronous vs. asynchronous I/O, and reads vs. writes. - - **blkio.io_serviced:** + - **blkio.io_serviced:** the number of I/O operations performed, regardless of their size. It also has 4 counters per device. - - **blkio.io_queued:** + - **blkio.io_queued:** indicates the number of I/O operations currently queued for this cgroup. In other words, if the cgroup isn't doing any I/O, this will be zero. Note that the opposite is not true. In other words, if diff --git a/docs/admin/systemd.md b/docs/admin/systemd.md index 03283cce8d..6d560335d5 100644 --- a/docs/admin/systemd.md +++ b/docs/admin/systemd.md @@ -6,6 +6,7 @@ description = "Controlling and configuring Docker using systemd" keywords = ["docker, daemon, systemd, configuration"] [menu.main] parent = "engine_admin" +weight="7" +++ diff --git a/docs/admin/using_supervisord.md b/docs/admin/using_supervisord.md index 8e52f18197..503bfeaee5 100644 --- a/docs/admin/using_supervisord.md +++ b/docs/admin/using_supervisord.md @@ -6,6 +6,7 @@ description = "How to use Supervisor process management with Docker" keywords = ["docker, supervisor, process management"] [menu.main] parent = "engine_admin" +weight="13" +++ diff --git a/docs/reference/commandline/dockerd.md b/docs/reference/commandline/dockerd.md index 8581ec095f..553fb57c85 100644 --- a/docs/reference/commandline/dockerd.md +++ b/docs/reference/commandline/dockerd.md @@ -56,7 +56,7 @@ Options: --ipv6 Enable IPv6 networking -l, --log-level=info Set the logging level --label=[] Set key=value labels to the daemon - --live-restore Enable live restore of docker when containers are still running + --live-restore Enables keeping containers alive during daemon downtime --log-driver=json-file Default driver for container logs --log-opt=map[] Default log driver options for containers --max-concurrent-downloads=3 Set the max concurrent downloads for each pull @@ -1002,14 +1002,14 @@ via flags. The docker daemon fails to start if an option is duplicated between the file and the flags, regardless their value. We do this to avoid silently ignore changes introduced in configuration reloads. For example, the daemon fails to start if you set daemon labels -in the configuration file and also set daemon labels via the `--label` flag. +in the configuration file and also set daemon labels via the `--label` flag. Options that are not present in the file are ignored when the daemon starts. ### Linux configuration file -The default location of the configuration file on Linux is +The default location of the configuration file on Linux is `/etc/docker/daemon.json`. The `--config-file` flag can be used to specify a - non-default location. + non-default location. This is a full example of the allowed configuration options on Linux: @@ -1024,6 +1024,7 @@ This is a full example of the allowed configuration options on Linux: "storage-driver": "", "storage-opts": [], "labels": [], + "live-restore": true, "log-driver": "", "log-opts": [], "mtu": 0, @@ -1085,7 +1086,7 @@ This is a full example of the allowed configuration options on Linux: The default location of the configuration file on Windows is `%programdata%\docker\config\daemon.json`. The `--config-file` flag can be - used to specify a non-default location. + used to specify a non-default location. This is a full example of the allowed configuration options on Windows: @@ -1099,7 +1100,8 @@ This is a full example of the allowed configuration options on Windows: "storage-driver": "", "storage-opts": [], "labels": [], - "log-driver": "", + "live-restore": true, + "log-driver": "", "mtu": 0, "pidfile": "", "graph": "", @@ -1139,6 +1141,7 @@ The list of currently supported options that can be reconfigured is this: - `cluster-store-opts`: it uses the new options to reload the discovery store. - `cluster-advertise`: it modifies the address advertised after reloading. - `labels`: it replaces the daemon labels with a new set of labels. +- `live-restore`: Enables [keeping containers alive during daemon downtime](../../admin/live-restore.md). - `max-concurrent-downloads`: it updates the max concurrent downloads for each pull. - `max-concurrent-uploads`: it updates the max concurrent uploads for each push. - `default-runtime`: it updates the runtime to be used if not is