From 92b0faaf83a23a9d261a5736d6e6bd59f29915d3 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Thu, 21 Mar 2024 00:21:19 +0100 Subject: [PATCH] engine: update cli reference yamldocs for v26.0.0 Signed-off-by: Sebastiaan van Stijn --- data/engine-cli/docker_container_exec.yaml | 5 ++ data/engine-cli/docker_container_run.yaml | 57 +++++++++++++++++++--- data/engine-cli/docker_image_build.yaml | 2 +- data/engine-cli/docker_network_create.yaml | 9 +++- data/engine-cli/docker_stack_deploy.yaml | 23 +++++++++ data/engine-cli/docker_stack_rm.yaml | 12 +++++ 6 files changed, 98 insertions(+), 10 deletions(-) diff --git a/data/engine-cli/docker_container_exec.yaml b/data/engine-cli/docker_container_exec.yaml index 55a48fe17b..fea80c9df6 100644 --- a/data/engine-cli/docker_container_exec.yaml +++ b/data/engine-cli/docker_container_exec.yaml @@ -75,6 +75,7 @@ options: value_type: bool default_value: "false" description: Give extended privileges to the command + details_url: '#privileged' deprecated: false hidden: false experimental: false @@ -181,6 +182,10 @@ examples: |- HOME=/root ``` + ### Escalate container privileges (--privileged) {#privileged} + + See [`docker run --privileged`](/reference/cli/docker/container/run/#privileged). + ### Set the working directory for the exec process (--workdir, -w) {#workdir} By default `docker exec` command runs in the same working directory set when diff --git a/data/engine-cli/docker_container_run.yaml b/data/engine-cli/docker_container_run.yaml index 9228abcdd8..997c218711 100644 --- a/data/engine-cli/docker_container_run.yaml +++ b/data/engine-cli/docker_container_run.yaml @@ -1036,6 +1036,7 @@ options: - option: userns value_type: string description: User namespace to use + details_url: '#userns' deprecated: false hidden: false experimental: false @@ -1177,7 +1178,7 @@ examples: |- #### Example: run htop inside a container - To run `htop` in a container that shares the process namespace of the host: + To run `htop` in a container that shares the process namespac of the host: 1. Run an alpine container with the `--pid=host` option: @@ -1238,6 +1239,21 @@ examples: |- strace: Process 1 attached ``` + ### Disable namespace remapping for a container (--userns) {#userns} + + If you enable user namespaces on the daemon, + all containers are started with user namespaces enabled by default. + To disable user namespace remapping for a specific container, + you can set the `--userns` flag to `host`. + + ```console + docker run --userns=host hello-world + ``` + + `host` is the only valid value for the `--userns` flag. + + For more information, refer to [Isolate containers with a user namespace](/engine/security/userns-remap/). + ### UTS settings (--uts) {#uts} ```text @@ -1293,7 +1309,37 @@ examples: |- of the containers, using `"shareable"` mode for the main (i.e. "donor") container, and `"container:"` for other containers. - ### Full container capabilities (--privileged) {#privileged} + ### Escalate container privileges (--privileged) {#privileged} + + The `--privileged` flag gives the following capabilities to a container: + + - Enables all Linux kernel capabilities + - Disables the default seccomp profile + - Disables the default AppArmor profile + - Disables the SELinux process label + - Grants access to all host devices + - Makes `/sys` read-write + - Makes cgroups mounts read-write + + In other words, the container can then do almost everything that the host can + do. This flag exists to allow special use-cases, like running Docker within + Docker. + + > **Warning** + > + > Use the `--privileged` flag with caution. + > A container with `--privileged` is not a securely sandboxed process. + > Containers in this mode can get a root shell on the host + > and take control over the system. + > + > For most use cases, this flag should not be the preferred solution. + > If your container requires escalated privileges, + > you should prefer to explicitly grant the necessary permissions, + > for example by adding individual kernel capabilities with `--cap-add`. + > + > For more information, see + > [Runtime privilege and Linux capabilities](/engine/reference/run/#runtime-privilege-and-linux-capabilities) + { .warning } The following example doesn't work, because by default, Docker drops most potentially dangerous kernel capabilities, including `CAP_SYS_ADMIN ` (which is @@ -1315,11 +1361,6 @@ examples: |- none 1.9G 0 1.9G 0% /mnt ``` - The `--privileged` flag gives all capabilities to the container, and it also - lifts all the limitations enforced by the `device` cgroup controller. In other - words, the container can then do almost everything that the host can do. This - flag exists to allow special use-cases, like running Docker within Docker. - ### Set working directory (-w, --workdir) {#workdir} ```console @@ -1967,7 +2008,7 @@ examples: |- password is hidden: ```console - $ docker run -i debian passwd root + $ docker run -it debian passwd root New password: Retype new password: passwd: password updated successfully diff --git a/data/engine-cli/docker_image_build.yaml b/data/engine-cli/docker_image_build.yaml index c3ba12baef..512067a3f2 100644 --- a/data/engine-cli/docker_image_build.yaml +++ b/data/engine-cli/docker_image_build.yaml @@ -24,7 +24,7 @@ long: |- > **Note** > > If the `URL` parameter contains a fragment the system recursively clones - > the repository and its submodules using a `git clone --recursive` command. + > the repository and its submodules. Git URLs accept context configuration in their fragment section, separated by a colon (`:`). The first part represents the reference that Git checks out, diff --git a/data/engine-cli/docker_network_create.yaml b/data/engine-cli/docker_network_create.yaml index eaf74f30bc..cb918ca8a8 100644 --- a/data/engine-cli/docker_network_create.yaml +++ b/data/engine-cli/docker_network_create.yaml @@ -313,7 +313,8 @@ examples: |- | `com.docker.network.container_iface_prefix` | - | Set a custom prefix for container interfaces | The following arguments can be passed to `docker network create` for any - network driver, again with their approximate equivalents to `docker daemon`. + network driver, again with their approximate equivalents to Docker daemon + flags used for the docker0 bridge: | Argument | Equivalent | Description | |--------------|----------------|--------------------------------------------| @@ -334,6 +335,12 @@ examples: |- ### Network internal mode (--internal) {#internal} + Containers on an internal network may communicate between each other, but not + with any other network, as no default route is configured and firewall rules + are set up to drop all traffic to or from other networks. Communication with + the gateway IP address (and thus appropriately configured host services) is + possible, and the host may communicate with any container IP directly. + By default, when you connect a container to an `overlay` network, Docker also connects a bridge network to it to provide external connectivity. If you want to create an externally isolated `overlay` network, you can specify the diff --git a/data/engine-cli/docker_stack_deploy.yaml b/data/engine-cli/docker_stack_deploy.yaml index f148769db7..adc5d43acd 100644 --- a/data/engine-cli/docker_stack_deploy.yaml +++ b/data/engine-cli/docker_stack_deploy.yaml @@ -27,6 +27,18 @@ options: experimentalcli: false kubernetes: false swarm: false + - option: detach + shorthand: d + value_type: bool + default_value: "true" + description: | + Exit immediately instead of waiting for the stack services to converge + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: prune value_type: bool default_value: "false" @@ -38,6 +50,17 @@ options: experimentalcli: false kubernetes: false swarm: false + - option: quiet + shorthand: q + value_type: bool + default_value: "false" + description: Suppress progress output + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: resolve-image value_type: string default_value: always diff --git a/data/engine-cli/docker_stack_rm.yaml b/data/engine-cli/docker_stack_rm.yaml index 68e65d71a3..3120f514d1 100644 --- a/data/engine-cli/docker_stack_rm.yaml +++ b/data/engine-cli/docker_stack_rm.yaml @@ -13,6 +13,18 @@ long: |- usage: docker stack rm [OPTIONS] STACK [STACK...] pname: docker stack plink: docker_stack.yaml +options: + - option: detach + shorthand: d + value_type: bool + default_value: "true" + description: Do not wait for stack removal + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false inherited_options: - option: help value_type: bool