diff --git a/data/engine-cli/docker_container_cp.yaml b/data/engine-cli/docker_container_cp.yaml index bdffbb5715..3dd4181795 100644 --- a/data/engine-cli/docker_container_cp.yaml +++ b/data/engine-cli/docker_container_cp.yaml @@ -129,7 +129,7 @@ examples: |- $ docker cp CONTAINER:/var/logs/ /tmp/app_logs ``` - Copy a file from container to stdout. Please note `cp` command produces a tar stream + Copy a file from container to stdout. Note `cp` command produces a tar stream ```console $ docker cp CONTAINER:/var/logs/app.log - | tar x -O | grep "ERROR" diff --git a/data/engine-cli/docker_container_create.yaml b/data/engine-cli/docker_container_create.yaml index b1d569b1bb..ed89811b83 100644 --- a/data/engine-cli/docker_container_create.yaml +++ b/data/engine-cli/docker_container_create.yaml @@ -866,7 +866,8 @@ options: - option: rm value_type: bool default_value: "false" - description: Automatically remove the container when it exits + description: | + Automatically remove the container and its associated anonymous volumes when it exits deprecated: false hidden: false experimental: false diff --git a/data/engine-cli/docker_container_logs.yaml b/data/engine-cli/docker_container_logs.yaml index 891c7802c2..380c50c4c5 100644 --- a/data/engine-cli/docker_container_logs.yaml +++ b/data/engine-cli/docker_container_logs.yaml @@ -26,7 +26,7 @@ long: |- a given date. You can specify the date as an RFC 3339 date, a UNIX timestamp, or a Go duration string (e.g. `1m30s`, `3h`). Besides RFC3339 date format you may also use RFC3339Nano, `2006-01-02T15:04:05`, - `2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local + `2006-01-02T15:04:05.999999999`, `2006-01-02T07:00`, and `2006-01-02`. The local timezone on the client will be used if you do not provide either a `Z` or a `+-00:00` timezone offset at the end of the timestamp. When providing Unix timestamps enter seconds[.nanoseconds], where seconds is the number of seconds diff --git a/data/engine-cli/docker_container_prune.yaml b/data/engine-cli/docker_container_prune.yaml index edc427f7e1..e6031d9081 100644 --- a/data/engine-cli/docker_container_prune.yaml +++ b/data/engine-cli/docker_container_prune.yaml @@ -65,7 +65,7 @@ examples: |- timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed 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 + `2006-01-02T15:04:05.999999999`, `2006-01-02T07: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 timestamps enter seconds[.nanoseconds], where seconds is the number of seconds diff --git a/data/engine-cli/docker_container_run.yaml b/data/engine-cli/docker_container_run.yaml index 8bb6fe3630..e12ddb4aac 100644 --- a/data/engine-cli/docker_container_run.yaml +++ b/data/engine-cli/docker_container_run.yaml @@ -900,7 +900,8 @@ options: - option: rm value_type: bool default_value: "false" - description: Automatically remove the container when it exits + description: | + Automatically remove the container and its associated anonymous volumes when it exits details_url: '#rm' deprecated: false hidden: false @@ -1189,14 +1190,7 @@ examples: |- 2. Install `htop` in the container: ```console - / # apk add htop - fetch https://dl-cdn.alpinelinux.org/alpine/v3.18/main/aarch64/APKINDEX.tar.gz - fetch https://dl-cdn.alpinelinux.org/alpine/v3.18/community/aarch64/APKINDEX.tar.gz - (1/3) Installing ncurses-terminfo-base (6.4_p20230506-r0) - (2/3) Installing libncursesw (6.4_p20230506-r0) - (3/3) Installing htop (3.2.2-r1) - Executing busybox-1.36.1-r2.trigger - OK: 9 MiB in 18 packages + / # apk add --quiet htop ``` 3. Invoke the `htop` command. @@ -1682,7 +1676,24 @@ examples: |- To start a container and connect it to a network, use the `--network` option. - The following commands create a network named `my-net` and adds a `busybox` container + If you want to add a running container to a network use the `docker network connect` subcommand. + + You can connect multiple containers to the same network. Once connected, the + containers can communicate using only another container's IP address + or name. For `overlay` networks or custom plugins that support multi-host + connectivity, containers connected to the same multi-host network but launched + from different Engines can also communicate in this way. + + > **Note** + > + > The default bridge network only allows containers to communicate with each other using + > internal IP addresses. User-created bridge networks provide DNS resolution between + > containers using container names. + + You can disconnect a container from a network using the `docker network + disconnect` command. + + The following commands create a network named `my-net` and add a `busybox` container to the `my-net` network. ```console @@ -1699,24 +1710,56 @@ examples: |- $ docker run -itd --network=my-net --ip=192.0.2.69 busybox ``` - If you want to add a running container to a network use the `docker network connect` subcommand. + To connect the container to more than one network, repeat the `--network` option. - You can connect multiple containers to the same network. Once connected, the - containers can communicate using only another container's IP address - or name. For `overlay` networks or custom plugins that support multi-host - connectivity, containers connected to the same multi-host network but launched - from different Engines can also communicate in this way. + ```console + $ docker network create --subnet 192.0.2.0/24 my-net1 + $ docker network create --subnet 192.0.3.0/24 my-net2 + $ docker run -itd --network=my-net1 --network=my-net2 busybox + ``` + + To specify options when connecting to more than one network, use the extended syntax + for the `--network` flag. Comma-separated options that can be specified in the extended + `--network` syntax are: + + | Option | Top-level Equivalent | Description | + |-----------------|---------------------------------------|-------------------------------------------------| + | `name` | | The name of the network (mandatory) | + | `alias` | `--network-alias` | Add network-scoped alias for the container | + | `ip` | `--ip` | IPv4 address (e.g., 172.30.100.104) | + | `ip6` | `--ip6` | IPv6 address (e.g., 2001:db8::33) | + | `mac-address` | `--mac-address` | Container MAC address (e.g., 92:d0:c6:0a:29:33) | + | `link-local-ip` | `--link-local-ip` | Container IPv4/IPv6 link-local addresses | + | `driver-opt` | `docker network connect --driver-opt` | Network driver options | + + ```console + $ docker network create --subnet 192.0.2.0/24 my-net1 + $ docker network create --subnet 192.0.3.0/24 my-net2 + $ docker run -itd --network=name=my-net1,ip=192.0.2.42 --network=name=my-net2,ip=192.0.3.42 busybox + ``` + + `sysctl` settings that start with `net.ipv4.`, `net.ipv6.` or `net.mpls.` can be + set per-interface using `driver-opt` label `com.docker.network.endpoint.sysctls`. + The interface name must be the string `IFNAME`. + + To set more than one `sysctl` for an interface, quote the whole `driver-opt` field, + remembering to escape the quotes for the shell if necessary. For example, if the + interface to `my-net` is given name `eth0`, the following example sets sysctls + `net.ipv4.conf.eth0.log_martians=1` and `net.ipv4.conf.eth0.forwarding=0`, and + assigns the IPv4 address `192.0.2.42`. + + ```console + $ docker network create --subnet 192.0.2.0/24 my-net + $ docker run -itd --network=name=my-net,\"driver-opt=com.docker.network.endpoint.sysctls=net.ipv4.conf.IFNAME.log_martians=1,net.ipv4.conf.IFNAME.forwarding=0\",ip=192.0.2.42 busybox + ``` > **Note** > - > The default bridge network only allow containers to communicate with each other using - > internal IP addresses. User-created bridge networks provide DNS resolution between - > containers using container names. + > Network drivers may restrict the sysctl settings that can be modified and, to protect + > the operation of the network, new restrictions may be added in the future. - You can disconnect a container from a network using the `docker network - disconnect` command. - - For more information on connecting a container to a network when using the `run` command, see the ["*Docker network overview*"](/network/). + For more information on connecting a container to a network when using the `run` command, + see the [Docker network overview](/network/). ### Mount volumes from container (--volumes-from) {#volumes-from} @@ -1870,17 +1913,19 @@ examples: |- > **Note** > - > This is experimental feature and as such doesn't represent a stable API. + > The CDI feature is experimental, and potentially subject to change. + > CDI is currently only supported for Linux containers. - Container Device Interface (CDI) is a - [standardized](https://github.com/cncf-tags/container-device-interface/blob/main/SPEC.md) - mechanism for container runtimes to create containers which are able to - interact with third party devices. + [Container Device Interface + (CDI)](https://github.com/cncf-tags/container-device-interface/blob/main/SPEC.md) + is a standardized mechanism for container runtimes to create containers which + are able to interact with third party devices. - With CDI, device configurations are defined using a JSON file. In addition to - enabling the container to interact with the device node, it also lets you - specify additional configuration for the device, such as kernel modules, host - libraries, and environment variables. + With CDI, device configurations are declaratively defined using a JSON or YAML + file. In addition to enabling the container to interact with the device node, + it also lets you specify additional configuration for the device, such as + environment variables, host mounts (such as shared objects), and executable + hooks. You can reference a CDI device with the `--device` flag using the fully-qualified name of the device, as shown in the following example: @@ -1892,10 +1937,10 @@ examples: |- This starts an `ubuntu` container with access to the specified CDI device, `vendor.com/class=device-name`, assuming that: - - A valid CDI specification (JSON file) for the requested device is available - on the system running the daemon, in one of the configured CDI specification - directories. - - The CDI feature has been enabled on the daemon side, see [Enable CDI + - A valid CDI specification (JSON or YAML file) for the requested device is + available on the system running the daemon, in one of the configured CDI + specification directories. + - The CDI feature has been enabled in the daemon; see [Enable CDI devices](/reference/cli/dockerd/#enable-cdi-devices). ### Attach to STDIN/STDOUT/STDERR (-a, --attach) {#attach} diff --git a/data/engine-cli/docker_create.yaml b/data/engine-cli/docker_create.yaml index 0c9befd1b4..883160b59b 100644 --- a/data/engine-cli/docker_create.yaml +++ b/data/engine-cli/docker_create.yaml @@ -849,7 +849,8 @@ options: - option: rm value_type: bool default_value: "false" - description: Automatically remove the container when it exits + description: | + Automatically remove the container and its associated anonymous volumes when it exits deprecated: false hidden: false experimental: false diff --git a/data/engine-cli/docker_image_prune.yaml b/data/engine-cli/docker_image_prune.yaml index 8dd067a4c9..610196c477 100644 --- a/data/engine-cli/docker_image_prune.yaml +++ b/data/engine-cli/docker_image_prune.yaml @@ -99,7 +99,7 @@ examples: |- timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed 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 + `2006-01-02T15:04:05.999999999`, `2006-01-02T07: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 timestamps enter seconds[.nanoseconds], where seconds is the number of seconds diff --git a/data/engine-cli/docker_image_push.yaml b/data/engine-cli/docker_image_push.yaml index 817ff50bd9..2d4fae01c5 100644 --- a/data/engine-cli/docker_image_push.yaml +++ b/data/engine-cli/docker_image_push.yaml @@ -49,6 +49,18 @@ options: experimentalcli: false kubernetes: false swarm: false + - option: platform + value_type: string + description: |- + Push a platform-specific manifest as a single-platform image to the registry. + 'os[/arch[/variant]]': Explicit platform (eg. linux/amd64) + deprecated: false + hidden: false + min_api_version: "1.46" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: quiet shorthand: q value_type: bool diff --git a/data/engine-cli/docker_network_connect.yaml b/data/engine-cli/docker_network_connect.yaml index 330957a495..a1eb96eb75 100644 --- a/data/engine-cli/docker_network_connect.yaml +++ b/data/engine-cli/docker_network_connect.yaml @@ -120,6 +120,26 @@ examples: |- $ docker network connect --alias db --alias mysql multi-host-network container2 ``` + ### Set sysctls for a container's interface (--driver-opt) {#sysctl} + + `sysctl` settings that start with `net.ipv4.` and `net.ipv6.` can be set per-interface + using `--driver-opt` label `com.docker.network.endpoint.sysctls`. The name of the + interface must be replaced by `IFNAME`. + + To set more than one `sysctl` for an interface, quote the whole value of the + `driver-opt` field, remembering to escape the quotes for the shell if necessary. + For example, if the interface to `my-net` is given name `eth3`, the following example + sets `net.ipv4.conf.eth3.log_martians=1` and `net.ipv4.conf.eth3.forwarding=0`. + + ```console + $ docker network connect --driver-opt=\"com.docker.network.endpoint.sysctls=net.ipv4.conf.IFNAME.log_martians=1,net.ipv4.conf.IFNAME.forwarding=0\" multi-host-network container2 + ``` + + > **Note** + > + > Network drivers may restrict the sysctl settings that can be modified and, to protect + > the operation of the network, new restrictions may be added in the future. + ### Network implications of stopping, pausing, or restarting containers You can pause, restart, and stop containers that are connected to a network. diff --git a/data/engine-cli/docker_network_create.yaml b/data/engine-cli/docker_network_create.yaml index cb918ca8a8..aca1adb79d 100644 --- a/data/engine-cli/docker_network_create.yaml +++ b/data/engine-cli/docker_network_create.yaml @@ -173,7 +173,7 @@ options: - option: ipv6 value_type: bool default_value: "false" - description: Enable IPv6 networking + description: Enable or disable IPv6 networking deprecated: false hidden: false experimental: false @@ -321,7 +321,7 @@ examples: |- | `--gateway` | - | IPv4 or IPv6 Gateway for the master subnet | | `--ip-range` | `--fixed-cidr` | Allocate IPs from a range | | `--internal` | - | Restrict external access to the network | - | `--ipv6` | `--ipv6` | Enable IPv6 networking | + | `--ipv6` | `--ipv6` | Enable or disable IPv6 networking | | `--subnet` | `--bip` | Subnet for network | For example, let's use `-o` or `--opt` options to specify an IP address binding diff --git a/data/engine-cli/docker_network_prune.yaml b/data/engine-cli/docker_network_prune.yaml index 073d66a868..b291f37a86 100644 --- a/data/engine-cli/docker_network_prune.yaml +++ b/data/engine-cli/docker_network_prune.yaml @@ -64,7 +64,7 @@ examples: |- timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed 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 + `2006-01-02T15:04:05.999999999`, `2006-01-02T07: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 timestamps enter seconds[.nanoseconds], where seconds is the number of seconds diff --git a/data/engine-cli/docker_push.yaml b/data/engine-cli/docker_push.yaml index 15535a6e20..912911f6b5 100644 --- a/data/engine-cli/docker_push.yaml +++ b/data/engine-cli/docker_push.yaml @@ -27,6 +27,18 @@ options: experimentalcli: false kubernetes: false swarm: false + - option: platform + value_type: string + description: |- + Push a platform-specific manifest as a single-platform image to the registry. + 'os[/arch[/variant]]': Explicit platform (eg. linux/amd64) + deprecated: false + hidden: false + min_api_version: "1.46" + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: quiet shorthand: q value_type: bool diff --git a/data/engine-cli/docker_run.yaml b/data/engine-cli/docker_run.yaml index b76f186e19..26cefcd309 100644 --- a/data/engine-cli/docker_run.yaml +++ b/data/engine-cli/docker_run.yaml @@ -869,7 +869,8 @@ options: - option: rm value_type: bool default_value: "false" - description: Automatically remove the container when it exits + description: | + Automatically remove the container and its associated anonymous volumes when it exits deprecated: false hidden: false experimental: false diff --git a/data/engine-cli/docker_service_logs.yaml b/data/engine-cli/docker_service_logs.yaml index 793dff1d1c..3a4a703f10 100644 --- a/data/engine-cli/docker_service_logs.yaml +++ b/data/engine-cli/docker_service_logs.yaml @@ -42,7 +42,7 @@ long: |- a given date. You can specify the date as an RFC 3339 date, a UNIX timestamp, or a Go duration string (e.g. `1m30s`, `3h`). Besides RFC3339 date format you may also use RFC3339Nano, `2006-01-02T15:04:05`, - `2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local + `2006-01-02T15:04:05.999999999`, `2006-01-02T07:00`, and `2006-01-02`. The local timezone on the client will be used if you do not provide either a `Z` or a `+-00:00` timezone offset at the end of the timestamp. When providing Unix timestamps enter seconds[.nanoseconds], where seconds is the number of seconds diff --git a/data/engine-cli/docker_swarm_unlock-key.yaml b/data/engine-cli/docker_swarm_unlock-key.yaml index 276ff532a2..324cfad138 100644 --- a/data/engine-cli/docker_swarm_unlock-key.yaml +++ b/data/engine-cli/docker_swarm_unlock-key.yaml @@ -59,7 +59,7 @@ examples: |- SWMKEY-1-fySn8TY4w5lKcWcJPIpKufejh9hxx5KYwx6XZigx3Q4 - Please remember to store this key in a password manager, since without it you + Remember to store this key in a password manager, since without it you will not be able to restart the manager. ``` @@ -76,7 +76,7 @@ examples: |- SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8 - Please remember to store this key in a password manager, since without it you + Remember to store this key in a password manager, since without it you will not be able to restart the manager. ``` diff --git a/data/engine-cli/docker_swarm_unlock.yaml b/data/engine-cli/docker_swarm_unlock.yaml index f0f595a970..a1605acb81 100644 --- a/data/engine-cli/docker_swarm_unlock.yaml +++ b/data/engine-cli/docker_swarm_unlock.yaml @@ -29,7 +29,7 @@ inherited_options: examples: |- ```console $ docker swarm unlock - Please enter unlock key: + Enter unlock key: ``` deprecated: false hidden: false diff --git a/data/engine-cli/docker_system_events.yaml b/data/engine-cli/docker_system_events.yaml index c0a389e314..fb8c743c43 100644 --- a/data/engine-cli/docker_system_events.yaml +++ b/data/engine-cli/docker_system_events.yaml @@ -129,7 +129,7 @@ long: |- relative to the client machine’s time. If you do not provide the `--since` option, the command returns only new and/or live events. Supported formats for date formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, - `2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local + `2006-01-02T15:04:05.999999999`, `2006-01-02T07:00`, and `2006-01-02`. The local timezone on the client will be used if you do not provide either a `Z` or a `+-00:00` timezone offset at the end of the timestamp. When providing Unix timestamps enter seconds[.nanoseconds], where seconds is the number of seconds diff --git a/data/engine-cli/docker_system_prune.yaml b/data/engine-cli/docker_system_prune.yaml index ebc455d208..ffa0df8f07 100644 --- a/data/engine-cli/docker_system_prune.yaml +++ b/data/engine-cli/docker_system_prune.yaml @@ -147,7 +147,7 @@ examples: |- timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed 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 + `2006-01-02T15:04:05.999999999`, `2006-01-02T07: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 timestamps enter seconds[.nanoseconds], where seconds is the number of seconds diff --git a/data/engine-cli/docker_trust_revoke.yaml b/data/engine-cli/docker_trust_revoke.yaml index 33f8037d3e..d2a0b3d981 100644 --- a/data/engine-cli/docker_trust_revoke.yaml +++ b/data/engine-cli/docker_trust_revoke.yaml @@ -101,7 +101,7 @@ examples: |- ```console $ docker trust revoke example/trust-demo - Please confirm you would like to delete all signature data for example/trust-demo? [y/N] y + Confirm you would like to delete all signature data for example/trust-demo? [y/N] y Enter passphrase for delegation key with ID 27d42a8: Successfully deleted signature for example/trust-demo ``` diff --git a/data/engine-cli/docker_volume_create.yaml b/data/engine-cli/docker_volume_create.yaml index 09e5966d8b..caaffe0713 100644 --- a/data/engine-cli/docker_volume_create.yaml +++ b/data/engine-cli/docker_volume_create.yaml @@ -194,7 +194,7 @@ examples: |- ``` If you specify a volume name already in use on the current driver, Docker - assumes you want to re-use the existing volume and doesn't return an error. + assumes you want to reuse the existing volume and doesn't return an error. ### Driver-specific options (-o, --opt) {#opt}