Merge pull request #16287 from mikebrow/16055-man-update-for-docker-run-with-host-volumes

man update for docker run with host volumes

docs/reference/run.md

@@ -1309,12 +1309,16 @@ container's `/etc/hosts` entry will be automatically updated.
 
 ### VOLUME (shared filesystems)
 
-    -v=[]: Create a bind mount with: [host-dir:]container-dir[:rw|ro].
+    -v=[]: Create a bind mount with: [host-dir:]container-dir[:<options>], where
-           If 'host-dir' is missing, then docker creates a new volume.
+    options are comma delimited and selected from [rw|ro] and [z|Z]. 
+           If 'host-dir' is missing, then docker creates a new volume. 
 		   If neither 'rw' or 'ro' is specified then the volume is mounted
 		   in read-write mode.
     --volumes-from="": Mount all volumes from the given container(s)
 
+> **Note**:
+> The auto-creation of the host path has been [*deprecated*](/misc/deprecated/#auto-creating-missing-host-paths-for-bind-mounts).
+
 The volumes commands are complex enough to have their own documentation
 in section [*Managing data in
 containers*](/userguide/dockervolumes). A developer can define

docs/userguide/dockervolumes.md

@@ -142,7 +142,7 @@ Mounting a host directory can be useful for testing. For example, you can mount
 source code inside a container. Then, change the source code and see its effect
 on the application in real time. The directory on the host must be specified as
 an absolute path and if the directory doesn't exist Docker will automatically
-create it for you.
+create it for you.  This auto-creation of the host path has been [*deprecated*](/userguide/dockervolumes/#auto-creating-missing-host-paths-for-bind-mounts).
 
 Docker volumes default to mount in read-write mode, but you can also set it to
 be mounted read-only.
@@ -165,6 +165,20 @@ user with access to host and its mounted directory.
 >should be portable. A host directory wouldn't be available on all potential
 >hosts.
 
+### Volume labels
+
+Labeling systems like SELinux require that proper labels are placed on volume
+content mounted into a container. Without a label, the security system might
+prevent the processes running inside the container from using the content. By
+default, Docker does not change the labels set by the OS.
+
+To change a label in the container context, you can add either of two suffixes
+`:z` or `:Z` to the volume mount. These suffixes tell Docker to relabel file
+objects on the shared volumes. The `z` option tells Docker that two containers
+share the volume content. As a result, Docker labels the content with a shared
+content label. Shared volume labels allow all containers to read/write content.
+The `Z` option tells Docker to label the content with a private unshared label.
+Only the current container can use a private volume.
 
 ### Mount a host file as a data volume
 

man/docker-run.1.md

@@ -430,9 +430,17 @@ standard input.
 ""--ulimit""=[]
     Ulimit options
 
-**-v**, **--volume**=[]
+**-v**, **--volume**=[] Create a bind mount 
-   Bind mount a volume (e.g., from the host: -v /host:/container, from Docker: -v /container)
+   (format: `[host-dir:]container-dir[:<suffix options>]`, where suffix options
-
+are comma delimited and selected from [rw|ro] and [z|Z].)
+   
+   (e.g., using -v /host-dir:/container-dir, bind mounts /host-dir in the
+host to /container-dir in the Docker container)
+   
+   If 'host-dir' is missing, then docker automatically creates the new volume
+on the host. **This auto-creation of the host path has been deprecated in
+Release: v1.9.**
+   
    The **-v** option can be used one or
 more times to add one or more mounts to a container. These mounts can then be
 used in other containers using the **--volumes-from** option.
@@ -467,8 +475,6 @@ For example, you can specify either `/foo` or `foo` for a `host-dir` value.
 If you supply the `/foo` value, Docker creates a bind-mount. If you supply 
 the `foo` specification, Docker creates a named volume.
 
-**Note:** Multiple Volume options can be added separated by a , (comma).
-
 **--volumes-from**=[]
    Mount volumes from the specified container(s)