diff --git a/_data/engine-cli/docker.yaml b/_data/engine-cli/docker.yaml index 02b4c8fad4c..0203b520772 100644 --- a/_data/engine-cli/docker.yaml +++ b/_data/engine-cli/docker.yaml @@ -4,6 +4,7 @@ cname: - docker build - docker checkpoint - docker commit +- docker config - docker container - docker cp - docker create @@ -58,6 +59,7 @@ clink: - docker_build.yaml - docker_checkpoint.yaml - docker_commit.yaml +- docker_config.yaml - docker_container.yaml - docker_cp.yaml - docker_create.yaml diff --git a/_data/engine-cli/docker_attach.yaml b/_data/engine-cli/docker_attach.yaml index bd01b497f30..aa19ce9cc27 100644 --- a/_data/engine-cli/docker_attach.yaml +++ b/_data/engine-cli/docker_attach.yaml @@ -1,10 +1,18 @@ command: docker attach -short: Attach to a running container +short: Attach local standard input, output, and error streams to a running container long: |- - Use `docker attach` to attach to a running container using the container's ID - or name, either to view its ongoing output or to control it interactively. + Use `docker attach` to attach your terminal's standard input, output, and error + (or any combination of the three) to a running container using the container's + ID or name. This allows you to view its ongoing output or to control it + interactively, as though the commands were running directly in your terminal. + + > **Note:** + > The `attach` command will display the output of the `ENTRYPOINT/CMD` process. This + > can appear as if the attach command is hung when in fact the process may simply + > not be interacting with the terminal at that time. + You can attach to the same contained process multiple times simultaneously, - screen sharing style, or quickly view the progress of your detached process. + even as a different user with the appropriate permissions. To stop a container, use `CTRL-c`. This key sequence sends `SIGKILL` to the container. If `--sig-proxy` is true (the default),`CTRL-c` sends a `SIGINT` to diff --git a/_data/engine-cli/docker_build.yaml b/_data/engine-cli/docker_build.yaml index 2c6fc4029ad..725fcf1a052 100644 --- a/_data/engine-cli/docker_build.yaml +++ b/_data/engine-cli/docker_build.yaml @@ -13,17 +13,22 @@ long: |- ### Git repositories When the `URL` parameter points to the location of a Git repository, the - repository acts as the build context. The system recursively clones the - repository and its submodules using a `git clone --depth 1 --recursive` - command. This command runs in a temporary directory on your local host. After - the command succeeds, the directory is sent to the Docker daemon as the - context. Local clones give you the ability to access private repositories using - local user credentials, VPN's, and so forth. + repository acts as the build context. The system recursively fetches the + repository and its submodules. The commit history is not preserved. A + repository is first pulled into a temporary directory on your local host. After + the that succeeds, the directory is sent to the Docker daemon as the context. + Local copy gives you the ability to access private repositories using local + user credentials, VPN's, and so forth. + + > **Note:** + > If the `URL` parameter contains a fragment the system will recursively clone + > the repository and its submodules using a `git clone --recursive` command. Git URLs accept context configuration in their fragment section, separated by a colon `:`. The first part represents the reference that Git will check out, - this can be either a branch, a tag, or a commit SHA. The second part represents - a subdirectory inside the repository that will be used as a build context. + this can be either a branch, a tag, or a remote reference. The second part + represents a subdirectory inside the repository that will be used as a build + context. For example, run this command to use a directory called `docker` in the branch `container`: @@ -40,12 +45,11 @@ long: |- `myrepo.git` | `refs/heads/master` | `/` `myrepo.git#mytag` | `refs/tags/mytag` | `/` `myrepo.git#mybranch` | `refs/heads/mybranch` | `/` - `myrepo.git#abcdef` | `sha1 = abcdef` | `/` + `myrepo.git#pull/42/head` | `refs/pull/42/head` | `/` `myrepo.git#:myfolder` | `refs/heads/master` | `/myfolder` `myrepo.git#master:myfolder` | `refs/heads/master` | `/myfolder` `myrepo.git#mytag:myfolder` | `refs/tags/mytag` | `/myfolder` `myrepo.git#mybranch:myfolder` | `refs/heads/mybranch` | `/myfolder` - `myrepo.git#abcdef:myfolder` | `sha1 = abcdef` | `/myfolder` ### Tarball contexts @@ -103,8 +107,9 @@ usage: docker build [OPTIONS] PATH | URL | - pname: docker plink: docker.yaml options: +- option: add-host + description: Add a custom host-to-IP mapping (host:ip) - option: build-arg - default_value: '[]' description: Set build-time variables - option: cache-from default_value: '[]' @@ -137,15 +142,18 @@ options: - option: force-rm default_value: "false" description: Always remove intermediate containers +- option: iidfile + description: Write the image ID to the file - option: isolation description: Container isolation technology - option: label - default_value: '[]' description: Set metadata for an image - option: memory shorthand: m + default_value: "0" description: Memory limit - option: memory-swap + default_value: "0" description: | Swap limit equal to memory plus swap: '-1' to enable unlimited swap - option: network @@ -169,277 +177,182 @@ options: default_value: '[]' description: Security options - option: shm-size - description: Size of /dev/shm, default value is 64MB + default_value: "0" + description: Size of /dev/shm - option: squash default_value: "false" description: Squash newly built layers into a single new layer - option: tag shorthand: t - default_value: '[]' description: Name and optionally a tag in the 'name:tag' format +- option: target + description: Set the target build stage to build. - option: ulimit default_value: '[]' description: Ulimit options -examples: |- - ### Build with PATH - - ```bash - $ docker build . - - Uploading context 10240 bytes - Step 1/3 : FROM busybox - Pulling repository busybox - ---> e9aa60c60128MB/2.284 MB (100%) endpoint: https://cdn-registry-1.docker.io/v1/ - Step 2/3 : RUN ls -lh / - ---> Running in 9c9e81692ae9 - total 24 - drwxr-xr-x 2 root root 4.0K Mar 12 2013 bin - drwxr-xr-x 5 root root 4.0K Oct 19 00:19 dev - drwxr-xr-x 2 root root 4.0K Oct 19 00:19 etc - drwxr-xr-x 2 root root 4.0K Nov 15 23:34 lib - lrwxrwxrwx 1 root root 3 Mar 12 2013 lib64 -> lib - dr-xr-xr-x 116 root root 0 Nov 15 23:34 proc - lrwxrwxrwx 1 root root 3 Mar 12 2013 sbin -> bin - dr-xr-xr-x 13 root root 0 Nov 15 23:34 sys - drwxr-xr-x 2 root root 4.0K Mar 12 2013 tmp - drwxr-xr-x 2 root root 4.0K Nov 15 23:34 usr - ---> b35f4035db3f - Step 3/3 : CMD echo Hello world - ---> Running in 02071fceb21b - ---> f52f38b7823e - Successfully built f52f38b7823e - Removing intermediate container 9c9e81692ae9 - Removing intermediate container 02071fceb21b - ``` - - This example specifies that the `PATH` is `.`, and so all the files in the - local directory get `tar`d and sent to the Docker daemon. The `PATH` specifies - where to find the files for the "context" of the build on the Docker daemon. - Remember that the daemon could be running on a remote machine and that no - parsing of the Dockerfile happens at the client side (where you're running - `docker build`). That means that *all* the files at `PATH` get sent, not just - the ones listed to [*ADD*](../builder.md#add) in the Dockerfile. - - The transfer of context from the local machine to the Docker daemon is what the - `docker` client means when you see the "Sending build context" message. - - If you wish to keep the intermediate containers after the build is complete, - you must use `--rm=false`. This does not affect the build cache. - - ### Build with URL - - ```bash - $ docker build github.com/creack/docker-firefox - ``` - - This will clone the GitHub repository and use the cloned repository as context. - The Dockerfile at the root of the repository is used as Dockerfile. You can - specify an arbitrary Git repository by using the `git://` or `git@` scheme. - - ```bash - $ docker build -f ctx/Dockerfile http://server/ctx.tar.gz - - Downloading context: http://server/ctx.tar.gz [===================>] 240 B/240 B - Step 1/3 : FROM busybox - ---> 8c2e06607696 - Step 2/3 : ADD ctx/container.cfg / - ---> e7829950cee3 - Removing intermediate container b35224abf821 - Step 3/3 : CMD /bin/ls - ---> Running in fbc63d321d73 - ---> 3286931702ad - Removing intermediate container fbc63d321d73 - Successfully built 377c409b35e4 - ``` - - This sends the URL `http://server/ctx.tar.gz` to the Docker daemon, which - downloads and extracts the referenced tarball. The `-f ctx/Dockerfile` - parameter specifies a path inside `ctx.tar.gz` to the `Dockerfile` that is used - to build the image. Any `ADD` commands in that `Dockerfile` that refer to local - paths must be relative to the root of the contents inside `ctx.tar.gz`. In the - example above, the tarball contains a directory `ctx/`, so the `ADD - ctx/container.cfg /` operation works as expected. - - ### Build with - - - ```bash - $ docker build - < Dockerfile - ``` - - This will read a Dockerfile from `STDIN` without context. Due to the lack of a - context, no contents of any local directory will be sent to the Docker daemon. - Since there is no context, a Dockerfile `ADD` only works if it refers to a - remote URL. - - ```bash - $ docker build - < context.tar.gz - ``` - - This will build an image for a compressed context read from `STDIN`. Supported - formats are: bzip2, gzip and xz. - - ### Use a .dockerignore file - - ```bash - $ docker build . - - Uploading context 18.829 MB - Uploading context - Step 1/2 : FROM busybox - ---> 769b9341d937 - Step 2/2 : CMD echo Hello world - ---> Using cache - ---> 99cc1ad10469 - Successfully built 99cc1ad10469 - $ echo ".git" > .dockerignore - $ docker build . - Uploading context 6.76 MB - Uploading context - Step 1/2 : FROM busybox - ---> 769b9341d937 - Step 2/2 : CMD echo Hello world - ---> Using cache - ---> 99cc1ad10469 - Successfully built 99cc1ad10469 - ``` - - This example shows the use of the `.dockerignore` file to exclude the `.git` - directory from the context. Its effect can be seen in the changed size of the - uploaded context. The builder reference contains detailed information on - [creating a .dockerignore file](../builder.md#dockerignore-file) - - ### Tag an image (-t) - - ```bash - $ docker build -t vieux/apache:2.0 . - ``` - - This will build like the previous example, but it will then tag the resulting - image. The repository name will be `vieux/apache` and the tag will be `2.0`. - [Read more about valid tags](tag.md). - - You can apply multiple tags to an image. For example, you can apply the `latest` - tag to a newly built image and add another tag that references a specific - version. - For example, to tag an image both as `whenry/fedora-jboss:latest` and - `whenry/fedora-jboss:v2.1`, use the following: - - ```bash - $ docker build -t whenry/fedora-jboss:latest -t whenry/fedora-jboss:v2.1 . - ``` - ### Specify a Dockerfile (-f) - - ```bash - $ docker build -f Dockerfile.debug . - ``` - - This will use a file called `Dockerfile.debug` for the build instructions - instead of `Dockerfile`. - - ```bash - $ docker build -f dockerfiles/Dockerfile.debug -t myapp_debug . - $ docker build -f dockerfiles/Dockerfile.prod -t myapp_prod . - ``` - - The above commands will build the current build context (as specified by the - `.`) twice, once using a debug version of a `Dockerfile` and once using a - production version. - - ```bash - $ cd /home/me/myapp/some/dir/really/deep - $ docker build -f /home/me/myapp/dockerfiles/debug /home/me/myapp - $ docker build -f ../../../../dockerfiles/debug /home/me/myapp - ``` - - These two `docker build` commands do the exact same thing. They both use the - contents of the `debug` file instead of looking for a `Dockerfile` and will use - `/home/me/myapp` as the root of the build context. Note that `debug` is in the - directory structure of the build context, regardless of how you refer to it on - the command line. - - > **Note:** - > `docker build` will return a `no such file or directory` error if the - > file or directory does not exist in the uploaded context. This may - > happen if there is no context, or if you specify a file that is - > elsewhere on the Host system. The context is limited to the current - > directory (and its children) for security reasons, and to ensure - > repeatable builds on remote Docker hosts. This is also the reason why - > `ADD ../file` will not work. - - ### Use a custom parent cgroup (--cgroup-parent) - - When `docker build` is run with the `--cgroup-parent` option the containers - used in the build will be run with the [corresponding `docker run` - flag](../run.md#specifying-custom-cgroups). - - ### Set ulimits in container (--ulimit) - - Using the `--ulimit` option with `docker build` will cause each build step's - container to be started using those [`--ulimit` - flag values](./run.md#set-ulimits-in-container-ulimit). - - ### Set build-time variables (--build-arg) - - You can use `ENV` instructions in a Dockerfile to define variable - values. These values persist in the built image. However, often - persistence is not what you want. Users want to specify variables differently - depending on which host they build an image on. - - A good example is `http_proxy` or source versions for pulling intermediate - files. The `ARG` instruction lets Dockerfile authors define values that users - can set at build-time using the `--build-arg` flag: - - ```bash - $ docker build --build-arg HTTP_PROXY=http://10.20.30.2:1234 . - ``` - - This flag allows you to pass the build-time variables that are - accessed like regular environment variables in the `RUN` instruction of the - Dockerfile. Also, these values don't persist in the intermediate or final images - like `ENV` values do. - - Using this flag will not alter the output you see when the `ARG` lines from the - Dockerfile are echoed during the build process. - - For detailed information on using `ARG` and `ENV` instructions, see the - [Dockerfile reference](../builder.md). - - ### Optional security options (--security-opt) - - This flag is only supported on a daemon running on Windows, and only supports - the `credentialspec` option. The `credentialspec` must be in the format - `file://spec.txt` or `registry://keyname`. - - ### Specify isolation technology for container (--isolation) - - This option is useful in situations where you are running Docker containers on - Windows. The `--isolation=` option sets a container's isolation - technology. On Linux, the only supported is the `default` option which uses - Linux namespaces. On Microsoft Windows, you can specify these values: - - - | Value | Description | - |-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| - | `default` | Use the value specified by the Docker daemon's `--exec-opt` . If the `daemon` does not specify an isolation technology, Microsoft Windows uses `process` as its default value. | - | `process` | Namespace isolation only. | - | `hyperv` | Hyper-V hypervisor partition-based isolation. | - - Specifying the `--isolation` flag without a value is the same as setting `--isolation="default"`. - - - ### Squash an image's layers (--squash) **Experimental Only** - - Once the image is built, squash the new layers into a new image with a single - new layer. Squashing does not destroy any existing image, rather it creates a new - image with the content of the squshed layers. This effectively makes it look - like all `Dockerfile` commands were created with a single layer. The build - cache is preserved with this method. - - **Note**: using this option means the new image will not be able to take - advantage of layer sharing with other images and may use significantly more - space. - - **Note**: using this option you may see significantly more space used due to - storing two copies of the image, one for the build cache with all the cache - layers in tact, and one for the squashed version. +examples: "### Build with PATH\n\n```bash\n$ docker build .\n\nUploading context 10240 + bytes\nStep 1/3 : FROM busybox\nPulling repository busybox\n ---> e9aa60c60128MB/2.284 + MB (100%) endpoint: https://cdn-registry-1.docker.io/v1/\nStep 2/3 : RUN ls -lh + /\n ---> Running in 9c9e81692ae9\ntotal 24\ndrwxr-xr-x 2 root root 4.0K + Mar 12 2013 bin\ndrwxr-xr-x 5 root root 4.0K Oct 19 00:19 dev\ndrwxr-xr-x + \ 2 root root 4.0K Oct 19 00:19 etc\ndrwxr-xr-x 2 root root + \ 4.0K Nov 15 23:34 lib\nlrwxrwxrwx 1 root root 3 Mar 12 + \ 2013 lib64 -> lib\ndr-xr-xr-x 116 root root 0 Nov 15 23:34 proc\nlrwxrwxrwx + \ 1 root root 3 Mar 12 2013 sbin -> bin\ndr-xr-xr-x 13 root root + \ 0 Nov 15 23:34 sys\ndrwxr-xr-x 2 root root 4.0K Mar 12 + \ 2013 tmp\ndrwxr-xr-x 2 root root 4.0K Nov 15 23:34 usr\n ---> b35f4035db3f\nStep + 3/3 : CMD echo Hello world\n ---> Running in 02071fceb21b\n ---> f52f38b7823e\nSuccessfully + built f52f38b7823e\nRemoving intermediate container 9c9e81692ae9\nRemoving intermediate + container 02071fceb21b\n```\n\nThis example specifies that the `PATH` is `.`, and + so all the files in the\nlocal directory get `tar`d and sent to the Docker daemon. + The `PATH` specifies\nwhere to find the files for the \"context\" of the build on + the Docker daemon.\nRemember that the daemon could be running on a remote machine + and that no\nparsing of the Dockerfile happens at the client side (where you're + running\n`docker build`). That means that *all* the files at `PATH` get sent, not + just\nthe ones listed to [*ADD*](../builder.md#add) in the Dockerfile.\n\nThe transfer + of context from the local machine to the Docker daemon is what the\n`docker` client + means when you see the \"Sending build context\" message.\n\nIf you wish to keep + the intermediate containers after the build is complete,\nyou must use `--rm=false`. + This does not affect the build cache.\n\n### Build with URL\n\n```bash\n$ docker + build github.com/creack/docker-firefox\n```\n\nThis will clone the GitHub repository + and use the cloned repository as context.\nThe Dockerfile at the root of the repository + is used as Dockerfile. You can\nspecify an arbitrary Git repository by using the + `git://` or `git@` scheme.\n\n```bash\n$ docker build -f ctx/Dockerfile http://server/ctx.tar.gz\n\nDownloading + context: http://server/ctx.tar.gz [===================>] 240 B/240 B\nStep 1/3 + : FROM busybox\n ---> 8c2e06607696\nStep 2/3 : ADD ctx/container.cfg /\n ---> e7829950cee3\nRemoving + intermediate container b35224abf821\nStep 3/3 : CMD /bin/ls\n ---> Running in fbc63d321d73\n + ---> 3286931702ad\nRemoving intermediate container fbc63d321d73\nSuccessfully built + 377c409b35e4\n```\n\nThis sends the URL `http://server/ctx.tar.gz` to the Docker + daemon, which\ndownloads and extracts the referenced tarball. The `-f ctx/Dockerfile`\nparameter + specifies a path inside `ctx.tar.gz` to the `Dockerfile` that is used\nto build + the image. Any `ADD` commands in that `Dockerfile` that refers to local\npaths must + be relative to the root of the contents inside `ctx.tar.gz`. In the\nexample above, + the tarball contains a directory `ctx/`, so the `ADD\nctx/container.cfg /` operation + works as expected.\n\n### Build with -\n\n```bash\n$ docker build - < Dockerfile\n```\n\nThis + will read a Dockerfile from `STDIN` without context. Due to the lack of a\ncontext, + no contents of any local directory will be sent to the Docker daemon.\nSince there + is no context, a Dockerfile `ADD` only works if it refers to a\nremote URL.\n\n```bash\n$ + docker build - < context.tar.gz\n```\n\nThis will build an image for a compressed + context read from `STDIN`. Supported\nformats are: bzip2, gzip and xz.\n\n### Use + a .dockerignore file\n\n```bash\n$ docker build .\n\nUploading context 18.829 MB\nUploading + context\nStep 1/2 : FROM busybox\n ---> 769b9341d937\nStep 2/2 : CMD echo Hello + world\n ---> Using cache\n ---> 99cc1ad10469\nSuccessfully built 99cc1ad10469\n$ + echo \".git\" > .dockerignore\n$ docker build .\nUploading context 6.76 MB\nUploading + context\nStep 1/2 : FROM busybox\n ---> 769b9341d937\nStep 2/2 : CMD echo Hello + world\n ---> Using cache\n ---> 99cc1ad10469\nSuccessfully built 99cc1ad10469\n```\n\nThis + example shows the use of the `.dockerignore` file to exclude the `.git`\ndirectory + from the context. Its effect can be seen in the changed size of the\nuploaded context. + The builder reference contains detailed information on\n[creating a .dockerignore + file](../builder.md#dockerignore-file)\n\n### Tag an image (-t)\n\n```bash\n$ docker + build -t vieux/apache:2.0 .\n```\n\nThis will build like the previous example, but + it will then tag the resulting\nimage. The repository name will be `vieux/apache` + and the tag will be `2.0`.\n[Read more about valid tags](tag.md).\n\nYou can apply + multiple tags to an image. For example, you can apply the `latest`\ntag to a newly + built image and add another tag that references a specific\nversion.\nFor example, + to tag an image both as `whenry/fedora-jboss:latest` and\n`whenry/fedora-jboss:v2.1`, + use the following:\n\n```bash\n$ docker build -t whenry/fedora-jboss:latest -t whenry/fedora-jboss:v2.1 + .\n```\n\n### Specify a Dockerfile (-f)\n\n```bash\n$ docker build -f Dockerfile.debug + .\n```\n\nThis will use a file called `Dockerfile.debug` for the build instructions\ninstead + of `Dockerfile`.\n\n```bash\n$ curl example.com/remote/Dockerfile | docker build + -f - .\n```\n\nThe above command will use the current directory as the build context + and read\na Dockerfile from stdin.\n\n```bash\n$ docker build -f dockerfiles/Dockerfile.debug + -t myapp_debug .\n$ docker build -f dockerfiles/Dockerfile.prod -t myapp_prod .\n```\n\nThe + above commands will build the current build context (as specified by the\n`.`) twice, + once using a debug version of a `Dockerfile` and once using a\nproduction version.\n\n```bash\n$ + cd /home/me/myapp/some/dir/really/deep\n$ docker build -f /home/me/myapp/dockerfiles/debug + /home/me/myapp\n$ docker build -f ../../../../dockerfiles/debug /home/me/myapp\n```\n\nThese + two `docker build` commands do the exact same thing. They both use the\ncontents + of the `debug` file instead of looking for a `Dockerfile` and will use\n`/home/me/myapp` + as the root of the build context. Note that `debug` is in the\ndirectory structure + of the build context, regardless of how you refer to it on\nthe command line.\n\n> + **Note:**\n> `docker build` will return a `no such file or directory` error if the\n> + file or directory does not exist in the uploaded context. This may\n> happen if + there is no context, or if you specify a file that is\n> elsewhere on the Host system. + The context is limited to the current\n> directory (and its children) for security + reasons, and to ensure\n> repeatable builds on remote Docker hosts. This is also + the reason why\n> `ADD ../file` will not work.\n\n### Use a custom parent cgroup + (--cgroup-parent)\n\nWhen `docker build` is run with the `--cgroup-parent` option + the containers\nused in the build will be run with the [corresponding `docker run`\nflag](../run.md#specifying-custom-cgroups).\n\n### + Set ulimits in container (--ulimit)\n\nUsing the `--ulimit` option with `docker + build` will cause each build step's\ncontainer to be started using those [`--ulimit`\nflag + values](./run.md#set-ulimits-in-container-ulimit).\n\n### Set build-time variables + (--build-arg)\n\nYou can use `ENV` instructions in a Dockerfile to define variable\nvalues. + These values persist in the built image. However, often\npersistence is not what + you want. Users want to specify variables differently\ndepending on which host they + build an image on.\n\nA good example is `http_proxy` or source versions for pulling + intermediate\nfiles. The `ARG` instruction lets Dockerfile authors define values + that users\ncan set at build-time using the `--build-arg` flag:\n\n```bash\n$ docker + build --build-arg HTTP_PROXY=http://10.20.30.2:1234 .\n```\n\nThis flag allows you + to pass the build-time variables that are\naccessed like regular environment variables + in the `RUN` instruction of the\nDockerfile. Also, these values don't persist in + the intermediate or final images\nlike `ENV` values do.\n\nUsing this flag will + not alter the output you see when the `ARG` lines from the\nDockerfile are echoed + during the build process.\n\nFor detailed information on using `ARG` and `ENV` instructions, + see the\n[Dockerfile reference](../builder.md).\n\n### Optional security options + (--security-opt)\n\nThis flag is only supported on a daemon running on Windows, + and only supports\nthe `credentialspec` option. The `credentialspec` must be in + the format\n`file://spec.txt` or `registry://keyname`.\n\n### Specify isolation + technology for container (--isolation)\n\nThis option is useful in situations where + you are running Docker containers on\nWindows. The `--isolation=` option + sets a container's isolation\ntechnology. On Linux, the only supported is the `default` + option which uses\nLinux namespaces. On Microsoft Windows, you can specify these + values:\n\n\n| Value | Description |\n|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| + `default` | Use the value specified by the Docker daemon's `--exec-opt` . If the + `daemon` does not specify an isolation technology, Microsoft Windows uses `process` + as its default value. |\n| `process` | Namespace isolation only. |\n| + `hyperv` | Hyper-V hypervisor partition-based isolation. |\n\nSpecifying + the `--isolation` flag without a value is the same as setting `--isolation=\"default\"`.\n\n### + Add entries to container hosts file (--add-host)\n\nYou can add other hosts into + a container's `/etc/hosts` file by using one or\nmore `--add-host` flags. This example + adds a static address for a host named\n`docker`:\n\n $ docker build --add-host=docker:10.180.0.1 + .\n\n### Specifying target build stage (--target)\n\nWhen building a Dockerfile + with multiple build stages, `--target` can be used to\nspecify an intermediate build + stage by name as a final stage for the resulting\nimage. Commands after the target + stage will be skipped.\n\n```Dockerfile\nFROM debian AS build-env\n...\n\nFROM alpine + AS production-env\n...\n```\n\n```bash\n$ docker build -t mybuildimage --target + build-env .\n```\n\n### Squash an image's layers (--squash) **Experimental Only**\n\n#### + Overview\n\nOnce the image is built, squash the new layers into a new image with + a single\nnew layer. Squashing does not destroy any existing image, rather it creates + a new\nimage with the content of the squashed layers. This effectively makes it + look\nlike all `Dockerfile` commands were created with a single layer. The build\ncache + is preserved with this method.\n\n**Note**: using this option means the new image + will not be able to take\nadvantage of layer sharing with other images and may use + significantly more\nspace.\n\n**Note**: using this option you may see significantly + more space used due to\nstoring two copies of the image, one for the build cache + with all the cache\nlayers in tact, and one for the squashed version.\n\n#### Prerequisites\n\nThe + example on this page is using experimental mode in Docker 1.13.\n\nExperimental + mode can be enabled by using the `--experimental` flag when starting the Docker + daemon or setting `experimental: true` in the `daemon.json` configuration file.\n\nBy + default, experimental mode is disabled. To see the current configuration, use the + `docker version` command.\n\n```none\n\nServer:\n Version: 1.13.1\n API version: + \ 1.26 (minimum version 1.12)\n Go version: go1.7.5\n Git commit: 092cba3\n + Built: Wed Feb 8 06:35:24 2017\n OS/Arch: linux/amd64\n Experimental: + false\n\n [...]\n\n```\n\nTo enable experimental mode, users need to restart the + docker daemon with the experimental flag enabled.\n\n#### Enable Docker experimental\n\nExperimental + 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.\n\n```\n\n{\n + \ \"experimental\": true\n}\n\n```\nThen make sure the experimental flag is enabled:\n\n```bash\n\n$ + docker version -f '{{.Server.Experimental}}'\ntrue\n\n```\n\n#### Build an image + with `--squash` argument\n\nThe following is an example of docker build with `--squash` + argument\n\n```Dockerfile\n\nFROM busybox\nRUN echo hello > /hello\nRUN echo world + >> /hello\nRUN touch remove_me /remove_me\nENV HELLO world\nRUN rm /remove_me\n\n```\nAn + image named `test` is built with `--squash` argument.\n\n```bash\n\n$ docker build + --squash -t test .\n\n[...]\n\n```\n\nIf everything is right, the history will look + like this:\n\n```bash\n$ docker history test \n\nIMAGE CREATED CREATED + BY SIZE COMMENT\n4e10cb5b4cac + \ 3 seconds ago 12 B + \ merge sha256:88a7b0112a41826885df0e7072698006ee8f621c6ab99fca7fe9151d7b599702 + to sha256:47bcc53f74dc94b1920f0b34f6036096526296767650f223433fe65c35f149eb\n + \ 5 minutes ago /bin/sh -c rm /remove_me 0 + B\n 5 minutes ago /bin/sh -c #(nop) ENV HELLO=world 0 + B\n 5 minutes ago /bin/sh -c touch remove_me /remove_me + \ 0 B\n 5 minutes ago /bin/sh -c echo world >> + /hello 0 B\n 6 minutes ago /bin/sh -c echo + hello > /hello 0 B\n 7 weeks ago /bin/sh + -c #(nop) CMD [\"sh\"] 0 B\n 7 weeks ago /bin/sh + -c #(nop) ADD file:47ca6e777c36a4cfff 1.113 MB\n\n```\nWe could find that all + layer's name is ``, and there is a new layer with COMMENT `merge`.\n\nTest + the image, check for `/remove_me` being gone, make sure `hello\\nworld` is in `/hello`, + make sure the `HELLO` envvar's value is `world`." diff --git a/_data/engine-cli/docker_commit.yaml b/_data/engine-cli/docker_commit.yaml index affa9f2109b..beab5228e89 100644 --- a/_data/engine-cli/docker_commit.yaml +++ b/_data/engine-cli/docker_commit.yaml @@ -2,7 +2,7 @@ command: docker commit short: Create a new image from a container's changes long: |- It can be useful to commit a container's file changes or settings into a new - image. This allows you debug a container by running an interactive shell, or to + image. This allows you to debug a container by running an interactive shell, or to export a working dataset to another server. Generally, it is better to use Dockerfiles to manage your images in a documented and maintainable way. [Read more about valid image names and tags](tag.md). @@ -27,7 +27,6 @@ options: description: Author (e.g., "John Hannibal Smith ") - option: change shorthand: c - default_value: '[]' description: Apply Dockerfile instruction to the created image - option: message shorthand: m diff --git a/_data/engine-cli/docker_config.yaml b/_data/engine-cli/docker_config.yaml new file mode 100644 index 00000000000..b2d23a90a71 --- /dev/null +++ b/_data/engine-cli/docker_config.yaml @@ -0,0 +1,17 @@ +command: docker config +short: Manage Docker configs +long: Manage Docker configs +usage: docker config +pname: docker +plink: docker.yaml +cname: +- docker config create +- docker config inspect +- docker config ls +- docker config rm +clink: +- docker_config_create.yaml +- docker_config_inspect.yaml +- docker_config_ls.yaml +- docker_config_rm.yaml + diff --git a/_data/engine-cli/docker_config_create.yaml b/_data/engine-cli/docker_config_create.yaml new file mode 100644 index 00000000000..f8d8ff45766 --- /dev/null +++ b/_data/engine-cli/docker_config_create.yaml @@ -0,0 +1,11 @@ +command: docker config create +short: Create a configuration file from a file or STDIN as content +long: Create a configuration file from a file or STDIN as content +usage: docker config create [OPTIONS] CONFIG file|- +pname: docker config +plink: docker_config.yaml +options: +- option: label + shorthand: l + description: Config labels + diff --git a/_data/engine-cli/docker_config_inspect.yaml b/_data/engine-cli/docker_config_inspect.yaml new file mode 100644 index 00000000000..a441c92260a --- /dev/null +++ b/_data/engine-cli/docker_config_inspect.yaml @@ -0,0 +1,14 @@ +command: docker config inspect +short: Display detailed information on one or more configuration files +long: Display detailed information on one or more configuration files +usage: docker config inspect [OPTIONS] CONFIG [CONFIG...] +pname: docker config +plink: docker_config.yaml +options: +- option: format + shorthand: f + description: Format the output using the given Go template +- option: pretty + default_value: "false" + description: Print the information in a human friendly format + diff --git a/_data/engine-cli/docker_config_ls.yaml b/_data/engine-cli/docker_config_ls.yaml new file mode 100644 index 00000000000..541c9f836c2 --- /dev/null +++ b/_data/engine-cli/docker_config_ls.yaml @@ -0,0 +1,18 @@ +command: docker config ls +aliases: list +short: List configs +long: List configs +usage: docker config ls [OPTIONS] +pname: docker config +plink: docker_config.yaml +options: +- option: filter + shorthand: f + description: Filter output based on conditions provided +- option: format + description: Pretty-print configs using a Go template +- option: quiet + shorthand: q + default_value: "false" + description: Only display IDs + diff --git a/_data/engine-cli/docker_config_rm.yaml b/_data/engine-cli/docker_config_rm.yaml new file mode 100644 index 00000000000..09b0193ba37 --- /dev/null +++ b/_data/engine-cli/docker_config_rm.yaml @@ -0,0 +1,8 @@ +command: docker config rm +aliases: remove +short: Remove one or more configuration files +long: Remove one or more configuration files +usage: docker config rm CONFIG [CONFIG...] +pname: docker config +plink: docker_config.yaml + diff --git a/_data/engine-cli/docker_container_attach.yaml b/_data/engine-cli/docker_container_attach.yaml index dc7b6dc8119..57bfb30d8ad 100644 --- a/_data/engine-cli/docker_container_attach.yaml +++ b/_data/engine-cli/docker_container_attach.yaml @@ -1,6 +1,6 @@ command: docker container attach -short: Attach to a running container -long: Attach to a running container +short: Attach local standard input, output, and error streams to a running container +long: Attach local standard input, output, and error streams to a running container usage: docker container attach [OPTIONS] CONTAINER pname: docker container plink: docker_container.yaml diff --git a/_data/engine-cli/docker_container_commit.yaml b/_data/engine-cli/docker_container_commit.yaml index 02372e375ed..20eb407f475 100644 --- a/_data/engine-cli/docker_container_commit.yaml +++ b/_data/engine-cli/docker_container_commit.yaml @@ -10,7 +10,6 @@ options: description: Author (e.g., "John Hannibal Smith ") - option: change shorthand: c - default_value: '[]' description: Apply Dockerfile instruction to the created image - option: message shorthand: m diff --git a/_data/engine-cli/docker_container_cp.yaml b/_data/engine-cli/docker_container_cp.yaml index fd52ea518b2..0f00d09eec9 100644 --- a/_data/engine-cli/docker_container_cp.yaml +++ b/_data/engine-cli/docker_container_cp.yaml @@ -12,6 +12,10 @@ usage: "docker container cp [OPTIONS] CONTAINER:SRC_PATH DEST_PATH|-\n\tdocker c pname: docker container plink: docker_container.yaml options: +- option: archive + shorthand: a + default_value: "false" + description: Archive mode (copy all uid/gid information) - option: follow-link shorthand: L default_value: "false" diff --git a/_data/engine-cli/docker_container_create.yaml b/_data/engine-cli/docker_container_create.yaml index 44f6ba2d81c..108c51a8631 100644 --- a/_data/engine-cli/docker_container_create.yaml +++ b/_data/engine-cli/docker_container_create.yaml @@ -6,11 +6,9 @@ pname: docker container plink: docker_container.yaml options: - option: add-host - default_value: '[]' description: Add a custom host-to-IP mapping (host:ip) - option: attach shorthand: a - default_value: '[]' description: Attach to STDIN, STDOUT or STDERR - option: blkio-weight default_value: "0" @@ -20,10 +18,8 @@ options: default_value: '[]' description: Block IO weight (relative device weight) - option: cap-add - default_value: '[]' description: Add Linux capabilities - option: cap-drop - default_value: '[]' description: Drop Linux capabilities - option: cgroup-parent description: Optional parent cgroup for the container @@ -52,17 +48,15 @@ options: default_value: "0" description: CPU shares (relative weight) - option: cpus - default_value: "0.000" description: Number of CPUs - option: cpuset-cpus description: CPUs in which to allow execution (0-3, 0,1) - option: cpuset-mems description: MEMs in which to allow execution (0-3, 0,1) -- option: credentialspec - description: Credential spec for managed service account (Windows only) - option: device - default_value: '[]' description: Add a host device to the container +- option: device-cgroup-rule + description: Add a rule to the cgroup allowed devices list - option: device-read-bps default_value: '[]' description: Limit read rate (bytes per second) from a device @@ -79,44 +73,40 @@ options: default_value: "true" description: Skip image verification - option: dns - default_value: '[]' description: Set custom DNS servers - option: dns-opt - default_value: '[]' description: Set DNS options - option: dns-option - default_value: '[]' description: Set DNS options - option: dns-search - default_value: '[]' description: Set custom DNS search domains - option: entrypoint description: Overwrite the default ENTRYPOINT of the image - option: env shorthand: e - default_value: '[]' description: Set environment variables - option: env-file - default_value: '[]' description: Read in a file of environment variables - option: expose - default_value: '[]' description: Expose a port or a range of ports - option: group-add - default_value: '[]' description: Add additional groups to join - option: health-cmd description: Command to run to check health - option: health-interval default_value: 0s - description: Time between running the check (ns|us|ms|s|m|h) (default 0s) + description: Time between running the check (ms|s|m|h) (default 0s) - option: health-retries default_value: "0" description: Consecutive failures needed to report unhealthy +- option: health-start-period + default_value: 0s + description: | + Start period for the container to initialize before starting health-retries countdown (ms|s|m|h) (default 0s) - option: health-timeout default_value: 0s description: | - Maximum time to allow one check to run (ns|us|ms|s|m|h) (default 0s) + Maximum time to allow one check to run (ms|s|m|h) (default 0s) - option: help default_value: "false" description: Print usage @@ -127,72 +117,70 @@ options: default_value: "false" description: | Run an init inside the container that forwards signals and reaps processes -- option: init-path - description: Path to the docker-init binary - option: interactive shorthand: i default_value: "false" description: Keep STDIN open even if not attached - option: io-maxbandwidth + default_value: "0" description: | Maximum IO bandwidth limit for the system drive (Windows only) - option: io-maxiops default_value: "0" description: Maximum IOps limit for the system drive (Windows only) - option: ip - description: Container IPv4 address (e.g. 172.30.100.104) + description: IPv4 address (e.g., 172.30.100.104) - option: ip6 - description: Container IPv6 address (e.g. 2001:db8::33) + description: IPv6 address (e.g., 2001:db8::33) - option: ipc description: IPC namespace to use - option: isolation description: Container isolation technology - option: kernel-memory + default_value: "0" description: Kernel memory limit - option: label shorthand: l - default_value: '[]' description: Set meta data on a container - option: label-file - default_value: '[]' description: Read in a line delimited file of labels - option: link - default_value: '[]' description: Add link to another container - option: link-local-ip - default_value: '[]' description: Container IPv4/IPv6 link-local addresses - option: log-driver description: Logging driver for the container - option: log-opt - default_value: '[]' description: Log driver options - option: mac-address - description: Container MAC address (e.g. 92:d0:c6:0a:29:33) + description: Container MAC address (e.g., 92:d0:c6:0a:29:33) - option: memory shorthand: m + default_value: "0" description: Memory limit - option: memory-reservation + default_value: "0" description: Memory soft limit - option: memory-swap + default_value: "0" description: | Swap limit equal to memory plus swap: '-1' to enable unlimited swap - option: memory-swappiness default_value: "-1" description: Tune container memory swappiness (0 to 100) +- option: mount + description: Attach a filesystem mount to the container - option: name description: Assign a name to the container - option: net default_value: default description: Connect a container to a network - option: net-alias - default_value: '[]' description: Add network-scoped alias for the container - option: network default_value: default description: Connect a container to a network - option: network-alias - default_value: '[]' description: Add network-scoped alias for the container - option: no-healthcheck default_value: "false" @@ -213,7 +201,6 @@ options: description: Give extended privileges to this container - option: publish shorthand: p - default_value: '[]' description: Publish a container's port(s) to the host - option: publish-all shorthand: P @@ -231,24 +218,22 @@ options: - option: runtime description: Runtime to use for this container - option: security-opt - default_value: '[]' description: Security Options - option: shm-size - description: Size of /dev/shm, default value is 64MB + default_value: "0" + description: Size of /dev/shm - option: stop-signal default_value: SIGTERM - description: Signal to stop a container, SIGTERM by default + description: Signal to stop a container - option: stop-timeout default_value: "0" description: Timeout (in seconds) to stop a container - option: storage-opt - default_value: '[]' description: Storage driver options for the container - option: sysctl default_value: map[] description: Sysctl options - option: tmpfs - default_value: '[]' description: Mount a tmpfs directory - option: tty shorthand: t @@ -266,12 +251,10 @@ options: description: UTS namespace to use - option: volume shorthand: v - default_value: '[]' description: Bind mount a volume - option: volume-driver description: Optional volume driver for the container - option: volumes-from - default_value: '[]' description: Mount volumes from the specified container(s) - option: workdir shorthand: w diff --git a/_data/engine-cli/docker_container_exec.yaml b/_data/engine-cli/docker_container_exec.yaml index c7f9156ae00..8d74e2738ca 100644 --- a/_data/engine-cli/docker_container_exec.yaml +++ b/_data/engine-cli/docker_container_exec.yaml @@ -13,7 +13,6 @@ options: description: Override the key sequence for detaching a container - option: env shorthand: e - default_value: '[]' description: Set environment variables - option: interactive shorthand: i diff --git a/_data/engine-cli/docker_container_logs.yaml b/_data/engine-cli/docker_container_logs.yaml index 7a70ce23353..456295e7c6a 100644 --- a/_data/engine-cli/docker_container_logs.yaml +++ b/_data/engine-cli/docker_container_logs.yaml @@ -13,7 +13,8 @@ options: default_value: "false" description: Follow log output - option: since - description: Show logs since timestamp + description: | + Show logs since timestamp (e.g. 2013-01-02T13:23:37) or relative (e.g. 42m for 42 minutes) - option: tail default_value: all description: Number of lines to show from the end of the logs diff --git a/_data/engine-cli/docker_container_prune.yaml b/_data/engine-cli/docker_container_prune.yaml index cddfed4032d..5185350289c 100644 --- a/_data/engine-cli/docker_container_prune.yaml +++ b/_data/engine-cli/docker_container_prune.yaml @@ -5,6 +5,8 @@ usage: docker container prune [OPTIONS] pname: docker container plink: docker_container.yaml options: +- option: filter + description: Provide filter values (e.g. 'until=') - option: force shorthand: f default_value: "false" @@ -23,3 +25,74 @@ examples: |- Total reclaimed space: 212 B ``` + ### Filtering + + The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more + than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) + + The currently supported filters are: + + * until (``) - only remove containers created before given timestamp + * label (`label=`, `label==`, `label!=`, or `label!==`) - only remove containers with (or without, in case `label!=...` is used) the specified labels. + + The `until` filter can be Unix timestamps, date formatted + timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed + relative to the daemon machine’s time. Supported formats for date + formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, + `2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local + timezone on the daemon will be used if you do not provide either a `Z` or a + `+-00:00` timezone offset at the end of the timestamp. When providing Unix + timestamps enter seconds[.nanoseconds], where seconds is the number of seconds + that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap + seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a + fraction of a second no more than nine digits long. + + The `label` filter accepts two formats. One is the `label=...` (`label=` or `label==`), + which removes containers with the specified labels. The other + format is the `label!=...` (`label!=` or `label!==`), which removes + containers without the specified labels. + + The following removes containers created more than 5 minutes ago: + + ```bash + $ docker ps -a --format 'table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.CreatedAt}}\t{{.Status}}' + + CONTAINER ID IMAGE COMMAND CREATED AT STATUS + 61b9efa71024 busybox "sh" 2017-01-04 13:23:33 -0800 PST Exited (0) 41 seconds ago + 53a9bc23a516 busybox "sh" 2017-01-04 13:11:59 -0800 PST Exited (0) 12 minutes ago + + $ docker container prune --force --filter "until=5m" + + Deleted Containers: + 53a9bc23a5168b6caa2bfbefddf1b30f93c7ad57f3dec271fd32707497cb9369 + + Total reclaimed space: 25 B + + $ docker ps -a --format 'table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.CreatedAt}}\t{{.Status}}' + + CONTAINER ID IMAGE COMMAND CREATED AT STATUS + 61b9efa71024 busybox "sh" 2017-01-04 13:23:33 -0800 PST Exited (0) 44 seconds ago + ``` + + The following removes containers created before `2017-01-04T13:10:00`: + + ```bash + $ docker ps -a --format 'table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.CreatedAt}}\t{{.Status}}' + + CONTAINER ID IMAGE COMMAND CREATED AT STATUS + 53a9bc23a516 busybox "sh" 2017-01-04 13:11:59 -0800 PST Exited (0) 7 minutes ago + 4a75091a6d61 busybox "sh" 2017-01-04 13:09:53 -0800 PST Exited (0) 9 minutes ago + + $ docker container prune --force --filter "until=2017-01-04T13:10:00" + + Deleted Containers: + 4a75091a6d618526fcd8b33ccd6e5928ca2a64415466f768a6180004b0c72c6c + + Total reclaimed space: 27 B + + $ docker ps -a --format 'table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.CreatedAt}}\t{{.Status}}' + + CONTAINER ID IMAGE COMMAND CREATED AT STATUS + 53a9bc23a516 busybox "sh" 2017-01-04 13:11:59 -0800 PST Exited (0) 9 minutes ago + ``` + diff --git a/_data/engine-cli/docker_container_run.yaml b/_data/engine-cli/docker_container_run.yaml index da091b65201..3afcc0d5b9d 100644 --- a/_data/engine-cli/docker_container_run.yaml +++ b/_data/engine-cli/docker_container_run.yaml @@ -6,11 +6,9 @@ pname: docker container plink: docker_container.yaml options: - option: add-host - default_value: '[]' description: Add a custom host-to-IP mapping (host:ip) - option: attach shorthand: a - default_value: '[]' description: Attach to STDIN, STDOUT or STDERR - option: blkio-weight default_value: "0" @@ -20,10 +18,8 @@ options: default_value: '[]' description: Block IO weight (relative device weight) - option: cap-add - default_value: '[]' description: Add Linux capabilities - option: cap-drop - default_value: '[]' description: Drop Linux capabilities - option: cgroup-parent description: Optional parent cgroup for the container @@ -52,14 +48,11 @@ options: default_value: "0" description: CPU shares (relative weight) - option: cpus - default_value: "0.000" description: Number of CPUs - option: cpuset-cpus description: CPUs in which to allow execution (0-3, 0,1) - option: cpuset-mems description: MEMs in which to allow execution (0-3, 0,1) -- option: credentialspec - description: Credential spec for managed service account (Windows only) - option: detach shorthand: d default_value: "false" @@ -67,8 +60,9 @@ options: - option: detach-keys description: Override the key sequence for detaching a container - option: device - default_value: '[]' description: Add a host device to the container +- option: device-cgroup-rule + description: Add a rule to the cgroup allowed devices list - option: device-read-bps default_value: '[]' description: Limit read rate (bytes per second) from a device @@ -85,44 +79,40 @@ options: default_value: "true" description: Skip image verification - option: dns - default_value: '[]' description: Set custom DNS servers - option: dns-opt - default_value: '[]' description: Set DNS options - option: dns-option - default_value: '[]' description: Set DNS options - option: dns-search - default_value: '[]' description: Set custom DNS search domains - option: entrypoint description: Overwrite the default ENTRYPOINT of the image - option: env shorthand: e - default_value: '[]' description: Set environment variables - option: env-file - default_value: '[]' description: Read in a file of environment variables - option: expose - default_value: '[]' description: Expose a port or a range of ports - option: group-add - default_value: '[]' description: Add additional groups to join - option: health-cmd description: Command to run to check health - option: health-interval default_value: 0s - description: Time between running the check (ns|us|ms|s|m|h) (default 0s) + description: Time between running the check (ms|s|m|h) (default 0s) - option: health-retries default_value: "0" description: Consecutive failures needed to report unhealthy +- option: health-start-period + default_value: 0s + description: | + Start period for the container to initialize before starting health-retries countdown (ms|s|m|h) (default 0s) - option: health-timeout default_value: 0s description: | - Maximum time to allow one check to run (ns|us|ms|s|m|h) (default 0s) + Maximum time to allow one check to run (ms|s|m|h) (default 0s) - option: help default_value: "false" description: Print usage @@ -133,72 +123,70 @@ options: default_value: "false" description: | Run an init inside the container that forwards signals and reaps processes -- option: init-path - description: Path to the docker-init binary - option: interactive shorthand: i default_value: "false" description: Keep STDIN open even if not attached - option: io-maxbandwidth + default_value: "0" description: | Maximum IO bandwidth limit for the system drive (Windows only) - option: io-maxiops default_value: "0" description: Maximum IOps limit for the system drive (Windows only) - option: ip - description: Container IPv4 address (e.g. 172.30.100.104) + description: IPv4 address (e.g., 172.30.100.104) - option: ip6 - description: Container IPv6 address (e.g. 2001:db8::33) + description: IPv6 address (e.g., 2001:db8::33) - option: ipc description: IPC namespace to use - option: isolation description: Container isolation technology - option: kernel-memory + default_value: "0" description: Kernel memory limit - option: label shorthand: l - default_value: '[]' description: Set meta data on a container - option: label-file - default_value: '[]' description: Read in a line delimited file of labels - option: link - default_value: '[]' description: Add link to another container - option: link-local-ip - default_value: '[]' description: Container IPv4/IPv6 link-local addresses - option: log-driver description: Logging driver for the container - option: log-opt - default_value: '[]' description: Log driver options - option: mac-address - description: Container MAC address (e.g. 92:d0:c6:0a:29:33) + description: Container MAC address (e.g., 92:d0:c6:0a:29:33) - option: memory shorthand: m + default_value: "0" description: Memory limit - option: memory-reservation + default_value: "0" description: Memory soft limit - option: memory-swap + default_value: "0" description: | Swap limit equal to memory plus swap: '-1' to enable unlimited swap - option: memory-swappiness default_value: "-1" description: Tune container memory swappiness (0 to 100) +- option: mount + description: Attach a filesystem mount to the container - option: name description: Assign a name to the container - option: net default_value: default description: Connect a container to a network - option: net-alias - default_value: '[]' description: Add network-scoped alias for the container - option: network default_value: default description: Connect a container to a network - option: network-alias - default_value: '[]' description: Add network-scoped alias for the container - option: no-healthcheck default_value: "false" @@ -219,7 +207,6 @@ options: description: Give extended privileges to this container - option: publish shorthand: p - default_value: '[]' description: Publish a container's port(s) to the host - option: publish-all shorthand: P @@ -237,27 +224,25 @@ options: - option: runtime description: Runtime to use for this container - option: security-opt - default_value: '[]' description: Security Options - option: shm-size - description: Size of /dev/shm, default value is 64MB + default_value: "0" + description: Size of /dev/shm - option: sig-proxy default_value: "true" description: Proxy received signals to the process - option: stop-signal default_value: SIGTERM - description: Signal to stop a container, SIGTERM by default + description: Signal to stop a container - option: stop-timeout default_value: "0" description: Timeout (in seconds) to stop a container - option: storage-opt - default_value: '[]' description: Storage driver options for the container - option: sysctl default_value: map[] description: Sysctl options - option: tmpfs - default_value: '[]' description: Mount a tmpfs directory - option: tty shorthand: t @@ -275,12 +260,10 @@ options: description: UTS namespace to use - option: volume shorthand: v - default_value: '[]' description: Bind mount a volume - option: volume-driver description: Optional volume driver for the container - option: volumes-from - default_value: '[]' description: Mount volumes from the specified container(s) - option: workdir shorthand: w diff --git a/_data/engine-cli/docker_container_update.yaml b/_data/engine-cli/docker_container_update.yaml index 3cb08f65d05..1c7137cd96d 100644 --- a/_data/engine-cli/docker_container_update.yaml +++ b/_data/engine-cli/docker_container_update.yaml @@ -25,18 +25,24 @@ options: shorthand: c default_value: "0" description: CPU shares (relative weight) +- option: cpus + description: Number of CPUs - option: cpuset-cpus description: CPUs in which to allow execution (0-3, 0,1) - option: cpuset-mems description: MEMs in which to allow execution (0-3, 0,1) - option: kernel-memory + default_value: "0" description: Kernel memory limit - option: memory shorthand: m + default_value: "0" description: Memory limit - option: memory-reservation + default_value: "0" description: Memory soft limit - option: memory-swap + default_value: "0" description: | Swap limit equal to memory plus swap: '-1' to enable unlimited swap - option: restart diff --git a/_data/engine-cli/docker_cp.yaml b/_data/engine-cli/docker_cp.yaml index f34fdeceb53..839416c24e0 100644 --- a/_data/engine-cli/docker_cp.yaml +++ b/_data/engine-cli/docker_cp.yaml @@ -86,6 +86,10 @@ usage: "docker cp [OPTIONS] CONTAINER:SRC_PATH DEST_PATH|-\n\tdocker cp [OPTIONS pname: docker plink: docker.yaml options: +- option: archive + shorthand: a + default_value: "false" + description: Archive mode (copy all uid/gid information) - option: follow-link shorthand: L default_value: "false" diff --git a/_data/engine-cli/docker_create.yaml b/_data/engine-cli/docker_create.yaml index 1ec480ce04e..8529e8ff2ab 100644 --- a/_data/engine-cli/docker_create.yaml +++ b/_data/engine-cli/docker_create.yaml @@ -17,11 +17,9 @@ pname: docker plink: docker.yaml options: - option: add-host - default_value: '[]' description: Add a custom host-to-IP mapping (host:ip) - option: attach shorthand: a - default_value: '[]' description: Attach to STDIN, STDOUT or STDERR - option: blkio-weight default_value: "0" @@ -31,10 +29,8 @@ options: default_value: '[]' description: Block IO weight (relative device weight) - option: cap-add - default_value: '[]' description: Add Linux capabilities - option: cap-drop - default_value: '[]' description: Drop Linux capabilities - option: cgroup-parent description: Optional parent cgroup for the container @@ -63,17 +59,15 @@ options: default_value: "0" description: CPU shares (relative weight) - option: cpus - default_value: "0.000" description: Number of CPUs - option: cpuset-cpus description: CPUs in which to allow execution (0-3, 0,1) - option: cpuset-mems description: MEMs in which to allow execution (0-3, 0,1) -- option: credentialspec - description: Credential spec for managed service account (Windows only) - option: device - default_value: '[]' description: Add a host device to the container +- option: device-cgroup-rule + description: Add a rule to the cgroup allowed devices list - option: device-read-bps default_value: '[]' description: Limit read rate (bytes per second) from a device @@ -90,44 +84,40 @@ options: default_value: "true" description: Skip image verification - option: dns - default_value: '[]' description: Set custom DNS servers - option: dns-opt - default_value: '[]' description: Set DNS options - option: dns-option - default_value: '[]' description: Set DNS options - option: dns-search - default_value: '[]' description: Set custom DNS search domains - option: entrypoint description: Overwrite the default ENTRYPOINT of the image - option: env shorthand: e - default_value: '[]' description: Set environment variables - option: env-file - default_value: '[]' description: Read in a file of environment variables - option: expose - default_value: '[]' description: Expose a port or a range of ports - option: group-add - default_value: '[]' description: Add additional groups to join - option: health-cmd description: Command to run to check health - option: health-interval default_value: 0s - description: Time between running the check (ns|us|ms|s|m|h) (default 0s) + description: Time between running the check (ms|s|m|h) (default 0s) - option: health-retries default_value: "0" description: Consecutive failures needed to report unhealthy +- option: health-start-period + default_value: 0s + description: | + Start period for the container to initialize before starting health-retries countdown (ms|s|m|h) (default 0s) - option: health-timeout default_value: 0s description: | - Maximum time to allow one check to run (ns|us|ms|s|m|h) (default 0s) + Maximum time to allow one check to run (ms|s|m|h) (default 0s) - option: help default_value: "false" description: Print usage @@ -138,72 +128,70 @@ options: default_value: "false" description: | Run an init inside the container that forwards signals and reaps processes -- option: init-path - description: Path to the docker-init binary - option: interactive shorthand: i default_value: "false" description: Keep STDIN open even if not attached - option: io-maxbandwidth + default_value: "0" description: | Maximum IO bandwidth limit for the system drive (Windows only) - option: io-maxiops default_value: "0" description: Maximum IOps limit for the system drive (Windows only) - option: ip - description: Container IPv4 address (e.g. 172.30.100.104) + description: IPv4 address (e.g., 172.30.100.104) - option: ip6 - description: Container IPv6 address (e.g. 2001:db8::33) + description: IPv6 address (e.g., 2001:db8::33) - option: ipc description: IPC namespace to use - option: isolation description: Container isolation technology - option: kernel-memory + default_value: "0" description: Kernel memory limit - option: label shorthand: l - default_value: '[]' description: Set meta data on a container - option: label-file - default_value: '[]' description: Read in a line delimited file of labels - option: link - default_value: '[]' description: Add link to another container - option: link-local-ip - default_value: '[]' description: Container IPv4/IPv6 link-local addresses - option: log-driver description: Logging driver for the container - option: log-opt - default_value: '[]' description: Log driver options - option: mac-address - description: Container MAC address (e.g. 92:d0:c6:0a:29:33) + description: Container MAC address (e.g., 92:d0:c6:0a:29:33) - option: memory shorthand: m + default_value: "0" description: Memory limit - option: memory-reservation + default_value: "0" description: Memory soft limit - option: memory-swap + default_value: "0" description: | Swap limit equal to memory plus swap: '-1' to enable unlimited swap - option: memory-swappiness default_value: "-1" description: Tune container memory swappiness (0 to 100) +- option: mount + description: Attach a filesystem mount to the container - option: name description: Assign a name to the container - option: net default_value: default description: Connect a container to a network - option: net-alias - default_value: '[]' description: Add network-scoped alias for the container - option: network default_value: default description: Connect a container to a network - option: network-alias - default_value: '[]' description: Add network-scoped alias for the container - option: no-healthcheck default_value: "false" @@ -224,7 +212,6 @@ options: description: Give extended privileges to this container - option: publish shorthand: p - default_value: '[]' description: Publish a container's port(s) to the host - option: publish-all shorthand: P @@ -242,24 +229,22 @@ options: - option: runtime description: Runtime to use for this container - option: security-opt - default_value: '[]' description: Security Options - option: shm-size - description: Size of /dev/shm, default value is 64MB + default_value: "0" + description: Size of /dev/shm - option: stop-signal default_value: SIGTERM - description: Signal to stop a container, SIGTERM by default + description: Signal to stop a container - option: stop-timeout default_value: "0" description: Timeout (in seconds) to stop a container - option: storage-opt - default_value: '[]' description: Storage driver options for the container - option: sysctl default_value: map[] description: Sysctl options - option: tmpfs - default_value: '[]' description: Mount a tmpfs directory - option: tty shorthand: t @@ -277,12 +262,10 @@ options: description: UTS namespace to use - option: volume shorthand: v - default_value: '[]' description: Bind mount a volume - option: volume-driver description: Optional volume driver for the container - option: volumes-from - default_value: '[]' description: Mount volumes from the specified container(s) - option: workdir shorthand: w @@ -373,3 +356,26 @@ examples: |- Specifying the `--isolation` flag without a value is the same as setting `--isolation="default"`. + ### Dealing with dynamically created devices (--device-cgroup-rule) + + Devices available to a container are assigned at creation time. The + assigned devices will both be added to the cgroup.allow file and + created into the container once it is run. This poses a problem when + a new device needs to be added to running container. + + One of the solution is to add a more permissive rule to a container + allowing it access to a wider range of devices. For example, supposing + our container needs access to a character device with major `42` and + any number of minor number (added as new devices appear), the + following rule would be added: + + ``` + docker create --device-cgroup-rule='c 42:* rmw' -name my-container my-image + ``` + + Then, a user could ask `udev` to execute a script that would `docker exec my-container mknod newDevX c 42 ` + the required device when it is added. + + NOTE: initially present devices still need to be explicitely added to + the create/run command + diff --git a/_data/engine-cli/docker_deploy.yaml b/_data/engine-cli/docker_deploy.yaml index 59557b35f01..fec5692689d 100644 --- a/_data/engine-cli/docker_deploy.yaml +++ b/_data/engine-cli/docker_deploy.yaml @@ -12,6 +12,9 @@ options: - option: compose-file shorthand: c description: Path to a Compose file +- option: prune + default_value: "false" + description: Prune services that are no longer referenced - option: with-registry-auth default_value: "false" description: Send registry authentication details to Swarm agents diff --git a/_data/engine-cli/docker_events.yaml b/_data/engine-cli/docker_events.yaml index 73e0306089f..d6816b5262e 100644 --- a/_data/engine-cli/docker_events.yaml +++ b/_data/engine-cli/docker_events.yaml @@ -120,7 +120,7 @@ long: |- * label (`label=` or `label==`) * network (`network=`) * plugin (`plugin=`) - * type (`type=`) + * type (`type=`) * volume (`volume=`) #### Format @@ -294,11 +294,7 @@ examples: |- 2015-12-23T21:38:24.705709133Z network create 8b111217944ba0ba844a65b13efcd57dc494932ee2527577758f939315ba2c5b (name=test-event-network-local, type=bridge) 2015-12-23T21:38:25.119625123Z network connect 8b111217944ba0ba844a65b13efcd57dc494932ee2527577758f939315ba2c5b (name=test-event-network-local, container=b4be644031a3d90b400f88ab3d4bdf4dc23adb250e696b6328b85441abe2c54e, type=bridge) - ``` - - The `type=plugin` filter is experimental. - ```bash $ docker events --filter 'type=plugin' 2016-07-25T17:30:14.825557616Z plugin pull ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest) diff --git a/_data/engine-cli/docker_exec.yaml b/_data/engine-cli/docker_exec.yaml index 63d4cfec01d..36b59b8e013 100644 --- a/_data/engine-cli/docker_exec.yaml +++ b/_data/engine-cli/docker_exec.yaml @@ -6,6 +6,14 @@ long: |- The command started using `docker exec` only runs while the container's primary process (`PID 1`) is running, and it is not restarted if the container is restarted. + + COMMAND will run in the default directory of the container. It the + underlying image has a custom directory specified with the WORKDIR directive + in its Dockerfile, this will be used instead. + + COMMAND should be an executable, a chained or a quoted command + will not work. Example: `docker exec -ti my_container "echo a && echo b"` will + not work, but `docker exec -ti my_container sh -c "echo a && echo b"` will. usage: docker exec [OPTIONS] CONTAINER COMMAND [ARG...] pname: docker plink: docker.yaml @@ -18,7 +26,6 @@ options: description: Override the key sequence for detaching a container - option: env shorthand: e - default_value: '[]' description: Set environment variables - option: interactive shorthand: i diff --git a/_data/engine-cli/docker_history.yaml b/_data/engine-cli/docker_history.yaml index 95a134db26c..e3ed71efb7b 100644 --- a/_data/engine-cli/docker_history.yaml +++ b/_data/engine-cli/docker_history.yaml @@ -5,6 +5,8 @@ usage: docker history [OPTIONS] IMAGE pname: docker plink: docker.yaml options: +- option: format + description: Pretty-print images using a Go template - option: human shorthand: H default_value: "true" @@ -42,3 +44,39 @@ examples: |- 511136ea3c5a 19 months ago 0 B Imported from - ``` + ### Format the output + + The formatting option (`--format`) will pretty-prints history output + using a Go template. + + Valid placeholders for the Go template are listed below: + + | Placeholder | Description | + | --------------- | ----------- | + | `.ID` | Image ID | + | `.CreatedSince` | Elapsed time since the image was created if `--human=true`, otherwise timestamp of when image was created | + | `.CreatedAt` | Timestamp of when image was created | + | `.CreatedBy` | Command that was used to create the image | + | `.Size` | Image disk size | + | `.Comment` | Comment for image | + + When using the `--format` option, the `history` command will either + output the data exactly as the template declares or, when using the + `table` directive, will include column headers as well. + + The following example uses a template without headers and outputs the + `ID` and `CreatedSince` entries separated by a colon for all images: + + ```bash + $ docker images --format "{{.ID}}: {{.Created}} ago" + + cc1b61406712: 2 weeks ago + : 2 weeks ago + : 2 weeks ago + : 2 weeks ago + : 2 weeks ago + : 3 weeks ago + : 3 weeks ago + : 3 weeks ago + ``` + diff --git a/_data/engine-cli/docker_image_build.yaml b/_data/engine-cli/docker_image_build.yaml index eacdec86b5d..4a4cdc803a4 100644 --- a/_data/engine-cli/docker_image_build.yaml +++ b/_data/engine-cli/docker_image_build.yaml @@ -5,8 +5,9 @@ usage: docker image build [OPTIONS] PATH | URL | - pname: docker image plink: docker_image.yaml options: +- option: add-host + description: Add a custom host-to-IP mapping (host:ip) - option: build-arg - default_value: '[]' description: Set build-time variables - option: cache-from default_value: '[]' @@ -39,15 +40,18 @@ options: - option: force-rm default_value: "false" description: Always remove intermediate containers +- option: iidfile + description: Write the image ID to the file - option: isolation description: Container isolation technology - option: label - default_value: '[]' description: Set metadata for an image - option: memory shorthand: m + default_value: "0" description: Memory limit - option: memory-swap + default_value: "0" description: | Swap limit equal to memory plus swap: '-1' to enable unlimited swap - option: network @@ -71,14 +75,16 @@ options: default_value: '[]' description: Security options - option: shm-size - description: Size of /dev/shm, default value is 64MB + default_value: "0" + description: Size of /dev/shm - option: squash default_value: "false" description: Squash newly built layers into a single new layer - option: tag shorthand: t - default_value: '[]' description: Name and optionally a tag in the 'name:tag' format +- option: target + description: Set the target build stage to build. - option: ulimit default_value: '[]' description: Ulimit options diff --git a/_data/engine-cli/docker_image_history.yaml b/_data/engine-cli/docker_image_history.yaml index f8e8c91d026..4e8969f884d 100644 --- a/_data/engine-cli/docker_image_history.yaml +++ b/_data/engine-cli/docker_image_history.yaml @@ -5,6 +5,8 @@ usage: docker image history [OPTIONS] IMAGE pname: docker image plink: docker_image.yaml options: +- option: format + description: Pretty-print images using a Go template - option: human shorthand: H default_value: "true" diff --git a/_data/engine-cli/docker_image_import.yaml b/_data/engine-cli/docker_image_import.yaml index 1aa59203a7e..592be058b4b 100644 --- a/_data/engine-cli/docker_image_import.yaml +++ b/_data/engine-cli/docker_image_import.yaml @@ -7,7 +7,6 @@ plink: docker_image.yaml options: - option: change shorthand: c - default_value: '[]' description: Apply Dockerfile instruction to the created image - option: message shorthand: m diff --git a/_data/engine-cli/docker_image_prune.yaml b/_data/engine-cli/docker_image_prune.yaml index 90025de2eb5..7bbe2393130 100644 --- a/_data/engine-cli/docker_image_prune.yaml +++ b/_data/engine-cli/docker_image_prune.yaml @@ -10,6 +10,8 @@ options: shorthand: a default_value: "false" description: Remove all unused images, not just dangling ones +- option: filter + description: Provide filter values (e.g. 'until=') - option: force shorthand: f default_value: "false" @@ -50,3 +52,97 @@ examples: |2- Total reclaimed space: 16.43 MB ``` + ### Filtering + + The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more + than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) + + The currently supported filters are: + + * until (``) - only remove images created before given timestamp + * label (`label=`, `label==`, `label!=`, or `label!==`) - only remove images with (or without, in case `label!=...` is used) the specified labels. + + The `until` filter can be Unix timestamps, date formatted + timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed + relative to the daemon machine’s time. Supported formats for date + formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, + `2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local + timezone on the daemon will be used if you do not provide either a `Z` or a + `+-00:00` timezone offset at the end of the timestamp. When providing Unix + timestamps enter seconds[.nanoseconds], where seconds is the number of seconds + that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap + seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a + fraction of a second no more than nine digits long. + + The `label` filter accepts two formats. One is the `label=...` (`label=` or `label==`), + which removes images with the specified labels. The other + format is the `label!=...` (`label!=` or `label!==`), which removes + images without the specified labels. + + The following removes images created before `2017-01-04T00:00:00`: + + ```bash + $ docker images --format 'table {{.Repository}}\t{{.Tag}}\t{{.ID}}\t{{.CreatedAt}}\t{{.Size}}' + REPOSITORY TAG IMAGE ID CREATED AT SIZE + foo latest 2f287ac753da 2017-01-04 13:42:23 -0800 PST 3.98 MB + alpine latest 88e169ea8f46 2016-12-27 10:17:25 -0800 PST 3.98 MB + busybox latest e02e811dd08f 2016-10-07 14:03:58 -0700 PDT 1.09 MB + + $ docker image prune -a --force --filter "until=2017-01-04T00:00:00" + + Deleted Images: + untagged: alpine:latest + untagged: alpine@sha256:dfbd4a3a8ebca874ebd2474f044a0b33600d4523d03b0df76e5c5986cb02d7e8 + untagged: busybox:latest + untagged: busybox@sha256:29f5d56d12684887bdfa50dcd29fc31eea4aaf4ad3bec43daf19026a7ce69912 + deleted: sha256:e02e811dd08fd49e7f6032625495118e63f597eb150403d02e3238af1df240ba + deleted: sha256:e88b3f82283bc59d5e0df427c824e9f95557e661fcb0ea15fb0fb6f97760f9d9 + + Total reclaimed space: 1.093 MB + + $ docker images --format 'table {{.Repository}}\t{{.Tag}}\t{{.ID}}\t{{.CreatedAt}}\t{{.Size}}' + + REPOSITORY TAG IMAGE ID CREATED AT SIZE + foo latest 2f287ac753da 2017-01-04 13:42:23 -0800 PST 3.98 MB + ``` + + The following removes images created more than 10 days (`240h`) ago: + + ```bash + $ docker images + + REPOSITORY TAG IMAGE ID CREATED SIZE + foo latest 2f287ac753da 14 seconds ago 3.98 MB + alpine latest 88e169ea8f46 8 days ago 3.98 MB + debian jessie 7b0a06c805e8 2 months ago 123 MB + busybox latest e02e811dd08f 2 months ago 1.09 MB + golang 1.7.0 138c2e655421 4 months ago 670 MB + + $ docker image prune -a --force --filter "until=240h" + + Deleted Images: + untagged: golang:1.7.0 + untagged: golang@sha256:6765038c2b8f407fd6e3ecea043b44580c229ccfa2a13f6d85866cf2b4a9628e + deleted: sha256:138c2e6554219de65614d88c15521bfb2da674cbb0bf840de161f89ff4264b96 + deleted: sha256:ec353c2e1a673f456c4b78906d0d77f9d9456cfb5229b78c6a960bfb7496b76a + deleted: sha256:fe22765feaf3907526b4921c73ea6643ff9e334497c9b7e177972cf22f68ee93 + deleted: sha256:ff845959c80148421a5c3ae11cc0e6c115f950c89bc949646be55ed18d6a2912 + deleted: sha256:a4320831346648c03db64149eafc83092e2b34ab50ca6e8c13112388f25899a7 + deleted: sha256:4c76020202ee1d9709e703b7c6de367b325139e74eebd6b55b30a63c196abaf3 + deleted: sha256:d7afd92fb07236c8a2045715a86b7d5f0066cef025018cd3ca9a45498c51d1d6 + deleted: sha256:9e63c5bce4585dd7038d830a1f1f4e44cb1a1515b00e620ac718e934b484c938 + untagged: debian:jessie + untagged: debian@sha256:c1af755d300d0c65bb1194d24bce561d70c98a54fb5ce5b1693beb4f7988272f + deleted: sha256:7b0a06c805e8f23807fb8856621c60851727e85c7bcb751012c813f122734c8d + deleted: sha256:f96222d75c5563900bc4dd852179b720a0885de8f7a0619ba0ac76e92542bbc8 + + Total reclaimed space: 792.6 MB + + $ docker images + + REPOSITORY TAG IMAGE ID CREATED SIZE + foo latest 2f287ac753da About a minute ago 3.98 MB + alpine latest 88e169ea8f46 8 days ago 3.98 MB + busybox latest e02e811dd08f 2 months ago 1.09 MB + ``` + diff --git a/_data/engine-cli/docker_image_push.yaml b/_data/engine-cli/docker_image_push.yaml index 2a516d53924..970b82a0643 100644 --- a/_data/engine-cli/docker_image_push.yaml +++ b/_data/engine-cli/docker_image_push.yaml @@ -7,5 +7,5 @@ plink: docker_image.yaml options: - option: disable-content-trust default_value: "true" - description: Skip image verification + description: Skip image signing diff --git a/_data/engine-cli/docker_images.yaml b/_data/engine-cli/docker_images.yaml index d0c638c6d20..a3e1f6f308d 100644 --- a/_data/engine-cli/docker_images.yaml +++ b/_data/engine-cli/docker_images.yaml @@ -252,22 +252,23 @@ examples: |- the specified pattern. ```bash - $ docker images + $ docker images - REPOSITORY TAG IMAGE ID CREATED SIZE - busybox latest e02e811dd08f 5 weeks ago 1.09 MB - busybox uclibc e02e811dd08f 5 weeks ago 1.09 MB - busybox musl 733eb3059dce 5 weeks ago 1.21 MB - busybox glibc 21c16b6787c6 5 weeks ago 4.19 MB + REPOSITORY TAG IMAGE ID CREATED SIZE + busybox latest e02e811dd08f 5 weeks ago 1.09 MB + busybox uclibc e02e811dd08f 5 weeks ago 1.09 MB + busybox musl 733eb3059dce 5 weeks ago 1.21 MB + busybox glibc 21c16b6787c6 5 weeks ago 4.19 MB ``` Filtering with `reference` would give: ```bash - $ docker images --filter=reference='busy*:*libc' - REPOSITORY TAG IMAGE ID CREATED SIZE - busybox uclibc e02e811dd08f 5 weeks ago 1.09 MB - busybox glibc 21c16b6787c6 5 weeks ago 4.19 MB + $ docker images --filter=reference='busy*:*libc' + + REPOSITORY TAG IMAGE ID CREATED SIZE + busybox uclibc e02e811dd08f 5 weeks ago 1.09 MB + busybox glibc 21c16b6787c6 5 weeks ago 4.19 MB ``` ### Format the output diff --git a/_data/engine-cli/docker_import.yaml b/_data/engine-cli/docker_import.yaml index ab24c0268ff..b4c53995f6b 100644 --- a/_data/engine-cli/docker_import.yaml +++ b/_data/engine-cli/docker_import.yaml @@ -19,7 +19,6 @@ plink: docker.yaml options: - option: change shorthand: c - default_value: '[]' description: Apply Dockerfile instruction to the created image - option: message shorthand: m diff --git a/_data/engine-cli/docker_info.yaml b/_data/engine-cli/docker_info.yaml index 0b4579c1344..aed92af0089 100644 --- a/_data/engine-cli/docker_info.yaml +++ b/_data/engine-cli/docker_info.yaml @@ -124,6 +124,7 @@ examples: |- Heartbeat Period: 5 seconds CA Configuration: Expiry Duration: 3 months + Root Rotation In Progress: false Node Address: 172.16.66.128 172.16.66.129 Manager Addresses: 172.16.66.128:2477 diff --git a/_data/engine-cli/docker_inspect.yaml b/_data/engine-cli/docker_inspect.yaml index 3c7619cbc07..aab32391596 100644 --- a/_data/engine-cli/docker_inspect.yaml +++ b/_data/engine-cli/docker_inspect.yaml @@ -1,12 +1,9 @@ command: docker inspect short: Return low-level information on Docker objects long: |- - By default, `docker inspect` will render all results in a JSON array. If the container and - image have the same name, this will return container JSON for unspecified type. - If a format is specified, the given template will be executed for each result. + ker inspect provides detailed information on constructs controlled by Docker. - Go's [text/template](http://golang.org/pkg/text/template/) package - describes all the details of the format. + By default, `docker inspect` will render results in a JSON array. usage: docker inspect [OPTIONS] NAME|ID [NAME|ID...] pname: docker plink: docker.yaml diff --git a/_data/engine-cli/docker_login.yaml b/_data/engine-cli/docker_login.yaml index f920c632ecd..9479e179fd4 100644 --- a/_data/engine-cli/docker_login.yaml +++ b/_data/engine-cli/docker_login.yaml @@ -20,7 +20,9 @@ long: "Login to a registry.\n\n### Login to a self-hosted registry\n\nIf you wan Apple macOS keychain: https://github.com/docker/docker-credential-helpers/releases\n- Microsoft Windows Credential Manager: https://github.com/docker/docker-credential-helpers/releases\n\nYou need to specify the credentials store in `$HOME/.docker/config.json`\nto tell the - docker engine to use it:\n\n```json\n{\n\t\"credsStore\": \"osxkeychain\"\n}\n```\n\nIf + docker engine to use it. The value of the config property should be\nthe suffix + of the program to use (i.e. everything after `docker-credential-`).\nFor example, + to use `docker-credential-osxkeychain`:\n\n```json\n{\n\t\"credsStore\": \"osxkeychain\"\n}\n```\n\nIf you are currently logged in, run `docker logout` to remove\nthe credentials from the file and run `docker login` again.\n\n### Credential helper protocol\n\nCredential helpers can be any program or script that follows a very simple protocol.\nThis diff --git a/_data/engine-cli/docker_logs.yaml b/_data/engine-cli/docker_logs.yaml index a5f18a4c8f4..72bea5f2818 100644 --- a/_data/engine-cli/docker_logs.yaml +++ b/_data/engine-cli/docker_logs.yaml @@ -48,7 +48,8 @@ options: default_value: "false" description: Follow log output - option: since - description: Show logs since timestamp + description: | + Show logs since timestamp (e.g. 2013-01-02T13:23:37) or relative (e.g. 42m for 42 minutes) - option: tail default_value: all description: Number of lines to show from the end of the logs diff --git a/_data/engine-cli/docker_network.yaml b/_data/engine-cli/docker_network.yaml index ce3dfb358b8..d5d9d7991d0 100644 --- a/_data/engine-cli/docker_network.yaml +++ b/_data/engine-cli/docker_network.yaml @@ -1,8 +1,8 @@ command: docker network short: Manage networks long: |- - Manage networks. You can use subcommand to create, list, inspect, remove, - connect and disconnect networks. + Manage networks. You can use subcommands to create, inspect, list, remove, + prune, connect, and disconnect networks. usage: docker network pname: docker plink: docker.yaml diff --git a/_data/engine-cli/docker_network_connect.yaml b/_data/engine-cli/docker_network_connect.yaml index 7a969df771e..3f1556cc43a 100644 --- a/_data/engine-cli/docker_network_connect.yaml +++ b/_data/engine-cli/docker_network_connect.yaml @@ -12,11 +12,10 @@ options: default_value: '[]' description: Add network-scoped alias for the container - option: ip - description: IP Address + description: IPv4 address (e.g., 172.30.100.104) - option: ip6 - description: IPv6 Address + description: IPv6 address (e.g., 2001:db8::33) - option: link - default_value: '[]' description: Add link to another container - option: link-local-ip default_value: '[]' diff --git a/_data/engine-cli/docker_network_create.yaml b/_data/engine-cli/docker_network_create.yaml index 3b564549053..d97c0292a1b 100644 --- a/_data/engine-cli/docker_network_create.yaml +++ b/_data/engine-cli/docker_network_create.yaml @@ -58,6 +58,11 @@ options: - option: aux-address default_value: map[] description: Auxiliary IPv4 or IPv6 addresses used by Network driver +- option: config-from + description: The network from which copying the configuration +- option: config-only + default_value: "false" + description: Create a configuration only network - option: driver shorthand: d default_value: bridge @@ -65,6 +70,9 @@ options: - option: gateway default_value: '[]' description: IPv4 or IPv6 Gateway for the master subnet +- option: ingress + default_value: "false" + description: Create swarm routing-mesh network - option: internal default_value: "false" description: Restrict external access to the network @@ -81,12 +89,13 @@ options: default_value: "false" description: Enable IPv6 networking - option: label - default_value: '[]' description: Set metadata on a network - option: opt shorthand: o default_value: map[] description: Set driver specific options +- option: scope + description: Control the network's scope - option: subnet default_value: '[]' description: Subnet in CIDR format that represents a network segment @@ -196,3 +205,20 @@ examples: |- to create an externally isolated `overlay` network, you can specify the `--internal` option. + ### Network ingress mode + + You can create the network which will be used to provide the routing-mesh in the + swarm cluster. You do so by specifying `--ingress` when creating the network. Only + one ingress network can be created at the time. The network can be removed only + if no services depend on it. Any option available when creating a overlay network + is also available when creating the ingress network, besides the `--attachable` option. + + ```bash + $ docker network create -d overlay \ + --subnet=10.11.0.0/16 \ + --ingress \ + --opt com.docker.network.mtu=9216 \ + --opt encrypted=true \ + my-ingress-network + ``` + diff --git a/_data/engine-cli/docker_network_inspect.yaml b/_data/engine-cli/docker_network_inspect.yaml index d2578511d00..f9ff99a9f8e 100644 --- a/_data/engine-cli/docker_network_inspect.yaml +++ b/_data/engine-cli/docker_network_inspect.yaml @@ -10,4 +10,8 @@ options: - option: format shorthand: f description: Format the output using the given Go template +- option: verbose + shorthand: v + default_value: "false" + description: Verbose output for diagnostics diff --git a/_data/engine-cli/docker_network_ls.yaml b/_data/engine-cli/docker_network_ls.yaml index f7ba824ad36..33f8f629a21 100644 --- a/_data/engine-cli/docker_network_ls.yaml +++ b/_data/engine-cli/docker_network_ls.yaml @@ -38,11 +38,11 @@ examples: "### List all networks\n\n```bash\n$ sudo docker network ls\nNETWORK I filter flags are combined as an `OR` filter. For example,\n`-f type=custom -f type=builtin` returns both `custom` and `builtin` networks.\n\nThe currently supported filters are:\n\n* driver\n* id (network's id)\n* label (`label=` or `label==`)\n* - name (network's name)\n* type (`custom|builtin`)\n\n#### Driver\n\nThe `driver` - filter matches networks based on their driver.\n\nThe following example matches - networks with the `bridge` driver:\n\n```bash\n$ docker network ls --filter driver=bridge\nNETWORK - ID NAME DRIVER SCOPE\ndb9db329f835 test1 - \ bridge local\nf6e212da9dfd test2 bridge + name (network's name)\n* scope (`swarm|global|local`)\n* type (`custom|builtin`)\n\n#### + Driver\n\nThe `driver` filter matches networks based on their driver.\n\nThe following + example matches networks with the `bridge` driver:\n\n```bash\n$ docker network + ls --filter driver=bridge\nNETWORK ID NAME DRIVER SCOPE\ndb9db329f835 + \ test1 bridge local\nf6e212da9dfd test2 bridge \ local\n```\n\n#### ID\n\nThe `id` filter matches on all or part of a network's ID.\n\nThe following filter matches all networks with an ID containing the\n`63d1ff1f77b0...` string.\n\n```bash\n$ docker network ls --filter id=63d1ff1f77b07ca51070a8c227e962238358bd310bde1529cf62e6c307ade161\nNETWORK @@ -67,7 +67,17 @@ examples: "### List all networks\n\n```bash\n$ sudo docker network ls\nNETWORK I \ local\n```\n\nYou can also filter for a substring in a name as this shows:\n\n```bash\n$ docker network ls --filter name=foo\nNETWORK ID NAME DRIVER \ SCOPE\n95e74588f40d foo bridge local\n06e7eef0a170 - \ foobar bridge local\n```\n\n#### Type\n\nThe `type` filter + \ foobar bridge local\n```\n\n#### Scope\n\nThe `scope` + filter matches networks based on their scope.\n\nThe following example matches networks + with the `swarm` scope:\n\n```bash\n$ docker network ls --filter scope=swarm\nNETWORK + ID NAME DRIVER SCOPE\nxbtm0v4f1lfh ingress + \ overlay swarm\nic6r88twuu92 swarmnet overlay + \ swarm\n```\n\nThe following example matches networks with the `local` + scope:\n\n```bash\n$ docker network ls --filter scope=local\nNETWORK ID NAME + \ DRIVER SCOPE\ne85227439ac7 bridge bridge + \ local\n0ca0e19443ed host host local\nca13cc149a36 + \ localnet bridge local\nf9e115d2de35 none + \ null local\n```\n\n#### Type\n\nThe `type` filter supports two values; `builtin` displays predefined networks\n(`bridge`, `none`, `host`), whereas `custom` displays user defined networks.\n\nThe following filter matches all user defined networks:\n\n```bash\n$ docker network ls --filter type=custom\nNETWORK @@ -78,16 +88,16 @@ examples: "### List all networks\n\n```bash\n$ sudo docker network ls\nNETWORK I type=custom -q`\n```\n\nA warning will be issued when trying to remove a network that has containers\nattached.\n\n### Formatting\n\nThe formatting options (`--format`) pretty-prints networks output\nusing a Go template.\n\nValid placeholders for the - Go template are listed below:\n\nPlaceholder | Description\n------------|------------------------------------------------------------------------------------------\n`.ID` - \ | Network ID\n`.Name` | Network name\n`.Driver` | Network driver\n`.Scope` - \ | Network scope (local, global)\n`.IPv6` | Whether IPv6 is enabled on the - network or not.\n`.Internal` | Whether the network is internal or not.\n`.Labels` - \ | All labels assigned to the network.\n`.Label` | Value of a specific label - for this network. For example `{{.Label \"project.version\"}}`\n\nWhen using the - `--format` option, the `network ls` command will either\noutput the data exactly - as the template declares or, when using the\n`table` directive, includes column - headers as well.\n\nThe following example uses a template without headers and outputs - the\n`ID` and `Driver` entries separated by a colon for all networks:\n\n```bash\n$ - docker network ls --format \"{{.ID}}: {{.Driver}}\"\nafaaab448eb2: bridge\nd1584f8dc718: - host\n391df270dc66: null\n```" + Go template are listed below:\n\nPlaceholder | Description\n-------------|------------------------------------------------------------------------------------------\n`.ID` + \ | Network ID\n`.Name` | Network name\n`.Driver` | Network driver\n`.Scope` + \ | Network scope (local, global)\n`.IPv6` | Whether IPv6 is enabled on + the network or not.\n`.Internal` | Whether the network is internal or not.\n`.Labels` + \ | All labels assigned to the network.\n`.Label` | Value of a specific label + for this network. For example `{{.Label \"project.version\"}}`\n`.CreatedAt` | Time + when the network was created\n\nWhen using the `--format` option, the `network ls` + command will either\noutput the data exactly as the template declares or, when using + the\n`table` directive, includes column headers as well.\n\nThe following example + uses a template without headers and outputs the\n`ID` and `Driver` entries separated + by a colon for all networks:\n\n```bash\n$ docker network ls --format \"{{.ID}}: + {{.Driver}}\"\nafaaab448eb2: bridge\nd1584f8dc718: host\n391df270dc66: null\n```" diff --git a/_data/engine-cli/docker_network_prune.yaml b/_data/engine-cli/docker_network_prune.yaml index dce3f0e93cb..9eb5589d0d2 100644 --- a/_data/engine-cli/docker_network_prune.yaml +++ b/_data/engine-cli/docker_network_prune.yaml @@ -7,6 +7,8 @@ usage: docker network prune [OPTIONS] pname: docker network plink: docker_network.yaml options: +- option: filter + description: Provide filter values (e.g. 'until=') - option: force shorthand: f default_value: "false" @@ -22,3 +24,57 @@ examples: |- n2 ``` + ### Filtering + + The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more + than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) + + The currently supported filters are: + + * until (``) - only remove networks created before given timestamp + * label (`label=`, `label==`, `label!=`, or `label!==`) - only remove networks with (or without, in case `label!=...` is used) the specified labels. + + The `until` filter can be Unix timestamps, date formatted + timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed + relative to the daemon machine’s time. Supported formats for date + formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, + `2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local + timezone on the daemon will be used if you do not provide either a `Z` or a + `+-00:00` timezone offset at the end of the timestamp. When providing Unix + timestamps enter seconds[.nanoseconds], where seconds is the number of seconds + that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap + seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a + fraction of a second no more than nine digits long. + + The `label` filter accepts two formats. One is the `label=...` (`label=` or `label==`), + which removes networks with the specified labels. The other + format is the `label!=...` (`label!=` or `label!==`), which removes + networks without the specified labels. + + The following removes networks created more than 5 minutes ago. Note that + system networks such as `bridge`, `host`, and `none` will never be pruned: + + ```none + $ docker network ls + + NETWORK ID NAME DRIVER SCOPE + 7430df902d7a bridge bridge local + ea92373fd499 foo-1-day-ago bridge local + ab53663ed3c7 foo-1-min-ago bridge local + 97b91972bc3b host host local + f949d337b1f5 none null local + + $ docker network prune --force --filter until=5m + + Deleted Networks: + foo-1-day-ago + + $ docker network ls + + NETWORK ID NAME DRIVER SCOPE + 7430df902d7a bridge bridge local + ab53663ed3c7 foo-1-min-ago bridge local + 97b91972bc3b host host local + f949d337b1f5 none null local + ``` + diff --git a/_data/engine-cli/docker_node_inspect.yaml b/_data/engine-cli/docker_node_inspect.yaml index a50c30a3cf2..934f396c518 100644 --- a/_data/engine-cli/docker_node_inspect.yaml +++ b/_data/engine-cli/docker_node_inspect.yaml @@ -15,106 +15,41 @@ options: description: Format the output using the given Go template - option: pretty default_value: "false" - description: Print the information in a human friendly format. -examples: |- - ### Inspect a node - - ```none - $ docker node inspect swarm-manager - - [ - { - "ID": "e216jshn25ckzbvmwlnh5jr3g", - "Version": { - "Index": 10 - }, - "CreatedAt": "2016-06-16T22:52:44.9910662Z", - "UpdatedAt": "2016-06-16T22:52:45.230878043Z", - "Spec": { - "Role": "manager", - "Availability": "active" - }, - "Description": { - "Hostname": "swarm-manager", - "Platform": { - "Architecture": "x86_64", - "OS": "linux" - }, - "Resources": { - "NanoCPUs": 1000000000, - "MemoryBytes": 1039843328 - }, - "Engine": { - "EngineVersion": "1.12.0", - "Plugins": [ - { - "Type": "Volume", - "Name": "local" - }, - { - "Type": "Network", - "Name": "overlay" - }, - { - "Type": "Network", - "Name": "null" - }, - { - "Type": "Network", - "Name": "host" - }, - { - "Type": "Network", - "Name": "bridge" - }, - { - "Type": "Network", - "Name": "overlay" - } - ] - } - }, - "Status": { - "State": "ready", - "Addr": "168.0.32.137" - }, - "ManagerStatus": { - "Leader": true, - "Reachability": "reachable", - "Addr": "168.0.32.137:2377" - } - } - ] - ``` - - ### Specify an output format - - ```none - $ docker node inspect --format '{{ .ManagerStatus.Leader }}' self - - false - - $ docker node inspect --pretty self - ID: e216jshn25ckzbvmwlnh5jr3g - Hostname: swarm-manager - Joined at: 2016-06-16 22:52:44.9910662 +0000 utc - Status: - State: Ready - Availability: Active - Address: 172.17.0.2 - Manager Status: - Address: 172.17.0.2:2377 - Raft Status: Reachable - Leader: Yes - Platform: - Operating System: linux - Architecture: x86_64 - Resources: - CPUs: 4 - Memory: 7.704 GiB - Plugins: - Network: overlay, bridge, null, host, overlay - Volume: local - Engine Version: 1.12.0 - ``` + description: Print the information in a human friendly format +examples: "### Inspect a node\n\n```none\n$ docker node inspect swarm-manager\n\n[\n{\n + \ \"ID\": \"e216jshn25ckzbvmwlnh5jr3g\",\n \"Version\": {\n \"Index\": + 10\n },\n \"CreatedAt\": \"2017-05-16T22:52:44.9910662Z\",\n \"UpdatedAt\": + \"2017-05-16T22:52:45.230878043Z\",\n \"Spec\": {\n \"Role\": \"manager\",\n + \ \"Availability\": \"active\"\n },\n \"Description\": {\n \"Hostname\": + \"swarm-manager\",\n \"Platform\": {\n \"Architecture\": \"x86_64\",\n + \ \"OS\": \"linux\"\n },\n \"Resources\": {\n \"NanoCPUs\": + 1000000000,\n \"MemoryBytes\": 1039843328\n },\n \"Engine\": + {\n \"EngineVersion\": \"17.06.0-ce\",\n \"Plugins\": [\n + \ {\n \"Type\": \"Volume\",\n \"Name\": + \"local\"\n },\n {\n \"Type\": + \"Network\",\n \"Name\": \"overlay\"\n },\n {\n + \ \"Type\": \"Network\",\n \"Name\": \"null\"\n + \ },\n {\n \"Type\": \"Network\",\n + \ \"Name\": \"host\"\n },\n {\n + \ \"Type\": \"Network\",\n \"Name\": \"bridge\"\n + \ },\n {\n \"Type\": \"Network\",\n + \ \"Name\": \"overlay\"\n }\n ]\n },\n + \ \"TLSInfo\": {\n \"TrustRoot\": \"-----BEGIN CERTIFICATE-----\\nMIIBazCCARCgAwIBAgIUOzgqU4tA2q5Yv1HnkzhSIwGyIBswCgYIKoZIzj0EAwIw\\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNTAyMDAyNDAwWhcNMzcwNDI3MDAy\\nNDAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\\nA0IABMbiAmET+HZyve35ujrnL2kOLBEQhFDZ5MhxAuYs96n796sFlfxTxC1lM/2g\\nAh8DI34pm3JmHgZxeBPKUURJHKWjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\\nAf8EBTADAQH/MB0GA1UdDgQWBBS3sjTJOcXdkls6WSY2rTx1KIJueTAKBggqhkjO\\nPQQDAgNJADBGAiEAoeVWkaXgSUAucQmZ3Yhmx22N/cq1EPBgYHOBZmHt0NkCIQC3\\nzONcJ/+WA21OXtb+vcijpUOXtNjyHfcox0N8wsLDqQ==\\n-----END + CERTIFICATE-----\\n\",\n \"CertIssuerSubject\": \"MBMxETAPBgNVBAMTCHN3YXJtLWNh\",\n + \ \"CertIssuerPublicKey\": \"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAExuICYRP4dnK97fm6OucvaQ4sERCEUNnkyHEC5iz3qfv3qwWV/FPELWUz/aACHwMjfimbcmYeBnF4E8pRREkcpQ==\"\n + \ }\n },\n \"Status\": {\n \"State\": \"ready\",\n \"Addr\": + \"168.0.32.137\"\n },\n \"ManagerStatus\": {\n \"Leader\": true,\n + \ \"Reachability\": \"reachable\",\n \"Addr\": \"168.0.32.137:2377\"\n + \ }\n}\n]\n```\n\n### Specify an output format\n\n```none\n$ docker node inspect + --format '{{ .ManagerStatus.Leader }}' self\n\nfalse\n\n$ docker node inspect --pretty + self\nID: e216jshn25ckzbvmwlnh5jr3g\nHostname: swarm-manager\nJoined + at: 2017-05-16 22:52:44.9910662 +0000 utc\nStatus:\n State: Ready\n + Availability: Active\n Address: 172.17.0.2\nManager Status:\n + Address: 172.17.0.2:2377\n Raft Status: Reachable\n Leader: + \ Yes\nPlatform:\n Operating System: linux\n Architecture: x86_64\nResources:\n + CPUs: 4\n Memory: 7.704 GiB\nPlugins:\n Network: + \ overlay, bridge, null, host, overlay\n Volume: local\nEngine + Version: 17.06.0-ce\nTLS Info:\n TrustRoot:\n-----BEGIN CERTIFICATE-----\nMIIBazCCARCgAwIBAgIUOzgqU4tA2q5Yv1HnkzhSIwGyIBswCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNTAyMDAyNDAwWhcNMzcwNDI3MDAy\nNDAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABMbiAmET+HZyve35ujrnL2kOLBEQhFDZ5MhxAuYs96n796sFlfxTxC1lM/2g\nAh8DI34pm3JmHgZxeBPKUURJHKWjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBS3sjTJOcXdkls6WSY2rTx1KIJueTAKBggqhkjO\nPQQDAgNJADBGAiEAoeVWkaXgSUAucQmZ3Yhmx22N/cq1EPBgYHOBZmHt0NkCIQC3\nzONcJ/+WA21OXtb+vcijpUOXtNjyHfcox0N8wsLDqQ==\n-----END + CERTIFICATE-----\n\n Issuer Public Key:\tMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAExuICYRP4dnK97fm6OucvaQ4sERCEUNnkyHEC5iz3qfv3qwWV/FPELWUz/aACHwMjfimbcmYeBnF4E8pRREkcpQ==\n + Issuer Subject:\tMBMxETAPBgNVBAMTCHN3YXJtLWNh\n```" diff --git a/_data/engine-cli/docker_node_ls.yaml b/_data/engine-cli/docker_node_ls.yaml index 374bfe9cf32..b360cd198c6 100644 --- a/_data/engine-cli/docker_node_ls.yaml +++ b/_data/engine-cli/docker_node_ls.yaml @@ -12,95 +12,58 @@ options: - option: filter shorthand: f description: Filter output based on conditions provided +- option: format + description: Pretty-print nodes using a Go template - option: quiet shorthand: q default_value: "false" description: Only display IDs -examples: |- - ```bash - $ docker node ls - - ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS - 1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active - 38ciaotwjuritcdtn9npbnkuz swarm-worker1 Ready Active - e216jshn25ckzbvmwlnh5jr3g * swarm-manager1 Ready Active Leader - ``` - - ### Filtering - - The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more - than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) - - The currently supported filters are: - - * [id](node_ls.md#id) - * [label](node_ls.md#label) - * [membership](node_ls.md#membership) - * [name](node_ls.md#name) - * [role](node_ls.md#role) - - #### id - - The `id` filter matches all or part of a node's id. - - ```bash - $ docker node ls -f id=1 - - ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS - 1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active - ``` - - #### label - - The `label` filter matches nodes based on engine labels and on the presence of a `label` alone or a `label` and a value. Node labels are currently not used for filtering. - - The following filter matches nodes with the `foo` label regardless of its value. - - ```bash - $ docker node ls -f "label=foo" - - ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS - 1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active - ``` - - #### membersip - - The `membership` filter matches nodes based on the presence of a `membership` and a value - `accepted` or `pending`. - - The following filter matches nodes with the `membership` of `accepted`. - - ```bash - $ docker node ls -f "membership=accepted" - - ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS - 1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active - 38ciaotwjuritcdtn9npbnkuz swarm-worker1 Ready Active - ``` - - #### name - - The `name` filter matches on all or part of a node hostname. - - The following filter matches the nodes with a name equal to `swarm-master` string. - - ```bash - $ docker node ls -f name=swarm-manager1 - - ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS - e216jshn25ckzbvmwlnh5jr3g * swarm-manager1 Ready Active Leader - ``` - - #### role - - The `role` filter matches nodes based on the presence of a `role` and a value `worker` or `manager`. - - The following filter matches nodes with the `manager` role. - - ```bash - $ docker node ls -f "role=manager" - - ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS - e216jshn25ckzbvmwlnh5jr3g * swarm-manager1 Ready Active Leader - ``` +examples: "```bash\n$ docker node ls\n\nID HOSTNAME STATUS + \ AVAILABILITY MANAGER STATUS\n1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready + \ Active\n38ciaotwjuritcdtn9npbnkuz swarm-worker1 Ready Active\ne216jshn25ckzbvmwlnh5jr3g + * swarm-manager1 Ready Active Leader\n```\n> **Note**:\n> In the above + example output, there is a hidden column of `.Self` that indicates if the\n> node + is the same node as the current docker daemon. A `*` (e.g., `e216jshn25ckzbvmwlnh5jr3g + *`)\n> means this node is the current docker daemon.\n\n\n### Filtering\n\nThe filtering + flag (`-f` or `--filter`) format is of \"key=value\". If there is more\nthan one + filter, then pass multiple flags (e.g., `--filter \"foo=bar\" --filter \"bif=baz\"`)\n\nThe + currently supported filters are:\n\n* [id](node_ls.md#id)\n* [label](node_ls.md#label)\n* + [membership](node_ls.md#membership)\n* [name](node_ls.md#name)\n* [role](node_ls.md#role)\n\n#### + id\n\nThe `id` filter matches all or part of a node's id.\n\n```bash\n$ docker node + ls -f id=1\n\nID HOSTNAME STATUS AVAILABILITY MANAGER + STATUS\n1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready Active\n```\n\n#### label\n\nThe + `label` filter matches nodes based on engine labels and on the presence of a `label` + alone or a `label` and a value. Node labels are currently not used for filtering.\n\nThe + following filter matches nodes with the `foo` label regardless of its value.\n\n```bash\n$ + docker node ls -f \"label=foo\"\n\nID HOSTNAME STATUS + \ AVAILABILITY MANAGER STATUS\n1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready + \ Active\n```\n\n#### membersip\n\nThe `membership` filter matches nodes based + on the presence of a `membership` and a value\n`accepted` or `pending`.\n\nThe following + filter matches nodes with the `membership` of `accepted`.\n\n```bash\n$ docker node + ls -f \"membership=accepted\"\n\nID HOSTNAME STATUS + \ AVAILABILITY MANAGER STATUS\n1bcef6utixb0l0ca7gxuivsj0 swarm-worker2 Ready + \ Active\n38ciaotwjuritcdtn9npbnkuz swarm-worker1 Ready Active\n```\n\n#### + name\n\nThe `name` filter matches on all or part of a node hostname.\n\nThe following + filter matches the nodes with a name equal to `swarm-master` string.\n\n```bash\n$ + docker node ls -f name=swarm-manager1\n\nID HOSTNAME STATUS + \ AVAILABILITY MANAGER STATUS\ne216jshn25ckzbvmwlnh5jr3g * swarm-manager1 Ready + \ Active Leader\n```\n\n#### role\n\nThe `role` filter matches nodes based + on the presence of a `role` and a value `worker` or `manager`.\n\nThe following + filter matches nodes with the `manager` role.\n\n```bash\n$ docker node ls -f \"role=manager\"\n\nID + \ HOSTNAME STATUS AVAILABILITY MANAGER STATUS\ne216jshn25ckzbvmwlnh5jr3g + * swarm-manager1 Ready Active Leader\n```\n\n### Formatting\n\nThe formatting + options (`--format`) pretty-prints nodes output\nusing a Go template.\n\nValid placeholders + for the Go template are listed below:\n\nPlaceholder | Description\n-----------------|------------------------------------------------------------------------------------------\n`.ID` + \ | Node ID\n`.Self` | Node of the daemon (`true/false`, `true`indicates + that the node is the same as current docker daemon)\n`.Hostname` | Node hostname\n`.Status` + \ | Node status\n`.Availability` | Node availability (\"active\", \"pause\", + or \"drain\")\n`.ManagerStatus` | Manager status of the node\n`.TLSStatus` | + TLS status of the node (\"Ready\", or \"Needs Rotation\" has TLS certificate signed + by an old CA)\n\nWhen using the `--format` option, the `node ls` command will either\noutput + the data exactly as the template declares or, when using the\n`table` directive, + includes column headers as well.\n\nThe following example uses a template without + headers and outputs the\n`ID`, `Hostname`, and `TLS Status` entries separated by + a colon for all nodes:\n\n```bash\n$ docker node ls --format \"{{.ID}}: {{.Hostname}} + {{.TLSStatus}}\"\ne216jshn25ckzbvmwlnh5jr3g: swarm-manager1 Ready\n35o6tiywb700jesrt3dmllaza: + swarm-worker1 Needs Rotation \n``" diff --git a/_data/engine-cli/docker_node_ps.yaml b/_data/engine-cli/docker_node_ps.yaml index 1af5c175e8d..f77939ad323 100644 --- a/_data/engine-cli/docker_node_ps.yaml +++ b/_data/engine-cli/docker_node_ps.yaml @@ -10,12 +10,18 @@ options: - option: filter shorthand: f description: Filter output based on conditions provided +- option: format + description: Pretty-print tasks using a Go template - option: no-resolve default_value: "false" description: Do not map IDs to Names - option: no-trunc default_value: "false" description: Do not truncate output +- option: quiet + shorthand: q + default_value: "false" + description: Only display task IDs examples: |- ```bash $ docker node ps swarm-manager1 @@ -85,5 +91,37 @@ examples: |- #### 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 + + The formatting options (`--format`) pretty-prints tasks output + using a Go template. + + Valid placeholders for the Go template are listed below: + + Placeholder | Description + ----------------|------------------------------------------------------------------------------------------ + `.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 `node 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 node ps --format "{{.Name}}: {{.Image}}" + top.1: busybox + top.2: busybox + top.3: busybox + ``` diff --git a/_data/engine-cli/docker_node_update.yaml b/_data/engine-cli/docker_node_update.yaml index 51846769557..520e1573f5a 100644 --- a/_data/engine-cli/docker_node_update.yaml +++ b/_data/engine-cli/docker_node_update.yaml @@ -6,15 +6,13 @@ pname: docker node plink: docker_node.yaml options: - option: availability - description: Availability of the node (active/pause/drain) + description: Availability of the node ("active"|"pause"|"drain") - option: label-add - default_value: '[]' description: Add or update a node label (key=value) - option: label-rm - default_value: '[]' description: Remove a node label if exists - option: role - description: Role of the node (worker/manager) + description: Role of the node ("worker"|"manager") examples: |- ### Add label metadata to a node diff --git a/_data/engine-cli/docker_plugin_create.yaml b/_data/engine-cli/docker_plugin_create.yaml index 148ebc60a29..7cb959e5cb3 100644 --- a/_data/engine-cli/docker_plugin_create.yaml +++ b/_data/engine-cli/docker_plugin_create.yaml @@ -17,6 +17,7 @@ examples: |- ```bash $ ls -ls /home/pluginDir + total 4 4 -rw-r--r-- 1 root root 431 Nov 7 01:40 config.json 0 drwxr-xr-x 19 root root 420 Nov 7 01:40 rootfs diff --git a/_data/engine-cli/docker_plugin_disable.yaml b/_data/engine-cli/docker_plugin_disable.yaml index 7fe61ff019b..456a33217e8 100644 --- a/_data/engine-cli/docker_plugin_disable.yaml +++ b/_data/engine-cli/docker_plugin_disable.yaml @@ -3,7 +3,7 @@ short: Disable a plugin long: |- ables a plugin. The plugin must be installed before it can be disabled, see [`docker plugin install`](plugin_install.md). Without the `-f` option, - a plugin that has references (eg, volumes, networks) cannot be disabled. + a plugin that has references (e.g., volumes, networks) cannot be disabled. usage: docker plugin disable [OPTIONS] PLUGIN pname: docker plugin plink: docker_plugin.yaml diff --git a/_data/engine-cli/docker_plugin_ls.yaml b/_data/engine-cli/docker_plugin_ls.yaml index 92802d72961..1748ad20a5b 100644 --- a/_data/engine-cli/docker_plugin_ls.yaml +++ b/_data/engine-cli/docker_plugin_ls.yaml @@ -4,13 +4,24 @@ short: List plugins long: |- Lists all the plugins that are currently installed. You can install plugins using the [`docker plugin install`](plugin_install.md) command. + You can also filter using the `-f` or `--filter` flag. + Refer to the [filtering](#filtering) section for more information about available filter options. usage: docker plugin ls [OPTIONS] pname: docker plugin plink: docker_plugin.yaml options: +- option: filter + shorthand: f + description: Provide filter values (e.g. 'enabled=true') +- option: format + description: Pretty-print plugins using a Go template - option: no-trunc default_value: "false" description: Don't truncate output +- option: quiet + shorthand: q + default_value: "false" + description: Only display plugin IDs examples: |- ```bash $ docker plugin ls @@ -19,3 +30,61 @@ examples: |- 69553ca1d123 tiborvass/sample-volume-plugin latest A test plugin for Docker true ``` + ### Filtering + + The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more + than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) + + The currently supported filters are: + + * enabled (boolean - true or false, 0 or 1) + * capability (string - currently `volumedriver`, `networkdriver`, `ipamdriver`, `logdriver`, `metricscollector`, or `authz`) + + #### enabled + + The `enabled` filter matches on plugins enabled or disabled. + + #### capability + + The `capability` filter matches on plugin capabilities. One plugin + might have multiple capabilities. Currently `volumedriver`, `networkdriver`, + `ipamdriver`, `logdriver`, `metricscollector`, and `authz` are supported capabilities. + + ```bash + $ docker plugin install --disable tiborvass/no-remove + + tiborvass/no-remove + + $ docker plugin ls --filter enabled=true + + NAME TAG DESCRIPTION ENABLED + ``` + + ### Formatting + + The formatting options (`--format`) pretty-prints plugins output + using a Go template. + + Valid placeholders for the Go template are listed below: + + Placeholder | Description + ---------------|------------------------------------------------------------------------------------------ + `.ID` | Plugin ID + `.Name` | Plugin name + `.Description` | Plugin description + `.Enabled` | Whether plugin is enabled or not + `.PluginReference` | The reference used to push/pull from a registry + + When using the `--format` option, the `plugin ls` 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 + `ID` and `Name` entries separated by a colon for all plugins: + + ```bash + $ docker plugin ls --format "{{.ID}}: {{.Name}}" + + 4be01827a72e: tiborvass/no-remove + ``` + diff --git a/_data/engine-cli/docker_plugin_push.yaml b/_data/engine-cli/docker_plugin_push.yaml index 0e5285d974c..d0d1b6912ae 100644 --- a/_data/engine-cli/docker_plugin_push.yaml +++ b/_data/engine-cli/docker_plugin_push.yaml @@ -12,7 +12,7 @@ plink: docker_plugin.yaml options: - option: disable-content-trust default_value: "true" - description: Skip image verification + description: Skip image signing examples: |- The following example shows how to push a sample `user/plugin`. @@ -21,6 +21,7 @@ examples: |- ID NAME TAG DESCRIPTION ENABLED 69553ca1d456 user/plugin latest A sample plugin for Docker false + $ docker plugin push user/plugin ``` diff --git a/_data/engine-cli/docker_plugin_rm.yaml b/_data/engine-cli/docker_plugin_rm.yaml index 82e275db820..4df92179d1a 100644 --- a/_data/engine-cli/docker_plugin_rm.yaml +++ b/_data/engine-cli/docker_plugin_rm.yaml @@ -20,9 +20,11 @@ examples: |- ```bash $ docker plugin disable tiborvass/sample-volume-plugin + tiborvass/sample-volume-plugin $ docker plugin rm tiborvass/sample-volume-plugin:latest + tiborvass/sample-volume-plugin ``` diff --git a/_data/engine-cli/docker_plugin_set.yaml b/_data/engine-cli/docker_plugin_set.yaml index 471bd36beb1..cc40f414f31 100644 --- a/_data/engine-cli/docker_plugin_set.yaml +++ b/_data/engine-cli/docker_plugin_set.yaml @@ -19,7 +19,6 @@ examples: |- ```bash $ docker plugin inspect -f {{.Settings.Env}} tiborvass/sample-volume-plugin - [DEBUG=0] $ docker plugin set tiborvass/sample-volume-plugin DEBUG=1 @@ -53,11 +52,13 @@ examples: |- ```bash $ docker plugin inspect -f '{{with $device := index .Settings.Devices 0}}{{$device.Path}}{{end}}' myplugin + /dev/foo $ docker plugins set myplugin mydevice.path=/dev/bar $ docker plugin inspect -f '{{with $device := index .Settings.Devices 0}}{{$device.Path}}{{end}}' myplugin + /dev/bar ``` @@ -66,15 +67,17 @@ examples: |- ### Change the source of the arguments - The following example change the source of the args on the `myplugin` plugin. + The following example change the value of the args on the `myplugin` plugin. ```bash $ docker plugin inspect -f '{{.Settings.Args}}' myplugin + ["foo", "bar"] - $ docker plugins set myplugin args="foo bar baz" + $ docker plugins set myplugin myargs="foo bar baz" $ docker plugin inspect -f '{{.Settings.Args}}' myplugin + ["foo", "bar", "baz"] ``` diff --git a/_data/engine-cli/docker_plugin_upgrade.yaml b/_data/engine-cli/docker_plugin_upgrade.yaml index 567c3673df2..b254e9b9c4c 100644 --- a/_data/engine-cli/docker_plugin_upgrade.yaml +++ b/_data/engine-cli/docker_plugin_upgrade.yaml @@ -34,28 +34,40 @@ examples: |- vieux/sshfs:next $ docker volume create -d vieux/sshfs:next -o sshcmd=root@1.2.3.4:/tmp/shared -o password=XXX sshvolume + sshvolume + $ docker run -it -v sshvolume:/data alpine sh -c "touch /data/hello" + $ docker plugin disable -f vieux/sshfs:next + viex/sshfs:next # Here docker volume ls doesn't show 'sshfsvolume', since the plugin is disabled $ docker volume ls + DRIVER VOLUME NAME $ docker plugin upgrade vieux/sshfs:next vieux/sshfs:next + Plugin "vieux/sshfs:next" is requesting the following privileges: - network: [host] - device: [/dev/fuse] - capabilities: [CAP_SYS_ADMIN] Do you grant the above permissions? [y/N] y Upgrade plugin vieux/sshfs:next to vieux/sshfs:next + $ docker plugin enable vieux/sshfs:next + viex/sshfs:next + $ docker volume ls + DRIVER VOLUME NAME viuex/sshfs:next sshvolume + $ docker run -it -v sshvolume:/data alpine sh -c "ls /data" + hello ``` diff --git a/_data/engine-cli/docker_ps.yaml b/_data/engine-cli/docker_ps.yaml index 65883cd004b..3309c5d97d9 100644 --- a/_data/engine-cli/docker_ps.yaml +++ b/_data/engine-cli/docker_ps.yaml @@ -66,18 +66,20 @@ examples: |- The currently supported filters are: - * id (`container's id`) + * id (container's id) * label (`label=` or `label==`) - * name (`container's name`) - * exited (`int` - the code of exited containers. Only useful with `--all`) + * name (container's name) + * exited (int - the code of exited containers. Only useful with `--all`) * status (`created|restarting|running|removing|paused|exited|dead`) * ancestor (`[:]`, `` or ``) - filters containers that were created from the given image or a descendant. - * before (`container's id or name`) - filters containers created before given id or name - * since (`container's id or name`) - filters containers created since given id or name + * before (container's id or name) - filters containers created before given id or name + * since (container's id or name) - filters containers created since given id or name * isolation (`default|process|hyperv`) (Windows daemon only) - * volume (`volume name or mount point`) - filters containers that mount volumes. - * network (`network id or name`) - filters containers connected to the provided network - * health (`starting|healthy|unhealthy|none`) - filters containers based on healthcheck status + * volume (volume name or mount point) - filters containers that mount volumes. + * network (network id or name) - filters containers connected to the provided network + * health (starting|healthy|unhealthy|none) - filters containers based on healthcheck status + * publish=(container's published port) - filters published ports by containers + * expose=(container's exposed port) - filters exposed ports by containers #### label @@ -324,6 +326,44 @@ examples: |- 9d4893ed80fe ubuntu "top" 10 minutes ago Up 10 minutes test1 ``` + #### publish and expose + + The `publish` and `expose` filters show only containers that have published or exposed port with a given port + number, port range, and/or protocol. The default protocol is `tcp` when not specified. + + The following filter matches all containers that have published port of 80: + + ```bash + $ docker run -d --publish=80 busybox top + $ docker run -d --expose=8080 busybox top + + $ docker ps -a + + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 9833437217a5 busybox "top" 5 seconds ago Up 4 seconds 8080/tcp dreamy_mccarthy + fc7e477723b7 busybox "top" 50 seconds ago Up 50 seconds 0.0.0.0:32768->80/tcp admiring_roentgen + + $ docker ps --filter publish=80 + + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + fc7e477723b7 busybox "top" About a minute ago Up About a minute 0.0.0.0:32768->80/tcp admiring_roentgen + ``` + + The following filter matches all containers that have exposed TCP port in the range of `8000-8080`: + ```bash + $ docker ps --filter expose=8000-8080/tcp + + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 9833437217a5 busybox "top" 21 seconds ago Up 19 seconds 8080/tcp dreamy_mccarthy + ``` + + The following filter matches all containers that have exposed UDP port `80`: + ```bash + $ docker ps --filter publish=80/udp + + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + ``` + ### Formatting The formatting option (`--format`) pretty-prints container output using a Go diff --git a/_data/engine-cli/docker_push.yaml b/_data/engine-cli/docker_push.yaml index ddbb5131256..de132ef0355 100644 --- a/_data/engine-cli/docker_push.yaml +++ b/_data/engine-cli/docker_push.yaml @@ -18,7 +18,7 @@ plink: docker.yaml options: - option: disable-content-trust default_value: "true" - description: Skip image verification + description: Skip image signing examples: |- ### Push a new image to a registry diff --git a/_data/engine-cli/docker_run.yaml b/_data/engine-cli/docker_run.yaml index 317bfbb7535..1bd40a6d195 100644 --- a/_data/engine-cli/docker_run.yaml +++ b/_data/engine-cli/docker_run.yaml @@ -17,11 +17,9 @@ pname: docker plink: docker.yaml options: - option: add-host - default_value: '[]' description: Add a custom host-to-IP mapping (host:ip) - option: attach shorthand: a - default_value: '[]' description: Attach to STDIN, STDOUT or STDERR - option: blkio-weight default_value: "0" @@ -31,10 +29,8 @@ options: default_value: '[]' description: Block IO weight (relative device weight) - option: cap-add - default_value: '[]' description: Add Linux capabilities - option: cap-drop - default_value: '[]' description: Drop Linux capabilities - option: cgroup-parent description: Optional parent cgroup for the container @@ -63,14 +59,11 @@ options: default_value: "0" description: CPU shares (relative weight) - option: cpus - default_value: "0.000" description: Number of CPUs - option: cpuset-cpus description: CPUs in which to allow execution (0-3, 0,1) - option: cpuset-mems description: MEMs in which to allow execution (0-3, 0,1) -- option: credentialspec - description: Credential spec for managed service account (Windows only) - option: detach shorthand: d default_value: "false" @@ -78,8 +71,9 @@ options: - option: detach-keys description: Override the key sequence for detaching a container - option: device - default_value: '[]' description: Add a host device to the container +- option: device-cgroup-rule + description: Add a rule to the cgroup allowed devices list - option: device-read-bps default_value: '[]' description: Limit read rate (bytes per second) from a device @@ -96,44 +90,40 @@ options: default_value: "true" description: Skip image verification - option: dns - default_value: '[]' description: Set custom DNS servers - option: dns-opt - default_value: '[]' description: Set DNS options - option: dns-option - default_value: '[]' description: Set DNS options - option: dns-search - default_value: '[]' description: Set custom DNS search domains - option: entrypoint description: Overwrite the default ENTRYPOINT of the image - option: env shorthand: e - default_value: '[]' description: Set environment variables - option: env-file - default_value: '[]' description: Read in a file of environment variables - option: expose - default_value: '[]' description: Expose a port or a range of ports - option: group-add - default_value: '[]' description: Add additional groups to join - option: health-cmd description: Command to run to check health - option: health-interval default_value: 0s - description: Time between running the check (ns|us|ms|s|m|h) (default 0s) + description: Time between running the check (ms|s|m|h) (default 0s) - option: health-retries default_value: "0" description: Consecutive failures needed to report unhealthy +- option: health-start-period + default_value: 0s + description: | + Start period for the container to initialize before starting health-retries countdown (ms|s|m|h) (default 0s) - option: health-timeout default_value: 0s description: | - Maximum time to allow one check to run (ns|us|ms|s|m|h) (default 0s) + Maximum time to allow one check to run (ms|s|m|h) (default 0s) - option: help default_value: "false" description: Print usage @@ -144,72 +134,70 @@ options: default_value: "false" description: | Run an init inside the container that forwards signals and reaps processes -- option: init-path - description: Path to the docker-init binary - option: interactive shorthand: i default_value: "false" description: Keep STDIN open even if not attached - option: io-maxbandwidth + default_value: "0" description: | Maximum IO bandwidth limit for the system drive (Windows only) - option: io-maxiops default_value: "0" description: Maximum IOps limit for the system drive (Windows only) - option: ip - description: Container IPv4 address (e.g. 172.30.100.104) + description: IPv4 address (e.g., 172.30.100.104) - option: ip6 - description: Container IPv6 address (e.g. 2001:db8::33) + description: IPv6 address (e.g., 2001:db8::33) - option: ipc description: IPC namespace to use - option: isolation description: Container isolation technology - option: kernel-memory + default_value: "0" description: Kernel memory limit - option: label shorthand: l - default_value: '[]' description: Set meta data on a container - option: label-file - default_value: '[]' description: Read in a line delimited file of labels - option: link - default_value: '[]' description: Add link to another container - option: link-local-ip - default_value: '[]' description: Container IPv4/IPv6 link-local addresses - option: log-driver description: Logging driver for the container - option: log-opt - default_value: '[]' description: Log driver options - option: mac-address - description: Container MAC address (e.g. 92:d0:c6:0a:29:33) + description: Container MAC address (e.g., 92:d0:c6:0a:29:33) - option: memory shorthand: m + default_value: "0" description: Memory limit - option: memory-reservation + default_value: "0" description: Memory soft limit - option: memory-swap + default_value: "0" description: | Swap limit equal to memory plus swap: '-1' to enable unlimited swap - option: memory-swappiness default_value: "-1" description: Tune container memory swappiness (0 to 100) +- option: mount + description: Attach a filesystem mount to the container - option: name description: Assign a name to the container - option: net default_value: default description: Connect a container to a network - option: net-alias - default_value: '[]' description: Add network-scoped alias for the container - option: network default_value: default description: Connect a container to a network - option: network-alias - default_value: '[]' description: Add network-scoped alias for the container - option: no-healthcheck default_value: "false" @@ -230,7 +218,6 @@ options: description: Give extended privileges to this container - option: publish shorthand: p - default_value: '[]' description: Publish a container's port(s) to the host - option: publish-all shorthand: P @@ -248,27 +235,25 @@ options: - option: runtime description: Runtime to use for this container - option: security-opt - default_value: '[]' description: Security Options - option: shm-size - description: Size of /dev/shm, default value is 64MB + default_value: "0" + description: Size of /dev/shm - option: sig-proxy default_value: "true" description: Proxy received signals to the process - option: stop-signal default_value: SIGTERM - description: Signal to stop a container, SIGTERM by default + description: Signal to stop a container - option: stop-timeout default_value: "0" description: Timeout (in seconds) to stop a container - option: storage-opt - default_value: '[]' description: Storage driver options for the container - option: sysctl default_value: map[] description: Sysctl options - option: tmpfs - default_value: '[]' description: Mount a tmpfs directory - option: tty shorthand: t @@ -286,12 +271,10 @@ options: description: UTS namespace to use - option: volume shorthand: v - default_value: '[]' description: Bind mount a volume - option: volume-driver description: Optional volume driver for the container - option: volumes-from - default_value: '[]' description: Mount volumes from the specified container(s) - option: workdir shorthand: w @@ -451,6 +434,29 @@ examples: |- For in-depth information about volumes, refer to [manage data in containers](https://docs.docker.com/engine/tutorials/dockervolumes/) + + ### Add bind-mounts or volumes using the --mount flag + + The `--mount` flag allows you to mount volumes, host-directories and `tmpfs` + mounts in a container. + + The `--mount` flag supports most options that are supported by the `-v` or the + `--volume` flag, but uses a different syntax. For in-depth information on the + `--mount` flag, and a comparison between `--volume` and `--mount`, refer to + the [service create command reference](service_create.md#add-bind-mounts-or-volumes). + + Even though there is no plan to deprecate `--volume`, usage of `--mount` is recommended. + + Examples: + + ```bash + $ docker run --read-only --mount type=volume,target=/icanwrite busybox touch /icanwrite/here + ``` + + ```bash + $ docker run -t -i --mount type=bind,src=/data,dst=/data busybox sh + ``` + ### Publish or expose port (-p, --expose) ```bash @@ -475,75 +481,49 @@ examples: |- $ docker run -e MYVAR1 --env MYVAR2=foo --env-file ./env.list ubuntu bash ``` - This sets simple (non-array) environmental variables in the container. For - illustration all three - flags are shown here. Where `-e`, `--env` take an environment variable and - value, or if no `=` is provided, then that variable's current value, set via - `export`, is passed through (i.e. `$MYVAR1` from the host is set to `$MYVAR1` - in the container). When no `=` is provided and that variable is not defined - in the client's environment then that variable will be removed from the - container's list of environment variables. All three flags, `-e`, `--env` and - `--env-file` can be repeated. + Use the `-e`, `--env`, and `--env-file` flags to set simple (non-array) + environment variables in the container you're running, or overwrite variables + that are defined in the Dockerfile of the image you're running. + + You can define the variable and its value when running the container: + + ```bash + $ docker run --env VAR1=value1 --env VAR2=value2 ubuntu env | grep VAR + VAR1=value1 + VAR2=value2 + ``` - Regardless of the order of these three flags, the `--env-file` are processed - first, and then `-e`, `--env` flags. This way, the `-e` or `--env` will - override variables as needed. + You can also use variables that you've exported to your local environment: ```bash - $ cat ./env.list - TEST_FOO=BAR - $ docker run --env TEST_FOO="This is a test" --env-file ./env.list busybox env | grep TEST_FOO - TEST_FOO=This is a test + export VAR1=value1 + export VAR2=value2 + + $ docker run --env VAR1 --env VAR2 ubuntu env | grep VAR + VAR1=value1 + VAR2=value2 ``` - The `--env-file` flag takes a filename as an argument and expects each line - to be in the `VAR=VAL` format, mimicking the argument passed to `--env`. Comment - lines need only be prefixed with `#` + When running the command, the Docker CLI client checks the value the variable + has in your local environment and passes it to the container. + If no `=` is provided and that variable is not exported in your local + environment, the variable won't be set in the container. - An example of a file passed with `--env-file` + You can also load the environment variables from a file. This file should use + the syntax `=value` (which sets the variable to the given value) or + `` (which takes the value from the local environment), and `#` for comments. ```bash - $ cat ./env.list - TEST_FOO=BAR + $ cat env.list + # This is a comment + VAR1=value1 + VAR2=value2 + USER - # this is a comment - TEST_APP_DEST_HOST=10.10.0.127 - TEST_APP_DEST_PORT=8888 - _TEST_BAR=FOO - TEST_APP_42=magic - helloWorld=true - 123qwe=bar - org.spring.config=something - - # pass through this variable from the caller - TEST_PASSTHROUGH - $ TEST_PASSTHROUGH=howdy docker run --env-file ./env.list busybox env - PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin - HOSTNAME=5198e0745561 - TEST_FOO=BAR - TEST_APP_DEST_HOST=10.10.0.127 - TEST_APP_DEST_PORT=8888 - _TEST_BAR=FOO - TEST_APP_42=magic - helloWorld=true - TEST_PASSTHROUGH=howdy - HOME=/root - 123qwe=bar - org.spring.config=something - - $ docker run --env-file ./env.list busybox env - PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin - HOSTNAME=5198e0745561 - TEST_FOO=BAR - TEST_APP_DEST_HOST=10.10.0.127 - TEST_APP_DEST_PORT=8888 - _TEST_BAR=FOO - TEST_APP_42=magic - helloWorld=true - TEST_PASSTHROUGH= - HOME=/root - 123qwe=bar - org.spring.config=something + $ docker run --env-file env.list ubuntu env | grep VAR + VAR1=value1 + VAR2=value2 + USER=denis ``` ### Set metadata on container (-l, --label, --label-file) @@ -725,11 +705,11 @@ examples: |- policy controls whether the Docker daemon restarts a container after exit. Docker supports the following restart policies: - | Policy | Result | - |-------------------|-----------------------------------------| - | `no` | Do not automatically restart the container when it exits. This is the default. | - | `failure` | Restart only if the container exits with a non-zero exit status. Optionally, limit the number of restart retries the Docker daemon attempts. | - | `always` | Always restart the container regardless of the exit status. When you specify always, the Docker daemon will try to restart the container indefinitely. The container will also always start on daemon startup, regardless of the current state of the container. | + | Policy | Result | + |:----------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + | `no` | Do not automatically restart the container when it exits. This is the default. | + | `failure` | Restart only if the container exits with a non-zero exit status. Optionally, limit the number of restart retries the Docker daemon attempts. | + | `always` | Always restart the container regardless of the exit status. When you specify always, the Docker daemon will try to restart the container indefinitely. The container will also always start on daemon startup, regardless of the current state of the container. | ```bash $ docker run --restart=always redis @@ -841,38 +821,45 @@ examples: |- ### Specify isolation technology for container (--isolation) This option is useful in situations where you are running Docker containers on - Microsoft Windows. The `--isolation ` option sets a container's isolation - technology. On Linux, the only supported is the `default` option which uses + Windows. The `--isolation ` option sets a container's isolation technology. + On Linux, the only supported is the `default` option which uses Linux namespaces. These two commands are equivalent on Linux: - ``` + ```bash $ docker run -d busybox top $ docker run -d --isolation default busybox top ``` - On Microsoft Windows, can take any of these values: + On Windows, `--isolation` can take one of these values: - | Value | Description | - |-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| - | `default` | Use the value specified by the Docker daemon's `--exec-opt` . If the `daemon` does not specify an isolation technology, Microsoft Windows uses `process` as its default value. | - | `process` | Namespace isolation only. | - | `hyperv` | Hyper-V hypervisor partition-based isolation. | + | Value | Description | + |:----------|:-------------------------------------------------------------------------------------------| + | `default` | Use the value specified by the Docker daemon's `--exec-opt` or system default (see below). | + | `process` | Shared-kernel namespace isolation (not supported on Windows client operating systems). | + | `hyperv` | Hyper-V hypervisor partition-based isolation. | - On Windows, the default isolation for client is `hyperv`, and for server is - `process`. Therefore when running on Windows server without a `daemon` option - set, these two commands are equivalent: - ``` - $ docker run -d --isolation default busybox top - $ docker run -d --isolation process busybox top - ``` + The default isolation on Windows server operating systems is `process`. The default (and only supported) + isolation on Windows client operating systems is `hyperv`. An attempt to start a container on a client + operating system with `--isolation process` will fail. - If you have set the `--exec-opt isolation=hyperv` option on the Docker `daemon`, - if running on Windows server, any of these commands also result in `hyperv` isolation: + On Windows server, assuming the default configuration, these commands are equivalent + and result in `process` isolation: + ```PowerShell + PS C:\> docker run -d microsoft/nanoserver powershell echo process + PS C:\> docker run -d --isolation default microsoft/nanoserver powershell echo process + PS C:\> docker run -d --isolation process microsoft/nanoserver powershell echo process ``` - $ docker run -d --isolation default busybox top - $ docker run -d --isolation hyperv busybox top + + If you have set the `--exec-opt isolation=hyperv` option on the Docker `daemon`, or + are running against a Windows client-based daemon, these commands are equivalent and + result in `hyperv` isolation: + + ```PowerShell + PS C:\> docker run -d microsoft/nanoserver powershell echo hyperv + PS C:\> docker run -d --isolation default microsoft/nanoserver powershell echo hyperv + PS C:\> docker run -d --isolation hyperv microsoft/nanoserver powershell echo hyperv ``` ### Configure namespaced kernel parameters (sysctls) at runtime diff --git a/_data/engine-cli/docker_secret_create.yaml b/_data/engine-cli/docker_secret_create.yaml index 6187463ebd9..e522ad4b10c 100644 --- a/_data/engine-cli/docker_secret_create.yaml +++ b/_data/engine-cli/docker_secret_create.yaml @@ -9,18 +9,19 @@ plink: docker_secret.yaml options: - option: label shorthand: l - default_value: '[]' description: Secret labels examples: |- ### Create a secret ```bash $ echo | docker secret create my_secret - - mhv17xfe3gh6xc4rij5orpfds + + onakdyv307se2tl7nl20anokv $ docker secret ls - ID NAME CREATED UPDATED SIZE - mhv17xfe3gh6xc4rij5orpfds my_secret 2016-10-27 23:25:43.909181089 +0000 UTC 2016-10-27 23:25:43.909181089 +0000 UTC 1679 + + ID NAME CREATED UPDATED + onakdyv307se2tl7nl20anokv my_secret 6 seconds ago 6 seconds ago ``` ### Create a secret with a file @@ -28,22 +29,22 @@ examples: |- ```bash $ docker secret create my_secret ./secret.json - mhv17xfe3gh6xc4rij5orpfds + dg426haahpi5ezmkkj5kyl3sn $ docker secret ls - ID NAME CREATED UPDATED SIZE - mhv17xfe3gh6xc4rij5orpfds my_secret 2016-10-27 23:25:43.909181089 +0000 UTC 2016-10-27 23:25:43.909181089 +0000 UTC 1679 + ID NAME CREATED UPDATED + dg426haahpi5ezmkkj5kyl3sn my_secret 7 seconds ago 7 seconds ago ``` ### Create a secret with labels ```bash $ docker secret create --label env=dev \ - --label rev=20161102 \ + --label rev=20170324 \ my_secret ./secret.json - jtn7g6aukl5ky7nr9gvwafoxh + eo7jnzguqgtpdah3cm5srfb97 ``` ```none @@ -51,22 +52,19 @@ examples: |- [ { - "ID": "jtn7g6aukl5ky7nr9gvwafoxh", + "ID": "eo7jnzguqgtpdah3cm5srfb97", "Version": { - "Index": 541 + "Index": 17 }, - "CreatedAt": "2016-11-03T20:54:12.924766548Z", - "UpdatedAt": "2016-11-03T20:54:12.924766548Z", + "CreatedAt": "2017-03-24T08:15:09.735271783Z", + "UpdatedAt": "2017-03-24T08:15:09.735271783Z", "Spec": { "Name": "my_secret", "Labels": { "env": "dev", - "rev": "20161102" - }, - "Data": null - }, - "Digest": "sha256:4212a44b14e94154359569333d3fc6a80f6b9959dfdaff26412f4b2796b1f387", - "SecretSize": 1679 + "rev": "20170324" + } + } } ] ``` diff --git a/_data/engine-cli/docker_secret_inspect.yaml b/_data/engine-cli/docker_secret_inspect.yaml index c9a1789bdb2..dfa65eeb105 100644 --- a/_data/engine-cli/docker_secret_inspect.yaml +++ b/_data/engine-cli/docker_secret_inspect.yaml @@ -18,6 +18,9 @@ options: - option: format shorthand: f description: Format the output using the given Go template +- option: pretty + default_value: "false" + description: Print the information in a human friendly format examples: |- ### Inspect a secret by name or ID @@ -27,8 +30,9 @@ examples: |- ```bash $ docker secret ls - ID NAME CREATED UPDATED - mhv17xfe3gh6xc4rij5orpfds secret.json 2016-10-27 23:25:43.909181089 +0000 UTC 2016-10-27 23:25:43.909181089 +0000 UTC + + ID NAME CREATED UPDATED + eo7jnzguqgtpdah3cm5srfb97 my_secret 3 minutes ago 3 minutes ago ``` ```none @@ -36,14 +40,18 @@ examples: |- [ { - "ID": "mhv17xfe3gh6xc4rij5orpfds", - "Version": { - "Index": 1198 + "ID": "eo7jnzguqgtpdah3cm5srfb97", + "Version": { + "Index": 17 }, - "CreatedAt": "2016-10-27T23:25:43.909181089Z", - "UpdatedAt": "2016-10-27T23:25:43.909181089Z", + "CreatedAt": "2017-03-24T08:15:09.735271783Z", + "UpdatedAt": "2017-03-24T08:15:09.735271783Z", "Spec": { - "Name": "secret.json" + "Name": "my_secret", + "Labels": { + "env": "dev", + "rev": "20170324" + } } } ] @@ -56,8 +64,8 @@ examples: |- secret. ```bash - $ docker secret inspect --format='{{.CreatedAt}}' mhv17xfe3gh6xc4rij5orpfds + $ docker secret inspect --format='{{.CreatedAt}}' eo7jnzguqgtpdah3cm5srfb97 - 2016-10-27 23:25:43.909181089 +0000 UTC + 2017-03-24 08:15:09.735271783 +0000 UTC ``` diff --git a/_data/engine-cli/docker_secret_ls.yaml b/_data/engine-cli/docker_secret_ls.yaml index ef6fa96a30c..5a9dd499aee 100644 --- a/_data/engine-cli/docker_secret_ls.yaml +++ b/_data/engine-cli/docker_secret_ls.yaml @@ -9,6 +9,11 @@ usage: docker secret ls [OPTIONS] pname: docker secret plink: docker_secret.yaml options: +- option: filter + shorthand: f + description: Filter output based on conditions provided +- option: format + description: Pretty-print secrets using a Go template - option: quiet shorthand: q default_value: "false" @@ -17,7 +22,112 @@ examples: |- ```bash $ docker secret ls - ID NAME CREATED UPDATED - mhv17xfe3gh6xc4rij5orpfds secret.json 2016-10-27 23:25:43.909181089 +0000 UTC 2016-10-27 23:25:43.909181089 +0000 UTC + ID NAME CREATED UPDATED + 6697bflskwj1998km1gnnjr38 q5s5570vtvnimefos1fyeo2u2 6 weeks ago 6 weeks ago + 9u9hk4br2ej0wgngkga6rp4hq my_secret 5 weeks ago 5 weeks ago + mem02h8n73mybpgqjf0kfi1n0 test_secret 3 seconds ago 3 seconds ago + ``` + + ### Filtering + + The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more + than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) + + The currently supported filters are: + + * [id](secret_ls.md#id) (secret's ID) + * [label](secret_ls.md#label) (`label=` or `label==`) + * [name](secret_ls.md#name) (secret's name) + + #### id + + The `id` filter matches all or prefix of a secret's id. + + ```bash + $ docker secret ls -f "id=6697bflskwj1998km1gnnjr38" + + ID NAME CREATED UPDATED + 6697bflskwj1998km1gnnjr38 q5s5570vtvnimefos1fyeo2u2 6 weeks ago 6 weeks ago + ``` + + #### label + + The `label` filter matches secrets based on the presence of a `label` alone or + a `label` and a value. + + The following filter matches all secrets with a `project` label regardless of + its value: + + ```bash + $ docker secret ls --filter label=project + + ID NAME CREATED UPDATED + mem02h8n73mybpgqjf0kfi1n0 test_secret About an hour ago About an hour ago + ``` + + The following filter matches only services with the `project` label with the + `project-a` value. + + ```bash + $ docker service ls --filter label=project=test + + ID NAME CREATED UPDATED + mem02h8n73mybpgqjf0kfi1n0 test_secret About an hour ago About an hour ago + ``` + + #### name + + The `name` filter matches on all or prefix of a secret's name. + + The following filter matches secret with a name containing a prefix of `test`. + + ```bash + $ docker secret ls --filter name=test_secret + + ID NAME CREATED UPDATED + mem02h8n73mybpgqjf0kfi1n0 test_secret About an hour ago About an hour ago + ``` + + ### Format the output + + The formatting option (`--format`) pretty prints secrets output + using a Go template. + + Valid placeholders for the Go template are listed below: + + | Placeholder | Description | + | ------------ | ------------------------------------------------------------------------------------ | + | `.ID` | Secret ID | + | `.Name` | Secret name | + | `.CreatedAt` | Time when the secret was created | + | `.UpdatedAt` | Time when the secret was updated | + | `.Labels` | All labels assigned to the secret | + | `.Label` | Value of a specific label for this secret. For example `{{.Label "secret.ssh.key"}}` | + + When using the `--format` option, the `secret ls` command will either + output the data exactly as the template declares or, when using the + `table` directive, will include column headers as well. + + The following example uses a template without headers and outputs the + `ID` and `Name` entries separated by a colon for all images: + + ```bash + $ docker secret ls --format "{{.ID}}: {{.Name}}" + + 77af4d6b9913: secret-1 + b6fa739cedf5: secret-2 + 78a85c484f71: secret-3 + ``` + + To list all secrets with their name and created date in a table format you + can use: + + ```bash + $ docker secret ls --format "table {{.ID}}\t{{.Name}}\t{{.CreatedAt}}" + + ID NAME CREATED + 77af4d6b9913 secret-1 5 minutes ago + b6fa739cedf5 secret-2 3 hours ago + 78a85c484f71 secret-3 10 days ago ``` diff --git a/_data/engine-cli/docker_service_create.yaml b/_data/engine-cli/docker_service_create.yaml index 575a8f88a5c..aa4f0c0e67d 100644 --- a/_data/engine-cli/docker_service_create.yaml +++ b/_data/engine-cli/docker_service_create.yaml @@ -7,61 +7,64 @@ usage: docker service create [OPTIONS] IMAGE [COMMAND] [ARG...] pname: docker service plink: docker_service.yaml options: +- option: config + description: Specify configurations to expose to the service - option: constraint - default_value: '[]' description: Placement constraints - option: container-label - default_value: '[]' description: Container labels +- option: credential-spec + description: Credential spec for managed service account (Windows only) +- option: detach + shorthand: d + default_value: "true" + description: | + Exit immediately instead of waiting for the service to converge - option: dns - default_value: '[]' description: Set custom DNS servers - option: dns-option - default_value: '[]' description: Set DNS options - option: dns-search - default_value: '[]' description: Set custom DNS search domains - option: endpoint-mode + default_value: vip description: Endpoint mode (vip or dnsrr) +- option: entrypoint + description: Overwrite the default ENTRYPOINT of the image - option: env shorthand: e - default_value: '[]' description: Set environment variables - option: env-file - default_value: '[]' description: Read in a file of environment variables - option: group - default_value: '[]' description: Set one or more supplementary user groups for the container - option: health-cmd description: Command to run to check health - option: health-interval - description: Time between running the check (ns|us|ms|s|m|h) + description: Time between running the check (ms|s|m|h) - option: health-retries default_value: "0" description: Consecutive failures needed to report unhealthy +- option: health-start-period + description: | + Start period for the container to initialize before counting retries towards unstable (ms|s|m|h) - option: health-timeout - description: Maximum time to allow one check to run (ns|us|ms|s|m|h) + description: Maximum time to allow one check to run (ms|s|m|h) - option: host - default_value: '[]' description: Set one or more custom host-to-IP mappings (host:ip) - option: hostname description: Container hostname - option: label shorthand: l - default_value: '[]' description: Service labels - option: limit-cpu - default_value: "0.000" description: Limit CPUs - option: limit-memory - default_value: 0 B + default_value: "0" description: Limit Memory - option: log-driver description: Logging driver for service - option: log-opt - default_value: '[]' description: Logging driver options - option: mode default_value: replicated @@ -71,35 +74,69 @@ options: - option: name description: Service name - option: network - default_value: '[]' description: Network attachments - option: no-healthcheck default_value: "false" description: Disable any container-specified HEALTHCHECK +- option: no-resolve-image + default_value: "false" + description: | + Do not query the registry to resolve image digest and supported platforms +- option: placement-pref + description: Add a placement preference - option: publish shorthand: p description: Publish a port as a node port +- option: quiet + shorthand: q + default_value: "false" + description: Suppress progress output +- option: read-only + default_value: "false" + description: Mount the container's root filesystem as read only - option: replicas description: Number of tasks - option: reserve-cpu - default_value: "0.000" description: Reserve CPUs - option: reserve-memory - default_value: 0 B + default_value: "0" description: Reserve Memory - option: restart-condition - description: Restart when condition is met (none, on-failure, or any) + description: | + Restart when condition is met ("none"|"on-failure"|"any") (default "any") - option: restart-delay - description: Delay between restart attempts (ns|us|ms|s|m|h) + description: Delay between restart attempts (ns|us|ms|s|m|h) (default 5s) - option: restart-max-attempts description: Maximum number of restarts before giving up - option: restart-window description: Window used to evaluate the restart policy (ns|us|ms|s|m|h) +- option: rollback-delay + default_value: 0s + description: Delay between task rollbacks (ns|us|ms|s|m|h) (default 0s) +- option: rollback-failure-action + description: | + Action on rollback failure ("pause"|"continue") (default "pause") +- option: rollback-max-failure-ratio + default_value: "0" + description: Failure rate to tolerate during a rollback (default 0) +- option: rollback-monitor + default_value: 0s + description: | + Duration after each task rollback to monitor for failure (ns|us|ms|s|m|h) (default 5s) +- option: rollback-order + description: | + Rollback order ("start-first"|"stop-first") (default "stop-first") +- option: rollback-parallelism + default_value: "1" + description: | + Maximum number of tasks rolled back simultaneously (0 to roll back all at once) - option: secret description: Specify secrets to expose to the service - option: stop-grace-period description: | - Time to wait before force killing a container (ns|us|ms|s|m|h) + Time to wait before force killing a container (ns|us|ms|s|m|h) (default 10s) +- option: stop-signal + description: Signal to stop the container - option: tty shorthand: t default_value: "false" @@ -108,15 +145,18 @@ options: default_value: 0s description: Delay between updates (ns|us|ms|s|m|h) (default 0s) - option: update-failure-action - default_value: pause - description: Action on update failure (pause|continue) + description: | + Action on update failure ("pause"|"continue"|"rollback") (default "pause") - option: update-max-failure-ratio default_value: "0" - description: Failure rate to tolerate during an update + description: Failure rate to tolerate during an update (default 0) - option: update-monitor default_value: 0s description: | - Duration after each task update to monitor for failure (ns|us|ms|s|m|h) (default 0s) + Duration after each task update to monitor for failure (ns|us|ms|s|m|h) (default 5s) +- option: update-order + description: | + Update order ("start-first"|"stop-first") (default "stop-first") - option: update-parallelism default_value: "1" description: | @@ -366,9 +406,22 @@ examples: |-

+ + consistency + + +

The consistency requirements for the mount; one of +

    +
  • default: Equivalent to consistent.
    • +
  • consistent: Full consistency. The container runtime and the host maintain an identical view of the mount at all times.
    • +
  • cached: The host's view of the mount is authoritative. There may be delays before updates made on the host are visible within a container.
    • +
  • delegated: 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.
    • +
+

+ + - #### Bind Propagation Bind propagation refers to whether or not mounts created within a given @@ -457,7 +510,7 @@ examples: |- Options specific to a given volume driver, which will be passed to the driver when creating the volume. Options are provided as a comma-separated list of key/value pairs, for example, - volume-opt=some-option=some-value,some-other-option=some-other-value. + volume-opt=some-option=some-value,volume-opt=some-other-option=some-other-value. For available options for a given driver, refer to that driver's documentation. @@ -636,6 +689,77 @@ examples: |- redis:3.0.6 ``` + ### Specify service placement preferences (--placement-pref) + + You can set up the service to divide tasks evenly over different categories of + nodes. One example of where this can be useful is to balance tasks over a set + of datacenters or availability zones. The example below illustrates this: + + ```bash + $ docker service create \ + --replicas 9 \ + --name redis_2 \ + --placement-pref 'spread=node.labels.datacenter' \ + redis:3.0.6 + ``` + + This uses `--placement-pref` with a `spread` strategy (currently the only + supported strategy) to spread tasks evenly over the values of the `datacenter` + node label. In this example, we assume that every node has a `datacenter` node + label attached to it. If there are three different values of this label among + nodes in the swarm, one third of the tasks will be placed on the nodes + associated with each value. This is true even if there are more nodes with one + value than another. For example, consider the following set of nodes: + + - Three nodes with `node.labels.datacenter=east` + - Two nodes with `node.labels.datacenter=south` + - One node with `node.labels.datacenter=west` + + Since we are spreading over the values of the `datacenter` label and the + service has 9 replicas, 3 replicas will end up in each datacenter. There are + three nodes associated with the value `east`, so each one will get one of the + three replicas reserved for this value. There are two nodes with the value + `south`, and the three replicas for this value will be divided between them, + with one receiving two replicas and another receiving just one. Finally, `west` + has a single node that will get all three replicas reserved for `west`. + + If the nodes in one category (for example, those with + `node.labels.datacenter=south`) can't handle their fair share of tasks due to + constraints or resource limitations, the extra tasks will be assigned to other + nodes instead, if possible. + + Both engine labels and node labels are supported by placement preferences. The + example above uses a node label, because the label is referenced with + `node.labels.datacenter`. To spread over the values of an engine label, use + `--placement-pref spread=engine.labels.`. + + It is possible to add multiple placement preferences to a service. This + establishes a hierarchy of preferences, so that tasks are first divided over + one category, and then further divided over additional categories. One example + of where this may be useful is dividing tasks fairly between datacenters, and + then splitting the tasks within each datacenter over a choice of racks. To add + multiple placement preferences, specify the `--placement-pref` flag multiple + times. The order is significant, and the placement preferences will be applied + in the order given when making scheduling decisions. + + The following example sets up a service with multiple placement preferences. + Tasks are spread first over the various datacenters, and then over racks + (as indicated by the respective labels): + + ```bash + $ docker service create \ + --replicas 9 \ + --name redis_2 \ + --placement-pref 'spread=node.labels.datacenter' \ + --placement-pref 'spread=node.labels.rack' \ + redis:3.0.6 + ``` + + When updating a service with `docker service update`, `--placement-pref-add` + appends a new placement preference after all existing placement preferences. + `--placement-pref-rm` removes an existing placement preference that matches the + argument. + ### Attach a service to an existing network (--network) You can use overlay networks to connect one or more services within the swarm. diff --git a/_data/engine-cli/docker_service_inspect.yaml b/_data/engine-cli/docker_service_inspect.yaml index fdf62116c2c..a0f715d4e59 100644 --- a/_data/engine-cli/docker_service_inspect.yaml +++ b/_data/engine-cli/docker_service_inspect.yaml @@ -18,7 +18,7 @@ options: description: Format the output using the given Go template - option: pretty default_value: "false" - description: Print the information in a human friendly format. + description: Print the information in a human friendly format examples: "### Inspect a service by name or ID\n\nYou can inspect a service, either by its *name*, or *ID*\n\nFor example, given the following service;\n\n```bash\n$ docker service ls\nID NAME MODE REPLICAS IMAGE\ndmu1ept4cxcf @@ -43,11 +43,11 @@ examples: "### Inspect a service by name or ID\n\nYou can inspect a service, eit of the default\nJSON output, by using the `--pretty` option:\n\n```bash\n$ docker service inspect --pretty frontend\n\nID:\t\tc8wgl7q4ndfd52ni6qftkvnnp\nName:\t\tfrontend\nLabels:\n - org.example.projectname=demo-app\nService Mode:\tREPLICATED\n Replicas:\t\t5\nPlacement:\nUpdateConfig:\n - Parallelism:\t0\nContainerSpec:\n Image:\t\tnginx:alpine\nResources:\nEndpoint Mode: - \ vip\nPorts:\n Name =\n Protocol = tcp\n TargetPort = 443\n PublishedPort = 4443\n```\n\nYou - can also use `--format pretty` for the same effect.\n\n\n#### Find the number of - tasks running as part of a service\n\nThe `--format` option can be used to obtain - specific information about a\nservice. For example, the following command outputs - the number of replicas\nof the \"redis\" service.\n\n```bash\n$ docker service inspect - --format='{{.Spec.Mode.Replicated.Replicas}}' redis\n\n10\n```" + Parallelism:\t0\n On failure:\tpause\n Max failure ratio:\t0\nContainerSpec:\n Image:\t\tnginx:alpine\nResources:\nNetworks:\tnet1\nEndpoint + Mode: vip\nPorts:\n PublishedPort = 4443\n Protocol = tcp\n TargetPort = 443\n + \ PublishMode = ingress\n```\n\nYou can also use `--format pretty` for the same + effect.\n\n\n#### Find the number of tasks running as part of a service\n\nThe `--format` + option can be used to obtain specific information about a\nservice. For example, + the following command outputs the number of replicas\nof the \"redis\" service.\n\n```bash\n$ + docker service inspect --format='{{.Spec.Mode.Replicated.Replicas}}' redis\n\n10\n```" diff --git a/_data/engine-cli/docker_service_logs.yaml b/_data/engine-cli/docker_service_logs.yaml index 7fc03ef1bc1..e9ad985e1ba 100644 --- a/_data/engine-cli/docker_service_logs.yaml +++ b/_data/engine-cli/docker_service_logs.yaml @@ -1,8 +1,13 @@ command: docker service logs -short: Fetch the logs of a service +short: Fetch the logs of a service or task long: |- The `docker service logs` command batch-retrieves logs present at the time of execution. + The `docker service logs` command can be used with either the name or ID of a + service, or with the ID of a task. If a service is passed, it will display logs + for all of the containers in that service. If a task is passed, it will only + display logs from that particular task. + > **Note**: This command is only functional for services that are started with > the `json-file` or `journald` logging driver. @@ -36,7 +41,7 @@ long: |- seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a fraction of a second no more than nine digits long. You can combine the `--since` option with either or both of the `--follow` or `--tail` options. -usage: docker service logs [OPTIONS] SERVICE +usage: docker service logs [OPTIONS] SERVICE|TASK pname: docker service plink: docker_service.yaml options: @@ -49,9 +54,19 @@ options: description: Follow log output - option: no-resolve default_value: "false" - description: Do not map IDs to Names + description: Do not map IDs to Names in output +- option: no-task-ids + default_value: "false" + description: Do not include task IDs in output +- option: no-trunc + default_value: "false" + description: Do not truncate output +- option: raw + default_value: "false" + description: Do not neatly format logs - option: since - description: Show logs since timestamp + description: | + Show logs since timestamp (e.g. 2013-01-02T13:23:37) or relative (e.g. 42m for 42 minutes) - option: tail default_value: all description: Number of lines to show from the end of the logs diff --git a/_data/engine-cli/docker_service_ls.yaml b/_data/engine-cli/docker_service_ls.yaml index cb082b7c191..e24dc6cea59 100644 --- a/_data/engine-cli/docker_service_ls.yaml +++ b/_data/engine-cli/docker_service_ls.yaml @@ -11,6 +11,8 @@ options: - option: filter shorthand: f description: Filter output based on conditions provided +- option: format + description: Pretty-print services using a Go template - option: quiet shorthand: q default_value: "false" @@ -39,6 +41,7 @@ examples: |- * [id](service_ls.md#id) * [label](service_ls.md#label) + * [mode](service_ls.md#mode) * [name](service_ls.md#name) #### id @@ -77,6 +80,18 @@ examples: |- 74nzcxxjv6fq backend replicated 3/3 redis:3.0.6 ``` + #### mode + + The `mode` filter matches on the mode (either `replicated` or `global`) of a service. + + The following filter matches only `global` services. + + ```bash + $ docker service ls --filter mode=global + ID NAME MODE REPLICAS IMAGE + w7y0v2yrn620 top global 1/1 busybox + ``` + #### name The `name` filter matches on all or part of a service's name. @@ -89,3 +104,33 @@ examples: |- 0bcjwfh8ychr redis replicated 1/1 redis:3.0.6 ``` + ### Formatting + + The formatting options (`--format`) pretty-prints services output + using a Go template. + + Valid placeholders for the Go template are listed below: + + Placeholder | Description + ------------|------------------------------------------------------------------------------------------ + `.ID` | Service ID + `.Name` | Service name + `.Mode` | Service mode (replicated, global) + `.Replicas` | Service replicas + `.Image` | Service image + `.Ports` | Service ports published in ingress mode + + When using the `--format` option, the `service ls` 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 + `ID`, `Mode`, and `Replicas` entries separated by a colon for all services: + + ```bash + $ docker service ls --format "{{.ID}}: {{.Mode}} {{.Replicas}}" + + 0zmvwuiu3vue: replicated 10/10 + fm6uf97exkul: global 5/5 + ``` + diff --git a/_data/engine-cli/docker_service_ps.yaml b/_data/engine-cli/docker_service_ps.yaml index eb454032a24..69efa95577d 100644 --- a/_data/engine-cli/docker_service_ps.yaml +++ b/_data/engine-cli/docker_service_ps.yaml @@ -1,15 +1,17 @@ command: docker service ps -short: List the tasks of a service +short: List the tasks of one or more services long: |- Lists the tasks that are running as part of the specified services. This command has to be run targeting a manager node. -usage: docker service ps [OPTIONS] SERVICE +usage: docker service ps [OPTIONS] SERVICE [SERVICE...] pname: docker service plink: docker_service.yaml options: - option: filter shorthand: f description: Filter output based on conditions provided +- option: format + description: Pretty-print tasks using a Go template - option: no-resolve default_value: "false" description: Do not map IDs to Names @@ -131,8 +133,39 @@ examples: |- 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 + + 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 `service 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 service ps --format "{{.Name}}: {{.Image}}" top + top.1: busybox + top.2: busybox + top.3: busybox + ``` diff --git a/_data/engine-cli/docker_service_update.yaml b/_data/engine-cli/docker_service_update.yaml index ee169d9517d..5db5bdbdeee 100644 --- a/_data/engine-cli/docker_service_update.yaml +++ b/_data/engine-cli/docker_service_update.yaml @@ -16,112 +16,125 @@ plink: docker_service.yaml options: - option: args description: Service command args +- option: config-add + description: Add or update a config file on a service +- option: config-rm + description: Remove a configuration file - option: constraint-add - default_value: '[]' description: Add or update a placement constraint - option: constraint-rm - default_value: '[]' description: Remove a constraint - option: container-label-add - default_value: '[]' description: Add or update a container label - option: container-label-rm - default_value: '[]' description: Remove a container label by its key +- option: credential-spec + description: Credential spec for managed service account (Windows only) +- option: detach + shorthand: d + default_value: "true" + description: | + Exit immediately instead of waiting for the service to converge - option: dns-add - default_value: '[]' description: Add or update a custom DNS server - option: dns-option-add - default_value: '[]' description: Add or update a DNS option - option: dns-option-rm - default_value: '[]' description: Remove a DNS option - option: dns-rm - default_value: '[]' description: Remove a custom DNS server - option: dns-search-add - default_value: '[]' description: Add or update a custom DNS search domain - option: dns-search-rm - default_value: '[]' description: Remove a DNS search domain - option: endpoint-mode description: Endpoint mode (vip or dnsrr) +- option: entrypoint + description: Overwrite the default ENTRYPOINT of the image - option: env-add - default_value: '[]' description: Add or update an environment variable - option: env-rm - default_value: '[]' description: Remove an environment variable - option: force default_value: "false" description: Force update even if no changes require it - option: group-add - default_value: '[]' description: Add an additional supplementary user group to the container - option: group-rm - default_value: '[]' description: | Remove a previously added supplementary user group from the container - option: health-cmd description: Command to run to check health - option: health-interval - description: Time between running the check (ns|us|ms|s|m|h) + description: Time between running the check (ms|s|m|h) - option: health-retries default_value: "0" description: Consecutive failures needed to report unhealthy +- option: health-start-period + description: | + Start period for the container to initialize before counting retries towards unstable (ms|s|m|h) - option: health-timeout - description: Maximum time to allow one check to run (ns|us|ms|s|m|h) + description: Maximum time to allow one check to run (ms|s|m|h) - option: host-add - default_value: '[]' description: Add or update a custom host-to-IP mapping (host:ip) - option: host-rm - default_value: '[]' description: Remove a custom host-to-IP mapping (host:ip) - option: hostname description: Container hostname - option: image description: Service image tag - option: label-add - default_value: '[]' description: Add or update a service label - option: label-rm - default_value: '[]' description: Remove a label by its key - option: limit-cpu - default_value: "0.000" description: Limit CPUs - option: limit-memory - default_value: 0 B + default_value: "0" description: Limit Memory - option: log-driver description: Logging driver for service - option: log-opt - default_value: '[]' description: Logging driver options - option: mount-add description: Add or update a mount on a service - option: mount-rm - default_value: '[]' description: Remove a mount by its target path +- option: network-add + description: Add a network +- option: network-rm + description: Remove a network - option: no-healthcheck default_value: "false" description: Disable any container-specified HEALTHCHECK +- option: no-resolve-image + default_value: "false" + description: | + Do not query the registry to resolve image digest and supported platforms +- option: placement-pref-add + description: Add a placement preference +- option: placement-pref-rm + description: Remove a placement preference - option: publish-add description: Add or update a published port - option: publish-rm description: Remove a published port by its target port +- option: quiet + shorthand: q + default_value: "false" + description: Suppress progress output +- option: read-only + default_value: "false" + description: Mount the container's root filesystem as read only - option: replicas description: Number of tasks - option: reserve-cpu - default_value: "0.000" description: Reserve CPUs - option: reserve-memory - default_value: 0 B + default_value: "0" description: Reserve Memory - option: restart-condition - description: Restart when condition is met (none, on-failure, or any) + description: Restart when condition is met ("none"|"on-failure"|"any") - option: restart-delay description: Delay between restart attempts (ns|us|ms|s|m|h) - option: restart-max-attempts @@ -131,33 +144,53 @@ options: - option: rollback default_value: "false" description: Rollback to previous specification +- option: rollback-delay + default_value: 0s + description: Delay between task rollbacks (ns|us|ms|s|m|h) +- option: rollback-failure-action + description: Action on rollback failure ("pause"|"continue") +- option: rollback-max-failure-ratio + default_value: "0" + description: Failure rate to tolerate during a rollback +- option: rollback-monitor + default_value: 0s + description: | + Duration after each task rollback to monitor for failure (ns|us|ms|s|m|h) +- option: rollback-order + description: Rollback order ("start-first"|"stop-first") +- option: rollback-parallelism + default_value: "0" + description: | + Maximum number of tasks rolled back simultaneously (0 to roll back all at once) - option: secret-add description: Add or update a secret on a service - option: secret-rm - default_value: '[]' description: Remove a secret - option: stop-grace-period description: | Time to wait before force killing a container (ns|us|ms|s|m|h) +- option: stop-signal + description: Signal to stop the container - option: tty shorthand: t default_value: "false" description: Allocate a pseudo-TTY - option: update-delay default_value: 0s - description: Delay between updates (ns|us|ms|s|m|h) (default 0s) + description: Delay between updates (ns|us|ms|s|m|h) - option: update-failure-action - default_value: pause - description: Action on update failure (pause|continue) + description: Action on update failure ("pause"|"continue"|"rollback") - option: update-max-failure-ratio default_value: "0" description: Failure rate to tolerate during an update - option: update-monitor default_value: 0s description: | - Duration after each task update to monitor for failure (ns|us|ms|s|m|h) (default 0s) + Duration after each task update to monitor for failure (ns|us|ms|s|m|h) +- option: update-order + description: Update order ("start-first"|"stop-first") - option: update-parallelism - default_value: "1" + default_value: "0" description: | Maximum number of tasks updated simultaneously (0 to update all at once) - option: user @@ -203,7 +236,18 @@ examples: "### Update a service\n\n```bash\n$ docker service update --limit-cpu \ web replicated 0/4 nginx:alpine\n\n```\n\nOther options can be combined with `--rollback` as well, for example, `--update-delay 0s` to execute the rollback without a delay between tasks:\n\n```bash\n$ docker service update \\\n --rollback - \\\n --update-delay 0s\n web\n\nweb\n\n```\n\n### Add or remove secrets\n\nUse + \\\n --update-delay 0s\n web\n\nweb\n\n```\n\nServices can also be set up to roll + back to the previous version automatically\nwhen an update fails. To set up a service + for automatic rollback, use\n`--update-failure-action=rollback`. A rollback will + be triggered if the fraction\nof the tasks which failed to update successfully exceeds + the value given with\n`--update-max-failure-ratio`.\n\nThe rate, parallelism, and + other parameters of a rollback operation are\ndetermined by the values passed with + the following flags:\n\n- `--rollback-delay`\n- `--rollback-failure-action`\n- `--rollback-max-failure-ratio`\n- + `--rollback-monitor`\n- `--rollback-parallelism`\n\nFor example, a service set up + with `--update-parallelism 1 --rollback-parallelism 3`\nwill update one task at + a time during a normal update, but during a rollback, 3\ntasks at a time will get + rolled back. These rollback parameters are respected both\nduring automatic rollbacks + and for rollbacks initiated manually using `--rollback`.\n\n### Add or remove secrets\n\nUse the `--secret-add` or `--secret-rm` options add or remove a service's\nsecrets.\n\nThe following example adds a secret named `ssh-2` and removes `ssh-1`:\n\n```bash\n$ docker service update \\\n --secret-add source=ssh-2,target=ssh-2 \\\n --secret-rm diff --git a/_data/engine-cli/docker_stack_deploy.yaml b/_data/engine-cli/docker_stack_deploy.yaml index 859f5131a5f..96bb9a00632 100644 --- a/_data/engine-cli/docker_stack_deploy.yaml +++ b/_data/engine-cli/docker_stack_deploy.yaml @@ -13,6 +13,9 @@ options: - option: compose-file shorthand: c description: Path to a Compose file +- option: prune + default_value: "false" + description: Prune services that are no longer referenced - option: with-registry-auth default_value: "false" description: Send registry authentication details to Swarm agents diff --git a/_data/engine-cli/docker_stack_ls.yaml b/_data/engine-cli/docker_stack_ls.yaml index d07d51fbf02..c2c41839a2e 100644 --- a/_data/engine-cli/docker_stack_ls.yaml +++ b/_data/engine-cli/docker_stack_ls.yaml @@ -5,6 +5,9 @@ long: Lists the stacks. usage: docker stack ls pname: docker stack plink: docker_stack.yaml +options: +- option: format + description: Pretty-print stacks using a Go template examples: |- The following command shows all stacks and some additional information: @@ -16,3 +19,27 @@ examples: |- myapp 2 ``` + ### Formatting + + The formatting option (`--format`) pretty-prints stacks using a Go template. + + Valid placeholders for the Go template are listed below: + + | Placeholder | Description | + | ----------- | ------------------ | + | `.Name` | Stack name | + | `.Services` | Number of services | + + When using the `--format` option, the `stack ls` command either outputs + 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 `Services` entries separated by a colon for all stacks: + + ```bash + $ docker stack ls --format "{{.Name}}: {{.Services}}" + web-server: 1 + web-cache: 4 + ``` + diff --git a/_data/engine-cli/docker_stack_ps.yaml b/_data/engine-cli/docker_stack_ps.yaml index 12cdba42309..1cdc7b5c92b 100644 --- a/_data/engine-cli/docker_stack_ps.yaml +++ b/_data/engine-cli/docker_stack_ps.yaml @@ -10,15 +10,34 @@ options: - option: filter shorthand: f description: Filter output based on conditions provided +- option: format + description: Pretty-print tasks using a Go template - option: no-resolve default_value: "false" description: Do not map IDs to Names - option: no-trunc default_value: "false" description: Do not truncate output +- option: quiet + shorthand: q + default_value: "false" + description: Only display task IDs 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 @@ -30,7 +49,163 @@ examples: |- The currently supported filters are: - * id - * name - * desired-stat + * [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": { + (...) + ``` diff --git a/_data/engine-cli/docker_stack_rm.yaml b/_data/engine-cli/docker_stack_rm.yaml index e2aa195e0e5..dcdd30420eb 100644 --- a/_data/engine-cli/docker_stack_rm.yaml +++ b/_data/engine-cli/docker_stack_rm.yaml @@ -1,10 +1,46 @@ command: docker stack rm aliases: remove, down -short: Remove the stack +short: Remove one or more stacks long: |- Remove the stack from the swarm. This command has to be run targeting a manager node. -usage: docker stack rm STACK +usage: docker stack rm STACK [STACK...] pname: docker stack plink: docker_stack.yaml +examples: |- + ### Remove a stack + + This will remove the stack with the name `myapp`. Services, networks, and secrets associated with the stack will be removed. + + ```bash + $ docker stack rm myapp + + Removing service myapp_redis + Removing service myapp_web + Removing service myapp_lb + Removing network myapp_default + Removing network myapp_frontend + ``` + + ### Remove multiple stacks + + This will remove all the specified stacks, `myapp` and `vossibility`. Services, networks, and secrets associated with all the specified stacks will be removed. + + ```bash + $ docker stack rm myapp vossibility + + Removing service myapp_redis + Removing service myapp_web + Removing service myapp_lb + Removing network myapp_default + Removing network myapp_frontend + Removing service vossibility_nsqd + Removing service vossibility_logstash + Removing service vossibility_elasticsearch + Removing service vossibility_kibana + Removing service vossibility_ghollector + Removing service vossibility_lookupd + Removing network vossibility_default + Removing network vossibility_vossibility + ``` diff --git a/_data/engine-cli/docker_stack_services.yaml b/_data/engine-cli/docker_stack_services.yaml index 843fb689d17..bfb96e05332 100644 --- a/_data/engine-cli/docker_stack_services.yaml +++ b/_data/engine-cli/docker_stack_services.yaml @@ -10,6 +10,8 @@ options: - option: filter shorthand: f description: Filter output based on conditions provided +- option: format + description: Pretty-print services using a Go template - option: quiet shorthand: q default_value: "false" @@ -47,3 +49,32 @@ examples: |- * name (`--filter name=myapp_web`) * label (`--filter label=key=value`) + ### Formatting + + The formatting options (`--format`) pretty-prints services output + using a Go template. + + Valid placeholders for the Go template are listed below: + + Placeholder | Description + ------------|------------------------------------------------------------------------------------------ + `.ID` | Service ID + `.Name` | Service name + `.Mode` | Service mode (replicated, global) + `.Replicas` | Service replicas + `.Image` | Service image + + When using the `--format` option, the `stack services` 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 + `ID`, `Mode`, and `Replicas` entries separated by a colon for all services: + + ```bash + $ docker stack services --format "{{.ID}}: {{.Mode}} {{.Replicas}}" + + 0zmvwuiu3vue: replicated 10/10 + fm6uf97exkul: global 5/5 + ``` + diff --git a/_data/engine-cli/docker_stats.yaml b/_data/engine-cli/docker_stats.yaml index 8f2e0bb9abb..23d95475dfe 100644 --- a/_data/engine-cli/docker_stats.yaml +++ b/_data/engine-cli/docker_stats.yaml @@ -37,6 +37,19 @@ examples: |- fervent_panini 0.02% 11.08 MiB/1.045 GiB 1.06% 648 B/648 B ``` + Running `docker stats` with customized format on all (Running and Stopped) containers. + + ```bash + $ docker stats --all --format "table {{.ID}}\t{{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}" + CONTAINER ID NAME CPU % MEM USAGE / LIMIT + c9dfa83f0317f87637d5b7e67aa4223337d947215c5a9947e697e4f7d3e0f834 ecstatic_noether 0.00% 56KiB / 15.57GiB + 8f92d01cf3b29b4f5fca4cd33d907e05def7af5a3684711b20a2369d211ec67f stoic_goodall 0.07% 32.86MiB / 15.57GiB + 38dd23dba00f307d53d040c1d18a91361bbdcccbf592315927d56cf13d8b7343 drunk_visvesvaraya 0.00% 0B / 0B + 5a8b07ec4cc52823f3cbfdb964018623c1ba307bce2c057ccdbde5f4f6990833 big_heisenberg 0.00% 0B / 0B + ``` + + `drunk_visvesvaraya` and `big_heisenberg` are stopped containers in the above example. + Running `docker stats` on all running containers against a Windows daemon. ```powershell diff --git a/_data/engine-cli/docker_swarm.yaml b/_data/engine-cli/docker_swarm.yaml index fc839c0186a..c9c48e986a4 100644 --- a/_data/engine-cli/docker_swarm.yaml +++ b/_data/engine-cli/docker_swarm.yaml @@ -5,6 +5,7 @@ usage: docker swarm pname: docker plink: docker.yaml cname: +- docker swarm ca - docker swarm init - docker swarm join - docker swarm join-token @@ -13,6 +14,7 @@ cname: - docker swarm unlock-key - docker swarm update clink: +- docker_swarm_ca.yaml - docker_swarm_init.yaml - docker_swarm_join.yaml - docker_swarm_join-token.yaml diff --git a/_data/engine-cli/docker_swarm_ca.yaml b/_data/engine-cli/docker_swarm_ca.yaml new file mode 100644 index 00000000000..e3db12c4deb --- /dev/null +++ b/_data/engine-cli/docker_swarm_ca.yaml @@ -0,0 +1,108 @@ +command: docker swarm ca +short: Manage root CA +long: View or rotate the current swarm CA certificate. This command must target a + manager node. +usage: docker swarm ca [OPTIONS] +pname: docker swarm +plink: docker_swarm.yaml +options: +- option: ca-cert + description: | + Path to the PEM-formatted root CA certificate to use for the new cluster +- option: ca-key + description: | + Path to the PEM-formatted root CA key to use for the new cluster +- option: cert-expiry + default_value: 2160h0m0s + description: Validity period for node certificates (ns|us|ms|s|m|h) +- option: detach + shorthand: d + default_value: "false" + description: | + Exit immediately instead of waiting for the root rotation to converge +- option: external-ca + description: Specifications of one or more certificate signing endpoints +- option: quiet + shorthand: q + default_value: "false" + description: Suppress progress output +- option: rotate + default_value: "false" + description: | + Rotate the swarm CA - if no certificate or key are provided, new ones will be generated +examples: |- + Run the `docker swarm ca` command without any options to view the current root CA certificate + in PEM format. + + ```bash + $ docker swarm ca + -----BEGIN CERTIFICATE----- + MIIBazCCARCgAwIBAgIUJPzo67QC7g8Ebg2ansjkZ8CbmaswCgYIKoZIzj0EAwIw + EzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNTAzMTcxMDAwWhcNMzcwNDI4MTcx + MDAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH + A0IABKL6/C0sihYEb935wVPRA8MqzPLn3jzou0OJRXHsCLcVExigrMdgmLCC+Va4 + +sJ+SLVO1eQbvLHH8uuDdF/QOU6jQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB + Af8EBTADAQH/MB0GA1UdDgQWBBSfUy5bjUnBAx/B0GkOBKp91XvxzjAKBggqhkjO + PQQDAgNJADBGAiEAnbvh0puOS5R/qvy1PMHY1iksYKh2acsGLtL/jAIvO4ACIQCi + lIwQqLkJ48SQqCjG1DBTSBsHmMSRT+6mE2My+Z3GKA== + -----END CERTIFICATE----- + ``` + + Pass the `--rotate` flag (and optionally a `--ca-cert`, along with a `--ca-key` or + `--external-ca` parameter flag), in order to rotate the current swarm root CA. + + ``` + $ docker swarm ca --rotate + desired root digest: sha256:05da740cf2577a25224c53019e2cce99bcc5ba09664ad6bb2a9425d9ebd1b53e + rotated TLS certificates: [=========================> ] 1/2 nodes + rotated CA certificates: [> ] 0/2 nodes + ``` + + Once the rotation os finished (all the progress bars have completed) the now-current + CA certificate will be printed: + + ``` + $ docker swarm ca --rotate + desired root digest: sha256:05da740cf2577a25224c53019e2cce99bcc5ba09664ad6bb2a9425d9ebd1b53e + rotated TLS certificates: [==================================================>] 2/2 nodes + rotated CA certificates: [==================================================>] 2/2 nodes + -----BEGIN CERTIFICATE----- + MIIBazCCARCgAwIBAgIUFynG04h5Rrl4lKyA4/E65tYKg8IwCgYIKoZIzj0EAwIw + EzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNTE2MDAxMDAwWhcNMzcwNTExMDAx + MDAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH + A0IABC2DuNrIETP7C7lfiEPk39tWaaU0I2RumUP4fX4+3m+87j0DU0CsemUaaOG6 + +PxHhGu2VXQ4c9pctPHgf7vWeVajQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB + Af8EBTADAQH/MB0GA1UdDgQWBBSEL02z6mCI3SmMDmITMr12qCRY2jAKBggqhkjO + PQQDAgNJADBGAiEA263Eb52+825EeNQZM0AME+aoH1319Zp9/J5ijILW+6ACIQCg + gyg5u9Iliel99l7SuMhNeLkrU7fXs+Of1nTyyM73ig== + -----END CERTIFICATE----- + ``` + + ### `--rotate` + + Root CA Rotation is recommended if one or more of the swarm managers have been + compromised, so that those managers can no longer connect to or be trusted by + any other node in the cluster. + + Alternately, root CA rotation can be used to give control of the swarm CA + to an external CA, or to take control back from an external CA. + + The `--rotate` flag does not require any parameters to do a rotation, but you can + optionally specify a certificate and key, or a certificate and external CA URL, + and those will be used instead of an automatically-generated certificate/key pair. + + Because the root CA key should be kept secret, if provided it will not be visible + when viewing swarm any information via the CLI or API. + + The root CA rotation will not be completed until all registered nodes have + rotated their TLS certificates. If the rotation is not completing within a + reasonable amount of time, try running + `docker node ls --format {{.ID}} {{.Hostname}} {{.Status}} {{.TLSStatus}}` to + see if any nodes are down or otherwise unable to rotate TLS certificates. + + + ### `--detach` + + Initiate the root CA rotation, but do not wait for the completion of or display the + progress of the rotation. + diff --git a/_data/engine-cli/docker_swarm_init.yaml b/_data/engine-cli/docker_swarm_init.yaml index c67eb204b62..1821d6b9d98 100644 --- a/_data/engine-cli/docker_swarm_init.yaml +++ b/_data/engine-cli/docker_swarm_init.yaml @@ -13,9 +13,15 @@ options: default_value: "false" description: | Enable manager autolocking (requiring an unlock key to start a stopped manager) +- option: availability + default_value: active + description: Availability of the node ("active"|"pause"|"drain") - option: cert-expiry default_value: 2160h0m0s description: Validity period for node certificates (ns|us|ms|s|m|h) +- option: data-path-addr + description: | + Address or interface to use for data path traffic (format: ) - option: dispatcher-heartbeat default_value: 5s description: Dispatcher heartbeat period (ns|us|ms|s|m|h) @@ -113,6 +119,15 @@ examples: |- Specifying a port is optional. If the value is a bare IP address or interface name, the default port 2377 will be used. + ### `--data-path-addr` + + This flag specifies the address that global scope network drivers will publish towards + other nodes in order to reach the containers running on this node. + Using this parameter it is then possible to separate the container's data traffic from the + management traffic of the cluster. + If unspecified, Docker will use the same IP address or interface that is used for the + advertise address. + ### `--task-history-limit` This flag sets up task history retention limit. @@ -132,3 +147,12 @@ examples: |- state to new managers. However, there is a performance cost to taking snapshots frequently. + ### `--availability` + + This flag specifies the availability of the node at the time the node joins a master. + Possible availability values are `active`, `pause`, or `drain`. + + This flag is useful in certain situations. For example, a cluster may want to have + dedicated manager nodes that are not served as worker nodes. This could be achieved + by passing `--availability=drain` to `docker swarm init`. + diff --git a/_data/engine-cli/docker_swarm_join.yaml b/_data/engine-cli/docker_swarm_join.yaml index 925eb587f63..47fd58c0166 100644 --- a/_data/engine-cli/docker_swarm_join.yaml +++ b/_data/engine-cli/docker_swarm_join.yaml @@ -10,6 +10,12 @@ plink: docker_swarm.yaml options: - option: advertise-addr description: 'Advertised address (format: [:port])' +- option: availability + default_value: active + description: Availability of the node ("active"|"pause"|"drain") +- option: data-path-addr + description: | + Address or interface to use for data path traffic (format: ) - option: listen-addr default_value: 0.0.0.0:2377 description: 'Listen address (format: [:port])' @@ -75,7 +81,25 @@ examples: |- This flag is generally not necessary when joining an existing swarm. + ### `--data-path-addr` + + This flag specifies the address that global scope network drivers will publish towards + other nodes in order to reach the containers running on this node. + Using this parameter it is then possible to separate the container's data traffic from the + management traffic of the cluster. + If unspecified, Docker will use the same IP address or interface that is used for the + advertise address. + ### `--token string` - Secret value required for nodes to join the swar + Secret value required for nodes to join the swarm + + ### `--availability` + + This flag specifies the availability of the node at the time the node joins a master. + Possible availability values are `active`, `pause`, or `drain`. + + This flag is useful in certain situations. For example, a cluster may want to have + dedicated manager nodes that are not served as worker nodes. This could be achieved + by passing `--availability=drain` to `docker swarm join`. diff --git a/_data/engine-cli/docker_system.yaml b/_data/engine-cli/docker_system.yaml index d3da32d99d8..12a585ecf80 100644 --- a/_data/engine-cli/docker_system.yaml +++ b/_data/engine-cli/docker_system.yaml @@ -1,6 +1,6 @@ command: docker system short: Manage Docker -long: Manage docker. +long: Manage Docker. usage: docker system pname: docker plink: docker.yaml diff --git a/_data/engine-cli/docker_system_df.yaml b/_data/engine-cli/docker_system_df.yaml index 3d2b176d60c..de6bf0ff403 100644 --- a/_data/engine-cli/docker_system_df.yaml +++ b/_data/engine-cli/docker_system_df.yaml @@ -7,6 +7,8 @@ usage: docker system df [OPTIONS] pname: docker system plink: docker_system.yaml options: +- option: format + description: Pretty-print images using a Go template - option: verbose shorthand: v default_value: "false" diff --git a/_data/engine-cli/docker_system_events.yaml b/_data/engine-cli/docker_system_events.yaml index 38325b6162d..0f3e06818b8 100644 --- a/_data/engine-cli/docker_system_events.yaml +++ b/_data/engine-cli/docker_system_events.yaml @@ -1,6 +1,137 @@ command: docker system events short: Get real time events from the server -long: Get real time events from the server +long: |- + Use `docker system events` to get real-time events from the server. These + events differ per Docker object type. + + ### Object types + + #### Containers + + Docker containers report the following events: + + - `attach` + - `commit` + - `copy` + - `create` + - `destroy` + - `detach` + - `die` + - `exec_create` + - `exec_detach` + - `exec_start` + - `export` + - `health_status` + - `kill` + - `oom` + - `pause` + - `rename` + - `resize` + - `restart` + - `start` + - `stop` + - `top` + - `unpause` + - `update` + + #### Images + + Docker images report the following events: + + - `delete` + - `import` + - `load` + - `pull` + - `push` + - `save` + - `tag` + - `untag` + + #### Plugins + + Docker plugins report the following events: + + - `install` + - `enable` + - `disable` + - `remove` + + #### Volumes + + Docker volumes report the following events: + + - `create` + - `mount` + - `unmount` + - `destroy` + + #### Networks + + Docker networks report the following events: + + - `create` + - `connect` + - `disconnect` + - `destroy` + + #### Daemons + + Docker daemons report the following events: + + - `reload` + + ### Limiting, filtering, and formatting the output + + #### Limit events by time + + The `--since` and `--until` parameters can be Unix timestamps, date formatted + timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed + relative to the client machine’s time. If you do not provide the `--since` option, + the command returns only new and/or live events. Supported formats for date + formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, + `2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local + timezone on the client will be used if you do not provide either a `Z` or a + `+-00:00` timezone offset at the end of the timestamp. When providing Unix + timestamps enter seconds[.nanoseconds], where seconds is the number of seconds + that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap + seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a + fraction of a second no more than nine digits long. + + #### Filtering + + The filtering flag (`-f` or `--filter`) format is of "key=value". If you would + like to use multiple filters, pass multiple flags (e.g., + `--filter "foo=bar" --filter "bif=baz"`) + + Using the same filter multiple times will be handled as a *OR*; for example + `--filter container=588a23dac085 --filter container=a8f7720b8c22` will display + events for container 588a23dac085 *OR* container a8f7720b8c22 + + Using multiple filters will be handled as a *AND*; for example + `--filter container=588a23dac085 --filter event=start` will display events for + container container 588a23dac085 *AND* the event type is *start* + + The currently supported filters are: + + * container (`container=`) + * daemon (`daemon=`) + * event (`event=`) + * image (`image=`) + * label (`label=` or `label==`) + * network (`network=`) + * plugin (`plugin=`) + * type (`type=`) + * volume (`volume=`) + + #### Format + + If a format (`--format`) is specified, the given template will be executed + instead of the default + format. Go's [text/template](http://golang.org/pkg/text/template/) package + describes all the details of the format. + + If a format is set to `{{json .}}`, the events are streamed as valid JSON + Lines. For information about JSON Lines, please refer to http://jsonlines.org/ . usage: docker system events [OPTIONS] pname: docker system plink: docker_system.yaml @@ -14,4 +145,184 @@ options: description: Show all events created since timestamp - option: until description: Stream events until this timestamp +examples: |- + ### Basic example + + You'll need two shells for this example. + + **Shell 1: Listening for events:** + + ```bash + $ docker system events + ``` + + **Shell 2: Start and Stop containers:** + + ```bash + $ docker create --name test alpine:latest top + $ docker start test + $ docker stop test + ``` + + **Shell 1: (Again .. now showing events):** + + ```none + 2017-01-05T00:35:58.859401177+08:00 container create 0fdb48addc82871eb34eb23a847cfd033dedd1a0a37bef2e6d9eb3870fc7ff37 (image=alpine:latest, name=test) + 2017-01-05T00:36:04.703631903+08:00 network connect e2e1f5ceda09d4300f3a846f0acfaa9a8bb0d89e775eb744c5acecd60e0529e2 (container=0fdb...ff37, name=bridge, type=bridge) + 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) + 2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) + 2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) + 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) + 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) + ``` + + To exit the `docker system events` command, use `CTRL+C`. + + ### Filter events by time + + You can filter the output by an absolute timestamp or relative time on the host + machine, using the following different time syntaxes: + + ```bash + $ docker system events --since 1483283804 + 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) + 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) + 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) + 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) + 2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) + 2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) + 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) + 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) + + $ docker system events --since '2017-01-05' + 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) + 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) + 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) + 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) + 2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) + 2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) + 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) + 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) + + $ docker system events --since '2013-09-03T15:49:29' + 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) + 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) + 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) + 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) + 2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) + 2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) + 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) + 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) + + $ docker system events --since '10m' + 2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local) + 2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test) + 2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge) + 2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) + 2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) + 2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) + 2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge) + 2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) + ``` + + ### Filter events by criteria + + The following commands show several different ways to filter the `docker event` + output. + + ```bash + $ docker system events --filter 'event=stop' + + 2017-01-05T00:40:22.880175420+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) + 2017-01-05T00:41:17.888104182+08:00 container stop 2a8f...4e78 (image=alpine, name=kickass_brattain) + + $ docker system events --filter 'image=alpine' + + 2017-01-05T00:41:55.784240236+08:00 container create d9cd...4d70 (image=alpine, name=happy_meitner) + 2017-01-05T00:41:55.913156783+08:00 container start d9cd...4d70 (image=alpine, name=happy_meitner) + 2017-01-05T00:42:01.106875249+08:00 container kill d9cd...4d70 (image=alpine, name=happy_meitner, signal=15) + 2017-01-05T00:42:11.111934041+08:00 container kill d9cd...4d70 (image=alpine, name=happy_meitner, signal=9) + 2017-01-05T00:42:11.119578204+08:00 container die d9cd...4d70 (exitCode=137, image=alpine, name=happy_meitner) + 2017-01-05T00:42:11.173276611+08:00 container stop d9cd...4d70 (image=alpine, name=happy_meitner) + + $ docker system events --filter 'container=test' + + 2017-01-05T00:43:00.139719934+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) + 2017-01-05T00:43:09.259951086+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15) + 2017-01-05T00:43:09.270102715+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test) + 2017-01-05T00:43:09.312556440+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test) + + $ docker system events --filter 'container=test' --filter 'container=d9cdb1525ea8' + + 2017-01-05T00:44:11.517071981+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test) + 2017-01-05T00:44:17.685870901+08:00 container start d9cd...4d70 (image=alpine, name=happy_meitner) + 2017-01-05T00:44:29.757658470+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=9) + 2017-01-05T00:44:29.767718510+08:00 container die 0fdb...ff37 (exitCode=137, image=alpine:latest, name=test) + 2017-01-05T00:44:29.815798344+08:00 container destroy 0fdb...ff37 (image=alpine:latest, name=test) + + $ docker system events --filter 'container=test' --filter 'event=stop' + + 2017-01-05T00:46:13.664099505+08:00 container stop a9d1...e130 (image=alpine, name=test) + + $ docker system events --filter 'type=volume' + + 2015-12-23T21:05:28.136212689Z volume create test-event-volume-local (driver=local) + 2015-12-23T21:05:28.383462717Z volume mount test-event-volume-local (read/write=true, container=562f...5025, destination=/foo, driver=local, propagation=rprivate) + 2015-12-23T21:05:28.650314265Z volume unmount test-event-volume-local (container=562f...5025, driver=local) + 2015-12-23T21:05:28.716218405Z volume destroy test-event-volume-local (driver=local) + + $ docker system events --filter 'type=network' + + 2015-12-23T21:38:24.705709133Z network create 8b11...2c5b (name=test-event-network-local, type=bridge) + 2015-12-23T21:38:25.119625123Z network connect 8b11...2c5b (name=test-event-network-local, container=b4be...c54e, type=bridge) + + $ docker system events --filter 'container=container_1' --filter 'container=container_2' + + 2014-09-03T15:49:29.999999999Z07:00 container die 4386fb97867d (image=ubuntu-1:14.04) + 2014-05-10T17:42:14.999999999Z07:00 container stop 4386fb97867d (image=ubuntu-1:14.04) + 2014-05-10T17:42:14.999999999Z07:00 container die 7805c1d35632 (imager=redis:2.8) + 2014-09-03T15:49:29.999999999Z07:00 container stop 7805c1d35632 (image=redis:2.8) + + $ docker system events --filter 'type=volume' + + 2015-12-23T21:05:28.136212689Z volume create test-event-volume-local (driver=local) + 2015-12-23T21:05:28.383462717Z volume mount test-event-volume-local (read/write=true, container=562fe10671e9273da25eed36cdce26159085ac7ee6707105fd534866340a5025, destination=/foo, driver=local, propagation=rprivate) + 2015-12-23T21:05:28.650314265Z volume unmount test-event-volume-local (container=562fe10671e9273da25eed36cdce26159085ac7ee6707105fd534866340a5025, driver=local) + 2015-12-23T21:05:28.716218405Z volume destroy test-event-volume-local (driver=local) + + $ docker system events --filter 'type=network' + + 2015-12-23T21:38:24.705709133Z network create 8b111217944ba0ba844a65b13efcd57dc494932ee2527577758f939315ba2c5b (name=test-event-network-local, type=bridge) + 2015-12-23T21:38:25.119625123Z network connect 8b111217944ba0ba844a65b13efcd57dc494932ee2527577758f939315ba2c5b (name=test-event-network-local, container=b4be644031a3d90b400f88ab3d4bdf4dc23adb250e696b6328b85441abe2c54e, type=bridge) + + $ docker system 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) + ``` + + ### Format the output + + ```bash + $ docker system events --filter 'type=container' --format 'Type={{.Type}} Status={{.Status}} ID={{.ID}}' + + Type=container Status=create ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 + Type=container Status=attach ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 + Type=container Status=start ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 + Type=container Status=resize ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 + Type=container Status=die ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 + Type=container Status=destroy ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 + ``` + + #### Format as JSON + + ```none + $ docker system events --format '{{json .}}' + + {"status":"create","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. + {"status":"attach","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. + {"Type":"network","Action":"connect","Actor":{"ID":"1b50a5bf755f6021dfa78e.. + {"status":"start","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f42.. + {"status":"resize","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. + ``` diff --git a/_data/engine-cli/docker_system_prune.yaml b/_data/engine-cli/docker_system_prune.yaml index 6dee6b68487..6b659eb4887 100644 --- a/_data/engine-cli/docker_system_prune.yaml +++ b/_data/engine-cli/docker_system_prune.yaml @@ -10,6 +10,8 @@ options: shorthand: a default_value: "false" description: Remove all unused images not just dangling ones +- option: filter + description: Provide filter values (e.g. 'label==') - option: force shorthand: f default_value: "false" @@ -29,5 +31,25 @@ examples: "```bash\n$ docker system prune -a\n\nWARNING! This will remove:\n\t- my-jq:latest\ndeleted: sha256:6e66d724542af9bc4c4abf4a909791d7260b6d0110d8e220708b09e4ee1322e1\ndeleted: sha256:07b3fa89d4b17009eb3988dfc592c7d30ab3ba52d2007832dffcf6d40e3eda7f\ndeleted: sha256:3a88a5c81eb5c283e72db2dbc6d65cbfd8e80b6c89bb6e714cfaaa0eed99c548\n\nTotal - reclaimed space: 13.5 MB\n```" + reclaimed space: 13.5 MB\n```\n\n### Filtering\n\nThe filtering flag (`-f` or `--filter`) + format is of \"key=value\". If there is more\nthan one filter, then pass multiple + flags (e.g., `--filter \"foo=bar\" --filter \"bif=baz\"`)\n\nThe currently supported + filters are:\n\n* until (``) - only remove containers, images, and networks + created before given timestamp\n* label (`label=`, `label==`, `label!=`, + or `label!==`) - only remove containers, images, networks, and volumes + with (or without, in case `label!=...` is used) the specified labels.\n\nThe `until` + filter can be Unix timestamps, date formatted\ntimestamps, or Go duration strings + (e.g. `10m`, `1h30m`) computed\nrelative to the daemon machine’s time. Supported + formats for date\nformatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`,\n`2006-01-02T15:04:05.999999999`, + `2006-01-02Z07:00`, and `2006-01-02`. The local\ntimezone on the daemon will be + used if you do not provide either a `Z` or a\n`+-00:00` timezone offset at the end + of the timestamp. When providing Unix\ntimestamps enter seconds[.nanoseconds], + where seconds is the number of seconds\nthat have elapsed since January 1, 1970 + (midnight UTC/GMT), not counting leap\nseconds (aka Unix epoch or Unix time), and + the optional .nanoseconds field is a\nfraction of a second no more than nine digits + long.\n\nThe `label` filter accepts two formats. One is the `label=...` (`label=` + or `label==`),\nwhich removes containers, images, networks, and volumes + with the specified labels. The other\nformat is the `label!=...` (`label!=` + or `label!==`), which removes\ncontainers, images, networks, and volumes + without the specified labels." diff --git a/_data/engine-cli/docker_update.yaml b/_data/engine-cli/docker_update.yaml index a0145d18693..de5d4e2f0a5 100644 --- a/_data/engine-cli/docker_update.yaml +++ b/_data/engine-cli/docker_update.yaml @@ -35,18 +35,24 @@ options: shorthand: c default_value: "0" description: CPU shares (relative weight) +- option: cpus + description: Number of CPUs - option: cpuset-cpus description: CPUs in which to allow execution (0-3, 0,1) - option: cpuset-mems description: MEMs in which to allow execution (0-3, 0,1) - option: kernel-memory + default_value: "0" description: Kernel memory limit - option: memory shorthand: m + default_value: "0" description: Memory limit - option: memory-reservation + default_value: "0" description: Memory soft limit - option: memory-swap + default_value: "0" description: | Swap limit equal to memory plus swap: '-1' to enable unlimited swap - option: restart diff --git a/_data/engine-cli/docker_volume.yaml b/_data/engine-cli/docker_volume.yaml index 7df8a9b9270..ad5134eae00 100644 --- a/_data/engine-cli/docker_volume.yaml +++ b/_data/engine-cli/docker_volume.yaml @@ -1,8 +1,8 @@ command: docker volume short: Manage volumes long: |- - Manage volumes. You can use subcommand to create, list, inspect, remove - volumes. + Manage volumes. You can use subcommands to create, inspect, list, remove, or + prune volumes. usage: docker volume COMMAND pname: docker plink: docker.yaml diff --git a/_data/engine-cli/docker_volume_create.yaml b/_data/engine-cli/docker_volume_create.yaml index 929ac3cc908..8b774d254ba 100644 --- a/_data/engine-cli/docker_volume_create.yaml +++ b/_data/engine-cli/docker_volume_create.yaml @@ -12,7 +12,6 @@ options: default_value: local description: Specify volume driver name - option: label - default_value: '[]' description: Set metadata for a volume - option: name description: Specify volume name diff --git a/_data/engine-cli/docker_volume_ls.yaml b/_data/engine-cli/docker_volume_ls.yaml index dc81e6947b1..95499710c43 100644 --- a/_data/engine-cli/docker_volume_ls.yaml +++ b/_data/engine-cli/docker_volume_ls.yaml @@ -63,9 +63,9 @@ examples: |- #### driver - The `driver` filter matches on all or part of a volume's driver name. + The `driver` filter matches volumes based on their driver. - The following filter matches all volumes with a driver name containing the `local` string. + The following example matches volumes that are created with the `local` driver: ```bash $ docker volume ls -f driver=local diff --git a/_data/engine-cli/docker_volume_prune.yaml b/_data/engine-cli/docker_volume_prune.yaml index 6462d7e9dd4..e18f78a6676 100644 --- a/_data/engine-cli/docker_volume_prune.yaml +++ b/_data/engine-cli/docker_volume_prune.yaml @@ -6,6 +6,8 @@ usage: docker volume prune [OPTIONS] pname: docker volume plink: docker_volume.yaml options: +- option: filter + description: Provide filter values (e.g. 'label=