Merge pull request #32319 from thaJeztah/17.04.0-docs-cherry-picks

[17.04.x] docs cherry picks

api/swagger.yaml

@@ -244,6 +244,9 @@ definitions:
       ReadOnly:
         description: "Whether the mount should be read-only."
         type: "boolean"
+      Consistency:
+        description: "The consistency requirement for the mount: `default`, `consistent`, `cached`, or `delegated`."
+        type: "string"
       BindOptions:
         description: "Optional configuration for the `bind` type."
         type: "object"

docs/api/version-history.md

@@ -18,6 +18,7 @@ keywords: "API, Docker, rcli, REST, documentation"
 [Docker Engine API v1.28](https://docs.docker.com/engine/api/v1.28/) documentation
 
 
+* `POST /containers/create` now includes a `Consistency` field to specify the consistency level for each `Mount`, with possible values `default`, `consistent`, `cached`, or `delegated`.
 * `GET /containers/create` now takes a `DeviceCgroupRules` field in `HostConfig` allowing to set custom device cgroup rules for the created container.
 * Optional query parameter `verbose` for `GET /networks/(id or name)` will now list all services with all the tasks, including the non-local tasks on the given network.
 * `GET /containers/(id or name)/attach/ws` now returns WebSocket in binary frame format for API version >= v1.28, and returns WebSocket in text frame format for API version< v1.28, for the purpose of backward-compatibility.

docs/deprecated.md

@@ -40,7 +40,7 @@ docker 1.9, but kept around for backward compatibility.
 Refer to [#17538](https://github.com/docker/docker/pull/17538) for further
 information.
 
-## `filter` param for `/images/json` endpoint
+### `filter` param for `/images/json` endpoint
 **Deprecated In Release: [v1.13.0](https://github.com/docker/docker/releases/tag/v1.13.0)**
 
 **Target For Removal In Release: v17.12**

docs/extend/index.md

@@ -150,7 +150,7 @@ Consider the following `config.json` file.
 {
 	"description": "sshFS plugin for Docker",
 	"documentation": "https://docs.docker.com/engine/extend/plugins/",
-	"entrypoint": ["/go/bin/docker-volume-sshfs"],
+	"entrypoint": ["/docker-volume-sshfs"],
 	"network": {
 		   "type": "host"
 		   },
@@ -165,7 +165,7 @@ Consider the following `config.json` file.
 ```
 
 This plugin is a volume driver. It requires a `host` network and the
-`CAP_SYS_ADMIN` capability. It depends upon the `/go/bin/docker-volume-sshfs`
+`CAP_SYS_ADMIN` capability. It depends upon the `/docker-volume-sshfs`
 entrypoint and uses the `/run/docker/plugins/sshfs.sock` socket to communicate
 with Docker Engine. This plugin has no runtime parameters.
 

docs/extend/legacy_plugins.md

@@ -15,8 +15,6 @@ keywords: "Examples, Usage, plugins, docker, documentation, user guide"
      will be rejected.
 -->
 
-# Use Docker Engine plugins
-
 This document describes the Docker Engine plugins generally available in Docker
 Engine. To view information on plugins managed by Docker,
 refer to [Docker Engine plugin system](index.md).
@@ -60,6 +58,7 @@ Plugin
 Plugin                                                                              | Description
 ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 [Azure File Storage plugin](https://github.com/Azure/azurefile-dockervolumedriver)  | Lets you mount Microsoft [Azure File Storage](https://azure.microsoft.com/blog/azure-file-storage-now-generally-available/) shares to Docker containers as volumes using the SMB 3.0 protocol. [Learn more](https://azure.microsoft.com/blog/persistent-docker-volumes-with-azure-file-storage/).
+[BeeGFS Volume Plugin](https://github.com/RedCoolBeans/docker-volume-beegfs)        | An open source volume plugin to create persistent volumes in a BeeGFS parallel file system.
 [Blockbridge plugin](https://github.com/blockbridge/blockbridge-docker-volume)      | A volume plugin that provides access to an extensible set of container-based persistent storage options. It supports single and multi-host Docker environments with features that include tenant isolation, automated provisioning, encryption, secure deletion, snapshots and QoS.
 [Contiv Volume Plugin](https://github.com/contiv/volplugin)                         | An open source volume plugin that provides multi-tenant, persistent, distributed storage with intent based consumption. It has support for Ceph and NFS.
 [Convoy plugin](https://github.com/rancher/convoy)                                  | A volume plugin for a variety of storage back-ends including device mapper and NFS. It's a simple standalone executable written in Go and provides the framework to support vendor-specific extensions such as snapshots, backups and restore.
@@ -76,7 +75,7 @@ Plugin
 [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/ContainX/docker-volume-netshare)                 | A volume plugin that provides volume management for NFS 3/4, AWS EFS and CIFS file systems.
-[Nimble Storage Volume Plugin](https://connect.nimblestorage.com/community/app-integration/docker)| A volume plug-in that integrates with Nimble Storage Unified Flash Fabric arrays. The plug-in abstracts array volume capabilities to the Docker administrator to allow self-provisioning of secure multi-tenant volumes and clones. 
+[Nimble Storage Volume Plugin](https://connect.nimblestorage.com/community/app-integration/docker)| A volume plug-in that integrates with Nimble Storage Unified Flash Fabric arrays. The plug-in abstracts array volume capabilities to the Docker administrator to allow self-provisioning of secure multi-tenant volumes and clones.
 [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.
 [Portworx Volume Plugin](https://github.com/portworx/px-dev)                        | A volume plugin that turns any server into a scale-out converged compute/storage node, providing container granular storage and highly available volumes across any node, using a shared-nothing storage backend that works with any docker scheduler.
 [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.

docs/reference/builder.md

@@ -1222,6 +1222,11 @@ This Dockerfile results in an image that causes `docker run`, to
 create a new mount point at `/myvol` and copy the  `greeting` file
 into the newly created volume.
 
+> **Note**:
+> When using Windows-based containers, the destination of a volume inside the
+> container must be one of: a non-existing or empty directory; or a drive other
+> than C:.
+
 > **Note**:
 > If any build steps change the data within the volume after it has been
 > declared, those changes will be discarded.

docs/reference/commandline/commit.md

@@ -74,7 +74,7 @@ svendowideit/testimage            version3            f5283438590d        16 sec
 ```bash
 $ docker ps
 
-ICONTAINER ID       IMAGE               COMMAND             CREATED             STATUS              PORTS              NAMES
+CONTAINER ID       IMAGE               COMMAND             CREATED             STATUS              PORTS              NAMES
 c3f279d17e0a        ubuntu:12.04        /bin/bash           7 days ago          Up 25 hours                            desperate_dubinsky
 197387f1b436        ubuntu:12.04        /bin/bash           7 days ago          Up 25 hours                            focused_hamilton
 

docs/reference/commandline/create.md

@@ -126,7 +126,8 @@ Options:
   -v, --volume value                Bind mount a volume (default []). The format
                                     is `[host-src:]container-dest[:<options>]`.
                                     The comma-delimited `options` are [rw|ro],
-                                    [z|Z], [[r]shared|[r]slave|[r]private], and
+                                    [z|Z], [[r]shared|[r]slave|[r]private],
+                                    [delegated|cached|consistent], and
                                     [nocopy]. The 'host-src' is an absolute path
                                     or a name value.
       --volume-driver string        Optional volume driver for the container

docs/reference/commandline/dockerd.md

@@ -17,33 +17,34 @@ keywords: "container, daemon, runtime"
 # daemon
 
 ```markdown
-Usage: dockerd [OPTIONS]
+Usage:	dockerd COMMAND
 
 A self-sufficient runtime for containers.
 
 Options:
-      --add-runtime value                     Register an additional OCI compatible runtime (default [])
+      --add-runtime runtime                   Register an additional OCI compatible runtime (default [])
       --api-cors-header string                Set CORS headers in the Engine API
-      --authorization-plugin value            Authorization plugins to load (default [])
+      --authorization-plugin list             Authorization plugins to load (default [])
       --bip string                            Specify network bridge IP
   -b, --bridge string                         Attach containers to a network bridge
       --cgroup-parent string                  Set parent cgroup for all containers
       --cluster-advertise string              Address or interface name to advertise
       --cluster-store string                  URL of the distributed storage backend
-      --cluster-store-opt value               Set cluster store options (default map[])
+      --cluster-store-opt map                 Set cluster store options (default map[])
       --config-file string                    Daemon configuration file (default "/etc/docker/daemon.json")
       --containerd string                     Path to containerd socket
+      --cpu-rt-period int                     Limit the CPU real-time period in microseconds
+      --cpu-rt-runtime int                    Limit the CPU real-time runtime in microseconds
   -D, --debug                                 Enable debug mode
-      --default-gateway value                 Container default gateway IPv4 address
-      --default-gateway-v6 value              Container default gateway IPv6 address
+      --default-gateway ip                    Container default gateway IPv4 address
+      --default-gateway-v6 ip                 Container default gateway IPv6 address
       --default-runtime string                Default OCI runtime for containers (default "runc")
-      --default-shm-size bytes                Set the default shm size for containers (default 64 MiB)
-      --default-ulimit value                  Default ulimits for containers (default [])
+      --default-ulimit ulimit                 Default ulimits for containers (default [])
       --disable-legacy-registry               Disable contacting legacy registries
-      --dns value                             DNS server to use (default [])
-      --dns-opt value                         DNS options to use (default [])
-      --dns-search value                      DNS search domains to use (default [])
-      --exec-opt value                        Runtime execution options (default [])
+      --dns list                              DNS server to use (default [])
+      --dns-opt list                          DNS options to use (default [])
+      --dns-search list                       DNS search domains to use (default [])
+      --exec-opt list                         Runtime execution options (default [])
       --exec-root string                      Root directory for execution state files (default "/var/run/docker")
       --experimental                          Enable experimental features
       --fixed-cidr string                     IPv4 subnet for fixed IPs
@@ -51,39 +52,39 @@ Options:
   -g, --graph string                          Root of the Docker runtime (default "/var/lib/docker")
   -G, --group string                          Group for the unix socket (default "docker")
       --help                                  Print usage
-  -H, --host value                            Daemon socket(s) to connect to (default [])
+  -H, --host list                             Daemon socket(s) to connect to (default [])
       --icc                                   Enable inter-container communication (default true)
       --init                                  Run an init in the container to forward signals and reap processes
       --init-path string                      Path to the docker-init binary
-      --insecure-registry value               Enable insecure registry communication (default [])
-      --ip value                              Default IP when binding container ports (default 0.0.0.0)
+      --insecure-registry list                Enable insecure registry communication (default [])
+      --ip ip                                 Default IP when binding container ports (default 0.0.0.0)
       --ip-forward                            Enable net.ipv4.ip_forward (default true)
       --ip-masq                               Enable IP masquerading (default true)
       --iptables                              Enable addition of iptables rules (default true)
       --ipv6                                  Enable IPv6 networking
-      --label value                           Set key=value labels to the daemon (default [])
-      --live-restore                          Enable live restore of docker when containers are still running (Linux only)
+      --label list                            Set key=value labels to the daemon (default [])
+      --live-restore                          Enable live restore of docker when containers are still running
       --log-driver string                     Default driver for container logs (default "json-file")
-  -l, --log-level string                      Set the logging level ("debug"|"info"|"warn"|"error"|"fatal") (default "info")
-      --log-opt value                         Default log driver options for containers (default map[])
+  -l, --log-level string                      Set the logging level ("debug", "info", "warn", "error", "fatal") (default "info")
+      --log-opt map                           Default log driver options for containers (default map[])
       --max-concurrent-downloads int          Set the max concurrent downloads for each pull (default 3)
       --max-concurrent-uploads int            Set the max concurrent uploads for each push (default 5)
-      --metrics-addr string                   Set address and port to serve the metrics api (default "")
+      --metrics-addr string                   Set default address and port to serve the metrics api on
       --mtu int                               Set the containers network MTU
       --oom-score-adjust int                  Set the oom_score_adj for the daemon (default -500)
   -p, --pidfile string                        Path to use for daemon PID file (default "/var/run/docker.pid")
       --raw-logs                              Full timestamps without ANSI coloring
-      --registry-mirror value                 Preferred Docker registry mirror (default [])
-      --seccomp-profile value                 Path to seccomp profile
+      --registry-mirror list                  Preferred Docker registry mirror (default [])
+      --seccomp-profile string                Path to seccomp profile
       --selinux-enabled                       Enable selinux support
-      --shutdown-timeout=15                   Set the shutdown timeout value in seconds
+      --shutdown-timeout int                  Set the default shutdown timeout (default 15)
   -s, --storage-driver string                 Storage driver to use
-      --storage-opt value                     Storage driver options (default [])
+      --storage-opt list                      Storage driver options (default [])
       --swarm-default-advertise-addr string   Set default address or interface for swarm advertised address
       --tls                                   Use TLS; implied by --tlsverify
-      --tlscacert string                      Trust certs signed only by this CA (default "/root/.docker/ca.pem")
-      --tlscert string                        Path to TLS certificate file (default "/root/.docker/cert.pem")
-      --tlskey string                         Path to TLS key file (default "/root/.docker/key.pem")
+      --tlscacert string                      Trust certs signed only by this CA (default "~/.docker/ca.pem")
+      --tlscert string                        Path to TLS certificate file (default "~/.docker/cert.pem")
+      --tlskey string                         Path to TLS key file (default ~/.docker/key.pem")
       --tlsverify                             Use TLS and verify the remote
       --userland-proxy                        Use userland proxy for loopback traffic (default true)
       --userland-proxy-path string            Path to the userland proxy binary
@@ -99,7 +100,13 @@ Options with [] may be specified multiple times.
 uses different binaries for the daemon and client. To run the daemon you
 type `dockerd`.
 
-To run the daemon with debug output, use `dockerd -D`.
+To run the daemon with debug output, use `dockerd -D` or add `debug: true` to
+the `daemon.json` file.
+
+> **Note**: In Docker 1.13 and higher, enable experimental features by starting
+> `dockerd` with the `--experimental` flag or adding `experimental: true` to the
+> `daemon.json` file. In earlier Docker versions, a different build was required
+> to enable experimental features.
 
 ## Examples
 

docs/reference/commandline/images.md

@@ -158,6 +158,7 @@ The currently supported filters are:
 * label (`label=<key>` or `label=<key>=<value>`)
 * before (`<image-name>[:<tag>]`,  `<image id>` or `<image@digest>`) - filter images created before given id or references
 * since (`<image-name>[:<tag>]`,  `<image id>` or `<image@digest>`) - filter images created since given id or references
+* reference (pattern of an image reference) - filter images whose reference matches the specified pattern
 
 #### Show untagged images (dangling)
 

docs/reference/commandline/inspect.md

@@ -63,7 +63,7 @@ $ docker inspect --format='{{.LogPath}}' $INSTANCE_ID
 ### Get an instance's image name
 
 ```bash
-$ docker inspect --format='{{.Container.Spec.Image}}' $INSTANCE_ID
+$ docker inspect --format='{{.Config.Image}}' $INSTANCE_ID
 ```
 
 ### List all port bindings

docs/reference/commandline/node_ps.md

@@ -104,7 +104,7 @@ redis.7.bg8c07zzg87di2mufeq51a2qp  redis:3.0.6  swarm-manager1  Running        R
 
 #### desired-state
 
-The `desired-state` filter can take the values `running`, `shutdown`, and `accepted`.
+The `desired-state` filter can take the values `running`, `shutdown`, or `accepted`.
 
 
 ### Formatting
@@ -119,7 +119,7 @@ Placeholder     | Description
 `.Name`         | Task name
 `.Image`        | Task image
 `.Node`         | Node ID
-`.DesiredState` | Desired state of the task (`running`, `shutdown`, and `accepted`)
+`.DesiredState` | Desired state of the task (`running`, `shutdown`, or `accepted`)
 `.CurrentState` | Current state of the task
 `.Error`        | Error
 `.Ports`        | Task published ports
@@ -129,7 +129,7 @@ output the data exactly as the template declares or, when using the
 `table` directive, includes column headers as well.
 
 The following example uses a template without headers and outputs the
-`ID` and `Driver` entries separated by a colon for all tasks:
+`Name` and `Image` entries separated by a colon for all tasks:
 
 ```bash
 $ docker node ps --format "{{.Name}}: {{.Image}}"

docs/reference/commandline/push.md

@@ -36,6 +36,10 @@ image and tag names.
 Killing the `docker push` process, for example by pressing `CTRL-c` while it is
 running in a terminal, terminates the push operation.
 
+Progress bars are shown during docker push, which show the uncompressed size. The 
+actual amount of data that's pushed will be compressed before sending, so the uploaded
+ size will not be reflected by the progress bar. 
+
 Registry credentials are managed by [docker login](login.md).
 
 ### Concurrent uploads

docs/reference/commandline/run.md

@@ -137,7 +137,8 @@ Options:
   -v, --volume value                Bind mount a volume (default []). The format
                                     is `[host-src:]container-dest[:<options>]`.
                                     The comma-delimited `options` are [rw|ro],
-                                    [z|Z], [[r]shared|[r]slave|[r]private], and
+                                    [z|Z], [[r]shared|[r]slave|[r]private],
+                                    [delegated|cached|consistent], and
                                     [nocopy]. The 'host-src' is an absolute path
                                     or a name value.
       --volume-driver string        Optional volume driver for the container

docs/reference/commandline/secret_create.md

@@ -27,8 +27,9 @@ Options:
 
 ## Description
 
-Creates a secret using standard input or from a file for the secret content. You must run this
-command on a manager node.
+Creates a secret using standard input or from a file for the secret content. You must run this command on a manager node. 
+
+For detailed information about using secrets, refer to [manage sensitive data with Docker secrets](https://docs.docker.com/engine/swarm/secrets/).
 
 ## Examples
 

docs/reference/commandline/secret_inspect.md

@@ -36,6 +36,8 @@ the given template will be executed for each result.
 Go's [text/template](http://golang.org/pkg/text/template/) package
 describes all the details of the format.
 
+For detailed information about using secrets, refer to [manage sensitive data with Docker secrets](https://docs.docker.com/engine/swarm/secrets/).
+
 ## Examples
 
 ### Inspect a secret by name or ID

docs/reference/commandline/secret_ls.md

@@ -31,6 +31,8 @@ Options:
 
 Run this command on a manager node to list the secrets in the swarm.
 
+For detailed information about using secrets, refer to [manage sensitive data with Docker secrets](https://docs.docker.com/engine/swarm/secrets/).
+
 ## Examples
 
 ```bash

docs/reference/commandline/secret_rm.md

@@ -32,6 +32,8 @@ Options:
 Removes the specified secrets from the swarm. This command has to be run
 targeting a manager node.
 
+For detailed information about using secrets, refer to [manage sensitive data with Docker secrets](https://docs.docker.com/engine/swarm/secrets/).
+
 ## Examples
 
 This example removes a secret:

docs/reference/commandline/service.md

@@ -28,7 +28,7 @@ Commands:
   inspect     Display detailed information on one or more services
   logs        Fetch the logs of a service
   ls          List services
-  ps          List the tasks of a service
+  ps          List the tasks of one or more services
   rm          Remove one or more services
   scale       Scale one or multiple replicated services
   update      Update a service

docs/reference/commandline/service_create.md

@@ -320,9 +320,22 @@ volumes in a service:
       </ul></p>
     </td>
   </tr>
+  <tr>
+    <td><b>consistency</b></td>
+    <td></td>
+    <td>
+      <p>The consistency requirements for the mount; one of
+         <ul>
+           <li><tt>default</tt>: Equivalent to <tt>consistent</tt>.</li>
+           <li><tt>consistent</tt>: Full consistency.  The container runtime and the host maintain an identical view of the mount at all times.</li>
+           <li><tt>cached</tt>: The host's view of the mount is authoritative.  There may be delays before updates made on the host are visible within a container.</li>
+           <li><tt>delegated</tt>: The container runtime's view of the mount is authoritative.  There may be delays before updates made in a container are are visible on the host.</li>
+        </ul>
+     </p>
+    </td>
+  </tr>
 </table>
 
-
 #### Bind Propagation
 
 Bind propagation refers to whether or not mounts created within a given
@@ -559,8 +572,8 @@ follows:
     <td><tt>node.hostname != node-2</tt></td>
   </tr>
   <tr>
-    <td<tt>node.role</tt></td>
-    <td><tt>node role: manager</tt></td>
+    <td><tt>node.role</tt></td>
+    <td>Node role</td>
     <td><tt>node.role == manager</tt></td>
   </tr>
   <tr>

docs/reference/commandline/service_ps.md

@@ -17,7 +17,7 @@ aliases: ["/engine/reference/commandline/service_tasks/"]
 # service ps
 
 ```Markdown
-Usage:  docker service ps [OPTIONS] SERVICE
+Usage:  docker service ps [OPTIONS] SERVICE [SERVICE...]
 
 List the tasks of one or more services
 
@@ -147,11 +147,9 @@ ID            NAME      IMAGE        NODE      DESIRED STATE  CURRENT STATE
 8eaxrb2fqpbn  redis.10  redis:3.0.6  manager1  Running        Running 8 seconds
 ```
 
-
 #### desired-state
 
-The `desired-state` filter can take the values `running`, `shutdown`, and `accepted`.
-
+The `desired-state` filter can take the values `running`, `shutdown`, or `accepted`.
 
 ### Formatting
 
@@ -166,7 +164,7 @@ Placeholder     | Description
 `.Name`         | Task name
 `.Image`        | Task image
 `.Node`         | Node ID
-`.DesiredState` | Desired state of the task (`running`, `shutdown`, and `accepted`)
+`.DesiredState` | Desired state of the task (`running`, `shutdown`, or `accepted`)
 `.CurrentState` | Current state of the task
 `.Error`        | Error
 `.Ports`        | Task published ports
@@ -176,7 +174,7 @@ output the data exactly as the template declares or, when using the
 `table` directive, includes column headers as well.
 
 The following example uses a template without headers and outputs the
-`ID` and `Driver` entries separated by a colon for all tasks:
+`Name` and `Image` entries separated by a colon for all tasks:
 
 ```bash
 $ docker service ps --format "{{.Name}}: {{.Image}}" top

docs/reference/commandline/stack_ps.md

@@ -36,8 +36,21 @@ command has to be run targeting a manager node.
 
 ## Examples
 
+### List the tasks that are part of a stack
+
+The following command shows all the tasks that are part of the `voting` stack:
+
 ```bash
-$ docker stack ps
+$ docker stack ps voting
+ID                  NAME                  IMAGE                                          NODE   DESIRED STATE  CURRENT STATE          ERROR  PORTS
+xim5bcqtgk1b        voting_worker.1       dockersamples/examplevotingapp_worker:latest   node2  Running        Running 2 minutes ago
+q7yik0ks1in6        voting_result.1       dockersamples/examplevotingapp_result:before   node1  Running        Running 2 minutes ago
+rx5yo0866nfx        voting_vote.1         dockersamples/examplevotingapp_vote:before     node3  Running        Running 2 minutes ago
+tz6j82jnwrx7        voting_db.1           postgres:9.4                                   node1  Running        Running 2 minutes ago
+w48spazhbmxc        voting_redis.1        redis:alpine                                   node2  Running        Running 3 minutes ago
+6jj1m02freg1        voting_visualizer.1   dockersamples/visualizer:stable                node1  Running        Running 2 minutes ago
+kqgdmededccb        voting_vote.2         dockersamples/examplevotingapp_vote:before     node2  Running        Running 2 minutes ago
+t72q3z038jeh        voting_redis.2        redis:alpine                                   node3  Running        Running 3 minutes ago
 ```
 
 ### Filtering
@@ -49,9 +62,165 @@ Multiple filter flags are combined as an `OR` filter. For example,
 
 The currently supported filters are:
 
-* id
-* name
-* desired-state
+* [id](#id)
+* [name](#name)
+* [node](#node)
+* [desired-state](#desired-state)
+
+#### id
+
+The `id` filter matches on all or a prefix of a task's ID.
+
+```bash
+$ docker stack ps -f "id=t" voting
+ID                  NAME                IMAGE               NODE         DESIRED STATE       CURRENTSTATE            ERROR  PORTS
+tz6j82jnwrx7        voting_db.1         postgres:9.4        node1        Running             Running 14 minutes ago
+t72q3z038jeh        voting_redis.2      redis:alpine        node3        Running             Running 14 minutes ago
+```
+
+#### name
+
+The `name` filter matches on task names.
+
+```bash
+$ docker stack ps -f "name=voting_redis" voting
+ID                  NAME                IMAGE               NODE         DESIRED STATE       CURRENTSTATE            ERROR  PORTS
+w48spazhbmxc        voting_redis.1      redis:alpine        node2        Running             Running 17 minutes ago
+t72q3z038jeh        voting_redis.2      redis:alpine        node3        Running             Running 17 minutes ago
+```
+
+#### node
+
+The `node` filter matches on a node name or a node ID.
+
+```bash
+$ docker stack ps -f "node=node1" voting
+ID                  NAME                  IMAGE                                          NODE   DESIRED STATE  CURRENT STATE          ERROR  PORTS
+q7yik0ks1in6        voting_result.1       dockersamples/examplevotingapp_result:before   node1  Running        Running 18 minutes ago
+tz6j82jnwrx7        voting_db.1           postgres:9.4                                   node1  Running        Running 18 minutes ago
+6jj1m02freg1        voting_visualizer.1   dockersamples/visualizer:stable                node1  Running        Running 18 minutes ago
+```
+
+#### desired-state
+
+The `desired-state` filter can take the values `running`, `shutdown`, or `accepted`.
+
+```bash
+$ docker stack ps -f "desired-state=running" voting
+ID                  NAME                  IMAGE                                          NODE   DESIRED STATE  CURRENT STATE           ERROR  PORTS
+xim5bcqtgk1b        voting_worker.1       dockersamples/examplevotingapp_worker:latest   node2  Running        Running 21 minutes ago
+q7yik0ks1in6        voting_result.1       dockersamples/examplevotingapp_result:before   node1  Running        Running 21 minutes ago
+rx5yo0866nfx        voting_vote.1         dockersamples/examplevotingapp_vote:before     node3  Running        Running 21 minutes ago
+tz6j82jnwrx7        voting_db.1           postgres:9.4                                   node1  Running        Running 21 minutes ago
+w48spazhbmxc        voting_redis.1        redis:alpine                                   node2  Running        Running 21 minutes ago
+6jj1m02freg1        voting_visualizer.1   dockersamples/visualizer:stable                node1  Running        Running 21 minutes ago
+kqgdmededccb        voting_vote.2         dockersamples/examplevotingapp_vote:before     node2  Running        Running 21 minutes ago
+t72q3z038jeh        voting_redis.2        redis:alpine                                   node3  Running        Running 21 minutes ago
+```
+
+### Formatting
+
+The formatting options (`--format`) pretty-prints tasks output using a Go template.
+
+Valid placeholders for the Go template are listed below:
+
+Placeholder     | Description
+----------------|------------------------------------------------------------------------------------------
+`.ID`           | Task ID
+`.Name`         | Task name
+`.Image`        | Task image
+`.Node`         | Node ID
+`.DesiredState` | Desired state of the task (`running`, `shutdown`, or `accepted`)
+`.CurrentState` | Current state of the task
+`.Error`        | Error
+`.Ports`        | Task published ports
+
+When using the `--format` option, the `stack ps` command will either
+output the data exactly as the template declares or, when using the
+`table` directive, includes column headers as well.
+
+The following example uses a template without headers and outputs the
+`Name` and `Image` entries separated by a colon for all tasks:
+
+```bash
+$ docker stack ps --format "{{.Name}}: {{.Image}}" voting
+voting_worker.1: dockersamples/examplevotingapp_worker:latest
+voting_result.1: dockersamples/examplevotingapp_result:before
+voting_vote.1: dockersamples/examplevotingapp_vote:before
+voting_db.1: postgres:9.4
+voting_redis.1: redis:alpine
+voting_visualizer.1: dockersamples/visualizer:stable
+voting_vote.2: dockersamples/examplevotingapp_vote:before
+voting_redis.2: redis:alpine
+```
+
+### Do not map IDs to Names
+
+The `--no-resolve` option shows IDs for task name, without mapping IDs to Names.
+
+```bash
+$ docker stack ps --no-resolve voting
+ID                  NAME                          IMAGE                                          NODE                        DESIRED STATE  CURRENT STATE            ERROR  PORTS
+xim5bcqtgk1b        10z9fjfqzsxnezo4hb81p8mqg.1   dockersamples/examplevotingapp_worker:latest   qaqt4nrzo775jrx6detglho01   Running        Running 30 minutes ago
+q7yik0ks1in6        hbxltua1na7mgqjnidldv5m65.1   dockersamples/examplevotingapp_result:before   mxpaef1tlh23s052erw88a4w5   Running        Running 30 minutes ago
+rx5yo0866nfx        qyprtqw1g5nrki557i974ou1d.1   dockersamples/examplevotingapp_vote:before     kanqcxfajd1r16wlnqcblobmm   Running        Running 31 minutes ago
+tz6j82jnwrx7        122f0xxngg17z52be7xspa72x.1   postgres:9.4                                   mxpaef1tlh23s052erw88a4w5   Running        Running 31 minutes ago
+w48spazhbmxc        tg61x8myx563ueo3urmn1ic6m.1   redis:alpine                                   qaqt4nrzo775jrx6detglho01   Running        Running 31 minutes ago
+6jj1m02freg1        8cqlyi444kzd3panjb7edh26v.1   dockersamples/visualizer:stable                mxpaef1tlh23s052erw88a4w5   Running        Running 31 minutes ago
+kqgdmededccb        qyprtqw1g5nrki557i974ou1d.2   dockersamples/examplevotingapp_vote:before     qaqt4nrzo775jrx6detglho01   Running        Running 31 minutes ago
+t72q3z038jeh        tg61x8myx563ueo3urmn1ic6m.2   redis:alpine                                   kanqcxfajd1r16wlnqcblobmm   Running        Running 31 minutes ago
+```
+
+### Do not truncate output
+
+When deploying a service, docker resolves the digest for the service's
+image, and pins the service to that digest. The digest is not shown by
+default, but is printed if `--no-trunc` is used. The `--no-trunc` option
+also shows the non-truncated task IDs, and error-messages, as can be seen below:
+
+```bash
+$ docker stack ps --no-trunc voting
+ID                          NAME                  IMAGE                                                                                                                 NODE   DESIRED STATE  CURREN STATE           ERROR  PORTS
+xim5bcqtgk1bxqz91jzo4a1s5   voting_worker.1       dockersamples/examplevotingapp_worker:latest@sha256:3e4ddf59c15f432280a2c0679c4fc5a2ee5a797023c8ef0d3baf7b1385e9fed   node2  Running        Runnin 32 minutes ago
+q7yik0ks1in6kv32gg6y6yjf7   voting_result.1       dockersamples/examplevotingapp_result:before@sha256:83b56996e930c292a6ae5187fda84dd6568a19d97cdb933720be15c757b7463   node1  Running        Runnin 32 minutes ago
+rx5yo0866nfxc58zf4irsss6n   voting_vote.1         dockersamples/examplevotingapp_vote:before@sha256:8e64b182c87de902f2b72321c89b4af4e2b942d76d0b772532ff27ec4c6ebf6     node3  Running        Runnin 32 minutes ago
+tz6j82jnwrx7n2offljp3mn03   voting_db.1           postgres:9.4@sha256:6046af499eae34d2074c0b53f9a8b404716d415e4a03e68bc1d2f8064f2b027                                   node1  Running        Runnin 32 minutes ago
+w48spazhbmxcmbjfi54gs7x90   voting_redis.1        redis:alpine@sha256:9cd405cd1ec1410eaab064a1383d0d8854d1ef74a54e1e4a92fb4ec7bdc3ee7                                   node2  Running        Runnin 32 minutes ago
+6jj1m02freg1n3z9n1evrzsbl   voting_visualizer.1   dockersamples/visualizer:stable@sha256:f924ad66c8e94b10baaf7bdb9cd491ef4e982a1d048a56a17e02bf5945401e5                node1  Running        Runnin 32 minutes ago
+kqgdmededccbhz2wuc0e9hx7g   voting_vote.2         dockersamples/examplevotingapp_vote:before@sha256:8e64b182c87de902f2b72321c89b4af4e2b942d76d0b772532ff27ec4c6ebf6     node2  Running        Runnin 32 minutes ago
+t72q3z038jehe1wbh9gdum076   voting_redis.2        redis:alpine@sha256:9cd405cd1ec1410eaab064a1383d0d8854d1ef74a54e1e4a92fb4ec7bdc3ee7                                   node3  Running        Runnin 32 minutes ago
+```
+
+### Only display task IDs
+
+The `-q ` or `--quiet` option only shows IDs of the tasks in the stack.
+This example outputs all task IDs of the "voting" stack;
+
+```bash
+$ docker stack ps -q voting
+xim5bcqtgk1b
+q7yik0ks1in6
+rx5yo0866nfx
+tz6j82jnwrx7
+w48spazhbmxc
+6jj1m02freg1
+kqgdmededccb
+t72q3z038jeh
+```
+
+This option can be used to perform batch operations. For example, you can use
+the task IDs as input for other commands, such as `docker inspect`. The
+following example inspects all tasks of the "voting" stack;
+
+```bash
+$ docker inspect $(docker stack ps -q voting)
+
+[
+    {
+        "ID": "xim5bcqtgk1b1gk0krq1",
+        "Version": {
+(...)
+```
 
 ## Related commands
 

docs/reference/commandline/system_df.md

@@ -77,6 +77,15 @@ my-named-vol                                                       0
 > **Note**: Network information is not shown because it doesn't consume the disk
 > space.
 
+## Performance
+
+The `system df` command can be very resource-intensive. It traverses the
+filesystem of every image, container, and volume in the system. You should be
+careful running this command in systems with lots of images, containers, or
+volumes or in systems where some images, containers, or volumes have very large
+filesystems with many files. You should also be careful not to run this command
+in systems where performance is critical.
+
 ## Related commands
 * [system prune](system_prune.md)
 * [container prune](container_prune.md)

docs/reference/run.md

@@ -458,10 +458,6 @@ If a container is connected to the default bridge network and `linked`
 with other containers, then the container's `/etc/hosts` file is updated
 with the linked container's name.
 
-If the container is connected to user-defined network, the container's
-`/etc/hosts` file is updated with names of all other containers in that
-user-defined network.
-
 > **Note** Since Docker may live update the container’s `/etc/hosts` file, there
 may be situations when processes inside the container can end up reading an
 empty or incomplete `/etc/hosts` file. In most cases, retrying the read again

experimental/README.md

@@ -13,9 +13,9 @@ please feel free to provide any feedback on these features you wish.
 
 Experimental features are now included in the standard Docker binaries as of
 version 1.13.0.
-For enabling experimental features, you need to start the Docker daemon with
-`--experimental` flag.
-You can also enable the daemon flag via `/etc/docker/daemon.json`. e.g.
+To enable experimental features, start the Docker daemon with the
+`--experimental` flag or enable the daemon flag in the
+`/etc/docker/daemon.json` configuration file:
 
 ```json
 {
@@ -23,7 +23,8 @@ You can also enable the daemon flag via `/etc/docker/daemon.json`. e.g.
 }
 ```
 
-Then make sure the experimental flag is enabled:
+You can check to see if experimental features are enabled on a running daemon
+using the following command:
 
 ```bash
 $ docker version -f '{{.Server.Experimental}}'
@@ -32,9 +33,18 @@ true
 
 ## Current experimental features
 
+Docker service logs command to view logs for a Docker service. This is needed in Swarm mode.
+Option to squash image layers to the base image after successful builds.
+Checkpoint and restore support for Containers.
+Metrics (Prometheus) output for basic container, image, and daemon operations.
+
+ * The top-level [docker deploy](../../docs/reference/deploy.md) command. The
+   `docker stack deploy` command is **not** experimental.
+ * [`docker service logs` command](../docs/reference/commandline/service_logs.md)
+ * [`--squash` option to `docker build` command](../docs/reference/commandline/build.md##squash-an-images-layers---squash-experimental-only)
  * [External graphdriver plugins](../docs/extend/plugins_graphdriver.md)
  * [Ipvlan Network Drivers](vlan-networks.md)
- * [Docker Stacks and Distributed Application Bundles](docker-stacks-and-bundles.md)
+ * [Distributed Application Bundles](docker-stacks-and-bundles.md)
  * [Checkpoint & Restore](checkpoint-restore.md)
 
 ## How to comment on an experimental feature

man/docker-run.1.md

@@ -625,6 +625,7 @@ any options, the systems uses the following options:
    * [rw|ro]
    * [z|Z]
    * [`[r]shared`|`[r]slave`|`[r]private`]
+   * [`delegated`|`cached`|`consistent`]
    * [nocopy]
 
 The `CONTAINER-DIR` must be an absolute path such as `/src/docs`. The `HOST-DIR`
@@ -642,9 +643,12 @@ You can specify multiple  **-v** options to mount one or more mounts to a
 container. To use these same mounts in other containers, specify the
 **--volumes-from** option also.
 
-You can add `:ro` or `:rw` suffix to a volume to mount it  read-only or
-read-write mode, respectively. By default, the volumes are mounted read-write.
-See examples.
+You can supply additional options for each bind-mount following an additional
+colon.  A `:ro` or `:rw` suffix mounts a volume in read-only or read-write
+mode, respectively. By default, volumes are mounted in read-write mode.
+You can also specify the consistency requirement for the mount, either
+`:consistent` (the default), `:cached`, or `:delegated`.  Multiple options are
+separated by commas, e.g. `:ro,cached`.
 
 Labeling systems like SELinux require that proper labels are placed on volume
 content mounted into a container. Without a label, the security system might

man/src/container/create.md

@@ -23,9 +23,12 @@ You can specify multiple  **-v** options to mount one or more mounts to a
 container. To use these same mounts in other containers, specify the
 **--volumes-from** option also.
 
-You can add `:ro` or `:rw` suffix to a volume to mount it  read-only or
-read-write mode, respectively. By default, the volumes are mounted read-write.
-See examples.
+You can supply additional options for each bind-mount following an additional
+colon.  A `:ro` or `:rw` suffix mounts a volume in read-only or read-write
+mode, respectively. By default, volumes are mounted in read-write mode.  
+You can also specify the consistency requirement for the mount, either
+`:consistent` (the default), `:cached`, or `:delegated`.  Multiple options are
+separated by commas, e.g. `:ro,cached`.
 
 Labeling systems like SELinux require that proper labels are placed on volume
 content mounted into a container. Without a label, the security system might

man/src/image/ls.md

@@ -21,6 +21,7 @@ Filters the output based on these conditions:
    - label=<key> or label=<key>=<value>
    - before=(<image-name>[:tag]|<image-id>|<image@digest>)
    - since=(<image-name>[:tag]|<image-id>|<image@digest>)
+   - reference=(pattern of an image reference)
 
 ## Format