Storage driver followup (docker#3386)

* Fix picky formatting errors

* Address post-merge feedback

* Changing the storage driver on D4M/D4W not supported

Author: Misty Stanley-Jones

engine/installation/linux/suse.md

@@ -180,9 +180,12 @@ the repository.
     $ sudo zypper install docker-ee-<VERSION_STRING>
     ```
 
-4.  Configure Docker to use the `btrfs` filesystem. Edit the file
-    `/etc/docker/daemon.json` (create it if it does not exist) and add the
-    following contents:
+4.  Configure Docker to use the `btrfs` filesystem. **This is only required if
+    the `/` filesystem is not using BTRFS.** However, explicitly specifying the
+    `storage-driver` has no harmful side effects.
+
+    Edit the file `/etc/docker/daemon.json` (create it if it does not exist) and
+    add the following contents:
 
     ```json
     {
@@ -243,9 +246,12 @@ need to download a new file each time you want to upgrade Docker.
     $ sudo zypper install /path/to/package.rpm
     ```
 
-4.  Configure Docker to use the `btrfs` filesystem. Edit the file
-    `/etc/docker/daemon.json` (create it if it does not exist) and add the
-    following contents:
+4.  Configure Docker to use the `btrfs` filesystem. **This is only required if
+    the `/` filesystem is not using BTRFS.** However, explicitly specifying the
+    `storage-driver` has no harmful side effects.
+
+    Edit the file `/etc/docker/daemon.json` (create it if it does not exist) and
+    add the following contents:
 
     ```json
     {

engine/userguide/storagedriver/aufs-driver.md

@@ -64,12 +64,11 @@ storage driver is configured, Docker uses it by default.
     <truncated output>
     ```
 
-3.  If you are using a different storage driver, then it means that either AUFS
-    is not included in the kernel (in which case a different default driver will
-    be used) or that means that Docker has been explicitly configured to use a
-    different driver. Check `/etc/docker/daemon.json` or the output of
-    `ps auxw |grep dockerd` to see if Docker has been started with the
-    `--storage-driver` flag.
+3.  If you are using a different storage driver, either AUFS is not included in
+    the kernel (in which case a different default driver will be used) or that
+    Docker has been explicitly configured to use a different driver. Check
+    `/etc/docker/daemon.json` or the output of `ps auxw | grep dockerd` to see
+    if Docker has been started with the `--storage-driver` flag.
 
 
 ## How the `aufs` storage driver works
@@ -112,6 +111,9 @@ Status: Downloaded newer image for ubuntu:latest
 
 #### The image layers
 
+> **Warning**: Do not directly manipulate any files or directories within
+> `/var/lib/docker/`. These files and directories are managed by Docker.
+
 All of the information about the image and container layers is stored in
 subdirectories of `/var/lib/docker/aufs/`.
 
@@ -129,10 +131,6 @@ subdirectories of `/var/lib/docker/aufs/`.
 If a container is running, the contents of `/var/lib/docker/aufs/` change in the
 following ways:
 
-> **Note**: If you see files or directories which end in `-init`, these are used
-> to prepare the container to use bind mounts, and should be considered an
-> implementation detail.
-
 - `diff/`: Differences introduced in the writable container layer, such as new
    or modified files.
 - `layers/`: Metadata about the writable container layer's parent layers.

engine/userguide/storagedriver/device-mapper-driver.md

@@ -203,16 +203,16 @@ assumes that the Docker daemon is in the `stopped` state.
     the thin pool, using the `lgconvert` command.
 
     ```none
-      $ sudo lvconvert -y \
-      --zero n \
-      -c 512K \
-      --thinpool docker/thinpool \
-      --poolmetadata docker/thinpoolmeta
-
-      WARNING: Converting logical volume docker/thinpool and docker/thinpoolmeta to thin pool's data and metadata volumes with metadata wiping.
-      THIS WILL DESTROY CONTENT OF LOGICAL VOLUME (filesystem etc.)
-      Converted docker/thinpool to thin pool.
-      ```
+    $ sudo lvconvert -y \
+    --zero n \
+    -c 512K \
+    --thinpool docker/thinpool \
+    --poolmetadata docker/thinpoolmeta
+
+    WARNING: Converting logical volume docker/thinpool and docker/thinpoolmeta to thin pool's data and metadata volumes with metadata wiping.
+    THIS WILL DESTROY CONTENT OF LOGICAL VOLUME (filesystem etc.)
+    Converted docker/thinpool to thin pool.
+    ```
 
 8.  Create an LVM profile that will enable automatic extension of the thin
     pool. Edit the file `/etc/lvm/profile/docker-thinpool.profile` and add the
@@ -247,12 +247,12 @@ assumes that the Docker daemon is in the `stopped` state.
     The example below will add 20% more capacity when the disk usage reaches
     80%.
 
-      ```none
-      activation {
-        thin_pool_autoextend_threshold=80
-        thin_pool_autoextend_percent=20
-      }
-      ```
+    ```none
+    activation {
+      thin_pool_autoextend_threshold=80
+      thin_pool_autoextend_percent=20
+    }
+    ```
 
     Save the file.
 
@@ -303,7 +303,7 @@ assumes that the Docker daemon is in the `stopped` state.
 
 13. Start Docker.
 
- 	  **systemd**:
+    **systemd**:
 
     ```bash
     $ sudo systemctl start docker
@@ -487,19 +487,15 @@ thin pool is 100 GB, and is increased to 200 GB.
     a.  Get the pool name first. The pool name is the first field, delimited by
         ` :`. This command extracts it.
 
-        ```bash
-        $ sudo dmsetup status | grep ' thin-pool ' | awk -F ': ' {'print $1'}
+            $ sudo dmsetup status | grep ' thin-pool ' | awk -F ': ' {'print $1'}
 
-        docker-8:1-123141-pool
-        ```
+            docker-8:1-123141-pool
 
     b.  Dump the device mapper table for the thin pool.
 
-        ```bash
-        $ sudo dmsetup table docker-8:1-123141-pool
+            $ sudo dmsetup table docker-8:1-123141-pool
 
-        0 209715200 thin-pool 7:1 7:0 128 32768 1 skip_block_zeroing
-        ```
+            0 209715200 thin-pool 7:1 7:0 128 32768 1 skip_block_zeroing
 
     c.  Calculate the total sectors of the thin pool using the second field
         of the output. The number is expressed in 512-k sectors. A 100G file has
@@ -509,13 +505,12 @@ thin pool is 100 GB, and is increased to 200 GB.
     d.  Reload the thin pool with the new sector number, using the following
         three `dmsetup`  commands.
 
-        ```bash
-        $ sudo dmsetup suspend docker-8:1-123141-pool
+            $ 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 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
 
-        $ sudo dmsetup resume docker-8:1-123141-pool
-        ```
 
 #### Resize a direct-lvm thin pool
 

engine/userguide/storagedriver/imagesandcontainers.md

@@ -43,69 +43,12 @@ new files, modifying existing files, and deleting files, are written to this thi
 writable container layer. The diagram below shows a container based on the Ubuntu
 15.04 image.
 
-The diagram below shows a container with the Ubuntu 15.04 image comprising 4
-stacked image layers, and the writable container layer on top.
-
 ![Docker image layers](images/container-layers.jpg)
 
 A _storage driver_ handles the details about the way these layers interact with
 each other. Different storage drivers are available, which have advantages
 and disadvantages in different situations.
 
-### Content addressable storage
-
-If you are already running Docker 1.10 or higher, you can skip this section and
-go straight to [Containers and layers](#containers-and-layers).
-
-Docker 1.10 introduced a new content addressable storage model. This is a
-completely new way to address image and layer data on disk. Previously, image
-and layer data was referenced and stored using a randomly generated UUID. In
-the new model this is replaced by a secure *content hash*.
-
-The new model improves security, provides a built-in way to avoid ID
-collisions, and guarantees data integrity after pull, push, load, and save
-operations. It also enables better sharing of layers by allowing many images to
-freely share their layers even if they didn’t come from the same build.
-
-The diagram below shows an updated version of the previous diagram,
-highlighting the changes implemented by Docker 1.10.
-
-![](images/container-layers-cas.jpg)
-
-All image layer IDs are cryptographic hashes, whereas the container ID is still
-a randomly generated UUID.
-
-The new model requires you to migrate existing images from Docker 1.9 and
-earlier, and it includes several changes to the filesystem structure of images
-and layers. If you are already running Docker 1.10 or higher, you can skip this
-section.
-
-Images created within Docker 1.9 or earlier need to be migrated before they can
-be used with the new model. This migration involves calculating new secure
-checksums and is performed automatically the first time you start an updated
-Docker daemon. After the migration is complete, all images and tags will have
-brand new secure IDs.
-
-Although the migration is automatic and transparent, it is computationally
-intensive. It may take some time to complete, and during this time, Docker will
-not respond to other requests. If this is a problem, you can use a
-[migration tool](https://github.com/docker/v1.10-migrator/releases) to migrate
-existing images to the new format before upgrading Docker. This avoids
-downtime and allows you to distribute migrated images to systems that have
-already been upgraded. For more information, see
-[https://github.com/docker/v1.10-migrator/releases](https://github.com/docker/v1.10-migrator/releases).
-
-During the migration, you need to expose your Docker host's data directory to
-the migration container. If you are using the default Docker data path, use a
-command like the following:
-
-```bash
-$ sudo docker run --rm -v /var/lib/docker:/var/lib/docker docker/v1.10-migrator
-```
-
-If you use the `devicemapper` storage driver, you need to include the
-`--privileged` option so that the container has access to your storage devices.
-
 ## Container and layers
 
 The major difference between a container and an image is the top writable layer.

engine/userguide/storagedriver/overlayfs-driver.md

@@ -484,19 +484,19 @@ The following generic performance best practices also apply to OverlayFS.
 To summarize the OverlayFS's aspect which is incompatible with other
 filesystems:
 
-- **open(2)**. OverlayFS only implements a subset of the POSIX standards.
-This can result in certain OverlayFS operations breaking POSIX standards. One
-such operation is the *copy-up* operation. Suppose that  your application calls
-`fd1=open("foo", O_RDONLY)` and then `fd2=open("foo", O_RDWR)`. In this case,
-your application expects `fd1` and `fd2` to refer to the same file. However, due
-to a copy-up operation that occurs after the first calling to `open(2)`, the
-descriptors refer to different files.
-
-`yum` is known to be affected unless the `yum-plugin-ovl` package is installed.
-If the `yum-plugin-ovl` package is not available in your distribution (e.g.
-RHEL/CentOS prior to 6.8 or 7.2), you may need to run `touch /var/lib/rpm/*`
-before running `yum install`.
-
-- **rename(2)**. OverlayFS does not fully support the `rename(2)` system call.
-Your application needs to detect its failure and fall back to a "copy and
-unlink" strategy.
+- **open(2)**: OverlayFS only implements a subset of the POSIX standards.
+  This can result in certain OverlayFS operations breaking POSIX standards. One
+  such operation is the *copy-up* operation. Suppose that  your application calls
+  `fd1=open("foo", O_RDONLY)` and then `fd2=open("foo", O_RDWR)`. In this case,
+  your application expects `fd1` and `fd2` to refer to the same file. However, due
+  to a copy-up operation that occurs after the first calling to `open(2)`, the
+  descriptors refer to different files.
+
+  `yum` is known to be affected unless the `yum-plugin-ovl` package is installed.
+  If the `yum-plugin-ovl` package is not available in your distribution (e.g.
+  RHEL/CentOS prior to 6.8 or 7.2), you may need to run `touch /var/lib/rpm/*`
+  before running `yum install`.
+
+- **rename(2)**: OverlayFS does not fully support the `rename(2)` system call.
+  Your application needs to detect its failure and fall back to a "copy and
+  unlink" strategy.

engine/userguide/storagedriver/selectadriver.md

@@ -98,9 +98,9 @@ to the container's writable layer.
 
 ### Docker for Mac and Docker for Windows
 
-Docker for Mac and Docker for Windows only support `overlay2` `aufs`, or
-`overlay`. However, `overlay` is not recommended. `aufs` is the default in
-stable releases and `overlay2` is the default in Edge releases. In addition,
+Docker for Mac and Docker for Windows are intended for development, rather
+than production. Modifying the storage driver on these platforms is not
+supported.
 
 ## Supported backing filesystems
 
@@ -149,7 +149,7 @@ Each Docker storage driver is based on a Linux filesystem or volume manager. Be
 sure to follow existing best practices for operating your storage driver
 (filesystem or volume manager) on top of your shared storage system. For
 example, if using the ZFS storage driver on top of a shared storage system, be
-sure to follow best practices for operating aZFS filesystems on top of that
+sure to follow best practices for operating ZFS filesystems on top of that
 specific shared storage system.
 
 ### Stability
@@ -198,9 +198,8 @@ Storage Driver: overlay
 
 To set the storage driver, set the option in the `daemon.json`
 file, which is located in `/etc/docker/` on Linux and
-`C:\ProgramData\docker\config\` on Windows Server. If you use Docker for Mac or
-Docker for Windows, click the Docker icon, choose **Preferences**, and choose
-**Daemon** on Docker for Mac or Docker for Windows.
+`C:\ProgramData\docker\config\` on Windows Server. Changing the storage driver
+on Docker for Mac or Docker for Windows is not supported.
 
 If the `daemon.json` file does not exist, create it. Assuming there are no other
 settings in the file, it should have the following contents:
@@ -216,14 +215,6 @@ You can specify any valid storage driver in place of `devicemapper`.
 Restart Docker for the changes to take effect. After restarting, run
 `docker info` again to verify that the new storage driver is being used.
 
-### Extra steps for Docker for Mac or Docker for Windows
-
-Before you change the default storage driver on Docker for Mac or Docker for
-Windows, it is recommended to do a factory reset to wipe the old storage
-location, since you will not be able to access it after you change the storage
-driver. If you need to save any containers, use `docker save` before doing the
-reset.
-
 ## Related information
 
 * [About images, containers, and storage drivers](imagesandcontainers.md)

engine/userguide/storagedriver/zfs-driver.md

@@ -87,7 +87,7 @@ use unless you have substantial experience with ZFS on Linux.
 
     Save and close the file.
 
-4.  Start docker. Use `docker info` to verify that the storage driver is `zfs`.
+4.  Start Docker. Use `docker info` to verify that the storage driver is `zfs`.
 
     ```bash
     $ sudo docker info
@@ -105,8 +105,8 @@ use unless you have substantial experience with ZFS on Linux.
        Space Available: 103498395648
        Parent Quota: no
        Compression: off
-      <output truncated>
-      ```
+    <output truncated>
+    ```
 
 ## Manage `zfs`