From 6fd4cff1f7da68a78d3c5933fe7d5c194b85db97 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 13 Dec 2023 15:16:56 +0100 Subject: [PATCH] docs: minor editorial improvements, typo fixes Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- docs/reference/commandline/attach.md | 79 ++-- docs/reference/commandline/build.md | 65 ++-- docs/reference/commandline/checkpoint.md | 14 +- docs/reference/commandline/cli.md | 56 ++- docs/reference/commandline/commit.md | 15 +- docs/reference/commandline/config_create.md | 3 +- docs/reference/commandline/config_inspect.md | 3 +- docs/reference/commandline/config_ls.md | 4 +- docs/reference/commandline/config_rm.md | 9 +- docs/reference/commandline/container_prune.md | 2 +- docs/reference/commandline/context_create.md | 14 +- docs/reference/commandline/context_use.md | 2 +- docs/reference/commandline/cp.md | 6 +- docs/reference/commandline/create.md | 8 +- docs/reference/commandline/dockerd.md | 367 +++++++++--------- docs/reference/commandline/events.md | 65 ++-- docs/reference/commandline/exec.md | 28 +- docs/reference/commandline/export.md | 6 +- docs/reference/commandline/history.md | 6 +- docs/reference/commandline/run.md | 71 ++-- docs/reference/commandline/swarm_init.md | 197 +++++----- docs/reference/commandline/system_df.md | 18 +- docs/reference/commandline/system_events.md | 42 +- docs/reference/commandline/system_prune.md | 6 +- docs/reference/commandline/tag.md | 50 +-- .../commandline/trust_key_generate.md | 4 +- docs/reference/commandline/trust_key_load.md | 2 +- docs/reference/commandline/trust_revoke.md | 2 +- docs/reference/commandline/trust_sign.md | 6 +- .../reference/commandline/trust_signer_add.md | 14 +- .../commandline/trust_signer_remove.md | 12 +- docs/reference/commandline/volume_create.md | 29 +- docs/reference/commandline/volume_ls.md | 4 +- docs/reference/commandline/volume_prune.md | 1 - docs/reference/commandline/volume_rm.md | 2 +- docs/reference/run.md | 4 +- 36 files changed, 596 insertions(+), 620 deletions(-) diff --git a/docs/reference/commandline/attach.md b/docs/reference/commandline/attach.md index e3b0e338a6..a0810305d9 100644 --- a/docs/reference/commandline/attach.md +++ b/docs/reference/commandline/attach.md @@ -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 (or any combination of the three) to a running container using the container's -ID or name. This allows you to view its ongoing output or to control it -interactively, as though the commands were running directly in your terminal. +ID or name. This lets you view its output or control it interactively, as +though the commands were running directly in your terminal. -> **Note:** -> The `attach` command will display the output of the `ENTRYPOINT/CMD` process. This -> can appear as if the attach command is hung when in fact the process may simply -> not be interacting with the terminal at that time. +> **Note** +> +> The `attach` command displays the output of the container's `ENTRYPOINT` and +> `CMD` process. This can appear as if the attach command is hung when in fact +> the process may simply not be writing any output at that time. You can attach to the same contained process multiple times simultaneously, from different sessions on the Docker host. @@ -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 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 > Linux: it ignores any signal with the default action. So, the process -> will not terminate on `SIGINT` or `SIGTERM` unless it is coded to do -> so. +> doesn't terminate on `SIGINT` or `SIGTERM` unless it's coded to do so. -It is forbidden to redirect the standard input of a `docker attach` command -while attaching to a TTY-enabled container (using the `-i` and `-t` options). +You can't redirect the standard input of a `docker attach` command while +attaching to a TTY-enabled container (using the `-i` and `-t` options). -While a client is connected to container's `stdio` using `docker attach`, Docker -uses a ~1MB memory buffer to maximize the throughput of the application. +While a client is connected to container's `stdio` using `docker attach`, +Docker uses a ~1MB memory buffer to maximize the throughput of the application. Once this buffer is full, the speed of the API connection is affected, and so this impacts the output process' writing speed. This is similar to other -applications like SSH. Because of this, it is not recommended to run -performance critical applications that generate a lot of output in the -foreground over a slow client connection. Instead, users should use the -`docker logs` command to get access to the logs. +applications like SSH. Because of this, it isn't recommended to run +performance-critical applications that generate a lot of output in the +foreground over a slow client connection. Instead, use the `docker logs` +command to get access to the logs. ## Examples ### Attach to and detach from a running container -The following example starts an ubuntu container running `top` in detached mode, +The following example starts an Alpine container running `top` in detached mode, then attaches to the container; ```console -$ docker run -d --name topdemo ubuntu:22.04 /usr/bin/top -b +$ docker run -d --name topdemo alpine top -b $ docker attach topdemo -top - 12:27:44 up 3 days, 21:54, 0 users, load average: 0.00, 0.00, 0.00 -Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie -%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 -MiB Mem : 3934.3 total, 770.1 free, 674.2 used, 2490.1 buff/cache -MiB Swap: 1024.0 total, 839.3 free, 184.7 used. 2814.0 avail Mem - - 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 +Mem: 2395856K used, 5638884K free, 2328K shrd, 61904K buff, 1524264K cached +CPU: 0% usr 0% sys 0% nic 99% idle 0% io 0% irq 0% sirq +Load average: 0.15 0.06 0.01 1/567 6 + PID PPID USER STAT VSZ %VSZ CPU %CPU COMMAND + 1 0 root R 1700 0% 3 0% top -b ``` As the container was started without the `-i`, and `-t` options, signals are @@ -85,14 +83,15 @@ container: ```console <...> - 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^P^Q + PID PPID USER STAT VSZ %VSZ CPU %CPU COMMAND + 1 0 root R 1700 0% 7 0% top -b +^P^Q ^C $ docker ps -a --filter name=topdemo -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -4cf0d0ebb079 ubuntu:22.04 "/usr/bin/top -b" About a minute ago Exited (0) About a minute ago topdemo +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +96254a235bd6 alpine "top -b" 44 seconds ago Exited (130) 8 seconds ago topdemo ``` Repeating the example above, but this time with the `-i` and `-t` options set; @@ -109,19 +108,17 @@ with `docker ps` shows that the container is still running in the background: ```console $ docker attach topdemo2 -top - 12:44:32 up 3 days, 22:11, 0 users, load average: 0.00, 0.00, 0.00 -Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie -%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 -MiB Mem : 3934.3 total, 770.6 free, 672.4 used, 2491.4 buff/cache -MiB Swap: 1024.0 total, 839.3 free, 184.7 used. 2815.8 avail Mem - - 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 +Mem: 2405344K used, 5629396K free, 2512K shrd, 65100K buff, 1524952K cached +CPU: 0% usr 0% sys 0% nic 99% idle 0% io 0% irq 0% sirq +Load average: 0.12 0.12 0.05 1/594 6 + PID PPID USER STAT VSZ %VSZ CPU %CPU COMMAND + 1 0 root R 1700 0% 3 0% top -b +read escape sequence $ docker ps -a --filter name=topdemo2 -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -b1661dce0fc2 ubuntu:22.04 "/usr/bin/top -b" 2 minutes ago Up 2 minutes topdemo2 +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +fde88b83c2c2 alpine "top -b" 22 seconds ago Up 21 seconds topdemo2 ``` ### Get the exit code of the container's command diff --git a/docs/reference/commandline/build.md b/docs/reference/commandline/build.md index c636a794d3..5963d9bb2b 100644 --- a/docs/reference/commandline/build.md +++ b/docs/reference/commandline/build.md @@ -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 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 that succeeds, the directory is sent to the Docker daemon as the context. Local copy gives you the ability to access private repositories using local -user credentials, VPN's, and so forth. +user credentials, VPNs, and so forth. > **Note** > @@ -100,18 +100,18 @@ 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 $ docker build http://server/context.tar.gz ``` The download operation will be performed on the host the Docker daemon is -running on, which is not necessarily the same host from which the build command +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 build context. Tarball contexts must be tar archives conforming to the standard -`tar` UNIX format and can be compressed with any one of the 'xz', 'bzip2', -'gzip' or 'identity' (no compression) formats. +`tar` Unix format and can be compressed with any one of the `xz`, `bzip2`, +`gzip` or `identity` (no compression) formats. ### Text files @@ -122,7 +122,7 @@ Instead of specifying a context, you can pass a single `Dockerfile` in the $ docker build - < Dockerfile ``` -With Powershell on Windows, you can run: +With PowerShell on Windows, you can run: ```powershell 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 an alternative file to use instead. This is useful in cases where the same set of files are used for multiple builds. The path must be to a file within the -build context. If a relative path is specified then it is interpreted as -relative to the root of the context. +build context. Relative path are interpreted as relative to the root of the context. In most cases, it's best to put each Dockerfile in an empty directory. Then, add to that directory only the files needed for building the Dockerfile. To @@ -152,8 +151,7 @@ running at the time the build is cancelled, the pull is cancelled as well. ## Return code -On a successful build, a return code of success `0` will be returned. When the -build fails, a non-zero failure code will be returned. +Successful builds return exit code `0`. Failed builds return a non-zero exit code. There should be informational output of the reason for failure output to `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. Remember that the daemon could be running on a remote machine and that no parsing of the Dockerfile happens at the client side (where you're running -`docker build`). That means that *all* the files at `PATH` get sent, not just -the ones listed to [*ADD*](https://docs.docker.com/engine/reference/builder/#add) +`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) in the Dockerfile. The transfer of context from the local machine to the Docker daemon is what the `docker` client means when you see the "Sending build context" message. If you wish to keep the intermediate containers after the build is complete, -you must use `--rm=false`. This does not affect the build cache. +you must use `--rm=false`. This doesn't affect the build cache. ### Build with URL @@ -252,7 +250,7 @@ Successfully built 377c409b35e4 This sends the URL `http://server/ctx.tar.gz` to the Docker daemon, which downloads and extracts the referenced tarball. The `-f ctx/Dockerfile` -parameter specifies a path inside `ctx.tar.gz` to the `Dockerfile` that is used +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 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 @@ -274,7 +272,7 @@ $ docker build - < context.tar.gz ``` 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 @@ -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 to ignore different sets of files. - ### Tag an image (-t, --tag) ```console @@ -375,12 +372,12 @@ the command line. > **Note** > > `docker build` returns a `no such file or directory` error if the -> file or directory does not exist in the uploaded context. This may -> happen if there is no context, or if you specify a file that is +> file or directory doesn't exist in the uploaded context. This may +> happen if there is no context, or if you specify a file that's > elsewhere on the Host system. The context is limited to the current > directory (and its children) for security reasons, and to ensure > repeatable builds on remote Docker hosts. This is also the reason why -> `ADD ../file` does not work. +> `ADD ../file` doesn't work. ### 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 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. 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 accessed like regular environment variables in the `RUN` instruction of the Dockerfile. Also, these values don't persist in the intermediate or final images -like `ENV` values do. You must add `--build-arg` for each build argument. +like `ENV` values do. You must add `--build-arg` for each build argument. Using this flag will not alter the output you see when the `ARG` lines from the Dockerfile are echoed during the build process. @@ -638,15 +635,14 @@ $ docker build --cache-from myname/myapp . #### Overview Once the image is built, squash the new layers into a new image with a single -new layer. Squashing does not destroy any existing image, rather it creates a new +new layer. Squashing doesn't destroy any existing image, rather it creates a new image with the content of the squashed layers. This effectively makes it look like all `Dockerfile` commands were created with a single layer. The build 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. - Squashing layers can be beneficial if your Dockerfile produces multiple layers modifying the same files, for example, files that are created in one step, and removed in another step. For other use-cases, squashing images may actually have @@ -656,15 +652,14 @@ images (saving space). For most use cases, multi-stage builds are a better alternative, as they give more fine-grained control over your build, and can take advantage of future -optimizations in the builder. Refer to the [use multi-stage builds](https://docs.docker.com/develop/develop-images/multistage-build/) -section in the userguide for more information. - +optimizations in the builder. Refer to the [Multi-stage builds](https://docs.docker.com/build/building/multi-stage/) +section for more information. #### Known limitations The `--squash` option has a number of known limitations: -- When squashing layers, the resulting image 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 base image is still supported. - 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. - While squashing layers may produce smaller images, it may have a negative impact on performance, as a single layer takes longer to extract, and - downloading a single layer cannot be parallelized. -- When attempting to squash an image that does not make changes to the + downloading a single layer can't be parallelized. +- When attempting to squash an image that doesn't make changes to the filesystem (for example, the Dockerfile only contains `ENV` instructions), the squash step will fail (see [issue #33823](https://github.com/moby/moby/issues/33823)). @@ -686,7 +681,7 @@ the Docker daemon or setting `experimental: true` in the `daemon.json` configura file. By default, experimental mode is disabled. To see the current configuration of -the docker daemon, use the `docker version` command and check the `Experimental` +the Docker daemon, use the `docker version` command and check the `Experimental` line in the `Engine` section: ```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. -#### Enable Docker experimental +#### Enable experimental features To enable experimental features, you need to start the Docker daemon with `--experimental` flag. You can also enable the daemon flag via @@ -735,7 +730,7 @@ true #### 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 FROM busybox diff --git a/docs/reference/commandline/checkpoint.md b/docs/reference/commandline/checkpoint.md index 93444d023d..052eec51ff 100644 --- a/docs/reference/commandline/checkpoint.md +++ b/docs/reference/commandline/checkpoint.md @@ -18,7 +18,7 @@ Manage checkpoints ## Description 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. 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 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). @@ -91,17 +91,17 @@ abc0123 ``` 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 -increases while the process is running, stops while it's checkpointed, and +in-between running/checkpoint/restoring, you should see that the counter +increases while the process is running, stops while it's frozen, and resumes from the point it left off once you restore. ### 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, -it would fail: +it fails: ```console $ docker checkpoint create cr checkpoint1 diff --git a/docs/reference/commandline/cli.md b/docs/reference/commandline/cli.md index cf4bbc6801..b40590f156 100644 --- a/docs/reference/commandline/cli.md +++ b/docs/reference/commandline/cli.md @@ -156,7 +156,7 @@ By default, the Docker command line stores its configuration files in a directory called `.docker` within your `$HOME` 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` 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 variables override properties you specify in a `config.json` file. - ### Change the `.docker` directory 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. > **Warning** -> +> > The configuration file and other files inside the `~/.docker` configuration > directory may contain sensitive information, such as authentication information > 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 -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. -| 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. | -| `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. | -| `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. | -| `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. | -| `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. | -| `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. | -| `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. | -| `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. | -| `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. | - +| Property | Description | +| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `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. See [`docker images`](images.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. 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. See [`docker ps`](ps.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. See [`docker service inspect`](service_inspect.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. See [`docker stats`](stats.md#format) for a list of supported formatting directives. | ### Custom HTTP headers 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 not allow these headers to change any headers it sets for itself. - ### Credential store options The property `credsStore` specifies an external binary to serve as the default credential store. When this property is set, `docker login` will attempt to store credentials in the binary specified by `docker-credential-` which -is visible on `$PATH`. If this property is not set, credentials will be stored -in the `auths` property of the config. For more information, see the -[**Credential stores** section in the `docker login` documentation](login.md#credential-stores) +is visible on `$PATH`. If this property isn't set, credentials are stored +in the `auths` property of the CLI configuration file. For more information, +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 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 [**Credential helpers** section in the `docker login` documentation](login.md#credential-helpers) - ### Automatic proxy configuration for containers The property `proxies` specifies proxy environment variables to be automatically 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 -daemon that the client connects to, or a configuration per host (docker daemon), -for example, "https://docker-daemon1.example.com". The following properties can +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), +for example, `https://docker-daemon1.example.com`. The following properties can be set for each environment: | 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. > **Warning** -> +> > Proxy settings may contain sensitive information (for example, if the proxy > requires authentication). Environment variables are stored as plain text in > the container's configuration, and as such can be inspected through the remote > API or committed to an image when using `docker commit`. +{ .warning } ### 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) * `[` (left bracket) * `\\` (two backward slashes) -* `_` (underscore) +* `_` (underscore) * `^` (caret) 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 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 key is the plugin name, while the value is a further map of options, which are specific to that plugin. - ### Sample configuration file 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 Certificate Authority, you need to place the certificate at -`tls//ca.crt` in your docker config directory. +`tls//ca.crt` in your Docker config directory. Alternatively you can trust the certificate globally by adding it to your system's list of root Certificate Authorities. diff --git a/docs/reference/commandline/commit.md b/docs/reference/commandline/commit.md index 353da72e4a..ff1c458e1a 100644 --- a/docs/reference/commandline/commit.md +++ b/docs/reference/commandline/commit.md @@ -22,21 +22,18 @@ Create a new image from a container's changes ## Description It can be useful to commit a container's file changes or settings into a new -image. This allows you to debug a container by running an interactive shell, or to -export a working dataset to another server. Generally, it is better to use -Dockerfiles to manage your images in a documented and maintainable way. -[Read more about valid image names and tags](tag.md). +image. This lets you debug a container by running an interactive shell, or +export a working dataset to another server. -The commit operation will not include any data contained in -volumes mounted inside the container. +Commits do not include any data contained in mounted volumes. By default, the container being committed and its processes will be paused while the image is committed. This reduces the likelihood of encountering data -corruption during the process of creating the commit. If this behavior is +corruption during the process of creating the commit. If this behavior is undesired, set the `--pause` option to false. -The `--change` option will apply `Dockerfile` instructions to the image that is -created. Supported `Dockerfile` instructions: +The `--change` option will apply `Dockerfile` instructions to the image that's +created. Supported `Dockerfile` instructions: `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`LABEL`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` ## Examples diff --git a/docs/reference/commandline/config_create.md b/docs/reference/commandline/config_create.md index c7465dbb1d..55ffd3bdf1 100644 --- a/docs/reference/commandline/config_create.md +++ b/docs/reference/commandline/config_create.md @@ -21,7 +21,7 @@ For detailed information about using configs, refer to [store configuration data > **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 > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the > documentation. @@ -88,7 +88,6 @@ $ docker config inspect my_config ] ``` - ## Related commands * [config inspect](config_inspect.md) diff --git a/docs/reference/commandline/config_inspect.md b/docs/reference/commandline/config_inspect.md index 7f5a9f6ba5..5758d3dbec 100644 --- a/docs/reference/commandline/config_inspect.md +++ b/docs/reference/commandline/config_inspect.md @@ -27,7 +27,7 @@ For detailed information about using configs, refer to [store configuration data > **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 > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the > documentation. @@ -86,7 +86,6 @@ $ docker config inspect --format='{{.CreatedAt}}' eo7jnzguqgtpdah3cm5srfb97 2017-03-24 08:15:09.735271783 +0000 UTC ``` - ## Related commands * [config create](config_create.md) diff --git a/docs/reference/commandline/config_ls.md b/docs/reference/commandline/config_ls.md index 68c36404ad..be9ddb7411 100644 --- a/docs/reference/commandline/config_ls.md +++ b/docs/reference/commandline/config_ls.md @@ -20,13 +20,13 @@ List configs ## 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/). > **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 > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the > documentation. diff --git a/docs/reference/commandline/config_rm.md b/docs/reference/commandline/config_rm.md index d5b7380c88..455e7ba7c9 100644 --- a/docs/reference/commandline/config_rm.md +++ b/docs/reference/commandline/config_rm.md @@ -12,13 +12,13 @@ Remove one or more configs ## 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/). > **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 > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the > documentation. @@ -34,9 +34,8 @@ sapth4csdo5b6wz2p5uimh5xg > **Warning** > -> Unlike `docker rm`, this command does not ask for confirmation before removing -> a config. - +> This command doesn't ask for confirmation before removing a config. +{ .warning } ## Related commands diff --git a/docs/reference/commandline/container_prune.md b/docs/reference/commandline/container_prune.md index 179a4e23d2..0e9cf251c9 100644 --- a/docs/reference/commandline/container_prune.md +++ b/docs/reference/commandline/container_prune.md @@ -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`, `2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local timezone on the daemon will be used if you do not provide either a `Z` or a -`+-00:00` timezone offset at the end of the timestamp. When providing Unix +`+-00:00` timezone offset at the end of the timestamp. When providing Unix timestamps enter seconds[.nanoseconds], where seconds is the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a diff --git a/docs/reference/commandline/context_create.md b/docs/reference/commandline/context_create.md index ae35fad844..738c6cd8cc 100644 --- a/docs/reference/commandline/context_create.md +++ b/docs/reference/commandline/context_create.md @@ -31,16 +31,16 @@ $ docker context create my-context --description "some description" --docker "ho ## Description -Creates a new `context`. This allows you to quickly switch the cli -configuration to connect to different clusters or single nodes. +Creates a new `context`. This lets you switch the daemon your `docker` CLI +connects to. ## Examples -### Create a context with a docker endpoint (--docker) +### Create a context with a Docker endpoint (--docker) -To create a context from scratch provide the docker and, if required, -kubernetes options. The example below creates the context `my-context` -with a docker endpoint of `/var/run/docker.sock`: +Use the `--docker` flag to create a context with a custom endpoint. The +following example creates a context named `my-context` with a docker endpoint +of `/var/run/docker.sock`: ```console $ docker context create \ @@ -58,7 +58,7 @@ from the existing context `existing-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 $ docker context create my-context diff --git a/docs/reference/commandline/context_use.md b/docs/reference/commandline/context_use.md index 32b33628d3..871a5d2db5 100644 --- a/docs/reference/commandline/context_use.md +++ b/docs/reference/commandline/context_use.md @@ -9,5 +9,5 @@ Set the current docker context ## Description 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. diff --git a/docs/reference/commandline/cp.md b/docs/reference/commandline/cp.md index 37697de169..bf3741d8b2 100644 --- a/docs/reference/commandline/cp.md +++ b/docs/reference/commandline/cp.md @@ -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 to the user and primary group at the source. If you specify the `-L` option, `docker cp` follows any symbolic link -in the `SRC_PATH`. `docker cp` does *not* create parent directories for -`DEST_PATH` if they do not exist. +in the `SRC_PATH`. `docker cp` doesn't create parent directories for +`DEST_PATH` if they don't exist. Assuming a path separator of `/`, a first argument of `SRC_PATH` and second argument of `DEST_PATH`, the behavior is as follows: @@ -111,7 +111,7 @@ $ docker cp CONTAINER:/var/logs/app.log - | tar x -O | grep "ERROR" ### 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 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 diff --git a/docs/reference/commandline/create.md b/docs/reference/commandline/create.md index a964390840..6b598a8398 100644 --- a/docs/reference/commandline/create.md +++ b/docs/reference/commandline/create.md @@ -120,14 +120,14 @@ Create a new container The `docker container create` (or shorthand: `docker create`) command creates a new container from the specified image, without starting it. -When creating a container, the docker daemon creates a writeable container layer -over the specified image and prepares it for running the specified command. The -container ID is then printed to `STDOUT`. This is similar to `docker run -d` +When creating a container, the Docker daemon creates a writeable container layer +over the specified image and prepares it for running the specified command. The +container ID is then printed to `STDOUT`. This is similar to `docker run -d` except the container is never started. You can then use the `docker container start` (or shorthand: `docker start`) command to start the container at any point. This is useful when you want to set up a container configuration ahead of time -so that it 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`. The `docker create` command shares most of its options with the `docker run` diff --git a/docs/reference/commandline/dockerd.md b/docs/reference/commandline/dockerd.md index 2aa4eabaad..313332bde3 100644 --- a/docs/reference/commandline/dockerd.md +++ b/docs/reference/commandline/dockerd.md @@ -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). > **Enabling experimental features** -> +> > Enable experimental features by starting `dockerd` with the `--experimental` > 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_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_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. | @@ -150,7 +150,7 @@ by the `dockerd` command line: ### Proxy configuration > **Note** -> +> > 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/). @@ -160,10 +160,10 @@ operations such as pulling and pushing images. The daemon can be configured in three ways: 1. Using environment variables (`HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`). -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). +2. Using the `http-proxy`, `https-proxy`, and `no-proxy` fields in the + [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 - 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 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 membership. -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 -un-authenticated direct access to the Docker daemon - and should be secured -either using the [built in HTTPS encrypted socket](https://docs.docker.com/engine/security/https/), or by -putting a secure web proxy in front of it. You can listen on port `2375` on all +If you need to access the Docker daemon remotely, you need to enable the tcp +Socket. When using a TCP socket, the Docker daemon provides un-encrypted and +un-authenticated direct access to the Docker daemon by default. You should secure +the daemon either using the [built in HTTPS encrypted socket](https://docs.docker.com/engine/security/protect-access/), +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 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 @@ -191,28 +191,28 @@ communication with the daemon. > **Note** > > 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 -> supported anymore for security reasons. +> TLS version 1.0 and higher is supported. Protocols SSLv3 and below are not +> supported for security reasons. -On Systemd based systems, you can communicate with the daemon via -[Systemd socket activation](https://0pointer.de/blog/projects/socket-activation.html), -use `dockerd -H fd://`. Using `fd://` will work perfectly for most setups but +On systemd based systems, you can communicate with the daemon via +[systemd socket activation](https://0pointer.de/blog/projects/socket-activation.html), +with `dockerd -H fd://`. Using `fd://` works for most setups, but 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 -find examples of using Systemd socket activation with Docker and Systemd in the +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 [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 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: ```console $ 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: ```console @@ -236,7 +236,7 @@ $ export DOCKER_TLS_VERIFY=1 $ 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 precedence over `HTTP_PROXY`. @@ -258,29 +258,28 @@ supported. If your key is protected with passphrase, you need to set up > **Warning** > -> Changing the default `docker` daemon binding to a -> TCP port or Unix *docker* user group will increase your security risks -> by allowing non-root users to gain *root* access on the host. Make sure -> you control access to `docker`. If you are binding -> to a TCP port, anyone with access to that port has full Docker access; -> so it is not advisable on an open network. -{: .warning :} +> Changing the default `docker` daemon binding to a TCP port or Unix `docker` +> user group introduces security risks, as it may allow non-root users to gain +> root access on the host. Make sure you control access to `docker`. If you are +> binding to a TCP port, anyone with access to that port has full Docker +> access; so it's not advisable on an open network. +{ .warning } -With `-H` it is possible to make the Docker daemon to listen on a -specific IP and port. By default, it will listen on -`unix:///var/run/docker.sock` to allow only local connections by the -*root* user. You *could* set it to `0.0.0.0:2375` or a specific host IP -to give access to everybody, but that is **not recommended** because -then it is trivial for someone to gain root access to the host where the -daemon is running. +With `-H` it's possible to make the Docker daemon to listen on a specific IP +and port. By default, it listens on `unix:///var/run/docker.sock` to allow +only local connections by the root user. You could set it to `0.0.0.0:2375` or +a specific host IP to give access to everybody, but that isn't recommended +because someone could gain root access to the host where the daemon is running. 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. `-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: @@ -293,7 +292,7 @@ For example: - `unix://path/to/socket` -> Unix socket located 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. `-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` -Set zfs filesystem under which docker will create its own datasets. -By default docker will pick up the zfs filesystem where docker graph -(`/var/lib/docker`) is located. +Specifies the ZFS filesystem that the daemon should use to create its datasets. +By default, the ZFS filesystem in `/var/lib/docker` is used. ###### 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 for containers. If user uses disk quota for btrfs when creating or running -a container with **--storage-opt size** option, docker should ensure the -**size** cannot be smaller than **btrfs.min_space**. +a container with **--storage-opt size** option, Docker should ensure the +**size** can't be smaller than **btrfs.min_space**. ###### Example @@ -374,8 +372,8 @@ $ sudo dockerd -s btrfs --storage-opt btrfs.min_space=10G ##### `overlay2.size` 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 -conditions the user can pass any size less than the backing fs size. +backing filesystem is `xfs` and mounted with `pquota` mount option. Under these +conditions the user can pass any size less than the backing filesystem size. ###### Example @@ -687,7 +685,7 @@ To set the DNS search domain for all Docker containers, use: $ 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 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 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 - 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. 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 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 > 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 -Docker considers a private registry either secure or insecure. In the rest of -this section, *registry* is used for *private registry*, and `myregistry:5000` -is a placeholder example for a private registry. +In this section, "registry" refers to a private registry, and `myregistry:5000` +is a placeholder example of 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 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 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 failed (i.e., wrong CA). -By default, Docker assumes all, but local (see local registries below), -registries are secure. Communicating with an insecure registry is not possible +By default, Docker assumes all registries to be secure, except for local registries. +Communicating with an insecure registry isn't possible if Docker assumes that registry is secure. In order to communicate with an insecure registry, the Docker daemon requires `--insecure-registry` in one of 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 as insecure. -If an insecure registry is not marked as insecure, `docker pull`, -`docker push`, and `docker search` will result in an error message prompting +If an insecure registry isn't marked as insecure, `docker pull`, +`docker push`, and `docker search` result in error messages, prompting the user to either secure or pass the `--insecure-registry` flag to the Docker daemon as described above. 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. Enabling `--insecure-registry`, i.e., allowing un-encrypted and/or untrusted -communication, can be useful when running a local registry. However, -because its use creates security vulnerabilities it should ONLY be enabled for -testing purposes. For increased security, users should add their CA to their +communication, can be useful when running a local registry. However, +because its use creates security vulnerabilities it should only be enabled for +testing purposes. For increased security, users should add their CA to their system's list of trusted CAs instead of enabling `--insecure-registry`. #### Legacy Registries 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 on v1 registries. - ### Running a Docker daemon behind an HTTPS_PROXY -When running inside a LAN that uses an `HTTPS` proxy, the Docker Hub -certificates will be replaced by the proxy's certificates. These certificates -need to be added to your Docker host's configuration: +When running inside a LAN that uses an `HTTPS` proxy, the proxy's certificates +replace Docker Hub's certificates. These certificates must be added to your +Docker host's configuration: 1. Install the `ca-certificates` package for your distribution 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 proxy is set up to require authentication. -This will only add the proxy and authentication to the Docker daemon's requests - -your `docker build`s and running containers will need extra configuration to -use the proxy +This only adds the proxy and authentication to the Docker daemon's requests. +To use the proxy when building images and running containers, see +[Configure Docker to use a proxy server](https://docs.docker.com/network/proxy/) ### 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 -these defaults are not set, `ulimit` settings will be inherited, if not set on -`docker run`, from the Docker daemon. Any `--ulimit` options passed to -`docker run` will overwrite these defaults. +these defaults aren't set, `ulimit` settings are inherited from the Docker daemon. +Any `--ulimit` options passed to `docker run` override the daemon defaults. -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 -please check the [run](run.md) reference. +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, see [`docker run` reference](run.md#ulimit). ### 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 [authorization plugin](../../extend/plugins_authorization.md) section. - ### Daemon user namespace options The Linux kernel [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, 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 -security improvement is that, by default, container processes running as the -`root` user will have expected administrative privilege (with some restrictions) -inside the container but will effectively be mapped to an unprivileged `uid` on +user and group range utilized by the host system. One of the most important +security improvements is that, by default, container processes running as the +`root` user have expected administrative privileges it expects (with some restrictions) +inside the container, but are effectively mapped to an unprivileged `uid` on the host. 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 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 -network topologies and can be disabled with `--ip-masq=false`. +IP to talk to other machines on the internet. This may interfere with some +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 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 $ 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 -The `--cgroup-parent` option allows you to set the default cgroup parent -to use for containers. If this option is not set, it defaults to `/docker` for -fs cgroup driver and `system.slice` for systemd cgroup driver. +The `--cgroup-parent` option lets you set the default cgroup parent +for containers. If this option isn't set, it defaults to `/docker` for +the cgroupfs driver, and `system.slice` for the systemd cgroup driver. If the cgroup has a leading forward slash (`/`), the cgroup is created 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` 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 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 @@ -903,7 +895,7 @@ the `--cgroup-parent` option on the daemon. #### 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 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 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 -to have prometheus collect metrics on Docker. For more information -on prometheus refer to the [prometheus website](https://prometheus.io/). +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, see +[Collect Docker metrics with Prometheus](https://docs.docker.com/config/daemon/prometheus/). -```yaml -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 +#### Node generic resources The `--node-generic-resources` option takes a list of key-value 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 requesting `NVIDIA-GPU=[0-16]` can land on a node that has enough GPUs for the task to run. Example of usage: + ```json { "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. 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 -the file and the flags, regardless of their value. We do this to avoid +using flags. The Docker daemon fails to start if an option is duplicated between +the file and the flags, regardless of their value. This is intentional, and avoids silently ignore changes introduced in configuration reloads. 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. @@ -983,14 +965,13 @@ $ echo $? 1 ``` - ##### On Linux The default location of the configuration file on Linux is -`/etc/docker/daemon.json`. The `--config-file` flag can be used to specify a - non-default location. +`/etc/docker/daemon.json`. Use the `--config-file` flag to specify a +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 { @@ -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. -> 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. -> See ["custom Docker daemon options"](https://docs.docker.com/config/daemon/systemd/#custom-docker-daemon-options) for how -> to accomplish this task with a systemd drop-in file. +> On systems that use systemd to start the Docker daemon, `-H` is already set, so +> 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 an example on how to configure the daemon using systemd drop-in files. ##### On Windows The default location of the configuration file on Windows is - `%programdata%\docker\config\daemon.json`. The `--config-file` flag can be - used to specify a non-default location. +`%programdata%\docker\config\daemon.json`. Use the `--config-file` flag +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 { @@ -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: @@ -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. #### 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: -- `buildkit`: It enables `buildkit` as default builder when set to `true` or disables it by -`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. +The optional field `features` in `daemon.json` lets you enable or disable specific +daemon features. + +```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 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 -in Windows with the key `Global\docker-daemon-config-$PID`. The options can -be modified in the configuration file but still will check for conflicts with -the provided flags. The daemon fails to reconfigure itself -if there are conflicts, but it won't stop execution. +to restart the process. The daemon uses the `SIGHUP` signal in Linux to reload, +and a global event in Windows with the key `Global\docker-daemon-config-$PID`. +You can modify the options in the configuration file, but the daemon still +checks for conflicting settings with the specified CLI flags. The daemon fails +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: -- `debug`: it changes the daemon to debug mode when set to true. -- `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/). -- `max-concurrent-downloads`: it updates the max concurrent downloads for each pull. -- `max-concurrent-uploads`: it updates the max concurrent uploads for each push. -- `max-download-attempts`: it updates the max download attempts for each pull. -- `default-runtime`: it updates the runtime to be used if not is - specified at container creation. It defaults to "default" which is - the runtime shipped with the official docker packages. -- `runtimes`: it updates the list of available OCI runtimes that can - be used to run containers. -- `authorization-plugin`: it specifies the authorization plugins to use. -- `allow-nondistributable-artifacts`: Replaces the set of registries to which the daemon will push nondistributable artifacts with a new set of registries. -- `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`: 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`: it replaces the daemon's existing configuration timeout with a new timeout for shutting down all containers. -- `features`: it explicitly enables or disables specific features. +| Option | Description | +| ---------------------------------- | ----------------------------------------------------------------------------------------------------------- | +| `debug` | Toggles debug mode of the daemon. | +| `labels` | Replaces the daemon labels with a new set of labels. | +| `live-restore` | Toggles [live restore](https://docs.docker.com/config/containers/live-restore/). | +| `max-concurrent-downloads` | Configures the max concurrent downloads for each pull. | +| `max-concurrent-uploads` | Configures the max concurrent uploads for each push. | +| `max-download-attempts` | Configures the max download attempts for each pull. | +| `default-runtime` | Configures the runtime to be used if not is specified at container creation. | +| `runtimes` | Configures the list of available OCI runtimes that can be used to run containers. | +| `authorization-plugin` | Specifies the authorization plugins to use. | +| `allow-nondistributable-artifacts` | Specifies a list of registries to which the daemon will push non-distributable artifacts. | +| `insecure-registries` | Specifies a list of registries that the daemon should consider insecure. | +| `registry-mirrors` | Specifies a list of registry mirrors. | +| `shutdown-timeout` | Configures the daemon's existing configuration timeout with a new timeout for shutting down all containers. | +| `features` | Enables or disables specific features. | ### Run multiple daemons -> **Note:** +> **Note** > -> Running multiple daemons on a single host is considered as "experimental". The user should be aware of -> unsolved problems. This solution may not work properly in some cases. Solutions are currently under development -> and will be delivered in the near future. +> Running multiple daemons on a single host is considered experimental. +> You may encounter unsolved problems, and things may not work as expected in some cases. 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 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: -```console +```text -b, --bridge= Attach containers to a network bridge --exec-root=/var/run/docker Root of the Docker execdriver --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. -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. -If you are not using the default, you must create and configure the bridge manually or just set it to 'none': `--bridge=none` -- `--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. +- The `-b, --bridge=` flag is set to `docker0` as default bridge network. + It is created automatically when you install Docker. + If you aren't using the default, you must create and configure the bridge manually, or set it to 'none': `--bridge=none` +- `--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 -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. -- `-p, --pidfile=/var/run/docker.pid` is the path where the process ID of the daemon is stored. 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`. -- `--iptables=false` prevents the Docker daemon from adding iptables rules. If -multiple daemons manage iptables rules, they may overwrite rules set by another -daemon. Be aware that disabling this option requires you to manually add -iptables rules to expose container ports. If you prevent Docker from adding -iptables rules, Docker will also not add IP masquerading rules, even if you set -`--ip-masq` to `true`. Without IP masquerading rules, Docker containers will not be -able to 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 -daemon flags. Specify the path for each daemon. + 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. +- `-p, --pidfile=/var/run/docker.pid` is the path where the process ID of the daemon is stored. + Specify the path for your PID file here. +- `--host=[]` specifies where the Docker daemon listens for client connections. + If unspecified, it defaults to `/var/run/docker.sock`. +- `--iptables=false` prevents the Docker daemon from adding iptables rules. If + multiple daemons manage iptables rules, they may overwrite rules set by another + daemon. Be aware that disabling this option requires you to manually add + iptables rules to expose container ports. If you prevent Docker from adding + iptables rules, Docker also doesn't add IP masquerading rules, even if you set + `--ip-masq` to `true`. Without IP masquerading rules, Docker containers can't + 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 daemon flags. Specify the path for each daemon. - `--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: diff --git a/docs/reference/commandline/events.md b/docs/reference/commandline/events.md index 56ca197596..d65605e349 100644 --- a/docs/reference/commandline/events.md +++ b/docs/reference/commandline/events.md @@ -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 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. 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 timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the client machine’s time. If you do not provide the `--since` option, -the command returns only new and/or live events. Supported formats for date +the command returns only new and/or live events. Supported formats for date formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, `2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local timezone on the client will be used if you do not provide either a `Z` or a -`+-00:00` timezone offset at the end of the timestamp. When providing Unix +`+-00:00` timezone offset at the end of the timestamp. When providing Unix timestamps enter seconds[.nanoseconds], where seconds is the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a @@ -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., `--filter "foo=bar" --filter "bif=baz"`) -Using the same filter multiple times will be handled as a *OR*; for example -`--filter container=588a23dac085 --filter container=a8f7720b8c22` will display -events for container 588a23dac085 *OR* container a8f7720b8c22 +Using the same filter multiple times is interpreted as a logical `OR`; for example, +`--filter container=588a23dac085 --filter container=a8f7720b8c22` displays +events for container `588a23dac085` or container `a8f7720b8c22`. -Using multiple filters will be handled as a *AND*; for example -`--filter container=588a23dac085 --filter event=start` will display events for -container container 588a23dac085 *AND* the event type is *start* +Using multiple filters is interpreted as a logical `AND`; for example, +`--filter container=588a23dac085 --filter event=start` displays events for +container `588a23dac085` and where the event type is `start`. The currently supported filters are: -* config (`config=`) -* container (`container=`) -* daemon (`daemon=`) -* event (`event=`) -* image (`image=`) -* label (`label=` or `label==`) -* network (`network=`) -* node (`node=`) -* plugin (`plugin=`) -* scope (`scope=`) -* secret (`secret=`) -* service (`service=`) -* type (`type=`) -* volume (`volume=`) +- config (`config=`) +- container (`container=`) +- daemon (`daemon=`) +- event (`event=`) +- image (`image=`) +- label (`label=` or `label==`) +- network (`network=`) +- node (`node=`) +- plugin (`plugin=`) +- scope (`scope=`) +- secret (`secret=`) +- service (`service=`) +- type (`type=`) +- volume (`volume=`) #### Format the output (--format) -If a format (`--format`) is specified, the given template will be executed -instead of the default -format. Go's [text/template](https://pkg.go.dev/text/template) package -describes all the details of the format. +If you specify a format (`--format`), the given template is executed +instead of the default format. Go's [text/template](https://pkg.go.dev/text/template) +package describes all the details of the format. -If a format is set to `{{json .}}`, the events are streamed as valid JSON -Lines. For information about JSON Lines, please refer to https://jsonlines.org/. +If a format is set to `{{json .}}`, events are streamed in the JSON Lines format. +For information about JSON Lines, see . ## Examples @@ -237,7 +236,7 @@ To exit the `docker events` command, use `CTRL+C`. ### Filter events by time You can filter the output by an absolute timestamp or relative time on the host -machine, using the following different time syntaxes: +machine, using the following different time formats: ```console $ docker events --since 1483283804 @@ -401,8 +400,8 @@ Type=container Status=destroy ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299 #### Format as JSON -To list events in JSON format, use the `json` directive, which is the equivalent -of `--format '{{ json . }}`. +To list events in JSON format, use the `json` directive, which is the same +`--format '{{ json . }}`. ```console $ docker events --format json @@ -413,5 +412,3 @@ $ docker events --format json {"status":"start","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f42.. {"status":"resize","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4.. ``` - -. diff --git a/docs/reference/commandline/exec.md b/docs/reference/commandline/exec.md index c9656b7ecd..1f1fafa747 100644 --- a/docs/reference/commandline/exec.md +++ b/docs/reference/commandline/exec.md @@ -28,17 +28,16 @@ Execute a 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 -process (`PID 1`) is running, and it is not restarted if the container is -restarted. +The command you specify with `docker exec` only runs while the container's +primary process (`PID 1`) is running, and it isn't restarted if the container +is restarted. -COMMAND runs in the default directory of the container. If the underlying image -has a custom directory specified with the WORKDIR directive in its Dockerfile, -this directory is used instead. +The command runs in the default working directory of the container. -COMMAND must be an executable. A chained or a quoted command does not 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. +The command must be an executable. A chained or a quoted command doesn't work. + +- This works: `docker exec -it my_container sh -c "echo a && echo b"` +- This doesn't work: `docker exec -it my_container "echo a && echo b"` ## Examples @@ -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 variables for the process started by `docker exec`. -The example below creates a new shell session in the container `mycontainer` with -environment variables `$VAR_A` and `$VAR_B` set to "1" and "2" respectively. +The following example creates a new shell session in the container `mycontainer`, +with environment variables `$VAR_A` set to `1`, and `$VAR_B` set to `2`. These environment variables are only valid for the `sh` process started by that -`docker exec` command, and are not available to other processes running inside +`docker exec` command, and aren't available to other processes running inside the container. ```console @@ -99,7 +98,7 @@ HOME=/root ### Set the working directory for the exec process (--workdir, -w) -By default `docker exec` command runs in the same working directory set when +By default `docker exec` command runs in the same working directory set when the container was created. ```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): ```console @@ -115,7 +114,6 @@ $ docker exec -it -w /root mycontainer pwd /root ``` - ### Try to run `docker exec` on a paused container If the container is paused, then the `docker exec` command fails with an error: diff --git a/docs/reference/commandline/export.md b/docs/reference/commandline/export.md index f2d84f1414..31fd70a774 100644 --- a/docs/reference/commandline/export.md +++ b/docs/reference/commandline/export.md @@ -18,9 +18,9 @@ Export a container's filesystem as a tar archive ## 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 -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. 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 -Each of these commands has the same result. +The following commands produce the same result. ```console $ docker export red_panda > latest.tar diff --git a/docs/reference/commandline/history.md b/docs/reference/commandline/history.md index 0756b1b646..a120d3e110 100644 --- a/docs/reference/commandline/history.md +++ b/docs/reference/commandline/history.md @@ -62,9 +62,9 @@ Valid placeholders for the Go template are listed below: | `.Size` | Image disk size | | `.Comment` | Comment for image | -When using the `--format` option, the `history` command will either -output the data exactly as the template declares or, when using the -`table` directive, will include column headers as well. +When using the `--format` option, the `history` command either +outputs the data exactly as the template declares or, when using the +`table` directive, includes column headers as well. The following example uses a template without headers and outputs the `ID` and `CreatedSince` entries separated by a colon (`:`) for the `busybox` diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md index 46e46db561..8ae0c6f7a6 100644 --- a/docs/reference/commandline/run.md +++ b/docs/reference/commandline/run.md @@ -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`. Use `docker ps -a` to view a list of all containers, including those that are stopped. - ## Examples ### Assign name (--name) @@ -281,9 +280,14 @@ container. The UTS namespace is for setting the hostname and the domain that's visible to running processes in that namespace. By default, all containers, including -those with `--network=host`, have their own UTS namespace. The `host` setting -will result in the container using the same UTS namespace as the host. Note -that `--hostname` and `--domainname` are invalid in `host` UTS mode. +those with `--network=host`, have their own UTS namespace. Setting `--uts` to +`host` results in the container using the same UTS namespace as the host. + +> **Note** +> +> Docker disallows combining the `--hostname` and `--domainname` flags with +> `--uts=host`. This is to prevent containers running in the host's UTS +> namespace from attempting to change the hosts' configuration. You may wish to share the UTS namespace with the host if you would like the hostname of the container to change as the hostname of the host changes. A more @@ -309,8 +313,9 @@ The `--ipc` flag accepts the following values: If not specified, daemon default is used, which can either be `"private"` or `"shareable"`, depending on the daemon version and configuration. -IPC (POSIX/SysV IPC) namespace provides separation of named shared memory -segments, semaphores and message queues. +[System V interprocess communication (IPC)](https://linux.die.net/man/5/ipc) +namespaces provide separation of named shared memory segments, semaphores and +message queues. Shared memory segments are used to accelerate inter-process communication at memory speed, rather than through pipes or through the network stack. Shared @@ -323,15 +328,17 @@ container, and `"container:"` for other containers. ### Full container capabilities (--privileged) +The following example doesn't work, because by default, Docker drops most +potentially dangerous kernel capabilities, including `CAP_SYS_ADMIN ` (which is +required to mount filesystems). + ```console $ docker run -t -i --rm ubuntu bash root@bc338942ef20:/# mount -t tmpfs none /mnt mount: permission denied ``` -This *doesn't* work, because by default, Docker drops most potentially dangerous kernel -capabilities, including `CAP_SYS_ADMIN ` (which is required to mount -filesystems). However, the `--privileged` flag allows it to run: +It works when you add the `--privileged` flag: ```console $ 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 ``` -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 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. @@ -349,11 +356,11 @@ flag exists to allow special use-cases, like running Docker within Docker. ### Set working directory (-w, --workdir) ```console -$ docker run -w /path/to/dir/ -i -t ubuntu pwd +$ docker run -w /path/to/dir/ -i -t ubuntu pwd ``` The `-w` option runs the command executed inside the directory specified, in this example, -`/path/to/dir/`. If the path does not exist, Docker creates it inside the container. +`/path/to/dir/`. If the path doesn't exist, Docker creates it inside the container. ### 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 ``` +For more information, see [tmpfs mounts](https://docs.docker.com/storage/tmpfs/#tmpfs-mounts). + ### Mount volume (-v) ```console @@ -597,14 +606,15 @@ VAR2=value2 When running the command, the Docker CLI client checks the value the variable has in your local environment and passes it to the container. -If no `=` is provided and that variable is not exported in your local -environment, the variable isn't set in the container. +If no `=` is provided and that variable isn't exported in your local +environment, the variable is unset in the container. You can also load the environment variables from a file. This file should use the syntax `=value` (which sets the variable to the given value) or -`` (which takes the value from the local environment), and `#` for comments. -Additionally, it's important to note that lines beginning with `#` are treated as line comments -and are ignored, whereas a `#` appearing anywhere else in a line is treated as part of the variable value. +`` (which takes the value from the local environment), and `#` for +comments. Lines beginning with `#` are treated as line comments and are +ignored, whereas a `#` appearing anywhere else in a line is treated as part of +the variable value. ```console $ cat env.list @@ -657,9 +667,8 @@ com.example.label3 You can load multiple label-files by supplying multiple `--label-file` flags. -For additional information on working with labels, see [*Labels - custom -metadata in Docker*](https://docs.docker.com/config/labels-custom-metadata/) in -the Docker User Guide. +For additional information on working with labels, see +[Labels](https://docs.docker.com/config/labels-custom-metadata/). ### Connect a container to a network (--network) @@ -887,9 +896,9 @@ $ cat somefile | docker run -i -a stdin mybuilder dobuild > **Note** > -> A process running as PID 1 inside a container is treated specially by Linux: -> it ignores any signal with the default action. As a result, the process will -> not terminate on `SIGINT` or `SIGTERM` unless it is coded to do so. +> A process running as PID 1 inside a container is treated specially by +> Linux: it ignores any signal with the default action. So, the process +> doesn't terminate on `SIGINT` or `SIGTERM` unless it's coded to do so. See also [the `docker cp` command](cp.md). @@ -1047,8 +1056,8 @@ Docker supports the following restart policies: $ docker run --restart=always redis ``` -This will run the `redis` container with a restart policy of **always** -so that if the container exits, Docker restarts it. +This runs the `redis` container with a restart policy of **always**. +If the container exits, Docker restarts it. When a restart policy is active on a container, it shows as either `Up` or `Restarting` in [`docker ps`](ps.md). It can also be useful to use [`docker @@ -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 > associated with the container when the container is removed. This is similar -> to running `docker rm -v my-container`. Only volumes that are specified without -> a name are removed. For example, when running: +> to running `docker rm -v my-container`. Only volumes that are specified +> without a name are removed. For example, when running the following command, +> volume `/foo` is removed, but not `/bar`: > > ```console > $ docker run --rm -v /foo -v awesome:/bar busybox top > ``` > -> the volume for `/foo` will be removed, but the volume for `/bar` will not. -> Volumes inherited via `--volumes-from` will be removed with the same logic: if -> the original volume was specified with a name it will **not** be removed. +> Volumes inherited via `--volumes-from` are removed with the same logic: +> if the original volume was specified with a name it isn't removed. ### Add entries to container hosts file (--add-host) @@ -1315,7 +1324,7 @@ use the following command: $ 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 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). diff --git a/docs/reference/commandline/swarm_init.md b/docs/reference/commandline/swarm_init.md index 113a25b07a..990bd15d9b 100644 --- a/docs/reference/commandline/swarm_init.md +++ b/docs/reference/commandline/swarm_init.md @@ -5,30 +5,30 @@ Initialize a swarm ### Options -| Name | Type | Default | Description | -|:----------------------------------|:--------------|:---------------|:-----------------------------------------------------------------------------------------------------------------------------| -| `--advertise-addr` | `string` | | Advertised address (format: `[:port]`) | -| `--autolock` | | | Enable manager autolocking (requiring an unlock key to start a stopped manager) | -| `--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) | -| `--data-path-addr` | `string` | | Address or interface to use for data path traffic (format: ``) | -| `--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-mask-length` | `uint32` | `24` | default address pool subnet mask length | -| `--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 | -| `--force-new-cluster` | | | Force create a new cluster from current state | -| `--listen-addr` | `node-addr` | `0.0.0.0:2377` | Listen address (format: `[:port]`) | -| `--max-snapshots` | `uint64` | `0` | Number of additional Raft snapshots to retain | -| `--snapshot-interval` | `uint64` | `10000` | Number of log entries between Raft snapshots | -| `--task-history-limit` | `int64` | `5` | Task history retention limit | +| Name | Type | Default | Description | +|:--------------------------------------------|:--------------|:---------------|:-----------------------------------------------------------------------------------------------------------------------------| +| [`--advertise-addr`](#advertise-addr) | `string` | | Advertised address (format: `[:port]`) | +| [`--autolock`](#autolock) | | | Enable manager autolocking (requiring an unlock key to start a stopped manager) | +| [`--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) | +| [`--data-path-addr`](#data-path-addr) | `string` | | Address or interface to use for data path traffic (format: ``) | +| [`--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`](#default-addr-pool) | `ipNetSlice` | | default address pool in CIDR format | +| `--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) | +| [`--external-ca`](#external-ca) | `external-ca` | | Specifications of one or more certificate signing endpoints | +| [`--force-new-cluster`](#force-new-cluster) | | | Force create a new cluster from current state | +| [`--listen-addr`](#listen-addr) | `node-addr` | `0.0.0.0:2377` | Listen address (format: `[:port]`) | +| [`--max-snapshots`](#max-snapshots) | `uint64` | `0` | Number of additional Raft snapshots to retain | +| [`--snapshot-interval`](#snapshot-interval) | `uint64` | `10000` | Number of log entries between Raft snapshots | +| `--task-history-limit` | `int64` | `5` | Task history retention limit | ## 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. ## 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: - docker swarm join \ - --token SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx \ - 172.17.0.2:2377 + docker swarm join --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. ``` -`docker swarm init` generates two random tokens, a worker token and a manager token. When you join -a new node to the swarm, the node joins as a worker or manager node based upon the token you pass -to [swarm join](swarm_join.md). +The `docker swarm init` command generates two random tokens: a worker token and +a manager token. When you join a new node to the swarm, the node joins as a +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 [swarm join-token](swarm_join-token.md). -### `--autolock` +### Protect manager keys and data (--autolock) -This flag enables automatic locking of managers with an encryption key. The -private keys and data stored by all managers will be protected by the -encryption key printed in the output, and will not be accessible without it. -Thus, it is very important to store this key in order to activate a manager -after it restarts. The key can be passed to `docker swarm unlock` to reactivate -the manager. Autolock can be disabled by running -`docker swarm update --autolock=false`. After disabling it, the encryption key -is no longer required to start the manager, and it will start up on its own -without user intervention. +The `--autolock` flag enables automatic locking of managers with an encryption +key. The private keys and data stored by all managers are protected by the +encryption key printed in the output, and is inaccessible without it. Make sure +to store this key securely, in order to reactivate a manager after it restarts. +Pass the key to the `docker swarm unlock` command to reactivate the manager. +You can disable autolock by running `docker swarm update --autolock=false`. +After disabling it, the encryption key is no longer required to start the +manager, and it will start up on its own without user intervention. -### `--cert-expiry` +### 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` +### Use an external certificate authority (--external-ca) -This flag sets the frequency with which nodes are told to use as a -period to report their health. +This flag sets up the swarm to use an external CA to issue node certificates. +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` +### 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 -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. +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. -### `--force-new-cluster` +### 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. - -### `--listen-addr` - -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`. +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 -name, the default port 2377 will be used. +name, the default port 2377 is used. -### `--advertise-addr` +### Specify interface for outbound control plane traffic (--advertise-addr) -This flag specifies the address that will be advertised to other members of the -swarm for API access and overlay networking. If unspecified, Docker will check -if the system has a single IP address, and use that IP address with the -listening port (see `--listen-addr`). If the system has multiple IP addresses, -`--advertise-addr` must be specified so that the correct address is chosen for -inter-manager communication and overlay networking. +The `--advertise-addr` flag specifies the address that will be advertised to +other members of the swarm for API access and overlay networking. If +unspecified, Docker will check if the system has a single IP address, and use +that IP address with the listening port (see `--listen-addr`). If the system +has multiple IP addresses, `--advertise-addr` must be specified so that the +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; -for example `--advertise-addr eth0:2377`. +It is also possible to specify a network interface to advertise that +interface's address; for example `--advertise-addr eth0:2377`. 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` +### Specify interface for data traffic (--data-path-addr) -This flag specifies the address that global scope network drivers will publish towards -other nodes in order to reach the containers running on this node. -Using this parameter it is then possible to separate the container's data traffic from the -management traffic of the cluster. -If unspecified, Docker will use the same IP address or interface that is used for the -advertise address. +The `--data-path-addr` flag specifies the address that global scope network +drivers will publish towards other nodes in order to reach the containers +running on this node. Using this parameter you can separate the container's +data traffic from the management traffic of the cluster. -### `--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 -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 can only be configured when initializing the 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; +### Configure port number for data traffic (--data-path-port) + +The `--data-path-port` flag allows you to configure the UDP port number to use +for data path traffic. The provided port number must be within the 1024 - 49151 +range. If this flag isn't set, or if it's set to 0, the default port number +4789 is used. The data path port can only be configured when initializing the +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 $ docker swarm init --data-path-port=7777 @@ -146,43 +143,45 @@ Data Path Port: 7777 <...> ``` -### `--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` +### Specify default subnet pools (--default-addr-pool) -### `--default-addr-pool-mask-length` -This flag specifies default subnet pools mask length for default-addr-pool. -Format example is `--default-addr-pool-mask-length 24` +The `--default-addr-pool` flag specifies default subnet pools for global scope +networks. For example, to specify two address pools: -### `--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` +### 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 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 disaster recovery purposes. -### `--snapshot-interval` +### Configure Raft snapshot log interval (--snapshot-interval) -This flag specifies how many log entries to allow in between Raft snapshots. -Setting this to a higher number will trigger snapshots less frequently. -Snapshots compact the Raft log and allow for more efficient transfer of the -state to new managers. However, there is a performance cost to taking snapshots -frequently. +The `--snapshot-interval` flag specifies how many log entries to allow in +between Raft snapshots. Setting this to a high number will trigger snapshots +less frequently. Snapshots compact the Raft log and allow for more efficient +transfer of the state to new managers. However, there is a performance cost to +taking snapshots frequently. -### `--availability` +### Configure the availability of a manager (--availability) -This flag specifies the availability of the node at the time the node joins a master. -Possible availability values are `active`, `pause`, or `drain`. +The `--availability` flag specifies the availability of the node at the time +the node joins a master. Possible availability values are `active`, `pause`, or +`drain`. -This flag is useful in certain situations. For example, a cluster may want to have -dedicated manager nodes that are not served as worker nodes. This could be achieved +This flag is useful in certain situations. For example, a cluster may want to +have dedicated manager nodes that don't serve as worker nodes. You can do this by passing `--availability=drain` to `docker swarm init`. - ## Related commands * [swarm ca](swarm_ca.md) diff --git a/docs/reference/commandline/system_df.md b/docs/reference/commandline/system_df.md index 1c05ff4b3e..98906152a7 100644 --- a/docs/reference/commandline/system_df.md +++ b/docs/reference/commandline/system_df.md @@ -16,11 +16,11 @@ Show docker disk usage ## Description 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 -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 $ docker system df @@ -31,7 +31,7 @@ Containers 2 0 212 B 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 $ 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) -* `UNIQUE SIZE` is the amount of space that is only used by a given image -* `SIZE` is the virtual size of the image, it is the sum of `SHARED SIZE` and `UNIQUE SIZE` +* `UNIQUE SIZE` is the amount of space that's only used by a given image +* `SIZE` is the virtual size of the image, it's the sum of `SHARED SIZE` and `UNIQUE SIZE` > **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 -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 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 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 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 `Type` and `TotalCount` entries separated by a colon (`:`): diff --git a/docs/reference/commandline/system_events.md b/docs/reference/commandline/system_events.md index 601d4c6e30..ec5c83cf19 100644 --- a/docs/reference/commandline/system_events.md +++ b/docs/reference/commandline/system_events.md @@ -108,11 +108,11 @@ Docker daemons report the following events: The `--since` and `--until` parameters can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the client machine’s time. If you do not provide the `--since` option, -the command returns only new and/or live events. Supported formats for date +the command returns only new and/or live events. Supported formats for date formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, `2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local timezone on the client will be used if you do not provide either a `Z` or a -`+-00:00` timezone offset at the end of the timestamp. When providing Unix +`+-00:00` timezone offset at the end of the timestamp. When providing Unix timestamps enter seconds[.nanoseconds], where seconds is the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a @@ -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., `--filter "foo=bar" --filter "bif=baz"`) -Using the same filter multiple times will be handled as a *OR*; for example -`--filter container=588a23dac085 --filter container=a8f7720b8c22` will display -events for container 588a23dac085 *OR* container a8f7720b8c22 +Using the same filter multiple times will be handled as a logical `OR`; for example, +`--filter container=588a23dac085 --filter container=a8f7720b8c22` displays +events for container `588a23dac085` or container `a8f7720b8c22`. -Using multiple filters will be handled as a *AND*; for example -`--filter container=588a23dac085 --filter event=start` will display events for -container container 588a23dac085 *AND* the event type is *start* +Using multiple filters will be handled as a logical `AND`; for example, +`--filter container=588a23dac085 --filter event=start` displays events for +container `588a23dac085` and where the event type is `start`. The currently supported filters are: -* container (`container=`) -* daemon (`daemon=`) -* event (`event=`) -* image (`image=`) -* label (`label=` or `label==`) -* network (`network=`) -* plugin (`plugin=`) -* type (`type=`) -* volume (`volume=`) +- container (`container=`) +- daemon (`daemon=`) +- event (`event=`) +- image (`image=`) +- label (`label=` or `label==`) +- network (`network=`) +- plugin (`plugin=`) +- type (`type=`) +- volume (`volume=`) ## Examples @@ -181,7 +181,7 @@ To exit the `docker system events` command, use `CTRL+C`. ### Filter events by time You can filter the output by an absolute timestamp or relative time on the host -machine, using the following different time syntaxes: +machine, using the following different time formats: ```console $ docker system events --since 1483283804 @@ -307,7 +307,7 @@ $ docker system events --filter 'type=plugin' ### 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) package describes all the details of the format. @@ -324,8 +324,8 @@ Type=container Status=destroy ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299 #### Format as JSON -If a format is set to `{{json .}}`, the events are streamed as valid JSON -Lines. For information about JSON Lines, please refer to https://jsonlines.org/ . +If a format is set to `{{json .}}`, events are streamed in the JSON Lines format. +For information about JSON Lines, see . ```console $ docker system events --format '{{json .}}' diff --git a/docs/reference/commandline/system_prune.md b/docs/reference/commandline/system_prune.md index 4c3ff284ac..5239821a43 100644 --- a/docs/reference/commandline/system_prune.md +++ b/docs/reference/commandline/system_prune.md @@ -17,7 +17,7 @@ Remove unused data ## Description -Remove all unused containers, networks, images (both dangling and unreferenced), +Remove all unused containers, networks, images (both dangling and unused), and optionally, volumes. ## Examples @@ -48,7 +48,7 @@ deleted: sha256:45761469c965421a92a69cc50e92c01e0cfa94fe026cdd1233445ea00e96289a 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` 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`, `2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local timezone on the daemon will be used if you do not provide either a `Z` or a -`+-00:00` timezone offset at the end of the timestamp. When providing Unix +`+-00:00` timezone offset at the end of the timestamp. When providing Unix timestamps enter seconds[.nanoseconds], where seconds is the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a diff --git a/docs/reference/commandline/tag.md b/docs/reference/commandline/tag.md index d2d3605d73..d9359f62ef 100644 --- a/docs/reference/commandline/tag.md +++ b/docs/reference/commandline/tag.md @@ -17,30 +17,30 @@ A full image name has the following format and components: `[HOST[:PORT_NUMBER]/]PATH` - `HOST`: The optional registry hostname specifies where the image is located. -The hostname must comply with standard DNS rules, but may not contain -underscores. If the hostname is not specified, the command uses Docker's public -registry at `registry-1.docker.io` by default. Note that `docker.io` is the -canonical reference for Docker's public registry. + The hostname must comply with standard DNS rules, but may not contain + underscores. If you don't specify a hostname, the command uses Docker's public + registry at `registry-1.docker.io` by default. Note that `docker.io` is the + canonical reference for Docker's public registry. - `PORT_NUMBER`: If a hostname is present, it may optionally be followed by a -registry port number in the format `:8080`. + registry port number in the format `:8080`. - `PATH`: The path consists of slash-separated components. Each -component may contain lowercase letters, digits and separators. A separator is -defined as a period, one or two underscores, or one or more hyphens. A component -may not start or end with a separator. While the -[OCI Distribution Specification](https://github.com/opencontainers/distribution-spec) -supports more than two slash-separated components, most registries only support -two slash-separated components. For Docker's public registry, the path format is -as follows: + component may contain lowercase letters, digits and separators. A separator is + defined as a period, one or two underscores, or one or more hyphens. A component + may not start or end with a separator. While the + [OCI Distribution Specification](https://github.com/opencontainers/distribution-spec) + supports more than two slash-separated components, most registries only support + two slash-separated components. For Docker's public registry, the path format is + as follows: - `[NAMESPACE/]REPOSITORY`: The first, optional component is typically a -user's or an organization's namespace. The second, mandatory component is the -repository name. When the namespace is not present, Docker uses `library` -as the default namespace. + user's or an organization's namespace. The second, mandatory component is the + repository name. When the namespace is not present, Docker uses `library` + as the default namespace. After the image name, the optional `TAG` is a custom, human-readable manifest -identifier that 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, -underscores, periods, and hyphens. It cannot 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. +underscores, periods, and hyphens. It can't start with a period or hyphen and +must be no longer than 128 characters. If you don't specify a tag, the command uses `latest` by default. You can group your images together using names and tags, and then [push](https://docs.docker.com/engine/reference/commandline/push) them to a @@ -50,8 +50,8 @@ registry. ### Tag an image referenced by ID -To tag a local image with ID "0e5574283393" as "fedora/httpd" with the tag -"version1.0": +To tag a local image with ID `0e5574283393` as `fedora/httpd` with the tag +`version1.0`: ```console $ docker tag 0e5574283393 fedora/httpd:version1.0 @@ -59,19 +59,19 @@ $ docker tag 0e5574283393 fedora/httpd:version1.0 ### Tag an image referenced by Name -To tag a local image "httpd" as "fedora/httpd" with the tag "version1.0": +To tag a local image `httpd` as `fedora/httpd` with the tag `version1.0`: ```console $ docker tag httpd fedora/httpd:version1.0 ``` -Note that since the tag name 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`. ### Tag an image referenced by Name and Tag -To tag a local image with the name "httpd" and the tag "test" as "fedora/httpd" -with the tag "version1.0.test": +To tag a local image with the name `httpd` and the tag `test` as `fedora/httpd` +with the tag `version1.0.test`: ```console $ docker tag httpd:test fedora/httpd:version1.0.test @@ -84,4 +84,4 @@ must include the registry hostname and port (if needed). ```console $ docker tag 0e5574283393 myregistryhost:5000/fedora/httpd:version1.0 -``` \ No newline at end of file +``` diff --git a/docs/reference/commandline/trust_key_generate.md b/docs/reference/commandline/trust_key_generate.md index 3afe2477f9..8e36f1b357 100644 --- a/docs/reference/commandline/trust_key_generate.md +++ b/docs/reference/commandline/trust_key_generate.md @@ -15,7 +15,7 @@ Generate and load a signing key-pair ## Description `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 @@ -32,7 +32,7 @@ $ ls 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`. The public key component `alice.pub` will be available in the current working directory, and can diff --git a/docs/reference/commandline/trust_key_load.md b/docs/reference/commandline/trust_key_load.md index 57fd480a9a..f2e862736e 100644 --- a/docs/reference/commandline/trust_key_load.md +++ b/docs/reference/commandline/trust_key_load.md @@ -14,7 +14,7 @@ Load a private key file for signing ## 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`. diff --git a/docs/reference/commandline/trust_revoke.md b/docs/reference/commandline/trust_revoke.md index 04a8a91330..23a0101e83 100644 --- a/docs/reference/commandline/trust_revoke.md +++ b/docs/reference/commandline/trust_revoke.md @@ -20,7 +20,7 @@ Remove trust for an image ### 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 diff --git a/docs/reference/commandline/trust_sign.md b/docs/reference/commandline/trust_sign.md index 567d0af6bd..c5b8148224 100644 --- a/docs/reference/commandline/trust_sign.md +++ b/docs/reference/commandline/trust_sign.md @@ -18,7 +18,7 @@ Sign an image ## Examples -### Sign a tag as a repo admin +### Sign a tag as a repository admin Given an image: @@ -125,9 +125,9 @@ Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e 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 $ docker trust inspect --pretty example/trust-demo diff --git a/docs/reference/commandline/trust_signer_add.md b/docs/reference/commandline/trust_signer_add.md index 1ca68faa4c..bd116b3db1 100644 --- a/docs/reference/commandline/trust_signer_add.md +++ b/docs/reference/commandline/trust_signer_add.md @@ -18,7 +18,7 @@ Add a signer ## Examples -### Add a signer to a repo +### Add a signer to a repository To add a new signer, `alice`, to this repository: @@ -66,9 +66,9 @@ Repository Key: 642692c14c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e 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 $ docker trust inspect --pretty example/trust-demo @@ -107,8 +107,10 @@ Repository Key: 95b9e5565eac3ef5ec01406801bdfb70feb40c17808d2222427c18046eb63beb Root Key: 748121c14bd1461f6c58cb3ef39087c8fdc7633bb11a98af844fd9a04e208103 ``` -## Add a signer to multiple repos +## Add a signer to multiple repositories + To add a signer, `alice`, to multiple repositories: + ```console $ docker trust inspect --pretty example/trust-demo @@ -192,8 +194,8 @@ Repository Key: ece554f14c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4553d2ab20a8d926 Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 ``` - -`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: +`docker trust signer add` adds signers to repositories on a best effort basis. +It continues to add the signer to subsequent repositories if one attempt fails: ```console $ docker trust signer add alice example/unauthorized example/authorized --key alice.crt diff --git a/docs/reference/commandline/trust_signer_remove.md b/docs/reference/commandline/trust_signer_remove.md index a92fe5b929..5e425d5e6f 100644 --- a/docs/reference/commandline/trust_signer_remove.md +++ b/docs/reference/commandline/trust_signer_remove.md @@ -18,7 +18,7 @@ Remove a signer ## Examples -### Remove a signer from a repo +### Remove a signer from a 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 ``` -`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 $ docker trust inspect --pretty example/trust-demo @@ -67,7 +67,7 @@ Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 ``` -### Remove a signer from multiple repos +### Remove a signer from multiple repositories To remove an existing signer, `alice`, from multiple repositories: @@ -154,9 +154,8 @@ Repository Key: ece554f14c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4553d2ab20a8d926 Root Key: 3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949 ``` -`docker trust signer remove` removes signers to repositories on a best effort -basis, so it will continue to remove the signer from subsequent repositories if -one attempt fails: +`docker trust signer remove` removes signers to repositories on a best effort basis. +It continues to remove the signer from subsequent repositories if one attempt fails: ```console $ 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 ``` - diff --git a/docs/reference/commandline/volume_create.md b/docs/reference/commandline/volume_create.md index e0129021ec..4f689ae622 100644 --- a/docs/reference/commandline/volume_create.md +++ b/docs/reference/commandline/volume_create.md @@ -41,23 +41,23 @@ hello $ 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. -Multiple containers can use the same volume in the same time period. This is -useful if two containers need access to shared data. For example, if one -container writes and the other reads the data. +Multiple containers can use the same volume. This is useful if two containers +need access to shared data. For example, if one container writes and the other +reads the data. -Volume names must be unique among drivers. This means you cannot use the same -volume name with two different drivers. If you attempt this `docker` returns an -error: +Volume names must be unique among drivers. This means you can't use the same +volume name with two different drivers. Attempting to create two volumes with +the same name results in an error: ```console 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 -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. ### 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 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 on Linux accepts options similar to the linux -`mount` command. You can provide multiple options by passing the `--opt` flag -multiple times. Some `mount` options (such as the `o` option) can take a -comma-separated list of options. Complete list of available mount options can be -found [here](https://man7.org/linux/man-pages/man8/mount.8.html). +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` +command. You can provide multiple options by passing the `--opt` flag multiple +times. Some `mount` options (such as the `o` option) can take a comma-separated +list of options. Complete list of available mount options can be 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 100 megabyte and `uid` of 1000. diff --git a/docs/reference/commandline/volume_ls.md b/docs/reference/commandline/volume_ls.md index cd7f27c08c..e5da1c8bf0 100644 --- a/docs/reference/commandline/volume_ls.md +++ b/docs/reference/commandline/volume_ls.md @@ -52,7 +52,7 @@ than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "b 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) - label (`label=` or `label==`) - 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 a `label` and a value. -First, let's create some volumes to illustrate this; +First, create some volumes to illustrate this; ```console $ docker volume create the-doctor --label is-timelord=yes diff --git a/docs/reference/commandline/volume_prune.md b/docs/reference/commandline/volume_prune.md index 9c923df325..d2671fa7a0 100644 --- a/docs/reference/commandline/volume_prune.md +++ b/docs/reference/commandline/volume_prune.md @@ -51,7 +51,6 @@ which removes volumes with the specified labels. The other format is the `label!=...` (`label!=` or `label!==`), which removes volumes without the specified labels. - ## Related commands * [volume create](volume_create.md) diff --git a/docs/reference/commandline/volume_rm.md b/docs/reference/commandline/volume_rm.md index 11cac0be42..279f8e0542 100644 --- a/docs/reference/commandline/volume_rm.md +++ b/docs/reference/commandline/volume_rm.md @@ -20,7 +20,7 @@ Remove one or more volumes. You cannot remove a volume that is in use by a conta ## 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 diff --git a/docs/reference/run.md b/docs/reference/run.md index 1dfb55936b..7eef5339ba 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -1207,7 +1207,7 @@ The health status is also displayed in the `docker ps` output. ### 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 starting a container, you can override the `USER` instruction by passing the `-u` option. @@ -1240,4 +1240,4 @@ $ docker run --rm -w /my/workdir alpine pwd /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.