wip: regenerate engine cli yaml

dvdksn · dvdksn · commit b9ca7336debd · 2024-07-02T15:25:16.000+02:00
Signed-off-by: David Karlsson &lt;35727626+dvdksn@users.noreply.github.com&gt;
diff --git a/data/engine-cli/docker.yaml b/data/engine-cli/docker.yaml
diff --git a/data/engine-cli/docker_container_attach.yaml b/data/engine-cli/docker_container_attach.yaml
@@ -190,7 +190,7 @@ examples: |-
 
     These `a`, `ctrl-a`, `X`, or `ctrl-\\` values are all examples of valid key
     sequences. To configure a different configuration default key sequence for all
-    containers, see [**Configuration file** section](/engine/reference/commandline/cli/#configuration-files).
+    containers, see [**Configuration file** section](/reference/cli/docker/#configuration-files).
 deprecated: false
 hidden: false
 experimental: false
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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.
-
-    You can disconnect a container from a network using the `docker network
-    disconnect` command.
+    > 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.
 
-    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}
 
@@ -1795,7 +1838,7 @@ examples: |-
 
     These `a`, `ctrl-a`, `X`, or `ctrl-\\` values are all examples of valid key
     sequences. To configure a different configuration default key sequence for all
-    containers, see [**Configuration file** section](/engine/reference/commandline/cli/#configuration-files).
+    containers, see [**Configuration file** section](/reference/cli/docker/#configuration-files).
 
     ### Add host device to container (--device) {#device}
 
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
diff --git a/data/engine-cli/docker_volume_create.yaml b/data/engine-cli/docker_volume_create.yaml
