From a2ca630175edabdde0010d3bc1017df5078714c6 Mon Sep 17 00:00:00 2001 From: Vincent Demeester Date: Wed, 21 Dec 2016 21:49:28 +0100 Subject: [PATCH 01/38] Merge pull request #29468 from hongbin/volume-plugin-fuxi Add Fuxi Volume Plugin to the docs (cherry picked from commit 13f45768f037d77da50317c338c32512e137c92c) Signed-off-by: Sebastiaan van Stijn --- docs/extend/legacy_plugins.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/extend/legacy_plugins.md b/docs/extend/legacy_plugins.md index 6ac914e366..e9ab6f40be 100644 --- a/docs/extend/legacy_plugins.md +++ b/docs/extend/legacy_plugins.md @@ -65,6 +65,7 @@ Plugin [Convoy plugin](https://github.com/rancher/convoy) | A volume plugin for a variety of storage back-ends including device mapper and NFS. It's a simple standalone executable written in Go and provides the framework to support vendor-specific extensions such as snapshots, backups and restore. [DRBD plugin](https://www.drbd.org/en/supported-projects/docker) | A volume plugin that provides highly available storage replicated by [DRBD](https://www.drbd.org). Data written to the docker volume is replicated in a cluster of DRBD nodes. [Flocker plugin](https://clusterhq.com/docker-plugin/) | A volume plugin that provides multi-host portable volumes for Docker, enabling you to run databases and other stateful containers and move them around across a cluster of machines. +[Fuxi Volume Plugin](https://github.com/openstack/fuxi) | A volume plugin that is developed as part of the OpenStack Kuryr project and implements the Docker volume plugin API by utilizing Cinder, the OpenStack block storage service. [gce-docker plugin](https://github.com/mcuadros/gce-docker) | A volume plugin able to attach, format and mount Google Compute [persistent-disks](https://cloud.google.com/compute/docs/disks/persistent-disks). [GlusterFS plugin](https://github.com/calavera/docker-volume-glusterfs) | A volume plugin that provides multi-host volumes management for Docker using GlusterFS. [Horcrux Volume Plugin](https://github.com/muthu-r/horcrux) | A volume plugin that allows on-demand, version controlled access to your data. Horcrux is an open-source plugin, written in Go, and supports SCP, [Minio](https://www.minio.io) and Amazon S3. From 8051adc7f35cac451844c4094f8b393ac20f5c31 Mon Sep 17 00:00:00 2001 From: Vincent Demeester Date: Mon, 19 Dec 2016 14:48:31 +0100 Subject: [PATCH 02/38] Merge pull request #29541 from tim-zju/spellError spell error: in other parts, they are lower-case (cherry picked from commit 8a41c1d548835afcc5f6021f15e0c885ed99ef7c) Signed-off-by: Sebastiaan van Stijn --- docs/api/v1.18.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api/v1.18.md b/docs/api/v1.18.md index 0db0c0f916..1a4d822189 100644 --- a/docs/api/v1.18.md +++ b/docs/api/v1.18.md @@ -21,8 +21,8 @@ redirect_from: - The daemon listens on `unix:///var/run/docker.sock` but you can [Bind Docker to another host/port or a Unix socket](../reference/commandline/dockerd.md#bind-docker-to-another-host-port-or-a-unix-socket). - The API tends to be REST, but for some complex commands, like `attach` - or `pull`, the HTTP connection is hijacked to transport `STDOUT`, - `STDIN` and `STDERR`. + or `pull`, the HTTP connection is hijacked to transport `stdout`, + `stdin` and `stderr`. ## 2. Endpoints From 114aa22e97d0b0ebc08d422577f1a305dbc6b782 Mon Sep 17 00:00:00 2001 From: Misty Stanley-Jones Date: Fri, 10 Feb 2017 09:25:29 -0800 Subject: [PATCH 03/38] Merge pull request #29559 from mstanleyjones/define_bridge Define bridge networks (cherry picked from commit c621fbce04ec845d5f9254bc59b11dfe06fff0e0) Signed-off-by: Sebastiaan van Stijn --- docs/reference/glossary.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index 0bc39a2023..b04db51e49 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -32,6 +32,28 @@ An image that has no parent is a **base image**. [boot2docker](http://boot2docker.io/) is a lightweight Linux distribution made specifically to run Docker containers. The boot2docker management tool for Mac and Windows was deprecated and replaced by [`docker-machine`](#machine) which you can install with the Docker Toolbox. +## bridge + +In terms of generic networking, a bridge is a Link Layer device which forwards +traffic between network segments. A bridge can be a hardware device or a +software device running within a host machine's kernel. + +In terms of Docker, a bridge network uses a software bridge which allows +containers connected to the same bridge network to communicate, while providing +isolation from containers which are not connected to that bridge network. +The Docker bridge driver automatically installs rules in the host machine so +that containers on different bridge networks cannot communicate directly with +each other. + +The default bridge network, which is also named `bridge`, behaves differently +from user-defined bridge networks. Containers connected to the default `bridge` +network can communicate with each other across the bridge by IP address but +cannot resolve each other's container name to an IP address unless they are +explicitly linked using the `--link` flag to `docker run`. + +For more information about Docker networking, see +[Understand container communication](https://docs.docker.com/engine/userguide/networking/default_network/container-communication/). + ## btrfs btrfs (B-tree file system) is a Linux [filesystem](#filesystem) that Docker From 199cd1e36e02bf15153c05fa9d4b1c90ba5775b6 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Wed, 21 Dec 2016 02:16:28 +0100 Subject: [PATCH 04/38] Merge pull request #29561 from londoncalling/docs-glossary-d4mac-d4win updates to glossary re: d4mac, d4win, toolbox per user request (cherry picked from commit fb41283e493ab5d9c083433cdffdf2fba4019ecb) Signed-off-by: Sebastiaan van Stijn --- docs/reference/glossary.md | 38 ++++++++++++++++++++++++++++++++++---- 1 file changed, 34 insertions(+), 4 deletions(-) diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index b04db51e49..e6b4e59f2f 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -115,6 +115,27 @@ develop, ship, and run applications - The docker daemon process running on the host which manages images and containers +## Docker for Mac + +[Docker for Mac](https://docs.docker.com/docker-for-mac/) is an easy-to-install, +lightweight Docker development environment designed specifically for the Mac. A +native Mac application, Docker for Mac uses the macOS Hypervisor framework, +networking, and filesystem. It's the best solution if you want to build, debug, +test, package, and ship Dockerized applications on a Mac. Docker for Mac +supersedes [Docker Toolbox](#toolbox) as state-of-the-art Docker for macOS. + +## Docker for Windows + +[Docker for Windows](https://docs.docker.com/docker-for-windows/) is an +easy-to-install, lightweight Docker development environment designed +specifically for Windows systems. Docker for Windows uses Microsoft Hyper-V, and +runs as a native Windows app. It works with Windows Server 2016, and gives you +the ability to set up and run Windows containers as well as the standard Linux +containers (with an option to switch between the two). Docker for Windows is the +best solution if you want to build, debug, test, package, and ship Dockerized +applications on Windows machines. It supersedes [Docker Toolbox](#toolbox) as +state-of-the-art Docker on Windows. + ## Docker Hub The [Docker Hub](https://hub.docker.com/) is a centralized resource for working with @@ -286,14 +307,23 @@ containers. ## Toolbox -Docker Toolbox is the installer for Mac and Windows users. +[Docker Toolbox](https://docs.docker.com/toolbox/overview/) is a legacy +installer for Mac and Windows users. It uses Oracle VirtualBox for +virtualization. + +For Macs running OS X El Capitan 10.11 and newer macOS releases, [Docker for +Mac](https://docs.docker.com/docker-for-mac/) is the better solution. + +For Windows 10 systems that support Microsoft Hyper-V (Professional, Enterprise +and Education), [Docker for +Windows](https://docs.docker.com/docker-for-windows/) is the better solution. ## Union file system -Union file systems, or UnionFS, are file systems that operate by creating layers, making them -very lightweight and fast. Docker uses union file systems to provide the building -blocks for containers. +Union file systems, or UnionFS, are file systems that operate by creating +layers, making them very lightweight and fast. Docker uses union file systems to +provide the building blocks for containers. ## virtual machine From 23c03e1146420b09636a49b00e42c72233b5bd1e Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 20 Dec 2016 13:18:57 +0100 Subject: [PATCH 05/38] Merge pull request #29569 from allencloud/update-docs-about-oom-score-adj update docs about --oom-score-adj (cherry picked from commit 0d93970c527b7bbe970655ada658f3c7466d015a) Signed-off-by: Sebastiaan van Stijn --- docs/reference/run.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/run.md b/docs/reference/run.md index 73769ed610..e0b233752f 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -836,7 +836,7 @@ The container has unlimited memory which can cause the host to run out memory and require killing system processes to free memory. The `--oom-score-adj` parameter can be changed to select the priority of which containers will be killed when the system is out of memory, with negative scores making them -less likely to be killed an positive more likely. +less likely to be killed, and positive scores more likely. ### Kernel memory constraints From d383ff9e4ddaef1623ccea0decf13b7cd49d7a49 Mon Sep 17 00:00:00 2001 From: Brian Goff Date: Tue, 20 Dec 2016 09:27:13 -0500 Subject: [PATCH 06/38] Merge pull request #29589 from lixiaobing10051267/masterDockerPs field NAMES ommitted after docker ps in commit.md (cherry picked from commit 9eb9abea6d22e795298871500df061ec7e9644f6) Signed-off-by: Sebastiaan van Stijn --- docs/reference/commandline/commit.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/reference/commandline/commit.md b/docs/reference/commandline/commit.md index 8f971a5d95..e9a8717012 100644 --- a/docs/reference/commandline/commit.md +++ b/docs/reference/commandline/commit.md @@ -49,9 +49,9 @@ created. Supported `Dockerfile` instructions: ## Commit a container $ docker ps - ID IMAGE COMMAND CREATED STATUS PORTS - c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours - 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours + ID IMAGE COMMAND CREATED STATUS PORTS NAMES + c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky + 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours focused_hamilton $ docker commit c3f279d17e0a svendowideit/testimage:version3 f5283438590d $ docker images @@ -62,9 +62,9 @@ created. Supported `Dockerfile` instructions: {% raw %} $ docker ps - ID IMAGE COMMAND CREATED STATUS PORTS - c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours - 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours + ID IMAGE COMMAND CREATED STATUS PORTS NAMES + c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky + 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours focused_hamilton $ docker inspect -f "{{ .Config.Env }}" c3f279d17e0a [HOME=/ PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin] $ docker commit --change "ENV DEBUG true" c3f279d17e0a svendowideit/testimage:version3 @@ -76,9 +76,9 @@ created. Supported `Dockerfile` instructions: ## Commit a container with new `CMD` and `EXPOSE` instructions $ docker ps - ID IMAGE COMMAND CREATED STATUS PORTS - c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours - 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours + ID IMAGE COMMAND CREATED STATUS PORTS NAMES + c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky + 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours focused_hamilton $ docker commit --change='CMD ["apachectl", "-DFOREGROUND"]' -c "EXPOSE 80" c3f279d17e0a svendowideit/testimage:version4 f5283438590d @@ -87,7 +87,7 @@ created. Supported `Dockerfile` instructions: 89373736e2e7f00bc149bd783073ac43d0507da250e999f3f1036e0db60817c0 $ docker ps - ID IMAGE COMMAND CREATED STATUS PORTS - 89373736e2e7 testimage:version4 "apachectl -DFOREGROU" 3 seconds ago Up 2 seconds 80/tcp - c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours - 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours + ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 89373736e2e7 testimage:version4 "apachectl -DFOREGROU" 3 seconds ago Up 2 seconds 80/tcp distracted_fermat + c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky + 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours focused_hamilton From 0e3248ebeb6228ab1dce99cc398ac508821f9b7a Mon Sep 17 00:00:00 2001 From: Vincent Demeester Date: Thu, 22 Dec 2016 15:17:51 +0100 Subject: [PATCH 07/38] Merge pull request #29600 from allencloud/update-docs-about-service-update update service update in docs (cherry picked from commit 524704143b1f27650db9debe22adb9cf1e583930) Signed-off-by: Sebastiaan van Stijn --- docs/api/v1.24.md | 2 +- docs/api/version-history.md | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/api/v1.24.md b/docs/api/v1.24.md index b86a102dc8..a1de53bed2 100644 --- a/docs/api/v1.24.md +++ b/docs/api/v1.24.md @@ -4835,7 +4835,7 @@ Return information on the service `id`. #### Update a service -`POST /services/(id or name)/update` +`POST /services/(id)/update` Update a service. When using this endpoint to create a service using a private repository from the registry, the `X-Registry-Auth` header can be used diff --git a/docs/api/version-history.md b/docs/api/version-history.md index 4363cfbd74..a9cd07c1f1 100644 --- a/docs/api/version-history.md +++ b/docs/api/version-history.md @@ -83,6 +83,7 @@ keywords: "API, Docker, rcli, REST, documentation" * `DELETE /secrets/{id}` removes the secret `id`. * `GET /secrets/{id}` returns information on the secret `id`. * `POST /secrets/{id}/update` updates the secret `id`. +* `POST /services/(id or name)/update` now accepts service name or prefix of service id as a parameter. ## v1.24 API changes From ba82978208ee389cb758a87daec510460bb9d954 Mon Sep 17 00:00:00 2001 From: Vincent Demeester Date: Thu, 22 Dec 2016 15:15:01 +0100 Subject: [PATCH 08/38] Merge pull request #29603 from mstanleyjones/docker_diff_improvements Clarify what docker diff shows (cherry picked from commit 0ca3e84227a04c0c6256f55b92e9205bd1ca9309) Signed-off-by: Sebastiaan van Stijn --- cli/command/container/diff.go | 2 +- docs/reference/commandline/diff.md | 57 ++++++++++++++++++---------- man/docker-diff.1.md | 60 ++++++++++++++++++------------ 3 files changed, 74 insertions(+), 45 deletions(-) diff --git a/cli/command/container/diff.go b/cli/command/container/diff.go index 12d6591014..168af74172 100644 --- a/cli/command/container/diff.go +++ b/cli/command/container/diff.go @@ -21,7 +21,7 @@ func NewDiffCommand(dockerCli *command.DockerCli) *cobra.Command { return &cobra.Command{ Use: "diff CONTAINER", - Short: "Inspect changes on a container's filesystem", + Short: "Inspect changes to files or directories on a container's filesystem", Args: cli.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error { opts.container = args[0] diff --git a/docs/reference/commandline/diff.md b/docs/reference/commandline/diff.md index be27678dcd..085c35d48f 100644 --- a/docs/reference/commandline/diff.md +++ b/docs/reference/commandline/diff.md @@ -13,36 +13,53 @@ keywords: "list, changed, files, container" will be rejected. --> -# diff +## diff ```markdown Usage: docker diff CONTAINER -Inspect changes on a container's filesystem +Inspect changes to files or directories on a container's filesystem Options: --help Print usage ``` -List the changed files and directories in a container᾿s filesystem. - There are 3 events that are listed in the `diff`: +List the changed files and directories in a container᾿s filesystem since the +container was created. Three different types of change are tracked: -1. `A` - Add -2. `D` - Delete -3. `C` - Change +| Symbol | Description | +|--------|---------------------------------| +| `A` | A file or directory was added | +| `D` | A file or directory was deleted | +| `C` | A file or directory was changed | -For example: +You can use the full or shortened container ID or the container name set using +`docker run --name` option. - $ docker diff 7bb0e258aefe +## Examples - C /dev - A /dev/kmsg - C /etc - A /etc/mtab - A /go - A /go/src - A /go/src/github.com - A /go/src/github.com/docker - A /go/src/github.com/docker/docker - A /go/src/github.com/docker/docker/.git - .... +Inspect the changes to an `nginx` container: + +```bash +$ docker diff 1fdfd1f54c1b + +C /dev +C /dev/console +C /dev/core +C /dev/stdout +C /dev/fd +C /dev/ptmx +C /dev/stderr +C /dev/stdin +C /run +A /run/nginx.pid +C /var/lib/nginx/tmp +A /var/lib/nginx/tmp/client_body +A /var/lib/nginx/tmp/fastcgi +A /var/lib/nginx/tmp/proxy +A /var/lib/nginx/tmp/scgi +A /var/lib/nginx/tmp/uwsgi +C /var/log/nginx +A /var/log/nginx/access.log +A /var/log/nginx/error.log +``` diff --git a/man/docker-diff.1.md b/man/docker-diff.1.md index 6c6c502533..3342ad1af5 100644 --- a/man/docker-diff.1.md +++ b/man/docker-diff.1.md @@ -2,7 +2,7 @@ % Docker Community % JUNE 2014 # NAME -docker-diff - Inspect changes on a container's filesystem +docker-diff - Inspect changes to files or directories on a container's filesystem # SYNOPSIS **docker diff** @@ -10,8 +10,16 @@ docker-diff - Inspect changes on a container's filesystem CONTAINER # DESCRIPTION -Inspect changes on a container's filesystem. You can use the full or -shortened container ID or the container name set using +List the changed files and directories in a container᾿s filesystem since the +container was created. Three different types of change are tracked: + +| Symbol | Description | +|--------|---------------------------------| +| `A` | A file or directory was added | +| `D` | A file or directory was deleted | +| `C` | A file or directory was changed | + +You can use the full or shortened container ID or the container name set using **docker run --name** option. # OPTIONS @@ -19,28 +27,32 @@ shortened container ID or the container name set using Print usage statement # EXAMPLES -Inspect the changes to on a nginx container: - # docker diff 1fdfd1f54c1b - C /dev - C /dev/console - C /dev/core - C /dev/stdout - C /dev/fd - C /dev/ptmx - C /dev/stderr - C /dev/stdin - C /run - A /run/nginx.pid - C /var/lib/nginx/tmp - A /var/lib/nginx/tmp/client_body - A /var/lib/nginx/tmp/fastcgi - A /var/lib/nginx/tmp/proxy - A /var/lib/nginx/tmp/scgi - A /var/lib/nginx/tmp/uwsgi - C /var/log/nginx - A /var/log/nginx/access.log - A /var/log/nginx/error.log +Inspect the changes to an `nginx` container: + +```bash +$ docker diff 1fdfd1f54c1b + +C /dev +C /dev/console +C /dev/core +C /dev/stdout +C /dev/fd +C /dev/ptmx +C /dev/stderr +C /dev/stdin +C /run +A /run/nginx.pid +C /var/lib/nginx/tmp +A /var/lib/nginx/tmp/client_body +A /var/lib/nginx/tmp/fastcgi +A /var/lib/nginx/tmp/proxy +A /var/lib/nginx/tmp/scgi +A /var/lib/nginx/tmp/uwsgi +C /var/log/nginx +A /var/log/nginx/access.log +A /var/log/nginx/error.log +``` # HISTORY From 25e8ff2b028085de12c4fa2bb35b89385346a28e Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Thu, 22 Dec 2016 21:50:58 +0100 Subject: [PATCH 09/38] Merge pull request #29615 from londoncalling/docs-glossary-followup-PR#29561 followup to incorporate review comments per previous reviews on PR#29561 (cherry picked from commit b39b0c4596d424cd98856fb633183f30807ad0a2) Signed-off-by: Sebastiaan van Stijn --- docs/reference/glossary.md | 60 ++++++++++++++++++++++++++++++-------- 1 file changed, 48 insertions(+), 12 deletions(-) diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index e6b4e59f2f..f829ad54c0 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -84,6 +84,28 @@ be done to get it running. *Also known as : docker-compose, fig* +## copy-on-write + +Docker uses a +[copy-on-write](https://docs.docker.com/engine/userguide/storagedriver/imagesandcontainers/#/the-copy-on-write-strategy) +technique and a [union file system](#union-file-system) for both images and +containers to optimize resources and speed performance. Multiple copies of an +entity share the same instance and each one makes only specific changes to its +unique layer. + +Multiple containers can share access to the same image, and make +container-specific changes on a writable layer which is deleted when +the container is removed. This speeds up container start times and performance. + +Images are essentially layers of filesystems typically predicated on a base +image under a writable layer, and built up with layers of differences from the +base image. This minimizes the footprint of the image and enables shared +development. + +For more about copy-on-write in the context of Docker, see [Understand images, +containers, and storage +drivers](https://docs.docker.com/engine/userguide/storagedriver/imagesandcontainers/). + ## container A container is a runtime instance of a [docker image](#image). @@ -122,19 +144,21 @@ lightweight Docker development environment designed specifically for the Mac. A native Mac application, Docker for Mac uses the macOS Hypervisor framework, networking, and filesystem. It's the best solution if you want to build, debug, test, package, and ship Dockerized applications on a Mac. Docker for Mac -supersedes [Docker Toolbox](#toolbox) as state-of-the-art Docker for macOS. +supersedes [Docker Toolbox](#toolbox) as state-of-the-art Docker on macOS. + ## Docker for Windows [Docker for Windows](https://docs.docker.com/docker-for-windows/) is an easy-to-install, lightweight Docker development environment designed -specifically for Windows systems. Docker for Windows uses Microsoft Hyper-V, and -runs as a native Windows app. It works with Windows Server 2016, and gives you -the ability to set up and run Windows containers as well as the standard Linux -containers (with an option to switch between the two). Docker for Windows is the -best solution if you want to build, debug, test, package, and ship Dockerized -applications on Windows machines. It supersedes [Docker Toolbox](#toolbox) as -state-of-the-art Docker on Windows. +specifically for Windows 10 systems that support Microsoft Hyper-V +(Professional, Enterprise and Education). Docker for Windows uses Hyper-V for +virtualization, and runs as a native Windows app. It works with Windows Server +2016, and gives you the ability to set up and run Windows containers as well as +the standard Linux containers, with an option to switch between the two. Docker +for Windows is the best solution if you want to build, debug, test, package, and +ship Dockerized applications from Windows machines. Docker for Windows +supersedes [Docker Toolbox](#toolbox) as state-of-the-art Docker on Windows. ## Docker Hub @@ -318,13 +342,25 @@ For Windows 10 systems that support Microsoft Hyper-V (Professional, Enterprise and Education), [Docker for Windows](https://docs.docker.com/docker-for-windows/) is the better solution. - ## Union file system -Union file systems, or UnionFS, are file systems that operate by creating -layers, making them very lightweight and fast. Docker uses union file systems to -provide the building blocks for containers. +Union file systems implement a [union +mount](https://en.wikipedia.org/wiki/Union_mount) and operate by creating +layers. Docker uses union file systems in conjunction with +[copy-on-write](#copy-on-write) techniques to provide the building blocks for +containers, making them very lightweight and fast. +For more on Docker and union file systems, see [Docker and AUFS in +practice](https://docs.docker.com/engine/userguide/storagedriver/aufs-driver/), +[Docker and Btrfs in +practice](https://docs.docker.com/engine/userguide/storagedriver/btrfs-driver/), +and [Docker and OverlayFS in +practice](https://docs.docker.com/engine/userguide/storagedriver/overlayfs-driver/) + +Example implementations of union file systems are +[UnionFS](https://en.wikipedia.org/wiki/UnionFS), +[AUFS](https://en.wikipedia.org/wiki/Aufs), and +[Btrfs](https://btrfs.wiki.kernel.org/index.php/Main_Page). ## virtual machine From db2e6cbc866418526fd7e7b3e69c5d1b639c06d0 Mon Sep 17 00:00:00 2001 From: Akihiro Suda Date: Mon, 26 Dec 2016 10:45:00 +0900 Subject: [PATCH 10/38] Merge pull request #29693 from davidxia/fix-typo Fix typo in docs (cherry picked from commit fb03b56b9b81182ef8561c57e2e7626658dc943b) Signed-off-by: Sebastiaan van Stijn --- docs/api/v1.22.md | 2 +- docs/api/v1.23.md | 2 +- docs/api/v1.24.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/api/v1.22.md b/docs/api/v1.22.md index e94081344c..7d5dfdd294 100644 --- a/docs/api/v1.22.md +++ b/docs/api/v1.22.md @@ -388,7 +388,7 @@ Create a container `"BlkioDeviceWriteBps": [{"Path": "/dev/sda", "Rate": "1024"}]"` - **BlkioDeviceReadIOps** - Limit read rate (IO per second) from a device in the form of: `"BlkioDeviceReadIOps": [{"Path": "device_path", "Rate": rate}]`, for example: `"BlkioDeviceReadIOps": [{"Path": "/dev/sda", "Rate": "1000"}]` - - **BlkioDeviceWiiteIOps** - Limit write rate (IO per second) to a device in the form of: `"BlkioDeviceWriteIOps": [{"Path": "device_path", "Rate": rate}]`, for example: + - **BlkioDeviceWriteIOps** - Limit write rate (IO per second) to a device in the form of: `"BlkioDeviceWriteIOps": [{"Path": "device_path", "Rate": rate}]`, for example: `"BlkioDeviceWriteIOps": [{"Path": "/dev/sda", "Rate": "1000"}]` - **MemorySwappiness** - Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. - **OomKillDisable** - Boolean value, whether to disable OOM Killer for the container or not. diff --git a/docs/api/v1.23.md b/docs/api/v1.23.md index e23811bb95..2c7b2d0d74 100644 --- a/docs/api/v1.23.md +++ b/docs/api/v1.23.md @@ -413,7 +413,7 @@ Create a container `"BlkioDeviceWriteBps": [{"Path": "/dev/sda", "Rate": "1024"}]"` - **BlkioDeviceReadIOps** - Limit read rate (IO per second) from a device in the form of: `"BlkioDeviceReadIOps": [{"Path": "device_path", "Rate": rate}]`, for example: `"BlkioDeviceReadIOps": [{"Path": "/dev/sda", "Rate": "1000"}]` - - **BlkioDeviceWiiteIOps** - Limit write rate (IO per second) to a device in the form of: `"BlkioDeviceWriteIOps": [{"Path": "device_path", "Rate": rate}]`, for example: + - **BlkioDeviceWriteIOps** - Limit write rate (IO per second) to a device in the form of: `"BlkioDeviceWriteIOps": [{"Path": "device_path", "Rate": rate}]`, for example: `"BlkioDeviceWriteIOps": [{"Path": "/dev/sda", "Rate": "1000"}]` - **MemorySwappiness** - Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. - **OomKillDisable** - Boolean value, whether to disable OOM Killer for the container or not. diff --git a/docs/api/v1.24.md b/docs/api/v1.24.md index a1de53bed2..e27fdfdfb9 100644 --- a/docs/api/v1.24.md +++ b/docs/api/v1.24.md @@ -431,7 +431,7 @@ Create a container `"BlkioDeviceWriteBps": [{"Path": "/dev/sda", "Rate": "1024"}]"` - **BlkioDeviceReadIOps** - Limit read rate (IO per second) from a device in the form of: `"BlkioDeviceReadIOps": [{"Path": "device_path", "Rate": rate}]`, for example: `"BlkioDeviceReadIOps": [{"Path": "/dev/sda", "Rate": "1000"}]` - - **BlkioDeviceWiiteIOps** - Limit write rate (IO per second) to a device in the form of: `"BlkioDeviceWriteIOps": [{"Path": "device_path", "Rate": rate}]`, for example: + - **BlkioDeviceWriteIOps** - Limit write rate (IO per second) to a device in the form of: `"BlkioDeviceWriteIOps": [{"Path": "device_path", "Rate": rate}]`, for example: `"BlkioDeviceWriteIOps": [{"Path": "/dev/sda", "Rate": "1000"}]` - **MemorySwappiness** - Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. - **OomKillDisable** - Boolean value, whether to disable OOM Killer for the container or not. From 676b256bf285ef33370a00b01a3ee5cac29ed561 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Wed, 28 Dec 2016 08:05:43 +0100 Subject: [PATCH 11/38] Merge pull request #29696 from zhenghenghuo/branch-two fix some typos (cherry picked from commit 38178cda418ec773e5a272826b676e55b49edb26) Signed-off-by: Sebastiaan van Stijn --- contrib/vagrant-docker/README.md | 2 +- docs/extend/plugins_volume.md | 4 ++-- docs/reference/commandline/dockerd.md | 4 ++-- experimental/vlan-networks.md | 2 +- pkg/locker/README.md | 2 +- 5 files changed, 7 insertions(+), 7 deletions(-) diff --git a/contrib/vagrant-docker/README.md b/contrib/vagrant-docker/README.md index 286a98504a..66e2fa5873 100644 --- a/contrib/vagrant-docker/README.md +++ b/contrib/vagrant-docker/README.md @@ -35,7 +35,7 @@ script end script ``` -Once that's done, you need to set up a SSH tunnel between your host machine and the vagrant machine that's running Docker. This can be done by running the following command in a host terminal: +Once that's done, you need to set up an SSH tunnel between your host machine and the vagrant machine that's running Docker. This can be done by running the following command in a host terminal: ``` ssh -L 2375:localhost:2375 -p 2222 vagrant@localhost diff --git a/docs/extend/plugins_volume.md b/docs/extend/plugins_volume.md index c060bf39b1..0a79efa022 100644 --- a/docs/extend/plugins_volume.md +++ b/docs/extend/plugins_volume.md @@ -169,7 +169,7 @@ Docker needs reminding of the path to the volume on the host. Respond with the path on the host filesystem where the volume has been made available, and/or a string error if an error occurred. `Mountpoint` is optional, -however the plugin may be queried again later if one is not provided. +however, the plugin may be queried again later if one is not provided. ### /VolumeDriver.Unmount @@ -257,7 +257,7 @@ Respond with a string error if an error occurred. `Mountpoint` is optional. ``` Get the list of capabilities the driver supports. -The driver is not required to implement this endpoint, however in such cases +The driver is not required to implement this endpoint, however, in such cases the default values will be taken. **Response**: diff --git a/docs/reference/commandline/dockerd.md b/docs/reference/commandline/dockerd.md index 24ac77611d..8d4423e3a4 100644 --- a/docs/reference/commandline/dockerd.md +++ b/docs/reference/commandline/dockerd.md @@ -237,7 +237,7 @@ drivers: `aufs`, `devicemapper`, `btrfs`, `zfs`, `overlay` and `overlay2`. The `aufs` driver is the oldest, but is based on a Linux kernel patch-set that is unlikely to be merged into the main kernel. These are also known to cause -some serious kernel crashes. However, `aufs` allows containers to share +some serious kernel crashes. However `aufs` allows containers to share executable and shared library memory, so is a useful choice when running thousands of containers with the same program or libraries. @@ -658,7 +658,7 @@ options for `zfs` start with `zfs` and options for `btrfs` start with `btrfs`. Overrides the Linux kernel version check allowing overlay2. Support for specifying multiple lower directories needed by overlay2 was added to the - Linux kernel in 4.0.0. However some older kernel versions may be patched + Linux kernel in 4.0.0. However, some older kernel versions may be patched to add multiple lower directory support for OverlayFS. This option should only be used after verifying this support exists in the kernel. Applying this option on a kernel without this support will cause failures on mount. diff --git a/experimental/vlan-networks.md b/experimental/vlan-networks.md index caec6d6c6b..1eb56e7998 100644 --- a/experimental/vlan-networks.md +++ b/experimental/vlan-networks.md @@ -166,7 +166,7 @@ $ ip route Example: Multi-Subnet Ipvlan L2 Mode starting two containers on the same subnet and pinging one another. In order for the `192.168.114.0/24` to reach `192.168.116.0/24` it requires an external router in L2 mode. L3 mode can route between subnets that share a common `-o parent=`. -Secondary addresses on network routers are common as an address space becomes exhausted to add another secondary to a L3 vlan interface or commonly referred to as a "switched virtual interface" (SVI). +Secondary addresses on network routers are common as an address space becomes exhausted to add another secondary to an L3 vlan interface or commonly referred to as a "switched virtual interface" (SVI). ``` docker network create -d ipvlan \ diff --git a/pkg/locker/README.md b/pkg/locker/README.md index e84a815cc5..98174982ef 100644 --- a/pkg/locker/README.md +++ b/pkg/locker/README.md @@ -4,7 +4,7 @@ Locker locker provides a mechanism for creating finer-grained locking to help free up more global locks to handle other tasks. -The implementation looks close to a sync.Mutex, however the user must provide a +The implementation looks close to a sync.Mutex, however, the user must provide a reference to use to refer to the underlying lock when locking and unlocking, and unlock may generate an error. From a405b95bcfaad61876da836138c6bf6fff008cfa Mon Sep 17 00:00:00 2001 From: Vincent Demeester Date: Tue, 27 Dec 2016 11:26:50 +0100 Subject: [PATCH 12/38] Merge pull request #29699 from yuexiao-wang/update-index Update the index of docker command line (cherry picked from commit af843c53f88c14fc494553a42ef45fb7937f13dc) Signed-off-by: Sebastiaan van Stijn --- docs/reference/commandline/index.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/reference/commandline/index.md b/docs/reference/commandline/index.md index 952fa09df1..87c7b4775f 100644 --- a/docs/reference/commandline/index.md +++ b/docs/reference/commandline/index.md @@ -45,6 +45,7 @@ read the [`dockerd`](dockerd.md) reference page. | [images](images.md) | List images | | [import](import.md) | Import the contents from a tarball to create a filesystem image | | [load](load.md) | Load an image from a tar archive or STDIN | +| [image prune](image_prune.md) | Remove unused images | | [rmi](rmi.md) | Remove one or more images | | [save](save.md) | Save images to a tar archive | | [tag](tag.md) | Tag an image into a repository | @@ -54,6 +55,7 @@ read the [`dockerd`](dockerd.md) reference page. | Command | Description | |:--------|:-------------------------------------------------------------------| | [attach](attach.md) | Attach to a running container | +| [container prune](container_prune.md) | Remove all stopped containers | | [cp](cp.md) | Copy files/folders from a container to a HOSTDIR or to STDOUT | | [create](create.md) | Create a new container | | [diff](diff.md) | Inspect changes on a container's filesystem | @@ -96,9 +98,9 @@ read the [`dockerd`](dockerd.md) reference page. | [network disconnect](network_disconnect.md) | Disconnect a container from a network | | [network inspect](network_inspect.md) | Display information about a network | | [network ls](network_ls.md) | Lists all the networks the Engine `daemon` knows about | +| [network prune](network_prune.md) | Remove all unused networks | | [network rm](network_rm.md) | Removes one or more networks | - ### Shared data volume commands | Command | Description | @@ -109,18 +111,17 @@ read the [`dockerd`](dockerd.md) reference page. | [volume prune](volume_prune.md) | Remove all unused volumes | | [volume rm](volume_rm.md) | Remove one or more volumes | - ### Swarm node commands | Command | Description | |:--------|:-------------------------------------------------------------------| -| [node promote](node_promote.md) | Promote a node that is pending a promotion to manager | | [node demote](node_demote.md) | Demotes an existing manager so that it is no longer a manager | | [node inspect](node_inspect.md) | Inspect a node in the swarm | -| [node update](node_update.md) | Update attributes for a node | -| [node ps](node_ps.md) | List tasks running on one or more nodes | | [node ls](node_ls.md) | List nodes in the swarm | +| [node promote](node_promote.md) | Promote a node that is pending a promotion to manager | +| [node ps](node_ps.md) | List tasks running on one or more nodes | | [node rm](node_rm.md) | Remove one or more nodes from the swarm | +| [node update](node_update.md) | Update attributes for a node | ### Swarm swarm commands @@ -129,8 +130,10 @@ read the [`dockerd`](dockerd.md) reference page. | [swarm init](swarm_init.md) | Initialize a swarm | | [swarm join](swarm_join.md) | Join a swarm as a manager node or worker node | | [swarm leave](swarm_leave.md) | Remove the current node from the swarm | -| [swarm update](swarm_update.md) | Update attributes of a swarm | | [swarm join-token](swarm_join_token.md) | Display or rotate join tokens | +| [swarm unlock](swarm_unlock.md) | Unlock swarm | +| [swarm unlock-key](swarm_unlock_key.md) | Manage the unlock key | +| [swarm update](swarm_update.md) | Update attributes of a swarm | ### Swarm service commands @@ -138,10 +141,11 @@ read the [`dockerd`](dockerd.md) reference page. |:--------|:-------------------------------------------------------------------| | [service create](service_create.md) | Create a new service | | [service inspect](service_inspect.md) | Inspect a service | +| [service logs](service_logs.md) | Fetch the logs of a service | | [service ls](service_ls.md) | List services in the swarm | +| [service ps](service_ps.md) | List the tasks of a service | | [service rm](service_rm.md) | Remove a service from the swarm | | [service scale](service_scale.md) | Set the number of replicas for the desired state of the service | -| [service ps](service_ps.md) | List the tasks of a service | | [service update](service_update.md) | Update the attributes of a service | ### Swarm secret commands From 6458b4e9519033d772f5042c332e510ca3f3dff6 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Wed, 28 Dec 2016 11:46:06 +0100 Subject: [PATCH 13/38] Merge pull request #29744 from yuexiao-wang/update-docker-ps Update the field 'CONTAINER ID' for docker ps (cherry picked from commit 01c62d6e54e49e2c954fb73881ede66ad6fa1b61) Signed-off-by: Sebastiaan van Stijn --- docs/reference/commandline/commit.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/reference/commandline/commit.md b/docs/reference/commandline/commit.md index e9a8717012..9ca3ec5a90 100644 --- a/docs/reference/commandline/commit.md +++ b/docs/reference/commandline/commit.md @@ -49,7 +49,7 @@ created. Supported `Dockerfile` instructions: ## Commit a container $ docker ps - ID IMAGE COMMAND CREATED STATUS PORTS NAMES + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours focused_hamilton $ docker commit c3f279d17e0a svendowideit/testimage:version3 @@ -62,7 +62,7 @@ created. Supported `Dockerfile` instructions: {% raw %} $ docker ps - ID IMAGE COMMAND CREATED STATUS PORTS NAMES + ICONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours focused_hamilton $ docker inspect -f "{{ .Config.Env }}" c3f279d17e0a @@ -76,7 +76,7 @@ created. Supported `Dockerfile` instructions: ## Commit a container with new `CMD` and `EXPOSE` instructions $ docker ps - ID IMAGE COMMAND CREATED STATUS PORTS NAMES + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours focused_hamilton @@ -87,7 +87,7 @@ created. Supported `Dockerfile` instructions: 89373736e2e7f00bc149bd783073ac43d0507da250e999f3f1036e0db60817c0 $ docker ps - ID IMAGE COMMAND CREATED STATUS PORTS NAMES + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 89373736e2e7 testimage:version4 "apachectl -DFOREGROU" 3 seconds ago Up 2 seconds 80/tcp distracted_fermat c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours focused_hamilton From d38979b8bbd2fb2016d700b350cdef7ae203ba26 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Wed, 28 Dec 2016 23:34:17 +0100 Subject: [PATCH 14/38] Merge pull request #29763 from omallo/29729-dostorage-plugin-docs Reference new DigitalOcean plugin (Closes #29729) (cherry picked from commit 841968d55cb332816890b969e3e4c1a04a795562) Signed-off-by: Sebastiaan van Stijn --- docs/extend/legacy_plugins.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/extend/legacy_plugins.md b/docs/extend/legacy_plugins.md index e9ab6f40be..0de2ad0633 100644 --- a/docs/extend/legacy_plugins.md +++ b/docs/extend/legacy_plugins.md @@ -63,6 +63,7 @@ Plugin [Blockbridge plugin](https://github.com/blockbridge/blockbridge-docker-volume) | A volume plugin that provides access to an extensible set of container-based persistent storage options. It supports single and multi-host Docker environments with features that include tenant isolation, automated provisioning, encryption, secure deletion, snapshots and QoS. [Contiv Volume Plugin](https://github.com/contiv/volplugin) | An open source volume plugin that provides multi-tenant, persistent, distributed storage with intent based consumption. It has support for Ceph and NFS. [Convoy plugin](https://github.com/rancher/convoy) | A volume plugin for a variety of storage back-ends including device mapper and NFS. It's a simple standalone executable written in Go and provides the framework to support vendor-specific extensions such as snapshots, backups and restore. +[DigitalOcean Block Storage plugin](https://github.com/omallo/docker-volume-plugin-dostorage) | Integrates DigitalOcean's [block storage solution](https://www.digitalocean.com/products/storage/) into the Docker ecosystem by automatically attaching a given block storage volume to a DigitalOcean droplet and making the contents of the volume available to Docker containers running on that droplet. [DRBD plugin](https://www.drbd.org/en/supported-projects/docker) | A volume plugin that provides highly available storage replicated by [DRBD](https://www.drbd.org). Data written to the docker volume is replicated in a cluster of DRBD nodes. [Flocker plugin](https://clusterhq.com/docker-plugin/) | A volume plugin that provides multi-host portable volumes for Docker, enabling you to run databases and other stateful containers and move them around across a cluster of machines. [Fuxi Volume Plugin](https://github.com/openstack/fuxi) | A volume plugin that is developed as part of the OpenStack Kuryr project and implements the Docker volume plugin API by utilizing Cinder, the OpenStack block storage service. From ff8f643ce19cad2a8899b9b45b8ee9a0f379a2f1 Mon Sep 17 00:00:00 2001 From: Vincent Demeester Date: Fri, 30 Dec 2016 11:15:16 +0100 Subject: [PATCH 15/38] Merge pull request #29774 from miaoyq/complete-plugin-create-docs-content Complete the document content (cherry picked from commit 5374d53322abd6a5b2ebb34b7422abc26d1b5eb3) Signed-off-by: Sebastiaan van Stijn --- docs/reference/commandline/plugin_create.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/reference/commandline/plugin_create.md b/docs/reference/commandline/plugin_create.md index 9d4e99e56a..fa74d31c39 100644 --- a/docs/reference/commandline/plugin_create.md +++ b/docs/reference/commandline/plugin_create.md @@ -41,8 +41,9 @@ $ ls -ls /home/pluginDir $ docker plugin create plugin /home/pluginDir plugin -NAME TAG DESCRIPTION ENABLED -plugin latest A sample plugin for Docker true +$ docker plugin ls +ID NAME TAG DESCRIPTION ENABLED +672d8144ec02 plugin latest A sample plugin for Docker false ``` The plugin can subsequently be enabled for local use or pushed to the public registry. From d9e0ef7cc8436622d182674621386ea4fc7ecea9 Mon Sep 17 00:00:00 2001 From: Alexander Morozov Date: Thu, 26 Jan 2017 10:45:03 -0800 Subject: [PATCH 16/38] Merge pull request #29830 from timthelion/issue29821 Docs: Be more clear when specifying valid formats for strings (cherry picked from commit effc91e7a54a44b50913e1c17a8d173656411847) Signed-off-by: Sebastiaan van Stijn --- docs/reference/commandline/tag.md | 8 ++++---- image/spec/v1.md | 4 ++-- man/docker-tag.1.md | 9 +++++---- 3 files changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/reference/commandline/tag.md b/docs/reference/commandline/tag.md index 983bfe27b2..ebb4c23c10 100644 --- a/docs/reference/commandline/tag.md +++ b/docs/reference/commandline/tag.md @@ -29,13 +29,13 @@ by a registry hostname. The hostname must comply with standard DNS rules, but may not contain underscores. If a hostname is present, it may optionally be followed by a port number in the format `:8080`. If not present, the command uses Docker's public registry located at `registry-1.docker.io` by default. Name -components may contain lowercase characters, digits and separators. A separator +components may contain lowercase letters, digits and separators. A separator is defined as a period, one or two underscores, or one or more dashes. A name component may not start or end with a separator. -A tag name may contain lowercase and uppercase characters, digits, underscores, -periods and dashes. A tag name may not start with a period or a dash and may -contain a maximum of 128 characters. +A tag name must be valid ASCII and may contain lowercase and uppercase letters, +digits, underscores, periods and dashes. A tag name may not start with a +period or a dash and may contain a maximum of 128 characters. You can group your images together using names and tags, and then upload them to [*Share Images via Repositories*](https://docs.docker.com/engine/tutorials/dockerrepos/#/contributing-to-docker-hub). diff --git a/image/spec/v1.md b/image/spec/v1.md index 57a599b8ff..69115549cb 100644 --- a/image/spec/v1.md +++ b/image/spec/v1.md @@ -92,7 +92,7 @@ This specification uses the following terms: often referred to as a tag as well, though it strictly refers to the full name of an image. Acceptable values for a tag suffix are implementation specific, but they SHOULD be limited to the set of - alphanumeric characters [a-zA-z0-9], punctuation + alphanumeric characters [a-zA-Z0-9], punctuation characters [._-], and MUST NOT contain a : character. @@ -105,7 +105,7 @@ This specification uses the following terms: my-app:3.1.4, my-app is the Repository component of the name. Acceptable values for repository name are implementation specific, but they SHOULD be limited to the set of - alphanumeric characters [a-zA-z0-9], and punctuation + alphanumeric characters [a-zA-Z0-9], and punctuation characters [._-], however it MAY contain additional / and : characters for organizational purposes, with the last : character being interpreted diff --git a/man/docker-tag.1.md b/man/docker-tag.1.md index 7f27e1b0e1..2fb5bd3f72 100644 --- a/man/docker-tag.1.md +++ b/man/docker-tag.1.md @@ -24,15 +24,16 @@ entire image name including the optional `TAG` after the ':'. present, it may optionally be followed by a port number in the format `:8080`. If not present, the command uses Docker's public registry located at `registry-1.docker.io` by default. Name components may contain lowercase - characters, digits and separators. A separator is defined as a period, one or + letters, digits and separators. A separator is defined as a period, one or two underscores, or one or more dashes. A name component may not start or end with a separator. **TAG** The tag assigned to the image to version and distinguish images with the same - name. The tag name may contain lowercase and uppercase characters, digits, - underscores, periods and dashes. A tag name may not start with a period or a - dash and may contain a maximum of 128 characters. + name. The tag name must be valid ASCII and may contain lowercase and + uppercase letters, digits, underscores, periods and hyphens. A tag name + may not start with a period or a hyphen and may contain a maximum of 128 + characters. # EXAMPLES From 27fb9af0e6fc8ab63ae4d20aa929d58791c31dac Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Mon, 9 Jan 2017 11:59:56 +0100 Subject: [PATCH 17/38] Merge pull request #29989 from yuexiao-wang/fix-url-alias Fix incorrect alias and URL (cherry picked from commit 03d28f75b878e277073a4db235af3381d3697eec) Signed-off-by: Sebastiaan van Stijn --- man/docker-login.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/man/docker-login.1.md b/man/docker-login.1.md index c0d4f795db..2eee40ef0c 100644 --- a/man/docker-login.1.md +++ b/man/docker-login.1.md @@ -20,7 +20,7 @@ do not specify a `SERVER`, the command uses Docker's public registry located at `docker login` requires user to use `sudo` or be `root`, except when: 1. connecting to a remote daemon, such as a `docker-machine` provisioned `docker engine`. -2. user is added to the `docker` group. This will impact the security of your system; the `docker` group is `root` equivalent. See [Docker Daemon Attack Surface](https://docs.docker.com/engine/articles/security/#docker-daemon-attack-surface) for details. +2. user is added to the `docker` group. This will impact the security of your system; the `docker` group is `root` equivalent. See [Docker Daemon Attack Surface](https://docs.docker.com/engine/security/security/#/docker-daemon-attack-surface) for details. You can log into any public or private repository for which you have credentials. When you log in, the command stores encoded credentials in From 03ed0afa29b549c334044ab836d80c024cc7d2b6 Mon Sep 17 00:00:00 2001 From: Vincent Demeester Date: Mon, 9 Jan 2017 16:48:56 +0100 Subject: [PATCH 18/38] Merge pull request #30000 from ralphtheninja/master Attempts -> MaxAttempts in /services/create (cherry picked from commit 4166801f606b54987fb9a3fda447fc71d3cd0c28) Signed-off-by: Sebastiaan van Stijn --- docs/api/v1.24.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/v1.24.md b/docs/api/v1.24.md index e27fdfdfb9..ca431c1d23 100644 --- a/docs/api/v1.24.md +++ b/docs/api/v1.24.md @@ -4689,7 +4689,7 @@ image](#create-an-image) section for more details. as part of this service. - **Condition** – Condition for restart (`none`, `on-failure`, or `any`). - **Delay** – Delay between restart attempts. - - **Attempts** – Maximum attempts to restart a given container before giving up (default value + - **MaxAttempts** – Maximum attempts to restart a given container before giving up (default value is 0, which is ignored). - **Window** – Windows is the time window used to evaluate the restart policy (default value is 0, which is unbounded). From e688aacaa582d06342d29e71abf5b68dfdaf87df Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 31 Jan 2017 19:20:30 -0800 Subject: [PATCH 19/38] Merge pull request #30011 from davidwilliamson/patch-1 Provide password to volume create command (cherry picked from commit 36db5f6f6895d62a04e509ad958fe3566d5780ba) Signed-off-by: Sebastiaan van Stijn --- docs/extend/index.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/docs/extend/index.md b/docs/extend/index.md index 1410b205e5..0dd672c312 100644 --- a/docs/extend/index.md +++ b/docs/extend/index.md @@ -46,6 +46,8 @@ operation, such as creating a volume. In the following example, you install the `sshfs` plugin, verify that it is enabled, and use it to create a volume. +> **Note**: This example is intended for instructional purposes only. Once the volume is created, your SSH password to the remote host will be exposed as plaintext when inspecting the volume. You should delete the volume as soon as you are done with the example. + 1. Install the `sshfs` plugin. ```bash @@ -75,13 +77,16 @@ enabled, and use it to create a volume. 3. Create a volume using the plugin. This example mounts the `/remote` directory on host `1.2.3.4` into a - volume named `sshvolume`. This volume can now be mounted into containers. + volume named `sshvolume`. + + This volume can now be mounted into containers. ```bash $ docker volume create \ -d vieux/sshfs \ --name sshvolume \ - -o sshcmd=user@1.2.3.4:/remote + -o sshcmd=user@1.2.3.4:/remote \ + -o password=$(cat file_containing_password_for_remote_host) sshvolume ``` @@ -97,11 +102,17 @@ enabled, and use it to create a volume. 5. Start a container that uses the volume `sshvolume`. ```bash - $ docker run -v sshvolume:/data busybox ls /data + $ docker run --rm -v sshvolume:/data busybox ls /data ``` +6. Remove the volume `sshvolume` + ```bash + docker volume rm sshvolume + + sshvolume + ``` To disable a plugin, use the `docker plugin disable` command. To completely remove it, use the `docker plugin remove` command. For other available commands and options, see the From 6e9f3fda7325aee22618d4f3ecb61856eafd1c22 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 17 Jan 2017 14:40:31 +0100 Subject: [PATCH 20/38] Merge pull request #30094 from miaoyq/complete-opt-for-plugin-install Complete the options for 'docker plugin install' (cherry picked from commit 8c7651998fcb41a73480f90aebe3ffadcb020d02) Signed-off-by: Sebastiaan van Stijn --- docs/reference/commandline/plugin_install.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/reference/commandline/plugin_install.md b/docs/reference/commandline/plugin_install.md index 0601193ce0..4cba32cf8b 100644 --- a/docs/reference/commandline/plugin_install.md +++ b/docs/reference/commandline/plugin_install.md @@ -23,6 +23,7 @@ Install a plugin Options: --alias string Local name for plugin --disable Do not enable the plugin on install + --disable-content-trust Skip image verification (default true) --grant-all-permissions Grant all permissions necessary to run the plugin --help Print usage ``` From 8b34bd1980ded6bb95bba408480e94e2c945fae1 Mon Sep 17 00:00:00 2001 From: Vincent Demeester Date: Fri, 13 Jan 2017 16:16:03 +0100 Subject: [PATCH 21/38] Merge pull request #30130 from ijc25/clarify-cp-docs Clarify `cp` documentation behaviour with trailing "/." (cherry picked from commit 8b7ba17d33d6af5fda28e86f2aa357be493f2cb8) Signed-off-by: Sebastiaan van Stijn --- docs/reference/commandline/cp.md | 4 ++-- man/docker-cp.1.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/reference/commandline/cp.md b/docs/reference/commandline/cp.md index fcfd35fce1..e990af6163 100644 --- a/docs/reference/commandline/cp.md +++ b/docs/reference/commandline/cp.md @@ -75,9 +75,9 @@ argument of `DEST_PATH`, the behavior is as follows: - `DEST_PATH` exists and is a file - Error condition: cannot copy a directory to a file - `DEST_PATH` exists and is a directory - - `SRC_PATH` does not end with `/.` + - `SRC_PATH` does not end with `/.` (that is: _slash_ followed by _dot_) - the source directory is copied into this directory - - `SRC_PATH` does end with `/.` + - `SRC_PATH` does end with `/.` (that is: _slash_ followed by _dot_) - the *content* of the source directory is copied into this directory diff --git a/man/docker-cp.1.md b/man/docker-cp.1.md index 949d60bb8b..41d3c3412e 100644 --- a/man/docker-cp.1.md +++ b/man/docker-cp.1.md @@ -59,9 +59,9 @@ argument of `DEST_PATH`, the behavior is as follows: - `DEST_PATH` exists and is a file - Error condition: cannot copy a directory to a file - `DEST_PATH` exists and is a directory - - `SRC_PATH` does not end with `/.` + - `SRC_PATH` does not end with `/.` (that is: _slash_ followed by _dot_) - the source directory is copied into this directory - - `SRC_PATH` does end with `/.` + - `SRC_PATH` does end with `/.` (that is: _slash_ followed by _dot_) - the *content* of the source directory is copied into this directory From 48ea08613f92bf222ef112abab23aac06b8efa40 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 24 Jan 2017 11:46:44 +0100 Subject: [PATCH 22/38] Merge pull request #30387 from coolljt0725/fix_typo typo: fix typo in api documents (cherry picked from commit de1a403810e16aa5d069ea8ca5e407aa447594f9) Signed-off-by: Sebastiaan van Stijn --- docs/api/v1.22.md | 2 +- docs/api/v1.23.md | 2 +- docs/api/v1.24.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/api/v1.22.md b/docs/api/v1.22.md index 7d5dfdd294..f3c111f264 100644 --- a/docs/api/v1.22.md +++ b/docs/api/v1.22.md @@ -1108,7 +1108,7 @@ Update resource configs of one or more containers. "Memory": 314572800, "MemorySwap": 514288000, "MemoryReservation": 209715200, - "KernelMemory": 52428800, + "KernelMemory": 52428800 } **Example response**: diff --git a/docs/api/v1.23.md b/docs/api/v1.23.md index 2c7b2d0d74..f70bbd5313 100644 --- a/docs/api/v1.23.md +++ b/docs/api/v1.23.md @@ -1143,7 +1143,7 @@ Update configuration of one or more containers. "RestartPolicy": { "MaximumRetryCount": 4, "Name": "on-failure" - }, + } } **Example response**: diff --git a/docs/api/v1.24.md b/docs/api/v1.24.md index ca431c1d23..44ebc25cd5 100644 --- a/docs/api/v1.24.md +++ b/docs/api/v1.24.md @@ -1170,7 +1170,7 @@ Update configuration of one or more containers. "RestartPolicy": { "MaximumRetryCount": 4, "Name": "on-failure" - }, + } } **Example response**: From 137b05e9f56da200556dbcd428221250be6d30e9 Mon Sep 17 00:00:00 2001 From: Misty Stanley-Jones Date: Tue, 7 Feb 2017 09:28:30 -0800 Subject: [PATCH 23/38] Merge pull request #30523 from nathanleclaire/document_init Document --init flag for docker run (cherry picked from commit e0cc664cc34959b301849378f3e98146b079fc5e) Signed-off-by: Sebastiaan van Stijn --- docs/reference/run.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/reference/run.md b/docs/reference/run.md index e0b233752f..1cc41c0194 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -667,7 +667,18 @@ It also causes any seccomp filters to be applied later, after privileges have be which may mean you can have a more restrictive set of filters. For more details, see the [kernel documentation](https://www.kernel.org/doc/Documentation/prctl/no_new_privs.txt). -## Specifying custom cgroups +## Specify an init process + +You can use the `--init` flag to indicate that an init process should be used as +the PID 1 in the container. Specifying an init process ensures the usual +responsibilities of an init system, such as reaping zombie processes, are +performed inside the created container. + +The default init process used is the first `docker-init` executable found in the +system path of the Docker daemon process. This `docker-init` binary, included in +the default installation, is backed by [tini](https://github.com/krallin/tini). + +## Specify custom cgroups Using the `--cgroup-parent` flag, you can pass a specific cgroup to run a container in. This allows you to create and manage cgroups on their own. You can From 492f2ab8fe6ba1dae45f93ac13e9ab7580a9edeb Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 14 Feb 2017 15:27:04 -0800 Subject: [PATCH 24/38] Merge pull request #30524 from mstanleyjones/30149_update_plugin_apidocs Update plugin_volume apidocs for v2 (cherry picked from commit 3dc87714d1bfcaf0620fabec3bfea89620b59337) Signed-off-by: Sebastiaan van Stijn --- docs/extend/plugins_volume.md | 252 ++++++++++++++++++++++------------ 1 file changed, 168 insertions(+), 84 deletions(-) diff --git a/docs/extend/plugins_volume.md b/docs/extend/plugins_volume.md index 0a79efa022..807ab5a486 100644 --- a/docs/extend/plugins_volume.md +++ b/docs/extend/plugins_volume.md @@ -16,67 +16,86 @@ keywords: "Examples, Usage, volume, docker, data, volumes, plugin, api" # Write a volume plugin Docker Engine volume plugins enable Engine deployments to be integrated with -external storage systems, such as Amazon EBS, and enable data volumes to persist -beyond the lifetime of a single Engine host. See the +external storage systems such as Amazon EBS, and enable data volumes to persist +beyond the lifetime of a single Docker host. See the [plugin documentation](legacy_plugins.md) for more information. ## Changelog ### 1.13.0 -- If used as part of the v2 plugin architecture, mountpoints that are part of paths returned by plugin have to be mounted under the directory specified by PropagatedMount in the plugin configuration [#26398](https://github.com/docker/docker/pull/26398) +- If used as part of the v2 plugin architecture, mountpoints that are part of + paths returned by the plugin must be mounted under the directory specified by + `PropagatedMount` in the plugin configuration + ([#26398](https://github.com/docker/docker/pull/26398)) ### 1.12.0 -- Add `Status` field to `VolumeDriver.Get` response ([#21006](https://github.com/docker/docker/pull/21006#)) -- Add `VolumeDriver.Capabilities` to get capabilities of the volume driver([#22077](https://github.com/docker/docker/pull/22077)) +- Add `Status` field to `VolumeDriver.Get` response + ([#21006](https://github.com/docker/docker/pull/21006#)) +- Add `VolumeDriver.Capabilities` to get capabilities of the volume driver + ([#22077](https://github.com/docker/docker/pull/22077)) ### 1.10.0 -- Add `VolumeDriver.Get` which gets the details about the volume ([#16534](https://github.com/docker/docker/pull/16534)) -- Add `VolumeDriver.List` which lists all volumes owned by the driver ([#16534](https://github.com/docker/docker/pull/16534)) +- Add `VolumeDriver.Get` which gets the details about the volume + ([#16534](https://github.com/docker/docker/pull/16534)) +- Add `VolumeDriver.List` which lists all volumes owned by the driver + ([#16534](https://github.com/docker/docker/pull/16534)) ### 1.8.0 -- Initial support for volume driver plugins ([#14659](https://github.com/docker/docker/pull/14659)) +- Initial support for volume driver plugins + ([#14659](https://github.com/docker/docker/pull/14659)) ## Command-line changes -A volume plugin makes use of the `-v`and `--volume-driver` flag on the `docker run` command. The `-v` flag accepts a volume name and the `--volume-driver` flag a driver type, for example: +To give a container access to a volume, use the `--volume` and `--volume-driver` +flags on the `docker container run` command. The `--volume` (or `-v`) flag +accepts a volume name and path on the host, and the `--volume-driver` flag +accepts a driver type. - $ docker run -ti -v volumename:/data --volume-driver=flocker busybox sh +```bash +$ docker volume create --driver=flocker volumename -This command passes the `volumename` through to the volume plugin as a -user-given name for the volume. The `volumename` must not begin with a `/`. +$ docker container run -it --volume volumename:/data busybox sh +``` -By having the user specify a `volumename`, a plugin can associate the volume -with an external volume beyond the lifetime of a single container or container -host. This can be used, for example, to move a stateful container from one -server to another. +### `--volume` -By specifying a `volumedriver` in conjunction with a `volumename`, users can use plugins such as [Flocker](https://clusterhq.com/docker-plugin/) to manage volumes external to a single host, such as those on EBS. +The `--volume` (or `-v`) flag takes a value that is in the format +`:`. The two parts of the value are +separated by a colon (`:`) character. +- The volume name is a human-readable name for the volume, and cannot begin with + a `/` character. It is referred to as `volume_name` in the rest of this topic. +- The `Mountpoint` is the path on the host (v1) or in the plugin (v2) where the + volume has been made available. + +### `volumedriver` + +Specifying a `volumedriver` in conjunction with a `volumename` allows you to +use plugins such as [Flocker](https://github.com/ScatterHQ/flocker) to manage +volumes external to a single host, such as those on EBS. ## Create a VolumeDriver The container creation endpoint (`/containers/create`) accepts a `VolumeDriver` -field of type `string` allowing to specify the name of the driver. It's default -value of `"local"` (the default driver for local volumes). +field of type `string` allowing to specify the name of the driver. If not +specified, it defaults to `"local"` (the default driver for local volumes). ## Volume plugin protocol -If a plugin registers itself as a `VolumeDriver` when activated, then it is -expected to provide writeable paths on the host filesystem for the Docker -daemon to provide to containers to consume. - -The Docker daemon handles bind-mounting the provided paths into user -containers. +If a plugin registers itself as a `VolumeDriver` when activated, it must +provide the Docker Daemon with writeable paths on the host filesystem. The Docker +daemon provides these paths to containers to consume. The Docker daemon makes +the volumes available by bind-mounting the provided paths into the containers. > **Note**: Volume plugins should *not* write data to the `/var/lib/docker/` > directory, including `/var/lib/docker/volumes`. The `/var/lib/docker/` > directory is reserved for Docker. -### /VolumeDriver.Create +### `/VolumeDriver.Create` **Request**: ```json @@ -87,9 +106,9 @@ containers. ``` Instruct the plugin that the user wants to create a volume, given a user -specified volume name. The plugin does not need to actually manifest the -volume on the filesystem yet (until Mount is called). -Opts is a map of driver specific options passed through from the user request. +specified volume name. The plugin does not need to actually manifest the +volume on the filesystem yet (until `Mount` is called). +`Opts` is a map of driver specific options passed through from the user request. **Response**: ```json @@ -100,7 +119,7 @@ Opts is a map of driver specific options passed through from the user request. Respond with a string error if an error occurred. -### /VolumeDriver.Remove +### `/VolumeDriver.Remove` **Request**: ```json @@ -109,7 +128,8 @@ Respond with a string error if an error occurred. } ``` -Delete the specified volume from disk. This request is issued when a user invokes `docker rm -v` to remove volumes associated with a container. +Delete the specified volume from disk. This request is issued when a user +invokes `docker rm -v` to remove volumes associated with a container. **Response**: ```json @@ -120,7 +140,7 @@ Delete the specified volume from disk. This request is issued when a user invoke Respond with a string error if an error occurred. -### /VolumeDriver.Mount +### `/VolumeDriver.Mount` **Request**: ```json @@ -131,47 +151,76 @@ Respond with a string error if an error occurred. ``` Docker requires the plugin to provide a volume, given a user specified volume -name. This is called once per container start. If the same volume_name is requested +name. `Mount` is called once per container start. If the same `volume_name` is requested more than once, the plugin may need to keep track of each new mount request and provision at the first mount request and deprovision at the last corresponding unmount request. `ID` is a unique ID for the caller that is requesting the mount. **Response**: -```json -{ - "Mountpoint": "/path/to/directory/on/host", - "Err": "" -} -``` -Respond with the path on the host filesystem where the volume has been made -available, and/or a string error if an error occurred. +- **v1**: -### /VolumeDriver.Path + ```json + { + "Mountpoint": "/path/to/directory/on/host", + "Err": "" + } + ``` + +- **v2**: + + ```json + { + "Mountpoint": "/path/under/PropagatedMount", + "Err": "" + } + ``` + +`Mountpoint` is the path on the host (v1) or in the plugin (v2) where the volume +has been made available. + +`Err` is either empty or contains an error string. + +### `/VolumeDriver.Path` **Request**: + ```json { "Name": "volume_name" } ``` -Docker needs reminding of the path to the volume on the host. +Request the path to the volume with the given `volume_name`. **Response**: -```json -{ - "Mountpoint": "/path/to/directory/on/host", - "Err": "" -} -``` -Respond with the path on the host filesystem where the volume has been made -available, and/or a string error if an error occurred. `Mountpoint` is optional, -however, the plugin may be queried again later if one is not provided. +- **v1**: -### /VolumeDriver.Unmount + ```json + { + "Mountpoin": "/path/to/directory/on/host", + "Err": "" + } + ``` + +- **v2**: + + ```json + { + "Mountpoint": "/path/under/PropagatedMount", + "Err": "" + } + ``` + +Respond with the path on the host (v1) or inside the plugin (v2) where the +volume has been made available, and/or a string error if an error occurred. + +`Mountpoint` is optional. However, the plugin may be queried again later if one +is not provided. + +### `/VolumeDriver.Unmount` **Request**: ```json @@ -181,8 +230,8 @@ however, the plugin may be queried again later if one is not provided. } ``` -Indication that Docker no longer is using the named volume. This is called once -per container stop. Plugin may deduce that it is safe to deprovision it at +Docker is no longer using the named volume. `Unmount` is called once per +container stop. Plugin may deduce that it is safe to deprovision the volume at this point. `ID` is a unique ID for the caller that is requesting the mount. @@ -197,7 +246,7 @@ this point. Respond with a string error if an error occurred. -### /VolumeDriver.Get +### `/VolumeDriver.Get` **Request**: ```json @@ -206,20 +255,36 @@ Respond with a string error if an error occurred. } ``` -Get the volume info. +Get info about `volume_name`. **Response**: -```json -{ - "Volume": { - "Name": "volume_name", - "Mountpoint": "/path/to/directory/on/host", - "Status": {} - }, - "Err": "" -} -``` + +- **v1**: + + ```json + { + "Volume": { + "Name": "volume_name", + "Mountpoint": "/path/to/directory/on/host", + "Status": {} + }, + "Err": "" + } + ``` + +- **v2**: + + ```json + { + "Volume": { + "Name": "volume_name", + "Mountpoint": "/path/under/PropagatedMount", + "Status": {} + }, + "Err": "" + } + ``` Respond with a string error if an error occurred. `Mountpoint` and `Status` are optional. @@ -235,17 +300,35 @@ optional. Get the list of volumes registered with the plugin. **Response**: -```json -{ - "Volumes": [ - { - "Name": "volume_name", - "Mountpoint": "/path/to/directory/on/host" - } - ], - "Err": "" -} -``` + +- **v1**: + + ```json + { + "Volumes": [ + { + "Name": "volume_name", + "Mountpoint": "/path/to/directory/on/host" + } + ], + "Err": "" + } + ``` + +- **v2**: + + ```json + { + "Volumes": [ + { + "Name": "volume_name", + "Mountpoint": "/path/under/PropagatedMount" + } + ], + "Err": "" + } + ``` + Respond with a string error if an error occurred. `Mountpoint` is optional. @@ -257,8 +340,9 @@ Respond with a string error if an error occurred. `Mountpoint` is optional. ``` Get the list of capabilities the driver supports. -The driver is not required to implement this endpoint, however, in such cases -the default values will be taken. + +The driver is not required to implement `Capabilities`. If it is not +implemented, the default values are used. **Response**: ```json @@ -270,7 +354,7 @@ the default values will be taken. ``` Supported scopes are `global` and `local`. Any other value in `Scope` will be -ignored and assumed to be `local`. Scope allows cluster managers to handle the -volume differently, for instance with a scope of `global`, the cluster manager -knows it only needs to create the volume once instead of on every engine. More -capabilities may be added in the future. +ignored, and `local` is used. `Scope` allows cluster managers to handle the +volume in different ways. For instance, a scope of `global`, signals to the +cluster manager that it only needs to create the volume once instead of on each +Docker host. More capabilities may be added in the future. From 84f026ba7e3608b8d3b22560b3694e630a7e1381 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Fri, 3 Feb 2017 19:48:06 -0800 Subject: [PATCH 25/38] Merge pull request #30553 from lewisdaly/21050-improve-user-namespace-docs Updated dockerd docs with note about user namespaces (cherry picked from commit d6b1b532a1e12c4969772519cb2643b285d1318f) Signed-off-by: Sebastiaan van Stijn --- docs/reference/commandline/dockerd.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/reference/commandline/dockerd.md b/docs/reference/commandline/dockerd.md index 8d4423e3a4..1af070c777 100644 --- a/docs/reference/commandline/dockerd.md +++ b/docs/reference/commandline/dockerd.md @@ -994,6 +994,19 @@ with user namespaces enabled or not. If the daemon is configured with user namespaces, the Security Options entry in the response will list "userns" as one of the enabled security features. +#### Behavior differences when user namespaces are enabled + +When you start the Docker daemon with `--userns-remap`, Docker segregates the graph directory +where the images are stored by adding an extra directory with a name corresponding to the +remapped UID and GID. For example, if the remapped UID and GID begin with `165536`, all +images and containers running with that remap setting are located in `/var/lib/docker/165536.165536` +instead of `/var/lib/docker/`. + +In addition, the files and directories within the new directory, which correspond to +images and container layers, are also owned by the new UID and GID. To set the ownership +correctly, you need to re-pull the images and restart the containers after starting the +daemon with `--userns-remap`. + ### Detailed information on `subuid`/`subgid` ranges Given potential advanced use of the subordinate ID ranges by power users, the From 56da5fa29b260d97de83bb855873a897211f5243 Mon Sep 17 00:00:00 2001 From: Vincent Demeester Date: Wed, 1 Feb 2017 09:50:11 +0100 Subject: [PATCH 26/38] Merge pull request #30619 from johndmulhausen/patch-3 Fix for 404 in docs (cherry picked from commit 1de72681b598003eb186011237639bbfc4f67318) Signed-off-by: Sebastiaan van Stijn --- docs/reference/builder.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/reference/builder.md b/docs/reference/builder.md index 6fa5a24150..7cb690c02a 100644 --- a/docs/reference/builder.md +++ b/docs/reference/builder.md @@ -2,6 +2,8 @@ title: "Dockerfile reference" description: "Dockerfiles use a simple DSL which allows you to automate the steps you would normally manually take to create an image." keywords: "builder, docker, Dockerfile, automation, image creation" +redirect_from: +- /reference/builder/ --- -# Use the Docker command line +# docker To list available commands, either run `docker` with no parameters or execute `docker help`: @@ -43,6 +43,8 @@ Commands: # […] ``` +## Description + Depending on your Docker system configuration, you may be required to preface each `docker` command with `sudo`. To avoid having to use `sudo` with the `docker` command, your system administrator can create a Unix group called @@ -51,7 +53,7 @@ each `docker` command with `sudo`. To avoid having to use `sudo` with the For more information about installing Docker or `sudo` configuration, refer to the [installation](https://docs.docker.com/engine/installation/) instructions for your operating system. -## Environment variables +### Environment variables For easy reference, the following list of environment variables are supported by the `docker` command line: @@ -69,7 +71,7 @@ by the `docker` command line: Equates to `--disable-content-trust=false` for build, create, pull, push, run. * `DOCKER_CONTENT_TRUST_SERVER` The URL of the Notary server to use. This defaults to the same URL as the registry. -* `DOCKER_HIDE_LEGACY_COMMANDS` When set, Docker hides "legacy" top-level commands (such as `docker rm`, and +* `DOCKER_HIDE_LEGACY_COMMANDS` When set, Docker hides "legacy" top-level commands (such as `docker rm`, and `docker pull`) in `docker help` output, and only `Management commands` per object-type (e.g., `docker container`) are printed. This may become the default in a future release, at which point this environment-variable is removed. * `DOCKER_TMPDIR` Location for temporary Docker files. @@ -85,7 +87,7 @@ These Go environment variables are case-insensitive. See the [Go specification](http://golang.org/pkg/net/http/) for details on these variables. -## Configuration files +### Configuration files By default, the Docker command line stores its configuration files in a directory called `.docker` within your `$HOME` directory. However, you can @@ -165,18 +167,25 @@ attach`, `docker exec`, `docker run` or `docker start` command. Following is a sample `config.json` file: - {% raw %} - { - "HttpHeaders": { - "MyHeader": "MyValue" - }, - "psFormat": "table {{.ID}}\\t{{.Image}}\\t{{.Command}}\\t{{.Labels}}", - "imagesFormat": "table {{.ID}}\\t{{.Repository}}\\t{{.Tag}}\\t{{.CreatedAt}}", - "statsFormat": "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}", - "serviceInspectFormat": "pretty", - "detachKeys": "ctrl-e,e" - } - {% endraw %} +```json +{% raw %} +{ + "HttpHeaders": { + "MyHeader": "MyValue" + }, + "psFormat": "table {{.ID}}\\t{{.Image}}\\t{{.Command}}\\t{{.Labels}}", + "imagesFormat": "table {{.ID}}\\t{{.Repository}}\\t{{.Tag}}\\t{{.CreatedAt}}", + "statsFormat": "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}", + "serviceInspectFormat": "pretty", + "detachKeys": "ctrl-e,e", + "credsStore": "secretservice", + "credHelpers": { + "awesomereg.example.org": "hip-star", + "unicorn.example.com": "vcbait" + } +} +{% endraw %} +``` ### Notary @@ -187,7 +196,9 @@ Certificate Authority, you need to place the certificate at Alternatively you can trust the certificate globally by adding it to your system's list of root Certificate Authorities. -## Help +## Examples + +### Display help text To list the help on any command just execute the command, followed by the `--help` option. @@ -203,13 +214,13 @@ To list the help on any command just execute the command, followed by the -a, --attach value Attach to STDIN, STDOUT or STDERR (default []) ... -## Option types +### Option types Single character command line options can be combined, so rather than typing `docker run -i -t --name test busybox sh`, you can write `docker run -it --name test busybox sh`. -### Boolean +#### Boolean Boolean options take the form `-d=false`. The value you see in the help text is the default value which is set if you do **not** specify that flag. If you @@ -222,27 +233,33 @@ container **will** run in "detached" mode, in the background. Options which default to `true` (e.g., `docker build --rm=true`) can only be set to the non-default value by explicitly setting them to `false`: - $ docker build --rm=false . +```bash +$ docker build --rm=false . +``` -### Multi +#### Multi You can specify options like `-a=[]` multiple times in a single command line, for example in these commands: - $ docker run -a stdin -a stdout -i -t ubuntu /bin/bash - $ docker run -a stdin -a stdout -a stderr ubuntu /bin/ls +```bash +$ docker run -a stdin -a stdout -i -t ubuntu /bin/bash + +$ docker run -a stdin -a stdout -a stderr ubuntu /bin/ls +``` Sometimes, multiple options can call for a more complex value string as for `-v`: - $ docker run -v /host:/container example/mysql +```bash +$ docker run -v /host:/container example/mysql +``` -> **Note:** -> Do not use the `-t` and `-a stderr` options together due to +> **Note**: Do not use the `-t` and `-a stderr` options together due to > limitations in the `pty` implementation. All `stderr` in `pty` mode > simply goes to `stdout`. -### Strings and Integers +#### Strings and Integers Options like `--name=""` expect a string, and they can only be specified once. Options like `-c=0` diff --git a/docs/reference/commandline/commit.md b/docs/reference/commandline/commit.md index 9ca3ec5a90..fcf7559199 100644 --- a/docs/reference/commandline/commit.md +++ b/docs/reference/commandline/commit.md @@ -28,6 +28,8 @@ Options: -p, --pause Pause container during commit (default true) ``` +## Description + It can be useful to commit a container's file changes or settings into a new image. This allows you debug a container by running an interactive shell, or to export a working dataset to another server. Generally, it is better to use @@ -46,48 +48,72 @@ The `--change` option will apply `Dockerfile` instructions to the image that is created. Supported `Dockerfile` instructions: `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`LABEL`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` -## Commit a container +## Examples - $ docker ps - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky - 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours focused_hamilton - $ docker commit c3f279d17e0a svendowideit/testimage:version3 - f5283438590d - $ docker images - REPOSITORY TAG ID CREATED SIZE - svendowideit/testimage version3 f5283438590d 16 seconds ago 335.7 MB +### Commit a container -## Commit a container with new configurations +```bash +$ docker ps - {% raw %} - $ docker ps - ICONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky - 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours focused_hamilton - $ docker inspect -f "{{ .Config.Env }}" c3f279d17e0a - [HOME=/ PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin] - $ docker commit --change "ENV DEBUG true" c3f279d17e0a svendowideit/testimage:version3 - f5283438590d - $ docker inspect -f "{{ .Config.Env }}" f5283438590d - [HOME=/ PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin DEBUG=true] - {% endraw %} +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky +197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours focused_hamilton -## Commit a container with new `CMD` and `EXPOSE` instructions +$ docker commit c3f279d17e0a svendowideit/testimage:version3 - $ docker ps - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky - 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours focused_hamilton +f5283438590d - $ docker commit --change='CMD ["apachectl", "-DFOREGROUND"]' -c "EXPOSE 80" c3f279d17e0a svendowideit/testimage:version4 - f5283438590d +$ docker images - $ docker run -d svendowideit/testimage:version4 - 89373736e2e7f00bc149bd783073ac43d0507da250e999f3f1036e0db60817c0 +REPOSITORY TAG ID CREATED SIZE +svendowideit/testimage version3 f5283438590d 16 seconds ago 335.7 MB +``` - $ docker ps - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 89373736e2e7 testimage:version4 "apachectl -DFOREGROU" 3 seconds ago Up 2 seconds 80/tcp distracted_fermat - c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky - 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours focused_hamilton +### Commit a container with new configurations + +```bash +{% raw %} +$ docker ps + +ICONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky +197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours focused_hamilton + +$ docker inspect -f "{{ .Config.Env }}" c3f279d17e0a + +[HOME=/ PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin] + +$ docker commit --change "ENV DEBUG true" c3f279d17e0a svendowideit/testimage:version3 + +f5283438590d + +$ docker inspect -f "{{ .Config.Env }}" f5283438590d + +[HOME=/ PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin DEBUG=true] +{% endraw %} +``` + +### Commit a container with new `CMD` and `EXPOSE` instructions + +```bash +$ docker ps + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky +197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours focused_hamilton + +$ docker commit --change='CMD ["apachectl", "-DFOREGROUND"]' -c "EXPOSE 80" c3f279d17e0a svendowideit/testimage:version4 + +f5283438590d + +$ docker run -d svendowideit/testimage:version4 + +89373736e2e7f00bc149bd783073ac43d0507da250e999f3f1036e0db60817c0 + +$ docker ps + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +89373736e2e7 testimage:version4 "apachectl -DFOREGROU" 3 seconds ago Up 2 seconds 80/tcp distracted_fermat +c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky +197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours focused_hamilton +``` diff --git a/docs/reference/commandline/container_prune.md b/docs/reference/commandline/container_prune.md index 43156406ec..345186b0d7 100644 --- a/docs/reference/commandline/container_prune.md +++ b/docs/reference/commandline/container_prune.md @@ -25,8 +25,14 @@ Options: --help Print usage ``` +## Description + +Removes all stopped containers. + ## Examples +### Prune containers + ```bash $ docker container prune WARNING! This will remove all stopped containers. @@ -38,7 +44,76 @@ f98f9c2aa1eaf727e4ec9c0283bc7d4aa4762fbdba7f26191f26c97f64090360 Total reclaimed space: 212 B ``` -## Related information +### Filtering + +The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more +than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) + +The currently supported filters are: + +* until (``) - only remove containers created before given timestamp + +The `until` filter can be Unix timestamps, date formatted +timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed +relative to the daemon machine’s time. Supported formats for date +formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, +`2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local +timezone on the daemon will be used if you do not provide either a `Z` or a +`+-00:00` timezone offset at the end of the timestamp. When providing Unix +timestamps enter seconds[.nanoseconds], where seconds is the number of seconds +that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap +seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a +fraction of a second no more than nine digits long. + +The following removes containers created more than 5 minutes ago: + +```bash +{% raw %} +$ docker ps -a --format 'table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.CreatedAt}}\t{{.Status}}' + +CONTAINER ID IMAGE COMMAND CREATED AT STATUS +61b9efa71024 busybox "sh" 2017-01-04 13:23:33 -0800 PST Exited (0) 41 seconds ago +53a9bc23a516 busybox "sh" 2017-01-04 13:11:59 -0800 PST Exited (0) 12 minutes ago + +$ docker container prune --force --filter "until=5m" + +Deleted Containers: +53a9bc23a5168b6caa2bfbefddf1b30f93c7ad57f3dec271fd32707497cb9369 + +Total reclaimed space: 25 B + +$ docker ps -a --format 'table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.CreatedAt}}\t{{.Status}}' + +CONTAINER ID IMAGE COMMAND CREATED AT STATUS +61b9efa71024 busybox "sh" 2017-01-04 13:23:33 -0800 PST Exited (0) 44 seconds ago +{% endraw %} +``` + +The following removes containers created before `2017-01-04T13:10:00`: + +```bash +{% raw %} +$ docker ps -a --format 'table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.CreatedAt}}\t{{.Status}}' + +CONTAINER ID IMAGE COMMAND CREATED AT STATUS +53a9bc23a516 busybox "sh" 2017-01-04 13:11:59 -0800 PST Exited (0) 7 minutes ago +4a75091a6d61 busybox "sh" 2017-01-04 13:09:53 -0800 PST Exited (0) 9 minutes ago + +$ docker container prune --force --filter "until=2017-01-04T13:10:00" + +Deleted Containers: +4a75091a6d618526fcd8b33ccd6e5928ca2a64415466f768a6180004b0c72c6c + +Total reclaimed space: 27 B + +$ docker ps -a --format 'table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.CreatedAt}}\t{{.Status}}' + +CONTAINER ID IMAGE COMMAND CREATED AT STATUS +53a9bc23a516 busybox "sh" 2017-01-04 13:11:59 -0800 PST Exited (0) 9 minutes ago +{% endraw %} +``` + +## Related commands * [system df](system_df.md) * [volume prune](volume_prune.md) diff --git a/docs/reference/commandline/cp.md b/docs/reference/commandline/cp.md index e990af6163..5cbbee25ae 100644 --- a/docs/reference/commandline/cp.md +++ b/docs/reference/commandline/cp.md @@ -31,6 +31,8 @@ Options: --help Print usage ``` +## Description + The `docker cp` utility copies the contents of `SRC_PATH` to the `DEST_PATH`. You can copy from the container's file system to the local machine or the reverse, from the local filesystem to the container. If `-` is specified for @@ -96,15 +98,16 @@ you must be explicit with a relative or absolute path, for example: It is not possible to copy certain system files such as resources under `/proc`, `/sys`, `/dev`, [tmpfs](run.md#mount-tmpfs-tmpfs), and mounts created by the user in the container. However, you can still copy such files by manually -running `tar` in `docker exec`. For example (consider `SRC_PATH` and `DEST_PATH` -are directories): +running `tar` in `docker exec`. Both of the following examples do the same thing +in different ways (consider `SRC_PATH` and `DEST_PATH` are directories): - $ docker exec foo tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | tar Cxf DEST_PATH - - -or - - $ tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | docker exec -i foo tar Cxf DEST_PATH - +```bash +$ docker exec foo tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | tar Cxf DEST_PATH - +``` +```bash +$ tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | docker exec -i foo tar Cxf DEST_PATH - +``` Using `-` as the `SRC_PATH` streams the contents of `STDIN` as a tar archive. The command extracts the content of the tar to the `DEST_PATH` in container's diff --git a/docs/reference/commandline/create.md b/docs/reference/commandline/create.md index e6582e4a38..00de1dc32b 100644 --- a/docs/reference/commandline/create.md +++ b/docs/reference/commandline/create.md @@ -132,6 +132,7 @@ Options: --volumes-from value Mount volumes from the specified container(s) (default []) -w, --workdir string Working directory inside the container ``` +## Description The `docker create` command creates a writeable container layer over the specified image and prepares it for running the specified command. The @@ -147,42 +148,64 @@ Please see the [run command](run.md) section and the [Docker run reference](../r ## Examples - $ docker create -t -i fedora bash - 6d8af538ec541dd581ebc2a24153a28329acb5268abe5ef868c1f1a261221752 - $ docker start -a -i 6d8af538ec5 - bash-4.2# +### Create and start a container + +```bash +$ docker create -t -i fedora bash + +6d8af538ec541dd581ebc2a24153a28329acb5268abe5ef868c1f1a261221752 + +$ docker start -a -i 6d8af538ec5 + +bash-4.2# +``` + +### Initialize volumes As of v1.4.0 container volumes are initialized during the `docker create` phase (i.e., `docker run` too). For example, this allows you to `create` the `data` volume container, and then use it from another container: - $ docker create -v /data --name data ubuntu - 240633dfbb98128fa77473d3d9018f6123b99c454b3251427ae190a7d951ad57 - $ docker run --rm --volumes-from data ubuntu ls -la /data - total 8 - drwxr-xr-x 2 root root 4096 Dec 5 04:10 . - drwxr-xr-x 48 root root 4096 Dec 5 04:11 .. +```bash +$ docker create -v /data --name data ubuntu + +240633dfbb98128fa77473d3d9018f6123b99c454b3251427ae190a7d951ad57 + +$ docker run --rm --volumes-from data ubuntu ls -la /data + +total 8 +drwxr-xr-x 2 root root 4096 Dec 5 04:10 . +drwxr-xr-x 48 root root 4096 Dec 5 04:11 .. +``` Similarly, `create` a host directory bind mounted volume container, which can then be used from the subsequent container: - $ docker create -v /home/docker:/docker --name docker ubuntu - 9aa88c08f319cd1e4515c3c46b0de7cc9aa75e878357b1e96f91e2c773029f03 - $ docker run --rm --volumes-from docker ubuntu ls -la /docker - total 20 - drwxr-sr-x 5 1000 staff 180 Dec 5 04:00 . - drwxr-xr-x 48 root root 4096 Dec 5 04:13 .. - -rw-rw-r-- 1 1000 staff 3833 Dec 5 04:01 .ash_history - -rw-r--r-- 1 1000 staff 446 Nov 28 11:51 .ashrc - -rw-r--r-- 1 1000 staff 25 Dec 5 04:00 .gitconfig - drwxr-sr-x 3 1000 staff 60 Dec 1 03:28 .local - -rw-r--r-- 1 1000 staff 920 Nov 28 11:51 .profile - drwx--S--- 2 1000 staff 460 Dec 5 00:51 .ssh - drwxr-xr-x 32 1000 staff 1140 Dec 5 04:01 docker +```bash +$ docker create -v /home/docker:/docker --name docker ubuntu + +9aa88c08f319cd1e4515c3c46b0de7cc9aa75e878357b1e96f91e2c773029f03 + +$ docker run --rm --volumes-from docker ubuntu ls -la /docker + +total 20 +drwxr-sr-x 5 1000 staff 180 Dec 5 04:00 . +drwxr-xr-x 48 root root 4096 Dec 5 04:13 .. +-rw-rw-r-- 1 1000 staff 3833 Dec 5 04:01 .ash_history +-rw-r--r-- 1 1000 staff 446 Nov 28 11:51 .ashrc +-rw-r--r-- 1 1000 staff 25 Dec 5 04:00 .gitconfig +drwxr-sr-x 3 1000 staff 60 Dec 1 03:28 .local +-rw-r--r-- 1 1000 staff 920 Nov 28 11:51 .profile +drwx--S--- 2 1000 staff 460 Dec 5 00:51 .ssh +drwxr-xr-x 32 1000 staff 1140 Dec 5 04:01 docker +``` + Set storage driver options per container. - $ docker create -it --storage-opt size=120G fedora /bin/bash +```bash +$ docker create -it --storage-opt size=120G fedora /bin/bash +``` This (size) will allow to set the container rootfs size to 120G at creation time. This option is only available for the `devicemapper`, `btrfs`, `overlay2`, diff --git a/docs/reference/commandline/deploy.md b/docs/reference/commandline/deploy.md index 53074b2fd4..a430a90105 100644 --- a/docs/reference/commandline/deploy.md +++ b/docs/reference/commandline/deploy.md @@ -14,7 +14,9 @@ advisory: "experimental" will be rejected. --> -# deploy (alias for stack deploy) (experimental) +# deploy (experimental) + +An alias for `stack deploy`. ```markdown Usage: docker deploy [OPTIONS] STACK @@ -31,15 +33,20 @@ Options: --with-registry-auth Send registry authentication details to Swarm agents ``` +## Description + Create and update a stack from a `compose` or a `dab` file on the swarm. This command has to be run targeting a manager node. -## Compose file +## Examples + +### Compose file The `deploy` command supports compose file version `3.0` and above. ```bash $ docker stack deploy --compose-file docker-compose.yml vossibility + Ignoring unsupported options: links Creating network vossibility_vossibility @@ -54,8 +61,9 @@ Creating service vossibility_lookupd You can verify that the services were correctly created -``` +```bash $ docker service ls + ID NAME MODE REPLICAS IMAGE 29bv0vnlm903 vossibility_lookupd replicated 1/1 nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662 4awt47624qwh vossibility_nsqd replicated 1/1 nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662 @@ -65,10 +73,11 @@ ID NAME MODE REPLICAS IMAGE axqh55ipl40h vossibility_vossibility-collector replicated 1/1 icecrime/vossibility-collector@sha256:f03f2977203ba6253988c18d04061c5ec7aab46bca9dfd89a9a1fa4500989fba ``` -## DAB file +### DAB file ```bash $ docker stack deploy --bundle-file vossibility-stack.dab vossibility + Loading bundle from vossibility-stack.dab Creating service vossibility_elasticsearch Creating service vossibility_kibana @@ -82,6 +91,7 @@ You can verify that the services were correctly created: ```bash $ docker service ls + ID NAME MODE REPLICAS IMAGE 29bv0vnlm903 vossibility_lookupd replicated 1/1 nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662 4awt47624qwh vossibility_nsqd replicated 1/1 nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662 @@ -91,7 +101,7 @@ ID NAME MODE REPLICAS IMAGE axqh55ipl40h vossibility_vossibility-collector replicated 1/1 icecrime/vossibility-collector@sha256:f03f2977203ba6253988c18d04061c5ec7aab46bca9dfd89a9a1fa4500989fba ``` -## Related information +## Related commands * [stack config](stack_config.md) * [stack deploy](stack_deploy.md) diff --git a/docs/reference/commandline/diff.md b/docs/reference/commandline/diff.md index 085c35d48f..e6e12cef80 100644 --- a/docs/reference/commandline/diff.md +++ b/docs/reference/commandline/diff.md @@ -13,7 +13,7 @@ keywords: "list, changed, files, container" will be rejected. --> -## diff +# diff ```markdown Usage: docker diff CONTAINER @@ -24,6 +24,8 @@ Options: --help Print usage ``` +## Description + List the changed files and directories in a container᾿s filesystem since the container was created. Three different types of change are tracked: diff --git a/docs/reference/commandline/docker_images.gif b/docs/reference/commandline/docker_images.gif deleted file mode 100644 index 5894ca270e002758b8f332141e00356e42868880..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 35785 zcmd3tS6CBW*sj+UAPFD|HS{DP9Sl`K#LzngL_|~wh=>J0Kv6{0(5o7H5isItu^ai_j`|%i=(+kus7_0yaNA47>mV; zii%50N=ZvgDgGCEGFeScO+{N+4I~zJ0sDe?UNh-Oink491>4dt5?8J@)TEc<>-SB4TS))R7}c z0#5#yKqfOd`M>PV%*@Kl3O{@HU~X<+Ufw^&#nBi3%dyJJnwpvuwY8_3nwp!NnU^mo zUHLC*U0uDsy_wgqpX=`*930FU9?l;hpO}~^zIX4!ga2}IX6DJ0Csj|M*3QpAfByX4 zyLXpAd{|yy{`>du|2*{nFBkF;6bpbi(EIO({u>h@vdW|Ct&fR;w$@>qcrXN0&a7xY`c7GB^N@v$7r*be2ujX3j+*UQ5MKnGzH`-P`a-L+DspQgL zGnS{dwQ1K_d+kIKblEGe4Lvr5kv=tL^y+OUu+{sPO3R{P3jf$h&{<^j`b)jGH8?>Uq8E^YhU>-JrYIyO&?{s@*Pn_VvWv z_lWH>Csg%*|HL26QuVrV{m1f~v5S%Y)nhTK7CHdXxe$t5S$_BI-p!k_Hdo!P=s$)1P1V~&Y2{vtmfPxsbkVUvk#Wq3)V zblS@z#%UJ_atYsYPfC=^u`fQ`zwwmz6AA*M20sQ|*mJPFTPjiA=v9PmEZ&PE&>0@3;FcQ8sU0l3ENxQ{Cq1 zaEfgMXRxW=ufe|AwB>E3q;9&P>GJiT0rTrL*vz-B!w1XF7kw0(XM$6gn=kP)Y5&OIDE7?Z1{U%Lq8-P{eJ$w=le*56bfS^m>{D7G4J^t zpKF~q-0t7;hmi^bB z(Fds=Qkkvv%5_?0W%J_abw0*CPgTTnId)vCt+;eRAo-Q!Z&5YKkh}TZoH8W}05v+W zOtGW#lB6~O?oqyi9?b^8dOLr8=r%47pYa~_oEI?$IsL$Tr}-cxP&w1GBzJ?vY}MU$ z$R5%+58k|*;xp1>j>^k164M%*4c5I=9zVDtUoGpsJ=A-|HH!b;h_U6bCvO(kNk%~O zKSJ+BNkAp#ngj|!|5iTG_T>t8W8ibuJjk9_DH`j-L`~RI)&Qhf^rJIR=)dMf)~&d_ zL)7&^MU9yrH%cc!4Pi=#`;)ni0H|{NaYT0euiZ4%*@|{w=PG>C`%RjSQV2o+C?f7Z zijk5WfRBkdkR?C+iKhFf1U{;iY3C^#OyR{e8q7DC<^-9cU|l&C24Mc|=DFQd?hN>K zgcmmY3tf1qYs5N?aZ*-cK!}=*5Po}{A2m{^kf}g4hZ?6~^jy9>=a!faX*D5eD~#)t z9kDQr!dBl_OU(peM4!x1iL+V1VQ5^;#~G_Yl}&MvG}HulZ98i47{G1qky&R~I#*+6 znL&mkS&6325U6-N@mna@R=TU$r18f@;d-{M5RaG=8hQKlhkLeSD|PF=Ww~TdZp8Eu z-BNcdY4}vO-I%Y2S@DTViQ5rHi&jiQc{>n*Tm$rg(I~7HD^OVEh>e+ z%|dv0hK;nn7Z%TZDXDe9Ta(VL)(?kp1{x?xJ}QC|xsvgw_cH@>6NE@RQtsoJ65R`1D9r z!z9=<>Q{YQGS_qWC6^*;o!9ysc2+9RxZ4#^O~0`IMY&yf_Nu(?CERkUq6R)e#4H^W zb>>52_5czlfq>%^PyYQ`cnu~2SQ?)op3Fz}*f#6pBhl|GzU|eShl^vIN;Q=dL`G_%I0; zp3#SOXz(|a7NYoRPWE2u;JZrw!rEMJ(yKj8TryY4f|Ph9t3R2(heLdQR6XD0x2@XjFqUQ1P$@RZSmoeiMSdfK)E#B?4YQY+mAaXq55GJcvRMx zHX%-e#M8m62$Qu@6L8NF_z6Ui{bqtO+i9^rRZWnkn>dXepsBe8{+k7Q(nhbltK3q)wW^O=PidsGa<}juJEZ>PLjLukVzih0RC&hw<~g0FI1&Z)|Rb-^Mc{+%fX)QLmJsaQ>(zHl`DBa_-MGWpV zz)>qybLqyz!x(p#EdYDF?Wu`5NewSfkQ3u|BC9g2`h|q?Tx`g{kpV~E2UrX6}j6qE<=?HzvptZQjSK{nGcQe<;f`OP1QGgx5a`HeWu4b*OLa zL4k|82leWhV&+Rjx?tSLK!=A6Fzp#rzO0fknCsYQwa+0unRsPA9 zD93a(*@^F$xKbt=*QXPjxKqg5(YZBC6y-4;qU;Z21gEBh^Pwme{m5U>r}{F3DxX)= zMMxJ&cvpY&tEBgV{|>Y~-MoL|?m)XO`y#$w>*&cdqN&&&D%TxL`4A`r(uBE$3BZw9na5X5Zh0Q>~Yw;d}>D8(3J&k+H-Vk-RYAA6vacHvXWLbAVZ5O z#-F*h@x&v0r(;)-DLRvXZnXXFbV_>Zj1q+@Q{_A>dGyT}4^<{?N==d`0aNxr@1L(S zPxK=&Lq|Oa#jyb~9IG%BuN3YII2u~TMuH`1{hKr7F0xLzdG}Q^L}Mz1I!NO^=j|Cn zT$(tBXitjKnncBUKui<6SO@)aJfmFf@oQf)#o2vgIeGI`Du^X-U4h<*q7CcexG%1I z9mwmsOp6sc59WbN0UFvFnIu5X@EN%?M>FaBRJaIBD+I4hZ)q7{3_2F9>fQwvzAFg4sW4CzaOvS{f0 zQ5evWcUl-tKI9&WDsrGS4m4$pvEl*1Ot1%_rDIR;w*3Zl$OVt$Nb%};_+c%uEXJ;F zdbbL(i^7^cTM>C0q%q{{DYQ+dDo2EyqtcCFmLNwef)>)g!ceSju0|vEe$6pw4s0?A zwMP5(?%hIh(#6wZT`FAq^=#M1oTHN{U?7!D$n`!-2B5ATvIaW{-26-?ROKJL%>uI> zD}=laeH5LONJB8Z^NGB`4^A;&yoeJo5p_X`H4`Lq5kTK>LIa}0hIjWC4SdHE=}<>_ z%*}RkX@Lbb+P%Ou*RFjPE$AqA$UPZhV^Yb?OyZ(|4HB8Lt`^Bj3{ZtBWD{9*V0bIF zBp)N>LW7}w7;Rc<3Jp%o-F^lu)S`_c@W6Qt$leYe)yBAvovY*)l~Rv%zGCE#$@OgG#87~u85m)Xmh0Oj zIzE{mc`iA!uzg0G=u$j_JuucS`y>X(K7o-Dm?cJ{o>-x}LezzxL+1LYQrSs-czrIc z!im=AXuWX3ymG;~^C3FBVo?qi=9B;yoJ>-s3rMW>sxSPpi{0e~jIv)AI)55v2f|iy z6kJ%j1qSC-rCC)`X;G@HS^3!+6XSS3+ybL$iIMqP`EEZ(od(B@T}b9dc+l2nN5<3j zxJQYx_6-+}ar;b5Wsg}TRN zeBI(caLX^pCbPy_&WFCOyMYtByY@I1n#Dg(6B%GmAtvWm1D&&4W6irXml>Amiji=^ z!2HT2Civ-(Av1u!E4FO5F37c|Gpr@Na!dU(u!mn3Fmf{{yX_O%XP{#v&JBV~2dQ#MqFUD)~t0 zDAp*G+(tQ?7J}+WdX8q~A4_O=8Nlwr?6RxNzc`9s?_}6;D8k@y61y{nkKhD*O5-pm zXHf(8P8Iwmmz|ie;TR`8^ezgPnu+$nt>TutuAC20SABgvbwPjLWRFIcYy|ddJ!5w| zEhwAYoyOf>%|h*nN1X8JvL*KY_nLB62hkSF)m1<6ogzo_R5a?PCiXgMcE*w`WmqkW zImm1O3+H#La}?KWX{#;OlgD(`?wrg|i9(lbU|msy4gIhttLK1u3vr=Cmusrafd$dm zM~yZ`UW?i7MB{Blv>3*l)~X-@yfN}d^mn7cE7!}HEnXlumoDs}GGX3!va{f(F`x2D z@#Y=b)YKdVN$rv&pihsnjYj&2xmp^&8(Z5`Rz6#zv2hoiQuL}I3KgJKGK~)qws*0} ziAE=KkN>HKsm%~-?HRc`pq)+MB!Fn#+hLu%T#D+ zQ#|#)k4BA|{4QhVs}>}!G}m2A?`aymjsN=t4g4Wf}S5ch9$0ceAg=rAk>J5P=k=?%}NDy;#U+ zoDGo=|0rAcI0^>)N3?k(P1GYoAnz50I@0Tgc4ZIDWVa4M9thB(nVK4-RdU&bTJHX_ z*}3n1+`v|&4s@F_YR5(~Rj@4;k>_Zv7wG6yZ9K%M*t_IgM$h9zyV^_F+0zg*^-zfm zYys}nQIAl;O$BDI+S)YvwzjHVjUMN8`J1AVh$D?6%GCBz1M_*0R9wjQ*H&SPP?+BC z7xB_(6KXTBhPEOA%cE;V0(~k%;n9;KY{ur~T^J9;BN8+j2={_`i0l<@eULg4)HUqgCas0)Kx}yavlp;lEOaHMVs>~pF*S@|4x6wUW7KC~K4^S9B~Nh-(MS#Xeb!Hy z)h@$?ZVi{d+#7hQt0kux$#F(>{&Q<=h4N$lhOp`@bg~cVU=MVYJ zS4N$;VeU3ifmHybJ7Z_J0}$?*$4l=*xt9i~fvU>FXiT6L4Xx=F-~9181AfsNb!nOR zGSG89BTx}$|w5O)yi`R4nI9~L-Vk;V!p+zXzSM}d|tN`5Vg$L#_b(PtWllE zug2q*^aK}{7-cz|UT5SUw;g!hmIHV9yg9M%bep1jPqTKnhg$ABMNLxuXHvDXhx)yV zR~P>(kilgEe$ST+H#CM#US8O-OXSAFg&q5fj{VBw{(JD9zy}F@-fN$B)F}kOavDN^qfb5pHr+nR5y&aStYL1A5oBa>q&K&rF>jZb9PJ~ zb2T}`=uK=+8@S^Kobv5Ygh$BkP$uxZ1nhiIue-~~HwbOc#YcbP{MJ!>ldSUWi#+_5 z?`yQRRae=cEL`l|EV4GuAv)}gy}e2n8hSW92?{JFa5N9Ra!N!H`CqZ`PprOQ8Tz8p zbw@7oJ528!SHS?xE^R{keex7g#IfBAb_4@Zcivpx5ZcI>0;r(|N=9 zqt1yc_kKm4`JSw9I@$i6AKLpOANW~)ym}>0!TtS;!?LMopT>p{X)nE|WQ^P=)z-eIrtg!z?{#_4t9b|k#2jE$jXXVV zfmX6uvL~|9Qy++JqG{-76(v)FJN^H~Y+F#njx}amO%^IHauWk0rt;EMPxDn#yaq|5 zhzi3Bn}pQt9s*TIV;Jx@0l3if{?x-6PwdTP5}>SCkal||1QfPpX@Ebxl4t03(w8-m zgPND&c~raMEtT_zpluAq&*{9R zB>^+z%iZLPg@NU}MIm8(W}2r*VwduN%r?gZteC&=8~~?Is_iK^1Qol+iqD8O@W+IJ zq!;l&X8T1;1E3c)e$^y06^i$G?OLs>>3lzGiuz(cj0r<%*7h}MyX$}?aLROA-=_cR z!)soz!4JU>={)g^Cv>0P?K^2e0lBf;OOv=jTDQ76=%Noc6GEf&mm)|jE5BBj({SxB zTgEiBF?gErhTjbP2#iJpKT*u=4L=F*s5PJD_*-Br3}INdQuQVYyD_srG#AnbegKfB z9`^+mC&oXx_rK8AX6x&R z-HQ_Z8($XgvX)PdZ8e#PfC{_eMM=2MUc21=nO*(D!=D*UR>Z^o^^PW($bF~((b3c> z3Hzx1hTSqm1FMz)e(f$V`%GSZQ(e`?1U2K@Jx`^`fMdhXKNhzShl{l=tDXD701!Q+ z=|HKb38!g)P4sv42$A@8@se6DSN?L<@NBsRhCTj{vy#Gu+R}c^K5YS0neVR*Yl~jm zasQYc3X?sW_4gBhcSHnC8=QoJ%*@XZ-TSxE;GTUc?{?#H7^Z0Nm)vPC_G|9TkFnY; z(XbmpwU&m1HgyMD?tuImlh3E@O-M{pZ+dlf89O4pWfAqA| z+G%ce$YUhC^uV^)OIJ@DV0eJAqbOc!Ciqc%$7vU5kI2UaRf5Wst7RX8#9%F&*&JBj zXYlXk(GNkAGJs?D>`UpW_I&e-KIQ2#wQ~l!TP!Ow7br%A6>N^1^`Ui#4pf+zRlLdo z4=W@t?0b8$c^nmfTzR*-^0L>uo~9d++^=Q>V&pIFe7WwpcfH5QZ5#UY?)T<=dA!}K z>XN~h@z0KN7?6Hf%GDN~PJ{b$ZPu0iDe+)M+TslC*-UY(7240GC%QlOl|0kM2A=)* z%9c&-(f8%gGF60XB;E!82R zz0X%EM8ZD_-=7pVCU@BUW@tL@fyjNu9SMB}bc=(T1aN#`|0XCadBdD%2qQFSWm@2Q zJKAqufm(;$rPf4p&7%&w+0cA!ooe3fGYO%u$x#K(83PucTg>YQQv0(q{ME(bpOyU! z9y#=FU$zss^{>Ih`LmJP)k?3OM=WQ(&+QrDDt{jxv6h_27}!6OClpXmT*{I5NVmy4 zIyCBNxs=1oCY%qU-`XdB-&>}4hFn5R+#kvo+Jv_yIJ%7clrH5rxYz1p-T58G+}63Dug>hG+{%1+5KW~w>eiR=N=XcPdG9&c>A?prH~Ny#g&z<)oQD< zEqi4}pG*0FXNAS(mHg&%sSeXO<&~R4EfjZ1m9Uxcd;SH%p*mA(mfJQ%%>+YZh5Mu# z6jkDCeimzp%Z>!7Z~NA%{2Wum!Yhp_1OC$|nGn$7Wm=D5gkwRw7)kBv*Or4$%gJb? z>~$#&10(C9eKeH>;>DYT3>9|WxvycaWmQ?`{zUmqZsq-oaYrf9ulY|xuHLIKJQuTp zLffqT2;f$}G`3YTn^R41$vL#`ccC-0IdYrScMCT$E{WnF8nqPmrPsKegq`-PZ@m`` z;NY_dcatLZ0{6G6magr6`+T>I=|>0~?idj7=}uR@&F7@+4^Vod{E6lvs|0ge|0csW zL^_<`CS{`+V%Urli`l}Kj}x$TAkVnX5Gwns7rvE(%J`?OHv-(X&B_?KckI__^7eL3 ztNBuc3M1xR`*o!1`~SXl(29X2aR6DL&uvVJ(ZK=1PI((S43;N?lLT}EhOd&w9TJ!1 zZnb4>@0}C6g|`RHrOvdL)+ZqkSpn5gT+ay&{J{z>oy01o1Gag%lbaDE8CDA>;JdgK z96iy24hXaoXW?TsDU9GKB<`7vV!V-ja~qKYm&;O)cu=Va4`wmAsR_ZD?{zOg_^Ii2 z5(nBfUNF&Z!}YIh!S+8(#|fLc$r!8mD4}ZxyRgb_!NMR9rWLQR-DUv%DC@YAiG4pw z(K!&~r6OREiW-(EoR&a?AR&0O)mFtME}}R@64E5C5o~4x&V&YGilrb7_3XNHdlXJq zNWs!PCXT^CRPaH#5ataMXlIz+YRgtx$E2bj?BISCkV z38#5}S=q%;47|@2HskcK-bDU>3hZGDMHU*Dt3~cByWtFk!-23Z=Z(^o!ftnt4d$U` zhxE{e=Mo#4u>aXN+v}M^e_p-hMzE5U@MXfnPF?k{cR|Z{daEVtW5r@4KU=>1sUxig zguZ1-F#Puroc$AoKN3JQo!OIx7r|wd*5QAXx>buIyb%>hsS$6FXtbMObx)VWuvJQ# z-20+}^BgB-pkmf9Qpi9t#XmIPz4Bxn`VZ2RMgZrykX0lsH#$4nX`NYn9*=tT@==ur zCaiRhiHT(jt-<}Xgs&*&1yhLJ0Qf>oX20BxNtc=52Bq8@vn|$3Gl|}B?YMB(vz|>` z9&G@*t0xnhFgsAGc@fC39W+RxDxUtfvDmi6GeijR94x`QImxwtc{|V=Sx=%JUKHf3 zYMuD|6-$tHOBT|YzqP5?Ee}=svOCo868K6^f)tK+HeOKU^&6Ziv-AgZM>HskR!ob zu^=-NyMebSnGHW-BDz#DC1=b=Hl!IA?@8OWftX~B0iRGv_YGjjxfx z8Ngtw;}L7XoXbJ2sZ5C(i9jh>vVr-uAGKh?M2;Vfhsb=`italXwTfEtVKN>v2mwSE zY{Btu_D;}?N-(WF6l@0c643b=xj#Z{)j(o08wJcAQvIj$_re;Sn0?2wcI<=606N`; znIcP9eNFH5m4F3M7CrfGp`^1p(S?S1G^7w{un8Uwe535@j68Zy5y!(Ow3LSnup-9~ z!};%!cWmbH$7|5Gy+Dx<+c+r17E7*iT+Jvf1!U??Vmzt4DaQ_J?M)xM7B7{ME**n) zU`7OvsR(I!HjZ zL0Uo@q{l~EwJ2VEM2`vm*_x`&%1&)t&6b+X_9P`*(g>}4k0Kn&d)oumsHbP&ph6^u zCkX*xVLObN7z-2&pc{KpJ09ZLb<_Zxm&^hWoG?|fGPPPV@~@#k%jZW&b#3@CUOrZZ zf%LzTb!R(2V*r)Ntmf!U6|Q&Qm;CVH94;s57c(8N=3c! zq_v8CvmG*%3%@QQ?EYEnpitM#awL$djHFPXBn#yn2Yr)!A$wF@%%I)V+zopRbpj zzam9Wv~`nn<>l<~W*nd2sqBa$6_#;ny$)HcjQmkXAfcm?ZuhUwxOZdpViyroc~Xjd-Yd=P z?K44y=AU3cy~Dm0#c9;0Vjg3g^TIxD>Z8;9bcA~;o9HB z<@XdrP|RbQ-~62cw*p(;Fp9sAx!wxhO}^d$HYxO5^d~4B`h4lOVWWzmuOd>3K0iRS zTYD)wbgq(*>tHz(QvHGz=We6(lFPY~>hI{rde)0sgli;Gi7O38WnIgghAJ3CZe^Et zWp!18nhM5nIdj;|eZM+abvbvnwE|D7B*#^-h}9MmMlw zYwwZcbMOgwj3X<;mI=Syi&qf9j$m|5bJXvZ3W6i_HAf_A^%mg=w)-8*iaezHySx|Z zD1Jr*2g&;t6%q#8B5rdm@HfkO?ZR%xjb&Tc3L8zliEriL!FDR=5ap?&4*G+pkH~Bk zlF2ZtzgX%?9^d2dXFCl(;D zODk4uz^>=4BDx8@)$56+to~9lv9N3I`R{jn$%W0O%V@;ox(5jr2|yccspNNF&q2jW zMBk`wD*N{PR1dDWf$RMx9oe9Zqj7Is)xh+DJN?0yY(NAsU<+N$}1O?>_xTGS27ZY61(M~jc zQci#JLU(7^=9@8_9q;VE>uWb%VkG-#!N)Dh@Af5|>k&7V1|F5OjV}U~cLPfQJ^**h zL~}Owrz=b4cwn+m#TT23=|=Gj`x4(eV-zAYO8PMCD)`mA$BH78w&YBb{Qb$|`2?M{ zmb%|{mRb7GIm+!#V5*%fVN> zC;oBoQ|FCucVKBpqRsLOmpq4`p4{n%Xqr&B`9|rDkhi|tI%L3$w%}2&6cSw6p6zTu z+>ofc;2NE^xS;6J8#uA7_`aO_e)RJD+c$_Z{H~H*r9*!|4E(Fdj$AZWg2r!Xkm+fA zmarO->*)0{ea*o26gzc*O%Nq_>r7DhmuHst!TqI0c&ac}dD0YB0JATKko6r9E z=9SP}$1$FU0y=eos@Q10%u6Q7xPiSI7Gvpg_aqA(0GOo zNTGOdX(O|LxI`-LNx1Xlk4>f5@|O6W{5B#={h&cnF)tj-{JHv~hvV^2pePjmw3Rav zp@fuw`oca#xhx@ciSRKfj56o9qcRlguM{7-|)PG<(w6pYvHm%wD-Wm zt^;qSDzQ`!N~Hr;3xQQFibTr4Y5n{DrexY>e@_||+8A+8Uv60fLlr_?J-3K$^32R6 z0mm#)X$}2+EqvB`Ro2<_S!&oUku9v6+DthW`u~cyEiS?Y4^HQ`W*6A7$qTkB%(VU>mx-FziG(1By+0K)qvN$nX~33CMWa2%}zJeJY9_P4}nh4`=8^Otbb!vT(B= zuE`zc(!;wB#w3EvNu8zkR2Eukw@v-@=J?fcz|2y!Ff04NUTkxUm+F>8;q525oN=c3 zwr9>QIy*kpTn`>T*A@pei<+b~FOo?2buchfO8FI@WZd{5NyVVJbTJgWrV}3sWdpm( zG(^ok9JG(>_+8p{Tp9@aN5vrEu9XPDfZCNE*N$C+*v%AmU17jy+T{p?bg3eYDgPgS ze~O`Zc<{i6ZCe{EEJN>enG$!d#cN^as}j8=GNdlj3u+*M>Z%QyzqVyEg$*#QwX)rm zIZd~{UYCRH%F{5RkalnTb?oC)db~*kmtvo}&C6CRodDa}6%#zW%==$#v*A^Wn`oU^ zDKzDO*r9C0^oLfxwJrsXREXDF9DZuQ_uB5`&)T9Z5)_9xka!cirqLRdtC5cX+jxKH z0m0Y%c?rZJ)__|xo{%W=Zs_$m7H}9L@!q@5wvo5S_~5b)Y$??g6WezCvjzq^&-XeD z(s$_S-dI|bu9N8@IquTwbScT6feO3VS96o{dE-x)Su-MqL=Ehhy*sd?A=G@YG*J5iMaNw}8;L+mc>w!P* z#a?vrbXFzC%J5;WqZ;q%Qkobxs2uN!*19z1ckn}1XW^_p4#urG&17mGGiG~{~ zbVXqId5e#|y&41pEH-d(zWLFs=1({3@fnL!2EJFJtKVd^btEJd_yZTO&$5B}guLG8 z5({6zgh>ik`Ztx1iyiE|MyL8Co6O4Ij|m6@vxLZR~T)~dHe1utjv7j<-Se7-hX}cC-bB|PC}H! ze&8o}JDC<~%7RUd&;Ox9Dl?pz*#)!UB$17}f@9OWlk~erXu1>jVnl8V4P(YWdwjLk zeFhJof{(sg8FI-_^+z-XT*33}*8PLn%L&gDdyPc?eJ&m?{_!Wp@hW?)`tR&JI~;)& z#uYYL!T!9w(8aNF0QRiJ$(ti%2v#D;Vq`4U=;s&tW1ac0)(xJO$)%CPu@CF5zxNz^b4Cjg>HwFXzxlZ4gNX}`)+5~PNhB2J+Cc10wrGQ?lA zP8UWgv_z>z@3<$u{kWd?WZ4#maHjLZI(ItaFmzbRHgaH{A1Be17%b$8hjG8#ktf&r z!bP`VXl!asSD>})8B=XE$&JoythXSO3*qRbYOmDj{7kJ{;MtAYy%bHLn*@Ex9YIxp z8?tPbb|6$dEX!kx*sM@~=HgKm9@~-_PWyGZfoXY*D^hfD&&kD+0db5^>6DVNL^{jU z*DwKd+TG^(PziBg1UFgBw_abP7)Th{0I~E?NQ=H|1Hx$p<2P9pI$#dW(WtsBKxl2U zYJz?UnSpjt7UeP>!|+)|m{KMvyk%a=&NL6VZT4Z>v$;ufLNv#Xvys8l?_r z-qwnaEHOF+6QZdq686m9H{SZ9R6ZnG!xb_lt&@nSC9A1ddW;yRl?}y}nXRA4*b5+u zXj&4nizK9;E?yh222gu0vM>e_C|Y#7en+EB>}zpxHWPD*glaNu{31Bhq*$32y3vT| zZSRK~UtKPlh3krX;uFQ~Y0zEgvsZMO+vVOAw4U1LfYFL93DpUKjGw;2dwNgOU8k@c z8!kz?1E75U7*wBLg+F}Z$>{2D5+Rep4WYdCd1MK7;)Q4|CSZEM@4R+X{3C^8`E*fd zpnGd24dZiA)bQ8?VUVQaT@;XhyX3C?~J$I@mR{bGpOcV3alHW@6pf4!tWLlaV9 zGI`_QxgxSm2v02+_n#ITn%r>4<_OI98SdttO-?CiA|RdHd0P9Uy>c+I=vX9SP`vFh zd2)W#+y=RGHYC-qFWd(aimZxjDND@TEau)i{9_|$sr10BmQW%T+Td2n)JvHfa=fh z-|WyGc*K=8t8HvYzr&mrt1SMk#3J=*yk(bS|h5$1~JRk_Pw zjW;KN34NhJ-hCM*JpgL}n|IO>@+6$5uSQG^m|2kR8m)Z{ldeh48ZfWPkv?uXyRh!C z8IY!PYxg|Ll8WOLiV}k%nAtz~WT~(#d@1!s*zYpcEw^P*l7Wqm19p5erry8j%k(SD z#qH7v2wigU?anzT*^#V#=Z0f>7t<}uMCOTTR7o}WyCzn?v|B7OhZ*b~ALQ~cMP}P~ui^ww>6;t#7BOd?9+Lnq$!0A7 zMe$j$M%?@K(_StGe64fau~Hva3Ocz3Pm2peTn;^HIS#ZDHvAsI2O#^RIR zxj}F9i(HEDn&;X4K!fW1+;eseK_wO4*;X$3T9lv$?GpR_`8L=ypJTF4mXvmNt=~3K zV&h`b z#}+)54+_}9vLOXMPRr|luK4;y!JXwm#3}FN^s3jLALmU3fv(*-2KXS!nLHv0dSsJt zm7`FsRTPU2^2uNc|IC+bC!Z{-faCJ#ONgAY+?ORp5!c+WjTK&RFQiu%^>tgY8u#Cb zx(I74Wqhu%FDd_3QqmZF!G4EQ22?heL42N(cOPH9UAszcPl62>u9yZig&JGS8vB46 z$G95j(i++UMc3IH&!08)0H;li>9XIK;9pG@vdlt}eW^ z?m$nS1_@T>)1;mQ!4Ut(c%&Y@^VXU;FIN@UGBvQ%V{-r85Ml-xDpZD$ z?8WOn&A3~Pny-u>+p1^lecfZ=NgaQjpMP3`f7Y~rd*DjZ@e=6S}ABI@a_P&i%$}!!6Kj>Fof|R_3 zFH9@Hm)VA+1uW$|-5&AOu->>Znrk)z_AXQs*`>f+X(oRQwJ&z?jc|Qp{^~F8W z9wdi4Z+k8=UvwpOLMy(l!ubel2ApqX03r?c7H(%7bJo1QWfoDGRQt#!&?MB(Tzc=^ z&rO@Z*zGg1zj4G!2H^Jgc4hm(FsHpQ8Z`m-noW)toNK322!2x)|22h}-S;1$K%It$ z(q;;2qEj>p`zs|B@rT1*oGdL7e$}^JYf)4V7IZ{mBkX|_f!T`=Z8_3wb*CEKlj^!1 zuz5IZ^Ny1m7;bBuVqei@aId1l=F$pbK4eJm^K(KC`OuIQq{ph4%(IY1Kv~}AkD8V> zNko~*Rm*W7B?ryEFK#koJm|!gjT`rXY@~Zy)?$Tf6f@XUO4$fo)vj;Y7=Og@%%Coj z8}PFo(c-|NhG%q1aHp)h8rRh}1g(>G)e-c2B*O}(_{EwuaKu=VRJ?ECT=D_^ct}n8+W?CPQ*FK1tf$tatMnp1WeaWh z?iS3v@GTY%B59sf;M)`{Z5>{u;F%kQSOX8+LBIi>U2(=|T1I9^M*g@M{cVBx_JCyZ5PLADFQEd2OZa>Le2Xid(I)3|dx^@(?JsH-KQ_ajPj%dpN%M$3K#g|HnMNC z0HmtNLwDn*#13z)`;SVObC9pcp`oMU8)z=Ghj6&vch)3Fne1pIN$)CmeG(O_wMGAA zH1>`n-AT~rLzJO`G{=_Y+Y5T@M&rH}ZV&$91UZeYsPaHq8O>Qwe#$pL`HJM?{@K84CI8bBMo zp_JR1HVi`*?%m6H9hZSeX$?9LA|JGHwOz#Sj=l5|;SI~-N8AL^#rkO$8`<)KUdf%o zcuc3_&s^BNHTu|@@ea%%tH%YGqD=7)@+`V2_aXkzSfu`=3k!Og*;!TIF}k@L2Ym_? z+aJ6Mp81i8s$dXPX7q(aXbK4x<=?Y*94@>%n-e@&nLk&PM0v$!$i!-+37xvS*P0Usoh=b&#OER z1MXbx!%@QUo#}yj2T3$6Y2xAvs>l{A?bpBZwD7ghGu;~-;y=4O0I-4mypBC&ED5g2 zyxQ|OWRvH=4?Um@N-yF+kJ+CN5C7|sl7d~5X{w|NmtUV5X=eG;|Q z(xRd|{CQC#_!%J{beZhJbI_!Xz&a6btw*~n+zJ!mxU_dYp5Xf7lg`}7+djy-Qh|)s zu8Z*iW?>u|2B8Va;N|1-lef$T(BL<0rJzS~-J3UL>8mF-tVt?;N*1N(q;oyrUgo!y z+@O*dU_r0cT(BM;m^wU9-J3ts%o;rYL41eMOeOCMMrv}=q~t?l=~;f+-;68{fZXC4k!{P+EH&K!(kn6Ym$gD|r1Tg=$WG9e|Z zu@p(NZ*61jOBy0OV@;G$WH;87(vU()Ly}5GdsLqJ-S_i6*Yn)htv8-o^d-=g;;jlv`l07B=BsIRsd;~a;C7&G;Q5AFw~fVV5D-yp^}xrG?RJFA(% zz5G_vts{zWEaz^qp_={Jwj4e_l%eEhi9K8Bj3rHWNkHRWaMK@HgQUf7myt{loa1954$ z2t1?cpa8iii3Pp9NHWaN9@rUYA!T8)M6jcT6;{!i(1Q58FRbAWV<~P*(%89 zVkA)3u;GeD+czCnN6|zTs3PgAT23R|^vf9Q2xL$J_7{GMoEKmz+v>1B-!ASsM`2PU zpJoLii67c;aO?5MJD081 zXj7s8q2T0daZuYe0dI|OClut(N4SZ*3;QCIZ8Z1t+T@=BxvAhjOMI=ooeH&1A)$`@ za85@ueKrFC=}xA_kFM9$=E{ndgOK%!8c@UO^!H zA48}O8{w|__2W#CU8g}n?e`#QX#BAUStm~Ye2kYh_FS6dG3U6Jb-eg6bO#3+Wf7nM z{Bz!NCIikHXRC_4$J%_hb~w22X5%wzk`Jlp>uTApS>3}EGd?Zg?%lpjB^mdqPF;BB z>d(cs{?ZI{oUiOXvFF7hXK#>GkCD4F>Rr*|QIPU{b zSi)v4iTwfAO3pZ9M-Gm9ghf4#=VXj1Z~5hr%ya`2kds5FMILYkwUHpVOa#8~SDUyQ zOA5r@78H`jL&{-;yk^l*%r24(DsD>qN|%#d@afFl&f^-fU6;`#Y=S`oG}oLy+R9Jj zU}d0zSPL}-2}1t-6N2XS$6q+0pluLoyuNl=h7l9E?pRI;ba#5V7vMW~x*?`I@2 z4JDUuo_H$lNcJ}#LJ6Gj*tB%YdhF_TA9mGWLK+^i7GkIGt^26XE z&aCIW|D^5=N&RTah_ehbk(9fB;W!c~N;DLsB!69J0H(sw!PctzTQLaepgvE~M7PC8 zx-z6@b0hd*)|`K}lDYAk0McvUi|08fe7Lm;-ZG_Vg&Ry>OJZUm=et*g0r2FGreYP( zUczeu(nfQj&`~l?F5orK9;0T1n2k}5PecHU8$`G4UwEyW*gI{L7+p?*B^X4Wd3Gq@ zNahh?HU;_N>3B&-&r|wXpk=+=sP@+H92giXQ zKk-nt5MVl6>Ojm;!I?6D1(9EkKq?4qWIx_5LgC@8RZkQ$-U_X=drc2TmcDX2zQ>}F z1!#TC-|cf)Vv`6$4fPp@&VEWVF5phWm1|r?{{D!q8Pi9u_1X_bH_r`o9=cn?bMfev z9gQWagcHreILyi^Eei4x7m>R;F&U(YaYLQ$!nmfyQz5^l3}QGEk+YX}v#&r9GRCxk z0bA@Tt$21mhH)z#0jO;Aoc(vEGLR7hJO+S&FB_x#4u6EsNdrsV-#W{QpU<3Qq;gqp zmi@_iPaC*zi7mO=Q9_rymi(NJk#pAC8G+ny*X?@HtO{`7NCbTl&|`E*vnK15f+Dd? zzh4_jZK2YS)c~t8w5#{BE}e`tc$1jZB@9rYkX|Yvk2K*Dz#)nSsjK}l#sR<0e4;NN zK+YZ_MQs25%E+Ru*;K|KH0(j6=q(gu3K`)?*-S5eDFh7dcQ{pwSdw7xz}2Qb3)0wR zVg7W3^f!kDdlPAwj=e_6#?kp!jPp zuRCe3JL1$Yu}6Cgso{Z#I4oPvrlSElX8P_)X9|LX03@__?8;)`$)ApT^z(A|ehv)l z`0(@B+Yc+UPA&Y5O)La9lrGE?BW?vItv`*!uw2B+@p~oWyi$DLdt7{!0$E{vU)?>Q zAa>Xhuyr`(S~wf}j@!rQUW(T!7_dzJlj`c8jy|v!*Y4>m+KE=8o3@Wi<}4|w5yR9E z`B^g|eoLAjJF#OF)+WneTn6_XN_%LBfGlyhM}kwLmHi6P9M;4p3_TZv{%jCptPHuY zCTZbpRc1rhMS%@2uk2MArXSFVjWW9(VHI|Yiv?NWU~D}MXl1$pk(_vkE*-oZlli(1 z;!cGfH_{J2MQF#M57wU<`Q;6B14ayZEqMo8;0BUsk9VYJb+5s_zY?a$&%7i8uUdV_ z?^&j=K~eVU%(oCV2*4B1$&Kq{H&i6TL`DO1yf$HTCM3byubu~q2YE}dBR07rO+Q1u*wFI(n6>*;^@l2!BPKyMLNzULaDO0`pPxdc@)jcEg&* zfcEcPd*Bl*0oRPu(=C(327!|woyR2 z?;G9@*^l$|VY|+BW+aXE|i>SOs z3kIndiqVqy(52UXo>Sn0E;O|(4x&hL#lop7$}nJMOuri0C19No{Z^5nt(Dy3#rS7{ z2umCm18Fc39r2}h3{Ct-PJ%CRgHR~-jF)^+Oay>3=Hrg%g6i>T>lj(@g5u2;pdlc} znT-e`C<6>YmI)ct@pm&k?hit;6qV3-kU6#B?mX<&D&O;4SrkV$z`zb#mv{ewIX(&l zx~gbcB{v!5@ZTg{rIHxPLyxEIhmKqY#IK|22cWh60A>U6($h!uu-N#4^388MAZLIS z_!H)w?QMz`FiVXOm2SMknRN~Ht=t5(3(KtA2cfQk5X zpAj+zgQ|89M9@WI`;qj@)ps?Nle_q|PQE4j%V17dUgxY(qkQqO91zL10X{k@Ys&QJ zZ#la8EnSf3ssktOi-APxe##jDwgt3rtaThcd`5q_0mDfe112Mc%8_PS8B6O`Edg6Gt(Iq% zY>BQ|CT%aDf@$d;rwOrrFYb`6;GtIFz5X4~Q?efqB)h}yY2WYoY_~sVw^L3j3>MbF zVL(u6M{rL^$cv89?T#?%yAh^$qrC6NltvXA*Lru;aNYG2cN$8& zZ@lPk-0o^Fz1<|;bH}@fV%*cQUD8?F)BBHd`uy|2Cdo1**IdiwjD`q#Y= zecJB-@}YavbilxE;792IBWqyGRO-)*0pL&jjxOaZe(^dDv( zW>CmyaGI}Q?A(Av*`SPCkMzRezwMntoY_$Ko*_jarqa0~)jx?MW<%<|Lt1711exK< zjUl~r!(9HuGB<{e7KSgH4x9HP&16QbvxjU#M(oN)$_z$CAC5Tw8Sz4lIIfS7eMZxW zqXOBZp8TVSvzbSFM;-o*!fIm_r;z}DW}wg5-mtINbT=)9FKZ9e(8qzWv5{yo%?4H_e*+_ zg$v`w{G-m=_mOw**Onox7RGBrM)BJBzZ`zhXm&$>cODwv(C=3q9p@jLydln7AD&?EJ1_l+e(q61?jz6M zW@7E5X8y?%ncaqplj9+i55A5S1At7{WXZzhXPFUK7R+(vSQ9zH6WE-MFk>PfXglmI zJl-yQZ14hp$p2W-=kd=QkGB^d@5r!>wOHmYk4Z$Br=0cD`<5})z9pdnMdke0Oeh|i zR(1e1dcexVb^;SksPX~8u|b1=YkNyuxu;pF{7FZ!{8K4#UiG%agG#B>-Fm?_-L-)6 z`+X|sjiqt77fq%_&%=?UurrmFHKmcY|LN%h`1tF`KQlXjcY~n{(;bcgiruU!Rb%yc zI%NWe-b0FE4H@tE?ftv+gn+TX_5dNc=jrJKPqV5VyiPx!OL~0tG=ky`>HqaGeRR$F zBed;xpORILFj4*4)$oW`tN-GGDOX#{bEovoC;A5}45)P><=qYp%{`X2rO#*7fLn$W zCkGHW)iAR~j&;bbQu`NotSN}LsLBKHOW$6fS9%8D55E@gIBRP1ylz)#>&ZgLkJSTt zFCvw98HCk1>@^~=O1gL9J{ecM`Q1SFzP3L9(n1)K*}L$~9`2d}K4bz~de4XcCXO6= z*;n1bS)Z(yS8((cpQ{=~k0X>!I_#J)juQyVEs|@_m$&c>6@&H^_NSYkF$O(?!iJ2!^$EcozOSdYzZ`RjV}aYL<0|)qt%GPsGrQ&ZY9N`LJkalQQ|wK4Cj>z zp3d3fl`nrF&R5 zwK!N7mZgMswILMKt=WNSG1yC{d;JOy2-lxMZI#bQRPR}J?#<>2d zqyIW)Wt4hZxv-LdaDAUkl z1)%837I|ZZmB5Pw9&CcpC_x? zh|}MnliAzM&(bf>U?$JVyi)k*7SV0a#$v;MgbbSHQPsI_zp&P>NDAATua?}z@ZAwa z0>s0H8m^MnwIU5ikD8wO?Cq8l8piLLclDWW3)}R1FY*fpzY58Rod1{OLR1$ zu_<^onUtldTv}dPWo?jBgd&?WQV39HSp~VMY7Xs0e^@*=J3lx)O1?VBCSOl+2AsPa zCGu8u&S4GhGLTYh7Ja_40w-F6JYs555P;tA8d5u66;zJP;O4Wz zJo_w{uM9~sBdZt+=KCRy{{OACm6Qz26-My^6BU?4^;Z-f3&@95rw^vf@d7Wi(I(w( zyQ@SvhzZ@R4fC|tGb=_^w8rvrEw|&S{n-vWD3%qWlKy_m3c(K{TfSmx_5z?{EpH?e zOFhz?z$*z5t7%l^dJcuPl1NmvOWXO{*0VC`v(T056Xd*tpp;J=}QAxzz)fqm~!=LY)ToA4PsQ(vpQMDGCUa?H|{)owzu2} zm62K->z|z5so>{KFtU1Jbeg1;8N`gMMT@Y|0YHW#g-S&`vk)m4Tr$522y!3EYUW_#9_btO9Az%ajVzg?o-q&7Usjx1Tu@cRibjrqB5%$^VNkS zd?FlhQmgW=5|rAE3$`Y2YX>E_l+IJw6X%elRkVi z?hTvwMzTlLNci>hZ6M!It)UNB--|>zre${?MnXw?;4Zq}0m^j6+=(W2LQb5cFxq(< zV73pY{|veFM58SjFRQneox-xjtE*Pi$stXb#!NNoq@ou$dXhabAucR(Pr8EjlC{-P zb@I=}E7kf@XYdjdlvXMrL3!4S^%tVyf#i)VcV!Ud3O|JO@R_$=?+#uhwDq zM4B0o*yiCaES$nM{RI}RA9$CXRpYMl3_B?#7Cv;0p47Xy5$}w|Os5m?(W6UZXRVWg z=w~;6EsGoY0$sY;4S79oNp?Lu%7z>_H|CqS!Rzd&;kNYhqf-n!$;!b*(co{`-NON@vYphk<{DQbk^A8rHTPNkJrLvRw zb|f@4zmPX5R(5JIU+>0rOnx%3%14!Uw#KxWy#6*@`2-7x?R7`?v~EOUgiU$2k%>YJ zD?2%{efu8qW-H3Y+_-f<$sXdBe^UFED_@n5m^$FtFkz0m5x_}>le6}bk%Q>SPAka+I4(6N(W8i*xW=+cH=4oY z*YQB^CH2&eD&P2X4C-Othe`$*=AU)DF`Z?^MXb>kjp-WdqAwGtTqGynC!r?RfdMqv zMLAUX$_42q0uN`^Z*ismXA;{d}GRnmyHwySgbHUeq}9U%!{OY4{qqz4^b4k{)Z)nBo( zBF;RD=+>2B8Ix3AIXw0f0!WepL|WtQQR)<09SAOW3MenhMQW0<*8x>4A>U& zwO7Ji7|mbUYs9bFYY!`c=J1y;HMqKBbkH4;mU`!ec~}ADVSh!T!7f5>FCjIZ2tgj3 z#X65pKKfH7Dn|6UCgBM21to!=@jBdUU(haz-6aaORDp1<4f?IvCEYZS5p`maj_cS$SC$F9+RS}pX2iJ(S`AbAN<`|hhCT* zv~t}TJd@}d5!Unm;u4waz)OO&GSH#>uMMZZqx*lKpT#?R( z1hvwEkbyi2VkjwB?6=cA&lNXsSbtc;ioD_NCi#^yc(R@s} z<1L6f#f4C2kT5qU9^+VS*wbx;dVYf)vGsF=Fqx^hV;Dx0*kBZ%2pPi0VUmPHfI@X^ zApK;^D}L#&t9Gn$ZjlyQGgSbg7?y~(b=s!{4{~cX2wk}?Pv!cF?bCS~&VOfN<%R@X z1J9^xPN&2Fp0Dsa;Anyo%zGFL16+CY<%$EvUrX-y&FhlDTeHWwe+9|{`WUi}Y)PLFHumC@s~Z%ITNeaq3Y1vFQe5;1H#mj-(mTI@uU z_dJvP_G&rbAv#T%V^ZK;S><&;TEd)9Y()y`+GX|$qUnor2c)Hd+Q&o`Tk`1%Pa@(* zJ1B@z;L=Es=0D+l%KNp+tTrePYhEI-v6kRWkG|_YhtT{rD4es=i(xE1 z&jFeSK0;D@TT_oFOroQW3k(>q!JzHMrqe|_Nc*0TxP_l&f@4}p(S^Wuv??mX^O z3EPQX{P6E5dE@V5ir~5D!aJYtX(Sa3{rUe@d63lKP07C-R(6k?7H)v!c_M+CNjS z9ZdBKPh}N~{z*%%daDX-q*m}KO#x{$foZm)33*pxyZ`6fdvVD;#V9?|9=4;y^whLV zvuPJ4(vuFQrxhVG)(}~9>6hnXI5Vt22Enpnfv{bOWL)O8xQND7aM2)KG%$(&E3i@` zbKN$Ro08d3loeZ>89SA!O$@gNvK|+})h7aHJF>>cGL?Z-d^LMW%o9!&$A)k48`7nQ z8F)$}kXD4~>^Kz;8zL#0fvKSUlataCS;02hNZ;&DTj2hj+6$C*{7!j7(qa zbmb|g^Tpetz3c_&Pn^}s6@3Sa6V8Y-a%CJ`=MEh69+NE@hTN61=lzZwFd{OhXn3?ONV{;+K-;FwU-x5X`g|WPDrmGKPqmJzoJ(l z>Rx~sgAWl3ye0GA98e1Mvf#)Zx(l?2hx|O+eUY|D+m0hNd9O-+xf(uyly~at=YYc3 zqTYB$;rt97=5Q3-qDtd+yZ2q@L`>1;`-P2FMSre{Uiw{dS+v+F2*`J^wPQj?4Z0go z5BDD^8T8*Np3^C*yYFLrwWOr0ME|u%s3;_p7|!uF7GL+ck%8|h*6x(dEo?9CD~2#} z#cHjGuDuIMAIpn~6}w^;B*hNs2PvMJ;8O$^)&xjWmr$Fzfw9Ln#o%h$C@OJ44g zhbjzm5o!_A-h~L~8DKV`q8+FNaFvJbDmTI_jeHSzu+V+pD2+N%|Mbe6I0oLGVG+wX z=qIa|=UVYg1kJ8M1)K1+c z!@A$bc)GF%5L{74O}=oi?skj$yKh30;irNgs7fwDp>2C5GUc>etX!!+wQO%r2g^K9O$Yrpy9Z`Yc~%5O0m+QI_C%+s^-;;q`!37LLP8@jzSw(cuArt-i_3XLjq z8l`2x8Qq%EvD_@@m3KyctKb#SC~G>OMQd$cn7F-(Oly*Gj+R!3i2~sXtPDtGF@=gx zddvr-Vy#W?I|6#kDYy5ZX1F0=WH#~nUiBT7nnCe#szIXP9+BTPhBkJbRNsne4kODL zf)q<3PkEFvMZlbLFc(l-$H?v{<*c_E=3o@>VMU{AFhkM2h9FuXGxfJ4egvz=wGYX| zhrLEob)ZVC+2?u6X+Px4{1k^y? zc9L5=Zn!OvVR4!dKt%2fR_yo;GS;ZPLkjI4+k)rL;!m2!MH%rO59d|Bhjb;0mu;Av zlg+oNHK~{!&ky|l-_7emB{eafR4r=qhA>H6M45yb(cU@Lm@jmo3Q58lNwXsq^E;hY z&P93R2mQJpN9bphPzt`tyIFUqG2T9d`>%U@VM&;R6~R#OZZalk>=d@ZhA5R=dYg|= zy-R9Q+h*JN=ywyDPhV8N`656r^E*pI&b3HSjxyl|E(;_3&qnFxl)Rju^k*xWb6ndz zlOD(=u~_2xZ4|1wYQ9w1i7D5)-D@eV#pi_Vn?UmX(cw8KG_(&nnV58)Hqg*=tSDT( zM0?lcX{NJ??{DvbJd)(qTw%l?R83s*K56U2nWCdi`AZyOA5*P}BIdfO*cs3+wKi<~ z-G-89G*TrfCnTRr#x6A~9FeZmAIy||K4d(&Bg6YpH?~v0_mryGLtKj0sAvdE&rR8} zR}N)K6r7edT@YE;9!sO(4u%Mm|Dd#q=+k&r=OqojFEGnjM*oYEM|JQQ%P`KI|A+jp z8^MEuK1j1LLl)i0*#k+HSBV-NOKT%UyWw4W_i5)=MXKFwWY)tTgSUNwB%kpt`gj(T zbEZ5HajH}HCA7LpxK=9_2`SQ?#v$CUkaNnX6NMTd;}sO^8oc}!}|JHVW%*? z6uMr~4b-0}*eCp45L?oj4ZgwK7VZ-?LEO@OIOcXmV3j;&Gzi1w`k7)D-(Hkqg7%dI zDp_Gu*KUkvQKfXxYp?r0$-*EChsJh4ao7|2gqwv8G1ECcIIYo#a%BJ(hlF30$%{c; zvUITuE3C6+n1(N62HPd_TKT2lm=o4Xk=-jwlg<;?yUHA^wlbMHJQnjr;7B81jCzd&5s+Ztufthp;YM#* ziSStyi6}0bFlgR#kRZGRiym*EEVUA`vg#RzP7F?W<{s*2Srjg-ZZSy8gCrej?$-wV zqP@ZT(0rkKZt^bv>(1>5gw0>;c6%Hi6|yG1|2eey1m;*|-?=y3zw{#Z#@>amCkBu3 z*-?O#0mAtsNOLhnYw5_@8M{=fs8_45^~Nb?uBj-XV){g*;e>!4tLUn&c*u%v?#8v4 zryXJs?GuwLxLFIj;SQXRgI1%(H|K@V?R_=ti!|FPf5OM*5nv;+e^AZZzAQmVo6J@O zZLF<{xwZBH=~a2~av{rlTk;7eBnT6VybI6tczEB^Q|w(48pzw9$IW+Vc%OKo)9LV< zCmuJm=&!dDY)QnOvcPxg&8&=%ECY&v> zzG*9BL3AiMwAh)wMgZQ~jlmq$wP^~rGfhi3iIS|)RwKWg;eDUg3f2fj)%_D|_=NiR z+tUOUbi7^S&&jn8tq;oN4;N!TY)j7HzeA%l)h2v7^T`KF|3b*Rnl&8T@8g;mmXY3Yryg#Ma+nl@cK0YqsjITP!52 zP1$o?PnhpE3zp8odo48C?^yXM#y zHf?LUW2=4a(%TNxTa{4jWz{=!TX!#qxUC|3&P3%uM(lcfifOQ&j*HkGxXl+EVf27c zly$n9J5)pbcdzEL`GLO!9pIvC*j=NDB z>iQ!4KQ&~@%WvNozWczbA!B~r{8pF$eTUOS*8FvQ^Y1?hB@=X+LZosFtNw{Su7j3R4(nTairqR=l3arvA1e_FCYp(^c1$RhuisI9mww7+%p!5=OC|+5#AH| zx(B&#{Kl?MGPKVdn3~)<`MAtgS@mYOzWlRezCE6Q71KV-VC5GkHv>A_X8M!TzJLr) z4ViiJp1hmAx2do1ap@gHpX>g<56_Sm+zH=>!a{705(ZNNM;;=>n_CYH%DZ>wgl&p9iqEXi}r1QO4S1|1wsmXXgJ z3Mb42CdC*;1WMZw)y9Uj^$k0+Hmq9zH!+fH(V%}PYYy2r34mVywDx3oz{(Kb) z*eeGdcAg7^xY5@CrL;Zyrr?mH@zJY3G4GD&OO#Qpk`Er|0b=)MiY8y;RNxFEl|~3} z%c7p0d|MtjMxY_%f4qBJsg%tG5u>Lu@PQ9qg-V_d93~CcRa+XV&G!ucj~$`$U42>1 zd&0GS4*?L6Q1pEw?5q_I?_f!H-X{r~ZP16~j7PSDn@E^&SlGF@v%y6V*}@d46g#!v zIUF7A%!HJEjogP&Y|J@)prxk@5MV-fY=BG{7!$7BcH3T5=%|%~2nyv6u*~ z6SH(e*aR$rCf5oj4IhyKv2k=7+B~R_ zgN@J8X*)dFg@ZDXbS-^2)4S9P0qCTi{dL^Jp7pVn`hJoJW z;JOh;+eX)7Onwc9FsZ)*>s^SbRg_#Z!xFi%_~(S1v=ICVz>`IGqNd~};vOK6_RI){ zl4*{TzTCKE(vng;$7)JRE`+L3fz%-fUJ}>J?HO)U`|Co@0P^P+i1MT)@3;&C0AH;Q z#*)L$bg~nijcI&8tf-iVGqmhxyzqYp_B96Unf)tW%-V9KK`RCFc@rmADcOJspvuBQr|M2M~bM6z|#u zrS$?pbr%DH?vWXYJ0MFTnQEp?toF(YgEo_i#ko#g+CPj&Kb0iAMotlFHA2wHtH%G6FAvm=Yp#oJrik0S)t}|2hUX5s4P6oi_ za4r=lzE1DK)BzKYV4+AJMZZVDT2sUvTK02QNEG1$f)F|#s-)_K(-YF5YX2Gv<{;nO-4Sic?+zN-B@dt{@$a>jMG( z?~=J{pYryGEE(BkO!Tm<+?iBpEbG=T)*MI){=+H6} zg`-;N`y(I~prqjC$nm`eWaVu2)WnbLwW^1c95Q~C8kruiKMH`3B<9^1vun{GjjyMf zfV@07fIpZu_Cytd#aA>UkwF%!rzajCbqnhd23zKxBoB&m z9c~G>jl%6ZMY~tpxD%=_XtG2Xz}>NF-kn~+I^x&|^tsq`c-~VkQO%MM3LB3*d=K$d z{v`=SehRf2odANTjYOCCd{rsoIQx#=m^QPw7Lf9=5K|oD(ZIbI4k5mG3p|X;@A!r< zVV|_rs+tkd9l`n$5ejuBhADB;*Let;5b4>&Tw-MX7_XnQ3=tU7p~ZzY(9AmSPP$Ov zki-E1vqs?(Z^?)4PXz(M^tgP{a_g18b-FAt-mV7lhi!n8PMOc2js2*7_-=hS5_o=8 zKuh&k3`$-Fhja}~gtGHtc>FOp_pk4?2Tq*0IOQplK@zUeOUIIwEB|qKGKC50=#?~# zEE$X6DZxPeoocT^IiqnKm&`k$wD3^Bh(NCqAW=4rOjf0Gs{n~+(>}05k#?{q`H+PD z1Ei3O06g-+1rSMaQ$-R>J+%NV8}l~hW&C61?@5BVXKq?WFHf2lf3wRF=i&XuM0HGF z*R1rjmf=Z((s@(3Ly#y5qOiz@XS%YH<8-NMau>HR;1|l|>CdEEyfsJmh;zv5U!Az3 zmc)!rj=cd#6cnwb^M&$4w_OflDY-nY$I93tD^hPgZ0H|5_0G z{hz&8i39S*qgx=7TKJO-yr5F_N>l>Jo^Y3AZasPUu~v(D$xgfTO`ar54FGn3fgji) zjWGyyC{Az4JV{SeXC(R(~Vhs_%tDqDtW0!St&KNyqGKd|AOADz}%Er??K3UYs3idT{1GdmRe9!(vY6cTrF%NB(q zdes1OfAO6Acw&Q?9+qe(i@{r}AaknqbA}MxBqZOmrUK6n5MY^>6qd##1mE;bN#4M7 zWAITDc+S@Yq^14&NqU@720+eephHitr8c~!oi55u_?BA3se`gdnJ$BSZ_B+OhVb-V z+!RHPu;7d7vA67H`VoKw64$f5;;S5C_Z^oHPf6Ug_EYA=jbq_jf^I*z}>#m3PO;vmK<3JsonZ{%tI_Tr}R$ow`!LSYc7VyHl~7NpV0)I1&}aZ0w% z5c%_K+^ry_Z#?obG6g0oiIOu_ypp01W~N}^Xa|&~al!%K!h^*Hsm26v0?LjEe0hs> zWrNZbV;()E8nciVc2!V0!vXKD5a)gue0`wPp#Q7=>8hA&z9p%b%m{4e4Q@C7H z3DqjRV_e_BKP#5J1OW@bt1~e*Wz&HrZ9wl`g8MVV=^u{#2?W!Yn##7iQJdQ9L>SA` z)NmAc($d6IDxDILxD12|B}io>O5Vn8fF~f_hF}jMRJ0H$3a*_E_B_yNMO<}J*7wy1 zb^>%A3043?fgEV6B`aY=Frn0Byt#HR_z3;ErIjO}F-1#}Tor}CpzL13*&zsG$}n$i zq!^&Q7QkrN40+@EUjG2da#3YKn06qq8eFS|yQL28{tm)KJL{j$;kyrbJayrsduv#8 za>Nc?bUPxahpGjk^PM9?fhDzoTW_0sGF_e=zNu4irh|geiHJ*BLKsv7^#>a>$>3-z z;j#|FNI`e)wqwijqaR0r6Hg)dFub;M>k8CzO$07-b`OPUQ)@vc!5_bRVQV`Iapr?> zJANH-jlUBRwT}=p;rQBwU_?1s`@P$SyEEUi$JMj5_)Citk@1PET|AZ0w(WeS=h!iMD$Mby%7)2t6CnZK?p)5H8&5dXb3DFwC-7YA?WQJp&l^V!(`I>(-5u{c z7gKwR@)`!B4);ws@H!H7DDaz!&ePrmC0zVHhPC9h{nMIC>D;||h5>_@IkU}a1O!Ut z56dv40cw*j`?N%=!`(aG*@p?cF;?nC2g%+ekRy0vq!VuzTJ90*0zf&d9FiZ{#l4Rc zr8XsU9tU_I%hpN@R(huNEEtNP8FXnGY>ytkd5{3N)Q)e!=5%Pl3b-*KxpvLj6^E%;xUG=2X)_@@ew!RB2iA1{}jMi!I7Qr0|PO;OaM7ykxg_$7`0HAvo8DLn4aqQ1?__Hx zylC6PsT*_h4`N3^_hH!;zu3(*4P}N#y~8OzBBIvzvH|Of9tMH;S68O0OH)CeBRbE0 zftY(N)H@BlI={j+lYmY-I@63A)U(r4*Q3nX-&FU_05o}JUx#Zs=*Y4+^NLcv)^Na64ihOvvsJXPbQO>u#>($)eSKpjp{y6`t zr~K8H`uv}luVVhb0%WHlbM`YIHh0A+hoGJ5Ve>b42>fGzl3Eh#uNOJGq?xcJQBf+@ zzjR=JN%qqvoa}P2(X!%&1f>hh%&W_)&HieO%TwQ%wVFM2%wJD=yf)As1fPF0YW6v=01Z%R#$F%HI4emuKNw zNBbAY&G!0FvQ7PDs^V9-oE1mG>5vPH{?F&aE7)9LGNJ|8g4OBqvJRZ|QQX(vH1nOc z9T*-_=)I7mb~Qw>!cD(VPkvgL!~uThAEmVm=Ffec6aba(f7Ic`*10}S=D^O@pS1Dj z|FS=I9^Gd%`AHTFz7pV=Dzd+62=P^){WbaC|H<0+CyXMcbDV}yVShgN6w+j#)x||M zH(4%tS}I#xDln~ju35@^5RkXdnj~))=^*w{Esb!Ssgb}-qYddqV77Ee&7Kj;v8Zgq z`{jtB`-6Rk!7gLDLw*4P0r@dMtICcB$ec%g)j3As4Dc`JALAv~m>iQK{LxpU7pvaF z3RagrfI#gDx6(@#nMLN6~XAFw?bM2Eg)LI>B#CvQ5F@c zXXP~!1@+>^`jq1OlY&z^#Z$uEwzlu1liC8lr!1ny(xO@w7wKl?)vut|m${^PH7WS_0u z3J5|@gM@{KhlKz

hX^kC2g)la!T~mzbHFo1C4VpP-?lqok##r91$LtE>yEgg*cx zMgR*+PD2C&MuQqiPD=nShd>7aD1*Vsg*wIn8iytT1h=k*u_A;k001zAAKin}BZkGt zgDWP3v=prFhl;22^Yr!h_xSnx`~01$?*N@Zcr_>%iW>mb4VsbA$%-4vgsm!&AmTDZ zMqJ@I)B->afdrix95jT%3jz(DSR-T%5ye3TE{K?UfI&cj@%ri9|H-qb&!0epq6&HQ zkcN;rJnoRV4nT&IHKNJ@@Sz4TLm~oLTqPuBAtdLH7E1cjNr8_@7y$Soa6ln&g0N~; z0svysn>mH*-OIPH-@kwx{kw|@1%M%h7!INJA<>5&1tLcVAfUiTLoF6;ojB~!0EmVW zFFfpI>5`@;oPYpu)rsNOgfas=M;Pa#z_@ek-p#xBqrtTc(egHEgk~oc4iFj=&Jfc> z5ELp~r6hppLOTZB8cxXgppLB>K;Qxb8S*FJZTaP>V#bSO{&-ylr=AOHXm zlyK1x7XVNI45z&yfB+w$P+%_r3?RY?0TL4AkVWEXx6hEPhglJThMEbX zo0e+osi?*`pQx<1>MEe5rYh^Kw4S=^tGMQ>>u#~u>g%t-x^wHU#1?C8PrU}K?6S2E zd+f8&Mr%s4%vNhHpUz6F?Y7)jLhZHSh8s|}-Ii;v|F++XtM0mlkbCaC@amc_yYzzV zZoK&B`{}&y2%*Ad4%OHputTWuB`ZtZkeYx71Ej+U09$*nz7$uiBfqOG*qlnoIS9e8 zMu@QSDlm@bbcJ*wZq^2wZB3VLc3{-vpo0@Lpg`#kD4>v( z)J8~M(lslfz+ypp1AM~@-Yn6=3S9q?H;cn50fXCxDDi>`HDvws434YNS`AWry&Mc9 zaG1d}FI=Sq&WSpK#Nsm`w!@Y$*tN>bXU8u4|2@4bag+uch%f*(;(V}#5d)?CLI4Ol zp@Is8n4pf(g30t8rq zTM-i1rV~aKFw7D#08qjXw|p=I5E&SNAe69x(`djvKybhSWF#!5&F+B^yoV0}P&!0F zX%Gm3NK#JYg#1Yj0>xv1Xll?NCuG1TFc1I-nF9?ImT&g9Xz9gQ+!8Pj-bU#S~3(sV}%WCI1DZ=CzD4+(2&}NCnh~{5FA*G3kl&y z`INGTd4#1ySaTlqxo!ji*juJHh652q4w2!Yi|Y!3O950UlI~#0C6~#}OhkZ<7W5%4 zh5>*Nm2nVf90UaR2E;??q7b23AOg({s6Zj%0{Fd7ni5F>01S1_P&z>g#dCr}uVbDnmFWWT(||!+Inl(( zQkFH4P%msr2nw81p5Z700O+J4|6mfwWbQFSg&@$Ley(BwE*Pjz1=@s_t|Ay5_!;sT zl7T@OMg)n2{Kp^_*qCv4B zjuHmIA`rCD3FOIRS0J#29e{5MOQ1_*fB+*I(Z~rUxQuL^AhID0A)bXWUlVr9SZ0!d ziiB8#$Ov!)BUEVtY*9e~fVcuNu_&7qAYUO;NEw!vrT`?jS!d`LYW%JimFlPG>BaXVe$)KLwM12 z`NiuhN+19xnD@Y0qyYd9#wQAZpk5Fr%u;B8;0i}@0|T%WVM@@T1aK(AAZEo72CxAO zn|O9lXg~opTomSV;FTecF-Z#0fG3>z#%F6n0|>xi8T*(|c5T37aZKc`LU9N zV;BtBxX4gunhON*+9g{#AT=OsPNU4_r6pkl=QDw5uS{mRn!o@6*gz7x%;u#X;RI-& zh5-&h=Q`W@&UntVp7+e>KKuF4fDW{s4S*5=7~lkyY_p=hoP!v+fCZ3_w4^6Z=}KGr z(wNS)rZ>&$PD|PaCNaptnioy#Qk(kJs7|%2SIz2HyZY6zj **Note:** -> If you're using an HTTPS encrypted socket, keep in mind that only +> **Note**: If you're using an HTTPS encrypted socket, keep in mind that only > TLS1.0 and greater are supported. Protocols SSLv3 and under are not > supported anymore for security reasons. @@ -135,18 +138,21 @@ time using multiple `-H` options: ```bash # listen using the default unix socket, and on 2 specific IP addresses on this host. + $ sudo dockerd -H unix:///var/run/docker.sock -H tcp://192.168.59.106 -H tcp://10.10.10.2 ``` The Docker client will honor the `DOCKER_HOST` environment variable to set the -`-H` flag for the client. +`-H` flag for the client. Use **one** of the following commands: ```bash $ docker -H tcp://0.0.0.0:2375 ps -# or +``` + +```bash $ export DOCKER_HOST="tcp://0.0.0.0:2375" + $ docker ps -# both are equal ``` Setting the `DOCKER_TLS_VERIFY` environment variable to any value other than @@ -164,7 +170,7 @@ The Docker client will honor the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables (or the lowercase versions thereof). `HTTPS_PROXY` takes precedence over `HTTP_PROXY`. -### Bind Docker to another host/port or a Unix socket +#### Bind Docker to another host/port or a Unix socket > **Warning**: > Changing the default `docker` daemon binding to a @@ -230,7 +236,7 @@ $ docker pull ubuntu $ docker -H tcp://127.0.0.1:2375 pull ubuntu ``` -### Daemon storage-driver option +### Daemon storage-driver The Docker daemon has support for several different image layer storage drivers: `aufs`, `devicemapper`, `btrfs`, `zfs`, `overlay` and `overlay2`. @@ -267,22 +273,20 @@ the same file can share a single page cache entry (or entries), it makes `overlay` as efficient with memory as `aufs` driver. Call `dockerd -s overlay` to use it. -> **Note:** -> As promising as `overlay` is, the feature is still quite young and should not -> be used in production. Most notably, using `overlay` can cause excessive -> inode consumption (especially as the number of images grows), as well as -> being incompatible with the use of RPMs. +> **Note**: As promising as `overlay` is, the feature is still quite young and +> should not be used in production. Most notably, using `overlay` can cause +> excessive inode consumption (especially as the number of images grows), as +> well as > being incompatible with the use of RPMs. The `overlay2` uses the same fast union filesystem but takes advantage of [additional features](https://lkml.org/lkml/2015/2/11/106) added in Linux kernel 4.0 to avoid excessive inode consumption. Call `dockerd -s overlay2` to use it. -> **Note:** -> Both `overlay` and `overlay2` are currently unsupported on `btrfs` or any -> Copy on Write filesystem and should only be used over `ext4` partitions. +> **Note**: Both `overlay` and `overlay2` are currently unsupported on `btrfs` +> or any Copy on Write filesystem and should only be used over `ext4` partitions. -### Storage driver options +### Options per storage driver Particular storage-driver can be configured with options specified with `--storage-opt` flags. Options for `devicemapper` are prefixed with `dm`, @@ -290,380 +294,376 @@ options for `zfs` start with `zfs` and options for `btrfs` start with `btrfs`. #### Devicemapper options -* `dm.thinpooldev` +##### `dm.thinpooldev` - Specifies a custom block storage device to use for the thin pool. +Specifies a custom block storage device to use for the thin pool. - If using a block device for device mapper storage, it is best to use `lvm` - to create and manage the thin-pool volume. This volume is then handed to Docker - to exclusively create snapshot volumes needed for images and containers. +If using a block device for device mapper storage, it is best to use `lvm` +to create and manage the thin-pool volume. This volume is then handed to Docker +to exclusively create snapshot volumes needed for images and containers. - Managing the thin-pool outside of Engine makes for the most feature-rich - method of having Docker utilize device mapper thin provisioning as the - backing storage for Docker containers. The highlights of the lvm-based - thin-pool management feature include: automatic or interactive thin-pool - resize support, dynamically changing thin-pool features, automatic thinp - metadata checking when lvm activates the thin-pool, etc. +Managing the thin-pool outside of Engine makes for the most feature-rich +method of having Docker utilize device mapper thin provisioning as the +backing storage for Docker containers. The highlights of the lvm-based +thin-pool management feature include: automatic or interactive thin-pool +resize support, dynamically changing thin-pool features, automatic thinp +metadata checking when lvm activates the thin-pool, etc. - As a fallback if no thin pool is provided, loopback files are - created. Loopback is very slow, but can be used without any - pre-configuration of storage. It is strongly recommended that you do - not use loopback in production. Ensure your Engine daemon has a - `--storage-opt dm.thinpooldev` argument provided. +As a fallback if no thin pool is provided, loopback files are +created. Loopback is very slow, but can be used without any +pre-configuration of storage. It is strongly recommended that you do +not use loopback in production. Ensure your Engine daemon has a +`--storage-opt dm.thinpooldev` argument provided. - Example use: +###### Example: - ```bash - $ sudo dockerd --storage-opt dm.thinpooldev=/dev/mapper/thin-pool - ``` +```bash +$ sudo dockerd --storage-opt dm.thinpooldev=/dev/mapper/thin-pool +``` -* `dm.basesize` +##### `dm.basesize` - Specifies the size to use when creating the base device, which limits the - size of images and containers. The default value is 10G. Note, thin devices - are inherently "sparse", so a 10G device which is mostly empty doesn't use - 10 GB of space on the pool. However, the filesystem will use more space for - the empty case the larger the device is. +Specifies the size to use when creating the base device, which limits the +size of images and containers. The default value is 10G. Note, thin devices +are inherently "sparse", so a 10G device which is mostly empty doesn't use +10 GB of space on the pool. However, the filesystem will use more space for +the empty case the larger the device is. - The base device size can be increased at daemon restart which will allow - all future images and containers (based on those new images) to be of the - new base device size. +The base device size can be increased at daemon restart which will allow +all future images and containers (based on those new images) to be of the +new base device size. - Example use: +###### Examples - ```bash - $ sudo dockerd --storage-opt dm.basesize=50G - ``` +```bash +$ sudo dockerd --storage-opt dm.basesize=50G +``` - This will increase the base device size to 50G. The Docker daemon will throw an - error if existing base device size is larger than 50G. A user can use - this option to expand the base device size however shrinking is not permitted. +This will increase the base device size to 50G. The Docker daemon will throw an +error if existing base device size is larger than 50G. A user can use +this option to expand the base device size however shrinking is not permitted. - This value affects the system-wide "base" empty filesystem - that may already be initialized and inherited by pulled images. Typically, - a change to this value requires additional steps to take effect: +This value affects the system-wide "base" empty filesystem +that may already be initialized and inherited by pulled images. Typically, +a change to this value requires additional steps to take effect: - ```bash - $ sudo service docker stop - $ sudo rm -rf /var/lib/docker - $ sudo service docker start - ``` + ```bash +$ sudo service docker stop - Example use: +$ sudo rm -rf /var/lib/docker - ```bash - $ sudo dockerd --storage-opt dm.basesize=20G - ``` +$ sudo service docker start +``` -* `dm.loopdatasize` - > **Note**: - > This option configures devicemapper loopback, which should not - > be used in production. +##### `dm.loopdatasize` - Specifies the size to use when creating the loopback file for the - "data" device which is used for the thin pool. The default size is - 100G. The file is sparse, so it will not initially take up this - much space. +> **Note**: This option configures devicemapper loopback, which should not +> be used in production. - Example use: +Specifies the size to use when creating the loopback file for the +"data" device which is used for the thin pool. The default size is +100G. The file is sparse, so it will not initially take up this +much space. - ```bash - $ sudo dockerd --storage-opt dm.loopdatasize=200G - ``` +###### Example -* `dm.loopmetadatasize` +```bash +$ sudo dockerd --storage-opt dm.loopdatasize=200G +``` - > **Note**: - > This option configures devicemapper loopback, which should not - > be used in production. +##### `dm.loopmetadatasize` - Specifies the size to use when creating the loopback file for the - "metadata" device which is used for the thin pool. The default size - is 2G. The file is sparse, so it will not initially take up - this much space. +> **Note**: This option configures devicemapper loopback, which should not +> be used in production. - Example use: +Specifies the size to use when creating the loopback file for the +"metadata" device which is used for the thin pool. The default size +is 2G. The file is sparse, so it will not initially take up +this much space. - ```bash - $ sudo dockerd --storage-opt dm.loopmetadatasize=4G - ``` +###### Example -* `dm.fs` +```bash +$ sudo dockerd --storage-opt dm.loopmetadatasize=4G +``` - Specifies the filesystem type to use for the base device. The supported - options are "ext4" and "xfs". The default is "xfs" +##### `dm.fs` - Example use: +Specifies the filesystem type to use for the base device. The supported +options are "ext4" and "xfs". The default is "xfs" - ```bash - $ sudo dockerd --storage-opt dm.fs=ext4 - ``` +###### Example -* `dm.mkfsarg` +```bash +$ sudo dockerd --storage-opt dm.fs=ext4 +``` - Specifies extra mkfs arguments to be used when creating the base device. +##### `dm.mkfsarg` - Example use: +Specifies extra mkfs arguments to be used when creating the base device. - ```bash - $ sudo dockerd --storage-opt "dm.mkfsarg=-O ^has_journal" - ``` +###### Example -* `dm.mountopt` +```bash +$ sudo dockerd --storage-opt "dm.mkfsarg=-O ^has_journal" +``` - Specifies extra mount options used when mounting the thin devices. +##### `dm.mountopt` - Example use: +Specifies extra mount options used when mounting the thin devices. - ```bash - $ sudo dockerd --storage-opt dm.mountopt=nodiscard - ``` +###### Example -* `dm.datadev` +```bash +$ sudo dockerd --storage-opt dm.mountopt=nodiscard +``` - (Deprecated, use `dm.thinpooldev`) +##### `dm.datadev` - Specifies a custom blockdevice to use for data for the thin pool. +(Deprecated, use `dm.thinpooldev`) - If using a block device for device mapper storage, ideally both datadev and - metadatadev should be specified to completely avoid using the loopback - device. +Specifies a custom blockdevice to use for data for the thin pool. - Example use: +If using a block device for device mapper storage, ideally both `datadev` and +`metadatadev` should be specified to completely avoid using the loopback +device. - ```bash - $ sudo dockerd \ - --storage-opt dm.datadev=/dev/sdb1 \ - --storage-opt dm.metadatadev=/dev/sdc1 - ``` +###### Example -* `dm.metadatadev` +```bash +$ sudo dockerd \ + --storage-opt dm.datadev=/dev/sdb1 \ + --storage-opt dm.metadatadev=/dev/sdc1 +``` - (Deprecated, use `dm.thinpooldev`) +##### `dm.metadatadev` - Specifies a custom blockdevice to use for metadata for the thin pool. +(Deprecated, use `dm.thinpooldev`) - For best performance the metadata should be on a different spindle than the - data, or even better on an SSD. +Specifies a custom blockdevice to use for metadata for the thin pool. - If setting up a new metadata pool it is required to be valid. This can be - achieved by zeroing the first 4k to indicate empty metadata, like this: +For best performance the metadata should be on a different spindle than the +data, or even better on an SSD. - ```bash - $ dd if=/dev/zero of=$metadata_dev bs=4096 count=1 - ``` +If setting up a new metadata pool it is required to be valid. This can be +achieved by zeroing the first 4k to indicate empty metadata, like this: - Example use: +```bash +$ dd if=/dev/zero of=$metadata_dev bs=4096 count=1 +``` - ```bash - $ sudo dockerd \ - --storage-opt dm.datadev=/dev/sdb1 \ - --storage-opt dm.metadatadev=/dev/sdc1 - ``` +###### Example -* `dm.blocksize` +```bash +$ sudo dockerd \ + --storage-opt dm.datadev=/dev/sdb1 \ + --storage-opt dm.metadatadev=/dev/sdc1 +``` - Specifies a custom blocksize to use for the thin pool. The default - blocksize is 64K. +##### `dm.blocksize` - Example use: +Specifies a custom blocksize to use for the thin pool. The default +blocksize is 64K. - ```bash - $ sudo dockerd --storage-opt dm.blocksize=512K - ``` +###### Example -* `dm.blkdiscard` +```bash +$ sudo dockerd --storage-opt dm.blocksize=512K +``` - Enables or disables the use of blkdiscard when removing devicemapper - devices. This is enabled by default (only) if using loopback devices and is - required to resparsify the loopback file on image/container removal. +##### `dm.blkdiscard` - Disabling this on loopback can lead to *much* faster container removal - times, but will make the space used in `/var/lib/docker` directory not be - returned to the system for other use when containers are removed. +Enables or disables the use of `blkdiscard` when removing devicemapper +devices. This is enabled by default (only) if using loopback devices and is +required to resparsify the loopback file on image/container removal. - Example use: +Disabling this on loopback can lead to *much* faster container removal +times, but will make the space used in `/var/lib/docker` directory not be +returned to the system for other use when containers are removed. - ```bash - $ sudo dockerd --storage-opt dm.blkdiscard=false - ``` +###### Examples -* `dm.override_udev_sync_check` +```bash +$ sudo dockerd --storage-opt dm.blkdiscard=false +``` - Overrides the `udev` synchronization checks between `devicemapper` and `udev`. - `udev` is the device manager for the Linux kernel. +##### `dm.override_udev_sync_check` - To view the `udev` sync support of a Docker daemon that is using the - `devicemapper` driver, run: +Overrides the `udev` synchronization checks between `devicemapper` and `udev`. +`udev` is the device manager for the Linux kernel. - ```bash - $ docker info - [...] - Udev Sync Supported: true - [...] - ``` +To view the `udev` sync support of a Docker daemon that is using the +`devicemapper` driver, run: - When `udev` sync support is `true`, then `devicemapper` and udev can - coordinate the activation and deactivation of devices for containers. +```bash +$ docker info +[...] +Udev Sync Supported: true +[...] +``` - When `udev` sync support is `false`, a race condition occurs between - the`devicemapper` and `udev` during create and cleanup. The race condition - results in errors and failures. (For information on these failures, see - [docker#4036](https://github.com/docker/docker/issues/4036)) +When `udev` sync support is `true`, then `devicemapper` and udev can +coordinate the activation and deactivation of devices for containers. - To allow the `docker` daemon to start, regardless of `udev` sync not being - supported, set `dm.override_udev_sync_check` to true: +When `udev` sync support is `false`, a race condition occurs between +the`devicemapper` and `udev` during create and cleanup. The race condition +results in errors and failures. (For information on these failures, see +[docker#4036](https://github.com/docker/docker/issues/4036)) - ```bash - $ sudo dockerd --storage-opt dm.override_udev_sync_check=true - ``` +To allow the `docker` daemon to start, regardless of `udev` sync not being +supported, set `dm.override_udev_sync_check` to true: - When this value is `true`, the `devicemapper` continues and simply warns - you the errors are happening. +```bash +$ sudo dockerd --storage-opt dm.override_udev_sync_check=true +``` - > **Note:** - > The ideal is to pursue a `docker` daemon and environment that does - > support synchronizing with `udev`. For further discussion on this - > topic, see [docker#4036](https://github.com/docker/docker/issues/4036). - > Otherwise, set this flag for migrating existing Docker daemons to - > a daemon with a supported environment. +When this value is `true`, the `devicemapper` continues and simply warns +you the errors are happening. -* `dm.use_deferred_removal` +> **Note**: The ideal is to pursue a `docker` daemon and environment that does +> support synchronizing with `udev`. For further discussion on this +> topic, see [docker#4036](https://github.com/docker/docker/issues/4036). +> Otherwise, set this flag for migrating existing Docker daemons to +> a daemon with a supported environment. - Enables use of deferred device removal if `libdm` and the kernel driver - support the mechanism. +##### `dm.use_deferred_removal` - Deferred device removal means that if device is busy when devices are - being removed/deactivated, then a deferred removal is scheduled on - device. And devices automatically go away when last user of the device - exits. +Enables use of deferred device removal if `libdm` and the kernel driver +support the mechanism. - For example, when a container exits, its associated thin device is removed. - If that device has leaked into some other mount namespace and can't be - removed, the container exit still succeeds and this option causes the - system to schedule the device for deferred removal. It does not wait in a - loop trying to remove a busy device. +Deferred device removal means that if device is busy when devices are +being removed/deactivated, then a deferred removal is scheduled on +device. And devices automatically go away when last user of the device +exits. - Example use: +For example, when a container exits, its associated thin device is removed. +If that device has leaked into some other mount namespace and can't be +removed, the container exit still succeeds and this option causes the +system to schedule the device for deferred removal. It does not wait in a +loop trying to remove a busy device. - ```bash - $ sudo dockerd --storage-opt dm.use_deferred_removal=true - ``` +###### Example -* `dm.use_deferred_deletion` +```bash +$ sudo dockerd --storage-opt dm.use_deferred_removal=true +``` - Enables use of deferred device deletion for thin pool devices. By default, - thin pool device deletion is synchronous. Before a container is deleted, - the Docker daemon removes any associated devices. If the storage driver - can not remove a device, the container deletion fails and daemon returns. +##### `dm.use_deferred_deletion` - Error deleting container: Error response from daemon: Cannot destroy container +Enables use of deferred device deletion for thin pool devices. By default, +thin pool device deletion is synchronous. Before a container is deleted, +the Docker daemon removes any associated devices. If the storage driver +can not remove a device, the container deletion fails and daemon returns. - To avoid this failure, enable both deferred device deletion and deferred - device removal on the daemon. +```none +Error deleting container: Error response from daemon: Cannot destroy container +``` - ```bash - $ sudo dockerd \ - --storage-opt dm.use_deferred_deletion=true \ - --storage-opt dm.use_deferred_removal=true - ``` +To avoid this failure, enable both deferred device deletion and deferred +device removal on the daemon. - With these two options enabled, if a device is busy when the driver is - deleting a container, the driver marks the device as deleted. Later, when - the device isn't in use, the driver deletes it. +```bash +$ sudo dockerd \ + --storage-opt dm.use_deferred_deletion=true \ + --storage-opt dm.use_deferred_removal=true +``` - In general it should be safe to enable this option by default. It will help - when unintentional leaking of mount point happens across multiple mount - namespaces. +With these two options enabled, if a device is busy when the driver is +deleting a container, the driver marks the device as deleted. Later, when +the device isn't in use, the driver deletes it. -* `dm.min_free_space` +In general it should be safe to enable this option by default. It will help +when unintentional leaking of mount point happens across multiple mount +namespaces. - Specifies the min free space percent in a thin pool require for new device - creation to succeed. This check applies to both free data space as well - as free metadata space. Valid values are from 0% - 99%. Value 0% disables - free space checking logic. If user does not specify a value for this option, - the Engine uses a default value of 10%. +##### `dm.min_free_space` - Whenever a new a thin pool device is created (during `docker pull` or during - container creation), the Engine checks if the minimum free space is - available. If sufficient space is unavailable, then device creation fails - and any relevant `docker` operation fails. +Specifies the min free space percent in a thin pool require for new device +creation to succeed. This check applies to both free data space as well +as free metadata space. Valid values are from 0% - 99%. Value 0% disables +free space checking logic. If user does not specify a value for this option, +the Engine uses a default value of 10%. - To recover from this error, you must create more free space in the thin pool - to recover from the error. You can create free space by deleting some images - and containers from the thin pool. You can also add more storage to the thin - pool. +Whenever a new a thin pool device is created (during `docker pull` or during +container creation), the Engine checks if the minimum free space is +available. If sufficient space is unavailable, then device creation fails +and any relevant `docker` operation fails. - To add more space to a LVM (logical volume management) thin pool, just add - more storage to the volume group container thin pool; this should automatically - resolve any errors. If your configuration uses loop devices, then stop the - Engine daemon, grow the size of loop files and restart the daemon to resolve - the issue. +To recover from this error, you must create more free space in the thin pool +to recover from the error. You can create free space by deleting some images +and containers from the thin pool. You can also add more storage to the thin +pool. - Example use: +To add more space to a LVM (logical volume management) thin pool, just add +more storage to the volume group container thin pool; this should automatically +resolve any errors. If your configuration uses loop devices, then stop the +Engine daemon, grow the size of loop files and restart the daemon to resolve +the issue. - ```bash - $ sudo dockerd --storage-opt dm.min_free_space=10% - ``` +###### Example -* `dm.xfs_nospace_max_retries` +```bash +$ sudo dockerd --storage-opt dm.min_free_space=10% +``` - Specifies the maximum number of retries XFS should attempt to complete - IO when ENOSPC (no space) error is returned by underlying storage device. +##### `dm.xfs_nospace_max_retries` - By default XFS retries infinitely for IO to finish and this can result - in unkillable process. To change this behavior one can set - xfs_nospace_max_retries to say 0 and XFS will not retry IO after getting - ENOSPC and will shutdown filesystem. +Specifies the maximum number of retries XFS should attempt to complete +IO when ENOSPC (no space) error is returned by underlying storage device. - Example use: +By default XFS retries infinitely for IO to finish and this can result +in unkillable process. To change this behavior one can set +xfs_nospace_max_retries to say 0 and XFS will not retry IO after getting +ENOSPC and will shutdown filesystem. - ```bash - $ sudo dockerd --storage-opt dm.xfs_nospace_max_retries=0 - ``` +###### Example + +```bash +$ sudo dockerd --storage-opt dm.xfs_nospace_max_retries=0 +``` #### ZFS options -* `zfs.fsname` +##### `zfs.fsname` - Set zfs filesystem under which docker will create its own datasets. - By default docker will pick up the zfs filesystem where docker graph - (`/var/lib/docker`) is located. +Set zfs filesystem under which docker will create its own datasets. +By default docker will pick up the zfs filesystem where docker graph +(`/var/lib/docker`) is located. - Example use: +###### Example - ```bash - $ sudo dockerd -s zfs --storage-opt zfs.fsname=zroot/docker - ``` +```bash +$ sudo dockerd -s zfs --storage-opt zfs.fsname=zroot/docker +``` #### Btrfs options -* `btrfs.min_space` +##### `btrfs.min_space` - Specifies the minimum size to use when creating the subvolume which is used - for containers. If user uses disk quota for btrfs when creating or running - a container with **--storage-opt size** option, docker should ensure the - **size** cannot be smaller than **btrfs.min_space**. +Specifies the minimum size to use when creating the subvolume which is used +for containers. If user uses disk quota for btrfs when creating or running +a container with **--storage-opt size** option, docker should ensure the +**size** cannot be smaller than **btrfs.min_space**. - Example use: +###### Example - ```bash - $ sudo dockerd -s btrfs --storage-opt btrfs.min_space=10G - ``` +```bash +$ sudo dockerd -s btrfs --storage-opt btrfs.min_space=10G +``` #### Overlay2 options -* `overlay2.override_kernel_check` +##### `overlay2.override_kernel_check` - Overrides the Linux kernel version check allowing overlay2. Support for - specifying multiple lower directories needed by overlay2 was added to the - Linux kernel in 4.0.0. However, some older kernel versions may be patched - to add multiple lower directory support for OverlayFS. This option should - only be used after verifying this support exists in the kernel. Applying - this option on a kernel without this support will cause failures on mount. +Overrides the Linux kernel version check allowing overlay2. Support for +specifying multiple lower directories needed by overlay2 was added to the +Linux kernel in 4.0.0. However, some older kernel versions may be patched +to add multiple lower directory support for OverlayFS. This option should +only be used after verifying this support exists in the kernel. Applying +this option on a kernel without this support will cause failures on mount. -## Docker runtime execution options +### Docker runtime execution options The Docker daemon relies on a [OCI](https://github.com/opencontainers/runtime-spec) compliant runtime @@ -706,9 +706,9 @@ This is the same example via the command line: $ sudo dockerd --add-runtime runc=runc --add-runtime custom=/usr/local/bin/my-runc-replacement ``` -> **Note**: defining runtime arguments via the command line is not supported. +> **Note**: Defining runtime arguments via the command line is not supported. -## Options for the runtime +#### Options for the runtime You can configure the runtime using options specified with the `--exec-opt` flag. All the flag's options have the `native` prefix. A @@ -738,7 +738,7 @@ Will make `hyperv` the default isolation technology on Windows. If no isolation value is specified on daemon start, on Windows client, the default is `hyperv`, and on Windows server, the default is `process`. -## Daemon DNS options +#### Daemon DNS options To set the DNS server for all Docker containers, use: @@ -753,8 +753,7 @@ To set the DNS search domain for all Docker containers, use: $ sudo dockerd --dns-search example.com ``` - -## Insecure registries +#### Insecure registries Docker considers a private registry either secure or insecure. In the rest of this section, *registry* is used for *private registry*, and `myregistry:5000` @@ -798,11 +797,11 @@ because its use creates security vulnerabilities it should ONLY be enabled for testing purposes. For increased security, users should add their CA to their system's list of trusted CAs instead of enabling `--insecure-registry`. -## Legacy Registries +##### Legacy Registries Enabling `--disable-legacy-registry` forces a docker daemon to only interact with registries which support the V2 protocol. Specifically, the daemon will not attempt `push`, `pull` and `login` to v1 registries. The exception to this is `search` which can still be performed on v1 registries. -## Running a Docker daemon behind an HTTPS_PROXY +#### Running a Docker daemon behind an HTTPS_PROXY When running inside a LAN that uses an `HTTPS` proxy, the Docker Hub certificates will be replaced by the proxy's certificates. These certificates @@ -819,7 +818,7 @@ This will only add the proxy and authentication to the Docker daemon's requests your `docker build`s and running containers will need extra configuration to use the proxy -## Default Ulimits +#### Default `ulimit` settings `--default-ulimit` allows you to set the default `ulimit` options to use for all containers. It takes the same options as `--ulimit` for `docker run`. If @@ -831,7 +830,7 @@ Be careful setting `nproc` with the `ulimit` flag as `nproc` is designed by Linu set the maximum number of processes available to a user, not to a container. For details please check the [run](run.md) reference. -## Nodes discovery +#### Node discovery The `--cluster-advertise` option specifies the `host:port` or `interface:port` combination that this particular daemon instance should use when advertising @@ -857,39 +856,16 @@ $ sudo dockerd \ The currently supported cluster store options are: -* `discovery.heartbeat` +| Option | Description | +|-----------------------|-------------| +| `discovery.heartbeat` | Specifies the heartbeat timer in seconds which is used by the daemon as a `keepalive` mechanism to make sure discovery module treats the node as alive in the cluster. If not configured, the default value is 20 seconds. | +| `discovery.ttl` | Specifies the TTL (time-to-live) in seconds which is used by the discovery module to timeout a node if a valid heartbeat is not received within the configured ttl value. If not configured, the default value is 60 seconds. | +| `kv.cacertfile` | Specifies the path to a local file with PEM encoded CA certificates to trust. | +| `kv.certfile` | Specifies the path to a local file with a PEM encoded certificate. This certificate is used as the client cert for communication with the Key/Value store. | +| `kv.keyfile` | Specifies the path to a local file with a PEM encoded private key. This private key is used as the client key for communication with the Key/Value store. | +| `kv.path` | Specifies the path in the Key/Value store. If not configured, the default value is 'docker/nodes'. | - Specifies the heartbeat timer in seconds which is used by the daemon as a - keepalive mechanism to make sure discovery module treats the node as alive - in the cluster. If not configured, the default value is 20 seconds. - -* `discovery.ttl` - - Specifies the ttl (time-to-live) in seconds which is used by the discovery - module to timeout a node if a valid heartbeat is not received within the - configured ttl value. If not configured, the default value is 60 seconds. - -* `kv.cacertfile` - - Specifies the path to a local file with PEM encoded CA certificates to trust - -* `kv.certfile` - - Specifies the path to a local file with a PEM encoded certificate. This - certificate is used as the client cert for communication with the - Key/Value store. - -* `kv.keyfile` - - Specifies the path to a local file with a PEM encoded private key. This - private key is used as the client key for communication with the - Key/Value store. - -* `kv.path` - - Specifies the path in the Key/Value store. If not configured, the default value is 'docker/nodes'. - -## Access authorization +#### Access authorization Docker's access authorization can be extended by authorization plugins that your organization can purchase or build themselves. You can install one or more @@ -914,7 +890,7 @@ For information about how to create an authorization plugin, see [authorization plugin](../../extend/plugins_authorization.md) section in the Docker extend section of this documentation. -## Daemon user namespace options +#### Daemon user namespace options The Linux kernel [user namespace support](http://man7.org/linux/man-pages/man7/user_namespaces.7.html) provides additional security by enabling a process, and therefore a container, to have a unique range of user and @@ -947,7 +923,7 @@ and provided subordinate uid and gid ranges. This default user will be named > pull`, `docker push`, and container startup as users expect with > user namespaces disabled. -### Starting the daemon with user namespaces enabled +##### Start the daemon with user namespaces enabled To enable user namespace support, start the daemon with the `--userns-remap` flag, which accepts values in the following formats: @@ -994,7 +970,7 @@ with user namespaces enabled or not. If the daemon is configured with user namespaces, the Security Options entry in the response will list "userns" as one of the enabled security features. -#### Behavior differences when user namespaces are enabled +##### Behavior differences when user namespaces are enabled When you start the Docker daemon with `--userns-remap`, Docker segregates the graph directory where the images are stored by adding an extra directory with a name corresponding to the @@ -1007,7 +983,7 @@ images and container layers, are also owned by the new UID and GID. To set the o correctly, you need to re-pull the images and restart the containers after starting the daemon with `--userns-remap`. -### Detailed information on `subuid`/`subgid` ranges +##### Detailed information on `subuid`/`subgid` ranges Given potential advanced use of the subordinate ID ranges by power users, the following paragraphs define how the Docker daemon currently uses the range entries @@ -1030,7 +1006,7 @@ following algorithm to create the mapping ranges: 2. Map segments will be created from each range in increasing value with a length matching the length of each segment. Therefore the range segment with the lowest numeric starting value will be equal to the remapped root, and continue up through host uid/gid equal to the range segment length. As an example, if the lowest segment starts at ID 1000 and has a length of 100, then a map of 1000 -> 0 (the remapped root) up through 1100 -> 100 will be created from this segment. If the next segment starts at ID 10000, then the next map will start with mapping 10000 -> 101 up to the length of this second segment. This will continue until no more segments are found in the subordinate files for this user. 3. If more than five range segments exist for a single user, only the first five will be utilized, matching the kernel's limitation of only five entries in `/proc/self/uid_map` and `proc/self/gid_map`. -### Disable user namespace for a container +##### Disable user namespace for a container If you enable user namespaces on the daemon, all containers are started with user namespaces enabled. In some situations you might want to disable @@ -1040,7 +1016,7 @@ To enable those advanced features for a specific container use `--userns=host` in the `run/exec/create` command. This option will completely disable user namespace mapping for the container's user. -### User namespace known restrictions +##### User namespace known restrictions The following standard Docker features are currently incompatible when running a Docker daemon with user namespaces enabled: @@ -1063,7 +1039,7 @@ process. The most notable restriction that we are aware of at this time is the inability to use `mknod`. Permission will be denied for device creation even as container `root` inside a user namespace. -## Miscellaneous options +### Miscellaneous options IP masquerading uses address translation to allow containers without a public IP to talk to other machines on the Internet. This may interfere with some @@ -1078,7 +1054,7 @@ set like this: export DOCKER_TMPDIR=/mnt/disk2/tmp /usr/local/bin/dockerd -D -g /var/lib/docker -H unix:// > /var/lib/docker-machine/docker.log 2>&1 -## Default cgroup parent +#### Default cgroup parent The `--cgroup-parent` option allows you to set the default cgroup parent to use for containers. If this option is not set, it defaults to `/docker` for @@ -1105,7 +1081,7 @@ This setting can also be set per container, using the `--cgroup-parent` option on `docker create` and `docker run`, and takes precedence over the `--cgroup-parent` option on the daemon. -## Daemon Metrics +#### Daemon metrics The `--metrics-addr` option takes a tcp address to serve the metrics API. This feature is still experimental, therefore, the daemon must be running in experimental @@ -1119,7 +1095,7 @@ If you are running a prometheus server you can add this address to your scrape c to have prometheus collect metrics on Docker. For more information on prometheus you can view the website [here](https://prometheus.io/). -```yml +```none scrape_configs: - job_name: 'docker' static_configs: @@ -1130,7 +1106,7 @@ Please note that this feature is still marked as experimental as metrics and met names could change while this feature is still in experimental. Please provide feedback on what you would like to see collected in the API. -## Daemon configuration file +#### Daemon configuration file The `--config-file` option allows you to set any configuration option for the daemon in a JSON format. This file uses the same flag names as keys, @@ -1145,7 +1121,7 @@ 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. Options that are not present in the file are ignored when the daemon starts. -### Linux configuration file +##### On Linux The default location of the configuration file on Linux is `/etc/docker/daemon.json`. The `--config-file` flag can be used to specify a @@ -1229,7 +1205,7 @@ This is a full example of the allowed configuration options on Linux: } ``` -### Windows configuration file +##### On Windows The default location of the configuration file on Windows is `%programdata%\docker\config\daemon.json`. The `--config-file` flag can be @@ -1276,7 +1252,7 @@ This is a full example of the allowed configuration options on Windows: } ``` -### Configuration reloading +#### Configuration reload behavior Some options can be reconfigured when the daemon is running without requiring to restart the process. We use the `SIGHUP` signal in Linux to reload, and a global event @@ -1312,7 +1288,7 @@ Configuration reload will log a warning message if it detects a change in previously configured cluster configurations. -## Running multiple daemons +### Run multiple daemons > **Note:** Running multiple daemons on a single host is considered as "experimental". The user should be aware of > unsolved problems. This solution may not work properly in some cases. Solutions are currently under development @@ -1325,7 +1301,7 @@ by providing them as flags, or by using a [daemon configuration file](#daemon-co The following daemon options must be configured for each daemon: -```bash +```none -b, --bridge= Attach containers to a network bridge --exec-root=/var/run/docker Root of the Docker execdriver -g, --graph=/var/lib/docker Root of the Docker runtime diff --git a/docs/reference/commandline/events.md b/docs/reference/commandline/events.md index 71f07fc124..d4599adcc5 100644 --- a/docs/reference/commandline/events.md +++ b/docs/reference/commandline/events.md @@ -28,29 +28,90 @@ Options: --until string Stream events until this timestamp ``` +## Description + +Use `docker events` to get real-time events from the server. These events differ +per Docker object type. + +### Object types + +#### Containers + Docker containers report the following events: - attach, commit, copy, create, destroy, detach, die, exec_create, exec_detach, exec_start, export, health_status, kill, oom, pause, rename, resize, restart, start, stop, top, unpause, update +- `attach` +- `commit` +- `copy` +- `create` +- `destroy` +- `detach` +- `die` +- `exec_create` +- `exec_detach` +- `exec_start` +- `export` +- `health_status` +- `kill` +- `oom` +- `pause` +- `rename` +- `resize` +- `restart` +- `start` +- `stop` +- `top` +- `unpause` +- `update` + +#### Images Docker images report the following events: - delete, import, load, pull, push, save, tag, untag +- `delete` +- `import` +- `load` +- `pull` +- `push` +- `save` +- `tag` +- `untag` + +#### Plugins Docker plugins report the following events: - install, enable, disable, remove +- `install` +- `enable` +- `disable` +- `remove` + +#### Volumes Docker volumes report the following events: - create, mount, unmount, destroy +- `create` +- `mount` +- `unmount` +- `destroy` + +#### Networks Docker networks report the following events: - create, connect, disconnect, destroy +- `create` +- `connect` +- `disconnect` +- `destroy` -Docker daemon reports the following events: +#### Daemons - reload +Docker daemons report the following events: + +- `reload` + +### Limiting, filtering, and formatting the output + +#### Limit events by time The `--since` and `--until` parameters can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed @@ -65,7 +126,7 @@ that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a fraction of a second no more than nine digits long. -## Filtering +#### Filtering The filtering flag (`-f` or `--filter`) format is of "key=value". If you would like to use multiple filters, pass multiple flags (e.g., @@ -91,7 +152,7 @@ The currently supported filters are: * type (`type=`) * volume (`volume=`) -## Format +#### Format If a format (`--format`) is specified, the given template will be executed instead of the default @@ -103,132 +164,190 @@ Lines. For information about JSON Lines, please refer to http://jsonlines.org/ . ## Examples +### Basic example + You'll need two shells for this example. **Shell 1: Listening for events:** - $ docker events +```bash +$ docker events +``` **Shell 2: Start and Stop containers:** - $ docker create --name test alpine:latest top - $ docker start test - $ docker stop test +```bash +$ docker create --name test alpine:latest top +$ docker start test +$ docker stop test +``` **Shell 1: (Again .. now showing events):** - 2017-01-05T00:35:58.859401177+08:00 container create 0fdb48addc82871eb34eb23a847cfd033dedd1a0a37bef2e6d9eb3870fc7ff37 (image=alpine:latest, name=test) - 2017-01-05T00:36:04.703631903+08:00 network connect e2e1f5ceda09d4300f3a846f0acfaa9a8bb0d89e775eb744c5acecd60e0529e2 (container=0fdb...ff37, name=bridge, type=bridge) - 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) - 2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) - 2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) - 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) - 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) +```none +2017-01-05T00:35:58.859401177+08:00 container create 0fdb48addc82871eb34eb23a847cfd033dedd1a0a37bef2e6d9eb3870fc7ff37 (image=alpine:latest, name=test) +2017-01-05T00:36:04.703631903+08:00 network connect e2e1f5ceda09d4300f3a846f0acfaa9a8bb0d89e775eb744c5acecd60e0529e2 (container=0fdb...ff37, name=bridge, type=bridge) +2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) +2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) +2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) +2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) +2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) +``` -**Show events in the past from a specified time:** +To exit the `docker events` command, use `CTRL+C`. - $ docker events --since 1483283804 - 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) - 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) - 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) - 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) - 2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) - 2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) - 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) - 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) +### Filter events by time - $ docker events --since '2017-01-05' - 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) - 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) - 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) - 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) - 2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) - 2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) - 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) - 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) +You can filter the output by an absolute timestamp or relative time on the host +machine, using the following different time syntaxes: - $ docker events --since '2013-09-03T15:49:29' - 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) - 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) - 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) - 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) - 2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) - 2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) - 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) - 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) +```bash +$ docker events --since 1483283804 +2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) +2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) +2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) +2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) +2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) +2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) +2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) +2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) -This example outputs all events that were generated in the last 3 minutes, -relative to the current time on the client machine: +$ docker events --since '2017-01-05' +2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) +2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) +2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) +2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) +2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) +2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) +2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) +2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) - $ docker events --since '10m' - 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) - 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) - 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) - 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) - 2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) - 2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) - 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) - 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) +$ docker events --since '2013-09-03T15:49:29' +2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) +2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) +2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) +2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) +2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) +2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) +2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) +2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) -**Filter events:** +$ docker events --since '10m' +2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) +2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) +2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) +2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) +2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) +2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) +2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) +2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) +``` - $ docker events --filter 'event=stop' - 2017-01-05T00:40:22.880175420+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) - 2017-01-05T00:41:17.888104182+08:00 container stop 2a8f...4e78 (image=alpine, name=kickass_brattain) +### Filter events by criteria - $ docker events --filter 'image=alpine' - 2017-01-05T00:41:55.784240236+08:00 container create d9cd...4d70 (image=alpine, name=happy_meitner) - 2017-01-05T00:41:55.913156783+08:00 container start d9cd...4d70 (image=alpine, name=happy_meitner) - 2017-01-05T00:42:01.106875249+08:00 container kill d9cd...4d70 (image=alpine, name=happy_meitner, signal=15) - 2017-01-05T00:42:11.111934041+08:00 container kill d9cd...4d70 (image=alpine, name=happy_meitner, signal=9) - 2017-01-05T00:42:11.119578204+08:00 container die d9cd...4d70 (exitCode=137, image=alpine, name=happy_meitner) - 2017-01-05T00:42:11.173276611+08:00 container stop d9cd...4d70 (image=alpine, name=happy_meitner) +The following commands show several different ways to filter the `docker event` +output. - $ docker events --filter 'container=test' - 2017-01-05T00:43:00.139719934+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) - 2017-01-05T00:43:09.259951086+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) - 2017-01-05T00:43:09.270102715+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) - 2017-01-05T00:43:09.312556440+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) +```bash +$ docker events --filter 'event=stop' - $ docker events --filter 'container=test' --filter 'container=d9cdb1525ea8' - 2017-01-05T00:44:11.517071981+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) - 2017-01-05T00:44:17.685870901+08:00 container start d9cd...4d70 (image=alpine, name=happy_meitner) - 2017-01-05T00:44:29.757658470+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=9) - 2017-01-05T00:44:29.767718510+08:00 container die 0fdb...ff37 (exitCode=137, image=alpine:latest, name=test) - 2017-01-05T00:44:29.815798344+08:00 container destroy 0fdb...ff37 (image=alpine:latest, name=test) +2017-01-05T00:40:22.880175420+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) +2017-01-05T00:41:17.888104182+08:00 container stop 2a8f...4e78 (image=alpine, name=kickass_brattain) - $ docker events --filter 'container=test' --filter 'event=stop' - 2017-01-05T00:46:13.664099505+08:00 container stop a9d1...e130 (image=alpine, name=test) +$ docker events --filter 'image=alpine' - $ docker events --filter 'type=volume' - 2015-12-23T21:05:28.136212689Z volume create test-event-volume-local (driver=local) - 2015-12-23T21:05:28.383462717Z volume mount test-event-volume-local (read/write=true, container=562f...5025, destination=/foo, driver=local, propagation=rprivate) - 2015-12-23T21:05:28.650314265Z volume unmount test-event-volume-local (container=562f...5025, driver=local) - 2015-12-23T21:05:28.716218405Z volume destroy test-event-volume-local (driver=local) +2017-01-05T00:41:55.784240236+08:00 container create d9cd...4d70 (image=alpine, name=happy_meitner) +2017-01-05T00:41:55.913156783+08:00 container start d9cd...4d70 (image=alpine, name=happy_meitner) +2017-01-05T00:42:01.106875249+08:00 container kill d9cd...4d70 (image=alpine, name=happy_meitner, signal=15) +2017-01-05T00:42:11.111934041+08:00 container kill d9cd...4d70 (image=alpine, name=happy_meitner, signal=9) +2017-01-05T00:42:11.119578204+08:00 container die d9cd...4d70 (exitCode=137, image=alpine, name=happy_meitner) +2017-01-05T00:42:11.173276611+08:00 container stop d9cd...4d70 (image=alpine, name=happy_meitner) - $ docker events --filter 'type=network' - 2015-12-23T21:38:24.705709133Z network create 8b11...2c5b (name=test-event-network-local, type=bridge) - 2015-12-23T21:38:25.119625123Z network connect 8b11...2c5b (name=test-event-network-local, container=b4be...c54e, type=bridge) +$ docker events --filter 'container=test' - $ docker events --filter 'type=plugin' (experimental) - 2016-07-25T17:30:14.825557616Z plugin pull ec7b...993f (name=tiborvass/sample-volume-plugin:latest) - 2016-07-25T17:30:14.888127370Z plugin enable ec7b...993f (name=tiborvass/sample-volume-plugin:latest) +2017-01-05T00:43:00.139719934+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) +2017-01-05T00:43:09.259951086+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) +2017-01-05T00:43:09.270102715+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) +2017-01-05T00:43:09.312556440+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) -**Format:** +$ docker events --filter 'container=test' --filter 'container=d9cdb1525ea8' - $ docker events --filter 'type=container' --format 'Type={{.Type}} Status={{.Status}} ID={{.ID}}' - Type=container Status=create ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 - Type=container Status=attach ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 - Type=container Status=start ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 - Type=container Status=resize ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 - Type=container Status=die ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 - Type=container Status=destroy ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 +2017-01-05T00:44:11.517071981+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) +2017-01-05T00:44:17.685870901+08:00 container start d9cd...4d70 (image=alpine, name=happy_meitner) +2017-01-05T00:44:29.757658470+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=9) +2017-01-05T00:44:29.767718510+08:00 container die 0fdb...ff37 (exitCode=137, image=alpine:latest, name=test) +2017-01-05T00:44:29.815798344+08:00 container destroy 0fdb...ff37 (image=alpine:latest, name=test) -**Format (as JSON Lines):** +$ docker events --filter 'container=test' --filter 'event=stop' +2017-01-05T00:46:13.664099505+08:00 container stop a9d1...e130 (image=alpine, name=test) + +$ docker events --filter 'type=volume' + +2015-12-23T21:05:28.136212689Z volume create test-event-volume-local (driver=local) +2015-12-23T21:05:28.383462717Z volume mount test-event-volume-local (read/write=true, container=562f...5025, destination=/foo, driver=local, propagation=rprivate) +2015-12-23T21:05:28.650314265Z volume unmount test-event-volume-local (container=562f...5025, driver=local) +2015-12-23T21:05:28.716218405Z volume destroy test-event-volume-local (driver=local) + +$ docker events --filter 'type=network' + +2015-12-23T21:38:24.705709133Z network create 8b11...2c5b (name=test-event-network-local, type=bridge) +2015-12-23T21:38:25.119625123Z network connect 8b11...2c5b (name=test-event-network-local, container=b4be...c54e, type=bridge) + +$ docker events --filter 'container=container_1' --filter 'container=container_2' + +2014-09-03T15:49:29.999999999Z07:00 container die 4386fb97867d (image=ubuntu-1:14.04) +2014-05-10T17:42:14.999999999Z07:00 container stop 4386fb97867d (image=ubuntu-1:14.04) +2014-05-10T17:42:14.999999999Z07:00 container die 7805c1d35632 (imager=redis:2.8) +2014-09-03T15:49:29.999999999Z07:00 container stop 7805c1d35632 (image=redis:2.8) + +$ docker events --filter 'type=volume' + +2015-12-23T21:05:28.136212689Z volume create test-event-volume-local (driver=local) +2015-12-23T21:05:28.383462717Z volume mount test-event-volume-local (read/write=true, container=562fe10671e9273da25eed36cdce26159085ac7ee6707105fd534866340a5025, destination=/foo, driver=local, propagation=rprivate) +2015-12-23T21:05:28.650314265Z volume unmount test-event-volume-local (container=562fe10671e9273da25eed36cdce26159085ac7ee6707105fd534866340a5025, driver=local) +2015-12-23T21:05:28.716218405Z volume destroy test-event-volume-local (driver=local) + +$ docker events --filter 'type=network' + +2015-12-23T21:38:24.705709133Z network create 8b111217944ba0ba844a65b13efcd57dc494932ee2527577758f939315ba2c5b (name=test-event-network-local, type=bridge) +2015-12-23T21:38:25.119625123Z network connect 8b111217944ba0ba844a65b13efcd57dc494932ee2527577758f939315ba2c5b (name=test-event-network-local, container=b4be644031a3d90b400f88ab3d4bdf4dc23adb250e696b6328b85441abe2c54e, type=bridge) +``` + +The `type=plugin` filter is experimental. + +```bash +$ docker events --filter 'type=plugin' + +2016-07-25T17:30:14.825557616Z plugin pull ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest) +2016-07-25T17:30:14.888127370Z plugin enable ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest) +``` + +### Format the output + +```bash +{% raw %} +$ docker events --filter 'type=container' --format 'Type={{.Type}} Status={{.Status}} ID={{.ID}}' + +Type=container Status=create ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 +Type=container Status=attach ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 +Type=container Status=start ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 +Type=container Status=resize ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 +Type=container Status=die ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 +Type=container Status=destroy ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 +{% endraw %} +``` + +#### Format as JSON + +```none +{% raw %} $ docker events --format '{{json .}}' + {"status":"create","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. {"status":"attach","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. {"Type":"network","Action":"connect","Actor":{"ID":"1b50a5bf755f6021dfa78e.. {"status":"start","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f42.. {"status":"resize","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. +{% endraw %} +``` diff --git a/docs/reference/commandline/exec.md b/docs/reference/commandline/exec.md index 38891c9ea0..df2ad6eae8 100644 --- a/docs/reference/commandline/exec.md +++ b/docs/reference/commandline/exec.md @@ -31,35 +31,61 @@ Options: -u, --user Username or UID (format: [:]) ``` +## Descriptino + The `docker exec` command runs a new command in a running container. The command started using `docker exec` only runs while the container's primary process (`PID 1`) is running, and it is not restarted if the container is restarted. -If the container is paused, then the `docker exec` command will fail with an error: - - $ docker pause test - test - $ docker ps - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 1ae3b36715d2 ubuntu:latest "bash" 17 seconds ago Up 16 seconds (Paused) test - $ docker exec test ls - FATA[0000] Error response from daemon: Container test is paused, unpause the container before exec - $ echo $? - 1 - ## Examples - $ docker run --name ubuntu_bash --rm -i -t ubuntu bash +### Run `docker exec` on a running container + +First, start a container. + +```bash +$ docker run --name ubuntu_bash --rm -i -t ubuntu bash +``` This will create a container named `ubuntu_bash` and start a Bash session. - $ docker exec -d ubuntu_bash touch /tmp/execWorks +Next, execute a command on the container. + +```bash +$ docker exec -d ubuntu_bash touch /tmp/execWorks +``` This will create a new file `/tmp/execWorks` inside the running container `ubuntu_bash`, in the background. - $ docker exec -it ubuntu_bash bash +Next, execute an interactive `bash` shell on the container. + +```bash +$ docker exec -it ubuntu_bash bash +``` This will create a new Bash session in the container `ubuntu_bash`. + +### Try to run `docker exec` on a paused container + +If the container is paused, then the `docker exec` command will fail with an error: + +```bash +$ docker pause test + +test + +$ docker ps + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +1ae3b36715d2 ubuntu:latest "bash" 17 seconds ago Up 16 seconds (Paused) test + +$ docker exec test ls + +FATA[0000] Error response from daemon: Container test is paused, unpause the container before exec + +$ echo $? +1 +``` diff --git a/docs/reference/commandline/export.md b/docs/reference/commandline/export.md index 1004fc30c0..9de509714a 100644 --- a/docs/reference/commandline/export.md +++ b/docs/reference/commandline/export.md @@ -25,19 +25,24 @@ Options: -o, --output string Write to a file, instead of STDOUT ``` +## Description + The `docker export` command does not export the contents of volumes associated with the container. If a volume is mounted on top of an existing directory in the container, `docker export` will export the contents of the *underlying* directory, not the contents of the volume. -Refer to [Backup, restore, or migrate data -volumes](https://docs.docker.com/engine/tutorials/dockervolumes/#backup-restore-or-migrate-data-volumes) in -the user guide for examples on exporting data in a volume. +Refer to [Backup, restore, or migrate data volumes](https://docs.docker.com/engine/tutorials/dockervolumes/#backup-restore-or-migrate-data-volumes) +in the user guide for examples on exporting data in a volume. ## Examples - $ docker export red_panda > latest.tar +Each of these commands has the same result. -Or +```bash +$ docker export red_panda > latest.tar +``` - $ docker export --output="latest.tar" red_panda +```bash +$ docker export --output="latest.tar" red_panda +``` diff --git a/docs/reference/commandline/history.md b/docs/reference/commandline/history.md index 00f88db35b..b68cc8695d 100644 --- a/docs/reference/commandline/history.md +++ b/docs/reference/commandline/history.md @@ -27,22 +27,30 @@ Options: -q, --quiet Only show numeric IDs ``` + +## Examples + To see how the `docker:latest` image was built: - $ docker history docker - IMAGE CREATED CREATED BY SIZE COMMENT - 3e23a5875458 8 days ago /bin/sh -c #(nop) ENV LC_ALL=C.UTF-8 0 B - 8578938dd170 8 days ago /bin/sh -c dpkg-reconfigure locales && loc 1.245 MB - be51b77efb42 8 days ago /bin/sh -c apt-get update && apt-get install 338.3 MB - 4b137612be55 6 weeks ago /bin/sh -c #(nop) ADD jessie.tar.xz in / 121 MB - 750d58736b4b 6 weeks ago /bin/sh -c #(nop) MAINTAINER Tianon Gravi `) - only remove images created before given timestamp + +The `until` filter can be Unix timestamps, date formatted +timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed +relative to the daemon machine’s time. Supported formats for date +formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, +`2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local +timezone on the daemon will be used if you do not provide either a `Z` or a +`+-00:00` timezone offset at the end of the timestamp. When providing Unix +timestamps enter seconds[.nanoseconds], where seconds is the number of seconds +that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap +seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a +fraction of a second no more than nine digits long. + +The following removes images created before `2017-01-04T00:00:00`: + +```bash +{% raw %} +$ docker images --format 'table {{.Repository}}\t{{.Tag}}\t{{.ID}}\t{{.CreatedAt}}\t{{.Size}}' +REPOSITORY TAG IMAGE ID CREATED AT SIZE +foo latest 2f287ac753da 2017-01-04 13:42:23 -0800 PST 3.98 MB +alpine latest 88e169ea8f46 2016-12-27 10:17:25 -0800 PST 3.98 MB +busybox latest e02e811dd08f 2016-10-07 14:03:58 -0700 PDT 1.09 MB + +$ docker image prune -a --force --filter "until=2017-01-04T00:00:00" + +Deleted Images: +untagged: alpine:latest +untagged: alpine@sha256:dfbd4a3a8ebca874ebd2474f044a0b33600d4523d03b0df76e5c5986cb02d7e8 +untagged: busybox:latest +untagged: busybox@sha256:29f5d56d12684887bdfa50dcd29fc31eea4aaf4ad3bec43daf19026a7ce69912 +deleted: sha256:e02e811dd08fd49e7f6032625495118e63f597eb150403d02e3238af1df240ba +deleted: sha256:e88b3f82283bc59d5e0df427c824e9f95557e661fcb0ea15fb0fb6f97760f9d9 + +Total reclaimed space: 1.093 MB + +$ docker images --format 'table {{.Repository}}\t{{.Tag}}\t{{.ID}}\t{{.CreatedAt}}\t{{.Size}}' + +REPOSITORY TAG IMAGE ID CREATED AT SIZE +foo latest 2f287ac753da 2017-01-04 13:42:23 -0800 PST 3.98 MB +{% endraw %} +``` + +The following removes images created more than 10 days (`240h`) ago: + +```bash +$ docker images + +REPOSITORY TAG IMAGE ID CREATED SIZE +foo latest 2f287ac753da 14 seconds ago 3.98 MB +alpine latest 88e169ea8f46 8 days ago 3.98 MB +debian jessie 7b0a06c805e8 2 months ago 123 MB +busybox latest e02e811dd08f 2 months ago 1.09 MB +golang 1.7.0 138c2e655421 4 months ago 670 MB + +$ docker image prune -a --force --filter "until=240h" + +Deleted Images: +untagged: golang:1.7.0 +untagged: golang@sha256:6765038c2b8f407fd6e3ecea043b44580c229ccfa2a13f6d85866cf2b4a9628e +deleted: sha256:138c2e6554219de65614d88c15521bfb2da674cbb0bf840de161f89ff4264b96 +deleted: sha256:ec353c2e1a673f456c4b78906d0d77f9d9456cfb5229b78c6a960bfb7496b76a +deleted: sha256:fe22765feaf3907526b4921c73ea6643ff9e334497c9b7e177972cf22f68ee93 +deleted: sha256:ff845959c80148421a5c3ae11cc0e6c115f950c89bc949646be55ed18d6a2912 +deleted: sha256:a4320831346648c03db64149eafc83092e2b34ab50ca6e8c13112388f25899a7 +deleted: sha256:4c76020202ee1d9709e703b7c6de367b325139e74eebd6b55b30a63c196abaf3 +deleted: sha256:d7afd92fb07236c8a2045715a86b7d5f0066cef025018cd3ca9a45498c51d1d6 +deleted: sha256:9e63c5bce4585dd7038d830a1f1f4e44cb1a1515b00e620ac718e934b484c938 +untagged: debian:jessie +untagged: debian@sha256:c1af755d300d0c65bb1194d24bce561d70c98a54fb5ce5b1693beb4f7988272f +deleted: sha256:7b0a06c805e8f23807fb8856621c60851727e85c7bcb751012c813f122734c8d +deleted: sha256:f96222d75c5563900bc4dd852179b720a0885de8f7a0619ba0ac76e92542bbc8 + +Total reclaimed space: 792.6 MB + +$ docker images + +REPOSITORY TAG IMAGE ID CREATED SIZE +foo latest 2f287ac753da About a minute ago 3.98 MB +alpine latest 88e169ea8f46 8 days ago 3.98 MB +busybox latest e02e811dd08f 2 months ago 1.09 MB +``` + +## Related commands * [system df](system_df.md) * [container prune](container_prune.md) diff --git a/docs/reference/commandline/images.md b/docs/reference/commandline/images.md index 3b9ea1fe17..e0e55524c0 100644 --- a/docs/reference/commandline/images.md +++ b/docs/reference/commandline/images.md @@ -35,6 +35,8 @@ Options: -q, --quiet Only show numeric IDs ``` +## Description + The default `docker images` will show all top level images, their repository and tags, and their size. @@ -51,21 +53,26 @@ An image will be listed more than once if it has multiple repository names or tags. This single image (identifiable by its matching `IMAGE ID`) uses up the `SIZE` listed only once. -### Listing the most recently created images +## Examples - $ docker images - REPOSITORY TAG IMAGE ID CREATED SIZE - 77af4d6b9913 19 hours ago 1.089 GB - committ latest b6fa739cedf5 19 hours ago 1.089 GB - 78a85c484f71 19 hours ago 1.089 GB - docker latest 30557a29d5ab 20 hours ago 1.089 GB - 5ed6274db6ce 24 hours ago 1.089 GB - postgres 9 746b819f315e 4 days ago 213.4 MB - postgres 9.3 746b819f315e 4 days ago 213.4 MB - postgres 9.3.5 746b819f315e 4 days ago 213.4 MB - postgres latest 746b819f315e 4 days ago 213.4 MB +### List the most recently created images -### Listing images by name and tag +```bash +$ docker images + +REPOSITORY TAG IMAGE ID CREATED SIZE + 77af4d6b9913 19 hours ago 1.089 GB +committ latest b6fa739cedf5 19 hours ago 1.089 GB + 78a85c484f71 19 hours ago 1.089 GB +docker latest 30557a29d5ab 20 hours ago 1.089 GB + 5ed6274db6ce 24 hours ago 1.089 GB +postgres 9 746b819f315e 4 days ago 213.4 MB +postgres 9.3 746b819f315e 4 days ago 213.4 MB +postgres 9.3.5 746b819f315e 4 days ago 213.4 MB +postgres latest 746b819f315e 4 days ago 213.4 MB +``` + +### List images by name and tag The `docker images` command takes an optional `[REPOSITORY[:TAG]]` argument that restricts the list to images that match the argument. If you specify @@ -74,11 +81,14 @@ given repository. For example, to list all images in the "java" repository, run this command : - $ docker images java - REPOSITORY TAG IMAGE ID CREATED SIZE - java 8 308e519aac60 6 days ago 824.5 MB - java 7 493d82594c15 3 months ago 656.3 MB - java latest 2711b1d6f3aa 5 months ago 603.9 MB +```bash +$ docker images java + +REPOSITORY TAG IMAGE ID CREATED SIZE +java 8 308e519aac60 6 days ago 824.5 MB +java 7 493d82594c15 3 months ago 656.3 MB +java latest 2711b1d6f3aa 5 months ago 603.9 MB +``` The `[REPOSITORY[:TAG]]` value must be an "exact match". This means that, for example, `docker images jav` does not match the image `java`. @@ -87,46 +97,57 @@ If both `REPOSITORY` and `TAG` are provided, only images matching that repository and tag are listed. To find all local images in the "java" repository with tag "8" you can use: - $ docker images java:8 - REPOSITORY TAG IMAGE ID CREATED SIZE - java 8 308e519aac60 6 days ago 824.5 MB +```bash +$ docker images java:8 + +REPOSITORY TAG IMAGE ID CREATED SIZE +java 8 308e519aac60 6 days ago 824.5 MB +``` If nothing matches `REPOSITORY[:TAG]`, the list is empty. - $ docker images java:0 - REPOSITORY TAG IMAGE ID CREATED SIZE +```bash +$ docker images java:0 -## Listing the full length image IDs +REPOSITORY TAG IMAGE ID CREATED SIZE +``` - $ docker images --no-trunc - REPOSITORY TAG IMAGE ID CREATED SIZE - sha256:77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182 19 hours ago 1.089 GB - committest latest sha256:b6fa739cedf5ea12a620a439402b6004d057da800f91c7524b5086a5e4749c9f 19 hours ago 1.089 GB - sha256:78a85c484f71509adeaace20e72e941f6bdd2b25b4c75da8693efd9f61a37921 19 hours ago 1.089 GB - docker latest sha256:30557a29d5abc51e5f1d5b472e79b7e296f595abcf19fe6b9199dbbc809c6ff4 20 hours ago 1.089 GB - sha256:0124422dd9f9cf7ef15c0617cda3931ee68346455441d66ab8bdc5b05e9fdce5 20 hours ago 1.089 GB - sha256:18ad6fad340262ac2a636efd98a6d1f0ea775ae3d45240d3418466495a19a81b 22 hours ago 1.082 GB - sha256:f9f1e26352f0a3ba6a0ff68167559f64f3e21ff7ada60366e2d44a04befd1d3a 23 hours ago 1.089 GB - tryout latest sha256:2629d1fa0b81b222fca63371ca16cbf6a0772d07759ff80e8d1369b926940074 23 hours ago 131.5 MB - sha256:5ed6274db6ceb2397844896966ea239290555e74ef307030ebb01ff91b1914df 24 hours ago 1.089 GB +### List the full length image IDs -## Listing image digests +```bash +$ docker images --no-trunc + +REPOSITORY TAG IMAGE ID CREATED SIZE + sha256:77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182 19 hours ago 1.089 GB +committest latest sha256:b6fa739cedf5ea12a620a439402b6004d057da800f91c7524b5086a5e4749c9f 19 hours ago 1.089 GB + sha256:78a85c484f71509adeaace20e72e941f6bdd2b25b4c75da8693efd9f61a37921 19 hours ago 1.089 GB +docker latest sha256:30557a29d5abc51e5f1d5b472e79b7e296f595abcf19fe6b9199dbbc809c6ff4 20 hours ago 1.089 GB + sha256:0124422dd9f9cf7ef15c0617cda3931ee68346455441d66ab8bdc5b05e9fdce5 20 hours ago 1.089 GB + sha256:18ad6fad340262ac2a636efd98a6d1f0ea775ae3d45240d3418466495a19a81b 22 hours ago 1.082 GB + sha256:f9f1e26352f0a3ba6a0ff68167559f64f3e21ff7ada60366e2d44a04befd1d3a 23 hours ago 1.089 GB +tryout latest sha256:2629d1fa0b81b222fca63371ca16cbf6a0772d07759ff80e8d1369b926940074 23 hours ago 131.5 MB + sha256:5ed6274db6ceb2397844896966ea239290555e74ef307030ebb01ff91b1914df 24 hours ago 1.089 GB +``` + +### List image digests Images that use the v2 or later format have a content-addressable identifier called a `digest`. As long as the input used to generate the image is unchanged, the digest value is predictable. To list image digest values, use the `--digests` flag: - $ docker images --digests - REPOSITORY TAG DIGEST IMAGE ID CREATED SIZE - localhost:5000/test/busybox sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf 4986bf8c1536 9 weeks ago 2.43 MB +```bash +$ docker images --digests +REPOSITORY TAG DIGEST IMAGE ID CREATED SIZE +localhost:5000/test/busybox sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf 4986bf8c1536 9 weeks ago 2.43 MB +``` When pushing or pulling to a 2.0 registry, the `push` or `pull` command output includes the image digest. You can `pull` using a digest value. You can also reference by digest in `create`, `run`, and `rmi` commands, as well as the `FROM` image reference in a Dockerfile. -## Filtering +### Filtering The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) @@ -138,133 +159,147 @@ The currently supported filters are: * before (`[:]`, `` or ``) - filter images created before given id or references * since (`[:]`, `` or ``) - filter images created since given id or references -##### Untagged images (dangling) +#### Show untagged images (dangling) - $ docker images --filter "dangling=true" +```bash +$ docker images --filter "dangling=true" - REPOSITORY TAG IMAGE ID CREATED SIZE - 8abc22fbb042 4 weeks ago 0 B - 48e5f45168b9 4 weeks ago 2.489 MB - bf747efa0e2f 4 weeks ago 0 B - 980fe10e5736 12 weeks ago 101.4 MB - dea752e4e117 12 weeks ago 101.4 MB - 511136ea3c5a 8 months ago 0 B +REPOSITORY TAG IMAGE ID CREATED SIZE + 8abc22fbb042 4 weeks ago 0 B + 48e5f45168b9 4 weeks ago 2.489 MB + bf747efa0e2f 4 weeks ago 0 B + 980fe10e5736 12 weeks ago 101.4 MB + dea752e4e117 12 weeks ago 101.4 MB + 511136ea3c5a 8 months ago 0 B +``` -This will display untagged images, that are the leaves of the images tree (not +This will display untagged images that are the leaves of the images tree (not intermediary layers). These images occur when a new build of an image takes the `repo:tag` away from the image ID, leaving it as `:` or untagged. A warning will be issued if trying to remove an image when a container is presently using it. By having this flag it allows for batch cleanup. -Ready for use by `docker rmi ...`, like: +You can use this in conjunction with `docker rmi ...`: - $ docker rmi $(docker images -f "dangling=true" -q) +```bash +$ docker rmi $(docker images -f "dangling=true" -q) - 8abc22fbb042 - 48e5f45168b9 - bf747efa0e2f - 980fe10e5736 - dea752e4e117 - 511136ea3c5a +8abc22fbb042 +48e5f45168b9 +bf747efa0e2f +980fe10e5736 +dea752e4e117 +511136ea3c5a +``` -NOTE: Docker will warn you if any containers exist that are using these untagged images. +> **Note**: Docker warns you if any containers exist that are using these +> untagged images. -##### Labeled images +#### Show images with a given label The `label` filter matches images based on the presence of a `label` alone or a `label` and a value. The following filter matches images with the `com.example.version` label regardless of its value. - $ docker images --filter "label=com.example.version" +```bash +$ docker images --filter "label=com.example.version" - REPOSITORY TAG IMAGE ID CREATED SIZE - match-me-1 latest eeae25ada2aa About a minute ago 188.3 MB - match-me-2 latest dea752e4e117 About a minute ago 188.3 MB +REPOSITORY TAG IMAGE ID CREATED SIZE +match-me-1 latest eeae25ada2aa About a minute ago 188.3 MB +match-me-2 latest dea752e4e117 About a minute ago 188.3 MB +``` The following filter matches images with the `com.example.version` label with the `1.0` value. - $ docker images --filter "label=com.example.version=1.0" - REPOSITORY TAG IMAGE ID CREATED SIZE - match-me latest 511136ea3c5a About a minute ago 188.3 MB +```bash +$ docker images --filter "label=com.example.version=1.0" + +REPOSITORY TAG IMAGE ID CREATED SIZE +match-me latest 511136ea3c5a About a minute ago 188.3 MB +``` In this example, with the `0.1` value, it returns an empty set because no matches were found. - $ docker images --filter "label=com.example.version=0.1" - REPOSITORY TAG IMAGE ID CREATED SIZE +```bash +$ docker images --filter "label=com.example.version=0.1" +REPOSITORY TAG IMAGE ID CREATED SIZE +``` -#### Before +#### Filter images by time The `before` filter shows only images created before the image with given id or reference. For example, having these images: - $ docker images - REPOSITORY TAG IMAGE ID CREATED SIZE - image1 latest eeae25ada2aa 4 minutes ago 188.3 MB - image2 latest dea752e4e117 9 minutes ago 188.3 MB - image3 latest 511136ea3c5a 25 minutes ago 188.3 MB +```bash +$ docker images + +REPOSITORY TAG IMAGE ID CREATED SIZE +image1 latest eeae25ada2aa 4 minutes ago 188.3 MB +image2 latest dea752e4e117 9 minutes ago 188.3 MB +image3 latest 511136ea3c5a 25 minutes ago 188.3 MB +``` Filtering with `before` would give: - $ docker images --filter "before=image1" - REPOSITORY TAG IMAGE ID CREATED SIZE - image2 latest dea752e4e117 9 minutes ago 188.3 MB - image3 latest 511136ea3c5a 25 minutes ago 188.3 MB +```bash +$ docker images --filter "before=image1" -#### Since - -The `since` filter shows only images created after the image with -given id or reference. For example, having these images: - - $ docker images - REPOSITORY TAG IMAGE ID CREATED SIZE - image1 latest eeae25ada2aa 4 minutes ago 188.3 MB - image2 latest dea752e4e117 9 minutes ago 188.3 MB - image3 latest 511136ea3c5a 25 minutes ago 188.3 MB +REPOSITORY TAG IMAGE ID CREATED SIZE +image2 latest dea752e4e117 9 minutes ago 188.3 MB +image3 latest 511136ea3c5a 25 minutes ago 188.3 MB +``` Filtering with `since` would give: - $ docker images --filter "since=image3" - REPOSITORY TAG IMAGE ID CREATED SIZE - image1 latest eeae25ada2aa 4 minutes ago 188.3 MB - image2 latest dea752e4e117 9 minutes ago 188.3 MB +```bash +$ docker images --filter "since=image3" +REPOSITORY TAG IMAGE ID CREATED SIZE +image1 latest eeae25ada2aa 4 minutes ago 188.3 MB +image2 latest dea752e4e117 9 minutes ago 188.3 MB +``` -#### Reference +#### Filter images by reference The `reference` filter shows only images whose reference matches the specified pattern. +```bash $ docker images + REPOSITORY TAG IMAGE ID CREATED SIZE busybox latest e02e811dd08f 5 weeks ago 1.09 MB busybox uclibc e02e811dd08f 5 weeks ago 1.09 MB busybox musl 733eb3059dce 5 weeks ago 1.21 MB busybox glibc 21c16b6787c6 5 weeks ago 4.19 MB +``` Filtering with `reference` would give: +```bash $ docker images --filter=reference='busy*:*libc' REPOSITORY TAG IMAGE ID CREATED SIZE busybox uclibc e02e811dd08f 5 weeks ago 1.09 MB busybox glibc 21c16b6787c6 5 weeks ago 4.19 MB +``` -## Formatting +### Format the output The formatting option (`--format`) will pretty print container output using a Go template. Valid placeholders for the Go template are listed below: -Placeholder | Description ----- | ---- -`.ID` | Image ID -`.Repository` | Image repository -`.Tag` | Image tag -`.Digest` | Image digest -`.CreatedSince` | Elapsed time since the image was created -`.CreatedAt` | Time when the image was created -`.Size` | Image disk size +| Placeholder | Description| +| ---- | ---- | +| `.ID` | Image ID | +| `.Repository` | Image repository | +| `.Tag` | Image tag | +| `.Digest` | Image digest | +| `.CreatedSince` | Elapsed time since the image was created | +| `.CreatedAt` | Time when the image was created | +| `.Size` | Image disk size | When using the `--format` option, the `image` command will either output the data exactly as the template declares or, when using the @@ -273,32 +308,38 @@ output the data exactly as the template declares or, when using the The following example uses a template without headers and outputs the `ID` and `Repository` entries separated by a colon for all images: - {% raw %} - $ docker images --format "{{.ID}}: {{.Repository}}" - 77af4d6b9913: - b6fa739cedf5: committ - 78a85c484f71: - 30557a29d5ab: docker - 5ed6274db6ce: - 746b819f315e: postgres - 746b819f315e: postgres - 746b819f315e: postgres - 746b819f315e: postgres - {% endraw %} +```bash +{% raw %} +$ docker images --format "{{.ID}}: {{.Repository}}" + +77af4d6b9913: +b6fa739cedf5: committ +78a85c484f71: +30557a29d5ab: docker +5ed6274db6ce: +746b819f315e: postgres +746b819f315e: postgres +746b819f315e: postgres +746b819f315e: postgres +{% endraw %} +``` To list all images with their repository and tag in a table format you can use: - {% raw %} - $ docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}" - IMAGE ID REPOSITORY TAG - 77af4d6b9913 - b6fa739cedf5 committ latest - 78a85c484f71 - 30557a29d5ab docker latest - 5ed6274db6ce - 746b819f315e postgres 9 - 746b819f315e postgres 9.3 - 746b819f315e postgres 9.3.5 - 746b819f315e postgres latest - {% endraw %} +```bash +{% raw %} +$ docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}" + +IMAGE ID REPOSITORY TAG +77af4d6b9913 +b6fa739cedf5 committ latest +78a85c484f71 +30557a29d5ab docker latest +5ed6274db6ce +746b819f315e postgres 9 +746b819f315e postgres 9.3 +746b819f315e postgres 9.3.5 +746b819f315e postgres latest +{% endraw %} +``` diff --git a/docs/reference/commandline/import.md b/docs/reference/commandline/import.md index 20e90a61fd..57edf650c9 100644 --- a/docs/reference/commandline/import.md +++ b/docs/reference/commandline/import.md @@ -26,6 +26,8 @@ Options: -m, --message string Set commit message for imported image ``` +## Description + You can specify a `URL` or `-` (dash) to take data directly from `STDIN`. The `URL` can point to an archive (.tar, .tar.gz, .tgz, .bzip, .tar.xz, or .txz) containing a filesystem or to an individual file on the Docker host. If you @@ -41,33 +43,45 @@ Supported `Dockerfile` instructions: ## Examples -**Import from a remote location:** +### Import from a remote location This will create a new untagged image. - $ docker import http://example.com/exampleimage.tgz +```bash +$ docker import http://example.com/exampleimage.tgz +``` -**Import from a local file:** +### Import from a local file -Import to docker via pipe and `STDIN`. +- Import to docker via pipe and `STDIN`. - $ cat exampleimage.tgz | docker import - exampleimagelocal:new + ```bash + $ cat exampleimage.tgz | docker import - exampleimagelocal:new + ``` -Import with a commit message. +- Import with a commit message. - $ cat exampleimage.tgz | docker import --message "New image imported from tarball" - exampleimagelocal:new + ```bash + $ cat exampleimage.tgz | docker import --message "New image imported from tarball" - exampleimagelocal:new + ``` -Import to docker from a local archive. +- Import to docker from a local archive. + ```bash $ docker import /path/to/exampleimage.tgz + ``` -**Import from a local directory:** +### Import from a local directory - $ sudo tar -c . | docker import - exampleimagedir +```bash +$ sudo tar -c . | docker import - exampleimagedir +``` -**Import from a local directory with new configurations:** +### Import from a local directory with new configurations - $ sudo tar -c . | docker import --change "ENV DEBUG true" - exampleimagedir +```bash +$ sudo tar -c . | docker import --change "ENV DEBUG true" - exampleimagedir +``` Note the `sudo` in this example – you must preserve the ownership of the files (especially root ownership) during the diff --git a/docs/reference/commandline/index.md b/docs/reference/commandline/index.md index 87c7b4775f..f38fc52a8c 100644 --- a/docs/reference/commandline/index.md +++ b/docs/reference/commandline/index.md @@ -25,6 +25,8 @@ You start the Docker daemon with the command line. How you start the daemon affects your Docker containers. For that reason you should also make sure to read the [`dockerd`](dockerd.md) reference page. +## Commands by object + ### Docker management commands | Command | Description | @@ -123,7 +125,7 @@ read the [`dockerd`](dockerd.md) reference page. | [node rm](node_rm.md) | Remove one or more nodes from the swarm | | [node update](node_update.md) | Update attributes for a node | -### Swarm swarm commands +### Swarm management commands | Command | Description | |:--------|:-------------------------------------------------------------------| diff --git a/docs/reference/commandline/info.md b/docs/reference/commandline/info.md index 50a084fcb2..aba4d190dd 100644 --- a/docs/reference/commandline/info.md +++ b/docs/reference/commandline/info.md @@ -25,6 +25,8 @@ Options: --help Print usage ``` +## Description + This command displays system wide information regarding the Docker installation. Information displayed includes the kernel version, number of containers and images. The number of images shown is the number of unique images. The same image tagged @@ -43,182 +45,201 @@ meta data regarding those images are stored. When run for the first time Docker allocates a certain amount of data space and meta data space from the space available on the volume where `/var/lib/docker` is mounted. -# Examples +## Examples -## Display Docker system information +### Show output + +The example below shows the output for a daemon running on Red Hat Enterprise Linux, +using the `devicemapper` storage driver. As can be seen in the output, additional +information about the `devicemapper` storage driver is shown: + +```bash +$ docker info + +Containers: 14 + Running: 3 + Paused: 1 + Stopped: 10 +Images: 52 +Server Version: 1.10.3 +Storage Driver: devicemapper + Pool Name: docker-202:2-25583803-pool + Pool Blocksize: 65.54 kB + Base Device Size: 10.74 GB + Backing Filesystem: xfs + Data file: /dev/loop0 + Metadata file: /dev/loop1 + Data Space Used: 1.68 GB + Data Space Total: 107.4 GB + Data Space Available: 7.548 GB + Metadata Space Used: 2.322 MB + Metadata Space Total: 2.147 GB + Metadata Space Available: 2.145 GB + Udev Sync Supported: true + Deferred Removal Enabled: false + Deferred Deletion Enabled: false + Deferred Deleted Device Count: 0 + Data loop file: /var/lib/docker/devicemapper/devicemapper/data + Metadata loop file: /var/lib/docker/devicemapper/devicemapper/metadata + Library Version: 1.02.107-RHEL7 (2015-12-01) +Execution Driver: native-0.2 +Logging Driver: json-file +Plugins: + Volume: local + Network: null host bridge +Kernel Version: 3.10.0-327.el7.x86_64 +Operating System: Red Hat Enterprise Linux Server 7.2 (Maipo) +OSType: linux +Architecture: x86_64 +CPUs: 1 +Total Memory: 991.7 MiB +Name: ip-172-30-0-91.ec2.internal +ID: I54V:OLXT:HVMM:TPKO:JPHQ:CQCD:JNLC:O3BZ:4ZVJ:43XJ:PFHZ:6N2S +Docker Root Dir: /var/lib/docker +Debug mode (client): false +Debug mode (server): false +Username: gordontheturtle +Registry: https://index.docker.io/v1/ +Insecure registries: + myinsecurehost:5000 + 127.0.0.0/8 +``` + +### Show debugging output Here is a sample output for a daemon running on Ubuntu, using the overlay2 storage driver and a node that is part of a 2-node swarm: - $ docker -D info - Containers: 14 - Running: 3 - Paused: 1 - Stopped: 10 - Images: 52 - Server Version: 1.13.0 - Storage Driver: overlay2 - Backing Filesystem: extfs - Supports d_type: true - Native Overlay Diff: false - Logging Driver: json-file - Cgroup Driver: cgroupfs - Plugins: - Volume: local - Network: bridge host macvlan null overlay - Swarm: active - NodeID: rdjq45w1op418waxlairloqbm - Is Manager: true - ClusterID: te8kdyw33n36fqiz74bfjeixd - Managers: 1 - Nodes: 2 - Orchestration: - Task History Retention Limit: 5 - Raft: - Snapshot Interval: 10000 - Number of Old Snapshots to Retain: 0 - Heartbeat Tick: 1 - Election Tick: 3 - Dispatcher: - Heartbeat Period: 5 seconds - CA Configuration: - Expiry Duration: 3 months - Node Address: 172.16.66.128 172.16.66.129 - Manager Addresses: - 172.16.66.128:2477 - Runtimes: runc - Default Runtime: runc - Init Binary: docker-init - containerd version: 8517738ba4b82aff5662c97ca4627e7e4d03b531 - runc version: ac031b5bf1cc92239461125f4c1ffb760522bbf2 - init version: N/A (expected: v0.13.0) - Security Options: - apparmor - seccomp - Profile: default - Kernel Version: 4.4.0-31-generic - Operating System: Ubuntu 16.04.1 LTS - OSType: linux - Architecture: x86_64 - CPUs: 2 - Total Memory: 1.937 GiB - Name: ubuntu - ID: H52R:7ZR6:EIIA:76JG:ORIY:BVKF:GSFU:HNPG:B5MK:APSC:SZ3Q:N326 - Docker Root Dir: /var/lib/docker - Debug Mode (client): true - Debug Mode (server): true - File Descriptors: 30 - Goroutines: 123 - System Time: 2016-11-12T17:24:37.955404361-08:00 - EventsListeners: 0 - Http Proxy: http://test:test@proxy.example.com:8080 - Https Proxy: https://test:test@proxy.example.com:8080 - No Proxy: localhost,127.0.0.1,docker-registry.somecorporation.com - Registry: https://index.docker.io/v1/ - WARNING: No swap limit support - Labels: - storage=ssd - staging=true - Experimental: false - Insecure Registries: - 127.0.0.0/8 - Registry Mirrors: - http://192.168.1.2/ - http://registry-mirror.example.com:5000/ - Live Restore Enabled: false +```bash +$ docker -D info -The global `-D` option tells all `docker` commands to output debug information. +Containers: 14 + Running: 3 + Paused: 1 + Stopped: 10 +Images: 52 +Server Version: 1.13.0 +Storage Driver: overlay2 + Backing Filesystem: extfs + Supports d_type: true + Native Overlay Diff: false +Logging Driver: json-file +Cgroup Driver: cgroupfs +Plugins: + Volume: local + Network: bridge host macvlan null overlay +Swarm: active + NodeID: rdjq45w1op418waxlairloqbm + Is Manager: true + ClusterID: te8kdyw33n36fqiz74bfjeixd + Managers: 1 + Nodes: 2 + Orchestration: + Task History Retention Limit: 5 + Raft: + Snapshot Interval: 10000 + Number of Old Snapshots to Retain: 0 + Heartbeat Tick: 1 + Election Tick: 3 + Dispatcher: + Heartbeat Period: 5 seconds + CA Configuration: + Expiry Duration: 3 months + Node Address: 172.16.66.128 172.16.66.129 + Manager Addresses: + 172.16.66.128:2477 +Runtimes: runc +Default Runtime: runc +Init Binary: docker-init +containerd version: 8517738ba4b82aff5662c97ca4627e7e4d03b531 +runc version: ac031b5bf1cc92239461125f4c1ffb760522bbf2 +init version: N/A (expected: v0.13.0) +Security Options: + apparmor + seccomp + Profile: default +Kernel Version: 4.4.0-31-generic +Operating System: Ubuntu 16.04.1 LTS +OSType: linux +Architecture: x86_64 +CPUs: 2 +Total Memory: 1.937 GiB +Name: ubuntu +ID: H52R:7ZR6:EIIA:76JG:ORIY:BVKF:GSFU:HNPG:B5MK:APSC:SZ3Q:N326 +Docker Root Dir: /var/lib/docker +Debug Mode (client): true +Debug Mode (server): true + File Descriptors: 30 + Goroutines: 123 + System Time: 2016-11-12T17:24:37.955404361-08:00 + EventsListeners: 0 +Http Proxy: http://test:test@proxy.example.com:8080 +Https Proxy: https://test:test@proxy.example.com:8080 +No Proxy: localhost,127.0.0.1,docker-registry.somecorporation.com +Registry: https://index.docker.io/v1/ +WARNING: No swap limit support +Labels: + storage=ssd + staging=true +Experimental: false +Insecure Registries: + 127.0.0.0/8 +Registry Mirrors: + http://192.168.1.2/ + http://registry-mirror.example.com:5000/ +Live Restore Enabled: false +``` -The example below shows the output for a daemon running on Red Hat Enterprise Linux, -using the devicemapper storage driver. As can be seen in the output, additional -information about the devicemapper storage driver is shown: +The global `-D` option causes all `docker` commands to output debug information. - $ docker info - Containers: 14 - Running: 3 - Paused: 1 - Stopped: 10 - Images: 52 - Server Version: 1.10.3 - Storage Driver: devicemapper - Pool Name: docker-202:2-25583803-pool - Pool Blocksize: 65.54 kB - Base Device Size: 10.74 GB - Backing Filesystem: xfs - Data file: /dev/loop0 - Metadata file: /dev/loop1 - Data Space Used: 1.68 GB - Data Space Total: 107.4 GB - Data Space Available: 7.548 GB - Metadata Space Used: 2.322 MB - Metadata Space Total: 2.147 GB - Metadata Space Available: 2.145 GB - Udev Sync Supported: true - Deferred Removal Enabled: false - Deferred Deletion Enabled: false - Deferred Deleted Device Count: 0 - Data loop file: /var/lib/docker/devicemapper/devicemapper/data - Metadata loop file: /var/lib/docker/devicemapper/devicemapper/metadata - Library Version: 1.02.107-RHEL7 (2015-12-01) - Execution Driver: native-0.2 - Logging Driver: json-file - Plugins: - Volume: local - Network: null host bridge - Kernel Version: 3.10.0-327.el7.x86_64 - Operating System: Red Hat Enterprise Linux Server 7.2 (Maipo) - OSType: linux - Architecture: x86_64 - CPUs: 1 - Total Memory: 991.7 MiB - Name: ip-172-30-0-91.ec2.internal - ID: I54V:OLXT:HVMM:TPKO:JPHQ:CQCD:JNLC:O3BZ:4ZVJ:43XJ:PFHZ:6N2S - Docker Root Dir: /var/lib/docker - Debug mode (client): false - Debug mode (server): false - Username: gordontheturtle - Registry: https://index.docker.io/v1/ - Insecure registries: - myinsecurehost:5000 - 127.0.0.0/8 +### Format the output You can also specify the output format: - $ docker info --format '{{json .}}' - {"ID":"I54V:OLXT:HVMM:TPKO:JPHQ:CQCD:JNLC:O3BZ:4ZVJ:43XJ:PFHZ:6N2S","Containers":14, ...} +```bash +{% raw %} +$ docker info --format '{{json .}}' + +{"ID":"I54V:OLXT:HVMM:TPKO:JPHQ:CQCD:JNLC:O3BZ:4ZVJ:43XJ:PFHZ:6N2S","Containers":14, ...} +``` + +### Run `docker info` on Windows Here is a sample output for a daemon running on Windows Server 2016: - E:\docker>docker info - Containers: 1 - Running: 0 - Paused: 0 - Stopped: 1 - Images: 17 - Server Version: 1.13.0 - Storage Driver: windowsfilter - Windows: - Logging Driver: json-file - Plugins: - Volume: local - Network: nat null overlay - Swarm: inactive - Default Isolation: process - Kernel Version: 10.0 14393 (14393.206.amd64fre.rs1_release.160912-1937) - Operating System: Windows Server 2016 Datacenter - OSType: windows - Architecture: x86_64 - CPUs: 8 - Total Memory: 3.999 GiB - Name: WIN-V0V70C0LU5P - ID: NYMS:B5VK:UMSL:FVDZ:EWB5:FKVK:LPFL:FJMQ:H6FT:BZJ6:L2TD:XH62 - Docker Root Dir: C:\control - Debug Mode (client): false - Debug Mode (server): false - Registry: https://index.docker.io/v1/ - Insecure Registries: - 127.0.0.0/8 - Registry Mirrors: - http://192.168.1.2/ - http://registry-mirror.example.com:5000/ - Live Restore Enabled: false +```none +E:\docker>docker info + +Containers: 1 + Running: 0 + Paused: 0 + Stopped: 1 +Images: 17 +Server Version: 1.13.0 +Storage Driver: windowsfilter + Windows: +Logging Driver: json-file +Plugins: + Volume: local + Network: nat null overlay +Swarm: inactive +Default Isolation: process +Kernel Version: 10.0 14393 (14393.206.amd64fre.rs1_release.160912-1937) +Operating System: Windows Server 2016 Datacenter +OSType: windows +Architecture: x86_64 +CPUs: 8 +Total Memory: 3.999 GiB +Name: WIN-V0V70C0LU5P +ID: NYMS:B5VK:UMSL:FVDZ:EWB5:FKVK:LPFL:FJMQ:H6FT:BZJ6:L2TD:XH62 +Docker Root Dir: C:\control +Debug Mode (client): false +Debug Mode (server): false +Registry: https://index.docker.io/v1/ +Insecure Registries: + 127.0.0.0/8 +Registry Mirrors: + http://192.168.1.2/ + http://registry-mirror.example.com:5000/ +Live Restore Enabled: false +``` diff --git a/docs/reference/commandline/inspect.md b/docs/reference/commandline/inspect.md index 7a0c3a0871..dfea20a57a 100644 --- a/docs/reference/commandline/inspect.md +++ b/docs/reference/commandline/inspect.md @@ -28,7 +28,9 @@ Options: --type Return JSON for specified type ``` -By default, this will render all results in a JSON array. If the container and +## Description + +By default, `docker inspect` will render all results in a JSON array. If the container and image have the same name, this will return container JSON for unspecified type. If a format is specified, the given template will be executed for each result. @@ -37,46 +39,53 @@ describes all the details of the format. ## Examples -**Get an instance's IP address:** +### Get an instance's IP address For the most part, you can pick out any field from the JSON in a fairly straightforward manner. - {% raw %} - $ docker inspect --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' $INSTANCE_ID - {% endraw %} +```bash +{% raw %} +$ docker inspect --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' $INSTANCE_ID +{% endraw %} +``` -**Get an instance's MAC address:** +### Get an instance's MAC address -For the most part, you can pick out any field from the JSON in a fairly -straightforward manner. +```bash +{% raw %} +$ docker inspect --format='{{range .NetworkSettings.Networks}}{{.MacAddress}}{{end}}' $INSTANCE_ID +{% endraw %} +``` - {% raw %} - $ docker inspect --format='{{range .NetworkSettings.Networks}}{{.MacAddress}}{{end}}' $INSTANCE_ID - {% endraw %} +### Get an instance's log path -**Get an instance's log path:** +```bash +{% raw %} +$ docker inspect --format='{{.LogPath}}' $INSTANCE_ID +{% endraw %} +``` - {% raw %} - $ docker inspect --format='{{.LogPath}}' $INSTANCE_ID - {% endraw %} +### Get an instance's image name -**Get a Task's image name:** +```bash +{% raw %} +$ docker inspect --format='{{.Container.Spec.Image}}' $INSTANCE_ID +{% endraw %} +``` - {% raw %} - $ docker inspect --format='{{.Container.Spec.Image}}' $INSTANCE_ID - {% endraw %} +### List all port bindings -**List all port bindings:** - -One can loop over arrays and maps in the results to produce simple text +You can loop over arrays and maps in the results to produce simple text output: - {% raw %} - $ docker inspect --format='{{range $p, $conf := .NetworkSettings.Ports}} {{$p}} -> {{(index $conf 0).HostPort}} {{end}}' $INSTANCE_ID - {% endraw %} +```bash +{% raw %} +$ docker inspect --format='{{range $p, $conf := .NetworkSettings.Ports}} {{$p}} -> {{(index $conf 0).HostPort}} {{end}}' $INSTANCE_ID +{% endraw %} +``` -**Find a specific port mapping:** +### Find a specific port mapping The `.Field` syntax doesn't work when the field name begins with a number, but the template language's `index` function does. The @@ -86,17 +95,21 @@ numeric public port, you use `index` to find the specific port map, and then `index` 0 contains the first object inside of that. Then we ask for the `HostPort` field to get the public address. - {% raw %} - $ docker inspect --format='{{(index (index .NetworkSettings.Ports "8787/tcp") 0).HostPort}}' $INSTANCE_ID - {% endraw %} +```bash +{% raw %} +$ docker inspect --format='{{(index (index .NetworkSettings.Ports "8787/tcp") 0).HostPort}}' $INSTANCE_ID +{% endraw %} +``` -**Get a subsection in JSON format:** +### Get a subsection in JSON format If you request a field which is itself a structure containing other fields, by default you get a Go-style dump of the inner values. Docker adds a template function, `json`, which can be applied to get results in JSON format. - {% raw %} - $ docker inspect --format='{{json .Config}}' $INSTANCE_ID - {% endraw %} +```bash +{% raw %} +$ docker inspect --format='{{json .Config}}' $INSTANCE_ID +{% endraw %} +``` diff --git a/docs/reference/commandline/kill.md b/docs/reference/commandline/kill.md index 32fde3d8b5..97b15add9b 100644 --- a/docs/reference/commandline/kill.md +++ b/docs/reference/commandline/kill.md @@ -25,10 +25,11 @@ Options: -s, --signal string Signal to send to the container (default "KILL") ``` +## Description + The main process inside the container will be sent `SIGKILL`, or any signal specified with option `--signal`. -> **Note:** -> `ENTRYPOINT` and `CMD` in the *shell* form run as a subcommand of `/bin/sh -c`, -> which does not pass signals. This means that the executable is not the container’s PID 1 -> and does not receive Unix signals. +> **Note**: `ENTRYPOINT` and `CMD` in the *shell* form run as a subcommand of +> `/bin/sh -c`, which does not pass signals. This means that the executable is +> not the container’s PID 1 and does not receive Unix signals. diff --git a/docs/reference/commandline/load.md b/docs/reference/commandline/load.md index 04a5bc7e56..f19362b433 100644 --- a/docs/reference/commandline/load.md +++ b/docs/reference/commandline/load.md @@ -26,28 +26,37 @@ Options: The tarball may be compressed with gzip, bzip, or xz -q, --quiet Suppress the load output but still outputs the imported images ``` +## Descriptino -Loads a tarred repository from a file or the standard input stream. -Restores both images and tags. +`docker load` loads a tarred repository from a file or the standard input stream. +It restores both images and tags. - $ docker images - REPOSITORY TAG IMAGE ID CREATED SIZE - $ docker load < busybox.tar.gz - # […] - Loaded image: busybox:latest - $ docker images - REPOSITORY TAG IMAGE ID CREATED SIZE - busybox latest 769b9341d937 7 weeks ago 2.489 MB - $ docker load --input fedora.tar - # […] - Loaded image: fedora:rawhide - # […] - Loaded image: fedora:20 - # […] - $ docker images - REPOSITORY TAG IMAGE ID CREATED SIZE - busybox latest 769b9341d937 7 weeks ago 2.489 MB - fedora rawhide 0d20aec6529d 7 weeks ago 387 MB - fedora 20 58394af37342 7 weeks ago 385.5 MB - fedora heisenbug 58394af37342 7 weeks ago 385.5 MB - fedora latest 58394af37342 7 weeks ago 385.5 MB +## Examples + +```bash +$ docker images + +REPOSITORY TAG IMAGE ID CREATED SIZE + +$ docker load < busybox.tar.gz + +Loaded image: busybox:latest +$ docker images +REPOSITORY TAG IMAGE ID CREATED SIZE +busybox latest 769b9341d937 7 weeks ago 2.489 MB + +$ docker load --input fedora.tar + +Loaded image: fedora:rawhide + +Loaded image: fedora:20 + +$ docker images + +REPOSITORY TAG IMAGE ID CREATED SIZE +busybox latest 769b9341d937 7 weeks ago 2.489 MB +fedora rawhide 0d20aec6529d 7 weeks ago 387 MB +fedora 20 58394af37342 7 weeks ago 385.5 MB +fedora heisenbug 58394af37342 7 weeks ago 385.5 MB +fedora latest 58394af37342 7 weeks ago 385.5 MB +``` diff --git a/docs/reference/commandline/login.md b/docs/reference/commandline/login.md index a0f35fd4d0..e5d16567b2 100644 --- a/docs/reference/commandline/login.md +++ b/docs/reference/commandline/login.md @@ -27,12 +27,20 @@ Options: -u, --username string Username ``` +## Description + +Login to a registry. + +### Login to a self-hosted registry + If you want to login to a self-hosted registry you can specify this by adding the server name. - example: - $ docker login localhost:8080 +```bash +$ docker login localhost:8080 +``` +### Privileged user requirement `docker login` requires user to use `sudo` or be `root`, except when: @@ -43,7 +51,7 @@ You can log into any public or private repository for which you have credentials. When you log in, the command stores encoded credentials in `$HOME/.docker/config.json` on Linux or `%USERPROFILE%/.docker/config.json` on Windows. -## Credentials store +### Credentials store The Docker Engine can keep user credentials in an external credentials store, such as the native keychain of the operating system. Using an external store @@ -60,8 +68,6 @@ you can download them from: - Apple macOS keychain: https://github.com/docker/docker-credential-helpers/releases - Microsoft Windows Credential Manager: https://github.com/docker/docker-credential-helpers/releases -### Usage - You need to specify the credentials store in `$HOME/.docker/config.json` to tell the docker engine to use it: @@ -74,7 +80,7 @@ to tell the docker engine to use it: If you are currently logged in, run `docker logout` to remove the credentials from the file and run `docker login` again. -### Protocol +### Credential helper protocol Credential helpers can be any program or script that follows a very simple protocol. This protocol is heavily inspired by Git, but it differs in the information shared. @@ -120,3 +126,31 @@ an example of that payload: `https://index.docker.io/v1`. The `erase` command can write error messages to `STDOUT` that the docker engine will show if there was an issue. + +### Credential helpers + +Credential helpers are similar to the credential store above, but act as the +designated programs to handle credentials for *specific registries*. The default +credential store (`credsStore` or the config file itself) will not be used for +operations concerning credentials of the specified registries. + +### Logging out + +If you are currently logged in, run `docker logout` to remove +the credentials from the default store. + +Credential helpers are specified in a similar way to `credsStore`, but +allow for multiple helpers to be configured at a time. Keys specify the +registry domain, and values specify the suffix of the program to use +(i.e. everything after `docker-credential-`). +For example: + +```json +{ + "credHelpers": { + "registry.example.com": "registryhelper", + "awesomereg.example.org": "hip-star", + "unicorn.example.io": "vcbait" + } +} +``` diff --git a/docs/reference/commandline/logout.md b/docs/reference/commandline/logout.md index 1635e2244b..1e150eb848 100644 --- a/docs/reference/commandline/logout.md +++ b/docs/reference/commandline/logout.md @@ -25,6 +25,8 @@ Options: --help Print usage ``` -For example: +## Examples - $ docker logout localhost:8080 +```bash +$ docker logout localhost:8080 +``` diff --git a/docs/reference/commandline/logs.md b/docs/reference/commandline/logs.md index 891e10b55c..75f25f7657 100644 --- a/docs/reference/commandline/logs.md +++ b/docs/reference/commandline/logs.md @@ -24,11 +24,13 @@ Options: --details Show extra details provided to logs -f, --follow Follow log output --help Print usage - --since string Show logs since timestamp + --since string Show logs since timestamp (e.g. 2013-01-02T13:23:37) or relative (e.g. 42m for 42 minutes) --tail string Number of lines to show from the end of the logs (default "all") -t, --timestamps Show timestamps ``` +## Description + The `docker logs` command batch-retrieves logs present at the time of execution. > **Note**: this command is only functional for containers that are started with diff --git a/docs/reference/commandline/menu.md b/docs/reference/commandline/menu.md deleted file mode 100644 index d58afacd76..0000000000 --- a/docs/reference/commandline/menu.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: "Command line reference" -description: "Docker's CLI command description and usage" -keywords: "Docker, Docker documentation, CLI, command line" -identifier: "smn_cli" ---- - - - -# The Docker commands - -This section contains reference information on using Docker's command line -client. Each command has a reference page along with samples. If you are -unfamiliar with the command line, you should start by reading about how to -[Use the Docker command line](cli.md). - -You start the Docker daemon with the command line. How you start the daemon -affects your Docker containers. For that reason you should also make sure to -read the [`dockerd`](dockerd.md) reference page. - -For a list of Docker commands see [Command line reference guide](index.md). diff --git a/docs/reference/commandline/network_connect.md b/docs/reference/commandline/network_connect.md index 52459a5d5f..7c5a5867f0 100644 --- a/docs/reference/commandline/network_connect.md +++ b/docs/reference/commandline/network_connect.md @@ -29,38 +29,55 @@ Options: --link-local-ip value Add a link-local address for the container (default []) ``` +## Description + Connects a container to a network. You can connect a container by name or by ID. Once connected, the container can communicate with other containers in the same network. +## Examples + +### Connect a running container to a network + ```bash $ docker network connect multi-host-network container1 ``` +### Connect a container to a network when it starts + You can also use the `docker run --network=` option to start a container and immediately connect it to a network. ```bash $ docker run -itd --network=multi-host-network busybox ``` +### Specify the IP address a container will use on a given network + You can specify the IP address you want to be assigned to the container's interface. ```bash $ docker network connect --ip 10.10.36.122 multi-host-network container2 ``` +### Use the legacy `--link` option + You can use `--link` option to link another container with a preferred alias ```bash $ docker network connect --link container1:c1 multi-host-network container2 ``` +### Create a network alias for a container + `--alias` option can be used to resolve the container by another name in the network being connected to. ```bash $ docker network connect --alias db --alias mysql multi-host-network container2 ``` + +### Network implications of stopping, pausing, or restarting containers + You can pause, restart, and stop containers that are connected to a network. A container connects to its configured networks when it runs. @@ -88,7 +105,7 @@ network but launched from different Engines can also communicate in this way. You can connect a container to one or more networks. The networks need not be the same type. For example, you can connect a single container bridge and overlay networks. -## Related information +## Related commands * [network inspect](network_inspect.md) * [network create](network_create.md) diff --git a/docs/reference/commandline/network_create.md b/docs/reference/commandline/network_create.md index e238217d41..4540d530c6 100644 --- a/docs/reference/commandline/network_create.md +++ b/docs/reference/commandline/network_create.md @@ -38,6 +38,8 @@ Options: network segment (default []) ``` +## Description + Creates a new network. The `DRIVER` accepts `bridge` or `overlay` which are the built-in network drivers. If you have installed a third party or your own custom network driver you can specify that `DRIVER` here also. If you don't specify the @@ -86,7 +88,9 @@ Network names must be unique. The Docker daemon attempts to identify naming conflicts but this is not guaranteed. It is the user's responsibility to avoid name conflicts. -## Connect containers +## Examples + +### Connect containers When you start a container, use the `--network` flag to connect it to a network. This example adds the `busybox` container to the `mynet` network: @@ -107,7 +111,7 @@ Engines can also communicate in this way. You can disconnect a container from a network using the `docker network disconnect` command. -## Specifying advanced options +### Specify advanced options When you create a network, Engine creates a non-overlapping subnetwork for the network by default. This subnetwork is not a subdivision of an existing @@ -150,7 +154,7 @@ $ docker network create -d overlay \ Be sure that your subnetworks do not overlap. If they do, the network create fails and Engine returns an error. -# Bridge driver options +### Bridge driver options When creating a custom network, the default network driver (i.e. `bridge`) has additional options that can be passed. The following are those options and the @@ -191,7 +195,7 @@ connects a bridge network to it to provide external connectivity. If you want to create an externally isolated `overlay` network, you can specify the `--internal` option. -## Related information +## Related commands * [network inspect](network_inspect.md) * [network connect](network_connect.md) diff --git a/docs/reference/commandline/network_disconnect.md b/docs/reference/commandline/network_disconnect.md index 42e976a500..e855894d27 100644 --- a/docs/reference/commandline/network_disconnect.md +++ b/docs/reference/commandline/network_disconnect.md @@ -25,14 +25,19 @@ Options: --help Print usage ``` -Disconnects a container from a network. The container must be running to disconnect it from the network. +## Description + +Disconnects a container from a network. The container must be running to +disconnect it from the network. + +## Examples ```bash $ docker network disconnect multi-host-network container1 ``` -## Related information +## Related commands * [network inspect](network_inspect.md) * [network connect](network_connect.md) diff --git a/docs/reference/commandline/network_inspect.md b/docs/reference/commandline/network_inspect.md index bc0005e38e..2b4c423bbb 100644 --- a/docs/reference/commandline/network_inspect.md +++ b/docs/reference/commandline/network_inspect.md @@ -25,7 +25,16 @@ Options: --help Print usage ``` -Returns information about one or more networks. By default, this command renders all results in a JSON object. For example, if you connect two containers to the default `bridge` network: +## Description + +Returns information about one or more networks. By default, this command renders +all results in a JSON object. + +## Examples + +## Inspect the `bridge` network + +Connect two containers to the default `bridge` network: ```bash $ sudo docker run -itd --name=container1 busybox @@ -47,8 +56,9 @@ template for each result. Go's [text/template](http://golang.org/pkg/text/template/) package describes all the details of the format. -```bash +```none $ sudo docker network inspect bridge + [ { "Name": "bridge", @@ -95,12 +105,19 @@ $ sudo docker network inspect bridge ] ``` -Returns the information about the user-defined network: +### Inspect a user-defined network + +Create and inspect a user-defined network: ```bash $ docker network create simple-network + 69568e6336d8c96bbf57869030919f7c69524f71183b44d80948bd3927c87f6a +``` + +```none $ docker network inspect simple-network + [ { "Name": "simple-network", @@ -124,12 +141,15 @@ $ docker network inspect simple-network ] ``` -For swarm mode overlay networks `network inspect` also shows the IP address and node name -of the peers. Peers are the nodes in the swarm cluster which have at least one task attached +### Inspect the `ingress` network + +For swarm mode overlay networks `network inspect` also shows the IP address and node name +of the peers. Peers are the nodes in the swarm cluster which have at least one task attached to the network. Node name is of the format `-`. -```bash +```none $ docker network inspect ingress + [ { "Name": "ingress", @@ -181,7 +201,7 @@ $ docker network inspect ingress ] ``` -## Related information +## Related commands * [network disconnect ](network_disconnect.md) * [network connect](network_connect.md) diff --git a/docs/reference/commandline/network_ls.md b/docs/reference/commandline/network_ls.md index a4f671d569..446fc4ae7d 100644 --- a/docs/reference/commandline/network_ls.md +++ b/docs/reference/commandline/network_ls.md @@ -31,8 +31,14 @@ Options: -q, --quiet Only display network IDs ``` +## Description + Lists all the networks the Engine `daemon` knows about. This includes the -networks that span across multiple hosts in a cluster, for example: +networks that span across multiple hosts in a cluster. + +## Examples + +### List all networks ```bash $ sudo docker network ls @@ -55,7 +61,7 @@ c288470c46f6c8949c5f7e5099b5b7947b07eabe8d9a27d79a9cbf111adcbf47 host 63d1ff1f77b07ca51070a8c227e962238358bd310bde1529cf62e6c307ade161 dev bridge local ``` -## Filtering +### Filtering The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`). @@ -175,7 +181,7 @@ $ docker network rm `docker network ls --filter type=custom -q` A warning will be issued when trying to remove a network that has containers attached. -## Formatting +### Formatting The formatting options (`--format`) pretty-prints networks output using a Go template. @@ -207,7 +213,7 @@ d1584f8dc718: host 391df270dc66: null ``` -## Related information +## Related commands * [network disconnect ](network_disconnect.md) * [network connect](network_connect.md) diff --git a/docs/reference/commandline/network_prune.md b/docs/reference/commandline/network_prune.md index 5b65465600..cd4026cd6a 100644 --- a/docs/reference/commandline/network_prune.md +++ b/docs/reference/commandline/network_prune.md @@ -16,12 +16,16 @@ Options: --help Print usage ``` -Remove all unused networks. Unused networks are those which are not referenced by any containers. +## Description -Example output: +Remove all unused networks. Unused networks are those which are not referenced +by any containers. + +## Examples ```bash $ docker network prune + WARNING! This will remove all networks not used by at least one container. Are you sure you want to continue? [y/N] y Deleted Networks: @@ -29,7 +33,55 @@ n1 n2 ``` -## Related information +### Filtering + +The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more +than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) + +The currently supported filters are: + +* until (``) - only remove networks created before given timestamp + +The `until` filter can be Unix timestamps, date formatted +timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed +relative to the daemon machine’s time. Supported formats for date +formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, +`2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local +timezone on the daemon will be used if you do not provide either a `Z` or a +`+-00:00` timezone offset at the end of the timestamp. When providing Unix +timestamps enter seconds[.nanoseconds], where seconds is the number of seconds +that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap +seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a +fraction of a second no more than nine digits long. + +The following removes networks created more than 5 minutes ago. Note that +system networks such as `bridge`, `host`, and `none` will never be pruned: + +```none +$ docker network ls + +NETWORK ID NAME DRIVER SCOPE +7430df902d7a bridge bridge local +ea92373fd499 foo-1-day-ago bridge local +ab53663ed3c7 foo-1-min-ago bridge local +97b91972bc3b host host local +f949d337b1f5 none null local + +$ docker network prune --force --filter until=5m + +Deleted Networks: +foo-1-day-ago + +$ docker network ls + +NETWORK ID NAME DRIVER SCOPE +7430df902d7a bridge bridge local +ab53663ed3c7 foo-1-min-ago bridge local +97b91972bc3b host host local +f949d337b1f5 none null local +``` + +## Related commands * [network disconnect ](network_disconnect.md) * [network connect](network_connect.md) diff --git a/docs/reference/commandline/network_rm.md b/docs/reference/commandline/network_rm.md index f06b4c002d..aab487a044 100644 --- a/docs/reference/commandline/network_rm.md +++ b/docs/reference/commandline/network_rm.md @@ -27,14 +27,23 @@ Options: --help Print usage ``` +## Description + Removes one or more networks by name or identifier. To remove a network, you must first disconnect any containers connected to it. + +## Examples + +### Remove a network + To remove the network named 'my-network': ```bash $ docker network rm my-network ``` +### Remove multiple networks + To delete multiple networks in a single `docker network rm` command, provide multiple network names or ids. The following example deletes a network with id `3695c422697f` and a network named `my-network`: @@ -48,7 +57,7 @@ If the deletion of one network fails, the command continues to the next on the list and tries to delete that. The command reports success or failure for each deletion. -## Related information +## Related commands * [network disconnect ](network_disconnect.md) * [network connect](network_connect.md) diff --git a/docs/reference/commandline/node_demote.md b/docs/reference/commandline/node_demote.md index 9a81bb9c04..e6e59d8945 100644 --- a/docs/reference/commandline/node_demote.md +++ b/docs/reference/commandline/node_demote.md @@ -25,14 +25,19 @@ Options: ``` -Demotes an existing manager so that it is no longer a manager. This command targets a docker engine that is a manager in the swarm. +## Description +Demotes an existing manager so that it is no longer a manager. This command +targets a docker engine that is a manager in the swarm. + + +## Examples ```bash $ docker node demote ``` -## Related information +## Related commands * [node inspect](node_inspect.md) * [node ls](node_ls.md) diff --git a/docs/reference/commandline/node_inspect.md b/docs/reference/commandline/node_inspect.md index fac688fe40..2ff6971742 100644 --- a/docs/reference/commandline/node_inspect.md +++ b/docs/reference/commandline/node_inspect.md @@ -26,108 +26,120 @@ Options: --pretty Print the information in a human friendly format. ``` +## Description + Returns information about a node. By default, this command renders all results in a JSON array. You can specify an alternate format to execute a given template for each result. Go's [text/template](http://golang.org/pkg/text/template/) package describes all the details of the format. -Example output: +## Examples - $ docker node inspect swarm-manager - [ - { - "ID": "e216jshn25ckzbvmwlnh5jr3g", - "Version": { - "Index": 10 +### Inspect a node + +```none +$ docker node inspect swarm-manager + +[ +{ + "ID": "e216jshn25ckzbvmwlnh5jr3g", + "Version": { + "Index": 10 + }, + "CreatedAt": "2016-06-16T22:52:44.9910662Z", + "UpdatedAt": "2016-06-16T22:52:45.230878043Z", + "Spec": { + "Role": "manager", + "Availability": "active" + }, + "Description": { + "Hostname": "swarm-manager", + "Platform": { + "Architecture": "x86_64", + "OS": "linux" }, - "CreatedAt": "2016-06-16T22:52:44.9910662Z", - "UpdatedAt": "2016-06-16T22:52:45.230878043Z", - "Spec": { - "Role": "manager", - "Availability": "active" + "Resources": { + "NanoCPUs": 1000000000, + "MemoryBytes": 1039843328 }, - "Description": { - "Hostname": "swarm-manager", - "Platform": { - "Architecture": "x86_64", - "OS": "linux" - }, - "Resources": { - "NanoCPUs": 1000000000, - "MemoryBytes": 1039843328 - }, - "Engine": { - "EngineVersion": "1.12.0", - "Plugins": [ - { - "Type": "Volume", - "Name": "local" - }, - { - "Type": "Network", - "Name": "overlay" - }, - { - "Type": "Network", - "Name": "null" - }, - { - "Type": "Network", - "Name": "host" - }, - { - "Type": "Network", - "Name": "bridge" - }, - { - "Type": "Network", - "Name": "overlay" - } - ] - } - }, - "Status": { - "State": "ready", - "Addr": "168.0.32.137" - }, - "ManagerStatus": { - "Leader": true, - "Reachability": "reachable", - "Addr": "168.0.32.137:2377" + "Engine": { + "EngineVersion": "1.12.0", + "Plugins": [ + { + "Type": "Volume", + "Name": "local" + }, + { + "Type": "Network", + "Name": "overlay" + }, + { + "Type": "Network", + "Name": "null" + }, + { + "Type": "Network", + "Name": "host" + }, + { + "Type": "Network", + "Name": "bridge" + }, + { + "Type": "Network", + "Name": "overlay" + } + ] } + }, + "Status": { + "State": "ready", + "Addr": "168.0.32.137" + }, + "ManagerStatus": { + "Leader": true, + "Reachability": "reachable", + "Addr": "168.0.32.137:2377" } - ] +} +] +``` - {% raw %} - $ docker node inspect --format '{{ .ManagerStatus.Leader }}' self - false - {% endraw %} +### Specify an output format - $ docker node inspect --pretty self - ID: e216jshn25ckzbvmwlnh5jr3g - Hostname: swarm-manager - Joined at: 2016-06-16 22:52:44.9910662 +0000 utc - Status: - State: Ready - Availability: Active - Address: 172.17.0.2 - Manager Status: - Address: 172.17.0.2:2377 - Raft Status: Reachable - Leader: Yes - Platform: - Operating System: linux - Architecture: x86_64 - Resources: - CPUs: 4 - Memory: 7.704 GiB - Plugins: - Network: overlay, bridge, null, host, overlay - Volume: local - Engine Version: 1.12.0 +```none +{% raw %} +$ docker node inspect --format '{{ .ManagerStatus.Leader }}' self -## Related information +false + +$ docker node inspect --pretty self +ID: e216jshn25ckzbvmwlnh5jr3g +Hostname: swarm-manager +Joined at: 2016-06-16 22:52:44.9910662 +0000 utc +Status: + State: Ready + Availability: Active + Address: 172.17.0.2 +Manager Status: + Address: 172.17.0.2:2377 + Raft Status: Reachable + Leader: Yes +Platform: + Operating System: linux + Architecture: x86_64 +Resources: + CPUs: 4 + Memory: 7.704 GiB +Plugins: + Network: overlay, bridge, null, host, overlay + Volume: local +Engine Version: 1.12.0 +{% endraw %} +``` + +## Related commands * [node demote](node_demote.md) * [node ls](node_ls.md) diff --git a/docs/reference/commandline/node_ls.md b/docs/reference/commandline/node_ls.md index 5f61713c2e..836fceaea2 100644 --- a/docs/reference/commandline/node_ls.md +++ b/docs/reference/commandline/node_ls.md @@ -29,9 +29,13 @@ Options: -q, --quiet Only display IDs ``` -Lists all the nodes that the Docker Swarm manager knows about. You can filter using the `-f` or `--filter` flag. Refer to the [filtering](#filtering) section for more information about available filter options. +## Description -Example output: +Lists all the nodes that the Docker Swarm manager knows about. You can filter +using the `-f` or `--filter` flag. Refer to the [filtering](#filtering) section +for more information about available filter options. + +## Examples ```bash $ docker node ls @@ -42,7 +46,7 @@ ID HOSTNAME STATUS AVAILABILITY MANAGER STATU e216jshn25ckzbvmwlnh5jr3g * swarm-manager1 Ready Active Leader ``` -## Filtering +### Filtering The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) @@ -55,7 +59,7 @@ The currently supported filters are: * [name](node_ls.md#name) * [role](node_ls.md#role) -#### ID +#### id The `id` filter matches all or part of a node's id. @@ -66,7 +70,7 @@ ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS 1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active ``` -#### Label +#### label The `label` filter matches nodes based on engine labels and on the presence of a `label` alone or a `label` and a value. Node labels are currently not used for filtering. @@ -79,7 +83,7 @@ ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS 1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active ``` -#### Membership +#### membersip The `membership` filter matches nodes based on the presence of a `membership` and a value `accepted` or `pending`. @@ -94,7 +98,7 @@ ID HOSTNAME STATUS AVAILABILITY MANAGER STATU 38ciaotwjuritcdtn9npbnkuz swarm-worker1 Ready Active ``` -#### Name +#### name The `name` filter matches on all or part of a node hostname. @@ -107,7 +111,7 @@ ID HOSTNAME STATUS AVAILABILITY MANAGER STATU e216jshn25ckzbvmwlnh5jr3g * swarm-manager1 Ready Active Leader ``` -#### Role +#### role The `role` filter matches nodes based on the presence of a `role` and a value `worker` or `manager`. @@ -120,7 +124,7 @@ ID HOSTNAME STATUS AVAILABILITY MANAGER STATU e216jshn25ckzbvmwlnh5jr3g * swarm-manager1 Ready Active Leader ``` -## Related information +## Related commands * [node demote](node_demote.md) * [node inspect](node_inspect.md) diff --git a/docs/reference/commandline/node_promote.md b/docs/reference/commandline/node_promote.md index 92092a8935..1ebbe9550c 100644 --- a/docs/reference/commandline/node_promote.md +++ b/docs/reference/commandline/node_promote.md @@ -24,14 +24,18 @@ Options: --help Print usage ``` -Promotes a node to manager. This command targets a docker engine that is a manager in the swarm. +## Description +Promotes a node to manager. This command targets a docker engine that is a +manager in the swarm. + +## Examples ```bash $ docker node promote ``` -## Related information +## Related commands * [node demote](node_demote.md) * [node inspect](node_inspect.md) diff --git a/docs/reference/commandline/node_ps.md b/docs/reference/commandline/node_ps.md index 7f07c5ea64..e2e1418287 100644 --- a/docs/reference/commandline/node_ps.md +++ b/docs/reference/commandline/node_ps.md @@ -28,20 +28,23 @@ Options: --no-trunc Do not truncate output ``` +## Description + Lists all the tasks on a Node that Docker knows about. You can filter using the `-f` or `--filter` flag. Refer to the [filtering](#filtering) section for more information about available filter options. -Example output: +## Examples - $ docker node ps swarm-manager1 - NAME IMAGE NODE DESIRED STATE CURRENT STATE - redis.1.7q92v0nr1hcgts2amcjyqg3pq redis:3.0.6 swarm-manager1 Running Running 5 hours - redis.6.b465edgho06e318egmgjbqo4o redis:3.0.6 swarm-manager1 Running Running 29 seconds - redis.7.bg8c07zzg87di2mufeq51a2qp redis:3.0.6 swarm-manager1 Running Running 5 seconds - redis.9.dkkual96p4bb3s6b10r7coxxt redis:3.0.6 swarm-manager1 Running Running 5 seconds - redis.10.0tgctg8h8cech4w0k0gwrmr23 redis:3.0.6 swarm-manager1 Running Running 5 seconds +```bash +$ docker node ps swarm-manager1 +NAME IMAGE NODE DESIRED STATE CURRENT STATE +redis.1.7q92v0nr1hcgts2amcjyqg3pq redis:3.0.6 swarm-manager1 Running Running 5 hours +redis.6.b465edgho06e318egmgjbqo4o redis:3.0.6 swarm-manager1 Running Running 29 seconds +redis.7.bg8c07zzg87di2mufeq51a2qp redis:3.0.6 swarm-manager1 Running Running 5 seconds +redis.9.dkkual96p4bb3s6b10r7coxxt redis:3.0.6 swarm-manager1 Running Running 5 seconds +redis.10.0tgctg8h8cech4w0k0gwrmr23 redis:3.0.6 swarm-manager1 Running Running 5 seconds +``` - -## Filtering +### Filtering The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) @@ -59,23 +62,27 @@ The `name` filter matches on all or part of a task's name. The following filter matches all tasks with a name containing the `redis` string. - $ docker node ps -f name=redis swarm-manager1 - NAME IMAGE NODE DESIRED STATE CURRENT STATE - redis.1.7q92v0nr1hcgts2amcjyqg3pq redis:3.0.6 swarm-manager1 Running Running 5 hours - redis.6.b465edgho06e318egmgjbqo4o redis:3.0.6 swarm-manager1 Running Running 29 seconds - redis.7.bg8c07zzg87di2mufeq51a2qp redis:3.0.6 swarm-manager1 Running Running 5 seconds - redis.9.dkkual96p4bb3s6b10r7coxxt redis:3.0.6 swarm-manager1 Running Running 5 seconds - redis.10.0tgctg8h8cech4w0k0gwrmr23 redis:3.0.6 swarm-manager1 Running Running 5 seconds +```bash +$ docker node ps -f name=redis swarm-manager1 +NAME IMAGE NODE DESIRED STATE CURRENT STATE +redis.1.7q92v0nr1hcgts2amcjyqg3pq redis:3.0.6 swarm-manager1 Running Running 5 hours +redis.6.b465edgho06e318egmgjbqo4o redis:3.0.6 swarm-manager1 Running Running 29 seconds +redis.7.bg8c07zzg87di2mufeq51a2qp redis:3.0.6 swarm-manager1 Running Running 5 seconds +redis.9.dkkual96p4bb3s6b10r7coxxt redis:3.0.6 swarm-manager1 Running Running 5 seconds +redis.10.0tgctg8h8cech4w0k0gwrmr23 redis:3.0.6 swarm-manager1 Running Running 5 seconds +``` #### id The `id` filter matches a task's id. - $ docker node ps -f id=bg8c07zzg87di2mufeq51a2qp swarm-manager1 - NAME IMAGE NODE DESIRED STATE CURRENT STATE - redis.7.bg8c07zzg87di2mufeq51a2qp redis:3.0.6 swarm-manager1 Running Running 5 seconds +```bash +$ docker node ps -f id=bg8c07zzg87di2mufeq51a2qp swarm-manager1 +NAME IMAGE NODE DESIRED STATE CURRENT STATE +redis.7.bg8c07zzg87di2mufeq51a2qp redis:3.0.6 swarm-manager1 Running Running 5 seconds +``` #### label @@ -86,6 +93,7 @@ The following filter matches tasks with the `usage` label regardless of its valu ```bash $ docker node ps -f "label=usage" + NAME IMAGE NODE DESIRED STATE CURRENT STATE redis.6.b465edgho06e318egmgjbqo4o redis:3.0.6 swarm-manager1 Running Running 10 minutes redis.7.bg8c07zzg87di2mufeq51a2qp redis:3.0.6 swarm-manager1 Running Running 9 minutes @@ -97,7 +105,7 @@ redis.7.bg8c07zzg87di2mufeq51a2qp redis:3.0.6 swarm-manager1 Running R The `desired-state` filter can take the values `running`, `shutdown`, and `accepted`. -## Related information +## Related commands * [node demote](node_demote.md) * [node inspect](node_inspect.md) diff --git a/docs/reference/commandline/node_rm.md b/docs/reference/commandline/node_rm.md index b245d636cc..c2fdd4d156 100644 --- a/docs/reference/commandline/node_rm.md +++ b/docs/reference/commandline/node_rm.md @@ -28,33 +28,40 @@ Options: --help Print usage ``` +## Description + When run from a manager node, removes the specified nodes from a swarm. -Example output: +## Examples -```nohighlight +### Remove a stopped node from the swarm + +```bash $ docker node rm swarm-node-02 Node swarm-node-02 removed from swarm ``` +### Attempt to remove a running node from a swarm Removes the specified nodes from the swarm, but only if the nodes are in the down state. If you attempt to remove an active node you will receive an error: -```nohighlight +```non $ docker node rm swarm-node-03 Error response from daemon: rpc error: code = 9 desc = node swarm-node-03 is not down and can't be removed ``` +### Forcibly remove an inaccessible node from a swarm + If you lose access to a worker node or need to shut it down because it has been compromised or is not behaving as expected, you can use the `--force` option. This may cause transient errors or interruptions, depending on the type of task being run on the node. -```nohighlight +```bash $ docker node rm --force swarm-node-03 Node swarm-node-03 removed from swarm @@ -63,7 +70,7 @@ Node swarm-node-03 removed from swarm A manager node must be demoted to a worker node (using `docker node demote`) before you can remove it from the swarm. -## Related information +## Related commands * [node demote](node_demote.md) * [node inspect](node_inspect.md) diff --git a/docs/reference/commandline/node_update.md b/docs/reference/commandline/node_update.md index aa65d0309e..ba824c9494 100644 --- a/docs/reference/commandline/node_update.md +++ b/docs/reference/commandline/node_update.md @@ -13,7 +13,7 @@ keywords: "resources, update, dynamically" will be rejected. --> -## update +# update ```markdown Usage: docker node update [OPTIONS] NODE @@ -28,6 +28,12 @@ Options: --role string Role of the node (worker/manager) ``` +## Description + +Update metadata about a node, such as its availability, labels, or roles. + +## Examples + ### Add label metadata to a node Add metadata to a swarm node using node labels. You can specify a node label as @@ -39,7 +45,7 @@ $ docker node update --label-add foo worker1 To add multiple labels to a node, pass the `--label-add` flag for each label: -``` bash +```bash $ docker node update --label-add foo --label-add bar worker1 ``` @@ -61,7 +67,7 @@ entity within the swarm. Do not confuse them with the docker daemon labels for For more information about labels, refer to [apply custom metadata](https://docs.docker.com/engine/userguide/labels-custom-metadata/). -## Related information +## Related commands * [node demote](node_demote.md) * [node inspect](node_inspect.md) diff --git a/docs/reference/commandline/pause.md b/docs/reference/commandline/pause.md index e2dd800d5f..5bb652b923 100644 --- a/docs/reference/commandline/pause.md +++ b/docs/reference/commandline/pause.md @@ -24,6 +24,8 @@ Options: --help Print usage ``` +## Description + The `docker pause` command suspends all processes in the specified containers. On Linux, this uses the cgroups freezer. Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. @@ -35,6 +37,12 @@ See the [cgroups freezer documentation](https://www.kernel.org/doc/Documentation/cgroup-v1/freezer-subsystem.txt) for further details. -## Related information +## Examples + +```bash +$ docker pause my_container +``` + +## Related commands * [unpause](unpause.md) diff --git a/docs/reference/commandline/plugin_create.md b/docs/reference/commandline/plugin_create.md index fa74d31c39..6f1754326b 100644 --- a/docs/reference/commandline/plugin_create.md +++ b/docs/reference/commandline/plugin_create.md @@ -21,34 +21,38 @@ Usage: docker plugin create [OPTIONS] PLUGIN PLUGIN-DATA-DIR Create a plugin from a rootfs and configuration. Plugin data directory must contain config.json and rootfs directory. Options: - --compress Compress the context using gzip + --compress Compress the context using gzip --help Print usage ``` +## Description + Creates a plugin. Before creating the plugin, prepare the plugin's root filesystem as well as [the config.json](../../extend/config.md) +## Examples The following example shows how to create a sample `plugin`. ```bash - $ ls -ls /home/pluginDir 4 -rw-r--r-- 1 root root 431 Nov 7 01:40 config.json 0 drwxr-xr-x 19 root root 420 Nov 7 01:40 rootfs $ docker plugin create plugin /home/pluginDir + plugin $ docker plugin ls + ID NAME TAG DESCRIPTION ENABLED 672d8144ec02 plugin latest A sample plugin for Docker false ``` The plugin can subsequently be enabled for local use or pushed to the public registry. -## Related information +## Related commands * [plugin disable](plugin_disable.md) * [plugin enable](plugin_enable.md) diff --git a/docs/reference/commandline/plugin_disable.md b/docs/reference/commandline/plugin_disable.md index 451f1ace9c..2ff81887f7 100644 --- a/docs/reference/commandline/plugin_disable.md +++ b/docs/reference/commandline/plugin_disable.md @@ -25,10 +25,13 @@ Options: --help Print usage ``` +## Description + Disables a plugin. The plugin must be installed before it can be disabled, see [`docker plugin install`](plugin_install.md). Without the `-f` option, a plugin that has references (eg, volumes, networks) cannot be disabled. +## Examples The following example shows that the `sample-volume-plugin` plugin is installed and enabled: @@ -53,7 +56,7 @@ ID NAME TAG DESCRIP 69553ca1d123 tiborvass/sample-volume-plugin latest A test plugin for Docker false ``` -## Related information +## Related commands * [plugin create](plugin_create.md) * [plugin enable](plugin_enable.md) diff --git a/docs/reference/commandline/plugin_enable.md b/docs/reference/commandline/plugin_enable.md index df8bee3af5..2098a115ad 100644 --- a/docs/reference/commandline/plugin_enable.md +++ b/docs/reference/commandline/plugin_enable.md @@ -25,9 +25,12 @@ Options: --timeout int HTTP client timeout (in seconds) ``` +## Description + Enables a plugin. The plugin must be installed before it can be enabled, see [`docker plugin install`](plugin_install.md). +## Examples The following example shows that the `sample-volume-plugin` plugin is installed, but disabled: @@ -52,7 +55,7 @@ ID NAME TAG DESCRIP 69553ca1d123 tiborvass/sample-volume-plugin latest A test plugin for Docker true ``` -## Related information +## Related commands * [plugin create](plugin_create.md) * [plugin disable](plugin_disable.md) diff --git a/docs/reference/commandline/plugin_inspect.md b/docs/reference/commandline/plugin_inspect.md index fdcc030c43..3a54b9f99b 100644 --- a/docs/reference/commandline/plugin_inspect.md +++ b/docs/reference/commandline/plugin_inspect.md @@ -25,15 +25,17 @@ Options: --help Print usage ``` +## Description + Returns information about a plugin. By default, this command renders all results in a JSON array. -Example output: +## Examples -```bash + +```none $ docker plugin inspect tiborvass/sample-volume-plugin:latest -``` -```JSON + { "Id": "8c74c978c434745c3ade82f1bc0acf38d04990eaf494fa507c16d9f1daa99c21", "Name": "tiborvass/sample-volume-plugin:latest", @@ -140,18 +142,21 @@ $ docker plugin inspect tiborvass/sample-volume-plugin:latest } } ``` + (output formatted for readability) +### Formatting the output ```bash +{% raw %} $ docker plugin inspect -f '{{.Id}}' tiborvass/sample-volume-plugin:latest -``` -``` + 8c74c978c434745c3ade82f1bc0acf38d04990eaf494fa507c16d9f1daa99c21 +{% endraw %} ``` -## Related information +## Related commands * [plugin create](plugin_create.md) * [plugin enable](plugin_enable.md) diff --git a/docs/reference/commandline/plugin_install.md b/docs/reference/commandline/plugin_install.md index 4cba32cf8b..78d9a61b75 100644 --- a/docs/reference/commandline/plugin_install.md +++ b/docs/reference/commandline/plugin_install.md @@ -28,16 +28,19 @@ Options: --help Print usage ``` +## Description + Installs and enables a plugin. Docker looks first for the plugin on your Docker host. If the plugin does not exist locally, then the plugin is pulled from the registry. Note that the minimum required registry version to distribute plugins is 2.3.0 +## Examples -The following example installs `vieus/sshfs` plugin and [set](plugin_set.md) it's env variable -`DEBUG` to 1. Install consists of pulling the plugin from Docker Hub, prompting -the user to accept the list of privileges that the plugin needs, settings parameters - and enabling the plugin. +The following example installs `vieus/sshfs` plugin and [sets](plugin_set.md) its +`DEBUG` environment variable to `1`. To install, `pull` the plugin from Docker +Hub and prompt the user to accept the list of privileges that the plugin needs, +set the plugin's parameters and enable the plugin. ```bash $ docker plugin install vieux/sshfs DEBUG=1 @@ -59,7 +62,7 @@ ID NAME TAG DESCRIPTION 69553ca1d123 vieux/sshfs latest sshFS plugin for Docker true ``` -## Related information +## Related commands * [plugin create](plugin_create.md) * [plugin disable](plugin_disable.md) diff --git a/docs/reference/commandline/plugin_ls.md b/docs/reference/commandline/plugin_ls.md index 7a3426d95f..9c44b48b53 100644 --- a/docs/reference/commandline/plugin_ls.md +++ b/docs/reference/commandline/plugin_ls.md @@ -28,10 +28,12 @@ Options: --no-trunc Don't truncate output ``` +## Description + Lists all the plugins that are currently installed. You can install plugins using the [`docker plugin install`](plugin_install.md) command. -Example output: +## Examples ```bash $ docker plugin ls @@ -40,7 +42,69 @@ ID NAME TAG DESCRIP 69553ca1d123 tiborvass/sample-volume-plugin latest A test plugin for Docker true ``` -## Related information +### Filtering + +The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more +than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) + +The currently supported filters are: + +* enabled (boolean - true or false, 0 or 1) +* capability (string - currently `volumedriver`, `networkdriver`, `ipamdriver`, or `authz`) + +#### enabled + +The `enabled` filter matches on plugins enabled or disabled. + +#### capability + +The `capability` filter matches on plugin capabilities. One plugin +might have multiple capabilities. Currently `volumedriver`, `networkdriver`, +`ipamdriver`, and `authz` are supported capabilities. + +```bash +$ docker plugin install --disable tiborvass/no-remove + +tiborvass/no-remove + +$ docker plugin ls --filter enabled=true + +NAME TAG DESCRIPTION ENABLED +``` + + +### Formatting + +The formatting options (`--format`) pretty-prints plugins output +using a Go template. + +Valid placeholders for the Go template are listed below: + +Placeholder | Description +---------------|------------------------------------------------------------------------------------------ +`.ID` | Plugin ID +`.Name` | Plugin name +`.Description` | Plugin description +`.Enabled` | Whether plugin is enabled or not +`.PluginReference` | The reference used to push/pull from a registry + +When using the `--format` option, the `plugin ls` command will either +output the data exactly as the template declares or, when using the +`table` directive, includes column headers as well. + +The following example uses a template without headers and outputs the +`ID` and `Name` entries separated by a colon for all plugins: + +```bash +{% raw %} +$ docker plugin ls --format "{{.ID}}: {{.Name}}" + +4be01827a72e: tiborvass/no-remove +{% endraw %} +``` + + +## Related commands * [plugin create](plugin_create.md) * [plugin disable](plugin_disable.md) diff --git a/docs/reference/commandline/plugin_push.md b/docs/reference/commandline/plugin_push.md index e61d10994c..905fa82ef1 100644 --- a/docs/reference/commandline/plugin_push.md +++ b/docs/reference/commandline/plugin_push.md @@ -22,22 +22,27 @@ Options: --help Print usage ``` -Use `docker plugin create` to create the plugin. Once the plugin is ready for distribution, -use `docker plugin push` to share your images to the Docker Hub registry or to a self-hosted one. +## Description + +After you have created a plugin using `docker plugin create` and the plugin is +ready for distribution, use `docker plugin push` to share your images to Docker +Hub or a self-hosted registry. Registry credentials are managed by [docker login](login.md). +## Examples + The following example shows how to push a sample `user/plugin`. ```bash - $ docker plugin ls + ID NAME TAG DESCRIPTION ENABLED 69553ca1d456 user/plugin latest A sample plugin for Docker false $ docker plugin push user/plugin ``` -## Related information +## Related commands * [plugin create](plugin_create.md) * [plugin disable](plugin_disable.md) diff --git a/docs/reference/commandline/plugin_rm.md b/docs/reference/commandline/plugin_rm.md index 323ce83f3c..c820c869fd 100644 --- a/docs/reference/commandline/plugin_rm.md +++ b/docs/reference/commandline/plugin_rm.md @@ -28,12 +28,17 @@ Options: --help Print usage ``` +## Description + Removes a plugin. You cannot remove a plugin if it is enabled, you must disable a plugin using the [`docker plugin disable`](plugin_disable.md) before removing it (or use --force, use of force is not recommended, since it can affect functioning of running containers using the plugin). -The following example disables and removes the `sample-volume-plugin:latest` plugin; +## Examples + +The following example disables and removes the `sample-volume-plugin:latest` +plugin: ```bash $ docker plugin disable tiborvass/sample-volume-plugin @@ -43,7 +48,7 @@ $ docker plugin rm tiborvass/sample-volume-plugin:latest tiborvass/sample-volume-plugin ``` -## Related information +## Related commands * [plugin create](plugin_create.md) * [plugin disable](plugin_disable.md) diff --git a/docs/reference/commandline/plugin_set.md b/docs/reference/commandline/plugin_set.md index c206a8a760..e63215a7ed 100644 --- a/docs/reference/commandline/plugin_set.md +++ b/docs/reference/commandline/plugin_set.md @@ -24,6 +24,8 @@ Options: --help Print usage ``` +## Description + Change settings for a plugin. The plugin must be disabled. The settings currently supported are: @@ -32,23 +34,33 @@ The settings currently supported are: * path of devices * args +## Examples + +### Change an environment variable + The following example change the env variable `DEBUG` on the `sample-volume-plugin` plugin. ```bash +{% raw %} $ docker plugin inspect -f {{.Settings.Env}} tiborvass/sample-volume-plugin + [DEBUG=0] $ docker plugin set tiborvass/sample-volume-plugin DEBUG=1 $ docker plugin inspect -f {{.Settings.Env}} tiborvass/sample-volume-plugin [DEBUG=1] +{% endraw %} ``` +### Change the source of a mount + The following example change the source of the `mymount` mount on the `myplugin` plugin. ```bash +{% raw %} $ docker plugin inspect -f '{{with $mount := index .Settings.Mounts 0}}{{$mount.Source}}{{end}}' myplugin /foo @@ -56,14 +68,19 @@ $ docker plugins set myplugin mymount.source=/bar $ docker plugin inspect -f '{{with $mount := index .Settings.Mounts 0}}{{$mount.Source}}{{end}}' myplugin /bar +{% endraw %} ``` -Note: since only `source` is settable in `mymount`, `docker plugins set mymount=/bar myplugin` would work too. +> **Note**: Since only `source` is settable in `mymount`, +> `docker plugins set mymount=/bar myplugin` would work too. + +### Change a device path The following example change the path of the `mydevice` device on the `myplugin` plugin. ```bash +{% raw %} $ docker plugin inspect -f '{{with $device := index .Settings.Devices 0}}{{$device.Path}}{{end}}' myplugin /dev/foo @@ -71,13 +88,18 @@ $ docker plugins set myplugin mydevice.path=/dev/bar $ docker plugin inspect -f '{{with $device := index .Settings.Devices 0}}{{$device.Path}}{{end}}' myplugin /dev/bar +{% endraw %} ``` -Note: since only `path` is settable in `mydevice`, `docker plugins set mydevice=/dev/bar myplugin` would work too. +> **Note**: Since only `path` is settable in `mydevice`, +> `docker plugins set mydevice=/dev/bar myplugin` would work too. + +### Change the source of the arguments The following example change the source of the args on the `myplugin` plugin. ```bash +{% raw %} $ docker plugin inspect -f '{{.Settings.Args}}' myplugin ["foo", "bar"] @@ -85,9 +107,10 @@ $ docker plugins set myplugin args="foo bar baz" $ docker plugin inspect -f '{{.Settings.Args}}' myplugin ["foo", "bar", "baz"] +{% endraw %} ``` -## Related information +## Related commands * [plugin create](plugin_create.md) * [plugin disable](plugin_disable.md) diff --git a/docs/reference/commandline/plugin_upgrade.md b/docs/reference/commandline/plugin_upgrade.md index 20efc577aa..38191fff73 100644 --- a/docs/reference/commandline/plugin_upgrade.md +++ b/docs/reference/commandline/plugin_upgrade.md @@ -27,11 +27,15 @@ Options: --skip-remote-check Do not check if specified remote plugin matches existing plugin image ``` +## Description + Upgrades an existing plugin to the specified remote plugin image. If no remote is specified, Docker will re-pull the current image and use the updated version. All existing references to the plugin will continue to work. The plugin must be disabled before running the upgrade. +## Examples + The following example installs `vieus/sshfs` plugin, uses it to create and use a volume, then upgrades the plugin. @@ -71,7 +75,7 @@ $ docker run -it -v sshvolume:/data alpine sh -c "ls /data" hello ``` -## Related information +## Related commands * [plugin create](plugin_create.md) * [plugin disable](plugin_disable.md) diff --git a/docs/reference/commandline/port.md b/docs/reference/commandline/port.md index bc90b6e786..c38763ea34 100644 --- a/docs/reference/commandline/port.md +++ b/docs/reference/commandline/port.md @@ -24,18 +24,24 @@ Options: --help Print usage ``` +## Examples + +### Show all mapped ports + You can find out all the ports mapped by not specifying a `PRIVATE_PORT`, or just a specific mapping: - $ docker ps - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - b650456536c7 busybox:latest top 54 minutes ago Up 54 minutes 0.0.0.0:1234->9876/tcp, 0.0.0.0:4321->7890/tcp test - $ docker port test - 7890/tcp -> 0.0.0.0:4321 - 9876/tcp -> 0.0.0.0:1234 - $ docker port test 7890/tcp - 0.0.0.0:4321 - $ docker port test 7890/udp - 2014/06/24 11:53:36 Error: No public port '7890/udp' published for test - $ docker port test 7890 - 0.0.0.0:4321 +```bash +$ docker ps +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +b650456536c7 busybox:latest top 54 minutes ago Up 54 minutes 0.0.0.0:1234->9876/tcp, 0.0.0.0:4321->7890/tcp test +$ docker port test +7890/tcp -> 0.0.0.0:4321 +9876/tcp -> 0.0.0.0:1234 +$ docker port test 7890/tcp +0.0.0.0:4321 +$ docker port test 7890/udp +2014/06/24 11:53:36 Error: No public port '7890/udp' published for test +$ docker port test 7890 +0.0.0.0:4321 +``` diff --git a/docs/reference/commandline/ps.md b/docs/reference/commandline/ps.md index 164e36433c..9fb5222513 100644 --- a/docs/reference/commandline/ps.md +++ b/docs/reference/commandline/ps.md @@ -46,6 +46,10 @@ Options: -s, --size Display total file sizes ``` +## Examples + +### Prevent truncating output + Running `docker ps --no-trunc` showing 2 linked containers. ```bash @@ -56,6 +60,8 @@ CONTAINER ID IMAGE COMMAND CREATED d7886598dbe2 crosbymichael/redis:latest /redis-server --dir 33 minutes ago Up 33 minutes 6379/tcp redis,webapp/db ``` +### Show both running and stopped containers + The `docker ps` command only shows running containers by default. To see all containers, use the `-a` (or `--all`) flag: @@ -67,7 +73,7 @@ $ docker ps -a container that exposes TCP ports `100, 101, 102` displays `100-102/tcp` in the `PORTS` column. -## Filtering +### Filtering The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`) @@ -87,7 +93,7 @@ The currently supported filters are: * network (network id or name) - filters containers connected to the provided network * health (starting|healthy|unhealthy|none) - filters containers based on healthcheck status -#### Label +#### label The `label` filter matches containers based on the presence of a `label` alone or a `label` and a value. @@ -111,7 +117,7 @@ CONTAINER ID IMAGE COMMAND CREATED d85756f57265 busybox "top" About a minute ago Up About a minute high_albattani ``` -#### Name +#### name The `name` filter matches on all or part of a container's name. @@ -135,7 +141,7 @@ CONTAINER ID IMAGE COMMAND CREATED 673394ef1d4c busybox "top" 38 minutes ago Up 38 minutes nostalgic_shockley ``` -#### Exited +#### exited The `exited` filter matches containers by exist status code. For example, to filter for containers that have exited successfully: @@ -149,13 +155,14 @@ ea09c3c82f6e registry:latest /srv/run.sh 2 weeks ago 48ee228c9464 fedora:20 bash 2 weeks ago Exited (0) 2 weeks ago tender_torvalds ``` -#### Killed containers +#### Filter by exit signal You can use a filter to locate containers that exited with status of `137` meaning a `SIGKILL(9)` killed them. -```bash +```none $ docker ps -a --filter 'exited=137' + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES b3e1c0ed5bfe ubuntu:latest "sleep 1000" 12 seconds ago Exited (137) 5 seconds ago grave_kowalevski a2eb5558d669 redis:latest "/entrypoint.sh redi 2 hours ago Exited (137) 2 hours ago sharp_lalande @@ -167,7 +174,7 @@ Any of these events result in a `137` status: * `docker kill` kills the container * Docker daemon restarts which kills all running containers -#### Status +#### status The `status` filter matches containers by status. You can filter using `created`, `restarting`, `running`, `removing`, `paused`, `exited` and `dead`. For example, @@ -191,7 +198,7 @@ CONTAINER ID IMAGE COMMAND CREATED 673394ef1d4c busybox "top" About an hour ago Up About an hour (Paused) nostalgic_shockley ``` -#### Ancestor +#### ancestor The `ancestor` filter matches containers based on its image or a descendant of it. The filter supports the following image representation: @@ -244,7 +251,9 @@ CONTAINER ID IMAGE COMMAND CREATED 82a598284012 ubuntu:12.04.5 "top" 3 minutes ago Up 3 minutes sleepy_bose ``` -#### Before +#### Create time + +##### before The `before` filter shows only containers created before the container with given id or name. For example, having these containers created: @@ -268,7 +277,7 @@ CONTAINER ID IMAGE COMMAND CREATED STATUS 6e63f6ff38b0 busybox "top" About a minute ago Up About a minute distracted_fermat ``` -#### Since +##### since The `since` filter shows only containers created since the container with given id or name. For example, with the same containers as in `before` filter: @@ -281,12 +290,13 @@ CONTAINER ID IMAGE COMMAND CREATED STATUS 4aace5031105 busybox "top" 10 minutes ago Up 10 minutes focused_hamilton ``` -#### Volume +#### volume The `volume` filter shows only containers that mount a specific volume or have a volume mounted in a specific path: -```bash{% raw %} +```bash +{% raw %} $ docker ps --filter volume=remote-volume --format "table {{.ID}}\t{{.Mounts}}" CONTAINER ID MOUNTS 9c3527ed70ce remote-volume @@ -294,9 +304,10 @@ CONTAINER ID MOUNTS $ docker ps --filter volume=/data --format "table {{.ID}}\t{{.Mounts}}" CONTAINER ID MOUNTS 9c3527ed70ce remote-volume -{% endraw %}``` +{% endraw %} +``` -#### Network +#### network The `network` filter shows only containers that are connected to a network with a given name or id. @@ -331,7 +342,45 @@ CONTAINER ID IMAGE COMMAND CREATED STATUS 9d4893ed80fe ubuntu "top" 10 minutes ago Up 10 minutes test1 ``` -## Formatting +#### publish and expose + +The `publish` and `expose` filters show only containers that have published or exposed port with a given port +number, port range, and/or protocol. The default protocol is `tcp` when not specified. + +The following filter matches all containers that have published port of 80: + +```bash +$ docker run -d --publish=80 busybox top +$ docker run -d --expose=8080 busybox top + +$ docker ps -a + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +9833437217a5 busybox "top" 5 seconds ago Up 4 seconds 8080/tcp dreamy_mccarthy +fc7e477723b7 busybox "top" 50 seconds ago Up 50 seconds 0.0.0.0:32768->80/tcp admiring_roentgen + +$ docker ps --filter publish=80 + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +fc7e477723b7 busybox "top" About a minute ago Up About a minute 0.0.0.0:32768->80/tcp admiring_roentgen +``` + +The following filter matches all containers that have exposed TCP port in the range of `8000-8080`: +```bash +$ docker ps --filter expose=8000-8080/tcp + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +9833437217a5 busybox "top" 21 seconds ago Up 19 seconds 8080/tcp dreamy_mccarthy +``` + +The following filter matches all containers that have exposed UDP port `80`: +```bash +$ docker ps --filter publish=80/udp + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +``` + +### Formatting The formatting option (`--format`) pretty-prints container output using a Go template. diff --git a/docs/reference/commandline/pull.md b/docs/reference/commandline/pull.md index 0c960b404a..7bf3df8363 100644 --- a/docs/reference/commandline/pull.md +++ b/docs/reference/commandline/pull.md @@ -26,6 +26,8 @@ Options: --help Print usage ``` +## Description + Most of your images will be created on top of a base image from the [Docker Hub](https://hub.docker.com) registry. @@ -35,7 +37,7 @@ can `pull` and try without needing to define and configure your own. To download a particular image, or set of images (i.e., a repository), use `docker pull`. -## Proxy configuration +### Proxy configuration If you are behind an HTTP proxy server, for example in corporate settings, before open a connect to registry, you may need to configure the Docker @@ -44,7 +46,7 @@ environment variables. To set these environment variables on a host using `systemd`, refer to the [control and configure Docker with systemd](https://docs.docker.com/engine/admin/systemd/#http-proxy) for variables configuration. -## Concurrent downloads +### Concurrent downloads By default the Docker daemon will pull three layers of an image at a time. If you are on a low bandwidth connection this may cause timeout issues and you may want to lower @@ -110,7 +112,7 @@ For more information about images, layers, and the content-addressable store, refer to [understand images, containers, and storage drivers](https://docs.docker.com/engine/userguide/storagedriver/imagesandcontainers/). -## Pull an image by digest (immutable identifier) +### Pull an image by digest (immutable identifier) So far, you've pulled images by their name (and "tag"). Using names and tags is a convenient way to work with images. When using tags, you can `docker pull` an @@ -175,7 +177,7 @@ MAINTAINER some maintainer > digest accordingly. -## Pulling from a different registry +### Pull from a different registry By default, `docker pull` pulls images from [Docker Hub](https://hub.docker.com). It is also possible to manually specify the path of a registry to pull from. For example, if you have @@ -196,7 +198,7 @@ registry is allowed to be accessed over an insecure connection. Refer to the [insecure registries](dockerd.md#insecure-registries) section for more information. -## Pull a repository with multiple images +### Pull a repository with multiple images By default, `docker pull` pulls a *single* image from the registry. A repository can contain multiple images. To pull all images from a repository, provide the @@ -231,7 +233,7 @@ fedora heisenbug 105182bb5e8b 5 days ago 372.7 MB fedora latest 105182bb5e8b 5 days ago 372.7 MB ``` -## Canceling a pull +### Cancel a pull Killing the `docker pull` process, for example by pressing `CTRL-c` while it is running in a terminal, will terminate the pull operation. diff --git a/docs/reference/commandline/push.md b/docs/reference/commandline/push.md index e36fd026d1..d33804d6c4 100644 --- a/docs/reference/commandline/push.md +++ b/docs/reference/commandline/push.md @@ -25,6 +25,8 @@ Options: --help Print usage ``` +## Description + Use `docker push` to share your images to the [Docker Hub](https://hub.docker.com) registry or to a self-hosted one. @@ -36,7 +38,7 @@ running in a terminal, terminates the push operation. Registry credentials are managed by [docker login](login.md). -## Concurrent uploads +### Concurrent uploads By default the Docker daemon will push five layers of an image at a time. If you are on a low bandwidth connection this may cause timeout issues and you may want to lower @@ -45,7 +47,7 @@ this via the `--max-concurrent-uploads` daemon option. See the ## Examples -### Pushing a new image to a registry +### Push a new image to a registry First save the new image by finding the container ID (using [`docker ps`](ps.md)) and then committing it to a new image name. Note that only `a-z0-9-_.` are @@ -62,6 +64,7 @@ registry: ```bash $ docker tag rhel-httpd registry-host:5000/myadmin/rhel-httpd + $ docker push registry-host:5000/myadmin/rhel-httpd ``` diff --git a/docs/reference/commandline/rename.md b/docs/reference/commandline/rename.md index be035f1ce4..90268a2a2c 100644 --- a/docs/reference/commandline/rename.md +++ b/docs/reference/commandline/rename.md @@ -24,4 +24,12 @@ Options: --help Print usage ``` -The `docker rename` command allows the container to be renamed to a different name. +## Description + +The `docker rename` command renames a container. + +## Examples + +```bash +$ docker rename my_container my_new_container +``` diff --git a/docs/reference/commandline/restart.md b/docs/reference/commandline/restart.md index 9f7ed00553..a2796afe33 100644 --- a/docs/reference/commandline/restart.md +++ b/docs/reference/commandline/restart.md @@ -24,3 +24,9 @@ Options: --help Print usage -t, --time int Seconds to wait for stop before killing the container (default 10) ``` + +## Examples + +```bash +$ docker restart my_container +``` diff --git a/docs/reference/commandline/rm.md b/docs/reference/commandline/rm.md index 1c3e795933..8ee5b2874d 100644 --- a/docs/reference/commandline/rm.md +++ b/docs/reference/commandline/rm.md @@ -29,40 +29,71 @@ Options: ## Examples - $ docker rm /redis - /redis +### Remove a container This will remove the container referenced under the link `/redis`. - $ docker rm --link /webapp/redis - /webapp/redis +```bash +$ docker rm /redis + +/redis +``` + +### Remove a link specified with `--link` on the default bridge network This will remove the underlying link between `/webapp` and the `/redis` -containers removing all network communication. +containers on the default bridge network, removing all network communication +between the two containers. This does not apply when `--link` is used with +user-specified networks. - $ docker rm --force redis - redis +```bash +$ docker rm --link /webapp/redis -The main process inside the container referenced under the link `/redis` will receive +/webapp/redis +``` + +### Force-remove a running container + +This command will force-remove a running container. + +```bash +$ docker rm --force redis + +redis +``` + +The main process inside the container referenced under the link `redis` will receive `SIGKILL`, then the container will be removed. - $ docker rm $(docker ps -a -q) +### Remove all stopped containers + +```bash +$ docker rm $(docker ps -a -q) +``` This command will delete all stopped containers. The command `docker ps -a -q` will return all existing container IDs and pass them to the `rm` command which will delete them. Any running containers will not be deleted. - $ docker rm -v redis - redis +### Remove a container and its volumes + +```bash +$ docker rm -v redis +redis +``` This command will remove the container and any volumes associated with it. Note that if a volume was specified with a name, it will not be removed. - $ docker create -v awesome:/foo -v /bar --name hello redis - hello - $ docker rm -v hello +### Remove a container and selectively remove volumes + +```bash +$ docker create -v awesome:/foo -v /bar --name hello redis +hello +$ docker rm -v hello +``` In this example, the volume for `/foo` will remain intact, but the volume for `/bar` will be removed. The same behavior holds for volumes inherited with diff --git a/docs/reference/commandline/rmi.md b/docs/reference/commandline/rmi.md index 149b7635b6..28e21d4398 100644 --- a/docs/reference/commandline/rmi.md +++ b/docs/reference/commandline/rmi.md @@ -26,58 +26,80 @@ Options: --no-prune Do not delete untagged parents ``` +## Examples + You can remove an image using its short or long ID, its tag, or its digest. If an image has one or more tag referencing it, you must remove all of them before the image is removed. Digest references are removed automatically when an image is removed by tag. - $ docker images - REPOSITORY TAG IMAGE ID CREATED SIZE - test1 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) - test latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) - test2 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) +```bash +$ docker images - $ docker rmi fd484f19954f - Error: Conflict, cannot delete image fd484f19954f because it is tagged in multiple repositories, use -f to force - 2013/12/11 05:47:16 Error: failed to remove one or more images +REPOSITORY TAG IMAGE ID CREATED SIZE +test1 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) +test latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) +test2 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) - $ docker rmi test1 - Untagged: test1:latest - $ docker rmi test2 - Untagged: test2:latest +$ docker rmi fd484f19954f - $ docker images - REPOSITORY TAG IMAGE ID CREATED SIZE - test latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) - $ docker rmi test - Untagged: test:latest - Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8 +Error: Conflict, cannot delete image fd484f19954f because it is tagged in multiple repositories, use -f to force +2013/12/11 05:47:16 Error: failed to remove one or more images + +$ docker rmi test1 + +Untagged: test1:latest + +$ docker rmi test2 + +Untagged: test2:latest + + +$ docker images + +REPOSITORY TAG IMAGE ID CREATED SIZE +test latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) + +$ docker rmi test + +Untagged: test:latest +Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8 +``` If you use the `-f` flag and specify the image's short or long ID, then this command untags and removes all images that match the specified ID. - $ docker images - REPOSITORY TAG IMAGE ID CREATED SIZE - test1 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) - test latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) - test2 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) +```bash +$ docker images - $ docker rmi -f fd484f19954f - Untagged: test1:latest - Untagged: test:latest - Untagged: test2:latest - Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8 +REPOSITORY TAG IMAGE ID CREATED SIZE +test1 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) +test latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) +test2 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) + +$ docker rmi -f fd484f19954f + +Untagged: test1:latest +Untagged: test:latest +Untagged: test2:latest +Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8 +``` An image pulled by digest has no tag associated with it: - $ docker images --digests - REPOSITORY TAG DIGEST IMAGE ID CREATED SIZE - localhost:5000/test/busybox sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf 4986bf8c1536 9 weeks ago 2.43 MB +```bash +$ docker images --digests + +REPOSITORY TAG DIGEST IMAGE ID CREATED SIZE +localhost:5000/test/busybox sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf 4986bf8c1536 9 weeks ago 2.43 MB +``` To remove an image using its digest: - $ docker rmi localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf - Untagged: localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf - Deleted: 4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125 - Deleted: ea13149945cb6b1e746bf28032f02e9b5a793523481a0a18645fc77ad53c4ea2 - Deleted: df7546f9f060a2268024c8a230d8639878585defcc1bc6f79d2728a13957871b +```bash +$ docker rmi localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf +Untagged: localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf +Deleted: 4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125 +Deleted: ea13149945cb6b1e746bf28032f02e9b5a793523481a0a18645fc77ad53c4ea2 +Deleted: df7546f9f060a2268024c8a230d8639878585defcc1bc6f79d2728a13957871b +``` diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md index e57ba4bbea..1ec6bf98cf 100644 --- a/docs/reference/commandline/run.md +++ b/docs/reference/commandline/run.md @@ -144,6 +144,8 @@ Options: -w, --workdir string Working directory inside the container ``` +## Descriptino + The `docker run` command first `creates` a writeable container layer over the specified image, and then `starts` it using the specified command. That is, `docker run` is equivalent to the API `/containers/create` then @@ -160,12 +162,15 @@ For information on connecting a container to a network, see the ["*Docker networ ### Assign name and allocate pseudo-TTY (--name, -it) - $ docker run --name test -it debian - root@d6c0fe130dba:/# exit 13 - $ echo $? - 13 - $ docker ps -a | grep test - d6c0fe130dba debian:7 "/bin/bash" 26 seconds ago Exited (13) 17 seconds ago test +```bash +$ docker run --name test -it debian + +root@d6c0fe130dba:/# exit 13 +$ echo $? +13 +$ docker ps -a | grep test +d6c0fe130dba debian:7 "/bin/bash" 26 seconds ago Exited (13) 17 seconds ago test +``` This example runs a container named `test` using the `debian:latest` image. The `-it` instructs Docker to allocate a pseudo-TTY connected to @@ -176,7 +181,9 @@ In the example, the `bash` shell is quit by entering ### Capture container ID (--cidfile) - $ docker run --cidfile /tmp/docker_test.cid ubuntu echo "test" +```bash +$ docker run --cidfile /tmp/docker_test.cid ubuntu echo "test" +``` This will create a container and print `test` to the console. The `cidfile` flag makes Docker attempt to create a new file and write the container ID to it. @@ -185,19 +192,23 @@ file when `docker run` exits. ### Full container capabilities (--privileged) - $ docker run -t -i --rm ubuntu bash - root@bc338942ef20:/# mount -t tmpfs none /mnt - mount: permission denied +```bash +$ docker run -t -i --rm ubuntu bash +root@bc338942ef20:/# mount -t tmpfs none /mnt +mount: permission denied +``` This will *not* work, because by default, most potentially dangerous kernel capabilities are dropped; including `cap_sys_admin` (which is required to mount filesystems). However, the `--privileged` flag will allow it to run: - $ docker run -t -i --privileged ubuntu bash - root@50e3f57e16e6:/# mount -t tmpfs none /mnt - root@50e3f57e16e6:/# df -h - Filesystem Size Used Avail Use% Mounted on - none 1.9G 0 1.9G 0% /mnt +```bash +$ docker run -t -i --privileged ubuntu bash +root@50e3f57e16e6:/# mount -t tmpfs none /mnt +root@50e3f57e16e6:/# df -h +Filesystem Size Used Avail Use% Mounted on +none 1.9G 0 1.9G 0% /mnt +``` The `--privileged` flag gives *all* capabilities to the container, and it also lifts all the limitations enforced by the `device` cgroup controller. In other @@ -206,14 +217,18 @@ flag exists to allow special use-cases, like running Docker within Docker. ### Set working directory (-w) - $ docker run -w /path/to/dir/ -i -t ubuntu pwd +```bash +$ docker run -w /path/to/dir/ -i -t ubuntu pwd +``` The `-w` lets the command being executed inside directory given, here `/path/to/dir/`. If the path does not exist it is created inside the container. ### Set storage driver options per container - $ docker run -it --storage-opt size=120G fedora /bin/bash +```bash +$ docker run -it --storage-opt size=120G fedora /bin/bash +``` This (size) will allow to set the container rootfs size to 120G at creation time. This option is only available for the `devicemapper`, `btrfs`, `overlay2`, @@ -226,14 +241,18 @@ Under these conditions, user can pass any size less then the backing fs size. ### Mount tmpfs (--tmpfs) - $ docker run -d --tmpfs /run:rw,noexec,nosuid,size=65536k my_image +```bash +$ docker run -d --tmpfs /run:rw,noexec,nosuid,size=65536k my_image +``` The `--tmpfs` flag mounts an empty tmpfs into the container with the `rw`, `noexec`, `nosuid`, `size=65536k` options. ### Mount volume (-v, --read-only) - $ docker run -v `pwd`:`pwd` -w `pwd` -i -t ubuntu pwd +```bash +$ docker run -v `pwd`:`pwd` -w `pwd` -i -t ubuntu pwd +``` The `-v` flag mounts the current working directory into the container. The `-w` lets the command being executed inside the current working directory, by @@ -241,21 +260,27 @@ changing into the directory to the value returned by `pwd`. So this combination executes the command using the container, but inside the current working directory. - $ docker run -v /doesnt/exist:/foo -w /foo -i -t ubuntu bash +```bash +$ docker run -v /doesnt/exist:/foo -w /foo -i -t ubuntu bash +``` When the host directory of a bind-mounted volume doesn't exist, Docker will automatically create this directory on the host for you. In the example above, Docker will create the `/doesnt/exist` folder before starting your container. - $ docker run --read-only -v /icanwrite busybox touch /icanwrite/here +```bash +$ docker run --read-only -v /icanwrite busybox touch /icanwrite/here +``` Volumes can be used in combination with `--read-only` to control where a container writes files. The `--read-only` flag mounts the container's root filesystem as read only prohibiting writes to locations other than the specified volumes for the container. - $ docker run -t -i -v /var/run/docker.sock:/var/run/docker.sock -v /path/to/static-docker-binary:/usr/bin/docker busybox sh +```bash +$ docker run -t -i -v /var/run/docker.sock:/var/run/docker.sock -v /path/to/static-docker-binary:/usr/bin/docker busybox sh +``` By bind-mounting the docker unix socket and statically linked docker binary (refer to [get the linux binary]( @@ -263,45 +288,55 @@ https://docs.docker.com/engine/installation/binaries/#/get-the-linux-binary)), you give the container the full access to create and manipulate the host's Docker daemon. -On Windows, the paths must be specified using Windows-style semantics. +On Windows, the paths must be specified using Windows-style semantics. - PS C:\> docker run -v c:\foo:c:\dest microsoft/nanoserver cmd /s /c type c:\dest\somefile.txt - Contents of file - - PS C:\> docker run -v c:\foo:d: microsoft/nanoserver cmd /s /c type d:\somefile.txt - Contents of file +```powershell +PS C:\> docker run -v c:\foo:c:\dest microsoft/nanoserver cmd /s /c type c:\dest\somefile.txt +Contents of file -The following examples will fail when using Windows-based containers, as the -destination of a volume or bind-mount inside the container must be one of: +PS C:\> docker run -v c:\foo:d: microsoft/nanoserver cmd /s /c type d:\somefile.txt +Contents of file +``` + +The following examples will fail when using Windows-based containers, as the +destination of a volume or bind-mount inside the container must be one of: a non-existing or empty directory; or a drive other than C:. Further, the source of a bind mount must be a local directory, not a file. - net use z: \\remotemachine\share - docker run -v z:\foo:c:\dest ... - docker run -v \\uncpath\to\directory:c:\dest ... - docker run -v c:\foo\somefile.txt:c:\dest ... - docker run -v c:\foo:c: ... - docker run -v c:\foo:c:\existing-directory-with-contents ... +```powershell +net use z: \\remotemachine\share +docker run -v z:\foo:c:\dest ... +docker run -v \\uncpath\to\directory:c:\dest ... +docker run -v c:\foo\somefile.txt:c:\dest ... +docker run -v c:\foo:c: ... +docker run -v c:\foo:c:\existing-directory-with-contents ... +``` For in-depth information about volumes, refer to [manage data in containers](https://docs.docker.com/engine/tutorials/dockervolumes/) ### Publish or expose port (-p, --expose) - $ docker run -p 127.0.0.1:80:8080 ubuntu bash +```bash +$ docker run -p 127.0.0.1:80:8080 ubuntu bash +``` This binds port `8080` of the container to port `80` on `127.0.0.1` of the host machine. The [Docker User Guide](https://docs.docker.com/engine/userguide/networking/default_network/dockerlinks/) explains in detail how to manipulate ports in Docker. - $ docker run --expose 80 ubuntu bash +```bash +$ docker run --expose 80 ubuntu bash +``` This exposes port `80` of the container without publishing the port to the host system's interfaces. ### Set environment variables (-e, --env, --env-file) - $ docker run -e MYVAR1 --env MYVAR2=foo --env-file ./env.list ubuntu bash +```bash +$ docker run -e MYVAR1 --env MYVAR2=foo --env-file ./env.list ubuntu bash +``` This sets simple (non-array) environmental variables in the container. For illustration all three @@ -317,10 +352,12 @@ Regardless of the order of these three flags, the `--env-file` are processed first, and then `-e`, `--env` flags. This way, the `-e` or `--env` will override variables as needed. - $ cat ./env.list - TEST_FOO=BAR - $ docker run --env TEST_FOO="This is a test" --env-file ./env.list busybox env | grep TEST_FOO - TEST_FOO=This is a test +```bash +$ cat ./env.list +TEST_FOO=BAR +$ docker run --env TEST_FOO="This is a test" --env-file ./env.list busybox env | grep TEST_FOO +TEST_FOO=This is a test +``` The `--env-file` flag takes a filename as an argument and expects each line to be in the `VAR=VAL` format, mimicking the argument passed to `--env`. Comment @@ -328,53 +365,57 @@ lines need only be prefixed with `#` An example of a file passed with `--env-file` - $ cat ./env.list - TEST_FOO=BAR +```bash +$ cat ./env.list +TEST_FOO=BAR - # this is a comment - TEST_APP_DEST_HOST=10.10.0.127 - TEST_APP_DEST_PORT=8888 - _TEST_BAR=FOO - TEST_APP_42=magic - helloWorld=true - 123qwe=bar - org.spring.config=something +# this is a comment +TEST_APP_DEST_HOST=10.10.0.127 +TEST_APP_DEST_PORT=8888 +_TEST_BAR=FOO +TEST_APP_42=magic +helloWorld=true +123qwe=bar +org.spring.config=something - # pass through this variable from the caller - TEST_PASSTHROUGH - $ TEST_PASSTHROUGH=howdy docker run --env-file ./env.list busybox env - PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin - HOSTNAME=5198e0745561 - TEST_FOO=BAR - TEST_APP_DEST_HOST=10.10.0.127 - TEST_APP_DEST_PORT=8888 - _TEST_BAR=FOO - TEST_APP_42=magic - helloWorld=true - TEST_PASSTHROUGH=howdy - HOME=/root - 123qwe=bar - org.spring.config=something +# pass through this variable from the caller +TEST_PASSTHROUGH +$ TEST_PASSTHROUGH=howdy docker run --env-file ./env.list busybox env +PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin +HOSTNAME=5198e0745561 +TEST_FOO=BAR +TEST_APP_DEST_HOST=10.10.0.127 +TEST_APP_DEST_PORT=8888 +_TEST_BAR=FOO +TEST_APP_42=magic +helloWorld=true +TEST_PASSTHROUGH=howdy +HOME=/root +123qwe=bar +org.spring.config=something - $ docker run --env-file ./env.list busybox env - PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin - HOSTNAME=5198e0745561 - TEST_FOO=BAR - TEST_APP_DEST_HOST=10.10.0.127 - TEST_APP_DEST_PORT=8888 - _TEST_BAR=FOO - TEST_APP_42=magic - helloWorld=true - TEST_PASSTHROUGH= - HOME=/root - 123qwe=bar - org.spring.config=something +$ docker run --env-file ./env.list busybox env +PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin +HOSTNAME=5198e0745561 +TEST_FOO=BAR +TEST_APP_DEST_HOST=10.10.0.127 +TEST_APP_DEST_PORT=8888 +_TEST_BAR=FOO +TEST_APP_42=magic +helloWorld=true +TEST_PASSTHROUGH= +HOME=/root +123qwe=bar +org.spring.config=something +``` ### Set metadata on container (-l, --label, --label-file) A label is a `key=value` pair that applies metadata to a container. To label a container with two labels: - $ docker run -l my-label --label com.example.foo=bar ubuntu bash +```bash +$ docker run -l my-label --label com.example.foo=bar ubuntu bash +``` The `my-label` key doesn't specify a value so the label defaults to an empty string(`""`). To add multiple labels, repeat the label flag (`-l` or `--label`). @@ -387,18 +428,22 @@ Use the `--label-file` flag to load multiple labels from a file. Delimit each label in the file with an EOL mark. The example below loads labels from a labels file in the current directory: - $ docker run --label-file ./labels ubuntu bash +```bash +$ docker run --label-file ./labels ubuntu bash +``` The label-file format is similar to the format for loading environment variables. (Unlike environment variables, labels are not visible to processes running inside a container.) The following example illustrates a label-file format: - com.example.label1="a label" +```none +com.example.label1="a label" - # this is a comment - com.example.label2=another\ label - com.example.label3 +# this is a comment +com.example.label2=another\ label +com.example.label3 +``` You can load multiple label-files by supplying multiple `--label-file` flags. @@ -430,16 +475,18 @@ or name. For `overlay` networks or custom plugins that support multi-host connectivity, containers connected to the same multi-host network but launched from different Engines can also communicate in this way. -**Note**: Service discovery is unavailable on the default bridge network. -Containers can communicate via their IP addresses by default. To communicate -by name, they must be linked. +> **Note**: Service discovery is unavailable on the default bridge network. +> Containers can communicate via their IP addresses by default. To communicate +> by name, they must be linked. You can disconnect a container from a network using the `docker network disconnect` command. ### Mount volumes from container (--volumes-from) - $ docker run --volumes-from 777f7dc92da7 --volumes-from ba8c0c54f0f2:ro -i -t ubuntu pwd +```bash +$ docker run --volumes-from 777f7dc92da7 --volumes-from ba8c0c54f0f2:ro -i -t ubuntu pwd +``` The `--volumes-from` flag mounts all the defined volumes from the referenced containers. Containers can be specified by repetitions of the `--volumes-from` @@ -467,18 +514,24 @@ The `-a` flag tells `docker run` to bind to the container's `STDIN`, `STDOUT` or `STDERR`. This makes it possible to manipulate the output and input as needed. - $ echo "test" | docker run -i -a stdin ubuntu cat - +```bash +$ echo "test" | docker run -i -a stdin ubuntu cat - +``` This pipes data into a container and prints the container's ID by attaching only to the container's `STDIN`. - $ docker run -a stderr ubuntu echo test +```bash +$ docker run -a stderr ubuntu echo test +``` This isn't going to print anything unless there's an error because we've only attached to the `STDERR` of the container. The container's logs still store what's been written to `STDERR` and `STDOUT`. - $ cat somefile | docker run -i -a stdin mybuilder dobuild +```bash +$ cat somefile | docker run -i -a stdin mybuilder dobuild +``` This is how piping a file into a container could be done for a build. The container's ID will be printed after the build is done and the build @@ -488,10 +541,18 @@ retrieve the container's ID once the container has finished running. ### Add host device to container (--device) - $ docker run --device=/dev/sdc:/dev/xvdc --device=/dev/sdd --device=/dev/zero:/dev/nulo -i -t ubuntu ls -l /dev/{xvdc,sdd,nulo} - brw-rw---- 1 root disk 8, 2 Feb 9 16:05 /dev/xvdc - brw-rw---- 1 root disk 8, 3 Feb 9 16:05 /dev/sdd - crw-rw-rw- 1 root root 1, 5 Feb 9 16:05 /dev/nulo +```bash +{% raw %} +$ docker run --device=/dev/sdc:/dev/xvdc \ + --device=/dev/sdd --device=/dev/zero:/dev/nulo \ + -i -t \ + ubuntu ls -l /dev/{xvdc,sdd,nulo} + +brw-rw---- 1 root disk 8, 2 Feb 9 16:05 /dev/xvdc +brw-rw---- 1 root disk 8, 3 Feb 9 16:05 /dev/sdd +crw-rw-rw- 1 root root 1, 5 Feb 9 16:05 /dev/nulo +{% endraw %} +``` It is often necessary to directly expose devices to a container. The `--device` option enables that. For example, a specific block storage device or loop @@ -502,24 +563,24 @@ By default, the container will be able to `read`, `write` and `mknod` these devi This can be overridden using a third `:rwm` set of options to each `--device` flag: +```bash +$ docker run --device=/dev/sda:/dev/xvdc --rm -it ubuntu fdisk /dev/xvdc - $ docker run --device=/dev/sda:/dev/xvdc --rm -it ubuntu fdisk /dev/xvdc +Command (m for help): q +$ docker run --device=/dev/sda:/dev/xvdc:r --rm -it ubuntu fdisk /dev/xvdc +You will not be able to write the partition table. - Command (m for help): q - $ docker run --device=/dev/sda:/dev/xvdc:r --rm -it ubuntu fdisk /dev/xvdc - You will not be able to write the partition table. +Command (m for help): q - Command (m for help): q +$ docker run --device=/dev/sda:/dev/xvdc:rw --rm -it ubuntu fdisk /dev/xvdc - $ docker run --device=/dev/sda:/dev/xvdc:rw --rm -it ubuntu fdisk /dev/xvdc +Command (m for help): q - Command (m for help): q +$ docker run --device=/dev/sda:/dev/xvdc:m --rm -it ubuntu fdisk /dev/xvdc +fdisk: unable to open /dev/xvdc: Operation not permitted +``` - $ docker run --device=/dev/sda:/dev/xvdc:m --rm -it ubuntu fdisk /dev/xvdc - fdisk: unable to open /dev/xvdc: Operation not permitted - -> **Note:** -> `--device` cannot be safely used with ephemeral devices. Block devices +> **Note**: `--device` cannot be safely used with ephemeral devices. Block devices > that may be removed should not be added to untrusted containers with > `--device`. @@ -529,54 +590,15 @@ 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: - - - - - - - - - - - - - - - - - - - - - - - - - -
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, but - do not start it on daemon startup if the container has been put - to a stopped state before. -
+| Policy | Result | +|-------------------|-----------------------------------------| +| `no` | Do not automatically restart the container when it exits. This is the default. | +| `failure` | 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. | - $ docker run --restart=always redis +```bash +$ 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. @@ -591,14 +613,17 @@ You can add other hosts into a container's `/etc/hosts` file by using one or more `--add-host` flags. This example adds a static address for a host named `docker`: - $ docker run --add-host=docker:10.180.0.1 --rm -it debian - root@f38c87f2a42d:/# ping docker - PING docker (10.180.0.1): 48 data bytes - 56 bytes from 10.180.0.1: icmp_seq=0 ttl=254 time=7.600 ms - 56 bytes from 10.180.0.1: icmp_seq=1 ttl=254 time=30.705 ms - ^C--- docker ping statistics --- - 2 packets transmitted, 2 packets received, 0% packet loss - round-trip min/avg/max/stddev = 7.600/19.152/30.705/11.553 ms +```bash +$ docker run --add-host=docker:10.180.0.1 --rm -it debian + +root@f38c87f2a42d:/# ping docker +PING docker (10.180.0.1): 48 data bytes +56 bytes from 10.180.0.1: icmp_seq=0 ttl=254 time=7.600 ms +56 bytes from 10.180.0.1: icmp_seq=1 ttl=254 time=30.705 ms +^C--- docker ping statistics --- +2 packets transmitted, 2 packets received, 0% packet loss +round-trip min/avg/max/stddev = 7.600/19.152/30.705/11.553 ms +``` Sometimes you need to connect to the Docker host from within your container. To enable this, pass the Docker host's IP address to @@ -609,8 +634,12 @@ The flags you pass to `ip addr show` depend on whether you are using IPv4 or IPv6 networking in your containers. Use the following flags for IPv4 address retrieval for a network device named `eth0`: - $ HOSTIP=`ip -4 addr show scope global dev eth0 | grep inet | awk '{print \$2}' | cut -d / -f 1` - $ docker run --add-host=docker:${HOSTIP} --rm -it debian +```bash +{% raw %} +$ HOSTIP=`ip -4 addr show scope global dev eth0 | grep inet | awk '{print \$2}' | cut -d / -f 1` +$ docker run --add-host=docker:${HOSTIP} --rm -it debian +{% endraw %} +``` For IPv6 use the `-6` flag instead of the `-4` flag. For other network devices, replace `eth0` with the correct device name (for example `docker0` @@ -623,15 +652,19 @@ available in the default container, you can set these using the `--ulimit` flag. `--ulimit` is specified with a soft and hard limit as such: `=[:]`, for example: - $ docker run --ulimit nofile=1024:1024 --rm debian sh -c "ulimit -n" - 1024 +```bash +$ docker run --ulimit nofile=1024:1024 --rm debian sh -c "ulimit -n" +1024 +``` -> **Note:** -> If you do not provide a `hard limit`, the `soft limit` will be used +> **Note**: If you do not provide a `hard limit`, the `soft limit` will be used > for both values. If no `ulimits` are set, they will be inherited from > the default `ulimits` set on the daemon. `as` option is disabled now. > In other words, the following script is not supported: -> `$ docker run -it --ulimit as=1024 fedora /bin/bash` +> +> ```bash +> $ docker run -it --ulimit as=1024 fedora /bin/bash` +> ``` The values are sent to the appropriate `syscall` as they are set. Docker doesn't perform any byte conversion. Take this into account when setting the values. @@ -642,10 +675,15 @@ Be careful setting `nproc` with the `ulimit` flag as `nproc` is designed by Linu maximum number of processes available to a user, not to a container. For example, start four containers with `daemon` user: - docker run -d -u daemon --ulimit nproc=3 busybox top - docker run -d -u daemon --ulimit nproc=3 busybox top - docker run -d -u daemon --ulimit nproc=3 busybox top - docker run -d -u daemon --ulimit nproc=3 busybox top +```bash +$ docker run -d -u daemon --ulimit nproc=3 busybox top + +$ docker run -d -u daemon --ulimit nproc=3 busybox top + +$ docker run -d -u daemon --ulimit nproc=3 busybox top + +$ docker run -d -u daemon --ulimit nproc=3 busybox top +``` The 4th container fails and reports "[8] System error: resource temporarily unavailable" error. This fails because the caller set `nproc=3` resulting in the first three containers using up @@ -710,8 +748,9 @@ The `--sysctl` sets namespaced kernel parameters (sysctls) in the container. For example, to turn on IP forwarding in the containers network namespace, run this command: - $ docker run --sysctl net.ipv4.ip_forward=1 someimage - +```bash +$ docker run --sysctl net.ipv4.ip_forward=1 someimage +``` > **Note**: Not all sysctls are namespaced. Docker does not support changing sysctls > inside of a container that also modify the host system. As the kernel @@ -719,14 +758,17 @@ network namespace, run this command: #### Currently supported sysctls - `IPC Namespace`: +- `IPC Namespace`: + ```none kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, kernel.shmall, kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced Sysctls beginning with fs.mqueue.* + ``` If you use the `--ipc=host` option these sysctls will not be allowed. - `Network Namespace`: - Sysctls beginning with net.* +- `Network Namespace`: + + Sysctls beginning with net.* If you use the `--network=host` option using these sysctls will not be allowed. diff --git a/docs/reference/commandline/save.md b/docs/reference/commandline/save.md index 88a5fed103..cba7385e11 100644 --- a/docs/reference/commandline/save.md +++ b/docs/reference/commandline/save.md @@ -25,21 +25,38 @@ Options: -o, --output string Write to a file, instead of STDOUT ``` +## Description + Produces a tarred repository to the standard output stream. Contains all parent layers, and all tags + versions, or specified `repo:tag`, for each argument provided. -It is used to create a backup that can then be used with `docker load` +## Examples - $ docker save busybox > busybox.tar - $ ls -sh busybox.tar - 2.7M busybox.tar - $ docker save --output busybox.tar busybox - $ ls -sh busybox.tar - 2.7M busybox.tar - $ docker save -o fedora-all.tar fedora - $ docker save -o fedora-latest.tar fedora:latest +### Create a backup that can then be used with `docker load`. -It is even useful to cherry-pick particular tags of an image repository +```bash +$ docker save busybox > busybox.tar - $ docker save -o ubuntu.tar ubuntu:lucid ubuntu:saucy +$ ls -sh busybox.tar + +2.7M busybox.tar + +$ docker save --output busybox.tar busybox + +$ ls -sh busybox.tar + +2.7M busybox.tar + +$ docker save -o fedora-all.tar fedora + +$ docker save -o fedora-latest.tar fedora:latest +``` + +### Cherry-pick particular tags + +You can even cherry-pick particular tags of an image repository. + +```bash +$ docker save -o ubuntu.tar ubuntu:lucid ubuntu:saucy +``` diff --git a/docs/reference/commandline/search.md b/docs/reference/commandline/search.md index 31faf37375..f645c78603 100644 --- a/docs/reference/commandline/search.md +++ b/docs/reference/commandline/search.md @@ -30,13 +30,14 @@ Options: --no-trunc Don't truncate output ``` +## Description + Search [Docker Hub](https://hub.docker.com) for images See [*Find Public Images on Docker Hub*](https://docs.docker.com/engine/tutorials/dockerrepos/#searching-for-images) for more details on finding shared images from the command line. -> **Note:** -> Search queries will only return up to 25 results +> **Note**: Search queries return a maximum of 25 results. ## Examples @@ -44,52 +45,57 @@ more details on finding shared images from the command line. This example displays images with a name containing 'busybox': - $ docker search busybox - NAME DESCRIPTION STARS OFFICIAL AUTOMATED - busybox Busybox base image. 316 [OK] - progrium/busybox 50 [OK] - radial/busyboxplus Full-chain, Internet enabled, busybox made... 8 [OK] - odise/busybox-python 2 [OK] - azukiapp/busybox This image is meant to be used as the base... 2 [OK] - ofayau/busybox-jvm Prepare busybox to install a 32 bits JVM. 1 [OK] - shingonoide/archlinux-busybox Arch Linux, a lightweight and flexible Lin... 1 [OK] - odise/busybox-curl 1 [OK] - ofayau/busybox-libc32 Busybox with 32 bits (and 64 bits) libs 1 [OK] - peelsky/zulu-openjdk-busybox 1 [OK] - skomma/busybox-data Docker image suitable for data volume cont... 1 [OK] - elektritter/busybox-teamspeak Lightweight teamspeak3 container based on... 1 [OK] - socketplane/busybox 1 [OK] - oveits/docker-nginx-busybox This is a tiny NginX docker image based on... 0 [OK] - ggtools/busybox-ubuntu Busybox ubuntu version with extra goodies 0 [OK] - nikfoundas/busybox-confd Minimal busybox based distribution of confd 0 [OK] - openshift/busybox-http-app 0 [OK] - jllopis/busybox 0 [OK] - swyckoff/busybox 0 [OK] - powellquiring/busybox 0 [OK] - williamyeh/busybox-sh Docker image for BusyBox's sh 0 [OK] - simplexsys/busybox-cli-powered Docker busybox images, with a few often us... 0 [OK] - fhisamoto/busybox-java Busybox java 0 [OK] - scottabernethy/busybox 0 [OK] - marclop/busybox-solr +```none +$ docker search busybox + +NAME DESCRIPTION STARS OFFICIAL AUTOMATED +busybox Busybox base image. 316 [OK] +progrium/busybox 50 [OK] +radial/busyboxplus Full-chain, Internet enabled, busybox made... 8 [OK] +odise/busybox-python 2 [OK] +azukiapp/busybox This image is meant to be used as the base... 2 [OK] +ofayau/busybox-jvm Prepare busybox to install a 32 bits JVM. 1 [OK] +shingonoide/archlinux-busybox Arch Linux, a lightweight and flexible Lin... 1 [OK] +odise/busybox-curl 1 [OK] +ofayau/busybox-libc32 Busybox with 32 bits (and 64 bits) libs 1 [OK] +peelsky/zulu-openjdk-busybox 1 [OK] +skomma/busybox-data Docker image suitable for data volume cont... 1 [OK] +elektritter/busybox-teamspeak Lightweight teamspeak3 container based on... 1 [OK] +socketplane/busybox 1 [OK] +oveits/docker-nginx-busybox This is a tiny NginX docker image based on... 0 [OK] +ggtools/busybox-ubuntu Busybox ubuntu version with extra goodies 0 [OK] +nikfoundas/busybox-confd Minimal busybox based distribution of confd 0 [OK] +openshift/busybox-http-app 0 [OK] +jllopis/busybox 0 [OK] +swyckoff/busybox 0 [OK] +powellquiring/busybox 0 [OK] +williamyeh/busybox-sh Docker image for BusyBox's sh 0 [OK] +simplexsys/busybox-cli-powered Docker busybox images, with a few often us... 0 [OK] +fhisamoto/busybox-java Busybox java 0 [OK] +scottabernethy/busybox 0 [OK] +marclop/busybox-solr +``` ### Display non-truncated description (--no-trunc) This example displays images with a name containing 'busybox', at least 3 stars and the description isn't truncated in the output: - $ docker search --stars=3 --no-trunc busybox - NAME DESCRIPTION STARS OFFICIAL AUTOMATED - busybox Busybox base image. 325 [OK] - progrium/busybox 50 [OK] - radial/busyboxplus Full-chain, Internet enabled, busybox made from scratch. Comes in git and cURL flavors. 8 [OK] +```bash +$ docker search --stars=3 --no-trunc busybox +NAME DESCRIPTION STARS OFFICIAL AUTOMATED +busybox Busybox base image. 325 [OK] +progrium/busybox 50 [OK] +radial/busyboxplus Full-chain, Internet enabled, busybox made from scratch. Comes in git and cURL flavors. 8 [OK] +``` -## Limit search results (--limit) +### Limit search results (--limit) The flag `--limit` is the maximum number of results returned by a search. This value could be in the range between 1 and 100. The default value of `--limit` is 25. -## Filtering +### Filtering The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`) @@ -101,34 +107,43 @@ The currently supported filters are: * is-official (true|false) - is the image official or not -### stars +#### stars This example displays images with a name containing 'busybox' and at least 3 stars: - $ docker search --filter stars=3 busybox - NAME DESCRIPTION STARS OFFICIAL AUTOMATED - busybox Busybox base image. 325 [OK] - progrium/busybox 50 [OK] - radial/busyboxplus Full-chain, Internet enabled, busybox made... 8 [OK] +```bash +$ docker search --filter stars=3 busybox + +NAME DESCRIPTION STARS OFFICIAL AUTOMATED +busybox Busybox base image. 325 [OK] +progrium/busybox 50 [OK] +radial/busyboxplus Full-chain, Internet enabled, busybox made... 8 [OK] +``` -### is-automated +#### is-automated This example displays images with a name containing 'busybox' and are automated builds: - $ docker search --filter is-automated busybox - NAME DESCRIPTION STARS OFFICIAL AUTOMATED - progrium/busybox 50 [OK] - radial/busyboxplus Full-chain, Internet enabled, busybox made... 8 [OK] +```bash +$ docker search --filter is-automated busybox -### is-official +NAME DESCRIPTION STARS OFFICIAL AUTOMATED +progrium/busybox 50 [OK] +radial/busyboxplus Full-chain, Internet enabled, busybox made... 8 [OK] +``` + +#### is-official This example displays images with a name containing 'busybox', at least 3 stars and are official builds: - $ docker search --filter "is-official=true" --filter "stars=3" busybox - NAME DESCRIPTION STARS OFFICIAL AUTOMATED - progrium/busybox 50 [OK] - radial/busyboxplus Full-chain, Internet enabled, busybox made... 8 [OK] +```bash +$ docker search --filter "is-official=true" --filter "stars=3" busybox + +NAME DESCRIPTION STARS OFFICIAL AUTOMATED +progrium/busybox 50 [OK] +radial/busyboxplus Full-chain, Internet enabled, busybox made... 8 [OK] +``` diff --git a/docs/reference/commandline/secret_create.md b/docs/reference/commandline/secret_create.md index aebcebbcdd..74839f7a9e 100644 --- a/docs/reference/commandline/secret_create.md +++ b/docs/reference/commandline/secret_create.md @@ -25,6 +25,8 @@ Options: -l, --label list Secret labels (default []) ``` +## Description + Creates a secret using standard input or from a file for the secret content. You must run this command on a manager node. @@ -45,9 +47,11 @@ mhv17xfe3gh6xc4rij5orpfds my_secret 2016-10-27 23:25:43.90918108 ```bash $ docker secret create my_secret ./secret.json + mhv17xfe3gh6xc4rij5orpfds $ docker secret ls + ID NAME CREATED UPDATED SIZE mhv17xfe3gh6xc4rij5orpfds my_secret 2016-10-27 23:25:43.909181089 +0000 UTC 2016-10-27 23:25:43.909181089 +0000 UTC 1679 ``` @@ -55,10 +59,16 @@ mhv17xfe3gh6xc4rij5orpfds my_secret 2016-10-27 23:25:43.90918108 ### Create a secret with labels ```bash -$ docker secret create --label env=dev --label rev=20161102 my_secret ./secret.json -jtn7g6aukl5ky7nr9gvwafoxh +$ docker secret create --label env=dev \ + --label rev=20161102 \ + my_secret ./secret.json +jtn7g6aukl5ky7nr9gvwafoxh +``` + +```none $ docker secret inspect my_secret + [ { "ID": "jtn7g6aukl5ky7nr9gvwafoxh", @@ -79,11 +89,10 @@ $ docker secret inspect my_secret "SecretSize": 1679 } ] - ``` -## Related information +## Related commands * [secret inspect](secret_inspect.md) * [secret ls](secret_ls.md) diff --git a/docs/reference/commandline/secret_inspect.md b/docs/reference/commandline/secret_inspect.md index de878f74e4..8ced58d783 100644 --- a/docs/reference/commandline/secret_inspect.md +++ b/docs/reference/commandline/secret_inspect.md @@ -25,6 +25,7 @@ Options: --help Print usage ``` +## Description Inspects the specified secret. This command has to be run targeting a manager node. @@ -37,7 +38,7 @@ describes all the details of the format. ## Examples -### Inspecting a secret by name or ID +### Inspect a secret by name or ID You can inspect a secret, either by its *name*, or *ID* @@ -49,8 +50,9 @@ ID NAME CREATED mhv17xfe3gh6xc4rij5orpfds secret.json 2016-10-27 23:25:43.909181089 +0000 UTC 2016-10-27 23:25:43.909181089 +0000 UTC ``` -```bash +```none $ docker secret inspect secret.json + [ { "ID": "mhv17xfe3gh6xc4rij5orpfds", @@ -66,19 +68,22 @@ $ docker secret inspect secret.json ] ``` -### Formatting secret output +### Formatting You can use the --format option to obtain specific information about a secret. The following example command outputs the creation time of the secret. -```bash{% raw %} +```bash +{% raw %} $ docker secret inspect --format='{{.CreatedAt}}' mhv17xfe3gh6xc4rij5orpfds + 2016-10-27 23:25:43.909181089 +0000 UTC -{% endraw %}``` +{% endraw %} +``` -## Related information +## Related commands * [secret create](secret_create.md) * [secret ls](secret_ls.md) diff --git a/docs/reference/commandline/secret_ls.md b/docs/reference/commandline/secret_ls.md index 6b34fc2146..72b9e4696d 100644 --- a/docs/reference/commandline/secret_ls.md +++ b/docs/reference/commandline/secret_ls.md @@ -27,16 +27,20 @@ Options: -q, --quiet Only display IDs ``` -Run this command on a manager node to list the secrets in the Swarm. +## Description + +Run this command on a manager node to list the secrets in the swarm. ## Examples ```bash $ docker secret ls + ID NAME CREATED UPDATED mhv17xfe3gh6xc4rij5orpfds secret.json 2016-10-27 23:25:43.909181089 +0000 UTC 2016-10-27 23:25:43.909181089 +0000 UTC ``` -## Related information + +## Related commands * [secret create](secret_create.md) * [secret inspect](secret_inspect.md) diff --git a/docs/reference/commandline/secret_rm.md b/docs/reference/commandline/secret_rm.md index f504b1ba4f..9887d3331a 100644 --- a/docs/reference/commandline/secret_rm.md +++ b/docs/reference/commandline/secret_rm.md @@ -27,9 +27,13 @@ Options: --help Print usage ``` +## Description + Removes the specified secrets from the swarm. This command has to be run targeting a manager node. +## Examples + This example removes a secret: ```bash @@ -41,7 +45,7 @@ sapth4csdo5b6wz2p5uimh5xg > before removing a secret. -## Related information +## Related commands * [secret create](secret_create.md) * [secret inspect](secret_inspect.md) diff --git a/docs/reference/commandline/service_create.md b/docs/reference/commandline/service_create.md index 18878219ae..4dd65c0ce1 100644 --- a/docs/reference/commandline/service_create.md +++ b/docs/reference/commandline/service_create.md @@ -68,6 +68,8 @@ Options: -w, --workdir string Working directory inside the container ``` +## Description + Creates a service as described by the specified parameters. You must run this command on a manager node. @@ -77,12 +79,15 @@ command on a manager node. ```bash $ docker service create --name redis redis:3.0.6 + dmu1ept4cxcfe8k8lhtux3ro3 $ docker service create --mode global --name redis2 redis:3.0.6 + a8q9dasaafudfs8q8w32udass $ docker service ls + ID NAME MODE REPLICAS IMAGE dmu1ept4cxcf redis replicated 1/1 redis:3.0.6 a8q9dasaafud redis2 global 1/1 redis:3.0.6 @@ -95,6 +100,7 @@ service. The following command creates a `redis` service with `5` replica tasks: ```bash $ docker service create --name redis --replicas=5 redis:3.0.6 + 4cdgfyky7ozwh3htjfw0d12qv ``` @@ -108,6 +114,7 @@ number of `RUNNING` tasks is `3`: ```bash $ docker service ls + ID NAME MODE REPLICAS IMAGE 4cdgfyky7ozw redis replicated 3/5 redis:3.0.7 ``` @@ -117,11 +124,13 @@ equal to the desired number: ```bash $ docker service ls + ID NAME MODE REPLICAS IMAGE 4cdgfyky7ozw redis replicated 5/5 redis:3.0.7 ``` ### Create a service with secrets + Use the `--secret` flag to give a container access to a [secret](secret_create.md). @@ -129,6 +138,7 @@ Create a service specifying a secret: ```bash $ docker service create --name redis --secret secret.json redis:3.0.6 + 4cdgfyky7ozwh3htjfw0d12qv ``` @@ -139,6 +149,7 @@ $ docker service create --name redis \ --secret source=ssh-key,target=ssh \ --secret source=app-key,target=app,uid=1000,gid=1001,mode=0400 \ redis:3.0.6 + 4cdgfyky7ozwh3htjfw0d12qv ``` @@ -172,12 +183,15 @@ This sets environmental variables for all tasks in a service. For example: $ docker service create --name redis_2 --replicas 5 --env MYVAR=foo redis:3.0.6 ``` -### Create a docker service with specific hostname (--hostname) +### Create a service with specific hostname (--hostname) + +This option sets the docker service containers hostname to a specific string. +For example: -This option sets the docker service containers hostname to a specific string. For example: ```bash $ docker service create --name redis --hostname myredis redis:3.0.6 ``` + ### Set metadata on a service (-l, --label) A label is a `key=value` pair that applies metadata to a service. To label a @@ -201,7 +215,7 @@ or write from files or directories on other containers or the host operating system. These types are _data volumes_ (often referred to simply as volumes) and _bind-mounts_. -Additionally, Docker also supports tmpfs mounts. +Additionally, Docker supports `tmpfs` mounts. A **bind-mount** makes a file or directory on the host available to the container it is mounted within. A bind-mount may be either read-only or @@ -303,19 +317,19 @@ The `--mount` flag supports most options that are supported by the `-v` or `--volume` flag for `docker run`, with some important exceptions: - The `--mount` flag allows you to specify a volume driver and volume driver - options *per volume*, without creating the volumes in advance. In contrast, - `docker run` allows you to specify a single volume driver which is shared - by all volumes, using the `--volume-driver` flag. + options *per volume*, without creating the volumes in advance. In contrast, + `docker run` allows you to specify a single volume driver which is shared + by all volumes, using the `--volume-driver` flag. - The `--mount` flag allows you to specify custom metadata ("labels") for a volume, - before the volume is created. + before the volume is created. - When you use `--mount` with `type=bind`, the host-path must refer to an *existing* - path on the host. The path will not be created for you and the service will fail - with an error if the path does not exist. + path on the host. The path will not be created for you and the service will fail + with an error if the path does not exist. - The `--mount` flag does not allow you to relabel a volume with `Z` or `z` flags, - which are used for `selinux` labeling. + which are used for `selinux` labeling. #### Create a service using a named volume @@ -532,18 +546,25 @@ In this example, we are going to set the template of the created containers base service's name and the node's ID where it sits. ```bash -$ docker service create --name hosttempl --hostname={% raw %}"{{.Node.ID}}-{{.Service.Name}}"{% endraw %} busybox top +{% raw %} +$ docker service create --name hosttempl \ + --hostname={% raw %}"{{.Node.ID}}-{{.Service.Name}}"\ + busybox top + va8ew30grofhjoychbr6iot8c $ docker service ps va8ew30grofhjoychbr6iot8c + ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS wo41w8hg8qan hosttempl.1 busybox:latest@sha256:29f5d56d12684887bdfa50dcd29fc31eea4aaf4ad3bec43daf19026a7ce69912 2e7a8a9c4da2 Running Running about a minute ago -$ docker inspect --format={% raw %}"{{.Config.Hostname}}"{% endraw %} hosttempl.1.wo41w8hg8qanxwjwsg4kxpprj +$ docker inspect --format="{{.Config.Hostname}}" hosttempl.1.wo41w8hg8qanxwjwsg4kxpprj + x3ti0erg11rjpg64m75kej2mz-hosttempl +{% endraw %} ``` -## Related information +## Related commands * [service inspect](service_inspect.md) * [service logs](service_logs.md) diff --git a/docs/reference/commandline/service_inspect.md b/docs/reference/commandline/service_inspect.md index 8b4ab62d89..c36047c589 100644 --- a/docs/reference/commandline/service_inspect.md +++ b/docs/reference/commandline/service_inspect.md @@ -26,6 +26,7 @@ Options: --pretty Print the information in a human friendly format. ``` +## Description Inspects the specified service. This command has to be run targeting a manager node. @@ -38,7 +39,7 @@ describes all the details of the format. ## Examples -### Inspecting a service by name or ID +### Inspect a service by name or ID You can inspect a service, either by its *name*, or *ID* @@ -53,8 +54,9 @@ dmu1ept4cxcf redis replicated 3/3 redis:3.0.6 Both `docker service inspect redis`, and `docker service inspect dmu1ept4cxcf` produce the same result: -```bash +```none $ docker service inspect redis + [ { "ID": "dmu1ept4cxcfe8k8lhtux3ro3", @@ -98,6 +100,7 @@ $ docker service inspect redis ```bash $ docker service inspect dmu1ept4cxcf + [ { "ID": "dmu1ept4cxcfe8k8lhtux3ro3", @@ -109,13 +112,14 @@ $ docker service inspect dmu1ept4cxcf ] ``` -### Inspect a service using pretty-print +### Formatting You can print the inspect output in a human-readable format instead of the default JSON output, by using the `--pretty` option: ```bash $ docker service inspect --pretty frontend + ID: c8wgl7q4ndfd52ni6qftkvnnp Name: frontend Labels: @@ -139,19 +143,22 @@ Ports: You can also use `--format pretty` for the same effect. -### Finding the number of tasks running as part of a service +#### Find the number of tasks running as part of a service The `--format` option can be used to obtain specific information about a service. For example, the following command outputs the number of replicas of the "redis" service. -```bash{% raw %} +```bash +{% raw %} $ docker service inspect --format='{{.Spec.Mode.Replicated.Replicas}}' redis + 10 -{% endraw %}``` +{% endraw %} +``` -## Related information +## Related commands * [service create](service_create.md) * [service logs](service_logs.md) diff --git a/docs/reference/commandline/service_logs.md b/docs/reference/commandline/service_logs.md index fdf6a3a245..844a58e0cf 100644 --- a/docs/reference/commandline/service_logs.md +++ b/docs/reference/commandline/service_logs.md @@ -30,9 +30,11 @@ Options: -t, --timestamps Show timestamps ``` +## Description + The `docker service logs` command batch-retrieves logs present at the time of execution. -> **Note**: this command is only functional for services that are started with +> **Note**: This command is only functional for services that are started with > the `json-file` or `journald` logging driver. For more information about selecting and configuring logging drivers, refer to @@ -66,7 +68,7 @@ seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a fraction of a second no more than nine digits long. You can combine the `--since` option with either or both of the `--follow` or `--tail` options. -## Related information +## Related commands * [service create](service_create.md) * [service inspect](service_inspect.md) diff --git a/docs/reference/commandline/service_ls.md b/docs/reference/commandline/service_ls.md index ccd68af750..2258b5b52f 100644 --- a/docs/reference/commandline/service_ls.md +++ b/docs/reference/commandline/service_ls.md @@ -29,12 +29,18 @@ Options: -q, --quiet Only display IDs ``` +## Description + This command when run targeting a manager, lists services are running in the swarm. +## Examples + On a manager node: + ```bash $ docker service ls + ID NAME MODE REPLICAS IMAGE c8wgl7q4ndfd frontend replicated 5/5 nginx:alpine dmu1ept4cxcf redis replicated 3/3 redis:3.0.6 @@ -44,7 +50,7 @@ iwe3278osahj mongo global 7/7 mongo:3.3 The `REPLICAS` column shows both the *actual* and *desired* number of tasks for the service. -## Filtering +### Filtering The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) @@ -55,7 +61,7 @@ The currently supported filters are: * [label](service_ls.md#label) * [name](service_ls.md#name) -#### ID +#### id The `id` filter matches all or part of a service's id. @@ -65,7 +71,7 @@ ID NAME MODE REPLICAS IMAGE 0bcjwfh8ychr redis replicated 1/1 redis:3.0.6 ``` -#### Label +#### label The `label` filter matches services based on the presence of a `label` alone or a `label` and a value. @@ -91,7 +97,7 @@ ID NAME MODE REPLICAS IMAGE 74nzcxxjv6fq backend replicated 3/3 redis:3.0.6 ``` -#### Name +#### name The `name` filter matches on all or part of a service's name. @@ -103,7 +109,42 @@ ID NAME MODE REPLICAS IMAGE 0bcjwfh8ychr redis replicated 1/1 redis:3.0.6 ``` +<<<<<<< HEAD ## Related information +======= +### Formatting + +The formatting options (`--format`) pretty-prints services output +using a Go template. + +Valid placeholders for the Go template are listed below: + +Placeholder | Description +------------|------------------------------------------------------------------------------------------ +`.ID` | Service ID +`.Name` | Service name +`.Mode` | Service mode (replicated, global) +`.Replicas` | Service replicas +`.Image` | Service image + +When using the `--format` option, the `service ls` command will either +output the data exactly as the template declares or, when using the +`table` directive, includes column headers as well. + +The following example uses a template without headers and outputs the +`ID`, `Mode`, and `Replicas` entries separated by a colon for all services: + +```bash +{% raw %} +$ docker service ls --format "{{.ID}}: {{.Mode}} {{.Replicas}}" + +0zmvwuiu3vue: replicated 10/10 +fm6uf97exkul: global 5/5 +{% endraw %} +``` + +## Related commands +>>>>>>> 40dbbd3... Merge pull request #30804 from mstanleyjones/cli_fixups * [service create](service_create.md) * [service inspect](service_inspect.md) diff --git a/docs/reference/commandline/service_ps.md b/docs/reference/commandline/service_ps.md index 61abb15f67..4b0118f2e5 100644 --- a/docs/reference/commandline/service_ps.md +++ b/docs/reference/commandline/service_ps.md @@ -29,12 +29,14 @@ Options: -q, --quiet Only display task IDs ``` -Lists the tasks that are running as part of the specified service. This command +## Description + +Lists the tasks that are running as part of the specified services. This command has to be run targeting a manager node. ## Examples -### Listing the tasks that are part of a service +### List the tasks that are part of a service The following command shows all the tasks that are part of the `redis` service: @@ -93,7 +95,7 @@ bk658fpbex0d57cqcwoe3jthu redis.2 redis:3.0.6@sha256:6a692a76c2081888b589 nvjljf7rmor4htv7l8rwcx7i7 \_ redis.2 redis:3.0.6@sha256:6a692a76c2081888b589e26e6ec835743119fe453d67ecf03df7de5b73d69842 worker2 Shutdown Rejected 5 minutes ago "No such image: redis@sha256:6a692a76c2081888b589e26e6ec835743119fe453d67ecf03df7de5b73d69842" ``` -## Filtering +### Filtering The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`). @@ -108,7 +110,7 @@ The currently supported filters are: * [desired-state](#desired-state) -#### ID +#### id The `id` filter matches on all or a prefix of a task's ID. @@ -120,7 +122,7 @@ ID NAME IMAGE NODE DESIRED STATE CURRENT STATE 8eaxrb2fqpbn redis.10 redis:3.0.6 manager1 Running Running 8 seconds ``` -#### Name +#### name The `name` filter matches on task names. @@ -131,7 +133,7 @@ qihejybwf1x5 redis.1 redis:3.0.6 manager1 Running Running 8 seconds ``` -#### Node +#### node The `node` filter matches on a node name or a node ID. @@ -150,7 +152,7 @@ ID NAME IMAGE NODE DESIRED STATE CURRENT STATE The `desired-state` filter can take the values `running`, `shutdown`, and `accepted`. -## Related information +## Related commands * [service create](service_create.md) * [service inspect](service_inspect.md) diff --git a/docs/reference/commandline/service_rm.md b/docs/reference/commandline/service_rm.md index d0ba90b26d..448f2c3b24 100644 --- a/docs/reference/commandline/service_rm.md +++ b/docs/reference/commandline/service_rm.md @@ -27,24 +27,29 @@ Options: --help Print usage ``` +## Description + Removes the specified services from the swarm. This command has to be run targeting a manager node. -For example, to remove the redis service: +## Examples + +Remove the `redis` service: ```bash $ docker service rm redis + redis + $ docker service ls + ID NAME MODE REPLICAS IMAGE ``` > **Warning**: Unlike `docker rm`, this command does not ask for confirmation > before removing a running service. - - -## Related information +## Related commands * [service create](service_create.md) * [service inspect](service_inspect.md) diff --git a/docs/reference/commandline/service_scale.md b/docs/reference/commandline/service_scale.md index 64075ed092..a3aef5fd34 100644 --- a/docs/reference/commandline/service_scale.md +++ b/docs/reference/commandline/service_scale.md @@ -24,9 +24,7 @@ Options: --help Print usage ``` -## Examples - -### Scale a service +## Description The scale command enables you to scale one or more replicated services either up or down to the desired number of replicas. This command cannot be applied on @@ -34,19 +32,27 @@ services which are global mode. The command will return immediately, but the actual scaling of the service may take some time. To stop all replicas of a service while keeping the service active in the swarm you can set the scale to 0. -For example, the following command scales the "frontend" service to 50 tasks. +## Examples + +### Scale a single service + +The following command scales the "frontend" service to 50 tasks. ```bash $ docker service scale frontend=50 + frontend scaled to 50 ``` The following command tries to scale a global service to 10 tasks and returns an error. -``` +```bash $ docker service create --mode global --name backend backend:latest + b4g08uwuairexjub6ome6usqh + $ docker service scale backend=10 + backend: scale can only be used with replicated mode ``` @@ -76,16 +82,18 @@ backend and frontend services: ```bash $ docker service scale backend=3 frontend=5 + backend scaled to 3 frontend scaled to 5 $ docker service ls + ID NAME MODE REPLICAS IMAGE 3pr5mlvu3fh9 frontend replicated 5/5 nginx:alpine 74nzcxxjv6fq backend replicated 3/3 redis:3.0.6 ``` -## Related information +## Related commands * [service create](service_create.md) * [service inspect](service_inspect.md) diff --git a/docs/reference/commandline/service_update.md b/docs/reference/commandline/service_update.md index 301a0eabe8..a98923eb63 100644 --- a/docs/reference/commandline/service_update.md +++ b/docs/reference/commandline/service_update.md @@ -80,6 +80,8 @@ Options: -w, --workdir string Working directory inside the container ``` +## Description + Updates a service as described by the specified parameters. This command has to be run targeting a manager node. The parameters are the same as [`docker service create`](service_create.md). Please look at the description there for further information. @@ -111,7 +113,7 @@ that only one task is replaced at a time (this is the default behavior). The `--update-delay 30s` setting introduces a 30 second delay between tasks, so that the rolling restart happens gradually. -### Adding and removing mounts +### Add or remove mounts Use the `--mount-add` or `--mount-rm` options add or remove a service's bind-mounts or volumes. @@ -151,7 +153,7 @@ $ docker service update --mount-rm /somewhere myservice myservice ``` -### Adding and removing secrets +### Add or remove secrets Use the `--secret-add` or `--secret-rm` options add or remove a service's secrets. @@ -170,7 +172,7 @@ $ docker service update \ Some flags of `service update` support the use of templating. See [`service create`](./service_create.md#templating) for the reference. -## Related information +## Related commands * [service create](service_create.md) * [service inspect](service_inspect.md) diff --git a/docs/reference/commandline/stack_deploy.md b/docs/reference/commandline/stack_deploy.md index 037feaebd7..39456b7ffa 100644 --- a/docs/reference/commandline/stack_deploy.md +++ b/docs/reference/commandline/stack_deploy.md @@ -30,15 +30,20 @@ Options: --with-registry-auth Send registry authentication details to Swarm agents ``` +## Description + Create and update a stack from a `compose` or a `dab` file on the swarm. This command has to be run targeting a manager node. -## Compose file +## Examples + +### Compose file The `deploy` command supports compose file version `3.0` and above." ```bash $ docker stack deploy --compose-file docker-compose.yml vossibility + Ignoring unsupported options: links Creating network vossibility_vossibility @@ -53,8 +58,9 @@ Creating service vossibility_lookupd You can verify that the services were correctly created -``` +```bash $ docker service ls + ID NAME MODE REPLICAS IMAGE 29bv0vnlm903 vossibility_lookupd replicated 1/1 nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662 4awt47624qwh vossibility_nsqd replicated 1/1 nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662 @@ -64,10 +70,11 @@ ID NAME MODE REPLICAS IMAGE axqh55ipl40h vossibility_vossibility-collector replicated 1/1 icecrime/vossibility-collector@sha256:f03f2977203ba6253988c18d04061c5ec7aab46bca9dfd89a9a1fa4500989fba ``` -## DAB file +### DAB file ```bash $ docker stack deploy --bundle-file vossibility-stack.dab vossibility + Loading bundle from vossibility-stack.dab Creating service vossibility_elasticsearch Creating service vossibility_kibana @@ -81,6 +88,7 @@ You can verify that the services were correctly created: ```bash $ docker service ls + ID NAME MODE REPLICAS IMAGE 29bv0vnlm903 vossibility_lookupd replicated 1/1 nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662 4awt47624qwh vossibility_nsqd replicated 1/1 nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662 @@ -90,7 +98,7 @@ ID NAME MODE REPLICAS IMAGE axqh55ipl40h vossibility_vossibility-collector replicated 1/1 icecrime/vossibility-collector@sha256:f03f2977203ba6253988c18d04061c5ec7aab46bca9dfd89a9a1fa4500989fba ``` -## Related information +## Related commands * [stack ls](stack_ls.md) * [stack ps](stack_ps.md) diff --git a/docs/reference/commandline/stack_ls.md b/docs/reference/commandline/stack_ls.md index 05c7215492..58cbde004f 100644 --- a/docs/reference/commandline/stack_ls.md +++ b/docs/reference/commandline/stack_ls.md @@ -27,9 +27,13 @@ Options: --help Print usage ``` +## Descriptino + Lists the stacks. -For example, the following command shows all stacks and some additional information: +## Examples + +The following command shows all stacks and some additional information: ```bash $ docker stack ls @@ -39,7 +43,7 @@ vossibility-stack 6 myapp 2 ``` -## Related information +## Related commands * [stack deploy](stack_deploy.md) * [stack ps](stack_ps.md) diff --git a/docs/reference/commandline/stack_ps.md b/docs/reference/commandline/stack_ps.md index 101e9feb11..9f221d8da6 100644 --- a/docs/reference/commandline/stack_ps.md +++ b/docs/reference/commandline/stack_ps.md @@ -27,10 +27,18 @@ Options: --no-trunc Do not truncate output ``` +## Description + Lists the tasks that are running as part of the specified stack. This command has to be run targeting a manager node. -## Filtering +## Examples + +```bash +$ docker stack ps +``` + +### Filtering The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`). @@ -43,7 +51,7 @@ The currently supported filters are: * name * desired-state -## Related information +## Related commands * [stack deploy](stack_deploy.md) * [stack ls](stack_ls.md) diff --git a/docs/reference/commandline/stack_rm.md b/docs/reference/commandline/stack_rm.md index fd639978ec..d9d50433a7 100644 --- a/docs/reference/commandline/stack_rm.md +++ b/docs/reference/commandline/stack_rm.md @@ -27,10 +27,12 @@ Options: --help Print usage ``` +## Description + Remove the stack from the swarm. This command has to be run targeting a manager node. -## Related information +## Related commands * [stack deploy](stack_deploy.md) * [stack ls](stack_ls.md) diff --git a/docs/reference/commandline/stack_services.md b/docs/reference/commandline/stack_services.md index 62779b4aa1..74af825840 100644 --- a/docs/reference/commandline/stack_services.md +++ b/docs/reference/commandline/stack_services.md @@ -27,10 +27,14 @@ Options: -q, --quiet Only display IDs ``` +### Description + Lists the services that are running as part of the specified stack. This command has to be run targeting a manager node. -For example, the following command shows all services in the `myapp` stack: +### Examples + +The following command shows all services in the `myapp` stack: ```bash $ docker stack services myapp @@ -40,7 +44,7 @@ ID NAME REPLICAS IMAGE dn7m7nhhfb9y myapp_db 1/1 mysql@sha256:a9a5b559f8821fe73d58c3606c812d1c044868d42c63817fa5125fd9d8b7b539 ``` -## Filtering +### Filtering The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`). @@ -62,7 +66,39 @@ The currently supported filters are: * name (`--filter name=myapp_web`) * label (`--filter label=key=value`) -## Related information +### Formatting + +The formatting options (`--format`) pretty-prints services output +using a Go template. + +Valid placeholders for the Go template are listed below: + +Placeholder | Description +------------|------------------------------------------------------------------------------------------ +`.ID` | Service ID +`.Name` | Service name +`.Mode` | Service mode (replicated, global) +`.Replicas` | Service replicas +`.Image` | Service image + +When using the `--format` option, the `stack services` command will either +output the data exactly as the template declares or, when using the +`table` directive, includes column headers as well. + +The following example uses a template without headers and outputs the +`ID`, `Mode`, and `Replicas` entries separated by a colon for all services: + +```bash +{% raw %} +$ docker stack services --format "{{.ID}}: {{.Mode}} {{.Replicas}}" + +0zmvwuiu3vue: replicated 10/10 +fm6uf97exkul: global 5/5 +{% endraw %} +``` + + +## Related commands * [stack deploy](stack_deploy.md) * [stack ls](stack_ls.md) diff --git a/docs/reference/commandline/start.md b/docs/reference/commandline/start.md index 980bce9585..aa672289ec 100644 --- a/docs/reference/commandline/start.md +++ b/docs/reference/commandline/start.md @@ -26,3 +26,9 @@ Options: --help Print usage -i, --interactive Attach container's STDIN ``` + +## Examples + +```bash +$ docker start my_container +``` diff --git a/docs/reference/commandline/stats.md b/docs/reference/commandline/stats.md index f5d0d54f35..0a2428983d 100644 --- a/docs/reference/commandline/stats.md +++ b/docs/reference/commandline/stats.md @@ -27,6 +27,8 @@ Options: --no-stream Disable streaming stats and only pull the first result ``` +## Description + The `docker stats` command returns a live data stream for running containers. To limit data to one or more specific containers, specify a list of container names or ids separated by a space. You can specify a stopped container but stopped containers do not return any data. If you want more detailed information about a container's resource usage, use the `/containers/(id)/stats` API endpoint. @@ -35,41 +37,49 @@ If you want more detailed information about a container's resource usage, use th Running `docker stats` on all running containers against a Linux daemon. - $ docker stats - CONTAINER CPU % MEM USAGE / LIMIT MEM % NET I/O BLOCK I/O - 1285939c1fd3 0.07% 796 KiB / 64 MiB 1.21% 788 B / 648 B 3.568 MB / 512 KB - 9c76f7834ae2 0.07% 2.746 MiB / 64 MiB 4.29% 1.266 KB / 648 B 12.4 MB / 0 B - d1ea048f04e4 0.03% 4.583 MiB / 64 MiB 6.30% 2.854 KB / 648 B 27.7 MB / 0 B +```bash +$ docker stats +CONTAINER CPU % MEM USAGE / LIMIT MEM % NET I/O BLOCK I/O +1285939c1fd3 0.07% 796 KiB / 64 MiB 1.21% 788 B / 648 B 3.568 MB / 512 KB +9c76f7834ae2 0.07% 2.746 MiB / 64 MiB 4.29% 1.266 KB / 648 B 12.4 MB / 0 B +d1ea048f04e4 0.03% 4.583 MiB / 64 MiB 6.30% 2.854 KB / 648 B 27.7 MB / 0 B +``` Running `docker stats` on multiple containers by name and id against a Linux daemon. - $ docker stats fervent_panini 5acfcb1b4fd1 - CONTAINER CPU % MEM USAGE/LIMIT MEM % NET I/O - 5acfcb1b4fd1 0.00% 115.2 MiB/1.045 GiB 11.03% 1.422 kB/648 B - fervent_panini 0.02% 11.08 MiB/1.045 GiB 1.06% 648 B/648 B +```bash +$ docker stats fervent_panini 5acfcb1b4fd1 +CONTAINER CPU % MEM USAGE/LIMIT MEM % NET I/O +5acfcb1b4fd1 0.00% 115.2 MiB/1.045 GiB 11.03% 1.422 kB/648 B +fervent_panini 0.02% 11.08 MiB/1.045 GiB 1.06% 648 B/648 B +``` Running `docker stats` on all running containers against a Windows daemon. - PS E:\> docker stats - CONTAINER CPU % PRIV WORKING SET NET I/O BLOCK I/O - 09d3bb5b1604 6.61% 38.21 MiB 17.1 kB / 7.73 kB 10.7 MB / 3.57 MB - 9db7aa4d986d 9.19% 38.26 MiB 15.2 kB / 7.65 kB 10.6 MB / 3.3 MB - 3f214c61ad1d 0.00% 28.64 MiB 64 kB / 6.84 kB 4.42 MB / 6.93 MB +```powershell +PS E:\> docker stats +CONTAINER CPU % PRIV WORKING SET NET I/O BLOCK I/O +09d3bb5b1604 6.61% 38.21 MiB 17.1 kB / 7.73 kB 10.7 MB / 3.57 MB +9db7aa4d986d 9.19% 38.26 MiB 15.2 kB / 7.65 kB 10.6 MB / 3.3 MB +3f214c61ad1d 0.00% 28.64 MiB 64 kB / 6.84 kB 4.42 MB / 6.93 MB +``` Running `docker stats` on multiple containers by name and id against a Windows daemon. - PS E:\> docker ps -a - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 3f214c61ad1d nanoserver "cmd" 2 minutes ago Up 2 minutes big_minsky - 9db7aa4d986d windowsservercore "cmd" 2 minutes ago Up 2 minutes mad_wilson - 09d3bb5b1604 windowsservercore "cmd" 2 minutes ago Up 2 minutes affectionate_easley +```powershell +PS E:\> docker ps -a +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +3f214c61ad1d nanoserver "cmd" 2 minutes ago Up 2 minutes big_minsky +9db7aa4d986d windowsservercore "cmd" 2 minutes ago Up 2 minutes mad_wilson +09d3bb5b1604 windowsservercore "cmd" 2 minutes ago Up 2 minutes affectionate_easley - PS E:\> docker stats 3f214c61ad1d mad_wilson - CONTAINER CPU % PRIV WORKING SET NET I/O BLOCK I/O - 3f214c61ad1d 0.00% 46.25 MiB 76.3 kB / 7.92 kB 10.3 MB / 14.7 MB - mad_wilson 9.59% 40.09 MiB 27.6 kB / 8.81 kB 17 MB / 20.1 MB +PS E:\> docker stats 3f214c61ad1d mad_wilson +CONTAINER CPU % PRIV WORKING SET NET I/O BLOCK I/O +3f214c61ad1d 0.00% 46.25 MiB 76.3 kB / 7.92 kB 10.3 MB / 14.7 MB +mad_wilson 9.59% 40.09 MiB 27.6 kB / 8.81 kB 17 MB / 20.1 MB +``` -## Formatting +### Formatting The formatting option (`--format`) pretty prints container output using a Go template. @@ -97,21 +107,25 @@ The following example uses a template without headers and outputs the `Container` and `CPUPerc` entries separated by a colon for all images: ```bash +{% raw %} $ docker stats --format "{{.Container}}: {{.CPUPerc}}" 09d3bb5b1604: 6.61% 9db7aa4d986d: 9.19% 3f214c61ad1d: 0.00% +{% endraw %} ``` To list all containers statistics with their name, CPU percentage and memory usage in a table format you can use: ```bash +{% raw %} $ docker stats --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}" CONTAINER CPU % PRIV WORKING SET 1285939c1fd3 0.07% 796 KiB / 64 MiB 9c76f7834ae2 0.07% 2.746 MiB / 64 MiB d1ea048f04e4 0.03% 4.583 MiB / 64 MiB +{% endraw %} ``` diff --git a/docs/reference/commandline/stop.md b/docs/reference/commandline/stop.md index 3090db98ae..dc00b38af5 100644 --- a/docs/reference/commandline/stop.md +++ b/docs/reference/commandline/stop.md @@ -25,5 +25,13 @@ Options: -t, --time int Seconds to wait for stop before killing it (default 10) ``` +## Description + The main process inside the container will receive `SIGTERM`, and after a grace period, `SIGKILL`. + +## Examples + +```bash +$ docker stop my_container +``` diff --git a/docs/reference/commandline/swarm_init.md b/docs/reference/commandline/swarm_init.md index 44afc27476..fa2c1c9364 100644 --- a/docs/reference/commandline/swarm_init.md +++ b/docs/reference/commandline/swarm_init.md @@ -34,9 +34,12 @@ Options: --task-history-limit int Task history retention limit (default 5) ``` +## Description + Initialize a swarm. The docker engine targeted by this command becomes a manager in the newly created single-node swarm. +## Examples ```bash $ docker swarm init --advertise-addr 192.168.99.121 @@ -133,7 +136,17 @@ Snapshots compact the Raft log and allow for more efficient transfer of the state to new managers. However, there is a performance cost to taking snapshots frequently. -## Related information +### `--availability` + +This flag specifies the availability of the node at the time the node joins a master. +Possible availability values are `active`, `pause`, or `drain`. + +This flag is useful in certain situations. For example, a cluster may want to have +dedicated manager nodes that are not served as worker nodes. This could be achieved +by passing `--availability=drain` to `docker swarm init`. + + +## Related commands * [swarm join](swarm_join.md) * [swarm leave](swarm_leave.md) diff --git a/docs/reference/commandline/swarm_join.md b/docs/reference/commandline/swarm_join.md index 0cde0d7bcd..d0b6685c45 100644 --- a/docs/reference/commandline/swarm_join.md +++ b/docs/reference/commandline/swarm_join.md @@ -27,10 +27,14 @@ Options: --token string Token for entry into the swarm ``` +## Description + Join a node to a swarm. The node joins as a manager node or worker node based upon the token you pass with the `--token` flag. If you pass a manager token, the node joins as a manager. If you pass a worker token, the node joins as a worker. +## Examples + ### Join a node to swarm as a manager The example below demonstrates joining a manager node using a manager token. @@ -95,7 +99,7 @@ This flag is generally not necessary when joining an existing swarm. Secret value required for nodes to join the swarm -## Related information +## Related commands * [swarm init](swarm_init.md) * [swarm leave](swarm_leave.md) diff --git a/docs/reference/commandline/swarm_join_token.md b/docs/reference/commandline/swarm_join_token.md index d731f028ba..60f5622072 100644 --- a/docs/reference/commandline/swarm_join_token.md +++ b/docs/reference/commandline/swarm_join_token.md @@ -26,12 +26,16 @@ Options: --rotate Rotate join token ``` +## Description + Join tokens are secrets that allow a node to join the swarm. There are two different join tokens available, one for the worker role and one for the manager role. You pass the token using the `--token` flag when you run [swarm join](swarm_join.md). Nodes use the join token only when they join the swarm. +## Examples + You can view or rotate the join tokens using `swarm join-token`. As a convenience, you can pass `worker` or `manager` as an argument to @@ -100,6 +104,6 @@ because the join token is only used for authorizing new nodes joining the swarm. Only print the token. Do not print a complete command for joining. -## Related information +## Related commands * [swarm join](swarm_join.md) diff --git a/docs/reference/commandline/swarm_leave.md b/docs/reference/commandline/swarm_leave.md index dbc88ca1b5..e534579345 100644 --- a/docs/reference/commandline/swarm_leave.md +++ b/docs/reference/commandline/swarm_leave.md @@ -25,6 +25,8 @@ Options: --help Print usage ``` +## Description + When you run this command on a worker, that worker leaves the swarm. You can use the `--force` option on a manager to remove it from the swarm. @@ -34,7 +36,10 @@ from a swarm is to demote it to a worker and then direct it to leave the quorum without using `--force`. Only use `--force` in situations where the swarm will no longer be used after the manager leaves, such as in a single-node swarm. +## Examples + Consider the following swarm, as seen from the manager: + ```bash $ docker node ls ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS @@ -44,13 +49,18 @@ dvfxp4zseq4s0rih1selh0d20 * manager1 Ready Active Leader ``` To remove `worker2`, issue the following command from `worker2` itself: + ```bash $ docker swarm leave Node left the default swarm. ``` -To remove an inactive node, use the [`node rm`](node_rm.md) command instead. -## Related information +The node will still appear in the node list, and marked as `down`. It no longer +affects swarm operation, but a long list of `down` nodes can clutter the node +list. To remove an inactive node from the list, use the [`node rm`](node_rm.md) +command. + +## Related commands * [node rm](node_rm.md) * [swarm init](swarm_init.md) diff --git a/docs/reference/commandline/swarm_unlock.md b/docs/reference/commandline/swarm_unlock.md index 164b7d35a4..bd7ed14ab6 100644 --- a/docs/reference/commandline/swarm_unlock.md +++ b/docs/reference/commandline/swarm_unlock.md @@ -24,18 +24,21 @@ Options: --help Print usage ``` +## Description + Unlocks a locked manager using a user-supplied unlock key. This command must be used to reactivate a manager after its Docker daemon restarts if the autolock setting is turned on. The unlock key is printed at the time when autolock is enabled, and is also available from the `docker swarm unlock-key` command. +## Examples ```bash $ docker swarm unlock Please enter unlock key: ``` -## Related information +## Related commands * [swarm init](swarm_init.md) * [swarm update](swarm_update.md) diff --git a/docs/reference/commandline/swarm_unlock_key.md b/docs/reference/commandline/swarm_unlock_key.md index a2597fe9ab..6dc3aae285 100644 --- a/docs/reference/commandline/swarm_unlock_key.md +++ b/docs/reference/commandline/swarm_unlock_key.md @@ -26,6 +26,8 @@ Options: --rotate Rotate unlock key ``` +## Description + An unlock key is a secret key needed to unlock a manager after its Docker daemon restarts. These keys are only used when the autolock feature is enabled for the swarm. @@ -33,9 +35,11 @@ swarm. You can view or rotate the unlock key using `swarm unlock-key`. To view the key, run the `docker swarm unlock-key` command without any arguments: +## Examples ```bash $ docker swarm unlock-key + To unlock a swarm manager after it restarts, run the `docker swarm unlock` command and provide the following key: @@ -77,7 +81,7 @@ key. The old unlock key will no longer be accepted. Only print the unlock key, without instructions. -## Related information +## Related commands * [swarm unlock](swarm_unlock.md) * [swarm init](swarm_init.md) diff --git a/docs/reference/commandline/swarm_update.md b/docs/reference/commandline/swarm_update.md index 0af63fe3e0..aed72d001e 100644 --- a/docs/reference/commandline/swarm_update.md +++ b/docs/reference/commandline/swarm_update.md @@ -31,14 +31,17 @@ Options: --task-history-limit int Task history retention limit (default 5) ``` +## Description + Updates a swarm with new parameter values. This command must target a manager node. +## Examples ```bash $ docker swarm update --cert-expiry 720h ``` -## Related information +## Related commands * [swarm init](swarm_init.md) * [swarm join](swarm_join.md) diff --git a/docs/reference/commandline/system_df.md b/docs/reference/commandline/system_df.md index c6e8bbdc68..6758bdeb72 100644 --- a/docs/reference/commandline/system_df.md +++ b/docs/reference/commandline/system_df.md @@ -25,12 +25,18 @@ Options: -v, --verbose Show detailed information on space usage ``` +## Description + The `docker system df` command displays information regarding the amount of disk space used by the docker daemon. +## Examples + By default the command will just show a summary of the data used: + ```bash $ docker system df + TYPE TOTAL ACTIVE SIZE RECLAIMABLE Images 5 2 16.43 MB 11.63 MB (70%) Containers 2 0 212 B 212 B (100%) @@ -38,8 +44,10 @@ Local Volumes 2 1 36 B ``` A more detailed view can be requested using the `-v, --verbose` flag: + ```bash $ docker system df -v + Images space usage: REPOSITORY TAG IMAGE ID CREATED SIZE SHARED SIZE UNIQUE SIZE CONTAINERS @@ -66,9 +74,10 @@ my-named-vol 0 * `UNIQUE SIZE` is the amount of space that is only used by a given image * `SIZE` is the virtual size of the image, it is the sum of `SHARED SIZE` and `UNIQUE SIZE` -Note that network information is not shown because it doesn't consume the disk space. +> **Note**: Network information is not shown because it doesn't consume the disk +> space. -## Related Information +## Related commands * [system prune](system_prune.md) * [container prune](container_prune.md) * [volume prune](volume_prune.md) diff --git a/docs/reference/commandline/system_prune.md b/docs/reference/commandline/system_prune.md index 46f8c4364a..7a304d9414 100644 --- a/docs/reference/commandline/system_prune.md +++ b/docs/reference/commandline/system_prune.md @@ -26,12 +26,15 @@ Options: --help Print usage ``` +## Description + Remove all unused containers, volumes, networks and images (both dangling and unreferenced). -Example output: +## Examples ```bash $ docker system prune -a + WARNING! This will remove: - all stopped containers - all volumes not used by at least one container @@ -64,7 +67,28 @@ deleted: sha256:3a88a5c81eb5c283e72db2dbc6d65cbfd8e80b6c89bb6e714cfaaa0eed99c548 Total reclaimed space: 13.5 MB ``` -## Related information +### Filtering + +The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more +than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) + +The currently supported filters are: + +* until (``) - only remove containers, images, and networks created before given timestamp + +The `until` filter can be Unix timestamps, date formatted +timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed +relative to the daemon machine’s time. Supported formats for date +formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, +`2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local +timezone on the daemon will be used if you do not provide either a `Z` or a +`+-00:00` timezone offset at the end of the timestamp. When providing Unix +timestamps enter seconds[.nanoseconds], where seconds is the number of seconds +that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap +seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a +fraction of a second no more than nine digits long. + +## Related commands * [volume create](volume_create.md) * [volume ls](volume_ls.md) diff --git a/docs/reference/commandline/tag.md b/docs/reference/commandline/tag.md index ebb4c23c10..5f9defd8a9 100644 --- a/docs/reference/commandline/tag.md +++ b/docs/reference/commandline/tag.md @@ -24,6 +24,8 @@ Options: --help Print usage ``` +## Description + An image name is made up of slash-separated name components, optionally prefixed by a registry hostname. The hostname must comply with standard DNS rules, but may not contain underscores. If a hostname is present, it may optionally be @@ -40,35 +42,43 @@ period or a dash and may contain a maximum of 128 characters. You can group your images together using names and tags, and then upload them to [*Share Images via Repositories*](https://docs.docker.com/engine/tutorials/dockerrepos/#/contributing-to-docker-hub). -# Examples +## Examples -## Tagging an image referenced by ID +### Tag an image referenced by ID To tag a local image with ID "0e5574283393" into the "fedora" repository with "version1.0": - docker tag 0e5574283393 fedora/httpd:version1.0 +```bash +$ docker tag 0e5574283393 fedora/httpd:version1.0 +``` -## Tagging an image referenced by Name +### Tag an image referenced by Name To tag a local image with name "httpd" into the "fedora" repository with "version1.0": - docker tag httpd fedora/httpd:version1.0 +```bash +$ docker tag httpd fedora/httpd:version1.0 +``` Note that since the tag name is not specified, the alias is created for an existing local version `httpd:latest`. -## Tagging an image referenced by Name and Tag +### Tag an image referenced by Name and Tag To tag a local image with name "httpd" and tag "test" into the "fedora" repository with "version1.0.test": - docker tag httpd:test fedora/httpd:version1.0.test +```bash +$ docker tag httpd:test fedora/httpd:version1.0.test +``` -## Tagging an image for a private repository +### Tag an image for a private repository To push an image to a private registry and not the central Docker registry you must tag it with the registry hostname and port (if needed). - docker tag 0e5574283393 myregistryhost:5000/fedora/httpd:version1.0 +```bash +$ docker tag 0e5574283393 myregistryhost:5000/fedora/httpd:version1.0 +``` diff --git a/docs/reference/commandline/unpause.md b/docs/reference/commandline/unpause.md index aa2326fefc..8915a43b40 100644 --- a/docs/reference/commandline/unpause.md +++ b/docs/reference/commandline/unpause.md @@ -24,6 +24,8 @@ Options: --help Print usage ``` +## Description + The `docker unpause` command un-suspends all processes in the specified containers. On Linux, it does this using the cgroups freezer. @@ -31,6 +33,12 @@ See the [cgroups freezer documentation](https://www.kernel.org/doc/Documentation/cgroup-v1/freezer-subsystem.txt) for further details. -## Related information +## Examples + +```bash +$ docker unpause my_container +``` + +## Related commands * [pause](pause.md) diff --git a/docs/reference/commandline/update.md b/docs/reference/commandline/update.md index a13900440f..f41cf39db8 100644 --- a/docs/reference/commandline/update.md +++ b/docs/reference/commandline/update.md @@ -37,6 +37,8 @@ Options: --restart string Restart policy to apply when a container exits ``` +## Description + The `docker update` command dynamically updates container configuration. You can use this command to prevent containers from consuming too many resources from their Docker host. With a single command, you can place diff --git a/docs/reference/commandline/version.md b/docs/reference/commandline/version.md index cb1bcee5b3..c2693886b9 100644 --- a/docs/reference/commandline/version.md +++ b/docs/reference/commandline/version.md @@ -25,6 +25,8 @@ Options: --help Print usage ``` +## Description + By default, this will render all version information in an easy to read layout. If a format is specified, the given template will be executed instead. @@ -33,35 +35,44 @@ describes all the details of the format. ## Examples -**Default output:** +### Default output - $ docker version - Client: - Version: 1.8.0 - API version: 1.20 - Go version: go1.4.2 - Git commit: f5bae0a - Built: Tue Jun 23 17:56:00 UTC 2015 - OS/Arch: linux/amd64 +```bash +$ docker version - Server: - Version: 1.8.0 - API version: 1.20 - Go version: go1.4.2 - Git commit: f5bae0a - Built: Tue Jun 23 17:56:00 UTC 2015 - OS/Arch: linux/amd64 +Client: +Version: 1.8.0 +API version: 1.20 +Go version: go1.4.2 +Git commit: f5bae0a +Built: Tue Jun 23 17:56:00 UTC 2015 +OS/Arch: linux/amd64 -**Get server version:** +Server: +Version: 1.8.0 +API version: 1.20 +Go version: go1.4.2 +Git commit: f5bae0a +Built: Tue Jun 23 17:56:00 UTC 2015 +OS/Arch: linux/amd64 +``` - {% raw %} - $ docker version --format '{{.Server.Version}}' - 1.8.0 - {% endraw %} +### Get the server version -**Dump raw data:** +```bash +{% raw %} +$ docker version --format '{{.Server.Version}}' - {% raw %} - $ docker version --format '{{json .}}' - {"Client":{"Version":"1.8.0","ApiVersion":"1.20","GitCommit":"f5bae0a","GoVersion":"go1.4.2","Os":"linux","Arch":"amd64","BuildTime":"Tue Jun 23 17:56:00 UTC 2015"},"ServerOK":true,"Server":{"Version":"1.8.0","ApiVersion":"1.20","GitCommit":"f5bae0a","GoVersion":"go1.4.2","Os":"linux","Arch":"amd64","KernelVersion":"3.13.2-gentoo","BuildTime":"Tue Jun 23 17:56:00 UTC 2015"}} - {% endraw %} +1.8.0 +{% endraw %} +``` + +### Dump raw JSON data + +```bash +{% raw %} +$ docker version --format '{{json .}}' + +{"Client":{"Version":"1.8.0","ApiVersion":"1.20","GitCommit":"f5bae0a","GoVersion":"go1.4.2","Os":"linux","Arch":"amd64","BuildTime":"Tue Jun 23 17:56:00 UTC 2015"},"ServerOK":true,"Server":{"Version":"1.8.0","ApiVersion":"1.20","GitCommit":"f5bae0a","GoVersion":"go1.4.2","Os":"linux","Arch":"amd64","KernelVersion":"3.13.2-gentoo","BuildTime":"Tue Jun 23 17:56:00 UTC 2015"}} +{% endraw %} +``` diff --git a/docs/reference/commandline/volume_create.md b/docs/reference/commandline/volume_create.md index 9b188a9500..b1eed37b5c 100644 --- a/docs/reference/commandline/volume_create.md +++ b/docs/reference/commandline/volume_create.md @@ -27,33 +27,51 @@ Options: -o, --opt value Set driver specific options (default map[]) ``` -Creates a new volume that containers can consume and store data in. If a name is not specified, Docker generates a random name. You create a volume and then configure the container to use it, for example: +## Description + +Creates a new volume that containers can consume and store data in. If a name is +not specified, Docker generates a random name. + +## Examples + +Create a volume and then configure the container to use it: ```bash $ docker volume create hello + hello $ docker run -d -v hello:/world busybox ls /world ``` -The mount is created inside the container's `/world` directory. Docker does not support relative paths for mount points inside the container. +The mount is created inside the container's `/world` directory. Docker does not +support relative paths for mount points inside the container. -Multiple containers can use the same volume in the same time period. This is useful if two containers need access to shared data. For example, if one container writes and the other reads the data. +Multiple containers can use the same volume in the same time period. This is +useful if two containers need access to shared data. For example, if one +container writes and the other reads the data. -Volume names must be unique among drivers. This means you cannot use the same volume name with two different drivers. If you attempt this `docker` returns an error: +Volume names must be unique among drivers. This means you cannot use the same +volume name with two different drivers. If you attempt this `docker` returns an +error: -``` +```none A volume named "hello" already exists with the "some-other" driver. Choose a different volume name. ``` -If you specify a volume name already in use on the current driver, Docker assumes you want to re-use the existing volume and does not return an error. +If you specify a volume name already in use on the current driver, Docker +assumes you want to re-use the existing volume and does not return an error. -## Driver specific options +### Driver-specific options -Some volume drivers may take options to customize the volume creation. Use the `-o` or `--opt` flags to pass driver options: +Some volume drivers may take options to customize the volume creation. Use the +`-o` or `--opt` flags to pass driver options: ```bash -$ docker volume create --driver fake --opt tardis=blue --opt timey=wimey +$ docker volume create --driver fake \ + --opt tardis=blue \ + --opt timey=wimey \ + foo ``` These options are passed directly to the volume driver. Options for @@ -61,28 +79,44 @@ different volume drivers may do different things (or nothing at all). The built-in `local` driver on Windows does not support any options. -The built-in `local` driver on Linux accepts options similar to the linux `mount` command. You can provide multiple options by passing the `--opt` flag multiple times. Some `mount` options (such as the `o` option) can take a comma-separated list of options. Complete list of available mount options can be found [here](http://man7.org/linux/man-pages/man8/mount.8.html). +The built-in `local` driver on Linux accepts options similar to the linux +`mount` command. You can provide multiple options by passing the `--opt` flag +multiple times. Some `mount` options (such as the `o` option) can take a +comma-separated list of options. Complete list of available mount options can be +found [here](http://man7.org/linux/man-pages/man8/mount.8.html). -For example, the following creates a `tmpfs` volume called `foo` with a size of 100 megabyte and `uid` of 1000. +For example, the following creates a `tmpfs` volume called `foo` with a size of +100 megabyte and `uid` of 1000. ```bash -$ docker volume create --driver local --opt type=tmpfs --opt device=tmpfs --opt o=size=100m,uid=1000 foo +$ docker volume create --driver local \ + --opt type=tmpfs \ + --opt device=tmpfs \ + --opt o=size=100m,uid=1000 \ + foo ``` Another example that uses `btrfs`: ```bash -$ docker volume create --driver local --opt type=btrfs --opt device=/dev/sda2 foo +$ docker volume create --driver local \ + --opt type=btrfs \ + --opt device=/dev/sda2 \ + foo ``` -Another example that uses `nfs` to mount the `/path/to/dir` in `rw` mode from `192.168.1.1`: +Another example that uses `nfs` to mount the `/path/to/dir` in `rw` mode from +`192.168.1.1`: ```bash -$ docker volume create --driver local --opt type=nfs --opt o=addr=192.168.1.1,rw --opt device=:/path/to/dir foo +$ docker volume create --driver local \ + --opt type=nfs \ + --opt o=addr=192.168.1.1,rw \ + --opt device=:/path/to/dir \ + foo ``` - -## Related information +## Related commands * [volume inspect](volume_inspect.md) * [volume ls](volume_ls.md) diff --git a/docs/reference/commandline/volume_inspect.md b/docs/reference/commandline/volume_inspect.md index 98e0ee5abf..530c2b1feb 100644 --- a/docs/reference/commandline/volume_inspect.md +++ b/docs/reference/commandline/volume_inspect.md @@ -25,32 +25,36 @@ Options: --help Print usage ``` +## Description + Returns information about a volume. By default, this command renders all results in a JSON array. You can specify an alternate format to execute a given template for each result. Go's [text/template](http://golang.org/pkg/text/template/) package describes all the details of the format. -Example output: +## Examples - $ docker volume create - 85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d - $ docker volume inspect 85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d - [ - { - "Name": "85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d", - "Driver": "local", - "Mountpoint": "/var/lib/docker/volumes/85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d/_data", - "Status": null - } - ] +```bash +$ docker volume create +85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d +$ docker volume inspect 85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d +[ + { + "Name": "85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d", + "Driver": "local", + "Mountpoint": "/var/lib/docker/volumes/85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d/_data", + "Status": null + } +] - {% raw %} - $ docker volume inspect --format '{{ .Mountpoint }}' 85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d - /var/lib/docker/volumes/85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d/_data - {% endraw %} +{% raw %} +$ docker volume inspect --format '{{ .Mountpoint }}' 85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d +/var/lib/docker/volumes/85bffb0677236974f93955d8ecc4df55ef5070117b0e53333cc1b443777be24d/_data +{% endraw %} +``` -## Related information +## Related commands * [volume create](volume_create.md) * [volume ls](volume_ls.md) diff --git a/docs/reference/commandline/volume_ls.md b/docs/reference/commandline/volume_ls.md index 90ecef2abe..9f9f972d03 100644 --- a/docs/reference/commandline/volume_ls.md +++ b/docs/reference/commandline/volume_ls.md @@ -34,22 +34,32 @@ Options: -q, --quiet Only display volume names ``` -List all the volumes Docker knows about. You can filter using the `-f` or `--filter` flag. Refer to the [filtering](#filtering) section for more information about available filter options. +## Description -Example output: +List all the volumes known to Docker. You can filter using the `-f` or +`--filter` flag. Refer to the [filtering](#filtering) section for more +information about available filter options. +## Examples + +### Create a volume ```bash $ docker volume create rosemary + rosemary -$docker volume create tyler + +$ docker volume create tyler + tyler + $ docker volume ls + DRIVER VOLUME NAME local rosemary local tyler ``` -## Filtering +### Filtering The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) @@ -61,7 +71,7 @@ The currently supported filters are: * label (`label=` or `label==`) * name (a volume's name) -### dangling +#### dangling The `dangling` filter matches on all volumes not referenced by any containers @@ -74,7 +84,7 @@ DRIVER VOLUME NAME local rosemary ``` -### driver +#### driver The `driver` filter matches on all or part of a volume's driver name. @@ -88,7 +98,7 @@ local rosemary local tyler ``` -#### Label +#### label The `label` filter matches volumes based on the presence of a `label` alone or a `label` and a value. @@ -97,8 +107,10 @@ First, let's create some volumes to illustrate this; ```bash $ docker volume create the-doctor --label is-timelord=yes + the-doctor $ docker volume create daleks --label is-timelord=no + daleks ``` @@ -113,7 +125,7 @@ local daleks local the-doctor ``` -As can be seen in the above example, both volumes with `is-timelord=yes`, and +As the above example demonstrates, both volumes with `is-timelord=yes`, and `is-timelord=no` are returned. Filtering on both `key` *and* `value` of the label, produces the expected result: @@ -134,17 +146,20 @@ $ docker volume ls --filter label=is-timelord=yes --filter label=is-timelord=no DRIVER VOLUME NAME ``` -### name +#### name The `name` filter matches on all or part of a volume's name. The following filter matches all volumes with a name containing the `rose` string. - $ docker volume ls -f name=rose - DRIVER VOLUME NAME - local rosemary +```bash +$ docker volume ls -f name=rose -## Formatting +DRIVER VOLUME NAME +local rosemary +``` + +### Formatting The formatting options (`--format`) pretty-prints volumes output using a Go template. @@ -168,13 +183,16 @@ The following example uses a template without headers and outputs the `Name` and `Driver` entries separated by a colon for all volumes: ```bash +{% raw %} $ docker volume ls --format "{{.Name}}: {{.Driver}}" + vol1: local vol2: local vol3: local +{% endraw %} ``` -## Related information +## Related commands * [volume create](volume_create.md) * [volume inspect](volume_inspect.md) diff --git a/docs/reference/commandline/volume_prune.md b/docs/reference/commandline/volume_prune.md index d910a49cdc..a9c4b70fc4 100644 --- a/docs/reference/commandline/volume_prune.md +++ b/docs/reference/commandline/volume_prune.md @@ -25,12 +25,15 @@ Options: --help Print usage ``` +## Description + Remove all unused volumes. Unused volumes are those which are not referenced by any containers -Example output: +## Examples ```bash $ docker volume prune + WARNING! This will remove all volumes not used by at least one container. Are you sure you want to continue? [y/N] y Deleted Volumes: @@ -40,7 +43,7 @@ my-named-vol Total reclaimed space: 36 B ``` -## Related information +## Related commands * [volume create](volume_create.md) * [volume ls](volume_ls.md) diff --git a/docs/reference/commandline/volume_rm.md b/docs/reference/commandline/volume_rm.md index 1bf9dba220..a1f2d3b9ff 100644 --- a/docs/reference/commandline/volume_rm.md +++ b/docs/reference/commandline/volume_rm.md @@ -28,12 +28,18 @@ Options: --help Print usage ``` +## Description + Remove one or more volumes. You cannot remove a volume that is in use by a container. - $ docker volume rm hello - hello +## Examples -## Related information +```bash + $ docker volume rm hello + hello +``` + +## Related commands * [volume create](volume_create.md) * [volume inspect](volume_inspect.md) diff --git a/docs/reference/commandline/wait.md b/docs/reference/commandline/wait.md index a07b82b071..ee8f9ab243 100644 --- a/docs/reference/commandline/wait.md +++ b/docs/reference/commandline/wait.md @@ -23,3 +23,36 @@ Block until one or more containers stop, then print their exit codes Options: --help Print usage ``` + +> **Note**: `docker wait` returns `0` when run against a container which had +> already exited before the `docker wait` command was run. + +## Examples + +Start a container in the background. + +```bash +$ docker run -dit --name=my_container ubuntu bash +``` + +Run `docker wait`, which should block until the container exits. + +```bash +$ docker wait my_container +``` + +In another terminal, stop the first container. The `docker wait` command above +returns the exit code. + +```bash +$ docker stop my_container +``` + +This is the same `docker wait` command from above, but it now exits, returning +`0`. + +```bash +$ docker wait my_container + +0 +``` From fdd29d908574be5604ccf5dcd5a2d6b5f70cc6ad Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Sat, 18 Feb 2017 09:53:51 -0800 Subject: [PATCH 33/38] Merge pull request #30898 from allencloud/add-link-query-in-container-rm-api-doc add link query in container rm api doc (cherry picked from commit b89aff1afa1f61993ab2ba18fd62d9375a195f5d) Signed-off-by: Sebastiaan van Stijn --- api/swagger.yaml | 5 +++++ docs/api/v1.18.md | 2 ++ docs/api/v1.19.md | 2 ++ docs/api/v1.20.md | 2 ++ docs/api/v1.21.md | 2 ++ docs/api/v1.22.md | 2 ++ docs/api/v1.23.md | 2 ++ docs/api/v1.24.md | 2 ++ 8 files changed, 19 insertions(+) diff --git a/api/swagger.yaml b/api/swagger.yaml index 761551ddd8..9a60664003 100644 --- a/api/swagger.yaml +++ b/api/swagger.yaml @@ -4043,6 +4043,11 @@ paths: description: "If the container is running, kill it before removing it." type: "boolean" default: false + - name: "link" + in: "query" + description: "Remove the specified link associated with the container." + type: "boolean" + default: false tags: ["Container"] /containers/{id}/archive: head: diff --git a/docs/api/v1.18.md b/docs/api/v1.18.md index 1a4d822189..d7aab29e02 100644 --- a/docs/api/v1.18.md +++ b/docs/api/v1.18.md @@ -1056,6 +1056,8 @@ Remove the container `id` from the filesystem associated to the container. Default `false`. - **force** - 1/True/true or 0/False/false, Kill then remove the container. Default `false`. +- **link** - 1/True/true or 0/False/false, Remove the specified + link associated to the container. Default `false`. **Status codes**: diff --git a/docs/api/v1.19.md b/docs/api/v1.19.md index a1a7280d3a..c5d6290fc3 100644 --- a/docs/api/v1.19.md +++ b/docs/api/v1.19.md @@ -1095,6 +1095,8 @@ Remove the container `id` from the filesystem associated to the container. Default `false`. - **force** - 1/True/true or 0/False/false, Kill then remove the container. Default `false`. +- **link** - 1/True/true or 0/False/false, Remove the specified + link associated to the container. Default `false`. **Status codes**: diff --git a/docs/api/v1.20.md b/docs/api/v1.20.md index 2532c49950..80868cc20a 100644 --- a/docs/api/v1.20.md +++ b/docs/api/v1.20.md @@ -1102,6 +1102,8 @@ Remove the container `id` from the filesystem associated to the container. Default `false`. - **force** - 1/True/true or 0/False/false, Kill then remove the container. Default `false`. +- **link** - 1/True/true or 0/False/false, Remove the specified + link associated to the container. Default `false`. **Status codes**: diff --git a/docs/api/v1.21.md b/docs/api/v1.21.md index b4f54b7c44..f21c722eb1 100644 --- a/docs/api/v1.21.md +++ b/docs/api/v1.21.md @@ -1185,6 +1185,8 @@ Remove the container `id` from the filesystem associated to the container. Default `false`. - **force** - 1/True/true or 0/False/false, Kill then remove the container. Default `false`. +- **link** - 1/True/true or 0/False/false, Remove the specified + link associated to the container. Default `false`. **Status codes**: diff --git a/docs/api/v1.22.md b/docs/api/v1.22.md index f3c111f264..6b3d6eceb6 100644 --- a/docs/api/v1.22.md +++ b/docs/api/v1.22.md @@ -1364,6 +1364,8 @@ Remove the container `id` from the filesystem associated to the container. Default `false`. - **force** - 1/True/true or 0/False/false, Kill then remove the container. Default `false`. +- **link** - 1/True/true or 0/False/false, Remove the specified + link associated to the container. Default `false`. **Status codes**: diff --git a/docs/api/v1.23.md b/docs/api/v1.23.md index f70bbd5313..aaf42045e8 100644 --- a/docs/api/v1.23.md +++ b/docs/api/v1.23.md @@ -1399,6 +1399,8 @@ Remove the container `id` from the filesystem associated to the container. Default `false`. - **force** - 1/True/true or 0/False/false, Kill then remove the container. Default `false`. +- **link** - 1/True/true or 0/False/false, Remove the specified + link associated to the container. Default `false`. **Status codes**: diff --git a/docs/api/v1.24.md b/docs/api/v1.24.md index 44ebc25cd5..197bee2685 100644 --- a/docs/api/v1.24.md +++ b/docs/api/v1.24.md @@ -1426,6 +1426,8 @@ Remove the container `id` from the filesystem associated to the container. Default `false`. - **force** - 1/True/true or 0/False/false, Kill then remove the container. Default `false`. +- **link** - 1/True/true or 0/False/false, Remove the specified + link associated to the container. Default `false`. **Status codes**: From 411ff56edf1d86b68df4e92fea42be1044ac4167 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 14 Feb 2017 13:10:24 -0800 Subject: [PATCH 34/38] Merge pull request #30921 from anusha-ragunathan/debug_docs Add plugin socket related debug docs. (cherry picked from commit fddab1444f2c2f7e240a4bde10971ed84967767b) Signed-off-by: Sebastiaan van Stijn --- docs/extend/index.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/extend/index.md b/docs/extend/index.md index a2aa208d6b..2b0cbeec2e 100644 --- a/docs/extend/index.md +++ b/docs/extend/index.md @@ -289,3 +289,28 @@ follows: $ docker-runc exec -t f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62 sh ``` +#### Using curl to debug plugin socket issues. + +To verify if the plugin API socket that the docker daemon communicates with +is responsive, use curl. In this example, we will make API calls from the +docker host to volume and network plugins using curl 7.47.0 to ensure that +the plugin is listening on the said socket. For a well functioning plugin, +these basic requests should work. Note that plugin sockets are available on the host under `/var/run/docker/plugins/` + + +```bash +curl -H "Content-Type: application/json" -XPOST -d '{}' --unix-socket /var/run/docker/plugins/e8a37ba56fc879c991f7d7921901723c64df6b42b87e6a0b055771ecf8477a6d/plugin.sock http:/VolumeDriver.List + +{"Mountpoint":"","Err":"","Volumes":[{"Name":"myvol1","Mountpoint":"/data/myvol1"},{"Name":"myvol2","Mountpoint":"/data/myvol2"}],"Volume":null} +``` + +```bash +curl -H "Content-Type: application/json" -XPOST -d '{}' --unix-socket /var/run/docker/plugins/45e00a7ce6185d6e365904c8bcf62eb724b1fe307e0d4e7ecc9f6c1eb7bcdb70/plugin.sock http:/NetworkDriver.GetCapabilities + +{"Scope":"local"} +``` +When using curl 7.5 and above, the URL should be of the form +`http://hostname/APICall`, where `hostname` is the valid hostname where the +plugin is installed and `APICall` is the call to the plugin API. + +For example, `http://localhost/VolumeDriver.List` From 1f1b15ae4c1513e643d9146ecbcb9e60c351e07a Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Sun, 12 Feb 2017 23:37:37 -0800 Subject: [PATCH 35/38] Merge pull request #30956 from yongtang/02122017-deprecated-login-email-removal Add missing link in deprecated.md (cherry picked from commit b5b6752230b77902536bab28403426c30d6f6ce0) Signed-off-by: Sebastiaan van Stijn --- docs/deprecated.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/deprecated.md b/docs/deprecated.md index 1298370ba9..a88e398079 100644 --- a/docs/deprecated.md +++ b/docs/deprecated.md @@ -23,7 +23,7 @@ see [Feature Deprecation Policy](https://docs.docker.com/engine/#feature-depreca ### Top-level network properties in NetworkSettings -**Deprecated In Release: v1.13.0** +**Deprecated In Release: [v1.13.0](https://github.com/docker/docker/releases/tag/v1.13.0)** **Target For Removal In Release: v1.16** From 93daa00ee63eda2291653559735e2506e240d4bd Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Mon, 13 Feb 2017 00:02:28 -0800 Subject: [PATCH 36/38] Merge pull request #30965 from YuPengZTE/devDes fix typo (cherry picked from commit a8f4d82176139babcd818fcb4590eec22860ffc9) Signed-off-by: Sebastiaan van Stijn --- docs/reference/commandline/exec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/commandline/exec.md b/docs/reference/commandline/exec.md index df2ad6eae8..1ae46cf194 100644 --- a/docs/reference/commandline/exec.md +++ b/docs/reference/commandline/exec.md @@ -31,7 +31,7 @@ Options: -u, --user Username or UID (format: [:]) ``` -## Descriptino +## Description The `docker exec` command runs a new command in a running container. From 23de3ee83b38babd47e4efdccbab1b7fe77f407c Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Thu, 16 Feb 2017 18:13:15 -0800 Subject: [PATCH 37/38] Merge pull request #31023 from mstanleyjones/fix_liquid_errors Fix some Liquid errors (cherry picked from commit 88de5c36c7afdae095322c64c0472d27c4ff3f43) Signed-off-by: Sebastiaan van Stijn --- docs/deprecated.md | 6 +++++- docs/extend/index.md | 26 ++++++++++++++------------ docs/extend/plugins_graphdriver.md | 4 ++++ 3 files changed, 23 insertions(+), 13 deletions(-) diff --git a/docs/deprecated.md b/docs/deprecated.md index a88e398079..9d3da96322 100644 --- a/docs/deprecated.md +++ b/docs/deprecated.md @@ -183,7 +183,11 @@ Log tags are now generated in a standard way across different logging drivers. Because of which, the driver specific log tag options `syslog-tag`, `gelf-tag` and `fluentd-tag` have been deprecated in favor of the generic `tag` option. - docker --log-driver=syslog --log-opt tag="{{.ImageName}}/{{.Name}}/{{.ID}}" +```bash +{% raw %} +docker --log-driver=syslog --log-opt tag="{{.ImageName}}/{{.Name}}/{{.ID}}" +{% endraw %} +``` ### LXC built-in exec driver **Deprecated In Release: [v1.8.0](https://github.com/docker/docker/releases/tag/v1.8.0)** diff --git a/docs/extend/index.md b/docs/extend/index.md index 2b0cbeec2e..99e02a8bab 100644 --- a/docs/extend/index.md +++ b/docs/extend/index.md @@ -20,7 +20,7 @@ title: Managed plugin system * [Debugging plugins](index.md#debugging-plugins) Docker Engine's plugins system allows you to install, start, stop, and remove -plugins using Docker Engine. +plugins using Docker Engine. For information about the legacy plugin system available in Docker Engine 1.12 and earlier, see [Understand legacy Docker Engine plugins](legacy_plugins.md). @@ -78,7 +78,7 @@ enabled, and use it to create a volume. 3. Create a volume using the plugin. This example mounts the `/remote` directory on host `1.2.3.4` into a volume named `sshvolume`. - + This volume can now be mounted into containers. ```bash @@ -110,7 +110,7 @@ enabled, and use it to create a volume. 6. Remove the volume `sshvolume` ```bash docker volume rm sshvolume - + sshvolume ``` To disable a plugin, use the `docker plugin disable` command. To completely @@ -122,10 +122,10 @@ commands and options, see the In swarm mode, it is possible to create a service that allows for attaching to networks or mounting volumes. Swarm schedules services based on plugin availability -on a node. In this example, a volume plugin is installed on a swarm worker and a volume +on a node. In this example, a volume plugin is installed on a swarm worker and a volume is created using the plugin. In the manager, a service is created with the relevant mount options. It can be observed that the service is scheduled to run on the worker -node with the said volume plugin and volume. +node with the said volume plugin and volume. In the following example, node1 is the manager and node2 is the worker. @@ -152,7 +152,7 @@ In the following example, node1 is the manager and node2 is the worker. Status: Downloaded newer image for tiborvass/sample-volume-plugin:latest Installed plugin tiborvass/sample-volume-plugin ``` - + ```bash $ docker volume create -d tiborvass/sample-volume-plugin --name pluginVol ``` @@ -163,15 +163,17 @@ In the following example, node1 is the manager and node2 is the worker. $ docker service create --name my-service --mount type=volume,volume-driver=tiborvass/sample-volume-plugin,source=pluginVol,destination=/tmp busybox top $ docker service ls - z1sj8bb8jnfn my-service replicated 1/1 busybox:latest + z1sj8bb8jnfn my-service replicated 1/1 busybox:latest ``` docker service ls shows service 1 instance of service running. 4. Observe the task getting scheduled in node 2: ```bash - $ docker ps --format '{{.ID}}\t {{.Status}} {{.Names}} {{.Command}}' + {% raw %} + $ docker ps --format '{{.ID}}\t {{.Status}} {{.Names}} {{.Command}}' 83fc1e842599 Up 2 days my-service.1.9jn59qzn7nbc3m0zt1hij12xs "top" + {% endraw %} ``` ## Developing a plugin @@ -228,7 +230,7 @@ with Docker Engine. This plugin has no runtime parameters. A new plugin can be created by running `docker plugin create ./path/to/plugin/data` where the plugin data contains a plugin configuration file `config.json` and a root filesystem -in subdirectory `rootfs`. +in subdirectory `rootfs`. After that the plugin `` will show up in `docker plugin ls`. Plugins can be pushed to remote registries with @@ -292,7 +294,7 @@ $ docker-runc exec -t f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b8 #### Using curl to debug plugin socket issues. To verify if the plugin API socket that the docker daemon communicates with -is responsive, use curl. In this example, we will make API calls from the +is responsive, use curl. In this example, we will make API calls from the docker host to volume and network plugins using curl 7.47.0 to ensure that the plugin is listening on the said socket. For a well functioning plugin, these basic requests should work. Note that plugin sockets are available on the host under `/var/run/docker/plugins/` @@ -309,8 +311,8 @@ curl -H "Content-Type: application/json" -XPOST -d '{}' --unix-socket /var/run/d {"Scope":"local"} ``` -When using curl 7.5 and above, the URL should be of the form -`http://hostname/APICall`, where `hostname` is the valid hostname where the +When using curl 7.5 and above, the URL should be of the form +`http://hostname/APICall`, where `hostname` is the valid hostname where the plugin is installed and `APICall` is the call to the plugin API. For example, `http://localhost/VolumeDriver.List` diff --git a/docs/extend/plugins_graphdriver.md b/docs/extend/plugins_graphdriver.md index d91c383b5f..7ec2e47c41 100644 --- a/docs/extend/plugins_graphdriver.md +++ b/docs/extend/plugins_graphdriver.md @@ -287,7 +287,9 @@ and `Parent`. `Parent` may be an empty string, in which case there is no parent. **Response**: ``` +{% raw %} {{ TAR STREAM }} +{% endraw %} ``` ### /GraphDriver.Changes @@ -330,7 +332,9 @@ Respond with a non-empty string error if an error occurred. **Request**: ``` +{% raw %} {{ TAR STREAM }} +{% endraw %} ``` Extract the changeset from the given diff into the layer with the specified `ID` From f6b33c65d5a6e35227af5e94337db78795bb1af3 Mon Sep 17 00:00:00 2001 From: Vincent Demeester Date: Mon, 20 Feb 2017 09:29:38 +0100 Subject: [PATCH 38/38] Merge pull request #31034 from erxian/refine-service-update-document add rollback explanation to docker service update command document (cherry picked from commit 75843d36aa5c3eaade50da005f9e0ff2602f3d5e) Signed-off-by: Sebastiaan van Stijn --- docs/reference/commandline/service_update.md | 45 ++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/docs/reference/commandline/service_update.md b/docs/reference/commandline/service_update.md index a98923eb63..d73b9a1a96 100644 --- a/docs/reference/commandline/service_update.md +++ b/docs/reference/commandline/service_update.md @@ -153,6 +153,51 @@ $ docker service update --mount-rm /somewhere myservice myservice ``` +### Rolling back to the previous version of a service + +Use the `--rollback` option to roll back to the previous version of the service. + +This will revert the service to the configuration that was in place before the most recent `docker service update` command. + +The following example updates the number of replicas for the service from 4 to 5, and then rolls back to the previous configuration. + +```bash +$ docker service update --replicas=5 web + +web + +$ docker service ls + +ID NAME MODE REPLICAS IMAGE +80bvrzp6vxf3 web replicated 0/5 nginx:alpine + +``` +Roll back the `web` service... + +```bash +$ docker service update --rollback web + +web + +$ docker service ls + +ID NAME MODE REPLICAS IMAGE +80bvrzp6vxf3 web replicated 0/4 nginx:alpine + +``` + +Other options can be combined with `--rollback` as well, for example, `--update-delay 0s` to execute the rollback without a delay between tasks: + +```bash +$ docker service update \ + --rollback \ + --update-delay 0s + web + +web + +``` + ### Add or remove secrets Use the `--secret-add` or `--secret-rm` options add or remove a service's