Merge pull request #22990 from thaJeztah/docs-cherry-picks

Docs cherry picks (2016-05-25)

19 files changed, 249 insertions, 162 deletions

diff --git a/docs/Dockerfile b/docs/Dockerfile
index 3690d1572a..ce6e6ff255 100644
--- a/docs/Dockerfile
+++ b/docs/Dockerfile
@@ -1,17 +1,8 @@
-FROM docs/base:latest
+FROM docs/base:oss
 MAINTAINER Mary Anthony <mary@docker.com> (@moxiegirl)
 
-RUN svn checkout https://github.com/docker/compose/trunk/docs /docs/content/compose
-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/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
 # To get the git info for this repo
 COPY . /src
-
+RUN rm -r /docs/content/$PROJECT/
 COPY . /docs/content/$PROJECT/
diff --git a/docs/Makefile b/docs/Makefile
index 711462ea5b..e2ab871de2 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -24,9 +24,8 @@ HUGO_BASE_URL=$(shell test -z "$(DOCKER_IP)" && echo localhost || echo "$(DOCKER
 HUGO_BIND_IP=0.0.0.0
 
 GIT_BRANCH := $(shell git rev-parse --abbrev-ref HEAD 2>/dev/null)
-DOCKER_IMAGE := docker$(if $(GIT_BRANCH),:$(GIT_BRANCH))
-DOCKER_DOCS_IMAGE := docs-base$(if $(GIT_BRANCH),:$(GIT_BRANCH))
-
+GIT_BRANCH_CLEAN := $(shell echo $(GIT_BRANCH) | sed -e "s/[^[:alnum:]]/-/g")
+DOCKER_DOCS_IMAGE := docker-docs$(if $(GIT_BRANCH_CLEAN),:$(GIT_BRANCH_CLEAN))
 
 DOCKER_RUN_DOCS := docker run --rm -it $(DOCS_MOUNT) -e AWS_S3_BUCKET -e NOCACHE
 
diff --git a/docs/deprecated.md b/docs/deprecated.md
index 2536278f88..b8ee3e5226 100644
--- a/docs/deprecated.md
+++ b/docs/deprecated.md
@@ -84,10 +84,9 @@ Because of which, the driver specific log tag options `syslog-tag`, `gelf-tag` a
 ### LXC built-in exec driver
 **Deprecated In Release: v1.8**
 
-**Target For Removal In Release: v1.10**
+**Removed In Release: v1.10**
 
-The built-in LXC execution driver is deprecated for an external implementation.
-The lxc-conf flag and API fields will also be removed.
+The built-in LXC execution driver, the lxc-conf flag, and API fields have been removed.
 
 ### Old Command Line Options
 **Deprecated In Release: [v1.8.0](https://github.com/docker/docker/releases/tag/v1.8.0)**
diff --git a/docs/extend/plugins.md b/docs/extend/plugins.md
index e40c611282..7a3687fced 100644
--- a/docs/extend/plugins.md
+++ b/docs/extend/plugins.md
@@ -60,7 +60,7 @@ Plugin
 [Keywhiz plugin](https://github.com/calavera/docker-volume-keywhiz)                 | A plugin that provides credentials and secret management using Keywhiz as a central repository.
 [Local Persist Plugin](https://github.com/CWSpear/local-persist)                    | A volume plugin that extends the default `local` driver's functionality by allowing you specify a mountpoint anywhere on the host, which enables the files to *always persist*, even if the volume is removed via `docker volume rm`.
 [NetApp Plugin](https://github.com/NetApp/netappdvp) (nDVP)                         | A volume plugin that provides direct integration with the Docker ecosystem for the NetApp storage portfolio. The nDVP package supports the provisioning and management of storage resources from the storage platform to Docker hosts, with a robust framework for adding additional platforms in the future.
-[Netshare plugin](https://github.com/gondor/docker-volume-netshare)                 | A volume plugin that provides volume management for NFS 3/4, AWS EFS and CIFS file systems.
+[Netshare plugin](https://github.com/ContainX/docker-volume-netshare)                 | A volume plugin that provides volume management for NFS 3/4, AWS EFS and CIFS file systems.
 [OpenStorage Plugin](https://github.com/libopenstorage/openstorage)                 | A cluster-aware volume plugin that provides volume management for file and block storage solutions.  It implements a vendor neutral specification for implementing extensions such as CoS, encryption, and snapshots. It has example drivers based on FUSE, NFS, NBD and EBS to name a few.
 [Quobyte Volume Plugin](https://github.com/quobyte/docker-volume)                   | A volume plugin that connects Docker to [Quobyte](http://www.quobyte.com/containers)'s data center file system, a general-purpose scalable and fault-tolerant storage platform.
 [REX-Ray plugin](https://github.com/emccode/rexray)                                 | A volume plugin which is written in Go and provides advanced storage functionality for many platforms including VirtualBox, EC2, Google Compute Engine, OpenStack, and EMC.
diff --git a/docs/installation/linux/fedora.md b/docs/installation/linux/fedora.md
index 782adc6735..8d297b4750 100644
--- a/docs/installation/linux/fedora.md
+++ b/docs/installation/linux/fedora.md
@@ -186,7 +186,7 @@ You can uninstall the Docker software with `dnf`.
 
 1. List the package you have installed.
 
-		$ dnf list installed | grep docker dnf list installed | grep docker
+		$ dnf list installed | grep docker
 		docker-engine.x86_64     1.7.1-0.1.fc21 @/docker-engine-1.7.1-0.1.fc21.el7.x86_64
 
 2. Remove the package.
diff --git a/docs/reference/builder.md b/docs/reference/builder.md
index 9a2f42ea8b..d2d831a821 100644
--- a/docs/reference/builder.md
+++ b/docs/reference/builder.md
@@ -361,7 +361,16 @@ RUN /bin/bash -c 'source $HOME/.bashrc ; echo $HOME'
 > This means that normal shell processing does not happen. For example,
 > `RUN [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`.
 > If you want shell processing then either use the *shell* form or execute
-> a shell directly, for example: `RUN [ "sh", "-c", "echo", "$HOME" ]`.
+> a shell directly, for example: `RUN [ "sh", "-c", "echo $HOME" ]`.
+>
+> **Note**:
+> In the *JSON* form, it is necessary to escape backslashes. This is
+> particularly relevant on Windows where the backslash is the path seperator.
+> The following line would otherwise be treated as *shell* form due to not
+> being valid JSON, and fail in an unexpected way:
+> `RUN ["c:\windows\system32\tasklist.exe"]`
+> The correct syntax for this example is:
+> `RUN ["c:\\windows\\system32\\tasklist.exe"]`
 
 The cache for `RUN` instructions isn't invalidated automatically during
 the next build. The cache for an instruction like
diff --git a/docs/reference/commandline/attach.md b/docs/reference/commandline/attach.md
index b28b6fc263..799fe1d176 100644
--- a/docs/reference/commandline/attach.md
+++ b/docs/reference/commandline/attach.md
@@ -28,7 +28,7 @@ detached  process.
 To stop a container, use `CTRL-c`. This key sequence sends `SIGKILL` to the
 container. If `--sig-proxy` is true (the default),`CTRL-c` sends a `SIGINT` to
 the container. You can detach from a container and leave it running using the
-using `CTRL-p CTRL-q` key sequence.
+ `CTRL-p CTRL-q` key sequence.
 
 > **Note:**
 > A process running as PID 1 inside a container is treated specially by
diff --git a/docs/reference/commandline/build.md b/docs/reference/commandline/build.md
index 4530f77bb1..f0f30a0ced 100644
--- a/docs/reference/commandline/build.md
+++ b/docs/reference/commandline/build.md
@@ -298,6 +298,9 @@ 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).
 
diff --git a/docs/reference/commandline/cp.md b/docs/reference/commandline/cp.md
index 841aeb36e0..8afabc95bc 100644
--- a/docs/reference/commandline/cp.md
+++ b/docs/reference/commandline/cp.md
@@ -81,7 +81,17 @@ you must be explicit with a relative or absolute path, for example:
     `/path/to/file:name.txt` or `./file:name.txt`
 
 It is not possible to copy certain system files such as resources under
-`/proc`, `/sys`, `/dev`, and mounts created by the user in the container.
+`/proc`, `/sys`, `/dev`, [tmpfs](run.md#mount-tmpfs-tmpfs), and mounts created by
+the user in the container. However, you can still copy such files by manually
+running `tar` in `docker exec`. For example (consider `SRC_PATH` and `DEST_PATH`
+are directories):
+
+    $ docker exec foo tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | tar Cxf DEST_PATH -
+
+or
+
+    $ tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | docker exec -i foo tar Cxf DEST_PATH -
+
 
 Using `-` as the `SRC_PATH` streams the contents of `STDIN` as a tar archive.
 The command extracts the content of the tar to the `DEST_PATH` in container's
diff --git a/docs/reference/commandline/pull.md b/docs/reference/commandline/pull.md
index 01ec88e8a6..0231422918 100644
--- a/docs/reference/commandline/pull.md
+++ b/docs/reference/commandline/pull.md
@@ -27,6 +27,15 @@ can `pull` and try without needing to define and configure your own.
 To download a particular image, or set of images (i.e., a repository),
 use `docker pull`.
 
+## Proxy configuration
+
+If you are behind a HTTP proxy server, for example in corporate settings,
+before open a connect to registry, you may need to configure the Docker
+daemon's proxy settings, using the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`
+environment variables. To set these environment variables on a host using
+`systemd`, refer to the [control and configure Docker with systemd](../../admin/systemd.md#http-proxy)
+for variables configuration.
+
 ## Examples
 
 ### Pull an image from Docker Hub
diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md
index 97553a67dc..544aa37240 100644
--- a/docs/reference/commandline/run.md
+++ b/docs/reference/commandline/run.md
@@ -227,12 +227,12 @@ system's interfaces.
 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).
-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.
+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
diff --git a/docs/reference/run.md b/docs/reference/run.md
index 942bba948f..447ae12cda 100644
--- a/docs/reference/run.md
+++ b/docs/reference/run.md
@@ -612,15 +612,12 @@ with the same logic -- if the original volume was specified with a name it will
 
 
 You can override the default labeling scheme for each container by specifying
-the `--security-opt` flag. For example, you can specify the MCS/MLS level, a
-requirement for MLS systems. Specifying the level in the following command
+the `--security-opt` flag. Specifying the level in the following command
 allows you to share the same content between containers.
 
     $ docker run --security-opt label=level:s0:c100,c200 -it fedora bash
 
-An MLS example might be:
-
-    $ docker run --security-opt label=level:TopSecret -it rhel7 bash
+> **Note**: Automatic translation of MLS labels is not currently supported.
 
 To disable the security labeling for this container versus running with the
 `--permissive` flag, use the following command:
@@ -1433,7 +1430,7 @@ The `host-src` can either be an absolute path or a `name` value. If you
 supply an absolute path for the `host-dir`, Docker bind-mounts to the path
 you specify. If you supply a `name`, Docker creates a named volume by that `name`.
 
-A `name` value must start with start with an alphanumeric character,
+A `name` value must start with an alphanumeric character,
 followed by `a-z0-9`, `_` (underscore), `.` (period) or `-` (hyphen).
 An absolute path starts with a `/` (forward slash).
 
diff --git a/docs/userguide/labels-custom-metadata.md b/docs/userguide/labels-custom-metadata.md
index 4c9a1a114c..c4b6d27a6a 100644
--- a/docs/userguide/labels-custom-metadata.md
+++ b/docs/userguide/labels-custom-metadata.md
@@ -22,7 +22,7 @@ times but with different values, newer labels overwrite previous labels. Docker
 uses the last `key=value` you supply.
 
 >**Note:** Support for daemon-labels was added in Docker 1.4.1. Labels on
->containers and images are new in Docker 1.6.0
+>containers and images were added in Docker 1.6.0
 
 ## Label keys (namespaces)
 
diff --git a/docs/userguide/networking/dockernetworks.md b/docs/userguide/networking/dockernetworks.md
index 465470e737..22b8b346a3 100644
--- a/docs/userguide/networking/dockernetworks.md
+++ b/docs/userguide/networking/dockernetworks.md
@@ -57,7 +57,7 @@ docker0   Link encap:Ethernet  HWaddr 02:42:47:bc:3a:eb
           RX bytes:1100 (1.1 KB)  TX bytes:648 (648.0 B)
 ```
 
-The `none` network adds a container to a container-specific network stack. That container lacks a network interface. Attaching to such a container and looking at it's stack you see this:
+The `none` network adds a container to a container-specific network stack. That container lacks a network interface. Attaching to such a container and looking at its stack you see this:
 
 ```
 $ docker attach nonenetcontainer
diff --git a/docs/userguide/networking/work-with-networks.md b/docs/userguide/networking/work-with-networks.md
index 867c5fa52f..481083bbef 100644
--- a/docs/userguide/networking/work-with-networks.md
+++ b/docs/userguide/networking/work-with-networks.md
@@ -289,7 +289,7 @@ examine its networking stack:
 $ docker attach container2
 ```
 
-If you look a the container's network stack you should see two Ethernet interfaces, one for the default bridge network and one for the `isolated_nw` network.
+If you look at the container's network stack you should see two Ethernet interfaces, one for the default bridge network and one for the `isolated_nw` network.
 
 ```bash
 / # ifconfig
diff --git a/docs/userguide/storagedriver/device-mapper-driver.md b/docs/userguide/storagedriver/device-mapper-driver.md
index 90f7424b9d..df089d319d 100644
--- a/docs/userguide/storagedriver/device-mapper-driver.md
+++ b/docs/userguide/storagedriver/device-mapper-driver.md
@@ -212,7 +212,7 @@ a `direct-lvm` configuration.
 > and have images you want to keep, `push` them Docker Hub or your private
 > Docker Trusted Registry before attempting this procedure.
 
-The procedure below will create a 90GB data volume and 4GB metadata volume to
+The procedure below will create a logical volume configured as a thin pool to
 use as backing for the storage pool. It assumes that you have a spare block
 device at `/dev/xvdf` with enough free space to complete the task. The device
 identifier and volume sizes may be be different in your environment and you
@@ -221,106 +221,146 @@ assumes that the Docker daemon is in the `stopped` state.
 
 1. Log in to the Docker host you want to configure and stop the Docker daemon.
 
-2. If it exists, delete your existing image store by removing the
-`/var/lib/docker` directory.
+2. Install the LVM2 package.
+	The LVM2 package includes the userspace toolset that provides logical volume
+	management facilities on linux.
+
+3. Create a physical volume replacing `/dev/xvdf` with your block device.
 
 	```bash
-	$ sudo rm -rf /var/lib/docker
+	$ pvcreate /dev/xvdf
 	```
 
-3. Create an LVM physical volume (PV) on your spare block device using the
-`pvcreate` command.
+4. Create a 'docker' volume group.
 
 	```bash
-	$ sudo pvcreate /dev/xvdf
-	Physical volume `/dev/xvdf` successfully created
+	$ vgcreate docker /dev/xvdf
 	```
 
-	The device identifier may be different on your system. Remember to substitute
-	your value in the command above. If your host is running on AWS EC2, you may
-	need to install `lvm2` and <a href="http://goo.gl/Q5pUwG"
-	target="_blank">attach an EBS device</a> to use this procedure.
+5. Create a thin pool named `thinpool`.
 
-4. Create a new volume group (VG) called `vg-docker` using the PV created in
-the previous step.
+	In this example, the data logical is 95% of the 'docker' volume group size.
+	Leaving this free space allows for auto expanding of either the data or
+	metadata if space runs low as a temporary stopgap.
 
 	```bash
-	$ sudo vgcreate vg-docker /dev/xvdf
-	Volume group `vg-docker` successfully created
+	$ lvcreate --wipesignatures y -n thinpool docker -l 95%VG
+	$ lvcreate --wipesignatures y -n thinpoolmeta docker -l 1%VG
 	```
 
-5. Create a new 90GB logical volume (LV) called `data` from space in the
-`vg-docker` volume group.
+6. Convert the pool to a thin pool.
 
 	```bash
-	$ sudo lvcreate -L 90G -n data vg-docker
-	Logical volume `data` created.
+	$ lvconvert -y --zero n -c 512K --thinpool docker/thinpool --poolmetadata docker/thinpoolmeta
+	```
+
+7. Configure autoextension of thin pools via an `lvm` profile.
+
+	```bash
+	$ vi /etc/lvm/profile/docker-thinpool.profile
+	```
+
+8. Specify 'thin_pool_autoextend_threshold' value.
+
+	The value should be the percentage of space used before `lvm` attempts
+	to autoextend the available space (100 = disabled).
+
+	```
+	thin_pool_autoextend_threshold = 80
+	```
+
+9. Modify the `thin_pool_autoextend_percent` for when thin pool autoextension occurs.
+
+	The value's setting is the perentage of space to increase the thin pool (100 =
+	disabled)
+
 	```
+	thin_pool_autoextend_percent = 20
+	```
+
+10. Check your work, your `docker-thinpool.profile` file should appear similar to the following:
 
-	The command creates an LVM logical volume called `data` and an associated
-	block device file at `/dev/vg-docker/data`. In a later step, you instruct the
-	`devicemapper` storage driver to use this block device to store image and
-	container data.
+	An example `/etc/lvm/profile/docker-thinpool.profile` file:
 
-	If you receive a signature detection warning, make sure you are working on
-	the correct devices before continuing. Signature warnings indicate that the
-	device you're working on is currently in use by LVM or has been used by LVM in
-	the past.
+	```
+	activation {
+		thin_pool_autoextend_threshold=80
+		thin_pool_autoextend_percent=20
+	}
+	```
+
+11. Apply your new lvm profile
+
+	```bash
+	$ lvchange --metadataprofile docker-thinpool docker/thinpool
+	```
 
-6. Create a new logical volume (LV) called `metadata` from space in the
-`vg-docker` volume group.
+12. Verify the `lv` is monitored.
 
 	```bash
-	$ sudo lvcreate -L 4G -n metadata vg-docker
-	Logical volume `metadata` created.
+	$ lvs -o+seg_monitor
 	```
 
-	This creates an LVM logical volume called `metadata` and an associated
-	block device file at `/dev/vg-docker/metadata`. In the next step you instruct
-	the `devicemapper` storage driver to use this block device to store image and
-	container metadata.
+13. If the Docker daemon was previously started, clear your graph driver directory.
+
+	Clearing your graph driver removes any images, containers, and volumes in your
+	Docker installation.
 
-7. Start the Docker daemon with the `devicemapper` storage driver and the
-`--storage-opt` flags.
+	```bash
+	$ rm -rf /var/lib/docker/*
+	```
 
-	The `data` and `metadata` devices that you pass to the `--storage-opt`
-	options were created in the previous steps.
+14. Configure the Docker daemon with specific devicemapper options.
+
+	There are two ways to do this. You can set options on the commmand line if you start the daemon there:
 
 	```bash
-	$ sudo docker daemon --storage-driver=devicemapper --storage-opt dm.datadev=/dev/vg-docker/data --storage-opt dm.metadatadev=/dev/vg-docker/metadata &
-	[1] 2163
-	[root@ip-10-0-0-75 centos]# INFO[0000] Listening for HTTP on unix (/var/run/docker.sock)
-	INFO[0027] Option DefaultDriver: bridge
-	INFO[0027] Option DefaultNetwork: bridge
-	<-- output truncated -->
-	INFO[0027] Daemon has completed initialization
-	INFO[0027] Docker daemon commit=1b09a95 graphdriver=aufs version=1.11.0-dev
+	--storage-driver=devicemapper --storage-opt=dm.thinpooldev=/dev/mapper/docker-thinpool --storage-opt dm.use_deferred_removal=true
 	```
 
-	It is also possible to set the `--storage-driver` and `--storage-opt` flags
-	in the Docker config file and start the daemon normally using the `service` or
-	`systemd` commands.
+	You can also set them for startup in the `daemon.json` configuration, for example:
+
+	```json
+	 {
+		 "storage-driver": "devicemapper",
+		 "storage-opts": [
+			 "dm.thinpooldev=/dev/mapper/docker-thinpool",
+			 "dm.use_deferred_removal=true"
+		 ]
+	 }
+	```
 
-8. Use the `docker info` command to verify that the daemon is using `data` and
-`metadata` devices you created.
+15. If using systemd and modifying the daemon configuration via unit or drop-in file, reload systemd to scan for changes.
 
 	```bash
-	$ sudo docker info
-	INFO[0180] GET /v1.20/info
-	Containers: 0
-	Images: 0
-	Storage Driver: devicemapper
-	 Pool Name: docker-202:1-1032-pool
-	 Pool Blocksize: 65.54 kB
-	 Backing Filesystem: xfs
-	 Data file: /dev/vg-docker/data
-	 Metadata file: /dev/vg-docker/metadata
-	[...]
+	$ systemctl daemon-reload
 	```
 
-	The output of the command above shows the storage driver as `devicemapper`.
-	The last two lines also confirm that the correct devices are being used for
-	the `Data file` and the `Metadata file`.
+16. Start the Docker daemon.
+
+	```bash
+	$ systemctl start docker
+	```
+
+After you start the Docker daemon, ensure you monitor your thin pool and volume
+group free space. While the volume group will auto-extend, it can still fill
+up. To monitor logical volumes, use `lvs` without options or `lvs -a` to see tha
+data and metadata sizes. To monitor volume group free space, use the `vgs` command.
+
+Logs can show the auto-extension of the thin pool when it hits the threshold, to
+view the logs use:
+
+```bash
+$ journalctl -fu dm-event.service
+```
+
+If you run into repeated problems with thin pool, you can use the
+`dm.min_free_space` option to tune the Engine behavior. This value ensures that
+operations fail with a warning when the free space is at or near the minimum.
+For information, see <a
+href="../../../reference/commandline/daemon/#storage-driver-options"
+target="_blank">the storage driver options in the Engine daemon reference</a>.
+
 
 ### Examine devicemapper structures on the host
 
@@ -329,20 +369,20 @@ You can use the `lsblk` command to see the device files created above and the
 
 ```bash
 $ sudo lsblk
-NAME                       MAJ:MIN RM  SIZE RO TYPE MOUNTPOINT
-xvda                       202:0    0    8G  0 disk
-└─xvda1                    202:1    0    8G  0 part /
-xvdf                       202:80   0   10G  0 disk
-├─vg--docker-data          253:0    0   90G  0 lvm
-│ └─docker-202:1-1032-pool 253:2    0   10G  0 dm
-└─vg--docker-metadata      253:1    0    4G  0 lvm
-  └─docker-202:1-1032-pool 253:2    0   10G  0 dm
+NAME			   MAJ:MIN RM  SIZE RO TYPE MOUNTPOINT
+xvda			   202:0	0	 8G  0 disk
+└─xvda1			   202:1	0	 8G  0 part /
+xvdf			   202:80	0	10G  0 disk
+├─vg--docker-data		   253:0	0	90G  0 lvm
+│ └─docker-202:1-1032-pool 253:2	0	10G  0 dm
+└─vg--docker-metadata	   253:1	0	 4G  0 lvm
+  └─docker-202:1-1032-pool 253:2	0	10G  0 dm
 ```
 
 The diagram below shows the image from prior examples updated with the detail
 from the `lsblk` command above.
 
-![](http://farm1.staticflickr.com/703/22116692899_0471e5e160_b.jpg)
+![](images/lsblk-diagram.jpg)
 
 In the diagram, the pool is named `Docker-202:1-1032-pool` and spans the `data`
 and `metadata` devices created earlier. The `devicemapper` constructs the pool
@@ -371,7 +411,8 @@ capacity.
 
 ### For a loop-lvm configuration
 
-In this scenario, the thin pool is configured to use `loop-lvm` mode. To show the specifics of the existing configuration use `docker info`:
+In this scenario, the thin pool is configured to use `loop-lvm` mode. To show
+the specifics of the existing configuration use `docker info`:
 
 ```bash
 $ sudo docker info
@@ -426,12 +467,10 @@ The `Data Space` values show that the pool is 100GB total. This example extends
 3. Verify the file size changed.
 
 	```bash
-	$ sudo ls -al /var/lib/docker/devicemapper/devicemapper/
-	total 1175492
-	drwx------ 2 root root         4096 Mar 29 02:45 .
-	drwx------ 5 root root         4096 Mar 29 02:48 ..
-	-rw------- 1 root root 214748364800 Mar 31 11:20 data
-	-rw------- 1 root root   2147483648 Mar 31 11:17 metadata
+	$ sudo ls -lh /var/lib/docker/devicemapper/devicemapper/
+	total 1.2G
+	-rw------- 1 root root 200G Apr 14 08:47 data
+	-rw------- 1 root root 2.0G Apr 19 13:27 metadata
 	```
 
 4. Reload data loop device
@@ -448,23 +487,35 @@ The `Data Space` values show that the pool is 100GB total. This example extends
 
 	a. Get the pool name first.
 
-		$ sudo dmsetup status docker-8:1-123141-pool: 0 209715200 thin-pool 91
-		422/524288 18338/1638400 - rw discard_passdown queue_if_no_space -
+	```bash
+	$ sudo dmsetup status | grep pool
+	docker-8:1-123141-pool: 0 209715200 thin-pool 91
+	422/524288 18338/1638400 - rw discard_passdown queue_if_no_space -
+	```
 
-		The name is the string before the colon.
+	The name is the string before the colon.
 
- 	b. Dump the device mapper table first.
+	b. Dump the device mapper table first.
 
-		$ sudo dmsetup table docker-8:1-123141-pool
-		0 209715200 thin-pool 7:1 7:0 128 32768 1 skip_block_zeroing
+	```bash
+	$ sudo dmsetup table docker-8:1-123141-pool
+	0 209715200 thin-pool 7:1 7:0 128 32768 1 skip_block_zeroing
+	```
 
 	c. Calculate the real total sectors of the thin pool now.
 
-		Change the second number of the table info (i.e. the disk end sector) to reflect the new number of 512 byte sectors in the disk. For example, as the new loop size is 200GB, change the second number to 419430400.
+	Change the second number of the table info (i.e. the disk end sector) to
+	reflect the new number of 512 byte sectors in the disk. For example, as the
+	new loop size is 200GB, change the second number to 419430400.
+
 
 	d. Reload the thin pool with the new sector number
 
-		$ sudo dmsetup suspend docker-8:1-123141-pool && sudo dmsetup reload docker-8:1-123141-pool --table '0 419430400 thin-pool 7:1 7:0 128 32768 1 skip_block_zeroing' && sudo dmsetup resume docker-8:1-123141-pool
+	```bash
+	$ sudo dmsetup suspend docker-8:1-123141-pool \
+	    && sudo dmsetup reload docker-8:1-123141-pool --table '0 419430400 thin-pool 7:1 7:0 128 32768 1 skip_block_zeroing' \
+	    && sudo dmsetup resume docker-8:1-123141-pool
+	```
 
 #### The device_tool
 
@@ -506,29 +557,39 @@ disk partition.
 
 	a. Get the pool name.
 
-		$ sudo dmsetup status | grep pool
-		docker-253:17-1835016-pool: 0 96460800 thin-pool 51593 6270/1048576 701943/753600 - rw no_discard_passdown queue_if_no_space
+	```bash
+	$ sudo dmsetup status | grep pool
+	docker-253:17-1835016-pool: 0 96460800 thin-pool 51593 6270/1048576 701943/753600 - rw no_discard_passdown queue_if_no_space
+	```
 
-		The name is the string before the colon.
+	The name is the string before the colon.
 
 	b. Dump the device mapper table.
 
-		$ sudo dmsetup table docker-253:17-1835016-pool
-		0 96460800 thin-pool 252:0 252:1 128 32768 1 skip_block_zeroing
+	```bash
+	$ sudo dmsetup table docker-253:17-1835016-pool
+	0 96460800 thin-pool 252:0 252:1 128 32768 1 skip_block_zeroing
+	```
 
 	c. Calculate the real total sectors of the thin pool now. we can use `blockdev` to get the real size of data lv.
 
-		Change the second number of the table info (i.e. the disk end sector) to
-		reflect the new number of 512 byte sectors in the disk. For example, as the
-		new data `lv` size is `264132100096` bytes, change the second number to
-		`515883008`.
+	Change the second number of the table info (i.e. the number of sectors) to
+	reflect the new number of 512 byte sectors in the disk. For example, as the
+	new data `lv` size is `264132100096` bytes, change the second number to
+	`515883008`.
 
-		$ sudo blockdev --getsize64 /dev/vg-docker/data
-		264132100096
+	```bash
+	$ sudo blockdev --getsize64 /dev/vg-docker/data
+	264132100096
+	```
 
 	d. Then reload the thin pool with the new sector number.
 
-		$ sudo dmsetup suspend docker-253:17-1835016-pool && sudo dmsetup reload docker-253:17-1835016-pool --table  '0 515883008 thin-pool 252:0 252:1 128 32768 1 skip_block_zeroing' && sudo dmsetup resume docker-253:17-1835016-pool
+	```bash
+	$ sudo dmsetup suspend docker-253:17-1835016-pool \
+	    && sudo dmsetup reload docker-253:17-1835016-pool --table  '0 515883008 thin-pool 252:0 252:1 128 32768 1 skip_block_zeroing' \
+	    && sudo dmsetup resume docker-253:17-1835016-pool
+	```
 
 ## Device Mapper and Docker performance
 
@@ -570,20 +631,20 @@ There are several other things that impact the performance of the
 `devicemapper` storage driver.
 
 - **The mode.** The default mode for Docker running the `devicemapper` storage
-driver is `loop-lvm`. This mode uses sparse files and suffers from poor
-performance. It is **not recommended for production**. The recommended mode for
- production environments is `direct-lvm` where the storage driver writes
-directly to raw block devices.
+  driver is `loop-lvm`. This mode uses sparse files and suffers from poor
+  performance. It is **not recommended for production**. The recommended mode for
+  production environments is `direct-lvm` where the storage driver writes
+  directly to raw block devices.
 
 - **High speed storage.** For best performance you should place the `Data file`
- and `Metadata file` on high speed storage such as SSD. This can be direct
-attached storage or from a SAN or NAS array.
+  and `Metadata file` on high speed storage such as SSD. This can be direct
+  attached storage or from a SAN or NAS array.
 
 - **Memory usage.** `devicemapper` is not the most memory efficient Docker
-storage driver. Launching *n* copies of the same container loads *n* copies of
-its files into memory. This can have a memory impact on your Docker host. As a
-result, the `devicemapper` storage driver may not be the best choice for PaaS
-and other high density use cases.
+  storage driver. Launching *n* copies of the same container loads *n* copies of
+  its files into memory. This can have a memory impact on your Docker host. As a
+  result, the `devicemapper` storage driver may not be the best choice for PaaS
+  and other high density use cases.
 
 One final point, data volumes provide the best and most predictable
 performance. This is because they bypass the storage driver and do not incur
diff --git a/docs/userguide/storagedriver/images/lsblk-diagram.jpg b/docs/userguide/storagedriver/images/lsblk-diagram.jpg
new file mode 100644
index 0000000000..641f780535
--- /dev/null
+++ b/docs/userguide/storagedriver/images/lsblk-diagram.jpg
diff --git a/docs/userguide/storagedriver/selectadriver.md b/docs/userguide/storagedriver/selectadriver.md
index a741a137c8..71bc4473c7 100644
--- a/docs/userguide/storagedriver/selectadriver.md
+++ b/docs/userguide/storagedriver/selectadriver.md
@@ -40,10 +40,10 @@ driver names:
 |AUFS          |`aufs`               |
 |Btrfs         |`btrfs`              |
 |Device Mapper |`devicemapper`       |
-|VFS*          |`vfs`                |
+|VFS           |`vfs`                |
 |ZFS           |`zfs`                |
 
-To find out which storage driver is set on the daemon , you use the
+To find out which storage driver is set on the daemon, you use the
 `docker info` command:
 
     $ docker info
@@ -71,18 +71,18 @@ For example, the `btrfs` storage driver on a Btrfs backing filesystem. The
 following table lists each storage driver and whether it must match the host's
 backing file system:
 
-|Storage driver |Must match backing filesystem |Incompatible with   |
-|---------------|------------------------------|--------------------|
-|`overlay`      |No                            |`btrfs` `aufs` `zfs`|
-|`aufs`         |No                            |`btrfs` `aufs`      |
-|`btrfs`        |Yes                           |   N/A              |
-|`devicemapper` |No                            |   N/A              |
-|`vfs`          |No                            |   N/A              |
-|`zfs`          |Yes                           |   N/A              |
+|Storage driver |Commonly used on |Disabled on                   |
+|---------------|-----------------|------------------------------|
+|`overlay`      |`ext4` `xfs`     |`btrfs` `aufs` `overlay` `zfs`|
+|`aufs`         |`ext4` `xfs`     |`btrfs` `aufs`                |
+|`btrfs`        |`btrfs` _only_   |   N/A                        |
+|`devicemapper` |`direct-lvm`     |   N/A                        |
+|`vfs`          |debugging only   |   N/A                        |
+|`zfs`          |`zfs` _only_     |   N/A                        |
 
 
 > **Note**
-> Incompatible with means some storage drivers can not run over certain backing
+> "Disabled on" means some storage drivers can not run over certain backing
 > filesystem.
 
 You can set the storage driver by passing the `--storage-driver=<name>` option
diff --git a/man/docker-cp.1.md b/man/docker-cp.1.md
index 84d64c2688..949d60bb8b 100644
--- a/man/docker-cp.1.md
+++ b/man/docker-cp.1.md
@@ -78,7 +78,16 @@ you must be explicit with a relative or absolute path, for example:
     `/path/to/file:name.txt` or `./file:name.txt`
 
 It is not possible to copy certain system files such as resources under
-`/proc`, `/sys`, `/dev`, and mounts created by the user in the container.
+`/proc`, `/sys`, `/dev`, tmpfs, and mounts created by the user in the container.
+However, you can still copy such files by manually running `tar` in `docker exec`.
+For example (consider `SRC_PATH` and `DEST_PATH` are directories):
+
+    $ docker exec foo tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | tar Cxf DEST_PATH -
+
+or
+
+    $ tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | docker exec -i foo tar Cxf DEST_PATH -
+
 
 Using `-` as the `SRC_PATH` streams the contents of `STDIN` as a tar archive.
 The command extracts the content of the tar to the `DEST_PATH` in container's