[17.06] CLI reference docs cherry-picks (and 1 completion fix)

components/cli/contrib/completion/bash/docker

@@ -3046,6 +3046,7 @@ _docker_service_update() {
 # and `docker service update`
 _docker_service_update_and_create() {
 	local options_with_args="
+		--credential-spec
 		--endpoint-mode
 		--entrypoint
 		--env -e

components/cli/docs/reference/builder.md

@@ -138,7 +138,7 @@ be UPPERCASE to distinguish them from arguments more easily.
 Docker runs instructions in a `Dockerfile` in order. A `Dockerfile` **must
 start with a \`FROM\` instruction**. The `FROM` instruction specifies the [*Base
 Image*](glossary.md#base-image) from which you are building. `FROM` may only be
-proceeded by one or more `ARG` instructions, which declare arguments that are used
+preceded by one or more `ARG` instructions, which declare arguments that are used
 in `FROM` lines in the `Dockerfile`.
 
 Docker treats lines that *begin* with `#` as a comment, unless the line is
@@ -499,7 +499,7 @@ valid `Dockerfile` must start with a `FROM` instruction. The image can be
 any valid image – it is especially easy to start by **pulling an image** from 
 the [*Public Repositories*](https://docs.docker.com/engine/tutorials/dockerrepos/).
 
-- `ARG` is the only instruction that may proceed `FROM` in the `Dockerfile`. 
+- `ARG` is the only instruction that may precede `FROM` in the `Dockerfile`.
   See [Understand how ARG and FROM interact](#understand-how-arg-and-from-interact).
 
 - `FROM` can appear multiple times within a single `Dockerfile` to 
@@ -530,15 +530,16 @@ FROM extras:${CODE_VERSION}
 CMD  /code/run-extras
 ```
 
-To use the default value of an `ARG` declared before the first `FROM` use an
-`ARG` instruction without a value:
+An `ARG` declared before a `FROM` is outside of a build stage, so it
+can't be used in any instruction after a `FROM`. To use the default value of
+an `ARG` declared before the first `FROM` use an `ARG` instruction without
+a value inside of a build stage:
 
 ```Dockerfile
-ARG  SETTINGS=default
-
-FROM busybox
-ARG  SETTINGS
-
+ARG VERSION=latest
+FROM busybox:$VERSION
+ARG VERSION
+RUN echo $VERSION > image_version
 ```
 
 ## RUN
@@ -1364,8 +1365,8 @@ defined in the Dockerfile, the build outputs a warning.
 [Warning] One or more build-args [foo] were not consumed.
 ```
 
-The Dockerfile author can define a single variable by specifying `ARG` once or many
-variables by specifying `ARG` more than once. For example, a valid Dockerfile:
+A Dockerfile may include one or more `ARG` instructions. For example,
+the following is a valid Dockerfile:
 
 ```
 FROM busybox
@@ -1374,7 +1375,13 @@ ARG buildno
 ...
 ```
 
-A Dockerfile author may optionally specify a default value for an `ARG` instruction:
+> **Warning:** It is not recommended to use build-time variables for
+>  passing secrets like github keys, user credentials etc. Build-time variable
+>  values are visible to any user of the image with the `docker history` command.
+
+### Default values
+
+An `ARG` instruction can optionally include a default value:
 
 ```
 FROM busybox
@@ -1383,8 +1390,10 @@ ARG buildno=1
 ...
 ```
 
-If an `ARG` value has a default and if there is no value passed at build-time, the
-builder uses the default.
+If an `ARG` instruction has a default value and if there is no value passed
+at build-time, the builder uses the default.
+
+### Scope
 
 An `ARG` variable definition comes into effect from the line on which it is
 defined in the `Dockerfile` not from the argument's use on the command-line or
@@ -1408,9 +1417,21 @@ subsequent line 3. The `USER` at line 4 evaluates to `what_user` as `user` is
 defined and the `what_user` value was passed on the command line. Prior to its definition by an
 `ARG` instruction, any use of a variable results in an empty string.
 
-> **Warning:** It is not recommended to use build-time variables for
->  passing secrets like github keys, user credentials etc. Build-time variable
->  values are visible to any user of the image with the `docker history` command.
+An `ARG` instruction goes out of scope at the end of the build
+stage where it was defined. To use an arg in multiple stages, each stage must
+include the `ARG` instruction.
+
+```
+FROM busybox
+ARG SETTINGS
+RUN ./run/setup $SETTINGS
+
+FROM busybox
+ARG SETTINGS
+RUN ./run/other $SETTINGS
+```
+
+### Using ARG variables
 
 You can use an `ARG` or an `ENV` instruction to specify variables that are
 available to the `RUN` instruction. Environment variables defined using the
@@ -1459,6 +1480,8 @@ from the command line and persist them in the final image by leveraging the
 `ENV` instruction. Variable expansion is only supported for [a limited set of
 Dockerfile instructions.](#environment-replacement)
 
+### Predefined ARGs
+
 Docker has a set of predefined `ARG` variables that you can use without a
 corresponding `ARG` instruction in the Dockerfile.
 

components/cli/docs/reference/commandline/cp.md

@@ -28,6 +28,7 @@ container source to stdout.
 
 Options:
   -L, --follow-link   Always follow symbol link in SRC_PATH
+  -a, --archive       Archive mode (copy all uid/gid information)
       --help          Print usage
 ```
 
@@ -53,7 +54,9 @@ copied recursively with permissions preserved if possible. Ownership is set to
 the user and primary group at the destination. For example, files copied to a
 container are created with `UID:GID` of the root user. Files copied to the local
 machine are created with the `UID:GID` of the user which invoked the `docker cp`
-command.  If you specify the `-L` option, `docker cp` follows any symbolic link
+command. However, if you specify the `-a` option, `docker cp` sets the ownership
+to the user and primary group at the source.
+If you specify the `-L` option, `docker cp` follows any symbolic link
 in the `SRC_PATH`.  `docker cp` does *not* create parent directories for
 `DEST_PATH` if they do not exist.
 

components/cli/docs/reference/commandline/events.md

@@ -80,35 +80,68 @@ Docker images report the following events:
 
 Docker plugins report the following events:
 
-- `install`
 - `enable`
 - `disable`
+- `install`
 - `remove`
 
 #### Volumes
 
 Docker volumes report the following events:
 
 - `create`
+- `destroy`
 - `mount`
 - `unmount`
-- `destroy`
 
 #### Networks
 
 Docker networks report the following events:
 
 - `create`
 - `connect`
-- `disconnect`
 - `destroy`
+- `disconnect`
+- `remove`
 
 #### Daemons
 
 Docker daemons report the following events:
 
 - `reload`
 
+#### Services
+
+Docker services report the following events:
+
+- `create`
+- `remove`
+- `update`
+
+#### Nodes
+
+Docker nodes report the following events:
+
+- `create`
+- `remove`
+- `update`
+
+#### Secrets
+
+Docker secrets report the following events:
+
+- `create`
+- `remove`
+- `update`
+
+#### Configs
+
+Docker configs report the following events:
+
+- `create`
+- `remove`
+- `update`
+
 ### Limiting, filtering, and formatting the output
 
 #### Limit events by time
@@ -149,7 +182,8 @@ The currently supported filters are:
 * label (`label=<key>` or `label=<key>=<value>`)
 * network (`network=<name or id>`)
 * plugin (`plugin=<name or id>`)
-* type (`type=<container or image or volume or network or daemon or plugin>`)
+* scope (`scope=<local or swarm>`)
+* type (`type=<container or image or volume or network or daemon or plugin or service or node or secret or config>`)
 * volume (`volume=<name or id>`)
 
 #### Format
@@ -317,6 +351,29 @@ $ docker events --filter 'type=plugin'
 
 2016-07-25T17:30:14.825557616Z plugin pull ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest)
 2016-07-25T17:30:14.888127370Z plugin enable ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest)
+
+$ docker events -f type=service
+
+2017-07-12T06:34:07.999446625Z service create wj64st89fzgchxnhiqpn8p4oj (name=reverent_albattani)
+2017-07-12T06:34:21.405496207Z service remove wj64st89fzgchxnhiqpn8p4oj (name=reverent_albattani)
+
+$ docker events -f type=node
+
+2017-07-12T06:21:51.951586759Z node update 3xyz5ttp1a253q74z1thwywk9 (name=ip-172-31-23-42, state.new=ready, state.old=unknown)
+
+$ docker events -f type=secret
+
+2017-07-12T06:32:13.915704367Z secret create s8o6tmlnndrgzbmdilyy5ymju (name=new_secret)
+2017-07-12T06:32:37.052647783Z secret remove s8o6tmlnndrgzbmdilyy5ymju (name=new_secret)
+
+$  docker events -f type=config
+2017-07-12T06:44:13.349037127Z config create u96zlvzdfsyb9sg4mhyxfh3rl (name=abc)
+2017-07-12T06:44:36.327694184Z config remove u96zlvzdfsyb9sg4mhyxfh3rl (name=abc)
+
+$ docker events --filter 'scope=swarm'
+
+2017-07-10T07:46:50.250024503Z service create m8qcxu8081woyof7w3jaax6gk (name=affectionate_wilson)
+2017-07-10T07:47:31.093797134Z secret create 6g5pufzsv438p9tbvl9j94od4 (name=new_secret)
 ```
 
 ### Format the output

components/cli/docs/reference/commandline/search.md

@@ -94,7 +94,6 @@ radial/busyboxplus   Full-chain, Internet enabled, busybox made from scratch. Co
 The flag `--limit` is the maximum number of results returned by a search. This value could
 be in the range between 1 and 100. The default value of `--limit` is 25.
 
-
 ### Filtering
 
 The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more
@@ -103,9 +102,8 @@ than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bi
 The currently supported filters are:
 
 * stars (int - number of stars the image has)
-* is-automated (true|false) - is the image automated or not
-* is-official (true|false) - is the image official or not
-
+* is-automated (boolean - true or false) - is the image automated or not
+* is-official (boolean - true or false) - is the image official or not
 
 #### stars
 
@@ -121,7 +119,6 @@ progrium/busybox                                                     50
 radial/busyboxplus   Full-chain, Internet enabled, busybox made...   8                    [OK]
 ```
 
-
 #### is-automated
 
 This example displays images with a name containing 'busybox'

components/cli/docs/reference/commandline/service_create.md

@@ -23,6 +23,7 @@ Create a new service
 Options:
       --constraint list                    Placement constraints
       --container-label list               Container labels
+      --credential-spec                    Credential spec for managed service account (Windows only)
   -d, --detach                             Exit immediately instead of waiting for the service to converge (default true)
       --dns list                           Set custom DNS servers
       --dns-option list                    Set DNS options
@@ -779,6 +780,24 @@ $ docker service create --name dns-cache -p 53:53/tcp -p 53:53/udp dns-cache
 $ docker service create --name dns-cache -p 53:53/udp dns-cache
 ```
 
+### Provide credential specs for managed service accounts (Windows only)
+
+This option is only used for services using Windows containers. The
+`--credential-spec` must be in the format `file://<filename>` or
+`registry://<value-name>`.
+
+When using the `file://<filename>` format, the referenced file must be
+present in the `CredentialSpecs` subdirectory in the docker data directory,
+which defaults to `C:\ProgramData\Docker\` on Windows. For example,
+specifying `file://spec.json` loads `C:\ProgramData\Docker\CredentialSpecs\spec.json`.
+
+When using the `registry://<value-name>` format, the credential spec is
+read from the Windows registry on the daemon's host. The specified
+registry value must be located in:
+
+    HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs
+
+
 ### Create services using templates
 
 You can use templates for some flags of `service create`, using the syntax

components/cli/docs/reference/commandline/service_update.md

@@ -26,6 +26,7 @@ Options:
       --constraint-rm list                 Remove a constraint
       --container-label-add list           Add or update a container label
       --container-label-rm list            Remove a container label by its key
+      --credential-spec                    Credential spec for managed service account (Windows only)
   -d, --detach                             Exit immediately instead of waiting for the service to converge (default true)
       --dns-add list                       Add or update a custom DNS server
       --dns-option-add list                Add or update a DNS option

components/cli/docs/reference/commandline/volume_ls.md

@@ -168,11 +168,11 @@ Valid placeholders for the Go template are listed below:
 
 Placeholder   | Description
 --------------|------------------------------------------------------------------------------------------
-`.Name`       | Network name
-`.Driver`     | Network driver
-`.Scope`      | Network scope (local, global)
-`.Mountpoint` | Whether the network is internal or not.
-`.Labels`     | All labels assigned to the volume.
+`.Name`       | Volume name
+`.Driver`     | Volume driver
+`.Scope`      | Volume scope (local, global)
+`.Mountpoint` | The mount point of the volume on the host
+`.Labels`     | All labels assigned to the volume
 `.Label`      | Value of a specific label for this volume. For example `{{.Label "project.version"}}`
 
 When using the `--format` option, the `volume ls` command will either