Guest24897
/
DockerCLI
mirror of https://github.com/docker/cli.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #4712 from dvdksn/docs-tier1-fresshness-q4 

docs: editorial improvements, typo fixes
This commit is contained in:
Sebastiaan van Stijn 2023-12-19 19:23:32 +01:00 committed by GitHub
parent a2c949212a 6fd4cff1f7
commit 5ba998d6b4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
36 changed files with 596 additions and 620 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

79
docs/reference/commandline/attach.md
View File

@ -22,13 +22,14 @@ Attach local standard input, output, and error streams to a running container
Use `docker attach` to attach your terminal's standard input, output, and error 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 (or any combination of the three) to a running container using the container's
ID or name. This allows you to view its ongoing output or to control it ID or name. This lets you view its output or control it interactively, as
interactively, as though the commands were running directly in your terminal. though the commands were running directly in your terminal.
> **Note:** > **Note**
> The `attach` command will display the output of the `ENTRYPOINT/CMD` process. This >
> can appear as if the attach command is hung when in fact the process may simply > The `attach` command displays the output of the container's `ENTRYPOINT` and
> not be interacting with the terminal at that time. > `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, You can attach to the same contained process multiple times simultaneously,
from different sessions on the Docker host. from different sessions on the Docker host.
@ -38,44 +39,41 @@ 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 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. a container and leave it running using the `CTRL-p CTRL-q` key sequence.
> **Note:** > **Note**
>
> A process running as PID 1 inside a container is treated specially by > 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 > Linux: it ignores any signal with the default action. So, the process
> will not terminate on `SIGINT` or `SIGTERM` unless it is coded to do > doesn't terminate on `SIGINT` or `SIGTERM` unless it's coded to do so.
> so.
It is forbidden to redirect the standard input of a `docker attach` command You can't redirect the standard input of a `docker attach` command while
while attaching to a TTY-enabled container (using the `-i` and `-t` options). 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 While a client is connected to container's `stdio` using `docker attach`,
uses a ~1MB memory buffer to maximize the throughput of the application. 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 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 this impacts the output process' writing speed. This is similar to other
applications like SSH. Because of this, it is not recommended to run applications like SSH. Because of this, it isn't recommended to run
performance critical applications that generate a lot of output in the performance-critical applications that generate a lot of output in the
foreground over a slow client connection. Instead, users should use the foreground over a slow client connection. Instead, use the `docker logs`
`docker logs` command to get access to the logs. command to get access to the logs.
## Examples ## Examples
### Attach to and detach from a running container ### Attach to and detach from a running container
The following example starts an ubuntu container running `top` in detached mode, The following example starts an Alpine container running `top` in detached mode,
then attaches to the container; then attaches to the container;
```console ```console
$ docker run -d --name topdemo ubuntu:22.04 /usr/bin/top -b $ docker run -d --name topdemo alpine top -b
$ docker attach topdemo $ docker attach topdemo
top - 12:27:44 up 3 days, 21:54, 0 users, load average: 0.00, 0.00, 0.00 Mem: 2395856K used, 5638884K free, 2328K shrd, 61904K buff, 1524264K cached
Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie CPU: 0% usr 0% sys 0% nic 99% idle 0% io 0% irq 0% sirq
%Cpu(s): 0.1 us, 0.1 sy, 0.0 ni, 99.8 id, 0.0 wa, 0.0 hi, 0.0 si, 0.0 st Load average: 0.15 0.06 0.01 1/567 6
MiB Mem : 3934.3 total, 770.1 free, 674.2 used, 2490.1 buff/cache PID PPID USER STAT VSZ %VSZ CPU %CPU COMMAND
MiB Swap: 1024.0 total, 839.3 free, 184.7 used. 2814.0 avail Mem 1 0 root R 1700 0% 3 0% top -b
PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND
1 root 20 0 7180 2896 2568 R 0.0 0.1 0:00.02 top
``` ```
As the container was started without the `-i`, and `-t` options, signals are As the container was started without the `-i`, and `-t` options, signals are
@ -85,14 +83,15 @@ container:
```console ```console
<...> <...>
PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND PID PPID USER STAT VSZ %VSZ CPU %CPU COMMAND
1 root 20 0 7180 2896 2568 R 0.0 0.1 0:00.02 top^P^Q 1 0 root R 1700 0% 7 0% top -b
^P^Q
^C ^C
$ docker ps -a --filter name=topdemo $ docker ps -a --filter name=topdemo
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
4cf0d0ebb079 ubuntu:22.04 "/usr/bin/top -b" About a minute ago Exited (0) About a minute ago topdemo 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; Repeating the example above, but this time with the `-i` and `-t` options set;
@ -109,19 +108,17 @@ with `docker ps` shows that the container is still running in the background:
```console ```console
$ docker attach topdemo2 $ docker attach topdemo2
top - 12:44:32 up 3 days, 22:11, 0 users, load average: 0.00, 0.00, 0.00 Mem: 2405344K used, 5629396K free, 2512K shrd, 65100K buff, 1524952K cached
Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie CPU: 0% usr 0% sys 0% nic 99% idle 0% io 0% irq 0% sirq
%Cpu(s): 50.0 us, 0.0 sy, 0.0 ni, 50.0 id, 0.0 wa, 0.0 hi, 0.0 si, 0.0 st Load average: 0.12 0.12 0.05 1/594 6
MiB Mem : 3934.3 total, 770.6 free, 672.4 used, 2491.4 buff/cache PID PPID USER STAT VSZ %VSZ CPU %CPU COMMAND
MiB Swap: 1024.0 total, 839.3 free, 184.7 used. 2815.8 avail Mem 1 0 root R 1700 0% 3 0% top -b
read escape sequence
PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND
1 root 20 0 7180 2776 2452 R 0.0 0.1 0:00.02 topread escape sequence
$ docker ps -a --filter name=topdemo2 $ docker ps -a --filter name=topdemo2
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
b1661dce0fc2 ubuntu:22.04 "/usr/bin/top -b" 2 minutes ago Up 2 minutes topdemo2 fde88b83c2c2 alpine "top -b" 22 seconds ago Up 21 seconds topdemo2
``` ```
### Get the exit code of the container's command ### Get the exit code of the container's command

65
docs/reference/commandline/build.md
View File

@ -60,11 +60,11 @@ pre-packaged tarball contexts and plain text files.
When the `URL` parameter points to the location of a Git repository, the 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 acts as the build context. The system recursively fetches the
repository and its submodules. The commit history is not preserved. A repository and its submodules. The commit history isn't preserved. A
repository is first pulled into a temporary directory on your local host. After repository is first pulled into a temporary directory on your local host. After
that succeeds, the directory is sent to the Docker daemon as the context. that succeeds, the directory is sent to the Docker daemon as the context.
Local copy gives you the ability to access private repositories using local Local copy gives you the ability to access private repositories using local
user credentials, VPN's, and so forth. user credentials, VPNs, and so forth.
> **Note** > **Note**
> >
@ -100,18 +100,18 @@ contexts:
### Tarball contexts ### Tarball contexts
If you pass an URL to a remote tarball, the URL itself is sent to the daemon: If you pass a URL to a remote tarball, the URL itself is sent to the daemon:
```console ```console
$ docker build http://server/context.tar.gz $ docker build http://server/context.tar.gz
``` ```
The download operation will be performed on the host the Docker daemon is The download operation will be performed on the host the Docker daemon is
running on, which is not necessarily the same host from which the build command running on, which isn't necessarily the same host from which the build command
is being issued. The Docker daemon will fetch `context.tar.gz` and use it as the is being issued. The Docker daemon will fetch `context.tar.gz` and use it as the
build context. Tarball contexts must be tar archives conforming to the standard 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', `tar` Unix format and can be compressed with any one of the `xz`, `bzip2`,
'gzip' or 'identity' (no compression) formats. `gzip` or `identity` (no compression) formats.
### Text files ### Text files
@ -122,7 +122,7 @@ Instead of specifying a context, you can pass a single `Dockerfile` in the
$ docker build - < Dockerfile $ docker build - < Dockerfile
``` ```
With Powershell on Windows, you can run: With PowerShell on Windows, you can run:
```powershell ```powershell
Get-Content Dockerfile | docker build - Get-Content Dockerfile | docker build -
@ -136,8 +136,7 @@ By default the `docker build` command will look for a `Dockerfile` at the root
of the build context. The `-f`, `--file`, option lets you specify the path to of the build context. The `-f`, `--file`, option lets you specify the path to
an alternative file to use instead. This is useful in cases where the same set an alternative file to use instead. This is useful in cases where the same set
of files are used for multiple builds. The path must be to a file within the of files are used for multiple builds. The path must be to a file within the
build context. If a relative path is specified then it is interpreted as build context. Relative path are interpreted as relative to the root of the context.
relative to the root of the context.
In most cases, it's best to put each Dockerfile in an empty directory. Then, 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 add to that directory only the files needed for building the Dockerfile. To
@ -152,8 +151,7 @@ running at the time the build is cancelled, the pull is cancelled as well.
## Return code ## Return code
On a successful build, a return code of success `0` will be returned. When the Successful builds return exit code `0`. Failed builds return a non-zero exit code.
build fails, a non-zero failure code will be returned.
There should be informational output of the reason for failure output to There should be informational output of the reason for failure output to
`STDERR`: `STDERR`:
@ -214,15 +212,15 @@ local directory get `tar`d and sent to the Docker daemon. The `PATH` specifies
where to find the files for the "context" of the build on the Docker daemon. 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 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 parsing of the Dockerfile happens at the client side (where you're running
`docker build`). That means that *all* the files at `PATH` get sent, not just `docker build`). That means that all the files at `PATH` get sent, not just
the ones listed to [*ADD*](https://docs.docker.com/engine/reference/builder/#add) the ones listed to [`ADD`](https://docs.docker.com/engine/reference/builder/#add)
in the Dockerfile. in the Dockerfile.
The transfer of context from the local machine to the Docker daemon is what the 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. `docker` client means when you see the "Sending build context" message.
If you wish to keep the intermediate containers after the build is complete, If you wish to keep the intermediate containers after the build is complete,
you must use `--rm=false`. This does not affect the build cache. you must use `--rm=false`. This doesn't affect the build cache.
### Build with URL ### Build with URL
@ -252,7 +250,7 @@ Successfully built 377c409b35e4
This sends the URL `http://server/ctx.tar.gz` to the Docker daemon, which This sends the URL `http://server/ctx.tar.gz` to the Docker daemon, which
downloads and extracts the referenced tarball. The `-f ctx/Dockerfile` downloads and extracts the referenced tarball. The `-f ctx/Dockerfile`
parameter specifies a path inside `ctx.tar.gz` to the `Dockerfile` that is used parameter specifies a path inside `ctx.tar.gz` to the `Dockerfile` used
to build the image. Any `ADD` commands in that `Dockerfile` that refers to local to build the image. Any `ADD` commands in that `Dockerfile` that refers to local
paths must be relative to the root of the contents inside `ctx.tar.gz`. In the 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 example above, the tarball contains a directory `ctx/`, so the `ADD
@ -274,7 +272,7 @@ $ docker build - < context.tar.gz
``` ```
This will build an image for a compressed context read from `STDIN`. Supported This will build an image for a compressed context read from `STDIN`. Supported
formats are: bzip2, gzip and xz. formats are: `bzip2`, `gzip` and `xz`.
### Use a .dockerignore file ### Use a .dockerignore file
@ -314,7 +312,6 @@ found, the `.dockerignore` file is used if present. Using a Dockerfile based
`.dockerignore` is useful if a project contains multiple Dockerfiles that expect `.dockerignore` is useful if a project contains multiple Dockerfiles that expect
to ignore different sets of files. to ignore different sets of files.
### <a name="tag"></a> Tag an image (-t, --tag) ### <a name="tag"></a> Tag an image (-t, --tag)
```console ```console
@ -375,12 +372,12 @@ the command line.
> **Note** > **Note**
> >
> `docker build` returns a `no such file or directory` error if the > `docker build` returns a `no such file or directory` error if the
> file or directory does not exist in the uploaded context. This may > 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 is > 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 > elsewhere on the Host system. The context is limited to the current
> directory (and its children) for security reasons, and to ensure > directory (and its children) for security reasons, and to ensure
> repeatable builds on remote Docker hosts. This is also the reason why > repeatable builds on remote Docker hosts. This is also the reason why
> `ADD ../file` does not work. > `ADD ../file` doesn't work.
### <a name="cgroup-parent"></a> Use a custom parent cgroup (--cgroup-parent) ### <a name="cgroup-parent"></a> Use a custom parent cgroup (--cgroup-parent)
@ -396,7 +393,7 @@ container to be started using those [`--ulimit` flag values](run.md#ulimit).
You can use `ENV` instructions in a Dockerfile to define variable You can use `ENV` instructions in a Dockerfile to define variable
values. These values persist in the built image. However, often values. These values persist in the built image. However, often
persistence is not what you want. Users want to specify variables differently persistence isn't what you want. Users want to specify variables differently
depending on which host they build an image on. depending on which host they build an image on.
A good example is `http_proxy` or source versions for pulling intermediate A good example is `http_proxy` or source versions for pulling intermediate
@ -410,7 +407,7 @@ $ docker build --build-arg HTTP_PROXY=http://10.20.30.2:1234 --build-arg FTP_PRO
This flag allows you to pass the build-time variables that are This flag allows you to pass the build-time variables that are
accessed like regular environment variables in the `RUN` instruction of the accessed like regular environment variables in the `RUN` instruction of the
Dockerfile. Also, these values don't persist in the intermediate or final images Dockerfile. Also, these values don't persist in the intermediate or final images
like `ENV` values do. You must add `--build-arg` for each build argument. like `ENV` values do. You must add `--build-arg` for each build argument.
Using this flag will not alter the output you see when the `ARG` lines from the Using this flag will not alter the output you see when the `ARG` lines from the
Dockerfile are echoed during the build process. Dockerfile are echoed during the build process.
@ -638,15 +635,14 @@ $ docker build --cache-from myname/myapp .
#### Overview #### Overview
Once the image is built, squash the new layers into a new image with a single Once the image is built, squash the new layers into a new image with a single
new layer. Squashing does not destroy any existing image, rather it creates a new 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 image with the content of the squashed layers. This effectively makes it look
like all `Dockerfile` commands were created with a single layer. The build like all `Dockerfile` commands were created with a single layer. The build
cache is preserved with this method. cache is preserved with this method.
The `--squash` option is an experimental feature, and should not be considered The `--squash` option is an experimental feature, and shouldn't be considered
stable. stable.
Squashing layers can be beneficial if your Dockerfile produces multiple layers Squashing layers can be beneficial if your Dockerfile produces multiple layers
modifying the same files, for example, files that are created in one step, and modifying the same files, for example, files that are created in one step, and
removed in another step. For other use-cases, squashing images may actually have removed in another step. For other use-cases, squashing images may actually have
@ -656,15 +652,14 @@ images (saving space).
For most use cases, multi-stage builds are a better alternative, as they give more 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 fine-grained control over your build, and can take advantage of future
optimizations in the builder. Refer to the [use multi-stage builds](https://docs.docker.com/develop/develop-images/multistage-build/) optimizations in the builder. Refer to the [Multi-stage builds](https://docs.docker.com/build/building/multi-stage/)
section in the userguide for more information. section for more information.
#### Known limitations #### Known limitations
The `--squash` option has a number of known limitations: The `--squash` option has a number of known limitations:
- When squashing layers, the resulting image cannot take advantage of layer - When squashing layers, the resulting image can't take advantage of layer
sharing with other images, and may use significantly more space. Sharing the sharing with other images, and may use significantly more space. Sharing the
base image is still supported. base image is still supported.
- When using this option you may see significantly more space used due to - When using this option you may see significantly more space used due to
@ -672,8 +667,8 @@ The `--squash` option has a number of known limitations:
layers intact, and one for the squashed version. layers intact, and one for the squashed version.
- While squashing layers may produce smaller images, it may have a negative - While squashing layers may produce smaller images, it may have a negative
impact on performance, as a single layer takes longer to extract, and impact on performance, as a single layer takes longer to extract, and
downloading a single layer cannot be parallelized. downloading a single layer can't be parallelized.
- When attempting to squash an image that does not make changes to the - When attempting to squash an image that doesn't make changes to the
filesystem (for example, the Dockerfile only contains `ENV` instructions), filesystem (for example, the Dockerfile only contains `ENV` instructions),
the squash step will fail (see [issue #33823](https://github.com/moby/moby/issues/33823)). the squash step will fail (see [issue #33823](https://github.com/moby/moby/issues/33823)).
@ -686,7 +681,7 @@ the Docker daemon or setting `experimental: true` in the `daemon.json` configura
file. file.
By default, experimental mode is disabled. To see the current configuration of By default, experimental mode is disabled. To see the current configuration of
the docker daemon, use the `docker version` command and check the `Experimental` the Docker daemon, use the `docker version` command and check the `Experimental`
line in the `Engine` section: line in the `Engine` section:
```console ```console
@ -711,10 +706,10 @@ Server: Docker Engine - Community
[...] [...]
``` ```
To enable experimental mode, users need to restart the docker daemon with the To enable experimental mode, users need to restart the Docker daemon with the
experimental flag enabled. experimental flag enabled.
#### Enable Docker experimental #### Enable experimental features
To enable experimental features, you need to start the Docker daemon with To enable experimental features, you need to start the Docker daemon with
`--experimental` flag. You can also enable the daemon flag via `--experimental` flag. You can also enable the daemon flag via
@ -735,7 +730,7 @@ true
#### Build an image with `--squash` argument #### Build an image with `--squash` argument
The following is an example of docker build with `--squash` argument The following is an example of a build with `--squash` argument
```dockerfile ```dockerfile
FROM busybox FROM busybox

14
docs/reference/commandline/checkpoint.md
View File

@ -18,7 +18,7 @@ Manage checkpoints
## Description ## Description
Checkpoint and Restore is an experimental feature that allows you to freeze a running Checkpoint and Restore is an experimental feature that allows you to freeze a running
container by checkpointing it, which turns its state into a collection of files container by specifying a checkpoint, which turns the container state into a collection of files
on disk. Later, the container can be restored from the point it was frozen. on disk. Later, the container can be restored from the point it was frozen.
This is accomplished using a tool called [CRIU](https://criu.org), which is an This is accomplished using a tool called [CRIU](https://criu.org), which is an
@ -29,7 +29,7 @@ checkpoint and restore in Docker is available in this
### Installing CRIU ### Installing CRIU
If you use a Debian system, you can add the CRIU PPA and install with `apt-get` If you use a Debian system, you can add the CRIU PPA and install with `apt-get`
[from the criu launchpad](https://launchpad.net/~criu/+archive/ubuntu/ppa). [from the CRIU launchpad](https://launchpad.net/~criu/+archive/ubuntu/ppa).
Alternatively, you can [build CRIU from source](https://criu.org/Installation). Alternatively, you can [build CRIU from source](https://criu.org/Installation).
@ -91,17 +91,17 @@ abc0123
``` ```
This process just logs an incrementing counter to stdout. If you run `docker logs` This process just logs an incrementing counter to stdout. If you run `docker logs`
in between running/checkpoint/restoring you should see that the counter in-between running/checkpoint/restoring, you should see that the counter
increases while the process is running, stops while it's checkpointed, and increases while the process is running, stops while it's frozen, and
resumes from the point it left off once you restore. resumes from the point it left off once you restore.
### Known limitations ### Known limitations
seccomp is only supported by CRIU in very up to date kernels. `seccomp` is only supported by CRIU in very up-to-date kernels.
External terminal (i.e. `docker run -t ..`) is not supported at the moment. External terminals (i.e. `docker run -t ..`) aren't supported.
If you try to create a checkpoint for a container with an external terminal, If you try to create a checkpoint for a container with an external terminal,
it would fail: it fails:
```console ```console
$ docker checkpoint create cr checkpoint1 $ docker checkpoint create cr checkpoint1

56
docs/reference/commandline/cli.md
View File

@ -156,7 +156,7 @@ By default, the Docker command line stores its configuration files in a
directory called `.docker` within your `$HOME` directory. directory called `.docker` within your `$HOME` directory.
Docker manages most of the files in the configuration directory Docker manages most of the files in the configuration directory
and you should not modify them. However, you can modify the and you shouldn't modify them. However, you can modify the
`config.json` file to control certain aspects of how the `docker` `config.json` file to control certain aspects of how the `docker`
command behaves. command behaves.
@ -167,7 +167,6 @@ and the `--config` flag are set, the flag takes precedent over the environment
variable. Command line options override environment variables and environment variable. Command line options override environment variables and environment
variables override properties you specify in a `config.json` file. variables override properties you specify in a `config.json` file.
### Change the `.docker` directory ### Change the `.docker` directory
To specify a different directory, use the `DOCKER_CONFIG` To specify a different directory, use the `DOCKER_CONFIG`
@ -201,7 +200,7 @@ By default, configuration file is stored in `~/.docker/config.json`. Refer to th
different location. different location.
> **Warning** > **Warning**
> >
> The configuration file and other files inside the `~/.docker` configuration > The configuration file and other files inside the `~/.docker` configuration
> directory may contain sensitive information, such as authentication information > directory may contain sensitive information, such as authentication information
> for proxies or, depending on your credential store, credentials for your image > for proxies or, depending on your credential store, credentials for your image
@ -210,38 +209,36 @@ different location.
### Customize the default output format for commands ### Customize the default output format for commands
These fields allow you to customize the default output format for some commands These fields lets you customize the default output format for some commands
if no `--format` flag is provided. if no `--format` flag is provided.
| Property | Description | | Property | Description |
|:-----------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `configFormat` | Custom default format for `docker config ls` output. Refer to the [**format the output** section in the `docker config ls` documentation](config_ls.md#format) for a list of supported formatting directives. | | `configFormat` | Custom default format for `docker config ls` output. See [`docker config ls`](config_ls.md#format) for a list of supported formatting directives. |
| `imagesFormat` | Custom default format for `docker images` / `docker image ls` output. Refer to the [**format the output** section in the `docker images` documentation](images.md#format) for a list of supported formatting directives. | | `imagesFormat` | Custom default format for `docker images` / `docker image ls` output. See [`docker images`](images.md#format) for a list of supported formatting directives. |
| `nodesFormat` | Custom default format for `docker node ls` output. Refer to the [**formatting** section in the `docker node ls` documentation](node_ls.md#format) for a list of supported formatting directives. | | `nodesFormat` | Custom default format for `docker node ls` output. See [`docker node ls`](node_ls.md#format) for a list of supported formatting directives. |
| `pluginsFormat` | Custom default format for `docker plugin ls` output. Refer to the [**formatting** section in the `docker plugin ls` documentation](plugin_ls.md#format) for a list of supported formatting directives. | | `pluginsFormat` | Custom default format for `docker plugin ls` output. See [`docker plugin ls`](plugin_ls.md#format) for a list of supported formatting directives. |
| `psFormat` | Custom default format for `docker ps` / `docker container ps` output. Refer to the [**formatting** section in the `docker ps` documentation](ps.md#format) for a list of supported formatting directives. | | `psFormat` | Custom default format for `docker ps` / `docker container ps` output. See [`docker ps`](ps.md#format) for a list of supported formatting directives. |
| `secretFormat` | Custom default format for `docker secret ls` output. Refer to the [**format the output** section in the `docker secret ls` documentation](secret_ls.md#format) for a list of supported formatting directives. | | `secretFormat` | Custom default format for `docker secret ls` output. See [`docker secret ls`](secret_ls.md#format) for a list of supported formatting directives. |
| `serviceInspectFormat` | Custom default format for `docker service inspect` output. Refer to the [**formatting** section in the `docker service inspect` documentation](service_inspect.md#format) for a list of supported formatting directives. | | `serviceInspectFormat` | Custom default format for `docker service inspect` output. See [`docker service inspect`](service_inspect.md#format) for a list of supported formatting directives. |
| `servicesFormat` | Custom default format for `docker service ls` output. Refer to the [**formatting** section in the `docker service ls` documentation](service_ls.md#format) for a list of supported formatting directives. | | `servicesFormat` | Custom default format for `docker service ls` output. See [`docker service ls`](service_ls.md#format) for a list of supported formatting directives. |
| `statsFormat` | Custom default format for `docker stats` output. Refer to the [**formatting** section in the `docker stats` documentation](stats.md#format) for a list of supported formatting directives. | | `statsFormat` | Custom default format for `docker stats` output. See [`docker stats`](stats.md#format) for a list of supported formatting directives. |
### Custom HTTP headers ### Custom HTTP headers
The property `HttpHeaders` specifies a set of headers to include in all messages The property `HttpHeaders` specifies a set of headers to include in all messages
sent from the Docker client to the daemon. Docker does not try to interpret or sent from the Docker client to the daemon. Docker doesn't try to interpret or
understand these headers; it simply puts them into the messages. Docker does understand these headers; it simply puts them into the messages. Docker does
not allow these headers to change any headers it sets for itself. not allow these headers to change any headers it sets for itself.
### Credential store options ### Credential store options
The property `credsStore` specifies an external binary to serve as the default The property `credsStore` specifies an external binary to serve as the default
credential store. When this property is set, `docker login` will attempt to credential store. When this property is set, `docker login` will attempt to
store credentials in the binary specified by `docker-credential-<value>` which store credentials in the binary specified by `docker-credential-<value>` which
is visible on `$PATH`. If this property is not set, credentials will be stored is visible on `$PATH`. If this property isn't set, credentials are stored
in the `auths` property of the config. For more information, see the in the `auths` property of the CLI configuration file. For more information,
[**Credential stores** section in the `docker login` documentation](login.md#credential-stores) see the [**Credential stores** section in the `docker login` documentation](login.md#credential-stores)
The property `credHelpers` specifies a set of credential helpers to use The property `credHelpers` specifies a set of credential helpers to use
preferentially over `credsStore` or `auths` when storing and retrieving preferentially over `credsStore` or `auths` when storing and retrieving
@ -250,14 +247,13 @@ credentials for specific registries. If this property is set, the binary
for a specific registry. For more information, see the for a specific registry. For more information, see the
[**Credential helpers** section in the `docker login` documentation](login.md#credential-helpers) [**Credential helpers** section in the `docker login` documentation](login.md#credential-helpers)
### Automatic proxy configuration for containers ### Automatic proxy configuration for containers
The property `proxies` specifies proxy environment variables to be automatically The property `proxies` specifies proxy environment variables to be automatically
set on containers, and set as `--build-arg` on containers used during `docker build`. set on containers, and set as `--build-arg` on containers used during `docker build`.
A `"default"` set of proxies can be configured, and will be used for any docker A `"default"` set of proxies can be configured, and will be used for any Docker
daemon that the client connects to, or a configuration per host (docker daemon), daemon that the client connects to, or a configuration per host (Docker daemon),
for example, "https://docker-daemon1.example.com". The following properties can for example, `https://docker-daemon1.example.com`. The following properties can
be set for each environment: be set for each environment:
| Property | Description | | Property | Description |
@ -274,11 +270,12 @@ used as proxy settings for the `docker` CLI or the `dockerd` daemon. Refer to th
sections for configuring proxy settings for the cli and daemon. sections for configuring proxy settings for the cli and daemon.
> **Warning** > **Warning**
> >
> Proxy settings may contain sensitive information (for example, if the proxy > Proxy settings may contain sensitive information (for example, if the proxy
> requires authentication). Environment variables are stored as plain text in > requires authentication). Environment variables are stored as plain text in
> the container's configuration, and as such can be inspected through the remote > the container's configuration, and as such can be inspected through the remote
> API or committed to an image when using `docker commit`. > API or committed to an image when using `docker commit`.
{ .warning }
### Default key-sequence to detach from containers ### Default key-sequence to detach from containers
@ -292,7 +289,7 @@ a letter [a-Z], or the `ctrl-` combined with any of the following:
* `@` (at sign) * `@` (at sign)
* `[` (left bracket) * `[` (left bracket)
* `\\` (two backward slashes) * `\\` (two backward slashes)
* `_` (underscore) * `_` (underscore)
* `^` (caret) * `^` (caret)
Your customization applies to all containers started in with your Docker client. Your customization applies to all containers started in with your Docker client.
@ -300,13 +297,12 @@ Users can override your custom or the default key sequence on a per-container
basis. To do this, the user specifies the `--detach-keys` flag with the `docker basis. To do this, the user specifies the `--detach-keys` flag with the `docker
attach`, `docker exec`, `docker run` or `docker start` command. attach`, `docker exec`, `docker run` or `docker start` command.
### CLI Plugin options ### CLI plugin options
The property `plugins` contains settings specific to CLI plugins. The The property `plugins` contains settings specific to CLI plugins. The
key is the plugin name, while the value is a further map of options, key is the plugin name, while the value is a further map of options,
which are specific to that plugin. which are specific to that plugin.
### Sample configuration file ### Sample configuration file
Following is a sample `config.json` file to illustrate the format used for Following is a sample `config.json` file to illustrate the format used for
@ -370,7 +366,7 @@ and require no configuration to enable them.
If using your own notary server and a self-signed certificate or an internal If using your own notary server and a self-signed certificate or an internal
Certificate Authority, you need to place the certificate at Certificate Authority, you need to place the certificate at
`tls/<registry_url>/ca.crt` in your docker config directory. `tls/<registry_url>/ca.crt` in your Docker config directory.
Alternatively you can trust the certificate globally by adding it to your system's Alternatively you can trust the certificate globally by adding it to your system's
list of root Certificate Authorities. list of root Certificate Authorities.

