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

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

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

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

@ -22,13 +22,14 @@ Attach local standard input, output, and error streams to a running container
Use `docker attach` to attach your terminal's standard input, output, and error
(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

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

@ -60,11 +60,11 @@ pre-packaged tarball contexts and plain text files.
When the `URL` parameter points to the location of a Git repository, the
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.
### <a name="tag"></a> 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.
### <a name="cgroup-parent"></a> Use a custom parent cgroup (--cgroup-parent)
@ -396,7 +393,7 @@ container to be started using those [`--ulimit` flag values](run.md#ulimit).
You can use `ENV` instructions in a Dockerfile to define variable
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

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

@ -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

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

@ -156,7 +156,7 @@ By default, the Docker command line stores its configuration files in a
directory called `.docker` within your `$HOME` directory.
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`
@ -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-<value>` 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 |
@ -279,6 +275,7 @@ sections for configuring proxy settings for the cli and daemon.
> 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/<registry_url>/ca.crt` in your docker config directory.
`tls/<registry_url>/ca.crt` in your Docker config directory.
Alternatively you can trust the certificate globally by adding it to your system's
list of root Certificate Authorities.

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

@ -22,21 +22,18 @@ Create a new image from a container's changes
## Description
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

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

@ -21,7 +21,7 @@ For detailed information about using configs, refer to [store configuration data
> **Note**
>
> 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)

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

@ -27,7 +27,7 @@ For detailed information about using configs, refer to [store configuration data
> **Note**
>
> 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)

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

@ -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.

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

@ -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

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

@ -48,7 +48,7 @@ relative to the daemon machine’s time. Supported formats for date
formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`,
`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

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

@ -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
### <a name="docker"></a> Create a context with a docker endpoint (--docker)
### <a name="docker"></a> Create a context with a Docker endpoint (--docker)
To create a context from scratch provide the docker and, if required,
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

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

@ -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.

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

@ -48,8 +48,8 @@ machine are created with the `UID:GID` of the user which invoked the `docker cp`
command. However, if you specify the `-a` option, `docker cp` sets the ownership
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

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

@ -120,14 +120,14 @@ Create a new container
The `docker container create` (or shorthand: `docker create`) command creates a
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`

363
docs/reference/commandline/dockerd.md
View 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. |
@ -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:

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

@ -23,7 +23,7 @@ Get real time events from the server
Use `docker events` to get real-time events from the server. These events differ
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=<name or id>`)
* container (`container=<name or id>`)
* daemon (`daemon=<name or id>`)
* event (`event=<event action>`)
* image (`image=<repository or tag>`)
* label (`label=<key>` or `label=<key>=<value>`)
* network (`network=<name or id>`)
* node (`node=<id>`)
* plugin (`plugin=<name or id>`)
* scope (`scope=<local or swarm>`)
* secret (`secret=<name or id>`)
* service (`service=<name or id>`)
* type (`type=<container or image or volume or network or daemon or plugin or service or node or secret or config>`)
* volume (`volume=<name>`)
- config (`config=<name or id>`)
- container (`container=<name or id>`)
- daemon (`daemon=<name or id>`)
- event (`event=<event action>`)
- image (`image=<repository or tag>`)
- label (`label=<key>` or `label=<key>=<value>`)
- network (`network=<name or id>`)
- node (`node=<id>`)
- plugin (`plugin=<name or id>`)
- scope (`scope=<local or swarm>`)
- secret (`secret=<name or id>`)
- service (`service=<name or id>`)
- type (`type=<container or image or volume or network or daemon or plugin or service or node or secret or config>`)
- volume (`volume=<name>`)
#### <a name="format"></a> 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 <https://jsonlines.org/>.
## 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..
```
.

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

@ -28,17 +28,16 @@ Execute a command in a running container
The `docker exec` command runs a new command in a running container.
The 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
@ -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:

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

@ -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

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

@ -62,9 +62,9 @@ Valid placeholders for the Go template are listed below:
| `.Size` | Image disk size |
| `.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`

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

@ -125,7 +125,6 @@ The `docker run` command runs a command in a new container, pulling the image if
You can restart a stopped container with all its previous changes intact using `docker start`.
Use `docker ps -a` to view a list of all containers, including those that are stopped.
## Examples
### <a name="name"></a> Assign name (--name)
@ -281,9 +280,14 @@ container.
The UTS namespace is for setting the hostname and the domain that's visible to
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:<donor-name-or-ID>"` for other containers.
### <a name="privileged"></a> Full container capabilities (--privileged)
The following example doesn't work, because by default, Docker drops most
potentially dangerous kernel capabilities, including `CAP_SYS_ADMIN ` (which is
required to mount filesystems).
```console
$ 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.
### <a name="workdir"></a> 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.
### <a name="storage-opt"></a> Set storage driver options per container (--storage-opt)
@ -384,6 +391,8 @@ container with the `rw`, `noexec`, `nosuid`, `size=65536k` options.
$ docker run -d --tmpfs /run:rw,noexec,nosuid,size=65536k my_image
```
For more information, see [tmpfs mounts](https://docs.docker.com/storage/tmpfs/#tmpfs-mounts).
### <a name="volume"></a> 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 `<variable>=value` (which sets the variable to the given value) or
`<variable>` (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.
`<variable>` (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/).
### <a name="network"></a> Connect a container to a network (--network)
@ -887,9 +896,9 @@ $ cat somefile | docker run -i -a stdin mybuilder dobuild
> **Note**
>
> 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.
### <a name="add-host"></a> Add entries to container hosts file (--add-host)
@ -1315,7 +1324,7 @@ use the following command:
$ docker run --security-opt no-new-privileges -it ubuntu bash
```
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).

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

@ -5,30 +5,30 @@ Initialize a swarm
### Options
| Name | Type | Default | Description |
|:----------------------------------|:--------------|:---------------|:-----------------------------------------------------------------------------------------------------------------------------|
| `--advertise-addr` | `string` | | Advertised address (format: `<ip\|interface>[: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: `<ip\|interface>`) |
| `--data-path-port` | `uint32` | `0` | Port number to use for data path traffic (1024 - 49151). If no value is set or is set to 0, the default port (4789) is used. |
| `--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: `<ip\|interface>[: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: `<ip\|interface>[: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: `<ip\|interface>`) |
| [`--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: `<ip\|interface>[: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 |
<!---MARKER_GEN_END-->
## 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`
### <a name="autolock"></a> 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`
### <a name=""></a> Configure node healthcheck frequency (--dispatcher-heartbeat)
This flag sets the validity period for node certificates.
The `--dispatcher-heartbeat` flag sets the frequency at which nodes are told to
report their health.
### `--dispatcher-heartbeat`
### <a name="external-ca"></a> Use an external certificate authority (--external-ca)
This flag sets the frequency with which nodes are told to use as a
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`
### <a name="force-new-cluster"></a> Force-restart node as a single-mode manager (--force-new-cluster)
This flag sets up the swarm to use an external CA to issue node certificates. The value takes
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`
### <a name="listen-addr"></a> Specify interface for inbound control plane traffic (--listen-addr)
This flag forces an existing node that was part of a quorum that was lost to restart as a single node Manager without losing its data.
### `--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`
### <a name="advertise-addr"></a> Specify interface for outbound control plane traffic (--advertise-addr)
This flag specifies the address that will be advertised to other members of the
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`
### <a name="data-path-addr"></a> Specify interface for data traffic (--data-path-addr)
This flag specifies the address that global scope network drivers will publish towards
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;
### <a name="data-path-port"></a> 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`
### <a name="default-addr-pool"></a> 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`
### <a name="max-snapshots"></a> Set limit for number of snapshots to keep (--max-snapshots)
This flag sets the number of old Raft snapshots to retain in addition to the
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`
### <a name="snapshot-interval"></a> Configure Raft snapshot log interval (--snapshot-interval)
This flag specifies how many log entries to allow in between Raft snapshots.
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`
### <a name="availability"></a> Configure the availability of a manager (--availability)
This flag specifies the availability of the node at the time the node joins a master.
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)

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

@ -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 (`:`):

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

@ -108,11 +108,11 @@ Docker daemons report the following events:
The `--since` and `--until` parameters can be Unix timestamps, date formatted
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=<name or id>`)
* daemon (`daemon=<name or id>`)
* event (`event=<event action>`)
* image (`image=<tag or id>`)
* label (`label=<key>` or `label=<key>=<value>`)
* network (`network=<name or id>`)
* plugin (`plugin=<name or id>`)
* type (`type=<container or image or volume or network or daemon or plugin>`)
* volume (`volume=<name or id>`)
- container (`container=<name or id>`)
- daemon (`daemon=<name or id>`)
- event (`event=<event action>`)
- image (`image=<tag or id>`)
- label (`label=<key>` or `label=<key>=<value>`)
- network (`network=<name or id>`)
- plugin (`plugin=<name or id>`)
- type (`type=<container or image or volume or network or daemon or plugin>`)
- volume (`volume=<name or id>`)
## 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'
### <a name="format"></a> Format the output (--format)
If a format (`--format`) is specified, the given template will be executed
If you specify a format (`--format`), the given template is executed
instead of the default format. Go's [text/template](https://pkg.go.dev/text/template)
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 <https://jsonlines.org/>.
```console
$ docker system events --format '{{json .}}'

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

@ -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

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

@ -17,30 +17,30 @@ A full image name has the following format and components:
`[HOST[:PORT_NUMBER]/]PATH`
- `HOST`: 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

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

@ -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

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

@ -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`.

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

@ -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

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

@ -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

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

@ -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

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

@ -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
```

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

@ -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.
### <a name="opt"></a> Driver-specific options (-o, --opt)
@ -74,13 +74,12 @@ $ docker volume create --driver fake \
These options are passed directly to the volume driver. Options for
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.

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

@ -52,7 +52,7 @@ than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "b
The currently supported filters are:
- dangling (boolean - true or false, 0 or 1)
- dangling (Boolean - true or false, 0 or 1)
- driver (a volume driver's name)
- label (`label=<key>` or `label=<key>=<value>`)
- 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

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

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

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

@ -20,7 +20,7 @@ Remove one or more volumes. You cannot remove a volume that is in use by a conta
## Description
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

4
docs/reference/run.md
View File

@ -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.