From 9374c5fea062e53055c809eab837d7a15cd7fc73 Mon Sep 17 00:00:00 2001 From: Misty Stanley-Jones Date: Mon, 9 Jan 2017 14:19:18 -0800 Subject: [PATCH] Add examples to CLI generation templates --- .../reference/commandline/container_attach.md | 31 + .../reference/commandline/container_commit.md | 25 + engine/reference/commandline/container_cp.md | 67 ++ .../reference/commandline/container_create.md | 15 + .../reference/commandline/container_diff.md | 28 + .../reference/commandline/container_exec.md | 15 + .../reference/commandline/container_export.md | 19 + .../reference/commandline/container_logs.md | 96 +++ .../reference/commandline/container_port.md | 40 ++ .../reference/commandline/container_prune.md | 75 +++ engine/reference/commandline/container_rm.md | 35 ++ .../reference/commandline/container_stats.md | 17 + engine/reference/commandline/container_top.md | 8 + .../reference/commandline/container_update.md | 69 +++ .../reference/commandline/container_wait.md | 14 + engine/reference/commandline/image_build.md | 264 ++++++++ engine/reference/commandline/image_history.md | 25 + engine/reference/commandline/image_import.md | 36 ++ engine/reference/commandline/image_load.md | 30 + engine/reference/commandline/image_ls.md | 92 +++ engine/reference/commandline/image_pull.md | 182 ++++++ engine/reference/commandline/image_push.md | 25 + engine/reference/commandline/image_rm.md | 8 + engine/reference/commandline/image_save.md | 17 + engine/reference/commandline/image_tag.md | 33 + engine/reference/commandline/inspect.md | 299 +++++++++ engine/reference/commandline/login.md | 8 + engine/reference/commandline/logout.md | 8 + .../reference/commandline/network_connect.md | 39 ++ .../reference/commandline/network_create.md | 81 +++ .../commandline/network_disconnect.md | 6 + .../reference/commandline/network_inspect.md | 89 +++ engine/reference/commandline/network_ls.md | 157 +++++ engine/reference/commandline/network_rm.md | 19 + engine/reference/commandline/run.md | 584 ++++++++++++++++++ engine/reference/commandline/search.md | 24 + engine/reference/commandline/secret_create.md | 54 ++ .../reference/commandline/secret_inspect.md | 44 ++ engine/reference/commandline/secret_ls.md | 8 + .../reference/commandline/service_create.md | 505 +++++++++++++++ .../reference/commandline/service_inspect.md | 116 ++++ engine/reference/commandline/service_ps.md | 117 ++++ engine/reference/commandline/service_scale.md | 61 ++ .../reference/commandline/service_update.md | 80 +++ engine/reference/commandline/system_events.md | 106 ++++ engine/reference/commandline/system_info.md | 149 +++++ engine/reference/commandline/version.md | 47 ++ engine/reference/commandline/volume_create.md | 34 + 48 files changed, 3901 insertions(+) diff --git a/engine/reference/commandline/container_attach.md b/engine/reference/commandline/container_attach.md index 64fb43a980..bf65a52673 100644 --- a/engine/reference/commandline/container_attach.md +++ b/engine/reference/commandline/container_attach.md @@ -13,3 +13,34 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +### Attaching to a container + +In this example the top command is run inside a container, from an image called +fedora, in detached mode. The ID from the container is passed into the **docker +attach** command: + +```bash +$ ID=$(sudo docker run -d fedora /usr/bin/top -b) + +$ sudo docker attach $ID +top - 02:05:52 up 3:05, 0 users, load average: 0.01, 0.02, 0.05 +Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie +Cpu(s): 0.1%us, 0.2%sy, 0.0%ni, 99.7%id, 0.0%wa, 0.0%hi, 0.0%si, 0.0%st +Mem: 373572k total, 355560k used, 18012k free, 27872k buffers +Swap: 786428k total, 0k used, 786428k free, 221740k cached + +PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND +1 root 20 0 17200 1116 912 R 0 0.3 0:00.03 top + +top - 02:05:55 up 3:05, 0 users, load average: 0.01, 0.02, 0.05 +Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie +Cpu(s): 0.0%us, 0.2%sy, 0.0%ni, 99.8%id, 0.0%wa, 0.0%hi, 0.0%si, 0.0%st +Mem: 373572k total, 355244k used, 18328k free, 27872k buffers +Swap: 786428k total, 0k used, 786428k free, 221776k cached + +PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND +1 root 20 0 17208 1144 932 R 0 0.3 0:00.03 top +``` diff --git a/engine/reference/commandline/container_commit.md b/engine/reference/commandline/container_commit.md index afe4930216..5cea5e22c3 100644 --- a/engine/reference/commandline/container_commit.md +++ b/engine/reference/commandline/container_commit.md @@ -13,3 +13,28 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +### Creating a new image from an existing container +An existing Fedora based container has had Apache installed while running +in interactive mode with the bash shell. Apache is also running. To +create a new image run `docker ps` to find the container's ID and then run: + +```bash +$ docker commit -m="Added Apache to Fedora base image" \ + -a="A D Ministrator" 98bd7fc99854 fedora/fedora_httpd:20 +``` + +Note that only `a-z0-9-_.` are allowed when naming images from an +existing container. + +### Apply specified Dockerfile instructions while committing the image +If an existing container was created without the DEBUG environment +variable set to "true", you can create a new image based on that +container by first getting the container's ID with `docker ps` and +then running: + +```bash +$ docker container commit -c="ENV DEBUG true" 98bd7fc99854 debug-image +``` diff --git a/engine/reference/commandline/container_cp.md b/engine/reference/commandline/container_cp.md index 6e911bf411..adb1db7b02 100644 --- a/engine/reference/commandline/container_cp.md +++ b/engine/reference/commandline/container_cp.md @@ -13,3 +13,70 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +Suppose a container has finished producing some output as a file it saves +to somewhere in its filesystem. This could be the output of a build job or +some other computation. You can copy these outputs from the container to a +location on your local host. + +If you want to copy the `/tmp/foo` directory from a container to the +existing `/tmp` directory on your host. If you run `docker container cp` in your `~` +(home) directory on the local host: + + $ docker container cp compassionate_darwin:tmp/foo /tmp + +Docker creates a `/tmp/foo` directory on your host. Alternatively, you can omit +the leading slash in the command. If you execute this command from your home +directory: + + $ docker container cp compassionate_darwin:tmp/foo tmp + +If `~/tmp` does not exist, Docker will create it and copy the contents of +`/tmp/foo` from the container into this new directory. If `~/tmp` already +exists as a directory, then Docker will copy the contents of `/tmp/foo` from +the container into a directory at `~/tmp/foo`. + +When copying a single file to an existing `LOCALPATH`, the `docker container cp` command +will either overwrite the contents of `LOCALPATH` if it is a file or place it +into `LOCALPATH` if it is a directory, overwriting an existing file of the same +name if one exists. For example, this command: + + $ docker container cp sharp_ptolemy:/tmp/foo/myfile.txt /test + +If `/test` does not exist on the local machine, it will be created as a file +with the contents of `/tmp/foo/myfile.txt` from the container. If `/test` +exists as a file, it will be overwritten. Lastly, if `/test` exists as a +directory, the file will be copied to `/test/myfile.txt`. + +Next, suppose you want to copy a file or folder into a container. For example, +this could be a configuration file or some other input to a long running +computation that you would like to place into a created container before it +starts. This is useful because it does not require the configuration file or +other input to exist in the container image. + +If you have a file, `config.yml`, in the current directory on your local host +and wish to copy it to an existing directory at `/etc/my-app.d` in a container, +this command can be used: + + $ docker container cp config.yml myappcontainer:/etc/my-app.d + +If you have several files in a local directory `/config` which you need to copy +to a directory `/etc/my-app.d` in a container: + + $ docker container cp /config/. myappcontainer:/etc/my-app.d + +The above command will copy the contents of the local `/config` directory into +the directory `/etc/my-app.d` in the container. + +Finally, if you want to copy a symbolic link into a container, you typically +want to copy the linked target and not the link itself. To copy the target, use +the `-L` option, for example: + + $ ln -s /tmp/somefile /tmp/somefile.ln + $ docker container cp -L /tmp/somefile.ln myappcontainer:/tmp/ + +This command copies content of the local `/tmp/somefile` into the file +`/tmp/somefile.ln` in the container. Without `-L` option, the `/tmp/somefile.ln` +preserves its symbolic link but not its content. diff --git a/engine/reference/commandline/container_create.md b/engine/reference/commandline/container_create.md index 237599bcc8..448c58677c 100644 --- a/engine/reference/commandline/container_create.md +++ b/engine/reference/commandline/container_create.md @@ -13,3 +13,18 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +### Specify isolation technology for container (--isolation) + +This option is useful in situations where you are running Docker containers on +Windows. The `--isolation=` option sets a container's isolation +technology. On Linux, the only supported is the `default` option which uses +Linux namespaces. On Microsoft Windows, you can specify these values: + +* `default`: Use the value specified by the Docker daemon's `--exec-opt` . If the `daemon` does not specify an isolation technology, Microsoft Windows uses `process` as its default value. +* `process`: Namespace isolation only. +* `hyperv`: Hyper-V hypervisor partition-based isolation. + +Specifying the `--isolation` flag without a value is the same as setting `--isolation="default"`. diff --git a/engine/reference/commandline/container_diff.md b/engine/reference/commandline/container_diff.md index afa1956e3b..7cf5e730f9 100644 --- a/engine/reference/commandline/container_diff.md +++ b/engine/reference/commandline/container_diff.md @@ -13,3 +13,31 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +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/engine/reference/commandline/container_exec.md b/engine/reference/commandline/container_exec.md index 01d30649bf..e7cefba1bb 100644 --- a/engine/reference/commandline/container_exec.md +++ b/engine/reference/commandline/container_exec.md @@ -13,3 +13,18 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + + $ 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 + +This will create a new file `/tmp/execWorks` inside the running container +`ubuntu_bash`, in the background. + + $ docker exec -it ubuntu_bash bash + +This will create a new Bash session in the container `ubuntu_bash`. diff --git a/engine/reference/commandline/container_export.md b/engine/reference/commandline/container_export.md index 67d383d886..220bf2f544 100644 --- a/engine/reference/commandline/container_export.md +++ b/engine/reference/commandline/container_export.md @@ -13,3 +13,22 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +Export the contents of the container called angry_bell to a tar file +called angry_bell.tar: + +```bash +$ docker export angry_bell > angry_bell.tar + +$ docker export --output=angry_bell-latest.tar angry_bell + +$ ls -sh angry_bell.tar + +321M angry_bell.tar + +$ ls -sh angry_bell-latest.tar + +321M angry_bell-latest.tar +``` diff --git a/engine/reference/commandline/container_logs.md b/engine/reference/commandline/container_logs.md index 55e92f3949..40f1bcbd60 100644 --- a/engine/reference/commandline/container_logs.md +++ b/engine/reference/commandline/container_logs.md @@ -13,3 +13,99 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +### Display all containers, including non-running + +```bash +$ docker container ls -a + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +a87ecb4f327c fedora:20 /bin/sh -c #(nop) MA 20 minutes ago Exit 0 desperate_brattain +01946d9d34d8 vpavlin/rhel7:latest /bin/sh -c #(nop) MA 33 minutes ago Exit 0 thirsty_bell +c1d3b0166030 acffc0358b9e /bin/sh -c yum -y up 2 weeks ago Exit 1 determined_torvalds +41d50ecd2f57 fedora:20 /bin/sh -c #(nop) MA 2 weeks ago Exit 0 drunk_pike +``` + +### Display only IDs of all containers, including non-running + +```bash +$ docker container ls -a -q + +a87ecb4f327c +01946d9d34d8 +c1d3b0166030 +41d50ecd2f57 +``` + +# Display only IDs of all containers that have the name `determined_torvalds` + +```bash +$ docker container ls -a -q --filter=name=determined_torvalds + +c1d3b0166030 +``` + +### Display containers with their commands + +```bash +{% raw %} +$ docker container ls --format "{{.ID}}: {{.Command}}" + +a87ecb4f327c: /bin/sh -c #(nop) MA +01946d9d34d8: /bin/sh -c #(nop) MA +c1d3b0166030: /bin/sh -c yum -y up +41d50ecd2f57: /bin/sh -c #(nop) MA +{% endraw %} +``` + +### Display containers with their labels in a table + +```bash +{% raw %} +$ docker container ls --format "table {{.ID}}\t{{.Labels}}" + +CONTAINER ID LABELS +a87ecb4f327c com.docker.swarm.node=ubuntu,com.docker.swarm.storage=ssd +01946d9d34d8 +c1d3b0166030 com.docker.swarm.node=debian,com.docker.swarm.cpu=6 +41d50ecd2f57 com.docker.swarm.node=fedora,com.docker.swarm.cpu=3,com.docker.swarm.storage=ssd +{% endraw %} +``` + +### Display containers with their node label in a table + +```bash +{% raw %} +$ docker container ls --format 'table {{.ID}}\t{{(.Label "com.docker.swarm.node")}}' + +CONTAINER ID NODE +a87ecb4f327c ubuntu +01946d9d34d8 +c1d3b0166030 debian +41d50ecd2f57 fedora +{% endraw %} +``` + +### Display containers with `remote-volume` mounted + +```bash +{% raw %} +$ docker container ls --filter volume=remote-volume --format "table {{.ID}}\t{{.Mounts}}" + +CONTAINER ID MOUNTS +9c3527ed70ce remote-volume +{% endraw %} +``` + +### Display containers with a volume mounted in `/data` + +```bash +{% raw %} +$ docker container ls --filter volume=/data --format "table {{.ID}}\t{{.Mounts}}" + +CONTAINER ID MOUNTS +9c3527ed70ce remote-volume +{% endraw %} +``` diff --git a/engine/reference/commandline/container_port.md b/engine/reference/commandline/container_port.md index 5a00bed24a..36e349467f 100644 --- a/engine/reference/commandline/container_port.md +++ b/engine/reference/commandline/container_port.md @@ -13,3 +13,43 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +```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 +``` + +### Find out all the ports mapped + +```bash +$ docker container port test + +7890/tcp -> 0.0.0.0:4321 +9876/tcp -> 0.0.0.0:1234 +``` + +### Find out a specific mapping + +```bash +$ docker container port test 7890/tcp + +0.0.0.0:4321 +``` + +```bash +$ docker container port test 7890 + +0.0.0.0:4321 +``` + +### An example showing error for non-existent mapping + +```bash +$ docker container port test 7890/udp + +2014/06/24 11:53:36 Error: No public port '7890/udp' published for test +``` diff --git a/engine/reference/commandline/container_prune.md b/engine/reference/commandline/container_prune.md index 8005e0a5c0..fbb2c9031a 100644 --- a/engine/reference/commandline/container_prune.md +++ b/engine/reference/commandline/container_prune.md @@ -13,3 +13,78 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +```bash +$ docker container prune +WARNING! This will remove all stopped containers. +Are you sure you want to continue? [y/N] y +Deleted Containers: +4a7f7eebae0f63178aff7eb0aa39cd3f0627a203ab2df258c1a00b456cf20063 +f98f9c2aa1eaf727e4ec9c0283bc7d4aa4762fbdba7f26191f26c97f64090360 + +Total reclaimed space: 212 B +``` + +### 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 %} +``` diff --git a/engine/reference/commandline/container_rm.md b/engine/reference/commandline/container_rm.md index b17168450a..9686dd8b32 100644 --- a/engine/reference/commandline/container_rm.md +++ b/engine/reference/commandline/container_rm.md @@ -13,3 +13,38 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +### Removing a container using its ID + +To remove a container using its ID, find either from a **docker ps -a** +command, or use the ID returned from the **docker run** command, or retrieve +it from a file used to store it using the **docker run --cidfile**: + + $ docker container rm abebf7571666 + +### Removing a container using the container name + +The name of the container can be found using the **docker ps -a** +command. The use that name as follows: + + $ docker container rm hopeful_morse + +### Removing a container and all associated volumes + + $ docker container 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 container rm -v hello + +In this example, the volume for `/foo` will remain in tact, but the volume for +`/bar` will be removed. The same behavior holds for volumes inherited with +`--volumes-from`. diff --git a/engine/reference/commandline/container_stats.md b/engine/reference/commandline/container_stats.md index 26bf990bdc..9498f7bb17 100644 --- a/engine/reference/commandline/container_stats.md +++ b/engine/reference/commandline/container_stats.md @@ -13,3 +13,20 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +Running `docker container stats` on all running containers + + $ docker container 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 container stats` on multiple containers by name and id. + + $ docker container 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 diff --git a/engine/reference/commandline/container_top.md b/engine/reference/commandline/container_top.md index 42fc4ceb16..918115a9aa 100644 --- a/engine/reference/commandline/container_top.md +++ b/engine/reference/commandline/container_top.md @@ -13,3 +13,11 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +Run **docker container top** with the ps option of -x: + + $ docker container top 8601afda2b -x + PID TTY STAT TIME COMMAND + 16623 ? Ss 0:00 sleep 99999 diff --git a/engine/reference/commandline/container_update.md b/engine/reference/commandline/container_update.md index eb1ee8ea8b..fcaf7485c8 100644 --- a/engine/reference/commandline/container_update.md +++ b/engine/reference/commandline/container_update.md @@ -13,3 +13,72 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +### Update a container's cpu-shares + +To limit a container's cpu-shares to 512, first identify the container +name or ID. You can use **docker ps** to find these values. You can also +use the ID returned from the **docker run** command. Then, do the following: + +```bash +$ docker container update --cpu-shares 512 abebf7571666 +``` + +### Update a container with cpu-shares and memory + +To update multiple resource configurations for multiple containers: + +```bash +$ docker container update --cpu-shares 512 -m 300M abebf7571666 hopeful_morse +``` + +### Update a container's kernel memory constraints + +You can update a container's kernel memory limit using the **--kernel-memory** +option. On kernel version older than 4.6, this option can be updated on a +running container only if the container was started with **--kernel-memory**. +If the container was started *without* **--kernel-memory** you need to stop +the container before updating kernel memory. + +For example, if you started a container with this command: + +```bash +$ docker run -dit --name test --kernel-memory 50M ubuntu bash +``` + +You can update kernel memory while the container is running: + +```bash +$ docker container update --kernel-memory 80M test +``` + +If you started a container *without* kernel memory initialized: + +```bash +$ docker run -dit --name test2 --memory 300M ubuntu bash +``` + +Update kernel memory of running container `test2` will fail. You need to stop +the container before updating the **--kernel-memory** setting. The next time you +start it, the container uses the new value. + +Kernel version newer than (include) 4.6 does not have this limitation, you +can use `--kernel-memory` the same way as other options. + +### Update a container's restart policy + +You can change a container's restart policy on a running container. The new +restart policy takes effect instantly after you run `docker container update` on a +container. + +To update restart policy for one or more containers: + +```bash +$ docker container update --restart=on-failure:3 abebf7571666 hopeful_morse +``` + +Note that if the container is started with "--rm" flag, you cannot update the restart +policy for it. The `AutoRemove` and `RestartPolicy` are mutually exclusive for the +container. diff --git a/engine/reference/commandline/container_wait.md b/engine/reference/commandline/container_wait.md index 4ec5462592..b1f309f2d4 100644 --- a/engine/reference/commandline/container_wait.md +++ b/engine/reference/commandline/container_wait.md @@ -13,3 +13,17 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +# EXAMPLES + +```bash +$ docker run -d fedora sleep 99 + +079b83f558a2bc52ecad6b2a5de13622d584e6bb1aea058c11b36511e85e7622 + +$ docker container wait 079b83f558a2bc + +0 +``` diff --git a/engine/reference/commandline/image_build.md b/engine/reference/commandline/image_build.md index 0b2eb54c84..71a7fc4e14 100644 --- a/engine/reference/commandline/image_build.md +++ b/engine/reference/commandline/image_build.md @@ -13,3 +13,267 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +### Build with PATH + +```bash +$ docker build . + +Uploading context 10240 bytes +Step 1/3 : FROM busybox +Pulling repository busybox + ---> e9aa60c60128MB/2.284 MB (100%) endpoint: https://cdn-registry-1.docker.io/v1/ +Step 2/3 : RUN ls -lh / + ---> Running in 9c9e81692ae9 +total 24 +drwxr-xr-x 2 root root 4.0K Mar 12 2013 bin +drwxr-xr-x 5 root root 4.0K Oct 19 00:19 dev +drwxr-xr-x 2 root root 4.0K Oct 19 00:19 etc +drwxr-xr-x 2 root root 4.0K Nov 15 23:34 lib +lrwxrwxrwx 1 root root 3 Mar 12 2013 lib64 -> lib +dr-xr-xr-x 116 root root 0 Nov 15 23:34 proc +lrwxrwxrwx 1 root root 3 Mar 12 2013 sbin -> bin +dr-xr-xr-x 13 root root 0 Nov 15 23:34 sys +drwxr-xr-x 2 root root 4.0K Mar 12 2013 tmp +drwxr-xr-x 2 root root 4.0K Nov 15 23:34 usr + ---> b35f4035db3f +Step 3/3 : CMD echo Hello world + ---> Running in 02071fceb21b + ---> f52f38b7823e +Successfully built f52f38b7823e +Removing intermediate container 9c9e81692ae9 +Removing intermediate container 02071fceb21b +``` + +This example specifies that the `PATH` is `.`, and so all the files in the +local directory get `tar`d and sent to the Docker daemon. The `PATH` specifies +where to find the files for the "context" of the build on the Docker daemon. +Remember that the daemon could be running on a remote machine and that no +parsing of the Dockerfile happens at the client side (where you're running +`docker build`). That means that *all* the files at `PATH` get sent, not just +the ones listed to [*ADD*](../builder.md#add) in the Dockerfile. + +The transfer of context from the local machine to the Docker daemon is what the +`docker` client means when you see the "Sending build context" message. + +If you wish to keep the intermediate containers after the build is complete, +you must use `--rm=false`. This does not affect the build cache. + +### Build with URL + +```bash +$ docker build github.com/creack/docker-firefox +``` + +This will clone the GitHub repository and use the cloned repository as context. +The Dockerfile at the root of the repository is used as Dockerfile. You can +specify an arbitrary Git repository by using the `git://` or `git@` scheme. + +```bash +$ docker build -f ctx/Dockerfile http://server/ctx.tar.gz + +Downloading context: http://server/ctx.tar.gz [===================>] 240 B/240 B +Step 1/3 : FROM busybox + ---> 8c2e06607696 +Step 2/3 : ADD ctx/container.cfg / + ---> e7829950cee3 +Removing intermediate container b35224abf821 +Step 3/3 : CMD /bin/ls + ---> Running in fbc63d321d73 + ---> 3286931702ad +Removing intermediate container fbc63d321d73 +Successfully built 377c409b35e4 +``` + +This sends the URL `http://server/ctx.tar.gz` to the Docker daemon, which +downloads and extracts the referenced tarball. The `-f ctx/Dockerfile` +parameter specifies a path inside `ctx.tar.gz` to the `Dockerfile` that is used +to build the image. Any `ADD` commands in that `Dockerfile` that refers to local +paths must be relative to the root of the contents inside `ctx.tar.gz`. In the +example above, the tarball contains a directory `ctx/`, so the `ADD +ctx/container.cfg /` operation works as expected. + +### Build with - + +```bash +$ docker build - < Dockerfile +``` + +This will read a Dockerfile from `STDIN` without context. Due to the lack of a +context, no contents of any local directory will be sent to the Docker daemon. +Since there is no context, a Dockerfile `ADD` only works if it refers to a +remote URL. + +```bash +$ docker build - < context.tar.gz +``` + +This will build an image for a compressed context read from `STDIN`. Supported +formats are: bzip2, gzip and xz. + +### Usage of .dockerignore + +```bash +$ docker build . + +Uploading context 18.829 MB +Uploading context +Step 1/2 : FROM busybox + ---> 769b9341d937 +Step 2/2 : CMD echo Hello world + ---> Using cache + ---> 99cc1ad10469 +Successfully built 99cc1ad10469 +$ echo ".git" > .dockerignore +$ docker build . +Uploading context 6.76 MB +Uploading context +Step 1/2 : FROM busybox + ---> 769b9341d937 +Step 2/2 : CMD echo Hello world + ---> Using cache + ---> 99cc1ad10469 +Successfully built 99cc1ad10469 +``` + +This example shows the use of the `.dockerignore` file to exclude the `.git` +directory from the context. Its effect can be seen in the changed size of the +uploaded context. The builder reference contains detailed information on +[creating a .dockerignore file](../builder.md#dockerignore-file) + +### Tag image (-t) + +```bash +$ docker build -t vieux/apache:2.0 . +``` + +This will build like the previous example, but it will then tag the resulting +image. The repository name will be `vieux/apache` and the tag will be `2.0`. +[Read more about valid tags](tag.md). + +You can apply multiple tags to an image. For example, you can apply the `latest` +tag to a newly built image and add another tag that references a specific +version. +For example, to tag an image both as `whenry/fedora-jboss:latest` and +`whenry/fedora-jboss:v2.1`, use the following: + +```bash +$ docker build -t whenry/fedora-jboss:latest -t whenry/fedora-jboss:v2.1 . +``` +### Specify Dockerfile (-f) + +```bash +$ docker build -f Dockerfile.debug . +``` + +This will use a file called `Dockerfile.debug` for the build instructions +instead of `Dockerfile`. + +```bash +$ docker build -f dockerfiles/Dockerfile.debug -t myapp_debug . +$ docker build -f dockerfiles/Dockerfile.prod -t myapp_prod . +``` + +The above commands will build the current build context (as specified by the +`.`) twice, once using a debug version of a `Dockerfile` and once using a +production version. + +```bash +$ cd /home/me/myapp/some/dir/really/deep +$ docker build -f /home/me/myapp/dockerfiles/debug /home/me/myapp +$ docker build -f ../../../../dockerfiles/debug /home/me/myapp +``` + +These two `docker build` commands do the exact same thing. They both use the +contents of the `debug` file instead of looking for a `Dockerfile` and will use +`/home/me/myapp` as the root of the build context. Note that `debug` is in the +directory structure of the build context, regardless of how you refer to it on +the command line. + +> **Note:** +> `docker build` will return a `no such file or directory` error if the +> file or directory does not exist in the uploaded context. This may +> happen if there is no context, or if you specify a file that is +> elsewhere on the Host system. The context is limited to the current +> directory (and its children) for security reasons, and to ensure +> repeatable builds on remote Docker hosts. This is also the reason why +> `ADD ../file` will not work. + +### Optional parent cgroup (--cgroup-parent) + +When `docker build` is run with the `--cgroup-parent` option the containers +used in the build will be run with the [corresponding `docker run` +flag](../run.md#specifying-custom-cgroups). + +### Set ulimits in container (--ulimit) + +Using the `--ulimit` option with `docker build` will cause each build step's +container to be started using those [`--ulimit` +flag values](./run.md#set-ulimits-in-container-ulimit). + +### Set build-time variables (--build-arg) + +You can use `ENV` instructions in a Dockerfile to define variable +values. These values persist in the built image. However, often +persistence is not what you want. Users want to specify variables differently +depending on which host they build an image on. + +A good example is `http_proxy` or source versions for pulling intermediate +files. The `ARG` instruction lets Dockerfile authors define values that users +can set at build-time using the `--build-arg` flag: + +```bash +$ docker build --build-arg HTTP_PROXY=http://10.20.30.2:1234 . +``` + +This flag allows you to pass the build-time variables that are +accessed like regular environment variables in the `RUN` instruction of the +Dockerfile. Also, these values don't persist in the intermediate or final images +like `ENV` values do. + +Using this flag will not alter the output you see when the `ARG` lines from the +Dockerfile are echoed during the build process. + +For detailed information on using `ARG` and `ENV` instructions, see the +[Dockerfile reference](../builder.md). + +### Optional security options (--security-opt) + +This flag is only supported on a daemon running on Windows, and only supports +the `credentialspec` option. The `credentialspec` must be in the format +`file://spec.txt` or `registry://keyname`. + +### Specify isolation technology for container (--isolation) + +This option is useful in situations where you are running Docker containers on +Windows. The `--isolation=` option sets a container's isolation +technology. On Linux, the only supported is the `default` option which uses +Linux namespaces. On Microsoft Windows, you can specify these values: + + +| Value | Description | +|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `default` | Use the value specified by the Docker daemon's `--exec-opt` . If the `daemon` does not specify an isolation technology, Microsoft Windows uses `process` as its default value. | +| `process` | Namespace isolation only. | +| `hyperv` | Hyper-V hypervisor partition-based isolation. | + +Specifying the `--isolation` flag without a value is the same as setting `--isolation="default"`. + + +### Squash an image's layers (--squash) **Experimental Only** + +Once the image is built, squash the new layers into a new image with a single +new layer. Squashing does not destroy any existing image, rather it creates a new +image with the content of the squashed layers. This effectively makes it look +like all `Dockerfile` commands were created with a single layer. The build +cache is preserved with this method. + +**Note**: using this option means the new image will not be able to take +advantage of layer sharing with other images and may use significantly more +space. + +**Note**: using this option you may see significantly more space used due to +storing two copies of the image, one for the build cache with all the cache +layers in tact, and one for the squashed version. diff --git a/engine/reference/commandline/image_history.md b/engine/reference/commandline/image_history.md index 8a4b7063dc..566a928e62 100644 --- a/engine/reference/commandline/image_history.md +++ b/engine/reference/commandline/image_history.md @@ -13,3 +13,28 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +```bash +$ docker history fedora + +IMAGE CREATED CREATED BY SIZE COMMENT +105182bb5e8b 5 days ago /bin/sh -c #(nop) ADD file:71356d2ad59aa3119d 372.7 MB +73bd853d2ea5 13 days ago /bin/sh -c #(nop) MAINTAINER Lokesh Mandvekar 0 B +511136ea3c5a 10 months ago 0 B Imported from - +``` + +### Display comments in the image history + +The `docker commit` command has a **-m** flag for adding comments to the image. These comments will be displayed in the image history. + +```bash +$ sudo docker history docker:scm + +IMAGE CREATED CREATED BY SIZE COMMENT +2ac9d1098bf1 3 months ago /bin/bash 241.4 MB Added Apache to Fedora base image +88b42ffd1f7c 5 months ago /bin/sh -c #(nop) ADD file:1fd8d7f9f6557cafc7 373.7 MB +c69cab00d6ef 5 months ago /bin/sh -c #(nop) MAINTAINER Lokesh Mandvekar 0 B +511136ea3c5a 19 months ago 0 B Imported from - +``` diff --git a/engine/reference/commandline/image_import.md b/engine/reference/commandline/image_import.md index bbd0abe245..ab4957a1b8 100644 --- a/engine/reference/commandline/image_import.md +++ b/engine/reference/commandline/image_import.md @@ -13,3 +13,39 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +### Import from a remote location + + # docker image import http://example.com/exampleimage.tgz example/imagerepo + +### Import from a local file + +Import to docker via pipe and stdin: + + # cat exampleimage.tgz | docker image import - example/imagelocal + +Import with a commit message. + + # cat exampleimage.tgz | docker image import --message "New image imported from tarball" - exampleimagelocal:new + +Import to a Docker image from a local file. + + # docker image import /path/to/exampleimage.tgz + + +### Import from a local file and tag + +Import to docker via pipe and stdin: + + # cat exampleimageV2.tgz | docker image import - example/imagelocal:V-2.0 + +### Import from a local directory + + # tar -c . | docker image import - exampleimagedir + +### Apply specified Dockerfile instructions while importing the image +This example sets the docker image ENV variable DEBUG to true by default. + + # tar -c . | docker image import -c="ENV DEBUG true" - exampleimagedir diff --git a/engine/reference/commandline/image_load.md b/engine/reference/commandline/image_load.md index d48334568c..f0490bd15b 100644 --- a/engine/reference/commandline/image_load.md +++ b/engine/reference/commandline/image_load.md @@ -13,3 +13,33 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +```bash +$ 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/engine/reference/commandline/image_ls.md b/engine/reference/commandline/image_ls.md index 14bc5947e8..75b6a9be07 100644 --- a/engine/reference/commandline/image_ls.md +++ b/engine/reference/commandline/image_ls.md @@ -13,3 +13,95 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +### Listing the images + +To list the images in a local repository (not the registry) run: + + $ docker image ls + +The list will contain the image repository name, a tag for the image, and an +image ID, when it was created and its virtual size. Columns: REPOSITORY, TAG, +IMAGE ID, CREATED, and SIZE. + +The `docker image ls` command takes an optional `[REPOSITORY[:TAG]]` argument +that restricts the list to images that match the argument. If you specify +`REPOSITORY`but no `TAG`, the `docker image ls` command lists all images in the +given repository. + + $ docker image ls java + +The `[REPOSITORY[:TAG]]` value must be an "exact match". This means that, for example, +`docker image ls jav` does not match the image `java`. + +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 image ls java:8 + +To get a verbose list of images which contains all the intermediate images +used in builds use **-a**: + + $ docker image ls -a + +Previously, the docker image ls command supported the --tree and --dot arguments, +which displayed different visualizations of the image data. Docker core removed +this functionality in the 1.7 version. If you liked this functionality, you can +still find it in the third-party dockviz tool: https://github.com/justone/dockviz. + +### Listing images in a desired format + +When using the --format option, the image command will either output the data +exactly as the template declares or, when using the `table` directive, will +include column headers as well. You can use special characters like `\t` for +inserting tab spacing between columns. + +The following example uses a template without headers and outputs the ID and +Repository entries separated by a colon for all images: + +```bash +{% raw %} +$ docker images --format "{{.ID}}: {{.Repository}}" + +77af4d6b9913: +b6fa739cedf5: committ +78a85c484bad: ipbabble +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: + +```bash +{% raw %} +$ docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}" + +IMAGE ID REPOSITORY TAG +77af4d6b9913 +b6fa739cedf5 committ latest +78a85c484bad ipbabble +30557a29d5ab docker latest +5ed6274db6ce +746b819f315e postgres 9 +746b819f315e postgres 9.3 +746b819f315e postgres 9.3.5 +746b819f315e postgres latest +{% endraw %} +``` + +Valid template placeholders are listed above. + +### Listing only the shortened image IDs + +Listing just the shortened image IDs. This can be useful for some automated +tools. + + $ docker image ls -q diff --git a/engine/reference/commandline/image_pull.md b/engine/reference/commandline/image_pull.md index 3a2cad8f4b..12832e0287 100644 --- a/engine/reference/commandline/image_pull.md +++ b/engine/reference/commandline/image_pull.md @@ -13,3 +13,185 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +### Pull an image from Docker Hub + +To download a particular image, or set of images (i.e., a repository), use +`docker image pull`. If no tag is provided, Docker Engine uses the `:latest` tag as a +default. This command pulls the `debian:latest` image: + + $ docker image pull debian + + Using default tag: latest + latest: Pulling from library/debian + fdd5d7827f33: Pull complete + a3ed95caeb02: Pull complete + Digest: sha256:e7d38b3517548a1c71e41bffe9c8ae6d6d29546ce46bf62159837aad072c90aa + Status: Downloaded newer image for debian:latest + +Docker images can consist of multiple layers. In the example above, the image +consists of two layers; `fdd5d7827f33` and `a3ed95caeb02`. + +Layers can be reused by images. For example, the `debian:jessie` image shares +both layers with `debian:latest`. Pulling the `debian:jessie` image therefore +only pulls its metadata, but not its layers, because all layers are already +present locally: + + $ docker image pull debian:jessie + + jessie: Pulling from library/debian + fdd5d7827f33: Already exists + a3ed95caeb02: Already exists + Digest: sha256:a9c958be96d7d40df920e7041608f2f017af81800ca5ad23e327bc402626b58e + Status: Downloaded newer image for debian:jessie + +To see which images are present locally, use the **docker-images(1)** +command: + + $ docker images + + REPOSITORY TAG IMAGE ID CREATED SIZE + debian jessie f50f9524513f 5 days ago 125.1 MB + debian latest f50f9524513f 5 days ago 125.1 MB + +Docker uses a content-addressable image store, and the image ID is a SHA256 +digest covering the image's configuration and layers. In the example above, +`debian:jessie` and `debian:latest` have the same image ID because they are +actually the *same* image tagged with different names. Because they are the +same image, their layers are stored only once and do not consume extra disk +space. + +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/) +in the online documentation. + + +### 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 image pull` an +image again to make sure you have the most up-to-date version of that image. +For example, `docker image pull ubuntu:14.04` pulls the latest version of the Ubuntu +14.04 image. + +In some cases you don't want images to be updated to newer versions, but prefer +to use a fixed version of an image. Docker enables you to pull an image by its +*digest*. When pulling an image by digest, you specify *exactly* which version +of an image to pull. Doing so, allows you to "pin" an image to that version, +and guarantee that the image you're using is always the same. + +To know the digest of an image, pull the image first. Let's pull the latest +`ubuntu:14.04` image from Docker Hub: + + $ docker image pull ubuntu:14.04 + + 14.04: Pulling from library/ubuntu + 5a132a7e7af1: Pull complete + fd2731e4c50c: Pull complete + 28a2f68d1120: Pull complete + a3ed95caeb02: Pull complete + Digest: sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 + Status: Downloaded newer image for ubuntu:14.04 + +Docker prints the digest of the image after the pull has finished. In the example +above, the digest of the image is: + + sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 + +Docker also prints the digest of an image when *pushing* to a registry. This +may be useful if you want to pin to a version of the image you just pushed. + +A digest takes the place of the tag when pulling an image, for example, to +pull the above image by digest, run the following command: + + $ docker image pull ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 + + sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2: Pulling from library/ubuntu + 5a132a7e7af1: Already exists + fd2731e4c50c: Already exists + 28a2f68d1120: Already exists + a3ed95caeb02: Already exists + Digest: sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 + Status: Downloaded newer image for ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 + +Digest can also be used in the `FROM` of a Dockerfile, for example: + + FROM ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 + MAINTAINER some maintainer + +> **Note**: Using this feature "pins" an image to a specific version in time. +> Docker will therefore not pull updated versions of an image, which may include +> security updates. If you want to pull an updated image, you need to change the +> digest accordingly. + +### Pulling from a different registry + +By default, `docker image pull` pulls images from Docker Hub. It is also possible to +manually specify the path of a registry to pull from. For example, if you have +set up a local registry, you can specify its path to pull from it. A registry +path is similar to a URL, but does not contain a protocol specifier (`https://`). + +The following command pulls the `testing/test-image` image from a local registry +listening on port 5000 (`myregistry.local:5000`): + + $ docker image pull myregistry.local:5000/testing/test-image + +Registry credentials are managed by **docker-login(1)**. + +Docker uses the `https://` protocol to communicate with a registry, unless the +registry is allowed to be accessed over an insecure connection. Refer to the +[insecure registries](https://docs.docker.com/engine/reference/commandline/daemon/#insecure-registries) +section in the online documentation for more information. + + +### Pull a repository with multiple images + +By default, `docker image pull` pulls a *single* image from the registry. A repository +can contain multiple images. To pull all images from a repository, provide the +`-a` (or `--all-tags`) option when using `docker image pull`. + +This command pulls all images from the `fedora` repository: + + $ docker image pull --all-tags fedora + + Pulling repository fedora + ad57ef8d78d7: Download complete + 105182bb5e8b: Download complete + 511136ea3c5a: Download complete + 73bd853d2ea5: Download complete + .... + + Status: Downloaded newer image for fedora + +After the pull has completed use the `docker images` command to see the +images that were pulled. The example below shows all the `fedora` images +that are present locally: + + $ docker images fedora + + REPOSITORY TAG IMAGE ID CREATED SIZE + fedora rawhide ad57ef8d78d7 5 days ago 359.3 MB + fedora 20 105182bb5e8b 5 days ago 372.7 MB + fedora heisenbug 105182bb5e8b 5 days ago 372.7 MB + fedora latest 105182bb5e8b 5 days ago 372.7 MB + + +### Canceling a pull + +Killing the `docker image pull` process, for example by pressing `CTRL-c` while it is +running in a terminal, will terminate the pull operation. + + $ docker image pull fedora + + Using default tag: latest + latest: Pulling from library/fedora + a3ed95caeb02: Pulling fs layer + 236608c7b546: Pulling fs layer + ^C + +> **Note**: Technically, the Engine terminates a pull operation when the +> connection between the Docker Engine daemon and the Docker Engine client +> initiating the pull is lost. If the connection with the Engine daemon is +> lost for other reasons than a manual interaction, the pull is also aborted. diff --git a/engine/reference/commandline/image_push.md b/engine/reference/commandline/image_push.md index b948a186ac..b72e77cafd 100644 --- a/engine/reference/commandline/image_push.md +++ b/engine/reference/commandline/image_push.md @@ -13,3 +13,28 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +### Pushing a new image to a registry + +First save the new image by finding the container ID (using **docker container ls**) +and then committing it to a new image name. Note that only `a-z0-9-_.` are +allowed when naming images: + + $ docker container commit c16378f943fe rhel-httpd + +Now, push the image to the registry using the image ID. In this example the +registry is on host named `registry-host` and listening on port `5000`. To do +this, tag the image with the host name or IP address, and the port of the +registry: + + $ docker image tag rhel-httpd registry-host:5000/myadmin/rhel-httpd + $ docker image push registry-host:5000/myadmin/rhel-httpd + +Check that this worked by running: + + $ docker image ls + +You should see both `rhel-httpd` and `registry-host:5000/myadmin/rhel-httpd` +listed. diff --git a/engine/reference/commandline/image_rm.md b/engine/reference/commandline/image_rm.md index 642a31a279..8879cfb99b 100644 --- a/engine/reference/commandline/image_rm.md +++ b/engine/reference/commandline/image_rm.md @@ -13,3 +13,11 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +### Removing an image + +Here is an example of removing an image: + + $ docker image rm fedora/httpd diff --git a/engine/reference/commandline/image_save.md b/engine/reference/commandline/image_save.md index c1b4d33081..d8dfae1295 100644 --- a/engine/reference/commandline/image_save.md +++ b/engine/reference/commandline/image_save.md @@ -13,3 +13,20 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +Save all fedora repository images to a fedora-all.tar and save the latest +fedora image to a fedora-latest.tar: + + $ docker image save fedora > fedora-all.tar + + $ docker image save --output=fedora-latest.tar fedora:latest + + $ ls -sh fedora-all.tar + + 721M fedora-all.tar + + $ ls -sh fedora-latest.tar + + 367M fedora-latest.tar diff --git a/engine/reference/commandline/image_tag.md b/engine/reference/commandline/image_tag.md index 2b58ab6601..e24fbf0e86 100644 --- a/engine/reference/commandline/image_tag.md +++ b/engine/reference/commandline/image_tag.md @@ -13,3 +13,36 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +### Tagging an image referenced by ID + +To tag a local image with ID "0e5574283393" into the "fedora" repository with +"version1.0": + + docker image tag 0e5574283393 fedora/httpd:version1.0 + +### Tagging an image referenced by Name + +To tag a local image with name "httpd" into the "fedora" repository with +"version1.0": + + docker image 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 + +To tag a local image with name "httpd" and tag "test" into the "fedora" +repository with "version1.0.test": + + docker image tag httpd:test fedora/httpd:version1.0.test + +### Tagging 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 image tag 0e5574283393 myregistryhost:5000/fedora/httpd:version1.0 diff --git a/engine/reference/commandline/inspect.md b/engine/reference/commandline/inspect.md index bf668cedfb..dcd311e62b 100644 --- a/engine/reference/commandline/inspect.md +++ b/engine/reference/commandline/inspect.md @@ -11,3 +11,302 @@ here, you'll need to find the string by searching this repo: https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +Get information about an image when image name conflicts with the container name, +e.g. both image and container are named rhel7: + + $ docker inspect --type=image rhel7 + [ + { + "Id": "fe01a428b9d9de35d29531e9994157978e8c48fa693e1bf1d221dffbbb67b170", + "Parent": "10acc31def5d6f249b548e01e8ffbaccfd61af0240c17315a7ad393d022c5ca2", + .... + } + ] + +### Getting information on a container + +To get information on a container use its ID or instance name: + + $ docker inspect d2cc496561d6 + [{ + "Id": "d2cc496561d6d520cbc0236b4ba88c362c446a7619992123f11c809cded25b47", + "Created": "2015-06-08T16:18:02.505155285Z", + "Path": "bash", + "Args": [], + "State": { + "Running": false, + "Paused": false, + "Restarting": false, + "OOMKilled": false, + "Dead": false, + "Pid": 0, + "ExitCode": 0, + "Error": "", + "StartedAt": "2015-06-08T16:18:03.643865954Z", + "FinishedAt": "2015-06-08T16:57:06.448552862Z" + }, + "Image": "ded7cd95e059788f2586a51c275a4f151653779d6a7f4dad77c2bd34601d94e4", + "NetworkSettings": { + "Bridge": "", + "SandboxID": "6b4851d1903e16dd6a567bd526553a86664361f31036eaaa2f8454d6f4611f6f", + "HairpinMode": false, + "LinkLocalIPv6Address": "", + "LinkLocalIPv6PrefixLen": 0, + "Ports": {}, + "SandboxKey": "/var/run/docker/netns/6b4851d1903e", + "SecondaryIPAddresses": null, + "SecondaryIPv6Addresses": null, + "EndpointID": "7587b82f0dada3656fda26588aee72630c6fab1536d36e394b2bfbcf898c971d", + "Gateway": "172.17.0.1", + "GlobalIPv6Address": "", + "GlobalIPv6PrefixLen": 0, + "IPAddress": "172.17.0.2", + "IPPrefixLen": 16, + "IPv6Gateway": "", + "MacAddress": "02:42:ac:12:00:02", + "Networks": { + "bridge": { + "NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812", + "EndpointID": "7587b82f0dada3656fda26588aee72630c6fab1536d36e394b2bfbcf898c971d", + "Gateway": "172.17.0.1", + "IPAddress": "172.17.0.2", + "IPPrefixLen": 16, + "IPv6Gateway": "", + "GlobalIPv6Address": "", + "GlobalIPv6PrefixLen": 0, + "MacAddress": "02:42:ac:12:00:02" + } + } + + }, + "ResolvConfPath": "/var/lib/docker/containers/d2cc496561d6d520cbc0236b4ba88c362c446a7619992123f11c809cded25b47/resolv.conf", + "HostnamePath": "/var/lib/docker/containers/d2cc496561d6d520cbc0236b4ba88c362c446a7619992123f11c809cded25b47/hostname", + "HostsPath": "/var/lib/docker/containers/d2cc496561d6d520cbc0236b4ba88c362c446a7619992123f11c809cded25b47/hosts", + "LogPath": "/var/lib/docker/containers/d2cc496561d6d520cbc0236b4ba88c362c446a7619992123f11c809cded25b47/d2cc496561d6d520cbc0236b4ba88c362c446a7619992123f11c809cded25b47-json.log", + "Name": "/adoring_wozniak", + "RestartCount": 0, + "Driver": "devicemapper", + "MountLabel": "", + "ProcessLabel": "", + "Mounts": [ + { + "Source": "/data", + "Destination": "/data", + "Mode": "ro,Z", + "RW": false + "Propagation": "" + } + ], + "AppArmorProfile": "", + "ExecIDs": null, + "HostConfig": { + "Binds": null, + "ContainerIDFile": "", + "Memory": 0, + "MemorySwap": 0, + "CpuShares": 0, + "CpuPeriod": 0, + "CpusetCpus": "", + "CpusetMems": "", + "CpuQuota": 0, + "BlkioWeight": 0, + "OomKillDisable": false, + "Privileged": false, + "PortBindings": {}, + "Links": null, + "PublishAllPorts": false, + "Dns": null, + "DnsSearch": null, + "DnsOptions": null, + "ExtraHosts": null, + "VolumesFrom": null, + "Devices": [], + "NetworkMode": "bridge", + "IpcMode": "", + "PidMode": "", + "UTSMode": "", + "CapAdd": null, + "CapDrop": null, + "RestartPolicy": { + "Name": "no", + "MaximumRetryCount": 0 + }, + "SecurityOpt": null, + "ReadonlyRootfs": false, + "Ulimits": null, + "LogConfig": { + "Type": "json-file", + "Config": {} + }, + "CgroupParent": "" + }, + "GraphDriver": { + "Name": "devicemapper", + "Data": { + "DeviceId": "5", + "DeviceName": "docker-253:1-2763198-d2cc496561d6d520cbc0236b4ba88c362c446a7619992123f11c809cded25b47", + "DeviceSize": "171798691840" + } + }, + "Config": { + "Hostname": "d2cc496561d6", + "Domainname": "", + "User": "", + "AttachStdin": true, + "AttachStdout": true, + "AttachStderr": true, + "ExposedPorts": null, + "Tty": true, + "OpenStdin": true, + "StdinOnce": true, + "Env": null, + "Cmd": [ + "bash" + ], + "Image": "fedora", + "Volumes": null, + "VolumeDriver": "", + "WorkingDir": "", + "Entrypoint": null, + "NetworkDisabled": false, + "MacAddress": "", + "OnBuild": null, + "Labels": {}, + "Memory": 0, + "MemorySwap": 0, + "CpuShares": 0, + "Cpuset": "", + "StopSignal": "SIGTERM" + } + } + ] +### Getting the IP address of a container instance + +To get the IP address of a container use: + +```bash +{% raw %} +$ docker inspect \ + --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' \ + d2cc496561d6 + +172.17.0.2 +{% endraw %} +``` + +### Listing all port bindings + +One can loop over arrays and maps in the results to produce simple text +output: + +```bash +{% raw %} +$ docker inspect \ + --format='{{range $p, $conf := .NetworkSettings.Ports}} \ + {{$p}} -> {{(index $conf 0).HostPort}} {{end}}' \ + d2cc496561d6 + + 80/tcp -> 80 +{% endraw %} +``` + +You can get more information about how to write a Go template from: +https://golang.org/pkg/text/template/. + +### Getting size information on a container + +```bash +$ docker inspect -s d2cc496561d6 + +[ +{ +.... +"SizeRw": 0, +"SizeRootFs": 972, +.... +} +] +``` +### Getting information on an image + +Use an image's ID or name (e.g., repository/name[:tag]) to get information +about the image: + +```bash +$ docker inspect ded7cd95e059 + +[{ +"Id": "ded7cd95e059788f2586a51c275a4f151653779d6a7f4dad77c2bd34601d94e4", +"Parent": "48ecf305d2cf7046c1f5f8fcbcd4994403173441d4a7f125b1bb0ceead9de731", +"Comment": "", +"Created": "2015-05-27T16:58:22.937503085Z", +"Container": "76cf7f67d83a7a047454b33007d03e32a8f474ad332c3a03c94537edd22b312b", +"ContainerConfig": { + "Hostname": "76cf7f67d83a", + "Domainname": "", + "User": "", + "AttachStdin": false, + "AttachStdout": false, + "AttachStderr": false, + "ExposedPorts": null, + "Tty": false, + "OpenStdin": false, + "StdinOnce": false, + "Env": null, + "Cmd": [ + "/bin/sh", + "-c", + "#(nop) ADD file:4be46382bcf2b095fcb9fe8334206b584eff60bb3fad8178cbd97697fcb2ea83 in /" + ], + "Image": "48ecf305d2cf7046c1f5f8fcbcd4994403173441d4a7f125b1bb0ceead9de731", + "Volumes": null, + "VolumeDriver": "", + "WorkingDir": "", + "Entrypoint": null, + "NetworkDisabled": false, + "MacAddress": "", + "OnBuild": null, + "Labels": {} +}, +"DockerVersion": "1.6.0", +"Author": "Lokesh Mandvekar \u003clsm5@fedoraproject.org\u003e", +"Config": { + "Hostname": "76cf7f67d83a", + "Domainname": "", + "User": "", + "AttachStdin": false, + "AttachStdout": false, + "AttachStderr": false, + "ExposedPorts": null, + "Tty": false, + "OpenStdin": false, + "StdinOnce": false, + "Env": null, + "Cmd": null, + "Image": "48ecf305d2cf7046c1f5f8fcbcd4994403173441d4a7f125b1bb0ceead9de731", + "Volumes": null, + "VolumeDriver": "", + "WorkingDir": "", + "Entrypoint": null, + "NetworkDisabled": false, + "MacAddress": "", + "OnBuild": null, + "Labels": {} +}, +"Architecture": "amd64", +"Os": "linux", +"Size": 186507296, +"VirtualSize": 186507296, +"GraphDriver": { + "Name": "devicemapper", + "Data": { + "DeviceId": "3", + "DeviceName": "docker-253:1-2763198-ded7cd95e059788f2586a51c275a4f151653779d6a7f4dad77c2bd34601d94e4", + "DeviceSize": "171798691840" + } +} +}] +``` diff --git a/engine/reference/commandline/login.md b/engine/reference/commandline/login.md index 628aa48644..22f9aa4ac0 100644 --- a/engine/reference/commandline/login.md +++ b/engine/reference/commandline/login.md @@ -11,3 +11,11 @@ here, you'll need to find the string by searching this repo: https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +### Login to a registry on your localhost + +```bash +$ docker login localhost:8080 +``` diff --git a/engine/reference/commandline/logout.md b/engine/reference/commandline/logout.md index 6c85bb4688..d0c6828671 100644 --- a/engine/reference/commandline/logout.md +++ b/engine/reference/commandline/logout.md @@ -11,3 +11,11 @@ here, you'll need to find the string by searching this repo: https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +### Log out from a registry on your localhost + +```bash +$ docker logout localhost:8080 +``` diff --git a/engine/reference/commandline/network_connect.md b/engine/reference/commandline/network_connect.md index ac389c151e..2be307c293 100644 --- a/engine/reference/commandline/network_connect.md +++ b/engine/reference/commandline/network_connect.md @@ -11,3 +11,42 @@ here, you'll need to find the string by searching this repo: https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + + +```bash +$ docker network connect multi-host-network container1 +``` + +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 --ip 172.20.88.22 --ip6 2001:db8::8822 busybox +``` +You can pause, restart, and stop containers that are connected to a network. +A container connects to its configured networks when it runs. + +If specified, the container's IP address(es) is reapplied when a stopped +container is restarted. If the IP address is no longer available, the container +fails to start. One way to guarantee that the IP address is available is +to specify an `--ip-range` when creating the network, and choose the static IP +address(es) from outside that range. This ensures that the IP address is not +given to another container while this container is not on the network. + +```bash +$ docker network create --subnet 172.20.0.0/16 --ip-range 172.20.240.0/20 multi-host-network +``` + +```bash +$ docker network connect --ip 172.20.128.2 multi-host-network container2 +``` + +To verify the container is connected, use the `docker network inspect` command. Use `docker network disconnect` to remove a container from the network. + +Once connected in network, containers can communicate using only another +container's IP address 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. + +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. diff --git a/engine/reference/commandline/network_create.md b/engine/reference/commandline/network_create.md index 794fe5d731..8399993f79 100644 --- a/engine/reference/commandline/network_create.md +++ b/engine/reference/commandline/network_create.md @@ -11,3 +11,84 @@ here, you'll need to find the string by searching this repo: https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +```bash +$ docker network create -d overlay my-multihost-network +``` + +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 + +When you start a container use the `--network` flag to connect it to a network. +This adds the `busybox` container to the `mynet` network. + +```bash +$ docker run -itd --network=mynet busybox +``` + +If you want to add a container to a network after the container is already +running use the `docker network connect` subcommand. + +You can connect multiple containers to the same network. Once connected, the +containers can communicate using only another container's IP address 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. + +You can disconnect a container from a network using the `docker network +disconnect` command. + +### Specifying 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 network. +It is purely for ip-addressing purposes. You can override this default and +specify subnetwork values directly using the `--subnet` option. On a +`bridge` network you can only create a single subnet: + +```bash +$ docker network create -d bridge --subnet=192.168.0.0/16 br0 +``` + +Additionally, you also specify the `--gateway` `--ip-range` and `--aux-address` +options. + +```bash +$ docker network create \ + --driver=bridge \ + --subnet=172.28.0.0/16 \ + --ip-range=172.28.5.0/24 \ + --gateway=172.28.5.254 \ + br0 +``` + +If you omit the `--gateway` flag the Engine selects one for you from inside a +preferred pool. For `overlay` networks and for network driver plugins that +support it you can create multiple subnetworks. + +```bash +$ docker network create -d overlay \ + --subnet=192.168.0.0/16 \ + --subnet=192.170.0.0/16 \ + --gateway=192.168.0.100 \ + --gateway=192.170.0.100 \ + --ip-range=192.168.1.0/24 \ + --aux-address="my-router=192.168.1.5" --aux-address="my-switch=192.168.1.6" \ + --aux-address="my-printer=192.170.1.5" --aux-address="my-nas=192.170.1.6" \ + my-multihost-network +``` + +Be sure that your subnetworks do not overlap. If they do, the network create +fails and Engine returns an error. + +#### Network internal mode + +By default, when you connect a container to an `overlay` network, Docker also +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. diff --git a/engine/reference/commandline/network_disconnect.md b/engine/reference/commandline/network_disconnect.md index 39c7b4e898..2de6f02ccc 100644 --- a/engine/reference/commandline/network_disconnect.md +++ b/engine/reference/commandline/network_disconnect.md @@ -11,3 +11,9 @@ here, you'll need to find the string by searching this repo: https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +```bash +$ docker network disconnect multi-host-network container1 +``` diff --git a/engine/reference/commandline/network_inspect.md b/engine/reference/commandline/network_inspect.md index 0a3e2aaf6b..71db125ab8 100644 --- a/engine/reference/commandline/network_inspect.md +++ b/engine/reference/commandline/network_inspect.md @@ -11,3 +11,92 @@ here, you'll need to find the string by searching this repo: https://www.github.com/docker/docker --> {% include cli.md %} + +## Exaples + +```bash +$ sudo docker run -itd --name=container1 busybox +f2870c98fd504370fb86e59f32cd0753b1ac9b69b7d80566ffc7192a82b3ed27 + +$ sudo docker run -itd --name=container2 busybox +bda12f8922785d1f160be70736f26c1e331ab8aaf8ed8d56728508f2e2fd4727 +``` + +The `network inspect` command shows the containers, by id, in its +results. 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. + +```bash +$ sudo docker network inspect bridge +[ + { + "Name": "bridge", + "Id": "b2b1a2cba717161d984383fd68218cf70bbbd17d328496885f7c921333228b0f", + "Scope": "local", + "Driver": "bridge", + "IPAM": { + "Driver": "default", + "Config": [ + { + "Subnet": "172.17.42.1/16", + "Gateway": "172.17.42.1" + } + ] + }, + "Internal": false, + "Containers": { + "bda12f8922785d1f160be70736f26c1e331ab8aaf8ed8d56728508f2e2fd4727": { + "Name": "container2", + "EndpointID": "0aebb8fcd2b282abe1365979536f21ee4ceaf3ed56177c628eae9f706e00e019", + "MacAddress": "02:42:ac:11:00:02", + "IPv4Address": "172.17.0.2/16", + "IPv6Address": "" + }, + "f2870c98fd504370fb86e59f32cd0753b1ac9b69b7d80566ffc7192a82b3ed27": { + "Name": "container1", + "EndpointID": "a00676d9c91a96bbe5bcfb34f705387a33d7cc365bac1a29e4e9728df92d10ad", + "MacAddress": "02:42:ac:11:00:01", + "IPv4Address": "172.17.0.1/16", + "IPv6Address": "" + } + }, + "Options": { + "com.docker.network.bridge.default_bridge": "true", + "com.docker.network.bridge.enable_icc": "true", + "com.docker.network.bridge.enable_ip_masquerade": "true", + "com.docker.network.bridge.host_binding_ipv4": "0.0.0.0", + "com.docker.network.bridge.name": "docker0", + "com.docker.network.driver.mtu": "1500" + } + } +] +``` + +Returns the information about the user-defined network: + +```bash +$ docker network create simple-network +69568e6336d8c96bbf57869030919f7c69524f71183b44d80948bd3927c87f6a +$ docker network inspect simple-network +[ + { + "Name": "simple-network", + "Id": "69568e6336d8c96bbf57869030919f7c69524f71183b44d80948bd3927c87f6a", + "Scope": "local", + "Driver": "bridge", + "IPAM": { + "Driver": "default", + "Config": [ + { + "Subnet": "172.22.0.0/16", + "Gateway": "172.22.0.1" + } + ] + }, + "Containers": {}, + "Options": {} + } +] +``` diff --git a/engine/reference/commandline/network_ls.md b/engine/reference/commandline/network_ls.md index 08ff5222f7..6142c10fba 100644 --- a/engine/reference/commandline/network_ls.md +++ b/engine/reference/commandline/network_ls.md @@ -11,3 +11,160 @@ here, you'll need to find the string by searching this repo: https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +```bash + $ docker network ls + NETWORK ID NAME DRIVER SCOPE + 7fca4eb8c647 bridge bridge local + 9f904ee27bf5 none null local + cf03ee007fb4 host host local + 78b03ee04fc4 multi-host overlay swarm +``` + +Use the `--no-trunc` option to display the full network id: + +```bash +$ docker network ls --no-trunc +NETWORK ID NAME DRIVER +18a2866682b85619a026c81b98a5e375bd33e1b0936a26cc497c283d27bae9b3 none null +c288470c46f6c8949c5f7e5099b5b7947b07eabe8d9a27d79a9cbf111adcbf47 host host +7b369448dccbf865d397c8d2be0cda7cf7edc6b0945f77d2529912ae917a0185 bridge bridge +95e74588f40db048e86320c6526440c504650a1ff3e9f7d60a497c4d2163e5bd foo bridge +63d1ff1f77b07ca51070a8c227e962238358bd310bde1529cf62e6c307ade161 dev bridge +``` + +### 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"`). +Multiple filter flags are combined as an `OR` filter. For example, +`-f type=custom -f type=builtin` returns both `custom` and `builtin` networks. + +The currently supported filters are: + +* driver +* id (network's id) +* label (`label=` or `label==`) +* name (network's name) +* type (custom|builtin) + +#### Driver + +The `driver` filter matches networks based on their driver. + +The following example matches networks with the `bridge` driver: + +```bash +$ docker network ls --filter driver=bridge +NETWORK ID NAME DRIVER +db9db329f835 test1 bridge +f6e212da9dfd test2 bridge +``` + +#### ID + +The `id` filter matches on all or part of a network's ID. + +The following filter matches all networks with an ID containing the +`63d1ff1f77b0...` string. + +```bash +$ docker network ls --filter id=63d1ff1f77b07ca51070a8c227e962238358bd310bde1529cf62e6c307ade161 +NETWORK ID NAME DRIVER +63d1ff1f77b0 dev bridge +``` + +You can also filter for a substring in an ID as this shows: + +```bash +$ docker network ls --filter id=95e74588f40d +NETWORK ID NAME DRIVER +95e74588f40d foo bridge + +$ docker network ls --filter id=95e +NETWORK ID NAME DRIVER +95e74588f40d foo bridge +``` + +#### Label + +The `label` filter matches networks based on the presence of a `label` alone or a `label` and a +value. + +The following filter matches networks with the `usage` label regardless of its value. + +```bash +$ docker network ls -f "label=usage" +NETWORK ID NAME DRIVER +db9db329f835 test1 bridge +f6e212da9dfd test2 bridge +``` + +The following filter matches networks with the `usage` label with the `prod` value. + +```bash +$ docker network ls -f "label=usage=prod" +NETWORK ID NAME DRIVER +f6e212da9dfd test2 bridge +``` + +#### Name + +The `name` filter matches on all or part of a network's name. + +The following filter matches all networks with a name containing the `foobar` string. + +```bash +$ docker network ls --filter name=foobar +NETWORK ID NAME DRIVER +06e7eef0a170 foobar bridge +``` + +You can also filter for a substring in a name as this shows: + +```bash +$ docker network ls --filter name=foo +NETWORK ID NAME DRIVER +95e74588f40d foo bridge +06e7eef0a170 foobar bridge +``` + +#### Type + +The `type` filter supports two values; `builtin` displays predefined networks +(`bridge`, `none`, `host`), whereas `custom` displays user defined networks. + +The following filter matches all user defined networks: + +```bash +$ docker network ls --filter type=custom +NETWORK ID NAME DRIVER +95e74588f40d foo bridge +63d1ff1f77b0 dev bridge +``` + +By having this flag it allows for batch cleanup. For example, use this filter +to delete all user defined networks: + +```bash +$ 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. + +### Format + +Format uses a Go template to print the output. The following variables are +supported: + +* .ID - Network ID +* .Name - Network name +* .Driver - Network driver +* .Scope - Network scope (local, global) +* .IPv6 - Whether IPv6 is enabled on the network or not +* .Internal - Whether the network is internal or not +* .Labels - All labels assigned to the network +* .Label - Value of a specific label for this network. For example `{% raw %}{{.Label "project.version"}}{% endraw %}` diff --git a/engine/reference/commandline/network_rm.md b/engine/reference/commandline/network_rm.md index 0245a9495a..ce789e9a56 100644 --- a/engine/reference/commandline/network_rm.md +++ b/engine/reference/commandline/network_rm.md @@ -11,3 +11,22 @@ here, you'll need to find the string by searching this repo: https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +```bash + $ docker network rm my-network +``` + +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`: + +```bash + $ docker network rm 3695c422697f my-network +``` + +When you specify multiple networks, the command attempts to delete each in turn. +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. diff --git a/engine/reference/commandline/run.md b/engine/reference/commandline/run.md index 71c486399c..603892781e 100644 --- a/engine/reference/commandline/run.md +++ b/engine/reference/commandline/run.md @@ -11,3 +11,587 @@ here, you'll need to find the string by searching this repo: https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +### 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 + +This example runs a container named `test` using the `debian:latest` +image. The `-it` instructs Docker to allocate a pseudo-TTY connected to +the container's stdin; creating an interactive `bash` shell in the container. +In the example, the `bash` shell is quit by entering +`exit 13`. This exit code is passed on to the caller of +`docker run`, and is recorded in the `test` container's metadata. + +### Capture container ID (--cidfile) + + $ 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. +If the file exists already, Docker will return an error. Docker will close this +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 + +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 + +The `--privileged` flag gives *all* capabilities to the container, and it also +lifts all the limitations enforced by the `device` cgroup controller. In other +words, the container can then do almost everything that the host can do. This +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 + +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 + +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`, +`windowsfilter` and `zfs` graph drivers. +For the `devicemapper`, `btrfs`, `windowsfilter` and `zfs` graph drivers, +user cannot pass a size less than the Default BaseFS Size. +For the `overlay2` storage driver, the size option is only available if the +backing fs is `xfs` and mounted with the `pquota` mount option. +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 + +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 + +The `-v` flag mounts the current working directory into the container. The `-w` +lets the command being executed inside the current working directory, by +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 + +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 + +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 + +By bind-mounting the docker unix socket and statically linked docker +binary (refer to [get the linux binary]( +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. + + 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 + +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 ... + +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 + +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 + +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 + +This sets simple (non-array) environmental variables in the container. For +illustration all three +flags are shown here. Where `-e`, `--env` take an environment variable and +value, or if no `=` is provided, then that variable's current value, set via +`export`, is passed through (i.e. `$MYVAR1` from the host is set to `$MYVAR1` +in the container). When no `=` is provided and that variable is not defined +in the client's environment then that variable will be removed from the +container's list of environment variables. All three flags, `-e`, `--env` and +`--env-file` can be repeated. + +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 + +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 +lines need only be prefixed with `#` + +An example of a file passed with `--env-file` + +```none +$ 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 + +# 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 +``` + +### 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 + +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`). + +The `key=value` must be unique to avoid overwriting the label value. If you +specify labels with identical keys but different values, each subsequent value +overwrites the previous. Docker uses the last `key=value` you supply. + +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 + +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" + + # this is a comment + com.example.label2=another\ label + com.example.label3 + +You can load multiple label-files by supplying multiple `--label-file` flags. + +For additional information on working with labels, see [*Labels - custom +metadata in Docker*](https://docs.docker.com/engine/userguide/labels-custom-metadata/) in the Docker User +Guide. + +### Connect a container to a network (--network) + +When you start a container use the `--network` flag to connect it to a network. +This adds the `busybox` container to the `my-net` network. + +```bash +$ docker run -itd --network=my-net busybox +``` + +You can also choose the IP addresses for the container with `--ip` and `--ip6` +flags when you start the container on a user-defined network. + +```bash +$ docker run -itd --network=my-net --ip=10.10.9.75 busybox +``` + +If you want to add a running container to a network use the `docker network connect` subcommand. + +You can connect multiple containers to the same network. Once connected, the +containers can communicate easily need only another container's IP address +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. + +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 + +The `--volumes-from` flag mounts all the defined volumes from the referenced +containers. Containers can be specified by repetitions of the `--volumes-from` +argument. The container ID may be optionally suffixed with `:ro` or `:rw` to +mount the volumes in read-only or read-write mode, respectively. By default, +the volumes are mounted in the same mode (read write or read only) as +the reference container. + +Labeling systems like SELinux require that proper labels are placed on volume +content mounted into a container. Without a label, the security system might +prevent the processes running inside the container from using the content. By +default, Docker does not change the labels set by the OS. + +To change the label in the container context, you can add either of two suffixes +`:z` or `:Z` to the volume mount. These suffixes tell Docker to relabel file +objects on the shared volumes. The `z` option tells Docker that two containers +share the volume content. As a result, Docker labels the content with a shared +content label. Shared volume labels allow all containers to read/write content. +The `Z` option tells Docker to label the content with a private unshared label. +Only the current container can use a private volume. + +### Attach to STDIN/STDOUT/STDERR (-a) + +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 - + +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 + +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 + +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 +logs could be retrieved using `docker logs`. This is +useful if you need to pipe a file or something else into a container and +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 + +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 +device or audio device can be added to an otherwise unprivileged container +(without the `--privileged` flag) and have the application directly access it. + +By default, the container will be able to `read`, `write` and `mknod` these devices. +This can be overridden using a third `:rwm` set of options to each `--device` +flag: + + + $ 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:rw --rm -it ubuntu fdisk /dev/xvdc + + 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 + +> **Note:** +> `--device` cannot be safely used with ephemeral devices. Block devices +> that may be removed should not be added to untrusted containers with +> `--device`. + +### Restart policies (--restart) + +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. +
+ + $ 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. + +More detailed information on restart policies can be found in the +[Restart Policies (--restart)](../run.md#restart-policies-restart) +section of the Docker run reference page. + +### Add entries to container hosts file (--add-host) + +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 + +Sometimes you need to connect to the Docker host from within your +container. To enable this, pass the Docker host's IP address to +the container using the `--add-host` flag. To find the host's address, +use the `ip addr show` command. + +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 + +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` +for the bridge device). + +### Set ulimits in container (--ulimit) + +Since setting `ulimit` settings in a container requires extra privileges not +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 + +> **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` + +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. + +#### For `nproc` usage + +Be careful setting `nproc` with the `ulimit` flag as `nproc` is designed by Linux to set the +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 + +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 +the three processes quota set for the `daemon` user. + +### Stop container with signal (--stop-signal) + +The `--stop-signal` flag sets the system call signal that will be sent to the container to exit. +This signal can be a valid unsigned number that matches a position in the kernel's syscall table, for instance 9, +or a signal name in the format SIGNAME, for instance SIGKILL. + +### Optional security options (--security-opt) + +On Windows, this flag can be used to specify the `credentialspec` option. +The `credentialspec` must be in the format `file://spec.txt` or `registry://keyname`. + +### Stop container with timeout (--stop-timeout) + +The `--stop-timeout` flag sets the timeout (in seconds) that a pre-defined (see `--stop-signal`) system call +signal that will be sent to the container to exit. After timeout elapses the container will be killed with SIGKILL. + +### Specify isolation technology for container (--isolation) + +This option is useful in situations where you are running Docker containers on +Windows. The `--isolation ` option sets a container's isolation technology. +On Linux, the only supported is the `default` option which uses +Linux namespaces. These two commands are equivalent on Linux: + +```bash +$ docker run -d busybox top +$ docker run -d --isolation default busybox top +``` + +On Windows, `--isolation` can take one of these values: + + +| Value | Description | +|-----------|--------------------------------------------------------------------------------------------| +| `default` | Use the value specified by the Docker daemon's `--exec-opt` or system default (see below). | +| `process` | Shared-kernel namespace isolation (not supported on Windows client operating systems). | +| `hyperv` | Hyper-V hypervisor partition-based isolation. | + +The default isolation on Windows server operating systems is `process`. The default (and only supported) +isolation on Windows client operating systems is `hyperv`. An attempt to start a container on a client +operating system with `--isolation process` will fail. + +On Windows server, assuming the default configuration, these commands are equivalent +and result in `process` isolation: + +```PowerShell +PS C:\> docker run -d microsoft/nanoserver powershell echo process +PS C:\> docker run -d --isolation default microsoft/nanoserver powershell echo process +PS C:\> docker run -d --isolation process microsoft/nanoserver powershell echo process +``` + +If you have set the `--exec-opt isolation=hyperv` option on the Docker `daemon`, or +are running against a Windows client-based daemon, these commands are equivalent and +result in `hyperv` isolation: + +```PowerShell +PS C:\> docker run -d microsoft/nanoserver powershell echo hyperv +PS C:\> docker run -d --isolation default microsoft/nanoserver powershell echo hyperv +PS C:\> docker run -d --isolation hyperv microsoft/nanoserver powershell echo hyperv +``` + +### Configure namespaced kernel parameters (sysctls) at runtime + +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 + + +> **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 +> evolves we expect to see more sysctls become namespaced. + +#### Currently supported sysctls + + `IPC Namespace`: + + 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.* + + If you use the `--network=host` option using these sysctls will not be allowed. diff --git a/engine/reference/commandline/search.md b/engine/reference/commandline/search.md index 6f3b6aeda0..cabb489ec1 100644 --- a/engine/reference/commandline/search.md +++ b/engine/reference/commandline/search.md @@ -11,3 +11,27 @@ here, you'll need to find the string by searching this repo: https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +### Search Docker Hub for ranked images + +Search a registry for the term 'fedora' and only display those images +ranked 3 or higher: + + $ docker search --filter=stars=3 fedora + NAME DESCRIPTION STARS OFFICIAL AUTOMATED + mattdm/fedora A basic Fedora image corresponding roughly... 50 + fedora (Semi) Official Fedora base image. 38 + mattdm/fedora-small A small Fedora image on which to build. Co... 8 + goldmann/wildfly A WildFly application server running on a ... 3 [OK] + +### Search Docker Hub for automated images + +Search Docker Hub for the term 'fedora' and only display automated images +ranked 1 or higher: + + $ docker search --filter=is-automated=true --filter=stars=1 fedora + NAME DESCRIPTION STARS OFFICIAL AUTOMATED + goldmann/wildfly A WildFly application server running on a ... 3 [OK] + tutum/fedora-20 Fedora 20 image with SSH access. For the r... 1 [OK] diff --git a/engine/reference/commandline/secret_create.md b/engine/reference/commandline/secret_create.md index d50a69fc74..a39cc58122 100644 --- a/engine/reference/commandline/secret_create.md +++ b/engine/reference/commandline/secret_create.md @@ -11,3 +11,57 @@ here, you'll need to find the string by searching this repo: https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +### Create a secret + +```bash +$ echo | docker secret create my_secret - +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 +``` + +### Create a secret with a file + +```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 +``` + +### Create a secret with labels + +```bash +$ docker secret create --label env=dev --label rev=20161102 my_secret ./secret.json +jtn7g6aukl5ky7nr9gvwafoxh + +$ docker secret inspect my_secret +[ + { + "ID": "jtn7g6aukl5ky7nr9gvwafoxh", + "Version": { + "Index": 541 + }, + "CreatedAt": "2016-11-03T20:54:12.924766548Z", + "UpdatedAt": "2016-11-03T20:54:12.924766548Z", + "Spec": { + "Name": "my_secret", + "Labels": { + "env": "dev", + "rev": "20161102" + }, + "Data": null + }, + "Digest": "sha256:4212a44b14e94154359569333d3fc6a80f6b9959dfdaff26412f4b2796b1f387", + "SecretSize": 1679 + } +] + +``` diff --git a/engine/reference/commandline/secret_inspect.md b/engine/reference/commandline/secret_inspect.md index 8ec9c9f7e7..88f1e8aeea 100644 --- a/engine/reference/commandline/secret_inspect.md +++ b/engine/reference/commandline/secret_inspect.md @@ -11,3 +11,47 @@ here, you'll need to find the string by searching this repo: https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +### Inspecting a secret by name or ID + +You can inspect a secret, either by its *name*, or *ID* + +For example, given the following secret: + +```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 +``` + +```bash +$ docker secret inspect secret.json +[ + { + "ID": "mhv17xfe3gh6xc4rij5orpfds", + "Version": { + "Index": 1198 + }, + "CreatedAt": "2016-10-27T23:25:43.909181089Z", + "UpdatedAt": "2016-10-27T23:25:43.909181089Z", + "Spec": { + "Name": "secret.json" + } + } +] +``` + +### Formatting secret output + +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 %} +$ docker secret inspect --format='{{.CreatedAt}}' mhv17xfe3gh6xc4rij5orpfds +2016-10-27 23:25:43.909181089 +0000 UTC +{% endraw %} +``` diff --git a/engine/reference/commandline/secret_ls.md b/engine/reference/commandline/secret_ls.md index fd7d2575a9..872e7a47c3 100644 --- a/engine/reference/commandline/secret_ls.md +++ b/engine/reference/commandline/secret_ls.md @@ -11,3 +11,11 @@ here, you'll need to find the string by searching this repo: https://www.github.com/docker/docker --> {% include cli.md %} + +## 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 +``` diff --git a/engine/reference/commandline/service_create.md b/engine/reference/commandline/service_create.md index 0d54336099..af7dc79f03 100644 --- a/engine/reference/commandline/service_create.md +++ b/engine/reference/commandline/service_create.md @@ -11,3 +11,508 @@ here, you'll need to find the string by searching this repo: https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +### Create a service + +```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 +``` + +### Create a service with 5 replica tasks (--replicas) + +Use the `--replicas` flag to set the number of replica tasks for a replicated +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 +``` + +The above command sets the *desired* number of tasks for the service. Even +though the command returns immediately, actual scaling of the service may take +some time. The `REPLICAS` column shows both the *actual* and *desired* number +of replica tasks for the service. + +In the following example the desired state is `5` replicas, but the current +number of `RUNNING` tasks is `3`: + +```bash +$ docker service ls + +ID NAME MODE REPLICAS IMAGE +4cdgfyky7ozw redis replicated 3/5 redis:3.0.7 +``` + +Once all the tasks are created and `RUNNING`, the actual number of tasks is +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). + +Create a service specifying a secret: + +```bash +$ docker service create --name redis --secret secret.json redis:3.0.6 + +4cdgfyky7ozwh3htjfw0d12qv +``` + +Create a service specifying the secret, target, user/group ID and mode: + +```bash +$ docker service create --name redis \ + --secret source=ssh-key,target=ssh \ + --secret src=app-key,target=app,uid=1000,gid=1001,mode=0400 \ + redis:3.0.6 + +4cdgfyky7ozwh3htjfw0d12qv +``` + +Secrets are located in `/run/secrets` in the container. If no target is +specified, the name of the secret will be used as the in memory file in the +container. If a target is specified, that will be the filename. In the +example above, two files will be created: `/run/secrets/ssh` and +`/run/secrets/app` for each of the secret targets specified. + +### Create a service with a rolling update policy + +```bash +$ docker service create \ + --replicas 10 \ + --name redis \ + --update-delay 10s \ + --update-parallelism 2 \ + redis:3.0.6 +``` + +When you run a [service update](service_update.md), the scheduler updates a +maximum of 2 tasks at a time, with `10s` between updates. For more information, +refer to the [rolling updates +tutorial](https://docs.docker.com/engine/swarm/swarm-tutorial/rolling-update/). + +### Set environment variables (-e, --env) + +This sets environmental variables for all tasks in a service. For example: + +```bash +$ docker service create \ + --name redis_2 \ + --replicas 5 \ + --env MYVAR=foo \ + redis:3.0.6 +``` + +### Create a docker service with specific hostname (--hostname) + +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 +service with two labels: + +```bash +$ docker service create \ + --name redis_2 \ + --label com.example.foo="bar" + --label bar=baz \ + redis:3.0.6 +``` + +For more information about labels, refer to [apply custom +metadata](https://docs.docker.com/engine/userguide/labels-custom-metadata/). + +### Add bind-mounts or volumes + +Docker supports two different kinds of mounts, which allow containers to read to +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. + +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 +read-write. For example, a container might share its host's DNS information by +means of a bind-mount of the host's `/etc/resolv.conf` or a container might +write logs to its host's `/var/log/myContainerLogs` directory. If you use +bind-mounts and your host and containers have different notions of permissions, +access controls, or other such details, you will run into portability issues. + +A **named volume** is a mechanism for decoupling persistent data needed by your +container from the image used to create the container and from the host machine. +Named volumes are created and managed by Docker, and a named volume persists +even when no container is currently using it. Data in named volumes can be +shared between a container and the host machine, as well as between multiple +containers. Docker uses a _volume driver_ to create, manage, and mount volumes. +You can back up or restore volumes using Docker commands. + +A **tmpfs** mounts a tmpfs inside a container for volatile data. + +Consider a situation where your image starts a lightweight web server. You could +use that image as a base image, copy in your website's HTML files, and package +that into another image. Each time your website changed, you'd need to update +the new image and redeploy all of the containers serving your website. A better +solution is to store the website in a named volume which is attached to each of +your web server containers when they start. To update the website, you just +update the named volume. + +For more information about named volumes, see +[Data Volumes](https://docs.docker.com/engine/tutorials/dockervolumes/). + +The following table describes options which apply to both bind-mounts and named +volumes in a service: + +| Option | Required | Description +|:-----------------------------------|:--------------------------|:----------------------------------------------------------------------------------------- +| `type` | | The type of mount, can be one of `volume`, `bind`, or `tmpfs`. Defaults to `volume` if no type is specified. `volume` mounts a [managed volume](volume_create.md) into the container. `bind` bind-mounts a directory or file from the host into the container. `tmpfs`: mount a tmpfs in the container. +| `src` or `source`vvvv | for `type=bind` only | `type=volume`: `src` is an optional way to specify the name of the volume (for example, `src=my-volume`). If the named volume does not exist, it is automatically created. If no `src` is specified, the volume is assigned a random name which is guaranteed to be unique on the host, but may not be unique cluster-wide. A randomly-named volume has the same lifecycle as its container and is destroyed when the *container* is destroyed (which is upon `service update`, or when scaling or re-balancing the service). `type=bind`: `src` is required, and specifies an absolute path to the file or directory to bind-mount (for example, `src=/path/on/host/`). An error is produced if the file or directory does not exist. `type=tmpfs`: `src` is not supported. +| `dst` or `destination` or `target` | yes | Mount path inside the container, for example `/some/path/in/container/`. If the path does not exist in the container's filesystem, the Engine creates a directory at the specified location before mounting the volume or bind-mount. +| *`readonly` or `ro` | | The Engine mounts binds and volumes `read-write` unless `readonly` option is given when mounting the bind or volume. When `true` or `1` or no value the bind or volume is mounted read-only. When `false` or `0` the bind or volume is mounted read-write. + +#### Bind Propagation + +Bind propagation refers to whether or not mounts created within a given +bind-mount or named volume can be propagated to replicas of that mount. Consider +a mount point `/mnt`, which is also mounted on `/tmp`. The propation settings +control whether a mount on `/tmp/a` would also be available on `/mnt/a`. Each +propagation setting has a recursive counterpoint. In the case of recursion, +consider that `/tmp/a` is also mounted as `/foo`. The propagation settings +control whether `/mnt/a` and/or `/tmp/a` would exist. + +The `bind-propagation` option defaults to `rprivate` for both bind-mounts and +volume mounts, and is only configurable for bind-mounts. In other words, named +volumes do not support bind propagation. + +- **`shared`**: Sub-mounts of the original mount are exposed to replica mounts, + and sub-mounts of replica mounts are also propagated to the + original mount. +- **`slave`**: similar to a shared mount, but only in one direction. If the + original mount exposes a sub-mount, the replica mount can see it. + However, if the replica mount exposes a sub-mount, the original + mount cannot see it. +- **`private`**: The mount is private. Sub-mounts within it are not exposed to + replica mounts, and sub-mounts of replica mounts are not + exposed to the original mount. +- **`rshared`**: The same as shared, but the propagation also extends to and from + mount points nested within any of the original or replica mount + points. +- **`rslave`**: The same as `slave`, but the propagation also extends to and from + mount points nested within any of the original or replica mount + points. +- **`rprivate`**: The default. The same as `private`, meaning that no mount points + anywhere within the original or replica mount points propagate + in either direction. + +For more information about bind propagation, see the +[Linux kernel documentation for shared subtree](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt). + +#### Options for Named Volumes +The following options can only be used for named volumes (`type=volume`); + +| Option | Description +|:----------------------|:-------------------------------------------------------------------------------------------------------------------- +| **volume-driver** | Name of the volume-driver plugin to use for the volume. Defaults to ``"local"``, to use the local volume driver to create the volume if the volume does not exist. +| **volume-label** | One or more custom metadata ("labels") to apply to the volume upon creation. For example, `volume-label=mylabel=hello-world,my-other-label=hello-mars`. For more information about labels, refer to [apply custom metadata](https://docs.docker.com/engine/userguide/labels-custom-metadata/). +| **volume-nocopy** | By default, if you attach an empty volume to a container, and files or directories already existed at the mount-path in the container (`dst`), the Engine copies those files and directories into the volume, allowing the host to access them. Set `volume-nocopy` to disables copying files from the container's filesystem to the volume and mount the empty volume. A value is optional. `true` or `1` is the default if you do not provide a value and disables copying. `false` or `0` enables copying. +| **volume-opt** | Options specific to a given volume driver, which will be passed to the driver when creating the volume. Options are provided as a comma-separated list of key/value pairs, for example, `volume-opt=some-option=some-value,some-other-option=some-other-value`. For available options for a given driver, refer to that driver's documentation. + +#### Options for tmpfs +The following options can only be used for tmpfs mounts (`type=tmpfs`); + +| Option | Description +|:----------------------|:-------------------------------------------------------------------------------------------------------------------- +| **tmpfs-size** | Size of the tmpfs mount in bytes. Unlimited by default in Linux. +| **tmpfs-mode** | File mode of the tmpfs in octal. (e.g. `"700"` or `"0700"`.) Defaults to ``"1777"`` in Linux. + +#### Differences between "--mount" and "--volume" + +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. + +- The `--mount` flag allows you to specify custom metadata ("labels") for a volume, + 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. + +- The `--mount` flag does not allow you to relabel a volume with `Z` or `z` flags, + which are used for `selinux` labeling. + +#### Create a service using a named volume + +The following example creates a service that uses a named volume: + +```bash +$ docker service create \ + --name my-service \ + --replicas 3 \ + --mount type=volume,source=my-volume,destination=/path/in/container,volume-label="color=red",volume-label="shape=round" \ + nginx:alpine +``` + +For each replica of the service, the engine requests a volume named "my-volume" +from the default ("local") volume driver where the task is deployed. If the +volume does not exist, the engine creates a new volume and applies the "color" +and "shape" labels. + +When the task is started, the volume is mounted on `/path/in/container/` inside +the container. + +Be aware that the default ("local") volume is a locally scoped volume driver. +This means that depending on where a task is deployed, either that task gets a +*new* volume named "my-volume", or shares the same "my-volume" with other tasks +of the same service. Multiple containers writing to a single shared volume can +cause data corruption if the software running inside the container is not +designed to handle concurrent processes writing to the same location. Also take +into account that containers can be re-scheduled by the Swarm orchestrator and +be deployed on a different node. + +#### Create a service that uses an anonymous volume + +The following command creates a service with three replicas with an anonymous +volume on `/path/in/container`: + +```bash +$ docker service create \ + --name my-service \ + --replicas 3 \ + --mount type=volume,destination=/path/in/container \ + nginx:alpine +``` + +In this example, no name (`source`) is specified for the volume, so a new volume +is created for each task. This guarantees that each task gets its own volume, +and volumes are not shared between tasks. Anonymous volumes are removed after +the task using them is complete. + +#### Create a service that uses a bind-mounted host directory + +The following example bind-mounts a host directory at `/path/in/container` in +the containers backing the service: + +```bash +$ docker service create \ + --name my-service \ + --mount type=bind,source=/path/on/host,destination=/path/in/container \ + nginx:alpine +``` + +### Set service mode (--mode) + +The service mode determines whether this is a _replicated_ service or a _global_ +service. A replicated service runs as many tasks as specified, while a global +service runs on each active node in the swarm. + +The following command creates a global service: + +```bash +$ docker service create \ + --name redis_2 \ + --mode global \ + redis:3.0.6 +``` + +### Specify service constraints (--constraint) + +You can limit the set of nodes where a task can be scheduled by defining +constraint expressions. Multiple constraints find nodes that satisfy every +expression (AND match). Constraints can match node or Docker Engine labels as +follows: + +| node attribute | matches | example | +|:----------------|:--------------------------|:------------------------------------------------| +| node.id | node ID | `node.id == 2ivku8v2gvtg4` | +| node.hostname | node hostname | `node.hostname != node-2` | +| node.role | node role: manager | `node.role == manager` | +| node.labels | user defined node labels | `node.labels.security == high` | +| engine.labels | Docker Engine's labels | `engine.labels.operatingsystem == ubuntu 14.04` | + +`engine.labels` apply to Docker Engine labels like operating system, +drivers, etc. Swarm administrators add `node.labels` for operational purposes by +using the [`docker node update`](node_update.md) command. + +For example, the following limits tasks for the redis service to nodes where the +node type label equals queue: + +```bash +$ docker service create \ + --name redis_2 \ + --constraint 'node.labels.type == queue' \ + redis:3.0.6 +``` + +### Attach a service to an existing network (--network) + +You can use overlay networks to connect one or more services within the swarm. + +First, create an overlay network on a manager node the docker network create +command: + +```bash +$ docker network create \ + --driver overlay \ + my-network + +etjpu59cykrptrgw0z0hk5snf +``` + +After you create an overlay network in swarm mode, all manager nodes have +access to the network. + +When you create a service and pass the --network flag to attach the service to +the overlay network: + +```bash +$ docker service create \ + --replicas 3 \ + --network my-network \ + --name my-web \ + nginx + +716thylsndqma81j6kkkb5aus +``` + +The swarm extends my-network to each node running the service. + +Containers on the same network can access each other using +[service discovery](https://docs.docker.com/engine/swarm/networking/#use-swarm-mode-service-discovery). + +### Publish service ports externally to the swarm (-p, --publish) + +You can publish service ports to make them available externally to the swarm +using the `--publish` flag: + +```bash +$ docker service create \ + --publish : \ + nginx +``` + +For example: + +```bash +$ docker service create \ + --name my_web \ + --replicas 3 \ + --publish 8080:80 \ + nginx +``` + +When you publish a service port, the swarm routing mesh makes the service +accessible at the target port on every node regardless if there is a task for +the service running on the node. For more information refer to +[Use swarm mode routing mesh](https://docs.docker.com/engine/swarm/ingress/). + +### Publish a port for TCP only or UDP only + +By default, when you publish a port, it is a TCP port. You can +specifically publish a UDP port instead of or in addition to a TCP port. When +you publish both TCP and UDP ports, Docker 1.12.2 and earlier require you to +add the suffix `/tcp` for TCP ports. Otherwise it is optional. + +#### TCP only + +The following two commands are equivalent. + +```bash +$ docker service create --name dns-cache -p 53:53 dns-cache + +$ docker service create --name dns-cache -p 53:53/tcp dns-cache +``` + +#### TCP and UDP + +```bash +$ docker service create --name dns-cache -p 53:53/tcp -p 53:53/udp dns-cache +``` + +#### UDP only + +```bash +$ docker service create --name dns-cache -p 53:53/udp dns-cache +``` + +### Create services using templates + +You can use templates for some flags of `service create`, using the syntax +provided by the Go's [text/template](http://golange.org/pkg/text/template/) package. + +The supported flags are the following : + +- `--hostname` +- `--mount` +- `--env` + +Valid placeholders for the Go template are listed below: + +Placeholder | Description +----------------- | -------------------------------------------- +`.Service.ID` | Service ID +`.Service.Name` | Service name +`.Service.Labels` | Service labels +`.Node.ID` | Node ID +`.Task.ID` | Task ID +`.Task.Name` | Task name +`.Task.Slot` | Task slot + +#### Template example + +In this example, we are going to set the template of the created containers based on the +service's name and the node's ID where it sits. + +```bash +{% raw %} +$ docker service create \ + --name hosttempl \ + --hostname="{{.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="{{.Config.Hostname}}" \ + hosttempl.1.wo41w8hg8qanxwjwsg4kxpprj + +x3ti0erg11rjpg64m75kej2mz-hosttempl +{% endraw %} +``` diff --git a/engine/reference/commandline/service_inspect.md b/engine/reference/commandline/service_inspect.md index aef31b7a9c..ce40a9e629 100644 --- a/engine/reference/commandline/service_inspect.md +++ b/engine/reference/commandline/service_inspect.md @@ -11,3 +11,119 @@ here, you'll need to find the string by searching this repo: https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +### Inspecting a service by name or ID + +You can inspect a service, either by its *name*, or *ID* + +For example, given the following service; + +```bash +$ docker service ls +ID NAME MODE REPLICAS IMAGE +dmu1ept4cxcf redis replicated 3/3 redis:3.0.6 +``` + +Both `docker service inspect redis`, and `docker service inspect dmu1ept4cxcf` +produce the same result: + +```bash +$ docker service inspect redis +[ + { + "ID": "dmu1ept4cxcfe8k8lhtux3ro3", + "Version": { + "Index": 12 + }, + "CreatedAt": "2016-06-17T18:44:02.558012087Z", + "UpdatedAt": "2016-06-17T18:44:02.558012087Z", + "Spec": { + "Name": "redis", + "TaskTemplate": { + "ContainerSpec": { + "Image": "redis:3.0.6" + }, + "Resources": { + "Limits": {}, + "Reservations": {} + }, + "RestartPolicy": { + "Condition": "any", + "MaxAttempts": 0 + }, + "Placement": {} + }, + "Mode": { + "Replicated": { + "Replicas": 1 + } + }, + "UpdateConfig": {}, + "EndpointSpec": { + "Mode": "vip" + } + }, + "Endpoint": { + "Spec": {} + } + } +] +``` + +```bash +$ docker service inspect dmu1ept4cxcf +[ + { + "ID": "dmu1ept4cxcfe8k8lhtux3ro3", + "Version": { + "Index": 12 + }, + ... + } +] +``` + +### Inspect a service using pretty-print + +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: + - org.example.projectname=demo-app +Service Mode: REPLICATED + Replicas: 5 +Placement: +UpdateConfig: + Parallelism: 0 +ContainerSpec: + Image: nginx:alpine +Resources: +Endpoint Mode: vip +Ports: + Name = + Protocol = tcp + TargetPort = 443 + PublishedPort = 4443 +``` + +You can also use `--format pretty` for the same effect. + + +### Finding 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 %} +$ docker service inspect --format='{{.Spec.Mode.Replicated.Replicas}}' redis +10 +{% endraw %} +``` diff --git a/engine/reference/commandline/service_ps.md b/engine/reference/commandline/service_ps.md index 818e653024..39cb85920a 100644 --- a/engine/reference/commandline/service_ps.md +++ b/engine/reference/commandline/service_ps.md @@ -13,3 +13,120 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +### Listing the tasks that are part of a service + +The following command shows all the tasks that are part of the `redis` service: + +```bash +$ docker service ps redis + +ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS +0qihejybwf1x redis.1 redis:3.0.5 manager1 Running Running 8 seconds +bk658fpbex0d redis.2 redis:3.0.5 worker2 Running Running 9 seconds +5ls5s5fldaqg redis.3 redis:3.0.5 worker1 Running Running 9 seconds +8ryt076polmc redis.4 redis:3.0.5 worker1 Running Running 9 seconds +1x0v8yomsncd redis.5 redis:3.0.5 manager1 Running Running 8 seconds +71v7je3el7rr redis.6 redis:3.0.5 worker2 Running Running 9 seconds +4l3zm9b7tfr7 redis.7 redis:3.0.5 worker2 Running Running 9 seconds +9tfpyixiy2i7 redis.8 redis:3.0.5 worker1 Running Running 9 seconds +3w1wu13yupln redis.9 redis:3.0.5 manager1 Running Running 8 seconds +8eaxrb2fqpbn redis.10 redis:3.0.5 manager1 Running Running 8 seconds +``` + +In addition to _running_ tasks, the output also shows the task history. For +example, after updating the service to use the `redis:3.0.6` image, the output +may look like this: + +```bash +$ docker service ps redis + +ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS +50qe8lfnxaxk redis.1 redis:3.0.6 manager1 Running Running 6 seconds ago +ky2re9oz86r9 \_ redis.1 redis:3.0.5 manager1 Shutdown Shutdown 8 seconds ago +3s46te2nzl4i redis.2 redis:3.0.6 worker2 Running Running less than a second ago +nvjljf7rmor4 \_ redis.2 redis:3.0.6 worker2 Shutdown Rejected 23 seconds ago "No such image: redis@sha256:6…" +vtiuz2fpc0yb \_ redis.2 redis:3.0.5 worker2 Shutdown Shutdown 1 second ago +jnarweeha8x4 redis.3 redis:3.0.6 worker1 Running Running 3 seconds ago +vs448yca2nz4 \_ redis.3 redis:3.0.5 worker1 Shutdown Shutdown 4 seconds ago +jf1i992619ir redis.4 redis:3.0.6 worker1 Running Running 10 seconds ago +blkttv7zs8ee \_ redis.4 redis:3.0.5 worker1 Shutdown Shutdown 11 seconds ago +``` + +The number of items in the task history is determined by the +`--task-history-limit` option that was set when initializing the swarm. You can +change the task history retention limit using the +[`docker swarm update`](swarm_update.md) command. + +When deploying a service, docker resolves the digest for the service's +image, and pins the service to that digest. The digest is not shown by +default, but is printed if `--no-trunc` is used. The `--no-trunc` option +also shows the non-truncated task ID, and error-messages, as can be seen below; + +```bash +$ docker service ps --no-trunc redis + +ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS +50qe8lfnxaxksi9w2a704wkp7 redis.1 redis:3.0.6@sha256:6a692a76c2081888b589e26e6ec835743119fe453d67ecf03df7de5b73d69842 manager1 Running Running 5 minutes ago +ky2re9oz86r9556i2szb8a8af \_ redis.1 redis:3.0.5@sha256:f8829e00d95672c48c60f468329d6693c4bdd28d1f057e755f8ba8b40008682e worker2 Shutdown Shutdown 5 minutes ago +bk658fpbex0d57cqcwoe3jthu redis.2 redis:3.0.6@sha256:6a692a76c2081888b589e26e6ec835743119fe453d67ecf03df7de5b73d69842 worker2 Running Running 5 seconds +nvjljf7rmor4htv7l8rwcx7i7 \_ redis.2 redis:3.0.6@sha256:6a692a76c2081888b589e26e6ec835743119fe453d67ecf03df7de5b73d69842 worker2 Shutdown Rejected 5 minutes ago "No such image: redis@sha256:6a692a76c2081888b589e26e6ec835743119fe453d67ecf03df7de5b73d69842" +``` + +## 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"`). +Multiple filter flags are combined as an `OR` filter. For example, +`-f name=redis.1 -f name=redis.7` returns both `redis.1` and `redis.7` tasks. + +The currently supported filters are: + +* [id](#id) +* [name](#name) +* [node](#node) +* [desired-state](#desired-state) + + +#### ID + +The `id` filter matches on all or a prefix of a task's ID. + +```bash +$ docker service ps -f "id=8" redis + +ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS +8ryt076polmc redis.4 redis:3.0.6 worker1 Running Running 9 seconds +8eaxrb2fqpbn redis.10 redis:3.0.6 manager1 Running Running 8 seconds +``` + +#### Name + +The `name` filter matches on task names. + +```bash +$ docker service ps -f "name=redis.1" redis +ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS +qihejybwf1x5 redis.1 redis:3.0.6 manager1 Running Running 8 seconds +``` + + +#### Node + +The `node` filter matches on a node name or a node ID. + +```bash +$ docker service ps -f "node=manager1" redis +ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS +0qihejybwf1x redis.1 redis:3.0.6 manager1 Running Running 8 seconds +1x0v8yomsncd redis.5 redis:3.0.6 manager1 Running Running 8 seconds +3w1wu13yupln redis.9 redis:3.0.6 manager1 Running Running 8 seconds +8eaxrb2fqpbn redis.10 redis:3.0.6 manager1 Running Running 8 seconds +``` + + +#### desired-state + +The `desired-state` filter can take the values `running`, `shutdown`, and `accepted`. diff --git a/engine/reference/commandline/service_scale.md b/engine/reference/commandline/service_scale.md index c57e7236f9..133e6f595c 100644 --- a/engine/reference/commandline/service_scale.md +++ b/engine/reference/commandline/service_scale.md @@ -13,3 +13,64 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +### Scale a service + +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 +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. + +```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. + +``` +$ docker service create --mode global --name backend backend:latest +b4g08uwuairexjub6ome6usqh +$ docker service scale backend=10 +backend: scale can only be used with replicated mode +``` + +Directly afterwards, run `docker service ls`, to see the actual number of +replicas. + +```bash +$ docker service ls --filter name=frontend + +ID NAME MODE REPLICAS IMAGE +3pr5mlvu3fh9 frontend replicated 15/50 nginx:alpine +``` + +You can also scale a service using the [`docker service update`](service_update.md) +command. The following commands are equivalent: + +```bash +$ docker service scale frontend=50 +$ docker service update --replicas=50 frontend +``` + +### Scale multiple services + +The `docker service scale` command allows you to set the desired number of +tasks for multiple services at once. The following example scales both the +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 +``` diff --git a/engine/reference/commandline/service_update.md b/engine/reference/commandline/service_update.md index 39a0dede99..1e0b545eeb 100644 --- a/engine/reference/commandline/service_update.md +++ b/engine/reference/commandline/service_update.md @@ -13,3 +13,83 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +### Update a service + +```bash +$ docker service update --limit-cpu 2 redis +``` + +### Perform a rolling restart with no parameter changes + +```bash +$ docker service update --force --update-parallelism 1 --update-delay 30s redis +``` + +In this example, the `--force` flag causes the service's tasks to be shut down +and replaced with new ones even though none of the other parameters would +normally cause that to happen. The `--update-parallelism 1` setting ensures +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 + +Use the `--mount-add` or `--mount-rm` options add or remove a service's bind-mounts +or volumes. + +The following example creates a service which mounts the `test-data` volume to +`/somewhere`. The next step updates the service to also mount the `other-volume` +volume to `/somewhere-else`volume, The last step unmounts the `/somewhere` mount +point, effectively removing the `test-data` volume. Each command returns the +service name. + +- The `--mount-add` flag takes the same parameters as the `--mount` flag on + `service create`. Refer to the [volumes and + bind-mounts](service_create.md#volumes-and-bind-mounts-mount) section in the + `service create` reference for details. + +- The `--mount-rm` flag takes the `target` path of the mount. + +```bash +$ docker service create \ + --name=myservice \ + --mount \ + type=volume,source=test-data,target=/somewhere \ + nginx:alpine \ + myservice + +myservice + +$ docker service update \ + --mount-add \ + type=volume,source=other-volume,target=/somewhere-else \ + myservice + +myservice + +$ docker service update --mount-rm /somewhere myservice + +myservice +``` + +### Adding and removing secrets + +Use the `--secret-add` or `--secret-rm` options add or remove a service's +secrets. + +The following example adds a secret named `ssh-2` and removes `ssh-1`: + +```bash +$ docker service update \ + --secret-add source=ssh-2,target=ssh-2 \ + --secret-rm ssh-1 \ + myservice +``` + +### Update services using templates + +Some flags of `service update` support the use of templating. +See [`service create`](./service_create.md#templating) for the reference. diff --git a/engine/reference/commandline/system_events.md b/engine/reference/commandline/system_events.md index 1d43a8c2e9..6ba3b245dd 100644 --- a/engine/reference/commandline/system_events.md +++ b/engine/reference/commandline/system_events.md @@ -13,3 +13,109 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +### Listening for Docker events + +After running docker events a container 786d698004576 is started and stopped +(The container name has been shortened in the output below): + + $ docker events + + 2015-01-28T20:21:31.000000000-08:00 59211849bc10: (from whenry/testimage:latest) start + 2015-01-28T20:21:31.000000000-08:00 59211849bc10: (from whenry/testimage:latest) die + 2015-01-28T20:21:32.000000000-08:00 59211849bc10: (from whenry/testimage:latest) stop + +### Listening for events since a given date +Again the output container IDs have been shortened for the purposes of this document: + + $ docker events --since '2015-01-28' + + 2015-01-28T20:25:38.000000000-08:00 c21f6c22ba27: (from whenry/testimage:latest) create + 2015-01-28T20:25:38.000000000-08:00 c21f6c22ba27: (from whenry/testimage:latest) start + 2015-01-28T20:25:39.000000000-08:00 c21f6c22ba27: (from whenry/testimage:latest) create + 2015-01-28T20:25:39.000000000-08:00 c21f6c22ba27: (from whenry/testimage:latest) start + 2015-01-28T20:25:40.000000000-08:00 c21f6c22ba27: (from whenry/testimage:latest) die + 2015-01-28T20:25:42.000000000-08:00 c21f6c22ba27: (from whenry/testimage:latest) stop + 2015-01-28T20:25:45.000000000-08:00 c21f6c22ba27: (from whenry/testimage:latest) start + 2015-01-28T20:25:45.000000000-08:00 c21f6c22ba27: (from whenry/testimage:latest) die + 2015-01-28T20:25:46.000000000-08:00 c21f6c22ba27: (from whenry/testimage:latest) stop + +The following example outputs all events that were generated in the last 3 minutes, +relative to the current time on the client machine: + + # docker events --since '3m' + 2015-05-12T11:51:30.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) die + 2015-05-12T15:52:12.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) stop + 2015-05-12T15:53:45.999999999Z07:00 7805c1d35632: (from redis:2.8) die + 2015-05-12T15:54:03.999999999Z07:00 7805c1d35632: (from redis:2.8) stop + +If you do not provide the --since option, the command returns only new and/or +live events. + +### Format + +If a format (`--format`) is specified, the given template will be executed +instead of the default format. Go's **text/template** package describes all the +details of the format. + + {% 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 %} + +If a format is set to `{% raw %}{{json .}}{% endraw %}`, the events are streamed as valid JSON +Lines. For information about JSON Lines, please refer to http://jsonlines.org/ . + + {% 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 %} + +### Filters + + $ docker events --filter 'event=stop' + 2014-05-10T17:42:14.999999999Z07:00 container stop 4386fb97867d (image=ubuntu-1:14.04) + 2014-09-03T17:42:14.999999999Z07:00 container stop 7805c1d35632 (image=redis:2.8) + + $ docker events --filter 'image=ubuntu-1:14.04' + 2014-05-10T17:42:14.999999999Z07:00 container start 4386fb97867d (image=ubuntu-1:14.04) + 2014-05-10T17:42:14.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) + + $ docker events --filter 'container=7805c1d35632' + 2014-05-10T17:42:14.999999999Z07:00 container die 7805c1d35632 (image=redis:2.8) + 2014-09-03T15:49:29.999999999Z07:00 container stop 7805c1d35632 (image= redis:2.8) + + $ docker events --filter 'container=7805c1d35632' --filter 'container=4386fb97867d' + 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 (image=redis:2.8) + 2014-09-03T15:49:29.999999999Z07:00 container stop 7805c1d35632 (image=redis:2.8) + + $ docker events --filter 'container=7805c1d35632' --filter 'event=stop' + 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) + + $ docker events --filter 'type=plugin' (experimental) + 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) diff --git a/engine/reference/commandline/system_info.md b/engine/reference/commandline/system_info.md index b23d898b45..ff7fbbc14e 100644 --- a/engine/reference/commandline/system_info.md +++ b/engine/reference/commandline/system_info.md @@ -13,3 +13,152 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +### Display Docker system information + +Here is a sample output for a daemon running on Ubuntu, using the overlay2 +storage driver: + + $ 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 + + + +The global `-D` option tells all `docker` commands to output debug information. + +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: + + $ docker info + Containers: 14 + Running: 3 + Paused: 1 + Stopped: 10 + Untagged 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 + +You can also specify the output format: + + {% raw %} + $ docker info --format '{{json .}}' + + {"ID":"I54V:OLXT:HVMM:TPKO:JPHQ:CQCD:JNLC:O3BZ:4ZVJ:43XJ:PFHZ:6N2S","Containers":14, ...} + {% endraw %} diff --git a/engine/reference/commandline/version.md b/engine/reference/commandline/version.md index 992d4b6362..70aa20027e 100644 --- a/engine/reference/commandline/version.md +++ b/engine/reference/commandline/version.md @@ -13,3 +13,50 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +### Display Docker version information + +The default output: + +```bash +$ 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 + + 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 +``` + +Get server version: + +```bash +{% raw %} +$ docker version --format '{{.Server.Version}}' + + 1.8.0 +{% endraw %} +``` + +Dump raw data: + +To view all available fields, you can use the format `{% raw %}{{json .}}{% endraw %}`. + +```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/engine/reference/commandline/volume_create.md b/engine/reference/commandline/volume_create.md index 1fac4851dd..5fb2ee19c4 100644 --- a/engine/reference/commandline/volume_create.md +++ b/engine/reference/commandline/volume_create.md @@ -13,3 +13,37 @@ https://www.github.com/docker/docker --> {% include cli.md %} + +## Examples + +$ docker volume create hello +hello +$ docker run -d -v hello:/world busybox ls /world + +The mount is created inside the container's `/src` directory. Docker doesn't +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. + +### Driver specific options + +Some volume drivers may take options to customize the volume creation. Use the +`-o` or `--opt` flags to pass driver options: + +$ docker volume create --driver fake --opt tardis=blue --opt timey=wimey + +These options are passed directly to the volume driver. Options for 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: + +$ docker volume create --driver local --opt type=tmpfs --opt device=tmpfs --opt o=size=100m,uid=1000 + +Another example: + +$ docker volume create --driver local --opt type=btrfs --opt device=/dev/sda2