15
docs/reference/commandline/commit.md
View File

@ -22,21 +22,18 @@ Create a new image from a container's changes
## Description ## Description
It can be useful to commit a container's file changes or settings into a new It can be useful to commit a container's file changes or settings into a new
image. This allows you to debug a container by running an interactive shell, or to image. This lets you debug a container by running an interactive shell, or
export a working dataset to another server. Generally, it is better to use export a working dataset to another server.
Dockerfiles to manage your images in a documented and maintainable way.
[Read more about valid image names and tags](tag.md).
The commit operation will not include any data contained in Commits do not include any data contained in mounted volumes.
volumes mounted inside the container.
By default, the container being committed and its processes will be paused By default, the container being committed and its processes will be paused
while the image is committed. This reduces the likelihood of encountering data while the image is committed. This reduces the likelihood of encountering data
corruption during the process of creating the commit. If this behavior is corruption during the process of creating the commit. If this behavior is
undesired, set the `--pause` option to false. undesired, set the `--pause` option to false.
The `--change` option will apply `Dockerfile` instructions to the image that is The `--change` option will apply `Dockerfile` instructions to the image that's
created. Supported `Dockerfile` instructions: created. Supported `Dockerfile` instructions:
`CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`LABEL`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`LABEL`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR`
## Examples ## Examples

3
docs/reference/commandline/config_create.md
View File

@ -21,7 +21,7 @@ For detailed information about using configs, refer to [store configuration data
> **Note** > **Note**
> >
> This is a cluster management command, and must be executed on a swarm > This is a cluster management command, and must be executed on a Swarm
> manager node. To learn about managers and workers, refer to the > manager node. To learn about managers and workers, refer to the
> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
> documentation. > documentation.
@ -88,7 +88,6 @@ $ docker config inspect my_config
] ]
``` ```
## Related commands ## Related commands
* [config inspect](config_inspect.md) * [config inspect](config_inspect.md)

3
docs/reference/commandline/config_inspect.md
View File

