Merge pull request #20294 from moxiegirl/cp-02122016-docs
Cp 02122016 docs
diff --git a/docs/Dockerfile b/docs/Dockerfile
index 2f29b21..3690d15 100644
--- a/docs/Dockerfile
+++ b/docs/Dockerfile
@@ -5,8 +5,9 @@
RUN svn checkout https://github.com/docker/swarm/trunk/docs /docs/content/swarm
RUN svn checkout https://github.com/docker/machine/trunk/docs /docs/content/machine
RUN svn checkout https://github.com/docker/distribution/trunk/docs /docs/content/registry
-RUN svn checkout https://github.com/kitematic/kitematic/trunk/docs /docs/content/kitematic
-RUN svn checkout https://github.com/docker/tutorials/trunk/docs /docs/content/
+RUN svn checkout https://github.com/docker/notary/trunk/docs /docs/content/notary
+RUN svn checkout https://github.com/docker/kitematic/trunk/docs /docs/content/kitematic
+RUN svn checkout https://github.com/docker/toolbox/trunk/docs /docs/content/toolbox
RUN svn checkout https://github.com/docker/opensource/trunk/docs /docs/content/opensource
ENV PROJECT=engine
diff --git a/docs/extend/plugins.md b/docs/extend/plugins.md
index 8aa0603..ea02c9a 100644
--- a/docs/extend/plugins.md
+++ b/docs/extend/plugins.md
@@ -53,6 +53,10 @@
another volume plugin that provides multi-host volumes management for Docker
using GlusterFS.
+* The [Horcrux Volume Plugin](https://github.com/muthu-r/horcrux) allows on-demand,
+ version controlled access to your data. Horcrux is an open-source plugin,
+ written in Go, and supports SCP, [Minio](https://www.minio.io) and Amazon S3.
+
* The [IPFS Volume Plugin](http://github.com/vdemeester/docker-volume-ipfs)
is an open source volume plugin that allows using an
[ipfs](https://ipfs.io/) filesystem as a volume.
diff --git a/docs/installation/cloud/cloud-ex-aws.md b/docs/installation/cloud/cloud-ex-aws.md
index 3163865..0484f24 100644
--- a/docs/installation/cloud/cloud-ex-aws.md
+++ b/docs/installation/cloud/cloud-ex-aws.md
@@ -1,6 +1,6 @@
<!--[metadata]>
+++
-title = "Example: Manual install on a cloud provider"
+title = "Example: Manual install on cloud provider"
description = "Example of a manual install of Docker Engine on a cloud provider, using Amazon Web Services (AWS) EC2. Shows how to create an EC2 instance, and install Docker Engine on it."
keywords = ["cloud, docker, machine, documentation, installation, AWS, EC2"]
[menu.main]
@@ -8,7 +8,7 @@
+++
<![end-metadata]-->
-# Example: Manual install on a cloud provider
+# Example: Manual install on cloud provider
You can install Docker Engine directly to servers you have on cloud providers. This example shows how to create an <a href="https://aws.amazon.com/" target="_blank"> Amazon Web Services (AWS)</a> EC2 instance, and install Docker Engine on it.
@@ -197,8 +197,12 @@
## Where to go next
-* Would you like a quicker way to do Docker cloud installs? See [Digital Ocean Example: Use Docker Machine to provision Docker on cloud hosts](cloud-ex-aws.md).
+_Looking for a quicker way to do Docker cloud installs and provision multiple hosts?_ You can use [Docker Machine](https://docs.docker.com/machine/overview/) to provision hosts.
-* To learn more about options for installing Docker Engine on cloud providers, see [Understand cloud install options and choose one](cloud.md).
+ * [Use Docker Machine to provision hosts on cloud providers](https://docs.docker.com/machine/get-started-cloud/)
-* To get started with Docker, see <a href="https://docs.docker.com/engine/userguide/" target="_blank"> Docker User Guide </a>.
+ * [Docker Machine driver reference](https://docs.docker.com/machine/drivers/)
+
+* [Install Docker Engine](../index.md)
+
+* [Docker User Guide](../../userguide/intro.md)
diff --git a/docs/installation/cloud/cloud-ex-machine-ocean.md b/docs/installation/cloud/cloud-ex-machine-ocean.md
index 2164f4b..ac00a84 100644
--- a/docs/installation/cloud/cloud-ex-machine-ocean.md
+++ b/docs/installation/cloud/cloud-ex-machine-ocean.md
@@ -14,7 +14,7 @@
You'll need to install and run Docker Machine, and create an account with the cloud provider.
-Then you provide account verification, security credentials, and configuration options for the providers as flags to `docker-machine create`. The flags are unique for each cloud-specific driver. For instance, to pass a Digital Ocean access token you use the `--digitalocean-access-token` flag.
+Then you provide account verification, security credentials, and configuration options for the providers as flags to `docker-machine create`. The flags are unique for each cloud-specific driver. For instance, to pass a Digital Ocean access token, you use the `--digitalocean-access-token` flag.
As an example, let's take a look at how to create a Dockerized <a href="https://digitalocean.com" target="_blank">Digital Ocean</a> _Droplet_ (cloud server).
@@ -44,7 +44,7 @@
This is the personal access token you'll use in the next step to create your cloud server.
-### Step 3. Start Docker Machine
+### Step 3. Install Docker Machine
1. If you have not done so already, install Docker Machine on your local host.
@@ -57,30 +57,6 @@
2. At a command terminal, use `docker-machine ls` to get a list of Docker Machines and their status.
$ docker-machine ls
- NAME ACTIVE DRIVER STATE URL SWARM
- default - virtualbox Stopped
-
-3. If Machine is stopped, start it.
-
- $ docker-machine start default
- (default) OUT | Starting VM...
- Started machines may have new IP addresses. You may need to re-run the `docker-machine env` command.
-
-4. Set environment variables to connect your shell to the local VM.
-
- $ docker-machine env default
- export DOCKER_TLS_VERIFY="1"
- export DOCKER_HOST="tcp://xxx.xxx.xx.xxx:xxxx"
- export DOCKER_CERT_PATH="/Users/londoncalling/.docker/machine/machines/default"
- export DOCKER_MACHINE_NAME="default"
- # Run this command to configure your shell:
- # eval "$(docker-machine env default)"
-
- eval "$(docker-machine env default)"
-
-5. Re-run `docker-machine ls` to check that it's now running.
-
- $ docker-machine ls
NAME ACTIVE DRIVER STATE URL SWARM
default * virtualbox Running tcp:////xxx.xxx.xx.xxx:xxxx
@@ -92,28 +68,15 @@
Hello from Docker.
This message shows that your installation appears to be working correctly.
+ ...
- To generate this message, Docker took the following steps:
- 1. The Docker client contacted the Docker daemon.
- 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
- 3. The Docker daemon created a new container from that image which runs the executable that produces the output you are currently reading.
- 4. The Docker daemon streamed that output to the Docker client, which sent it to your terminal.
-
- To try something more ambitious, you can run an Ubuntu container with:
- $ docker run -it ubuntu bash
-
- Share images, automate workflows, and more with a free Docker Hub account: https://hub.docker.com
-
- For more examples and ideas, visit:
- https://docs.docker.com/userguide/
-
-### Step 4. Use Docker Machine to Create the Droplet
+### Step 4. Use Machine to Create the Droplet
1. Run `docker-machine create` with the `digitalocean` driver and pass your key to the `--digitalocean-access-token` flag, along with a name for the new cloud server.
For this example, we'll call our new Droplet "docker-sandbox".
- $ docker-machine create --driver digitalocean --digitalocean-access-token 455275108641c7716462d6f35d08b76b246b6b6151a816cf75de63c5ef918872 docker-sandbox
+ $ docker-machine create --driver digitalocean --digitalocean-access-token xxxxx docker-sandbox
Running pre-create checks...
Creating machine...
(docker-sandbox) OUT | Creating SSH key...
@@ -163,45 +126,52 @@
default - virtualbox Running tcp://192.168.99.100:2376
docker-sandbox * digitalocean Running tcp://45.55.222.72:2376
-6. Log in to the Droplet with the `docker-machine ssh` command.
+6. Run some `docker-machine` commands to inspect the remote host. For example, `docker-machine ip <machine>` gets the host IP adddress and `docker-machine inspect <machine>` lists all the details.
- $ docker-machine ssh docker-sandbox
- Welcome to Ubuntu 14.04.3 LTS (GNU/Linux 3.13.0-71-generic x86_64)
+ $ docker-machine ip docker-sandbox
+ 104.131.43.236
- * Documentation: https://help.ubuntu.com/
+ $ docker-machine inspect docker-sandbox
+ {
+ "ConfigVersion": 3,
+ "Driver": {
+ "IPAddress": "104.131.43.236",
+ "MachineName": "docker-sandbox",
+ "SSHUser": "root",
+ "SSHPort": 22,
+ "SSHKeyPath": "/Users/samanthastevens/.docker/machine/machines/docker-sandbox/id_rsa",
+ "StorePath": "/Users/samanthastevens/.docker/machine",
+ "SwarmMaster": false,
+ "SwarmHost": "tcp://0.0.0.0:3376",
+ "SwarmDiscovery": "",
+ ...
- System information as of Mon Dec 21 21:38:53 EST 2015
+7. Verify Docker Engine is installed correctly by running `docker` commands.
- System load: 0.77 Processes: 70
- Usage of /: 11.4% of 19.56GB Users logged in: 0
- Memory usage: 15% IP address for eth0: 45.55.139.48
- Swap usage: 0% IP address for docker0: 172.17.0.1
+ Start with something basic like `docker run hello-world`, or for a more interesting test, run a Dockerized webserver on your new remote machine.
- Graph this data and manage this system at:
- https://landscape.canonical.com/
+ In this example, the `-p` option is used to expose port 80 from the `nginx` container and make it accessible on port `8000` of the `docker-sandbox` host.
-7. Verify Docker Engine is installed correctly by running `docker run hello-world`.
+ $ docker run -d -p 8000:80 --name webserver kitematic/hello-world-nginx
+ Unable to find image 'kitematic/hello-world-nginx:latest' locally
+ latest: Pulling from kitematic/hello-world-nginx
+ a285d7f063ea: Pull complete
+ 2d7baf27389b: Pull complete
+ ...
+ Digest: sha256:ec0ca6dcb034916784c988b4f2432716e2e92b995ac606e080c7a54b52b87066
+ Status: Downloaded newer image for kitematic/hello-world-nginx:latest
+ 942dfb4a0eaae75bf26c9785ade4ff47ceb2ec2a152be82b9d7960e8b5777e65
- ubuntu@ip-172-31-0-151:~$ sudo docker run hello-world
- Unable to find image 'hello-world:latest' locally
- latest: Pulling from library/hello-world
- b901d36b6f2f: Pull complete
- 0a6ba66e537a: Pull complete
- Digest: sha256:8be990ef2aeb16dbcb9271ddfe2610fa6658d13f6dfb8bc72074cc1ca36966a7
- Status: Downloaded newer image for hello-world:latest
+ In a web browser, go to `http://<host_ip>:8000` to bring up the webserver home page. You got the `<host_ip>` from the output of the `docker-machine ip <machine>` command you ran in a previous step. Use the port you exposed in the `docker run` command.
- Hello from Docker.
- This message shows that your installation appears to be working correctly.
- . . .
-
- You can type keyboard command Control-D or `exit` to log out of the remote server.
+ 
#### Understand the defaults and options on the create command
For convenience, `docker-machine` will use sensible defaults for choosing settings such as the image that the server is based on, but you override the defaults using the respective flags (e.g. `--digitalocean-image`). This is useful if, for example, you want to create a cloud server with a lot of memory and CPUs (by default `docker-machine` creates a small server). For a full list of the flags/settings available and their defaults, see the output of `docker-machine create -h` at the command line. See also <a href="https://docs.docker.com/machine/drivers/os-base/" target="_blank">Driver options and operating system defaults</a> and information about the <a href="https://docs.docker.com/machine/reference/create/" target="_blank">create</a> command in the Docker Machine documentation.
-### Step 5. Use Docker Machine to remove the Droplet
+### Step 5. Use Machine to remove the Droplet
To remove a host and all of its containers and images, first stop the machine, then use `docker-machine rm`:
@@ -220,8 +190,12 @@
## Where to go next
-* To learn more about options for installing Docker Engine on cloud providers, see [Understand cloud install options and choose one](cloud.md).
+* [Docker Machine driver reference](https://docs.docker.com/machine/drivers/)
-* To learn more about using Docker Machine to provision cloud hosts, see <a href="https://docs.docker.com/machine/get-started-cloud/" target="_blank">Using Docker Machine with a cloud provider</a>.
+* [Docker Machine Overview](https://docs.docker.com/machine/overview/)
-* To get started with Docker, see <a href="https://docs.docker.com/engine/userguide/" target="_blank"> Docker User Guide</a>.
+* [Use Docker Machine to provision hosts on cloud providers](https://docs.docker.com/machine/get-started-cloud/)
+
+* [Install Docker Engine](../../installation/index.md)
+
+* [Docker User Guide](../../userguide/intro.md)
diff --git a/docs/installation/cloud/index.md b/docs/installation/cloud/index.md
index 96589c4..c7a83d3 100644
--- a/docs/installation/cloud/index.md
+++ b/docs/installation/cloud/index.md
@@ -8,7 +8,7 @@
"/engine/installation/rackspace/",
"/engine/installation/joyent/"
]
-title = "In the cloud"
+title = "On cloud providers"
description = "Cloud Installations"
keywords = ["Docker install "]
[menu.main]
@@ -20,6 +20,6 @@
# Install Engine in the cloud
-* [Understand cloud install options and choose one](cloud.md)
-* [Example: Use Docker Machine to provision cloud hosts](cloud-ex-machine-ocean.md)
+* [Understand cloud install options and choose one](overview.md)
+* [Example: Use Machine to provision cloud hosts](cloud-ex-machine-ocean.md)
* [Example: Manual install on a cloud provider](cloud-ex-aws.md)
diff --git a/docs/installation/cloud/cloud.md b/docs/installation/cloud/overview.md
similarity index 72%
rename from docs/installation/cloud/cloud.md
rename to docs/installation/cloud/overview.md
index d5ba411..e8b3bb7 100644
--- a/docs/installation/cloud/cloud.md
+++ b/docs/installation/cloud/overview.md
@@ -1,5 +1,8 @@
<!--[metadata]>
+++
+aliases = [
+ "/engine/installation/cloud/cloud/",
+]
title = "Choose how to install"
description = "Installation instructions for Docker on cloud."
keywords = ["cloud, docker, machine, documentation, installation"]
@@ -9,7 +12,7 @@
+++
<![end-metadata]-->
-# Understand cloud install options and choose one
+# Choose how to install
You can install Docker Engine on any cloud platform that runs an operating system (OS) that Docker supports. This includes many flavors and versions of Linux, along with Mac and Windows.
@@ -26,11 +29,11 @@
2. Decide which OS you want to run on the cloud host.
-3. Understand the Docker prerequisites and install process for the chosen OS. See [Install Docker Engine](index.md) for a list of supported systems and links to the install guides.
+3. Understand the Docker prerequisites and install process for the chosen OS. See [Install Docker Engine](../index.md) for a list of supported systems and links to the install guides.
4. Create a host with a Docker supported OS, and install Docker per the instructions for that OS.
-[Example: Manual install on a cloud provider](cloud-ex-aws.md) shows how to create an <a href="https://aws.amazon.com/" target="_blank"> Amazon Web Services (AWS)</a> EC2 instance, and install Docker Engine on it.
+[Example (AWS): Manual install on a cloud provider](cloud-ex-aws.md) shows how to create an <a href="https://aws.amazon.com/" target="_blank"> Amazon Web Services (AWS)</a> EC2 instance, and install Docker Engine on it.
## Use Docker Machine to provision cloud hosts
@@ -41,13 +44,13 @@
To do this, you use the `docker-machine create` command with the driver for the cloud provider, and provider-specific flags for account verification, security credentials, and other configuration details.
-[Example: Use Docker Machine to provision cloud hosts](cloud-ex-machine-ocean.md) walks you through the steps to set up Docker Machine and provision a Dockerized host on [Digital Ocean](https://www.digitalocean.com/).
+[Example: Use Docker Machine to provision cloud hosts](cloud-ex-machine-ocean.md) walks you through the steps to set up Docker Machine and provision a Dockerized host on <a href="https://www.digitalocean.com/" target="_blank">Digital Ocean</a>).
## Where to go next
* [Example: Manual install on a cloud provider](cloud-ex-aws.md) (AWS EC2)
* [Example: Use Docker Machine to provision cloud hosts](cloud-ex-machine-ocean.md) (Digital Ocean)
-* [Using Docker Machine with a cloud provider](https://docs.docker.com/machine/get-started-cloud/)
+* For supported platforms, see [Install Docker Engine](../index.md).
-* <a href="https://docs.docker.com/engine/userguide/" target="_blank"> Docker User Guide </a> (after your install is complete, get started using Docker)
+* To get started with Docker post-install, see [Docker User Guide](../../userguide/intro.md).
diff --git a/docs/installation/images/nginx-webserver.png b/docs/installation/images/nginx-webserver.png
new file mode 100644
index 0000000..941fdaa
--- /dev/null
+++ b/docs/installation/images/nginx-webserver.png
Binary files differ
diff --git a/docs/installation/index.md b/docs/installation/index.md
index 54d85c1..f4c530a 100644
--- a/docs/installation/index.md
+++ b/docs/installation/index.md
@@ -30,7 +30,7 @@
If your linux distribution is not listed above, don't give up yet. To try out Docker on a distribution that is not listed above, go here: [Installation from binaries](binaries.md).
## On Cloud
-* [Choose how to Install](cloud/cloud.md)
+* [Choose how to Install](cloud/overview.md)
* [Example: Manual install on a cloud provider](cloud/cloud-ex-aws.md)
* [Example: Use Docker Machine to provision cloud hosts](cloud/cloud-ex-machine-ocean.md)
diff --git a/docs/installation/mac.md b/docs/installation/mac.md
index 1df35ff..89b69d8 100644
--- a/docs/installation/mac.md
+++ b/docs/installation/mac.md
@@ -387,7 +387,7 @@
## Upgrade Docker Toolbox
-To upgrade Docker Toolbox, download an re-run [the Docker Toolbox
+To upgrade Docker Toolbox, download and re-run [the Docker Toolbox
installer](https://docker.com/toolbox/).
diff --git a/docs/installation/windows.md b/docs/installation/windows.md
index a743061..099bd78 100644
--- a/docs/installation/windows.md
+++ b/docs/installation/windows.md
@@ -324,7 +324,7 @@
## Upgrade Docker Toolbox
-To upgrade Docker Toolbox, download an re-run [the Docker Toolbox
+To upgrade Docker Toolbox, download and re-run [the Docker Toolbox
installer](https://www.docker.com/toolbox).
## Container port redirection
diff --git a/docs/reference/api/docker_remote_api.md b/docs/reference/api/docker_remote_api.md
index a4b6e72..af39cc6 100644
--- a/docs/reference/api/docker_remote_api.md
+++ b/docs/reference/api/docker_remote_api.md
@@ -24,9 +24,20 @@
`docker` exists on your system, `docker` applies ownership of the socket to the
group.
-The current version of the API is v1.22 which means calling `/info` is the same
-as calling `/v1.22/info`. To call an older version of the API use
-`/v1.21/info`.
+To connect to the Docker daemon with cURL you need to use cURL 7.40 or
+later, as these versions have the `--unix-socket` flag available. To
+run `curl` against the deamon on the default socket, use the
+following:
+
+ curl --unix-socket /var/run/docker.sock http://containers/json
+
+If you have bound the Docker daemon to a different socket path or TCP
+port, you would reference that in your cURL rather than the
+default.
+
+The current version of the API is v1.23 which means calling `/info` is the same
+as calling `/v1.23/info`. To call an older version of the API use
+`/v1.22/info`.
Use the table below to find the API version for a Docker version:
@@ -93,7 +104,7 @@
Running `docker rmi` emits an **untag** event when removing an image name. The `rmi` command may also emit **delete** events when images are deleted by ID directly or by deleting the last tag referring to the image.
-> **Acknowledgement**: This diagram and the accompanying text were used with the permission of Matt Good and Gilder Labs. See Matt's original blog post [Docker Events Explained](http://gliderlabs.com/blog/2015/04/14/docker-events-explained/).
+> **Acknowledgement**: This diagram and the accompanying text were used with the permission of Matt Good and Gilder Labs. See Matt's original blog post [Docker Events Explained](https://gliderlabs.com/blog/2015/04/14/docker-events-explained/).
## Version history
diff --git a/docs/reference/api/remote_api_client_libraries.md b/docs/reference/api/remote_api_client_libraries.md
index 677145a..fd4b3e3 100644
--- a/docs/reference/api/remote_api_client_libraries.md
+++ b/docs/reference/api/remote_api_client_libraries.md
@@ -124,6 +124,12 @@
</tr>
<tr>
<td>JavaScript (NodeJS)</td>
+ <td>dockerizer</td>
+ <td><a class="reference external" href="https://github.com/kesarion/dockerizer">https://github.com/kesarion/dockerizer</a></td>
+ <td>Active</td>
+ </tr>
+ <tr>
+ <td>JavaScript (NodeJS)</td>
<td>dockerode</td>
<td><a class="reference external" href="https://github.com/apocas/dockerode">https://github.com/apocas/dockerode</a>
Install via NPM: <cite>npm install dockerode</cite></td>
@@ -191,6 +197,12 @@
<td>Active</td>
</tr>
<tr>
+ <td>PHP</td>
+ <td>Docker-PHP-Client</td>
+ <td><a class="reference external" href="https://github.com/jarkt/docker-php-client">https://github.com/jarkt/docker-php-client</a></td>
+ <td>Active</td>
+ </tr>
+ <tr>
<td>Python</td>
<td>docker-py</td>
<td><a class="reference external" href="https://github.com/docker/docker-py">https://github.com/docker/docker-py</a></td>
diff --git a/docs/reference/commandline/attach.md b/docs/reference/commandline/attach.md
index 124474b..dfe2908 100644
--- a/docs/reference/commandline/attach.md
+++ b/docs/reference/commandline/attach.md
@@ -54,7 +54,7 @@
the following:
* `a-z` (a single lowercase alpha character )
-* `@` (ampersand)
+* `@` (at sign)
* `[` (left bracket)
* `\\` (two backward slashes)
* `_` (underscore)
diff --git a/docs/reference/commandline/cli.md b/docs/reference/commandline/cli.md
index 26d2469..96486d7 100644
--- a/docs/reference/commandline/cli.md
+++ b/docs/reference/commandline/cli.md
@@ -111,7 +111,7 @@
a letter [a-Z], or the `ctrl-` combined with any of the following:
* `a-z` (a single lowercase alpha character )
-* `@` (ampersand)
+* `@` (at sign)
* `[` (left bracket)
* `\\` (two backward slashes)
* `_` (underscore)
diff --git a/docs/reference/commandline/info.md b/docs/reference/commandline/info.md
index 51ae269..5bb6fb2 100644
--- a/docs/reference/commandline/info.md
+++ b/docs/reference/commandline/info.md
@@ -44,6 +44,7 @@
Total Memory: 62.86 GiB
Name: docker
ID: I54V:OLXT:HVMM:TPKO:JPHQ:CQCD:JNLC:O3BZ:4ZVJ:43XJ:PFHZ:6N2S
+ Debug mode (client): true
Debug mode (server): true
File Descriptors: 59
Goroutines: 159
diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md
index dce1019..e9b913d 100644
--- a/docs/reference/commandline/run.md
+++ b/docs/reference/commandline/run.md
@@ -220,7 +220,8 @@
$ docker run -e MYVAR1 --env MYVAR2=foo --env-file ./env.list ubuntu bash
-This sets environmental variables in the container. For illustration all three
+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 is passed
through (i.e. `$MYVAR1` from the host is set to `$MYVAR1` in the container).
diff --git a/docs/reference/run.md b/docs/reference/run.md
index e38fd1f..ba2fc2d 100644
--- a/docs/reference/run.md
+++ b/docs/reference/run.md
@@ -1049,8 +1049,8 @@
up for the specified user. If one wants to add more to that list of groups, then
one can use this flag:
- $ docker run -it --rm --group-add audio --group-add dbus --group-add 777 busybox id
- uid=0(root) gid=0(root) groups=10(wheel),29(audio),81(dbus),777
+ $ docker run --rm --group-add audio --group-add nogroup --group-add 777 busybox id
+ uid=0(root) gid=0(root) groups=10(wheel),29(audio),99(nogroup),777
## Runtime privilege and Linux capabilities
@@ -1059,6 +1059,14 @@
--privileged=false: Give extended privileges to this container
--device=[]: Allows you to run devices inside the container without the --privileged flag.
+> **Note:**
+> With Docker 1.10 and greater, the default seccomp profile will also block
+> syscalls, regardless of `--cap-add` passed to the container. We recommend in
+> these cases to create your own custom seccomp profile based off our
+> [default](https://github.com/docker/docker/blob/master/profiles/seccomp/default.json).
+> Or if you don't want to run with the default seccomp profile, you can pass
+> `--security-opt=seccomp:unconfined` on run.
+
By default, Docker containers are "unprivileged" and cannot, for
example, run a Docker daemon inside a Docker container. This is because
by default a container is not allowed to access any devices, but a
@@ -1429,7 +1437,10 @@
Dockerfile `USER` instruction. When starting a container, the operator can override
the `USER` instruction by passing the `-u` option.
- -u="": Username or UID
+ -u="", --user="": Sets the username or UID used and optionally the groupname or GID for the specified command.
+
+ The followings examples are all valid:
+ --user=[ user | user:group | uid | uid:gid | user:gid | uid:group ]
> **Note:** if you pass a numeric uid, it must be in the range of 0-2147483647.
diff --git a/docs/userguide/containers/dockervolumes.md b/docs/userguide/containers/dockervolumes.md
index 0fb7fe2..63d7e51 100644
--- a/docs/userguide/containers/dockervolumes.md
+++ b/docs/userguide/containers/dockervolumes.md
@@ -126,8 +126,8 @@
docker run -v /c/Users/<path>:/<container path> ...`
```
-All other paths come from your virtual machine's filesystem. For example, if
-you are using VirtualBox some other folder available for sharing, you need to do
+All other paths come from your virtual machine's filesystem, so if you want
+to make some other host folder available for sharing, you need to do
additional work. In the case of VirtualBox you need to make the host folder
available as a shared folder in VirtualBox. Then, you can mount it using the
Docker `-v` flag.
diff --git a/docs/userguide/index.md b/docs/userguide/index.md
index 1bffafc..2509997 100644
--- a/docs/userguide/index.md
+++ b/docs/userguide/index.md
@@ -1,8 +1,8 @@
<!--[metadata]>
+++
title = "User guide"
-description = "Welcome to the user guide"
-keywords = ["docker, introduction, documentation, about, technology, docker.io, user, guide, user's, manual, platform, framework, home, intro"]
+description = "How to use the Docker Engine user guide"
+keywords = ["engine, introduction, documentation, about, technology, docker, user, guide, framework, home, intro"]
[menu.main]
parent="engine_use"
identifier = "engine_guide"
@@ -10,4 +10,54 @@
+++
<![end-metadata]-->
-# User guide
+# Docker Engine user guide
+
+This guide helps users learn how to use Docker Engine.
+
+- [Introduction to Engine user guide](intro.md)
+
+## Learn by example
+
+- [Hello world in a container](containers/dockerizing.md)
+- [Build your own images](containers/dockerimages.md)
+- [Network containers](containers/networkingcontainers.md)
+- [Run a simple application](containers/usingdocker.md)
+- [Manage data in containers](containers/dockervolumes.md)
+- [Store images on Docker Hub](containers/dockerrepos.md)
+
+## Work with images
+
+- [Best practices for writing Dockerfiles](eng-image/dockerfile_best-practices.md)
+- [Create a base image](eng-image/baseimages.md)
+- [Image management](eng-image/image_management.md)
+
+## Manage storage drivers
+
+- [Understand images, containers, and storage drivers](storagedriver/imagesandcontainers.md)
+- [Select a storage driver](storagedriver/selectadriver.md)
+- [AUFS storage in practice](storagedriver/aufs-driver.md)
+- [Btrfs storage in practice](storagedriver/btrfs-driver.md)
+- [Device Mapper storage in practice](storagedriver/device-mapper-driver.md)
+- [OverlayFS storage in practice](storagedriver/overlayfs-driver.md)
+- [ZFS storage in practice](storagedriver/zfs-driver.md)
+
+## Configure networks
+
+- [Understand Docker container networks](networking/dockernetworks.md)
+- [Embedded DNS server in user-defined networks](networking/configure-dns.md)
+- [Get started with multi-host networking](networking/get-started-overlay.md)
+- [Work with network commands](networking/work-with-networks.md)
+
+### Work with the default network
+
+- [Understand container communication](networking/default_network/container-communication.md)
+- [Legacy container links](networking/default_network/dockerlinks.md)
+- [Binding container ports to the host](networking/default_network/binding.md)
+- [Build your own bridge](networking/default_network/build-bridges.md)
+- [Configure container DNS](networking/default_network/configure-dns.md)
+- [Customize the docker0 bridge](networking/default_network/custom-docker0.md)
+- [IPv6 with Docker](networking/default_network/ipv6.md)
+
+## Misc
+
+- [Apply custom metadata](labels-custom-metadata.md)
diff --git a/docs/userguide/networking/default_network/options.md b/docs/userguide/networking/default_network/options.md
deleted file mode 100644
index 612dffb..0000000
--- a/docs/userguide/networking/default_network/options.md
+++ /dev/null
@@ -1,141 +0,0 @@
-<!--[metadata]>
-+++
-draft=true
-title = "Tools and Examples"
-keywords = ["docker, bridge, docker0, network"]
-[menu.main]
-parent = "smn_networking_def"
-+++
-<![end-metadata]-->
-
-<!--[metadata]>
-We may want to add it back in later under another form. Labeled DRAFT for now. Won't be built.
-<![end-metadata]-->
-
-# Quick guide to the options
-Here is a quick list of the networking-related Docker command-line options, in case it helps you find the section below that you are looking for.
-
-Some networking command-line options can only be supplied to the Docker server when it starts up, and cannot be changed once it is running:
-- `-b BRIDGE` or `--bridge=BRIDGE` -- see
-
- [Building your own bridge](#bridge-building)
-
-- `--bip=CIDR` -- see
-
- [Customizing docker0](#docker0)
-
-- `--default-gateway=IP_ADDRESS` -- see
-
- [How Docker networks a container](#container-networking)
-
-- `--default-gateway-v6=IP_ADDRESS` -- see
-
- [IPv6](#ipv6)
-
-- `--fixed-cidr` -- see
-
- [Customizing docker0](#docker0)
-
-- `--fixed-cidr-v6` -- see
-
- [IPv6](#ipv6)
-
-- `-H SOCKET...` or `--host=SOCKET...` --
-
- This might sound like it would affect container networking,
-
- but it actually faces in the other direction:
-
- it tells the Docker server over what channels
-
- it should be willing to receive commands
-
- like "run container" and "stop container."
-
-- `--icc=true|false` -- see
-
- [Communication between containers](#between-containers)
-
-- `--ip=IP_ADDRESS` -- see
-
- [Binding container ports](#binding-ports)
-
-- `--ipv6=true|false` -- see
-
- [IPv6](#ipv6)
-
-- `--ip-forward=true|false` -- see
-
- [Communication between containers and the wider world](#the-world)
-
-- `--iptables=true|false` -- see
-
- [Communication between containers](#between-containers)
-
-- `--mtu=BYTES` -- see
-
- [Customizing docker0](#docker0)
-
-- `--userland-proxy=true|false` -- see
-
- [Binding container ports](#binding-ports)
-
-There are three networking options that can be supplied either at startup or when `docker run` is invoked. When provided at startup, set the default value that `docker run` will later use if the options are not specified:
-- `--dns=IP_ADDRESS...` -- see
-
- [Configuring DNS](#dns)
-
-- `--dns-search=DOMAIN...` -- see
-
- [Configuring DNS](#dns)
-
-- `--dns-opt=OPTION...` -- see
-
- [Configuring DNS](#dns)
-
-Finally, several networking options can only be provided when calling `docker run` because they specify something specific to one container:
-- `-h HOSTNAME` or `--hostname=HOSTNAME` -- see
-
- [Configuring DNS](#dns) and
-
- [How Docker networks a container](#container-networking)
-
-- `--link=CONTAINER_NAME_or_ID:ALIAS` -- see
-
- [Configuring DNS](#dns) and
-
- [Communication between containers](#between-containers)
-
-- `--net=bridge|none|container:NAME_or_ID|host` -- see
-
- [How Docker networks a container](#container-networking)
-
-- `--mac-address=MACADDRESS...` -- see
-
- [How Docker networks a container](#container-networking)
-
-- `-p SPEC` or `--publish=SPEC` -- see
-
- [Binding container ports](#binding-ports)
-
-- `-P` or `--publish-all=true|false` -- see
-
- [Binding container ports](#binding-ports)
-
-To supply networking options to the Docker server at startup, use the `DOCKER_OPTS` variable in the Docker upstart configuration file. For Ubuntu, edit the variable in `/etc/default/docker` or `/etc/sysconfig/docker` for CentOS.
-
-The following example illustrates how to configure Docker on Ubuntu to recognize a newly built bridge.
-
-Edit the `/etc/default/docker` file:
-
-```
-$ echo 'DOCKER_OPTS="-b=bridge0"' >> /etc/default/docker
-```
-
-Then restart the Docker server.
-
-```
-$ sudo service docker start
-```
-
-For additional information on bridges, see [building your own bridge](#building-your-own-bridge) later on this page.
diff --git a/docs/userguide/networking/default_network/saveme.md b/docs/userguide/networking/default_network/saveme.md
deleted file mode 100644
index f0ef85e..0000000
--- a/docs/userguide/networking/default_network/saveme.md
+++ /dev/null
@@ -1,28 +0,0 @@
-<!--[metadata]>
-+++
-draft=true
-title = "Saved text"
-keywords = ["docker, bridge, docker0, network"]
-[menu.main]
-parent = "smn_networking_def"
-+++
-<![end-metadata]-->
-
-<!--[metadata]>
-This content was extracted from the original introduction. We may want to add it back in later under another form. Labeled DRAFT for now. Won't be built.
-<![end-metadata]-->
-
-
-## A Brief introduction to networking and docker
-When Docker starts, it creates a virtual interface named `docker0` on the host machine. It randomly chooses an address and subnet from the private range defined by [RFC 1918](http://tools.ietf.org/html/rfc1918) that are not in use on the host machine, and assigns it to `docker0`. Docker made the choice `172.17.42.1/16` when I started it a few minutes ago, for example -- a 16-bit netmask providing 65,534 addresses for the host machine and its containers. The MAC address is generated using the IP address allocated to the container to avoid ARP collisions, using a range from `02:42:ac:11:00:00` to `02:42:ac:11:ff:ff`.
-
-> **Note:** This document discusses advanced networking configuration and options for Docker. In most cases you won't need this information. If you're looking to get started with a simpler explanation of Docker networking and an introduction to the concept of container linking see the [Docker User Guide](dockerlinks.md).
-
-But `docker0` is no ordinary interface. It is a virtual _Ethernet bridge_ that automatically forwards packets between any other network interfaces that are attached to it. This lets containers communicate both with the host machine and with each other. Every time Docker creates a container, it creates a pair of "peer" interfaces that are like opposite ends of a pipe -- a packet sent on one will be received on the other. It gives one of the peers to the container to become its `eth0` interface and keeps the other peer, with a unique name like `vethAQI2QT`, out in the namespace of the host machine. By binding every `veth*` interface to the `docker0` bridge, Docker creates a virtual subnet shared between the host machine and every Docker container.
-
-The remaining sections of this document explain all of the ways that you can use Docker options and -- in advanced cases -- raw Linux networking commands to tweak, supplement, or entirely replace Docker's default networking configuration.
-
-## Editing networking config files
-Starting with Docker v.1.2.0, you can now edit `/etc/hosts`, `/etc/hostname` and `/etc/resolve.conf` in a running container. This is useful if you need to install bind or other services that might override one of those files.
-
-Note, however, that changes to these files will not be saved by `docker commit`, nor will they be saved during `docker run`. That means they won't be saved in the image, nor will they persist when a container is restarted; they will only "stick" in a running container.
diff --git a/docs/userguide/networking/default_network/tools.md b/docs/userguide/networking/default_network/tools.md
deleted file mode 100644
index 545c1e0..0000000
--- a/docs/userguide/networking/default_network/tools.md
+++ /dev/null
@@ -1,83 +0,0 @@
-<!--[metadata]>
-+++
-draft=true
-title = "Tools and Examples"
-keywords = ["docker, bridge, docker0, network"]
-[menu.main]
-parent = "smn_networking_def"
-+++
-<![end-metadata]-->
-
-<!--[metadata]>
-Dave Tucker instructed remove this. We may want to add it back in later under another form. Labeled DRAFT for now. Won't be built.
-<![end-metadata]-->
-
-# Tools and examples
-Before diving into the following sections on custom network topologies, you might be interested in glancing at a few external tools or examples of the same kinds of configuration. Here are two:
-- Jérôme Petazzoni has created a `pipework` shell script to help you
-
- connect together containers in arbitrarily complex scenarios:
-
- [https://github.com/jpetazzo/pipework](https://github.com/jpetazzo/pipework)
-
-- Brandon Rhodes has created a whole network topology of Docker
-
- containers for the next edition of Foundations of Python Network
-
- Programming that includes routing, NAT'd firewalls, and servers that
-
- offer HTTP, SMTP, POP, IMAP, Telnet, SSH, and FTP:
-
- [https://github.com/brandon-rhodes/fopnp/tree/m/playground](https://github.com/brandon-rhodes/fopnp/tree/m/playground)
-
-Both tools use networking commands very much like the ones you saw in the previous section, and will see in the following sections.
-
-# Building a point-to-point connection
-<a name="point-to-point"></a>
-
-By default, Docker attaches all containers to the virtual subnet implemented by `docker0`. You can create containers that are each connected to some different virtual subnet by creating your own bridge as shown in [Building your own bridge](#bridge-building), starting each container with `docker run --net=none`, and then attaching the containers to your bridge with the shell commands shown in [How Docker networks a container](#container-networking).
-
-But sometimes you want two particular containers to be able to communicate directly without the added complexity of both being bound to a host-wide Ethernet bridge.
-
-The solution is simple: when you create your pair of peer interfaces, simply throw _both_ of them into containers, and configure them as classic point-to-point links. The two containers will then be able to communicate directly (provided you manage to tell each container the other's IP address, of course). You might adjust the instructions of the previous section to go something like this:
-
-```
-# Start up two containers in two terminal windows
-
-$ docker run -i -t --rm --net=none base /bin/bash
-root@1f1f4c1f931a:/#
-
-$ docker run -i -t --rm --net=none base /bin/bash
-root@12e343489d2f:/#
-
-# Learn the container process IDs
-# and create their namespace entries
-
-$ docker inspect -f '{{.State.Pid}}' 1f1f4c1f931a
-2989
-$ docker inspect -f '{{.State.Pid}}' 12e343489d2f
-3004
-$ sudo mkdir -p /var/run/netns
-$ sudo ln -s /proc/2989/ns/net /var/run/netns/2989
-$ sudo ln -s /proc/3004/ns/net /var/run/netns/3004
-
-# Create the "peer" interfaces and hand them out
-
-$ sudo ip link add A type veth peer name B
-
-$ sudo ip link set A netns 2989
-$ sudo ip netns exec 2989 ip addr add 10.1.1.1/32 dev A
-$ sudo ip netns exec 2989 ip link set A up
-$ sudo ip netns exec 2989 ip route add 10.1.1.2/32 dev A
-
-$ sudo ip link set B netns 3004
-$ sudo ip netns exec 3004 ip addr add 10.1.1.2/32 dev B
-$ sudo ip netns exec 3004 ip link set B up
-$ sudo ip netns exec 3004 ip route add 10.1.1.1/32 dev B
-```
-
-The two containers should now be able to ping each other and make connections successfully. Point-to-point links like this do not depend on a subnet nor a netmask, but on the bare assertion made by `ip route` that some other single IP address is connected to a particular network interface.
-
-Note that point-to-point links can be safely combined with other kinds of network connectivity -- there is no need to start the containers with `--net=none` if you want point-to-point links to be an addition to the container's normal networking instead of a replacement.
-
-A final permutation of this pattern is to create the point-to-point link between the Docker host and one container, which would allow the host to communicate with that one container on some single IP address and thus communicate "out-of-band" of the bridge that connects the other, more usual containers. But unless you have very specific networking needs that drive you to such a solution, it is probably far preferable to use `--icc=false` to lock down inter-container communication, as we explored earlier.
diff --git a/docs/userguide/networking/dockernetworks.md b/docs/userguide/networking/dockernetworks.md
index b9f1a63..a64b969 100644
--- a/docs/userguide/networking/dockernetworks.md
+++ b/docs/userguide/networking/dockernetworks.md
@@ -421,7 +421,7 @@
form them into a swarm which includes a discovery service as well.
To create an overlay network, you configure options on the `daemon` on each
-Docker Engine for use with `overlay` network. There are two options to set:
+Docker Engine for use with `overlay` network. There are three options to set:
<table>
<thead>
diff --git a/docs/userguide/networking/get-started-overlay.md b/docs/userguide/networking/get-started-overlay.md
index 39d7da9..4854fe6 100644
--- a/docs/userguide/networking/get-started-overlay.md
+++ b/docs/userguide/networking/get-started-overlay.md
@@ -19,6 +19,7 @@
* Access to a key-value store. Docker supports Consul, Etcd, and ZooKeeper (Distributed store) key-value stores.
* A cluster of hosts with connectivity to the key-value store.
* A properly configured Engine `daemon` on each host in the cluster.
+* Hosts within the cluster must have unique hostnames because the key-value store uses the hostnames to identify cluster members.
Though Docker Machine and Docker Swarm are not mandatory to experience Docker
multi-host networking, this example uses them to illustrate how they are
diff --git a/docs/userguide/networking/work-with-networks.md b/docs/userguide/networking/work-with-networks.md
index b668bc1..ecc5462 100644
--- a/docs/userguide/networking/work-with-networks.md
+++ b/docs/userguide/networking/work-with-networks.md
@@ -62,7 +62,7 @@
Unlike `bridge` networks, `overlay` networks require some pre-existing conditions
before you can create one. These conditions are:
-* Access to a key-value store. Engine supports Consul Etcd, and ZooKeeper (Distributed store) key-value stores.
+* Access to a key-value store. Engine supports Consul, Etcd, and ZooKeeper (Distributed store) key-value stores.
* A cluster of hosts with connectivity to the key-value store.
* A properly configured Engine `daemon` on each host in the swarm.
@@ -312,6 +312,7 @@
TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:0
RX bytes:0 (0.0 B) TX bytes:0 (0.0 B)
+```
On the `isolated_nw` which was user defined, the Docker embedded DNS server enables name resolution for other containers in the network. Inside of `container2` it is possible to ping `container3` by name.
@@ -376,7 +377,7 @@
### Linking containers in user-defined networks
-In the above example, container_2 was able to resolve container_3's name automatically
+In the above example, `container2` was able to resolve `container3`'s name automatically
in the user defined network `isolated_nw`, but the name resolution did not succeed
automatically in the default `bridge` network. This is expected in order to maintain
backward compatibility with [legacy link](default_network/dockerlinks.md).
@@ -396,7 +397,7 @@
* ability to dynamically attach and detach to multiple networks
* supports the `--link` option to provide name alias for the linked container
-Continuing with the above example, create another container `container_4` in `isolated_nw`
+Continuing with the above example, create another container `container4` in `isolated_nw`
with `--link` to provide additional name resolution using alias for other containers in
the same network.
@@ -405,26 +406,25 @@
01b5df970834b77a9eadbaff39051f237957bd35c4c56f11193e0594cfd5117c
```
-With the help of `--link` container4 will be able to reach container5 using the
+With the help of `--link` `container4` will be able to reach `container5` using the
aliased name `c5` as well.
-Please note that while creating container4, we linked to a container named `container5`
+Please note that while creating `container4`, we linked to a container named `container5`
which is not created yet. That is one of the differences in behavior between the
-`legacy link` in default `bridge` network and the new `link` functionality in user defined
-networks. The `legacy link` is static in nature and it hard-binds the container with the
-alias and it doesnt tolerate linked container restarts. While the new `link` functionality
-in user defined networks are dynamic in nature and supports linked container restarts
-including tolerating ip-address changes on the linked container.
-Now let us launch another container named `container5` linking container4 to c4.
+*legacy link* in default `bridge` network and the new *link* functionality in user defined
+networks. The *legacy link* is static in nature and it hard-binds the container with the
+alias and it doesn't tolerate linked container restarts. While the new *link* functionality
+
+Now let us launch another container named `container5` linking `container4` to c4.
```bash
$ docker run --net=isolated_nw -itd --name=container5 --link container4:c4 busybox
72eccf2208336f31e9e33ba327734125af00d1e1d2657878e2ee8154fbb23c7a
```
-As expected, container4 will be able to reach container5 by both its container name and
-its alias c5 and container5 will be able to reach container4 by its container name and
+As expected, `container4` will be able to reach `container5` by both its container name and
+its alias c5 and `container5` will be able to reach `container4` by its container name and
its alias c4.
```bash
@@ -491,7 +491,7 @@
76b7dc932e037589e6553f59f76008e5b76fa069638cd39776b890607f567aaa
```
-let us connect container4 and container5 to the new network `local_alias`
+let us connect `container4` and `container5` to the new network `local_alias`
```
$ docker network connect --link container5:foo local_alias container4
@@ -525,7 +525,7 @@
```
Note that the ping succeeds for both the aliases but on different networks.
-Let us conclude this section by disconnecting container5 from the `isolated_nw`
+Let us conclude this section by disconnecting `container5` from the `isolated_nw`
and observe the results
```
@@ -550,9 +550,9 @@
```
In conclusion, the new link functionality in user defined networks provides all the
-benefits of legacy links while avoiding most of the well-known issues with `legacy links`.
+benefits of legacy links while avoiding most of the well-known issues with *legacy links*.
-One notable missing functionality compared to `legacy links` is the injection of
+One notable missing functionality compared to *legacy links* is the injection of
environment variables. Though very useful, environment variable injection is static
in nature and must be injected when the container is started. One cannot inject
environment variables into a running container without significant effort and hence
@@ -561,10 +561,10 @@
### Network-scoped alias
-While `links` provide private name resolution that is localized within a container,
+While *link*s provide private name resolution that is localized within a container,
the network-scoped alias provides a way for a container to be discovered by an
alternate name by any other container within the scope of a particular network.
-Unlike the `link` alias, which is defined by the consumer of a service, the
+Unlike the *link* alias, which is defined by the consumer of a service, the
network-scoped alias is defined by the container that is offering the service
to the network.
@@ -788,8 +788,8 @@
where the daemon is unable to cleanup stale connectivity endpoints. Such stale endpoints
may cause an error `container already connected to network` when a new container is
connected to that network with the same name as the stale endpoint. In order to cleanup
-these stale endpoints, first remove the container and force disconnect
-(`docker network disconnect -f`) the endpoint from the network. Once the endpoint is
+these stale endpoints, first remove the container and force disconnect
+(`docker network disconnect -f`) the endpoint from the network. Once the endpoint is
cleaned up, the container can be connected to the network.
```
diff --git a/man/docker-attach.1.md b/man/docker-attach.1.md
index adecceb..c78f4fb 100644
--- a/man/docker-attach.1.md
+++ b/man/docker-attach.1.md
@@ -55,7 +55,7 @@
the following:
* `a-z` (a single lowercase alpha character )
-* `@` (ampersand)
+* `@` (at sign)
* `[` (left bracket)
* `\\` (two backward slashes)
* `_` (underscore)
