Merge pull request #189 from tiborvass/update-docs

Update docs, completion, man

contrib/completion/zsh/_docker

@@ -2620,7 +2620,7 @@ __docker_subcommand() {
                 "($help)--default-gateway-v6[Container default gateway IPv6 address]:IPv6 address: " \
                 "($help)--default-shm-size=[Default shm size for containers]:size:" \
                 "($help)*--default-ulimit=[Default ulimits for containers]:ulimit: " \
-                "($help)--disable-legacy-registry[Disable contacting legacy registries]" \
+                "($help)--disable-legacy-registry[Disable contacting legacy registries (default true)]" \
                 "($help)*--dns=[DNS server to use]:DNS: " \
                 "($help)*--dns-opt=[DNS options to use]:DNS option: " \
                 "($help)*--dns-search=[DNS search domains to use]:DNS search: " \

docs/deprecated.md

@@ -138,7 +138,7 @@ on all subcommands (due to it conflicting with, e.g. `-h` / `--hostname` on
 ### `-e` and `--email` flags on `docker login`
 **Deprecated In Release: [v1.11.0](https://github.com/docker/docker/releases/tag/v1.11.0)**
 
-**Target For Removal In Release: v17.06**
+**Removed In Release: [v17.06](https://github.com/docker/docker-ce/releases/tag/v17.06.0-ce)**
 
 The docker login command is removing the ability to automatically register for an account with the target registry if the given username doesn't exist. Due to this change, the email flag is no longer required, and will be deprecated.
 
@@ -292,7 +292,7 @@ of the `--changes` flag that allows to pass `Dockerfile` commands.
 
 **Target For Removal In Release: v17.12**
 
-Version 1.9 adds a flag (`--disable-legacy-registry=false`) which prevents the
+Version 1.8.3 added a flag (`--disable-legacy-registry=false`) which prevents the
 docker daemon from `pull`, `push`, and `login` operations against v1
 registries.  Though enabled by default, this signals the intent to deprecate
 the v1 protocol.

docs/extend/legacy_plugins.md

@@ -87,8 +87,9 @@ Plugin
 
  Plugin                                                       | Description
 ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
- [Twistlock AuthZ Broker](https://github.com/twistlock/authz) | A basic extendable authorization plugin that runs directly on the host or inside a container. This plugin allows you to define user policies that it evaluates during authorization. Basic authorization is provided if Docker daemon is started with the --tlsverify flag (username is extracted from the certificate common name).
+[Casbin AuthZ Plugin](https://github.com/casbin/casbin-authz-plugin) | An authorization plugin based on [Casbin](https://github.com/casbin/casbin), which supports access control models like ACL, RBAC, ABAC. The access control model can be customized. The policy can be persisted into file or DB.
- [HBM plugin](https://github.com/kassisol/hbm)                | An authorization plugin that prevents from executing commands with certains parameters.
+[HBM plugin](https://github.com/kassisol/hbm)                 | An authorization plugin that prevents from executing commands with certains parameters.
+[Twistlock AuthZ Broker](https://github.com/twistlock/authz)  | A basic extendable authorization plugin that runs directly on the host or inside a container. This plugin allows you to define user policies that it evaluates during authorization. Basic authorization is provided if Docker daemon is started with the --tlsverify flag (username is extracted from the certificate common name).
 
 ## Troubleshooting a plugin
 

docs/reference/builder.md

@@ -94,8 +94,8 @@ instructions.
 Whenever possible, Docker will re-use the intermediate images (cache),
 to accelerate the `docker build` process significantly. This is indicated by
 the `Using cache` message in the console output.
-(For more information, see the [Build cache section](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/#/build-cache)) in the
+(For more information, see the [Build cache section](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/#build-cache) in the
-`Dockerfile` best practices guide:
+`Dockerfile` best practices guide):
 
     $ docker build -t svendowideit/ambassador .
     Sending build context to Docker daemon 15.36 kB
@@ -1281,18 +1281,28 @@ 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**:
+### Notes about specifying volumes
-> 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**:
+Keep the following things in mind about volumes in the `Dockerfile`.
-> If any build steps change the data within the volume after it has been
-> declared, those changes will be discarded.
 
-> **Note**:
+- **Volumes on Windows-based containers**: When using Windows-based containers,
-> The list is parsed as a JSON array, which means that
+  the destination of a volume inside the container must be one of:
-> you must use double-quotes (") around words not single-quotes (').
+  
+  - a non-existing or empty directory
+  - a drive other than `C:`
+
+- **Changing the volume from within the Dockerfile**: If any build steps change the
+  data within the volume after it has been declared, those changes will be discarded.
+
+- **JSON formatting**: The list is parsed as a JSON array.
+  You must enclose words with double quotes (`"`)rather than single quotes (`'`).
+
+- **The host directory is declared at container run-time**: The host directory
+  (the mountpoint) is, by its nature, host-dependent. This is to preserve image
+  portability. since a given host directory can't be guaranteed to be available
+  on all hosts.For this reason, you can't mount a host directory from
+  within the Dockerfile. The `VOLUME` instruction does not support specifying a `host-dir`
+  parameter.  You must specify the mountpoint when you create or run the container.
 
 ## USER
 

docs/reference/commandline/dockerd.md

@@ -42,7 +42,7 @@ Options:
       --default-gateway-v6 ip                 Container default gateway IPv6 address
       --default-runtime string                Default OCI runtime for containers (default "runc")
       --default-ulimit ulimit                 Default ulimits for containers (default [])
-      --disable-legacy-registry               Disable contacting legacy registries
+      --disable-legacy-registry               Disable contacting legacy registries (default true)
       --dns list                              DNS server to use (default [])
       --dns-opt list                          DNS options to use (default [])
       --dns-search list                       DNS search domains to use (default [])
@@ -901,7 +901,18 @@ system's list of trusted CAs instead of enabling `--insecure-registry`.
 
 ##### Legacy Registries
 
-Enabling `--disable-legacy-registry` forces a docker daemon to only interact with registries which support the V2 protocol.  Specifically, the daemon will not attempt `push`, `pull` and `login` to v1 registries.  The exception to this is `search` which can still be performed on v1 registries.
+Operations against registries supporting only the legacy v1 protocol are
+disabled by default. Specifically, the daemon will not attempt `push`,
+`pull` and `login` to v1 registries. The exception to this is `search`
+which can still be performed on v1 registries.
+
+Add `"disable-legacy-registry":false` to the [daemon configuration
+file](#daemon-configuration-file), or set the
+`--disable-legacy-registry=false` flag, if you need to interact with
+registries that have not yet migrated to the v2 protocol.
+
+Interaction v1 registries will no longer be supported in Docker v17.12,
+and the `disable-legacy-registry` configuration option will be removed.
 
 #### Running a Docker daemon behind an HTTPS_PROXY
 

docs/reference/commandline/node_ls.md

@@ -89,7 +89,7 @@ ID                         HOSTNAME       STATUS  AVAILABILITY  MANAGER STATUS
 1bcef6utixb0l0ca7gxuivsj0  swarm-worker2  Ready   Active
 ```
 
-#### membersip
+#### membership
 
 The `membership` filter matches nodes based on the presence of a `membership` and a value
 `accepted` or `pending`.

docs/reference/commandline/run.md

@@ -745,6 +745,41 @@ PS C:\> docker run -d --isolation default microsoft/nanoserver powershell echo h
 PS C:\> docker run -d --isolation hyperv microsoft/nanoserver powershell echo hyperv
 ```
 
+### Specify hard limits on memory available to containers (-m, --memory)
+
+These parameters always set an upper limit on the memory available to the container. On Linux, this
+is set on the cgroup and applications in a container can query it at `/sys/fs/cgroup/memory/memory.limit_in_bytes`.
+
+On Windows, this will affect containers differently depending on what type of isolation is used.
+
+- With `process` isolation, Windows will report the full memory of the host system, not the limit to applications running inside the container
+    ```powershell
+    docker run -it -m 2GB --isolation=process microsoft/nanoserver powershell Get-ComputerInfo *memory*
+
+    CsTotalPhysicalMemory      : 17064509440
+    CsPhyicallyInstalledMemory : 16777216
+    OsTotalVisibleMemorySize   : 16664560
+    OsFreePhysicalMemory       : 14646720
+    OsTotalVirtualMemorySize   : 19154928
+    OsFreeVirtualMemory        : 17197440
+    OsInUseVirtualMemory       : 1957488
+    OsMaxProcessMemorySize     : 137438953344
+    ```
+- With `hyperv` isolation, Windows will create a utility VM that is big enough to hold the memory limit, plus the minimal OS needed to host the container. That size is reported as "Total Physical Memory."
+    ```powershell
+    docker run -it -m 2GB --isolation=hyperv microsoft/nanoserver powershell Get-ComputerInfo *memory*
+
+    CsTotalPhysicalMemory      : 2683355136
+    CsPhyicallyInstalledMemory :
+    OsTotalVisibleMemorySize   : 2620464
+    OsFreePhysicalMemory       : 2306552
+    OsTotalVirtualMemorySize   : 2620464
+    OsFreeVirtualMemory        : 2356692
+    OsInUseVirtualMemory       : 263772
+    OsMaxProcessMemorySize     : 137438953344
+    ```
+
+
 ### Configure namespaced kernel parameters (sysctls) at runtime
 
 The `--sysctl` sets namespaced kernel parameters (sysctls) in the

docs/reference/run.md

@@ -1123,7 +1123,7 @@ by default a container is not allowed to access any devices, but a
 the documentation on [cgroups devices](https://www.kernel.org/doc/Documentation/cgroup-v1/devices.txt)).
 
 When the operator executes `docker run --privileged`, Docker will enable
-to access to all devices on the host as well as set some configuration
+access to all devices on the host as well as set some configuration
 in AppArmor or SELinux to allow the container nearly all the same access to the
 host as processes running outside containers on the host. Additional
 information about running with `--privileged` is available on the

man/dockerd.8.md

@@ -192,7 +192,7 @@ $ sudo dockerd --add-runtime runc=runc --add-runtime custom=/usr/local/bin/my-ru
   Default ulimits for containers.
 
 **--disable-legacy-registry**=*true*|*false*
-  Disable contacting legacy registries
+  Disable contacting legacy registries. Default is `true`.
 
 **--dns**=""
   Force Docker to use specific DNS servers