diff --git a/_data/engine-cli/docker_attach.yaml b/_data/engine-cli/docker_attach.yaml index 6334682a944a..0686d6ed4c84 100644 --- a/_data/engine-cli/docker_attach.yaml +++ b/_data/engine-cli/docker_attach.yaml @@ -1,65 +1,6 @@ command: docker attach short: Attach local standard input, output, and error streams to a running container -long: |- - 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, - from different sessions on the Docker host. - - 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 - the container. If the container was run with `-i` and `-t`, you can detach from - a container and leave it running using the `CTRL-p CTRL-q` key sequence. - - > **Note:** - > A process running as PID 1 inside a container is treated specially by - > Linux: it ignores any signal with the default action. So, the process - > will not terminate on `SIGINT` or `SIGTERM` unless it is coded to do - > so. - - It is forbidden to redirect the standard input of a `docker attach` command - while attaching to a tty-enabled container (i.e.: launched with `-t`). - - While a client is connected to container's stdio using `docker attach`, Docker - uses a ~1MB memory buffer to maximize the throughput of the application. If - this buffer is filled, the speed of the API connection will start to have an - effect on the process output writing speed. This is similar to other - applications like SSH. Because of this, it is not recommended to run - performance critical applications that generate a lot of output in the - foreground over a slow client connection. Instead, users should use the - `docker logs` command to get access to the logs. - - ### Override the detach sequence - - If you want, you can configure an override the Docker key sequence for detach. - This is useful if the Docker default sequence conflicts with key sequence you - use for other applications. There are two ways to define your own detach key - sequence, as a per-container override or as a configuration property on your - entire configuration. - - To override the sequence for an individual container, use the - `--detach-keys=""` flag with the `docker attach` command. The format of - the `` is either a letter [a-Z], or the `ctrl-` combined with any of - the following: - - * `a-z` (a single lowercase alpha character ) - * `@` (at sign) - * `[` (left bracket) - * `\\` (two backward slashes) - * `_` (underscore) - * `^` (caret) - - These `a`, `ctrl-a`, `X`, or `ctrl-\\` values are all examples of valid key - sequences. To configure a different configuration default key sequence for all - containers, see [**Configuration file** section](cli.md#configuration-files). +long: Attach local standard input, output, and error streams to a running container usage: docker attach [OPTIONS] CONTAINER pname: docker plink: docker.yaml @@ -90,74 +31,6 @@ options: experimentalcli: false kubernetes: false swarm: false -examples: |- - ### Attach to and detach from a running container - - ```bash - $ docker run -d --name topdemo ubuntu /usr/bin/top -b - - $ docker attach topdemo - - top - 02:05:52 up 3:05, 0 users, load average: 0.01, 0.02, 0.05 - Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie - Cpu(s): 0.1%us, 0.2%sy, 0.0%ni, 99.7%id, 0.0%wa, 0.0%hi, 0.0%si, 0.0%st - Mem: 373572k total, 355560k used, 18012k free, 27872k buffers - Swap: 786428k total, 0k used, 786428k free, 221740k cached - - PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND - 1 root 20 0 17200 1116 912 R 0 0.3 0:00.03 top - - top - 02:05:55 up 3:05, 0 users, load average: 0.01, 0.02, 0.05 - Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie - Cpu(s): 0.0%us, 0.2%sy, 0.0%ni, 99.8%id, 0.0%wa, 0.0%hi, 0.0%si, 0.0%st - Mem: 373572k total, 355244k used, 18328k free, 27872k buffers - Swap: 786428k total, 0k used, 786428k free, 221776k cached - - PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND - 1 root 20 0 17208 1144 932 R 0 0.3 0:00.03 top - - - top - 02:05:58 up 3:06, 0 users, load average: 0.01, 0.02, 0.05 - Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie - Cpu(s): 0.2%us, 0.3%sy, 0.0%ni, 99.5%id, 0.0%wa, 0.0%hi, 0.0%si, 0.0%st - Mem: 373572k total, 355780k used, 17792k free, 27880k buffers - Swap: 786428k total, 0k used, 786428k free, 221776k cached - - PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND - 1 root 20 0 17208 1144 932 R 0 0.3 0:00.03 top - ^C$ - - $ echo $? - 0 - $ docker ps -a | grep topdemo - - 7998ac8581f9 ubuntu:14.04 "/usr/bin/top -b" 38 seconds ago Exited (0) 21 seconds ago topdemo - ``` - - ### Get the exit code of the container's command - - And in this second example, you can see the exit code returned by the `bash` - process is returned by the `docker attach` command to its caller too: - - ```bash - $ docker run --name test -d -it debian - - 275c44472aebd77c926d4527885bb09f2f6db21d878c75f0a1c212c03d3bcfab - - $ docker attach test - - root@f38c87f2a42d:/# exit 13 - - exit - - $ echo $? - - 13 - - $ docker ps -a | grep test - - 275c44472aeb debian:7 "/bin/bash" 26 seconds ago Exited (13) 17 seconds ago test - ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_build.yaml b/_data/engine-cli/docker_build.yaml index f853b8f8b540..6c0ed3ab0043 100644 --- a/_data/engine-cli/docker_build.yaml +++ b/_data/engine-cli/docker_build.yaml @@ -1,114 +1,6 @@ command: docker build short: Build an image from a Dockerfile -long: |- - The `docker build` command builds Docker images from a Dockerfile and a - "context". A build's context is the set of files located in the specified - `PATH` or `URL`. The build process can refer to any of the files in the - context. For example, your build can use a [*COPY*](../builder.md#copy) - instruction to reference a file in the context. - - The `URL` parameter can refer to three kinds of resources: Git repositories, - pre-packaged tarball contexts and plain text files. - - ### Git repositories - - When the `URL` parameter points to the location of a Git repository, the - 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 - 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, - and 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`: - - ```bash - $ docker build https://github.com/docker/rootfs.git#container:docker - ``` - - The following table represents all the valid suffixes with their build - contexts: - - Build Syntax Suffix | Commit Used | Build Context Used - --------------------------------|-----------------------|------------------- - `myrepo.git` | `refs/heads/master` | `/` - `myrepo.git#mytag` | `refs/tags/mytag` | `/` - `myrepo.git#mybranch` | `refs/heads/mybranch` | `/` - `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` - - > **Note** - > - > You cannot specify the build-context directory (`myfolder` in the examples above) - > when using BuildKit as builder (`DOCKER_BUILDKIT=1`). Support for this feature - > is tracked in [buildkit#1684](https://github.com/moby/buildkit/issues/1684). - - ### Tarball contexts - - If you pass an URL to a remote tarball, the URL itself is sent to the daemon: - - ```bash - $ docker build http://server/context.tar.gz - ``` - - The download operation will be performed on the host the Docker daemon is - running on, which is not necessarily the same host from which the build command - is being issued. The Docker daemon will fetch `context.tar.gz` and use it as the - build context. Tarball contexts must be tar archives conforming to the standard - `tar` UNIX format and can be compressed with any one of the 'xz', 'bzip2', - 'gzip' or 'identity' (no compression) formats. - - ### Text files - - Instead of specifying a context, you can pass a single `Dockerfile` in the - `URL` or pipe the file in via `STDIN`. To pipe a `Dockerfile` from `STDIN`: - - ```bash - $ docker build - < Dockerfile - ``` - - With Powershell on Windows, you can run: - - ```powershell - Get-Content Dockerfile | docker build - - ``` - - If you use `STDIN` or specify a `URL` pointing to a plain text file, the system - places the contents into a file called `Dockerfile`, and any `-f`, `--file` - option is ignored. In this scenario, there is no context. - - By default the `docker build` command will look for a `Dockerfile` at the root - of the build context. The `-f`, `--file`, option lets you specify the path to - an alternative file to use instead. This is useful in cases where the same set - of files are used for multiple builds. The path must be to a file within the - build context. If a relative path is specified then it is interpreted as - relative to the root of the context. - - In most cases, it's best to put each Dockerfile in an empty directory. Then, - add to that directory only the files needed for building the Dockerfile. To - increase the build's performance, you can exclude files and directories by - adding a `.dockerignore` file to that directory as well. For information on - creating one, see the [.dockerignore file](../builder.md#dockerignore-file). - - If the Docker client loses connection to the daemon, the build is canceled. - This happens if you interrupt the Docker client with `CTRL-c` or if the Docker - client is killed for any reason. If the build initiated a pull which is still - running at the time the build is cancelled, the pull is cancelled as well. +long: Build an image from a Dockerfile usage: docker build [OPTIONS] PATH | URL | - pname: docker plink: docker.yaml @@ -403,8 +295,7 @@ options: default_value: "false" description: Stream attaches to server to negotiate build context deprecated: false - min_api_version: "1.31" - experimental: true + experimental: false experimentalcli: false kubernetes: false swarm: false @@ -434,586 +325,6 @@ options: experimentalcli: false kubernetes: false swarm: false -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 refers 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). - - When using the [BuildKit backend](../builder.md#buildkit), `docker build` searches - for a `.dockerignore` file relative to the Dockerfile name. For example, running - `docker build -f myapp.Dockerfile .` will first look for an ignore file named - `myapp.Dockerfile.dockerignore`. If such a file is not found, the `.dockerignore` - file is used if present. Using a Dockerfile based `.dockerignore` is useful if a - project contains multiple Dockerfiles that expect to ignore different sets of - files. - - - ### 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 - $ curl example.com/remote/Dockerfile | docker build -f - . - ``` - - The above command will use the current directory as the build context and read - a Dockerfile from stdin. - - ```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` returns 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` does 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#specify-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 --build-arg FTP_PROXY=http://40.50.60.5:4567 . - ``` - - 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. You must add `--build-arg` for each build argument. - - 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). - - You may also use the `--build-arg` flag without a value, in which case the value - from the local environment will be propagated into the Docker container being - built: - - ```bash - $ export HTTP_PROXY=http://10.20.30.2:1234 - $ docker build --build-arg HTTP_PROXY . - ``` - - This is similar to how `docker run -e` works. Refer to the [`docker run` documentation](https://docs.docker.com/engine/reference/commandline/run/#set-environment-variables--e---env---env-file) - for more information. - - ### 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"`. - - ### Add entries to container hosts file (--add-host) - - You can add other hosts into a container's `/etc/hosts` file by using one or - more `--add-host` flags. This example adds a static address for a host named - `docker`: - - $ docker build --add-host=docker:10.180.0.1 . - - ### Specifying target build stage (--target) - - When building a Dockerfile with multiple build stages, `--target` can be used to - specify an intermediate build stage by name as a final stage for the resulting - image. Commands after the target stage will be skipped. - - ```dockerfile - FROM debian AS build-env - ... - - FROM alpine AS production-env - ... - ``` - - ```bash - $ docker build -t mybuildimage --target build-env . - ``` - - ### Custom build outputs - - By default, a local container image is created from the build result. The - `--output` (or `-o`) flag allows you to override this behavior, and a specify a - custom exporter. For example, custom exporters allow you to export the build - artifacts as files on the local filesystem instead of a Docker image, which can - be useful for generating local binaries, code generation etc. - - The value for `--output` is a CSV-formatted string defining the exporter type - and options. Currently, `local` and `tar` exporters are supported. The `local` - exporter writes the resulting build files to a directory on the client side. The - `tar` exporter is similar but writes the files as a single tarball (`.tar`). - - If no type is specified, the value defaults to the output directory of the local - exporter. Use a hyphen (`-`) to write the output tarball to standard output - (`STDOUT`). - - The following example builds an image using the current directory (`.`) as build - context, and exports the files to a directory named `out` in the current directory. - If the directory does not exist, Docker creates the directory automatically: - - ```bash - $ docker build -o out . - ``` - - The example above uses the short-hand syntax, omitting the `type` options, and - thus uses the default (`local`) exporter. The example below shows the equivalent - using the long-hand CSV syntax, specifying both `type` and `dest` (destination - path): - - ```bash - $ docker build --output type=local,dest=out . - ``` - - Use the `tar` type to export the files as a `.tar` archive: - - ```bash - $ docker build --output type=tar,dest=out.tar . - ``` - - The example below shows the equivalent when using the short-hand syntax. In this - case, `-` is specified as destination, which automatically selects the `tar` type, - and writes the output tarball to standard output, which is then redirected to - the `out.tar` file: - - ```bash - docker build -o - . > out.tar - ``` - - The `--output` option exports all files from the target stage. A common pattern - for exporting only specific files is to do multi-stage builds and to copy the - desired files to a new scratch stage with [`COPY --from`](../builder.md#copy). - - The example `Dockerfile` below uses a separate stage to collect the - build-artifacts for exporting: - - ```dockerfile - FROM golang AS build-stage - RUN go get -u github.com/LK4D4/vndr - - FROM scratch AS export-stage - COPY --from=build-stage /go/bin/vndr / - ``` - - When building the Dockerfile with the `-o` option, only the files from the final - stage are exported to the `out` directory, in this case, the `vndr` binary: - - ```bash - $ docker build -o out . - - [+] Building 2.3s (7/7) FINISHED - => [internal] load build definition from Dockerfile 0.1s - => => transferring dockerfile: 176B 0.0s - => [internal] load .dockerignore 0.0s - => => transferring context: 2B 0.0s - => [internal] load metadata for docker.io/library/golang:latest 1.6s - => [build-stage 1/2] FROM docker.io/library/golang@sha256:2df96417dca0561bf1027742dcc5b446a18957cd28eba6aa79269f23f1846d3f 0.0s - => => resolve docker.io/library/golang@sha256:2df96417dca0561bf1027742dcc5b446a18957cd28eba6aa79269f23f1846d3f 0.0s - => CACHED [build-stage 2/2] RUN go get -u github.com/LK4D4/vndr 0.0s - => [export-stage 1/1] COPY --from=build-stage /go/bin/vndr / 0.2s - => exporting to client 0.4s - => => copying files 10.30MB 0.3s - - $ ls ./out - vndr - ``` - - > **Note** - > - > This feature requires the BuildKit backend. You can either - > [enable BuildKit](../builder.md#buildkit) or use the [buildx](https://github.com/docker/buildx) - > plugin which provides more output type options. - - ### Specifying external cache sources - - In addition to local build cache, the builder can reuse the cache generated from - previous builds with the `--cache-from` flag pointing to an image in the registry. - - To use an image as a cache source, cache metadata needs to be written into the - image on creation. This can be done by setting `--build-arg BUILDKIT_INLINE_CACHE=1` - when building the image. After that, the built image can be used as a cache source - for subsequent builds. - - Upon importing the cache, the builder will only pull the JSON metadata from the - registry and determine possible cache hits based on that information. If there - is a cache hit, the matched layers are pulled into the local environment. - - In addition to images, the cache can also be pulled from special cache manifests - generated by [`buildx`](https://github.com/docker/buildx) or the BuildKit CLI - (`buildctl`). These manifests (when built with the `type=registry` and `mode=max` - options) allow pulling layer data for intermediate stages in multi-stage builds. - - The following example builds an image with inline-cache metadata and pushes it - to a registry, then uses the image as a cache source on another machine: - - ```bash - $ docker build -t myname/myapp --build-arg BUILDKIT_INLINE_CACHE=1 . - $ docker push myname/myapp - ``` - - After pushing the image, the image is used as cache source on another machine. - BuildKit automatically pulls the image from the registry if needed. - - ```bash - # on another machine - $ docker build --cache-from myname/myapp . - ``` - - > **Note** - > - > This feature requires the BuildKit backend. You can either - > [enable BuildKit](../builder.md#buildkit) or use the [buildx](https://github.com/docker/buildx) - > plugin. The previous builder has limited support for reusing cache from - > pre-pulled images. - - ### Squash an image's layers (--squash) (experimental) - - #### Overview - - 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 squashed layers. This effectively makes it look - like all `Dockerfile` commands were created with a single layer. The build - cache is preserved with this method. - - The `--squash` option is an experimental feature, and should not be considered - stable. - - - Squashing layers can be beneficial if your Dockerfile produces multiple layers - modifying the same files, for example, files that are created in one step, and - removed in another step. For other use-cases, squashing images may actually have - a negative impact on performance; when pulling an image consisting of multiple - layers, layers can be pulled in parallel, and allows sharing layers between - images (saving space). - - For most use cases, multi-stage builds are a better alternative, as they give more - fine-grained control over your build, and can take advantage of future - optimizations in the builder. Refer to the [use multi-stage builds](https://docs.docker.com/develop/develop-images/multistage-build/) - section in the userguide for more information. - - - #### Known limitations - - The `--squash` option has a number of known limitations: - - - When squashing layers, the resulting image cannot take advantage of layer - sharing with other images, and may use significantly more space. Sharing the - base image is still supported. - - When 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. - - While squashing layers may produce smaller images, it may have a negative - impact on performance, as a single layer takes longer to extract, and - downloading a single layer cannot be parallelized. - - When attempting to squash an image that does not make changes to the - filesystem (for example, the Dockerfile only contains `ENV` instructions), - the squash step will fail (see [issue #33823](https://github.com/moby/moby/issues/33823)). - - #### Prerequisites - - The example on this page is using experimental mode in Docker 19.03. - - Experimental mode can be enabled by using the `--experimental` flag when starting - the Docker daemon or setting `experimental: true` in the `daemon.json` configuration - file. - - By default, experimental mode is disabled. To see the current configuration of - the docker daemon, use the `docker version` command and check the `Experimental` - line in the `Engine` section: - - ```console - Client: Docker Engine - Community - Version: 19.03.8 - API version: 1.40 - Go version: go1.12.17 - Git commit: afacb8b - Built: Wed Mar 11 01:21:11 2020 - OS/Arch: darwin/amd64 - Experimental: false - - Server: Docker Engine - Community - Engine: - Version: 19.03.8 - API version: 1.40 (minimum version 1.12) - Go version: go1.12.17 - Git commit: afacb8b - Built: Wed Mar 11 01:29:16 2020 - OS/Arch: linux/amd64 - Experimental: true - [...] - ``` - - To enable experimental mode, users need to restart the docker daemon with the - experimental flag enabled. - - #### Enable Docker experimental - - Experimental features are now included in the standard Docker binaries as of - version 1.13.0. For enabling experimental features, you need to start the - Docker daemon with `--experimental` flag. You can also enable the daemon flag - via `/etc/docker/daemon.json`. e.g. - - ```json - { - "experimental": true - } - ``` - - Then make sure the experimental flag is enabled: - - ```bash - $ docker version -f '{{.Server.Experimental}}' - true - ``` - - #### Build an image with `--squash` argument - - The following is an example of docker build with `--squash` argument - - ```dockerfile - FROM busybox - RUN echo hello > /hello - RUN echo world >> /hello - RUN touch remove_me /remove_me - ENV HELLO=world - RUN rm /remove_me - ``` - - An image named `test` is built with `--squash` argument. - - ```bash - $ docker build --squash -t test . - - [...] - ``` - - If everything is right, the history looks like this: - - ```bash - $ docker history test - - IMAGE CREATED CREATED BY SIZE COMMENT - 4e10cb5b4cac 3 seconds ago 12 B merge sha256:88a7b0112a41826885df0e7072698006ee8f621c6ab99fca7fe9151d7b599702 to sha256:47bcc53f74dc94b1920f0b34f6036096526296767650f223433fe65c35f149eb - 5 minutes ago /bin/sh -c rm /remove_me 0 B - 5 minutes ago /bin/sh -c #(nop) ENV HELLO=world 0 B - 5 minutes ago /bin/sh -c touch remove_me /remove_me 0 B - 5 minutes ago /bin/sh -c echo world >> /hello 0 B - 6 minutes ago /bin/sh -c echo hello > /hello 0 B - 7 weeks ago /bin/sh -c #(nop) CMD ["sh"] 0 B - 7 weeks ago /bin/sh -c #(nop) ADD file:47ca6e777c36a4cfff 1.113 MB - ``` - - We could find that a layer's name is ``, and there is a new layer with - COMMENT `merge`. - - Test the image, check for `/remove_me` being gone, make sure `hello\nworld` is - in `/hello`, make sure the `HELLO` environment variable's value is `world`. deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_builder_build.yaml b/_data/engine-cli/docker_builder_build.yaml index c2005186a13d..30b108b6d808 100644 --- a/_data/engine-cli/docker_builder_build.yaml +++ b/_data/engine-cli/docker_builder_build.yaml @@ -295,8 +295,7 @@ options: default_value: "false" description: Stream attaches to server to negotiate build context deprecated: false - min_api_version: "1.31" - experimental: true + experimental: false experimentalcli: false kubernetes: false swarm: false diff --git a/_data/engine-cli/docker_commit.yaml b/_data/engine-cli/docker_commit.yaml index 964b0a6d64e0..af3ab5d677e9 100644 --- a/_data/engine-cli/docker_commit.yaml +++ b/_data/engine-cli/docker_commit.yaml @@ -1,23 +1,6 @@ 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 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). - - The commit operation will not include any data contained in - volumes mounted inside the container. - - By default, the container being committed and its processes will be paused - while the image is committed. This reduces the likelihood of encountering data - corruption during the process of creating the commit. If this behavior is - undesired, set the `--pause` option to false. - - The `--change` option will apply `Dockerfile` instructions to the image that is - created. Supported `Dockerfile` instructions: - `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`LABEL`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` +long: Create a new image from a container's changes usage: docker commit [OPTIONS] CONTAINER [REPOSITORY[:TAG]] pname: docker plink: docker.yaml @@ -59,72 +42,6 @@ options: experimentalcli: false kubernetes: false swarm: false -examples: |- - ### Commit a container - - ```bash - $ docker ps - - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky - 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours focused_hamilton - - $ docker commit c3f279d17e0a svendowideit/testimage:version3 - - f5283438590d - - $ docker images - - REPOSITORY TAG ID CREATED SIZE - svendowideit/testimage version3 f5283438590d 16 seconds ago 335.7 MB - ``` - - ### Commit a container with new configurations - - ```bash - $ docker ps - - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky - 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours focused_hamilton - - $ docker inspect -f "{{ .Config.Env }}" c3f279d17e0a - - [HOME=/ PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin] - - $ docker commit --change "ENV DEBUG=true" c3f279d17e0a svendowideit/testimage:version3 - - f5283438590d - - $ docker inspect -f "{{ .Config.Env }}" f5283438590d - - [HOME=/ PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin DEBUG=true] - ``` - - ### Commit a container with new `CMD` and `EXPOSE` instructions - - ```bash - $ docker ps - - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky - 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours focused_hamilton - - $ docker commit --change='CMD ["apachectl", "-DFOREGROUND"]' -c "EXPOSE 80" c3f279d17e0a svendowideit/testimage:version4 - - f5283438590d - - $ docker run -d svendowideit/testimage:version4 - - 89373736e2e7f00bc149bd783073ac43d0507da250e999f3f1036e0db60817c0 - - $ docker ps - - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 89373736e2e7 testimage:version4 "apachectl -DFOREGROU" 3 seconds ago Up 2 seconds 80/tcp distracted_fermat - c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky - 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours focused_hamilton - ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_attach.yaml b/_data/engine-cli/docker_container_attach.yaml index 95b4d3ede8be..de9922e58ed9 100644 --- a/_data/engine-cli/docker_container_attach.yaml +++ b/_data/engine-cli/docker_container_attach.yaml @@ -1,6 +1,65 @@ command: docker container attach 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 +long: |- + 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, + from different sessions on the Docker host. + + 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 + the container. If the container was run with `-i` and `-t`, you can detach from + a container and leave it running using the `CTRL-p CTRL-q` key sequence. + + > **Note:** + > A process running as PID 1 inside a container is treated specially by + > Linux: it ignores any signal with the default action. So, the process + > will not terminate on `SIGINT` or `SIGTERM` unless it is coded to do + > so. + + It is forbidden to redirect the standard input of a `docker attach` command + while attaching to a tty-enabled container (i.e.: launched with `-t`). + + While a client is connected to container's stdio using `docker attach`, Docker + uses a ~1MB memory buffer to maximize the throughput of the application. If + this buffer is filled, the speed of the API connection will start to have an + effect on the process output writing speed. This is similar to other + applications like SSH. Because of this, it is not recommended to run + performance critical applications that generate a lot of output in the + foreground over a slow client connection. Instead, users should use the + `docker logs` command to get access to the logs. + + ### Override the detach sequence + + If you want, you can configure an override the Docker key sequence for detach. + This is useful if the Docker default sequence conflicts with key sequence you + use for other applications. There are two ways to define your own detach key + sequence, as a per-container override or as a configuration property on your + entire configuration. + + To override the sequence for an individual container, use the + `--detach-keys=""` flag with the `docker attach` command. The format of + the `` is either a letter [a-Z], or the `ctrl-` combined with any of + the following: + + * `a-z` (a single lowercase alpha character ) + * `@` (at sign) + * `[` (left bracket) + * `\\` (two backward slashes) + * `_` (underscore) + * `^` (caret) + + These `a`, `ctrl-a`, `X`, or `ctrl-\\` values are all examples of valid key + sequences. To configure a different configuration default key sequence for all + containers, see [**Configuration file** section](cli.md#configuration-files). usage: docker container attach [OPTIONS] CONTAINER pname: docker container plink: docker_container.yaml @@ -31,6 +90,74 @@ options: experimentalcli: false kubernetes: false swarm: false +examples: |- + ### Attach to and detach from a running container + + ```bash + $ docker run -d --name topdemo ubuntu /usr/bin/top -b + + $ docker attach topdemo + + top - 02:05:52 up 3:05, 0 users, load average: 0.01, 0.02, 0.05 + Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie + Cpu(s): 0.1%us, 0.2%sy, 0.0%ni, 99.7%id, 0.0%wa, 0.0%hi, 0.0%si, 0.0%st + Mem: 373572k total, 355560k used, 18012k free, 27872k buffers + Swap: 786428k total, 0k used, 786428k free, 221740k cached + + PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND + 1 root 20 0 17200 1116 912 R 0 0.3 0:00.03 top + + top - 02:05:55 up 3:05, 0 users, load average: 0.01, 0.02, 0.05 + Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie + Cpu(s): 0.0%us, 0.2%sy, 0.0%ni, 99.8%id, 0.0%wa, 0.0%hi, 0.0%si, 0.0%st + Mem: 373572k total, 355244k used, 18328k free, 27872k buffers + Swap: 786428k total, 0k used, 786428k free, 221776k cached + + PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND + 1 root 20 0 17208 1144 932 R 0 0.3 0:00.03 top + + + top - 02:05:58 up 3:06, 0 users, load average: 0.01, 0.02, 0.05 + Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie + Cpu(s): 0.2%us, 0.3%sy, 0.0%ni, 99.5%id, 0.0%wa, 0.0%hi, 0.0%si, 0.0%st + Mem: 373572k total, 355780k used, 17792k free, 27880k buffers + Swap: 786428k total, 0k used, 786428k free, 221776k cached + + PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND + 1 root 20 0 17208 1144 932 R 0 0.3 0:00.03 top + ^C$ + + $ echo $? + 0 + $ docker ps -a | grep topdemo + + 7998ac8581f9 ubuntu:14.04 "/usr/bin/top -b" 38 seconds ago Exited (0) 21 seconds ago topdemo + ``` + + ### Get the exit code of the container's command + + And in this second example, you can see the exit code returned by the `bash` + process is returned by the `docker attach` command to its caller too: + + ```bash + $ docker run --name test -d -it debian + + 275c44472aebd77c926d4527885bb09f2f6db21d878c75f0a1c212c03d3bcfab + + $ docker attach test + + root@f38c87f2a42d:/# exit 13 + + exit + + $ echo $? + + 13 + + $ docker ps -a | grep test + + 275c44472aeb debian:7 "/bin/bash" 26 seconds ago Exited (13) 17 seconds ago test + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_commit.yaml b/_data/engine-cli/docker_container_commit.yaml index 8524a53a5bcb..691449a6f3f3 100644 --- a/_data/engine-cli/docker_container_commit.yaml +++ b/_data/engine-cli/docker_container_commit.yaml @@ -1,6 +1,23 @@ command: docker container commit short: Create a new image from a container's changes -long: 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 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). + + The commit operation will not include any data contained in + volumes mounted inside the container. + + By default, the container being committed and its processes will be paused + while the image is committed. This reduces the likelihood of encountering data + corruption during the process of creating the commit. If this behavior is + undesired, set the `--pause` option to false. + + The `--change` option will apply `Dockerfile` instructions to the image that is + created. Supported `Dockerfile` instructions: + `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`LABEL`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` usage: docker container commit [OPTIONS] CONTAINER [REPOSITORY[:TAG]] pname: docker container plink: docker_container.yaml @@ -42,6 +59,72 @@ options: experimentalcli: false kubernetes: false swarm: false +examples: |- + ### Commit a container + + ```bash + $ docker ps + + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky + 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours focused_hamilton + + $ docker commit c3f279d17e0a svendowideit/testimage:version3 + + f5283438590d + + $ docker images + + REPOSITORY TAG ID CREATED SIZE + svendowideit/testimage version3 f5283438590d 16 seconds ago 335.7 MB + ``` + + ### Commit a container with new configurations + + ```bash + $ docker ps + + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky + 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours focused_hamilton + + $ docker inspect -f "{{ .Config.Env }}" c3f279d17e0a + + [HOME=/ PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin] + + $ docker commit --change "ENV DEBUG=true" c3f279d17e0a svendowideit/testimage:version3 + + f5283438590d + + $ docker inspect -f "{{ .Config.Env }}" f5283438590d + + [HOME=/ PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin DEBUG=true] + ``` + + ### Commit a container with new `CMD` and `EXPOSE` instructions + + ```bash + $ docker ps + + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky + 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours focused_hamilton + + $ docker commit --change='CMD ["apachectl", "-DFOREGROUND"]' -c "EXPOSE 80" c3f279d17e0a svendowideit/testimage:version4 + + f5283438590d + + $ docker run -d svendowideit/testimage:version4 + + 89373736e2e7f00bc149bd783073ac43d0507da250e999f3f1036e0db60817c0 + + $ docker ps + + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 89373736e2e7 testimage:version4 "apachectl -DFOREGROU" 3 seconds ago Up 2 seconds 80/tcp distracted_fermat + c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky + 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours focused_hamilton + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_cp.yaml b/_data/engine-cli/docker_container_cp.yaml index e308f4068a30..383371634a5e 100644 --- a/_data/engine-cli/docker_container_cp.yaml +++ b/_data/engine-cli/docker_container_cp.yaml @@ -1,12 +1,88 @@ command: docker container cp short: Copy files/folders between a container and the local filesystem long: |- - Copy files/folders between a container and the local filesystem + The `docker cp` utility copies the contents of `SRC_PATH` to the `DEST_PATH`. + You can copy from the container's file system to the local machine or the + reverse, from the local filesystem to the container. If `-` is specified for + either the `SRC_PATH` or `DEST_PATH`, you can also stream a tar archive from + `STDIN` or to `STDOUT`. The `CONTAINER` can be a running or stopped container. + The `SRC_PATH` or `DEST_PATH` can be a file or directory. - Use '-' as the source to read a tar archive from stdin - and extract it to a directory destination in a container. - Use '-' as the destination to stream a tar archive of a - container source to stdout. + The `docker cp` command assumes container paths are relative to the container's + `/` (root) directory. This means supplying the initial forward slash is optional; + The command sees `compassionate_darwin:/tmp/foo/myfile.txt` and + `compassionate_darwin:tmp/foo/myfile.txt` as identical. Local machine paths can + be an absolute or relative value. The command interprets a local machine's + relative paths as relative to the current working directory where `docker cp` is + run. + + The `cp` command behaves like the Unix `cp -a` command in that directories are + copied recursively with permissions preserved if possible. Ownership is set to + the user and primary group at the destination. For example, files copied to a + container are created with `UID:GID` of the root user. Files copied to the local + machine are created with the `UID:GID` of the user which invoked the `docker cp` + command. However, if you specify the `-a` option, `docker cp` sets the ownership + to the user and primary group at the source. + If you specify the `-L` option, `docker cp` follows any symbolic link + in the `SRC_PATH`. `docker cp` does *not* create parent directories for + `DEST_PATH` if they do not exist. + + Assuming a path separator of `/`, a first argument of `SRC_PATH` and second + argument of `DEST_PATH`, the behavior is as follows: + + - `SRC_PATH` specifies a file + - `DEST_PATH` does not exist + - the file is saved to a file created at `DEST_PATH` + - `DEST_PATH` does not exist and ends with `/` + - Error condition: the destination directory must exist. + - `DEST_PATH` exists and is a file + - the destination is overwritten with the source file's contents + - `DEST_PATH` exists and is a directory + - the file is copied into this directory using the basename from + `SRC_PATH` + - `SRC_PATH` specifies a directory + - `DEST_PATH` does not exist + - `DEST_PATH` is created as a directory and the *contents* of the source + directory are copied into this directory + - `DEST_PATH` exists and is a file + - Error condition: cannot copy a directory to a file + - `DEST_PATH` exists and is a directory + - `SRC_PATH` does not end with `/.` (that is: _slash_ followed by _dot_) + - the source directory is copied into this directory + - `SRC_PATH` does end with `/.` (that is: _slash_ followed by _dot_) + - the *content* of the source directory is copied into this + directory + + The command requires `SRC_PATH` and `DEST_PATH` to exist according to the above + rules. If `SRC_PATH` is local and is a symbolic link, the symbolic link, not + the target, is copied by default. To copy the link target and not the link, specify + the `-L` option. + + A colon (`:`) is used as a delimiter between `CONTAINER` and its path. You can + also use `:` when specifying paths to a `SRC_PATH` or `DEST_PATH` on a local + machine, for example `file:name.txt`. If you use a `:` in a local machine path, + you must be explicit with a relative or absolute path, for example: + + `/path/to/file:name.txt` or `./file:name.txt` + + It is not possible to copy certain system files such as resources under + `/proc`, `/sys`, `/dev`, [tmpfs](run.md#mount-tmpfs---tmpfs), and mounts created by + the user in the container. However, you can still copy such files by manually + running `tar` in `docker exec`. Both of the following examples do the same thing + in different ways (consider `SRC_PATH` and `DEST_PATH` are directories): + + ```bash + $ docker exec CONTAINER tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | tar Cxf DEST_PATH - + ``` + + ```bash + $ tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | docker exec -i CONTAINER tar Cxf DEST_PATH - + ``` + + Using `-` as the `SRC_PATH` streams the contents of `STDIN` as a tar archive. + The command extracts the content of the tar to the `DEST_PATH` in container's + filesystem. In this case, `DEST_PATH` must specify a directory. Using `-` as + the `DEST_PATH` streams the contents of the resource as a tar archive to `STDOUT`. usage: "docker container cp [OPTIONS] CONTAINER:SRC_PATH DEST_PATH|-\n\tdocker cp [OPTIONS] SRC_PATH|- CONTAINER:DEST_PATH" pname: docker container diff --git a/_data/engine-cli/docker_container_create.yaml b/_data/engine-cli/docker_container_create.yaml index efbd9f0d478f..2049a5ed1ab1 100644 --- a/_data/engine-cli/docker_container_create.yaml +++ b/_data/engine-cli/docker_container_create.yaml @@ -1,6 +1,17 @@ command: docker container create short: Create a new container -long: Create a new container +long: |- + The `docker create` command creates a writeable container layer over the + specified image and prepares it for running the specified command. The + container ID is then printed to `STDOUT`. This is similar to `docker run -d` + except the container is never started. You can then use the + `docker start ` command to start the container at any point. + + This is useful when you want to set up a container configuration ahead of time + so that it is ready to start when you need it. The initial status of the + new container is `created`. + + Please see the [run command](run.md) section and the [Docker run reference](../run.md) for more details. usage: docker container create [OPTIONS] IMAGE [COMMAND] [ARG...] pname: docker container plink: docker_container.yaml @@ -65,6 +76,20 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: cgroupns + value_type: string + description: |- + Cgroup namespace to use (host|private) + 'host': Run the container in the Docker host's cgroup namespace + 'private': Run the container in its own private cgroup namespace + '': Use the cgroup namespace as configured by the + default-cgroupns-mode option on the daemon (default) + deprecated: false + min_api_version: "1.41" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: cidfile value_type: string description: Write the container ID to the file @@ -689,6 +714,15 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: pull + value_type: string + default_value: missing + description: Pull image before creating ("always"|"missing"|"never") + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: read-only value_type: bool default_value: "false" @@ -863,6 +897,114 @@ options: experimentalcli: false kubernetes: false swarm: false +examples: |- + ### Create and start a container + + ```bash + $ docker create -t -i fedora bash + + 6d8af538ec541dd581ebc2a24153a28329acb5268abe5ef868c1f1a261221752 + + $ docker start -a -i 6d8af538ec5 + + bash-4.2# + ``` + + ### Initialize volumes + + As of v1.4.0 container volumes are initialized during the `docker create` phase + (i.e., `docker run` too). For example, this allows you to `create` the `data` + volume container, and then use it from another container: + + ```bash + $ docker create -v /data --name data ubuntu + + 240633dfbb98128fa77473d3d9018f6123b99c454b3251427ae190a7d951ad57 + + $ docker run --rm --volumes-from data ubuntu ls -la /data + + total 8 + drwxr-xr-x 2 root root 4096 Dec 5 04:10 . + drwxr-xr-x 48 root root 4096 Dec 5 04:11 .. + ``` + + Similarly, `create` a host directory bind mounted volume container, which can + then be used from the subsequent container: + + ```bash + $ docker create -v /home/docker:/docker --name docker ubuntu + + 9aa88c08f319cd1e4515c3c46b0de7cc9aa75e878357b1e96f91e2c773029f03 + + $ docker run --rm --volumes-from docker ubuntu ls -la /docker + + total 20 + drwxr-sr-x 5 1000 staff 180 Dec 5 04:00 . + drwxr-xr-x 48 root root 4096 Dec 5 04:13 .. + -rw-rw-r-- 1 1000 staff 3833 Dec 5 04:01 .ash_history + -rw-r--r-- 1 1000 staff 446 Nov 28 11:51 .ashrc + -rw-r--r-- 1 1000 staff 25 Dec 5 04:00 .gitconfig + drwxr-sr-x 3 1000 staff 60 Dec 1 03:28 .local + -rw-r--r-- 1 1000 staff 920 Nov 28 11:51 .profile + drwx--S--- 2 1000 staff 460 Dec 5 00:51 .ssh + drwxr-xr-x 32 1000 staff 1140 Dec 5 04:01 docker + ``` + + + Set storage driver options per container. + + ```bash + $ docker create -it --storage-opt size=120G fedora /bin/bash + ``` + + This (size) will allow to set the container rootfs size to 120G at creation time. + This option is only available for the `devicemapper`, `btrfs`, `overlay2`, + `windowsfilter` and `zfs` graph drivers. + For the `devicemapper`, `btrfs`, `windowsfilter` and `zfs` graph drivers, + user cannot pass a size less than the Default BaseFS Size. + For the `overlay2` storage driver, the size option is only available if the + backing fs is `xfs` and mounted with the `pquota` mount option. + Under these conditions, user can pass any size less than the backing fs size. + + ### 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 if the + daemon is running on Windows server, or `hyperv` if running on Windows client. | + | `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"`. + + ### 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 explicitly added to + the create/run command deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_diff.yaml b/_data/engine-cli/docker_container_diff.yaml index 48c1ccf5d327..d6da6550eee5 100644 --- a/_data/engine-cli/docker_container_diff.yaml +++ b/_data/engine-cli/docker_container_diff.yaml @@ -1,9 +1,46 @@ command: docker container diff short: Inspect changes to files or directories on a container's filesystem -long: Inspect changes to files or directories on a container's filesystem +long: |- + List the changed files and directories in a container᾿s filesystem since the + container was created. Three different types of change are tracked: + + | Symbol | Description | + |--------|---------------------------------| + | `A` | A file or directory was added | + | `D` | A file or directory was deleted | + | `C` | A file or directory was changed | + + You can use the full or shortened container ID or the container name set using + `docker run --name` option. usage: docker container diff CONTAINER pname: docker container plink: docker_container.yaml +examples: |- + Inspect the changes to an `nginx` container: + + ```bash + $ docker diff 1fdfd1f54c1b + + C /dev + C /dev/console + C /dev/core + C /dev/stdout + C /dev/fd + C /dev/ptmx + C /dev/stderr + C /dev/stdin + C /run + A /run/nginx.pid + C /var/lib/nginx/tmp + A /var/lib/nginx/tmp/client_body + A /var/lib/nginx/tmp/fastcgi + A /var/lib/nginx/tmp/proxy + A /var/lib/nginx/tmp/scgi + A /var/lib/nginx/tmp/uwsgi + C /var/log/nginx + A /var/log/nginx/access.log + A /var/log/nginx/error.log + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_exec.yaml b/_data/engine-cli/docker_container_exec.yaml index 7f6a1a5ea0ba..128904a2e43a 100644 --- a/_data/engine-cli/docker_container_exec.yaml +++ b/_data/engine-cli/docker_container_exec.yaml @@ -1,6 +1,19 @@ command: docker container exec short: Run a command in a running container -long: Run a command in a running container +long: |- + The `docker exec` command runs a new command in a running container. + + 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. If 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 container exec [OPTIONS] CONTAINER COMMAND [ARG...] pname: docker container plink: docker_container.yaml @@ -33,6 +46,15 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: env-file + value_type: list + description: Read in a file of environment variables + deprecated: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: interactive shorthand: i value_type: bool @@ -81,6 +103,80 @@ options: experimentalcli: false kubernetes: false swarm: false +examples: |- + ### Run `docker exec` on a running container + + First, start a container. + + ```bash + $ docker run --name ubuntu_bash --rm -i -t ubuntu bash + ``` + + This will create a container named `ubuntu_bash` and start a Bash session. + + Next, execute a command on the container. + + ```bash + $ docker exec -d ubuntu_bash touch /tmp/execWorks + ``` + + This will create a new file `/tmp/execWorks` inside the running container + `ubuntu_bash`, in the background. + + Next, execute an interactive `bash` shell on the container. + + ```bash + $ docker exec -it ubuntu_bash bash + ``` + + This will create a new Bash session in the container `ubuntu_bash`. + + Next, set an environment variable in the current bash session. + + ```bash + $ docker exec -it -e VAR=1 ubuntu_bash bash + ``` + + This will create a new Bash session in the container `ubuntu_bash` with environment + variable `$VAR` set to "1". Note that this environment variable will only be valid + on the current Bash session. + + By default `docker exec` command runs in the same working directory set when container was created. + + ```bash + $ docker exec -it ubuntu_bash pwd + / + ``` + + You can select working directory for the command to execute into + + ```bash + $ docker exec -it -w /root ubuntu_bash pwd + /root + ``` + + + ### Try to run `docker exec` on a paused container + + If the container is paused, then the `docker exec` command will fail with an error: + + ```bash + $ docker pause test + + test + + $ docker ps + + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 1ae3b36715d2 ubuntu:latest "bash" 17 seconds ago Up 16 seconds (Paused) test + + $ docker exec test ls + + FATA[0000] Error response from daemon: Container test is paused, unpause the container before exec + + $ echo $? + 1 + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_export.yaml b/_data/engine-cli/docker_container_export.yaml index e45c77d971bf..79f9574d1016 100644 --- a/_data/engine-cli/docker_container_export.yaml +++ b/_data/engine-cli/docker_container_export.yaml @@ -1,6 +1,13 @@ command: docker container export short: Export a container's filesystem as a tar archive -long: Export a container's filesystem as a tar archive +long: |- + The `docker export` command does not export the contents of volumes associated + with the container. If a volume is mounted on top of an existing directory in + the container, `docker export` will export the contents of the *underlying* + directory, not the contents of the volume. + + Refer to [Backup, restore, or migrate data volumes](https://docs.docker.com/v17.03/engine/tutorials/dockervolumes/#backup-restore-or-migrate-data-volumes) + in the user guide for examples on exporting data in a volume. usage: docker container export [OPTIONS] CONTAINER pname: docker container plink: docker_container.yaml @@ -14,6 +21,16 @@ options: experimentalcli: false kubernetes: false swarm: false +examples: |- + Each of these commands has the same result. + + ```bash + $ docker export red_panda > latest.tar + ``` + + ```bash + $ docker export --output="latest.tar" red_panda + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_kill.yaml b/_data/engine-cli/docker_container_kill.yaml index 44c184add63b..78f7f21e8222 100644 --- a/_data/engine-cli/docker_container_kill.yaml +++ b/_data/engine-cli/docker_container_kill.yaml @@ -1,6 +1,16 @@ command: docker container kill short: Kill one or more running containers -long: Kill one or more running containers +long: |- + The `docker kill` subcommand kills one or more containers. The main process + inside the container is sent `SIGKILL` signal (default), or the signal that is + specified with the `--signal` option. You can kill a container using the + container's ID, ID-prefix, or name. + + > **Note** + > + > `ENTRYPOINT` and `CMD` in the *shell* form run as a child process of + > `/bin/sh -c`, which does not pass signals. This means that the executable is + > not the container’s PID 1 and does not receive Unix signals. usage: docker container kill [OPTIONS] CONTAINER [CONTAINER...] pname: docker container plink: docker_container.yaml @@ -15,6 +25,37 @@ options: experimentalcli: false kubernetes: false swarm: false +examples: |- + ### Send a KILL signal to a container + + The following example sends the default `KILL` signal to the container named + `my_container`: + + ```bash + $ docker kill my_container + ``` + + ### Send a custom signal to a container + + The following example sends a `SIGHUP` signal to the container named + `my_container`: + + ```bash + $ docker kill --signal=SIGHUP my_container + ``` + + + You can specify a custom signal either by _name_, or _number_. The `SIG` prefix + is optional, so the following examples are equivalent: + + ```bash + $ docker kill --signal=SIGHUP my_container + $ docker kill --signal=HUP my_container + $ docker kill --signal=1 my_container + ``` + + Refer to the [`signal(7)`](http://man7.org/linux/man-pages/man7/signal.7.html) + man-page for a list of standard Linux signals. deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_logs.yaml b/_data/engine-cli/docker_container_logs.yaml index 4bfb043e3aea..dac68b162fb6 100644 --- a/_data/engine-cli/docker_container_logs.yaml +++ b/_data/engine-cli/docker_container_logs.yaml @@ -1,6 +1,43 @@ command: docker container logs short: Fetch the logs of a container -long: Fetch the logs of a container +long: |- + The `docker logs` command batch-retrieves logs present at the time of execution. + + > **Note** + > + > This command is only functional for containers that are started with the + > `json-file` or `journald` logging driver. + + For more information about selecting and configuring logging drivers, refer to + [Configure logging drivers](https://docs.docker.com/config/containers/logging/configure/). + + The `docker logs --follow` command will continue streaming the new output from + the container's `STDOUT` and `STDERR`. + + Passing a negative number or a non-integer to `--tail` is invalid and the + value is set to `all` in that case. + + The `docker logs --timestamps` command will add an [RFC3339Nano timestamp](https://golang.org/pkg/time/#pkg-constants) + , for example `2014-09-16T06:17:46.000000000Z`, to each + log entry. To ensure that the timestamps are aligned the + nano-second part of the timestamp will be padded with zero when necessary. + + The `docker logs --details` command will add on extra attributes, such as + environment variables and labels, provided to `--log-opt` when creating the + container. + + The `--since` option shows only the container logs generated after + a given date. You can specify the date as an RFC 3339 date, a UNIX + timestamp, or a Go duration string (e.g. `1m30s`, `3h`). Besides RFC3339 date + format you may also use RFC3339Nano, `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. You can combine the + `--since` option with either or both of the `--follow` or `--tail` options. usage: docker container logs [OPTIONS] CONTAINER pname: docker container plink: docker_container.yaml @@ -27,13 +64,14 @@ options: - option: since value_type: string description: | - Show logs since timestamp (e.g. 2013-01-02T13:23:37) or relative (e.g. 42m for 42 minutes) + Show logs since timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: tail + shorthand: "n" value_type: string default_value: all description: Number of lines to show from the end of the logs @@ -55,13 +93,27 @@ options: - option: until value_type: string description: | - Show logs before a timestamp (e.g. 2013-01-02T13:23:37) or relative (e.g. 42m for 42 minutes) + Show logs before a timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) deprecated: false min_api_version: "1.35" experimental: false experimentalcli: false kubernetes: false swarm: false +examples: |- + ### Retrieve logs until a specific point in time + + In order to retrieve logs before a specific point in time, run: + + ```bash + $ docker run --name test -d busybox sh -c "while true; do $(echo date); sleep 1; done" + $ date + Tue 14 Nov 2017 16:40:00 CET + $ docker logs -f --until=2s test + Tue 14 Nov 2017 16:40:00 CET + Tue 14 Nov 2017 16:40:01 CET + Tue 14 Nov 2017 16:40:02 CET + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_ls.yaml b/_data/engine-cli/docker_container_ls.yaml index 59f445b59adb..3c7bd751c637 100644 --- a/_data/engine-cli/docker_container_ls.yaml +++ b/_data/engine-cli/docker_container_ls.yaml @@ -66,7 +66,7 @@ options: shorthand: q value_type: bool default_value: "false" - description: Only display numeric IDs + description: Only display container IDs deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_pause.yaml b/_data/engine-cli/docker_container_pause.yaml index dd28f672aa2e..c08e6ca6cbd7 100644 --- a/_data/engine-cli/docker_container_pause.yaml +++ b/_data/engine-cli/docker_container_pause.yaml @@ -1,9 +1,23 @@ command: docker container pause short: Pause all processes within one or more containers -long: Pause all processes within one or more containers +long: |- + The `docker pause` command suspends all processes in the specified containers. + On Linux, this uses the freezer cgroup. Traditionally, when suspending a process + the `SIGSTOP` signal is used, which is observable by the process being suspended. + With the freezer cgroup the process is unaware, and unable to capture, + that it is being suspended, and subsequently resumed. On Windows, only Hyper-V + containers can be paused. + + See the + [freezer cgroup documentation](https://www.kernel.org/doc/Documentation/cgroup-v1/freezer-subsystem.txt) + for further details. usage: docker container pause CONTAINER [CONTAINER...] pname: docker container plink: docker_container.yaml +examples: |- + ```bash + $ docker pause my_container + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_port.yaml b/_data/engine-cli/docker_container_port.yaml index e211a449a382..632a34fa9a0a 100644 --- a/_data/engine-cli/docker_container_port.yaml +++ b/_data/engine-cli/docker_container_port.yaml @@ -4,6 +4,35 @@ long: List port mappings or a specific mapping for the container usage: docker container port CONTAINER [PRIVATE_PORT[/PROTO]] pname: docker container plink: docker_container.yaml +examples: |- + ### Show all mapped ports + + You can find out all the ports mapped by not specifying a `PRIVATE_PORT`, or + just a specific mapping: + + ```bash + $ docker ps + + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + b650456536c7 busybox:latest top 54 minutes ago Up 54 minutes 0.0.0.0:1234->9876/tcp, 0.0.0.0:4321->7890/tcp test + + $ docker port test + + 7890/tcp -> 0.0.0.0:4321 + 9876/tcp -> 0.0.0.0:1234 + + $ docker port test 7890/tcp + + 0.0.0.0:4321 + + $ docker port test 7890/udp + + 2014/06/24 11:53:36 Error: No public port '7890/udp' published for test + + $ docker port test 7890 + + 0.0.0.0:4321 + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_rename.yaml b/_data/engine-cli/docker_container_rename.yaml index 088cfe0119db..ae765712b033 100644 --- a/_data/engine-cli/docker_container_rename.yaml +++ b/_data/engine-cli/docker_container_rename.yaml @@ -1,9 +1,13 @@ command: docker container rename short: Rename a container -long: Rename a container +long: The `docker rename` command renames a container. usage: docker container rename CONTAINER NEW_NAME pname: docker container plink: docker_container.yaml +examples: |- + ```bash + $ docker rename my_container my_new_container + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_restart.yaml b/_data/engine-cli/docker_container_restart.yaml index 74d8bbac860b..a96f01905aa1 100644 --- a/_data/engine-cli/docker_container_restart.yaml +++ b/_data/engine-cli/docker_container_restart.yaml @@ -15,6 +15,10 @@ options: experimentalcli: false kubernetes: false swarm: false +examples: |- + ```bash + $ docker restart my_container + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_rm.yaml b/_data/engine-cli/docker_container_rm.yaml index cce60569f697..ff381319716b 100644 --- a/_data/engine-cli/docker_container_rm.yaml +++ b/_data/engine-cli/docker_container_rm.yaml @@ -35,6 +35,75 @@ options: experimentalcli: false kubernetes: false swarm: false +examples: |- + ### Remove a container + + This removes the container referenced under the link `/redis`. + + ```bash + $ docker rm /redis + + /redis + ``` + + ### Remove a link specified with `--link` on the default bridge network + + This removes the underlying link between `/webapp` and the `/redis` + containers on the default bridge network, removing all network communication + between the two containers. This does not apply when `--link` is used with + user-specified networks. + + ```bash + $ docker rm --link /webapp/redis + + /webapp/redis + ``` + + ### Force-remove a running container + + This command force-removes a running container. + + ```bash + $ docker rm --force redis + + redis + ``` + + The main process inside the container referenced under the link `redis` will receive + `SIGKILL`, then the container will be removed. + + ### Remove all stopped containers + + ```bash + $ docker rm $(docker ps -a -q) + ``` + + This command deletes all stopped containers. The command + `docker ps -a -q` above returns all existing container IDs and passes them to + the `rm` command which deletes them. Running containers are not deleted. + + ### Remove a container and its volumes + + ```bash + $ docker rm -v redis + redis + ``` + + This command removes the container and any volumes associated with it. + Note that if a volume was specified with a name, it will not be removed. + + ### Remove a container and selectively remove volumes + + ```bash + $ docker create -v awesome:/foo -v /bar --name hello redis + hello + + $ docker rm -v hello + ``` + + In this example, the volume for `/foo` remains intact, but the volume for + `/bar` is removed. The same behavior holds for volumes inherited with + `--volumes-from`. deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_run.yaml b/_data/engine-cli/docker_container_run.yaml index 87a149bbda95..d3e8e5cd53c4 100644 --- a/_data/engine-cli/docker_container_run.yaml +++ b/_data/engine-cli/docker_container_run.yaml @@ -1,6 +1,17 @@ command: docker container run short: Run a command in a new container -long: Run a command in a new container +long: |- + The `docker run` command first `creates` a writeable container layer over the + specified image, and then `starts` it using the specified command. That is, + `docker run` is equivalent to the API `/containers/create` then + `/containers/(id)/start`. A stopped container can be restarted with all its + previous changes intact using `docker start`. See `docker ps -a` to view a list + of all containers. + + The `docker run` command can be used in combination with `docker commit` to + [*change the command that a container runs*](commit.md). There is additional detailed information about `docker run` in the [Docker run reference](../run.md). + + For information on connecting a container to a network, see the ["*Docker network overview*"](https://docs.docker.com/network/). usage: docker container run [OPTIONS] IMAGE [COMMAND] [ARG...] pname: docker container plink: docker_container.yaml @@ -65,6 +76,20 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: cgroupns + value_type: string + description: |- + Cgroup namespace to use (host|private) + 'host': Run the container in the Docker host's cgroup namespace + 'private': Run the container in its own private cgroup namespace + '': Use the cgroup namespace as configured by the + default-cgroupns-mode option on the daemon (default) + deprecated: false + min_api_version: "1.41" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: cidfile value_type: string description: Write the container ID to the file @@ -707,6 +732,15 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: pull + value_type: string + default_value: missing + description: Pull image before running ("always"|"missing"|"never") + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: read-only value_type: bool default_value: "false" @@ -890,6 +924,718 @@ options: experimentalcli: false kubernetes: false swarm: false +examples: |- + ### Assign name and allocate pseudo-TTY (--name, -it) + + ```bash + $ docker run --name test -it debian + + root@d6c0fe130dba:/# exit 13 + $ echo $? + 13 + $ docker ps -a | grep test + d6c0fe130dba debian:7 "/bin/bash" 26 seconds ago Exited (13) 17 seconds ago test + ``` + + This example runs a container named `test` using the `debian:latest` + image. The `-it` instructs Docker to allocate a pseudo-TTY connected to + the container's stdin; creating an interactive `bash` shell in the container. + In the example, the `bash` shell is quit by entering + `exit 13`. This exit code is passed on to the caller of + `docker run`, and is recorded in the `test` container's metadata. + + ### Capture container ID (--cidfile) + + ```bash + $ docker run --cidfile /tmp/docker_test.cid ubuntu echo "test" + ``` + + This will create a container and print `test` to the console. The `cidfile` + flag makes Docker attempt to create a new file and write the container ID to it. + If the file exists already, Docker will return an error. Docker will close this + file when `docker run` exits. + + ### Full container capabilities (--privileged) + + ```bash + $ docker run -t -i --rm ubuntu bash + root@bc338942ef20:/# mount -t tmpfs none /mnt + mount: permission denied + ``` + + This will *not* work, because by default, most potentially dangerous kernel + capabilities are dropped; including `cap_sys_admin` (which is required to mount + filesystems). However, the `--privileged` flag will allow it to run: + + ```bash + $ docker run -t -i --privileged ubuntu bash + root@50e3f57e16e6:/# mount -t tmpfs none /mnt + root@50e3f57e16e6:/# df -h + Filesystem Size Used Avail Use% Mounted on + none 1.9G 0 1.9G 0% /mnt + ``` + + The `--privileged` flag gives *all* capabilities to the container, and it also + lifts all the limitations enforced by the `device` cgroup controller. In other + words, the container can then do almost everything that the host can do. This + flag exists to allow special use-cases, like running Docker within Docker. + + ### Set working directory (-w) + + ```bash + $ docker run -w /path/to/dir/ -i -t ubuntu pwd + ``` + + The `-w` lets the command being executed inside directory given, here + `/path/to/dir/`. If the path does not exist it is created inside the container. + + ### Set storage driver options per container + + ```bash + $ docker run -it --storage-opt size=120G fedora /bin/bash + ``` + + This (size) will allow to set the container rootfs size to 120G at creation time. + This option is only available for the `devicemapper`, `btrfs`, `overlay2`, + `windowsfilter` and `zfs` graph drivers. + For the `devicemapper`, `btrfs`, `windowsfilter` and `zfs` graph drivers, + user cannot pass a size less than the Default BaseFS Size. + For the `overlay2` storage driver, the size option is only available if the + backing fs is `xfs` and mounted with the `pquota` mount option. + Under these conditions, user can pass any size less than the backing fs size. + + ### Mount tmpfs (--tmpfs) + + ```bash + $ docker run -d --tmpfs /run:rw,noexec,nosuid,size=65536k my_image + ``` + + The `--tmpfs` flag mounts an empty tmpfs into the container with the `rw`, + `noexec`, `nosuid`, `size=65536k` options. + + ### Mount volume (-v, --read-only) + + ```bash + $ docker run -v `pwd`:`pwd` -w `pwd` -i -t ubuntu pwd + ``` + + The `-v` flag mounts the current working directory into the container. The `-w` + lets the command being executed inside the current working directory, by + changing into the directory to the value returned by `pwd`. So this + combination executes the command using the container, but inside the + current working directory. + + ```bash + $ docker run -v /doesnt/exist:/foo -w /foo -i -t ubuntu bash + ``` + + When the host directory of a bind-mounted volume doesn't exist, Docker + will automatically create this directory on the host for you. In the + example above, Docker will create the `/doesnt/exist` + folder before starting your container. + + ```bash + $ docker run --read-only -v /icanwrite busybox touch /icanwrite/here + ``` + + Volumes can be used in combination with `--read-only` to control where + a container writes files. The `--read-only` flag mounts the container's root + filesystem as read only prohibiting writes to locations other than the + specified volumes for the container. + + ```bash + $ docker run -t -i -v /var/run/docker.sock:/var/run/docker.sock -v /path/to/static-docker-binary:/usr/bin/docker busybox sh + ``` + + By bind-mounting the docker unix socket and statically linked docker + binary (refer to [get the linux binary](https://docs.docker.com/engine/install/binaries/#install-static-binaries)), + you give the container the full access to create and manipulate the host's + Docker daemon. + + On Windows, the paths must be specified using Windows-style semantics. + + ```powershell + PS C:\> docker run -v c:\foo:c:\dest microsoft/nanoserver cmd /s /c type c:\dest\somefile.txt + Contents of file + + PS C:\> docker run -v c:\foo:d: microsoft/nanoserver cmd /s /c type d:\somefile.txt + Contents of file + ``` + + The following examples will fail when using Windows-based containers, as the + destination of a volume or bind mount inside the container must be one of: + a non-existing or empty directory; or a drive other than C:. Further, the source + of a bind mount must be a local directory, not a file. + + ```powershell + net use z: \\remotemachine\share + docker run -v z:\foo:c:\dest ... + docker run -v \\uncpath\to\directory:c:\dest ... + docker run -v c:\foo\somefile.txt:c:\dest ... + docker run -v c:\foo:c: ... + docker run -v c:\foo:c:\existing-directory-with-contents ... + ``` + + For in-depth information about volumes, refer to [manage data in containers](https://docs.docker.com/storage/volumes/) + + + ### 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-volumes-or-memory-filesystems). + + 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 + $ docker run -p 127.0.0.1:80:8080/tcp ubuntu bash + ``` + + This binds port `8080` of the container to TCP port `80` on `127.0.0.1` of the host + machine. You can also specify `udp` and `sctp` ports. + The [Docker User Guide](https://docs.docker.com/network/links/) + explains in detail how to manipulate ports in Docker. + + Note that ports which are not bound to the host (i.e., `-p 80:80` instead of + `-p 127.0.0.1:80:80`) will be accessible from the outside. This also applies if + you configured UFW to block this specific port, as Docker manages his + own iptables rules. [Read more](https://docs.docker.com/network/iptables/) + + ```bash + $ docker run --expose 80 ubuntu bash + ``` + + This exposes port `80` of the container without publishing the port to the host + system's interfaces. + + ### Set environment variables (-e, --env, --env-file) + + ```bash + $ docker run -e MYVAR1 --env MYVAR2=foo --env-file ./env.list ubuntu bash + ``` + + 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 + ``` + + You can also use variables that you've exported to your local environment: + + ```bash + export VAR1=value1 + export VAR2=value2 + + $ docker run --env VAR1 --env VAR2 ubuntu env | grep VAR + VAR1=value1 + VAR2=value2 + ``` + + 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. + + 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 + # This is a comment + VAR1=value1 + VAR2=value2 + USER + + $ docker run --env-file env.list ubuntu env | grep VAR + VAR1=value1 + VAR2=value2 + USER=denis + ``` + + ### Set metadata on container (-l, --label, --label-file) + + A label is a `key=value` pair that applies metadata to a container. To label a container with two labels: + + ```bash + $ docker run -l my-label --label com.example.foo=bar ubuntu bash + ``` + + The `my-label` key doesn't specify a value so the label defaults to an empty + string (`""`). To add multiple labels, repeat the label flag (`-l` or `--label`). + + The `key=value` must be unique to avoid overwriting the label value. If you + specify labels with identical keys but different values, each subsequent value + overwrites the previous. Docker uses the last `key=value` you supply. + + Use the `--label-file` flag to load multiple labels from a file. Delimit each + label in the file with an EOL mark. The example below loads labels from a + labels file in the current directory: + + ```bash + $ docker run --label-file ./labels ubuntu bash + ``` + + The label-file format is similar to the format for loading environment + variables. (Unlike environment variables, labels are not visible to processes + running inside a container.) The following example illustrates a label-file + format: + + ```console + com.example.label1="a label" + + # this is a comment + com.example.label2=another\ label + com.example.label3 + ``` + + You can load multiple label-files by supplying multiple `--label-file` flags. + + For additional information on working with labels, see [*Labels - custom + metadata in Docker*](https://docs.docker.com/config/labels-custom-metadata/) in + the Docker User Guide. + + ### Connect a container to a network (--network) + + When you start a container use the `--network` flag to connect it to a network. + This adds the `busybox` container to the `my-net` network. + + ```bash + $ docker run -itd --network=my-net busybox + ``` + + You can also choose the IP addresses for the container with `--ip` and `--ip6` + flags when you start the container on a user-defined network. + + ```bash + $ docker run -itd --network=my-net --ip=10.10.9.75 busybox + ``` + + If you want to add a running container to a network use the `docker network connect` subcommand. + + You can connect multiple containers to the same network. Once connected, the + containers can communicate easily need only another container's IP address + or name. For `overlay` networks or custom plugins that support multi-host + connectivity, containers connected to the same multi-host network but launched + from different Engines can also communicate in this way. + + > **Note** + > + > Service discovery is unavailable on the default bridge network. Containers can + > communicate via their IP addresses by default. To communicate by name, they + > must be linked. + + You can disconnect a container from a network using the `docker network + disconnect` command. + + ### Mount volumes from container (--volumes-from) + + ```bash + $ docker run --volumes-from 777f7dc92da7 --volumes-from ba8c0c54f0f2:ro -i -t ubuntu pwd + ``` + + The `--volumes-from` flag mounts all the defined volumes from the referenced + containers. Containers can be specified by repetitions of the `--volumes-from` + argument. The container ID may be optionally suffixed with `:ro` or `:rw` to + mount the volumes in read-only or read-write mode, respectively. By default, + the volumes are mounted in the same mode (read write or read only) as + the reference container. + + Labeling systems like SELinux require that proper labels are placed on volume + content mounted into a container. Without a label, the security system might + prevent the processes running inside the container from using the content. By + default, Docker does not change the labels set by the OS. + + To change the label in the container context, you can add either of two suffixes + `:z` or `:Z` to the volume mount. These suffixes tell Docker to relabel file + objects on the shared volumes. The `z` option tells Docker that two containers + share the volume content. As a result, Docker labels the content with a shared + content label. Shared volume labels allow all containers to read/write content. + The `Z` option tells Docker to label the content with a private unshared label. + Only the current container can use a private volume. + + ### Attach to STDIN/STDOUT/STDERR (-a) + + The `-a` flag tells `docker run` to bind to the container's `STDIN`, `STDOUT` + or `STDERR`. This makes it possible to manipulate the output and input as + needed. + + ```bash + $ echo "test" | docker run -i -a stdin ubuntu cat - + ``` + + This pipes data into a container and prints the container's ID by attaching + only to the container's `STDIN`. + + ```bash + $ docker run -a stderr ubuntu echo test + ``` + + This isn't going to print anything unless there's an error because we've + only attached to the `STDERR` of the container. The container's logs + still store what's been written to `STDERR` and `STDOUT`. + + ```bash + $ cat somefile | docker run -i -a stdin mybuilder dobuild + ``` + + This is how piping a file into a container could be done for a build. + The container's ID will be printed after the build is done and the build + logs could be retrieved using `docker logs`. This is + useful if you need to pipe a file or something else into a container and + retrieve the container's ID once the container has finished running. + + ### Add host device to container (--device) + + ```bash + $ docker run --device=/dev/sdc:/dev/xvdc \ + --device=/dev/sdd --device=/dev/zero:/dev/nulo \ + -i -t \ + ubuntu ls -l /dev/{xvdc,sdd,nulo} + + brw-rw---- 1 root disk 8, 2 Feb 9 16:05 /dev/xvdc + brw-rw---- 1 root disk 8, 3 Feb 9 16:05 /dev/sdd + crw-rw-rw- 1 root root 1, 5 Feb 9 16:05 /dev/nulo + ``` + + It is often necessary to directly expose devices to a container. The `--device` + option enables that. For example, a specific block storage device or loop + device or audio device can be added to an otherwise unprivileged container + (without the `--privileged` flag) and have the application directly access it. + + By default, the container will be able to `read`, `write` and `mknod` these devices. + This can be overridden using a third `:rwm` set of options to each `--device` + flag. If the container is running in privileged mode, then the permissions specified + will be ignored. + + ```bash + $ docker run --device=/dev/sda:/dev/xvdc --rm -it ubuntu fdisk /dev/xvdc + + Command (m for help): q + $ docker run --device=/dev/sda:/dev/xvdc:r --rm -it ubuntu fdisk /dev/xvdc + You will not be able to write the partition table. + + Command (m for help): q + + $ docker run --device=/dev/sda:/dev/xvdc:rw --rm -it ubuntu fdisk /dev/xvdc + + Command (m for help): q + + $ docker run --device=/dev/sda:/dev/xvdc:m --rm -it ubuntu fdisk /dev/xvdc + fdisk: unable to open /dev/xvdc: Operation not permitted + ``` + + > **Note** + > + > The `--device` option cannot be safely used with ephemeral devices. Block devices + > that may be removed should not be added to untrusted containers with `--device`. + + For Windows, the format of the string passed to the `--device` option is in + the form of `--device=/`. Beginning with Windows Server 2019 + and Windows 10 October 2018 Update, Windows only supports an IdType of + `class` and the Id as a [device interface class + GUID](https://docs.microsoft.com/en-us/windows-hardware/drivers/install/overview-of-device-interface-classes). + Refer to the table defined in the [Windows container + docs](https://docs.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/hardware-devices-in-containers) + for a list of container-supported device interface class GUIDs. + + If this option is specified for a process-isolated Windows container, _all_ + devices that implement the requested device interface class GUID are made + available in the container. For example, the command below makes all COM + ports on the host visible in the container. + + ```powershell + PS C:\> docker run --device=class/86E0D1E0-8089-11D0-9CE4-08003E301F73 mcr.microsoft.com/windows/servercore:ltsc2019 + ``` + + > **Note** + > + > The `--device` option is only supported on process-isolated Windows containers. + > This option fails if the container isolation is `hyperv` or when running Linux + > Containers on Windows (LCOW). + + ### Access an NVIDIA GPU + + The `--gpus­` flag allows you to access NVIDIA GPU resources. First you need to + install [nvidia-container-runtime](https://nvidia.github.io/nvidia-container-runtime/). + Visit [Specify a container's resources](https://docs.docker.com/config/containers/resource_constraints/) + for more information. + + To use `--gpus`, specify which GPUs (or all) to use. If no value is provied, all + available GPUs are used. The example below exposes all available GPUs. + + ```bash + $ docker run -it --rm --gpus all ubuntu nvidia-smi + ``` + + Use the `device` option to specify GPUs. The example below exposes a specific + GPU. + + ```bash + $ docker run -it --rm --gpus device=GPU-3a23c669-1f69-c64e-cf85-44e9b07e7a2a ubuntu nvidia-smi + ``` + + The example below exposes the first and third GPUs. + + ```bash + $ docker run -it --rm --gpus device=0,2 nvidia-smi + ``` + + ### Restart policies (--restart) + + Use Docker's `--restart` to specify a container's *restart policy*. A restart + 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. | + | `on-failure[:max-retries]` | Restart only if the container exits with a non-zero exit status. Optionally, limit the number of restart retries the Docker daemon attempts. | + | `unless-stopped` | Restart the container unless it is explicitly stopped or Docker itself is stopped or restarted. | + | `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 + ``` + + This will run the `redis` container with a restart policy of **always** + so that if the container exits, Docker will restart it. + + More detailed information on restart policies can be found in the + [Restart Policies (--restart)](../run.md#restart-policies---restart) + section of the Docker run reference page. + + ### Add entries to container hosts file (--add-host) + + You can add other hosts into a container's `/etc/hosts` file by using one or + more `--add-host` flags. This example adds a static address for a host named + `docker`: + + ```bash + $ docker run --add-host=docker:10.180.0.1 --rm -it debian + + root@f38c87f2a42d:/# ping docker + PING docker (10.180.0.1): 48 data bytes + 56 bytes from 10.180.0.1: icmp_seq=0 ttl=254 time=7.600 ms + 56 bytes from 10.180.0.1: icmp_seq=1 ttl=254 time=30.705 ms + ^C--- docker ping statistics --- + 2 packets transmitted, 2 packets received, 0% packet loss + round-trip min/avg/max/stddev = 7.600/19.152/30.705/11.553 ms + ``` + + Sometimes you need to connect to the Docker host from within your + container. To enable this, pass the Docker host's IP address to + the container using the `--add-host` flag. To find the host's address, + use the `ip addr show` command. + + The flags you pass to `ip addr show` depend on whether you are + using IPv4 or IPv6 networking in your containers. Use the following + flags for IPv4 address retrieval for a network device named `eth0`: + + ```bash + $ HOSTIP=`ip -4 addr show scope global dev eth0 | grep inet | awk '{print $2}' | cut -d / -f 1 | sed -n 1p` + $ docker run --add-host=docker:${HOSTIP} --rm -it debian + ``` + + For IPv6 use the `-6` flag instead of the `-4` flag. For other network + devices, replace `eth0` with the correct device name (for example `docker0` + for the bridge device). + + ### Set ulimits in container (--ulimit) + + Since setting `ulimit` settings in a container requires extra privileges not + available in the default container, you can set these using the `--ulimit` flag. + `--ulimit` is specified with a soft and hard limit as such: + `=[:]`, for example: + + ```bash + $ docker run --ulimit nofile=1024:1024 --rm debian sh -c "ulimit -n" + 1024 + ``` + + > **Note** + > + > If you do not provide a `hard limit`, the `soft limit` is used + > for both values. If no `ulimits` are set, they are inherited from + > the default `ulimits` set on the daemon. The `as` option is disabled now. + > In other words, the following script is not supported: + > + > ```bash + > $ docker run -it --ulimit as=1024 fedora /bin/bash` + > ``` + + The values are sent to the appropriate `syscall` as they are set. + Docker doesn't perform any byte conversion. Take this into account when setting the values. + + #### For `nproc` usage + + Be careful setting `nproc` with the `ulimit` flag as `nproc` is designed by Linux to set the + maximum number of processes available to a user, not to a container. For example, start four + containers with `daemon` user: + + ```bash + $ docker run -d -u daemon --ulimit nproc=3 busybox top + + $ docker run -d -u daemon --ulimit nproc=3 busybox top + + $ docker run -d -u daemon --ulimit nproc=3 busybox top + + $ docker run -d -u daemon --ulimit nproc=3 busybox top + ``` + + The 4th container fails and reports "[8] System error: resource temporarily unavailable" error. + This fails because the caller set `nproc=3` resulting in the first three containers using up + the three processes quota set for the `daemon` user. + + ### Stop container with signal (--stop-signal) + + The `--stop-signal` flag sets the system call signal that will be sent to the container to exit. + This signal can be a valid unsigned number that matches a position in the kernel's syscall table, for instance 9, + or a signal name in the format SIGNAME, for instance SIGKILL. + + ### Optional security options (--security-opt) + + On Windows, this flag can be used to specify the `credentialspec` option. + The `credentialspec` must be in the format `file://spec.txt` or `registry://keyname`. + + ### Stop container with timeout (--stop-timeout) + + The `--stop-timeout` flag sets the timeout (in seconds) that a pre-defined (see `--stop-signal`) system call + signal that will be sent to the container to exit. After timeout elapses the container will be killed with SIGKILL. + + ### 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. These two commands are equivalent on Linux: + + ```bash + $ docker run -d busybox top + $ docker run -d --isolation default busybox top + ``` + + On Windows, `--isolation` can take one of these values: + + + | 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 older than Windows 10 1809). | + | `hyperv` | Hyper-V hypervisor partition-based isolation. | + + The default isolation on Windows server operating systems is `process`. The default + isolation on Windows client operating systems is `hyperv`. An attempt to start a container on a client + operating system older than Windows 10 1809 with `--isolation process` will fail. + + 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 + ``` + + 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 + ``` + + ### Specify hard limits on memory available to containers (-m, --memory) + + These parameters always set an upper limit on the memory available to the container. On Linux, this + is set on the cgroup and applications in a container can query it at `/sys/fs/cgroup/memory/memory.limit_in_bytes`. + + On Windows, this will affect containers differently depending on what type of isolation is used. + + - With `process` isolation, Windows will report the full memory of the host system, not the limit to applications running inside the container + + ```powershell + PS C:\> docker run -it -m 2GB --isolation=process microsoft/nanoserver powershell Get-ComputerInfo *memory* + + CsTotalPhysicalMemory : 17064509440 + CsPhyicallyInstalledMemory : 16777216 + OsTotalVisibleMemorySize : 16664560 + OsFreePhysicalMemory : 14646720 + OsTotalVirtualMemorySize : 19154928 + OsFreeVirtualMemory : 17197440 + OsInUseVirtualMemory : 1957488 + OsMaxProcessMemorySize : 137438953344 + ``` + + - With `hyperv` isolation, Windows will create a utility VM that is big enough to hold the memory limit, plus the minimal OS needed to host the container. That size is reported as "Total Physical Memory." + + ```powershell + PS C:\> docker run -it -m 2GB --isolation=hyperv microsoft/nanoserver powershell Get-ComputerInfo *memory* + + CsTotalPhysicalMemory : 2683355136 + CsPhyicallyInstalledMemory : + OsTotalVisibleMemorySize : 2620464 + OsFreePhysicalMemory : 2306552 + OsTotalVirtualMemorySize : 2620464 + OsFreeVirtualMemory : 2356692 + OsInUseVirtualMemory : 263772 + OsMaxProcessMemorySize : 137438953344 + ``` + + + ### Configure namespaced kernel parameters (sysctls) at runtime + + The `--sysctl` sets namespaced kernel parameters (sysctls) in the + container. For example, to turn on IP forwarding in the containers + network namespace, run this command: + + ```bash + $ docker run --sysctl net.ipv4.ip_forward=1 someimage + ``` + + > **Note** + > + > Not all sysctls are namespaced. Docker does not support changing sysctls + > inside of a container that also modify the host system. As the kernel + > evolves we expect to see more sysctls become namespaced. + + #### Currently supported sysctls + + IPC Namespace: + + - `kernel.msgmax`, `kernel.msgmnb`, `kernel.msgmni`, `kernel.sem`, + `kernel.shmall`, `kernel.shmmax`, `kernel.shmmni`, `kernel.shm_rmid_forced`. + - Sysctls beginning with `fs.mqueue.*` + - If you use the `--ipc=host` option these sysctls are not allowed. + + Network Namespace: + + - Sysctls beginning with `net.*` + - If you use the `--network=host` option using these sysctls are not allowed. deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_start.yaml b/_data/engine-cli/docker_container_start.yaml index e31d6be262e3..7c520b562e35 100644 --- a/_data/engine-cli/docker_container_start.yaml +++ b/_data/engine-cli/docker_container_start.yaml @@ -51,6 +51,10 @@ options: experimentalcli: false kubernetes: false swarm: false +examples: |- + ```bash + $ docker start my_container + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_stats.yaml b/_data/engine-cli/docker_container_stats.yaml index d8f081e8b5d5..936b9c2ce306 100644 --- a/_data/engine-cli/docker_container_stats.yaml +++ b/_data/engine-cli/docker_container_stats.yaml @@ -1,6 +1,33 @@ command: docker container stats short: Display a live stream of container(s) resource usage statistics -long: Display a live stream of container(s) resource usage statistics +long: |- + The `docker stats` command returns a live data stream for running containers. To + limit data to one or more specific containers, specify a list of container names + or ids separated by a space. You can specify a stopped container but stopped + containers do not return any data. + + If you need more detailed information about a container's resource usage, use + the `/containers/(id)/stats` API endpoint. + + > **Note** + > + > On Linux, the Docker CLI reports memory usage by subtracting cache usage from + > the total memory usage. The API does not perform such a calculation but rather + > provides the total memory usage and the amount from the cache so that clients + > can use the data as needed. The cache usage is defined as the value of + > `total_inactive_file` field in the `memory.stat` file on cgroup v1 hosts. + > + > On Docker 19.03 and older, the cache usage was defined as the value of `cache` + > field. On cgroup v2 hosts, the cache usage is defined as the value of + > `inactive_file` field. + + > **Note** + > + > The `PIDS` column contains the number of processes and kernel threads created + > by that container. Threads is the term used by Linux kernel. Other equivalent + > terms are "lightweight process" or "kernel task", etc. A large number in the + > `PIDS` column combined with a small number of processes (as reported by `ps` + > or `top`) may indicate that something in the container is creating many threads. usage: docker container stats [OPTIONS] [CONTAINER...] pname: docker container plink: docker_container.yaml @@ -41,6 +68,136 @@ options: experimentalcli: false kubernetes: false swarm: false +examples: |- + Running `docker stats` on all running containers against a Linux daemon. + + ```bash + $ docker stats + + CONTAINER ID NAME CPU % MEM USAGE / LIMIT MEM % NET I/O BLOCK I/O PIDS + b95a83497c91 awesome_brattain 0.28% 5.629MiB / 1.952GiB 0.28% 916B / 0B 147kB / 0B 9 + 67b2525d8ad1 foobar 0.00% 1.727MiB / 1.952GiB 0.09% 2.48kB / 0B 4.11MB / 0B 2 + e5c383697914 test-1951.1.kay7x1lh1twk9c0oig50sd5tr 0.00% 196KiB / 1.952GiB 0.01% 71.2kB / 0B 770kB / 0B 1 + 4bda148efbc0 random.1.vnc8on831idyr42slu578u3cr 0.00% 1.672MiB / 1.952GiB 0.08% 110kB / 0B 578kB / 0B 2 + ``` + + If you don't [specify a format string using `--format`](#formatting), the + following columns are shown. + + | Column name | Description | + |---------------------------|-----------------------------------------------------------------------------------------------| + | `CONTAINER ID` and `Name` | the ID and name of the container | + | `CPU %` and `MEM %` | the percentage of the host's CPU and memory the container is using | + | `MEM USAGE / LIMIT` | the total memory the container is using, and the total amount of memory it is allowed to use | + | `NET I/O` | The amount of data the container has sent and received over its network interface | + | `BLOCK I/O` | The amount of data the container has read to and written from block devices on the host | + | `PIDs` | the number of processes or threads the container has created | + + Running `docker stats` on multiple containers by name and id against a Linux daemon. + + ```bash + $ docker stats awesome_brattain 67b2525d8ad1 + + CONTAINER ID NAME CPU % MEM USAGE / LIMIT MEM % NET I/O BLOCK I/O PIDS + b95a83497c91 awesome_brattain 0.28% 5.629MiB / 1.952GiB 0.28% 916B / 0B 147kB / 0B 9 + 67b2525d8ad1 foobar 0.00% 1.727MiB / 1.952GiB 0.09% 2.48kB / 0B 4.11MB / 0B 2 + ``` + + Running `docker stats` with customized format on all (Running and Stopped) containers. + + ```bash + $ docker stats --all --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}" fervent_panini 5acfcb1b4fd1 drunk_visvesvaraya big_heisenberg + + CONTAINER CPU % MEM USAGE / LIMIT + fervent_panini 0.00% 56KiB / 15.57GiB + 5acfcb1b4fd1 0.07% 32.86MiB / 15.57GiB + drunk_visvesvaraya 0.00% 0B / 0B + 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 + PS E:\> docker stats + CONTAINER ID CPU % PRIV WORKING SET NET I/O BLOCK I/O + 09d3bb5b1604 6.61% 38.21 MiB 17.1 kB / 7.73 kB 10.7 MB / 3.57 MB + 9db7aa4d986d 9.19% 38.26 MiB 15.2 kB / 7.65 kB 10.6 MB / 3.3 MB + 3f214c61ad1d 0.00% 28.64 MiB 64 kB / 6.84 kB 4.42 MB / 6.93 MB + ``` + + Running `docker stats` on multiple containers by name and id against a Windows daemon. + + ```powershell + PS E:\> docker ps -a + CONTAINER ID NAME IMAGE COMMAND CREATED STATUS PORTS NAMES + 3f214c61ad1d awesome_brattain nanoserver "cmd" 2 minutes ago Up 2 minutes big_minsky + 9db7aa4d986d mad_wilson windowsservercore "cmd" 2 minutes ago Up 2 minutes mad_wilson + 09d3bb5b1604 fervent_panini windowsservercore "cmd" 2 minutes ago Up 2 minutes affectionate_easley + + PS E:\> docker stats 3f214c61ad1d mad_wilson + CONTAINER ID NAME CPU % PRIV WORKING SET NET I/O BLOCK I/O + 3f214c61ad1d awesome_brattain 0.00% 46.25 MiB 76.3 kB / 7.92 kB 10.3 MB / 14.7 MB + 9db7aa4d986d mad_wilson 9.59% 40.09 MiB 27.6 kB / 8.81 kB 17 MB / 20.1 MB + ``` + + ### Formatting + + The formatting option (`--format`) pretty prints container output + using a Go template. + + Valid placeholders for the Go template are listed below: + + Placeholder | Description + ------------ | -------------------------------------------- + `.Container` | Container name or ID (user input) + `.Name` | Container name + `.ID` | Container ID + `.CPUPerc` | CPU percentage + `.MemUsage` | Memory usage + `.NetIO` | Network IO + `.BlockIO` | Block IO + `.MemPerc` | Memory percentage (Not available on Windows) + `.PIDs` | Number of PIDs (Not available on Windows) + + + When using the `--format` option, the `stats` 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 + `Container` and `CPUPerc` entries separated by a colon (`:`) for all images: + + ```bash + $ docker stats --format "{{.Container}}: {{.CPUPerc}}" + + 09d3bb5b1604: 6.61% + 9db7aa4d986d: 9.19% + 3f214c61ad1d: 0.00% + ``` + + To list all containers statistics with their name, CPU percentage and memory + usage in a table format you can use: + + ```bash + $ docker stats --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}" + + CONTAINER CPU % PRIV WORKING SET + 1285939c1fd3 0.07% 796 KiB / 64 MiB + 9c76f7834ae2 0.07% 2.746 MiB / 64 MiB + d1ea048f04e4 0.03% 4.583 MiB / 64 MiB + ``` + + The default format is as follows: + + On Linux: + + "table {{.ID}}\t{{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.MemPerc}}\t{{.NetIO}}\t{{.BlockIO}}\t{{.PIDs}}" + + On Windows: + + "table {{.ID}}\t{{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.NetIO}}\t{{.BlockIO}}" deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_stop.yaml b/_data/engine-cli/docker_container_stop.yaml index 80fa23dc9904..a753948782de 100644 --- a/_data/engine-cli/docker_container_stop.yaml +++ b/_data/engine-cli/docker_container_stop.yaml @@ -1,6 +1,8 @@ command: docker container stop short: Stop one or more running containers -long: Stop one or more running containers +long: |- + The main process inside the container will receive `SIGTERM`, and after a grace + period, `SIGKILL`. usage: docker container stop [OPTIONS] CONTAINER [CONTAINER...] pname: docker container plink: docker_container.yaml @@ -15,6 +17,10 @@ options: experimentalcli: false kubernetes: false swarm: false +examples: |- + ```bash + $ docker stop my_container + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_unpause.yaml b/_data/engine-cli/docker_container_unpause.yaml index fcd8612ee64c..ab1e27afd3a2 100644 --- a/_data/engine-cli/docker_container_unpause.yaml +++ b/_data/engine-cli/docker_container_unpause.yaml @@ -1,9 +1,20 @@ command: docker container unpause short: Unpause all processes within one or more containers -long: Unpause all processes within one or more containers +long: |- + The `docker unpause` command un-suspends all processes in the specified containers. + On Linux, it does this using the freezer cgroup. + + See the + [freezer cgroup documentation](https://www.kernel.org/doc/Documentation/cgroup-v1/freezer-subsystem.txt) + for further details. usage: docker container unpause CONTAINER [CONTAINER...] pname: docker container plink: docker_container.yaml +examples: |- + ```bash + $ docker unpause my_container + my_container + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_update.yaml b/_data/engine-cli/docker_container_update.yaml index 252ce3126973..5af9566f4cda 100644 --- a/_data/engine-cli/docker_container_update.yaml +++ b/_data/engine-cli/docker_container_update.yaml @@ -1,6 +1,22 @@ command: docker container update short: Update configuration of one or more containers -long: Update configuration of one or more containers +long: |- + The `docker update` command dynamically updates container configuration. + You can use this command to prevent containers from consuming too many + resources from their Docker host. With a single command, you can place + limits on a single container or on many. To specify more than one container, + provide space-separated list of container names or IDs. + + With the exception of the `--kernel-memory` option, you can specify these + options on a running or a stopped container. On kernel version older than + 4.6, you can only update `--kernel-memory` on a stopped container or on + a running container with kernel memory initialized. + + > **Warning** + > + > The `docker update` and `docker container update` commands are not supported + > for Windows containers. + {: .warning } usage: docker container update [OPTIONS] CONTAINER [CONTAINER...] pname: docker container plink: docker_container.yaml @@ -144,6 +160,79 @@ options: experimentalcli: false kubernetes: false swarm: false +examples: |- + The following sections illustrate ways to use this command. + + ### Update a container's cpu-shares + + To limit a container's cpu-shares to 512, first identify the container + name or ID. You can use `docker ps` to find these values. You can also + use the ID returned from the `docker run` command. Then, do the following: + + ```bash + $ docker update --cpu-shares 512 abebf7571666 + ``` + + ### Update a container with cpu-shares and memory + + To update multiple resource configurations for multiple containers: + + ```bash + $ docker update --cpu-shares 512 -m 300M abebf7571666 hopeful_morse + ``` + + ### Update a container's kernel memory constraints + + You can update a container's kernel memory limit using the `--kernel-memory` + option. On kernel version older than 4.6, this option can be updated on a + running container only if the container was started with `--kernel-memory`. + If the container was started *without* `--kernel-memory` you need to stop + the container before updating kernel memory. + + > **Note** + > + > The `--kernel-memory` option has been deprecated since Docker 20.03. + + For example, if you started a container with this command: + + ```bash + $ docker run -dit --name test --kernel-memory 50M ubuntu bash + ``` + + You can update kernel memory while the container is running: + + ```bash + $ docker update --kernel-memory 80M test + ``` + + If you started a container *without* kernel memory initialized: + + ```bash + $ docker run -dit --name test2 --memory 300M ubuntu bash + ``` + + Update kernel memory of running container `test2` will fail. You need to stop + the container before updating the `--kernel-memory` setting. The next time you + start it, the container uses the new value. + + Kernel version newer than (include) 4.6 does not have this limitation, you + can use `--kernel-memory` the same way as other options. + + ### Update a container's restart policy + + You can change a container's restart policy on a running container. The new + restart policy takes effect instantly after you run `docker update` on a + container. + + To update restart policy for one or more containers: + + ```bash + $ docker update --restart=on-failure:3 abebf7571666 hopeful_morse + ``` + + Note that if the container is started with "--rm" flag, you cannot update the restart + policy for it. The `AutoRemove` and `RestartPolicy` are mutually exclusive for the + container. deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_container_wait.yaml b/_data/engine-cli/docker_container_wait.yaml index 9edf8772ba72..024aa6547ae4 100644 --- a/_data/engine-cli/docker_container_wait.yaml +++ b/_data/engine-cli/docker_container_wait.yaml @@ -4,6 +4,34 @@ long: Block until one or more containers stop, then print their exit codes usage: docker container wait CONTAINER [CONTAINER...] pname: docker container plink: docker_container.yaml +examples: |- + Start a container in the background. + + ```bash + $ docker run -dit --name=my_container ubuntu bash + ``` + + Run `docker wait`, which should block until the container exits. + + ```bash + $ docker wait my_container + ``` + + In another terminal, stop the first container. The `docker wait` command above + returns the exit code. + + ```bash + $ docker stop my_container + ``` + + This is the same `docker wait` command from above, but it now exits, returning + `0`. + + ```bash + $ docker wait my_container + + 0 + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_cp.yaml b/_data/engine-cli/docker_cp.yaml index 0c70ef58ee37..7697299246d5 100644 --- a/_data/engine-cli/docker_cp.yaml +++ b/_data/engine-cli/docker_cp.yaml @@ -1,88 +1,12 @@ command: docker cp short: Copy files/folders between a container and the local filesystem long: |- - The `docker cp` utility copies the contents of `SRC_PATH` to the `DEST_PATH`. - You can copy from the container's file system to the local machine or the - reverse, from the local filesystem to the container. If `-` is specified for - either the `SRC_PATH` or `DEST_PATH`, you can also stream a tar archive from - `STDIN` or to `STDOUT`. The `CONTAINER` can be a running or stopped container. - The `SRC_PATH` or `DEST_PATH` can be a file or directory. + Copy files/folders between a container and the local filesystem - The `docker cp` command assumes container paths are relative to the container's - `/` (root) directory. This means supplying the initial forward slash is optional; - The command sees `compassionate_darwin:/tmp/foo/myfile.txt` and - `compassionate_darwin:tmp/foo/myfile.txt` as identical. Local machine paths can - be an absolute or relative value. The command interprets a local machine's - relative paths as relative to the current working directory where `docker cp` is - run. - - The `cp` command behaves like the Unix `cp -a` command in that directories are - copied recursively with permissions preserved if possible. Ownership is set to - the user and primary group at the destination. For example, files copied to a - container are created with `UID:GID` of the root user. Files copied to the local - machine are created with the `UID:GID` of the user which invoked the `docker cp` - command. However, if you specify the `-a` option, `docker cp` sets the ownership - to the user and primary group at the source. - If you specify the `-L` option, `docker cp` follows any symbolic link - in the `SRC_PATH`. `docker cp` does *not* create parent directories for - `DEST_PATH` if they do not exist. - - Assuming a path separator of `/`, a first argument of `SRC_PATH` and second - argument of `DEST_PATH`, the behavior is as follows: - - - `SRC_PATH` specifies a file - - `DEST_PATH` does not exist - - the file is saved to a file created at `DEST_PATH` - - `DEST_PATH` does not exist and ends with `/` - - Error condition: the destination directory must exist. - - `DEST_PATH` exists and is a file - - the destination is overwritten with the source file's contents - - `DEST_PATH` exists and is a directory - - the file is copied into this directory using the basename from - `SRC_PATH` - - `SRC_PATH` specifies a directory - - `DEST_PATH` does not exist - - `DEST_PATH` is created as a directory and the *contents* of the source - directory are copied into this directory - - `DEST_PATH` exists and is a file - - Error condition: cannot copy a directory to a file - - `DEST_PATH` exists and is a directory - - `SRC_PATH` does not end with `/.` (that is: _slash_ followed by _dot_) - - the source directory is copied into this directory - - `SRC_PATH` does end with `/.` (that is: _slash_ followed by _dot_) - - the *content* of the source directory is copied into this - directory - - The command requires `SRC_PATH` and `DEST_PATH` to exist according to the above - rules. If `SRC_PATH` is local and is a symbolic link, the symbolic link, not - the target, is copied by default. To copy the link target and not the link, specify - the `-L` option. - - A colon (`:`) is used as a delimiter between `CONTAINER` and its path. You can - also use `:` when specifying paths to a `SRC_PATH` or `DEST_PATH` on a local - machine, for example `file:name.txt`. If you use a `:` in a local machine path, - you must be explicit with a relative or absolute path, for example: - - `/path/to/file:name.txt` or `./file:name.txt` - - It is not possible to copy certain system files such as resources under - `/proc`, `/sys`, `/dev`, [tmpfs](run.md#mount-tmpfs---tmpfs), and mounts created by - the user in the container. However, you can still copy such files by manually - running `tar` in `docker exec`. Both of the following examples do the same thing - in different ways (consider `SRC_PATH` and `DEST_PATH` are directories): - - ```bash - $ docker exec CONTAINER tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | tar Cxf DEST_PATH - - ``` - - ```bash - $ tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | docker exec -i CONTAINER tar Cxf DEST_PATH - - ``` - - Using `-` as the `SRC_PATH` streams the contents of `STDIN` as a tar archive. - The command extracts the content of the tar to the `DEST_PATH` in container's - filesystem. In this case, `DEST_PATH` must specify a directory. Using `-` as - the `DEST_PATH` streams the contents of the resource as a tar archive to `STDOUT`. + Use '-' as the source to read a tar archive from stdin + and extract it to a directory destination in a container. + Use '-' as the destination to stream a tar archive of a + container source to stdout. usage: "docker cp [OPTIONS] CONTAINER:SRC_PATH DEST_PATH|-\n\tdocker cp [OPTIONS] SRC_PATH|- CONTAINER:DEST_PATH" pname: docker diff --git a/_data/engine-cli/docker_create.yaml b/_data/engine-cli/docker_create.yaml index 5269b80acdfb..a6f8ab88a948 100644 --- a/_data/engine-cli/docker_create.yaml +++ b/_data/engine-cli/docker_create.yaml @@ -1,17 +1,6 @@ command: docker create short: Create a new container -long: |- - The `docker create` command creates a writeable container layer over the - specified image and prepares it for running the specified command. The - container ID is then printed to `STDOUT`. This is similar to `docker run -d` - except the container is never started. You can then use the - `docker start ` command to start the container at any point. - - This is useful when you want to set up a container configuration ahead of time - so that it is ready to start when you need it. The initial status of the - new container is `created`. - - Please see the [run command](run.md) section and the [Docker run reference](../run.md) for more details. +long: Create a new container usage: docker create [OPTIONS] IMAGE [COMMAND] [ARG...] pname: docker plink: docker.yaml @@ -76,6 +65,20 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: cgroupns + value_type: string + description: |- + Cgroup namespace to use (host|private) + 'host': Run the container in the Docker host's cgroup namespace + 'private': Run the container in its own private cgroup namespace + '': Use the cgroup namespace as configured by the + default-cgroupns-mode option on the daemon (default) + deprecated: false + min_api_version: "1.41" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: cidfile value_type: string description: Write the container ID to the file @@ -700,6 +703,15 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: pull + value_type: string + default_value: missing + description: Pull image before creating ("always"|"missing"|"never") + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: read-only value_type: bool default_value: "false" @@ -874,114 +886,6 @@ options: experimentalcli: false kubernetes: false swarm: false -examples: |- - ### Create and start a container - - ```bash - $ docker create -t -i fedora bash - - 6d8af538ec541dd581ebc2a24153a28329acb5268abe5ef868c1f1a261221752 - - $ docker start -a -i 6d8af538ec5 - - bash-4.2# - ``` - - ### Initialize volumes - - As of v1.4.0 container volumes are initialized during the `docker create` phase - (i.e., `docker run` too). For example, this allows you to `create` the `data` - volume container, and then use it from another container: - - ```bash - $ docker create -v /data --name data ubuntu - - 240633dfbb98128fa77473d3d9018f6123b99c454b3251427ae190a7d951ad57 - - $ docker run --rm --volumes-from data ubuntu ls -la /data - - total 8 - drwxr-xr-x 2 root root 4096 Dec 5 04:10 . - drwxr-xr-x 48 root root 4096 Dec 5 04:11 .. - ``` - - Similarly, `create` a host directory bind mounted volume container, which can - then be used from the subsequent container: - - ```bash - $ docker create -v /home/docker:/docker --name docker ubuntu - - 9aa88c08f319cd1e4515c3c46b0de7cc9aa75e878357b1e96f91e2c773029f03 - - $ docker run --rm --volumes-from docker ubuntu ls -la /docker - - total 20 - drwxr-sr-x 5 1000 staff 180 Dec 5 04:00 . - drwxr-xr-x 48 root root 4096 Dec 5 04:13 .. - -rw-rw-r-- 1 1000 staff 3833 Dec 5 04:01 .ash_history - -rw-r--r-- 1 1000 staff 446 Nov 28 11:51 .ashrc - -rw-r--r-- 1 1000 staff 25 Dec 5 04:00 .gitconfig - drwxr-sr-x 3 1000 staff 60 Dec 1 03:28 .local - -rw-r--r-- 1 1000 staff 920 Nov 28 11:51 .profile - drwx--S--- 2 1000 staff 460 Dec 5 00:51 .ssh - drwxr-xr-x 32 1000 staff 1140 Dec 5 04:01 docker - ``` - - - Set storage driver options per container. - - ```bash - $ docker create -it --storage-opt size=120G fedora /bin/bash - ``` - - This (size) will allow to set the container rootfs size to 120G at creation time. - This option is only available for the `devicemapper`, `btrfs`, `overlay2`, - `windowsfilter` and `zfs` graph drivers. - For the `devicemapper`, `btrfs`, `windowsfilter` and `zfs` graph drivers, - user cannot pass a size less than the Default BaseFS Size. - For the `overlay2` storage driver, the size option is only available if the - backing fs is `xfs` and mounted with the `pquota` mount option. - Under these conditions, user can pass any size less than the backing fs size. - - ### 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 if the - daemon is running on Windows server, or `hyperv` if running on Windows client. | - | `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"`. - - ### 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 explicitly added to - the create/run command deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_diff.yaml b/_data/engine-cli/docker_diff.yaml index 4fd4fd4fa0e3..469a0139304f 100644 --- a/_data/engine-cli/docker_diff.yaml +++ b/_data/engine-cli/docker_diff.yaml @@ -1,46 +1,9 @@ command: docker diff short: Inspect changes to files or directories on a container's filesystem -long: |- - List the changed files and directories in a container᾿s filesystem since the - container was created. Three different types of change are tracked: - - | Symbol | Description | - |--------|---------------------------------| - | `A` | A file or directory was added | - | `D` | A file or directory was deleted | - | `C` | A file or directory was changed | - - You can use the full or shortened container ID or the container name set using - `docker run --name` option. +long: Inspect changes to files or directories on a container's filesystem usage: docker diff CONTAINER pname: docker plink: docker.yaml -examples: |- - Inspect the changes to an `nginx` container: - - ```bash - $ docker diff 1fdfd1f54c1b - - C /dev - C /dev/console - C /dev/core - C /dev/stdout - C /dev/fd - C /dev/ptmx - C /dev/stderr - C /dev/stdin - C /run - A /run/nginx.pid - C /var/lib/nginx/tmp - A /var/lib/nginx/tmp/client_body - A /var/lib/nginx/tmp/fastcgi - A /var/lib/nginx/tmp/proxy - A /var/lib/nginx/tmp/scgi - A /var/lib/nginx/tmp/uwsgi - C /var/log/nginx - A /var/log/nginx/access.log - A /var/log/nginx/error.log - ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_events.yaml b/_data/engine-cli/docker_events.yaml index da511c95c646..599aedb4fa18 100644 --- a/_data/engine-cli/docker_events.yaml +++ b/_data/engine-cli/docker_events.yaml @@ -1,184 +1,6 @@ command: docker events short: Get real time events from the server -long: |- - Use `docker events` to get real-time events from the server. These events differ - per Docker object type. Different event types have different scopes. Local - scoped events are only seen on the node they take place on, and swarm scoped - events are seen on all managers. - - Only the last 1000 log events are returned. You can use filters to further limit - the number of events returned. - - ### Object types - - #### Containers - - Docker containers report the following events: - - - `attach` - - `commit` - - `copy` - - `create` - - `destroy` - - `detach` - - `die` - - `exec_create` - - `exec_detach` - - `exec_die` - - `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: - - - `enable` - - `disable` - - `install` - - `remove` - - #### Volumes - - Docker volumes report the following events: - - - `create` - - `destroy` - - `mount` - - `unmount` - - #### Networks - - Docker networks report the following events: - - - `create` - - `connect` - - `destroy` - - `disconnect` - - `remove` - - #### Daemons - - Docker daemons report the following events: - - - `reload` - - #### Services - - Docker services report the following events: - - - `create` - - `remove` - - `update` - - #### Nodes - - Docker nodes report the following events: - - - `create` - - `remove` - - `update` - - #### Secrets - - Docker secrets report the following events: - - - `create` - - `remove` - - `update` - - #### Configs - - Docker configs report the following events: - - - `create` - - `remove` - - `update` - - ### Limiting, filtering, and formatting the output - - #### Limit events by time - - 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. - - Only the last 1000 log events are returned. You can use filters to further limit - the number of events returned. - - #### 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: - - * config (`config=`) - * container (`container=`) - * daemon (`daemon=`) - * event (`event=`) - * image (`image=`) - * label (`label=` or `label==`) - * network (`network=`) - * node (`node=`) - * plugin (`plugin=`) - * scope (`scope=`) - * secret (`secret=`) - * service (`service=`) - * 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/. +long: Get real time events from the server usage: docker events [OPTIONS] pname: docker plink: docker.yaml @@ -216,215 +38,6 @@ options: experimentalcli: false kubernetes: false swarm: false -examples: |- - ### Basic example - - You'll need two shells for this example. - - **Shell 1: Listening for events:** - - ```bash - $ docker 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):** - - ```console - 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 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 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 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 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 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) - - $ docker events --since '2017-01-05T00:35:30' --until '2017-01-05T00:36: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) - ``` - - ### Filter events by criteria - - The following commands show several different ways to filter the `docker event` - output. - - ```bash - $ docker 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 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 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 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 events --filter 'container=test' --filter 'event=stop' - - 2017-01-05T00:46:13.664099505+08:00 container stop a9d1...e130 (image=alpine, name=test) - - $ docker 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 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 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 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 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 events --filter 'type=plugin' - - 2016-07-25T17:30:14.825557616Z plugin pull ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest) - 2016-07-25T17:30:14.888127370Z plugin enable ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest) - - $ docker events -f type=service - - 2017-07-12T06:34:07.999446625Z service create wj64st89fzgchxnhiqpn8p4oj (name=reverent_albattani) - 2017-07-12T06:34:21.405496207Z service remove wj64st89fzgchxnhiqpn8p4oj (name=reverent_albattani) - - $ docker events -f type=node - - 2017-07-12T06:21:51.951586759Z node update 3xyz5ttp1a253q74z1thwywk9 (name=ip-172-31-23-42, state.new=ready, state.old=unknown) - - $ docker events -f type=secret - - 2017-07-12T06:32:13.915704367Z secret create s8o6tmlnndrgzbmdilyy5ymju (name=new_secret) - 2017-07-12T06:32:37.052647783Z secret remove s8o6tmlnndrgzbmdilyy5ymju (name=new_secret) - - $ docker events -f type=config - 2017-07-12T06:44:13.349037127Z config create u96zlvzdfsyb9sg4mhyxfh3rl (name=abc) - 2017-07-12T06:44:36.327694184Z config remove u96zlvzdfsyb9sg4mhyxfh3rl (name=abc) - - $ docker events --filter 'scope=swarm' - - 2017-07-10T07:46:50.250024503Z service create m8qcxu8081woyof7w3jaax6gk (name=affectionate_wilson) - 2017-07-10T07:47:31.093797134Z secret create 6g5pufzsv438p9tbvl9j94od4 (name=new_secret) - ``` - - ### Format the output - - ```bash - $ docker 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 - - ```bash - $ docker 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.. - ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_exec.yaml b/_data/engine-cli/docker_exec.yaml index b845ceb9e703..d081cf87cb1d 100644 --- a/_data/engine-cli/docker_exec.yaml +++ b/_data/engine-cli/docker_exec.yaml @@ -1,19 +1,6 @@ command: docker exec short: Run a command in a running container -long: |- - The `docker exec` command runs a new command in a running container. - - 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. If 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. +long: Run a command in a running container usage: docker exec [OPTIONS] CONTAINER COMMAND [ARG...] pname: docker plink: docker.yaml @@ -46,6 +33,15 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: env-file + value_type: list + description: Read in a file of environment variables + deprecated: false + min_api_version: "1.25" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: interactive shorthand: i value_type: bool @@ -94,80 +90,6 @@ options: experimentalcli: false kubernetes: false swarm: false -examples: |- - ### Run `docker exec` on a running container - - First, start a container. - - ```bash - $ docker run --name ubuntu_bash --rm -i -t ubuntu bash - ``` - - This will create a container named `ubuntu_bash` and start a Bash session. - - Next, execute a command on the container. - - ```bash - $ docker exec -d ubuntu_bash touch /tmp/execWorks - ``` - - This will create a new file `/tmp/execWorks` inside the running container - `ubuntu_bash`, in the background. - - Next, execute an interactive `bash` shell on the container. - - ```bash - $ docker exec -it ubuntu_bash bash - ``` - - This will create a new Bash session in the container `ubuntu_bash`. - - Next, set an environment variable in the current bash session. - - ```bash - $ docker exec -it -e VAR=1 ubuntu_bash bash - ``` - - This will create a new Bash session in the container `ubuntu_bash` with environment - variable `$VAR` set to "1". Note that this environment variable will only be valid - on the current Bash session. - - By default `docker exec` command runs in the same working directory set when container was created. - - ```bash - $ docker exec -it ubuntu_bash pwd - / - ``` - - You can select working directory for the command to execute into - - ```bash - $ docker exec -it -w /root ubuntu_bash pwd - /root - ``` - - - ### Try to run `docker exec` on a paused container - - If the container is paused, then the `docker exec` command will fail with an error: - - ```bash - $ docker pause test - - test - - $ docker ps - - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 1ae3b36715d2 ubuntu:latest "bash" 17 seconds ago Up 16 seconds (Paused) test - - $ docker exec test ls - - FATA[0000] Error response from daemon: Container test is paused, unpause the container before exec - - $ echo $? - 1 - ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_export.yaml b/_data/engine-cli/docker_export.yaml index b75e3d580f9c..86a643f5893e 100644 --- a/_data/engine-cli/docker_export.yaml +++ b/_data/engine-cli/docker_export.yaml @@ -1,13 +1,6 @@ command: docker export short: Export a container's filesystem as a tar archive -long: |- - The `docker export` command does not export the contents of volumes associated - with the container. If a volume is mounted on top of an existing directory in - the container, `docker export` will export the contents of the *underlying* - directory, not the contents of the volume. - - Refer to [Backup, restore, or migrate data volumes](https://docs.docker.com/v17.03/engine/tutorials/dockervolumes/#backup-restore-or-migrate-data-volumes) - in the user guide for examples on exporting data in a volume. +long: Export a container's filesystem as a tar archive usage: docker export [OPTIONS] CONTAINER pname: docker plink: docker.yaml @@ -21,16 +14,6 @@ options: experimentalcli: false kubernetes: false swarm: false -examples: |- - Each of these commands has the same result. - - ```bash - $ docker export red_panda > latest.tar - ``` - - ```bash - $ docker export --output="latest.tar" red_panda - ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_history.yaml b/_data/engine-cli/docker_history.yaml index 13fc6d0ef1bd..6a574e45bf72 100644 --- a/_data/engine-cli/docker_history.yaml +++ b/_data/engine-cli/docker_history.yaml @@ -36,68 +36,12 @@ options: shorthand: q value_type: bool default_value: "false" - description: Only show numeric IDs + description: Only show image IDs deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false -examples: |- - To see how the `docker:latest` image was built: - - ```bash - $ docker history docker - - IMAGE CREATED CREATED BY SIZE COMMENT - 3e23a5875458 8 days ago /bin/sh -c #(nop) ENV LC_ALL=C.UTF-8 0 B - 8578938dd170 8 days ago /bin/sh -c dpkg-reconfigure locales && loc 1.245 MB - be51b77efb42 8 days ago /bin/sh -c apt-get update && apt-get install 338.3 MB - 4b137612be55 6 weeks ago /bin/sh -c #(nop) ADD jessie.tar.xz in / 121 MB - 750d58736b4b 6 weeks ago /bin/sh -c #(nop) MAINTAINER Tianon Gravi : 4 weeks ago - ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_image_build.yaml b/_data/engine-cli/docker_image_build.yaml index 647384bf9c6c..c4b9036f5520 100644 --- a/_data/engine-cli/docker_image_build.yaml +++ b/_data/engine-cli/docker_image_build.yaml @@ -1,6 +1,114 @@ command: docker image build short: Build an image from a Dockerfile -long: Build an image from a Dockerfile +long: |- + The `docker build` command builds Docker images from a Dockerfile and a + "context". A build's context is the set of files located in the specified + `PATH` or `URL`. The build process can refer to any of the files in the + context. For example, your build can use a [*COPY*](../builder.md#copy) + instruction to reference a file in the context. + + The `URL` parameter can refer to three kinds of resources: Git repositories, + pre-packaged tarball contexts and plain text files. + + ### Git repositories + + When the `URL` parameter points to the location of a Git repository, the + 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 + 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, + and 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`: + + ```bash + $ docker build https://github.com/docker/rootfs.git#container:docker + ``` + + The following table represents all the valid suffixes with their build + contexts: + + Build Syntax Suffix | Commit Used | Build Context Used + --------------------------------|-----------------------|------------------- + `myrepo.git` | `refs/heads/master` | `/` + `myrepo.git#mytag` | `refs/tags/mytag` | `/` + `myrepo.git#mybranch` | `refs/heads/mybranch` | `/` + `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` + + > **Note** + > + > You cannot specify the build-context directory (`myfolder` in the examples above) + > when using BuildKit as builder (`DOCKER_BUILDKIT=1`). Support for this feature + > is tracked in [buildkit#1684](https://github.com/moby/buildkit/issues/1684). + + ### Tarball contexts + + If you pass an URL to a remote tarball, the URL itself is sent to the daemon: + + ```bash + $ docker build http://server/context.tar.gz + ``` + + The download operation will be performed on the host the Docker daemon is + running on, which is not necessarily the same host from which the build command + is being issued. The Docker daemon will fetch `context.tar.gz` and use it as the + build context. Tarball contexts must be tar archives conforming to the standard + `tar` UNIX format and can be compressed with any one of the 'xz', 'bzip2', + 'gzip' or 'identity' (no compression) formats. + + ### Text files + + Instead of specifying a context, you can pass a single `Dockerfile` in the + `URL` or pipe the file in via `STDIN`. To pipe a `Dockerfile` from `STDIN`: + + ```bash + $ docker build - < Dockerfile + ``` + + With Powershell on Windows, you can run: + + ```powershell + Get-Content Dockerfile | docker build - + ``` + + If you use `STDIN` or specify a `URL` pointing to a plain text file, the system + places the contents into a file called `Dockerfile`, and any `-f`, `--file` + option is ignored. In this scenario, there is no context. + + By default the `docker build` command will look for a `Dockerfile` at the root + of the build context. The `-f`, `--file`, option lets you specify the path to + an alternative file to use instead. This is useful in cases where the same set + of files are used for multiple builds. The path must be to a file within the + build context. If a relative path is specified then it is interpreted as + relative to the root of the context. + + In most cases, it's best to put each Dockerfile in an empty directory. Then, + add to that directory only the files needed for building the Dockerfile. To + increase the build's performance, you can exclude files and directories by + adding a `.dockerignore` file to that directory as well. For information on + creating one, see the [.dockerignore file](../builder.md#dockerignore-file). + + If the Docker client loses connection to the daemon, the build is canceled. + This happens if you interrupt the Docker client with `CTRL-c` or if the Docker + client is killed for any reason. If the build initiated a pull which is still + running at the time the build is cancelled, the pull is cancelled as well. usage: docker image build [OPTIONS] PATH | URL | - pname: docker image plink: docker_image.yaml @@ -295,8 +403,7 @@ options: default_value: "false" description: Stream attaches to server to negotiate build context deprecated: false - min_api_version: "1.31" - experimental: true + experimental: false experimentalcli: false kubernetes: false swarm: false @@ -326,6 +433,586 @@ options: experimentalcli: false kubernetes: false swarm: false +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 refers 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). + + When using the [BuildKit backend](../builder.md#buildkit), `docker build` searches + for a `.dockerignore` file relative to the Dockerfile name. For example, running + `docker build -f myapp.Dockerfile .` will first look for an ignore file named + `myapp.Dockerfile.dockerignore`. If such a file is not found, the `.dockerignore` + file is used if present. Using a Dockerfile based `.dockerignore` is useful if a + project contains multiple Dockerfiles that expect to ignore different sets of + files. + + + ### 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 + $ curl example.com/remote/Dockerfile | docker build -f - . + ``` + + The above command will use the current directory as the build context and read + a Dockerfile from stdin. + + ```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` returns 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` does 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#specify-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 --build-arg FTP_PROXY=http://40.50.60.5:4567 . + ``` + + 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. You must add `--build-arg` for each build argument. + + 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). + + You may also use the `--build-arg` flag without a value, in which case the value + from the local environment will be propagated into the Docker container being + built: + + ```bash + $ export HTTP_PROXY=http://10.20.30.2:1234 + $ docker build --build-arg HTTP_PROXY . + ``` + + This is similar to how `docker run -e` works. Refer to the [`docker run` documentation](https://docs.docker.com/engine/reference/commandline/run/#set-environment-variables--e---env---env-file) + for more information. + + ### 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"`. + + ### Add entries to container hosts file (--add-host) + + You can add other hosts into a container's `/etc/hosts` file by using one or + more `--add-host` flags. This example adds a static address for a host named + `docker`: + + $ docker build --add-host=docker:10.180.0.1 . + + ### Specifying target build stage (--target) + + When building a Dockerfile with multiple build stages, `--target` can be used to + specify an intermediate build stage by name as a final stage for the resulting + image. Commands after the target stage will be skipped. + + ```dockerfile + FROM debian AS build-env + ... + + FROM alpine AS production-env + ... + ``` + + ```bash + $ docker build -t mybuildimage --target build-env . + ``` + + ### Custom build outputs + + By default, a local container image is created from the build result. The + `--output` (or `-o`) flag allows you to override this behavior, and a specify a + custom exporter. For example, custom exporters allow you to export the build + artifacts as files on the local filesystem instead of a Docker image, which can + be useful for generating local binaries, code generation etc. + + The value for `--output` is a CSV-formatted string defining the exporter type + and options. Currently, `local` and `tar` exporters are supported. The `local` + exporter writes the resulting build files to a directory on the client side. The + `tar` exporter is similar but writes the files as a single tarball (`.tar`). + + If no type is specified, the value defaults to the output directory of the local + exporter. Use a hyphen (`-`) to write the output tarball to standard output + (`STDOUT`). + + The following example builds an image using the current directory (`.`) as build + context, and exports the files to a directory named `out` in the current directory. + If the directory does not exist, Docker creates the directory automatically: + + ```bash + $ docker build -o out . + ``` + + The example above uses the short-hand syntax, omitting the `type` options, and + thus uses the default (`local`) exporter. The example below shows the equivalent + using the long-hand CSV syntax, specifying both `type` and `dest` (destination + path): + + ```bash + $ docker build --output type=local,dest=out . + ``` + + Use the `tar` type to export the files as a `.tar` archive: + + ```bash + $ docker build --output type=tar,dest=out.tar . + ``` + + The example below shows the equivalent when using the short-hand syntax. In this + case, `-` is specified as destination, which automatically selects the `tar` type, + and writes the output tarball to standard output, which is then redirected to + the `out.tar` file: + + ```bash + docker build -o - . > out.tar + ``` + + The `--output` option exports all files from the target stage. A common pattern + for exporting only specific files is to do multi-stage builds and to copy the + desired files to a new scratch stage with [`COPY --from`](../builder.md#copy). + + The example `Dockerfile` below uses a separate stage to collect the + build-artifacts for exporting: + + ```dockerfile + FROM golang AS build-stage + RUN go get -u github.com/LK4D4/vndr + + FROM scratch AS export-stage + COPY --from=build-stage /go/bin/vndr / + ``` + + When building the Dockerfile with the `-o` option, only the files from the final + stage are exported to the `out` directory, in this case, the `vndr` binary: + + ```bash + $ docker build -o out . + + [+] Building 2.3s (7/7) FINISHED + => [internal] load build definition from Dockerfile 0.1s + => => transferring dockerfile: 176B 0.0s + => [internal] load .dockerignore 0.0s + => => transferring context: 2B 0.0s + => [internal] load metadata for docker.io/library/golang:latest 1.6s + => [build-stage 1/2] FROM docker.io/library/golang@sha256:2df96417dca0561bf1027742dcc5b446a18957cd28eba6aa79269f23f1846d3f 0.0s + => => resolve docker.io/library/golang@sha256:2df96417dca0561bf1027742dcc5b446a18957cd28eba6aa79269f23f1846d3f 0.0s + => CACHED [build-stage 2/2] RUN go get -u github.com/LK4D4/vndr 0.0s + => [export-stage 1/1] COPY --from=build-stage /go/bin/vndr / 0.2s + => exporting to client 0.4s + => => copying files 10.30MB 0.3s + + $ ls ./out + vndr + ``` + + > **Note** + > + > This feature requires the BuildKit backend. You can either + > [enable BuildKit](../builder.md#buildkit) or use the [buildx](https://github.com/docker/buildx) + > plugin which provides more output type options. + + ### Specifying external cache sources + + In addition to local build cache, the builder can reuse the cache generated from + previous builds with the `--cache-from` flag pointing to an image in the registry. + + To use an image as a cache source, cache metadata needs to be written into the + image on creation. This can be done by setting `--build-arg BUILDKIT_INLINE_CACHE=1` + when building the image. After that, the built image can be used as a cache source + for subsequent builds. + + Upon importing the cache, the builder will only pull the JSON metadata from the + registry and determine possible cache hits based on that information. If there + is a cache hit, the matched layers are pulled into the local environment. + + In addition to images, the cache can also be pulled from special cache manifests + generated by [`buildx`](https://github.com/docker/buildx) or the BuildKit CLI + (`buildctl`). These manifests (when built with the `type=registry` and `mode=max` + options) allow pulling layer data for intermediate stages in multi-stage builds. + + The following example builds an image with inline-cache metadata and pushes it + to a registry, then uses the image as a cache source on another machine: + + ```bash + $ docker build -t myname/myapp --build-arg BUILDKIT_INLINE_CACHE=1 . + $ docker push myname/myapp + ``` + + After pushing the image, the image is used as cache source on another machine. + BuildKit automatically pulls the image from the registry if needed. + + ```bash + # on another machine + $ docker build --cache-from myname/myapp . + ``` + + > **Note** + > + > This feature requires the BuildKit backend. You can either + > [enable BuildKit](../builder.md#buildkit) or use the [buildx](https://github.com/docker/buildx) + > plugin. The previous builder has limited support for reusing cache from + > pre-pulled images. + + ### Squash an image's layers (--squash) (experimental) + + #### Overview + + 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 squashed layers. This effectively makes it look + like all `Dockerfile` commands were created with a single layer. The build + cache is preserved with this method. + + The `--squash` option is an experimental feature, and should not be considered + stable. + + + Squashing layers can be beneficial if your Dockerfile produces multiple layers + modifying the same files, for example, files that are created in one step, and + removed in another step. For other use-cases, squashing images may actually have + a negative impact on performance; when pulling an image consisting of multiple + layers, layers can be pulled in parallel, and allows sharing layers between + images (saving space). + + For most use cases, multi-stage builds are a better alternative, as they give more + fine-grained control over your build, and can take advantage of future + optimizations in the builder. Refer to the [use multi-stage builds](https://docs.docker.com/develop/develop-images/multistage-build/) + section in the userguide for more information. + + + #### Known limitations + + The `--squash` option has a number of known limitations: + + - When squashing layers, the resulting image cannot take advantage of layer + sharing with other images, and may use significantly more space. Sharing the + base image is still supported. + - When 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. + - While squashing layers may produce smaller images, it may have a negative + impact on performance, as a single layer takes longer to extract, and + downloading a single layer cannot be parallelized. + - When attempting to squash an image that does not make changes to the + filesystem (for example, the Dockerfile only contains `ENV` instructions), + the squash step will fail (see [issue #33823](https://github.com/moby/moby/issues/33823)). + + #### Prerequisites + + The example on this page is using experimental mode in Docker 19.03. + + Experimental mode can be enabled by using the `--experimental` flag when starting + the Docker daemon or setting `experimental: true` in the `daemon.json` configuration + file. + + By default, experimental mode is disabled. To see the current configuration of + the docker daemon, use the `docker version` command and check the `Experimental` + line in the `Engine` section: + + ```console + Client: Docker Engine - Community + Version: 19.03.8 + API version: 1.40 + Go version: go1.12.17 + Git commit: afacb8b + Built: Wed Mar 11 01:21:11 2020 + OS/Arch: darwin/amd64 + Experimental: false + + Server: Docker Engine - Community + Engine: + Version: 19.03.8 + API version: 1.40 (minimum version 1.12) + Go version: go1.12.17 + Git commit: afacb8b + Built: Wed Mar 11 01:29:16 2020 + OS/Arch: linux/amd64 + Experimental: true + [...] + ``` + + To enable experimental mode, users need to restart the docker daemon with the + experimental flag enabled. + + #### Enable Docker experimental + + Experimental features are now included in the standard Docker binaries as of + version 1.13.0. For enabling experimental features, you need to start the + Docker daemon with `--experimental` flag. You can also enable the daemon flag + via `/etc/docker/daemon.json`. e.g. + + ```json + { + "experimental": true + } + ``` + + Then make sure the experimental flag is enabled: + + ```bash + $ docker version -f '{{.Server.Experimental}}' + true + ``` + + #### Build an image with `--squash` argument + + The following is an example of docker build with `--squash` argument + + ```dockerfile + FROM busybox + RUN echo hello > /hello + RUN echo world >> /hello + RUN touch remove_me /remove_me + ENV HELLO=world + RUN rm /remove_me + ``` + + An image named `test` is built with `--squash` argument. + + ```bash + $ docker build --squash -t test . + + [...] + ``` + + If everything is right, the history looks like this: + + ```bash + $ docker history test + + IMAGE CREATED CREATED BY SIZE COMMENT + 4e10cb5b4cac 3 seconds ago 12 B merge sha256:88a7b0112a41826885df0e7072698006ee8f621c6ab99fca7fe9151d7b599702 to sha256:47bcc53f74dc94b1920f0b34f6036096526296767650f223433fe65c35f149eb + 5 minutes ago /bin/sh -c rm /remove_me 0 B + 5 minutes ago /bin/sh -c #(nop) ENV HELLO=world 0 B + 5 minutes ago /bin/sh -c touch remove_me /remove_me 0 B + 5 minutes ago /bin/sh -c echo world >> /hello 0 B + 6 minutes ago /bin/sh -c echo hello > /hello 0 B + 7 weeks ago /bin/sh -c #(nop) CMD ["sh"] 0 B + 7 weeks ago /bin/sh -c #(nop) ADD file:47ca6e777c36a4cfff 1.113 MB + ``` + + We could find that a layer's name is ``, and there is a new layer with + COMMENT `merge`. + + Test the image, check for `/remove_me` being gone, make sure `hello\nworld` is + in `/hello`, make sure the `HELLO` environment variable's value is `world`. deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_image_history.yaml b/_data/engine-cli/docker_image_history.yaml index 265accf0968a..e2a25beb51e1 100644 --- a/_data/engine-cli/docker_image_history.yaml +++ b/_data/engine-cli/docker_image_history.yaml @@ -36,12 +36,68 @@ options: shorthand: q value_type: bool default_value: "false" - description: Only show numeric IDs + description: Only show image IDs deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false +examples: |- + To see how the `docker:latest` image was built: + + ```bash + $ docker history docker + + IMAGE CREATED CREATED BY SIZE COMMENT + 3e23a5875458 8 days ago /bin/sh -c #(nop) ENV LC_ALL=C.UTF-8 0 B + 8578938dd170 8 days ago /bin/sh -c dpkg-reconfigure locales && loc 1.245 MB + be51b77efb42 8 days ago /bin/sh -c apt-get update && apt-get install 338.3 MB + 4b137612be55 6 weeks ago /bin/sh -c #(nop) ADD jessie.tar.xz in / 121 MB + 750d58736b4b 6 weeks ago /bin/sh -c #(nop) MAINTAINER Tianon Gravi : 4 weeks ago + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_image_import.yaml b/_data/engine-cli/docker_image_import.yaml index b2a66563960b..3c40450ae127 100644 --- a/_data/engine-cli/docker_image_import.yaml +++ b/_data/engine-cli/docker_image_import.yaml @@ -1,6 +1,18 @@ command: docker image import short: Import the contents from a tarball to create a filesystem image -long: Import the contents from a tarball to create a filesystem image +long: |- + You can specify a `URL` or `-` (dash) to take data directly from `STDIN`. The + `URL` can point to an archive (.tar, .tar.gz, .tgz, .bzip, .tar.xz, or .txz) + containing a filesystem or to an individual file on the Docker host. If you + specify an archive, Docker untars it in the container relative to the `/` + (root). If you specify an individual file, you must specify the full path within + the host. To import from a remote location, specify a `URI` that begins with the + `http://` or `https://` protocol. + + The `--change` option will apply `Dockerfile` instructions to the image + that is created. + Supported `Dockerfile` instructions: + `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` usage: docker image import [OPTIONS] file|URL|- [REPOSITORY[:TAG]] pname: docker image plink: docker_image.yaml @@ -32,6 +44,51 @@ options: experimentalcli: false kubernetes: false swarm: false +examples: |- + ### Import from a remote location + + This will create a new untagged image. + + ```bash + $ docker import http://example.com/exampleimage.tgz + ``` + + ### Import from a local file + + - Import to docker via pipe and `STDIN`. + + ```bash + $ cat exampleimage.tgz | docker import - exampleimagelocal:new + ``` + + - Import with a commit message. + + ```bash + $ cat exampleimage.tgz | docker import --message "New image imported from tarball" - exampleimagelocal:new + ``` + + - Import to docker from a local archive. + + ```bash + $ docker import /path/to/exampleimage.tgz + ``` + + ### Import from a local directory + + ```bash + $ sudo tar -c . | docker import - exampleimagedir + ``` + + ### Import from a local directory with new configurations + + ```bash + $ sudo tar -c . | docker import --change "ENV DEBUG=true" - exampleimagedir + ``` + + Note the `sudo` in this example – you must preserve + the ownership of the files (especially root ownership) during the + archiving with tar. If you are not root (or the sudo command) when you + tar, then the ownerships might not get preserved. deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_image_load.yaml b/_data/engine-cli/docker_image_load.yaml index 61d47dab9bfd..82eb7be00808 100644 --- a/_data/engine-cli/docker_image_load.yaml +++ b/_data/engine-cli/docker_image_load.yaml @@ -1,6 +1,8 @@ command: docker image load short: Load an image from a tar archive or STDIN -long: Load an image from a tar archive or STDIN +long: |- + Load an image or repository from a tar archive (even if compressed with gzip, + bzip2, or xz) from a file or STDIN. It restores both images and tags. usage: docker image load [OPTIONS] pname: docker image plink: docker_image.yaml @@ -24,6 +26,34 @@ options: experimentalcli: false kubernetes: false swarm: false +examples: |- + ```bash + $ docker image ls + + REPOSITORY TAG IMAGE ID CREATED SIZE + + $ docker load < busybox.tar.gz + + Loaded image: busybox:latest + $ docker images + REPOSITORY TAG IMAGE ID CREATED SIZE + busybox latest 769b9341d937 7 weeks ago 2.489 MB + + $ docker load --input fedora.tar + + Loaded image: fedora:rawhide + + Loaded image: fedora:20 + + $ docker images + + REPOSITORY TAG IMAGE ID CREATED SIZE + busybox latest 769b9341d937 7 weeks ago 2.489 MB + fedora rawhide 0d20aec6529d 7 weeks ago 387 MB + fedora 20 58394af37342 7 weeks ago 385.5 MB + fedora heisenbug 58394af37342 7 weeks ago 385.5 MB + fedora latest 58394af37342 7 weeks ago 385.5 MB + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_image_ls.yaml b/_data/engine-cli/docker_image_ls.yaml index 0e341e81fae0..6180769565e8 100644 --- a/_data/engine-cli/docker_image_ls.yaml +++ b/_data/engine-cli/docker_image_ls.yaml @@ -1,7 +1,22 @@ command: docker image ls -aliases: images, list +aliases: list short: List images -long: List images +long: |- + The default `docker images` will show all top level + images, their repository and tags, and their size. + + Docker images have intermediate layers that increase reusability, + decrease disk usage, and speed up `docker build` by + allowing each step to be cached. These intermediate layers are not shown + by default. + + The `SIZE` is the cumulative space taken up by the image and all + its parent images. This is also the disk space used by the contents of the + Tar file created when you `docker save` an image. + + An image will be listed more than once if it has multiple repository names + or tags. This single image (identifiable by its matching `IMAGE ID`) + uses up the `SIZE` listed only once. usage: docker image ls [OPTIONS] [REPOSITORY[:TAG]] pname: docker image plink: docker_image.yaml @@ -55,12 +70,308 @@ options: shorthand: q value_type: bool default_value: "false" - description: Only show numeric IDs + description: Only show image IDs deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false +examples: |- + ### List the most recently created images + + ```bash + $ docker images + + REPOSITORY TAG IMAGE ID CREATED SIZE + 77af4d6b9913 19 hours ago 1.089 GB + committ latest b6fa739cedf5 19 hours ago 1.089 GB + 78a85c484f71 19 hours ago 1.089 GB + docker latest 30557a29d5ab 20 hours ago 1.089 GB + 5ed6274db6ce 24 hours ago 1.089 GB + postgres 9 746b819f315e 4 days ago 213.4 MB + postgres 9.3 746b819f315e 4 days ago 213.4 MB + postgres 9.3.5 746b819f315e 4 days ago 213.4 MB + postgres latest 746b819f315e 4 days ago 213.4 MB + ``` + + ### List images by name and tag + + The `docker images` command takes an optional `[REPOSITORY[:TAG]]` argument + that restricts the list to images that match the argument. If you specify + `REPOSITORY`but no `TAG`, the `docker images` command lists all images in the + given repository. + + For example, to list all images in the "java" repository, run this command : + + ```bash + $ docker images java + + REPOSITORY TAG IMAGE ID CREATED SIZE + java 8 308e519aac60 6 days ago 824.5 MB + java 7 493d82594c15 3 months ago 656.3 MB + java latest 2711b1d6f3aa 5 months ago 603.9 MB + ``` + + The `[REPOSITORY[:TAG]]` value must be an "exact match". This means that, for example, + `docker images jav` does not match the image `java`. + + If both `REPOSITORY` and `TAG` are provided, only images matching that + repository and tag are listed. To find all local images in the "java" + repository with tag "8" you can use: + + ```bash + $ docker images java:8 + + REPOSITORY TAG IMAGE ID CREATED SIZE + java 8 308e519aac60 6 days ago 824.5 MB + ``` + + If nothing matches `REPOSITORY[:TAG]`, the list is empty. + + ```bash + $ docker images java:0 + + REPOSITORY TAG IMAGE ID CREATED SIZE + ``` + + ### List the full length image IDs + + ```bash + $ docker images --no-trunc + + REPOSITORY TAG IMAGE ID CREATED SIZE + sha256:77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182 19 hours ago 1.089 GB + committest latest sha256:b6fa739cedf5ea12a620a439402b6004d057da800f91c7524b5086a5e4749c9f 19 hours ago 1.089 GB + sha256:78a85c484f71509adeaace20e72e941f6bdd2b25b4c75da8693efd9f61a37921 19 hours ago 1.089 GB + docker latest sha256:30557a29d5abc51e5f1d5b472e79b7e296f595abcf19fe6b9199dbbc809c6ff4 20 hours ago 1.089 GB + sha256:0124422dd9f9cf7ef15c0617cda3931ee68346455441d66ab8bdc5b05e9fdce5 20 hours ago 1.089 GB + sha256:18ad6fad340262ac2a636efd98a6d1f0ea775ae3d45240d3418466495a19a81b 22 hours ago 1.082 GB + sha256:f9f1e26352f0a3ba6a0ff68167559f64f3e21ff7ada60366e2d44a04befd1d3a 23 hours ago 1.089 GB + tryout latest sha256:2629d1fa0b81b222fca63371ca16cbf6a0772d07759ff80e8d1369b926940074 23 hours ago 131.5 MB + sha256:5ed6274db6ceb2397844896966ea239290555e74ef307030ebb01ff91b1914df 24 hours ago 1.089 GB + ``` + + ### List image digests + + Images that use the v2 or later format have a content-addressable identifier + called a `digest`. As long as the input used to generate the image is + unchanged, the digest value is predictable. To list image digest values, use + the `--digests` flag: + + ```bash + $ docker images --digests + REPOSITORY TAG DIGEST IMAGE ID CREATED SIZE + localhost:5000/test/busybox sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf 4986bf8c1536 9 weeks ago 2.43 MB + ``` + + When pushing or pulling to a 2.0 registry, the `push` or `pull` command + output includes the image digest. You can `pull` using a digest value. You can + also reference by digest in `create`, `run`, and `rmi` commands, as well as the + `FROM` image reference in a Dockerfile. + + ### 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: + + * dangling (boolean - true or false) + * label (`label=` or `label==`) + * before (`[:]`, `` or ``) - filter images created before given id or references + * since (`[:]`, `` or ``) - filter images created since given id or references + * reference (pattern of an image reference) - filter images whose reference matches the specified pattern + + #### Show untagged images (dangling) + + ```bash + $ docker images --filter "dangling=true" + + REPOSITORY TAG IMAGE ID CREATED SIZE + 8abc22fbb042 4 weeks ago 0 B + 48e5f45168b9 4 weeks ago 2.489 MB + bf747efa0e2f 4 weeks ago 0 B + 980fe10e5736 12 weeks ago 101.4 MB + dea752e4e117 12 weeks ago 101.4 MB + 511136ea3c5a 8 months ago 0 B + ``` + + This will display untagged images that are the leaves of the images tree (not + intermediary layers). These images occur when a new build of an image takes the + `repo:tag` away from the image ID, leaving it as `:` or untagged. + A warning will be issued if trying to remove an image when a container is presently + using it. By having this flag it allows for batch cleanup. + + You can use this in conjunction with `docker rmi ...`: + + ```bash + $ docker rmi $(docker images -f "dangling=true" -q) + + 8abc22fbb042 + 48e5f45168b9 + bf747efa0e2f + 980fe10e5736 + dea752e4e117 + 511136ea3c5a + ``` + + Docker warns you if any containers exist that are using these untagged images. + + + #### Show images with a given label + + The `label` filter matches images based on the presence of a `label` alone or a `label` and a + value. + + The following filter matches images with the `com.example.version` label regardless of its value. + + ```bash + $ docker images --filter "label=com.example.version" + + REPOSITORY TAG IMAGE ID CREATED SIZE + match-me-1 latest eeae25ada2aa About a minute ago 188.3 MB + match-me-2 latest dea752e4e117 About a minute ago 188.3 MB + ``` + + The following filter matches images with the `com.example.version` label with the `1.0` value. + + ```bash + $ docker images --filter "label=com.example.version=1.0" + + REPOSITORY TAG IMAGE ID CREATED SIZE + match-me latest 511136ea3c5a About a minute ago 188.3 MB + ``` + + In this example, with the `0.1` value, it returns an empty set because no matches were found. + + ```bash + $ docker images --filter "label=com.example.version=0.1" + REPOSITORY TAG IMAGE ID CREATED SIZE + ``` + + #### Filter images by time + + The `before` filter shows only images created before the image with + given id or reference. For example, having these images: + + ```bash + $ docker images + + REPOSITORY TAG IMAGE ID CREATED SIZE + image1 latest eeae25ada2aa 4 minutes ago 188.3 MB + image2 latest dea752e4e117 9 minutes ago 188.3 MB + image3 latest 511136ea3c5a 25 minutes ago 188.3 MB + ``` + + Filtering with `before` would give: + + ```bash + $ docker images --filter "before=image1" + + REPOSITORY TAG IMAGE ID CREATED SIZE + image2 latest dea752e4e117 9 minutes ago 188.3 MB + image3 latest 511136ea3c5a 25 minutes ago 188.3 MB + ``` + + Filtering with `since` would give: + + ```bash + $ docker images --filter "since=image3" + REPOSITORY TAG IMAGE ID CREATED SIZE + image1 latest eeae25ada2aa 4 minutes ago 188.3 MB + image2 latest dea752e4e117 9 minutes ago 188.3 MB + ``` + + #### Filter images by reference + + The `reference` filter shows only images whose reference matches + the specified pattern. + + ```bash + $ 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 + ``` + + 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 + ``` + + Filtering with multiple `reference` would give, either match A or B: + + ```bash + $ docker images --filter=reference='busy*:uclibc' --filter=reference='busy*:glibc' + + 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 + + The formatting option (`--format`) will pretty print container output + using a Go template. + + Valid placeholders for the Go template are listed below: + + | Placeholder | Description| + | ---- | ---- | + | `.ID` | Image ID | + | `.Repository` | Image repository | + | `.Tag` | Image tag | + | `.Digest` | Image digest | + | `.CreatedSince` | Elapsed time since the image was created | + | `.CreatedAt` | Time when the image was created | + | `.Size` | Image disk size | + + When using the `--format` option, the `image` 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 `Repository` entries separated by a colon (`:`) for all images: + + ```bash + $ docker images --format "{{.ID}}: {{.Repository}}" + + 77af4d6b9913: + b6fa739cedf5: committ + 78a85c484f71: + 30557a29d5ab: docker + 5ed6274db6ce: + 746b819f315e: postgres + 746b819f315e: postgres + 746b819f315e: postgres + 746b819f315e: postgres + ``` + + To list all images with their repository and tag in a table format you + can use: + + ```bash + $ docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}" + + IMAGE ID REPOSITORY TAG + 77af4d6b9913 + b6fa739cedf5 committ latest + 78a85c484f71 + 30557a29d5ab docker latest + 5ed6274db6ce + 746b819f315e postgres 9 + 746b819f315e postgres 9.3 + 746b819f315e postgres 9.3.5 + 746b819f315e postgres latest + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_image_pull.yaml b/_data/engine-cli/docker_image_pull.yaml index 8e8b67509779..099bcf4a222c 100644 --- a/_data/engine-cli/docker_image_pull.yaml +++ b/_data/engine-cli/docker_image_pull.yaml @@ -1,6 +1,30 @@ command: docker image pull short: Pull an image or a repository from a registry -long: Pull an image or a repository from a registry +long: |- + Most of your images will be created on top of a base image from the + [Docker Hub](https://hub.docker.com) registry. + + [Docker Hub](https://hub.docker.com) contains many pre-built images that you + can `pull` and try without needing to define and configure your own. + + To download a particular image, or set of images (i.e., a repository), + use `docker pull`. + + ### Proxy configuration + + If you are behind an HTTP proxy server, for example in corporate settings, + before open a connect to registry, you may need to configure the Docker + daemon's proxy settings, using the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` + environment variables. To set these environment variables on a host using + `systemd`, refer to the [control and configure Docker with systemd](https://docs.docker.com/config/daemon/systemd/#httphttps-proxy) + for variables configuration. + + ### Concurrent downloads + + By default the Docker daemon will pull three layers of an image at a time. + If you are on a low bandwidth connection this may cause timeout issues and you may want to lower + this via the `--max-concurrent-downloads` daemon option. See the + [daemon documentation](dockerd.md) for more details. usage: docker image pull [OPTIONS] NAME[:TAG|@DIGEST] pname: docker image plink: docker_image.yaml @@ -43,6 +67,208 @@ options: experimentalcli: false kubernetes: false swarm: false +examples: |- + ### Pull an image from Docker Hub + + To download a particular image, or set of images (i.e., a repository), use + `docker pull`. If no tag is provided, Docker Engine uses the `:latest` tag as a + default. This command pulls the `debian:latest` image: + + ```bash + $ docker pull debian + + Using default tag: latest + latest: Pulling from library/debian + fdd5d7827f33: Pull complete + a3ed95caeb02: Pull complete + Digest: sha256:e7d38b3517548a1c71e41bffe9c8ae6d6d29546ce46bf62159837aad072c90aa + Status: Downloaded newer image for debian:latest + ``` + + Docker images can consist of multiple layers. In the example above, the image + consists of two layers; `fdd5d7827f33` and `a3ed95caeb02`. + + Layers can be reused by images. For example, the `debian:jessie` image shares + both layers with `debian:latest`. Pulling the `debian:jessie` image therefore + only pulls its metadata, but not its layers, because all layers are already + present locally: + + ```bash + $ docker pull debian:jessie + + jessie: Pulling from library/debian + fdd5d7827f33: Already exists + a3ed95caeb02: Already exists + Digest: sha256:a9c958be96d7d40df920e7041608f2f017af81800ca5ad23e327bc402626b58e + Status: Downloaded newer image for debian:jessie + ``` + + To see which images are present locally, use the [`docker images`](images.md) + command: + + ```bash + $ docker images + + REPOSITORY TAG IMAGE ID CREATED SIZE + debian jessie f50f9524513f 5 days ago 125.1 MB + debian latest f50f9524513f 5 days ago 125.1 MB + ``` + + Docker uses a content-addressable image store, and the image ID is a SHA256 + digest covering the image's configuration and layers. In the example above, + `debian:jessie` and `debian:latest` have the same image ID because they are + actually the *same* image tagged with different names. Because they are the + same image, their layers are stored only once and do not consume extra disk + space. + + For more information about images, layers, and the content-addressable store, + refer to [understand images, containers, and storage drivers](https://docs.docker.com/storage/storagedriver/). + + + ### Pull an image by digest (immutable identifier) + + So far, you've pulled images by their name (and "tag"). Using names and tags is + a convenient way to work with images. When using tags, you can `docker pull` an + image again to make sure you have the most up-to-date version of that image. + For example, `docker pull ubuntu:14.04` pulls the latest version of the Ubuntu + 14.04 image. + + In some cases you don't want images to be updated to newer versions, but prefer + to use a fixed version of an image. Docker enables you to pull an image by its + *digest*. When pulling an image by digest, you specify *exactly* which version + of an image to pull. Doing so, allows you to "pin" an image to that version, + and guarantee that the image you're using is always the same. + + To know the digest of an image, pull the image first. Let's pull the latest + `ubuntu:14.04` image from Docker Hub: + + ```bash + $ docker pull ubuntu:14.04 + + 14.04: Pulling from library/ubuntu + 5a132a7e7af1: Pull complete + fd2731e4c50c: Pull complete + 28a2f68d1120: Pull complete + a3ed95caeb02: Pull complete + Digest: sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 + Status: Downloaded newer image for ubuntu:14.04 + ``` + + Docker prints the digest of the image after the pull has finished. In the example + above, the digest of the image is: + + sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 + + Docker also prints the digest of an image when *pushing* to a registry. This + may be useful if you want to pin to a version of the image you just pushed. + + A digest takes the place of the tag when pulling an image, for example, to + pull the above image by digest, run the following command: + + ```bash + $ docker pull ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 + + sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2: Pulling from library/ubuntu + 5a132a7e7af1: Already exists + fd2731e4c50c: Already exists + 28a2f68d1120: Already exists + a3ed95caeb02: Already exists + Digest: sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 + Status: Downloaded newer image for ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 + ``` + + Digest can also be used in the `FROM` of a Dockerfile, for example: + + ```dockerfile + FROM ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 + MAINTAINER some maintainer + ``` + + > **Note** + > + > Using this feature "pins" an image to a specific version in time. + > Docker will therefore not pull updated versions of an image, which may include + > security updates. If you want to pull an updated image, you need to change the + > digest accordingly. + + + ### Pull from a different registry + + By default, `docker pull` pulls images from [Docker Hub](https://hub.docker.com). It is also possible to + manually specify the path of a registry to pull from. For example, if you have + set up a local registry, you can specify its path to pull from it. A registry + path is similar to a URL, but does not contain a protocol specifier (`https://`). + + The following command pulls the `testing/test-image` image from a local registry + listening on port 5000 (`myregistry.local:5000`): + + ```bash + $ docker pull myregistry.local:5000/testing/test-image + ``` + + Registry credentials are managed by [docker login](login.md). + + Docker uses the `https://` protocol to communicate with a registry, unless the + registry is allowed to be accessed over an insecure connection. Refer to the + [insecure registries](dockerd.md#insecure-registries) section for more information. + + + ### Pull a repository with multiple images + + By default, `docker pull` pulls a *single* image from the registry. A repository + can contain multiple images. To pull all images from a repository, provide the + `-a` (or `--all-tags`) option when using `docker pull`. + + This command pulls all images from the `fedora` repository: + + ```bash + $ docker pull --all-tags fedora + + Pulling repository fedora + ad57ef8d78d7: Download complete + 105182bb5e8b: Download complete + 511136ea3c5a: Download complete + 73bd853d2ea5: Download complete + .... + + Status: Downloaded newer image for fedora + ``` + + After the pull has completed use the `docker images` command to see the + images that were pulled. The example below shows all the `fedora` images + that are present locally: + + ```bash + $ docker images fedora + + REPOSITORY TAG IMAGE ID CREATED SIZE + fedora rawhide ad57ef8d78d7 5 days ago 359.3 MB + fedora 20 105182bb5e8b 5 days ago 372.7 MB + fedora heisenbug 105182bb5e8b 5 days ago 372.7 MB + fedora latest 105182bb5e8b 5 days ago 372.7 MB + ``` + + ### Cancel a pull + + Killing the `docker pull` process, for example by pressing `CTRL-c` while it is + running in a terminal, will terminate the pull operation. + + ```bash + $ docker pull fedora + + Using default tag: latest + latest: Pulling from library/fedora + a3ed95caeb02: Pulling fs layer + 236608c7b546: Pulling fs layer + ^C + ``` + + > **Note** + > + > The Engine terminates a pull operation when the connection between the Docker + > Engine daemon and the Docker Engine client initiating the pull is lost. If the + > connection with the Engine daemon is lost for other reasons than a manual + > interaction, the pull is also aborted. deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_image_push.yaml b/_data/engine-cli/docker_image_push.yaml index b4f5f22b86e5..d164f612fe26 100644 --- a/_data/engine-cli/docker_image_push.yaml +++ b/_data/engine-cli/docker_image_push.yaml @@ -1,10 +1,41 @@ command: docker image push short: Push an image or a repository to a registry -long: Push an image or a repository to a registry +long: |- + Use `docker image push` to share your images to the [Docker Hub](https://hub.docker.com) + registry or to a self-hosted one. + + Refer to the [`docker image tag`](tag.md) reference for more information about valid + image and tag names. + + Killing the `docker image push` process, for example by pressing `CTRL-c` while it is + running in a terminal, terminates the push operation. + + Progress bars are shown during docker push, which show the uncompressed size. + The actual amount of data that's pushed will be compressed before sending, so + the uploaded size will not be reflected by the progress bar. + + Registry credentials are managed by [docker login](login.md). + + ### Concurrent uploads + + By default the Docker daemon will push five layers of an image at a time. + If you are on a low bandwidth connection this may cause timeout issues and you may want to lower + this via the `--max-concurrent-uploads` daemon option. See the + [daemon documentation](dockerd.md) for more details. usage: docker image push [OPTIONS] NAME[:TAG] pname: docker image plink: docker_image.yaml options: +- option: all-tags + shorthand: a + value_type: bool + default_value: "false" + description: Push all tagged images in the repository + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: disable-content-trust value_type: bool default_value: "true" @@ -14,6 +45,92 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Suppress verbose output + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +examples: |- + ### Push a new image to a registry + + First save the new image by finding the container ID (using [`docker container ls`](ps.md)) + and then committing it to a new image name. Note that only `a-z0-9-_.` are + allowed when naming images: + + ```bash + $ docker container commit c16378f943fe rhel-httpd:latest + ``` + + Now, push the image to the registry using the image ID. In this example the + registry is on host named `registry-host` and listening on port `5000`. To do + this, tag the image with the host name or IP address, and the port of the + registry: + + ```bash + $ docker image tag rhel-httpd:latest registry-host:5000/myadmin/rhel-httpd:latest + + $ docker image push registry-host:5000/myadmin/rhel-httpd:latest + ``` + + Check that this worked by running: + + ```bash + $ docker image ls + ``` + + You should see both `rhel-httpd` and `registry-host:5000/myadmin/rhel-httpd` + listed. + + ### Push all tags of an image + + Use the `-a` (or `--all-tags`) option to push To push all tags of a local image. + + The following example creates multiple tags for an image, and pushes all those + tags to Docker Hub. + + + ```bash + $ docker image tag myimage registry-host:5000/myname/myimage:latest + $ docker image tag myimage registry-host:5000/myname/myimage:v1.0.1 + $ docker image tag myimage registry-host:5000/myname/myimage:v1.0 + $ docker image tag myimage registry-host:5000/myname/myimage:v1 + ``` + + The image is now tagged under multiple names: + + ```bash + $ docker image ls + + REPOSITORY TAG IMAGE ID CREATED SIZE + myimage latest 6d5fcfe5ff17 2 hours ago 1.22MB + registry-host:5000/myname/myimage latest 6d5fcfe5ff17 2 hours ago 1.22MB + registry-host:5000/myname/myimage v1 6d5fcfe5ff17 2 hours ago 1.22MB + registry-host:5000/myname/myimage v1.0 6d5fcfe5ff17 2 hours ago 1.22MB + registry-host:5000/myname/myimage v1.0.1 6d5fcfe5ff17 2 hours ago 1.22MB + ``` + + When pushing with the `--all-tags` option, all tags of the `registry-host:5000/myname/myimage` + image are pushed: + + + ```bash + $ docker image push --all-tags registry-host:5000/myname/myimage + + The push refers to repository [registry-host:5000/myname/myimage] + 195be5f8be1d: Pushed + latest: digest: sha256:edafc0a0fb057813850d1ba44014914ca02d671ae247107ca70c94db686e7de6 size: 4527 + 195be5f8be1d: Layer already exists + v1: digest: sha256:edafc0a0fb057813850d1ba44014914ca02d671ae247107ca70c94db686e7de6 size: 4527 + 195be5f8be1d: Layer already exists + v1.0: digest: sha256:edafc0a0fb057813850d1ba44014914ca02d671ae247107ca70c94db686e7de6 size: 4527 + 195be5f8be1d: Layer already exists + v1.0.1: digest: sha256:edafc0a0fb057813850d1ba44014914ca02d671ae247107ca70c94db686e7de6 size: 4527 + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_image_rm.yaml b/_data/engine-cli/docker_image_rm.yaml index c60a4984296f..a3c00f697428 100644 --- a/_data/engine-cli/docker_image_rm.yaml +++ b/_data/engine-cli/docker_image_rm.yaml @@ -1,7 +1,15 @@ command: docker image rm aliases: rmi, remove short: Remove one or more images -long: Remove one or more images +long: |- + Removes (and un-tags) one or more images from the host node. If an image has + multiple tags, using this command with the tag as a parameter only removes the + tag. If the tag is the only one for the image, both the image and the tag are + removed. + + This does not remove images from a registry. You cannot remove an image of a + running container unless you use the `-f` option. To see all images on a host + use the [`docker image ls`](images.md) command. usage: docker image rm [OPTIONS] IMAGE [IMAGE...] pname: docker image plink: docker_image.yaml @@ -25,6 +33,82 @@ options: experimentalcli: false kubernetes: false swarm: false +examples: |- + You can remove an image using its short or long ID, its tag, or its digest. If + an image has one or more tags referencing it, you must remove all of them before + the image is removed. Digest references are removed automatically when an image + is removed by tag. + + ```bash + $ docker images + + REPOSITORY TAG IMAGE ID CREATED SIZE + test1 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) + test latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) + test2 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) + + $ docker rmi fd484f19954f + + Error: Conflict, cannot delete image fd484f19954f because it is tagged in multiple repositories, use -f to force + 2013/12/11 05:47:16 Error: failed to remove one or more images + + $ docker rmi test1:latest + + Untagged: test1:latest + + $ docker rmi test2:latest + + Untagged: test2:latest + + + $ docker images + + REPOSITORY TAG IMAGE ID CREATED SIZE + test latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) + + $ docker rmi test:latest + + Untagged: test:latest + Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8 + ``` + + If you use the `-f` flag and specify the image's short or long ID, then this + command untags and removes all images that match the specified ID. + + ```bash + $ docker images + + REPOSITORY TAG IMAGE ID CREATED SIZE + test1 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) + test latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) + test2 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) + + $ docker rmi -f fd484f19954f + + Untagged: test1:latest + Untagged: test:latest + Untagged: test2:latest + Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8 + ``` + + An image pulled by digest has no tag associated with it: + + ```bash + $ docker images --digests + + REPOSITORY TAG DIGEST IMAGE ID CREATED SIZE + localhost:5000/test/busybox sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf 4986bf8c1536 9 weeks ago 2.43 MB + ``` + + To remove an image using its digest: + + ```bash + $ docker rmi localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf + Untagged: localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf + Deleted: 4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125 + Deleted: ea13149945cb6b1e746bf28032f02e9b5a793523481a0a18645fc77ad53c4ea2 + Deleted: df7546f9f060a2268024c8a230d8639878585defcc1bc6f79d2728a13957871b + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_image_save.yaml b/_data/engine-cli/docker_image_save.yaml index 1fbdbb1a052f..ae1d5c6811ad 100644 --- a/_data/engine-cli/docker_image_save.yaml +++ b/_data/engine-cli/docker_image_save.yaml @@ -1,6 +1,9 @@ command: docker image save short: Save one or more images to a tar archive (streamed to STDOUT by default) -long: Save one or more images to a tar archive (streamed to STDOUT by default) +long: |- + Produces a tarred repository to the standard output stream. + Contains all parent layers, and all tags + versions, or specified `repo:tag`, for + each argument provided. usage: docker image save [OPTIONS] IMAGE [IMAGE...] pname: docker image plink: docker_image.yaml @@ -14,6 +17,42 @@ options: experimentalcli: false kubernetes: false swarm: false +examples: |- + ### Create a backup that can then be used with `docker load`. + + ```bash + $ docker save busybox > busybox.tar + + $ ls -sh busybox.tar + + 2.7M busybox.tar + + $ docker save --output busybox.tar busybox + + $ ls -sh busybox.tar + + 2.7M busybox.tar + + $ docker save -o fedora-all.tar fedora + + $ docker save -o fedora-latest.tar fedora:latest + ``` + + ### Save an image to a tar.gz file using gzip + + You can use gzip to save the image file and make the backup smaller. + + ```bash + docker save myimage:latest | gzip > myimage_latest.tar.gz + ``` + + ### Cherry-pick particular tags + + You can even cherry-pick particular tags of an image repository. + + ```bash + $ docker save -o ubuntu.tar ubuntu:lucid ubuntu:saucy + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_image_tag.yaml b/_data/engine-cli/docker_image_tag.yaml index 3830ef1b8d2f..dd8b2a37bb37 100644 --- a/_data/engine-cli/docker_image_tag.yaml +++ b/_data/engine-cli/docker_image_tag.yaml @@ -1,9 +1,63 @@ command: docker image tag short: Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE -long: Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE +long: |- + An image name is made up of slash-separated name components, optionally prefixed + by a registry hostname. The hostname must comply with standard DNS rules, but + may not contain underscores. If a hostname is present, it may optionally be + followed by a port number in the format `:8080`. If not present, the command + uses Docker's public registry located at `registry-1.docker.io` by default. Name + components may contain lowercase letters, digits and separators. A separator + is defined as a period, one or two underscores, or one or more dashes. A name + component may not start or end with a separator. + + A tag name must be valid ASCII and may contain lowercase and uppercase letters, + digits, underscores, periods and dashes. A tag name may not start with a + period or a dash and may contain a maximum of 128 characters. + + You can group your images together using names and tags, and then upload them + to [*Share images on Docker Hub*](https://docs.docker.com/get-started/part3/). usage: docker image tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG] pname: docker image plink: docker_image.yaml +examples: |- + ### Tag an image referenced by ID + + To tag a local image with ID "0e5574283393" into the "fedora" repository with + "version1.0": + + ```bash + $ docker tag 0e5574283393 fedora/httpd:version1.0 + ``` + + ### Tag an image referenced by Name + + To tag a local image with name "httpd" into the "fedora" repository with + "version1.0": + + ```bash + $ docker tag httpd fedora/httpd:version1.0 + ``` + + Note that since the tag name is not specified, the alias is created for an + existing local version `httpd:latest`. + + ### Tag an image referenced by Name and Tag + + To tag a local image with name "httpd" and tag "test" into the "fedora" + repository with "version1.0.test": + + ```bash + $ docker tag httpd:test fedora/httpd:version1.0.test + ``` + + ### Tag an image for a private repository + + To push an image to a private registry and not the central Docker + registry you must tag it with the registry hostname and port (if needed). + + ```bash + $ docker tag 0e5574283393 myregistryhost:5000/fedora/httpd:version1.0 + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_images.yaml b/_data/engine-cli/docker_images.yaml index 76d8eacd870f..703e49f418af 100644 --- a/_data/engine-cli/docker_images.yaml +++ b/_data/engine-cli/docker_images.yaml @@ -1,21 +1,6 @@ command: docker images short: List images -long: |- - The default `docker images` will show all top level - images, their repository and tags, and their size. - - Docker images have intermediate layers that increase reusability, - decrease disk usage, and speed up `docker build` by - allowing each step to be cached. These intermediate layers are not shown - by default. - - The `SIZE` is the cumulative space taken up by the image and all - its parent images. This is also the disk space used by the contents of the - Tar file created when you `docker save` an image. - - An image will be listed more than once if it has multiple repository names - or tags. This single image (identifiable by its matching `IMAGE ID`) - uses up the `SIZE` listed only once. +long: List images usage: docker images [OPTIONS] [REPOSITORY[:TAG]] pname: docker plink: docker.yaml @@ -69,308 +54,12 @@ options: shorthand: q value_type: bool default_value: "false" - description: Only show numeric IDs + description: Only show image IDs deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false -examples: |- - ### List the most recently created images - - ```bash - $ docker images - - REPOSITORY TAG IMAGE ID CREATED SIZE - 77af4d6b9913 19 hours ago 1.089 GB - committ latest b6fa739cedf5 19 hours ago 1.089 GB - 78a85c484f71 19 hours ago 1.089 GB - docker latest 30557a29d5ab 20 hours ago 1.089 GB - 5ed6274db6ce 24 hours ago 1.089 GB - postgres 9 746b819f315e 4 days ago 213.4 MB - postgres 9.3 746b819f315e 4 days ago 213.4 MB - postgres 9.3.5 746b819f315e 4 days ago 213.4 MB - postgres latest 746b819f315e 4 days ago 213.4 MB - ``` - - ### List images by name and tag - - The `docker images` command takes an optional `[REPOSITORY[:TAG]]` argument - that restricts the list to images that match the argument. If you specify - `REPOSITORY`but no `TAG`, the `docker images` command lists all images in the - given repository. - - For example, to list all images in the "java" repository, run this command : - - ```bash - $ docker images java - - REPOSITORY TAG IMAGE ID CREATED SIZE - java 8 308e519aac60 6 days ago 824.5 MB - java 7 493d82594c15 3 months ago 656.3 MB - java latest 2711b1d6f3aa 5 months ago 603.9 MB - ``` - - The `[REPOSITORY[:TAG]]` value must be an "exact match". This means that, for example, - `docker images jav` does not match the image `java`. - - If both `REPOSITORY` and `TAG` are provided, only images matching that - repository and tag are listed. To find all local images in the "java" - repository with tag "8" you can use: - - ```bash - $ docker images java:8 - - REPOSITORY TAG IMAGE ID CREATED SIZE - java 8 308e519aac60 6 days ago 824.5 MB - ``` - - If nothing matches `REPOSITORY[:TAG]`, the list is empty. - - ```bash - $ docker images java:0 - - REPOSITORY TAG IMAGE ID CREATED SIZE - ``` - - ### List the full length image IDs - - ```bash - $ docker images --no-trunc - - REPOSITORY TAG IMAGE ID CREATED SIZE - sha256:77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182 19 hours ago 1.089 GB - committest latest sha256:b6fa739cedf5ea12a620a439402b6004d057da800f91c7524b5086a5e4749c9f 19 hours ago 1.089 GB - sha256:78a85c484f71509adeaace20e72e941f6bdd2b25b4c75da8693efd9f61a37921 19 hours ago 1.089 GB - docker latest sha256:30557a29d5abc51e5f1d5b472e79b7e296f595abcf19fe6b9199dbbc809c6ff4 20 hours ago 1.089 GB - sha256:0124422dd9f9cf7ef15c0617cda3931ee68346455441d66ab8bdc5b05e9fdce5 20 hours ago 1.089 GB - sha256:18ad6fad340262ac2a636efd98a6d1f0ea775ae3d45240d3418466495a19a81b 22 hours ago 1.082 GB - sha256:f9f1e26352f0a3ba6a0ff68167559f64f3e21ff7ada60366e2d44a04befd1d3a 23 hours ago 1.089 GB - tryout latest sha256:2629d1fa0b81b222fca63371ca16cbf6a0772d07759ff80e8d1369b926940074 23 hours ago 131.5 MB - sha256:5ed6274db6ceb2397844896966ea239290555e74ef307030ebb01ff91b1914df 24 hours ago 1.089 GB - ``` - - ### List image digests - - Images that use the v2 or later format have a content-addressable identifier - called a `digest`. As long as the input used to generate the image is - unchanged, the digest value is predictable. To list image digest values, use - the `--digests` flag: - - ```bash - $ docker images --digests - REPOSITORY TAG DIGEST IMAGE ID CREATED SIZE - localhost:5000/test/busybox sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf 4986bf8c1536 9 weeks ago 2.43 MB - ``` - - When pushing or pulling to a 2.0 registry, the `push` or `pull` command - output includes the image digest. You can `pull` using a digest value. You can - also reference by digest in `create`, `run`, and `rmi` commands, as well as the - `FROM` image reference in a Dockerfile. - - ### 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: - - * dangling (boolean - true or false) - * label (`label=` or `label==`) - * before (`[:]`, `` or ``) - filter images created before given id or references - * since (`[:]`, `` or ``) - filter images created since given id or references - * reference (pattern of an image reference) - filter images whose reference matches the specified pattern - - #### Show untagged images (dangling) - - ```bash - $ docker images --filter "dangling=true" - - REPOSITORY TAG IMAGE ID CREATED SIZE - 8abc22fbb042 4 weeks ago 0 B - 48e5f45168b9 4 weeks ago 2.489 MB - bf747efa0e2f 4 weeks ago 0 B - 980fe10e5736 12 weeks ago 101.4 MB - dea752e4e117 12 weeks ago 101.4 MB - 511136ea3c5a 8 months ago 0 B - ``` - - This will display untagged images that are the leaves of the images tree (not - intermediary layers). These images occur when a new build of an image takes the - `repo:tag` away from the image ID, leaving it as `:` or untagged. - A warning will be issued if trying to remove an image when a container is presently - using it. By having this flag it allows for batch cleanup. - - You can use this in conjunction with `docker rmi ...`: - - ```bash - $ docker rmi $(docker images -f "dangling=true" -q) - - 8abc22fbb042 - 48e5f45168b9 - bf747efa0e2f - 980fe10e5736 - dea752e4e117 - 511136ea3c5a - ``` - - Docker warns you if any containers exist that are using these untagged images. - - - #### Show images with a given label - - The `label` filter matches images based on the presence of a `label` alone or a `label` and a - value. - - The following filter matches images with the `com.example.version` label regardless of its value. - - ```bash - $ docker images --filter "label=com.example.version" - - REPOSITORY TAG IMAGE ID CREATED SIZE - match-me-1 latest eeae25ada2aa About a minute ago 188.3 MB - match-me-2 latest dea752e4e117 About a minute ago 188.3 MB - ``` - - The following filter matches images with the `com.example.version` label with the `1.0` value. - - ```bash - $ docker images --filter "label=com.example.version=1.0" - - REPOSITORY TAG IMAGE ID CREATED SIZE - match-me latest 511136ea3c5a About a minute ago 188.3 MB - ``` - - In this example, with the `0.1` value, it returns an empty set because no matches were found. - - ```bash - $ docker images --filter "label=com.example.version=0.1" - REPOSITORY TAG IMAGE ID CREATED SIZE - ``` - - #### Filter images by time - - The `before` filter shows only images created before the image with - given id or reference. For example, having these images: - - ```bash - $ docker images - - REPOSITORY TAG IMAGE ID CREATED SIZE - image1 latest eeae25ada2aa 4 minutes ago 188.3 MB - image2 latest dea752e4e117 9 minutes ago 188.3 MB - image3 latest 511136ea3c5a 25 minutes ago 188.3 MB - ``` - - Filtering with `before` would give: - - ```bash - $ docker images --filter "before=image1" - - REPOSITORY TAG IMAGE ID CREATED SIZE - image2 latest dea752e4e117 9 minutes ago 188.3 MB - image3 latest 511136ea3c5a 25 minutes ago 188.3 MB - ``` - - Filtering with `since` would give: - - ```bash - $ docker images --filter "since=image3" - REPOSITORY TAG IMAGE ID CREATED SIZE - image1 latest eeae25ada2aa 4 minutes ago 188.3 MB - image2 latest dea752e4e117 9 minutes ago 188.3 MB - ``` - - #### Filter images by reference - - The `reference` filter shows only images whose reference matches - the specified pattern. - - ```bash - $ 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 - ``` - - 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 - ``` - - Filtering with multiple `reference` would give, either match A or B: - - ```bash - $ docker images --filter=reference='busy*:uclibc' --filter=reference='busy*:glibc' - - 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 - - The formatting option (`--format`) will pretty print container output - using a Go template. - - Valid placeholders for the Go template are listed below: - - | Placeholder | Description| - | ---- | ---- | - | `.ID` | Image ID | - | `.Repository` | Image repository | - | `.Tag` | Image tag | - | `.Digest` | Image digest | - | `.CreatedSince` | Elapsed time since the image was created | - | `.CreatedAt` | Time when the image was created | - | `.Size` | Image disk size | - - When using the `--format` option, the `image` 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 `Repository` entries separated by a colon (`:`) for all images: - - ```bash - $ docker images --format "{{.ID}}: {{.Repository}}" - - 77af4d6b9913: - b6fa739cedf5: committ - 78a85c484f71: - 30557a29d5ab: docker - 5ed6274db6ce: - 746b819f315e: postgres - 746b819f315e: postgres - 746b819f315e: postgres - 746b819f315e: postgres - ``` - - To list all images with their repository and tag in a table format you - can use: - - ```bash - $ docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}" - - IMAGE ID REPOSITORY TAG - 77af4d6b9913 - b6fa739cedf5 committ latest - 78a85c484f71 - 30557a29d5ab docker latest - 5ed6274db6ce - 746b819f315e postgres 9 - 746b819f315e postgres 9.3 - 746b819f315e postgres 9.3.5 - 746b819f315e postgres latest - ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_import.yaml b/_data/engine-cli/docker_import.yaml index a2e73f20a2e8..3c53394f4bed 100644 --- a/_data/engine-cli/docker_import.yaml +++ b/_data/engine-cli/docker_import.yaml @@ -1,18 +1,6 @@ command: docker import short: Import the contents from a tarball to create a filesystem image -long: |- - You can specify a `URL` or `-` (dash) to take data directly from `STDIN`. The - `URL` can point to an archive (.tar, .tar.gz, .tgz, .bzip, .tar.xz, or .txz) - containing a filesystem or to an individual file on the Docker host. If you - specify an archive, Docker untars it in the container relative to the `/` - (root). If you specify an individual file, you must specify the full path within - the host. To import from a remote location, specify a `URI` that begins with the - `http://` or `https://` protocol. - - The `--change` option will apply `Dockerfile` instructions to the image - that is created. - Supported `Dockerfile` instructions: - `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` +long: Import the contents from a tarball to create a filesystem image usage: docker import [OPTIONS] file|URL|- [REPOSITORY[:TAG]] pname: docker plink: docker.yaml @@ -44,51 +32,6 @@ options: experimentalcli: false kubernetes: false swarm: false -examples: |- - ### Import from a remote location - - This will create a new untagged image. - - ```bash - $ docker import http://example.com/exampleimage.tgz - ``` - - ### Import from a local file - - - Import to docker via pipe and `STDIN`. - - ```bash - $ cat exampleimage.tgz | docker import - exampleimagelocal:new - ``` - - - Import with a commit message. - - ```bash - $ cat exampleimage.tgz | docker import --message "New image imported from tarball" - exampleimagelocal:new - ``` - - - Import to docker from a local archive. - - ```bash - $ docker import /path/to/exampleimage.tgz - ``` - - ### Import from a local directory - - ```bash - $ sudo tar -c . | docker import - exampleimagedir - ``` - - ### Import from a local directory with new configurations - - ```bash - $ sudo tar -c . | docker import --change "ENV DEBUG=true" - exampleimagedir - ``` - - Note the `sudo` in this example – you must preserve - the ownership of the files (especially root ownership) during the - archiving with tar. If you are not root (or the sudo command) when you - tar, then the ownerships might not get preserved. deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_info.yaml b/_data/engine-cli/docker_info.yaml index f7d480511e87..933f3a824d2a 100644 --- a/_data/engine-cli/docker_info.yaml +++ b/_data/engine-cli/docker_info.yaml @@ -1,23 +1,6 @@ command: docker info short: Display system-wide information -long: |- - This command displays system wide information regarding the Docker installation. - Information displayed includes the kernel version, number of containers and images. - The number of images shown is the number of unique images. The same image tagged - under different names is counted only once. - - If a 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. - - Depending on the storage driver in use, additional information can be shown, such - as pool name, data file, metadata file, data space used, total data space, metadata - space used, and total metadata space. - - The data file is where the images are stored and the metadata file is where the - meta data regarding those images are stored. When run for the first time Docker - allocates a certain amount of data space and meta data space from the space - available on the volume where `/var/lib/docker` is mounted. +long: Display system-wide information usage: docker info [OPTIONS] pname: docker plink: docker.yaml @@ -31,209 +14,6 @@ options: experimentalcli: false kubernetes: false swarm: false -examples: |- - ### Show output - - The example below shows the output for a daemon running on Red Hat Enterprise Linux, - using the `devicemapper` storage driver. As can be seen in the output, additional - information about the `devicemapper` storage driver is shown: - - ```bash - $ docker info - Client: - Debug Mode: false - - Server: - Containers: 14 - Running: 3 - Paused: 1 - Stopped: 10 - Images: 52 - Server Version: 1.10.3 - Storage Driver: devicemapper - Pool Name: docker-202:2-25583803-pool - Pool Blocksize: 65.54 kB - Base Device Size: 10.74 GB - Backing Filesystem: xfs - Data file: /dev/loop0 - Metadata file: /dev/loop1 - Data Space Used: 1.68 GB - Data Space Total: 107.4 GB - Data Space Available: 7.548 GB - Metadata Space Used: 2.322 MB - Metadata Space Total: 2.147 GB - Metadata Space Available: 2.145 GB - Udev Sync Supported: true - Deferred Removal Enabled: false - Deferred Deletion Enabled: false - Deferred Deleted Device Count: 0 - Data loop file: /var/lib/docker/devicemapper/devicemapper/data - Metadata loop file: /var/lib/docker/devicemapper/devicemapper/metadata - Library Version: 1.02.107-RHEL7 (2015-12-01) - Execution Driver: native-0.2 - Logging Driver: json-file - Plugins: - Volume: local - Network: null host bridge - Kernel Version: 3.10.0-327.el7.x86_64 - Operating System: Red Hat Enterprise Linux Server 7.2 (Maipo) - OSType: linux - Architecture: x86_64 - CPUs: 1 - Total Memory: 991.7 MiB - Name: ip-172-30-0-91.ec2.internal - ID: I54V:OLXT:HVMM:TPKO:JPHQ:CQCD:JNLC:O3BZ:4ZVJ:43XJ:PFHZ:6N2S - Docker Root Dir: /var/lib/docker - Debug Mode: false - Username: gordontheturtle - Registry: https://index.docker.io/v1/ - Insecure registries: - myinsecurehost:5000 - 127.0.0.0/8 - ``` - - ### Show debugging output - - Here is a sample output for a daemon running on Ubuntu, using the overlay2 - storage driver and a node that is part of a 2-node swarm: - - ```bash - $ docker -D info - Client: - Debug Mode: true - - Server: - Containers: 14 - Running: 3 - Paused: 1 - Stopped: 10 - Images: 52 - Server Version: 1.13.0 - Storage Driver: overlay2 - Backing Filesystem: extfs - Supports d_type: true - Native Overlay Diff: false - Logging Driver: json-file - Cgroup Driver: cgroupfs - Plugins: - Volume: local - Network: bridge host macvlan null overlay - Swarm: active - NodeID: rdjq45w1op418waxlairloqbm - Is Manager: true - ClusterID: te8kdyw33n36fqiz74bfjeixd - Managers: 1 - Nodes: 2 - Orchestration: - Task History Retention Limit: 5 - Raft: - Snapshot Interval: 10000 - Number of Old Snapshots to Retain: 0 - Heartbeat Tick: 1 - Election Tick: 3 - Dispatcher: - 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 - Runtimes: runc - Default Runtime: runc - Init Binary: docker-init - containerd version: 8517738ba4b82aff5662c97ca4627e7e4d03b531 - runc version: ac031b5bf1cc92239461125f4c1ffb760522bbf2 - init version: N/A (expected: v0.13.0) - Security Options: - apparmor - seccomp - Profile: default - Kernel Version: 4.4.0-31-generic - Operating System: Ubuntu 16.04.1 LTS - OSType: linux - Architecture: x86_64 - CPUs: 2 - Total Memory: 1.937 GiB - Name: ubuntu - ID: H52R:7ZR6:EIIA:76JG:ORIY:BVKF:GSFU:HNPG:B5MK:APSC:SZ3Q:N326 - Docker Root Dir: /var/lib/docker - Debug Mode: true - File Descriptors: 30 - Goroutines: 123 - System Time: 2016-11-12T17:24:37.955404361-08:00 - EventsListeners: 0 - Http Proxy: http://test:test@proxy.example.com:8080 - Https Proxy: https://test:test@proxy.example.com:8080 - No Proxy: localhost,127.0.0.1,docker-registry.somecorporation.com - Registry: https://index.docker.io/v1/ - WARNING: No swap limit support - Labels: - storage=ssd - staging=true - Experimental: false - Insecure Registries: - 127.0.0.0/8 - Registry Mirrors: - http://192.168.1.2/ - http://registry-mirror.example.com:5000/ - Live Restore Enabled: false - ``` - - The global `-D` option causes all `docker` commands to output debug information. - - ### Format the output - - You can also specify the output format: - - ```bash - $ docker info --format '{{json .}}' - - {"ID":"I54V:OLXT:HVMM:TPKO:JPHQ:CQCD:JNLC:O3BZ:4ZVJ:43XJ:PFHZ:6N2S","Containers":14, ...} - ``` - - ### Run `docker info` on Windows - - Here is a sample output for a daemon running on Windows Server 2016: - - ```console - E:\docker>docker info - Client: - Debug Mode: false - - Server: - Containers: 1 - Running: 0 - Paused: 0 - Stopped: 1 - Images: 17 - Server Version: 1.13.0 - Storage Driver: windowsfilter - Windows: - Logging Driver: json-file - Plugins: - Volume: local - Network: nat null overlay - Swarm: inactive - Default Isolation: process - Kernel Version: 10.0 14393 (14393.206.amd64fre.rs1_release.160912-1937) - Operating System: Windows Server 2016 Datacenter - OSType: windows - Architecture: x86_64 - CPUs: 8 - Total Memory: 3.999 GiB - Name: WIN-V0V70C0LU5P - ID: NYMS:B5VK:UMSL:FVDZ:EWB5:FKVK:LPFL:FJMQ:H6FT:BZJ6:L2TD:XH62 - Docker Root Dir: C:\control - Debug Mode: false - Registry: https://index.docker.io/v1/ - Insecure Registries: - 127.0.0.0/8 - Registry Mirrors: - http://192.168.1.2/ - http://registry-mirror.example.com:5000/ - Live Restore Enabled: false - ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_kill.yaml b/_data/engine-cli/docker_kill.yaml index 997dc41cf62e..7e101bdb8052 100644 --- a/_data/engine-cli/docker_kill.yaml +++ b/_data/engine-cli/docker_kill.yaml @@ -1,16 +1,6 @@ command: docker kill short: Kill one or more running containers -long: |- - The `docker kill` subcommand kills one or more containers. The main process - inside the container is sent `SIGKILL` signal (default), or the signal that is - specified with the `--signal` option. You can kill a container using the - container's ID, ID-prefix, or name. - - > **Note** - > - > `ENTRYPOINT` and `CMD` in the *shell* form run as a child process of - > `/bin/sh -c`, which does not pass signals. This means that the executable is - > not the container’s PID 1 and does not receive Unix signals. +long: Kill one or more running containers usage: docker kill [OPTIONS] CONTAINER [CONTAINER...] pname: docker plink: docker.yaml @@ -25,37 +15,6 @@ options: experimentalcli: false kubernetes: false swarm: false -examples: |- - ### Send a KILL signal to a container - - The following example sends the default `KILL` signal to the container named - `my_container`: - - ```bash - $ docker kill my_container - ``` - - ### Send a custom signal to a container - - The following example sends a `SIGHUP` signal to the container named - `my_container`: - - ```bash - $ docker kill --signal=SIGHUP my_container - ``` - - - You can specify a custom signal either by _name_, or _number_. The `SIG` prefix - is optional, so the following examples are equivalent: - - ```bash - $ docker kill --signal=SIGHUP my_container - $ docker kill --signal=HUP my_container - $ docker kill --signal=1 my_container - ``` - - Refer to the [`signal(7)`](http://man7.org/linux/man-pages/man7/signal.7.html) - man-page for a list of standard Linux signals. deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_load.yaml b/_data/engine-cli/docker_load.yaml index 6c78f498e051..6b74f63b037d 100644 --- a/_data/engine-cli/docker_load.yaml +++ b/_data/engine-cli/docker_load.yaml @@ -1,8 +1,6 @@ command: docker load short: Load an image from a tar archive or STDIN -long: |- - Load an image or repository from a tar archive (even if compressed with gzip, - bzip2, or xz) from a file or STDIN. It restores both images and tags. +long: Load an image from a tar archive or STDIN usage: docker load [OPTIONS] pname: docker plink: docker.yaml @@ -26,34 +24,6 @@ options: experimentalcli: false kubernetes: false swarm: false -examples: |- - ```bash - $ docker image ls - - REPOSITORY TAG IMAGE ID CREATED SIZE - - $ docker load < busybox.tar.gz - - Loaded image: busybox:latest - $ docker images - REPOSITORY TAG IMAGE ID CREATED SIZE - busybox latest 769b9341d937 7 weeks ago 2.489 MB - - $ docker load --input fedora.tar - - Loaded image: fedora:rawhide - - Loaded image: fedora:20 - - $ docker images - - REPOSITORY TAG IMAGE ID CREATED SIZE - busybox latest 769b9341d937 7 weeks ago 2.489 MB - fedora rawhide 0d20aec6529d 7 weeks ago 387 MB - fedora 20 58394af37342 7 weeks ago 385.5 MB - fedora heisenbug 58394af37342 7 weeks ago 385.5 MB - fedora latest 58394af37342 7 weeks ago 385.5 MB - ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_logs.yaml b/_data/engine-cli/docker_logs.yaml index 269efd81da45..ce5f9ca82133 100644 --- a/_data/engine-cli/docker_logs.yaml +++ b/_data/engine-cli/docker_logs.yaml @@ -1,43 +1,6 @@ command: docker logs short: Fetch the logs of a container -long: |- - The `docker logs` command batch-retrieves logs present at the time of execution. - - > **Note** - > - > This command is only functional for containers that are started with the - > `json-file` or `journald` logging driver. - - For more information about selecting and configuring logging drivers, refer to - [Configure logging drivers](https://docs.docker.com/config/containers/logging/configure/). - - The `docker logs --follow` command will continue streaming the new output from - the container's `STDOUT` and `STDERR`. - - Passing a negative number or a non-integer to `--tail` is invalid and the - value is set to `all` in that case. - - The `docker logs --timestamps` command will add an [RFC3339Nano timestamp](https://golang.org/pkg/time/#pkg-constants) - , for example `2014-09-16T06:17:46.000000000Z`, to each - log entry. To ensure that the timestamps are aligned the - nano-second part of the timestamp will be padded with zero when necessary. - - The `docker logs --details` command will add on extra attributes, such as - environment variables and labels, provided to `--log-opt` when creating the - container. - - The `--since` option shows only the container logs generated after - a given date. You can specify the date as an RFC 3339 date, a UNIX - timestamp, or a Go duration string (e.g. `1m30s`, `3h`). Besides RFC3339 date - format you may also use RFC3339Nano, `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. You can combine the - `--since` option with either or both of the `--follow` or `--tail` options. +long: Fetch the logs of a container usage: docker logs [OPTIONS] CONTAINER pname: docker plink: docker.yaml @@ -64,13 +27,14 @@ options: - option: since value_type: string description: | - Show logs since timestamp (e.g. 2013-01-02T13:23:37) or relative (e.g. 42m for 42 minutes) + Show logs since timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: tail + shorthand: "n" value_type: string default_value: all description: Number of lines to show from the end of the logs @@ -92,27 +56,13 @@ options: - option: until value_type: string description: | - Show logs before a timestamp (e.g. 2013-01-02T13:23:37) or relative (e.g. 42m for 42 minutes) + Show logs before a timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) deprecated: false min_api_version: "1.35" experimental: false experimentalcli: false kubernetes: false swarm: false -examples: |- - ### Retrieve logs until a specific point in time - - In order to retrieve logs before a specific point in time, run: - - ```bash - $ docker run --name test -d busybox sh -c "while true; do $(echo date); sleep 1; done" - $ date - Tue 14 Nov 2017 16:40:00 CET - $ docker logs -f --until=2s test - Tue 14 Nov 2017 16:40:00 CET - Tue 14 Nov 2017 16:40:01 CET - Tue 14 Nov 2017 16:40:02 CET - ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_manifest.yaml b/_data/engine-cli/docker_manifest.yaml index 28453f61a0ff..bec43280ed51 100644 --- a/_data/engine-cli/docker_manifest.yaml +++ b/_data/engine-cli/docker_manifest.yaml @@ -56,6 +56,7 @@ long: |- --arch string Set architecture --help Print usage --os string Set operating system + --os-version string Set operating system version --os-features stringSlice Set operating system feature --variant string Set architecture variant @@ -94,11 +95,13 @@ cname: - docker manifest create - docker manifest inspect - docker manifest push +- docker manifest rm clink: - docker_manifest_annotate.yaml - docker_manifest_create.yaml - docker_manifest_inspect.yaml - docker_manifest_push.yaml +- docker_manifest_rm.yaml examples: |- ### Inspect an image's manifest object diff --git a/_data/engine-cli/docker_manifest_annotate.yaml b/_data/engine-cli/docker_manifest_annotate.yaml index c1491c2e6b81..9807caa1be92 100644 --- a/_data/engine-cli/docker_manifest_annotate.yaml +++ b/_data/engine-cli/docker_manifest_annotate.yaml @@ -30,6 +30,14 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: os-version + value_type: string + description: Set operating system version + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: variant value_type: string description: Set architecture variant diff --git a/_data/engine-cli/docker_manifest_rm.yaml b/_data/engine-cli/docker_manifest_rm.yaml new file mode 100644 index 000000000000..513d2a7b2c57 --- /dev/null +++ b/_data/engine-cli/docker_manifest_rm.yaml @@ -0,0 +1,12 @@ +command: docker manifest rm +short: Delete one or more manifest lists from local storage +long: Delete one or more manifest lists from local storage +usage: docker manifest rm MANIFEST_LIST [MANIFEST_LIST...] +pname: docker manifest +plink: docker_manifest.yaml +deprecated: false +experimental: false +experimentalcli: true +kubernetes: false +swarm: false + diff --git a/_data/engine-cli/docker_network_create.yaml b/_data/engine-cli/docker_network_create.yaml index 94e6248ce76c..6f24e23d734e 100644 --- a/_data/engine-cli/docker_network_create.yaml +++ b/_data/engine-cli/docker_network_create.yaml @@ -85,7 +85,7 @@ options: swarm: false - option: config-from value_type: string - description: The network from which copying the configuration + description: The network from which to copy the configuration deprecated: false min_api_version: "1.30" experimental: false diff --git a/_data/engine-cli/docker_pause.yaml b/_data/engine-cli/docker_pause.yaml index b99213ce7df6..d3964e514218 100644 --- a/_data/engine-cli/docker_pause.yaml +++ b/_data/engine-cli/docker_pause.yaml @@ -1,23 +1,9 @@ command: docker pause short: Pause all processes within one or more containers -long: |- - The `docker pause` command suspends all processes in the specified containers. - On Linux, this uses the freezer cgroup. Traditionally, when suspending a process - the `SIGSTOP` signal is used, which is observable by the process being suspended. - With the freezer cgroup the process is unaware, and unable to capture, - that it is being suspended, and subsequently resumed. On Windows, only Hyper-V - containers can be paused. - - See the - [freezer cgroup documentation](https://www.kernel.org/doc/Documentation/cgroup-v1/freezer-subsystem.txt) - for further details. +long: Pause all processes within one or more containers usage: docker pause CONTAINER [CONTAINER...] pname: docker plink: docker.yaml -examples: |- - ```bash - $ docker pause my_container - ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_port.yaml b/_data/engine-cli/docker_port.yaml index 72eea3238fd4..bd564f2509c6 100644 --- a/_data/engine-cli/docker_port.yaml +++ b/_data/engine-cli/docker_port.yaml @@ -4,35 +4,6 @@ long: List port mappings or a specific mapping for the container usage: docker port CONTAINER [PRIVATE_PORT[/PROTO]] pname: docker plink: docker.yaml -examples: |- - ### Show all mapped ports - - You can find out all the ports mapped by not specifying a `PRIVATE_PORT`, or - just a specific mapping: - - ```bash - $ docker ps - - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - b650456536c7 busybox:latest top 54 minutes ago Up 54 minutes 0.0.0.0:1234->9876/tcp, 0.0.0.0:4321->7890/tcp test - - $ docker port test - - 7890/tcp -> 0.0.0.0:4321 - 9876/tcp -> 0.0.0.0:1234 - - $ docker port test 7890/tcp - - 0.0.0.0:4321 - - $ docker port test 7890/udp - - 2014/06/24 11:53:36 Error: No public port '7890/udp' published for test - - $ docker port test 7890 - - 0.0.0.0:4321 - ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_ps.yaml b/_data/engine-cli/docker_ps.yaml index 9d751f4536ba..24f7894dc80f 100644 --- a/_data/engine-cli/docker_ps.yaml +++ b/_data/engine-cli/docker_ps.yaml @@ -65,7 +65,7 @@ options: shorthand: q value_type: bool default_value: "false" - description: Only display numeric IDs + description: Only display container IDs deprecated: false experimental: false experimentalcli: false @@ -81,408 +81,6 @@ options: experimentalcli: false kubernetes: false swarm: false -examples: |- - ### Prevent truncating output - - Running `docker ps --no-trunc` showing 2 linked containers. - - ```bash - $ docker ps - - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 4c01db0b339c ubuntu:12.04 bash 17 seconds ago Up 16 seconds 3300-3310/tcp webapp - d7886598dbe2 crosbymichael/redis:latest /redis-server --dir 33 minutes ago Up 33 minutes 6379/tcp redis,webapp/db - ``` - - ### Show both running and stopped containers - - The `docker ps` command only shows running containers by default. To see all - containers, use the `-a` (or `--all`) flag: - - ```bash - $ docker ps -a - ``` - - `docker ps` groups exposed ports into a single range if possible. E.g., a - container that exposes TCP ports `100, 101, 102` displays `100-102/tcp` in - the `PORTS` column. - - ### Show disk usage by container - - The `docker ps -s` command displays two different on-disk-sizes for each container: - - ```bash - $ docker ps -s - - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES SIZE SIZE - e90b8831a4b8 nginx "/bin/bash -c 'mkdir " 11 weeks ago Up 4 hours my_nginx 35.58 kB (virtual 109.2 MB) - 00c6131c5e30 telegraf:1.5 "/entrypoint.sh" 11 weeks ago Up 11 weeks my_telegraf 0 B (virtual 209.5 MB) - ``` - * The "size" information shows the amount of data (on disk) that is used for the _writable_ layer of each container - * The "virtual size" is the total amount of disk-space used for the read-only _image_ data used by the container and the writable layer. - - For more information, refer to the [container size on disk](https://docs.docker.com/storage/storagedriver/#container-size-on-disk) section. - - - ### 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: - - | Filter | Description | - |:----------------------|:-------------------------------------------------------------------------------------------------------------------------------------| - | `id` | Container's ID | - | `name` | Container's name | - | `label` | An arbitrary string representing either a key or a key-value pair. Expressed as `` or `=` | - | `exited` | An integer representing the container's exit code. Only useful with `--all`. | - | `status` | One of `created`, `restarting`, `running`, `removing`, `paused`, `exited`, or `dead` | - | `ancestor` | Filters containers which share a given image as an ancestor. Expressed as `[:]`, ``, or `` | - | `before` or `since` | Filters containers created before or after a given container ID or name | - | `volume` | Filters running containers which have mounted a given volume or bind mount. | - | `network` | Filters running containers connected to a given network. | - | `publish` or `expose` | Filters containers which publish or expose a given port. Expressed as `[/]` or `/[]` | - | `health` | Filters containers based on their healthcheck status. One of `starting`, `healthy`, `unhealthy` or `none`. | - | `isolation` | Windows daemon only. One of `default`, `process`, or `hyperv`. | - | `is-task` | Filters containers that are a "task" for a service. Boolean option (`true` or `false`) | - - - #### label - - The `label` filter matches containers based on the presence of a `label` alone or a `label` and a - value. - - The following filter matches containers with the `color` label regardless of its value. - - ```bash - $ docker ps --filter "label=color" - - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 673394ef1d4c busybox "top" 47 seconds ago Up 45 seconds nostalgic_shockley - d85756f57265 busybox "top" 52 seconds ago Up 51 seconds high_albattani - ``` - - The following filter matches containers with the `color` label with the `blue` value. - - ```bash - $ docker ps --filter "label=color=blue" - - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - d85756f57265 busybox "top" About a minute ago Up About a minute high_albattani - ``` - - #### name - - The `name` filter matches on all or part of a container's name. - - The following filter matches all containers with a name containing the `nostalgic_stallman` string. - - ```bash - $ docker ps --filter "name=nostalgic_stallman" - - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 9b6247364a03 busybox "top" 2 minutes ago Up 2 minutes nostalgic_stallman - ``` - - You can also filter for a substring in a name as this shows: - - ```bash - $ docker ps --filter "name=nostalgic" - - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 715ebfcee040 busybox "top" 3 seconds ago Up 1 second i_am_nostalgic - 9b6247364a03 busybox "top" 7 minutes ago Up 7 minutes nostalgic_stallman - 673394ef1d4c busybox "top" 38 minutes ago Up 38 minutes nostalgic_shockley - ``` - - #### exited - - The `exited` filter matches containers by exist status code. For example, to - filter for containers that have exited successfully: - - ```bash - $ docker ps -a --filter 'exited=0' - - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - ea09c3c82f6e registry:latest /srv/run.sh 2 weeks ago Exited (0) 2 weeks ago 127.0.0.1:5000->5000/tcp desperate_leakey - 106ea823fe4e fedora:latest /bin/sh -c 'bash -l' 2 weeks ago Exited (0) 2 weeks ago determined_albattani - 48ee228c9464 fedora:20 bash 2 weeks ago Exited (0) 2 weeks ago tender_torvalds - ``` - - #### Filter by exit signal - - You can use a filter to locate containers that exited with status of `137` - meaning a `SIGKILL(9)` killed them. - - ```bash - $ docker ps -a --filter 'exited=137' - - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - b3e1c0ed5bfe ubuntu:latest "sleep 1000" 12 seconds ago Exited (137) 5 seconds ago grave_kowalevski - a2eb5558d669 redis:latest "/entrypoint.sh redi 2 hours ago Exited (137) 2 hours ago sharp_lalande - ``` - - Any of these events result in a `137` status: - - * the `init` process of the container is killed manually - * `docker kill` kills the container - * Docker daemon restarts which kills all running containers - - #### status - - The `status` filter matches containers by status. You can filter using - `created`, `restarting`, `running`, `removing`, `paused`, `exited` and `dead`. For example, - to filter for `running` containers: - - ```bash - $ docker ps --filter status=running - - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 715ebfcee040 busybox "top" 16 minutes ago Up 16 minutes i_am_nostalgic - d5c976d3c462 busybox "top" 23 minutes ago Up 23 minutes top - 9b6247364a03 busybox "top" 24 minutes ago Up 24 minutes nostalgic_stallman - ``` - - To filter for `paused` containers: - - ```bash - $ docker ps --filter status=paused - - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 673394ef1d4c busybox "top" About an hour ago Up About an hour (Paused) nostalgic_shockley - ``` - - #### ancestor - - The `ancestor` filter matches containers based on its image or a descendant of - it. The filter supports the following image representation: - - - `image` - - `image:tag` - - `image:tag@digest` - - `short-id` - - `full-id` - - If you don't specify a `tag`, the `latest` tag is used. For example, to filter - for containers that use the latest `ubuntu` image: - - ```bash - $ docker ps --filter ancestor=ubuntu - - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 919e1179bdb8 ubuntu-c1 "top" About a minute ago Up About a minute admiring_lovelace - 5d1e4a540723 ubuntu-c2 "top" About a minute ago Up About a minute admiring_sammet - 82a598284012 ubuntu "top" 3 minutes ago Up 3 minutes sleepy_bose - bab2a34ba363 ubuntu "top" 3 minutes ago Up 3 minutes focused_yonath - ``` - - Match containers based on the `ubuntu-c1` image which, in this case, is a child - of `ubuntu`: - - ```bash - $ docker ps --filter ancestor=ubuntu-c1 - - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 919e1179bdb8 ubuntu-c1 "top" About a minute ago Up About a minute admiring_lovelace - ``` - - Match containers based on the `ubuntu` version `12.04.5` image: - - ```bash - $ docker ps --filter ancestor=ubuntu:12.04.5 - - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 82a598284012 ubuntu:12.04.5 "top" 3 minutes ago Up 3 minutes sleepy_bose - ``` - - The following matches containers based on the layer `d0e008c6cf02` or an image - that have this layer in its layer stack. - - ```bash - $ docker ps --filter ancestor=d0e008c6cf02 - - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 82a598284012 ubuntu:12.04.5 "top" 3 minutes ago Up 3 minutes sleepy_bose - ``` - - #### Create time - - ##### before - - The `before` filter shows only containers created before the container with - given id or name. For example, having these containers created: - - ```bash - $ docker ps - - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 9c3527ed70ce busybox "top" 14 seconds ago Up 15 seconds desperate_dubinsky - 4aace5031105 busybox "top" 48 seconds ago Up 49 seconds focused_hamilton - 6e63f6ff38b0 busybox "top" About a minute ago Up About a minute distracted_fermat - ``` - - Filtering with `before` would give: - - ```bash - $ docker ps -f before=9c3527ed70ce - - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 4aace5031105 busybox "top" About a minute ago Up About a minute focused_hamilton - 6e63f6ff38b0 busybox "top" About a minute ago Up About a minute distracted_fermat - ``` - - ##### since - - The `since` filter shows only containers created since the container with given - id or name. For example, with the same containers as in `before` filter: - - ```bash - $ docker ps -f since=6e63f6ff38b0 - - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 9c3527ed70ce busybox "top" 10 minutes ago Up 10 minutes desperate_dubinsky - 4aace5031105 busybox "top" 10 minutes ago Up 10 minutes focused_hamilton - ``` - - #### volume - - The `volume` filter shows only containers that mount a specific volume or have - a volume mounted in a specific path: - - ```bash - $ docker ps --filter volume=remote-volume --format "table {{.ID}}\t{{.Mounts}}" - - CONTAINER ID MOUNTS - 9c3527ed70ce remote-volume - - $ docker ps --filter volume=/data --format "table {{.ID}}\t{{.Mounts}}" - - CONTAINER ID MOUNTS - 9c3527ed70ce remote-volume - ``` - - #### network - - The `network` filter shows only containers that are connected to a network with - a given name or id. - - The following filter matches all containers that are connected to a network - with a name containing `net1`. - - ```bash - $ docker run -d --net=net1 --name=test1 ubuntu top - $ docker run -d --net=net2 --name=test2 ubuntu top - - $ docker ps --filter network=net1 - - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 9d4893ed80fe ubuntu "top" 10 minutes ago Up 10 minutes test1 - ``` - - The network filter matches on both the network's name and id. The following - example shows all containers that are attached to the `net1` network, using - the network id as a filter; - - ```bash - $ docker network inspect --format "{{.ID}}" net1 - - 8c0b4110ae930dbe26b258de9bc34a03f98056ed6f27f991d32919bfe401d7c5 - - $ docker ps --filter network=8c0b4110ae930dbe26b258de9bc34a03f98056ed6f27f991d32919bfe401d7c5 - - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 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 - template. - - Valid placeholders for the Go template are listed below: - - | Placeholder | Description | - |:--------------|:------------------------------------------------------------------------------------------------| - | `.ID` | Container ID | - | `.Image` | Image ID | - | `.Command` | Quoted command | - | `.CreatedAt` | Time when the container was created. | - | `.RunningFor` | Elapsed time since the container was started. | - | `.Ports` | Exposed ports. | - | `.Status` | Container status. | - | `.Size` | Container disk size. | - | `.Names` | Container names. | - | `.Labels` | All labels assigned to the container. | - | `.Label` | Value of a specific label for this container. For example `'{{.Label "com.docker.swarm.cpu"}}'` | - | `.Mounts` | Names of the volumes mounted in this container. | - | `.Networks` | Names of the networks attached to this container. | - - When using the `--format` option, the `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 `ID` and - `Command` entries separated by a colon (`:`) for all running containers: - - ```bash - $ docker ps --format "{{.ID}}: {{.Command}}" - - a87ecb4f327c: /bin/sh -c #(nop) MA - 01946d9d34d8: /bin/sh -c #(nop) MA - c1d3b0166030: /bin/sh -c yum -y up - 41d50ecd2f57: /bin/sh -c #(nop) MA - ``` - - To list all running containers with their labels in a table format you can use: - - ```bash - $ docker ps --format "table {{.ID}}\t{{.Labels}}" - - CONTAINER ID LABELS - a87ecb4f327c com.docker.swarm.node=ubuntu,com.docker.swarm.storage=ssd - 01946d9d34d8 - c1d3b0166030 com.docker.swarm.node=debian,com.docker.swarm.cpu=6 - 41d50ecd2f57 com.docker.swarm.node=fedora,com.docker.swarm.cpu=3,com.docker.swarm.storage=ssd - ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_pull.yaml b/_data/engine-cli/docker_pull.yaml index b06db059c7a4..26521820e077 100644 --- a/_data/engine-cli/docker_pull.yaml +++ b/_data/engine-cli/docker_pull.yaml @@ -1,30 +1,6 @@ command: docker pull short: Pull an image or a repository from a registry -long: |- - Most of your images will be created on top of a base image from the - [Docker Hub](https://hub.docker.com) registry. - - [Docker Hub](https://hub.docker.com) contains many pre-built images that you - can `pull` and try without needing to define and configure your own. - - To download a particular image, or set of images (i.e., a repository), - use `docker pull`. - - ### Proxy configuration - - If you are behind an HTTP proxy server, for example in corporate settings, - before open a connect to registry, you may need to configure the Docker - daemon's proxy settings, using the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` - environment variables. To set these environment variables on a host using - `systemd`, refer to the [control and configure Docker with systemd](https://docs.docker.com/config/daemon/systemd/#httphttps-proxy) - for variables configuration. - - ### Concurrent downloads - - By default the Docker daemon will pull three layers of an image at a time. - If you are on a low bandwidth connection this may cause timeout issues and you may want to lower - this via the `--max-concurrent-downloads` daemon option. See the - [daemon documentation](dockerd.md) for more details. +long: Pull an image or a repository from a registry usage: docker pull [OPTIONS] NAME[:TAG|@DIGEST] pname: docker plink: docker.yaml @@ -67,208 +43,6 @@ options: experimentalcli: false kubernetes: false swarm: false -examples: |- - ### Pull an image from Docker Hub - - To download a particular image, or set of images (i.e., a repository), use - `docker pull`. If no tag is provided, Docker Engine uses the `:latest` tag as a - default. This command pulls the `debian:latest` image: - - ```bash - $ docker pull debian - - Using default tag: latest - latest: Pulling from library/debian - fdd5d7827f33: Pull complete - a3ed95caeb02: Pull complete - Digest: sha256:e7d38b3517548a1c71e41bffe9c8ae6d6d29546ce46bf62159837aad072c90aa - Status: Downloaded newer image for debian:latest - ``` - - Docker images can consist of multiple layers. In the example above, the image - consists of two layers; `fdd5d7827f33` and `a3ed95caeb02`. - - Layers can be reused by images. For example, the `debian:jessie` image shares - both layers with `debian:latest`. Pulling the `debian:jessie` image therefore - only pulls its metadata, but not its layers, because all layers are already - present locally: - - ```bash - $ docker pull debian:jessie - - jessie: Pulling from library/debian - fdd5d7827f33: Already exists - a3ed95caeb02: Already exists - Digest: sha256:a9c958be96d7d40df920e7041608f2f017af81800ca5ad23e327bc402626b58e - Status: Downloaded newer image for debian:jessie - ``` - - To see which images are present locally, use the [`docker images`](images.md) - command: - - ```bash - $ docker images - - REPOSITORY TAG IMAGE ID CREATED SIZE - debian jessie f50f9524513f 5 days ago 125.1 MB - debian latest f50f9524513f 5 days ago 125.1 MB - ``` - - Docker uses a content-addressable image store, and the image ID is a SHA256 - digest covering the image's configuration and layers. In the example above, - `debian:jessie` and `debian:latest` have the same image ID because they are - actually the *same* image tagged with different names. Because they are the - same image, their layers are stored only once and do not consume extra disk - space. - - For more information about images, layers, and the content-addressable store, - refer to [understand images, containers, and storage drivers](https://docs.docker.com/storage/storagedriver/). - - - ### Pull an image by digest (immutable identifier) - - So far, you've pulled images by their name (and "tag"). Using names and tags is - a convenient way to work with images. When using tags, you can `docker pull` an - image again to make sure you have the most up-to-date version of that image. - For example, `docker pull ubuntu:14.04` pulls the latest version of the Ubuntu - 14.04 image. - - In some cases you don't want images to be updated to newer versions, but prefer - to use a fixed version of an image. Docker enables you to pull an image by its - *digest*. When pulling an image by digest, you specify *exactly* which version - of an image to pull. Doing so, allows you to "pin" an image to that version, - and guarantee that the image you're using is always the same. - - To know the digest of an image, pull the image first. Let's pull the latest - `ubuntu:14.04` image from Docker Hub: - - ```bash - $ docker pull ubuntu:14.04 - - 14.04: Pulling from library/ubuntu - 5a132a7e7af1: Pull complete - fd2731e4c50c: Pull complete - 28a2f68d1120: Pull complete - a3ed95caeb02: Pull complete - Digest: sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 - Status: Downloaded newer image for ubuntu:14.04 - ``` - - Docker prints the digest of the image after the pull has finished. In the example - above, the digest of the image is: - - sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 - - Docker also prints the digest of an image when *pushing* to a registry. This - may be useful if you want to pin to a version of the image you just pushed. - - A digest takes the place of the tag when pulling an image, for example, to - pull the above image by digest, run the following command: - - ```bash - $ docker pull ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 - - sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2: Pulling from library/ubuntu - 5a132a7e7af1: Already exists - fd2731e4c50c: Already exists - 28a2f68d1120: Already exists - a3ed95caeb02: Already exists - Digest: sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 - Status: Downloaded newer image for ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 - ``` - - Digest can also be used in the `FROM` of a Dockerfile, for example: - - ```dockerfile - FROM ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2 - MAINTAINER some maintainer - ``` - - > **Note** - > - > Using this feature "pins" an image to a specific version in time. - > Docker will therefore not pull updated versions of an image, which may include - > security updates. If you want to pull an updated image, you need to change the - > digest accordingly. - - - ### Pull from a different registry - - By default, `docker pull` pulls images from [Docker Hub](https://hub.docker.com). It is also possible to - manually specify the path of a registry to pull from. For example, if you have - set up a local registry, you can specify its path to pull from it. A registry - path is similar to a URL, but does not contain a protocol specifier (`https://`). - - The following command pulls the `testing/test-image` image from a local registry - listening on port 5000 (`myregistry.local:5000`): - - ```bash - $ docker pull myregistry.local:5000/testing/test-image - ``` - - Registry credentials are managed by [docker login](login.md). - - Docker uses the `https://` protocol to communicate with a registry, unless the - registry is allowed to be accessed over an insecure connection. Refer to the - [insecure registries](dockerd.md#insecure-registries) section for more information. - - - ### Pull a repository with multiple images - - By default, `docker pull` pulls a *single* image from the registry. A repository - can contain multiple images. To pull all images from a repository, provide the - `-a` (or `--all-tags`) option when using `docker pull`. - - This command pulls all images from the `fedora` repository: - - ```bash - $ docker pull --all-tags fedora - - Pulling repository fedora - ad57ef8d78d7: Download complete - 105182bb5e8b: Download complete - 511136ea3c5a: Download complete - 73bd853d2ea5: Download complete - .... - - Status: Downloaded newer image for fedora - ``` - - After the pull has completed use the `docker images` command to see the - images that were pulled. The example below shows all the `fedora` images - that are present locally: - - ```bash - $ docker images fedora - - REPOSITORY TAG IMAGE ID CREATED SIZE - fedora rawhide ad57ef8d78d7 5 days ago 359.3 MB - fedora 20 105182bb5e8b 5 days ago 372.7 MB - fedora heisenbug 105182bb5e8b 5 days ago 372.7 MB - fedora latest 105182bb5e8b 5 days ago 372.7 MB - ``` - - ### Cancel a pull - - Killing the `docker pull` process, for example by pressing `CTRL-c` while it is - running in a terminal, will terminate the pull operation. - - ```bash - $ docker pull fedora - - Using default tag: latest - latest: Pulling from library/fedora - a3ed95caeb02: Pulling fs layer - 236608c7b546: Pulling fs layer - ^C - ``` - - > **Note** - > - > The Engine terminates a pull operation when the connection between the Docker - > Engine daemon and the Docker Engine client initiating the pull is lost. If the - > connection with the Engine daemon is lost for other reasons than a manual - > interaction, the pull is also aborted. deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_push.yaml b/_data/engine-cli/docker_push.yaml index e911e02f21b3..8916b8235674 100644 --- a/_data/engine-cli/docker_push.yaml +++ b/_data/engine-cli/docker_push.yaml @@ -1,31 +1,20 @@ command: docker push short: Push an image or a repository to a registry -long: |- - Use `docker push` to share your images to the [Docker Hub](https://hub.docker.com) - registry or to a self-hosted one. - - Refer to the [`docker tag`](tag.md) reference for more information about valid - image and tag names. - - Killing the `docker push` process, for example by pressing `CTRL-c` while it is - running in a terminal, terminates the push operation. - - Progress bars are shown during docker push, which show the uncompressed size. - The actual amount of data that's pushed will be compressed before sending, so - the uploaded size will not be reflected by the progress bar. - - Registry credentials are managed by [docker login](login.md). - - ### Concurrent uploads - - By default the Docker daemon will push five layers of an image at a time. - If you are on a low bandwidth connection this may cause timeout issues and you may want to lower - this via the `--max-concurrent-uploads` daemon option. See the - [daemon documentation](dockerd.md) for more details. +long: Push an image or a repository to a registry usage: docker push [OPTIONS] NAME[:TAG] pname: docker plink: docker.yaml options: +- option: all-tags + shorthand: a + value_type: bool + default_value: "false" + description: Push all tagged images in the repository + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: disable-content-trust value_type: bool default_value: "true" @@ -35,36 +24,16 @@ options: experimentalcli: false kubernetes: false swarm: false -examples: |- - ### Push a new image to a registry - - First save the new image by finding the container ID (using [`docker ps`](ps.md)) - and then committing it to a new image name. Note that only `a-z0-9-_.` are - allowed when naming images: - - ```bash - $ docker commit c16378f943fe rhel-httpd - ``` - - Now, push the image to the registry using the image ID. In this example the - registry is on host named `registry-host` and listening on port `5000`. To do - this, tag the image with the host name or IP address, and the port of the - registry: - - ```bash - $ docker tag rhel-httpd registry-host:5000/myadmin/rhel-httpd - - $ docker push registry-host:5000/myadmin/rhel-httpd - ``` - - Check that this worked by running: - - ```bash - $ docker images - ``` - - You should see both `rhel-httpd` and `registry-host:5000/myadmin/rhel-httpd` - listed. +- option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Suppress verbose output + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_rename.yaml b/_data/engine-cli/docker_rename.yaml index c57ea4b5b820..340d1bf01db1 100644 --- a/_data/engine-cli/docker_rename.yaml +++ b/_data/engine-cli/docker_rename.yaml @@ -1,13 +1,9 @@ command: docker rename short: Rename a container -long: The `docker rename` command renames a container. +long: Rename a container usage: docker rename CONTAINER NEW_NAME pname: docker plink: docker.yaml -examples: |- - ```bash - $ docker rename my_container my_new_container - ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_restart.yaml b/_data/engine-cli/docker_restart.yaml index 90ff107560de..cf8af42bba12 100644 --- a/_data/engine-cli/docker_restart.yaml +++ b/_data/engine-cli/docker_restart.yaml @@ -15,10 +15,6 @@ options: experimentalcli: false kubernetes: false swarm: false -examples: |- - ```bash - $ docker restart my_container - ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_rm.yaml b/_data/engine-cli/docker_rm.yaml index 10294bb6bf10..304180c77095 100644 --- a/_data/engine-cli/docker_rm.yaml +++ b/_data/engine-cli/docker_rm.yaml @@ -35,75 +35,6 @@ options: experimentalcli: false kubernetes: false swarm: false -examples: |- - ### Remove a container - - This removes the container referenced under the link `/redis`. - - ```bash - $ docker rm /redis - - /redis - ``` - - ### Remove a link specified with `--link` on the default bridge network - - This removes the underlying link between `/webapp` and the `/redis` - containers on the default bridge network, removing all network communication - between the two containers. This does not apply when `--link` is used with - user-specified networks. - - ```bash - $ docker rm --link /webapp/redis - - /webapp/redis - ``` - - ### Force-remove a running container - - This command force-removes a running container. - - ```bash - $ docker rm --force redis - - redis - ``` - - The main process inside the container referenced under the link `redis` will receive - `SIGKILL`, then the container will be removed. - - ### Remove all stopped containers - - ```bash - $ docker rm $(docker ps -a -q) - ``` - - This command deletes all stopped containers. The command - `docker ps -a -q` above returns all existing container IDs and passes them to - the `rm` command which deletes them. Running containers are not deleted. - - ### Remove a container and its volumes - - ```bash - $ docker rm -v redis - redis - ``` - - This command removes the container and any volumes associated with it. - Note that if a volume was specified with a name, it will not be removed. - - ### Remove a container and selectively remove volumes - - ```bash - $ docker create -v awesome:/foo -v /bar --name hello redis - hello - - $ docker rm -v hello - ``` - - In this example, the volume for `/foo` remains intact, but the volume for - `/bar` is removed. The same behavior holds for volumes inherited with - `--volumes-from`. deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_rmi.yaml b/_data/engine-cli/docker_rmi.yaml index 7cb0a842125d..52698aca04a8 100644 --- a/_data/engine-cli/docker_rmi.yaml +++ b/_data/engine-cli/docker_rmi.yaml @@ -1,14 +1,6 @@ command: docker rmi short: Remove one or more images -long: |- - Removes (and un-tags) one or more images from the host node. If an image has - multiple tags, using this command with the tag as a parameter only removes the - tag. If the tag is the only one for the image, both the image and the tag are - removed. - - This does not remove images from a registry. You cannot remove an image of a - running container unless you use the `-f` option. To see all images on a host - use the [`docker image ls`](images.md) command. +long: Remove one or more images usage: docker rmi [OPTIONS] IMAGE [IMAGE...] pname: docker plink: docker.yaml @@ -32,82 +24,6 @@ options: experimentalcli: false kubernetes: false swarm: false -examples: |- - You can remove an image using its short or long ID, its tag, or its digest. If - an image has one or more tags referencing it, you must remove all of them before - the image is removed. Digest references are removed automatically when an image - is removed by tag. - - ```bash - $ docker images - - REPOSITORY TAG IMAGE ID CREATED SIZE - test1 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) - test latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) - test2 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) - - $ docker rmi fd484f19954f - - Error: Conflict, cannot delete image fd484f19954f because it is tagged in multiple repositories, use -f to force - 2013/12/11 05:47:16 Error: failed to remove one or more images - - $ docker rmi test1:latest - - Untagged: test1:latest - - $ docker rmi test2:latest - - Untagged: test2:latest - - - $ docker images - - REPOSITORY TAG IMAGE ID CREATED SIZE - test latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) - - $ docker rmi test:latest - - Untagged: test:latest - Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8 - ``` - - If you use the `-f` flag and specify the image's short or long ID, then this - command untags and removes all images that match the specified ID. - - ```bash - $ docker images - - REPOSITORY TAG IMAGE ID CREATED SIZE - test1 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) - test latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) - test2 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) - - $ docker rmi -f fd484f19954f - - Untagged: test1:latest - Untagged: test:latest - Untagged: test2:latest - Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8 - ``` - - An image pulled by digest has no tag associated with it: - - ```bash - $ docker images --digests - - REPOSITORY TAG DIGEST IMAGE ID CREATED SIZE - localhost:5000/test/busybox sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf 4986bf8c1536 9 weeks ago 2.43 MB - ``` - - To remove an image using its digest: - - ```bash - $ docker rmi localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf - Untagged: localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf - Deleted: 4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125 - Deleted: ea13149945cb6b1e746bf28032f02e9b5a793523481a0a18645fc77ad53c4ea2 - Deleted: df7546f9f060a2268024c8a230d8639878585defcc1bc6f79d2728a13957871b - ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_run.yaml b/_data/engine-cli/docker_run.yaml index 9051b68f6387..0f752c439e15 100644 --- a/_data/engine-cli/docker_run.yaml +++ b/_data/engine-cli/docker_run.yaml @@ -1,17 +1,6 @@ command: docker run short: Run a command in a new container -long: |- - The `docker run` command first `creates` a writeable container layer over the - specified image, and then `starts` it using the specified command. That is, - `docker run` is equivalent to the API `/containers/create` then - `/containers/(id)/start`. A stopped container can be restarted with all its - previous changes intact using `docker start`. See `docker ps -a` to view a list - of all containers. - - The `docker run` command can be used in combination with `docker commit` to - [*change the command that a container runs*](commit.md). There is additional detailed information about `docker run` in the [Docker run reference](../run.md). - - For information on connecting a container to a network, see the ["*Docker network overview*"](https://docs.docker.com/network/). +long: Run a command in a new container usage: docker run [OPTIONS] IMAGE [COMMAND] [ARG...] pname: docker plink: docker.yaml @@ -76,6 +65,20 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: cgroupns + value_type: string + description: |- + Cgroup namespace to use (host|private) + 'host': Run the container in the Docker host's cgroup namespace + 'private': Run the container in its own private cgroup namespace + '': Use the cgroup namespace as configured by the + default-cgroupns-mode option on the daemon (default) + deprecated: false + min_api_version: "1.41" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: cidfile value_type: string description: Write the container ID to the file @@ -718,6 +721,15 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: pull + value_type: string + default_value: missing + description: Pull image before running ("always"|"missing"|"never") + deprecated: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: read-only value_type: bool default_value: "false" @@ -901,717 +913,6 @@ options: experimentalcli: false kubernetes: false swarm: false -examples: |- - ### Assign name and allocate pseudo-TTY (--name, -it) - - ```bash - $ docker run --name test -it debian - - root@d6c0fe130dba:/# exit 13 - $ echo $? - 13 - $ docker ps -a | grep test - d6c0fe130dba debian:7 "/bin/bash" 26 seconds ago Exited (13) 17 seconds ago test - ``` - - This example runs a container named `test` using the `debian:latest` - image. The `-it` instructs Docker to allocate a pseudo-TTY connected to - the container's stdin; creating an interactive `bash` shell in the container. - In the example, the `bash` shell is quit by entering - `exit 13`. This exit code is passed on to the caller of - `docker run`, and is recorded in the `test` container's metadata. - - ### Capture container ID (--cidfile) - - ```bash - $ docker run --cidfile /tmp/docker_test.cid ubuntu echo "test" - ``` - - This will create a container and print `test` to the console. The `cidfile` - flag makes Docker attempt to create a new file and write the container ID to it. - If the file exists already, Docker will return an error. Docker will close this - file when `docker run` exits. - - ### Full container capabilities (--privileged) - - ```bash - $ docker run -t -i --rm ubuntu bash - root@bc338942ef20:/# mount -t tmpfs none /mnt - mount: permission denied - ``` - - This will *not* work, because by default, most potentially dangerous kernel - capabilities are dropped; including `cap_sys_admin` (which is required to mount - filesystems). However, the `--privileged` flag will allow it to run: - - ```bash - $ docker run -t -i --privileged ubuntu bash - root@50e3f57e16e6:/# mount -t tmpfs none /mnt - root@50e3f57e16e6:/# df -h - Filesystem Size Used Avail Use% Mounted on - none 1.9G 0 1.9G 0% /mnt - ``` - - The `--privileged` flag gives *all* capabilities to the container, and it also - lifts all the limitations enforced by the `device` cgroup controller. In other - words, the container can then do almost everything that the host can do. This - flag exists to allow special use-cases, like running Docker within Docker. - - ### Set working directory (-w) - - ```bash - $ docker run -w /path/to/dir/ -i -t ubuntu pwd - ``` - - The `-w` lets the command being executed inside directory given, here - `/path/to/dir/`. If the path does not exist it is created inside the container. - - ### Set storage driver options per container - - ```bash - $ docker run -it --storage-opt size=120G fedora /bin/bash - ``` - - This (size) will allow to set the container rootfs size to 120G at creation time. - This option is only available for the `devicemapper`, `btrfs`, `overlay2`, - `windowsfilter` and `zfs` graph drivers. - For the `devicemapper`, `btrfs`, `windowsfilter` and `zfs` graph drivers, - user cannot pass a size less than the Default BaseFS Size. - For the `overlay2` storage driver, the size option is only available if the - backing fs is `xfs` and mounted with the `pquota` mount option. - Under these conditions, user can pass any size less than the backing fs size. - - ### Mount tmpfs (--tmpfs) - - ```bash - $ docker run -d --tmpfs /run:rw,noexec,nosuid,size=65536k my_image - ``` - - The `--tmpfs` flag mounts an empty tmpfs into the container with the `rw`, - `noexec`, `nosuid`, `size=65536k` options. - - ### Mount volume (-v, --read-only) - - ```bash - $ docker run -v `pwd`:`pwd` -w `pwd` -i -t ubuntu pwd - ``` - - The `-v` flag mounts the current working directory into the container. The `-w` - lets the command being executed inside the current working directory, by - changing into the directory to the value returned by `pwd`. So this - combination executes the command using the container, but inside the - current working directory. - - ```bash - $ docker run -v /doesnt/exist:/foo -w /foo -i -t ubuntu bash - ``` - - When the host directory of a bind-mounted volume doesn't exist, Docker - will automatically create this directory on the host for you. In the - example above, Docker will create the `/doesnt/exist` - folder before starting your container. - - ```bash - $ docker run --read-only -v /icanwrite busybox touch /icanwrite/here - ``` - - Volumes can be used in combination with `--read-only` to control where - a container writes files. The `--read-only` flag mounts the container's root - filesystem as read only prohibiting writes to locations other than the - specified volumes for the container. - - ```bash - $ docker run -t -i -v /var/run/docker.sock:/var/run/docker.sock -v /path/to/static-docker-binary:/usr/bin/docker busybox sh - ``` - - By bind-mounting the docker unix socket and statically linked docker - binary (refer to [get the linux binary](https://docs.docker.com/engine/install/binaries/#install-static-binaries)), - you give the container the full access to create and manipulate the host's - Docker daemon. - - On Windows, the paths must be specified using Windows-style semantics. - - ```powershell - PS C:\> docker run -v c:\foo:c:\dest microsoft/nanoserver cmd /s /c type c:\dest\somefile.txt - Contents of file - - PS C:\> docker run -v c:\foo:d: microsoft/nanoserver cmd /s /c type d:\somefile.txt - Contents of file - ``` - - The following examples will fail when using Windows-based containers, as the - destination of a volume or bind mount inside the container must be one of: - a non-existing or empty directory; or a drive other than C:. Further, the source - of a bind mount must be a local directory, not a file. - - ```powershell - net use z: \\remotemachine\share - docker run -v z:\foo:c:\dest ... - docker run -v \\uncpath\to\directory:c:\dest ... - docker run -v c:\foo\somefile.txt:c:\dest ... - docker run -v c:\foo:c: ... - docker run -v c:\foo:c:\existing-directory-with-contents ... - ``` - - For in-depth information about volumes, refer to [manage data in containers](https://docs.docker.com/storage/volumes/) - - - ### 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-volumes-or-memory-filesystems). - - 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 - $ docker run -p 127.0.0.1:80:8080/tcp ubuntu bash - ``` - - This binds port `8080` of the container to TCP port `80` on `127.0.0.1` of the host - machine. You can also specify `udp` and `sctp` ports. - The [Docker User Guide](https://docs.docker.com/network/links/) - explains in detail how to manipulate ports in Docker. - - Note that ports which are not bound to the host (i.e., `-p 80:80` instead of - `-p 127.0.0.1:80:80`) will be accessible from the outside. This also applies if - you configured UFW to block this specific port, as Docker manages his - own iptables rules. [Read more](https://docs.docker.com/network/iptables/) - - ```bash - $ docker run --expose 80 ubuntu bash - ``` - - This exposes port `80` of the container without publishing the port to the host - system's interfaces. - - ### Set environment variables (-e, --env, --env-file) - - ```bash - $ docker run -e MYVAR1 --env MYVAR2=foo --env-file ./env.list ubuntu bash - ``` - - 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 - ``` - - You can also use variables that you've exported to your local environment: - - ```bash - export VAR1=value1 - export VAR2=value2 - - $ docker run --env VAR1 --env VAR2 ubuntu env | grep VAR - VAR1=value1 - VAR2=value2 - ``` - - 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. - - 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 - # This is a comment - VAR1=value1 - VAR2=value2 - USER - - $ docker run --env-file env.list ubuntu env | grep VAR - VAR1=value1 - VAR2=value2 - USER=denis - ``` - - ### Set metadata on container (-l, --label, --label-file) - - A label is a `key=value` pair that applies metadata to a container. To label a container with two labels: - - ```bash - $ docker run -l my-label --label com.example.foo=bar ubuntu bash - ``` - - The `my-label` key doesn't specify a value so the label defaults to an empty - string (`""`). To add multiple labels, repeat the label flag (`-l` or `--label`). - - The `key=value` must be unique to avoid overwriting the label value. If you - specify labels with identical keys but different values, each subsequent value - overwrites the previous. Docker uses the last `key=value` you supply. - - Use the `--label-file` flag to load multiple labels from a file. Delimit each - label in the file with an EOL mark. The example below loads labels from a - labels file in the current directory: - - ```bash - $ docker run --label-file ./labels ubuntu bash - ``` - - The label-file format is similar to the format for loading environment - variables. (Unlike environment variables, labels are not visible to processes - running inside a container.) The following example illustrates a label-file - format: - - ```console - com.example.label1="a label" - - # this is a comment - com.example.label2=another\ label - com.example.label3 - ``` - - You can load multiple label-files by supplying multiple `--label-file` flags. - - For additional information on working with labels, see [*Labels - custom - metadata in Docker*](https://docs.docker.com/config/labels-custom-metadata/) in - the Docker User Guide. - - ### Connect a container to a network (--network) - - When you start a container use the `--network` flag to connect it to a network. - This adds the `busybox` container to the `my-net` network. - - ```bash - $ docker run -itd --network=my-net busybox - ``` - - You can also choose the IP addresses for the container with `--ip` and `--ip6` - flags when you start the container on a user-defined network. - - ```bash - $ docker run -itd --network=my-net --ip=10.10.9.75 busybox - ``` - - If you want to add a running container to a network use the `docker network connect` subcommand. - - You can connect multiple containers to the same network. Once connected, the - containers can communicate easily need only another container's IP address - or name. For `overlay` networks or custom plugins that support multi-host - connectivity, containers connected to the same multi-host network but launched - from different Engines can also communicate in this way. - - > **Note** - > - > Service discovery is unavailable on the default bridge network. Containers can - > communicate via their IP addresses by default. To communicate by name, they - > must be linked. - - You can disconnect a container from a network using the `docker network - disconnect` command. - - ### Mount volumes from container (--volumes-from) - - ```bash - $ docker run --volumes-from 777f7dc92da7 --volumes-from ba8c0c54f0f2:ro -i -t ubuntu pwd - ``` - - The `--volumes-from` flag mounts all the defined volumes from the referenced - containers. Containers can be specified by repetitions of the `--volumes-from` - argument. The container ID may be optionally suffixed with `:ro` or `:rw` to - mount the volumes in read-only or read-write mode, respectively. By default, - the volumes are mounted in the same mode (read write or read only) as - the reference container. - - Labeling systems like SELinux require that proper labels are placed on volume - content mounted into a container. Without a label, the security system might - prevent the processes running inside the container from using the content. By - default, Docker does not change the labels set by the OS. - - To change the label in the container context, you can add either of two suffixes - `:z` or `:Z` to the volume mount. These suffixes tell Docker to relabel file - objects on the shared volumes. The `z` option tells Docker that two containers - share the volume content. As a result, Docker labels the content with a shared - content label. Shared volume labels allow all containers to read/write content. - The `Z` option tells Docker to label the content with a private unshared label. - Only the current container can use a private volume. - - ### Attach to STDIN/STDOUT/STDERR (-a) - - The `-a` flag tells `docker run` to bind to the container's `STDIN`, `STDOUT` - or `STDERR`. This makes it possible to manipulate the output and input as - needed. - - ```bash - $ echo "test" | docker run -i -a stdin ubuntu cat - - ``` - - This pipes data into a container and prints the container's ID by attaching - only to the container's `STDIN`. - - ```bash - $ docker run -a stderr ubuntu echo test - ``` - - This isn't going to print anything unless there's an error because we've - only attached to the `STDERR` of the container. The container's logs - still store what's been written to `STDERR` and `STDOUT`. - - ```bash - $ cat somefile | docker run -i -a stdin mybuilder dobuild - ``` - - This is how piping a file into a container could be done for a build. - The container's ID will be printed after the build is done and the build - logs could be retrieved using `docker logs`. This is - useful if you need to pipe a file or something else into a container and - retrieve the container's ID once the container has finished running. - - ### Add host device to container (--device) - - ```bash - $ docker run --device=/dev/sdc:/dev/xvdc \ - --device=/dev/sdd --device=/dev/zero:/dev/nulo \ - -i -t \ - ubuntu ls -l /dev/{xvdc,sdd,nulo} - - brw-rw---- 1 root disk 8, 2 Feb 9 16:05 /dev/xvdc - brw-rw---- 1 root disk 8, 3 Feb 9 16:05 /dev/sdd - crw-rw-rw- 1 root root 1, 5 Feb 9 16:05 /dev/nulo - ``` - - It is often necessary to directly expose devices to a container. The `--device` - option enables that. For example, a specific block storage device or loop - device or audio device can be added to an otherwise unprivileged container - (without the `--privileged` flag) and have the application directly access it. - - By default, the container will be able to `read`, `write` and `mknod` these devices. - This can be overridden using a third `:rwm` set of options to each `--device` - flag: - - ```bash - $ docker run --device=/dev/sda:/dev/xvdc --rm -it ubuntu fdisk /dev/xvdc - - Command (m for help): q - $ docker run --device=/dev/sda:/dev/xvdc:r --rm -it ubuntu fdisk /dev/xvdc - You will not be able to write the partition table. - - Command (m for help): q - - $ docker run --device=/dev/sda:/dev/xvdc:rw --rm -it ubuntu fdisk /dev/xvdc - - Command (m for help): q - - $ docker run --device=/dev/sda:/dev/xvdc:m --rm -it ubuntu fdisk /dev/xvdc - fdisk: unable to open /dev/xvdc: Operation not permitted - ``` - - > **Note** - > - > The `--device` option cannot be safely used with ephemeral devices. Block devices - > that may be removed should not be added to untrusted containers with `--device`. - - For Windows, the format of the string passed to the `--device` option is in - the form of `--device=/`. Beginning with Windows Server 2019 - and Windows 10 October 2018 Update, Windows only supports an IdType of - `class` and the Id as a [device interface class - GUID](https://docs.microsoft.com/en-us/windows-hardware/drivers/install/overview-of-device-interface-classes). - Refer to the table defined in the [Windows container - docs](https://docs.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/hardware-devices-in-containers) - for a list of container-supported device interface class GUIDs. - - If this option is specified for a process-isolated Windows container, _all_ - devices that implement the requested device interface class GUID are made - available in the container. For example, the command below makes all COM - ports on the host visible in the container. - - ```powershell - PS C:\> docker run --device=class/86E0D1E0-8089-11D0-9CE4-08003E301F73 mcr.microsoft.com/windows/servercore:ltsc2019 - ``` - - > **Note** - > - > The `--device` option is only supported on process-isolated Windows containers. - > This option fails if the container isolation is `hyperv` or when running Linux - > Containers on Windows (LCOW). - - ### Access an NVIDIA GPU - - The `--gpus­` flag allows you to access NVIDIA GPU resources. First you need to - install [nvidia-container-runtime](https://nvidia.github.io/nvidia-container-runtime/). - Visit [Specify a container's resources](https://docs.docker.com/config/containers/resource_constraints/) - for more information. - - To use `--gpus`, specify which GPUs (or all) to use. If no value is provied, all - available GPUs are used. The example below exposes all available GPUs. - - ```bash - $ docker run -it --rm --gpus all ubuntu nvidia-smi - ``` - - Use the `device` option to specify GPUs. The example below exposes a specific - GPU. - - ```bash - $ docker run -it --rm --gpus device=GPU-3a23c669-1f69-c64e-cf85-44e9b07e7a2a ubuntu nvidia-smi - ``` - - The example below exposes the first and third GPUs. - - ```bash - $ docker run -it --rm --gpus device=0,2 nvidia-smi - ``` - - ### Restart policies (--restart) - - Use Docker's `--restart` to specify a container's *restart policy*. A restart - 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. | - | `on-failure[:max-retries]` | Restart only if the container exits with a non-zero exit status. Optionally, limit the number of restart retries the Docker daemon attempts. | - | `unless-stopped` | Restart the container unless it is explicitly stopped or Docker itself is stopped or restarted. | - | `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 - ``` - - This will run the `redis` container with a restart policy of **always** - so that if the container exits, Docker will restart it. - - More detailed information on restart policies can be found in the - [Restart Policies (--restart)](../run.md#restart-policies---restart) - section of the Docker run reference page. - - ### Add entries to container hosts file (--add-host) - - You can add other hosts into a container's `/etc/hosts` file by using one or - more `--add-host` flags. This example adds a static address for a host named - `docker`: - - ```bash - $ docker run --add-host=docker:10.180.0.1 --rm -it debian - - root@f38c87f2a42d:/# ping docker - PING docker (10.180.0.1): 48 data bytes - 56 bytes from 10.180.0.1: icmp_seq=0 ttl=254 time=7.600 ms - 56 bytes from 10.180.0.1: icmp_seq=1 ttl=254 time=30.705 ms - ^C--- docker ping statistics --- - 2 packets transmitted, 2 packets received, 0% packet loss - round-trip min/avg/max/stddev = 7.600/19.152/30.705/11.553 ms - ``` - - Sometimes you need to connect to the Docker host from within your - container. To enable this, pass the Docker host's IP address to - the container using the `--add-host` flag. To find the host's address, - use the `ip addr show` command. - - The flags you pass to `ip addr show` depend on whether you are - using IPv4 or IPv6 networking in your containers. Use the following - flags for IPv4 address retrieval for a network device named `eth0`: - - ```bash - $ HOSTIP=`ip -4 addr show scope global dev eth0 | grep inet | awk '{print $2}' | cut -d / -f 1 | sed -n 1p` - $ docker run --add-host=docker:${HOSTIP} --rm -it debian - ``` - - For IPv6 use the `-6` flag instead of the `-4` flag. For other network - devices, replace `eth0` with the correct device name (for example `docker0` - for the bridge device). - - ### Set ulimits in container (--ulimit) - - Since setting `ulimit` settings in a container requires extra privileges not - available in the default container, you can set these using the `--ulimit` flag. - `--ulimit` is specified with a soft and hard limit as such: - `=[:]`, for example: - - ```bash - $ docker run --ulimit nofile=1024:1024 --rm debian sh -c "ulimit -n" - 1024 - ``` - - > **Note** - > - > If you do not provide a `hard limit`, the `soft limit` is used - > for both values. If no `ulimits` are set, they are inherited from - > the default `ulimits` set on the daemon. The `as` option is disabled now. - > In other words, the following script is not supported: - > - > ```bash - > $ docker run -it --ulimit as=1024 fedora /bin/bash` - > ``` - - The values are sent to the appropriate `syscall` as they are set. - Docker doesn't perform any byte conversion. Take this into account when setting the values. - - #### For `nproc` usage - - Be careful setting `nproc` with the `ulimit` flag as `nproc` is designed by Linux to set the - maximum number of processes available to a user, not to a container. For example, start four - containers with `daemon` user: - - ```bash - $ docker run -d -u daemon --ulimit nproc=3 busybox top - - $ docker run -d -u daemon --ulimit nproc=3 busybox top - - $ docker run -d -u daemon --ulimit nproc=3 busybox top - - $ docker run -d -u daemon --ulimit nproc=3 busybox top - ``` - - The 4th container fails and reports "[8] System error: resource temporarily unavailable" error. - This fails because the caller set `nproc=3` resulting in the first three containers using up - the three processes quota set for the `daemon` user. - - ### Stop container with signal (--stop-signal) - - The `--stop-signal` flag sets the system call signal that will be sent to the container to exit. - This signal can be a valid unsigned number that matches a position in the kernel's syscall table, for instance 9, - or a signal name in the format SIGNAME, for instance SIGKILL. - - ### Optional security options (--security-opt) - - On Windows, this flag can be used to specify the `credentialspec` option. - The `credentialspec` must be in the format `file://spec.txt` or `registry://keyname`. - - ### Stop container with timeout (--stop-timeout) - - The `--stop-timeout` flag sets the timeout (in seconds) that a pre-defined (see `--stop-signal`) system call - signal that will be sent to the container to exit. After timeout elapses the container will be killed with SIGKILL. - - ### 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. These two commands are equivalent on Linux: - - ```bash - $ docker run -d busybox top - $ docker run -d --isolation default busybox top - ``` - - On Windows, `--isolation` can take one of these values: - - - | 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 older than Windows 10 1809). | - | `hyperv` | Hyper-V hypervisor partition-based isolation. | - - The default isolation on Windows server operating systems is `process`. The default - isolation on Windows client operating systems is `hyperv`. An attempt to start a container on a client - operating system older than Windows 10 1809 with `--isolation process` will fail. - - 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 - ``` - - 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 - ``` - - ### Specify hard limits on memory available to containers (-m, --memory) - - These parameters always set an upper limit on the memory available to the container. On Linux, this - is set on the cgroup and applications in a container can query it at `/sys/fs/cgroup/memory/memory.limit_in_bytes`. - - On Windows, this will affect containers differently depending on what type of isolation is used. - - - With `process` isolation, Windows will report the full memory of the host system, not the limit to applications running inside the container - - ```powershell - PS C:\> docker run -it -m 2GB --isolation=process microsoft/nanoserver powershell Get-ComputerInfo *memory* - - CsTotalPhysicalMemory : 17064509440 - CsPhyicallyInstalledMemory : 16777216 - OsTotalVisibleMemorySize : 16664560 - OsFreePhysicalMemory : 14646720 - OsTotalVirtualMemorySize : 19154928 - OsFreeVirtualMemory : 17197440 - OsInUseVirtualMemory : 1957488 - OsMaxProcessMemorySize : 137438953344 - ``` - - - With `hyperv` isolation, Windows will create a utility VM that is big enough to hold the memory limit, plus the minimal OS needed to host the container. That size is reported as "Total Physical Memory." - - ```powershell - PS C:\> docker run -it -m 2GB --isolation=hyperv microsoft/nanoserver powershell Get-ComputerInfo *memory* - - CsTotalPhysicalMemory : 2683355136 - CsPhyicallyInstalledMemory : - OsTotalVisibleMemorySize : 2620464 - OsFreePhysicalMemory : 2306552 - OsTotalVirtualMemorySize : 2620464 - OsFreeVirtualMemory : 2356692 - OsInUseVirtualMemory : 263772 - OsMaxProcessMemorySize : 137438953344 - ``` - - - ### Configure namespaced kernel parameters (sysctls) at runtime - - The `--sysctl` sets namespaced kernel parameters (sysctls) in the - container. For example, to turn on IP forwarding in the containers - network namespace, run this command: - - ```bash - $ docker run --sysctl net.ipv4.ip_forward=1 someimage - ``` - - > **Note** - > - > Not all sysctls are namespaced. Docker does not support changing sysctls - > inside of a container that also modify the host system. As the kernel - > evolves we expect to see more sysctls become namespaced. - - #### Currently supported sysctls - - IPC Namespace: - - - `kernel.msgmax`, `kernel.msgmnb`, `kernel.msgmni`, `kernel.sem`, - `kernel.shmall`, `kernel.shmmax`, `kernel.shmmni`, `kernel.shm_rmid_forced`. - - Sysctls beginning with `fs.mqueue.*` - - If you use the `--ipc=host` option these sysctls are not allowed. - - Network Namespace: - - - Sysctls beginning with `net.*` - - If you use the `--network=host` option using these sysctls are not allowed. deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_save.yaml b/_data/engine-cli/docker_save.yaml index d494fe39bc1e..b4f7d740dd45 100644 --- a/_data/engine-cli/docker_save.yaml +++ b/_data/engine-cli/docker_save.yaml @@ -1,9 +1,6 @@ command: docker save short: Save one or more images to a tar archive (streamed to STDOUT by default) -long: |- - Produces a tarred repository to the standard output stream. - Contains all parent layers, and all tags + versions, or specified `repo:tag`, for - each argument provided. +long: Save one or more images to a tar archive (streamed to STDOUT by default) usage: docker save [OPTIONS] IMAGE [IMAGE...] pname: docker plink: docker.yaml @@ -17,42 +14,6 @@ options: experimentalcli: false kubernetes: false swarm: false -examples: |- - ### Create a backup that can then be used with `docker load`. - - ```bash - $ docker save busybox > busybox.tar - - $ ls -sh busybox.tar - - 2.7M busybox.tar - - $ docker save --output busybox.tar busybox - - $ ls -sh busybox.tar - - 2.7M busybox.tar - - $ docker save -o fedora-all.tar fedora - - $ docker save -o fedora-latest.tar fedora:latest - ``` - - ### Save an image to a tar.gz file using gzip - - You can use gzip to save the image file and make the backup smaller. - - ```bash - docker save myimage:latest | gzip > myimage_latest.tar.gz - ``` - - ### Cherry-pick particular tags - - You can even cherry-pick particular tags of an image repository. - - ```bash - $ docker save -o ubuntu.tar ubuntu:lucid ubuntu:saucy - ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_search.yaml b/_data/engine-cli/docker_search.yaml index e28cf27a7dd2..cdbf97e27b67 100644 --- a/_data/engine-cli/docker_search.yaml +++ b/_data/engine-cli/docker_search.yaml @@ -5,15 +5,6 @@ usage: docker search [OPTIONS] TERM pname: docker plink: docker.yaml options: -- option: automated - value_type: bool - default_value: "false" - description: Only show automated builds - deprecated: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - option: filter shorthand: f value_type: filter @@ -49,16 +40,6 @@ options: experimentalcli: false kubernetes: false swarm: false -- option: stars - shorthand: s - value_type: uint - default_value: "0" - description: Only displays with at least x stars - deprecated: true - experimental: false - experimentalcli: false - kubernetes: false - swarm: false examples: |- ### Search images by name diff --git a/_data/engine-cli/docker_service_create.yaml b/_data/engine-cli/docker_service_create.yaml index ed0bcd3179c6..8c3a46e72170 100644 --- a/_data/engine-cli/docker_service_create.yaml +++ b/_data/engine-cli/docker_service_create.yaml @@ -13,6 +13,24 @@ usage: docker service create [OPTIONS] IMAGE [COMMAND] [ARG...] pname: docker service plink: docker_service.yaml options: +- option: cap-add + value_type: list + description: Add Linux capabilities + deprecated: false + min_api_version: "1.41" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: cap-drop + value_type: list + description: Drop Linux capabilities + deprecated: false + min_api_version: "1.41" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: config value_type: config description: Specify configurations to expose to the service @@ -248,6 +266,16 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: limit-pids + value_type: int64 + default_value: "0" + description: Limit maximum number of processes (default 0 = unlimited) + deprecated: false + min_api_version: "1.41" + experimental: false + experimentalcli: false + kubernetes: false + swarm: true - option: log-driver value_type: string description: Logging driver for service @@ -264,10 +292,21 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: max-concurrent + value_type: uint + description: | + Number of job tasks to run concurrently (default equal to --replicas) + deprecated: false + min_api_version: "1.41" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: mode value_type: string default_value: replicated - description: Service mode (replicated or global) + description: | + Service mode (replicated, global, replicated-job, or global-job) deprecated: false experimental: false experimentalcli: false @@ -533,6 +572,16 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: ulimit + value_type: ulimit + default_value: '[]' + description: Ulimit options + deprecated: false + min_api_version: "1.41" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: update-delay value_type: duration default_value: 0s @@ -1640,6 +1689,66 @@ examples: |- --generic-resource "SSD=1" \ nvidia/cuda ``` + + ### Running as a job + + Jobs are a special kind of service designed to run an operation to completion + and then stop, as opposed to running long-running daemons. When a Task + belonging to a job exits successfully (return value 0), the Task is marked as + "Completed", and is not run again. + + Jobs are started by using one of two modes, `replicated-job` or `global-job` + + ```bash + $ docker service create --name myjob \ + --mode replicated-job \ + bash "true" + ``` + + This command will run one Task, which will, using the `bash` image, execute the + command `true`, which will return 0 and then exit. + + Though Jobs are ultimately a different kind of service, they a couple of + caveats compared to other services: + + - None of the update or rollback configuration options are valid. Jobs can be + updated, but cannot be rolled out or rolled back, making these configuration + options moot. + - Jobs are never restarted on reaching the `Complete` state. This means that + for jobs, setting `--restart-condition` to `any` is the same as setting it to + `on-failure`. + + Jobs are available in both replicated and global modes. + + #### Replicated Jobs + + A replicated job is like a replicated service. Setting the `--replicas` flag + will specify total number of iterations of a job to execute. + + By default, all replicas of a replicated job will launch at once. To control + the total number of replicas that are executing simultaneously at any one time, + the `--max-concurrent` flag can be used: + + ```bash + $ docker service create --name mythrottledjob \ + --mode replicated-job \ + --replicas 10 \ + --max-concurrent 2 \ + bash "true" + ``` + + The above command will execute 10 Tasks in total, but only 2 of them will be + run at any given time. + + #### Global Jobs + + Global jobs are like global services, in that a Task is executed once on each node + matching placement constraints. Global jobs are represented by the mode `global-job`. + + Note that after a Global job is created, any new Nodes added to the cluster + will have a Task from that job started on them. The Global Job does not as a + whole have a "done" state, except insofar as every Node meeting the job's + constraints has a Completed task. deprecated: false min_api_version: "1.24" experimental: false diff --git a/_data/engine-cli/docker_service_logs.yaml b/_data/engine-cli/docker_service_logs.yaml index 859e3750498e..29cd8214a618 100644 --- a/_data/engine-cli/docker_service_logs.yaml +++ b/_data/engine-cli/docker_service_logs.yaml @@ -114,13 +114,14 @@ options: - option: since value_type: string description: | - Show logs since timestamp (e.g. 2013-01-02T13:23:37) or relative (e.g. 42m for 42 minutes) + Show logs since timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: tail + shorthand: "n" value_type: string 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 d10b9824a384..b0886d216882 100644 --- a/_data/engine-cli/docker_service_ls.yaml +++ b/_data/engine-cli/docker_service_ls.yaml @@ -41,122 +41,51 @@ options: experimentalcli: false kubernetes: false swarm: false -examples: |- - On a manager node: - - ```bash - $ docker service ls - - ID NAME MODE REPLICAS IMAGE - c8wgl7q4ndfd frontend replicated 5/5 nginx:alpine - dmu1ept4cxcf redis replicated 3/3 redis:3.0.6 - iwe3278osahj mongo global 7/7 mongo:3.3 - ``` - - The `REPLICAS` column shows both the *actual* and *desired* number of tasks for - the service. - - ### 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](service_ls.md#id) - * [label](service_ls.md#label) - * [mode](service_ls.md#mode) - * [name](service_ls.md#name) - - #### id - - The `id` filter matches all or part of a service's id. - - ```bash - $ docker service ls -f "id=0bcjw" - ID NAME MODE REPLICAS IMAGE - 0bcjwfh8ychr redis replicated 1/1 redis:3.0.6 - ``` - - #### label - - The `label` filter matches services based on the presence of a `label` alone or - a `label` and a value. - - The following filter matches all services with a `project` label regardless of - its value: - - ```bash - $ docker service ls --filter label=project - ID NAME MODE REPLICAS IMAGE - 01sl1rp6nj5u frontend2 replicated 1/1 nginx:alpine - 36xvvwwauej0 frontend replicated 5/5 nginx:alpine - 74nzcxxjv6fq backend replicated 3/3 redis:3.0.6 - ``` - - The following filter matches only services with the `project` label with the - `project-a` value. - - ```bash - $ docker service ls --filter label=project=project-a - ID NAME MODE REPLICAS IMAGE - 36xvvwwauej0 frontend replicated 5/5 nginx:alpine - 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. - - The following filter matches services with a name containing `redis`. - - ```bash - $ docker service ls --filter name=redis - ID NAME MODE REPLICAS IMAGE - 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 - ``` +examples: "On a manager node:\n\n```bash\n$ docker service ls\n\nID NAME + \ MODE REPLICAS IMAGE\nc8wgl7q4ndfd frontend replicated + \ 5/5 nginx:alpine\ndmu1ept4cxcf redis replicated 3/3 + \ redis:3.0.6\niwe3278osahj mongo global 7/7 mongo:3.3\nhh08h9uu8uwr + \ job replicated-job 1/1 (3/5 completed) nginx:latest \n```\n\nThe + `REPLICAS` column shows both the *actual* and *desired* number of tasks for\nthe + service. If the service is in `replicated-job` or `global-job`, it will\nadditionally + show the completion status of the job as completed tasks over\ntotal tasks the job + will execute.\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](service_ls.md#id)\n* [label](service_ls.md#label)\n* [mode](service_ls.md#mode)\n* + [name](service_ls.md#name)\n\n#### id\n\nThe `id` filter matches all or part of + a service's id.\n\n```bash\n$ docker service ls -f \"id=0bcjw\"\nID NAME + \ MODE REPLICAS IMAGE\n0bcjwfh8ychr redis replicated 1/1 redis:3.0.6\n```\n\n#### + label\n\nThe `label` filter matches services based on the presence of a `label` + alone or\na `label` and a value.\n\nThe following filter matches all services with + a `project` label regardless of\nits value:\n\n```bash\n$ docker service ls --filter + label=project\nID NAME MODE REPLICAS IMAGE\n01sl1rp6nj5u + \ frontend2 replicated 1/1 nginx:alpine\n36xvvwwauej0 frontend replicated + \ 5/5 nginx:alpine\n74nzcxxjv6fq backend replicated 3/3 redis:3.0.6\n```\n\nThe + following filter matches only services with the `project` label with the\n`project-a` + value.\n\n```bash\n$ docker service ls --filter label=project=project-a\nID NAME + \ MODE REPLICAS IMAGE\n36xvvwwauej0 frontend replicated 5/5 nginx:alpine\n74nzcxxjv6fq + \ backend replicated 3/3 redis:3.0.6\n```\n\n#### mode\n\nThe `mode` filter + matches on the mode (either `replicated` or `global`) of a service.\n\nThe following + filter matches only `global` services.\n\n```bash\n$ docker service ls --filter + mode=global\nID NAME MODE REPLICAS + \ IMAGE\nw7y0v2yrn620 top global 1/1 + \ busybox\n```\n\n#### name\n\nThe `name` filter matches on all or + part of a service's name.\n\nThe following filter matches services with a name containing + `redis`.\n\n```bash\n$ docker service ls --filter name=redis\nID NAME + \ MODE REPLICAS IMAGE\n0bcjwfh8ychr redis replicated 1/1 redis:3.0.6\n```\n\n### + Formatting\n\nThe formatting options (`--format`) pretty-prints services output\nusing + a Go template.\n\nValid placeholders for the Go template are listed below:\n\nPlaceholder + | Description\n------------|------------------------------------------------------------------------------------------\n`.ID` + \ | Service ID\n`.Name` | Service name\n`.Mode` | Service mode (replicated, + global)\n`.Replicas` | Service replicas\n`.Image` | Service image\n`.Ports` | + Service ports published in ingress mode\n\nWhen using the `--format` option, the + `service 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`, `Mode`, and `Replicas` + entries separated by a colon (`:`) for all services:\n\n```bash\n$ docker service + ls --format \"{{.ID}}: {{.Mode}} {{.Replicas}}\"\n\n0zmvwuiu3vue: replicated 10/10\nfm6uf97exkul: + global 5/5\n```" deprecated: false min_api_version: "1.24" experimental: false diff --git a/_data/engine-cli/docker_service_scale.yaml b/_data/engine-cli/docker_service_scale.yaml index 23d9c04f1126..f385722311b7 100644 --- a/_data/engine-cli/docker_service_scale.yaml +++ b/_data/engine-cli/docker_service_scale.yaml @@ -49,7 +49,7 @@ examples: |- $ docker service scale backend=10 - backend: scale can only be used with replicated mode + backend: scale can only be used with replicated or replicated-job mode ``` Directly afterwards, run `docker service ls`, to see the actual number of diff --git a/_data/engine-cli/docker_service_update.yaml b/_data/engine-cli/docker_service_update.yaml index d67a6dba7786..a7a45b38cc5d 100644 --- a/_data/engine-cli/docker_service_update.yaml +++ b/_data/engine-cli/docker_service_update.yaml @@ -29,6 +29,24 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: cap-add + value_type: list + description: Add Linux capabilities + deprecated: false + min_api_version: "1.41" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: cap-drop + value_type: list + description: Drop Linux capabilities + deprecated: false + min_api_version: "1.41" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: config-add value_type: config description: Add or update a config file on a service @@ -366,6 +384,16 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: limit-pids + value_type: int64 + default_value: "0" + description: Limit maximum number of processes (default 0 = unlimited) + deprecated: false + min_api_version: "1.41" + experimental: false + experimentalcli: false + kubernetes: false + swarm: true - option: log-driver value_type: string description: Logging driver for service @@ -382,6 +410,16 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: max-concurrent + value_type: uint + description: | + Number of job tasks to run concurrently (default equal to --replicas) + deprecated: false + min_api_version: "1.41" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: mount-add value_type: mount description: Add or update a mount on a service @@ -693,6 +731,25 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: ulimit-add + value_type: ulimit + default_value: '[]' + description: Add or update a ulimit option + deprecated: false + min_api_version: "1.41" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: ulimit-rm + value_type: list + description: Remove a ulimit option + deprecated: false + min_api_version: "1.41" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: update-delay value_type: duration default_value: 0s @@ -953,6 +1010,23 @@ examples: |- `service update` supports the same `--isolation` flag as `service create` See [`service create`](service_create.md) for the reference. + + ### Updating Jobs + + When a service is created as a job, by setting its mode to `replicated-job` or + to `global-job` when doing `service create`, options for updating it are + limited. + + Updating a Job immediately stops any Tasks that are in progress. The operation + creates a new set of Tasks for the job and effectively resets its completion + status. If any Tasks were running before the update, they are stopped, and new + Tasks are created. + + Jobs cannot be rolled out or rolled back. None of the flags for configuring + update or rollback settings are valid with job modes. + + To run a job again with the same parameters that it was run previously, it can + be force updated with the `--force` flag. deprecated: false min_api_version: "1.24" experimental: false diff --git a/_data/engine-cli/docker_stack_deploy.yaml b/_data/engine-cli/docker_stack_deploy.yaml index e291ecab0876..a42d84d32dae 100644 --- a/_data/engine-cli/docker_stack_deploy.yaml +++ b/_data/engine-cli/docker_stack_deploy.yaml @@ -14,14 +14,6 @@ usage: docker stack deploy [OPTIONS] STACK pname: docker stack plink: docker_stack.yaml options: -- option: bundle-file - value_type: string - description: Path to a Distributed Application Bundle file - deprecated: false - experimental: true - experimentalcli: false - kubernetes: false - swarm: true - option: compose-file shorthand: c value_type: stringSlice @@ -157,34 +149,6 @@ examples: |- 9gc5m4met4he vossibility_logstash replicated 1/1 logstash@sha256:2dc8bddd1bb4a5a34e8ebaf73749f6413c101b2edef6617f2f7713926d2141fe axqh55ipl40h vossibility_vossibility-collector replicated 1/1 icecrime/vossibility-collector@sha256:f03f2977203ba6253988c18d04061c5ec7aab46bca9dfd89a9a1fa4500989fba ``` - - ### DAB file - - ```bash - $ docker stack deploy --bundle-file vossibility-stack.dab vossibility - - Loading bundle from vossibility-stack.dab - Creating service vossibility_elasticsearch - Creating service vossibility_kibana - Creating service vossibility_logstash - Creating service vossibility_lookupd - Creating service vossibility_nsqd - Creating service vossibility_vossibility-collector - ``` - - You can verify that the services were correctly created: - - ```bash - $ docker service ls - - ID NAME MODE REPLICAS IMAGE - 29bv0vnlm903 vossibility_lookupd replicated 1/1 nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662 - 4awt47624qwh vossibility_nsqd replicated 1/1 nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662 - 4tjx9biia6fs vossibility_elasticsearch replicated 1/1 elasticsearch@sha256:12ac7c6af55d001f71800b83ba91a04f716e58d82e748fa6e5a7359eed2301aa - 7563uuzr9eys vossibility_kibana replicated 1/1 kibana@sha256:6995a2d25709a62694a937b8a529ff36da92ebee74bafd7bf00e6caf6db2eb03 - 9gc5m4met4he vossibility_logstash replicated 1/1 logstash@sha256:2dc8bddd1bb4a5a34e8ebaf73749f6413c101b2edef6617f2f7713926d2141fe - axqh55ipl40h vossibility_vossibility-collector replicated 1/1 icecrime/vossibility-collector@sha256:f03f2977203ba6253988c18d04061c5ec7aab46bca9dfd89a9a1fa4500989fba - ``` deprecated: false min_api_version: "1.25" experimental: false diff --git a/_data/engine-cli/docker_start.yaml b/_data/engine-cli/docker_start.yaml index fe0567d0c937..0765be250e8e 100644 --- a/_data/engine-cli/docker_start.yaml +++ b/_data/engine-cli/docker_start.yaml @@ -51,10 +51,6 @@ options: experimentalcli: false kubernetes: false swarm: false -examples: |- - ```bash - $ docker start my_container - ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_stats.yaml b/_data/engine-cli/docker_stats.yaml index 190e0dfc65f2..407c517766b6 100644 --- a/_data/engine-cli/docker_stats.yaml +++ b/_data/engine-cli/docker_stats.yaml @@ -1,28 +1,6 @@ command: docker stats short: Display a live stream of container(s) resource usage statistics -long: |- - The `docker stats` command returns a live data stream for running containers. To - limit data to one or more specific containers, specify a list of container names - or ids separated by a space. You can specify a stopped container but stopped - containers do not return any data. - - If you need more detailed information about a container's resource usage, use - the `/containers/(id)/stats` API endpoint. - - > **Note** - > - > On Linux, the Docker CLI reports memory usage by subtracting page cache usage - > from the total memory usage. The API does not perform such a calculation but - > rather provides the total memory usage and the amount from the page cache so - > that clients can use the data as needed. - - > **Note** - > - > The `PIDS` column contains the number of processes and kernel threads created - > by that container. Threads is the term used by Linux kernel. Other equivalent - > terms are "lightweight process" or "kernel task", etc. A large number in the - > `PIDS` column combined with a small number of processes (as reported by `ps` - > or `top`) may indicate that something in the container is creating many threads. +long: Display a live stream of container(s) resource usage statistics usage: docker stats [OPTIONS] [CONTAINER...] pname: docker plink: docker.yaml @@ -63,136 +41,6 @@ options: experimentalcli: false kubernetes: false swarm: false -examples: |- - Running `docker stats` on all running containers against a Linux daemon. - - ```bash - $ docker stats - - CONTAINER ID NAME CPU % MEM USAGE / LIMIT MEM % NET I/O BLOCK I/O PIDS - b95a83497c91 awesome_brattain 0.28% 5.629MiB / 1.952GiB 0.28% 916B / 0B 147kB / 0B 9 - 67b2525d8ad1 foobar 0.00% 1.727MiB / 1.952GiB 0.09% 2.48kB / 0B 4.11MB / 0B 2 - e5c383697914 test-1951.1.kay7x1lh1twk9c0oig50sd5tr 0.00% 196KiB / 1.952GiB 0.01% 71.2kB / 0B 770kB / 0B 1 - 4bda148efbc0 random.1.vnc8on831idyr42slu578u3cr 0.00% 1.672MiB / 1.952GiB 0.08% 110kB / 0B 578kB / 0B 2 - ``` - - If you don't [specify a format string using `--format`](#formatting), the - following columns are shown. - - | Column name | Description | - |---------------------------|-----------------------------------------------------------------------------------------------| - | `CONTAINER ID` and `Name` | the ID and name of the container | - | `CPU %` and `MEM %` | the percentage of the host's CPU and memory the container is using | - | `MEM USAGE / LIMIT` | the total memory the container is using, and the total amount of memory it is allowed to use | - | `NET I/O` | The amount of data the container has sent and received over its network interface | - | `BLOCK I/O` | The amount of data the container has read to and written from block devices on the host | - | `PIDs` | the number of processes or threads the container has created | - - Running `docker stats` on multiple containers by name and id against a Linux daemon. - - ```bash - $ docker stats awesome_brattain 67b2525d8ad1 - - CONTAINER ID NAME CPU % MEM USAGE / LIMIT MEM % NET I/O BLOCK I/O PIDS - b95a83497c91 awesome_brattain 0.28% 5.629MiB / 1.952GiB 0.28% 916B / 0B 147kB / 0B 9 - 67b2525d8ad1 foobar 0.00% 1.727MiB / 1.952GiB 0.09% 2.48kB / 0B 4.11MB / 0B 2 - ``` - - Running `docker stats` with customized format on all (Running and Stopped) containers. - - ```bash - $ docker stats --all --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}" fervent_panini 5acfcb1b4fd1 drunk_visvesvaraya big_heisenberg - - CONTAINER CPU % MEM USAGE / LIMIT - fervent_panini 0.00% 56KiB / 15.57GiB - 5acfcb1b4fd1 0.07% 32.86MiB / 15.57GiB - drunk_visvesvaraya 0.00% 0B / 0B - 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 - PS E:\> docker stats - CONTAINER ID CPU % PRIV WORKING SET NET I/O BLOCK I/O - 09d3bb5b1604 6.61% 38.21 MiB 17.1 kB / 7.73 kB 10.7 MB / 3.57 MB - 9db7aa4d986d 9.19% 38.26 MiB 15.2 kB / 7.65 kB 10.6 MB / 3.3 MB - 3f214c61ad1d 0.00% 28.64 MiB 64 kB / 6.84 kB 4.42 MB / 6.93 MB - ``` - - Running `docker stats` on multiple containers by name and id against a Windows daemon. - - ```powershell - PS E:\> docker ps -a - CONTAINER ID NAME IMAGE COMMAND CREATED STATUS PORTS NAMES - 3f214c61ad1d awesome_brattain nanoserver "cmd" 2 minutes ago Up 2 minutes big_minsky - 9db7aa4d986d mad_wilson windowsservercore "cmd" 2 minutes ago Up 2 minutes mad_wilson - 09d3bb5b1604 fervent_panini windowsservercore "cmd" 2 minutes ago Up 2 minutes affectionate_easley - - PS E:\> docker stats 3f214c61ad1d mad_wilson - CONTAINER ID NAME CPU % PRIV WORKING SET NET I/O BLOCK I/O - 3f214c61ad1d awesome_brattain 0.00% 46.25 MiB 76.3 kB / 7.92 kB 10.3 MB / 14.7 MB - 9db7aa4d986d mad_wilson 9.59% 40.09 MiB 27.6 kB / 8.81 kB 17 MB / 20.1 MB - ``` - - ### Formatting - - The formatting option (`--format`) pretty prints container output - using a Go template. - - Valid placeholders for the Go template are listed below: - - Placeholder | Description - ------------ | -------------------------------------------- - `.Container` | Container name or ID (user input) - `.Name` | Container name - `.ID` | Container ID - `.CPUPerc` | CPU percentage - `.MemUsage` | Memory usage - `.NetIO` | Network IO - `.BlockIO` | Block IO - `.MemPerc` | Memory percentage (Not available on Windows) - `.PIDs` | Number of PIDs (Not available on Windows) - - - When using the `--format` option, the `stats` 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 - `Container` and `CPUPerc` entries separated by a colon (`:`) for all images: - - ```bash - $ docker stats --format "{{.Container}}: {{.CPUPerc}}" - - 09d3bb5b1604: 6.61% - 9db7aa4d986d: 9.19% - 3f214c61ad1d: 0.00% - ``` - - To list all containers statistics with their name, CPU percentage and memory - usage in a table format you can use: - - ```bash - $ docker stats --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}" - - CONTAINER CPU % PRIV WORKING SET - 1285939c1fd3 0.07% 796 KiB / 64 MiB - 9c76f7834ae2 0.07% 2.746 MiB / 64 MiB - d1ea048f04e4 0.03% 4.583 MiB / 64 MiB - ``` - - The default format is as follows: - - On Linux: - - "table {{.ID}}\t{{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.MemPerc}}\t{{.NetIO}}\t{{.BlockIO}}\t{{.PIDs}}" - - On Windows: - - "table {{.ID}}\t{{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.NetIO}}\t{{.BlockIO}}" deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_stop.yaml b/_data/engine-cli/docker_stop.yaml index 3d775e86e354..55cbe6c88b73 100644 --- a/_data/engine-cli/docker_stop.yaml +++ b/_data/engine-cli/docker_stop.yaml @@ -1,8 +1,6 @@ command: docker stop short: Stop one or more running containers -long: |- - The main process inside the container will receive `SIGTERM`, and after a grace - period, `SIGKILL`. +long: Stop one or more running containers usage: docker stop [OPTIONS] CONTAINER [CONTAINER...] pname: docker plink: docker.yaml @@ -17,10 +15,6 @@ options: experimentalcli: false kubernetes: false swarm: false -examples: |- - ```bash - $ docker stop my_container - ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_system_events.yaml b/_data/engine-cli/docker_system_events.yaml index 942ad3cf8b74..1e0af5962918 100644 --- a/_data/engine-cli/docker_system_events.yaml +++ b/_data/engine-cli/docker_system_events.yaml @@ -1,8 +1,13 @@ command: docker system events short: 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. + Use `docker events` to get real-time events from the server. These events differ + per Docker object type. Different event types have different scopes. Local + scoped events are only seen on the node they take place on, and swarm scoped + events are seen on all managers. + + Only the last 1000 log events are returned. You can use filters to further limit + the number of events returned. ### Object types @@ -19,6 +24,7 @@ long: |- - `die` - `exec_create` - `exec_detach` + - `exec_die` - `exec_start` - `export` - `health_status` @@ -51,9 +57,9 @@ long: |- Docker plugins report the following events: - - `install` - `enable` - `disable` + - `install` - `remove` #### Volumes @@ -61,9 +67,9 @@ long: |- Docker volumes report the following events: - `create` + - `destroy` - `mount` - `unmount` - - `destroy` #### Networks @@ -71,8 +77,9 @@ long: |- - `create` - `connect` - - `disconnect` - `destroy` + - `disconnect` + - `remove` #### Daemons @@ -80,6 +87,38 @@ long: |- - `reload` + #### Services + + Docker services report the following events: + + - `create` + - `remove` + - `update` + + #### Nodes + + Docker nodes report the following events: + + - `create` + - `remove` + - `update` + + #### Secrets + + Docker secrets report the following events: + + - `create` + - `remove` + - `update` + + #### Configs + + Docker configs report the following events: + + - `create` + - `remove` + - `update` + ### Limiting, filtering, and formatting the output #### Limit events by time @@ -97,6 +136,9 @@ 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. + Only the last 1000 log events are returned. You can use filters to further limit + the number of events returned. + #### Filtering The filtering flag (`-f` or `--filter`) format is of "key=value". If you would @@ -113,15 +155,20 @@ long: |- The currently supported filters are: + * config (`config=`) * container (`container=`) * daemon (`daemon=`) * event (`event=`) - * image (`image=`) + * image (`image=`) * label (`label=` or `label==`) * network (`network=`) + * node (`node=`) * plugin (`plugin=`) - * type (`type=`) - * volume (`volume=`) + * scope (`scope=`) + * secret (`secret=`) + * service (`service=`) + * type (`type=`) + * volume (`volume=`) #### Format @@ -131,7 +178,7 @@ long: |- 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/ . + Lines. For information about JSON Lines, please refer to http://jsonlines.org/. usage: docker system events [OPTIONS] pname: docker system plink: docker_system.yaml @@ -177,7 +224,7 @@ examples: |- **Shell 1: Listening for events:** ```bash - $ docker system events + $ docker events ``` **Shell 2: Start and Stop containers:** @@ -200,7 +247,7 @@ examples: |- 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`. + To exit the `docker events` command, use `CTRL+C`. ### Filter events by time @@ -208,8 +255,7 @@ examples: |- machine, using the following different time syntaxes: ```bash - $ docker system events --since 1483283804 - + $ docker 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) @@ -219,8 +265,7 @@ examples: |- 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' - + $ docker 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) @@ -230,8 +275,7 @@ examples: |- 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' - + $ docker 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) @@ -241,8 +285,7 @@ examples: |- 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' - + $ docker 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) @@ -251,6 +294,12 @@ examples: |- 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 events --since '2017-01-05T00:35:30' --until '2017-01-05T00:36: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) ``` ### Filter events by criteria @@ -259,12 +308,12 @@ examples: |- output. ```bash - $ docker system events --filter 'event=stop' + $ docker 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' + $ docker 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) @@ -273,14 +322,14 @@ examples: |- 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' + $ docker 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' + $ docker 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) @@ -288,51 +337,74 @@ examples: |- 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' + $ docker 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' + $ docker 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' + $ docker 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' + $ docker 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' + $ docker 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' + $ docker 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' + $ docker events --filter 'type=plugin' 2016-07-25T17:30:14.825557616Z plugin pull ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest) 2016-07-25T17:30:14.888127370Z plugin enable ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest) + + $ docker events -f type=service + + 2017-07-12T06:34:07.999446625Z service create wj64st89fzgchxnhiqpn8p4oj (name=reverent_albattani) + 2017-07-12T06:34:21.405496207Z service remove wj64st89fzgchxnhiqpn8p4oj (name=reverent_albattani) + + $ docker events -f type=node + + 2017-07-12T06:21:51.951586759Z node update 3xyz5ttp1a253q74z1thwywk9 (name=ip-172-31-23-42, state.new=ready, state.old=unknown) + + $ docker events -f type=secret + + 2017-07-12T06:32:13.915704367Z secret create s8o6tmlnndrgzbmdilyy5ymju (name=new_secret) + 2017-07-12T06:32:37.052647783Z secret remove s8o6tmlnndrgzbmdilyy5ymju (name=new_secret) + + $ docker events -f type=config + 2017-07-12T06:44:13.349037127Z config create u96zlvzdfsyb9sg4mhyxfh3rl (name=abc) + 2017-07-12T06:44:36.327694184Z config remove u96zlvzdfsyb9sg4mhyxfh3rl (name=abc) + + $ docker events --filter 'scope=swarm' + + 2017-07-10T07:46:50.250024503Z service create m8qcxu8081woyof7w3jaax6gk (name=affectionate_wilson) + 2017-07-10T07:47:31.093797134Z secret create 6g5pufzsv438p9tbvl9j94od4 (name=new_secret) ``` ### Format the output ```bash - $ docker system events --filter 'type=container' --format 'Type={{.Type}} Status={{.Status}} ID={{.ID}}' + $ docker events --filter 'type=container' --format 'Type={{.Type}} Status={{.Status}} ID={{.ID}}' Type=container Status=create ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 Type=container Status=attach ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26 @@ -345,7 +417,7 @@ examples: |- #### Format as JSON ```bash - $ docker system events --format '{{json .}}' + $ docker events --format '{{json .}}' {"status":"create","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. {"status":"attach","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. diff --git a/_data/engine-cli/docker_system_info.yaml b/_data/engine-cli/docker_system_info.yaml index 9662751bf0d5..76522319c70a 100644 --- a/_data/engine-cli/docker_system_info.yaml +++ b/_data/engine-cli/docker_system_info.yaml @@ -1,6 +1,23 @@ command: docker system info short: Display system-wide information -long: Display system-wide information +long: |- + This command displays system wide information regarding the Docker installation. + Information displayed includes the kernel version, number of containers and images. + The number of images shown is the number of unique images. The same image tagged + under different names is counted only once. + + If a 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. + + Depending on the storage driver in use, additional information can be shown, such + as pool name, data file, metadata file, data space used, total data space, metadata + space used, and total metadata space. + + The data file is where the images are stored and the metadata file is where the + meta data regarding those images are stored. When run for the first time Docker + allocates a certain amount of data space and meta data space from the space + available on the volume where `/var/lib/docker` is mounted. usage: docker system info [OPTIONS] pname: docker system plink: docker_system.yaml @@ -14,6 +31,212 @@ options: experimentalcli: false kubernetes: false swarm: false +examples: |- + ### Show output + + The example below shows the output for a daemon running on Red Hat Enterprise Linux, + using the `devicemapper` storage driver. As can be seen in the output, additional + information about the `devicemapper` storage driver is shown: + + ```bash + $ docker info + Client: + Context: default + Debug Mode: false + + Server: + Containers: 14 + Running: 3 + Paused: 1 + Stopped: 10 + Images: 52 + Server Version: 1.10.3 + Storage Driver: devicemapper + Pool Name: docker-202:2-25583803-pool + Pool Blocksize: 65.54 kB + Base Device Size: 10.74 GB + Backing Filesystem: xfs + Data file: /dev/loop0 + Metadata file: /dev/loop1 + Data Space Used: 1.68 GB + Data Space Total: 107.4 GB + Data Space Available: 7.548 GB + Metadata Space Used: 2.322 MB + Metadata Space Total: 2.147 GB + Metadata Space Available: 2.145 GB + Udev Sync Supported: true + Deferred Removal Enabled: false + Deferred Deletion Enabled: false + Deferred Deleted Device Count: 0 + Data loop file: /var/lib/docker/devicemapper/devicemapper/data + Metadata loop file: /var/lib/docker/devicemapper/devicemapper/metadata + Library Version: 1.02.107-RHEL7 (2015-12-01) + Execution Driver: native-0.2 + Logging Driver: json-file + Plugins: + Volume: local + Network: null host bridge + Kernel Version: 3.10.0-327.el7.x86_64 + Operating System: Red Hat Enterprise Linux Server 7.2 (Maipo) + OSType: linux + Architecture: x86_64 + CPUs: 1 + Total Memory: 991.7 MiB + Name: ip-172-30-0-91.ec2.internal + ID: I54V:OLXT:HVMM:TPKO:JPHQ:CQCD:JNLC:O3BZ:4ZVJ:43XJ:PFHZ:6N2S + Docker Root Dir: /var/lib/docker + Debug Mode: false + Username: gordontheturtle + Registry: https://index.docker.io/v1/ + Insecure registries: + myinsecurehost:5000 + 127.0.0.0/8 + ``` + + ### Show debugging output + + Here is a sample output for a daemon running on Ubuntu, using the overlay2 + storage driver and a node that is part of a 2-node swarm: + + ```bash + $ docker -D info + Client: + Context: default + Debug Mode: true + + Server: + Containers: 14 + Running: 3 + Paused: 1 + Stopped: 10 + Images: 52 + Server Version: 1.13.0 + Storage Driver: overlay2 + Backing Filesystem: extfs + Supports d_type: true + Native Overlay Diff: false + Logging Driver: json-file + Cgroup Driver: cgroupfs + Plugins: + Volume: local + Network: bridge host macvlan null overlay + Swarm: active + NodeID: rdjq45w1op418waxlairloqbm + Is Manager: true + ClusterID: te8kdyw33n36fqiz74bfjeixd + Managers: 1 + Nodes: 2 + Orchestration: + Task History Retention Limit: 5 + Raft: + Snapshot Interval: 10000 + Number of Old Snapshots to Retain: 0 + Heartbeat Tick: 1 + Election Tick: 3 + Dispatcher: + 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 + Runtimes: runc + Default Runtime: runc + Init Binary: docker-init + containerd version: 8517738ba4b82aff5662c97ca4627e7e4d03b531 + runc version: ac031b5bf1cc92239461125f4c1ffb760522bbf2 + init version: N/A (expected: v0.13.0) + Security Options: + apparmor + seccomp + Profile: default + Kernel Version: 4.4.0-31-generic + Operating System: Ubuntu 16.04.1 LTS + OSType: linux + Architecture: x86_64 + CPUs: 2 + Total Memory: 1.937 GiB + Name: ubuntu + ID: H52R:7ZR6:EIIA:76JG:ORIY:BVKF:GSFU:HNPG:B5MK:APSC:SZ3Q:N326 + Docker Root Dir: /var/lib/docker + Debug Mode: true + File Descriptors: 30 + Goroutines: 123 + System Time: 2016-11-12T17:24:37.955404361-08:00 + EventsListeners: 0 + Http Proxy: http://test:test@proxy.example.com:8080 + Https Proxy: https://test:test@proxy.example.com:8080 + No Proxy: localhost,127.0.0.1,docker-registry.somecorporation.com + Registry: https://index.docker.io/v1/ + WARNING: No swap limit support + Labels: + storage=ssd + staging=true + Experimental: false + Insecure Registries: + 127.0.0.0/8 + Registry Mirrors: + http://192.168.1.2/ + http://registry-mirror.example.com:5000/ + Live Restore Enabled: false + ``` + + The global `-D` option causes all `docker` commands to output debug information. + + ### Format the output + + You can also specify the output format: + + ```bash + $ docker info --format '{{json .}}' + + {"ID":"I54V:OLXT:HVMM:TPKO:JPHQ:CQCD:JNLC:O3BZ:4ZVJ:43XJ:PFHZ:6N2S","Containers":14, ...} + ``` + + ### Run `docker info` on Windows + + Here is a sample output for a daemon running on Windows Server 2016: + + ```console + E:\docker>docker info + Client: + Context: default + Debug Mode: false + + Server: + Containers: 1 + Running: 0 + Paused: 0 + Stopped: 1 + Images: 17 + Server Version: 1.13.0 + Storage Driver: windowsfilter + Windows: + Logging Driver: json-file + Plugins: + Volume: local + Network: nat null overlay + Swarm: inactive + Default Isolation: process + Kernel Version: 10.0 14393 (14393.206.amd64fre.rs1_release.160912-1937) + Operating System: Windows Server 2016 Datacenter + OSType: windows + Architecture: x86_64 + CPUs: 8 + Total Memory: 3.999 GiB + Name: WIN-V0V70C0LU5P + ID: NYMS:B5VK:UMSL:FVDZ:EWB5:FKVK:LPFL:FJMQ:H6FT:BZJ6:L2TD:XH62 + Docker Root Dir: C:\control + Debug Mode: false + Registry: https://index.docker.io/v1/ + Insecure Registries: + 127.0.0.0/8 + Registry Mirrors: + http://192.168.1.2/ + http://registry-mirror.example.com:5000/ + Live Restore Enabled: false + ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_tag.yaml b/_data/engine-cli/docker_tag.yaml index 0ee4da089110..32d8c71d0e22 100644 --- a/_data/engine-cli/docker_tag.yaml +++ b/_data/engine-cli/docker_tag.yaml @@ -1,63 +1,9 @@ command: docker tag short: Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE -long: |- - An image name is made up of slash-separated name components, optionally prefixed - by a registry hostname. The hostname must comply with standard DNS rules, but - may not contain underscores. If a hostname is present, it may optionally be - followed by a port number in the format `:8080`. If not present, the command - uses Docker's public registry located at `registry-1.docker.io` by default. Name - components may contain lowercase letters, digits and separators. A separator - is defined as a period, one or two underscores, or one or more dashes. A name - component may not start or end with a separator. - - A tag name must be valid ASCII and may contain lowercase and uppercase letters, - digits, underscores, periods and dashes. A tag name may not start with a - period or a dash and may contain a maximum of 128 characters. - - You can group your images together using names and tags, and then upload them - to [*Share images on Docker Hub*](https://docs.docker.com/get-started/part3/). +long: Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE usage: docker tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG] pname: docker plink: docker.yaml -examples: |- - ### Tag an image referenced by ID - - To tag a local image with ID "0e5574283393" into the "fedora" repository with - "version1.0": - - ```bash - $ docker tag 0e5574283393 fedora/httpd:version1.0 - ``` - - ### Tag an image referenced by Name - - To tag a local image with name "httpd" into the "fedora" repository with - "version1.0": - - ```bash - $ docker tag httpd fedora/httpd:version1.0 - ``` - - Note that since the tag name is not specified, the alias is created for an - existing local version `httpd:latest`. - - ### Tag an image referenced by Name and Tag - - To tag a local image with name "httpd" and tag "test" into the "fedora" - repository with "version1.0.test": - - ```bash - $ docker tag httpd:test fedora/httpd:version1.0.test - ``` - - ### Tag an image for a private repository - - To push an image to a private registry and not the central Docker - registry you must tag it with the registry hostname and port (if needed). - - ```bash - $ docker tag 0e5574283393 myregistryhost:5000/fedora/httpd:version1.0 - ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_unpause.yaml b/_data/engine-cli/docker_unpause.yaml index a1221d2768ba..04999fad33ae 100644 --- a/_data/engine-cli/docker_unpause.yaml +++ b/_data/engine-cli/docker_unpause.yaml @@ -1,20 +1,9 @@ command: docker unpause short: Unpause all processes within one or more containers -long: |- - The `docker unpause` command un-suspends all processes in the specified containers. - On Linux, it does this using the freezer cgroup. - - See the - [freezer cgroup documentation](https://www.kernel.org/doc/Documentation/cgroup-v1/freezer-subsystem.txt) - for further details. +long: Unpause all processes within one or more containers usage: docker unpause CONTAINER [CONTAINER...] pname: docker plink: docker.yaml -examples: |- - ```bash - $ docker unpause my_container - my_container - ``` deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_update.yaml b/_data/engine-cli/docker_update.yaml index a76196a8735a..aa2c44cddd09 100644 --- a/_data/engine-cli/docker_update.yaml +++ b/_data/engine-cli/docker_update.yaml @@ -1,22 +1,6 @@ command: docker update short: Update configuration of one or more containers -long: |- - The `docker update` command dynamically updates container configuration. - You can use this command to prevent containers from consuming too many - resources from their Docker host. With a single command, you can place - limits on a single container or on many. To specify more than one container, - provide space-separated list of container names or IDs. - - With the exception of the `--kernel-memory` option, you can specify these - options on a running or a stopped container. On kernel version older than - 4.6, you can only update `--kernel-memory` on a stopped container or on - a running container with kernel memory initialized. - - > **Warning** - > - > The `docker update` and `docker container update` commands are not supported - > for Windows containers. - {: .warning } +long: Update configuration of one or more containers usage: docker update [OPTIONS] CONTAINER [CONTAINER...] pname: docker plink: docker.yaml @@ -160,75 +144,6 @@ options: experimentalcli: false kubernetes: false swarm: false -examples: |- - The following sections illustrate ways to use this command. - - ### Update a container's cpu-shares - - To limit a container's cpu-shares to 512, first identify the container - name or ID. You can use `docker ps` to find these values. You can also - use the ID returned from the `docker run` command. Then, do the following: - - ```bash - $ docker update --cpu-shares 512 abebf7571666 - ``` - - ### Update a container with cpu-shares and memory - - To update multiple resource configurations for multiple containers: - - ```bash - $ docker update --cpu-shares 512 -m 300M abebf7571666 hopeful_morse - ``` - - ### Update a container's kernel memory constraints - - You can update a container's kernel memory limit using the `--kernel-memory` - option. On kernel version older than 4.6, this option can be updated on a - running container only if the container was started with `--kernel-memory`. - If the container was started *without* `--kernel-memory` you need to stop - the container before updating kernel memory. - - For example, if you started a container with this command: - - ```bash - $ docker run -dit --name test --kernel-memory 50M ubuntu bash - ``` - - You can update kernel memory while the container is running: - - ```bash - $ docker update --kernel-memory 80M test - ``` - - If you started a container *without* kernel memory initialized: - - ```bash - $ docker run -dit --name test2 --memory 300M ubuntu bash - ``` - - Update kernel memory of running container `test2` will fail. You need to stop - the container before updating the `--kernel-memory` setting. The next time you - start it, the container uses the new value. - - Kernel version newer than (include) 4.6 does not have this limitation, you - can use `--kernel-memory` the same way as other options. - - ### Update a container's restart policy - - You can change a container's restart policy on a running container. The new - restart policy takes effect instantly after you run `docker update` on a - container. - - To update restart policy for one or more containers: - - ```bash - $ docker update --restart=on-failure:3 abebf7571666 hopeful_morse - ``` - - Note that if the container is started with "--rm" flag, you cannot update the restart - policy for it. The `AutoRemove` and `RestartPolicy` are mutually exclusive for the - container. deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_version.yaml b/_data/engine-cli/docker_version.yaml index de9aa0ac2270..90e72519fad1 100644 --- a/_data/engine-cli/docker_version.yaml +++ b/_data/engine-cli/docker_version.yaml @@ -40,6 +40,7 @@ examples: |- Git commit: afacb8b Built: Wed Mar 11 01:21:11 2020 OS/Arch: darwin/amd64 + Context: default Experimental: true Server: @@ -77,6 +78,50 @@ examples: |- {"Client":{"Platform":{"Name":"Docker Engine - Community"},"Version":"19.03.8","ApiVersion":"1.40","DefaultAPIVersion":"1.40","GitCommit":"afacb8b","GoVersion":"go1.12.17","Os":"darwin","Arch":"amd64","BuildTime":"Wed Mar 11 01:21:11 2020","Experimental":true},"Server":{"Platform":{"Name":"Docker Engine - Community"},"Components":[{"Name":"Engine","Version":"19.03.8","Details":{"ApiVersion":"1.40","Arch":"amd64","BuildTime":"Wed Mar 11 01:29:16 2020","Experimental":"true","GitCommit":"afacb8b","GoVersion":"go1.12.17","KernelVersion":"4.19.76-linuxkit","MinAPIVersion":"1.12","Os":"linux"}},{"Name":"containerd","Version":"v1.2.13","Details":{"GitCommit":"7ad184331fa3e55e52b890ea95e65ba581ae3429"}},{"Name":"runc","Version":"1.0.0-rc10","Details":{"GitCommit":"dc9208a3303feef5b3839f4323d9beb36df0a9dd"}},{"Name":"docker-init","Version":"0.18.0","Details":{"GitCommit":"fec3683"}}],"Version":"19.03.8","ApiVersion":"1.40","MinAPIVersion":"1.12","GitCommit":"afacb8b","GoVersion":"go1.12.17","Os":"linux","Arch":"amd64","KernelVersion":"4.19.76-linuxkit","Experimental":true,"BuildTime":"2020-03-11T01:29:16.000000000+00:00"}} ``` + + ### Print the current context + + The following example prints the currently used [`docker context`](context.md): + + ```bash + $ docker version --format='{{.Client.Context}}' + default + ``` + + As an example, this output can be used to dynamically change your shell prompt + to indicate your active context. The example below illustrates how this output + could be used when using Bash as your shell. + + Declare a function to obtain the current context in your `~/.bashrc`, and set + this command as your `PROMPT_COMMAND` + + ```bash + function docker_context_prompt() { + PS1="context: $(docker version --format='{{.Client.Context}}')> " + } + + PROMPT_COMMAND=docker_context_prompt + ``` + + After reloading the `~/.bashrc`, the prompt now shows the currently selected + `docker context`: + + ```bash + $ source ~/.bashrc + context: default> docker context create --docker host=unix:///var/run/docker.sock my-context + my-context + Successfully created context "my-context" + context: default> docker context use my-context + my-context + Current context is now "my-context" + context: my-context> docker context use default + default + Current context is now "default" + context: default> + ``` + + Refer to the [`docker context` section](context.md) in the command line reference + for more information about `docker context`. deprecated: false experimental: false experimentalcli: false diff --git a/_data/engine-cli/docker_wait.yaml b/_data/engine-cli/docker_wait.yaml index 745c76f1f33e..4ea1b46cac44 100644 --- a/_data/engine-cli/docker_wait.yaml +++ b/_data/engine-cli/docker_wait.yaml @@ -4,34 +4,6 @@ long: Block until one or more containers stop, then print their exit codes usage: docker wait CONTAINER [CONTAINER...] pname: docker plink: docker.yaml -examples: |- - Start a container in the background. - - ```bash - $ docker run -dit --name=my_container ubuntu bash - ``` - - Run `docker wait`, which should block until the container exits. - - ```bash - $ docker wait my_container - ``` - - In another terminal, stop the first container. The `docker wait` command above - returns the exit code. - - ```bash - $ docker stop my_container - ``` - - This is the same `docker wait` command from above, but it now exits, returning - `0`. - - ```bash - $ docker wait my_container - - 0 - ``` deprecated: false experimental: false experimentalcli: false diff --git a/engine/reference/commandline/attach.md b/engine/reference/commandline/attach.md deleted file mode 100644 index 9a1bfdd2c7f9..000000000000 --- a/engine/reference/commandline/attach.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -datafolder: engine-cli -datafile: docker_attach -title: docker attach -redirect_from: - - /edge/engine/reference/commandline/attach/ -skip_read_time: true ---- - - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/build.md b/engine/reference/commandline/build.md deleted file mode 100644 index a5bf8c658f98..000000000000 --- a/engine/reference/commandline/build.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -datafolder: engine-cli -datafile: docker_build -title: docker build -redirect_from: - - /edge/engine/reference/commandline/build/ -skip_read_time: true ---- - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/commit.md b/engine/reference/commandline/commit.md deleted file mode 100644 index 7c0a93bd68d9..000000000000 --- a/engine/reference/commandline/commit.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -datafolder: engine-cli -datafile: docker_commit -title: docker commit -redirect_from: - - /edge/engine/reference/commandline/commit/ -skip_read_time: true ---- - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/container_attach.md b/engine/reference/commandline/container_attach.md index bf06f6492947..879a00b0502d 100644 --- a/engine/reference/commandline/container_attach.md +++ b/engine/reference/commandline/container_attach.md @@ -1,9 +1,10 @@ --- datafolder: engine-cli datafile: docker_container_attach -title: docker container attach +title: docker attach / docker container attach redirect_from: - /edge/engine/reference/commandline/container_attach/ + - /engine/reference/commandline/attach/ skip_read_time: true --- -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/create.md b/engine/reference/commandline/create.md deleted file mode 100644 index 46d7b638f806..000000000000 --- a/engine/reference/commandline/create.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -datafolder: engine-cli -datafile: docker_create -title: docker create -redirect_from: - - /edge/engine/reference/commandline/create/ -skip_read_time: true ---- - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/diff.md b/engine/reference/commandline/diff.md deleted file mode 100644 index 124bbcec68ef..000000000000 --- a/engine/reference/commandline/diff.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -datafolder: engine-cli -datafile: docker_diff -title: docker diff -redirect_from: - - /edge/engine/reference/commandline/diff/ -skip_read_time: true ---- - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/events.md b/engine/reference/commandline/events.md deleted file mode 100644 index dff38e20e2a4..000000000000 --- a/engine/reference/commandline/events.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -datafolder: engine-cli -datafile: docker_events -title: docker events -redirect_from: - - /edge/engine/reference/commandline/events/ -skip_read_time: true ---- - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/exec.md b/engine/reference/commandline/exec.md deleted file mode 100644 index 4a4716b43704..000000000000 --- a/engine/reference/commandline/exec.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -datafolder: engine-cli -datafile: docker_exec -title: docker exec -redirect_from: - - /edge/engine/reference/commandline/exec/ -skip_read_time: true ---- - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/export.md b/engine/reference/commandline/export.md deleted file mode 100644 index 5152f2365661..000000000000 --- a/engine/reference/commandline/export.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -datafolder: engine-cli -datafile: docker_export -title: docker export -redirect_from: - - /edge/engine/reference/commandline/export/ -skip_read_time: true ---- - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/history.md b/engine/reference/commandline/history.md deleted file mode 100644 index b97b7c12985b..000000000000 --- a/engine/reference/commandline/history.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -datafolder: engine-cli -datafile: docker_history -title: docker history -redirect_from: - - /edge/engine/reference/commandline/history/ -skip_read_time: true ---- - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/image_build.md b/engine/reference/commandline/image_build.md index e2f583e9b247..5d9e0365ddda 100644 --- a/engine/reference/commandline/image_build.md +++ b/engine/reference/commandline/image_build.md @@ -1,9 +1,10 @@ --- datafolder: engine-cli datafile: docker_image_build -title: docker image build +title: docker build / docker image build redirect_from: - /edge/engine/reference/commandline/image_build/ + - /engine/reference/commandline/build/ skip_read_time: true --- -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/import.md b/engine/reference/commandline/import.md deleted file mode 100644 index 72f125ea1be5..000000000000 --- a/engine/reference/commandline/import.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -datafolder: engine-cli -datafile: docker_import -title: docker import -redirect_from: - - /edge/engine/reference/commandline/import/ -skip_read_time: true ---- - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/kill.md b/engine/reference/commandline/kill.md deleted file mode 100644 index 6212a06de7d9..000000000000 --- a/engine/reference/commandline/kill.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -datafolder: engine-cli -datafile: docker_kill -title: docker kill -redirect_from: - - /edge/engine/reference/commandline/kill/ -skip_read_time: true ---- - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/load.md b/engine/reference/commandline/load.md deleted file mode 100644 index 76305e96bca0..000000000000 --- a/engine/reference/commandline/load.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -datafolder: engine-cli -datafile: docker_load -title: docker load -redirect_from: - - /edge/engine/reference/commandline/load/ -skip_read_time: true ---- - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/logs.md b/engine/reference/commandline/logs.md deleted file mode 100644 index b1c6f077801a..000000000000 --- a/engine/reference/commandline/logs.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -datafolder: engine-cli -datafile: docker_logs -title: docker logs -redirect_from: - - /edge/engine/reference/commandline/logs/ -skip_read_time: true ---- - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/pause.md b/engine/reference/commandline/pause.md deleted file mode 100644 index 130c076cb97d..000000000000 --- a/engine/reference/commandline/pause.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -datafolder: engine-cli -datafile: docker_pause -title: docker pause -redirect_from: - - /edge/engine/reference/commandline/pause/ -skip_read_time: true ---- - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/port.md b/engine/reference/commandline/port.md deleted file mode 100644 index ae2d44f37dde..000000000000 --- a/engine/reference/commandline/port.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -datafolder: engine-cli -datafile: docker_port -title: docker port -redirect_from: - - /edge/engine/reference/commandline/port/ -skip_read_time: true ---- - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/ps.md b/engine/reference/commandline/ps.md deleted file mode 100644 index d09d9696ff6a..000000000000 --- a/engine/reference/commandline/ps.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -datafolder: engine-cli -datafile: docker_ps -title: docker ps -redirect_from: - - /edge/engine/reference/commandline/ps/ -skip_read_time: true ---- - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/pull.md b/engine/reference/commandline/pull.md deleted file mode 100644 index 07e5638505e5..000000000000 --- a/engine/reference/commandline/pull.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -datafolder: engine-cli -datafile: docker_pull -title: docker pull -redirect_from: - - /edge/engine/reference/commandline/pull/ -skip_read_time: true ---- - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/push.md b/engine/reference/commandline/push.md deleted file mode 100644 index f21fc7e92926..000000000000 --- a/engine/reference/commandline/push.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -datafolder: engine-cli -datafile: docker_push -title: docker push -redirect_from: - - /edge/engine/reference/commandline/push/ -skip_read_time: true ---- - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/rename.md b/engine/reference/commandline/rename.md deleted file mode 100644 index e9e4c6dc0682..000000000000 --- a/engine/reference/commandline/rename.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -datafolder: engine-cli -datafile: docker_rename -title: docker rename -redirect_from: - - /edge/engine/reference/commandline/rename/ -skip_read_time: true ---- - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/restart.md b/engine/reference/commandline/restart.md deleted file mode 100644 index 1636a7dc324b..000000000000 --- a/engine/reference/commandline/restart.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -datafolder: engine-cli -datafile: docker_restart -title: docker restart -redirect_from: - - /edge/engine/reference/commandline/restart/ -skip_read_time: true ---- - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/rm.md b/engine/reference/commandline/rm.md deleted file mode 100644 index 21690804a824..000000000000 --- a/engine/reference/commandline/rm.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -datafolder: engine-cli -datafile: docker_rm -title: docker rm -redirect_from: - - /edge/engine/reference/commandline/rm/ -skip_read_time: true ---- - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/rmi.md b/engine/reference/commandline/rmi.md deleted file mode 100644 index 436ba45c25f5..000000000000 --- a/engine/reference/commandline/rmi.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -datafolder: engine-cli -datafile: docker_rmi -title: docker rmi -redirect_from: - - /edge/engine/reference/commandline/rmi/ -skip_read_time: true ---- - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/run.md b/engine/reference/commandline/run.md deleted file mode 100644 index 5e1e6964e970..000000000000 --- a/engine/reference/commandline/run.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -datafolder: engine-cli -datafile: docker_run -title: docker run -redirect_from: - - /reference/run - - /edge/engine/reference/commandline/run/ -skip_read_time: true ---- - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/save.md b/engine/reference/commandline/save.md deleted file mode 100644 index 59e52c8e2130..000000000000 --- a/engine/reference/commandline/save.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -datafolder: engine-cli -datafile: docker_save -title: docker save -redirect_from: - - /edge/engine/reference/commandline/save/ -skip_read_time: true ---- - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/start.md b/engine/reference/commandline/start.md deleted file mode 100644 index 68f2b7119168..000000000000 --- a/engine/reference/commandline/start.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -datafolder: engine-cli -datafile: docker_start -title: docker start -redirect_from: - - /edge/engine/reference/commandline/start/ -skip_read_time: true ---- - - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/stats.md b/engine/reference/commandline/stats.md deleted file mode 100644 index d8b4f67de7c0..000000000000 --- a/engine/reference/commandline/stats.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -datafolder: engine-cli -datafile: docker_stats -title: docker stats -redirect_from: - - /edge/engine/reference/commandline/stats/ -skip_read_time: true ---- - - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/stop.md b/engine/reference/commandline/stop.md deleted file mode 100644 index 3c6cbec77d96..000000000000 --- a/engine/reference/commandline/stop.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -datafolder: engine-cli -datafile: docker_stop -title: docker stop -redirect_from: - - /edge/engine/reference/commandline/stop/ -skip_read_time: true ---- - - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/system_events.md b/engine/reference/commandline/system_events.md index ea4b4499ee92..de552cd5f0ca 100644 --- a/engine/reference/commandline/system_events.md +++ b/engine/reference/commandline/system_events.md @@ -1,9 +1,10 @@ --- datafolder: engine-cli datafile: docker_system_events -title: docker system events +title: docker events / docker system events redirect_from: - /edge/engine/reference/commandline/system_events/ + - /engine/reference/commandline/events/ skip_read_time: true --- - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/top.md b/engine/reference/commandline/top.md deleted file mode 100644 index 566bdd1284c1..000000000000 --- a/engine/reference/commandline/top.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -datafolder: engine-cli -datafile: docker_top -title: docker top -redirect_from: - - /edge/engine/reference/commandline/top/ -skip_read_time: true ---- - - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/unpause.md b/engine/reference/commandline/unpause.md deleted file mode 100644 index 4b84ffe282cb..000000000000 --- a/engine/reference/commandline/unpause.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -datafolder: engine-cli -datafile: docker_unpause -title: docker unpause -redirect_from: - - /edge/engine/reference/commandline/unpause/ -skip_read_time: true ---- - - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/update.md b/engine/reference/commandline/update.md deleted file mode 100644 index 09229d3d178e..000000000000 --- a/engine/reference/commandline/update.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -datafolder: engine-cli -datafile: docker_update -title: docker update -redirect_from: - - /edge/engine/reference/commandline/update/ -skip_read_time: true ---- - - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/wait.md b/engine/reference/commandline/wait.md deleted file mode 100644 index ab08240175b1..000000000000 --- a/engine/reference/commandline/wait.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -datafolder: engine-cli -datafile: docker_wait -title: docker wait -redirect_from: - - /edge/engine/reference/commandline/wait/ -skip_read_time: true ---- - - -{% include cli.md datafolder=page.datafolder datafile=page.datafile %}