Add documentation for using overlay2

Add mention in dockerd command line and storage driver selection documentation.

Signed-off-by: Derek McGowan <derek@mcgstyle.net> (github: dmcgowan)

docs/reference/commandline/dockerd.md

@@ -142,7 +142,7 @@ precedence over `HTTP_PROXY`.
 ### Daemon storage-driver option
 
 The Docker daemon has support for several different image layer storage
-drivers: `aufs`, `devicemapper`, `btrfs`, `zfs` and `overlay`.
+drivers: `aufs`, `devicemapper`, `btrfs`, `zfs`, `overlay` and `overlay2`.
 
 The `aufs` driver is the oldest, but is based on a Linux kernel patch-set that
 is unlikely to be merged into the main kernel. These are also known to cause
@@ -180,9 +180,14 @@ Linux kernel as of [3.18.0](https://lkml.org/lkml/2014/10/26/137). Call
 > inode consumption (especially as the number of images grows), as well as
 > being incompatible with the use of RPMs.
 
+The `overlay2` uses the same fast union filesystem but takes advantage of
+[additional features](https://lkml.org/lkml/2015/2/11/106) added in Linux
+kernel 4.0 to avoid excessive inode consumption. Call `dockerd -s overlay2`
+to use it.
+
 > **Note:**
-> It is currently unsupported on `btrfs` or any Copy on Write filesystem
-> and should only be used over `ext4` partitions.
+> Both `overlay` and `overlay2` are currently unsupported on `btrfs` or any
+> Copy on Write filesystem and should only be used over `ext4` partitions.
 
 ### Storage driver options
 

docs/userguide/storagedriver/selectadriver.md

@@ -34,14 +34,14 @@ and all containers created by that daemon instance use the same storage driver.
  The table below shows the supported storage driver technologies and their
 driver names:
 
-|Technology    |Storage driver name  |
-|--------------|---------------------|
-|OverlayFS     |`overlay`            |
-|AUFS          |`aufs`               |
-|Btrfs         |`btrfs`              |
-|Device Mapper |`devicemapper`       |
-|VFS           |`vfs`                |
-|ZFS           |`zfs`                |
+|Technology    |Storage driver name    |
+|--------------|-----------------------|
+|OverlayFS     |`overlay` or `overlay2`|
+|AUFS          |`aufs`                 |
+|Btrfs         |`btrfs`                |
+|Device Mapper |`devicemapper`         |
+|VFS           |`vfs`                  |
+|ZFS           |`zfs`                  |
 
 To find out which storage driver is set on the daemon, you use the
 `docker info` command:
@@ -71,14 +71,15 @@ 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 |Commonly used on |Disabled on                              |
-|---------------|-----------------|-----------------------------------------|
-|`overlay`      |`ext4` `xfs`     |`btrfs` `aufs` `overlay` `zfs` `eCryptfs`|
-|`aufs`         |`ext4` `xfs`     |`btrfs` `aufs` `eCryptfs`                |
-|`btrfs`        |`btrfs` _only_   |   N/A                                   |
-|`devicemapper` |`direct-lvm`     |   N/A                                   |
-|`vfs`          |debugging only   |   N/A                                   |
-|`zfs`          |`zfs` _only_     |   N/A                                   |
+|Storage driver |Commonly used on |Disabled on                                         |
+|---------------|-----------------|----------------------------------------------------|
+|`overlay`      |`ext4` `xfs`     |`btrfs` `aufs` `overlay` `overlay2` `zfs` `eCryptfs`|
+|`overlay2`     |`ext4` `xfs`     |`btrfs` `aufs` `overlay` `overlay2` `zfs` `eCryptfs`|
+|`aufs`         |`ext4` `xfs`     |`btrfs` `aufs` `eCryptfs`                           |
+|`btrfs`        |`btrfs` _only_   |   N/A                                              |
+|`devicemapper` |`direct-lvm`     |   N/A                                              |
+|`vfs`          |debugging only   |   N/A                                              |
+|`zfs`          |`zfs` _only_     |   N/A                                              |
 
 
 > **Note**
@@ -198,6 +199,24 @@ the guidance offered by the table below along with the points mentioned above.
 
 ![](images/driver-pros-cons.png)
 
+### Overlay vs Overlay2
+
+OverlayFS has 2 storage drivers which both make use of the same OverlayFS
+technology but with different implementations and incompatible on disk
+storage. Since the storage is incompatible, switching between the two
+will require re-creating all image content. The `overlay` driver is the
+original implementation and the only option in Docker 1.11 and before.
+The `overlay` driver has known limitations with inode exhaustion and
+commit performance. The `overlay2` driver addresses this limitation, but
+is only compatible with Linux kernel 4.0 and later. For users on a pre-4.0
+kernel or with an existing `overlay` graph, it is recommended to stay
+on `overlay`. For users with at least a 4.0 kernel and no existing or required
+`overlay` graph data, then `overlay2` may be used.
+
+> **Note**
+> `overlay2` graph data will not interfere with `overlay` graph data. However
+> when switching to `overlay2`, the user is responsible for removing
+> `overlay` graph data to avoid storage duplication.
 
 ## Related information
 

man/dockerd.8.md

@@ -226,7 +226,7 @@ output otherwise.
   Force the Docker runtime to use a specific storage driver.
 
 **--selinux-enabled**=*true*|*false*
-  Enable selinux support. Default is false. SELinux does not presently support the overlay storage driver.
+  Enable selinux support. Default is false. SELinux does not presently support either of the overlay storage drivers.
 
 **--storage-opt**=[]
   Set storage driver options. See STORAGE DRIVER OPTIONS.