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

engine: update reference docs with latest changes from 20.10 branch 

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Sebastiaan van Stijn 2022-04-01 21:37:25 +02:00
parent e9e09ef39d
commit 098129a0c1
No known key found for this signature in database
GPG Key ID: 76698F39D527CE8C
27 changed files with 307 additions and 255 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
_data/engine-cli/docker_build.yaml
View File

@ -41,16 +41,16 @@ long: |-
The following table represents all the valid suffixes with their build The following table represents all the valid suffixes with their build
contexts: contexts:
Build Syntax Suffix | Commit Used | Build Context Used | Build Syntax Suffix | Commit Used | Build Context Used |
--------------------------------|-----------------------|------------------- |--------------------------------|-----------------------|--------------------|
`myrepo.git` | `refs/heads/master` | `/` | `myrepo.git` | `refs/heads/master` | `/` |
`myrepo.git#mytag` | `refs/tags/mytag` | `/` | `myrepo.git#mytag` | `refs/tags/mytag` | `/` |
`myrepo.git#mybranch` | `refs/heads/mybranch` | `/` | `myrepo.git#mybranch` | `refs/heads/mybranch` | `/` |
`myrepo.git#pull/42/head` | `refs/pull/42/head` | `/` | `myrepo.git#pull/42/head` | `refs/pull/42/head` | `/` |
`myrepo.git#:myfolder` | `refs/heads/master` | `/myfolder` | `myrepo.git#:myfolder` | `refs/heads/master` | `/myfolder` |
`myrepo.git#master:myfolder` | `refs/heads/master` | `/myfolder` | `myrepo.git#master:myfolder` | `refs/heads/master` | `/myfolder` |
`myrepo.git#mytag:myfolder` | `refs/tags/mytag` | `/myfolder` | `myrepo.git#mytag:myfolder` | `refs/tags/mytag` | `/myfolder` |
`myrepo.git#mybranch:myfolder` | `refs/heads/mybranch` | `/myfolder` | `myrepo.git#mybranch:myfolder` | `refs/heads/mybranch` | `/myfolder` |
> **Note** > **Note**
> >
@ -699,11 +699,11 @@ examples: |-
Linux namespaces. On Microsoft Windows, you can specify these values: Linux namespaces. On Microsoft Windows, you can specify these values:
| Value | Description | | Value | Description |
|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| |-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `default` | Use the value specified by the Docker daemon's `--exec-opt` . If the `daemon` does not specify an isolation technology, Microsoft Windows uses `process` as its default value. | | `default` | Use the value specified by the Docker daemon's `--exec-opt` . If the `daemon` does not specify an isolation technology, Microsoft Windows uses `process` as its default value. |
| `process` | Namespace isolation only. | | `process` | Namespace isolation only. |
| `hyperv` | Hyper-V hypervisor partition-based isolation. | | `hyperv` | Hyper-V hypervisor partition-based isolation. |
Specifying the `--isolation` flag without a value is the same as setting `--isolation="default"`. Specifying the `--isolation` flag without a value is the same as setting `--isolation="default"`.
@ -723,10 +723,10 @@ examples: |-
```dockerfile ```dockerfile
FROM debian AS build-env FROM debian AS build-env
... # ...
FROM alpine AS production-env FROM alpine AS production-env
... # ...
``` ```
```console ```console

2
_data/engine-cli/docker_checkpoint.yaml
View File

