Merge pull request #6449 from DanHam/fix-device-mapper-doc

Fix device mapper doc

storage/storagedriver/device-mapper-driver.md

@@ -42,10 +42,18 @@ Before following these procedures, you must first meet all the
 
 ### Configure `loop-lvm` mode for testing
 
-This configuration is only appropriate for testing. Loopback devices are slow
+This configuration is only appropriate for testing. The `loop-lvm` mode makes
-and resource-intensive, and they require you to create file on disk at specific sizes.
+use of a 'loopback' mechanism that allows files on the local disk to be
-They can also introduce race conditions. They are available for testing because
+read from and written to as if they were an actual physical disk or block
-the setup is easier.
+device.
+However, the addition of the loopback mechanism, and interaction with the OS
+filesystem layer, means that IO operations can be slow and resource-intensive.
+Use of loopback devices can also introduce race conditions.
+However, setting up `loop-lvm` mode can help identify basic issues (such as
+missing user space packages, kernel drivers, etc.) ahead of attempting the more
+complex set up required to enable `direct-lvm` mode. `loop-lvm` mode should
+therefore only be used to perform rudimentary testing prior to configuring
+`direct-lvm`.
 
 For production systems, see
 [Configure direct-lvm mode for production](#configure-direct-lvm-mode-for-production).
@@ -100,7 +108,7 @@ For production systems, see
       Data Space Used: 11.8 MB
       Data Space Total: 107.4 GB
       Data Space Available: 7.44 GB
-      Metadata Space Used: 581.6 kB
+      Metadata Space Used: 581.6 KB
       Metadata Space Total: 2.147 GB
       Metadata Space Available: 2.147 GB
       Thin Pool Minimum Free Space: 10.74 GB
@@ -127,7 +135,7 @@ For production systems, see
 Production hosts using the `devicemapper` storage driver must use `direct-lvm`
 mode. This mode uses block devices to create the thin pool. This is faster than
 using loopback devices, uses system resources more efficiently, and block
-devices can grow as needed. However, more set-up is required than `loop-lvm`
+devices can grow as needed. However, more setup is required than in `loop-lvm`
 mode.
 
 After you have satisfied the [prerequisites](#prerequisites), follow the steps
@@ -255,7 +263,7 @@ assumes that the Docker daemon is in the `stopped` state.
 7.  Convert the volumes to a thin pool and a storage location for metadata for
     the thin pool, using the `lvconvert` command.
 
-    ```none
+    ```bash
     $ sudo lvconvert -y \
     --zero n \
     -c 512K \
@@ -303,23 +311,37 @@ assumes that the Docker daemon is in the `stopped` state.
     Logical volume docker/thinpool changed.
     ```
 
-11. Enable monitoring for logical volumes on your host. Without this step,
+11. Ensure monitoring of the logical volume is enabled.
-    automatic extension does not occur even in the presence of the LVM profile.
 
     ```bash
     $ sudo lvs -o+seg_monitor
 
     LV       VG     Attr       LSize  Pool Origin Data%  Meta%  Move Log Cpy%Sync Convert Monitor
-    thinpool docker twi-a-t--- 95.00g             0.00   0.01                             monitored
+    thinpool docker twi-a-t--- 95.00g             0.00   0.01                             not monitored
     ```
 
+    If the output in the `Monitor` column reports, as above, that the volume is
+    `not monitored`, then monitoring needs to be explicitly enabled. Without
+    this step, automatic extension of the logical volume will not occur,
+    regardless of any settings in the applied profile.
+
+    ```bash
+    $ sudo lvchange --monitor y docker/thinpool
+    ```
+
+    Double check that monitoring is now enabled by running the
+    `sudo lvs -o+seg_monitor` command a second time. The `Monitor` column
+    should now report the logical volume is being `monitored`.
+
 12. If you have ever run Docker on this host before, or if `/var/lib/docker/`
     exists, move it out of the way so that Docker can use the new LVM pool to
     store the contents of image and containers.
 
     ```bash
-    $ mkdir /var/lib/docker.bk
+    $ sudo su -
-    $ mv /var/lib/docker/* /var/lib/docker.bk
+    # mkdir /var/lib/docker.bk
+    # mv /var/lib/docker/* /var/lib/docker.bk
+    # exit
     ```
 
     If any of the following steps fail and you need to restore, you can remove
@@ -394,7 +416,7 @@ assumes that the Docker daemon is in the `stopped` state.
     `/var/lib/docker.bk` directory which contains the previous configuration.
 
     ```bash
-    $ rm -rf /var/lib/docker.bk
+    $ sudo rm -rf /var/lib/docker.bk
     ```
 
 ## Manage devicemapper
@@ -404,17 +426,17 @@ assumes that the Docker daemon is in the `stopped` state.
 Do not rely on LVM auto-extension alone. The volume group
 automatically extends, but the volume can still fill up. You can monitor
 free space on the volume using `lvs` or `lvs -a`. Consider using a monitoring
-tool at the OS level, such a Nagios.
+tool at the OS level, such as Nagios.
 
 To view the LVM logs, you can use `journalctl`:
 
 ```bash
-$ journalctl -fu dm-event.service
+$ sudo journalctl -fu dm-event.service
 ```
 
 If you run into repeated problems with thin pool, you can set the storage option
 `dm.min_free_space` to a value (representing a percentage) in
-`/etc/docker.daemon.json`. For instance, setting it to `10` ensures
+`/etc/docker/daemon.json`. For instance, setting it to `10` ensures
 that operations fail with a warning when the free space is at or near 10%.
 See the
 [storage driver options in the Engine daemon reference](/engine/reference/commandline/dockerd/#storage-driver-options){: target="_blank" class="_"}.