diff --git a/docs/reference/commandline/attach.md b/docs/reference/commandline/attach.md index a0810305d9..ffbf58a81d 100644 --- a/docs/reference/commandline/attach.md +++ b/docs/reference/commandline/attach.md @@ -1,4 +1,4 @@ -# attach +# docker attach Attach local standard input, output, and error streams to a running container @@ -9,159 +9,12 @@ Attach local standard input, output, and error streams to a running container ### Options -| Name | Type | Default | Description | -|:--------------------------------|:---------|:--------|:----------------------------------------------------| -| [`--detach-keys`](#detach-keys) | `string` | | Override the key sequence for detaching a container | -| `--no-stdin` | | | Do not attach STDIN | -| `--sig-proxy` | | | Proxy all received signals to the process | +| Name | Type | Default | Description | +|:----------------|:---------|:--------|:----------------------------------------------------| +| `--detach-keys` | `string` | | Override the key sequence for detaching a container | +| `--no-stdin` | | | Do not attach STDIN | +| `--sig-proxy` | | | Proxy all received signals to the process | -## Description - -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 lets you view its output or control it interactively, as -though the commands were running directly in your terminal. - -> **Note** -> -> The `attach` command displays the output of the container's `ENTRYPOINT` and -> `CMD` process. This can appear as if the attach command is hung when in fact -> the process may simply not be writing any output 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 -> doesn't terminate on `SIGINT` or `SIGTERM` unless it's coded to do so. - -You can't redirect the standard input of a `docker attach` command while -attaching to a TTY-enabled container (using the `-i` and `-t` options). - -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. -Once this buffer is full, the speed of the API connection is affected, and so -this impacts the output process' writing speed. This is similar to other -applications like SSH. Because of this, it isn't recommended to run -performance-critical applications that generate a lot of output in the -foreground over a slow client connection. Instead, use the `docker logs` -command to get access to the logs. - -## Examples - -### Attach to and detach from a running container - -The following example starts an Alpine container running `top` in detached mode, -then attaches to the container; - -```console -$ docker run -d --name topdemo alpine top -b - -$ docker attach topdemo - -Mem: 2395856K used, 5638884K free, 2328K shrd, 61904K buff, 1524264K cached -CPU: 0% usr 0% sys 0% nic 99% idle 0% io 0% irq 0% sirq -Load average: 0.15 0.06 0.01 1/567 6 - PID PPID USER STAT VSZ %VSZ CPU %CPU COMMAND - 1 0 root R 1700 0% 3 0% top -b -``` - -As the container was started without the `-i`, and `-t` options, signals are -forwarded to the attached process, which means that the default `CTRL-p CTRL-q` -detach key sequence produces no effect, but pressing `CTRL-c` terminates the -container: - -```console -<...> - PID PPID USER STAT VSZ %VSZ CPU %CPU COMMAND - 1 0 root R 1700 0% 7 0% top -b -^P^Q -^C - -$ docker ps -a --filter name=topdemo - -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -96254a235bd6 alpine "top -b" 44 seconds ago Exited (130) 8 seconds ago topdemo -``` - -Repeating the example above, but this time with the `-i` and `-t` options set; - -```console -$ docker run -dit --name topdemo2 ubuntu:22.04 /usr/bin/top -b -``` - -Now, when attaching to the container, and pressing the `CTRL-p CTRL-q` ("read -escape sequence"), the Docker CLI is handling the detach sequence, and the -`attach` command is detached from the container. Checking the container's status -with `docker ps` shows that the container is still running in the background: - -```console -$ docker attach topdemo2 - -Mem: 2405344K used, 5629396K free, 2512K shrd, 65100K buff, 1524952K cached -CPU: 0% usr 0% sys 0% nic 99% idle 0% io 0% irq 0% sirq -Load average: 0.12 0.12 0.05 1/594 6 - PID PPID USER STAT VSZ %VSZ CPU %CPU COMMAND - 1 0 root R 1700 0% 3 0% top -b -read escape sequence - -$ docker ps -a --filter name=topdemo2 - -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -fde88b83c2c2 alpine "top -b" 22 seconds ago Up 21 seconds topdemo2 -``` - -### 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: - -```console -$ docker run --name test -dit alpine -275c44472aebd77c926d4527885bb09f2f6db21d878c75f0a1c212c03d3bcfab - -$ docker attach test -/# exit 13 - -$ echo $? -13 - -$ docker ps -a --filter name=test - -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -a2fe3fd886db alpine "/bin/sh" About a minute ago Exited (13) 40 seconds ago test -``` - -### Override the detach sequence (--detach-keys) - -Use the `--detach-keys` option to 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). diff --git a/docs/reference/commandline/build.md b/docs/reference/commandline/build.md index 61f7f384a9..40983fb0e7 100644 --- a/docs/reference/commandline/build.md +++ b/docs/reference/commandline/build.md @@ -1,4 +1,4 @@ -# build +# docker build Build an image from a Dockerfile @@ -9,754 +9,39 @@ Build an image from a Dockerfile ### Options -| Name | Type | Default | Description | -|:------------------------------------|:--------------|:----------|:------------------------------------------------------------------| -| [`--add-host`](#add-host) | `list` | | Add a custom host-to-IP mapping (`host:ip`) | -| [`--build-arg`](#build-arg) | `list` | | Set build-time variables | -| [`--cache-from`](#cache-from) | `stringSlice` | | Images to consider as cache sources | -| [`--cgroup-parent`](#cgroup-parent) | `string` | | Set the parent cgroup for the `RUN` instructions during build | -| `--compress` | | | Compress the build context using gzip | -| `--cpu-period` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) period | -| `--cpu-quota` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) quota | -| `-c`, `--cpu-shares` | `int64` | `0` | CPU shares (relative weight) | -| `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) | -| `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) | -| `--disable-content-trust` | | | Skip image verification | -| [`-f`](#file), [`--file`](#file) | `string` | | Name of the Dockerfile (Default is `PATH/Dockerfile`) | -| `--force-rm` | | | Always remove intermediate containers | -| `--iidfile` | `string` | | Write the image ID to the file | -| [`--isolation`](#isolation) | `string` | | Container isolation technology | -| `--label` | `list` | | Set metadata for an image | -| `-m`, `--memory` | `bytes` | `0` | Memory limit | -| `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: -1 to enable unlimited swap | -| [`--network`](#network) | `string` | `default` | Set the networking mode for the RUN instructions during build | -| `--no-cache` | | | Do not use cache when building the image | -| `--platform` | `string` | | Set platform if server is multi-platform capable | -| `--pull` | | | Always attempt to pull a newer version of the image | -| `-q`, `--quiet` | | | Suppress the build output and print image ID on success | -| `--rm` | | | Remove intermediate containers after a successful build | -| [`--security-opt`](#security-opt) | `stringSlice` | | Security options | -| `--shm-size` | `bytes` | `0` | Size of `/dev/shm` | -| [`--squash`](#squash) | | | Squash newly built layers into a single new layer | -| [`-t`](#tag), [`--tag`](#tag) | `list` | | Name and optionally a tag in the `name:tag` format | -| [`--target`](#target) | `string` | | Set the target build stage to build. | -| [`--ulimit`](#ulimit) | `ulimit` | | Ulimit options | +| Name | Type | Default | Description | +|:--------------------------|:--------------|:----------|:------------------------------------------------------------------| +| `--add-host` | `list` | | Add a custom host-to-IP mapping (`host:ip`) | +| `--build-arg` | `list` | | Set build-time variables | +| `--cache-from` | `stringSlice` | | Images to consider as cache sources | +| `--cgroup-parent` | `string` | | Set the parent cgroup for the `RUN` instructions during build | +| `--compress` | | | Compress the build context using gzip | +| `--cpu-period` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) period | +| `--cpu-quota` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) quota | +| `-c`, `--cpu-shares` | `int64` | `0` | CPU shares (relative weight) | +| `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) | +| `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) | +| `--disable-content-trust` | | | Skip image verification | +| `-f`, `--file` | `string` | | Name of the Dockerfile (Default is `PATH/Dockerfile`) | +| `--force-rm` | | | Always remove intermediate containers | +| `--iidfile` | `string` | | Write the image ID to the file | +| `--isolation` | `string` | | Container isolation technology | +| `--label` | `list` | | Set metadata for an image | +| `-m`, `--memory` | `bytes` | `0` | Memory limit | +| `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: -1 to enable unlimited swap | +| `--network` | `string` | `default` | Set the networking mode for the RUN instructions during build | +| `--no-cache` | | | Do not use cache when building the image | +| `--platform` | `string` | | Set platform if server is multi-platform capable | +| `--pull` | | | Always attempt to pull a newer version of the image | +| `-q`, `--quiet` | | | Suppress the build output and print image ID on success | +| `--rm` | | | Remove intermediate containers after a successful build | +| `--security-opt` | `stringSlice` | | Security options | +| `--shm-size` | `bytes` | `0` | Size of `/dev/shm` | +| `--squash` | | | Squash newly built layers into a single new layer | +| `-t`, `--tag` | `list` | | Name and optionally a tag in the `name:tag` format | +| `--target` | `string` | | Set the target build stage to build. | +| `--ulimit` | `ulimit` | | Ulimit options | -## Description - -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*](https://docs.docker.com/engine/reference/builder/#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 isn't preserved. A -repository is first pulled into a temporary directory on your local host. After -that succeeds, the command sends the directory to the Docker daemon as the context. -Local copy gives you the ability to access private repositories using local -user credentials, VPNs, and so forth. - -> **Note** -> -> If the `URL` parameter contains a fragment the system recursively clones -> 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 checks out, -and can be either a branch, a tag, or a remote reference. The second part -represents a subdirectory inside the repository used as a build -context. - -For example, run this command to use a directory called `docker` in the branch -`container`: - -```console -$ 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` | - -### Tarball contexts - -If you pass a URL to a remote tarball, the command sends the URL itself to the -daemon: - -```console -$ docker build http://server/context.tar.gz -``` - -The host running the Docker daemon performs the download operation, -which isn't necessarily the same host that issued the build command. -The Docker daemon fetches `context.tar.gz` and uses 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`: - -```console -$ docker build - < Dockerfile -``` - -With PowerShell on Windows, you run: - -```powershell -Get-Content Dockerfile | docker build - -``` - -If you use `STDIN` or specify a `URL` pointing to a plain text file, the daemon -places the contents into a `Dockerfile`, and ignores any `-f`, `--file` -option. In this scenario, there is no context. - -By default the `docker build` command looks 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 that use the same -set of files for multiple builds. The path must be to a file within the -build context. Relative path are 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](https://docs.docker.com/engine/reference/builder/#dockerignore-file). - -If the Docker client loses connection to the daemon, it cancels the build. -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 client also cancels the pull. - -## Return code - -Successful builds return exit code `0`. When the build fails, the command -returns a non-zero exit code and prints an error message to `STDERR`: - -```console -$ docker build -t fail . - -Sending build context to Docker daemon 2.048 kB -Sending build context to Docker daemon -Step 1/3 : FROM busybox - ---> 4986bf8c1536 -Step 2/3 : RUN exit 13 - ---> Running in e26670ec7a0a -INFO[0000] The command [/bin/sh -c exit 13] returned a non-zero code: 13 -$ echo $? -1 -``` - -See also: - -[*Dockerfile Reference*](https://docs.docker.com/engine/reference/builder/). - -## Examples - -### Build with PATH - -```console -$ 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 `tar`s all the files in the -local directory and sends them 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` are sent, not just -the ones listed to [`ADD`](https://docs.docker.com/engine/reference/builder/#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 doesn't affect the build cache. - -### Build with URL - -```console -$ docker build github.com/creack/docker-firefox -``` - -This clones the GitHub repository, using the cloned repository as context, -and the Dockerfile at the root of the repository. You can -specify an arbitrary Git repository by using the `git://` or `git@` scheme. - -```console -$ 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` used -to build the image. Any `ADD` commands in that `Dockerfile` that refer to local -paths must be relative to the root of the contents inside `ctx.tar.gz`. In the -example above, the tarball contains a directory `ctx/`, so the `ADD -ctx/container.cfg /` operation works as expected. - -### Build with `-` - -```console -$ docker build - < Dockerfile -``` - -This example reads a Dockerfile from `STDIN` without context. Due to the lack of a -context, the command doesn't send contents of any local directory to the Docker daemon. -Since there is no context, a Dockerfile `ADD` only works if it refers to a -remote URL. - -```console -$ docker build - < context.tar.gz -``` - -This example builds an image for a compressed context read from `STDIN`. -Supported formats are: `bzip2`, `gzip` and `xz`. - -### Use a .dockerignore file - -```console -$ 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. You can see its effect in the changed size of the -uploaded context. The builder reference contains detailed information on -[creating a .dockerignore file](https://docs.docker.com/engine/reference/builder/#dockerignore-file). - -When using the [BuildKit backend](https://docs.docker.com/build/buildkit/), -`docker build` searches for a `.dockerignore` file relative to the Dockerfile -name. For example, running `docker build -f myapp.Dockerfile .` first looks -for an ignore file named `myapp.Dockerfile.dockerignore`. If it can't find such a file, -if present, it uses the `.dockerignore` file. 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, --tag) - -```console -$ docker build -t vieux/apache:2.0 . -``` - -This examples builds in the same way as the previous example, but it then tags the resulting -image. The repository name will be `vieux/apache` and the tag `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: - -```console -$ docker build -t whenry/fedora-jboss:latest -t whenry/fedora-jboss:v2.1 . -``` - -### Specify a Dockerfile (-f, --file) - -```console -$ docker build -f Dockerfile.debug . -``` - -This uses a file called `Dockerfile.debug` for the build instructions -instead of `Dockerfile`. - -```console -$ curl example.com/remote/Dockerfile | docker build -f - . -``` - -The above command uses the current directory as the build context and reads -a Dockerfile from stdin. - -```console -$ docker build -f dockerfiles/Dockerfile.debug -t myapp_debug . -$ docker build -f dockerfiles/Dockerfile.prod -t myapp_prod . -``` - -The above commands build the current build context (as specified by the -`.`) twice. Once using a debug version of a `Dockerfile` and once using a -production version. - -```console -$ 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 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 doesn't exist in the uploaded context. This may -> happen if there is no context, or if you specify a file that's -> 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` doesn't work. - -### Use a custom parent cgroup (--cgroup-parent) - -When you run `docker build` with the `--cgroup-parent` option, the daemon runs the containers -used in the build with the [corresponding `docker run` flag](../run.md#specify-custom-cgroups). - -### Set ulimits in container (--ulimit) - -Using the `--ulimit` option with `docker build` causes the daemon to start each build step's -container using those [`--ulimit` flag values](run.md#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. Often persistence isn't 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: - -```console -$ 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. 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 doesn't alter the output you see when the build process echoes the`ARG` lines from the -Dockerfile. - -For detailed information on using `ARG` and `ENV` instructions, see the -[Dockerfile reference](https://docs.docker.com/engine/reference/builder/). - -You can also use the `--build-arg` flag without a value, in which case the daemon -propagates the value from the local environment into the Docker container it's building: - -```console -$ export HTTP_PROXY=http://10.20.30.2:1234 -$ docker build --build-arg HTTP_PROXY . -``` - -This example is similar to how `docker run -e` works. Refer to the [`docker run` documentation](run.md#env) -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 build container's `/etc/hosts` file by using one -or more `--add-host` flags. This example adds static addresses for hosts named -`my-hostname` and `my_hostname_v6`: - -```console -$ docker build --add-host my_hostname=8.8.8.8 --add-host my_hostname_v6=2001:4860:4860::8888 . -``` - -If you need your build to connect to services running on the host, you can use -the special `host-gateway` value for `--add-host`. In the following example, -build containers resolve `host.docker.internal` to the host's gateway IP. - -```console -$ docker build --add-host host.docker.internal=host-gateway . -``` - -You can wrap an IPv6 address in square brackets. -`=` and `:` are both valid separators. -Both formats in the following example are valid: - -```console -$ docker build --add-host my-hostname:10.180.0.1 --add-host my-hostname_v6=[2001:4860:4860::8888] . -``` - -### Specifying target build stage (--target) - -When building a Dockerfile with multiple build stages, you can use the `--target` -option to specify an intermediate build stage by name as a final stage for the -resulting image. The daemon skips commands after the target stage. - -```dockerfile -FROM debian AS build-env -# ... - -FROM alpine AS production-env -# ... -``` - -```console -$ docker build -t mybuildimage --target build-env . -``` - -### Custom build outputs (--output) - -> **Note** -> -> This feature requires the BuildKit backend. You can either -> [enable BuildKit](https://docs.docker.com/build/buildkit/#getting-started) or -> use the [buildx](https://github.com/docker/buildx) plugin which provides more -> output type options. - -By default, a local container image is created from the build result. The -`--output` (or `-o`) flag allows you to override this behavior, and specify a -custom exporter. 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 that supports `local` and `tar` exporters. - -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 you specify no type, 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 a 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: - -```console -$ 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): - -```console -$ docker build --output type=local,dest=out . -``` - -Use the `tar` type to export the files as a `.tar` archive: - -```console -$ 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: - -```console -$ 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`](https://docs.docker.com/engine/reference/builder/#copy). - -The example, the `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, the command only exports the files from the final -stage to the `out` directory, in this case, the `vndr` binary: - -```console -$ 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 -``` - -### Specifying external cache sources (--cache-from) - -> **Note** -> -> This feature requires the BuildKit backend. You can either -> [enable BuildKit](https://docs.docker.com/build/buildkit/#getting-started) or -> use the [buildx](https://github.com/docker/buildx) plugin. The previous -> builder has limited support for reusing cache from pre-pulled images. - -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. You can do this by setting `--build-arg BUILDKIT_INLINE_CACHE=1` -when building the image. After that, you can use the built image as a cache source -for subsequent builds. - -Upon importing the cache, the builder only pulls the JSON metadata from the -registry and determine possible cache hits based on that information. If there -is a cache hit, the builder pulls the matched layers 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: - -```console -$ 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. - -On another machine: - -```console -$ docker build --cache-from myname/myapp . -``` - -### Set the networking mode for the RUN instructions during build (--network) - -#### Overview - -Available options for the networking mode are: - -- `default` (default): Run in the default network. -- `none`: Run with no network access. -- `host`: Run in the host’s network environment. - -Find more details in the [Dockerfile documentation](https://docs.docker.com/engine/reference/builder/#run---network). - -### Squash an image's layers (--squash) (experimental) - -#### Overview - -> **Note** -> The `--squash` option is an experimental feature, and should not be considered -> stable. - -Once the image is built, this flag squashes the new layers into a new image with -a single new layer. Squashing doesn't 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 `--squash` flag preserves the build cache. - -Squashing layers can be beneficial if your Dockerfile produces multiple layers -modifying the same files. For example, files 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, the daemon can pull layers 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 [Multi-stage builds](https://docs.docker.com/build/building/multi-stage/) -section for more information. - -#### Known limitations - -The `--squash` option has a number of known limitations: - -- When squashing layers, the resulting image can't 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 intact, 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 - you can't parallelize downloading a single layer. -- When attempting to squash an image that doesn't 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 23.03. - -You can enable experimental mode 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: 23.0.3 - API version: 1.42 - Go version: go1.19.7 - Git commit: 3e7cbfd - Built: Tue Apr 4 22:05:41 2023 - OS/Arch: darwin/amd64 - Context: default - -Server: Docker Engine - Community - Engine: - Version: 23.0.3 - API version: 1.42 (minimum version 1.12) - Go version: go1.19.7 - Git commit: 59118bf - Built: Tue Apr 4 22:05:41 2023 - OS/Arch: linux/amd64 - Experimental: true - [...] -``` - -#### Build an image with the `--squash` flag - -The following is an example of a build with the `--squash` flag. Below is the -`Dockerfile`: - -```dockerfile -FROM busybox -RUN echo hello > /hello -RUN echo world >> /hello -RUN touch remove_me /remove_me -ENV HELLO=world -RUN rm /remove_me -``` - -Next, build an image named `test` using the `--squash` flag. - -```console -$ docker build --squash -t test . -``` - -After the build completes, the history looks like the below. The history could show that a layer's -name is ``, and there is a new layer with COMMENT `merge`. - -```console -$ 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 -``` - -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`. diff --git a/docs/reference/commandline/commit.md b/docs/reference/commandline/commit.md index ff1c458e1a..281d96e488 100644 --- a/docs/reference/commandline/commit.md +++ b/docs/reference/commandline/commit.md @@ -1,4 +1,4 @@ -# commit +# docker commit Create a new image from a container's changes @@ -9,97 +9,13 @@ Create a new image from a container's changes ### Options -| Name | Type | Default | Description | -|:---------------------------------------|:---------|:--------|:-----------------------------------------------------------| -| `-a`, `--author` | `string` | | Author (e.g., `John Hannibal Smith `) | -| [`-c`](#change), [`--change`](#change) | `list` | | Apply Dockerfile instruction to the created image | -| `-m`, `--message` | `string` | | Commit message | -| `-p`, `--pause` | | | Pause container during commit | +| Name | Type | Default | Description | +|:------------------|:---------|:--------|:-----------------------------------------------------------| +| `-a`, `--author` | `string` | | Author (e.g., `John Hannibal Smith `) | +| `-c`, `--change` | `list` | | Apply Dockerfile instruction to the created image | +| `-m`, `--message` | `string` | | Commit message | +| `-p`, `--pause` | | | Pause container during commit | -## Description - -It can be useful to commit a container's file changes or settings into a new -image. This lets you debug a container by running an interactive shell, or -export a working dataset to another server. - -Commits do not include any data contained in mounted volumes. - -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's -created. Supported `Dockerfile` instructions: -`CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`LABEL`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` - -## Examples - -### Commit a container - -```console -$ docker ps - -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -c3f279d17e0a ubuntu:22.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky -197387f1b436 ubuntu:22.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 (--change) - -```console -$ docker ps - -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -c3f279d17e0a ubuntu:22.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky -197387f1b436 ubuntu:22.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 - -```console -$ docker ps - -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -c3f279d17e0a ubuntu:22.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky -197387f1b436 ubuntu:22.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:22.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky -197387f1b436 ubuntu:22.04 /bin/bash 7 days ago Up 25 hours focused_hamilton -``` diff --git a/docs/reference/commandline/container_attach.md b/docs/reference/commandline/container_attach.md index 10ce5539a2..a0810305d9 100644 --- a/docs/reference/commandline/container_attach.md +++ b/docs/reference/commandline/container_attach.md @@ -1,4 +1,4 @@ -# container attach +# attach Attach local standard input, output, and error streams to a running container @@ -9,15 +9,159 @@ Attach local standard input, output, and error streams to a running container ### Options -| Name | Type | Default | Description | -|:----------------|:---------|:--------|:----------------------------------------------------| -| `--detach-keys` | `string` | | Override the key sequence for detaching a container | -| `--no-stdin` | | | Do not attach STDIN | -| `--sig-proxy` | | | Proxy all received signals to the process | +| Name | Type | Default | Description | +|:--------------------------------|:---------|:--------|:----------------------------------------------------| +| [`--detach-keys`](#detach-keys) | `string` | | Override the key sequence for detaching a container | +| `--no-stdin` | | | Do not attach STDIN | +| `--sig-proxy` | | | Proxy all received signals to the process | ## Description -See [docker attach](attach.md) for more information. +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 lets you view its output or control it interactively, as +though the commands were running directly in your terminal. + +> **Note** +> +> The `attach` command displays the output of the container's `ENTRYPOINT` and +> `CMD` process. This can appear as if the attach command is hung when in fact +> the process may simply not be writing any output 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 +> doesn't terminate on `SIGINT` or `SIGTERM` unless it's coded to do so. + +You can't redirect the standard input of a `docker attach` command while +attaching to a TTY-enabled container (using the `-i` and `-t` options). + +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. +Once this buffer is full, the speed of the API connection is affected, and so +this impacts the output process' writing speed. This is similar to other +applications like SSH. Because of this, it isn't recommended to run +performance-critical applications that generate a lot of output in the +foreground over a slow client connection. Instead, use the `docker logs` +command to get access to the logs. + +## Examples + +### Attach to and detach from a running container + +The following example starts an Alpine container running `top` in detached mode, +then attaches to the container; + +```console +$ docker run -d --name topdemo alpine top -b + +$ docker attach topdemo + +Mem: 2395856K used, 5638884K free, 2328K shrd, 61904K buff, 1524264K cached +CPU: 0% usr 0% sys 0% nic 99% idle 0% io 0% irq 0% sirq +Load average: 0.15 0.06 0.01 1/567 6 + PID PPID USER STAT VSZ %VSZ CPU %CPU COMMAND + 1 0 root R 1700 0% 3 0% top -b +``` + +As the container was started without the `-i`, and `-t` options, signals are +forwarded to the attached process, which means that the default `CTRL-p CTRL-q` +detach key sequence produces no effect, but pressing `CTRL-c` terminates the +container: + +```console +<...> + PID PPID USER STAT VSZ %VSZ CPU %CPU COMMAND + 1 0 root R 1700 0% 7 0% top -b +^P^Q +^C + +$ docker ps -a --filter name=topdemo + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +96254a235bd6 alpine "top -b" 44 seconds ago Exited (130) 8 seconds ago topdemo +``` + +Repeating the example above, but this time with the `-i` and `-t` options set; + +```console +$ docker run -dit --name topdemo2 ubuntu:22.04 /usr/bin/top -b +``` + +Now, when attaching to the container, and pressing the `CTRL-p CTRL-q` ("read +escape sequence"), the Docker CLI is handling the detach sequence, and the +`attach` command is detached from the container. Checking the container's status +with `docker ps` shows that the container is still running in the background: + +```console +$ docker attach topdemo2 + +Mem: 2405344K used, 5629396K free, 2512K shrd, 65100K buff, 1524952K cached +CPU: 0% usr 0% sys 0% nic 99% idle 0% io 0% irq 0% sirq +Load average: 0.12 0.12 0.05 1/594 6 + PID PPID USER STAT VSZ %VSZ CPU %CPU COMMAND + 1 0 root R 1700 0% 3 0% top -b +read escape sequence + +$ docker ps -a --filter name=topdemo2 + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +fde88b83c2c2 alpine "top -b" 22 seconds ago Up 21 seconds topdemo2 +``` + +### 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: + +```console +$ docker run --name test -dit alpine +275c44472aebd77c926d4527885bb09f2f6db21d878c75f0a1c212c03d3bcfab + +$ docker attach test +/# exit 13 + +$ echo $? +13 + +$ docker ps -a --filter name=test + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +a2fe3fd886db alpine "/bin/sh" About a minute ago Exited (13) 40 seconds ago test +``` + +### Override the detach sequence (--detach-keys) + +Use the `--detach-keys` option to 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). diff --git a/docs/reference/commandline/container_commit.md b/docs/reference/commandline/container_commit.md index 7a4e63b986..ff1c458e1a 100644 --- a/docs/reference/commandline/container_commit.md +++ b/docs/reference/commandline/container_commit.md @@ -1,4 +1,4 @@ -# container commit +# commit Create a new image from a container's changes @@ -9,16 +9,97 @@ Create a new image from a container's changes ### Options -| Name | Type | Default | Description | -|:------------------|:---------|:--------|:-----------------------------------------------------------| -| `-a`, `--author` | `string` | | Author (e.g., `John Hannibal Smith `) | -| `-c`, `--change` | `list` | | Apply Dockerfile instruction to the created image | -| `-m`, `--message` | `string` | | Commit message | -| `-p`, `--pause` | | | Pause container during commit | +| Name | Type | Default | Description | +|:---------------------------------------|:---------|:--------|:-----------------------------------------------------------| +| `-a`, `--author` | `string` | | Author (e.g., `John Hannibal Smith `) | +| [`-c`](#change), [`--change`](#change) | `list` | | Apply Dockerfile instruction to the created image | +| `-m`, `--message` | `string` | | Commit message | +| `-p`, `--pause` | | | Pause container during commit | ## Description -See [docker commit](commit.md) for more information. +It can be useful to commit a container's file changes or settings into a new +image. This lets you debug a container by running an interactive shell, or +export a working dataset to another server. + +Commits do not include any data contained in mounted volumes. + +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's +created. Supported `Dockerfile` instructions: +`CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`LABEL`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` + +## Examples + +### Commit a container + +```console +$ docker ps + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +c3f279d17e0a ubuntu:22.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky +197387f1b436 ubuntu:22.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 (--change) + +```console +$ docker ps + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +c3f279d17e0a ubuntu:22.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky +197387f1b436 ubuntu:22.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 + +```console +$ docker ps + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +c3f279d17e0a ubuntu:22.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky +197387f1b436 ubuntu:22.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:22.04 /bin/bash 7 days ago Up 25 hours desperate_dubinsky +197387f1b436 ubuntu:22.04 /bin/bash 7 days ago Up 25 hours focused_hamilton +``` diff --git a/docs/reference/commandline/container_cp.md b/docs/reference/commandline/container_cp.md index 4c91817bd3..bf3741d8b2 100644 --- a/docs/reference/commandline/container_cp.md +++ b/docs/reference/commandline/container_cp.md @@ -1,4 +1,4 @@ -# container cp +# cp Copy files/folders between a container and the local filesystem @@ -25,4 +25,107 @@ container source to stdout. ## Description -See [docker cp](cp.md) for more information. +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. + +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` doesn't create parent directories for +`DEST_PATH` if they don't 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` + +## Examples + +Copy a local file into container + +```console +$ docker cp ./some_file CONTAINER:/work +``` + +Copy files from container to local path + +```console +$ docker cp CONTAINER:/var/logs/ /tmp/app_logs +``` + +Copy a file from container to stdout. Please note `cp` command produces a tar stream + +```console +$ docker cp CONTAINER:/var/logs/app.log - | tar x -O | grep "ERROR" +``` + +### Corner cases + +It isn't possible to copy certain system files such as resources under +`/proc`, `/sys`, `/dev`, [tmpfs](run.md#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): + +```console +$ docker exec CONTAINER tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | tar Cxf DEST_PATH - +``` + +```console +$ 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`. diff --git a/docs/reference/commandline/container_create.md b/docs/reference/commandline/container_create.md index 06335a52d9..6b598a8398 100644 --- a/docs/reference/commandline/container_create.md +++ b/docs/reference/commandline/container_create.md @@ -1,4 +1,4 @@ -# container create +# create Create a new container @@ -117,4 +117,84 @@ Create a new container ## Description -See [docker create](create.md) for more information. +The `docker container create` (or shorthand: `docker create`) command creates a +new container from the specified image, without starting it. + +When creating a container, the Docker daemon 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 container start` +(or shorthand: `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's ready to start when you need it. The initial status of the +new container is `created`. + +The `docker create` command shares most of its options with the `docker run` +command (which performs a `docker create` before starting it). Refer to the +[`docker run` command](run.md) section and the [Docker run reference](../run.md) +for details on the available flags and options. + +## Examples + +### Create and start a container + +The following example creates an interactive container with a pseudo-TTY attached, +then starts the container and attaches to it: + +```console +$ docker container create -i -t --name mycontainer alpine +6d8af538ec541dd581ebc2a24153a28329acb5268abe5ef868c1f1a261221752 + +$ docker container start --attach -i mycontainer +/ # echo hello world +hello world +``` + +The above is the equivalent of a `docker run`: + +```console +$ docker run -it --name mycontainer2 alpine +/ # echo hello world +hello world +``` + +### Initialize volumes + +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: + +```console +$ 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: + +```console +$ 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 +``` diff --git a/docs/reference/commandline/container_diff.md b/docs/reference/commandline/container_diff.md index 03e537c5ee..05f2990dbc 100644 --- a/docs/reference/commandline/container_diff.md +++ b/docs/reference/commandline/container_diff.md @@ -1,4 +1,4 @@ -# container diff +# diff Inspect changes to files or directories on a container's filesystem @@ -12,4 +12,42 @@ Inspect changes to files or directories on a container's filesystem ## Description -See [docker diff](diff.md) for more information. +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. + +## Examples + +Inspect the changes to an `nginx` container: + +```console +$ 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 +``` diff --git a/docs/reference/commandline/container_exec.md b/docs/reference/commandline/container_exec.md index 1f7d4aa4fa..1f1fafa747 100644 --- a/docs/reference/commandline/container_exec.md +++ b/docs/reference/commandline/container_exec.md @@ -1,4 +1,4 @@ -# container exec +# exec Execute a command in a running container @@ -9,21 +9,128 @@ Execute a command in a running container ### Options -| Name | Type | Default | Description | -|:----------------------|:---------|:--------|:-------------------------------------------------------| -| `-d`, `--detach` | | | Detached mode: run command in the background | -| `--detach-keys` | `string` | | Override the key sequence for detaching a container | -| `-e`, `--env` | `list` | | Set environment variables | -| `--env-file` | `list` | | Read in a file of environment variables | -| `-i`, `--interactive` | | | Keep STDIN open even if not attached | -| `--privileged` | | | Give extended privileges to the command | -| `-t`, `--tty` | | | Allocate a pseudo-TTY | -| `-u`, `--user` | `string` | | Username or UID (format: `[:]`) | -| `-w`, `--workdir` | `string` | | Working directory inside the container | +| Name | Type | Default | Description | +|:------------------------------------------|:---------|:--------|:-------------------------------------------------------| +| `-d`, `--detach` | | | Detached mode: run command in the background | +| `--detach-keys` | `string` | | Override the key sequence for detaching a container | +| [`-e`](#env), [`--env`](#env) | `list` | | Set environment variables | +| `--env-file` | `list` | | Read in a file of environment variables | +| `-i`, `--interactive` | | | Keep STDIN open even if not attached | +| `--privileged` | | | Give extended privileges to the command | +| `-t`, `--tty` | | | Allocate a pseudo-TTY | +| `-u`, `--user` | `string` | | Username or UID (format: `[:]`) | +| [`-w`](#workdir), [`--workdir`](#workdir) | `string` | | Working directory inside the container | ## Description -See [docker exec](exec.md) for more information. +The `docker exec` command runs a new command in a running container. + +The command you specify with `docker exec` only runs while the container's +primary process (`PID 1`) is running, and it isn't restarted if the container +is restarted. + +The command runs in the default working directory of the container. + +The command must be an executable. A chained or a quoted command doesn't work. + +- This works: `docker exec -it my_container sh -c "echo a && echo b"` +- This doesn't work: `docker exec -it my_container "echo a && echo b"` + +## Examples + +### Run `docker exec` on a running container + +First, start a container. + +```console +$ docker run --name mycontainer -d -i -t alpine /bin/sh +``` + +This creates and starts a container named `mycontainer` from an `alpine` image +with an `sh` shell as its main process. The `-d` option (shorthand for `--detach`) +sets the container to run in the background, in detached mode, with a pseudo-TTY +attached (`-t`). The `-i` option is set to keep `STDIN` attached (`-i`), which +prevents the `sh` process from exiting immediately. + +Next, execute a command on the container. + +```console +$ docker exec -d mycontainer touch /tmp/execWorks +``` + +This creates a new file `/tmp/execWorks` inside the running container +`mycontainer`, in the background. + +Next, execute an interactive `sh` shell on the container. + +```console +$ docker exec -it mycontainer sh +``` + +This starts a new shell session in the container `mycontainer`. + +### Set environment variables for the exec process (--env, -e) + +Next, set environment variables in the current bash session. + +The `docker exec` command inherits the environment variables that are set at the +time the container is created. Use the `--env` (or the `-e` shorthand) to +override global environment variables, or to set additional environment +variables for the process started by `docker exec`. + +The following example creates a new shell session in the container `mycontainer`, +with environment variables `$VAR_A` set to `1`, and `$VAR_B` set to `2`. +These environment variables are only valid for the `sh` process started by that +`docker exec` command, and aren't available to other processes running inside +the container. + +```console +$ docker exec -e VAR_A=1 -e VAR_B=2 mycontainer env +PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin +HOSTNAME=f64a4851eb71 +VAR_A=1 +VAR_B=2 +HOME=/root +``` + +### Set the working directory for the exec process (--workdir, -w) + +By default `docker exec` command runs in the same working directory set when +the container was created. + +```console +$ docker exec -it mycontainer pwd +/ +``` + +You can specify an alternative working directory for the command to execute +using the `--workdir` option (or the `-w` shorthand): + +```console +$ docker exec -it -w /root mycontainer pwd +/root +``` + +### Try to run `docker exec` on a paused container + +If the container is paused, then the `docker exec` command fails with an error: + +```console +$ docker pause mycontainer +mycontainer + +$ docker ps + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +482efdf39fac alpine "/bin/sh" 17 seconds ago Up 16 seconds (Paused) mycontainer + +$ docker exec mycontainer sh + +Error response from daemon: Container mycontainer is paused, unpause the container before exec + +$ echo $? +1 +``` diff --git a/docs/reference/commandline/container_export.md b/docs/reference/commandline/container_export.md index c0f1220587..31fd70a774 100644 --- a/docs/reference/commandline/container_export.md +++ b/docs/reference/commandline/container_export.md @@ -1,4 +1,4 @@ -# container export +# export Export a container's filesystem as a tar archive @@ -18,4 +18,22 @@ Export a container's filesystem as a tar archive ## Description -See [docker export](export.md) for more information. +The `docker export` command doesn't 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` exports the contents of the underlying +directory, not the contents of the volume. + +Refer to [Backup, restore, or migrate data volumes](https://docs.docker.com/storage/volumes/#back-up-restore-or-migrate-data-volumes) +in the user guide for examples on exporting data in a volume. + +## Examples + +The following commands produce the same result. + +```console +$ docker export red_panda > latest.tar +``` + +```console +$ docker export --output="latest.tar" red_panda +``` diff --git a/docs/reference/commandline/container_kill.md b/docs/reference/commandline/container_kill.md index a7febea02e..2d12d6eb4d 100644 --- a/docs/reference/commandline/container_kill.md +++ b/docs/reference/commandline/container_kill.md @@ -1,4 +1,4 @@ -# container kill +# kill Kill one or more running containers @@ -9,13 +9,66 @@ Kill one or more running containers ### Options -| Name | Type | Default | Description | -|:-----------------|:---------|:--------|:--------------------------------| -| `-s`, `--signal` | `string` | | Signal to send to the container | +| Name | Type | Default | Description | +|:---------------------------------------|:---------|:--------|:--------------------------------| +| [`-s`](#signal), [`--signal`](#signal) | `string` | | Signal to send to the container | ## Description -See [docker kill](kill.md) for more information. +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 reference a container by its +ID, ID-prefix, or name. + +The `--signal` flag sets the system call signal that is sent to the container. +This signal can be a signal name in the format `SIG`, for instance `SIGINT`, +or an unsigned number that matches a position in the kernel's syscall table, +for instance `2`. + +While the default (`SIGKILL`) signal will terminate the container, the signal +set through `--signal` may be non-terminal, depending on the container's main +process. For example, the `SIGHUP` signal in most cases will be non-terminal, +and the container will continue running after receiving the signal. + +> **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. + +## Examples + + +### Send a KILL signal to a container + +The following example sends the default `SIGKILL` signal to the container named +`my_container`: + +```console +$ docker kill my_container +``` + +### Send a custom signal to a container (--signal) + +The following example sends a `SIGHUP` signal to the container named +`my_container`: + +```console +$ 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: + +```console +$ docker kill --signal=SIGHUP my_container +$ docker kill --signal=HUP my_container +$ docker kill --signal=1 my_container +``` + +Refer to the [`signal(7)`](https://man7.org/linux/man-pages/man7/signal.7.html) +man-page for a list of standard Linux signals. diff --git a/docs/reference/commandline/container_logs.md b/docs/reference/commandline/container_logs.md index f35a96d2b9..5fddcbdf0c 100644 --- a/docs/reference/commandline/container_logs.md +++ b/docs/reference/commandline/container_logs.md @@ -1,4 +1,4 @@ -# container logs +# logs Fetch the logs of a container @@ -16,11 +16,58 @@ Fetch the logs of a container | `--since` | `string` | | Show logs since timestamp (e.g. `2013-01-02T13:23:37Z`) or relative (e.g. `42m` for 42 minutes) | | `-n`, `--tail` | `string` | `all` | Number of lines to show from the end of the logs | | `-t`, `--timestamps` | | | Show timestamps | -| `--until` | `string` | | Show logs before a timestamp (e.g. `2013-01-02T13:23:37Z`) or relative (e.g. `42m` for 42 minutes) | +| [`--until`](#until) | `string` | | Show logs before a timestamp (e.g. `2013-01-02T13:23:37Z`) or relative (e.g. `42m` for 42 minutes) | ## Description -See [docker logs](logs.md) for more information. +The `docker logs` command batch-retrieves logs present at the time of execution. + +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://pkg.go.dev/time#RFC3339Nano) +, 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. + +## Examples + +### Retrieve logs until a specific point in time (--until) + +In order to retrieve logs before a specific point in time, run: + +```console +$ 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 +``` diff --git a/docs/reference/commandline/container_ls.md b/docs/reference/commandline/container_ls.md index 76fb07c75e..062fdcb4cd 100644 --- a/docs/reference/commandline/container_ls.md +++ b/docs/reference/commandline/container_ls.md @@ -1,4 +1,4 @@ -# container ls +# ps List containers @@ -9,20 +9,440 @@ List containers ### Options -| Name | Type | Default | Description | -|:-----------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `-a`, `--all` | | | Show all containers (default shows just running) | -| `-f`, `--filter` | `filter` | | Filter output based on conditions provided | -| `--format` | `string` | | Format output using a custom template:
'table': Print output in table format with column headers (default)
'table TEMPLATE': Print output in table format using the given Go template
'json': Print in JSON format
'TEMPLATE': Print output using the given Go template.
Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | -| `-n`, `--last` | `int` | `-1` | Show n last created containers (includes all states) | -| `-l`, `--latest` | | | Show the latest created container (includes all states) | -| `--no-trunc` | | | Don't truncate output | -| `-q`, `--quiet` | | | Only display container IDs | -| `-s`, `--size` | | | Display total file sizes | +| Name | Type | Default | Description | +|:---------------------------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [`-a`](#all), [`--all`](#all) | | | Show all containers (default shows just running) | +| [`-f`](#filter), [`--filter`](#filter) | `filter` | | Filter output based on conditions provided | +| [`--format`](#format) | `string` | | Format output using a custom template:
'table': Print output in table format with column headers (default)
'table TEMPLATE': Print output in table format using the given Go template
'json': Print in JSON format
'TEMPLATE': Print output using the given Go template.
Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | +| `-n`, `--last` | `int` | `-1` | Show n last created containers (includes all states) | +| `-l`, `--latest` | | | Show the latest created container (includes all states) | +| [`--no-trunc`](#no-trunc) | | | Don't truncate output | +| `-q`, `--quiet` | | | Only display container IDs | +| [`-s`](#size), [`--size`](#size) | | | Display total file sizes | -## Description +## Examples -See [docker ps](ps.md) for more information. +### Do not truncate output (--no-trunc) + +Running `docker ps --no-trunc` showing 2 linked containers. + +```console +$ docker ps --no-trunc + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +ca5534a51dd04bbcebe9b23ba05f389466cf0c190f1f8f182d7eea92a9671d00 ubuntu:22.04 bash 17 seconds ago Up 16 seconds 3300-3310/tcp webapp +9ca9747b233100676a48cc7806131586213fa5dab86dd1972d6a8732e3a84a4d crosbymichael/redis:latest /redis-server --dir 33 minutes ago Up 33 minutes 6379/tcp redis,webapp/db +``` + +### Show both running and stopped containers (-a, --all) + +The `docker ps` command only shows running containers by default. To see all +containers, use the `--all` (or `-a`) flag: + +```console +$ 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 (--size) + +The `docker ps --size` (or `-s`) command displays two different on-disk-sizes for each container: + +```console +$ docker ps --size + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 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 (--filter) + +The `--filter` (or `-f`) flag 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. + +```console +$ 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. + +```console +$ 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. + +```console +$ 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: + +```console +$ 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: + +```console +$ 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. + +```console +$ 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. The possible values for the container status are: + +| Status | Description | +| :----------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `created` | A container that has never been started. | +| `running` | A running container, started by either `docker start` or `docker run`. | +| `paused` | A paused container. See `docker pause`. | +| `restarting` | A container which is starting due to the designated restart policy for that container. | +| `exited` | A container which is no longer running. For example, the process inside the container completed or the container was stopped using the `docker stop` command. | +| `removing` | A container which is in the process of being removed. See `docker rm`. | +| `dead` | A "defunct" container; for example, a container that was only partially removed because resources were kept busy by an external process. `dead` containers cannot be (re)started, only removed. | + +For example, to filter for `running` containers: + +```console +$ 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: + +```console +$ 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: + +```console +$ 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`: + +```console +$ 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 `22.04` image: + +```console +$ docker ps --filter ancestor=ubuntu:22.04 + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +82a598284012 ubuntu:22.04 "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. + +```console +$ docker ps --filter ancestor=d0e008c6cf02 + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +82a598284012 ubuntu:22.04 "top" 3 minutes ago Up 3 minutes sleepy_bose +``` + +#### Create time + +##### before + +The `before` filter shows only containers created before the container with +a given ID or name. For example, having these containers created: + +```console +$ 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: + +```console +$ 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 a given +ID or name. For example, with the same containers as in `before` filter: + +```console +$ 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: + +```console +$ 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`. + +```console +$ 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: + +```console +$ 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: + +```console +$ 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`: + +```console +$ 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`: + +```console +$ docker ps --filter publish=80/udp + +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +``` + +### Format the output (--format) + +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. | +| `.State` | Container status (for example; "created", "running", "exited"). | +| `.Status` | Container status with details about duration and health-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: + +```console +$ 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: + +```console +$ 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 +``` + +To list all running containers in JSON format, use the `json` directive: + +```console +$ docker ps --format json +{"Command":"\"/docker-entrypoint.…\"","CreatedAt":"2021-03-10 00:15:05 +0100 CET","ID":"a762a2b37a1d","Image":"nginx","Labels":"maintainer=NGINX Docker Maintainers \u003cdocker-maint@nginx.com\u003e","LocalVolumes":"0","Mounts":"","Names":"boring_keldysh","Networks":"bridge","Ports":"80/tcp","RunningFor":"4 seconds ago","Size":"0B","State":"running","Status":"Up 3 seconds"} +``` diff --git a/docs/reference/commandline/container_pause.md b/docs/reference/commandline/container_pause.md index bdd0ec7bc9..bf22b75442 100644 --- a/docs/reference/commandline/container_pause.md +++ b/docs/reference/commandline/container_pause.md @@ -1,4 +1,4 @@ -# container pause +# pause Pause all processes within one or more containers @@ -12,4 +12,23 @@ Pause all processes within one or more containers ## Description -See [docker pause](pause.md) for more information. +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. + +## Examples + +```console +$ docker pause my_container +``` + +## Related commands + +* [unpause](unpause.md) diff --git a/docs/reference/commandline/container_port.md b/docs/reference/commandline/container_port.md index bf27663ee7..d36212c9c2 100644 --- a/docs/reference/commandline/container_port.md +++ b/docs/reference/commandline/container_port.md @@ -1,4 +1,4 @@ -# container port +# port List port mappings or a specific mapping for the container @@ -10,6 +10,33 @@ List port mappings or a specific mapping for the container -## Description +## Examples -See [docker port](port.md) for more information. +### Show all mapped ports + +You can find out all the ports mapped by not specifying a `PRIVATE_PORT`, or +just a specific mapping: + +```console +$ 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 +``` diff --git a/docs/reference/commandline/container_rename.md b/docs/reference/commandline/container_rename.md index ecb5c786d5..b445a74ede 100644 --- a/docs/reference/commandline/container_rename.md +++ b/docs/reference/commandline/container_rename.md @@ -1,4 +1,4 @@ -# container rename +# rename Rename a container @@ -12,4 +12,10 @@ Rename a container ## Description -See [docker rename](rename.md) for more information. +The `docker rename` command renames a container. + +## Examples + +```console +$ docker rename my_container my_new_container +``` diff --git a/docs/reference/commandline/container_restart.md b/docs/reference/commandline/container_restart.md index 2a6d411667..7eb5b033dc 100644 --- a/docs/reference/commandline/container_restart.md +++ b/docs/reference/commandline/container_restart.md @@ -1,4 +1,4 @@ -# container restart +# restart Restart one or more containers @@ -17,6 +17,8 @@ Restart one or more containers -## Description +## Examples -See [docker restart](restart.md) for more information. +```console +$ docker restart my_container +``` diff --git a/docs/reference/commandline/container_rm.md b/docs/reference/commandline/container_rm.md index 58b0f0deda..cbb8b81c45 100644 --- a/docs/reference/commandline/container_rm.md +++ b/docs/reference/commandline/container_rm.md @@ -1,4 +1,4 @@ -# container rm +# rm Remove one or more containers @@ -9,15 +9,102 @@ Remove one or more containers ### Options -| Name | Type | Default | Description | -|:------------------|:-----|:--------|:--------------------------------------------------------| -| `-f`, `--force` | | | Force the removal of a running container (uses SIGKILL) | -| `-l`, `--link` | | | Remove the specified link | -| `-v`, `--volumes` | | | Remove anonymous volumes associated with the container | +| Name | Type | Default | Description | +|:------------------------------------------|:-----|:--------|:--------------------------------------------------------| +| [`-f`](#force), [`--force`](#force) | | | Force the removal of a running container (uses SIGKILL) | +| [`-l`](#link), [`--link`](#link) | | | Remove the specified link | +| [`-v`](#volumes), [`--volumes`](#volumes) | | | Remove anonymous volumes associated with the container | -## Description +## Examples -See [docker rm](rm.md) for more information. +### Remove a container + +This removes the container referenced under the link `/redis`. + +```console +$ docker rm /redis + +/redis +``` + +### Remove a link specified with `--link` on the default bridge network (--link) + +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. + +```console +$ docker rm --link /webapp/redis + +/webapp/redis +``` + +### Force-remove a running container (--force) + +This command force-removes a running container. + +```console +$ 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 + +Use the [`docker container prune`](container_prune.md) command to remove all +stopped containers, or refer to the [`docker system prune`](system_prune.md) +command to remove unused containers in addition to other Docker resources, such +as (unused) images and networks. + +Alternatively, you can use the `docker ps` with the `-q` / `--quiet` option to +generate a list of container IDs to remove, and use that list as argument for +the `docker rm` command. + +Combining commands can be more flexible, but is less portable as it depends +on features provided by the shell, and the exact syntax may differ depending on +what shell is used. To use this approach on Windows, consider using PowerShell +or Bash. + +The example below uses `docker ps -q` to print the IDs of all containers that +have exited (`--filter status=exited`), and removes those containers with +the `docker rm` command: + +```console +$ docker rm $(docker ps --filter status=exited -q) +``` + +Or, using the `xargs` Linux utility: + +```console +$ docker ps --filter status=exited -q | xargs docker rm +``` + +### Remove a container and its volumes (-v, --volumes) + +```console +$ docker rm --volumes 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 + +```console +$ 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`. diff --git a/docs/reference/commandline/container_run.md b/docs/reference/commandline/container_run.md index f5449e8456..de40a83f33 100644 --- a/docs/reference/commandline/container_run.md +++ b/docs/reference/commandline/container_run.md @@ -1,4 +1,4 @@ -# container run +# run Create and run a new container from an image @@ -9,115 +9,1460 @@ Create and run a new container from an image ### Options -| Name | Type | Default | Description | -|:--------------------------|:--------------|:----------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `--add-host` | `list` | | Add a custom host-to-IP mapping (host:ip) | -| `--annotation` | `map` | `map[]` | Add an annotation to the container (passed through to the OCI runtime) | -| `-a`, `--attach` | `list` | | Attach to STDIN, STDOUT or STDERR | -| `--blkio-weight` | `uint16` | `0` | Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) | -| `--blkio-weight-device` | `list` | | Block IO weight (relative device weight) | -| `--cap-add` | `list` | | Add Linux capabilities | -| `--cap-drop` | `list` | | Drop Linux capabilities | -| `--cgroup-parent` | `string` | | Optional parent cgroup for the container | -| `--cgroupns` | `string` | | 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) | -| `--cidfile` | `string` | | Write the container ID to the file | -| `--cpu-count` | `int64` | `0` | CPU count (Windows only) | -| `--cpu-percent` | `int64` | `0` | CPU percent (Windows only) | -| `--cpu-period` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) period | -| `--cpu-quota` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) quota | -| `--cpu-rt-period` | `int64` | `0` | Limit CPU real-time period in microseconds | -| `--cpu-rt-runtime` | `int64` | `0` | Limit CPU real-time runtime in microseconds | -| `-c`, `--cpu-shares` | `int64` | `0` | CPU shares (relative weight) | -| `--cpus` | `decimal` | | Number of CPUs | -| `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) | -| `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) | -| `-d`, `--detach` | | | Run container in background and print container ID | -| `--detach-keys` | `string` | | Override the key sequence for detaching a container | -| `--device` | `list` | | Add a host device to the container | -| `--device-cgroup-rule` | `list` | | Add a rule to the cgroup allowed devices list | -| `--device-read-bps` | `list` | | Limit read rate (bytes per second) from a device | -| `--device-read-iops` | `list` | | Limit read rate (IO per second) from a device | -| `--device-write-bps` | `list` | | Limit write rate (bytes per second) to a device | -| `--device-write-iops` | `list` | | Limit write rate (IO per second) to a device | -| `--disable-content-trust` | | | Skip image verification | -| `--dns` | `list` | | Set custom DNS servers | -| `--dns-option` | `list` | | Set DNS options | -| `--dns-search` | `list` | | Set custom DNS search domains | -| `--domainname` | `string` | | Container NIS domain name | -| `--entrypoint` | `string` | | Overwrite the default ENTRYPOINT of the image | -| `-e`, `--env` | `list` | | Set environment variables | -| `--env-file` | `list` | | Read in a file of environment variables | -| `--expose` | `list` | | Expose a port or a range of ports | -| `--gpus` | `gpu-request` | | GPU devices to add to the container ('all' to pass all GPUs) | -| `--group-add` | `list` | | Add additional groups to join | -| `--health-cmd` | `string` | | Command to run to check health | -| `--health-interval` | `duration` | `0s` | Time between running the check (ms\|s\|m\|h) (default 0s) | -| `--health-retries` | `int` | `0` | Consecutive failures needed to report unhealthy | -| `--health-start-interval` | `duration` | `0s` | Time between running the check during the start period (ms\|s\|m\|h) (default 0s) | -| `--health-start-period` | `duration` | `0s` | Start period for the container to initialize before starting health-retries countdown (ms\|s\|m\|h) (default 0s) | -| `--health-timeout` | `duration` | `0s` | Maximum time to allow one check to run (ms\|s\|m\|h) (default 0s) | -| `--help` | | | Print usage | -| `-h`, `--hostname` | `string` | | Container host name | -| `--init` | | | Run an init inside the container that forwards signals and reaps processes | -| `-i`, `--interactive` | | | Keep STDIN open even if not attached | -| `--io-maxbandwidth` | `bytes` | `0` | Maximum IO bandwidth limit for the system drive (Windows only) | -| `--io-maxiops` | `uint64` | `0` | Maximum IOps limit for the system drive (Windows only) | -| `--ip` | `string` | | IPv4 address (e.g., 172.30.100.104) | -| `--ip6` | `string` | | IPv6 address (e.g., 2001:db8::33) | -| `--ipc` | `string` | | IPC mode to use | -| `--isolation` | `string` | | Container isolation technology | -| `--kernel-memory` | `bytes` | `0` | Kernel memory limit | -| `-l`, `--label` | `list` | | Set meta data on a container | -| `--label-file` | `list` | | Read in a line delimited file of labels | -| `--link` | `list` | | Add link to another container | -| `--link-local-ip` | `list` | | Container IPv4/IPv6 link-local addresses | -| `--log-driver` | `string` | | Logging driver for the container | -| `--log-opt` | `list` | | Log driver options | -| `--mac-address` | `string` | | Container MAC address (e.g., 92:d0:c6:0a:29:33) | -| `-m`, `--memory` | `bytes` | `0` | Memory limit | -| `--memory-reservation` | `bytes` | `0` | Memory soft limit | -| `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: '-1' to enable unlimited swap | -| `--memory-swappiness` | `int64` | `-1` | Tune container memory swappiness (0 to 100) | -| `--mount` | `mount` | | Attach a filesystem mount to the container | -| `--name` | `string` | | Assign a name to the container | -| `--network` | `network` | | Connect a container to a network | -| `--network-alias` | `list` | | Add network-scoped alias for the container | -| `--no-healthcheck` | | | Disable any container-specified HEALTHCHECK | -| `--oom-kill-disable` | | | Disable OOM Killer | -| `--oom-score-adj` | `int` | `0` | Tune host's OOM preferences (-1000 to 1000) | -| `--pid` | `string` | | PID namespace to use | -| `--pids-limit` | `int64` | `0` | Tune container pids limit (set -1 for unlimited) | -| `--platform` | `string` | | Set platform if server is multi-platform capable | -| `--privileged` | | | Give extended privileges to this container | -| `-p`, `--publish` | `list` | | Publish a container's port(s) to the host | -| `-P`, `--publish-all` | | | Publish all exposed ports to random ports | -| `--pull` | `string` | `missing` | Pull image before running (`always`, `missing`, `never`) | -| `-q`, `--quiet` | | | Suppress the pull output | -| `--read-only` | | | Mount the container's root filesystem as read only | -| `--restart` | `string` | `no` | Restart policy to apply when a container exits | -| `--rm` | | | Automatically remove the container when it exits | -| `--runtime` | `string` | | Runtime to use for this container | -| `--security-opt` | `list` | | Security Options | -| `--shm-size` | `bytes` | `0` | Size of /dev/shm | -| `--sig-proxy` | | | Proxy received signals to the process | -| `--stop-signal` | `string` | | Signal to stop the container | -| `--stop-timeout` | `int` | `0` | Timeout (in seconds) to stop a container | -| `--storage-opt` | `list` | | Storage driver options for the container | -| `--sysctl` | `map` | `map[]` | Sysctl options | -| `--tmpfs` | `list` | | Mount a tmpfs directory | -| `-t`, `--tty` | | | Allocate a pseudo-TTY | -| `--ulimit` | `ulimit` | | Ulimit options | -| `-u`, `--user` | `string` | | Username or UID (format: [:]) | -| `--userns` | `string` | | User namespace to use | -| `--uts` | `string` | | UTS namespace to use | -| `-v`, `--volume` | `list` | | Bind mount a volume | -| `--volume-driver` | `string` | | Optional volume driver for the container | -| `--volumes-from` | `list` | | Mount volumes from the specified container(s) | -| `-w`, `--workdir` | `string` | | Working directory inside the container | +| Name | Type | Default | Description | +|:------------------------------------------------------|:--------------|:----------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [`--add-host`](#add-host) | `list` | | Add a custom host-to-IP mapping (host:ip) | +| `--annotation` | `map` | `map[]` | Add an annotation to the container (passed through to the OCI runtime) | +| [`-a`](#attach), [`--attach`](#attach) | `list` | | Attach to STDIN, STDOUT or STDERR | +| `--blkio-weight` | `uint16` | `0` | Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) | +| `--blkio-weight-device` | `list` | | Block IO weight (relative device weight) | +| `--cap-add` | `list` | | Add Linux capabilities | +| `--cap-drop` | `list` | | Drop Linux capabilities | +| [`--cgroup-parent`](#cgroup-parent) | `string` | | Optional parent cgroup for the container | +| `--cgroupns` | `string` | | 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) | +| [`--cidfile`](#cidfile) | `string` | | Write the container ID to the file | +| `--cpu-count` | `int64` | `0` | CPU count (Windows only) | +| `--cpu-percent` | `int64` | `0` | CPU percent (Windows only) | +| `--cpu-period` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) period | +| `--cpu-quota` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) quota | +| `--cpu-rt-period` | `int64` | `0` | Limit CPU real-time period in microseconds | +| `--cpu-rt-runtime` | `int64` | `0` | Limit CPU real-time runtime in microseconds | +| `-c`, `--cpu-shares` | `int64` | `0` | CPU shares (relative weight) | +| `--cpus` | `decimal` | | Number of CPUs | +| `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) | +| `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) | +| [`-d`](#detach), [`--detach`](#detach) | | | Run container in background and print container ID | +| [`--detach-keys`](#detach-keys) | `string` | | Override the key sequence for detaching a container | +| [`--device`](#device) | `list` | | Add a host device to the container | +| [`--device-cgroup-rule`](#device-cgroup-rule) | `list` | | Add a rule to the cgroup allowed devices list | +| `--device-read-bps` | `list` | | Limit read rate (bytes per second) from a device | +| `--device-read-iops` | `list` | | Limit read rate (IO per second) from a device | +| `--device-write-bps` | `list` | | Limit write rate (bytes per second) to a device | +| `--device-write-iops` | `list` | | Limit write rate (IO per second) to a device | +| `--disable-content-trust` | | | Skip image verification | +| `--dns` | `list` | | Set custom DNS servers | +| `--dns-option` | `list` | | Set DNS options | +| `--dns-search` | `list` | | Set custom DNS search domains | +| `--domainname` | `string` | | Container NIS domain name | +| `--entrypoint` | `string` | | Overwrite the default ENTRYPOINT of the image | +| [`-e`](#env), [`--env`](#env) | `list` | | Set environment variables | +| `--env-file` | `list` | | Read in a file of environment variables | +| `--expose` | `list` | | Expose a port or a range of ports | +| [`--gpus`](#gpus) | `gpu-request` | | GPU devices to add to the container ('all' to pass all GPUs) | +| `--group-add` | `list` | | Add additional groups to join | +| `--health-cmd` | `string` | | Command to run to check health | +| `--health-interval` | `duration` | `0s` | Time between running the check (ms\|s\|m\|h) (default 0s) | +| `--health-retries` | `int` | `0` | Consecutive failures needed to report unhealthy | +| `--health-start-interval` | `duration` | `0s` | Time between running the check during the start period (ms\|s\|m\|h) (default 0s) | +| `--health-start-period` | `duration` | `0s` | Start period for the container to initialize before starting health-retries countdown (ms\|s\|m\|h) (default 0s) | +| `--health-timeout` | `duration` | `0s` | Maximum time to allow one check to run (ms\|s\|m\|h) (default 0s) | +| `--help` | | | Print usage | +| `-h`, `--hostname` | `string` | | Container host name | +| [`--init`](#init) | | | Run an init inside the container that forwards signals and reaps processes | +| [`-i`](#interactive), [`--interactive`](#interactive) | | | Keep STDIN open even if not attached | +| `--io-maxbandwidth` | `bytes` | `0` | Maximum IO bandwidth limit for the system drive (Windows only) | +| `--io-maxiops` | `uint64` | `0` | Maximum IOps limit for the system drive (Windows only) | +| `--ip` | `string` | | IPv4 address (e.g., 172.30.100.104) | +| `--ip6` | `string` | | IPv6 address (e.g., 2001:db8::33) | +| [`--ipc`](#ipc) | `string` | | IPC mode to use | +| [`--isolation`](#isolation) | `string` | | Container isolation technology | +| `--kernel-memory` | `bytes` | `0` | Kernel memory limit | +| [`-l`](#label), [`--label`](#label) | `list` | | Set meta data on a container | +| `--label-file` | `list` | | Read in a line delimited file of labels | +| `--link` | `list` | | Add link to another container | +| `--link-local-ip` | `list` | | Container IPv4/IPv6 link-local addresses | +| [`--log-driver`](#log-driver) | `string` | | Logging driver for the container | +| `--log-opt` | `list` | | Log driver options | +| `--mac-address` | `string` | | Container MAC address (e.g., 92:d0:c6:0a:29:33) | +| [`-m`](#memory), [`--memory`](#memory) | `bytes` | `0` | Memory limit | +| `--memory-reservation` | `bytes` | `0` | Memory soft limit | +| `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: '-1' to enable unlimited swap | +| `--memory-swappiness` | `int64` | `-1` | Tune container memory swappiness (0 to 100) | +| [`--mount`](#mount) | `mount` | | Attach a filesystem mount to the container | +| [`--name`](#name) | `string` | | Assign a name to the container | +| [`--network`](#network) | `network` | | Connect a container to a network | +| `--network-alias` | `list` | | Add network-scoped alias for the container | +| `--no-healthcheck` | | | Disable any container-specified HEALTHCHECK | +| `--oom-kill-disable` | | | Disable OOM Killer | +| `--oom-score-adj` | `int` | `0` | Tune host's OOM preferences (-1000 to 1000) | +| [`--pid`](#pid) | `string` | | PID namespace to use | +| `--pids-limit` | `int64` | `0` | Tune container pids limit (set -1 for unlimited) | +| `--platform` | `string` | | Set platform if server is multi-platform capable | +| [`--privileged`](#privileged) | | | Give extended privileges to this container | +| [`-p`](#publish), [`--publish`](#publish) | `list` | | Publish a container's port(s) to the host | +| [`-P`](#publish-all), [`--publish-all`](#publish-all) | | | Publish all exposed ports to random ports | +| [`--pull`](#pull) | `string` | `missing` | Pull image before running (`always`, `missing`, `never`) | +| `-q`, `--quiet` | | | Suppress the pull output | +| [`--read-only`](#read-only) | | | Mount the container's root filesystem as read only | +| [`--restart`](#restart) | `string` | `no` | Restart policy to apply when a container exits | +| [`--rm`](#rm) | | | Automatically remove the container when it exits | +| `--runtime` | `string` | | Runtime to use for this container | +| [`--security-opt`](#security-opt) | `list` | | Security Options | +| `--shm-size` | `bytes` | `0` | Size of /dev/shm | +| `--sig-proxy` | | | Proxy received signals to the process | +| [`--stop-signal`](#stop-signal) | `string` | | Signal to stop the container | +| [`--stop-timeout`](#stop-timeout) | `int` | `0` | Timeout (in seconds) to stop a container | +| [`--storage-opt`](#storage-opt) | `list` | | Storage driver options for the container | +| [`--sysctl`](#sysctl) | `map` | `map[]` | Sysctl options | +| [`--tmpfs`](#tmpfs) | `list` | | Mount a tmpfs directory | +| [`-t`](#tty), [`--tty`](#tty) | | | Allocate a pseudo-TTY | +| [`--ulimit`](#ulimit) | `ulimit` | | Ulimit options | +| `-u`, `--user` | `string` | | Username or UID (format: [:]) | +| `--userns` | `string` | | User namespace to use | +| [`--uts`](#uts) | `string` | | UTS namespace to use | +| [`-v`](#volume), [`--volume`](#volume) | `list` | | Bind mount a volume | +| `--volume-driver` | `string` | | Optional volume driver for the container | +| [`--volumes-from`](#volumes-from) | `list` | | Mount volumes from the specified container(s) | +| [`-w`](#workdir), [`--workdir`](#workdir) | `string` | | Working directory inside the container | ## Description -See [docker run](run.md) for more information. +The `docker run` command runs a command in a new container, pulling the image if needed and starting the container. + +You can restart a stopped container with all its previous changes intact using `docker start`. +Use `docker ps -a` to view a list of all containers, including those that are stopped. + +## Examples + +### Assign name (--name) + +The `--name` flag lets you specify a custom identifier for a container. The +following example runs a container named `test` using the `nginx:alpine` image +in [detached mode](#detach). + +```console +$ docker run --name test -d nginx:alpine +4bed76d3ad428b889c56c1ecc2bf2ed95cb08256db22dc5ef5863e1d03252a19 +$ docker ps +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +4bed76d3ad42 nginx:alpine "/docker-entrypoint.…" 1 second ago Up Less than a second 80/tcp test +``` + +You can reference the container by name with other commands. For example, the +following commands stop and remove a container named `test`: + +```console +$ docker stop test +test +$ docker rm test +test +``` + +If you don't specify a custom name using the `--name` flag, the daemon assigns +a randomly generated name, such as `vibrant_cannon`, to the container. Using a +custom-defined name provides the benefit of having an easy-to-remember ID for a +container. + +Moreover, if you connect the container to a user-defined bridge network, other +containers on the same network can refer to the container by name via DNS. + +```console +$ docker network create mynet +cb79f45948d87e389e12013fa4d969689ed2c3316985dd832a43aaec9a0fe394 +$ docker run --name test --net mynet -d nginx:alpine +58df6ecfbc2ad7c42d088ed028d367f9e22a5f834d7c74c66c0ab0485626c32a +$ docker run --net mynet busybox:latest ping test +PING test (172.18.0.2): 56 data bytes +64 bytes from 172.18.0.2: seq=0 ttl=64 time=0.073 ms +64 bytes from 172.18.0.2: seq=1 ttl=64 time=0.411 ms +64 bytes from 172.18.0.2: seq=2 ttl=64 time=0.319 ms +64 bytes from 172.18.0.2: seq=3 ttl=64 time=0.383 ms +... +``` + +### Capture container ID (--cidfile) + +To help with automation, you can have Docker write the container ID out to a +file of your choosing. This is similar to how some programs might write out +their process ID to a file (you might've seen them as PID files): + +```console +$ docker run --cidfile /tmp/docker_test.cid ubuntu echo "test" +``` + +This creates a container and prints `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 returns an error. Docker closes this +file when `docker run` exits. + +### PID settings (--pid) + +```text +--pid="" : Set the PID (Process) Namespace mode for the container, + 'container:': joins another container's PID namespace + 'host': use the host's PID namespace inside the container +``` + +By default, all containers have the PID namespace enabled. + +PID namespace provides separation of processes. The PID Namespace removes the +view of the system processes, and allows process ids to be reused including +PID 1. + +In certain cases you want your container to share the host's process namespace, +allowing processes within the container to see all of the processes on the +system. For example, you could build a container with debugging tools like +`strace` or `gdb`, but want to use these tools when debugging processes within +the container. + +#### Example: run htop inside a container + +To run `htop` in a container that shares the process namespac of the host: + +1. Run an alpine container with the `--pid=host` option: + + ```console + $ docker run --rm -it --pid=host alpine + ``` + +2. Install `htop` in the container: + + ```console + / # apk add htop + fetch https://dl-cdn.alpinelinux.org/alpine/v3.18/main/aarch64/APKINDEX.tar.gz + fetch https://dl-cdn.alpinelinux.org/alpine/v3.18/community/aarch64/APKINDEX.tar.gz + (1/3) Installing ncurses-terminfo-base (6.4_p20230506-r0) + (2/3) Installing libncursesw (6.4_p20230506-r0) + (3/3) Installing htop (3.2.2-r1) + Executing busybox-1.36.1-r2.trigger + OK: 9 MiB in 18 packages + ``` + +3. Invoke the `htop` command. + + ```console + / # htop + ``` + +#### Example, join another container's PID namespace + +Joining another container's PID namespace can be useful for debugging that +container. + +1. Start a container running a Redis server: + + ```console + $ docker run --rm --name my-nginx -d nginx:alpine + ``` + +2. Run an Alpine container that attaches the `--pid` namespace to the + `my-nginx` container: + + ```console + $ docker run --rm -it --pid=container:my-nginx \ + --cap-add SYS_PTRACE \ + --security-opt seccomp=unconfined \ + alpine + ``` + +3. Install `strace` in the Alpine container: + + ```console + / # apk add strace + ``` + +4. Attach to process 1, the process ID of the `my-nginx` container: + + ```console + / # strace -p 1 + strace: Process 1 attached + ``` + +### UTS settings (--uts) + +```text +--uts="" : Set the UTS namespace mode for the container + 'host': use the host's UTS namespace inside the container +``` + +The UTS namespace is for setting the hostname and the domain that's visible to +running processes in that namespace. By default, all containers, including +those with `--network=host`, have their own UTS namespace. Setting `--uts` to +`host` results in the container using the same UTS namespace as the host. + +> **Note** +> +> Docker disallows combining the `--hostname` and `--domainname` flags with +> `--uts=host`. This is to prevent containers running in the host's UTS +> namespace from attempting to change the hosts' configuration. + +You may wish to share the UTS namespace with the host if you would like the +hostname of the container to change as the hostname of the host changes. A more +advanced use case would be changing the host's hostname from a container. + +### IPC settings (--ipc) + +```text +--ipc="MODE" : Set the IPC mode for the container +``` + +The `--ipc` flag accepts the following values: + +| Value | Description | +|:---------------------------|:----------------------------------------------------------------------------------| +| "" | Use daemon's default. | +| "none" | Own private IPC namespace, with /dev/shm not mounted. | +| "private" | Own private IPC namespace. | +| "shareable" | Own private IPC namespace, with a possibility to share it with other containers. | +| "container:<_name-or-ID_>" | Join another ("shareable") container's IPC namespace. | +| "host" | Use the host system's IPC namespace. | + +If not specified, daemon default is used, which can either be `"private"` +or `"shareable"`, depending on the daemon version and configuration. + +[System V interprocess communication (IPC)](https://linux.die.net/man/5/ipc) +namespaces provide separation of named shared memory segments, semaphores and +message queues. + +Shared memory segments are used to accelerate inter-process communication at +memory speed, rather than through pipes or through the network stack. Shared +memory is commonly used by databases and custom-built (typically C/OpenMPI, +C++/using boost libraries) high performance applications for scientific +computing and financial services industries. If these types of applications +are broken into multiple containers, you might need to share the IPC mechanisms +of the containers, using `"shareable"` mode for the main (i.e. "donor") +container, and `"container:"` for other containers. + +### Full container capabilities (--privileged) + +The following example doesn't work, because by default, Docker drops most +potentially dangerous kernel capabilities, including `CAP_SYS_ADMIN ` (which is +required to mount filesystems). + +```console +$ docker run -t -i --rm ubuntu bash +root@bc338942ef20:/# mount -t tmpfs none /mnt +mount: permission denied +``` + +It works when you add the `--privileged` flag: + +```console +$ 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, --workdir) + +```console +$ docker run -w /path/to/dir/ -i -t ubuntu pwd +``` + +The `-w` option runs the command executed inside the directory specified, in this example, +`/path/to/dir/`. If the path doesn't exist, Docker creates it inside the container. + +### Set storage driver options per container (--storage-opt) + +```console +$ docker run -it --storage-opt size=120G fedora /bin/bash +``` + +This (size) constraints the container filesystem size to 120G at creation time. +This option is only available for the `btrfs`, `overlay2`, `windowsfilter`, +and `zfs` storage drivers. + +For the `overlay2` storage driver, the size option is only available if the +backing filesystem is `xfs` and mounted with the `pquota` mount option. +Under these conditions, you can pass any size less than the backing filesystem size. + +For the `windowsfilter`, `btrfs`, and `zfs` storage drivers, you cannot pass a +size less than the Default BaseFS Size. + +### Mount tmpfs (--tmpfs) + +The `--tmpfs` flag lets you create a `tmpfs` mount. + +The options that you can pass to `--tmpfs` are identical to the Linux `mount -t +tmpfs -o` command. The following example mounts an empty `tmpfs` into the +container with the `rw`, `noexec`, `nosuid`, `size=65536k` options. + +```console +$ docker run -d --tmpfs /run:rw,noexec,nosuid,size=65536k my_image +``` + +For more information, see [tmpfs mounts](https://docs.docker.com/storage/tmpfs/). + +### Mount volume (-v) + +```console +$ docker run -v $(pwd):$(pwd) -w $(pwd) -i -t ubuntu pwd +``` + +The example above mounts the current directory into the container at the same path +using the `-v` flag, sets it as the working directory, and then runs the `pwd` command inside the container. + +As of Docker Engine version 23, you can use relative paths on the host. + +```console +$ docker run -v ./content:/content -w /content -i -t ubuntu pwd +``` + +The example above mounts the `content` directory in the current directory into the container at the +`/content` path using the `-v` flag, sets it as the working directory, and then +runs the `pwd` command inside the container. + +```console +$ 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 +automatically creates this directory on the host for you. In the +example above, Docker creates the `/doesnt/exist` +folder before starting your container. + +### Mount volume read-only (--read-only) + +```console +$ docker run --read-only -v /icanwrite busybox touch /icanwrite/here +``` + +You can use volumes in combination with the `--read-only` flag 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. + +```console +$ 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, you must specify the paths using Windows-style path 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 fails 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 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 +[Bind mounts](https://docs.docker.com/storage/bind-mounts/). + +Even though there is no plan to deprecate `--volume`, usage of `--mount` is recommended. + +Examples: + +```console +$ docker run --read-only --mount type=volume,target=/icanwrite busybox touch /icanwrite/here +``` + +```console +$ docker run -t -i --mount type=bind,src=/data,dst=/data busybox sh +``` + +### Publish or expose port (-p, --expose) + +```console +$ docker run -p 127.0.0.1:80:8080/tcp nginx:alpine +``` + +This binds port `8080` of the container to TCP port `80` on `127.0.0.1` of the +host. You can also specify `udp` and `sctp` ports. The [Networking overview +page](https://docs.docker.com/network/) explains in detail how to publish ports +with Docker. + +> **Note** +> +> If you don't specify an IP address (i.e., `-p 80:80` instead of `-p +> 127.0.0.1:80:80`) when publishing a container's ports, Docker publishes the +> port on all interfaces (address `0.0.0.0`) by default. These ports are +> externally accessible. This also applies if you configured UFW to block this +> specific port, as Docker manages its own iptables rules. [Read +> more](https://docs.docker.com/network/packet-filtering-firewalls/) + +```console +$ docker run --expose 80 nginx:alpine +``` + +This exposes port `80` of the container without publishing the port to the host +system's interfaces. + +### Publish all exposed ports (-P, --publish-all) + +```console +$ docker run -P nginx:alpine +``` + +The `-P`, or `--publish-all`, flag publishes all the exposed ports to the host. +Docker binds each exposed port to a random port on the host. + +The `-P` flag only publishes port numbers that are explicitly flagged as +exposed, either using the Dockerfile `EXPOSE` instruction or the `--expose` +flag for the `docker run` command. + +The range of ports are within an *ephemeral port range* defined by +`/proc/sys/net/ipv4/ip_local_port_range`. Use the `-p` flag to explicitly map a +single port or range of ports. + +### Set the pull policy (--pull) + +Use the `--pull` flag to set the image pull policy when creating (and running) +the container. + +The `--pull` flag can take one of these values: + +| Value | Description | +|:--------------------|:------------------------------------------------------------------------------------------------------------------| +| `missing` (default) | Pull the image if it was not found in the image cache, or use the cached image otherwise. | +| `never` | Do not pull the image, even if it's missing, and produce an error if the image does not exist in the image cache. | +| `always` | Always perform a pull before creating the container. | + +When creating (and running) a container from an image, the daemon checks if the +image exists in the local image cache. If the image is missing, an error is +returned to the CLI, allowing it to initiate a pull. + +The default (`missing`) is to only pull the image if it's not present in the +daemon's image cache. This default allows you to run images that only exist +locally (for example, images you built from a Dockerfile, but that have not +been pushed to a registry), and reduces networking. + +The `always` option always initiates a pull before creating the container. This +option makes sure the image is up-to-date, and prevents you from using outdated +images, but may not be suitable in situations where you want to test a locally +built image before pushing (as pulling the image overwrites the existing image +in the image cache). + +The `never` option disables (implicit) pulling images when creating containers, +and only uses images that are available in the image cache. If the specified +image is not found, an error is produced, and the container is not created. +This option is useful in situations where networking is not available, or to +prevent images from being pulled implicitly when creating containers. + +The following example shows `docker run` with the `--pull=never` option set, +which produces en error as the image is missing in the image-cache: + +```console +$ docker run --pull=never hello-world +docker: Error response from daemon: No such image: hello-world:latest. +``` + +### Set environment variables (-e, --env, --env-file) + +```console +$ 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 +defined in the Dockerfile of the image you're running. + +You can define the variable and its value when running the container: + +```console +$ docker run --env VAR1=value1 --env VAR2=value2 ubuntu env | grep VAR +VAR1=value1 +VAR2=value2 +``` + +You can also use variables exported to your local environment: + +```console +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 isn't exported in your local +environment, the variable is unset 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. Lines beginning with `#` are treated as line comments and are +ignored, whereas a `#` appearing anywhere else in a line is treated as part of +the variable value. + +```console +$ cat env.list +# This is a comment +VAR1=value1 +VAR2=value2 +USER + +$ docker run --env-file env.list ubuntu env | grep -E 'VAR|USER' +VAR1=value1 +VAR2=value2 +USER=jonzeolla +``` + +### 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: + +```console +$ 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: + +```console +$ 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 shows 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](https://docs.docker.com/config/labels-custom-metadata/). + +### Connect a container to a network (--network) + +To start a container and connect it to a network, use the `--network` option. + +The following commands create a network named `my-net` and adds a `busybox` container +to the `my-net` network. + +```console +$ docker network create my-net +$ 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. To assign a +static IP to containers, you must specify subnet block for the network. + +```console +$ docker network create --subnet 192.0.2.0/24 my-net +$ docker run -itd --network=my-net --ip=192.0.2.69 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 using 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** +> +> The default bridge network only allow containers to communicate with each other using +> internal IP addresses. User-created bridge networks provide DNS resolution between +> containers using container names. + +You can disconnect a container from a network using the `docker network +disconnect` command. + +For more information on connecting a container to a network when using the `run` command, see the ["*Docker network overview*"](https://docs.docker.com/network/). + +### Mount volumes from container (--volumes-from) + +```console +$ 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. You can specify more than one container 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, +Docker mounts the volumes in the same mode (read write or read only) as +the reference container. + +Labeling systems like SELinux require placing proper labels 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. + +### Detached mode (-d, --detach) + +The `--detach` (or `-d`) flag starts a container as a background process that +doesn't occupy your terminal window. By design, containers started in detached +mode exit when the root process used to run the container exits, unless you +also specify the `--rm` option. If you use `-d` with `--rm`, the container is +removed when it exits or when the daemon exits, whichever happens first. + +Don't pass a `service x start` command to a detached container. For example, +this command attempts to start the `nginx` service. + +```console +$ docker run -d -p 80:80 my_image service nginx start +``` + +This succeeds in starting the `nginx` service inside the container. However, it +fails the detached container paradigm in that, the root process (`service nginx +start`) returns and the detached container stops as designed. As a result, the +`nginx` service starts but can't be used. Instead, to start a process such as +the `nginx` web server do the following: + +```console +$ docker run -d -p 80:80 my_image nginx -g 'daemon off;' +``` + +To do input/output with a detached container use network connections or shared +volumes. These are required because the container is no longer listening to the +command line where `docker run` was run. + +### Override the detach sequence (--detach-keys) + +Use the `--detach-keys` option to 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). + +### Add host device to container (--device) + +```console +$ docker run -it --rm \ + --device=/dev/sdc:/dev/xvdc \ + --device=/dev/sdd \ + --device=/dev/zero:/dev/foobar \ + ubuntu ls -l /dev/{xvdc,sdd,foobar} + +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/foobar +``` + +It's often necessary to directly expose devices to a container. The `--device` +option enables that. For example, adding a specific block storage device or loop +device or audio device to an otherwise unprivileged container +(without the `--privileged` flag) and have the application directly access it. + +By default, the container is 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 Docker ignores the +specified permissions. + +```console +$ 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. You shouldn't +> add block devices that may be removed 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 you specify this option for a process-isolated Windows container, Docker makes +_all_ devices that implement the requested device interface class GUID +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, +> and produces an error if the container isolation is `hyperv`. + +### Attach to STDIN/STDOUT/STDERR (-a, --attach) + +The `--attach` (or `-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. You can specify to which of the three standard streams +(`STDIN`, `STDOUT`, `STDERR`) you'd like to connect instead, as in: + +```console +$ docker run -a stdin -a stdout -i -t ubuntu /bin/bash +``` + +The following example pipes data into a container and prints the container's ID +by attaching only to the container's `STDIN`. + +```console +$ echo "test" | docker run -i -a stdin ubuntu cat - +``` + +The following example doesn't print anything to the console unless there's an +error because output is only attached to the `STDERR` of the container. The +container's logs still store what's written to `STDERR` and `STDOUT`. + +```console +$ docker run -a stderr ubuntu echo test +``` + +The following example shows a way of using `--attach` to pipe a file into a +container. The command prints the container's ID after the build completes and +you can retrieve the build logs 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. + +```console +$ cat somefile | docker run -i -a stdin mybuilder dobuild +``` + +> **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 +> doesn't terminate on `SIGINT` or `SIGTERM` unless it's coded to do so. + +See also [the `docker cp` command](cp.md). + +### Keep STDIN open (-i, --interactive) + +The `--interactive` (or `-i`) flag keeps the container's `STDIN` open, and lets +you send input to the container through standard input. + +```console +$ echo hello | docker run --rm -i busybox cat +hello +``` + +The `-i` flag is most often used together with the `--tty` flag to bind the I/O +streams of the container to a pseudo terminal, creating an interactive terminal +session for the container. See [Allocate a pseudo-TTY](#tty) for more examples. + +```console +$ docker run -it debian +root@10a3e71492b0:/# factor 90 +90: 2 3 3 5 +root@10a3e71492b0:/# exit +exit +``` + +Using the `-i` flag on its own allows for composition, such as piping input to +containers: + +```console +$ docker run --rm -i busybox echo "foo bar baz" \ + | docker run --rm -i busybox awk '{ print $2 }' \ + | docker run --rm -i busybox rev +rab +``` + +### Specify an init process + +You can use the `--init` flag to indicate that an init process should be used as +the PID 1 in the container. Specifying an init process ensures the usual +responsibilities of an init system, such as reaping zombie processes, are +performed inside the created container. + +The default init process used is the first `docker-init` executable found in the +system path of the Docker daemon process. This `docker-init` binary, included in +the default installation, is backed by [tini](https://github.com/krallin/tini). + +### Allocate a pseudo-TTY (-t, --tty) + +The `--tty` (or `-t`) flag attaches a pseudo-TTY to the container, connecting +your terminal to the I/O streams of the container. Allocating a pseudo-TTY to +the container means that you get access to input and output feature that TTY +devices provide. + +For example, the following command runs the `passwd` command in a `debian` +container, to set a new password for the `root` user. + +```console +$ docker run -i debian passwd root +New password: karjalanpiirakka9 +Retype new password: karjalanpiirakka9 +passwd: password updated successfully +``` + +If you run this command with only the `-i` flag (which lets you send text to +`STDIN` of the container), the `passwd` prompt displays the password in plain +text. However, if you try the same thing but also adding the `-t` flag, the +password is hidden: + +```console +$ docker run -i debian passwd root +New password: +Retype new password: +passwd: password updated successfully +``` + +This is because `passwd` can suppress the output of characters to the terminal +using the echo-off TTY feature. + +You can use the `-t` flag without `-i` flag. This still allocates a pseudo-TTY +to the container, but with no way of writing to `STDIN`. The only time this +might be useful is if the output of the container requires a TTY environment. + +### Specify custom cgroups + +Using the `--cgroup-parent` flag, you can pass a specific cgroup to run a +container in. This allows you to create and manage cgroups on their own. You can +define custom resources for those cgroups and put containers under a common +parent group. + +### Using dynamically created devices (--device-cgroup-rule) + +Docker assigns devices available to a container at creation time. The +assigned devices are added to the cgroup.allow file and +created into the container when it runs. This poses a problem when +you need to add a new device to running container. + +One solution is to add a more permissive rule to a container +allowing it access to a wider range of devices. For example, supposing +the container needs access to a character device with major `42` and +any number of minor numbers (added as new devices appear), add the +following rule: + +```console +$ docker run -d --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**: You still need to explicitly add initially present devices to the +> `docker run` / `docker create` command. + +### Access an NVIDIA GPU + +The `--gpus` flag allows you to access NVIDIA GPU resources. First you need to +install the [nvidia-container-runtime](https://nvidia.github.io/nvidia-container-runtime/). + +Read [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 you provide no value, Docker uses all +available GPUs. The example below exposes all available GPUs. + +```console +$ docker run -it --rm --gpus all ubuntu nvidia-smi +``` + +Use the `device` option to specify GPUs. The example below exposes a specific +GPU. + +```console +$ docker run -it --rm --gpus device=GPU-3a23c669-1f69-c64e-cf85-44e9b07e7a2a ubuntu nvidia-smi +``` + +The example below exposes the first and third GPUs. + +```console +$ docker run -it --rm --gpus '"device=0,2"' ubuntu nvidia-smi +``` + +### Restart policies (--restart) + +Use the `--restart` flag 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's 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 tries to restart the container indefinitely. The container always starts on daemon startup, regardless of the current state of the container. | + +```console +$ docker run --restart=always redis +``` + +This runs the `redis` container with a restart policy of **always**. +If the container exits, Docker restarts it. + +When a restart policy is active on a container, it shows as either `Up` or +`Restarting` in [`docker ps`](ps.md). It can also be useful to use [`docker +events`](events.md) to see the restart policy in effect. + +An increasing delay (double the previous delay, starting at 100 milliseconds) +is added before each restart to prevent flooding the server. This means the +daemon waits for 100 ms, then 200 ms, 400, 800, 1600, and so on until either +the `on-failure` limit, the maximum delay of 1 minute is hit, or when you +`docker stop` or `docker rm -f` the container. + +If a container is successfully restarted (the container is started and runs +for at least 10 seconds), the delay is reset to its default value of 100 ms. + +#### Specify a limit for restart attempts + +You can specify the maximum amount of times Docker attempts to restart the +container when using the **on-failure** policy. By default, Docker never stops +attempting to restart the container. + +The following example runs the `redis` container with a restart policy of +**on-failure** and a maximum restart count of 10. + +```console +$ docker run --restart=on-failure:10 redis +``` + +If the `redis` container exits with a non-zero exit status more than 10 times +in a row, Docker stops trying to restart the container. Providing a maximum +restart limit is only valid for the **on-failure** policy. + +#### Inspect container restarts + +The number of (attempted) restarts for a container can be obtained using the +[`docker inspect`](commandline/inspect.md) command. For example, to get the +number of restarts for container "my-container"; + +```console +$ docker inspect -f "{{ .RestartCount }}" my-container +2 +``` + +Or, to get the last time the container was (re)started; + +```console +$ docker inspect -f "{{ .State.StartedAt }}" my-container +2015-03-04T23:47:07.691840179Z +``` + +Combining `--restart` (restart policy) with the `--rm` (clean up) flag results +in an error. On container restart, attached clients are disconnected. + +### Clean up (--rm) + +By default, a container's file system persists even after the container exits. +This makes debugging a lot easier, since you can inspect the container's final +state and you retain all your data. + +If you are running short-term **foreground** processes, these container file +systems can start to pile up. If you'd like Docker to automatically clean up +the container and remove the file system when the container exits, use the +`--rm` flag: + +```text +--rm=false: Automatically remove the container when it exits +``` + +> **Note** +> +> If you set the `--rm` flag, Docker also removes the anonymous volumes +> associated with the container when the container is removed. This is similar +> to running `docker rm -v my-container`. Only volumes that are specified +> without a name are removed. For example, when running the following command, +> volume `/foo` is removed, but not `/bar`: +> +> ```console +> $ docker run --rm -v /foo -v awesome:/bar busybox top +> ``` +> +> Volumes inherited via `--volumes-from` are removed with the same logic: +> if the original volume was specified with a name it isn't removed. + +### 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 +`my-hostname`: + +```console +$ docker run --add-host=my-hostname=8.8.8.8 --rm -it alpine + +/ # ping my-hostname +PING my-hostname (8.8.8.8): 56 data bytes +64 bytes from 8.8.8.8: seq=0 ttl=37 time=93.052 ms +64 bytes from 8.8.8.8: seq=1 ttl=37 time=92.467 ms +64 bytes from 8.8.8.8: seq=2 ttl=37 time=92.252 ms +^C +--- my-hostname ping statistics --- +4 packets transmitted, 4 packets received, 0% packet loss +round-trip min/avg/max = 92.209/92.495/93.052 ms +``` + +You can wrap an IPv6 address in square brackets: + +```console +$ docker run --add-host my-hostname=[2001:db8::33] --rm -it alpine +``` + +The `--add-host` flag supports a special `host-gateway` value that resolves to +the internal IP address of the host. This is useful when you want containers to +connect to services running on the host machine. + +It's conventional to use `host.docker.internal` as the hostname referring to +`host-gateway`. Docker Desktop automatically resolves this hostname, see +[Explore networking features](https://docs.docker.com/desktop/networking/#i-want-to-connect-from-a-container-to-a-service-on-the-host). + +The following example shows how the special `host-gateway` value works. The +example runs an HTTP server that serves a file from host to container over the +`host.docker.internal` hostname, which resolves to the host's internal IP. + +```console +$ echo "hello from host!" > ./hello +$ python3 -m http.server 8000 +Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ... +$ docker run \ + --add-host host.docker.internal=host-gateway \ + curlimages/curl -s host.docker.internal:8000/hello +hello from host! +``` + +The `--add-host` flag also accepts a `:` separator, for example: + +```console +$ docker run --add-host=my-hostname:8.8.8.8 --rm -it alpine +``` + +### Logging drivers (--log-driver) + +The container can have a different logging driver than the Docker daemon. Use +the `--log-driver=` with the `docker run` command to configure the +container's logging driver. + +To learn about the supported logging drivers and how to use them, refer to +[Configure logging drivers](https://docs.docker.com/config/containers/logging/configure/). + +To disable logging for a container, set the `--log-driver` flag to `none`: + +```console +$ docker run --log-driver=none -d nginx:alpine +5101d3b7fe931c27c2ba0e65fd989654d297393ad65ae238f20b97a020e7295b +$ docker logs 5101d3b +Error response from daemon: configured logging driver does not support reading +``` + +### 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. +Specify `--ulimit` with a soft and hard limit in the format +`=[:]`. For example: + +```console +$ docker run --ulimit nofile=1024:1024 --rm debian sh -c "ulimit -n" +1024 +``` + +> **Note** +> +> If you don't provide a hard limit value, Docker uses the soft limit value +> for both values. If you don't provide any values, they are inherited from +> the default `ulimits` set on the daemon. + +> **Note** +> +> The `as` option is deprecated. +> In other words, the following script is not supported: +> +> ```console +> $ docker run -it --ulimit as=1024 fedora /bin/bash +> ``` + +Docker sends the values to the appropriate OS `syscall` and 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 Linux uses `nproc` to set the +maximum number of processes available to a user, not to a container. For example, start four +containers with `daemon` user: + +```console +$ 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 a "[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 sends the system call signal to the +container to exit. This signal can be a signal name in the format `SIG`, +for instance `SIGKILL`, or an unsigned number that matches a position in the +kernel's syscall table, for instance `9`. + +The default value is defined by [`STOPSIGNAL`](https://docs.docker.com/engine/reference/builder/#stopsignal) +in the image, or `SIGTERM` if the image has no `STOPSIGNAL` defined. + +### Optional security options (--security-opt) + +| Option | Description | +|:------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--security-opt="label=user:USER"` | Set the label user for the container | +| `--security-opt="label=role:ROLE"` | Set the label role for the container | +| `--security-opt="label=type:TYPE"` | Set the label type for the container | +| `--security-opt="label=level:LEVEL"` | Set the label level for the container | +| `--security-opt="label=disable"` | Turn off label confinement for the container | +| `--security-opt="apparmor=PROFILE"` | Set the apparmor profile to be applied to the container | +| `--security-opt="no-new-privileges=true"` | Disable container processes from gaining new privileges | +| `--security-opt="seccomp=unconfined"` | Turn off seccomp confinement for the container | +| `--security-opt="seccomp=builtin"` | Use the default (built-in) seccomp profile for the container. This can be used to enable seccomp for a container running on a daemon with a custom default profile set, or with seccomp disabled ("unconfined"). | +| `--security-opt="seccomp=profile.json"` | White-listed syscalls seccomp Json file to be used as a seccomp filter | + +The `--security-opt` flag lets you override the default labeling scheme for a +container. Specifying the level in the following command allows you to share +the same content between containers. + +```console +$ docker run --security-opt label=level:s0:c100,c200 -it fedora bash +``` + +> **Note** +> +> Automatic translation of MLS labels isn't supported. + +To disable the security labeling for a container entirely, you can use +`label=disable`: + +```console +$ docker run --security-opt label=disable -it ubuntu bash +``` + +If you want a tighter security policy on the processes within a container, you +can specify a custom `type` label. The following example runs a container +that's only allowed to listen on Apache ports: + +```console +$ docker run --security-opt label=type:svirt_apache_t -it ubuntu bash +``` + +> **Note** +> +> You would have to write policy defining a `svirt_apache_t` type. + +To prevent your container processes from gaining additional privileges, you can +use the following command: + +```console +$ docker run --security-opt no-new-privileges -it ubuntu bash +``` + +This means that commands that raise privileges such as `su` or `sudo` no longer work. +It also causes any seccomp filters to be applied later, after privileges have been dropped +which may mean you can have a more restrictive set of filters. +For more details, see the [kernel documentation](https://www.kernel.org/doc/Documentation/prctl/no_new_privs.txt). + +On Windows, you can use the `--security-opt` flag 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 number of seconds to wait for the container +to stop after sending the pre-defined (see `--stop-signal`) system call signal. +If the container does not exit after the timeout elapses, it's forcibly killed +with a `SIGKILL` signal. + +If you set `--stop-timeout` to `-1`, no timeout is applied, and the daemon +waits indefinitely for the container to exit. + +The Daemon determines the default, and is 10 seconds for Linux containers, +and 30 seconds for Windows containers. + +### 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: + +```console +$ 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. | +| `hyperv` | Hyper-V hypervisor partition-based isolation. | + +The default isolation on Windows server operating systems is `process`, and `hyperv` +on Windows client operating systems, such as Windows 10. Process isolation has better +performance, but requires that the image and host use the same kernel version. + +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. Linux sets this +on the cgroup and applications in a container can query it at `/sys/fs/cgroup/memory/memory.limit_in_bytes`. + +On Windows, this affects containers differently depending on what type of isolation you use. + +- With `process` isolation, Windows reports 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 creates 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 (--sysctl) + +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: + +```console +$ 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. + +## Command internals + +The `docker run` command is equivalent to the following API calls: + +- `//containers/create` + - If that call returns a 404 (image not found), and depending on the `--pull` option ("always", "missing", "never") the call can trigger a `docker pull `. +- `/containers/create` again after pulling the image. +- `/containers/(id)/start` to start the container. +- `/containers/(id)/attach` to attach to the container when starting with the `-it` flags for interactive containers. diff --git a/docs/reference/commandline/container_start.md b/docs/reference/commandline/container_start.md index 9ad73bcc34..866a24921a 100644 --- a/docs/reference/commandline/container_start.md +++ b/docs/reference/commandline/container_start.md @@ -1,4 +1,4 @@ -# container start +# start Start one or more stopped containers @@ -20,6 +20,8 @@ Start one or more stopped containers -## Description +## Examples -See [docker start](start.md) for more information. +```console +$ docker start my_container +``` diff --git a/docs/reference/commandline/container_stats.md b/docs/reference/commandline/container_stats.md index 6c42550f83..f59ea7838a 100644 --- a/docs/reference/commandline/container_stats.md +++ b/docs/reference/commandline/container_stats.md @@ -1,4 +1,4 @@ -# container stats +# stats Display a live stream of container(s) resource usage statistics @@ -9,16 +9,181 @@ Display a live stream of container(s) resource usage statistics ### Options -| Name | Type | Default | Description | -|:--------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `-a`, `--all` | | | Show all containers (default shows just running) | -| `--format` | `string` | | Format output using a custom template:
'table': Print output in table format with column headers (default)
'table TEMPLATE': Print output in table format using the given Go template
'json': Print in JSON format
'TEMPLATE': Print output using the given Go template.
Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | -| `--no-stream` | | | Disable streaming stats and only pull the first result | -| `--no-trunc` | | | Do not truncate output | +| Name | Type | Default | Description | +|:----------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `-a`, `--all` | | | Show all containers (default shows just running) | +| [`--format`](#format) | `string` | | Format output using a custom template:
'table': Print output in table format with column headers (default)
'table TEMPLATE': Print output in table format using the given Go template
'json': Print in JSON format
'TEMPLATE': Print output using the given Go template.
Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | +| `--no-stream` | | | Disable streaming stats and only pull the first result | +| `--no-trunc` | | | Do not truncate output | ## Description -See [docker stats](stats.md) for more information. +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. + +## Examples + +Running `docker stats` on all running containers against a Linux daemon. + +```console +$ 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`](#format), 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 received and sent over its network interface | +| `BLOCK I/O` | The amount of data the container has written to and read 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. + +```console +$ 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` on container with name `nginx` and getting output in `json` format. + +```console +$ docker stats nginx --no-stream --format "{{ json . }}" +{"BlockIO":"0B / 13.3kB","CPUPerc":"0.03%","Container":"nginx","ID":"ed37317fbf42","MemPerc":"0.24%","MemUsage":"2.352MiB / 982.5MiB","Name":"nginx","NetIO":"539kB / 606kB","PIDs":"2"} +``` + +Running `docker stats` with customized format on all (running and stopped) containers. + +```console +$ docker stats --all --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}" fervent_panini 5acfcb1b4fd1 humble_visvesvaraya big_heisenberg + +CONTAINER CPU % MEM USAGE / LIMIT +fervent_panini 0.00% 56KiB / 15.57GiB +5acfcb1b4fd1 0.07% 32.86MiB / 15.57GiB +humble_visvesvaraya 0.00% 0B / 0B +big_heisenberg 0.00% 0B / 0B +``` + +`humble_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 +``` + +### Format the output (--format) + +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: + +```console +$ 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: + +```console +$ 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}}" + diff --git a/docs/reference/commandline/container_stop.md b/docs/reference/commandline/container_stop.md index e61890b071..d46148356b 100644 --- a/docs/reference/commandline/container_stop.md +++ b/docs/reference/commandline/container_stop.md @@ -1,4 +1,4 @@ -# container stop +# stop Stop one or more running containers @@ -19,4 +19,13 @@ Stop one or more running containers ## Description -See [docker stop](stop.md) for more information. +The main process inside the container will receive `SIGTERM`, and after a grace +period, `SIGKILL`. The first signal can be changed with the `STOPSIGNAL` +instruction in the container's Dockerfile, or the `--stop-signal` option to +`docker run`. + +## Examples + +```console +$ docker stop my_container +``` diff --git a/docs/reference/commandline/container_top.md b/docs/reference/commandline/container_top.md index f314f2a401..7974577c69 100644 --- a/docs/reference/commandline/container_top.md +++ b/docs/reference/commandline/container_top.md @@ -1,4 +1,4 @@ -# container top +# top Display the running processes of a container @@ -9,7 +9,3 @@ Display the running processes of a container - -## Description - -See [docker top](top.md) for more information. diff --git a/docs/reference/commandline/container_unpause.md b/docs/reference/commandline/container_unpause.md index bd5e34761c..a5165812cc 100644 --- a/docs/reference/commandline/container_unpause.md +++ b/docs/reference/commandline/container_unpause.md @@ -1,4 +1,4 @@ -# container unpause +# unpause Unpause all processes within one or more containers @@ -12,4 +12,20 @@ Unpause all processes within one or more containers ## Description -See [docker unpause](unpause.md) for more information. +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. + +## Examples + +```console +$ docker unpause my_container +my_container +``` + +## Related commands + +* [pause](pause.md) diff --git a/docs/reference/commandline/container_update.md b/docs/reference/commandline/container_update.md index 9095e298e9..a2dbcd7804 100644 --- a/docs/reference/commandline/container_update.md +++ b/docs/reference/commandline/container_update.md @@ -1,4 +1,4 @@ -# container update +## update Update configuration of one or more containers @@ -9,26 +9,116 @@ Update configuration of one or more containers ### Options -| Name | Type | Default | Description | -|:-----------------------|:----------|:--------|:-----------------------------------------------------------------------------| -| `--blkio-weight` | `uint16` | `0` | Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) | -| `--cpu-period` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) period | -| `--cpu-quota` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) quota | -| `--cpu-rt-period` | `int64` | `0` | Limit the CPU real-time period in microseconds | -| `--cpu-rt-runtime` | `int64` | `0` | Limit the CPU real-time runtime in microseconds | -| `-c`, `--cpu-shares` | `int64` | `0` | CPU shares (relative weight) | -| `--cpus` | `decimal` | | Number of CPUs | -| `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) | -| `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) | -| `-m`, `--memory` | `bytes` | `0` | Memory limit | -| `--memory-reservation` | `bytes` | `0` | Memory soft limit | -| `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: -1 to enable unlimited swap | -| `--pids-limit` | `int64` | `0` | Tune container pids limit (set -1 for unlimited) | -| `--restart` | `string` | | Restart policy to apply when a container exits | +| Name | Type | Default | Description | +|:---------------------------------------------------|:----------|:--------|:-----------------------------------------------------------------------------| +| `--blkio-weight` | `uint16` | `0` | Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) | +| `--cpu-period` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) period | +| `--cpu-quota` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) quota | +| `--cpu-rt-period` | `int64` | `0` | Limit the CPU real-time period in microseconds | +| `--cpu-rt-runtime` | `int64` | `0` | Limit the CPU real-time runtime in microseconds | +| [`-c`](#cpu-shares), [`--cpu-shares`](#cpu-shares) | `int64` | `0` | CPU shares (relative weight) | +| `--cpus` | `decimal` | | Number of CPUs | +| `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) | +| `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) | +| [`-m`](#memory), [`--memory`](#memory) | `bytes` | `0` | Memory limit | +| `--memory-reservation` | `bytes` | `0` | Memory soft limit | +| `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: -1 to enable unlimited swap | +| `--pids-limit` | `int64` | `0` | Tune container pids limit (set -1 for unlimited) | +| [`--restart`](#restart) | `string` | | Restart policy to apply when a container exits | ## Description -See [docker update](update.md) for more information. +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 } + +## Examples + +The following sections illustrate ways to use this command. + +### Update a container's cpu-shares (--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: + +```console +$ docker update --cpu-shares 512 abebf7571666 +``` + +### Update a container with cpu-shares and memory (-m, --memory) + +To update multiple resource configurations for multiple containers: + +```console +$ docker update --cpu-shares 512 -m 300M abebf7571666 hopeful_morse +``` + +### Update a container's kernel memory constraints (--kernel-memory) + +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.10. + +For example, if you started a container with this command: + +```console +$ docker run -dit --name test --kernel-memory 50M ubuntu bash +``` + +You can update kernel memory while the container is running: + +```console +$ docker update --kernel-memory 80M test +``` + +If you started a container without kernel memory initialized: + +```console +$ 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 (--restart) + +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: + +```console +$ 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. diff --git a/docs/reference/commandline/container_wait.md b/docs/reference/commandline/container_wait.md index 013ea92c1c..6cec6b2a02 100644 --- a/docs/reference/commandline/container_wait.md +++ b/docs/reference/commandline/container_wait.md @@ -1,4 +1,4 @@ -# container wait +# wait Block until one or more containers stop, then print their exit codes @@ -10,6 +10,37 @@ Block until one or more containers stop, then print their exit codes -## Description +> **Note** +> +> `docker wait` returns `0` when run against a container which had already +> exited before the `docker wait` command was run. -See [docker wait](wait.md) for more information. +## Examples + +Start a container in the background. + +```console +$ docker run -dit --name=my_container ubuntu bash +``` + +Run `docker wait`, which should block until the container exits. + +```console +$ docker wait my_container +``` + +In another terminal, stop the first container. The `docker wait` command above +returns the exit code. + +```console +$ docker stop my_container +``` + +This is the same `docker wait` command from above, but it now exits, returning +`0`. + +```console +$ docker wait my_container + +0 +``` diff --git a/docs/reference/commandline/cp.md b/docs/reference/commandline/cp.md index bf3741d8b2..41c9529f9f 100644 --- a/docs/reference/commandline/cp.md +++ b/docs/reference/commandline/cp.md @@ -1,4 +1,4 @@ -# cp +# docker cp Copy files/folders between a container and the local filesystem @@ -23,109 +23,3 @@ container source to stdout. -## Description - -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. - -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` doesn't create parent directories for -`DEST_PATH` if they don't 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` - -## Examples - -Copy a local file into container - -```console -$ docker cp ./some_file CONTAINER:/work -``` - -Copy files from container to local path - -```console -$ docker cp CONTAINER:/var/logs/ /tmp/app_logs -``` - -Copy a file from container to stdout. Please note `cp` command produces a tar stream - -```console -$ docker cp CONTAINER:/var/logs/app.log - | tar x -O | grep "ERROR" -``` - -### Corner cases - -It isn't possible to copy certain system files such as resources under -`/proc`, `/sys`, `/dev`, [tmpfs](run.md#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): - -```console -$ docker exec CONTAINER tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | tar Cxf DEST_PATH - -``` - -```console -$ 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`. diff --git a/docs/reference/commandline/create.md b/docs/reference/commandline/create.md index 6b598a8398..ce34f5b12c 100644 --- a/docs/reference/commandline/create.md +++ b/docs/reference/commandline/create.md @@ -1,4 +1,4 @@ -# create +# docker create Create a new container @@ -115,86 +115,3 @@ Create a new container -## Description - -The `docker container create` (or shorthand: `docker create`) command creates a -new container from the specified image, without starting it. - -When creating a container, the Docker daemon 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 container start` -(or shorthand: `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's ready to start when you need it. The initial status of the -new container is `created`. - -The `docker create` command shares most of its options with the `docker run` -command (which performs a `docker create` before starting it). Refer to the -[`docker run` command](run.md) section and the [Docker run reference](../run.md) -for details on the available flags and options. - -## Examples - -### Create and start a container - -The following example creates an interactive container with a pseudo-TTY attached, -then starts the container and attaches to it: - -```console -$ docker container create -i -t --name mycontainer alpine -6d8af538ec541dd581ebc2a24153a28329acb5268abe5ef868c1f1a261221752 - -$ docker container start --attach -i mycontainer -/ # echo hello world -hello world -``` - -The above is the equivalent of a `docker run`: - -```console -$ docker run -it --name mycontainer2 alpine -/ # echo hello world -hello world -``` - -### Initialize volumes - -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: - -```console -$ 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: - -```console -$ 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 -``` diff --git a/docs/reference/commandline/diff.md b/docs/reference/commandline/diff.md index 05f2990dbc..36185898a6 100644 --- a/docs/reference/commandline/diff.md +++ b/docs/reference/commandline/diff.md @@ -1,4 +1,4 @@ -# diff +# docker diff Inspect changes to files or directories on a container's filesystem @@ -10,44 +10,3 @@ Inspect changes to files or directories on a container's filesystem -## Description - -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. - -## Examples - -Inspect the changes to an `nginx` container: - -```console -$ 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 -``` diff --git a/docs/reference/commandline/events.md b/docs/reference/commandline/events.md index d65605e349..a5012cd6b7 100644 --- a/docs/reference/commandline/events.md +++ b/docs/reference/commandline/events.md @@ -1,4 +1,4 @@ -# events +# docker events Get real time events from the server @@ -9,406 +9,13 @@ Get real time events from the server ### Options -| Name | Type | Default | Description | -|:---------------------------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [`-f`](#filter), [`--filter`](#filter) | `filter` | | Filter output based on conditions provided | -| [`--format`](#format) | `string` | | Format output using a custom template:
'json': Print in JSON format
'TEMPLATE': Print output using the given Go template.
Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | -| [`--since`](#since) | `string` | | Show all events created since timestamp | -| `--until` | `string` | | Stream events until this timestamp | +| Name | Type | Default | Description | +|:-----------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `-f`, `--filter` | `filter` | | Filter output based on conditions provided | +| `--format` | `string` | | Format output using a custom template:
'json': Print in JSON format
'TEMPLATE': Print output using the given Go template.
Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | +| `--since` | `string` | | Show all events created since timestamp | +| `--until` | `string` | | Stream events until this timestamp | -## Description - -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 (--since, --until) - -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 (--filter) - -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 is interpreted as a logical `OR`; for example, -`--filter container=588a23dac085 --filter container=a8f7720b8c22` displays -events for container `588a23dac085` or container `a8f7720b8c22`. - -Using multiple filters is interpreted as a logical `AND`; for example, -`--filter container=588a23dac085 --filter event=start` displays events for -container `588a23dac085` and where 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 the output (--format) - -If you specify a format (`--format`), the given template is executed -instead of the default format. Go's [text/template](https://pkg.go.dev/text/template) -package describes all the details of the format. - -If a format is set to `{{json .}}`, events are streamed in the JSON Lines format. -For information about JSON Lines, see . - -## Examples - -### Basic example - -You'll need two shells for this example. - -**Shell 1: Listening for events:** - -```console -$ docker events -``` - -**Shell 2: Start and Stop containers:** - -```console -$ 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 formats: - -```console -$ 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. - -```console -$ 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:22.04) -2014-05-10T17:42:14.999999999Z07:00 container stop 4386fb97867d (image=ubuntu:22.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 - -```console -$ 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 - -To list events in JSON format, use the `json` directive, which is the same -`--format '{{ json . }}`. - -```console -$ 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.. -``` diff --git a/docs/reference/commandline/exec.md b/docs/reference/commandline/exec.md index 1f1fafa747..67bf20a137 100644 --- a/docs/reference/commandline/exec.md +++ b/docs/reference/commandline/exec.md @@ -1,4 +1,4 @@ -# exec +# docker exec Execute a command in a running container @@ -9,128 +9,18 @@ Execute a command in a running container ### Options -| Name | Type | Default | Description | -|:------------------------------------------|:---------|:--------|:-------------------------------------------------------| -| `-d`, `--detach` | | | Detached mode: run command in the background | -| `--detach-keys` | `string` | | Override the key sequence for detaching a container | -| [`-e`](#env), [`--env`](#env) | `list` | | Set environment variables | -| `--env-file` | `list` | | Read in a file of environment variables | -| `-i`, `--interactive` | | | Keep STDIN open even if not attached | -| `--privileged` | | | Give extended privileges to the command | -| `-t`, `--tty` | | | Allocate a pseudo-TTY | -| `-u`, `--user` | `string` | | Username or UID (format: `[:]`) | -| [`-w`](#workdir), [`--workdir`](#workdir) | `string` | | Working directory inside the container | +| Name | Type | Default | Description | +|:----------------------|:---------|:--------|:-------------------------------------------------------| +| `-d`, `--detach` | | | Detached mode: run command in the background | +| `--detach-keys` | `string` | | Override the key sequence for detaching a container | +| `-e`, `--env` | `list` | | Set environment variables | +| `--env-file` | `list` | | Read in a file of environment variables | +| `-i`, `--interactive` | | | Keep STDIN open even if not attached | +| `--privileged` | | | Give extended privileges to the command | +| `-t`, `--tty` | | | Allocate a pseudo-TTY | +| `-u`, `--user` | `string` | | Username or UID (format: `[:]`) | +| `-w`, `--workdir` | `string` | | Working directory inside the container | -## Description - -The `docker exec` command runs a new command in a running container. - -The command you specify with `docker exec` only runs while the container's -primary process (`PID 1`) is running, and it isn't restarted if the container -is restarted. - -The command runs in the default working directory of the container. - -The command must be an executable. A chained or a quoted command doesn't work. - -- This works: `docker exec -it my_container sh -c "echo a && echo b"` -- This doesn't work: `docker exec -it my_container "echo a && echo b"` - -## Examples - -### Run `docker exec` on a running container - -First, start a container. - -```console -$ docker run --name mycontainer -d -i -t alpine /bin/sh -``` - -This creates and starts a container named `mycontainer` from an `alpine` image -with an `sh` shell as its main process. The `-d` option (shorthand for `--detach`) -sets the container to run in the background, in detached mode, with a pseudo-TTY -attached (`-t`). The `-i` option is set to keep `STDIN` attached (`-i`), which -prevents the `sh` process from exiting immediately. - -Next, execute a command on the container. - -```console -$ docker exec -d mycontainer touch /tmp/execWorks -``` - -This creates a new file `/tmp/execWorks` inside the running container -`mycontainer`, in the background. - -Next, execute an interactive `sh` shell on the container. - -```console -$ docker exec -it mycontainer sh -``` - -This starts a new shell session in the container `mycontainer`. - -### Set environment variables for the exec process (--env, -e) - -Next, set environment variables in the current bash session. - -The `docker exec` command inherits the environment variables that are set at the -time the container is created. Use the `--env` (or the `-e` shorthand) to -override global environment variables, or to set additional environment -variables for the process started by `docker exec`. - -The following example creates a new shell session in the container `mycontainer`, -with environment variables `$VAR_A` set to `1`, and `$VAR_B` set to `2`. -These environment variables are only valid for the `sh` process started by that -`docker exec` command, and aren't available to other processes running inside -the container. - -```console -$ docker exec -e VAR_A=1 -e VAR_B=2 mycontainer env -PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin -HOSTNAME=f64a4851eb71 -VAR_A=1 -VAR_B=2 -HOME=/root -``` - -### Set the working directory for the exec process (--workdir, -w) - -By default `docker exec` command runs in the same working directory set when -the container was created. - -```console -$ docker exec -it mycontainer pwd -/ -``` - -You can specify an alternative working directory for the command to execute -using the `--workdir` option (or the `-w` shorthand): - -```console -$ docker exec -it -w /root mycontainer pwd -/root -``` - -### Try to run `docker exec` on a paused container - -If the container is paused, then the `docker exec` command fails with an error: - -```console -$ docker pause mycontainer -mycontainer - -$ docker ps - -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -482efdf39fac alpine "/bin/sh" 17 seconds ago Up 16 seconds (Paused) mycontainer - -$ docker exec mycontainer sh - -Error response from daemon: Container mycontainer is paused, unpause the container before exec - -$ echo $? -1 -``` diff --git a/docs/reference/commandline/export.md b/docs/reference/commandline/export.md index 31fd70a774..558f2b87e9 100644 --- a/docs/reference/commandline/export.md +++ b/docs/reference/commandline/export.md @@ -1,4 +1,4 @@ -# export +# docker export Export a container's filesystem as a tar archive @@ -16,24 +16,3 @@ Export a container's filesystem as a tar archive -## Description - -The `docker export` command doesn't 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` exports the contents of the underlying -directory, not the contents of the volume. - -Refer to [Backup, restore, or migrate data volumes](https://docs.docker.com/storage/volumes/#back-up-restore-or-migrate-data-volumes) -in the user guide for examples on exporting data in a volume. - -## Examples - -The following commands produce the same result. - -```console -$ docker export red_panda > latest.tar -``` - -```console -$ docker export --output="latest.tar" red_panda -``` diff --git a/docs/reference/commandline/history.md b/docs/reference/commandline/history.md index a120d3e110..7ffc950335 100644 --- a/docs/reference/commandline/history.md +++ b/docs/reference/commandline/history.md @@ -1,4 +1,4 @@ -# history +# docker history Show the history of an image @@ -9,70 +9,13 @@ Show the history of an image ### Options -| Name | Type | Default | Description | -|:----------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [`--format`](#format) | `string` | | Format output using a custom template:
'table': Print output in table format with column headers (default)
'table TEMPLATE': Print output in table format using the given Go template
'json': Print in JSON format
'TEMPLATE': Print output using the given Go template.
Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | -| `-H`, `--human` | | | Print sizes and dates in human readable format | -| `--no-trunc` | | | Don't truncate output | -| `-q`, `--quiet` | | | Only show image IDs | +| Name | Type | Default | Description | +|:----------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--format` | `string` | | Format output using a custom template:
'table': Print output in table format with column headers (default)
'table TEMPLATE': Print output in table format using the given Go template
'json': Print in JSON format
'TEMPLATE': Print output using the given Go template.
Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | +| `-H`, `--human` | | | Print sizes and dates in human readable format | +| `--no-trunc` | | | Don't truncate output | +| `-q`, `--quiet` | | | Only show image IDs | -## Examples - -To see how the `docker:latest` image was built: - -```console -$ 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 Format the output (--format) - -The formatting option (`--format`) will pretty-prints history output -using a Go template. - -Valid placeholders for the Go template are listed below: - -| Placeholder | Description | -|-----------------|-----------------------------------------------------------------------------------------------------------| -| `.ID` | Image ID | -| `.CreatedSince` | Elapsed time since the image was created if `--human=true`, otherwise timestamp of when image was created | -| `.CreatedAt` | Timestamp of when image was created | -| `.CreatedBy` | Command that was used to create the image | -| `.Size` | Image disk size | -| `.Comment` | Comment for image | - -When using the `--format` option, the `history` command 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 -`ID` and `CreatedSince` entries separated by a colon (`:`) for the `busybox` -image: - -```console -$ docker history --format "{{.ID}}: {{.CreatedSince}}" busybox - -f6e427c148a7: 4 weeks ago -: 4 weeks ago -``` diff --git a/docs/reference/commandline/image_build.md b/docs/reference/commandline/image_build.md index e27c85964e..61f7f384a9 100644 --- a/docs/reference/commandline/image_build.md +++ b/docs/reference/commandline/image_build.md @@ -1,4 +1,4 @@ -# image build +# build Build an image from a Dockerfile @@ -9,42 +9,754 @@ Build an image from a Dockerfile ### Options -| Name | Type | Default | Description | -|:--------------------------|:--------------|:----------|:------------------------------------------------------------------| -| `--add-host` | `list` | | Add a custom host-to-IP mapping (`host:ip`) | -| `--build-arg` | `list` | | Set build-time variables | -| `--cache-from` | `stringSlice` | | Images to consider as cache sources | -| `--cgroup-parent` | `string` | | Set the parent cgroup for the `RUN` instructions during build | -| `--compress` | | | Compress the build context using gzip | -| `--cpu-period` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) period | -| `--cpu-quota` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) quota | -| `-c`, `--cpu-shares` | `int64` | `0` | CPU shares (relative weight) | -| `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) | -| `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) | -| `--disable-content-trust` | | | Skip image verification | -| `-f`, `--file` | `string` | | Name of the Dockerfile (Default is `PATH/Dockerfile`) | -| `--force-rm` | | | Always remove intermediate containers | -| `--iidfile` | `string` | | Write the image ID to the file | -| `--isolation` | `string` | | Container isolation technology | -| `--label` | `list` | | Set metadata for an image | -| `-m`, `--memory` | `bytes` | `0` | Memory limit | -| `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: -1 to enable unlimited swap | -| `--network` | `string` | `default` | Set the networking mode for the RUN instructions during build | -| `--no-cache` | | | Do not use cache when building the image | -| `--platform` | `string` | | Set platform if server is multi-platform capable | -| `--pull` | | | Always attempt to pull a newer version of the image | -| `-q`, `--quiet` | | | Suppress the build output and print image ID on success | -| `--rm` | | | Remove intermediate containers after a successful build | -| `--security-opt` | `stringSlice` | | Security options | -| `--shm-size` | `bytes` | `0` | Size of `/dev/shm` | -| `--squash` | | | Squash newly built layers into a single new layer | -| `-t`, `--tag` | `list` | | Name and optionally a tag in the `name:tag` format | -| `--target` | `string` | | Set the target build stage to build. | -| `--ulimit` | `ulimit` | | Ulimit options | +| Name | Type | Default | Description | +|:------------------------------------|:--------------|:----------|:------------------------------------------------------------------| +| [`--add-host`](#add-host) | `list` | | Add a custom host-to-IP mapping (`host:ip`) | +| [`--build-arg`](#build-arg) | `list` | | Set build-time variables | +| [`--cache-from`](#cache-from) | `stringSlice` | | Images to consider as cache sources | +| [`--cgroup-parent`](#cgroup-parent) | `string` | | Set the parent cgroup for the `RUN` instructions during build | +| `--compress` | | | Compress the build context using gzip | +| `--cpu-period` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) period | +| `--cpu-quota` | `int64` | `0` | Limit the CPU CFS (Completely Fair Scheduler) quota | +| `-c`, `--cpu-shares` | `int64` | `0` | CPU shares (relative weight) | +| `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) | +| `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) | +| `--disable-content-trust` | | | Skip image verification | +| [`-f`](#file), [`--file`](#file) | `string` | | Name of the Dockerfile (Default is `PATH/Dockerfile`) | +| `--force-rm` | | | Always remove intermediate containers | +| `--iidfile` | `string` | | Write the image ID to the file | +| [`--isolation`](#isolation) | `string` | | Container isolation technology | +| `--label` | `list` | | Set metadata for an image | +| `-m`, `--memory` | `bytes` | `0` | Memory limit | +| `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: -1 to enable unlimited swap | +| [`--network`](#network) | `string` | `default` | Set the networking mode for the RUN instructions during build | +| `--no-cache` | | | Do not use cache when building the image | +| `--platform` | `string` | | Set platform if server is multi-platform capable | +| `--pull` | | | Always attempt to pull a newer version of the image | +| `-q`, `--quiet` | | | Suppress the build output and print image ID on success | +| `--rm` | | | Remove intermediate containers after a successful build | +| [`--security-opt`](#security-opt) | `stringSlice` | | Security options | +| `--shm-size` | `bytes` | `0` | Size of `/dev/shm` | +| [`--squash`](#squash) | | | Squash newly built layers into a single new layer | +| [`-t`](#tag), [`--tag`](#tag) | `list` | | Name and optionally a tag in the `name:tag` format | +| [`--target`](#target) | `string` | | Set the target build stage to build. | +| [`--ulimit`](#ulimit) | `ulimit` | | Ulimit options | ## Description -See [docker build](build.md) for more information. +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*](https://docs.docker.com/engine/reference/builder/#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 isn't preserved. A +repository is first pulled into a temporary directory on your local host. After +that succeeds, the command sends the directory to the Docker daemon as the context. +Local copy gives you the ability to access private repositories using local +user credentials, VPNs, and so forth. + +> **Note** +> +> If the `URL` parameter contains a fragment the system recursively clones +> 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 checks out, +and can be either a branch, a tag, or a remote reference. The second part +represents a subdirectory inside the repository used as a build +context. + +For example, run this command to use a directory called `docker` in the branch +`container`: + +```console +$ 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` | + +### Tarball contexts + +If you pass a URL to a remote tarball, the command sends the URL itself to the +daemon: + +```console +$ docker build http://server/context.tar.gz +``` + +The host running the Docker daemon performs the download operation, +which isn't necessarily the same host that issued the build command. +The Docker daemon fetches `context.tar.gz` and uses 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`: + +```console +$ docker build - < Dockerfile +``` + +With PowerShell on Windows, you run: + +```powershell +Get-Content Dockerfile | docker build - +``` + +If you use `STDIN` or specify a `URL` pointing to a plain text file, the daemon +places the contents into a `Dockerfile`, and ignores any `-f`, `--file` +option. In this scenario, there is no context. + +By default the `docker build` command looks 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 that use the same +set of files for multiple builds. The path must be to a file within the +build context. Relative path are 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](https://docs.docker.com/engine/reference/builder/#dockerignore-file). + +If the Docker client loses connection to the daemon, it cancels the build. +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 client also cancels the pull. + +## Return code + +Successful builds return exit code `0`. When the build fails, the command +returns a non-zero exit code and prints an error message to `STDERR`: + +```console +$ docker build -t fail . + +Sending build context to Docker daemon 2.048 kB +Sending build context to Docker daemon +Step 1/3 : FROM busybox + ---> 4986bf8c1536 +Step 2/3 : RUN exit 13 + ---> Running in e26670ec7a0a +INFO[0000] The command [/bin/sh -c exit 13] returned a non-zero code: 13 +$ echo $? +1 +``` + +See also: + +[*Dockerfile Reference*](https://docs.docker.com/engine/reference/builder/). + +## Examples + +### Build with PATH + +```console +$ 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 `tar`s all the files in the +local directory and sends them 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` are sent, not just +the ones listed to [`ADD`](https://docs.docker.com/engine/reference/builder/#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 doesn't affect the build cache. + +### Build with URL + +```console +$ docker build github.com/creack/docker-firefox +``` + +This clones the GitHub repository, using the cloned repository as context, +and the Dockerfile at the root of the repository. You can +specify an arbitrary Git repository by using the `git://` or `git@` scheme. + +```console +$ 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` used +to build the image. Any `ADD` commands in that `Dockerfile` that refer to local +paths must be relative to the root of the contents inside `ctx.tar.gz`. In the +example above, the tarball contains a directory `ctx/`, so the `ADD +ctx/container.cfg /` operation works as expected. + +### Build with `-` + +```console +$ docker build - < Dockerfile +``` + +This example reads a Dockerfile from `STDIN` without context. Due to the lack of a +context, the command doesn't send contents of any local directory to the Docker daemon. +Since there is no context, a Dockerfile `ADD` only works if it refers to a +remote URL. + +```console +$ docker build - < context.tar.gz +``` + +This example builds an image for a compressed context read from `STDIN`. +Supported formats are: `bzip2`, `gzip` and `xz`. + +### Use a .dockerignore file + +```console +$ 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. You can see its effect in the changed size of the +uploaded context. The builder reference contains detailed information on +[creating a .dockerignore file](https://docs.docker.com/engine/reference/builder/#dockerignore-file). + +When using the [BuildKit backend](https://docs.docker.com/build/buildkit/), +`docker build` searches for a `.dockerignore` file relative to the Dockerfile +name. For example, running `docker build -f myapp.Dockerfile .` first looks +for an ignore file named `myapp.Dockerfile.dockerignore`. If it can't find such a file, +if present, it uses the `.dockerignore` file. 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, --tag) + +```console +$ docker build -t vieux/apache:2.0 . +``` + +This examples builds in the same way as the previous example, but it then tags the resulting +image. The repository name will be `vieux/apache` and the tag `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: + +```console +$ docker build -t whenry/fedora-jboss:latest -t whenry/fedora-jboss:v2.1 . +``` + +### Specify a Dockerfile (-f, --file) + +```console +$ docker build -f Dockerfile.debug . +``` + +This uses a file called `Dockerfile.debug` for the build instructions +instead of `Dockerfile`. + +```console +$ curl example.com/remote/Dockerfile | docker build -f - . +``` + +The above command uses the current directory as the build context and reads +a Dockerfile from stdin. + +```console +$ docker build -f dockerfiles/Dockerfile.debug -t myapp_debug . +$ docker build -f dockerfiles/Dockerfile.prod -t myapp_prod . +``` + +The above commands build the current build context (as specified by the +`.`) twice. Once using a debug version of a `Dockerfile` and once using a +production version. + +```console +$ 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 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 doesn't exist in the uploaded context. This may +> happen if there is no context, or if you specify a file that's +> 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` doesn't work. + +### Use a custom parent cgroup (--cgroup-parent) + +When you run `docker build` with the `--cgroup-parent` option, the daemon runs the containers +used in the build with the [corresponding `docker run` flag](../run.md#specify-custom-cgroups). + +### Set ulimits in container (--ulimit) + +Using the `--ulimit` option with `docker build` causes the daemon to start each build step's +container using those [`--ulimit` flag values](run.md#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. Often persistence isn't 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: + +```console +$ 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. 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 doesn't alter the output you see when the build process echoes the`ARG` lines from the +Dockerfile. + +For detailed information on using `ARG` and `ENV` instructions, see the +[Dockerfile reference](https://docs.docker.com/engine/reference/builder/). + +You can also use the `--build-arg` flag without a value, in which case the daemon +propagates the value from the local environment into the Docker container it's building: + +```console +$ export HTTP_PROXY=http://10.20.30.2:1234 +$ docker build --build-arg HTTP_PROXY . +``` + +This example is similar to how `docker run -e` works. Refer to the [`docker run` documentation](run.md#env) +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 build container's `/etc/hosts` file by using one +or more `--add-host` flags. This example adds static addresses for hosts named +`my-hostname` and `my_hostname_v6`: + +```console +$ docker build --add-host my_hostname=8.8.8.8 --add-host my_hostname_v6=2001:4860:4860::8888 . +``` + +If you need your build to connect to services running on the host, you can use +the special `host-gateway` value for `--add-host`. In the following example, +build containers resolve `host.docker.internal` to the host's gateway IP. + +```console +$ docker build --add-host host.docker.internal=host-gateway . +``` + +You can wrap an IPv6 address in square brackets. +`=` and `:` are both valid separators. +Both formats in the following example are valid: + +```console +$ docker build --add-host my-hostname:10.180.0.1 --add-host my-hostname_v6=[2001:4860:4860::8888] . +``` + +### Specifying target build stage (--target) + +When building a Dockerfile with multiple build stages, you can use the `--target` +option to specify an intermediate build stage by name as a final stage for the +resulting image. The daemon skips commands after the target stage. + +```dockerfile +FROM debian AS build-env +# ... + +FROM alpine AS production-env +# ... +``` + +```console +$ docker build -t mybuildimage --target build-env . +``` + +### Custom build outputs (--output) + +> **Note** +> +> This feature requires the BuildKit backend. You can either +> [enable BuildKit](https://docs.docker.com/build/buildkit/#getting-started) or +> use the [buildx](https://github.com/docker/buildx) plugin which provides more +> output type options. + +By default, a local container image is created from the build result. The +`--output` (or `-o`) flag allows you to override this behavior, and specify a +custom exporter. 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 that supports `local` and `tar` exporters. + +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 you specify no type, 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 a 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: + +```console +$ 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): + +```console +$ docker build --output type=local,dest=out . +``` + +Use the `tar` type to export the files as a `.tar` archive: + +```console +$ 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: + +```console +$ 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`](https://docs.docker.com/engine/reference/builder/#copy). + +The example, the `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, the command only exports the files from the final +stage to the `out` directory, in this case, the `vndr` binary: + +```console +$ 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 +``` + +### Specifying external cache sources (--cache-from) + +> **Note** +> +> This feature requires the BuildKit backend. You can either +> [enable BuildKit](https://docs.docker.com/build/buildkit/#getting-started) or +> use the [buildx](https://github.com/docker/buildx) plugin. The previous +> builder has limited support for reusing cache from pre-pulled images. + +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. You can do this by setting `--build-arg BUILDKIT_INLINE_CACHE=1` +when building the image. After that, you can use the built image as a cache source +for subsequent builds. + +Upon importing the cache, the builder only pulls the JSON metadata from the +registry and determine possible cache hits based on that information. If there +is a cache hit, the builder pulls the matched layers 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: + +```console +$ 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. + +On another machine: + +```console +$ docker build --cache-from myname/myapp . +``` + +### Set the networking mode for the RUN instructions during build (--network) + +#### Overview + +Available options for the networking mode are: + +- `default` (default): Run in the default network. +- `none`: Run with no network access. +- `host`: Run in the host’s network environment. + +Find more details in the [Dockerfile documentation](https://docs.docker.com/engine/reference/builder/#run---network). + +### Squash an image's layers (--squash) (experimental) + +#### Overview + +> **Note** +> The `--squash` option is an experimental feature, and should not be considered +> stable. + +Once the image is built, this flag squashes the new layers into a new image with +a single new layer. Squashing doesn't 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 `--squash` flag preserves the build cache. + +Squashing layers can be beneficial if your Dockerfile produces multiple layers +modifying the same files. For example, files 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, the daemon can pull layers 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 [Multi-stage builds](https://docs.docker.com/build/building/multi-stage/) +section for more information. + +#### Known limitations + +The `--squash` option has a number of known limitations: + +- When squashing layers, the resulting image can't 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 intact, 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 + you can't parallelize downloading a single layer. +- When attempting to squash an image that doesn't 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 23.03. + +You can enable experimental mode 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: 23.0.3 + API version: 1.42 + Go version: go1.19.7 + Git commit: 3e7cbfd + Built: Tue Apr 4 22:05:41 2023 + OS/Arch: darwin/amd64 + Context: default + +Server: Docker Engine - Community + Engine: + Version: 23.0.3 + API version: 1.42 (minimum version 1.12) + Go version: go1.19.7 + Git commit: 59118bf + Built: Tue Apr 4 22:05:41 2023 + OS/Arch: linux/amd64 + Experimental: true + [...] +``` + +#### Build an image with the `--squash` flag + +The following is an example of a build with the `--squash` flag. Below is the +`Dockerfile`: + +```dockerfile +FROM busybox +RUN echo hello > /hello +RUN echo world >> /hello +RUN touch remove_me /remove_me +ENV HELLO=world +RUN rm /remove_me +``` + +Next, build an image named `test` using the `--squash` flag. + +```console +$ docker build --squash -t test . +``` + +After the build completes, the history looks like the below. The history could show that a layer's +name is ``, and there is a new layer with COMMENT `merge`. + +```console +$ 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 +``` + +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`. diff --git a/docs/reference/commandline/image_history.md b/docs/reference/commandline/image_history.md index 97f437cfb0..a120d3e110 100644 --- a/docs/reference/commandline/image_history.md +++ b/docs/reference/commandline/image_history.md @@ -1,4 +1,4 @@ -# image history +# history Show the history of an image @@ -9,16 +9,70 @@ Show the history of an image ### Options -| Name | Type | Default | Description | -|:----------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `--format` | `string` | | Format output using a custom template:
'table': Print output in table format with column headers (default)
'table TEMPLATE': Print output in table format using the given Go template
'json': Print in JSON format
'TEMPLATE': Print output using the given Go template.
Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | -| `-H`, `--human` | | | Print sizes and dates in human readable format | -| `--no-trunc` | | | Don't truncate output | -| `-q`, `--quiet` | | | Only show image IDs | +| Name | Type | Default | Description | +|:----------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [`--format`](#format) | `string` | | Format output using a custom template:
'table': Print output in table format with column headers (default)
'table TEMPLATE': Print output in table format using the given Go template
'json': Print in JSON format
'TEMPLATE': Print output using the given Go template.
Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | +| `-H`, `--human` | | | Print sizes and dates in human readable format | +| `--no-trunc` | | | Don't truncate output | +| `-q`, `--quiet` | | | Only show image IDs | -## Description +## Examples -See [docker history](history.md) for more information. +To see how the `docker:latest` image was built: + +```console +$ 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 Format the output (--format) + +The formatting option (`--format`) will pretty-prints history output +using a Go template. + +Valid placeholders for the Go template are listed below: + +| Placeholder | Description | +|-----------------|-----------------------------------------------------------------------------------------------------------| +| `.ID` | Image ID | +| `.CreatedSince` | Elapsed time since the image was created if `--human=true`, otherwise timestamp of when image was created | +| `.CreatedAt` | Timestamp of when image was created | +| `.CreatedBy` | Command that was used to create the image | +| `.Size` | Image disk size | +| `.Comment` | Comment for image | + +When using the `--format` option, the `history` command 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 +`ID` and `CreatedSince` entries separated by a colon (`:`) for the `busybox` +image: + +```console +$ docker history --format "{{.ID}}: {{.CreatedSince}}" busybox + +f6e427c148a7: 4 weeks ago +: 4 weeks ago +``` diff --git a/docs/reference/commandline/image_import.md b/docs/reference/commandline/image_import.md index 0399a919c5..5e38332821 100644 --- a/docs/reference/commandline/image_import.md +++ b/docs/reference/commandline/image_import.md @@ -1,4 +1,4 @@ -# image import +# import Import the contents from a tarball to create a filesystem image @@ -20,4 +20,72 @@ Import the contents from a tarball to create a filesystem image ## Description -See [docker import](import.md) for more information. +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 applies `Dockerfile` instructions to the image that is +created. Supported `Dockerfile` instructions: +`CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` + +## Examples + +### Import from a remote location + +This creates a new untagged image. + +```console +$ docker import https://example.com/exampleimage.tgz +``` + +### Import from a local file + +Import to docker via pipe and `STDIN`. + +```console +$ cat exampleimage.tgz | docker import - exampleimagelocal:new +``` + +Import with a commit message. + +```console +$ cat exampleimage.tgz | docker import --message "New image imported from tarball" - exampleimagelocal:new +``` + +Import to docker from a local archive. + +```console +$ docker import /path/to/exampleimage.tgz +``` + +### Import from a local directory + +```console +$ sudo tar -c . | docker import - exampleimagedir +``` + +### Import from a local directory with new configurations + +```console +$ 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. + +## When the daemon supports multiple operating systems + +If the daemon supports multiple operating systems, and the image being imported +does not match the default operating system, it may be necessary to add +`--platform`. This would be necessary when importing a Linux image into a Windows +daemon. + +```console +$ docker import --platform=linux .\linuximage.tar +``` diff --git a/docs/reference/commandline/image_load.md b/docs/reference/commandline/image_load.md index b78855c361..098af0a243 100644 --- a/docs/reference/commandline/image_load.md +++ b/docs/reference/commandline/image_load.md @@ -1,4 +1,4 @@ -# image load +# load Load an image from a tar archive or STDIN @@ -9,14 +9,52 @@ Load an image from a tar archive or STDIN ### Options -| Name | Type | Default | Description | -|:----------------|:---------|:--------|:---------------------------------------------| -| `-i`, `--input` | `string` | | Read from tar archive file, instead of STDIN | -| `-q`, `--quiet` | | | Suppress the load output | +| Name | Type | Default | Description | +|:------------------------------------|:---------|:--------|:---------------------------------------------| +| [`-i`](#input), [`--input`](#input) | `string` | | Read from tar archive file, instead of STDIN | +| `-q`, `--quiet` | | | Suppress the load output | ## Description -See [docker load](load.md) for more information. +Load an image or repository from a tar archive (even if compressed with gzip, +bzip2, xz or zstd) from a file or STDIN. It restores both images and tags. + +## Examples + +```console +$ docker image ls + +REPOSITORY TAG IMAGE ID CREATED SIZE +``` + +### Load images from STDIN + +```console +$ 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 +``` + +### Load images from a file (--input) + +```console +$ 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 +``` diff --git a/docs/reference/commandline/image_ls.md b/docs/reference/commandline/image_ls.md index 7cabd920f0..1467c37c6e 100644 --- a/docs/reference/commandline/image_ls.md +++ b/docs/reference/commandline/image_ls.md @@ -1,4 +1,4 @@ -# image ls +# images List images @@ -9,18 +9,338 @@ List images ### Options -| Name | Type | Default | Description | -|:-----------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `-a`, `--all` | | | Show all images (default hides intermediate images) | -| `--digests` | | | Show digests | -| `-f`, `--filter` | `filter` | | Filter output based on conditions provided | -| `--format` | `string` | | Format output using a custom template:
'table': Print output in table format with column headers (default)
'table TEMPLATE': Print output in table format using the given Go template
'json': Print in JSON format
'TEMPLATE': Print output using the given Go template.
Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | -| `--no-trunc` | | | Don't truncate output | -| `-q`, `--quiet` | | | Only show image IDs | +| Name | Type | Default | Description | +|:---------------------------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `-a`, `--all` | | | Show all images (default hides intermediate images) | +| [`--digests`](#digests) | | | Show digests | +| [`-f`](#filter), [`--filter`](#filter) | `filter` | | Filter output based on conditions provided | +| [`--format`](#format) | `string` | | Format output using a custom template:
'table': Print output in table format with column headers (default)
'table TEMPLATE': Print output in table format using the given Go template
'json': Print in JSON format
'TEMPLATE': Print output using the given Go template.
Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | +| [`--no-trunc`](#no-trunc) | | | Don't truncate output | +| `-q`, `--quiet` | | | Only show image IDs | ## Description -See [docker images](images.md) for more information. +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. + +## Examples + +### List the most recently created images + +```console +$ 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 the following command: + +```console +$ 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: + +```console +$ 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. + +```console +$ docker images java:0 + +REPOSITORY TAG IMAGE ID CREATED SIZE +``` + +### List the full length image IDs (--no-trunc) + +```console +$ 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 (--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: + +```console +$ 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 (--filter) + +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) + +```console +$ 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`: + +```console +$ 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. + +```console +$ 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. + +```console +$ 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. + +```console +$ 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 +a given ID or reference. For example, having these images: + +```console +$ 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: + +```console +$ 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: + +```console +$ 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. + +```console +$ 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: + +```console +$ 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: + +```console +$ 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 (--format) + +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: + +```console +$ 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: + +```console +$ 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 +``` + +To list all images in JSON format, use the `json` directive: + +```console +$ docker images --format json +{"Containers":"N/A","CreatedAt":"2021-03-04 03:24:42 +0100 CET","CreatedSince":"5 days ago","Digest":"\u003cnone\u003e","ID":"4dd97cefde62","Repository":"ubuntu","SharedSize":"N/A","Size":"72.9MB","Tag":"latest","UniqueSize":"N/A","VirtualSize":"72.9MB"} +{"Containers":"N/A","CreatedAt":"2021-02-17 22:19:54 +0100 CET","CreatedSince":"2 weeks ago","Digest":"\u003cnone\u003e","ID":"28f6e2705743","Repository":"alpine","SharedSize":"N/A","Size":"5.61MB","Tag":"latest","UniqueSize":"N/A","VirtualSize":"5.613MB"} +``` diff --git a/docs/reference/commandline/image_pull.md b/docs/reference/commandline/image_pull.md index d9f298eecb..ada165558c 100644 --- a/docs/reference/commandline/image_pull.md +++ b/docs/reference/commandline/image_pull.md @@ -1,4 +1,4 @@ -# image pull +# pull Download an image from a registry @@ -9,16 +9,236 @@ Download an image from a registry ### Options -| Name | Type | Default | Description | -|:--------------------------|:---------|:--------|:-------------------------------------------------| -| `-a`, `--all-tags` | | | Download all tagged images in the repository | -| `--disable-content-trust` | | | Skip image verification | -| `--platform` | `string` | | Set platform if server is multi-platform capable | -| `-q`, `--quiet` | | | Suppress verbose output | +| Name | Type | Default | Description | +|:---------------------------------------------|:---------|:--------|:-------------------------------------------------| +| [`-a`](#all-tags), [`--all-tags`](#all-tags) | | | Download all tagged images in the repository | +| `--disable-content-trust` | | | Skip image verification | +| `--platform` | `string` | | Set platform if server is multi-platform capable | +| `-q`, `--quiet` | | | Suppress verbose output | ## Description -See [docker pull](pull.md) for more information. +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, refer to the [dockerd command-line reference](dockerd.md#proxy-configuration) +for details. + +### 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. + +## Examples + +### Pull an image from Docker Hub + +To download a particular image, or set of images (i.e., a repository), use +`docker image pull` (or the `docker pull` shorthand). If no tag is provided, +Docker Engine uses the `:latest` tag as a default. This example pulls the +`debian:latest` image: + +```console +$ docker image pull debian + +Using default tag: latest +latest: Pulling from library/debian +e756f3fdd6a3: Pull complete +Digest: sha256:3f1d6c17773a45c97bd8f158d665c9709d7b29ed7917ac934086ad96f92e4510 +Status: Downloaded newer image for debian:latest +docker.io/library/debian:latest +``` + +Docker images can consist of multiple layers. In the example above, the image +consists of a single layer; `e756f3fdd6a3`. + +Layers can be reused by images. For example, the `debian:bookworm` image shares +its layer with the `debian:latest`. Pulling the `debian:bookworm` image therefore +only pulls its metadata, but not its layers, because the layer is already present +locally: + +```console +$ docker image pull debian:bookworm + +bookworm: Pulling from library/debian +Digest: sha256:3f1d6c17773a45c97bd8f158d665c9709d7b29ed7917ac934086ad96f92e4510 +Status: Downloaded newer image for debian:bookworm +docker.io/library/debian:bookworm +``` + +To see which images are present locally, use the [`docker images`](images.md) +command: + +```console +$ docker images + +REPOSITORY TAG IMAGE ID CREATED SIZE +debian bookworm 4eacea30377a 8 days ago 124MB +debian latest 4eacea30377a 8 days ago 124MB +``` + +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:bookworm` and `debian:latest` have the same image ID because they are +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:22.04` pulls the latest version of the Ubuntu +22.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:22.04` image from Docker Hub: + +```console +$ docker pull ubuntu:22.04 + +22.04: Pulling from library/ubuntu +125a6e411906: Pull complete +Digest: sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d +Status: Downloaded newer image for ubuntu:22.04 +docker.io/library/ubuntu:22.04 +``` + +Docker prints the digest of the image after the pull has finished. In the example +above, the digest of the image is: + +```console +sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d +``` + +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: + +```console +$ docker pull ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d + +docker.io/library/ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d: Pulling from library/ubuntu +Digest: sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d +Status: Image is up to date for ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d +docker.io/library/ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d +``` + +Digest can also be used in the `FROM` of a Dockerfile, for example: + +```dockerfile +FROM ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d +LABEL org.opencontainers.image.authors="some maintainer " +``` + +> **Note** +> +> Using this feature "pins" an image to a specific version in time. +> Docker does 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`): + +```console +$ docker image 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 (-a, --all-tags) + +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 `ubuntu` repository: + +```console +$ docker image pull --all-tags ubuntu + +Pulling repository ubuntu +ad57ef8d78d7: Download complete +105182bb5e8b: Download complete +511136ea3c5a: Download complete +73bd853d2ea5: Download complete +.... + +Status: Downloaded newer image for ubuntu +``` + +After the pull has completed use the `docker image ls` command (or the `docker images` +shorthand) to see the images that were pulled. The example below shows all the +`ubuntu` images that are present locally: + +```console +$ docker image ls --filter reference=ubuntu +REPOSITORY TAG IMAGE ID CREATED SIZE +ubuntu 18.04 c6ad7e71ba7d 5 weeks ago 63.2MB +ubuntu bionic c6ad7e71ba7d 5 weeks ago 63.2MB +ubuntu 22.04 5ccefbfc0416 2 months ago 78MB +ubuntu focal ff0fea8310f3 2 months ago 72.8MB +ubuntu latest ff0fea8310f3 2 months ago 72.8MB +ubuntu jammy 41ba606c8ab9 3 months ago 79MB +ubuntu 20.04 ba6acccedd29 7 months ago 72.8MB +``` + +### 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. + +```console +$ docker pull ubuntu + +Using default tag: latest +latest: Pulling from library/ubuntu +a3ed95caeb02: Pulling fs layer +236608c7b546: Pulling fs layer +^C +``` + +The Engine terminates a pull operation when the connection between the daemon +and the client (initiating the pull) is cut or lost for any reason or the +command is manually terminated. diff --git a/docs/reference/commandline/image_push.md b/docs/reference/commandline/image_push.md index 964b61aec1..a2c83dbe10 100644 --- a/docs/reference/commandline/image_push.md +++ b/docs/reference/commandline/image_push.md @@ -1,4 +1,4 @@ -# image push +# push Upload an image to a registry @@ -9,15 +9,114 @@ Upload an image to a registry ### Options -| Name | Type | Default | Description | -|:--------------------------|:-----|:--------|:--------------------------------------------| -| `-a`, `--all-tags` | | | Push all tags of an image to the repository | -| `--disable-content-trust` | | | Skip image signing | -| `-q`, `--quiet` | | | Suppress verbose output | +| Name | Type | Default | Description | +|:---------------------------------------------|:-----|:--------|:--------------------------------------------| +| [`-a`](#all-tags), [`--all-tags`](#all-tags) | | | Push all tags of an image to the repository | +| `--disable-content-trust` | | | Skip image signing | +| `-q`, `--quiet` | | | Suppress verbose output | ## Description -See [docker push](push.md) for more information. +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. + +## 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: + +```console +$ 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: + +```console +$ 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: + +```console +$ docker image ls +``` + +You should see both `rhel-httpd` and `registry-host:5000/myadmin/rhel-httpd` +listed. + +### Push all tags of an image (-a, --all-tags) + +Use the `-a` (or `--all-tags`) option 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. + + +```console +$ 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: + +```console +$ 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: + + +```console +$ 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 +``` + diff --git a/docs/reference/commandline/image_rm.md b/docs/reference/commandline/image_rm.md index 4bd4e3f9e2..5fd35e9931 100644 --- a/docs/reference/commandline/image_rm.md +++ b/docs/reference/commandline/image_rm.md @@ -1,4 +1,4 @@ -# image rm +# rmi Remove one or more images @@ -19,4 +19,89 @@ Remove one or more images ## Description -See [docker rmi](rmi.md) for more information. +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. + +## 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. + +```console +$ 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. + +```console +$ 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: + +```console +$ 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: + +```console +$ docker rmi localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf +Untagged: localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf +Deleted: 4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125 +Deleted: ea13149945cb6b1e746bf28032f02e9b5a793523481a0a18645fc77ad53c4ea2 +Deleted: df7546f9f060a2268024c8a230d8639878585defcc1bc6f79d2728a13957871b +``` diff --git a/docs/reference/commandline/image_save.md b/docs/reference/commandline/image_save.md index 77aa3cdf8f..d6df5574c1 100644 --- a/docs/reference/commandline/image_save.md +++ b/docs/reference/commandline/image_save.md @@ -1,4 +1,4 @@ -# image save +# save Save one or more images to a tar archive (streamed to STDOUT by default) @@ -18,4 +18,44 @@ Save one or more images to a tar archive (streamed to STDOUT by default) ## Description -See [docker save](save.md) for more information. +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. + +## Examples + +### Create a backup that can then be used with `docker load`. + +```console +$ 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. + +```console +$ docker save myimage:latest | gzip > myimage_latest.tar.gz +``` + +### Cherry-pick particular tags + +You can even cherry-pick particular tags of an image repository. + +```console +$ docker save -o ubuntu.tar ubuntu:lucid ubuntu:saucy +``` diff --git a/docs/reference/commandline/image_tag.md b/docs/reference/commandline/image_tag.md index 55dcdf7209..d9359f62ef 100644 --- a/docs/reference/commandline/image_tag.md +++ b/docs/reference/commandline/image_tag.md @@ -1,4 +1,4 @@ -# image tag +# tag Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE @@ -12,4 +12,76 @@ Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE ## Description -See [docker tag](tag.md) for more information. +A full image name has the following format and components: + +`[HOST[:PORT_NUMBER]/]PATH` + +- `HOST`: The optional registry hostname specifies where the image is located. + The hostname must comply with standard DNS rules, but may not contain + underscores. If you don't specify a hostname, the command uses Docker's public + registry at `registry-1.docker.io` by default. Note that `docker.io` is the + canonical reference for Docker's public registry. +- `PORT_NUMBER`: If a hostname is present, it may optionally be followed by a + registry port number in the format `:8080`. +- `PATH`: The path consists of slash-separated components. Each + component may contain lowercase letters, digits and separators. A separator is + defined as a period, one or two underscores, or one or more hyphens. A component + may not start or end with a separator. While the + [OCI Distribution Specification](https://github.com/opencontainers/distribution-spec) + supports more than two slash-separated components, most registries only support + two slash-separated components. For Docker's public registry, the path format is + as follows: + - `[NAMESPACE/]REPOSITORY`: The first, optional component is typically a + user's or an organization's namespace. The second, mandatory component is the + repository name. When the namespace is not present, Docker uses `library` + as the default namespace. + +After the image name, the optional `TAG` is a custom, human-readable manifest +identifier that's typically a specific version or variant of an image. The tag +must be valid ASCII and can contain lowercase and uppercase letters, digits, +underscores, periods, and hyphens. It can't start with a period or hyphen and +must be no longer than 128 characters. If you don't specify a tag, the command uses `latest` by default. + +You can group your images together using names and tags, and then +[push](https://docs.docker.com/engine/reference/commandline/push) them to a +registry. + +## Examples + +### Tag an image referenced by ID + +To tag a local image with ID `0e5574283393` as `fedora/httpd` with the tag +`version1.0`: + +```console +$ docker tag 0e5574283393 fedora/httpd:version1.0 +``` + +### Tag an image referenced by Name + +To tag a local image `httpd` as `fedora/httpd` with the tag `version1.0`: + +```console +$ docker tag httpd fedora/httpd:version1.0 +``` + +Note that since the tag name isn't 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 the name `httpd` and the tag `test` as `fedora/httpd` +with the tag `version1.0.test`: + +```console +$ docker tag httpd:test fedora/httpd:version1.0.test +``` + +### Tag an image for a private registry + +To push an image to a private registry and not the public Docker registry you +must include the registry hostname and port (if needed). + +```console +$ docker tag 0e5574283393 myregistryhost:5000/fedora/httpd:version1.0 +``` diff --git a/docs/reference/commandline/images.md b/docs/reference/commandline/images.md index 1467c37c6e..1fa9f6a319 100644 --- a/docs/reference/commandline/images.md +++ b/docs/reference/commandline/images.md @@ -1,4 +1,4 @@ -# images +# docker images List images @@ -9,338 +9,15 @@ List images ### Options -| Name | Type | Default | Description | -|:---------------------------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `-a`, `--all` | | | Show all images (default hides intermediate images) | -| [`--digests`](#digests) | | | Show digests | -| [`-f`](#filter), [`--filter`](#filter) | `filter` | | Filter output based on conditions provided | -| [`--format`](#format) | `string` | | Format output using a custom template:
'table': Print output in table format with column headers (default)
'table TEMPLATE': Print output in table format using the given Go template
'json': Print in JSON format
'TEMPLATE': Print output using the given Go template.
Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | -| [`--no-trunc`](#no-trunc) | | | Don't truncate output | -| `-q`, `--quiet` | | | Only show image IDs | +| Name | Type | Default | Description | +|:-----------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `-a`, `--all` | | | Show all images (default hides intermediate images) | +| `--digests` | | | Show digests | +| `-f`, `--filter` | `filter` | | Filter output based on conditions provided | +| `--format` | `string` | | Format output using a custom template:
'table': Print output in table format with column headers (default)
'table TEMPLATE': Print output in table format using the given Go template
'json': Print in JSON format
'TEMPLATE': Print output using the given Go template.
Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | +| `--no-trunc` | | | Don't truncate output | +| `-q`, `--quiet` | | | Only show image IDs | -## Description - -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. - -## Examples - -### List the most recently created images - -```console -$ 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 the following command: - -```console -$ 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: - -```console -$ 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. - -```console -$ docker images java:0 - -REPOSITORY TAG IMAGE ID CREATED SIZE -``` - -### List the full length image IDs (--no-trunc) - -```console -$ 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 (--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: - -```console -$ 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 (--filter) - -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) - -```console -$ 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`: - -```console -$ 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. - -```console -$ 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. - -```console -$ 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. - -```console -$ 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 -a given ID or reference. For example, having these images: - -```console -$ 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: - -```console -$ 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: - -```console -$ 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. - -```console -$ 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: - -```console -$ 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: - -```console -$ 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 (--format) - -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: - -```console -$ 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: - -```console -$ 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 -``` - -To list all images in JSON format, use the `json` directive: - -```console -$ docker images --format json -{"Containers":"N/A","CreatedAt":"2021-03-04 03:24:42 +0100 CET","CreatedSince":"5 days ago","Digest":"\u003cnone\u003e","ID":"4dd97cefde62","Repository":"ubuntu","SharedSize":"N/A","Size":"72.9MB","Tag":"latest","UniqueSize":"N/A","VirtualSize":"72.9MB"} -{"Containers":"N/A","CreatedAt":"2021-02-17 22:19:54 +0100 CET","CreatedSince":"2 weeks ago","Digest":"\u003cnone\u003e","ID":"28f6e2705743","Repository":"alpine","SharedSize":"N/A","Size":"5.61MB","Tag":"latest","UniqueSize":"N/A","VirtualSize":"5.613MB"} -``` diff --git a/docs/reference/commandline/import.md b/docs/reference/commandline/import.md index 5e38332821..1b3eec0224 100644 --- a/docs/reference/commandline/import.md +++ b/docs/reference/commandline/import.md @@ -1,4 +1,4 @@ -# import +# docker import Import the contents from a tarball to create a filesystem image @@ -18,74 +18,3 @@ Import the contents from a tarball to create a filesystem image -## Description - -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 applies `Dockerfile` instructions to the image that is -created. Supported `Dockerfile` instructions: -`CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` - -## Examples - -### Import from a remote location - -This creates a new untagged image. - -```console -$ docker import https://example.com/exampleimage.tgz -``` - -### Import from a local file - -Import to docker via pipe and `STDIN`. - -```console -$ cat exampleimage.tgz | docker import - exampleimagelocal:new -``` - -Import with a commit message. - -```console -$ cat exampleimage.tgz | docker import --message "New image imported from tarball" - exampleimagelocal:new -``` - -Import to docker from a local archive. - -```console -$ docker import /path/to/exampleimage.tgz -``` - -### Import from a local directory - -```console -$ sudo tar -c . | docker import - exampleimagedir -``` - -### Import from a local directory with new configurations - -```console -$ 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. - -## When the daemon supports multiple operating systems - -If the daemon supports multiple operating systems, and the image being imported -does not match the default operating system, it may be necessary to add -`--platform`. This would be necessary when importing a Linux image into a Windows -daemon. - -```console -$ docker import --platform=linux .\linuximage.tar -``` diff --git a/docs/reference/commandline/index.md b/docs/reference/commandline/index.md index 2dd4e7e4d0..2be6c2e160 100644 --- a/docs/reference/commandline/index.md +++ b/docs/reference/commandline/index.md @@ -20,72 +20,71 @@ read the [`dockerd`](dockerd.md) reference page. ### Docker management commands -| Command | Description | -|:----------------------|:-----------------------------------------------------| -| [dockerd](dockerd.md) | Launch the Docker daemon | -| [info](info.md) | Display system-wide information | -| [inspect](inspect.md) | Return low-level information on a container or image | -| [version](version.md) | Show the Docker version information | - +| Command | Description | +| :-------------------------------- | :--------------------------------------------------- | +| [dockerd](dockerd.md) | Launch the Docker daemon | +| [inspect](inspect.md) | Return low-level information on a container or image | +| [system events](system_events.md) | Get real-time events from the server | +| [system info](system_info.md) | Display system-wide information | +| [version](version.md) | Show the Docker version information | ### Image commands -| Command | Description | -|:------------------------------|:----------------------------------------------------------------| -| [build](build.md) | Build an image from a Dockerfile | -| [commit](commit.md) | Create a new image from a container's changes | -| [history](history.md) | Show the history of an image | -| [images](images.md) | List images | -| [import](import.md) | Import the contents from a tarball to create a filesystem image | -| [load](load.md) | Load an image from a tar archive or STDIN | -| [image prune](image_prune.md) | Remove unused images | -| [rmi](rmi.md) | Remove one or more images | -| [save](save.md) | Save images to a tar archive | -| [tag](tag.md) | Tag an image into a repository | +| Command | Description | +| :-------------------------------- | :-------------------------------------------------------------- | +| [image build](image_build.md) | Build an image from a Dockerfile | +| [image commit](image_commit.md) | Create a new image from a container's changes | +| [image history](image_history.md) | Show the history of an image | +| [image import](image_import.md) | Import the contents from a tarball to create a filesystem image | +| [image load](image_load.md) | Load an image from a tar archive or STDIN | +| [image ls](image_ls.md) | List images | +| [image prune](image_prune.md) | Remove unused images | +| [image rm](image_rm.md) | Remove one or more images | +| [image save](image_save.md) | Save images to a tar archive | +| [image tag](image_tag.md) | Tag an image into a repository | ### Container commands -| Command | Description | -|:--------------------------------------|:-----------------------------------------------------------------| -| [attach](attach.md) | Attach to a running container | -| [container prune](container_prune.md) | Remove all stopped containers | -| [cp](cp.md) | Copy files/folders from a container to a HOSTDIR or to STDOUT | -| [create](create.md) | Create a new container | -| [diff](diff.md) | Inspect changes on a container's filesystem | -| [events](events.md) | Get real time events from the server | -| [exec](exec.md) | Execute a command in a running container | -| [export](export.md) | Export a container's filesystem as a tar archive | -| [kill](kill.md) | Kill a running container | -| [logs](logs.md) | Fetch the logs of a container | -| [pause](pause.md) | Pause all processes within a container | -| [port](port.md) | List port mappings or a specific mapping for the container | -| [ps](ps.md) | List containers | -| [rename](rename.md) | Rename a container | -| [restart](restart.md) | Restart a running container | -| [rm](rm.md) | Remove one or more containers | -| [run](run.md) | Create and run a new container from an image | -| [start](start.md) | Start one or more stopped containers | -| [stats](stats.md) | Display a live stream of container(s) resource usage statistics | -| [stop](stop.md) | Stop a running container | -| [top](top.md) | Display the running processes of a container | -| [unpause](unpause.md) | Unpause all processes within a container | -| [update](update.md) | Update configuration of one or more containers | -| [wait](wait.md) | Block until a container stops, then print its exit code | +| Command | Description | +| :---------------------------------------- | :-------------------------------------------------------------- | +| [container attach](container_attach.md) | Attach to a running container | +| [container cp](container_cp.md) | Copy files/folders from a container to a HOSTDIR or to STDOUT | +| [container create](container_create.md) | Create a new container | +| [container diff](container_diff.md) | Inspect changes on a container's filesystem | +| [container exec](container_exec.md) | Execute a command in a running container | +| [container export](container_export.md) | Export a container's filesystem as a tar archive | +| [container kill](container_kill.md) | Kill a running container | +| [container logs](container_logs.md) | Fetch the logs of a container | +| [container ls](container_ls.md) | List containers | +| [container pause](container_pause.md) | Pause all processes within a container | +| [container port](container_port.md) | List port mappings or a specific mapping for the container | +| [container prune](container_prune.md) | Remove all stopped containers | +| [container rename](container_rename.md) | Rename a container | +| [container restart](container_restart.md) | Restart a running container | +| [container rm](container_rm.md) | Remove one or more containers | +| [container run](container_run.md) | Create and run a new container from an image | +| [container start](container_start.md) | Start one or more stopped containers | +| [container stats](container_stats.md) | Display a live stream of container(s) resource usage statistics | +| [container stop](container_stop.md) | Stop a running container | +| [container top](container_top.md) | Display the running processes of a container | +| [container unpause](container_unpause.md) | Unpause all processes within a container | +| [container update](container_update.md) | Update configuration of one or more containers | +| [container wait](container_wait.md) | Block until a container stops, then print its exit code | ### Hub and registry commands -| Command | Description | -|:--------------------|:------------------------------------------------------------------------| -| [login](login.md) | Log in to a registry | -| [logout](logout.md) | Log out from a registry | -| [pull](pull.md) | Download an image from a registry | -| [push](push.md) | Upload an image to a registry | -| [search](search.md) | Search Docker Hub for images | +| Command | Description | +| :------------------ | :-------------------------------- | +| [login](login.md) | Log in to a registry | +| [logout](logout.md) | Log out from a registry | +| [pull](pull.md) | Download an image from a registry | +| [push](push.md) | Upload an image to a registry | +| [search](search.md) | Search Docker Hub for images | ### Network and connectivity commands | Command | Description | -|:--------------------------------------------|:-------------------------------------------------------| +| :------------------------------------------ | :----------------------------------------------------- | | [network connect](network_connect.md) | Connect a container to a network | | [network create](network_create.md) | Create a new network | | [network disconnect](network_disconnect.md) | Disconnect a container from a network | @@ -97,7 +96,7 @@ read the [`dockerd`](dockerd.md) reference page. ### Shared data volume commands | Command | Description | -|:------------------------------------|:-----------------------------------------------------------------| +| :---------------------------------- | :--------------------------------------------------------------- | | [volume create](volume_create.md) | Creates a new volume where containers can consume and store data | | [volume inspect](volume_inspect.md) | Display information about a volume | | [volume ls](volume_ls.md) | Lists all the volumes Docker knows about | @@ -107,7 +106,7 @@ read the [`dockerd`](dockerd.md) reference page. ### Swarm node commands | Command | Description | -|:--------------------------------|:--------------------------------------------------------------| +| :------------------------------ | :------------------------------------------------------------ | | [node demote](node_demote.md) | Demotes an existing manager so that it is no longer a manager | | [node inspect](node_inspect.md) | Inspect a node in the swarm | | [node ls](node_ls.md) | List nodes in the swarm | @@ -119,19 +118,19 @@ read the [`dockerd`](dockerd.md) reference page. ### Swarm management commands | Command | Description | -|:----------------------------------------|:----------------------------------------------| +| :-------------------------------------- | :-------------------------------------------- | | [swarm init](swarm_init.md) | Initialize a swarm | +| [swarm join-token](swarm_join-token.md) | Display or rotate join tokens | | [swarm join](swarm_join.md) | Join a swarm as a manager node or worker node | | [swarm leave](swarm_leave.md) | Remove the current node from the swarm | -| [swarm join-token](swarm_join-token.md) | Display or rotate join tokens | -| [swarm unlock](swarm_unlock.md) | Unlock swarm | | [swarm unlock-key](swarm_unlock-key.md) | Manage the unlock key | +| [swarm unlock](swarm_unlock.md) | Unlock swarm | | [swarm update](swarm_update.md) | Update attributes of a swarm | ### Swarm service commands | Command | Description | -|:--------------------------------------|:----------------------------------------------------------------| +| :------------------------------------ | :-------------------------------------------------------------- | | [service create](service_create.md) | Create a new service | | [service inspect](service_inspect.md) | Inspect a service | | [service logs](service_logs.md) | Fetch the logs of a service or task | @@ -144,7 +143,7 @@ read the [`dockerd`](dockerd.md) reference page. ### Swarm secret commands | Command | Description | -|:-------------------------------------|:------------------------------------------------| +| :----------------------------------- | :---------------------------------------------- | | [secret create](secret_create.md) | Create a secret from a file or STDIN as content | | [secret inspect](service_inspect.md) | Inspect the specified secret | | [secret ls](secret_ls.md) | List secrets in the swarm | @@ -153,18 +152,18 @@ read the [`dockerd`](dockerd.md) reference page. ### Swarm stack commands | Command | Description | -|:------------------------------------|:--------------------------------------------------------| +| :---------------------------------- | :------------------------------------------------------ | +| [stack config](stack_config.md) | Output the Compose file after merges and interpolations | | [stack deploy](stack_deploy.md) | Deploy a new stack or update an existing stack | | [stack ls](stack_ls.md) | List stacks in the swarm | | [stack ps](stack_ps.md) | List the tasks in the stack | | [stack rm](stack_rm.md) | Remove the stack from the swarm | | [stack services](stack_services.md) | List the services in the stack | -| [stack config](stack_config.md) | Output the Compose file after merges and interpolations | ### Plugin commands | Command | Description | -|:------------------------------------|:------------------------------------------------| +| :---------------------------------- | :---------------------------------------------- | | [plugin create](plugin_create.md) | Create a plugin from a rootfs and configuration | | [plugin disable](plugin_disable.md) | Disable a plugin | | [plugin enable](plugin_enable.md) | Enable a plugin | @@ -178,13 +177,12 @@ read the [`dockerd`](dockerd.md) reference page. ### Context commands | Command | Description | -|:--------------------------------------|:-------------------------------| +| :------------------------------------ | :----------------------------- | | [context create](context_create.md) | Create a context | | [context export](context_export.md) | Export a context | | [context import](context_import.md) | Import a context | +| [context inspect](context_inspect.md) | Inspect one or more contexts | | [context ls](context_ls.md) | List contexts | | [context rm](context_rm.md) | Remove one or more contexts | | [context update](context_update.md) | Update a context | | [context use](context_use.md) | Set the current docker context | -| [context inspect](context_inspect.md) | Inspect one or more contexts | - diff --git a/docs/reference/commandline/info.md b/docs/reference/commandline/info.md index 48fb3597d5..c155096a91 100644 --- a/docs/reference/commandline/info.md +++ b/docs/reference/commandline/info.md @@ -1,4 +1,4 @@ -# info +# docker info Display system-wide information @@ -9,169 +9,10 @@ Display system-wide information ### Options -| Name | Type | Default | Description | -|:---------------------------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [`-f`](#format), [`--format`](#format) | `string` | | Format output using a custom template:
'json': Print in JSON format
'TEMPLATE': Print output using the given Go template.
Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | +| Name | Type | Default | Description | +|:-----------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `-f`, `--format` | `string` | | Format output using a custom template:
'json': Print in JSON format
'TEMPLATE': Print output using the given Go template.
Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | -## Description - -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](https://pkg.go.dev/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. - -## Examples - -### Show output - -The example below shows the output for a daemon running on Ubuntu Linux, -using the `overlay2` storage driver. As can be seen in the output, additional -information about the `overlay2` storage driver is shown: - -```console -$ docker info - -Client: Docker Engine - Community - Version: 24.0.0 - Context: default - Debug Mode: false - Plugins: - buildx: Docker Buildx (Docker Inc.) - Version: v0.10.4 - Path: /usr/libexec/docker/cli-plugins/docker-buildx - compose: Docker Compose (Docker Inc.) - Version: v2.17.2 - Path: /usr/libexec/docker/cli-plugins/docker-compose - -Server: - Containers: 14 - Running: 3 - Paused: 1 - Stopped: 10 - Images: 52 - Server Version: 23.0.3 - Storage Driver: overlay2 - Backing Filesystem: extfs - Supports d_type: true - Using metacopy: false - Native Overlay Diff: true - userxattr: false - Logging Driver: json-file - Cgroup Driver: systemd - Cgroup Version: 2 - Plugins: - Volume: local - Network: bridge host ipvlan macvlan null overlay - Log: awslogs fluentd gcplogs gelf journald json-file local splunk syslog - CDI spec directories: - /etc/cdi - /var/run/cdi - Swarm: inactive - Runtimes: io.containerd.runc.v2 runc - Default Runtime: runc - Init Binary: docker-init - containerd version: 2806fc1057397dbaeefbea0e4e17bddfbd388f38 - runc version: v1.1.5-0-gf19387a - init version: de40ad0 - Security Options: - apparmor - seccomp - Profile: builtin - cgroupns - Kernel Version: 5.15.0-25-generic - Operating System: Ubuntu 22.04 LTS - OSType: linux - Architecture: x86_64 - CPUs: 1 - Total Memory: 991.7 MiB - Name: ip-172-30-0-91.ec2.internal - ID: 4cee4408-10d2-4e17-891c-a41736ac4536 - Docker Root Dir: /var/lib/docker - Debug Mode: false - Username: gordontheturtle - Experimental: false - Insecure Registries: - myinsecurehost:5000 - 127.0.0.0/8 - Live Restore Enabled: false -``` - -### Format the output (--format) - -You can also specify the output format: - -```console -$ docker info --format '{{json .}}' - -{"ID":"4cee4408-10d2-4e17-891c-a41736ac4536","Containers":14, ...} -``` - -### Run `docker info` on Windows - -Here is a sample output for a daemon running on Windows Server: - -```console -C:\> docker info - -Client: Docker Engine - Community - Version: 24.0.0 - Context: default - Debug Mode: false - Plugins: - buildx: Docker Buildx (Docker Inc.) - Version: v0.10.4 - Path: C:\Program Files\Docker\cli-plugins\docker-buildx.exe - compose: Docker Compose (Docker Inc.) - Version: v2.17.2 - Path: C:\Program Files\Docker\cli-plugins\docker-compose.exe - -Server: - Containers: 1 - Running: 0 - Paused: 0 - Stopped: 1 - Images: 17 - Server Version: 23.0.3 - Storage Driver: windowsfilter - Logging Driver: json-file - Plugins: - Volume: local - Network: ics internal l2bridge l2tunnel nat null overlay private transparent - Log: awslogs etwlogs fluentd gcplogs gelf json-file local splunk syslog - Swarm: inactive - Default Isolation: process - Kernel Version: 10.0 20348 (20348.1.amd64fre.fe_release.210507-1500) - Operating System: Microsoft Windows Server Version 21H2 (OS Build 20348.707) - OSType: windows - Architecture: x86_64 - CPUs: 8 - Total Memory: 3.999 GiB - Name: WIN-V0V70C0LU5P - ID: 2880d38d-464e-4d01-91bd-c76f33ba3981 - Docker Root Dir: C:\ProgramData\docker - Debug Mode: false - Experimental: true - Insecure Registries: - myregistry:5000 - 127.0.0.0/8 - Registry Mirrors: - http://192.168.1.2/ - http://registry-mirror.example.com:5000/ - Live Restore Enabled: false -``` diff --git a/docs/reference/commandline/kill.md b/docs/reference/commandline/kill.md index 2d12d6eb4d..27f8974973 100644 --- a/docs/reference/commandline/kill.md +++ b/docs/reference/commandline/kill.md @@ -1,4 +1,4 @@ -# kill +# docker kill Kill one or more running containers @@ -9,66 +9,10 @@ Kill one or more running containers ### Options -| Name | Type | Default | Description | -|:---------------------------------------|:---------|:--------|:--------------------------------| -| [`-s`](#signal), [`--signal`](#signal) | `string` | | Signal to send to the container | +| Name | Type | Default | Description | +|:-----------------|:---------|:--------|:--------------------------------| +| `-s`, `--signal` | `string` | | Signal to send to the container | -## Description - -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 reference a container by its -ID, ID-prefix, or name. - -The `--signal` flag sets the system call signal that is sent to the container. -This signal can be a signal name in the format `SIG`, for instance `SIGINT`, -or an unsigned number that matches a position in the kernel's syscall table, -for instance `2`. - -While the default (`SIGKILL`) signal will terminate the container, the signal -set through `--signal` may be non-terminal, depending on the container's main -process. For example, the `SIGHUP` signal in most cases will be non-terminal, -and the container will continue running after receiving the signal. - -> **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. - -## Examples - - -### Send a KILL signal to a container - -The following example sends the default `SIGKILL` signal to the container named -`my_container`: - -```console -$ docker kill my_container -``` - -### Send a custom signal to a container (--signal) - -The following example sends a `SIGHUP` signal to the container named -`my_container`: - -```console -$ 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: - -```console -$ docker kill --signal=SIGHUP my_container -$ docker kill --signal=HUP my_container -$ docker kill --signal=1 my_container -``` - -Refer to the [`signal(7)`](https://man7.org/linux/man-pages/man7/signal.7.html) -man-page for a list of standard Linux signals. diff --git a/docs/reference/commandline/load.md b/docs/reference/commandline/load.md index 098af0a243..778d263077 100644 --- a/docs/reference/commandline/load.md +++ b/docs/reference/commandline/load.md @@ -1,4 +1,4 @@ -# load +# docker load Load an image from a tar archive or STDIN @@ -9,52 +9,11 @@ Load an image from a tar archive or STDIN ### Options -| Name | Type | Default | Description | -|:------------------------------------|:---------|:--------|:---------------------------------------------| -| [`-i`](#input), [`--input`](#input) | `string` | | Read from tar archive file, instead of STDIN | -| `-q`, `--quiet` | | | Suppress the load output | +| Name | Type | Default | Description | +|:----------------|:---------|:--------|:---------------------------------------------| +| `-i`, `--input` | `string` | | Read from tar archive file, instead of STDIN | +| `-q`, `--quiet` | | | Suppress the load output | -## Description - -Load an image or repository from a tar archive (even if compressed with gzip, -bzip2, xz or zstd) from a file or STDIN. It restores both images and tags. - -## Examples - -```console -$ docker image ls - -REPOSITORY TAG IMAGE ID CREATED SIZE -``` - -### Load images from STDIN - -```console -$ 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 -``` - -### Load images from a file (--input) - -```console -$ 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 -``` diff --git a/docs/reference/commandline/logs.md b/docs/reference/commandline/logs.md index 5fddcbdf0c..840f0562a5 100644 --- a/docs/reference/commandline/logs.md +++ b/docs/reference/commandline/logs.md @@ -1,4 +1,4 @@ -# logs +# docker logs Fetch the logs of a container @@ -16,58 +16,8 @@ Fetch the logs of a container | `--since` | `string` | | Show logs since timestamp (e.g. `2013-01-02T13:23:37Z`) or relative (e.g. `42m` for 42 minutes) | | `-n`, `--tail` | `string` | `all` | Number of lines to show from the end of the logs | | `-t`, `--timestamps` | | | Show timestamps | -| [`--until`](#until) | `string` | | Show logs before a timestamp (e.g. `2013-01-02T13:23:37Z`) or relative (e.g. `42m` for 42 minutes) | +| `--until` | `string` | | Show logs before a timestamp (e.g. `2013-01-02T13:23:37Z`) or relative (e.g. `42m` for 42 minutes) | -## Description - -The `docker logs` command batch-retrieves logs present at the time of execution. - -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://pkg.go.dev/time#RFC3339Nano) -, 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. - -## Examples - -### Retrieve logs until a specific point in time (--until) - -In order to retrieve logs before a specific point in time, run: - -```console -$ 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 -``` diff --git a/docs/reference/commandline/pause.md b/docs/reference/commandline/pause.md index bf22b75442..0840d7fb81 100644 --- a/docs/reference/commandline/pause.md +++ b/docs/reference/commandline/pause.md @@ -1,4 +1,4 @@ -# pause +# docker pause Pause all processes within one or more containers @@ -10,25 +10,3 @@ Pause all processes within one or more containers -## Description - -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. - -## Examples - -```console -$ docker pause my_container -``` - -## Related commands - -* [unpause](unpause.md) diff --git a/docs/reference/commandline/port.md b/docs/reference/commandline/port.md index d36212c9c2..4ac285e00d 100644 --- a/docs/reference/commandline/port.md +++ b/docs/reference/commandline/port.md @@ -1,4 +1,4 @@ -# port +# docker port List port mappings or a specific mapping for the container @@ -10,33 +10,3 @@ List port mappings or a specific mapping for the container -## Examples - -### Show all mapped ports - -You can find out all the ports mapped by not specifying a `PRIVATE_PORT`, or -just a specific mapping: - -```console -$ 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 -``` diff --git a/docs/reference/commandline/ps.md b/docs/reference/commandline/ps.md index 062fdcb4cd..57fcc6199a 100644 --- a/docs/reference/commandline/ps.md +++ b/docs/reference/commandline/ps.md @@ -1,4 +1,4 @@ -# ps +# docker ps List containers @@ -9,440 +9,17 @@ List containers ### Options -| Name | Type | Default | Description | -|:---------------------------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [`-a`](#all), [`--all`](#all) | | | Show all containers (default shows just running) | -| [`-f`](#filter), [`--filter`](#filter) | `filter` | | Filter output based on conditions provided | -| [`--format`](#format) | `string` | | Format output using a custom template:
'table': Print output in table format with column headers (default)
'table TEMPLATE': Print output in table format using the given Go template
'json': Print in JSON format
'TEMPLATE': Print output using the given Go template.
Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | -| `-n`, `--last` | `int` | `-1` | Show n last created containers (includes all states) | -| `-l`, `--latest` | | | Show the latest created container (includes all states) | -| [`--no-trunc`](#no-trunc) | | | Don't truncate output | -| `-q`, `--quiet` | | | Only display container IDs | -| [`-s`](#size), [`--size`](#size) | | | Display total file sizes | +| Name | Type | Default | Description | +|:-----------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `-a`, `--all` | | | Show all containers (default shows just running) | +| `-f`, `--filter` | `filter` | | Filter output based on conditions provided | +| `--format` | `string` | | Format output using a custom template:
'table': Print output in table format with column headers (default)
'table TEMPLATE': Print output in table format using the given Go template
'json': Print in JSON format
'TEMPLATE': Print output using the given Go template.
Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | +| `-n`, `--last` | `int` | `-1` | Show n last created containers (includes all states) | +| `-l`, `--latest` | | | Show the latest created container (includes all states) | +| `--no-trunc` | | | Don't truncate output | +| `-q`, `--quiet` | | | Only display container IDs | +| `-s`, `--size` | | | Display total file sizes | -## Examples - -### Do not truncate output (--no-trunc) - -Running `docker ps --no-trunc` showing 2 linked containers. - -```console -$ docker ps --no-trunc - -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -ca5534a51dd04bbcebe9b23ba05f389466cf0c190f1f8f182d7eea92a9671d00 ubuntu:22.04 bash 17 seconds ago Up 16 seconds 3300-3310/tcp webapp -9ca9747b233100676a48cc7806131586213fa5dab86dd1972d6a8732e3a84a4d crosbymichael/redis:latest /redis-server --dir 33 minutes ago Up 33 minutes 6379/tcp redis,webapp/db -``` - -### Show both running and stopped containers (-a, --all) - -The `docker ps` command only shows running containers by default. To see all -containers, use the `--all` (or `-a`) flag: - -```console -$ 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 (--size) - -The `docker ps --size` (or `-s`) command displays two different on-disk-sizes for each container: - -```console -$ docker ps --size - -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 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 (--filter) - -The `--filter` (or `-f`) flag 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. - -```console -$ 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. - -```console -$ 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. - -```console -$ 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: - -```console -$ 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: - -```console -$ 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. - -```console -$ 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. The possible values for the container status are: - -| Status | Description | -| :----------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `created` | A container that has never been started. | -| `running` | A running container, started by either `docker start` or `docker run`. | -| `paused` | A paused container. See `docker pause`. | -| `restarting` | A container which is starting due to the designated restart policy for that container. | -| `exited` | A container which is no longer running. For example, the process inside the container completed or the container was stopped using the `docker stop` command. | -| `removing` | A container which is in the process of being removed. See `docker rm`. | -| `dead` | A "defunct" container; for example, a container that was only partially removed because resources were kept busy by an external process. `dead` containers cannot be (re)started, only removed. | - -For example, to filter for `running` containers: - -```console -$ 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: - -```console -$ 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: - -```console -$ 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`: - -```console -$ 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 `22.04` image: - -```console -$ docker ps --filter ancestor=ubuntu:22.04 - -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -82a598284012 ubuntu:22.04 "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. - -```console -$ docker ps --filter ancestor=d0e008c6cf02 - -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -82a598284012 ubuntu:22.04 "top" 3 minutes ago Up 3 minutes sleepy_bose -``` - -#### Create time - -##### before - -The `before` filter shows only containers created before the container with -a given ID or name. For example, having these containers created: - -```console -$ 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: - -```console -$ 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 a given -ID or name. For example, with the same containers as in `before` filter: - -```console -$ 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: - -```console -$ 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`. - -```console -$ 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: - -```console -$ 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: - -```console -$ 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`: - -```console -$ 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`: - -```console -$ docker ps --filter publish=80/udp - -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -``` - -### Format the output (--format) - -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. | -| `.State` | Container status (for example; "created", "running", "exited"). | -| `.Status` | Container status with details about duration and health-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: - -```console -$ 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: - -```console -$ 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 -``` - -To list all running containers in JSON format, use the `json` directive: - -```console -$ docker ps --format json -{"Command":"\"/docker-entrypoint.…\"","CreatedAt":"2021-03-10 00:15:05 +0100 CET","ID":"a762a2b37a1d","Image":"nginx","Labels":"maintainer=NGINX Docker Maintainers \u003cdocker-maint@nginx.com\u003e","LocalVolumes":"0","Mounts":"","Names":"boring_keldysh","Networks":"bridge","Ports":"80/tcp","RunningFor":"4 seconds ago","Size":"0B","State":"running","Status":"Up 3 seconds"} -``` diff --git a/docs/reference/commandline/pull.md b/docs/reference/commandline/pull.md index ada165558c..9ea408dbff 100644 --- a/docs/reference/commandline/pull.md +++ b/docs/reference/commandline/pull.md @@ -1,4 +1,4 @@ -# pull +# docker pull Download an image from a registry @@ -9,236 +9,13 @@ Download an image from a registry ### Options -| Name | Type | Default | Description | -|:---------------------------------------------|:---------|:--------|:-------------------------------------------------| -| [`-a`](#all-tags), [`--all-tags`](#all-tags) | | | Download all tagged images in the repository | -| `--disable-content-trust` | | | Skip image verification | -| `--platform` | `string` | | Set platform if server is multi-platform capable | -| `-q`, `--quiet` | | | Suppress verbose output | +| Name | Type | Default | Description | +|:--------------------------|:---------|:--------|:-------------------------------------------------| +| `-a`, `--all-tags` | | | Download all tagged images in the repository | +| `--disable-content-trust` | | | Skip image verification | +| `--platform` | `string` | | Set platform if server is multi-platform capable | +| `-q`, `--quiet` | | | Suppress verbose output | -## Description - -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, refer to the [dockerd command-line reference](dockerd.md#proxy-configuration) -for details. - -### 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. - -## Examples - -### Pull an image from Docker Hub - -To download a particular image, or set of images (i.e., a repository), use -`docker image pull` (or the `docker pull` shorthand). If no tag is provided, -Docker Engine uses the `:latest` tag as a default. This example pulls the -`debian:latest` image: - -```console -$ docker image pull debian - -Using default tag: latest -latest: Pulling from library/debian -e756f3fdd6a3: Pull complete -Digest: sha256:3f1d6c17773a45c97bd8f158d665c9709d7b29ed7917ac934086ad96f92e4510 -Status: Downloaded newer image for debian:latest -docker.io/library/debian:latest -``` - -Docker images can consist of multiple layers. In the example above, the image -consists of a single layer; `e756f3fdd6a3`. - -Layers can be reused by images. For example, the `debian:bookworm` image shares -its layer with the `debian:latest`. Pulling the `debian:bookworm` image therefore -only pulls its metadata, but not its layers, because the layer is already present -locally: - -```console -$ docker image pull debian:bookworm - -bookworm: Pulling from library/debian -Digest: sha256:3f1d6c17773a45c97bd8f158d665c9709d7b29ed7917ac934086ad96f92e4510 -Status: Downloaded newer image for debian:bookworm -docker.io/library/debian:bookworm -``` - -To see which images are present locally, use the [`docker images`](images.md) -command: - -```console -$ docker images - -REPOSITORY TAG IMAGE ID CREATED SIZE -debian bookworm 4eacea30377a 8 days ago 124MB -debian latest 4eacea30377a 8 days ago 124MB -``` - -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:bookworm` and `debian:latest` have the same image ID because they are -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:22.04` pulls the latest version of the Ubuntu -22.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:22.04` image from Docker Hub: - -```console -$ docker pull ubuntu:22.04 - -22.04: Pulling from library/ubuntu -125a6e411906: Pull complete -Digest: sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d -Status: Downloaded newer image for ubuntu:22.04 -docker.io/library/ubuntu:22.04 -``` - -Docker prints the digest of the image after the pull has finished. In the example -above, the digest of the image is: - -```console -sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d -``` - -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: - -```console -$ docker pull ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d - -docker.io/library/ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d: Pulling from library/ubuntu -Digest: sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d -Status: Image is up to date for ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d -docker.io/library/ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d -``` - -Digest can also be used in the `FROM` of a Dockerfile, for example: - -```dockerfile -FROM ubuntu@sha256:26c68657ccce2cb0a31b330cb0be2b5e108d467f641c62e13ab40cbec258c68d -LABEL org.opencontainers.image.authors="some maintainer " -``` - -> **Note** -> -> Using this feature "pins" an image to a specific version in time. -> Docker does 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`): - -```console -$ docker image 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 (-a, --all-tags) - -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 `ubuntu` repository: - -```console -$ docker image pull --all-tags ubuntu - -Pulling repository ubuntu -ad57ef8d78d7: Download complete -105182bb5e8b: Download complete -511136ea3c5a: Download complete -73bd853d2ea5: Download complete -.... - -Status: Downloaded newer image for ubuntu -``` - -After the pull has completed use the `docker image ls` command (or the `docker images` -shorthand) to see the images that were pulled. The example below shows all the -`ubuntu` images that are present locally: - -```console -$ docker image ls --filter reference=ubuntu -REPOSITORY TAG IMAGE ID CREATED SIZE -ubuntu 18.04 c6ad7e71ba7d 5 weeks ago 63.2MB -ubuntu bionic c6ad7e71ba7d 5 weeks ago 63.2MB -ubuntu 22.04 5ccefbfc0416 2 months ago 78MB -ubuntu focal ff0fea8310f3 2 months ago 72.8MB -ubuntu latest ff0fea8310f3 2 months ago 72.8MB -ubuntu jammy 41ba606c8ab9 3 months ago 79MB -ubuntu 20.04 ba6acccedd29 7 months ago 72.8MB -``` - -### 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. - -```console -$ docker pull ubuntu - -Using default tag: latest -latest: Pulling from library/ubuntu -a3ed95caeb02: Pulling fs layer -236608c7b546: Pulling fs layer -^C -``` - -The Engine terminates a pull operation when the connection between the daemon -and the client (initiating the pull) is cut or lost for any reason or the -command is manually terminated. diff --git a/docs/reference/commandline/push.md b/docs/reference/commandline/push.md index a2c83dbe10..16e9c19246 100644 --- a/docs/reference/commandline/push.md +++ b/docs/reference/commandline/push.md @@ -1,4 +1,4 @@ -# push +# docker push Upload an image to a registry @@ -9,114 +9,12 @@ Upload an image to a registry ### Options -| Name | Type | Default | Description | -|:---------------------------------------------|:-----|:--------|:--------------------------------------------| -| [`-a`](#all-tags), [`--all-tags`](#all-tags) | | | Push all tags of an image to the repository | -| `--disable-content-trust` | | | Skip image signing | -| `-q`, `--quiet` | | | Suppress verbose output | +| Name | Type | Default | Description | +|:--------------------------|:-----|:--------|:--------------------------------------------| +| `-a`, `--all-tags` | | | Push all tags of an image to the repository | +| `--disable-content-trust` | | | Skip image signing | +| `-q`, `--quiet` | | | Suppress verbose output | -## Description - -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. - -## 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: - -```console -$ 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: - -```console -$ 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: - -```console -$ docker image ls -``` - -You should see both `rhel-httpd` and `registry-host:5000/myadmin/rhel-httpd` -listed. - -### Push all tags of an image (-a, --all-tags) - -Use the `-a` (or `--all-tags`) option 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. - - -```console -$ 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: - -```console -$ 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: - - -```console -$ 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 -``` - diff --git a/docs/reference/commandline/rename.md b/docs/reference/commandline/rename.md index b445a74ede..1e813055ee 100644 --- a/docs/reference/commandline/rename.md +++ b/docs/reference/commandline/rename.md @@ -1,4 +1,4 @@ -# rename +# docker rename Rename a container @@ -10,12 +10,3 @@ Rename a container -## Description - -The `docker rename` command renames a container. - -## Examples - -```console -$ docker rename my_container my_new_container -``` diff --git a/docs/reference/commandline/restart.md b/docs/reference/commandline/restart.md index 7eb5b033dc..2c6681cd2a 100644 --- a/docs/reference/commandline/restart.md +++ b/docs/reference/commandline/restart.md @@ -1,4 +1,4 @@ -# restart +# docker restart Restart one or more containers @@ -17,8 +17,3 @@ Restart one or more containers -## Examples - -```console -$ docker restart my_container -``` diff --git a/docs/reference/commandline/rm.md b/docs/reference/commandline/rm.md index cbb8b81c45..0c0bf05820 100644 --- a/docs/reference/commandline/rm.md +++ b/docs/reference/commandline/rm.md @@ -1,4 +1,4 @@ -# rm +# docker rm Remove one or more containers @@ -9,102 +9,12 @@ Remove one or more containers ### Options -| Name | Type | Default | Description | -|:------------------------------------------|:-----|:--------|:--------------------------------------------------------| -| [`-f`](#force), [`--force`](#force) | | | Force the removal of a running container (uses SIGKILL) | -| [`-l`](#link), [`--link`](#link) | | | Remove the specified link | -| [`-v`](#volumes), [`--volumes`](#volumes) | | | Remove anonymous volumes associated with the container | +| Name | Type | Default | Description | +|:------------------|:-----|:--------|:--------------------------------------------------------| +| `-f`, `--force` | | | Force the removal of a running container (uses SIGKILL) | +| `-l`, `--link` | | | Remove the specified link | +| `-v`, `--volumes` | | | Remove anonymous volumes associated with the container | -## Examples - -### Remove a container - -This removes the container referenced under the link `/redis`. - -```console -$ docker rm /redis - -/redis -``` - -### Remove a link specified with `--link` on the default bridge network (--link) - -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. - -```console -$ docker rm --link /webapp/redis - -/webapp/redis -``` - -### Force-remove a running container (--force) - -This command force-removes a running container. - -```console -$ 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 - -Use the [`docker container prune`](container_prune.md) command to remove all -stopped containers, or refer to the [`docker system prune`](system_prune.md) -command to remove unused containers in addition to other Docker resources, such -as (unused) images and networks. - -Alternatively, you can use the `docker ps` with the `-q` / `--quiet` option to -generate a list of container IDs to remove, and use that list as argument for -the `docker rm` command. - -Combining commands can be more flexible, but is less portable as it depends -on features provided by the shell, and the exact syntax may differ depending on -what shell is used. To use this approach on Windows, consider using PowerShell -or Bash. - -The example below uses `docker ps -q` to print the IDs of all containers that -have exited (`--filter status=exited`), and removes those containers with -the `docker rm` command: - -```console -$ docker rm $(docker ps --filter status=exited -q) -``` - -Or, using the `xargs` Linux utility: - -```console -$ docker ps --filter status=exited -q | xargs docker rm -``` - -### Remove a container and its volumes (-v, --volumes) - -```console -$ docker rm --volumes 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 - -```console -$ 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`. diff --git a/docs/reference/commandline/rmi.md b/docs/reference/commandline/rmi.md index 5fd35e9931..574fa03114 100644 --- a/docs/reference/commandline/rmi.md +++ b/docs/reference/commandline/rmi.md @@ -1,4 +1,4 @@ -# rmi +# docker rmi Remove one or more images @@ -17,91 +17,3 @@ Remove one or more images -## Description - -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. - -## 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. - -```console -$ 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. - -```console -$ 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: - -```console -$ 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: - -```console -$ docker rmi localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf -Untagged: localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf -Deleted: 4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125 -Deleted: ea13149945cb6b1e746bf28032f02e9b5a793523481a0a18645fc77ad53c4ea2 -Deleted: df7546f9f060a2268024c8a230d8639878585defcc1bc6f79d2728a13957871b -``` diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md index 3f79db3724..f4a72ba7bf 100644 --- a/docs/reference/commandline/run.md +++ b/docs/reference/commandline/run.md @@ -1,4 +1,4 @@ -# run +# docker run Create and run a new container from an image @@ -9,1460 +9,112 @@ Create and run a new container from an image ### Options -| Name | Type | Default | Description | -|:------------------------------------------------------|:--------------|:----------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [`--add-host`](#add-host) | `list` | | Add a custom host-to-IP mapping (host:ip) | -| `--annotation` | `map` | `map[]` | Add an annotation to the container (passed through to the OCI runtime) | -| [`-a`](#attach), [`--attach`](#attach) | `list` | | Attach to STDIN, STDOUT or STDERR | -| `--blkio-weight` | `uint16` | `0` | Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) | -| `--blkio-weight-device` | `list` | | Block IO weight (relative device weight) | -| `--cap-add` | `list` | | Add Linux capabilities | -| `--cap-drop` | `list` | | Drop Linux capabilities | -| [`--cgroup-parent`](#cgroup-parent) | `string` | | Optional parent cgroup for the container | -| `--cgroupns` | `string` | | 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) | -| [`--cidfile`](#cidfile) | `string` | | Write the container ID to the file | -| `--cpu-count` | `int64` | `0` | CPU count (Windows only) | -| `--cpu-percent` | `int64` | `0` | CPU percent (Windows only) | -| `--cpu-period` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) period | -| `--cpu-quota` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) quota | -| `--cpu-rt-period` | `int64` | `0` | Limit CPU real-time period in microseconds | -| `--cpu-rt-runtime` | `int64` | `0` | Limit CPU real-time runtime in microseconds | -| `-c`, `--cpu-shares` | `int64` | `0` | CPU shares (relative weight) | -| `--cpus` | `decimal` | | Number of CPUs | -| `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) | -| `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) | -| [`-d`](#detach), [`--detach`](#detach) | | | Run container in background and print container ID | -| [`--detach-keys`](#detach-keys) | `string` | | Override the key sequence for detaching a container | -| [`--device`](#device) | `list` | | Add a host device to the container | -| [`--device-cgroup-rule`](#device-cgroup-rule) | `list` | | Add a rule to the cgroup allowed devices list | -| `--device-read-bps` | `list` | | Limit read rate (bytes per second) from a device | -| `--device-read-iops` | `list` | | Limit read rate (IO per second) from a device | -| `--device-write-bps` | `list` | | Limit write rate (bytes per second) to a device | -| `--device-write-iops` | `list` | | Limit write rate (IO per second) to a device | -| `--disable-content-trust` | | | Skip image verification | -| `--dns` | `list` | | Set custom DNS servers | -| `--dns-option` | `list` | | Set DNS options | -| `--dns-search` | `list` | | Set custom DNS search domains | -| `--domainname` | `string` | | Container NIS domain name | -| `--entrypoint` | `string` | | Overwrite the default ENTRYPOINT of the image | -| [`-e`](#env), [`--env`](#env) | `list` | | Set environment variables | -| `--env-file` | `list` | | Read in a file of environment variables | -| `--expose` | `list` | | Expose a port or a range of ports | -| [`--gpus`](#gpus) | `gpu-request` | | GPU devices to add to the container ('all' to pass all GPUs) | -| `--group-add` | `list` | | Add additional groups to join | -| `--health-cmd` | `string` | | Command to run to check health | -| `--health-interval` | `duration` | `0s` | Time between running the check (ms\|s\|m\|h) (default 0s) | -| `--health-retries` | `int` | `0` | Consecutive failures needed to report unhealthy | -| `--health-start-interval` | `duration` | `0s` | Time between running the check during the start period (ms\|s\|m\|h) (default 0s) | -| `--health-start-period` | `duration` | `0s` | Start period for the container to initialize before starting health-retries countdown (ms\|s\|m\|h) (default 0s) | -| `--health-timeout` | `duration` | `0s` | Maximum time to allow one check to run (ms\|s\|m\|h) (default 0s) | -| `--help` | | | Print usage | -| `-h`, `--hostname` | `string` | | Container host name | -| [`--init`](#init) | | | Run an init inside the container that forwards signals and reaps processes | -| [`-i`](#interactive), [`--interactive`](#interactive) | | | Keep STDIN open even if not attached | -| `--io-maxbandwidth` | `bytes` | `0` | Maximum IO bandwidth limit for the system drive (Windows only) | -| `--io-maxiops` | `uint64` | `0` | Maximum IOps limit for the system drive (Windows only) | -| `--ip` | `string` | | IPv4 address (e.g., 172.30.100.104) | -| `--ip6` | `string` | | IPv6 address (e.g., 2001:db8::33) | -| [`--ipc`](#ipc) | `string` | | IPC mode to use | -| [`--isolation`](#isolation) | `string` | | Container isolation technology | -| `--kernel-memory` | `bytes` | `0` | Kernel memory limit | -| [`-l`](#label), [`--label`](#label) | `list` | | Set meta data on a container | -| `--label-file` | `list` | | Read in a line delimited file of labels | -| `--link` | `list` | | Add link to another container | -| `--link-local-ip` | `list` | | Container IPv4/IPv6 link-local addresses | -| [`--log-driver`](#log-driver) | `string` | | Logging driver for the container | -| `--log-opt` | `list` | | Log driver options | -| `--mac-address` | `string` | | Container MAC address (e.g., 92:d0:c6:0a:29:33) | -| [`-m`](#memory), [`--memory`](#memory) | `bytes` | `0` | Memory limit | -| `--memory-reservation` | `bytes` | `0` | Memory soft limit | -| `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: '-1' to enable unlimited swap | -| `--memory-swappiness` | `int64` | `-1` | Tune container memory swappiness (0 to 100) | -| [`--mount`](#mount) | `mount` | | Attach a filesystem mount to the container | -| [`--name`](#name) | `string` | | Assign a name to the container | -| [`--network`](#network) | `network` | | Connect a container to a network | -| `--network-alias` | `list` | | Add network-scoped alias for the container | -| `--no-healthcheck` | | | Disable any container-specified HEALTHCHECK | -| `--oom-kill-disable` | | | Disable OOM Killer | -| `--oom-score-adj` | `int` | `0` | Tune host's OOM preferences (-1000 to 1000) | -| [`--pid`](#pid) | `string` | | PID namespace to use | -| `--pids-limit` | `int64` | `0` | Tune container pids limit (set -1 for unlimited) | -| `--platform` | `string` | | Set platform if server is multi-platform capable | -| [`--privileged`](#privileged) | | | Give extended privileges to this container | -| [`-p`](#publish), [`--publish`](#publish) | `list` | | Publish a container's port(s) to the host | -| [`-P`](#publish-all), [`--publish-all`](#publish-all) | | | Publish all exposed ports to random ports | -| [`--pull`](#pull) | `string` | `missing` | Pull image before running (`always`, `missing`, `never`) | -| `-q`, `--quiet` | | | Suppress the pull output | -| [`--read-only`](#read-only) | | | Mount the container's root filesystem as read only | -| [`--restart`](#restart) | `string` | `no` | Restart policy to apply when a container exits | -| [`--rm`](#rm) | | | Automatically remove the container when it exits | -| `--runtime` | `string` | | Runtime to use for this container | -| [`--security-opt`](#security-opt) | `list` | | Security Options | -| `--shm-size` | `bytes` | `0` | Size of /dev/shm | -| `--sig-proxy` | | | Proxy received signals to the process | -| [`--stop-signal`](#stop-signal) | `string` | | Signal to stop the container | -| [`--stop-timeout`](#stop-timeout) | `int` | `0` | Timeout (in seconds) to stop a container | -| [`--storage-opt`](#storage-opt) | `list` | | Storage driver options for the container | -| [`--sysctl`](#sysctl) | `map` | `map[]` | Sysctl options | -| [`--tmpfs`](#tmpfs) | `list` | | Mount a tmpfs directory | -| [`-t`](#tty), [`--tty`](#tty) | | | Allocate a pseudo-TTY | -| [`--ulimit`](#ulimit) | `ulimit` | | Ulimit options | -| `-u`, `--user` | `string` | | Username or UID (format: [:]) | -| `--userns` | `string` | | User namespace to use | -| [`--uts`](#uts) | `string` | | UTS namespace to use | -| [`-v`](#volume), [`--volume`](#volume) | `list` | | Bind mount a volume | -| `--volume-driver` | `string` | | Optional volume driver for the container | -| [`--volumes-from`](#volumes-from) | `list` | | Mount volumes from the specified container(s) | -| [`-w`](#workdir), [`--workdir`](#workdir) | `string` | | Working directory inside the container | +| Name | Type | Default | Description | +|:--------------------------|:--------------|:----------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--add-host` | `list` | | Add a custom host-to-IP mapping (host:ip) | +| `--annotation` | `map` | `map[]` | Add an annotation to the container (passed through to the OCI runtime) | +| `-a`, `--attach` | `list` | | Attach to STDIN, STDOUT or STDERR | +| `--blkio-weight` | `uint16` | `0` | Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) | +| `--blkio-weight-device` | `list` | | Block IO weight (relative device weight) | +| `--cap-add` | `list` | | Add Linux capabilities | +| `--cap-drop` | `list` | | Drop Linux capabilities | +| `--cgroup-parent` | `string` | | Optional parent cgroup for the container | +| `--cgroupns` | `string` | | 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) | +| `--cidfile` | `string` | | Write the container ID to the file | +| `--cpu-count` | `int64` | `0` | CPU count (Windows only) | +| `--cpu-percent` | `int64` | `0` | CPU percent (Windows only) | +| `--cpu-period` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) period | +| `--cpu-quota` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) quota | +| `--cpu-rt-period` | `int64` | `0` | Limit CPU real-time period in microseconds | +| `--cpu-rt-runtime` | `int64` | `0` | Limit CPU real-time runtime in microseconds | +| `-c`, `--cpu-shares` | `int64` | `0` | CPU shares (relative weight) | +| `--cpus` | `decimal` | | Number of CPUs | +| `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) | +| `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) | +| `-d`, `--detach` | | | Run container in background and print container ID | +| `--detach-keys` | `string` | | Override the key sequence for detaching a container | +| `--device` | `list` | | Add a host device to the container | +| `--device-cgroup-rule` | `list` | | Add a rule to the cgroup allowed devices list | +| `--device-read-bps` | `list` | | Limit read rate (bytes per second) from a device | +| `--device-read-iops` | `list` | | Limit read rate (IO per second) from a device | +| `--device-write-bps` | `list` | | Limit write rate (bytes per second) to a device | +| `--device-write-iops` | `list` | | Limit write rate (IO per second) to a device | +| `--disable-content-trust` | | | Skip image verification | +| `--dns` | `list` | | Set custom DNS servers | +| `--dns-option` | `list` | | Set DNS options | +| `--dns-search` | `list` | | Set custom DNS search domains | +| `--domainname` | `string` | | Container NIS domain name | +| `--entrypoint` | `string` | | Overwrite the default ENTRYPOINT of the image | +| `-e`, `--env` | `list` | | Set environment variables | +| `--env-file` | `list` | | Read in a file of environment variables | +| `--expose` | `list` | | Expose a port or a range of ports | +| `--gpus` | `gpu-request` | | GPU devices to add to the container ('all' to pass all GPUs) | +| `--group-add` | `list` | | Add additional groups to join | +| `--health-cmd` | `string` | | Command to run to check health | +| `--health-interval` | `duration` | `0s` | Time between running the check (ms\|s\|m\|h) (default 0s) | +| `--health-retries` | `int` | `0` | Consecutive failures needed to report unhealthy | +| `--health-start-interval` | `duration` | `0s` | Time between running the check during the start period (ms\|s\|m\|h) (default 0s) | +| `--health-start-period` | `duration` | `0s` | Start period for the container to initialize before starting health-retries countdown (ms\|s\|m\|h) (default 0s) | +| `--health-timeout` | `duration` | `0s` | Maximum time to allow one check to run (ms\|s\|m\|h) (default 0s) | +| `--help` | | | Print usage | +| `-h`, `--hostname` | `string` | | Container host name | +| `--init` | | | Run an init inside the container that forwards signals and reaps processes | +| `-i`, `--interactive` | | | Keep STDIN open even if not attached | +| `--io-maxbandwidth` | `bytes` | `0` | Maximum IO bandwidth limit for the system drive (Windows only) | +| `--io-maxiops` | `uint64` | `0` | Maximum IOps limit for the system drive (Windows only) | +| `--ip` | `string` | | IPv4 address (e.g., 172.30.100.104) | +| `--ip6` | `string` | | IPv6 address (e.g., 2001:db8::33) | +| `--ipc` | `string` | | IPC mode to use | +| `--isolation` | `string` | | Container isolation technology | +| `--kernel-memory` | `bytes` | `0` | Kernel memory limit | +| `-l`, `--label` | `list` | | Set meta data on a container | +| `--label-file` | `list` | | Read in a line delimited file of labels | +| `--link` | `list` | | Add link to another container | +| `--link-local-ip` | `list` | | Container IPv4/IPv6 link-local addresses | +| `--log-driver` | `string` | | Logging driver for the container | +| `--log-opt` | `list` | | Log driver options | +| `--mac-address` | `string` | | Container MAC address (e.g., 92:d0:c6:0a:29:33) | +| `-m`, `--memory` | `bytes` | `0` | Memory limit | +| `--memory-reservation` | `bytes` | `0` | Memory soft limit | +| `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: '-1' to enable unlimited swap | +| `--memory-swappiness` | `int64` | `-1` | Tune container memory swappiness (0 to 100) | +| `--mount` | `mount` | | Attach a filesystem mount to the container | +| `--name` | `string` | | Assign a name to the container | +| `--network` | `network` | | Connect a container to a network | +| `--network-alias` | `list` | | Add network-scoped alias for the container | +| `--no-healthcheck` | | | Disable any container-specified HEALTHCHECK | +| `--oom-kill-disable` | | | Disable OOM Killer | +| `--oom-score-adj` | `int` | `0` | Tune host's OOM preferences (-1000 to 1000) | +| `--pid` | `string` | | PID namespace to use | +| `--pids-limit` | `int64` | `0` | Tune container pids limit (set -1 for unlimited) | +| `--platform` | `string` | | Set platform if server is multi-platform capable | +| `--privileged` | | | Give extended privileges to this container | +| `-p`, `--publish` | `list` | | Publish a container's port(s) to the host | +| `-P`, `--publish-all` | | | Publish all exposed ports to random ports | +| `--pull` | `string` | `missing` | Pull image before running (`always`, `missing`, `never`) | +| `-q`, `--quiet` | | | Suppress the pull output | +| `--read-only` | | | Mount the container's root filesystem as read only | +| `--restart` | `string` | `no` | Restart policy to apply when a container exits | +| `--rm` | | | Automatically remove the container when it exits | +| `--runtime` | `string` | | Runtime to use for this container | +| `--security-opt` | `list` | | Security Options | +| `--shm-size` | `bytes` | `0` | Size of /dev/shm | +| `--sig-proxy` | | | Proxy received signals to the process | +| `--stop-signal` | `string` | | Signal to stop the container | +| `--stop-timeout` | `int` | `0` | Timeout (in seconds) to stop a container | +| `--storage-opt` | `list` | | Storage driver options for the container | +| `--sysctl` | `map` | `map[]` | Sysctl options | +| `--tmpfs` | `list` | | Mount a tmpfs directory | +| `-t`, `--tty` | | | Allocate a pseudo-TTY | +| `--ulimit` | `ulimit` | | Ulimit options | +| `-u`, `--user` | `string` | | Username or UID (format: [:]) | +| `--userns` | `string` | | User namespace to use | +| `--uts` | `string` | | UTS namespace to use | +| `-v`, `--volume` | `list` | | Bind mount a volume | +| `--volume-driver` | `string` | | Optional volume driver for the container | +| `--volumes-from` | `list` | | Mount volumes from the specified container(s) | +| `-w`, `--workdir` | `string` | | Working directory inside the container | -## Description - -The `docker run` command runs a command in a new container, pulling the image if needed and starting the container. - -You can restart a stopped container with all its previous changes intact using `docker start`. -Use `docker ps -a` to view a list of all containers, including those that are stopped. - -## Examples - -### Assign name (--name) - -The `--name` flag lets you specify a custom identifier for a container. The -following example runs a container named `test` using the `nginx:alpine` image -in [detached mode](#detach). - -```console -$ docker run --name test -d nginx:alpine -4bed76d3ad428b889c56c1ecc2bf2ed95cb08256db22dc5ef5863e1d03252a19 -$ docker ps -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -4bed76d3ad42 nginx:alpine "/docker-entrypoint.…" 1 second ago Up Less than a second 80/tcp test -``` - -You can reference the container by name with other commands. For example, the -following commands stop and remove a container named `test`: - -```console -$ docker stop test -test -$ docker rm test -test -``` - -If you don't specify a custom name using the `--name` flag, the daemon assigns -a randomly generated name, such as `vibrant_cannon`, to the container. Using a -custom-defined name provides the benefit of having an easy-to-remember ID for a -container. - -Moreover, if you connect the container to a user-defined bridge network, other -containers on the same network can refer to the container by name via DNS. - -```console -$ docker network create mynet -cb79f45948d87e389e12013fa4d969689ed2c3316985dd832a43aaec9a0fe394 -$ docker run --name test --net mynet -d nginx:alpine -58df6ecfbc2ad7c42d088ed028d367f9e22a5f834d7c74c66c0ab0485626c32a -$ docker run --net mynet busybox:latest ping test -PING test (172.18.0.2): 56 data bytes -64 bytes from 172.18.0.2: seq=0 ttl=64 time=0.073 ms -64 bytes from 172.18.0.2: seq=1 ttl=64 time=0.411 ms -64 bytes from 172.18.0.2: seq=2 ttl=64 time=0.319 ms -64 bytes from 172.18.0.2: seq=3 ttl=64 time=0.383 ms -... -``` - -### Capture container ID (--cidfile) - -To help with automation, you can have Docker write the container ID out to a -file of your choosing. This is similar to how some programs might write out -their process ID to a file (you might've seen them as PID files): - -```console -$ docker run --cidfile /tmp/docker_test.cid ubuntu echo "test" -``` - -This creates a container and prints `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 returns an error. Docker closes this -file when `docker run` exits. - -### PID settings (--pid) - -```text ---pid="" : Set the PID (Process) Namespace mode for the container, - 'container:': joins another container's PID namespace - 'host': use the host's PID namespace inside the container -``` - -By default, all containers have the PID namespace enabled. - -PID namespace provides separation of processes. The PID Namespace removes the -view of the system processes, and allows process ids to be reused including -PID 1. - -In certain cases you want your container to share the host's process namespace, -allowing processes within the container to see all of the processes on the -system. For example, you could build a container with debugging tools like -`strace` or `gdb`, but want to use these tools when debugging processes within -the container. - -#### Example: run htop inside a container - -To run `htop` in a container that shares the process namespac of the host: - -1. Run an alpine container with the `--pid=host` option: - - ```console - $ docker run --rm -it --pid=host alpine - ``` - -2. Install `htop` in the container: - - ```console - / # apk add htop - fetch https://dl-cdn.alpinelinux.org/alpine/v3.18/main/aarch64/APKINDEX.tar.gz - fetch https://dl-cdn.alpinelinux.org/alpine/v3.18/community/aarch64/APKINDEX.tar.gz - (1/3) Installing ncurses-terminfo-base (6.4_p20230506-r0) - (2/3) Installing libncursesw (6.4_p20230506-r0) - (3/3) Installing htop (3.2.2-r1) - Executing busybox-1.36.1-r2.trigger - OK: 9 MiB in 18 packages - ``` - -3. Invoke the `htop` command. - - ```console - / # htop - ``` - -#### Example, join another container's PID namespace - -Joining another container's PID namespace can be useful for debugging that -container. - -1. Start a container running a Redis server: - - ```console - $ docker run --rm --name my-nginx -d nginx:alpine - ``` - -2. Run an Alpine container that attaches the `--pid` namespace to the - `my-nginx` container: - - ```console - $ docker run --rm -it --pid=container:my-nginx \ - --cap-add SYS_PTRACE \ - --security-opt seccomp=unconfined \ - alpine - ``` - -3. Install `strace` in the Alpine container: - - ```console - / # apk add strace - ``` - -4. Attach to process 1, the process ID of the `my-nginx` container: - - ```console - / # strace -p 1 - strace: Process 1 attached - ``` - -### UTS settings (--uts) - -```text ---uts="" : Set the UTS namespace mode for the container - 'host': use the host's UTS namespace inside the container -``` - -The UTS namespace is for setting the hostname and the domain that's visible to -running processes in that namespace. By default, all containers, including -those with `--network=host`, have their own UTS namespace. Setting `--uts` to -`host` results in the container using the same UTS namespace as the host. - -> **Note** -> -> Docker disallows combining the `--hostname` and `--domainname` flags with -> `--uts=host`. This is to prevent containers running in the host's UTS -> namespace from attempting to change the hosts' configuration. - -You may wish to share the UTS namespace with the host if you would like the -hostname of the container to change as the hostname of the host changes. A more -advanced use case would be changing the host's hostname from a container. - -### IPC settings (--ipc) - -```text ---ipc="MODE" : Set the IPC mode for the container -``` - -The `--ipc` flag accepts the following values: - -| Value | Description | -|:---------------------------|:----------------------------------------------------------------------------------| -| "" | Use daemon's default. | -| "none" | Own private IPC namespace, with /dev/shm not mounted. | -| "private" | Own private IPC namespace. | -| "shareable" | Own private IPC namespace, with a possibility to share it with other containers. | -| "container:<_name-or-ID_>" | Join another ("shareable") container's IPC namespace. | -| "host" | Use the host system's IPC namespace. | - -If not specified, daemon default is used, which can either be `"private"` -or `"shareable"`, depending on the daemon version and configuration. - -[System V interprocess communication (IPC)](https://linux.die.net/man/5/ipc) -namespaces provide separation of named shared memory segments, semaphores and -message queues. - -Shared memory segments are used to accelerate inter-process communication at -memory speed, rather than through pipes or through the network stack. Shared -memory is commonly used by databases and custom-built (typically C/OpenMPI, -C++/using boost libraries) high performance applications for scientific -computing and financial services industries. If these types of applications -are broken into multiple containers, you might need to share the IPC mechanisms -of the containers, using `"shareable"` mode for the main (i.e. "donor") -container, and `"container:"` for other containers. - -### Full container capabilities (--privileged) - -The following example doesn't work, because by default, Docker drops most -potentially dangerous kernel capabilities, including `CAP_SYS_ADMIN ` (which is -required to mount filesystems). - -```console -$ docker run -t -i --rm ubuntu bash -root@bc338942ef20:/# mount -t tmpfs none /mnt -mount: permission denied -``` - -It works when you add the `--privileged` flag: - -```console -$ 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, --workdir) - -```console -$ docker run -w /path/to/dir/ -i -t ubuntu pwd -``` - -The `-w` option runs the command executed inside the directory specified, in this example, -`/path/to/dir/`. If the path doesn't exist, Docker creates it inside the container. - -### Set storage driver options per container (--storage-opt) - -```console -$ docker run -it --storage-opt size=120G fedora /bin/bash -``` - -This (size) constraints the container filesystem size to 120G at creation time. -This option is only available for the `btrfs`, `overlay2`, `windowsfilter`, -and `zfs` storage drivers. - -For the `overlay2` storage driver, the size option is only available if the -backing filesystem is `xfs` and mounted with the `pquota` mount option. -Under these conditions, you can pass any size less than the backing filesystem size. - -For the `windowsfilter`, `btrfs`, and `zfs` storage drivers, you cannot pass a -size less than the Default BaseFS Size. - -### Mount tmpfs (--tmpfs) - -The `--tmpfs` flag lets you create a `tmpfs` mount. - -The options that you can pass to `--tmpfs` are identical to the Linux `mount -t -tmpfs -o` command. The following example mounts an empty `tmpfs` into the -container with the `rw`, `noexec`, `nosuid`, `size=65536k` options. - -```console -$ docker run -d --tmpfs /run:rw,noexec,nosuid,size=65536k my_image -``` - -For more information, see [tmpfs mounts](https://docs.docker.com/storage/tmpfs/#tmpfs-mounts). - -### Mount volume (-v) - -```console -$ docker run -v $(pwd):$(pwd) -w $(pwd) -i -t ubuntu pwd -``` - -The example above mounts the current directory into the container at the same path -using the `-v` flag, sets it as the working directory, and then runs the `pwd` command inside the container. - -As of Docker Engine version 23, you can use relative paths on the host. - -```console -$ docker run -v ./content:/content -w /content -i -t ubuntu pwd -``` - -The example above mounts the `content` directory in the current directory into the container at the -`/content` path using the `-v` flag, sets it as the working directory, and then -runs the `pwd` command inside the container. - -```console -$ 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 -automatically creates this directory on the host for you. In the -example above, Docker creates the `/doesnt/exist` -folder before starting your container. - -### Mount volume read-only (--read-only) - -```console -$ docker run --read-only -v /icanwrite busybox touch /icanwrite/here -``` - -You can use volumes in combination with the `--read-only` flag 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. - -```console -$ 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, you must specify the paths using Windows-style path 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 fails 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 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 -[Bind mounts](https://docs.docker.com/storage/bind-mounts/). - -Even though there is no plan to deprecate `--volume`, usage of `--mount` is recommended. - -Examples: - -```console -$ docker run --read-only --mount type=volume,target=/icanwrite busybox touch /icanwrite/here -``` - -```console -$ docker run -t -i --mount type=bind,src=/data,dst=/data busybox sh -``` - -### Publish or expose port (-p, --expose) - -```console -$ docker run -p 127.0.0.1:80:8080/tcp nginx:alpine -``` - -This binds port `8080` of the container to TCP port `80` on `127.0.0.1` of the -host. You can also specify `udp` and `sctp` ports. The [Networking overview -page](https://docs.docker.com/network/) explains in detail how to publish ports -with Docker. - -> **Note** -> -> If you don't specify an IP address (i.e., `-p 80:80` instead of `-p -> 127.0.0.1:80:80`) when publishing a container's ports, Docker publishes the -> port on all interfaces (address `0.0.0.0`) by default. These ports are -> externally accessible. This also applies if you configured UFW to block this -> specific port, as Docker manages its own iptables rules. [Read -> more](https://docs.docker.com/network/packet-filtering-firewalls/) - -```console -$ docker run --expose 80 nginx:alpine -``` - -This exposes port `80` of the container without publishing the port to the host -system's interfaces. - -### Publish all exposed ports (-P, --publish-all) - -```console -$ docker run -P nginx:alpine -``` - -The `-P`, or `--publish-all`, flag publishes all the exposed ports to the host. -Docker binds each exposed port to a random port on the host. - -The `-P` flag only publishes port numbers that are explicitly flagged as -exposed, either using the Dockerfile `EXPOSE` instruction or the `--expose` -flag for the `docker run` command. - -The range of ports are within an *ephemeral port range* defined by -`/proc/sys/net/ipv4/ip_local_port_range`. Use the `-p` flag to explicitly map a -single port or range of ports. - -### Set the pull policy (--pull) - -Use the `--pull` flag to set the image pull policy when creating (and running) -the container. - -The `--pull` flag can take one of these values: - -| Value | Description | -|:--------------------|:------------------------------------------------------------------------------------------------------------------| -| `missing` (default) | Pull the image if it was not found in the image cache, or use the cached image otherwise. | -| `never` | Do not pull the image, even if it's missing, and produce an error if the image does not exist in the image cache. | -| `always` | Always perform a pull before creating the container. | - -When creating (and running) a container from an image, the daemon checks if the -image exists in the local image cache. If the image is missing, an error is -returned to the CLI, allowing it to initiate a pull. - -The default (`missing`) is to only pull the image if it's not present in the -daemon's image cache. This default allows you to run images that only exist -locally (for example, images you built from a Dockerfile, but that have not -been pushed to a registry), and reduces networking. - -The `always` option always initiates a pull before creating the container. This -option makes sure the image is up-to-date, and prevents you from using outdated -images, but may not be suitable in situations where you want to test a locally -built image before pushing (as pulling the image overwrites the existing image -in the image cache). - -The `never` option disables (implicit) pulling images when creating containers, -and only uses images that are available in the image cache. If the specified -image is not found, an error is produced, and the container is not created. -This option is useful in situations where networking is not available, or to -prevent images from being pulled implicitly when creating containers. - -The following example shows `docker run` with the `--pull=never` option set, -which produces en error as the image is missing in the image-cache: - -```console -$ docker run --pull=never hello-world -docker: Error response from daemon: No such image: hello-world:latest. -``` - -### Set environment variables (-e, --env, --env-file) - -```console -$ 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 -defined in the Dockerfile of the image you're running. - -You can define the variable and its value when running the container: - -```console -$ docker run --env VAR1=value1 --env VAR2=value2 ubuntu env | grep VAR -VAR1=value1 -VAR2=value2 -``` - -You can also use variables exported to your local environment: - -```console -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 isn't exported in your local -environment, the variable is unset 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. Lines beginning with `#` are treated as line comments and are -ignored, whereas a `#` appearing anywhere else in a line is treated as part of -the variable value. - -```console -$ cat env.list -# This is a comment -VAR1=value1 -VAR2=value2 -USER - -$ docker run --env-file env.list ubuntu env | grep -E 'VAR|USER' -VAR1=value1 -VAR2=value2 -USER=jonzeolla -``` - -### 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: - -```console -$ 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: - -```console -$ 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 shows 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](https://docs.docker.com/config/labels-custom-metadata/). - -### Connect a container to a network (--network) - -To start a container and connect it to a network, use the `--network` option. - -The following commands create a network named `my-net` and adds a `busybox` container -to the `my-net` network. - -```console -$ docker network create my-net -$ 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. To assign a -static IP to containers, you must specify subnet block for the network. - -```console -$ docker network create --subnet 192.0.2.0/24 my-net -$ docker run -itd --network=my-net --ip=192.0.2.69 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 using 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** -> -> The default bridge network only allow containers to communicate with each other using -> internal IP addresses. User-created bridge networks provide DNS resolution between -> containers using container names. - -You can disconnect a container from a network using the `docker network -disconnect` command. - -For more information on connecting a container to a network when using the `run` command, see the ["*Docker network overview*"](https://docs.docker.com/network/). - -### Mount volumes from container (--volumes-from) - -```console -$ 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. You can specify more than one container 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, -Docker mounts the volumes in the same mode (read write or read only) as -the reference container. - -Labeling systems like SELinux require placing proper labels 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. - -### Detached mode (-d, --detach) - -The `--detach` (or `-d`) flag starts a container as a background process that -doesn't occupy your terminal window. By design, containers started in detached -mode exit when the root process used to run the container exits, unless you -also specify the `--rm` option. If you use `-d` with `--rm`, the container is -removed when it exits or when the daemon exits, whichever happens first. - -Don't pass a `service x start` command to a detached container. For example, -this command attempts to start the `nginx` service. - -```console -$ docker run -d -p 80:80 my_image service nginx start -``` - -This succeeds in starting the `nginx` service inside the container. However, it -fails the detached container paradigm in that, the root process (`service nginx -start`) returns and the detached container stops as designed. As a result, the -`nginx` service starts but can't be used. Instead, to start a process such as -the `nginx` web server do the following: - -```console -$ docker run -d -p 80:80 my_image nginx -g 'daemon off;' -``` - -To do input/output with a detached container use network connections or shared -volumes. These are required because the container is no longer listening to the -command line where `docker run` was run. - -### Override the detach sequence (--detach-keys) - -Use the `--detach-keys` option to 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). - -### Add host device to container (--device) - -```console -$ docker run -it --rm \ - --device=/dev/sdc:/dev/xvdc \ - --device=/dev/sdd \ - --device=/dev/zero:/dev/foobar \ - ubuntu ls -l /dev/{xvdc,sdd,foobar} - -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/foobar -``` - -It's often necessary to directly expose devices to a container. The `--device` -option enables that. For example, adding a specific block storage device or loop -device or audio device to an otherwise unprivileged container -(without the `--privileged` flag) and have the application directly access it. - -By default, the container is 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 Docker ignores the -specified permissions. - -```console -$ 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. You shouldn't -> add block devices that may be removed 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 you specify this option for a process-isolated Windows container, Docker makes -_all_ devices that implement the requested device interface class GUID -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, -> and produces an error if the container isolation is `hyperv`. - -### Attach to STDIN/STDOUT/STDERR (-a, --attach) - -The `--attach` (or `-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. You can specify to which of the three standard streams -(`STDIN`, `STDOUT`, `STDERR`) you'd like to connect instead, as in: - -```console -$ docker run -a stdin -a stdout -i -t ubuntu /bin/bash -``` - -The following example pipes data into a container and prints the container's ID -by attaching only to the container's `STDIN`. - -```console -$ echo "test" | docker run -i -a stdin ubuntu cat - -``` - -The following example doesn't print anything to the console unless there's an -error because output is only attached to the `STDERR` of the container. The -container's logs still store what's written to `STDERR` and `STDOUT`. - -```console -$ docker run -a stderr ubuntu echo test -``` - -The following example shows a way of using `--attach` to pipe a file into a -container. The command prints the container's ID after the build completes and -you can retrieve the build logs 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. - -```console -$ cat somefile | docker run -i -a stdin mybuilder dobuild -``` - -> **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 -> doesn't terminate on `SIGINT` or `SIGTERM` unless it's coded to do so. - -See also [the `docker cp` command](cp.md). - -### Keep STDIN open (-i, --interactive) - -The `--interactive` (or `-i`) flag keeps the container's `STDIN` open, and lets -you send input to the container through standard input. - -```console -$ echo hello | docker run --rm -i busybox cat -hello -``` - -The `-i` flag is most often used together with the `--tty` flag to bind the I/O -streams of the container to a pseudo terminal, creating an interactive terminal -session for the container. See [Allocate a pseudo-TTY](#tty) for more examples. - -```console -$ docker run -it debian -root@10a3e71492b0:/# factor 90 -90: 2 3 3 5 -root@10a3e71492b0:/# exit -exit -``` - -Using the `-i` flag on its own allows for composition, such as piping input to -containers: - -```console -$ docker run --rm -i busybox echo "foo bar baz" \ - | docker run --rm -i busybox awk '{ print $2 }' \ - | docker run --rm -i busybox rev -rab -``` - -### Specify an init process - -You can use the `--init` flag to indicate that an init process should be used as -the PID 1 in the container. Specifying an init process ensures the usual -responsibilities of an init system, such as reaping zombie processes, are -performed inside the created container. - -The default init process used is the first `docker-init` executable found in the -system path of the Docker daemon process. This `docker-init` binary, included in -the default installation, is backed by [tini](https://github.com/krallin/tini). - -### Allocate a pseudo-TTY (-t, --tty) - -The `--tty` (or `-t`) flag attaches a pseudo-TTY to the container, connecting -your terminal to the I/O streams of the container. Allocating a pseudo-TTY to -the container means that you get access to input and output feature that TTY -devices provide. - -For example, the following command runs the `passwd` command in a `debian` -container, to set a new password for the `root` user. - -```console -$ docker run -i debian passwd root -New password: karjalanpiirakka9 -Retype new password: karjalanpiirakka9 -passwd: password updated successfully -``` - -If you run this command with only the `-i` flag (which lets you send text to -`STDIN` of the container), the `passwd` prompt displays the password in plain -text. However, if you try the same thing but also adding the `-t` flag, the -password is hidden: - -```console -$ docker run -i debian passwd root -New password: -Retype new password: -passwd: password updated successfully -``` - -This is because `passwd` can suppress the output of characters to the terminal -using the echo-off TTY feature. - -You can use the `-t` flag without `-i` flag. This still allocates a pseudo-TTY -to the container, but with no way of writing to `STDIN`. The only time this -might be useful is if the output of the container requires a TTY environment. - -### Specify custom cgroups - -Using the `--cgroup-parent` flag, you can pass a specific cgroup to run a -container in. This allows you to create and manage cgroups on their own. You can -define custom resources for those cgroups and put containers under a common -parent group. - -### Using dynamically created devices (--device-cgroup-rule) - -Docker assigns devices available to a container at creation time. The -assigned devices are added to the cgroup.allow file and -created into the container when it runs. This poses a problem when -you need to add a new device to running container. - -One solution is to add a more permissive rule to a container -allowing it access to a wider range of devices. For example, supposing -the container needs access to a character device with major `42` and -any number of minor numbers (added as new devices appear), add the -following rule: - -```console -$ docker run -d --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**: You still need to explicitly add initially present devices to the -> `docker run` / `docker create` command. - -### Access an NVIDIA GPU - -The `--gpus` flag allows you to access NVIDIA GPU resources. First you need to -install the [nvidia-container-runtime](https://nvidia.github.io/nvidia-container-runtime/). - -Read [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 you provide no value, Docker uses all -available GPUs. The example below exposes all available GPUs. - -```console -$ docker run -it --rm --gpus all ubuntu nvidia-smi -``` - -Use the `device` option to specify GPUs. The example below exposes a specific -GPU. - -```console -$ docker run -it --rm --gpus device=GPU-3a23c669-1f69-c64e-cf85-44e9b07e7a2a ubuntu nvidia-smi -``` - -The example below exposes the first and third GPUs. - -```console -$ docker run -it --rm --gpus '"device=0,2"' ubuntu nvidia-smi -``` - -### Restart policies (--restart) - -Use the `--restart` flag 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's 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 tries to restart the container indefinitely. The container always starts on daemon startup, regardless of the current state of the container. | - -```console -$ docker run --restart=always redis -``` - -This runs the `redis` container with a restart policy of **always**. -If the container exits, Docker restarts it. - -When a restart policy is active on a container, it shows as either `Up` or -`Restarting` in [`docker ps`](ps.md). It can also be useful to use [`docker -events`](events.md) to see the restart policy in effect. - -An increasing delay (double the previous delay, starting at 100 milliseconds) -is added before each restart to prevent flooding the server. This means the -daemon waits for 100 ms, then 200 ms, 400, 800, 1600, and so on until either -the `on-failure` limit, the maximum delay of 1 minute is hit, or when you -`docker stop` or `docker rm -f` the container. - -If a container is successfully restarted (the container is started and runs -for at least 10 seconds), the delay is reset to its default value of 100 ms. - -#### Specify a limit for restart attempts - -You can specify the maximum amount of times Docker attempts to restart the -container when using the **on-failure** policy. By default, Docker never stops -attempting to restart the container. - -The following example runs the `redis` container with a restart policy of -**on-failure** and a maximum restart count of 10. - -```console -$ docker run --restart=on-failure:10 redis -``` - -If the `redis` container exits with a non-zero exit status more than 10 times -in a row, Docker stops trying to restart the container. Providing a maximum -restart limit is only valid for the **on-failure** policy. - -#### Inspect container restarts - -The number of (attempted) restarts for a container can be obtained using the -[`docker inspect`](commandline/inspect.md) command. For example, to get the -number of restarts for container "my-container"; - -```console -$ docker inspect -f "{{ .RestartCount }}" my-container -2 -``` - -Or, to get the last time the container was (re)started; - -```console -$ docker inspect -f "{{ .State.StartedAt }}" my-container -2015-03-04T23:47:07.691840179Z -``` - -Combining `--restart` (restart policy) with the `--rm` (clean up) flag results -in an error. On container restart, attached clients are disconnected. - -### Clean up (--rm) - -By default, a container's file system persists even after the container exits. -This makes debugging a lot easier, since you can inspect the container's final -state and you retain all your data. - -If you are running short-term **foreground** processes, these container file -systems can start to pile up. If you'd like Docker to automatically clean up -the container and remove the file system when the container exits, use the -`--rm` flag: - -```text ---rm=false: Automatically remove the container when it exits -``` - -> **Note** -> -> If you set the `--rm` flag, Docker also removes the anonymous volumes -> associated with the container when the container is removed. This is similar -> to running `docker rm -v my-container`. Only volumes that are specified -> without a name are removed. For example, when running the following command, -> volume `/foo` is removed, but not `/bar`: -> -> ```console -> $ docker run --rm -v /foo -v awesome:/bar busybox top -> ``` -> -> Volumes inherited via `--volumes-from` are removed with the same logic: -> if the original volume was specified with a name it isn't removed. - -### 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 -`my-hostname`: - -```console -$ docker run --add-host=my-hostname=8.8.8.8 --rm -it alpine - -/ # ping my-hostname -PING my-hostname (8.8.8.8): 56 data bytes -64 bytes from 8.8.8.8: seq=0 ttl=37 time=93.052 ms -64 bytes from 8.8.8.8: seq=1 ttl=37 time=92.467 ms -64 bytes from 8.8.8.8: seq=2 ttl=37 time=92.252 ms -^C ---- my-hostname ping statistics --- -4 packets transmitted, 4 packets received, 0% packet loss -round-trip min/avg/max = 92.209/92.495/93.052 ms -``` - -You can wrap an IPv6 address in square brackets: - -```console -$ docker run --add-host my-hostname=[2001:db8::33] --rm -it alpine -``` - -The `--add-host` flag supports a special `host-gateway` value that resolves to -the internal IP address of the host. This is useful when you want containers to -connect to services running on the host machine. - -It's conventional to use `host.docker.internal` as the hostname referring to -`host-gateway`. Docker Desktop automatically resolves this hostname, see -[Explore networking features](https://docs.docker.com/desktop/networking/#i-want-to-connect-from-a-container-to-a-service-on-the-host). - -The following example shows how the special `host-gateway` value works. The -example runs an HTTP server that serves a file from host to container over the -`host.docker.internal` hostname, which resolves to the host's internal IP. - -```console -$ echo "hello from host!" > ./hello -$ python3 -m http.server 8000 -Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ... -$ docker run \ - --add-host host.docker.internal=host-gateway \ - curlimages/curl -s host.docker.internal:8000/hello -hello from host! -``` - -The `--add-host` flag also accepts a `:` separator, for example: - -```console -$ docker run --add-host=my-hostname:8.8.8.8 --rm -it alpine -``` - -### Logging drivers (--log-driver) - -The container can have a different logging driver than the Docker daemon. Use -the `--log-driver=` with the `docker run` command to configure the -container's logging driver. - -To learn about the supported logging drivers and how to use them, refer to -[Configure logging drivers](https://docs.docker.com/config/containers/logging/configure/). - -To disable logging for a container, set the `--log-driver` flag to `none`: - -```console -$ docker run --log-driver=none -d nginx:alpine -5101d3b7fe931c27c2ba0e65fd989654d297393ad65ae238f20b97a020e7295b -$ docker logs 5101d3b -Error response from daemon: configured logging driver does not support reading -``` - -### 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. -Specify `--ulimit` with a soft and hard limit in the format -`=[:]`. For example: - -```console -$ docker run --ulimit nofile=1024:1024 --rm debian sh -c "ulimit -n" -1024 -``` - -> **Note** -> -> If you don't provide a hard limit value, Docker uses the soft limit value -> for both values. If you don't provide any values, they are inherited from -> the default `ulimits` set on the daemon. - -> **Note** -> -> The `as` option is deprecated. -> In other words, the following script is not supported: -> -> ```console -> $ docker run -it --ulimit as=1024 fedora /bin/bash -> ``` - -Docker sends the values to the appropriate OS `syscall` and 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 Linux uses `nproc` to set the -maximum number of processes available to a user, not to a container. For example, start four -containers with `daemon` user: - -```console -$ 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 a "[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 sends the system call signal to the -container to exit. This signal can be a signal name in the format `SIG`, -for instance `SIGKILL`, or an unsigned number that matches a position in the -kernel's syscall table, for instance `9`. - -The default value is defined by [`STOPSIGNAL`](https://docs.docker.com/engine/reference/builder/#stopsignal) -in the image, or `SIGTERM` if the image has no `STOPSIGNAL` defined. - -### Optional security options (--security-opt) - -| Option | Description | -|:------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `--security-opt="label=user:USER"` | Set the label user for the container | -| `--security-opt="label=role:ROLE"` | Set the label role for the container | -| `--security-opt="label=type:TYPE"` | Set the label type for the container | -| `--security-opt="label=level:LEVEL"` | Set the label level for the container | -| `--security-opt="label=disable"` | Turn off label confinement for the container | -| `--security-opt="apparmor=PROFILE"` | Set the apparmor profile to be applied to the container | -| `--security-opt="no-new-privileges=true"` | Disable container processes from gaining new privileges | -| `--security-opt="seccomp=unconfined"` | Turn off seccomp confinement for the container | -| `--security-opt="seccomp=builtin"` | Use the default (built-in) seccomp profile for the container. This can be used to enable seccomp for a container running on a daemon with a custom default profile set, or with seccomp disabled ("unconfined"). | -| `--security-opt="seccomp=profile.json"` | White-listed syscalls seccomp Json file to be used as a seccomp filter | - -The `--security-opt` flag lets you override the default labeling scheme for a -container. Specifying the level in the following command allows you to share -the same content between containers. - -```console -$ docker run --security-opt label=level:s0:c100,c200 -it fedora bash -``` - -> **Note** -> -> Automatic translation of MLS labels isn't supported. - -To disable the security labeling for a container entirely, you can use -`label=disable`: - -```console -$ docker run --security-opt label=disable -it ubuntu bash -``` - -If you want a tighter security policy on the processes within a container, you -can specify a custom `type` label. The following example runs a container -that's only allowed to listen on Apache ports: - -```console -$ docker run --security-opt label=type:svirt_apache_t -it ubuntu bash -``` - -> **Note** -> -> You would have to write policy defining a `svirt_apache_t` type. - -To prevent your container processes from gaining additional privileges, you can -use the following command: - -```console -$ docker run --security-opt no-new-privileges -it ubuntu bash -``` - -This means that commands that raise privileges such as `su` or `sudo` no longer work. -It also causes any seccomp filters to be applied later, after privileges have been dropped -which may mean you can have a more restrictive set of filters. -For more details, see the [kernel documentation](https://www.kernel.org/doc/Documentation/prctl/no_new_privs.txt). - -On Windows, you can use the `--security-opt` flag 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 number of seconds to wait for the container -to stop after sending the pre-defined (see `--stop-signal`) system call signal. -If the container does not exit after the timeout elapses, it's forcibly killed -with a `SIGKILL` signal. - -If you set `--stop-timeout` to `-1`, no timeout is applied, and the daemon -waits indefinitely for the container to exit. - -The Daemon determines the default, and is 10 seconds for Linux containers, -and 30 seconds for Windows containers. - -### 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: - -```console -$ 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. | -| `hyperv` | Hyper-V hypervisor partition-based isolation. | - -The default isolation on Windows server operating systems is `process`, and `hyperv` -on Windows client operating systems, such as Windows 10. Process isolation has better -performance, but requires that the image and host use the same kernel version. - -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. Linux sets this -on the cgroup and applications in a container can query it at `/sys/fs/cgroup/memory/memory.limit_in_bytes`. - -On Windows, this affects containers differently depending on what type of isolation you use. - -- With `process` isolation, Windows reports 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 creates 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 (--sysctl) - -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: - -```console -$ 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. - -## Command internals - -The `docker run` command is equivalent to the following API calls: - -- `//containers/create` - - If that call returns a 404 (image not found), and depending on the `--pull` option ("always", "missing", "never") the call can trigger a `docker pull `. -- `/containers/create` again after pulling the image. -- `/containers/(id)/start` to start the container. -- `/containers/(id)/attach` to attach to the container when starting with the `-it` flags for interactive containers. diff --git a/docs/reference/commandline/save.md b/docs/reference/commandline/save.md index d6df5574c1..1c9f9c53db 100644 --- a/docs/reference/commandline/save.md +++ b/docs/reference/commandline/save.md @@ -1,4 +1,4 @@ -# save +# docker save Save one or more images to a tar archive (streamed to STDOUT by default) @@ -16,46 +16,3 @@ Save one or more images to a tar archive (streamed to STDOUT by default) -## Description - -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. - -## Examples - -### Create a backup that can then be used with `docker load`. - -```console -$ 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. - -```console -$ docker save myimage:latest | gzip > myimage_latest.tar.gz -``` - -### Cherry-pick particular tags - -You can even cherry-pick particular tags of an image repository. - -```console -$ docker save -o ubuntu.tar ubuntu:lucid ubuntu:saucy -``` diff --git a/docs/reference/commandline/start.md b/docs/reference/commandline/start.md index 866a24921a..d4ea72a7c1 100644 --- a/docs/reference/commandline/start.md +++ b/docs/reference/commandline/start.md @@ -1,4 +1,4 @@ -# start +# docker start Start one or more stopped containers @@ -20,8 +20,3 @@ Start one or more stopped containers -## Examples - -```console -$ docker start my_container -``` diff --git a/docs/reference/commandline/stats.md b/docs/reference/commandline/stats.md index f59ea7838a..f1fec24e49 100644 --- a/docs/reference/commandline/stats.md +++ b/docs/reference/commandline/stats.md @@ -1,4 +1,4 @@ -# stats +# docker stats Display a live stream of container(s) resource usage statistics @@ -9,181 +9,13 @@ Display a live stream of container(s) resource usage statistics ### Options -| Name | Type | Default | Description | -|:----------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `-a`, `--all` | | | Show all containers (default shows just running) | -| [`--format`](#format) | `string` | | Format output using a custom template:
'table': Print output in table format with column headers (default)
'table TEMPLATE': Print output in table format using the given Go template
'json': Print in JSON format
'TEMPLATE': Print output using the given Go template.
Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | -| `--no-stream` | | | Disable streaming stats and only pull the first result | -| `--no-trunc` | | | Do not truncate output | +| Name | Type | Default | Description | +|:--------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `-a`, `--all` | | | Show all containers (default shows just running) | +| `--format` | `string` | | Format output using a custom template:
'table': Print output in table format with column headers (default)
'table TEMPLATE': Print output in table format using the given Go template
'json': Print in JSON format
'TEMPLATE': Print output using the given Go template.
Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | +| `--no-stream` | | | Disable streaming stats and only pull the first result | +| `--no-trunc` | | | Do not truncate output | -## Description - -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. - -## Examples - -Running `docker stats` on all running containers against a Linux daemon. - -```console -$ 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`](#format), 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 received and sent over its network interface | -| `BLOCK I/O` | The amount of data the container has written to and read 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. - -```console -$ 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` on container with name `nginx` and getting output in `json` format. - -```console -$ docker stats nginx --no-stream --format "{{ json . }}" -{"BlockIO":"0B / 13.3kB","CPUPerc":"0.03%","Container":"nginx","ID":"ed37317fbf42","MemPerc":"0.24%","MemUsage":"2.352MiB / 982.5MiB","Name":"nginx","NetIO":"539kB / 606kB","PIDs":"2"} -``` - -Running `docker stats` with customized format on all (running and stopped) containers. - -```console -$ docker stats --all --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}" fervent_panini 5acfcb1b4fd1 humble_visvesvaraya big_heisenberg - -CONTAINER CPU % MEM USAGE / LIMIT -fervent_panini 0.00% 56KiB / 15.57GiB -5acfcb1b4fd1 0.07% 32.86MiB / 15.57GiB -humble_visvesvaraya 0.00% 0B / 0B -big_heisenberg 0.00% 0B / 0B -``` - -`humble_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 -``` - -### Format the output (--format) - -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: - -```console -$ 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: - -```console -$ 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}}" - diff --git a/docs/reference/commandline/stop.md b/docs/reference/commandline/stop.md index d46148356b..16934813c5 100644 --- a/docs/reference/commandline/stop.md +++ b/docs/reference/commandline/stop.md @@ -1,4 +1,4 @@ -# stop +# docker stop Stop one or more running containers @@ -17,15 +17,3 @@ Stop one or more running containers -## Description - -The main process inside the container will receive `SIGTERM`, and after a grace -period, `SIGKILL`. The first signal can be changed with the `STOPSIGNAL` -instruction in the container's Dockerfile, or the `--stop-signal` option to -`docker run`. - -## Examples - -```console -$ docker stop my_container -``` diff --git a/docs/reference/commandline/system_events.md b/docs/reference/commandline/system_events.md index ec5c83cf19..d65605e349 100644 --- a/docs/reference/commandline/system_events.md +++ b/docs/reference/commandline/system_events.md @@ -1,4 +1,4 @@ -# system events +# events Get real time events from the server @@ -13,7 +13,7 @@ Get real time events from the server |:---------------------------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`-f`](#filter), [`--filter`](#filter) | `filter` | | Filter output based on conditions provided | | [`--format`](#format) | `string` | | Format output using a custom template:
'json': Print in JSON format
'TEMPLATE': Print output using the given Go template.
Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | -| `--since` | `string` | | Show all events created since timestamp | +| [`--since`](#since) | `string` | | Show all events created since timestamp | | `--until` | `string` | | Stream events until this timestamp | @@ -21,8 +21,13 @@ Get real time events from the server ## Description -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 @@ -72,9 +77,9 @@ Docker images report the following events: Docker plugins report the following events: -- `install` - `enable` - `disable` +- `install` - `remove` #### Volumes @@ -82,9 +87,9 @@ Docker plugins report the following events: Docker volumes report the following events: - `create` +- `destroy` - `mount` - `unmount` -- `destroy` #### Networks @@ -92,8 +97,9 @@ Docker networks report the following events: - `create` - `connect` -- `disconnect` - `destroy` +- `disconnect` +- `remove` #### Daemons @@ -101,9 +107,41 @@ 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 +#### Limit events by time (--since, --until) The `--since` and `--until` parameters can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed @@ -118,31 +156,48 @@ 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 (--filter) 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 logical `OR`; for example, +Using the same filter multiple times is interpreted as a logical `OR`; for example, `--filter container=588a23dac085 --filter container=a8f7720b8c22` displays events for container `588a23dac085` or container `a8f7720b8c22`. -Using multiple filters will be handled as a logical `AND`; for example, +Using multiple filters is interpreted as a logical `AND`; for example, `--filter container=588a23dac085 --filter event=start` displays events for container `588a23dac085` and where the event type is `start`. 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 the output (--format) + +If you specify a format (`--format`), the given template is executed +instead of the default format. Go's [text/template](https://pkg.go.dev/text/template) +package describes all the details of the format. + +If a format is set to `{{json .}}`, events are streamed in the JSON Lines format. +For information about JSON Lines, see . ## Examples @@ -153,7 +208,7 @@ You'll need two shells for this example. **Shell 1: Listening for events:** ```console -$ docker system events +$ docker events ``` **Shell 2: Start and Stop containers:** @@ -176,7 +231,7 @@ $ docker stop test 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 @@ -184,8 +239,7 @@ You can filter the output by an absolute timestamp or relative time on the host machine, using the following different time formats: ```console -$ 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) @@ -195,8 +249,7 @@ $ docker system events --since 1483283804 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) @@ -206,8 +259,7 @@ $ docker system events --since '2017-01-05' 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) @@ -217,8 +269,7 @@ $ docker system events --since '2013-09-03T15:49:29' 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) @@ -227,6 +278,12 @@ $ docker system events --since '10m' 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 @@ -235,12 +292,12 @@ The following commands show several different ways to filter the `docker event` output. ```console -$ 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) @@ -249,14 +306,14 @@ $ docker system events --filter 'image=alpine' 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) @@ -264,55 +321,74 @@ $ docker system events --filter 'container=test' --filter 'container=d9cdb1525ea 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:22.04 ) -2014-05-10T17:42:14.999999999Z07:00 container stop 4386fb97867d (image=ubuntu:22.04 ) +2014-09-03T15:49:29.999999999Z07:00 container die 4386fb97867d (image=ubuntu:22.04) +2014-05-10T17:42:14.999999999Z07:00 container stop 4386fb97867d (image=ubuntu:22.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 (--format) - -If you specify a format (`--format`), the given template is executed -instead of the default format. Go's [text/template](https://pkg.go.dev/text/template) -package describes all the details of the format. +### Format the output ```console -$ 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 @@ -324,11 +400,11 @@ Type=container Status=destroy ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299 #### Format as JSON -If a format is set to `{{json .}}`, events are streamed in the JSON Lines format. -For information about JSON Lines, see . +To list events in JSON format, use the `json` directive, which is the same +`--format '{{ json . }}`. ```console -$ docker system events --format '{{json .}}' +$ docker events --format json {"status":"create","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. {"status":"attach","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. diff --git a/docs/reference/commandline/system_info.md b/docs/reference/commandline/system_info.md index e85ace3382..48fb3597d5 100644 --- a/docs/reference/commandline/system_info.md +++ b/docs/reference/commandline/system_info.md @@ -1,4 +1,4 @@ -# system info +# info Display system-wide information @@ -9,10 +9,169 @@ Display system-wide information ### Options -| Name | Type | Default | Description | -|:-----------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `-f`, `--format` | `string` | | Format output using a custom template:
'json': Print in JSON format
'TEMPLATE': Print output using the given Go template.
Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | +| Name | Type | Default | Description | +|:---------------------------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [`-f`](#format), [`--format`](#format) | `string` | | Format output using a custom template:
'json': Print in JSON format
'TEMPLATE': Print output using the given Go template.
Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates | +## Description + +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](https://pkg.go.dev/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. + +## Examples + +### Show output + +The example below shows the output for a daemon running on Ubuntu Linux, +using the `overlay2` storage driver. As can be seen in the output, additional +information about the `overlay2` storage driver is shown: + +```console +$ docker info + +Client: Docker Engine - Community + Version: 24.0.0 + Context: default + Debug Mode: false + Plugins: + buildx: Docker Buildx (Docker Inc.) + Version: v0.10.4 + Path: /usr/libexec/docker/cli-plugins/docker-buildx + compose: Docker Compose (Docker Inc.) + Version: v2.17.2 + Path: /usr/libexec/docker/cli-plugins/docker-compose + +Server: + Containers: 14 + Running: 3 + Paused: 1 + Stopped: 10 + Images: 52 + Server Version: 23.0.3 + Storage Driver: overlay2 + Backing Filesystem: extfs + Supports d_type: true + Using metacopy: false + Native Overlay Diff: true + userxattr: false + Logging Driver: json-file + Cgroup Driver: systemd + Cgroup Version: 2 + Plugins: + Volume: local + Network: bridge host ipvlan macvlan null overlay + Log: awslogs fluentd gcplogs gelf journald json-file local splunk syslog + CDI spec directories: + /etc/cdi + /var/run/cdi + Swarm: inactive + Runtimes: io.containerd.runc.v2 runc + Default Runtime: runc + Init Binary: docker-init + containerd version: 2806fc1057397dbaeefbea0e4e17bddfbd388f38 + runc version: v1.1.5-0-gf19387a + init version: de40ad0 + Security Options: + apparmor + seccomp + Profile: builtin + cgroupns + Kernel Version: 5.15.0-25-generic + Operating System: Ubuntu 22.04 LTS + OSType: linux + Architecture: x86_64 + CPUs: 1 + Total Memory: 991.7 MiB + Name: ip-172-30-0-91.ec2.internal + ID: 4cee4408-10d2-4e17-891c-a41736ac4536 + Docker Root Dir: /var/lib/docker + Debug Mode: false + Username: gordontheturtle + Experimental: false + Insecure Registries: + myinsecurehost:5000 + 127.0.0.0/8 + Live Restore Enabled: false +``` + +### Format the output (--format) + +You can also specify the output format: + +```console +$ docker info --format '{{json .}}' + +{"ID":"4cee4408-10d2-4e17-891c-a41736ac4536","Containers":14, ...} +``` + +### Run `docker info` on Windows + +Here is a sample output for a daemon running on Windows Server: + +```console +C:\> docker info + +Client: Docker Engine - Community + Version: 24.0.0 + Context: default + Debug Mode: false + Plugins: + buildx: Docker Buildx (Docker Inc.) + Version: v0.10.4 + Path: C:\Program Files\Docker\cli-plugins\docker-buildx.exe + compose: Docker Compose (Docker Inc.) + Version: v2.17.2 + Path: C:\Program Files\Docker\cli-plugins\docker-compose.exe + +Server: + Containers: 1 + Running: 0 + Paused: 0 + Stopped: 1 + Images: 17 + Server Version: 23.0.3 + Storage Driver: windowsfilter + Logging Driver: json-file + Plugins: + Volume: local + Network: ics internal l2bridge l2tunnel nat null overlay private transparent + Log: awslogs etwlogs fluentd gcplogs gelf json-file local splunk syslog + Swarm: inactive + Default Isolation: process + Kernel Version: 10.0 20348 (20348.1.amd64fre.fe_release.210507-1500) + Operating System: Microsoft Windows Server Version 21H2 (OS Build 20348.707) + OSType: windows + Architecture: x86_64 + CPUs: 8 + Total Memory: 3.999 GiB + Name: WIN-V0V70C0LU5P + ID: 2880d38d-464e-4d01-91bd-c76f33ba3981 + Docker Root Dir: C:\ProgramData\docker + Debug Mode: false + Experimental: true + Insecure Registries: + myregistry:5000 + 127.0.0.0/8 + Registry Mirrors: + http://192.168.1.2/ + http://registry-mirror.example.com:5000/ + Live Restore Enabled: false +``` diff --git a/docs/reference/commandline/tag.md b/docs/reference/commandline/tag.md index d9359f62ef..4e980570a1 100644 --- a/docs/reference/commandline/tag.md +++ b/docs/reference/commandline/tag.md @@ -1,4 +1,4 @@ -# tag +# docker tag Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE @@ -10,78 +10,3 @@ Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE -## Description - -A full image name has the following format and components: - -`[HOST[:PORT_NUMBER]/]PATH` - -- `HOST`: The optional registry hostname specifies where the image is located. - The hostname must comply with standard DNS rules, but may not contain - underscores. If you don't specify a hostname, the command uses Docker's public - registry at `registry-1.docker.io` by default. Note that `docker.io` is the - canonical reference for Docker's public registry. -- `PORT_NUMBER`: If a hostname is present, it may optionally be followed by a - registry port number in the format `:8080`. -- `PATH`: The path consists of slash-separated components. Each - component may contain lowercase letters, digits and separators. A separator is - defined as a period, one or two underscores, or one or more hyphens. A component - may not start or end with a separator. While the - [OCI Distribution Specification](https://github.com/opencontainers/distribution-spec) - supports more than two slash-separated components, most registries only support - two slash-separated components. For Docker's public registry, the path format is - as follows: - - `[NAMESPACE/]REPOSITORY`: The first, optional component is typically a - user's or an organization's namespace. The second, mandatory component is the - repository name. When the namespace is not present, Docker uses `library` - as the default namespace. - -After the image name, the optional `TAG` is a custom, human-readable manifest -identifier that's typically a specific version or variant of an image. The tag -must be valid ASCII and can contain lowercase and uppercase letters, digits, -underscores, periods, and hyphens. It can't start with a period or hyphen and -must be no longer than 128 characters. If you don't specify a tag, the command uses `latest` by default. - -You can group your images together using names and tags, and then -[push](https://docs.docker.com/engine/reference/commandline/push) them to a -registry. - -## Examples - -### Tag an image referenced by ID - -To tag a local image with ID `0e5574283393` as `fedora/httpd` with the tag -`version1.0`: - -```console -$ docker tag 0e5574283393 fedora/httpd:version1.0 -``` - -### Tag an image referenced by Name - -To tag a local image `httpd` as `fedora/httpd` with the tag `version1.0`: - -```console -$ docker tag httpd fedora/httpd:version1.0 -``` - -Note that since the tag name isn't 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 the name `httpd` and the tag `test` as `fedora/httpd` -with the tag `version1.0.test`: - -```console -$ docker tag httpd:test fedora/httpd:version1.0.test -``` - -### Tag an image for a private registry - -To push an image to a private registry and not the public Docker registry you -must include the registry hostname and port (if needed). - -```console -$ docker tag 0e5574283393 myregistryhost:5000/fedora/httpd:version1.0 -``` diff --git a/docs/reference/commandline/top.md b/docs/reference/commandline/top.md index 7974577c69..b35f492031 100644 --- a/docs/reference/commandline/top.md +++ b/docs/reference/commandline/top.md @@ -1,4 +1,4 @@ -# top +# docker top Display the running processes of a container @@ -9,3 +9,4 @@ Display the running processes of a container + diff --git a/docs/reference/commandline/unpause.md b/docs/reference/commandline/unpause.md index a5165812cc..f8d69ef879 100644 --- a/docs/reference/commandline/unpause.md +++ b/docs/reference/commandline/unpause.md @@ -1,4 +1,4 @@ -# unpause +# docker unpause Unpause all processes within one or more containers @@ -10,22 +10,3 @@ Unpause all processes within one or more containers -## Description - -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. - -## Examples - -```console -$ docker unpause my_container -my_container -``` - -## Related commands - -* [pause](pause.md) diff --git a/docs/reference/commandline/update.md b/docs/reference/commandline/update.md index a2dbcd7804..60557bdbfb 100644 --- a/docs/reference/commandline/update.md +++ b/docs/reference/commandline/update.md @@ -1,4 +1,4 @@ -## update +# docker update Update configuration of one or more containers @@ -9,116 +9,23 @@ Update configuration of one or more containers ### Options -| Name | Type | Default | Description | -|:---------------------------------------------------|:----------|:--------|:-----------------------------------------------------------------------------| -| `--blkio-weight` | `uint16` | `0` | Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) | -| `--cpu-period` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) period | -| `--cpu-quota` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) quota | -| `--cpu-rt-period` | `int64` | `0` | Limit the CPU real-time period in microseconds | -| `--cpu-rt-runtime` | `int64` | `0` | Limit the CPU real-time runtime in microseconds | -| [`-c`](#cpu-shares), [`--cpu-shares`](#cpu-shares) | `int64` | `0` | CPU shares (relative weight) | -| `--cpus` | `decimal` | | Number of CPUs | -| `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) | -| `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) | -| [`-m`](#memory), [`--memory`](#memory) | `bytes` | `0` | Memory limit | -| `--memory-reservation` | `bytes` | `0` | Memory soft limit | -| `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: -1 to enable unlimited swap | -| `--pids-limit` | `int64` | `0` | Tune container pids limit (set -1 for unlimited) | -| [`--restart`](#restart) | `string` | | Restart policy to apply when a container exits | +| Name | Type | Default | Description | +|:-----------------------|:----------|:--------|:-----------------------------------------------------------------------------| +| `--blkio-weight` | `uint16` | `0` | Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) | +| `--cpu-period` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) period | +| `--cpu-quota` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) quota | +| `--cpu-rt-period` | `int64` | `0` | Limit the CPU real-time period in microseconds | +| `--cpu-rt-runtime` | `int64` | `0` | Limit the CPU real-time runtime in microseconds | +| `-c`, `--cpu-shares` | `int64` | `0` | CPU shares (relative weight) | +| `--cpus` | `decimal` | | Number of CPUs | +| `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) | +| `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) | +| `-m`, `--memory` | `bytes` | `0` | Memory limit | +| `--memory-reservation` | `bytes` | `0` | Memory soft limit | +| `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: -1 to enable unlimited swap | +| `--pids-limit` | `int64` | `0` | Tune container pids limit (set -1 for unlimited) | +| `--restart` | `string` | | Restart policy to apply when a container exits | -## Description - -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 } - -## Examples - -The following sections illustrate ways to use this command. - -### Update a container's cpu-shares (--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: - -```console -$ docker update --cpu-shares 512 abebf7571666 -``` - -### Update a container with cpu-shares and memory (-m, --memory) - -To update multiple resource configurations for multiple containers: - -```console -$ docker update --cpu-shares 512 -m 300M abebf7571666 hopeful_morse -``` - -### Update a container's kernel memory constraints (--kernel-memory) - -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.10. - -For example, if you started a container with this command: - -```console -$ docker run -dit --name test --kernel-memory 50M ubuntu bash -``` - -You can update kernel memory while the container is running: - -```console -$ docker update --kernel-memory 80M test -``` - -If you started a container without kernel memory initialized: - -```console -$ 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 (--restart) - -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: - -```console -$ 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. diff --git a/docs/reference/commandline/wait.md b/docs/reference/commandline/wait.md index 6cec6b2a02..79dbf1507f 100644 --- a/docs/reference/commandline/wait.md +++ b/docs/reference/commandline/wait.md @@ -1,4 +1,4 @@ -# wait +# docker wait Block until one or more containers stop, then print their exit codes @@ -10,37 +10,3 @@ Block until one or more containers stop, then print their exit codes -> **Note** -> -> `docker wait` returns `0` when run against a container which had already -> exited before the `docker wait` command was run. - -## Examples - -Start a container in the background. - -```console -$ docker run -dit --name=my_container ubuntu bash -``` - -Run `docker wait`, which should block until the container exits. - -```console -$ docker wait my_container -``` - -In another terminal, stop the first container. The `docker wait` command above -returns the exit code. - -```console -$ docker stop my_container -``` - -This is the same `docker wait` command from above, but it now exits, returning -`0`. - -```console -$ docker wait my_container - -0 -``` diff --git a/docs/reference/run.md b/docs/reference/run.md index 9f6151b8f7..41fd2c0dc2 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -114,13 +114,13 @@ $ docker attach 0246aa4d1448 For more information about `docker run` flags related to foreground and background modes, see: -- [`docker run --detach`](commandline/run.md#detach): run container in background -- [`docker run --attach`](commandline/run.md#attach): attach to `stdin`, `stdout`, and `stderr` -- [`docker run --tty`](commandline/run.md#tty): allocate a pseudo-tty -- [`docker run --interactive`](commandline/run.md#interactive): keep `stdin` open even if not attached +- [`docker run --detach`](commandline/container_run.md#detach): run container in background +- [`docker run --attach`](commandline/container_run.md#attach): attach to `stdin`, `stdout`, and `stderr` +- [`docker run --tty`](commandline/container_run.md#tty): allocate a pseudo-tty +- [`docker run --interactive`](commandline/container_run.md#interactive): keep `stdin` open even if not attached For more information about re-attaching to a background container, see -[`docker attach`](commandline/attach.md). +[`docker attach`](commandline/container_attach.md). ## Container identification @@ -135,7 +135,7 @@ You can identify a container in three ways: The UUID identifier is a random ID assigned to the container by the daemon. The daemon generates a random string name for containers automatically. You can -also defined a custom name using [the `--name` flag](./commandline/run.md#name). +also defined a custom name using [the `--name` flag](./commandline/container_run.md#name). Defining a `name` can be a handy way to add meaning to a container. If you specify a `name`, you can use it when referring to the container in a user-defined network. This works for both background and foreground Docker