@ -5,7 +5,7 @@ long: |-
container by checkpointing it, which turns its state into a collection of files container by checkpointing it, which turns its state into a collection of files
on disk. Later, the container can be restored from the point it was frozen. on disk. Later, the container can be restored from the point it was frozen.
This is accomplished using a tool called [CRIU](http://criu.org), which is an This is accomplished using a tool called [CRIU](https://criu.org), which is an
external dependency of this feature. A good overview of the history of external dependency of this feature. A good overview of the history of
checkpoint and restore in Docker is available in this checkpoint and restore in Docker is available in this
[Kubernetes blog post](https://kubernetes.io/blog/2015/07/how-did-quake-demo-from-dockercon-work/). [Kubernetes blog post](https://kubernetes.io/blog/2015/07/how-did-quake-demo-from-dockercon-work/).

2
_data/engine-cli/docker_config_ls.yaml
View File

@ -121,7 +121,7 @@ examples: |-
Valid placeholders for the Go template are listed below: Valid placeholders for the Go template are listed below:
| Placeholder | Description | | Placeholder | Description |
| ------------ | ------------------------------------------------------------------------------------ | |--------------|--------------------------------------------------------------------------------------|
| `.ID` | Config ID | | `.ID` | Config ID |
| `.Name` | Config name | | `.Name` | Config name |
| `.CreatedAt` | Time when the config was created | | `.CreatedAt` | Time when the config was created |

2
_data/engine-cli/docker_context.yaml
View File

@ -1,6 +1,6 @@
command: docker context command: docker context
short: Manage contexts short: Manage contexts
long: Manage contexts long: Manage contexts.
usage: docker context usage: docker context
pname: docker pname: docker
plink: docker.yaml plink: docker.yaml

58
_data/engine-cli/docker_cp.yaml
View File

@ -64,25 +64,6 @@ long: |-
you must be explicit with a relative or absolute path, for example: you must be explicit with a relative or absolute path, for example:
`/path/to/file:name.txt` or `./file:name.txt` `/path/to/file:name.txt` or `./file:name.txt`
It is not possible to copy certain system files such as resources under
`/proc`, `/sys`, `/dev`, [tmpfs](run.md#mount-tmpfs---tmpfs), and mounts created by
the user in the container. However, you can still copy such files by manually
running `tar` in `docker exec`. Both of the following examples do the same thing
in different ways (consider `SRC_PATH` and `DEST_PATH` are directories):
```console
$ docker exec CONTAINER tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | tar Cxf DEST_PATH -
```
```console
$ tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | docker exec -i CONTAINER tar Cxf DEST_PATH -
```
Using `-` as the `SRC_PATH` streams the contents of `STDIN` as a tar archive.
The command extracts the content of the tar to the `DEST_PATH` in container's
filesystem. In this case, `DEST_PATH` must specify a directory. Using `-` as
the `DEST_PATH` streams the contents of the resource as a tar archive to `STDOUT`.
usage: "docker cp [OPTIONS] CONTAINER:SRC_PATH DEST_PATH|-\n\tdocker cp [OPTIONS] usage: "docker cp [OPTIONS] CONTAINER:SRC_PATH DEST_PATH|-\n\tdocker cp [OPTIONS]
SRC_PATH|- CONTAINER:DEST_PATH" SRC_PATH|- CONTAINER:DEST_PATH"
pname: docker pname: docker
@ -108,6 +89,45 @@ options:
experimentalcli: false experimentalcli: false
kubernetes: false kubernetes: false
swarm: false swarm: false
examples: |-
Copy a local file into container
```console
$ docker cp ./some_file CONTAINER:/work
```
Copy files from container to local path
```console
$ docker cp CONTAINER:/var/logs/ /tmp/app_logs
```
Copy a file from container to stdout. Please note `cp` command produces a tar stream
```console
$ docker cp CONTAINER:/var/logs/app.log - | tar x -O | grep "ERROR"
```
### Corner cases
It is not possible to copy certain system files such as resources under
`/proc`, `/sys`, `/dev`, [tmpfs](run.md#mount-tmpfs---tmpfs), and mounts created by
the user in the container. However, you can still copy such files by manually
running `tar` in `docker exec`. Both of the following examples do the same thing
in different ways (consider `SRC_PATH` and `DEST_PATH` are directories):
```console
$ docker exec CONTAINER tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | tar Cxf DEST_PATH -
```
```console
$ tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | docker exec -i CONTAINER tar Cxf DEST_PATH -
```
Using `-` as the `SRC_PATH` streams the contents of `STDIN` as a tar archive.
The command extracts the content of the tar to the `DEST_PATH` in container's
filesystem. In this case, `DEST_PATH` must specify a directory. Using `-` as
the `DEST_PATH` streams the contents of the resource as a tar archive to `STDOUT`.
deprecated: false deprecated: false
experimental: false experimental: false
experimentalcli: false experimentalcli: false

92
_data/engine-cli/docker_create.yaml
View File

@ -1,17 +1,23 @@
command: docker create command: docker create
short: Create a new container short: Create a new container
long: |- long: |-
The `docker create` command creates a writeable container layer over the The `docker container create` (or shorthand: `docker create`) command creates a
specified image and prepares it for running the specified command. The 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` 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 except the container is never started. You can then use the `docker container start`
`docker start <container_id>` command to start the container at any point. (or shorthand: `docker start`) command to start the container at any point.
This is useful when you want to set up a container configuration ahead of time This is useful when you want to set up a container configuration ahead of time
so that it is ready to start when you need it. The initial status of the so that it is ready to start when you need it. The initial status of the
new container is `created`. new container is `created`.
Please see the [run command](run.md) section and the [Docker run reference](../run.md) for more details. The `docker create` command shares most of its options with the `docker run`
command (which performs a `docker create` before starting it). Refer to the
[`docker run` command](run.md) section and the [Docker run reference](../run.md)
for details on the available flags and options.
usage: docker create [OPTIONS] IMAGE [COMMAND] [ARG...] usage: docker create [OPTIONS] IMAGE [COMMAND] [ARG...]
pname: docker pname: docker
plink: docker.yaml plink: docker.yaml
@ -900,19 +906,29 @@ options:
examples: |- examples: |-
### Create and start a container ### Create and start a container
```console The following example creates an interactive container with a pseudo-TTY attached,
$ docker create -t -i fedora bash then starts the container and attaches to it:
```console
$ docker container create -i -t --name mycontainer alpine
6d8af538ec541dd581ebc2a24153a28329acb5268abe5ef868c1f1a261221752 6d8af538ec541dd581ebc2a24153a28329acb5268abe5ef868c1f1a261221752
$ docker start -a -i 6d8af538ec5 $ docker container start --attach -i mycontainer
/ # echo hello world
hello world
```
bash-4.2# The above is the equivalent of a `docker run`:
```console
$ docker run -it --name mycontainer2 alpine
/ # echo hello world
hello world
``` ```
### Initialize volumes ### Initialize volumes
As of v1.4.0 container volumes are initialized during the `docker create` phase Container volumes are initialized during the `docker create` phase
(i.e., `docker run` too). For example, this allows you to `create` the `data` (i.e., `docker run` too). For example, this allows you to `create` the `data`
volume container, and then use it from another container: volume container, and then use it from another container:
@ -949,62 +965,6 @@ examples: |-
drwx--S--- 2 1000 staff 460 Dec 5 00:51 .ssh drwx--S--- 2 1000 staff 460 Dec 5 00:51 .ssh
drwxr-xr-x 32 1000 staff 1140 Dec 5 04:01 docker drwxr-xr-x 32 1000 staff 1140 Dec 5 04:01 docker
``` ```
Set storage driver options per container.
```console
$ docker create -it --storage-opt size=120G fedora /bin/bash
```
This (size) will allow to set the container rootfs size to 120G at creation time.
This option is only available for the `devicemapper`, `btrfs`, `overlay2`,
`windowsfilter` and `zfs` graph drivers.
For the `devicemapper`, `btrfs`, `windowsfilter` and `zfs` graph drivers,
user cannot pass a size less than the Default BaseFS Size.
For the `overlay2` storage driver, the size option is only available if the
backing fs is `xfs` and mounted with the `pquota` mount option.
Under these conditions, user can pass any size less than the backing fs size.
### Specify isolation technology for container (--isolation)
This option is useful in situations where you are running Docker containers on
Windows. The `--isolation=<value>` option sets a container's isolation
technology. On Linux, the only supported is the `default` option which uses
Linux namespaces. On Microsoft Windows, you can specify these values:
| Value | Description |
|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `default` | Use the value specified by the Docker daemon's `--exec-opt` . If the `daemon` does not specify an isolation technology, Microsoft Windows uses `process` as its default value if the
daemon is running on Windows server, or `hyperv` if running on Windows client. |
| `process` | Namespace isolation only. |
| `hyperv` | Hyper-V hypervisor partition-based isolation. |
Specifying the `--isolation` flag without a value is the same as setting `--isolation="default"`.
### Dealing with dynamically created devices (--device-cgroup-rule)
Devices available to a container are assigned at creation time. The
assigned devices will both be added to the cgroup.allow file and
created into the container once it is run. This poses a problem when
a new device needs to be added to running container.
One of the solutions is to add a more permissive rule to a container
allowing it access to a wider range of devices. For example, supposing
our container needs access to a character device with major `42` and
any number of minor number (added as new devices appear), the
following rule would be added:
```console
$ docker create --device-cgroup-rule='c 42:* rmw' -name my-container my-image
```
Then, a user could ask `udev` to execute a script that would `docker exec my-container mknod newDevX c 42 <minor>`
the required device when it is added.
NOTE: initially present devices still need to be explicitly added to
the create/run command
deprecated: false deprecated: false
experimental: false experimental: false
experimentalcli: false experimentalcli: false

14
_data/engine-cli/docker_history.yaml
View File

@ -75,14 +75,14 @@ examples: |-
Valid placeholders for the Go template are listed below: Valid placeholders for the Go template are listed below:
| Placeholder | Description | | Placeholder | Description |
| --------------- | ----------- | |-----------------|-----------------------------------------------------------------------------------------------------------|
| `.ID` | Image ID | | `.ID` | Image ID |
| `.CreatedSince` | Elapsed time since the image was created if `--human=true`, otherwise timestamp of when image was created | | `.CreatedSince` | Elapsed time since the image was created if `--human=true`, otherwise timestamp of when image was created |
| `.CreatedAt` | Timestamp of when image was created | | `.CreatedAt` | Timestamp of when image was created |
| `.CreatedBy` | Command that was used to create the image | | `.CreatedBy` | Command that was used to create the image |
| `.Size` | Image disk size | | `.Size` | Image disk size |
| `.Comment` | Comment for image | | `.Comment` | Comment for image |
When using the `--format` option, the `history` command will either When using the `--format` option, the `history` command will either
output the data exactly as the template declares or, when using the output the data exactly as the template declares or, when using the

16
_data/engine-cli/docker_images.yaml
View File

@ -323,15 +323,15 @@ examples: |-
Valid placeholders for the Go template are listed below: Valid placeholders for the Go template are listed below:
| Placeholder | Description| | Placeholder | Description |
| ---- | ---- | |-----------------|------------------------------------------|
| `.ID` | Image ID | | `.ID` | Image ID |
| `.Repository` | Image repository | | `.Repository` | Image repository |
| `.Tag` | Image tag | | `.Tag` | Image tag |
| `.Digest` | Image digest | | `.Digest` | Image digest |
| `.CreatedSince` | Elapsed time since the image was created | | `.CreatedSince` | Elapsed time since the image was created |
| `.CreatedAt` | Time when the image was created | | `.CreatedAt` | Time when the image was created |
| `.Size` | Image disk size | | `.Size` | Image disk size |
When using the `--format` option, the `image` command will either When using the `--format` option, the `image` command will either
output the data exactly as the template declares or, when using the output the data exactly as the template declares or, when using the

7
_data/engine-cli/docker_import.yaml
View File

@ -9,9 +9,8 @@ long: |-
the host. To import from a remote location, specify a `URI` that begins with the the host. To import from a remote location, specify a `URI` that begins with the
`http://` or `https://` protocol. `http://` or `https://` protocol.
The `--change` option will apply `Dockerfile` instructions to the image The `--change` option applies `Dockerfile` instructions to the image that is
that is created. created. Supported `Dockerfile` instructions:
Supported `Dockerfile` instructions:
`CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR`
usage: docker import [OPTIONS] file|URL|- [REPOSITORY[:TAG]] usage: docker import [OPTIONS] file|URL|- [REPOSITORY[:TAG]]
pname: docker pname: docker
@ -47,7 +46,7 @@ options:
examples: |- examples: |-
### Import from a remote location ### Import from a remote location
This will create a new untagged image. This creates a new untagged image.
```console ```console
$ docker import https://example.com/exampleimage.tgz $ docker import https://example.com/exampleimage.tgz

10
_data/engine-cli/docker_network_connect.yaml
View File

@ -68,7 +68,8 @@ examples: |-
### Connect a container to a network when it starts ### Connect a container to a network when it starts
You can also use the `docker run --network=<network-name>` option to start a container and immediately connect it to a network. You can also use the `docker run --network=<network-name>` option to start a
container and immediately connect it to a network.
```console ```console
$ docker run -itd --network=multi-host-network busybox $ docker run -itd --network=multi-host-network busybox
@ -119,14 +120,17 @@ examples: |-
$ docker network connect --ip 172.20.128.2 multi-host-network container2 $ docker network connect --ip 172.20.128.2 multi-host-network container2
``` ```
To verify the container is connected, use the `docker network inspect` command. Use `docker network disconnect` to remove a container from the network. To verify the container is connected, use the `docker network inspect` command.
Use `docker network disconnect` to remove a container from the network.
Once connected in network, containers can communicate using only another Once connected in network, containers can communicate using only another
container's IP address or name. For `overlay` networks or custom plugins that container's IP address or name. For `overlay` networks or custom plugins that
support multi-host connectivity, containers connected to the same multi-host support multi-host connectivity, containers connected to the same multi-host
network but launched from different Engines can also communicate in this way. network but launched from different Engines can also communicate in this way.
You can connect a container to one or more networks. The networks need not be the same type. For example, you can connect a single container bridge and overlay networks. You can connect a container to one or more networks. The networks need not be
the same type. For example, you can connect a single container bridge and overlay
networks.
deprecated: false deprecated: false
min_api_version: "1.21" min_api_version: "1.21"
experimental: false experimental: false

2
_data/engine-cli/docker_network_create.yaml
View File

@ -300,7 +300,7 @@ examples: |-
|--------------|----------------|--------------------------------------------| |--------------|----------------|--------------------------------------------|
| `--gateway` | - | IPv4 or IPv6 Gateway for the master subnet | | `--gateway` | - | IPv4 or IPv6 Gateway for the master subnet |
| `--ip-range` | `--fixed-cidr` | Allocate IPs from a range | | `--ip-range` | `--fixed-cidr` | Allocate IPs from a range |
| `--internal` | - | Restrict external access to the network | | `--internal` | - | Restrict external access to the network |
| `--ipv6` | `--ipv6` | Enable IPv6 networking | | `--ipv6` | `--ipv6` | Enable IPv6 networking |
| `--subnet` | `--bip` | Subnet for network | | `--subnet` | `--bip` | Subnet for network |

22
_data/engine-cli/docker_network_ls.yaml
View File

@ -220,17 +220,17 @@ examples: |-
Valid placeholders for the Go template are listed below: Valid placeholders for the Go template are listed below:
Placeholder | Description | Placeholder | Description |
-------------|------------------------------------------------------------------------------------------ |--------------|----------------------------------------------------------------------------------------|
`.ID` | Network ID | `.ID` | Network ID |
`.Name` | Network name | `.Name` | Network name |
`.Driver` | Network driver | `.Driver` | Network driver |
`.Scope` | Network scope (local, global) | `.Scope` | Network scope (local, global) |
`.IPv6` | Whether IPv6 is enabled on the network or not. | `.IPv6` | Whether IPv6 is enabled on the network or not. |
`.Internal` | Whether the network is internal or not. | `.Internal` | Whether the network is internal or not. |
`.Labels` | All labels assigned to the network. | `.Labels` | All labels assigned to the network. |
`.Label` | Value of a specific label for this network. For example `{{.Label "project.version"}}` | `.Label` | Value of a specific label for this network. For example `{{.Label "project.version"}}` |
`.CreatedAt` | Time when the network was created | `.CreatedAt` | Time when the network was created |
When using the `--format` option, the `network ls` command will either When using the `--format` option, the `network ls` command will either
output the data exactly as the template declares or, when using the output the data exactly as the template declares or, when using the

20
_data/engine-cli/docker_node_ls.yaml
View File

@ -185,16 +185,16 @@ examples: |-
Valid placeholders for the Go template are listed below: Valid placeholders for the Go template are listed below:
Placeholder | Description | Placeholder | Description |
-----------------|------------------------------------------------------------------------------------------ |------------------|-------------------------------------------------------------------------------------------------------|
`.ID` | Node ID | `.ID` | Node ID |
`.Self` | Node of the daemon (`true/false`, `true`indicates that the node is the same as current docker daemon) | `.Self` | Node of the daemon (`true/false`, `true`indicates that the node is the same as current docker daemon) |
`.Hostname` | Node hostname | `.Hostname` | Node hostname |
`.Status` | Node status | `.Status` | Node status |
`.Availability` | Node availability ("active", "pause", or "drain") | `.Availability` | Node availability ("active", "pause", or "drain") |
`.ManagerStatus` | Manager status of the node | `.ManagerStatus` | Manager status of the node |
`.TLSStatus` | TLS status of the node ("Ready", or "Needs Rotation" has TLS certificate signed by an old CA) | `.TLSStatus` | TLS status of the node ("Ready", or "Needs Rotation" has TLS certificate signed by an old CA) |
`.EngineVersion` | Engine version | `.EngineVersion` | Engine version |
When using the `--format` option, the `node ls` command will either When using the `--format` option, the `node ls` command will either
output the data exactly as the template declares or, when using the output the data exactly as the template declares or, when using the

20
_data/engine-cli/docker_node_ps.yaml
View File

@ -140,16 +140,16 @@ examples: |-
Valid placeholders for the Go template are listed below: Valid placeholders for the Go template are listed below:
Placeholder | Description | Placeholder | Description |
----------------|------------------------------------------------------------------------------------------ |-----------------|------------------------------------------------------------------|
`.ID` | Task ID | `.ID` | Task ID |
`.Name` | Task name | `.Name` | Task name |
`.Image` | Task image | `.Image` | Task image |
`.Node` | Node ID | `.Node` | Node ID |
`.DesiredState` | Desired state of the task (`running`, `shutdown`, or `accepted`) | `.DesiredState` | Desired state of the task (`running`, `shutdown`, or `accepted`) |
`.CurrentState` | Current state of the task | `.CurrentState` | Current state of the task |
`.Error` | Error | `.Error` | Error |
`.Ports` | Task published ports | `.Ports` | Task published ports |
When using the `--format` option, the `node ps` command will either When using the `--format` option, the `node ps` command will either
output the data exactly as the template declares or, when using the output the data exactly as the template declares or, when using the

14
_data/engine-cli/docker_plugin_ls.yaml
View File

@ -91,13 +91,13 @@ examples: |-
Valid placeholders for the Go template are listed below: Valid placeholders for the Go template are listed below:
Placeholder | Description | Placeholder | Description |
-------------------|------------------------------------------------------------ |--------------------|-------------------------------------------------|
`.ID` | Plugin ID | `.ID` | Plugin ID |
`.Name` | Plugin name and tag | `.Name` | Plugin name and tag |
`.Description` | Plugin description | `.Description` | Plugin description |
`.Enabled` | Whether plugin is enabled or not | `.Enabled` | Whether plugin is enabled or not |
`.PluginReference` | The reference used to push/pull from a registry | `.PluginReference` | The reference used to push/pull from a registry |
When using the `--format` option, the `plugin ls` command will either When using the `--format` option, the `plugin ls` command will either
output the data exactly as the template declares or, when using the output the data exactly as the template declares or, when using the

6
_data/engine-cli/docker_pull.yaml
View File

@ -130,8 +130,8 @@ examples: |-
So far, you've pulled images by their name (and "tag"). Using names and tags is So far, you've pulled images by their name (and "tag"). Using names and tags is
a convenient way to work with images. When using tags, you can `docker pull` an a convenient way to work with images. When using tags, you can `docker pull` an
image again to make sure you have the most up-to-date version of that image. image again to make sure you have the most up-to-date version of that image.
For example, `docker pull ubuntu:14.04` pulls the latest version of the Ubuntu For example, `docker pull ubuntu:20.04` pulls the latest version of the Ubuntu
14.04 image. 20.04 image.
In some cases you don't want images to be updated to newer versions, but prefer In some cases you don't want images to be updated to newer versions, but prefer
to use a fixed version of an image. Docker enables you to pull an image by its to use a fixed version of an image. Docker enables you to pull an image by its
@ -140,7 +140,7 @@ examples: |-
and guarantee that the image you're using is always the same. and guarantee that the image you're using is always the same.
To know the digest of an image, pull the image first. Let's pull the latest To know the digest of an image, pull the image first. Let's pull the latest
`ubuntu:14.04` image from Docker Hub: `ubuntu:20.04` image from Docker Hub:
```console ```console
$ docker pull ubuntu:20.04 $ docker pull ubuntu:20.04

100
_data/engine-cli/docker_run.yaml
View File

@ -1114,7 +1114,7 @@ examples: |-
Note that ports which are not bound to the host (i.e., `-p 80:80` instead of Note that ports which are not bound to the host (i.e., `-p 80:80` instead of
`-p 127.0.0.1:80:80`) will be accessible from the outside. This also applies if `-p 127.0.0.1:80:80`) will be accessible from the outside. This also applies if
you configured UFW to block this specific port, as Docker manages his you configured UFW to block this specific port, as Docker manages its
own iptables rules. [Read more](https://docs.docker.com/network/iptables/) own iptables rules. [Read more](https://docs.docker.com/network/iptables/)
```console ```console
@ -1124,6 +1124,48 @@ examples: |-
This exposes port `80` of the container without publishing the port to the host This exposes port `80` of the container without publishing the port to the host
system's interfaces. system's interfaces.
### <a name="pull"></a> Set the pull policy (--pull)
Use the `--pull` flag to set the image pull policy when creating (and running)
the container.
The `--pull` flag can take one of these values:
| Value | Description |
|:--------------------|:------------------------------------------------------------------------------------------------------------------|
| `missing` (default) | Pull the image if it was not found in the image cache, or use the cached image otherwise. |
| `never` | Do not pull the image, even if it's missing, and produce an error if the image does not exist in the image cache. |
| `always` | Always perform a pull before creating the container. |
When creating (and running) a container from an image, the daemon checks if the
image exists in the local image cache. If the image is missing, an error is
returned to the cli, allowing it to initiate a pull.
The default (`missing`) is to only pull the image if it is not present in the
daemon's image cache. This default allows you to run images that only exist
locally (for example, images you built from a Dockerfile, but that have not
been pushed to a registry), and reduces networking.
The `always` option always initiates a pull before creating the container. This
option makes sure the image is up-to-date, and prevents you from using outdated
images, but may not be suitable in situations where you want to test a locally
built image before pushing (as pulling the image overwrites the existing image
in the image cache).
The `never` option disables (implicit) pulling images when creating containers,
and only uses images that are available in the image cache. If the specified
image is not found, an error is produced, and the container is not created.
This option is useful in situations where networking is not available, or to
prevent images from being pulled implicitly when creating containers.
The following example shows `docker run` with the `--pull=never` option set,
which produces en error as the image is missing in the image-cache:
```console
$ docker run --pull=never hello-world
docker: Error response from daemon: No such image: hello-world:latest.
```
### Set environment variables (-e, --env, --env-file) ### Set environment variables (-e, --env, --env-file)
```console ```console
@ -1169,10 +1211,10 @@ examples: |-
VAR2=value2 VAR2=value2
USER USER
$ docker run --env-file env.list ubuntu env | grep VAR $ docker run --env-file env.list ubuntu env | grep -E 'VAR|USER'
VAR1=value1 VAR1=value1
VAR2=value2 VAR2=value2
USER=denis USER=jonzeolla
``` ```
### Set metadata on container (-l, --label, --label-file) ### Set metadata on container (-l, --label, --label-file)
@ -1376,9 +1418,32 @@ examples: |-
> This option fails if the container isolation is `hyperv` or when running Linux > This option fails if the container isolation is `hyperv` or when running Linux
> Containers on Windows (LCOW). > Containers on Windows (LCOW).
### <a name="device-cgroup-rule"></a> Using dynamically created devices (--device-cgroup-rule)
Devices available to a container are assigned at creation time. The
assigned devices will both be added to the cgroup.allow file and
created into the container once it is run. This poses a problem when
a new device needs to be added to running container.
One of the solutions is to add a more permissive rule to a container
allowing it access to a wider range of devices. For example, supposing
our container needs access to a character device with major `42` and
any number of minor number (added as new devices appear), the
following rule would be added:
```console
$ docker run -d --device-cgroup-rule='c 42:* rmw' -name my-container my-image
```
Then, a user could ask `udev` to execute a script that would `docker exec my-container mknod newDevX c 42 <minor>`
the required device when it is added.
> **Note**: initially present devices still need to be explicitly added to the
> `docker run` / `docker create` command.
### Access an NVIDIA GPU ### Access an NVIDIA GPU
The `--gpus­` flag allows you to access NVIDIA GPU resources. First you need to The `--gpus` flag allows you to access NVIDIA GPU resources. First you need to
install [nvidia-container-runtime](https://nvidia.github.io/nvidia-container-runtime/). install [nvidia-container-runtime](https://nvidia.github.io/nvidia-container-runtime/).
Visit [Specify a container's resources](https://docs.docker.com/config/containers/resource_constraints/) Visit [Specify a container's resources](https://docs.docker.com/config/containers/resource_constraints/)
for more information. for more information.
@ -1400,7 +1465,7 @@ examples: |-
The example below exposes the first and third GPUs. The example below exposes the first and third GPUs.
```console ```console
$ docker run -it --rm --gpus device=0,2 nvidia-smi $ docker run -it --rm --gpus '"device=0,2"' nvidia-smi
``` ```
### Restart policies (--restart) ### Restart policies (--restart)
@ -1485,7 +1550,7 @@ examples: |-
> In other words, the following script is not supported: > In other words, the following script is not supported:
> >
> ```console > ```console
> $ docker run -it --ulimit as=1024 fedora /bin/bash` > $ docker run -it --ulimit as=1024 fedora /bin/bash
> ``` > ```
The values are sent to the appropriate `syscall` as they are set. The values are sent to the appropriate `syscall` as they are set.
@ -1541,9 +1606,9 @@ examples: |-
### Specify isolation technology for container (--isolation) ### Specify isolation technology for container (--isolation)
This option is useful in situations where you are running Docker containers on This option is useful in situations where you are running Docker containers on
Windows. The `--isolation <value>` option sets a container's isolation technology. Windows. The `--isolation=<value>` option sets a container's isolation technology.
On Linux, the only supported is the `default` option which uses On Linux, the only supported is the `default` option which uses Linux namespaces.
Linux namespaces. These two commands are equivalent on Linux: These two commands are equivalent on Linux:
```console ```console
$ docker run -d busybox top $ docker run -d busybox top
@ -1552,16 +1617,15 @@ examples: |-
On Windows, `--isolation` can take one of these values: On Windows, `--isolation` can take one of these values:
| Value | Description |
|:----------|:-------------------------------------------------------------------------------------------|
| `default` | Use the value specified by the Docker daemon's `--exec-opt` or system default (see below). |
| `process` | Shared-kernel namespace isolation. |
| `hyperv` | Hyper-V hypervisor partition-based isolation. |
| Value | Description | The default isolation on Windows server operating systems is `process`, and `hyperv`
|:----------|:------------------------------------------------------------------------------------------------------------------| on Windows client operating systems, such as Windows 10. Process isolation is more
| `default` | Use the value specified by the Docker daemon's `--exec-opt` or system default (see below). | performant, but requires the image to
| `process` | Shared-kernel namespace isolation (not supported on Windows client operating systems older than Windows 10 1809). |
| `hyperv` | Hyper-V hypervisor partition-based isolation. |
The default isolation on Windows server operating systems is `process`. The default
isolation on Windows client operating systems is `hyperv`. An attempt to start a container on a client
operating system older than Windows 10 1809 with `--isolation process` will fail.
On Windows server, assuming the default configuration, these commands are equivalent On Windows server, assuming the default configuration, these commands are equivalent
and result in `process` isolation: and result in `process` isolation:

2
_data/engine-cli/docker_search.yaml
View File

@ -153,7 +153,7 @@ examples: |-
Valid placeholders for the Go template are: Valid placeholders for the Go template are:
| Placeholder | Description | | Placeholder | Description |
| -------------- | --------------------------------- | |----------------|-----------------------------------|
| `.Name` | Image Name | | `.Name` | Image Name |
| `.Description` | Image description | | `.Description` | Image description |
| `.StarCount` | Number of stars for the image | | `.StarCount` | Number of stars for the image |

2
_data/engine-cli/docker_secret_ls.yaml
View File

@ -121,7 +121,7 @@ examples: |-
Valid placeholders for the Go template are listed below: Valid placeholders for the Go template are listed below:
| Placeholder | Description | | Placeholder | Description |
| ------------ | ------------------------------------------------------------------------------------ | |--------------|--------------------------------------------------------------------------------------|
| `.ID` | Secret ID | | `.ID` | Secret ID |
| `.Name` | Secret name | | `.Name` | Secret name |
| `.CreatedAt` | Time when the secret was created | | `.CreatedAt` | Time when the secret was created |

19
_data/engine-cli/docker_service_create.yaml
View File

@ -1240,16 +1240,15 @@ examples: |-
expression (AND match). Constraints can match node or Docker Engine labels as expression (AND match). Constraints can match node or Docker Engine labels as
follows: follows:
node attribute | matches | example | node attribute | matches | example |
---------------------|--------------------------------|----------------------------------------------- |----------------------|--------------------------------|-----------------------------------------------|
`node.id` | Node ID | `node.id==2ivku8v2gvtg4` | `node.id` | Node ID | `node.id==2ivku8v2gvtg4` |
`node.hostname` | Node hostname | `node.hostname!=node-2` | `node.hostname` | Node hostname | `node.hostname!=node-2` |
`node.role` | Node role (`manager`/`worker`) | `node.role==manager` | `node.role` | Node role (`manager`/`worker`) | `node.role==manager` |
`node.platform.os` | Node operating system | `node.platform.os==windows` | `node.platform.os` | Node operating system | `node.platform.os==windows` |
`node.platform.arch` | Node architecture | `node.platform.arch==x86_64` | `node.platform.arch` | Node architecture | `node.platform.arch==x86_64` |
`node.labels` | User-defined node labels | `node.labels.security==high` | `node.labels` | User-defined node labels | `node.labels.security==high` |
`engine.labels` | Docker Engine's labels | `engine.labels.operatingsystem==ubuntu-14.04` | `engine.labels` | Docker Engine's labels | `engine.labels.operatingsystem==ubuntu-14.04` |
`engine.labels` apply to Docker Engine labels like operating system, drivers, `engine.labels` apply to Docker Engine labels like operating system, drivers,
etc. Swarm administrators add `node.labels` for operational purposes by using etc. Swarm administrators add `node.labels` for operational purposes by using

16
_data/engine-cli/docker_service_ls.yaml
View File

@ -138,14 +138,14 @@ examples: |-
Valid placeholders for the Go template are listed below: Valid placeholders for the Go template are listed below:
Placeholder | Description | Placeholder | Description |
------------|------------------------------------------------------------------------------------------ |-------------|-----------------------------------------|
`.ID` | Service ID | `.ID` | Service ID |
`.Name` | Service name | `.Name` | Service name |
`.Mode` | Service mode (replicated, global) | `.Mode` | Service mode (replicated, global) |
`.Replicas` | Service replicas | `.Replicas` | Service replicas |
`.Image` | Service image | `.Image` | Service image |
`.Ports` | Service ports published in ingress mode | `.Ports` | Service ports published in ingress mode |
When using the `--format` option, the `service ls` command will either When using the `--format` option, the `service ls` command will either
output the data exactly as the template declares or, when using the output the data exactly as the template declares or, when using the

20
_data/engine-cli/docker_service_ps.yaml
View File

@ -182,16 +182,16 @@ examples: |-
Valid placeholders for the Go template are listed below: Valid placeholders for the Go template are listed below:
Placeholder | Description | Placeholder | Description |
----------------|------------------------------------------------------------------------------------------ |-----------------|------------------------------------------------------------------|
`.ID` | Task ID | `.ID` | Task ID |
`.Name` | Task name | `.Name` | Task name |
`.Image` | Task image | `.Image` | Task image |
`.Node` | Node ID | `.Node` | Node ID |
`.DesiredState` | Desired state of the task (`running`, `shutdown`, or `accepted`) | `.DesiredState` | Desired state of the task (`running`, `shutdown`, or `accepted`) |
`.CurrentState` | Current state of the task | `.CurrentState` | Current state of the task |
`.Error` | Error | `.Error` | Error |
`.Ports` | Task published ports | `.Ports` | Task published ports |
When using the `--format` option, the `service ps` command will either When using the `--format` option, the `service ps` command will either
output the data exactly as the template declares or, when using the output the data exactly as the template declares or, when using the

2
_data/engine-cli/docker_stack_ls.yaml
View File

@ -75,7 +75,7 @@ examples: |-
Valid placeholders for the Go template are listed below: Valid placeholders for the Go template are listed below:
| Placeholder | Description | | Placeholder | Description |
| --------------- | ------------------ | |-----------------|--------------------|
| `.Name` | Stack name | | `.Name` | Stack name |
| `.Services` | Number of services | | `.Services` | Number of services |
| `.Orchestrator` | Orchestrator name | | `.Orchestrator` | Orchestrator name |

20
_data/engine-cli/docker_stack_ps.yaml
View File

@ -177,16 +177,16 @@ examples: |-
Valid placeholders for the Go template are listed below: Valid placeholders for the Go template are listed below:
Placeholder | Description | Placeholder | Description |
----------------|------------------------------------------------------------------------------------------ |-----------------|------------------------------------------------------------------|
`.ID` | Task ID | `.ID` | Task ID |
`.Name` | Task name | `.Name` | Task name |
`.Image` | Task image | `.Image` | Task image |
`.Node` | Node ID | `.Node` | Node ID |
`.DesiredState` | Desired state of the task (`running`, `shutdown`, or `accepted`) | `.DesiredState` | Desired state of the task (`running`, `shutdown`, or `accepted`) |
`.CurrentState` | Current state of the task | `.CurrentState` | Current state of the task |
`.Error` | Error | `.Error` | Error |
`.Ports` | Task published ports | `.Ports` | Task published ports |
When using the `--format` option, the `stack ps` command will either When using the `--format` option, the `stack ps` command will either
output the data exactly as the template declares or, when using the output the data exactly as the template declares or, when using the

14
_data/engine-cli/docker_stack_services.yaml
View File

@ -120,13 +120,13 @@ examples: |-
Valid placeholders for the Go template are listed below: Valid placeholders for the Go template are listed below:
Placeholder | Description | Placeholder | Description |
------------|------------------------------------------------------------------- |-------------|-----------------------------------|
`.ID` | Service ID | `.ID` | Service ID |
`.Name` | Service name | `.Name` | Service name |
`.Mode` | Service mode (replicated, global) | `.Mode` | Service mode (replicated, global) |
`.Replicas` | Service replicas | `.Replicas` | Service replicas |
`.Image` | Service image | `.Image` | Service image |
When using the `--format` option, the `stack services` command will either When using the `--format` option, the `stack services` command will either
output the data exactly as the template declares or, when using the output the data exactly as the template declares or, when using the

30
_data/engine-cli/docker_stats.yaml
View File

@ -103,6 +103,13 @@ examples: |-
67b2525d8ad1 foobar 0.00% 1.727MiB / 1.952GiB 0.09% 2.48kB / 0B 4.11MB / 0B 2 67b2525d8ad1 foobar 0.00% 1.727MiB / 1.952GiB 0.09% 2.48kB / 0B 4.11MB / 0B 2
``` ```
Running `docker stats` on container with name nginx and getting output in `json` format.
```console
$ docker stats nginx --no-stream --format "{{ json . }}"
{"BlockIO":"0B / 13.3kB","CPUPerc":"0.03%","Container":"nginx","ID":"ed37317fbf42","MemPerc":"0.24%","MemUsage":"2.352MiB / 982.5MiB","Name":"nginx","NetIO":"539kB / 606kB","PIDs":"2"}
```
Running `docker stats` with customized format on all (Running and Stopped) containers. Running `docker stats` with customized format on all (Running and Stopped) containers.
```console ```console
@ -149,18 +156,17 @@ examples: |-
Valid placeholders for the Go template are listed below: Valid placeholders for the Go template are listed below:
Placeholder | Description | Placeholder | Description |
------------ | -------------------------------------------- |--------------|----------------------------------------------|
`.Container` | Container name or ID (user input) | `.Container` | Container name or ID (user input) |
`.Name` | Container name | `.Name` | Container name |
`.ID` | Container ID | `.ID` | Container ID |
`.CPUPerc` | CPU percentage | `.CPUPerc` | CPU percentage |
`.MemUsage` | Memory usage | `.MemUsage` | Memory usage |
`.NetIO` | Network IO | `.NetIO` | Network IO |
`.BlockIO` | Block IO | `.BlockIO` | Block IO |
`.MemPerc` | Memory percentage (Not available on Windows) | `.MemPerc` | Memory percentage (Not available on Windows) |
`.PIDs` | Number of PIDs (Not available on Windows) | `.PIDs` | Number of PIDs (Not available on Windows) |
When using the `--format` option, the `stats` command either When using the `--format` option, the `stats` command either
outputs the data exactly as the template declares or, when using the outputs the data exactly as the template declares or, when using the

16
_data/engine-cli/docker_volume_ls.yaml
View File

@ -162,14 +162,14 @@ examples: |-
Valid placeholders for the Go template are listed below: Valid placeholders for the Go template are listed below:
Placeholder | Description | Placeholder | Description |
--------------|------------------------------------------------------------------------------------------ |---------------|---------------------------------------------------------------------------------------|
`.Name` | Volume name | `.Name` | Volume name |
`.Driver` | Volume driver | `.Driver` | Volume driver |
`.Scope` | Volume scope (local, global) | `.Scope` | Volume scope (local, global) |
`.Mountpoint` | The mount point of the volume on the host | `.Mountpoint` | The mount point of the volume on the host |
`.Labels` | All labels assigned to the volume | `.Labels` | All labels assigned to the volume |
`.Label` | Value of a specific label for this volume. For example `{{.Label "project.version"}}` | `.Label` | Value of a specific label for this volume. For example `{{.Label "project.version"}}` |
When using the `--format` option, the `volume ls` command will either When using the `--format` option, the `volume ls` command will either
output the data exactly as the template declares or, when using the output the data exactly as the template declares or, when using the