@ -27,7 +27,7 @@ For detailed information about using configs, refer to [store configuration data
> **Note** > **Note**
> >
> This is a cluster management command, and must be executed on a swarm > This is a cluster management command, and must be executed on a Swarm
> manager node. To learn about managers and workers, refer to the > manager node. To learn about managers and workers, refer to the
> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
> documentation. > documentation.
@ -86,7 +86,6 @@ $ docker config inspect --format='{{.CreatedAt}}' eo7jnzguqgtpdah3cm5srfb97
2017-03-24 08:15:09.735271783 +0000 UTC 2017-03-24 08:15:09.735271783 +0000 UTC
``` ```
## Related commands ## Related commands
* [config create](config_create.md) * [config create](config_create.md)

4
docs/reference/commandline/config_ls.md
View File

@ -20,13 +20,13 @@ List configs
## Description ## Description
Run this command on a manager node to list the configs in the swarm. Run this command on a manager node to list the configs in the Swarm.
For detailed information about using configs, refer to [store configuration data using Docker Configs](https://docs.docker.com/engine/swarm/configs/). For detailed information about using configs, refer to [store configuration data using Docker Configs](https://docs.docker.com/engine/swarm/configs/).
> **Note** > **Note**
> >
> This is a cluster management command, and must be executed on a swarm > This is a cluster management command, and must be executed on a Swarm
> manager node. To learn about managers and workers, refer to the > manager node. To learn about managers and workers, refer to the
> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
> documentation. > documentation.

9
docs/reference/commandline/config_rm.md
View File

@ -12,13 +12,13 @@ Remove one or more configs
## Description ## Description
Removes the specified configs from the swarm. Removes the specified configs from the Swarm.
For detailed information about using configs, refer to [store configuration data using Docker Configs](https://docs.docker.com/engine/swarm/configs/). For detailed information about using configs, refer to [store configuration data using Docker Configs](https://docs.docker.com/engine/swarm/configs/).
> **Note** > **Note**
> >
> This is a cluster management command, and must be executed on a swarm > This is a cluster management command, and must be executed on a Swarm
> manager node. To learn about managers and workers, refer to the > manager node. To learn about managers and workers, refer to the
> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
> documentation. > documentation.
@ -34,9 +34,8 @@ sapth4csdo5b6wz2p5uimh5xg
> **Warning** > **Warning**
> >
> Unlike `docker rm`, this command does not ask for confirmation before removing > This command doesn't ask for confirmation before removing a config.
> a config. { .warning }
## Related commands ## Related commands

2
docs/reference/commandline/container_prune.md
View File

@ -48,7 +48,7 @@ relative to the daemon machine’s time. Supported formats for date
formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, 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 `2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local
timezone on the daemon will be used if you do not provide either a `Z` or a timezone on the daemon will be used if you do not provide either a `Z` or a
`+-00:00` timezone offset at the end of the timestamp. When providing Unix `+-00:00` timezone offset at the end of the timestamp. When providing Unix
timestamps enter seconds[.nanoseconds], where seconds is the number of seconds timestamps enter seconds[.nanoseconds], where seconds is the number of seconds
that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap 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 seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a

14
docs/reference/commandline/context_create.md
View File

@ -31,16 +31,16 @@ $ docker context create my-context --description "some description" --docker "ho
## Description ## Description
Creates a new `context`. This allows you to quickly switch the cli Creates a new `context`. This lets you switch the daemon your `docker` CLI
configuration to connect to different clusters or single nodes. connects to.
## Examples ## Examples
### <a name="docker"></a> Create a context with a docker endpoint (--docker) ### <a name="docker"></a> Create a context with a Docker endpoint (--docker)
To create a context from scratch provide the docker and, if required, Use the `--docker` flag to create a context with a custom endpoint. The
kubernetes options. The example below creates the context `my-context` following example creates a context named `my-context` with a docker endpoint
with a docker endpoint of `/var/run/docker.sock`: of `/var/run/docker.sock`:
```console ```console
$ docker context create \ $ docker context create \
@ -58,7 +58,7 @@ from the existing context `existing-context`:
$ docker context create --from existing-context my-context $ docker context create --from existing-context my-context
``` ```
If the `--from` option is not set, the `context` is created from the current context: If the `--from` option isn't set, the `context` is created from the current context:
```console ```console
$ docker context create my-context $ docker context create my-context

2
docs/reference/commandline/context_use.md
View File

@ -9,5 +9,5 @@ Set the current docker context
## Description ## Description
Set the default context to use, when `DOCKER_HOST`, `DOCKER_CONTEXT` environment Set the default context to use, when `DOCKER_HOST`, `DOCKER_CONTEXT` environment
variables and `--host`, `--context` global options are not set. variables and `--host`, `--context` global options aren't set.
To disable usage of contexts, you can use the special `default` context. To disable usage of contexts, you can use the special `default` context.

6
docs/reference/commandline/cp.md
View File

@ -48,8 +48,8 @@ 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 command. However, if you specify the `-a` option, `docker cp` sets the ownership
to the user and primary group at the source. to the user and primary group at the source.
If you specify the `-L` option, `docker cp` follows any symbolic link If you specify the `-L` option, `docker cp` follows any symbolic link
in the `SRC_PATH`. `docker cp` does *not* create parent directories for in the `SRC_PATH`. `docker cp` doesn't create parent directories for
`DEST_PATH` if they do not exist. `DEST_PATH` if they don't exist.
Assuming a path separator of `/`, a first argument of `SRC_PATH` and second Assuming a path separator of `/`, a first argument of `SRC_PATH` and second
argument of `DEST_PATH`, the behavior is as follows: argument of `DEST_PATH`, the behavior is as follows:
@ -111,7 +111,7 @@ $ docker cp CONTAINER:/var/logs/app.log - | tar x -O | grep "ERROR"
### Corner cases ### Corner cases
It is not possible to copy certain system files such as resources under It isn't possible to copy certain system files such as resources under
`/proc`, `/sys`, `/dev`, [tmpfs](run.md#tmpfs), and mounts created by `/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 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 running `tar` in `docker exec`. Both of the following examples do the same thing

8
docs/reference/commandline/create.md
View File

@ -120,14 +120,14 @@ Create a new container
The `docker container create` (or shorthand: `docker create`) command creates a The `docker container create` (or shorthand: `docker create`) command creates a
new container from the specified image, without starting it. new container from the specified image, without starting it.
When creating a container, the docker daemon creates a writeable container layer 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 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` 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` 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. (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 This is useful when you want to set up a container configuration ahead of time
so that it is ready to start when you need it. The initial status of the so that it's ready to start when you need it. The initial status of the
new container is `created`. new container is `created`.
The `docker create` command shares most of its options with the `docker run` The `docker create` command shares most of its options with the `docker run`

367
docs/reference/commandline/dockerd.md
View File

@ -124,7 +124,7 @@ To run the daemon with debug output, use `dockerd --debug` or add `"debug": true
to [the `daemon.json` file](#daemon-configuration-file). to [the `daemon.json` file](#daemon-configuration-file).
> **Enabling experimental features** > **Enabling experimental features**
> >
> Enable experimental features by starting `dockerd` with the `--experimental` > Enable experimental features by starting `dockerd` with the `--experimental`
> flag or adding `"experimental": true` to the `daemon.json` file. > flag or adding `"experimental": true` to the `daemon.json` file.
@ -137,7 +137,7 @@ by the `dockerd` command line:
|:--------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |:--------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `DOCKER_CERT_PATH` | Location of your authentication keys. This variable is used both by the [`docker` CLI](cli.md) and the `dockerd` daemon. | | `DOCKER_CERT_PATH` | Location of your authentication keys. This variable is used both by the [`docker` CLI](cli.md) and the `dockerd` daemon. |
| `DOCKER_DRIVER` | The storage driver to use. | | `DOCKER_DRIVER` | The storage driver to use. |
| `DOCKER_RAMDISK` | If set this disables 'pivot_root'. | | `DOCKER_RAMDISK` | If set this disables `pivot_root`. |
| `DOCKER_TLS_VERIFY` | When set Docker uses TLS and verifies the remote. This variable is used both by the [`docker` CLI](cli.md) and the `dockerd` daemon. | | `DOCKER_TLS_VERIFY` | When set Docker uses TLS and verifies the remote. This variable is used both by the [`docker` CLI](cli.md) and the `dockerd` daemon. |
| `DOCKER_TMPDIR` | Location for temporary files created by the daemon. | | `DOCKER_TMPDIR` | Location for temporary files created by the daemon. |
| `HTTP_PROXY` | Proxy URL for HTTP requests unless overridden by NoProxy. See the [Go specification](https://pkg.go.dev/golang.org/x/net/http/httpproxy#Config) for details. | | `HTTP_PROXY` | Proxy URL for HTTP requests unless overridden by NoProxy. See the [Go specification](https://pkg.go.dev/golang.org/x/net/http/httpproxy#Config) for details. |
@ -150,7 +150,7 @@ by the `dockerd` command line:
### Proxy configuration ### Proxy configuration
> **Note** > **Note**
> >
> Refer to the [Docker Desktop manual](https://docs.docker.com/desktop/networking/#httphttps-proxy-support) > Refer to the [Docker Desktop manual](https://docs.docker.com/desktop/networking/#httphttps-proxy-support)
> if you are running [Docker Desktop](https://docs.docker.com/desktop/). > if you are running [Docker Desktop](https://docs.docker.com/desktop/).
@ -160,10 +160,10 @@ operations such as pulling and pushing images. The daemon can be configured
in three ways: in three ways:
1. Using environment variables (`HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`). 1. Using environment variables (`HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`).
2. Using the "http-proxy", "https-proxy", and "no-proxy" fields in the 2. Using the `http-proxy`, `https-proxy`, and `no-proxy` fields in the
[daemon configuration file](#daemon-configuration-file) (Docker Engine 23.0 or newer). [daemon configuration file](#daemon-configuration-file) (Docker Engine version 23.0 or later).
3. Using the `--http-proxy`, `--https-proxy`, and `--no-proxy` command-line 3. Using the `--http-proxy`, `--https-proxy`, and `--no-proxy` command-line
options. (Docker Engine 23.0 or newer). options. (Docker Engine version 23.0 or later).
The command-line and configuration file options take precedence over environment The command-line and configuration file options take precedence over environment
variables. Refer to [control and configure Docker with systemd](https://docs.docker.com/config/daemon/systemd/#httphttps-proxy) variables. Refer to [control and configure Docker with systemd](https://docs.docker.com/config/daemon/systemd/#httphttps-proxy)
@ -178,11 +178,11 @@ By default, a `unix` domain socket (or IPC socket) is created at
`/var/run/docker.sock`, requiring either `root` permission, or `docker` group `/var/run/docker.sock`, requiring either `root` permission, or `docker` group
membership. membership.
If you need to access the Docker daemon remotely, you need to enable the `tcp` If you need to access the Docker daemon remotely, you need to enable the tcp
Socket. Beware that the default setup provides un-encrypted and Socket. When using a TCP socket, the Docker daemon provides un-encrypted and
un-authenticated direct access to the Docker daemon - and should be secured un-authenticated direct access to the Docker daemon by default. You should secure
either using the [built in HTTPS encrypted socket](https://docs.docker.com/engine/security/https/), or by the daemon either using the [built in HTTPS encrypted socket](https://docs.docker.com/engine/security/protect-access/),
putting a secure web proxy in front of it. You can listen on port `2375` on all or by putting a secure web proxy in front of it. You can listen on port `2375` on all
network interfaces with `-H tcp://0.0.0.0:2375`, or on a particular network network interfaces with `-H tcp://0.0.0.0:2375`, or on a particular network
interface using its IP address: `-H tcp://192.168.59.103:2375`. It is interface using its IP address: `-H tcp://192.168.59.103:2375`. It is
conventional to use port `2375` for un-encrypted, and port `2376` for encrypted conventional to use port `2375` for un-encrypted, and port `2376` for encrypted
@ -191,28 +191,28 @@ communication with the daemon.
> **Note** > **Note**
> >
> If you're using an HTTPS encrypted socket, keep in mind that only > If you're using an HTTPS encrypted socket, keep in mind that only
> TLS1.0 and greater are supported. Protocols SSLv3 and under are not > TLS version 1.0 and higher is supported. Protocols SSLv3 and below are not
> supported anymore for security reasons. > supported for security reasons.
On Systemd based systems, you can communicate with the daemon via On systemd based systems, you can communicate with the daemon via
[Systemd socket activation](https://0pointer.de/blog/projects/socket-activation.html), [systemd socket activation](https://0pointer.de/blog/projects/socket-activation.html),
use `dockerd -H fd://`. Using `fd://` will work perfectly for most setups but with `dockerd -H fd://`. Using `fd://` works for most setups, but
you can also specify individual sockets: `dockerd -H fd://3`. If the you can also specify individual sockets: `dockerd -H fd://3`. If the
specified socket activated files aren't found, then Docker will exit. You can specified socket activated files aren't found, the daemon exits. You can
find examples of using Systemd socket activation with Docker and Systemd in the find examples of using systemd socket activation with Docker and systemd in the
[Docker source tree](https://github.com/docker/docker/tree/master/contrib/init/systemd/). [Docker source tree](https://github.com/docker/docker/tree/master/contrib/init/systemd/).
You can configure the Docker daemon to listen to multiple sockets at the same You can configure the Docker daemon to listen to multiple sockets at the same
time using multiple `-H` options: time using multiple `-H` options:
The example below runs the daemon listening on the default unix socket, and The example below runs the daemon listening on the default Unix socket, and
on 2 specific IP addresses on this host: on 2 specific IP addresses on this host:
```console ```console
$ sudo dockerd -H unix:///var/run/docker.sock -H tcp://192.168.59.106 -H tcp://10.10.10.2 $ sudo dockerd -H unix:///var/run/docker.sock -H tcp://192.168.59.106 -H tcp://10.10.10.2
``` ```
The Docker client will honor the `DOCKER_HOST` environment variable to set the The Docker client honors the `DOCKER_HOST` environment variable to set the
`-H` flag for the client. Use **one** of the following commands: `-H` flag for the client. Use **one** of the following commands:
```console ```console
@ -236,7 +236,7 @@ $ export DOCKER_TLS_VERIFY=1
$ docker ps $ docker ps
``` ```
The Docker client will honor the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` The Docker client honors the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`
environment variables (or the lowercase versions thereof). `HTTPS_PROXY` takes environment variables (or the lowercase versions thereof). `HTTPS_PROXY` takes
precedence over `HTTP_PROXY`. precedence over `HTTP_PROXY`.
@ -258,29 +258,28 @@ supported. If your key is protected with passphrase, you need to set up
> **Warning** > **Warning**
> >
> Changing the default `docker` daemon binding to a > Changing the default `docker` daemon binding to a TCP port or Unix `docker`
> TCP port or Unix *docker* user group will increase your security risks > user group introduces security risks, as it may allow non-root users to gain
> by allowing non-root users to gain *root* access on the host. Make sure > root access on the host. Make sure you control access to `docker`. If you are
> you control access to `docker`. If you are binding > binding to a TCP port, anyone with access to that port has full Docker
> to a TCP port, anyone with access to that port has full Docker access; > access; so it's not advisable on an open network.
> so it is not advisable on an open network. { .warning }
{: .warning :}
With `-H` it is possible to make the Docker daemon to listen on a With `-H` it's possible to make the Docker daemon to listen on a specific IP
specific IP and port. By default, it will listen on and port. By default, it listens on `unix:///var/run/docker.sock` to allow
`unix:///var/run/docker.sock` to allow only local connections by the only local connections by the root user. You could set it to `0.0.0.0:2375` or
*root* user. You *could* set it to `0.0.0.0:2375` or a specific host IP a specific host IP to give access to everybody, but that isn't recommended
to give access to everybody, but that is **not recommended** because because someone could gain root access to the host where the daemon is running.
then it is trivial for someone to gain root access to the host where the
daemon is running.
Similarly, the Docker client can use `-H` to connect to a custom port. Similarly, the Docker client can use `-H` to connect to a custom port.
The Docker client will default to connecting to `unix:///var/run/docker.sock` The Docker client defaults to connecting to `unix:///var/run/docker.sock`
on Linux, and `tcp://127.0.0.1:2376` on Windows. on Linux, and `tcp://127.0.0.1:2376` on Windows.
`-H` accepts host and port assignment in the following format: `-H` accepts host and port assignment in the following format:
tcp://[host]:[port][path] or unix://path ```text
tcp://[host]:[port][path] or unix://path
```
For example: For example:
@ -293,7 +292,7 @@ For example:
- `unix://path/to/socket` -> Unix socket located - `unix://path/to/socket` -> Unix socket located
at `path/to/socket` at `path/to/socket`
`-H`, when empty, will default to the same value as `-H`, when empty, defaults to the same value as
when no `-H` was passed in. when no `-H` was passed in.
`-H` also accepts short form for TCP bindings: `host:` or `host:port` or `:port` `-H` also accepts short form for TCP bindings: `host:` or `host:port` or `:port`
@ -344,9 +343,8 @@ Particular storage-driver can be configured with options specified with
##### `zfs.fsname` ##### `zfs.fsname`
Set zfs filesystem under which docker will create its own datasets. Specifies the ZFS filesystem that the daemon should use to create its datasets.
By default docker will pick up the zfs filesystem where docker graph By default, the ZFS filesystem in `/var/lib/docker` is used.
(`/var/lib/docker`) is located.
###### Example ###### Example
@ -360,8 +358,8 @@ $ sudo dockerd -s zfs --storage-opt zfs.fsname=zroot/docker
Specifies the minimum size to use when creating the subvolume which is used Specifies the minimum size to use when creating the subvolume which is used
for containers. If user uses disk quota for btrfs when creating or running for containers. If user uses disk quota for btrfs when creating or running
a container with **--storage-opt size** option, docker should ensure the a container with **--storage-opt size** option, Docker should ensure the
**size** cannot be smaller than **btrfs.min_space**. **size** can't be smaller than **btrfs.min_space**.
###### Example ###### Example
@ -374,8 +372,8 @@ $ sudo dockerd -s btrfs --storage-opt btrfs.min_space=10G
##### `overlay2.size` ##### `overlay2.size`
Sets the default max size of the container. It is supported only when the Sets the default max size of the container. It is supported only when the
backing fs is `xfs` and mounted with `pquota` mount option. Under these backing filesystem is `xfs` and mounted with `pquota` mount option. Under these
conditions the user can pass any size less than the backing fs size. conditions the user can pass any size less than the backing filesystem size.
###### Example ###### Example
@ -687,7 +685,7 @@ To set the DNS search domain for all Docker containers, use:
$ sudo dockerd --dns-search example.com $ sudo dockerd --dns-search example.com
``` ```
### Allow push of nondistributable artifacts ### Allow push of non-distributable artifacts
Some images (e.g., Windows base images) contain artifacts whose distribution is Some images (e.g., Windows base images) contain artifacts whose distribution is
restricted by license. When these images are pushed to a registry, restricted restricted by license. When these images are pushed to a registry, restricted
@ -697,38 +695,41 @@ To override this behavior for specific registries, use the
`--allow-nondistributable-artifacts` option in one of the following forms: `--allow-nondistributable-artifacts` option in one of the following forms:
* `--allow-nondistributable-artifacts myregistry:5000` tells the Docker daemon * `--allow-nondistributable-artifacts myregistry:5000` tells the Docker daemon
to push nondistributable artifacts to myregistry:5000. to push non-distributable artifacts to myregistry:5000.
* `--allow-nondistributable-artifacts 10.1.0.0/16` tells the Docker daemon to * `--allow-nondistributable-artifacts 10.1.0.0/16` tells the Docker daemon to
push nondistributable artifacts to all registries whose resolved IP address push non-distributable artifacts to all registries whose resolved IP address
is within the subnet described by the CIDR syntax. is within the subnet described by the CIDR syntax.
This option can be used multiple times. This option can be used multiple times.
This option is useful when pushing images containing nondistributable artifacts This option is useful when pushing images containing non-distributable artifacts
to a registry on an air-gapped network so hosts on that network can pull the to a registry on an air-gapped network so hosts on that network can pull the
images without connecting to another server. images without connecting to another server.
> **Warning**: Nondistributable artifacts typically have restrictions on how > **Warning**
>
> Non-distributable artifacts typically have restrictions on how
> and where they can be distributed and shared. Only use this feature to push > and where they can be distributed and shared. Only use this feature to push
> artifacts to private registries and ensure that you are in compliance with > artifacts to private registries and ensure that you are in compliance with
> any terms that cover redistributing nondistributable artifacts. > any terms that cover redistributing non-distributable artifacts.
{ .warning }
### Insecure registries ### Insecure registries
Docker considers a private registry either secure or insecure. In the rest of In this section, "registry" refers to a private registry, and `myregistry:5000`
this section, *registry* is used for *private registry*, and `myregistry:5000` is a placeholder example of a private registry.
is a placeholder example for a private registry.
Docker considers a private registry either secure or insecure.
A secure registry uses TLS and a copy of its CA certificate is placed on the A secure registry uses TLS and a copy of its CA certificate is placed on the
Docker host at `/etc/docker/certs.d/myregistry:5000/ca.crt`. An insecure Docker host at `/etc/docker/certs.d/myregistry:5000/ca.crt`. An insecure
registry is either not using TLS (i.e., listening on plain text HTTP), or is registry is either not using TLS (i.e., listening on plain text HTTP), or is
using TLS with a CA certificate not known by the Docker daemon. The latter can using TLS with a CA certificate not known by the Docker daemon. The latter can
happen when the certificate was not found under happen when the certificate wasn't found under
`/etc/docker/certs.d/myregistry:5000/`, or if the certificate verification `/etc/docker/certs.d/myregistry:5000/`, or if the certificate verification
failed (i.e., wrong CA). failed (i.e., wrong CA).
By default, Docker assumes all, but local (see local registries below), By default, Docker assumes all registries to be secure, except for local registries.
registries are secure. Communicating with an insecure registry is not possible Communicating with an insecure registry isn't possible
if Docker assumes that registry is secure. In order to communicate with an if Docker assumes that registry is secure. In order to communicate with an
insecure registry, the Docker daemon requires `--insecure-registry` in one of insecure registry, the Docker daemon requires `--insecure-registry` in one of
the following two forms: the following two forms:
@ -742,34 +743,33 @@ the following two forms:
The flag can be used multiple times to allow multiple registries to be marked The flag can be used multiple times to allow multiple registries to be marked
as insecure. as insecure.
If an insecure registry is not marked as insecure, `docker pull`, If an insecure registry isn't marked as insecure, `docker pull`,
`docker push`, and `docker search` will result in an error message prompting `docker push`, and `docker search` result in error messages, prompting
the user to either secure or pass the `--insecure-registry` flag to the Docker the user to either secure or pass the `--insecure-registry` flag to the Docker
daemon as described above. daemon as described above.
Local registries, whose IP address falls in the 127.0.0.0/8 range, are Local registries, whose IP address falls in the 127.0.0.0/8 range, are
automatically marked as insecure as of Docker 1.3.2. It is not recommended to automatically marked as insecure as of Docker 1.3.2. It isn't recommended to
rely on this, as it may change in the future. rely on this, as it may change in the future.
Enabling `--insecure-registry`, i.e., allowing un-encrypted and/or untrusted Enabling `--insecure-registry`, i.e., allowing un-encrypted and/or untrusted
communication, can be useful when running a local registry. However, communication, can be useful when running a local registry. However,
because its use creates security vulnerabilities it should ONLY be enabled for because its use creates security vulnerabilities it should only be enabled for
testing purposes. For increased security, users should add their CA to their testing purposes. For increased security, users should add their CA to their
system's list of trusted CAs instead of enabling `--insecure-registry`. system's list of trusted CAs instead of enabling `--insecure-registry`.
#### Legacy Registries #### Legacy Registries
Operations against registries supporting only the legacy v1 protocol are no longer Operations against registries supporting only the legacy v1 protocol are no longer
supported. Specifically, the daemon will not attempt `push`, `pull` and `login` supported. Specifically, the daemon doesn't attempt to push, pull or sign in
to v1 registries. The exception to this is `search` which can still be performed to v1 registries. The exception to this is `search` which can still be performed
on v1 registries. on v1 registries.
### Running a Docker daemon behind an HTTPS_PROXY ### Running a Docker daemon behind an HTTPS_PROXY
When running inside a LAN that uses an `HTTPS` proxy, the Docker Hub When running inside a LAN that uses an `HTTPS` proxy, the proxy's certificates
certificates will be replaced by the proxy's certificates. These certificates replace Docker Hub's certificates. These certificates must be added to your
need to be added to your Docker host's configuration: Docker host's configuration:
1. Install the `ca-certificates` package for your distribution 1. Install the `ca-certificates` package for your distribution
2. Ask your network admin for the proxy's CA certificate and append them to 2. Ask your network admin for the proxy's CA certificate and append them to
@ -778,21 +778,20 @@ need to be added to your Docker host's configuration:
The `username:` and `password@` are optional - and are only needed if your The `username:` and `password@` are optional - and are only needed if your
proxy is set up to require authentication. proxy is set up to require authentication.
This will only add the proxy and authentication to the Docker daemon's requests - This only adds the proxy and authentication to the Docker daemon's requests.
your `docker build`s and running containers will need extra configuration to To use the proxy when building images and running containers, see
use the proxy [Configure Docker to use a proxy server](https://docs.docker.com/network/proxy/)
### Default `ulimit` settings ### Default `ulimit` settings
`--default-ulimit` allows you to set the default `ulimit` options to use for The `--default-ulimit` flag lets you set the default `ulimit` options to use for
all containers. It takes the same options as `--ulimit` for `docker run`. If all containers. It takes the same options as `--ulimit` for `docker run`. If
these defaults are not set, `ulimit` settings will be inherited, if not set on these defaults aren't set, `ulimit` settings are inherited from the Docker daemon.
`docker run`, from the Docker daemon. Any `--ulimit` options passed to Any `--ulimit` options passed to `docker run` override the daemon defaults.
`docker run` will overwrite these defaults.
Be careful setting `nproc` with the `ulimit` flag as `nproc` is designed by Linux to Be careful setting `nproc` with the `ulimit` flag, as `nproc` is designed by Linux to
set the maximum number of processes available to a user, not to a container. For details set the maximum number of processes available to a user, not to a container.
please check the [run](run.md) reference. For details, see [`docker run` reference](run.md#ulimit).
### Access authorization ### Access authorization
@ -818,17 +817,16 @@ allow the request for it to complete.
For information about how to create an authorization plugin, refer to the For information about how to create an authorization plugin, refer to the
[authorization plugin](../../extend/plugins_authorization.md) section. [authorization plugin](../../extend/plugins_authorization.md) section.
### Daemon user namespace options ### Daemon user namespace options
The Linux kernel The Linux kernel
[user namespace support](https://man7.org/linux/man-pages/man7/user_namespaces.7.html) [user namespace support](https://man7.org/linux/man-pages/man7/user_namespaces.7.html)
provides additional security by enabling a process, and therefore a container, provides additional security by enabling a process, and therefore a container,
to have a unique range of user and group IDs which are outside the traditional to have a unique range of user and group IDs which are outside the traditional
user and group range utilized by the host system. Potentially the most important user and group range utilized by the host system. One of the most important
security improvement is that, by default, container processes running as the security improvements is that, by default, container processes running as the
`root` user will have expected administrative privilege (with some restrictions) `root` user have expected administrative privileges it expects (with some restrictions)
inside the container but will effectively be mapped to an unprivileged `uid` on inside the container, but are effectively mapped to an unprivileged `uid` on
the host. the host.
For details about how to use this feature, as well as limitations, see For details about how to use this feature, as well as limitations, see
@ -856,29 +854,23 @@ PING host.docker.internal (192.0.2.0): 56 data bytes
### Miscellaneous options ### Miscellaneous options
IP masquerading uses address translation to allow containers without a public IP masquerading uses address translation to allow containers without a public
IP to talk to other machines on the Internet. This may interfere with some IP to talk to other machines on the internet. This may interfere with some
network topologies and can be disabled with `--ip-masq=false`. network topologies, and can be disabled with `--ip-masq=false`.
Docker supports softlinks for the Docker data directory (`/var/lib/docker`) and Docker supports soft links for the Docker data directory (`/var/lib/docker`) and
for `/var/lib/docker/tmp`. The `DOCKER_TMPDIR` and the data directory can be for `/var/lib/docker/tmp`. The `DOCKER_TMPDIR` and the data directory can be
set like this: set like this:
```console
$ DOCKER_TMPDIR=/mnt/disk2/tmp /usr/local/bin/dockerd --data-root /var/lib/docker -H unix:// > /var/lib/docker-machine/docker.log 2>&1
```
or
```console ```console
$ export DOCKER_TMPDIR=/mnt/disk2/tmp $ export DOCKER_TMPDIR=/mnt/disk2/tmp
$ /usr/local/bin/dockerd --data-root /var/lib/docker -H unix:// > /var/lib/docker-machine/docker.log 2>&1 $ sudo -E dockerd --data-root /var/lib/docker -H unix://
```` ````
#### Default cgroup parent #### Default cgroup parent
The `--cgroup-parent` option allows you to set the default cgroup parent The `--cgroup-parent` option lets you set the default cgroup parent
to use for containers. If this option is not set, it defaults to `/docker` for for containers. If this option isn't set, it defaults to `/docker` for
fs cgroup driver and `system.slice` for systemd cgroup driver. the cgroupfs driver, and `system.slice` for the systemd cgroup driver.
If the cgroup has a leading forward slash (`/`), the cgroup is created If the cgroup has a leading forward slash (`/`), the cgroup is created
under the root cgroup, otherwise the cgroup is created under the daemon under the root cgroup, otherwise the cgroup is created under the daemon
@ -889,7 +881,7 @@ Assuming the daemon is running in cgroup `daemoncgroup`,
`/sys/fs/cgroup/memory/foobar`, whereas using `--cgroup-parent=foobar` `/sys/fs/cgroup/memory/foobar`, whereas using `--cgroup-parent=foobar`
creates the cgroup in `/sys/fs/cgroup/memory/daemoncgroup/foobar` creates the cgroup in `/sys/fs/cgroup/memory/daemoncgroup/foobar`
The systemd cgroup driver has different rules for `--cgroup-parent`. Systemd The systemd cgroup driver has different rules for `--cgroup-parent`. systemd
represents hierarchy by slice and the name of the slice encodes the location in represents hierarchy by slice and the name of the slice encodes the location in
the tree. So `--cgroup-parent` for systemd cgroups should be a slice name. A the tree. So `--cgroup-parent` for systemd cgroups should be a slice name. A
name can consist of a dash-separated series of names, which describes the path name can consist of a dash-separated series of names, which describes the path
@ -903,7 +895,7 @@ the `--cgroup-parent` option on the daemon.
#### Daemon metrics #### Daemon metrics
The `--metrics-addr` option takes a tcp address to serve the metrics API. The `--metrics-addr` option takes a TCP address to serve the metrics API.
This feature is still experimental, therefore, the daemon must be running in experimental This feature is still experimental, therefore, the daemon must be running in experimental
mode for this feature to work. mode for this feature to work.
@ -913,34 +905,24 @@ allowing you to make requests on the API at `127.0.0.1:9323/metrics` to receive
Port `9323` is the [default port associated with Docker Port `9323` is the [default port associated with Docker
metrics](https://github.com/prometheus/prometheus/wiki/Default-port-allocations) metrics](https://github.com/prometheus/prometheus/wiki/Default-port-allocations)
to avoid collisions with other prometheus exporters and services. to avoid collisions with other Prometheus exporters and services.
If you are running a prometheus server you can add this address to your scrape configs If you are running a Prometheus server you can add this address to your scrape configs
to have prometheus collect metrics on Docker. For more information to have Prometheus collect metrics on Docker. For more information, see
on prometheus refer to the [prometheus website](https://prometheus.io/). [Collect Docker metrics with Prometheus](https://docs.docker.com/config/daemon/prometheus/).
```yaml #### Node generic resources
scrape_configs:
- job_name: 'docker'
static_configs:
- targets: ['127.0.0.1:9323']
```
Please note that this feature is still marked as experimental as metrics and metric
names could change while this feature is still in experimental. Please provide
feedback on what you would like to see collected in the API.
#### Node Generic Resources
The `--node-generic-resources` option takes a list of key-value The `--node-generic-resources` option takes a list of key-value
pair (`key=value`) that allows you to advertise user defined resources pair (`key=value`) that allows you to advertise user defined resources
in a swarm cluster. in a Swarm cluster.
The current expected use case is to advertise NVIDIA GPUs so that services The current expected use case is to advertise NVIDIA GPUs so that services
requesting `NVIDIA-GPU=[0-16]` can land on a node that has enough GPUs for requesting `NVIDIA-GPU=[0-16]` can land on a node that has enough GPUs for
the task to run. the task to run.
Example of usage: Example of usage:
```json ```json
{ {
"node-generic-resources": [ "node-generic-resources": [
@ -958,8 +940,8 @@ except for flags that allow several entries, where it uses the plural
of the flag name, e.g., `labels` for the `label` flag. of the flag name, e.g., `labels` for the `label` flag.
The options set in the configuration file must not conflict with options set The options set in the configuration file must not conflict with options set
via flags. The docker daemon fails to start if an option is duplicated between using flags. The Docker daemon fails to start if an option is duplicated between
the file and the flags, regardless of their value. We do this to avoid the file and the flags, regardless of their value. This is intentional, and avoids
silently ignore changes introduced in configuration reloads. silently ignore changes introduced in configuration reloads.
For example, the daemon fails to start if you set daemon labels For example, the daemon fails to start if you set daemon labels
in the configuration file and also set daemon labels via the `--label` flag. in the configuration file and also set daemon labels via the `--label` flag.
@ -983,14 +965,13 @@ $ echo $?
1 1
``` ```
##### On Linux ##### On Linux
The default location of the configuration file on Linux is The default location of the configuration file on Linux is
`/etc/docker/daemon.json`. The `--config-file` flag can be used to specify a `/etc/docker/daemon.json`. Use the `--config-file` flag to specify a
non-default location. non-default location.
This is a full example of the allowed configuration options on Linux: The following is a full example of the allowed configuration options on Linux:
```json ```json
{ {
@ -1109,22 +1090,22 @@ This is a full example of the allowed configuration options on Linux:
} }
``` ```
> **Note:** > **Note**
> >
> You cannot set options in `daemon.json` that have already been set on > You can't set options in `daemon.json` that have already been set on
> daemon startup as a flag. > daemon startup as a flag.
> On systems that use `systemd` to start the Docker daemon, `-H` is already set, so > On systems that use systemd to start the Docker daemon, `-H` is already set, so
> you cannot use the `hosts` key in `daemon.json` to add listening addresses. > you can't use the `hosts` key in `daemon.json` to add listening addresses.
> See ["custom Docker daemon options"](https://docs.docker.com/config/daemon/systemd/#custom-docker-daemon-options) for how > See [custom Docker daemon options](https://docs.docker.com/config/daemon/systemd/#custom-docker-daemon-options)
> to accomplish this task with a systemd drop-in file. > for an example on how to configure the daemon using systemd drop-in files.
##### On Windows ##### On Windows
The default location of the configuration file on Windows is The default location of the configuration file on Windows is
`%programdata%\docker\config\daemon.json`. The `--config-file` flag can be `%programdata%\docker\config\daemon.json`. Use the `--config-file` flag
used to specify a non-default location. to specify a non-default location.
This is a full example of the allowed configuration options on Windows: The following is a full example of the allowed configuration options on Windows:
```json ```json
{ {
@ -1170,7 +1151,8 @@ This is a full example of the allowed configuration options on Windows:
} }
``` ```
The `default-runtime` option is by default unset, in which case dockerd will auto-detect the runtime. This detection is currently based on if the `containerd` flag is set. The `default-runtime` option is by default unset, in which case dockerd automatically detects the runtime.
This detection is based on if the `containerd` flag is set.
Accepted values: Accepted values:
@ -1178,60 +1160,69 @@ Accepted values:
- `io.containerd.runhcs.v1` - This is uses the containerd `runhcs` shim to run the container and uses the v2 HCS API's in Windows. - `io.containerd.runhcs.v1` - This is uses the containerd `runhcs` shim to run the container and uses the v2 HCS API's in Windows.
#### Feature options #### Feature options
The optional field `features` in `daemon.json` allows users to enable or disable specific
daemon features. For example, `{"features":{"buildkit": true}}` enables `buildkit` as the
default docker image builder.
The list of currently supported feature options: The optional field `features` in `daemon.json` lets you enable or disable specific
- `buildkit`: It enables `buildkit` as default builder when set to `true` or disables it by daemon features.
`false`. Note that if this option is not explicitly set in the daemon config file, then it
is up to the cli to determine which builder to invoke. ```json
{
"features": {
"some-feature": true,
"some-disabled-feature-enabled-by-default": false
}
}
```
The list of feature options include:
- `containerd-snapshotter`: when set to `true`, the daemon uses containerd
snapshotters instead of the classic storage drivers for storing image and
container data. For more information, see
[containerd storage](https://docs.docker.com/storage/containerd/).
#### Configuration reload behavior #### Configuration reload behavior
Some options can be reconfigured when the daemon is running without requiring Some options can be reconfigured when the daemon is running without requiring
to restart the process. We use the `SIGHUP` signal in Linux to reload, and a global event to restart the process. The daemon uses the `SIGHUP` signal in Linux to reload,
in Windows with the key `Global\docker-daemon-config-$PID`. The options can and a global event in Windows with the key `Global\docker-daemon-config-$PID`.
be modified in the configuration file but still will check for conflicts with You can modify the options in the configuration file, but the daemon still
the provided flags. The daemon fails to reconfigure itself checks for conflicting settings with the specified CLI flags. The daemon fails
if there are conflicts, but it won't stop execution. to reconfigure itself if there are conflicts, but it won't stop execution.
The list of currently supported options that can be reconfigured is this: The list of currently supported options that can be reconfigured is this:
- `debug`: it changes the daemon to debug mode when set to true. | Option | Description |
- `labels`: it replaces the daemon labels with a new set of labels. | ---------------------------------- | ----------------------------------------------------------------------------------------------------------- |
- `live-restore`: Enables [keeping containers alive during daemon downtime](https://docs.docker.com/config/containers/live-restore/). | `debug` | Toggles debug mode of the daemon. |
- `max-concurrent-downloads`: it updates the max concurrent downloads for each pull. | `labels` | Replaces the daemon labels with a new set of labels. |
- `max-concurrent-uploads`: it updates the max concurrent uploads for each push. | `live-restore` | Toggles [live restore](https://docs.docker.com/config/containers/live-restore/). |
- `max-download-attempts`: it updates the max download attempts for each pull. | `max-concurrent-downloads` | Configures the max concurrent downloads for each pull. |
- `default-runtime`: it updates the runtime to be used if not is | `max-concurrent-uploads` | Configures the max concurrent uploads for each push. |
specified at container creation. It defaults to "default" which is | `max-download-attempts` | Configures the max download attempts for each pull. |
the runtime shipped with the official docker packages. | `default-runtime` | Configures the runtime to be used if not is specified at container creation. |
- `runtimes`: it updates the list of available OCI runtimes that can | `runtimes` | Configures the list of available OCI runtimes that can be used to run containers. |
be used to run containers. | `authorization-plugin` | Specifies the authorization plugins to use. |
- `authorization-plugin`: it specifies the authorization plugins to use. | `allow-nondistributable-artifacts` | Specifies a list of registries to which the daemon will push non-distributable artifacts. |
- `allow-nondistributable-artifacts`: Replaces the set of registries to which the daemon will push nondistributable artifacts with a new set of registries. | `insecure-registries` | Specifies a list of registries that the daemon should consider insecure. |
- `insecure-registries`: it replaces the daemon insecure registries with a new set of insecure registries. If some existing insecure registries in daemon's configuration are not in newly reloaded insecure registries, these existing ones will be removed from daemon's config. | `registry-mirrors` | Specifies a list of registry mirrors. |
- `registry-mirrors`: it replaces the daemon registry mirrors with a new set of registry mirrors. If some existing registry mirrors in daemon's configuration are not in newly reloaded registry mirrors, these existing ones will be removed from daemon's config. | `shutdown-timeout` | Configures the daemon's existing configuration timeout with a new timeout for shutting down all containers. |
- `shutdown-timeout`: it replaces the daemon's existing configuration timeout with a new timeout for shutting down all containers. | `features` | Enables or disables specific features. |
- `features`: it explicitly enables or disables specific features.
### Run multiple daemons ### Run multiple daemons
> **Note:** > **Note**
> >
> Running multiple daemons on a single host is considered as "experimental". The user should be aware of > Running multiple daemons on a single host is considered experimental.
> unsolved problems. This solution may not work properly in some cases. Solutions are currently under development > You may encounter unsolved problems, and things may not work as expected in some cases.
> and will be delivered in the near future.
This section describes how to run multiple Docker daemons on a single host. To This section describes how to run multiple Docker daemons on a single host. To
run multiple daemons, you must configure each daemon so that it does not run multiple daemons, you must configure each daemon so that it doesn't
conflict with other daemons on the same host. You can set these options either conflict with other daemons on the same host. You can set these options either
by providing them as flags, or by using a [daemon configuration file](#daemon-configuration-file). by providing them as flags, or by using a [daemon configuration file](#daemon-configuration-file).
The following daemon options must be configured for each daemon: The following daemon options must be configured for each daemon:
```console ```text
-b, --bridge= Attach containers to a network bridge -b, --bridge= Attach containers to a network bridge
--exec-root=/var/run/docker Root of the Docker execdriver --exec-root=/var/run/docker Root of the Docker execdriver
--data-root=/var/lib/docker Root of persisted Docker data --data-root=/var/lib/docker Root of persisted Docker data
@ -1245,30 +1236,32 @@ The following daemon options must be configured for each daemon:
``` ```
When your daemons use different values for these flags, you can run them on the same host without any problems. When your daemons use different values for these flags, you can run them on the same host without any problems.
It is very important to properly understand the meaning of those options and to use them correctly. It is important that you understand the meaning of these options and to use them correctly.
- The `-b, --bridge=` flag is set to `docker0` as default bridge network. It is created automatically when you install Docker. - The `-b, --bridge=` flag is set to `docker0` as default bridge network.
If you are not using the default, you must create and configure the bridge manually or just set it to 'none': `--bridge=none` It is created automatically when you install Docker.
- `--exec-root` is the path where the container state is stored. The default value is `/var/run/docker`. Specify the path for If you aren't using the default, you must create and configure the bridge manually, or set it to 'none': `--bridge=none`
your running daemon here. - `--exec-root` is the path where the container state is stored.
The default value is `/var/run/docker`.
Specify the path for your running daemon here.
- `--data-root` is the path where persisted data such as images, volumes, and - `--data-root` is the path where persisted data such as images, volumes, and
cluster state are stored. The default value is `/var/lib/docker`. To avoid any cluster state are stored. The default value is `/var/lib/docker`. To avoid any
conflict with other daemons, set this parameter separately for each daemon. conflict with other daemons, set this parameter separately for each daemon.
- `-p, --pidfile=/var/run/docker.pid` is the path where the process ID of the daemon is stored. Specify the path for your - `-p, --pidfile=/var/run/docker.pid` is the path where the process ID of the daemon is stored.
pid file here. Specify the path for your PID file here.
- `--host=[]` specifies where the Docker daemon will listen for client connections. If unspecified, it defaults to `/var/run/docker.sock`. - `--host=[]` specifies where the Docker daemon listens for client connections.
- `--iptables=false` prevents the Docker daemon from adding iptables rules. If If unspecified, it defaults to `/var/run/docker.sock`.
multiple daemons manage iptables rules, they may overwrite rules set by another - `--iptables=false` prevents the Docker daemon from adding iptables rules. If
daemon. Be aware that disabling this option requires you to manually add multiple daemons manage iptables rules, they may overwrite rules set by another
iptables rules to expose container ports. If you prevent Docker from adding daemon. Be aware that disabling this option requires you to manually add
iptables rules, Docker will also not add IP masquerading rules, even if you set iptables rules to expose container ports. If you prevent Docker from adding
`--ip-masq` to `true`. Without IP masquerading rules, Docker containers will not be iptables rules, Docker also doesn't add IP masquerading rules, even if you set
able to connect to external hosts or the internet when using network other than `--ip-masq` to `true`. Without IP masquerading rules, Docker containers can't
default bridge. connect to external hosts or the internet when using network other than default bridge.
- `--config-file=/etc/docker/daemon.json` is the path where configuration file is stored. You can use it instead of - `--config-file=/etc/docker/daemon.json` is the path where configuration file is stored.
daemon flags. Specify the path for each daemon. You can use it instead of daemon flags. Specify the path for each daemon.
- `--tls*` Docker daemon supports `--tlsverify` mode that enforces encrypted and authenticated remote connections. - `--tls*` Docker daemon supports `--tlsverify` mode that enforces encrypted and authenticated remote connections.
The `--tls*` options enable use of specific certificates for individual daemons. The `--tls*` options enable use of specific certificates for individual daemons.
Example script for a separate “bootstrap” instance of the Docker daemon without network: Example script for a separate “bootstrap” instance of the Docker daemon without network:

65
docs/reference/commandline/events.md
View File

@ -23,7 +23,7 @@ Get real time events from the server
Use `docker events` to get real-time events from the server. These events differ 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 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 scoped events are only seen on the node they take place on, and Swarm scoped
events are seen on all managers. events are seen on all managers.
Only the last 1000 log events are returned. You can use filters to further limit Only the last 1000 log events are returned. You can use filters to further limit
@ -146,11 +146,11 @@ Docker configs report the following events:
The `--since` and `--until` parameters can be Unix timestamps, date formatted The `--since` and `--until` parameters can be Unix timestamps, date formatted
timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed 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, 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 the command returns only new and/or live events. Supported formats for date
formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, 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 `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 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 `+-00:00` timezone offset at the end of the timestamp. When providing Unix
timestamps enter seconds[.nanoseconds], where seconds is the number of seconds timestamps enter seconds[.nanoseconds], where seconds is the number of seconds
that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap 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 seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a
@ -165,40 +165,39 @@ The filtering flag (`-f` or `--filter`) format is of "key=value". If you would
like to use multiple filters, pass multiple flags (e.g., like to use multiple filters, pass multiple flags (e.g.,
`--filter "foo=bar" --filter "bif=baz"`) `--filter "foo=bar" --filter "bif=baz"`)
Using the same filter multiple times will be handled as a *OR*; for example Using the same filter multiple times is interpreted as a logical `OR`; for example,
`--filter container=588a23dac085 --filter container=a8f7720b8c22` will display `--filter container=588a23dac085 --filter container=a8f7720b8c22` displays
events for container 588a23dac085 *OR* container a8f7720b8c22 events for container `588a23dac085` or container `a8f7720b8c22`.
Using multiple filters will be handled as a *AND*; for example Using multiple filters is interpreted as a logical `AND`; for example,
`--filter container=588a23dac085 --filter event=start` will display events for `--filter container=588a23dac085 --filter event=start` displays events for
container container 588a23dac085 *AND* the event type is *start* container `588a23dac085` and where the event type is `start`.
The currently supported filters are: The currently supported filters are:
* config (`config=<name or id>`) - config (`config=<name or id>`)
* container (`container=<name or id>`) - container (`container=<name or id>`)
* daemon (`daemon=<name or id>`) - daemon (`daemon=<name or id>`)
* event (`event=<event action>`) - event (`event=<event action>`)
* image (`image=<repository or tag>`) - image (`image=<repository or tag>`)
* label (`label=<key>` or `label=<key>=<value>`) - label (`label=<key>` or `label=<key>=<value>`)
* network (`network=<name or id>`) - network (`network=<name or id>`)
* node (`node=<id>`) - node (`node=<id>`)
* plugin (`plugin=<name or id>`) - plugin (`plugin=<name or id>`)
* scope (`scope=<local or swarm>`) - scope (`scope=<local or swarm>`)
* secret (`secret=<name or id>`) - secret (`secret=<name or id>`)
* service (`service=<name or id>`) - service (`service=<name or id>`)
* type (`type=<container or image or volume or network or daemon or plugin or service or node or secret or config>`) - type (`type=<container or image or volume or network or daemon or plugin or service or node or secret or config>`)
* volume (`volume=<name>`) - volume (`volume=<name>`)
#### <a name="format"></a> Format the output (--format) #### <a name="format"></a> Format the output (--format)
If a format (`--format`) is specified, the given template will be executed If you specify a format (`--format`), the given template is executed
instead of the default instead of the default format. Go's [text/template](https://pkg.go.dev/text/template)
format. Go's [text/template](https://pkg.go.dev/text/template) package package describes all the details of the format.
describes all the details of the format.
If a format is set to `{{json .}}`, the events are streamed as valid JSON If a format is set to `{{json .}}`, events are streamed in the JSON Lines format.
Lines. For information about JSON Lines, please refer to https://jsonlines.org/. For information about JSON Lines, see <https://jsonlines.org/>.
## Examples ## Examples
@ -237,7 +236,7 @@ To exit the `docker events` command, use `CTRL+C`.
### Filter events by time ### Filter events by time
You can filter the output by an absolute timestamp or relative time on the host You can filter the output by an absolute timestamp or relative time on the host
machine, using the following different time syntaxes: machine, using the following different time formats:
```console ```console
$ docker events --since 1483283804 $ docker events --since 1483283804
@ -401,8 +400,8 @@ Type=container Status=destroy ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299
#### Format as JSON #### Format as JSON
To list events in JSON format, use the `json` directive, which is the equivalent To list events in JSON format, use the `json` directive, which is the same
of `--format '{{ json . }}`. `--format '{{ json . }}`.
```console ```console
$ docker events --format json $ docker events --format json
@ -413,5 +412,3 @@ $ docker events --format json
{"status":"start","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f42.. {"status":"start","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f42..
{"status":"resize","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. {"status":"resize","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4..
``` ```
.

28
docs/reference/commandline/exec.md
View File

@ -28,17 +28,16 @@ Execute a command in a running container
The `docker exec` command runs a new command in a running container. The `docker exec` command runs a new command in a running container.
The command started using `docker exec` only runs while the container's primary The command you specify with `docker exec` only runs while the container's
process (`PID 1`) is running, and it is not restarted if the container is primary process (`PID 1`) is running, and it isn't restarted if the container
restarted. is restarted.
COMMAND runs in the default directory of the container. If the underlying image The command runs in the default working directory of the container.
has a custom directory specified with the WORKDIR directive in its Dockerfile,
this directory is used instead.
COMMAND must be an executable. A chained or a quoted command does not work. The command must be an executable. A chained or a quoted command doesn't work.
For example, `docker exec -it my_container sh -c "echo a && echo b"` does
work, but `docker exec -it my_container "echo a && echo b"` does not. - 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 ## Examples
@ -82,10 +81,10 @@ time the container is created. Use the `--env` (or the `-e` shorthand) to
override global environment variables, or to set additional environment override global environment variables, or to set additional environment
variables for the process started by `docker exec`. variables for the process started by `docker exec`.
The example below creates a new shell session in the container `mycontainer` with The following example creates a new shell session in the container `mycontainer`,
environment variables `$VAR_A` and `$VAR_B` set to "1" and "2" respectively. 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 These environment variables are only valid for the `sh` process started by that
`docker exec` command, and are not available to other processes running inside `docker exec` command, and aren't available to other processes running inside
the container. the container.
```console ```console
@ -99,7 +98,7 @@ HOME=/root
### <a name="workdir"></a> Set the working directory for the exec process (--workdir, -w) ### <a name="workdir"></a> Set the working directory for the exec process (--workdir, -w)
By default `docker exec` command runs in the same working directory set when By default `docker exec` command runs in the same working directory set when
the container was created. the container was created.
```console ```console
@ -107,7 +106,7 @@ $ docker exec -it mycontainer pwd
/ /
``` ```
You can specify an alternative working directory for the command to execute You can specify an alternative working directory for the command to execute
using the `--workdir` option (or the `-w` shorthand): using the `--workdir` option (or the `-w` shorthand):
```console ```console
@ -115,7 +114,6 @@ $ docker exec -it -w /root mycontainer pwd
/root /root
``` ```
### Try to run `docker exec` on a paused container ### Try to run `docker exec` on a paused container
If the container is paused, then the `docker exec` command fails with an error: If the container is paused, then the `docker exec` command fails with an error:

6
docs/reference/commandline/export.md
View File

@ -18,9 +18,9 @@ Export a container's filesystem as a tar archive
## Description ## Description
The `docker export` command does not export the contents of volumes associated 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 with the container. If a volume is mounted on top of an existing directory in
the container, `docker export` will export the contents of the *underlying* the container, `docker export` exports the contents of the underlying
directory, not the contents of the volume. 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) Refer to [Backup, restore, or migrate data volumes](https://docs.docker.com/storage/volumes/#back-up-restore-or-migrate-data-volumes)
@ -28,7 +28,7 @@ in the user guide for examples on exporting data in a volume.
## Examples ## Examples
Each of these commands has the same result. The following commands produce the same result.
```console ```console
$ docker export red_panda > latest.tar $ docker export red_panda > latest.tar

6
docs/reference/commandline/history.md
View File

@ -62,9 +62,9 @@ Valid placeholders for the Go template are listed below:
| `.Size` | Image disk size | | `.Size` | Image disk size |
| `.Comment` | Comment for image | | `.Comment` | Comment for image |
When using the `--format` option, the `history` command will either When using the `--format` option, the `history` command either
output the data exactly as the template declares or, when using the outputs the data exactly as the template declares or, when using the
`table` directive, will include column headers as well. `table` directive, includes column headers as well.
The following example uses a template without headers and outputs the The following example uses a template without headers and outputs the
`ID` and `CreatedSince` entries separated by a colon (`:`) for the `busybox` `ID` and `CreatedSince` entries separated by a colon (`:`) for the `busybox`

71
docs/reference/commandline/run.md
View File

@ -125,7 +125,6 @@ The `docker run` command runs a command in a new container, pulling the image if
You can restart a stopped container with all its previous changes intact using `docker start`. 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. Use `docker ps -a` to view a list of all containers, including those that are stopped.
## Examples ## Examples
### <a name="name"></a> Assign name (--name) ### <a name="name"></a> Assign name (--name)
@ -281,9 +280,14 @@ container.
The UTS namespace is for setting the hostname and the domain that's visible to 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 running processes in that namespace. By default, all containers, including
those with `--network=host`, have their own UTS namespace. The `host` setting those with `--network=host`, have their own UTS namespace. Setting `--uts` to
will result in the container using the same UTS namespace as the host. Note `host` results in the container using the same UTS namespace as the host.
that `--hostname` and `--domainname` are invalid in `host` UTS mode.
> **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 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 hostname of the container to change as the hostname of the host changes. A more
@ -309,8 +313,9 @@ The `--ipc` flag accepts the following values:
If not specified, daemon default is used, which can either be `"private"` If not specified, daemon default is used, which can either be `"private"`
or `"shareable"`, depending on the daemon version and configuration. or `"shareable"`, depending on the daemon version and configuration.
IPC (POSIX/SysV IPC) namespace provides separation of named shared memory [System V interprocess communication (IPC)](https://linux.die.net/man/5/ipc)
segments, semaphores and message queues. namespaces provide separation of named shared memory segments, semaphores and
message queues.
Shared memory segments are used to accelerate inter-process communication at Shared memory segments are used to accelerate inter-process communication at
memory speed, rather than through pipes or through the network stack. Shared memory speed, rather than through pipes or through the network stack. Shared
@ -323,15 +328,17 @@ container, and `"container:<donor-name-or-ID>"` for other containers.
### <a name="privileged"></a> Full container capabilities (--privileged) ### <a name="privileged"></a> 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 ```console
$ docker run -t -i --rm ubuntu bash $ docker run -t -i --rm ubuntu bash
root@bc338942ef20:/# mount -t tmpfs none /mnt root@bc338942ef20:/# mount -t tmpfs none /mnt
mount: permission denied mount: permission denied
``` ```
This *doesn't* work, because by default, Docker drops most potentially dangerous kernel It works when you add the `--privileged` flag:
capabilities, including `CAP_SYS_ADMIN ` (which is required to mount
filesystems). However, the `--privileged` flag allows it to run:
```console ```console
$ docker run -t -i --privileged ubuntu bash $ docker run -t -i --privileged ubuntu bash
@ -341,7 +348,7 @@ Filesystem Size Used Avail Use% Mounted on
none 1.9G 0 1.9G 0% /mnt none 1.9G 0 1.9G 0% /mnt
``` ```
The `--privileged` flag gives *all* capabilities to the container, and it also The `--privileged` flag gives all capabilities to the container, and it also
lifts all the limitations enforced by the `device` cgroup controller. In other 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 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. flag exists to allow special use-cases, like running Docker within Docker.
@ -349,11 +356,11 @@ flag exists to allow special use-cases, like running Docker within Docker.
### <a name="workdir"></a> Set working directory (-w, --workdir) ### <a name="workdir"></a> Set working directory (-w, --workdir)
```console ```console
$ docker run -w /path/to/dir/ -i -t ubuntu pwd $ docker run -w /path/to/dir/ -i -t ubuntu pwd
``` ```
The `-w` option runs the command executed inside the directory specified, in this example, The `-w` option runs the command executed inside the directory specified, in this example,
`/path/to/dir/`. If the path does not exist, Docker creates it inside the container. `/path/to/dir/`. If the path doesn't exist, Docker creates it inside the container.
### <a name="storage-opt"></a> Set storage driver options per container (--storage-opt) ### <a name="storage-opt"></a> Set storage driver options per container (--storage-opt)
@ -384,6 +391,8 @@ container with the `rw`, `noexec`, `nosuid`, `size=65536k` options.
$ docker run -d --tmpfs /run:rw,noexec,nosuid,size=65536k my_image $ 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).
### <a name="volume"></a> Mount volume (-v) ### <a name="volume"></a> Mount volume (-v)
```console ```console
@ -597,14 +606,15 @@ VAR2=value2
When running the command, the Docker CLI client checks the value the variable When running the command, the Docker CLI client checks the value the variable
has in your local environment and passes it to the container. has in your local environment and passes it to the container.
If no `=` is provided and that variable is not exported in your local If no `=` is provided and that variable isn't exported in your local
environment, the variable isn't set in the container. environment, the variable is unset in the container.
You can also load the environment variables from a file. This file should use You can also load the environment variables from a file. This file should use
the syntax `<variable>=value` (which sets the variable to the given value) or the syntax `<variable>=value` (which sets the variable to the given value) or
`<variable>` (which takes the value from the local environment), and `#` for comments. `<variable>` (which takes the value from the local environment), and `#` for
Additionally, it's important to note that lines beginning with `#` are treated as line comments comments. Lines beginning with `#` are treated as line comments and are
and are ignored, whereas a `#` appearing anywhere else in a line is treated as part of the variable value. ignored, whereas a `#` appearing anywhere else in a line is treated as part of
the variable value.
```console ```console
$ cat env.list $ cat env.list
@ -657,9 +667,8 @@ com.example.label3
You can load multiple label-files by supplying multiple `--label-file` flags. You can load multiple label-files by supplying multiple `--label-file` flags.
For additional information on working with labels, see [*Labels - custom For additional information on working with labels, see
metadata in Docker*](https://docs.docker.com/config/labels-custom-metadata/) in [Labels](https://docs.docker.com/config/labels-custom-metadata/).
the Docker User Guide.
### <a name="network"></a> Connect a container to a network (--network) ### <a name="network"></a> Connect a container to a network (--network)
@ -887,9 +896,9 @@ $ cat somefile | docker run -i -a stdin mybuilder dobuild
> **Note** > **Note**
> >
> A process running as PID 1 inside a container is treated specially by Linux: > A process running as PID 1 inside a container is treated specially by
> it ignores any signal with the default action. As a result, the process will > Linux: it ignores any signal with the default action. So, the process
> not terminate on `SIGINT` or `SIGTERM` unless it is coded to do so. > doesn't terminate on `SIGINT` or `SIGTERM` unless it's coded to do so.
See also [the `docker cp` command](cp.md). See also [the `docker cp` command](cp.md).
@ -1047,8 +1056,8 @@ Docker supports the following restart policies:
$ docker run --restart=always redis $ docker run --restart=always redis
``` ```
This will run the `redis` container with a restart policy of **always** This runs the `redis` container with a restart policy of **always**.
so that if the container exits, Docker restarts it. If the container exits, Docker restarts it.
When a restart policy is active on a container, it shows as either `Up` or 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 `Restarting` in [`docker ps`](ps.md). It can also be useful to use [`docker
@ -1120,16 +1129,16 @@ the container and remove the file system when the container exits, use the
> >
> If you set the `--rm` flag, Docker also removes the anonymous volumes > If you set the `--rm` flag, Docker also removes the anonymous volumes
> associated with the container when the container is removed. This is similar > 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 > to running `docker rm -v my-container`. Only volumes that are specified
> a name are removed. For example, when running: > without a name are removed. For example, when running the following command,
> volume `/foo` is removed, but not `/bar`:
> >
> ```console > ```console
> $ docker run --rm -v /foo -v awesome:/bar busybox top > $ docker run --rm -v /foo -v awesome:/bar busybox top
> ``` > ```
> >
> the volume for `/foo` will be removed, but the volume for `/bar` will not. > Volumes inherited via `--volumes-from` are removed with the same logic:
> Volumes inherited via `--volumes-from` will be removed with the same logic: if > if the original volume was specified with a name it isn't removed.
> the original volume was specified with a name it will **not** be removed.
### <a name="add-host"></a> Add entries to container hosts file (--add-host) ### <a name="add-host"></a> Add entries to container hosts file (--add-host)
@ -1315,7 +1324,7 @@ use the following command:
$ docker run --security-opt no-new-privileges -it ubuntu bash $ docker run --security-opt no-new-privileges -it ubuntu bash
``` ```
This means that commands that raise privileges such as `su` or `sudo` will no longer work. 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 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. 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). For more details, see the [kernel documentation](https://www.kernel.org/doc/Documentation/prctl/no_new_privs.txt).

197
docs/reference/commandline/swarm_init.md
View File

@ -5,30 +5,30 @@ Initialize a swarm
### Options ### Options
| Name | Type | Default | Description | | Name | Type | Default | Description |
|:----------------------------------|:--------------|:---------------|:-----------------------------------------------------------------------------------------------------------------------------| |:--------------------------------------------|:--------------|:---------------|:-----------------------------------------------------------------------------------------------------------------------------|
| `--advertise-addr` | `string` | | Advertised address (format: `<ip\|interface>[:port]`) | | [`--advertise-addr`](#advertise-addr) | `string` | | Advertised address (format: `<ip\|interface>[:port]`) |
| `--autolock` | | | Enable manager autolocking (requiring an unlock key to start a stopped manager) | | [`--autolock`](#autolock) | | | Enable manager autolocking (requiring an unlock key to start a stopped manager) |
| `--availability` | `string` | `active` | Availability of the node (`active`, `pause`, `drain`) | | [`--availability`](#availability) | `string` | `active` | Availability of the node (`active`, `pause`, `drain`) |
| `--cert-expiry` | `duration` | `2160h0m0s` | Validity period for node certificates (ns\|us\|ms\|s\|m\|h) | | `--cert-expiry` | `duration` | `2160h0m0s` | Validity period for node certificates (ns\|us\|ms\|s\|m\|h) |
| `--data-path-addr` | `string` | | Address or interface to use for data path traffic (format: `<ip\|interface>`) | | [`--data-path-addr`](#data-path-addr) | `string` | | Address or interface to use for data path traffic (format: `<ip\|interface>`) |
| `--data-path-port` | `uint32` | `0` | Port number to use for data path traffic (1024 - 49151). If no value is set or is set to 0, the default port (4789) is used. | | [`--data-path-port`](#data-path-port) | `uint32` | `0` | Port number to use for data path traffic (1024 - 49151). If no value is set or is set to 0, the default port (4789) is used. |
| `--default-addr-pool` | `ipNetSlice` | | default address pool in CIDR format | | [`--default-addr-pool`](#default-addr-pool) | `ipNetSlice` | | default address pool in CIDR format |
| `--default-addr-pool-mask-length` | `uint32` | `24` | default address pool subnet mask length | | `--default-addr-pool-mask-length` | `uint32` | `24` | default address pool subnet mask length |
| `--dispatcher-heartbeat` | `duration` | `5s` | Dispatcher heartbeat period (ns\|us\|ms\|s\|m\|h) | | `--dispatcher-heartbeat` | `duration` | `5s` | Dispatcher heartbeat period (ns\|us\|ms\|s\|m\|h) |
| `--external-ca` | `external-ca` | | Specifications of one or more certificate signing endpoints | | [`--external-ca`](#external-ca) | `external-ca` | | Specifications of one or more certificate signing endpoints |
| `--force-new-cluster` | | | Force create a new cluster from current state | | [`--force-new-cluster`](#force-new-cluster) | | | Force create a new cluster from current state |
| `--listen-addr` | `node-addr` | `0.0.0.0:2377` | Listen address (format: `<ip\|interface>[:port]`) | | [`--listen-addr`](#listen-addr) | `node-addr` | `0.0.0.0:2377` | Listen address (format: `<ip\|interface>[:port]`) |
| `--max-snapshots` | `uint64` | `0` | Number of additional Raft snapshots to retain | | [`--max-snapshots`](#max-snapshots) | `uint64` | `0` | Number of additional Raft snapshots to retain |
| `--snapshot-interval` | `uint64` | `10000` | Number of log entries between Raft snapshots | | [`--snapshot-interval`](#snapshot-interval) | `uint64` | `10000` | Number of log entries between Raft snapshots |
| `--task-history-limit` | `int64` | `5` | Task history retention limit | | `--task-history-limit` | `int64` | `5` | Task history retention limit |
<!---MARKER_GEN_END--> <!---MARKER_GEN_END-->
## Description ## Description
Initialize a swarm. The docker engine targeted by this command becomes a manager Initialize a swarm. The Docker Engine targeted by this command becomes a manager
in the newly created single-node swarm. in the newly created single-node swarm.
## Examples ## Examples
@ -40,94 +40,91 @@ Swarm initialized: current node (bvz81updecsj6wjz393c09vti) is now a manager.
To add a worker to this swarm, run the following command: To add a worker to this swarm, run the following command:
docker swarm join \ docker swarm join --token SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx 172.17.0.2:2377
--token SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx \
172.17.0.2:2377
To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions. To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.
``` ```
`docker swarm init` generates two random tokens, a worker token and a manager token. When you join The `docker swarm init` command generates two random tokens: a worker token and
a new node to the swarm, the node joins as a worker or manager node based upon the token you pass a manager token. When you join a new node to the swarm, the node joins as a
to [swarm join](swarm_join.md). worker or manager node based upon the token you pass to [swarm
join](swarm_join.md).
After you create the swarm, you can display or rotate the token using After you create the swarm, you can display or rotate the token using
[swarm join-token](swarm_join-token.md). [swarm join-token](swarm_join-token.md).
### `--autolock` ### <a name="autolock"></a> Protect manager keys and data (--autolock)
This flag enables automatic locking of managers with an encryption key. The The `--autolock` flag enables automatic locking of managers with an encryption
private keys and data stored by all managers will be protected by the key. The private keys and data stored by all managers are protected by the
encryption key printed in the output, and will not be accessible without it. encryption key printed in the output, and is inaccessible without it. Make sure
Thus, it is very important to store this key in order to activate a manager to store this key securely, in order to reactivate a manager after it restarts.
after it restarts. The key can be passed to `docker swarm unlock` to reactivate Pass the key to the `docker swarm unlock` command to reactivate the manager.
the manager. Autolock can be disabled by running You can disable autolock by running `docker swarm update --autolock=false`.
`docker swarm update --autolock=false`. After disabling it, the encryption key After disabling it, the encryption key is no longer required to start the
is no longer required to start the manager, and it will start up on its own manager, and it will start up on its own without user intervention.
without user intervention.
### `--cert-expiry` ### <a name=""></a> Configure node healthcheck frequency (--dispatcher-heartbeat)
This flag sets the validity period for node certificates. The `--dispatcher-heartbeat` flag sets the frequency at which nodes are told to
report their health.
### `--dispatcher-heartbeat` ### <a name="external-ca"></a> Use an external certificate authority (--external-ca)
This flag sets the frequency with which nodes are told to use as a This flag sets up the swarm to use an external CA to issue node certificates.
period to report their health. The value takes the form `protocol=X,url=Y`. The value for `protocol` specifies
what protocol should be used to send signing requests to the external CA.
Currently, the only supported value is `cfssl`. The URL specifies the endpoint
where signing requests should be submitted.
### `--external-ca` ### <a name="force-new-cluster"></a> Force-restart node as a single-mode manager (--force-new-cluster)
This flag sets up the swarm to use an external CA to issue node certificates. The value takes This flag forces an existing node that was part of a quorum that was lost to
the form `protocol=X,url=Y`. The value for `protocol` specifies what protocol should be used restart as a single-node Manager without losing its data.
to send signing requests to the external CA. Currently, the only supported value is `cfssl`.
The URL specifies the endpoint where signing requests should be submitted.
### `--force-new-cluster` ### <a name="listen-addr"></a> Specify interface for inbound control plane traffic (--listen-addr)
This flag forces an existing node that was part of a quorum that was lost to restart as a single node Manager without losing its data. The node listens for inbound swarm manager traffic on this address. The default
is to listen on `0.0.0.0:2377`. It is also possible to specify a network
### `--listen-addr` interface to listen on that interface's address; for example `--listen-addr
eth0:2377`.
The node listens for inbound swarm manager traffic on this address. The default is to listen on
0.0.0.0:2377. It is also possible to specify a network interface to listen on that interface's
address; for example `--listen-addr eth0:2377`.
Specifying a port is optional. If the value is a bare IP address or interface Specifying a port is optional. If the value is a bare IP address or interface
name, the default port 2377 will be used. name, the default port 2377 is used.
### `--advertise-addr` ### <a name="advertise-addr"></a> Specify interface for outbound control plane traffic (--advertise-addr)
This flag specifies the address that will be advertised to other members of the The `--advertise-addr` flag specifies the address that will be advertised to
swarm for API access and overlay networking. If unspecified, Docker will check other members of the swarm for API access and overlay networking. If
if the system has a single IP address, and use that IP address with the unspecified, Docker will check if the system has a single IP address, and use
listening port (see `--listen-addr`). If the system has multiple IP addresses, that IP address with the listening port (see `--listen-addr`). If the system
`--advertise-addr` must be specified so that the correct address is chosen for has multiple IP addresses, `--advertise-addr` must be specified so that the
inter-manager communication and overlay networking. correct address is chosen for inter-manager communication and overlay
networking.
It is also possible to specify a network interface to advertise that interface's address; It is also possible to specify a network interface to advertise that
for example `--advertise-addr eth0:2377`. interface's address; for example `--advertise-addr eth0:2377`.
Specifying a port is optional. If the value is a bare IP address or interface Specifying a port is optional. If the value is a bare IP address or interface
name, the default port 2377 will be used. name, the default port 2377 is used.
### `--data-path-addr` ### <a name="data-path-addr"></a> Specify interface for data traffic (--data-path-addr)
This flag specifies the address that global scope network drivers will publish towards The `--data-path-addr` flag specifies the address that global scope network
other nodes in order to reach the containers running on this node. drivers will publish towards other nodes in order to reach the containers
Using this parameter it is then possible to separate the container's data traffic from the running on this node. Using this parameter you can separate the container's
management traffic of the cluster. data traffic from the management traffic of the cluster.
If unspecified, Docker will use the same IP address or interface that is used for the
advertise address.
### `--data-path-port` If unspecified, the IP address or interface of the advertise address is used.
This flag allows you to configure the UDP port number to use for data path ### <a name="data-path-port"></a> Configure port number for data traffic (--data-path-port)
traffic. The provided port number must be within the 1024 - 49151 range. If
this flag is not set or is set to 0, the default port number 4789 is used. The `--data-path-port` flag allows you to configure the UDP port number to use
The data path port can only be configured when initializing the swarm, and for data path traffic. The provided port number must be within the 1024 - 49151
applies to all nodes that join the swarm. range. If this flag isn't set, or if it's set to 0, the default port number
The following example initializes a new Swarm, and configures the data path 4789 is used. The data path port can only be configured when initializing the
port to UDP port 7777; swarm, and applies to all nodes that join the swarm. The following example
initializes a new Swarm, and configures the data path port to UDP port 7777;
```console ```console
$ docker swarm init --data-path-port=7777 $ docker swarm init --data-path-port=7777
@ -146,43 +143,45 @@ Data Path Port: 7777
<...> <...>
``` ```
### `--default-addr-pool` ### <a name="default-addr-pool"></a> Specify default subnet pools (--default-addr-pool)
This flag specifies default subnet pools for global scope networks.
Format example is `--default-addr-pool 30.30.0.0/16 --default-addr-pool 40.40.0.0/16`
### `--default-addr-pool-mask-length` The `--default-addr-pool` flag specifies default subnet pools for global scope
This flag specifies default subnet pools mask length for default-addr-pool. networks. For example, to specify two address pools:
Format example is `--default-addr-pool-mask-length 24`
### `--task-history-limit` ```console
$ docker swarm init \
--default-addr-pool 30.30.0.0/16 \
--default-addr-pool 40.40.0.0/16
```
This flag sets up task history retention limit. Use the `--default-addr-pool-mask-length` flag to specify the default subnet
pools mask length for the subnet pools.
### `--max-snapshots` ### <a name="max-snapshots"></a> Set limit for number of snapshots to keep (--max-snapshots)
This flag sets the number of old Raft snapshots to retain in addition to the This flag sets the number of old Raft snapshots to retain in addition to the
current Raft snapshots. By default, no old snapshots are retained. This option current Raft snapshots. By default, no old snapshots are retained. This option
may be used for debugging, or to store old snapshots of the swarm state for may be used for debugging, or to store old snapshots of the swarm state for
disaster recovery purposes. disaster recovery purposes.
### `--snapshot-interval` ### <a name="snapshot-interval"></a> Configure Raft snapshot log interval (--snapshot-interval)
This flag specifies how many log entries to allow in between Raft snapshots. The `--snapshot-interval` flag specifies how many log entries to allow in
Setting this to a higher number will trigger snapshots less frequently. between Raft snapshots. Setting this to a high number will trigger snapshots
Snapshots compact the Raft log and allow for more efficient transfer of the less frequently. Snapshots compact the Raft log and allow for more efficient
state to new managers. However, there is a performance cost to taking snapshots transfer of the state to new managers. However, there is a performance cost to
frequently. taking snapshots frequently.
### `--availability` ### <a name="availability"></a> Configure the availability of a manager (--availability)
This flag specifies the availability of the node at the time the node joins a master. The `--availability` flag specifies the availability of the node at the time
Possible availability values are `active`, `pause`, or `drain`. the node joins a master. Possible availability values are `active`, `pause`, or
`drain`.
This flag is useful in certain situations. For example, a cluster may want to have This flag is useful in certain situations. For example, a cluster may want to
dedicated manager nodes that are not served as worker nodes. This could be achieved have dedicated manager nodes that don't serve as worker nodes. You can do this
by passing `--availability=drain` to `docker swarm init`. by passing `--availability=drain` to `docker swarm init`.
## Related commands ## Related commands
* [swarm ca](swarm_ca.md) * [swarm ca](swarm_ca.md)

18
docs/reference/commandline/system_df.md
View File

@ -16,11 +16,11 @@ Show docker disk usage
## Description ## Description
The `docker system df` command displays information regarding the The `docker system df` command displays information regarding the
amount of disk space used by the docker daemon. amount of disk space used by the Docker daemon.
## Examples ## Examples
By default the command will just show a summary of the data used: By default the command displays a summary of the data used:
```console ```console
$ docker system df $ docker system df
@ -31,7 +31,7 @@ Containers 2 0 212 B
Local Volumes 2 1 36 B 0 B (0%) Local Volumes 2 1 36 B 0 B (0%)
``` ```
A more detailed view can be requested using the `-v, --verbose` flag: Use the `-v, --verbose` flag to get more detailed information:
```console ```console
$ docker system df -v $ docker system df -v
@ -59,19 +59,19 @@ my-named-vol 0
``` ```
* `SHARED SIZE` is the amount of space that an image shares with another one (i.e. their common data) * `SHARED SIZE` is the amount of space that an image shares with another one (i.e. their common data)
* `UNIQUE SIZE` is the amount of space that is only used by a given image * `UNIQUE SIZE` is the amount of space that's only used by a given image
* `SIZE` is the virtual size of the image, it is the sum of `SHARED SIZE` and `UNIQUE SIZE` * `SIZE` is the virtual size of the image, it's the sum of `SHARED SIZE` and `UNIQUE SIZE`
> **Note** > **Note**
> >
> Network information is not shown because it does not consume disk space. > Network information isn't shown, because it doesn't consume disk space.
## Performance ## Performance
The `system df` command can be very resource-intensive. It traverses the Running the `system df` command can be resource-intensive. It traverses the
filesystem of every image, container, and volume in the system. You should be filesystem of every image, container, and volume in the system. You should be
careful running this command in systems with lots of images, containers, or careful running this command in systems with lots of images, containers, or
volumes or in systems where some images, containers, or volumes have very large volumes or in systems where some images, containers, or volumes have large
filesystems with many files. You should also be careful not to run this command filesystems with many files. You should also be careful not to run this command
in systems where performance is critical. in systems where performance is critical.
@ -92,7 +92,7 @@ Valid placeholders for the Go template are listed below:
When using the `--format` option, the `system df` command outputs When using the `--format` option, the `system df` command outputs
the data exactly as the template declares or, when using the the data exactly as the template declares or, when using the
`table` directive, will include column headers as well. `table` directive, includes column headers as well.
The following example uses a template without headers and outputs the The following example uses a template without headers and outputs the
`Type` and `TotalCount` entries separated by a colon (`:`): `Type` and `TotalCount` entries separated by a colon (`:`):

42
docs/reference/commandline/system_events.md
View File

@ -108,11 +108,11 @@ Docker daemons report the following events:
The `--since` and `--until` parameters can be Unix timestamps, date formatted The `--since` and `--until` parameters can be Unix timestamps, date formatted
timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed 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, 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 the command returns only new and/or live events. Supported formats for date
formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, 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 `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 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 `+-00:00` timezone offset at the end of the timestamp. When providing Unix
timestamps enter seconds[.nanoseconds], where seconds is the number of seconds timestamps enter seconds[.nanoseconds], where seconds is the number of seconds
that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap 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 seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a
@ -124,25 +124,25 @@ The filtering flag (`-f` or `--filter`) format is of "key=value". If you would
like to use multiple filters, pass multiple flags (e.g., like to use multiple filters, pass multiple flags (e.g.,
`--filter "foo=bar" --filter "bif=baz"`) `--filter "foo=bar" --filter "bif=baz"`)
Using the same filter multiple times will be handled as a *OR*; for example Using the same filter multiple times will be handled as a logical `OR`; for example,
`--filter container=588a23dac085 --filter container=a8f7720b8c22` will display `--filter container=588a23dac085 --filter container=a8f7720b8c22` displays
events for container 588a23dac085 *OR* container a8f7720b8c22 events for container `588a23dac085` or container `a8f7720b8c22`.
Using multiple filters will be handled as a *AND*; for example Using multiple filters will be handled as a logical `AND`; for example,
`--filter container=588a23dac085 --filter event=start` will display events for `--filter container=588a23dac085 --filter event=start` displays events for
container container 588a23dac085 *AND* the event type is *start* container `588a23dac085` and where the event type is `start`.
The currently supported filters are: The currently supported filters are:
* container (`container=<name or id>`) - container (`container=<name or id>`)
* daemon (`daemon=<name or id>`) - daemon (`daemon=<name or id>`)
* event (`event=<event action>`) - event (`event=<event action>`)
* image (`image=<tag or id>`) - image (`image=<tag or id>`)
* label (`label=<key>` or `label=<key>=<value>`) - label (`label=<key>` or `label=<key>=<value>`)
* network (`network=<name or id>`) - network (`network=<name or id>`)
* plugin (`plugin=<name or id>`) - plugin (`plugin=<name or id>`)
* type (`type=<container or image or volume or network or daemon or plugin>`) - type (`type=<container or image or volume or network or daemon or plugin>`)
* volume (`volume=<name or id>`) - volume (`volume=<name or id>`)
## Examples ## Examples
@ -181,7 +181,7 @@ To exit the `docker system events` command, use `CTRL+C`.
### Filter events by time ### Filter events by time
You can filter the output by an absolute timestamp or relative time on the host You can filter the output by an absolute timestamp or relative time on the host
machine, using the following different time syntaxes: machine, using the following different time formats:
```console ```console
$ docker system events --since 1483283804 $ docker system events --since 1483283804
@ -307,7 +307,7 @@ $ docker system events --filter 'type=plugin'
### <a name="format"></a> Format the output (--format) ### <a name="format"></a> Format the output (--format)
If a format (`--format`) is specified, the given template will be executed 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) instead of the default format. Go's [text/template](https://pkg.go.dev/text/template)
package describes all the details of the format. package describes all the details of the format.
@ -324,8 +324,8 @@ Type=container Status=destroy ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299
#### Format as JSON #### Format as JSON
If a format is set to `{{json .}}`, the events are streamed as valid JSON If a format is set to `{{json .}}`, events are streamed in the JSON Lines format.
Lines. For information about JSON Lines, please refer to https://jsonlines.org/ . For information about JSON Lines, see <https://jsonlines.org/>.
```console ```console
$ docker system events --format '{{json .}}' $ docker system events --format '{{json .}}'

6
docs/reference/commandline/system_prune.md
View File

@ -17,7 +17,7 @@ Remove unused data
## Description ## Description
Remove all unused containers, networks, images (both dangling and unreferenced), Remove all unused containers, networks, images (both dangling and unused),
and optionally, volumes. and optionally, volumes.
## Examples ## Examples
@ -48,7 +48,7 @@ deleted: sha256:45761469c965421a92a69cc50e92c01e0cfa94fe026cdd1233445ea00e96289a
Total reclaimed space: 1.84kB Total reclaimed space: 1.84kB
``` ```
By default, volumes are not removed to prevent important data from being By default, volumes aren't removed to prevent important data from being
deleted if there is currently no container using the volume. Use the `--volumes` deleted if there is currently no container using the volume. Use the `--volumes`
flag when running the command to prune anonymous volumes as well: flag when running the command to prune anonymous volumes as well:
@ -109,7 +109,7 @@ relative to the daemon machine’s time. Supported formats for date
formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, 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 `2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local
timezone on the daemon will be used if you do not provide either a `Z` or a timezone on the daemon will be used if you do not provide either a `Z` or a
`+-00:00` timezone offset at the end of the timestamp. When providing Unix `+-00:00` timezone offset at the end of the timestamp. When providing Unix
timestamps enter seconds[.nanoseconds], where seconds is the number of seconds timestamps enter seconds[.nanoseconds], where seconds is the number of seconds
that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap 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 seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a

50
docs/reference/commandline/tag.md
View File

@ -17,30 +17,30 @@ A full image name has the following format and components:
`[HOST[:PORT_NUMBER]/]PATH` `[HOST[:PORT_NUMBER]/]PATH`
- `HOST`: The optional registry hostname specifies where the image is located. - `HOST`: The optional registry hostname specifies where the image is located.
The hostname must comply with standard DNS rules, but may not contain The hostname must comply with standard DNS rules, but may not contain
underscores. If the hostname is not specified, the command uses Docker's public 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 registry at `registry-1.docker.io` by default. Note that `docker.io` is the
canonical reference for Docker's public registry. canonical reference for Docker's public registry.
- `PORT_NUMBER`: If a hostname is present, it may optionally be followed by a - `PORT_NUMBER`: If a hostname is present, it may optionally be followed by a
registry port number in the format `:8080`. registry port number in the format `:8080`.
- `PATH`: The path consists of slash-separated components. Each - `PATH`: The path consists of slash-separated components. Each
component may contain lowercase letters, digits and separators. A separator is 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 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 may not start or end with a separator. While the
[OCI Distribution Specification](https://github.com/opencontainers/distribution-spec) [OCI Distribution Specification](https://github.com/opencontainers/distribution-spec)
supports more than two slash-separated components, most registries only support supports more than two slash-separated components, most registries only support
two slash-separated components. For Docker's public registry, the path format is two slash-separated components. For Docker's public registry, the path format is
as follows: as follows:
- `[NAMESPACE/]REPOSITORY`: The first, optional component is typically a - `[NAMESPACE/]REPOSITORY`: The first, optional component is typically a
user's or an organization's namespace. The second, mandatory component is the user's or an organization's namespace. The second, mandatory component is the
repository name. When the namespace is not present, Docker uses `library` repository name. When the namespace is not present, Docker uses `library`
as the default namespace. as the default namespace.
After the image name, the optional `TAG` is a custom, human-readable manifest After the image name, the optional `TAG` is a custom, human-readable manifest
identifier that is typically a specific version or variant of an image. The tag 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, must be valid ASCII and can contain lowercase and uppercase letters, digits,
underscores, periods, and hyphens. It cannot start with a period or hyphen and underscores, periods, and hyphens. It can't start with a period or hyphen and
must be no longer than 128 characters. If the tag is not specified, the command uses `latest` by default. 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 You can group your images together using names and tags, and then
[push](https://docs.docker.com/engine/reference/commandline/push) them to a [push](https://docs.docker.com/engine/reference/commandline/push) them to a
@ -50,8 +50,8 @@ registry.
### Tag an image referenced by ID ### Tag an image referenced by ID
To tag a local image with ID "0e5574283393" as "fedora/httpd" with the tag To tag a local image with ID `0e5574283393` as `fedora/httpd` with the tag
"version1.0": `version1.0`:
```console ```console
$ docker tag 0e5574283393 fedora/httpd:version1.0 $ docker tag 0e5574283393 fedora/httpd:version1.0
@ -59,19 +59,19 @@ $ docker tag 0e5574283393 fedora/httpd:version1.0
### Tag an image referenced by Name ### Tag an image referenced by Name
To tag a local image "httpd" as "fedora/httpd" with the tag "version1.0": To tag a local image `httpd` as `fedora/httpd` with the tag `version1.0`:
```console ```console
$ docker tag httpd fedora/httpd:version1.0 $ docker tag httpd fedora/httpd:version1.0
``` ```
Note that since the tag name is not specified, the alias is created for an Note that since the tag name isn't specified, the alias is created for an
existing local version `httpd:latest`. existing local version `httpd:latest`.
### Tag an image referenced by Name and Tag ### Tag an image referenced by Name and Tag
To tag a local image with the name "httpd" and the tag "test" as "fedora/httpd" To tag a local image with the name `httpd` and the tag `test` as `fedora/httpd`
with the tag "version1.0.test": with the tag `version1.0.test`:
```console ```console
$ docker tag httpd:test fedora/httpd:version1.0.test $ docker tag httpd:test fedora/httpd:version1.0.test
@ -84,4 +84,4 @@ must include the registry hostname and port (if needed).
```console ```console
$ docker tag 0e5574283393 myregistryhost:5000/fedora/httpd:version1.0 $ docker tag 0e5574283393 myregistryhost:5000/fedora/httpd:version1.0
``` ```

4
docs/reference/commandline/trust_key_generate.md
View File

@ -15,7 +15,7 @@ Generate and load a signing key-pair
## Description ## Description
`docker trust key generate` generates a key-pair to be used with signing, `docker trust key generate` generates a key-pair to be used with signing,
and loads the private key into the local docker trust keystore. and loads the private key into the local Docker trust keystore.
## Examples ## Examples
@ -32,7 +32,7 @@ $ ls
alice.pub alice.pub
``` ```
The private signing key is encrypted by the passphrase and loaded into the docker trust keystore. The private signing key is encrypted by the passphrase and loaded into the Docker trust keystore.
All passphrase requests to sign with the key will be referred to by the provided `NAME`. All passphrase requests to sign with the key will be referred to by the provided `NAME`.
The public key component `alice.pub` will be available in the current working directory, and can The public key component `alice.pub` will be available in the current working directory, and can

2
docs/reference/commandline/trust_key_load.md
View File

@ -14,7 +14,7 @@ Load a private key file for signing
## Description ## Description
`docker trust key load` adds private keys to the local docker trust keystore. `docker trust key load` adds private keys to the local Docker trust keystore.
To add a signer to a repository use `docker trust signer add`. To add a signer to a repository use `docker trust signer add`.

2
docs/reference/commandline/trust_revoke.md
View File

@ -20,7 +20,7 @@ Remove trust for an image
### Revoke signatures from a signed tag ### Revoke signatures from a signed tag
Here's an example of a repo with two signed tags: Here's an example of a repository with two signed tags:
```console ```console

6
docs/reference/commandline/trust_sign.md
View File

@ -18,7 +18,7 @@ Sign an image
## Examples ## Examples
### Sign a tag as a repo admin ### Sign a tag as a repository admin
Given an image: Given an image:
@ -125,9 +125,9 @@ Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e
Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949
``` ```
## Initialize a new repo and sign a tag ## Initialize a new repository and sign a tag
When signing an image on a repo for the first time, `docker trust sign` sets up new keys before signing the image. When signing an image on a repository for the first time, `docker trust sign` sets up new keys before signing the image.
```console ```console
$ docker trust inspect --pretty example/trust-demo $ docker trust inspect --pretty example/trust-demo

14
docs/reference/commandline/trust_signer_add.md
View File

@ -18,7 +18,7 @@ Add a signer
## Examples ## Examples
### Add a signer to a repo ### Add a signer to a repository
To add a new signer, `alice`, to this repository: To add a new signer, `alice`, to this repository:
@ -66,9 +66,9 @@ Repository Key: 642692c14c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e
Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949
``` ```
## Initialize a new repo and add a signer ## Initialize a new repository and add a signer
When adding a signer on a repo for the first time, `docker trust signer add` sets up a new repo if it doesn't exist. When adding a signer on a repository for the first time, `docker trust signer add` sets up a new repository if it doesn't exist.
```console ```console
$ docker trust inspect --pretty example/trust-demo $ docker trust inspect --pretty example/trust-demo
@ -107,8 +107,10 @@ Repository Key: 95b9e5565eac3ef5ec01406801bdfb70feb40c17808d2222427c18046eb63beb
Root Key: 748121c14bd1461f6c58cb3ef39087c8fdc7633bb11a98af844fd9a04e208103 Root Key: 748121c14bd1461f6c58cb3ef39087c8fdc7633bb11a98af844fd9a04e208103
``` ```
## Add a signer to multiple repos ## Add a signer to multiple repositories
To add a signer, `alice`, to multiple repositories: To add a signer, `alice`, to multiple repositories:
```console ```console
$ docker trust inspect --pretty example/trust-demo $ docker trust inspect --pretty example/trust-demo
@ -192,8 +194,8 @@ Repository Key: ece554f14c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4553d2ab20a8d926
Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949
``` ```
`docker trust signer add` adds signers to repositories on a best effort basis.
`docker trust signer add` adds signers to repositories on a best effort basis, so it will continue to add the signer to subsequent repositories if one attempt fails: It continues to add the signer to subsequent repositories if one attempt fails:
```console ```console
$ docker trust signer add alice example/unauthorized example/authorized --key alice.crt $ docker trust signer add alice example/unauthorized example/authorized --key alice.crt

12
docs/reference/commandline/trust_signer_remove.md
View File

@ -18,7 +18,7 @@ Remove a signer
## Examples ## Examples
### Remove a signer from a repo ### Remove a signer from a repository
To remove an existing signer, `alice`, from this repository: To remove an existing signer, `alice`, from this repository:
@ -49,7 +49,7 @@ Enter passphrase for repository key with ID 642692c:
Successfully removed alice from example/trust-demo Successfully removed alice from example/trust-demo
``` ```
`docker trust inspect --pretty` now does not list `alice` as a valid signer: `docker trust inspect --pretty` now doesn't list `alice` as a valid signer:
```console ```console
$ docker trust inspect --pretty example/trust-demo $ docker trust inspect --pretty example/trust-demo
@ -67,7 +67,7 @@ Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e
Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949
``` ```
### Remove a signer from multiple repos ### Remove a signer from multiple repositories
To remove an existing signer, `alice`, from multiple repositories: To remove an existing signer, `alice`, from multiple repositories:
@ -154,9 +154,8 @@ Repository Key: ece554f14c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4553d2ab20a8d926
Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949
``` ```
`docker trust signer remove` removes signers to repositories on a best effort `docker trust signer remove` removes signers to repositories on a best effort basis.
basis, so it will continue to remove the signer from subsequent repositories if It continues to remove the signer from subsequent repositories if one attempt fails:
one attempt fails:
```console ```console
$ docker trust signer remove alice example/unauthorized example/authorized $ docker trust signer remove alice example/unauthorized example/authorized
@ -170,4 +169,3 @@ Successfully removed alice from example/authorized
Error removing signer from: example/unauthorized Error removing signer from: example/unauthorized
``` ```

29
docs/reference/commandline/volume_create.md
View File

@ -41,23 +41,23 @@ hello
$ docker run -d -v hello:/world busybox ls /world $ docker run -d -v hello:/world busybox ls /world
``` ```
The mount is created inside the container's `/world` directory. Docker does not The mount is created inside the container's `/world` directory. Docker doesn't
support relative paths for mount points inside the container. support relative paths for mount points inside the container.
Multiple containers can use the same volume in the same time period. This is Multiple containers can use the same volume. This is useful if two containers
useful if two containers need access to shared data. For example, if one need access to shared data. For example, if one container writes and the other
container writes and the other reads the data. reads the data.
Volume names must be unique among drivers. This means you cannot use the same Volume names must be unique among drivers. This means you can't use the same
volume name with two different drivers. If you attempt this `docker` returns an volume name with two different drivers. Attempting to create two volumes with
error: the same name results in an error:
```console ```console
A volume named "hello" already exists with the "some-other" driver. Choose a different volume name. A volume named "hello" already exists with the "some-other" driver. Choose a different volume name.
``` ```
If you specify a volume name already in use on the current driver, Docker If you specify a volume name already in use on the current driver, Docker
assumes you want to re-use the existing volume and does not return an error. assumes you want to re-use the existing volume and doesn't return an error.
### <a name="opt"></a> Driver-specific options (-o, --opt) ### <a name="opt"></a> Driver-specific options (-o, --opt)
@ -74,13 +74,12 @@ $ docker volume create --driver fake \
These options are passed directly to the volume driver. Options for These options are passed directly to the volume driver. Options for
different volume drivers may do different things (or nothing at all). different volume drivers may do different things (or nothing at all).
The built-in `local` driver on Windows does not support any options. The built-in `local` driver accepts no options on Windows. On Linux and with
Docker Desktop, the `local` driver accepts options similar to the Linux `mount`
The built-in `local` driver on Linux accepts options similar to the linux command. You can provide multiple options by passing the `--opt` flag multiple
`mount` command. You can provide multiple options by passing the `--opt` flag times. Some `mount` options (such as the `o` option) can take a comma-separated
multiple times. Some `mount` options (such as the `o` option) can take a list of options. Complete list of available mount options can be found
comma-separated list of options. Complete list of available mount options can be [here](https://man7.org/linux/man-pages/man8/mount.8.html).
found [here](https://man7.org/linux/man-pages/man8/mount.8.html).
For example, the following creates a `tmpfs` volume called `foo` with a size of For example, the following creates a `tmpfs` volume called `foo` with a size of
100 megabyte and `uid` of 1000. 100 megabyte and `uid` of 1000.

4
docs/reference/commandline/volume_ls.md
View File

@ -52,7 +52,7 @@ than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "b
The currently supported filters are: The currently supported filters are:
- dangling (boolean - true or false, 0 or 1) - dangling (Boolean - true or false, 0 or 1)
- driver (a volume driver's name) - driver (a volume driver's name)
- label (`label=<key>` or `label=<key>=<value>`) - label (`label=<key>` or `label=<key>=<value>`)
- name (a volume's name) - name (a volume's name)
@ -89,7 +89,7 @@ local tyler
The `label` filter matches volumes based on the presence of a `label` alone or The `label` filter matches volumes based on the presence of a `label` alone or
a `label` and a value. a `label` and a value.
First, let's create some volumes to illustrate this; First, create some volumes to illustrate this;
```console ```console
$ docker volume create the-doctor --label is-timelord=yes $ docker volume create the-doctor --label is-timelord=yes

1
docs/reference/commandline/volume_prune.md
View File

@ -51,7 +51,6 @@ which removes volumes with the specified labels. The other
format is the `label!=...` (`label!=<key>` or `label!=<key>=<value>`), which removes format is the `label!=...` (`label!=<key>` or `label!=<key>=<value>`), which removes
volumes without the specified labels. volumes without the specified labels.
## Related commands ## Related commands
* [volume create](volume_create.md) * [volume create](volume_create.md)

2
docs/reference/commandline/volume_rm.md
View File

@ -20,7 +20,7 @@ Remove one or more volumes. You cannot remove a volume that is in use by a conta
## Description ## Description
Remove one or more volumes. You cannot remove a volume that is in use by a container. Remove one or more volumes. You can't remove a volume that's in use by a container.
## Examples ## Examples

4
docs/reference/run.md
View File

@ -1207,7 +1207,7 @@ The health status is also displayed in the `docker ps` output.
### User ### User
The default user within a container is `root` (id = 0). You can set a default The default user within a container is `root` (uid = 0). You can set a default
user to run the first process with the Dockerfile `USER` instruction. When user to run the first process with the Dockerfile `USER` instruction. When
starting a container, you can override the `USER` instruction by passing the starting a container, you can override the `USER` instruction by passing the
`-u` option. `-u` option.
@ -1240,4 +1240,4 @@ $ docker run --rm -w /my/workdir alpine pwd
/my/workdir /my/workdir
``` ```
If the directory doesn't already exist in the container, it will be created. If the directory doesn't already exist in the container, it's created.