From 9349f58b8a26e0df6ab370912fb2ddd4492459d0 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 8 Mar 2024 16:18:56 +0100 Subject: [PATCH] docs: clarify what the --privileged flag does Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- docs/reference/commandline/container_exec.md | 6 +++- docs/reference/commandline/container_run.md | 37 ++++++++++++++++---- docs/reference/run.md | 11 +++--- 3 files changed, 42 insertions(+), 12 deletions(-) diff --git a/docs/reference/commandline/container_exec.md b/docs/reference/commandline/container_exec.md index 1f1fafa747ea..896c05ae6c40 100644 --- a/docs/reference/commandline/container_exec.md +++ b/docs/reference/commandline/container_exec.md @@ -16,7 +16,7 @@ Execute a command in a running container | [`-e`](#env), [`--env`](#env) | `list` | | Set environment variables | | `--env-file` | `list` | | Read in a file of environment variables | | `-i`, `--interactive` | | | Keep STDIN open even if not attached | -| `--privileged` | | | Give extended privileges to the command | +| [`--privileged`](#privileged) | | | Give extended privileges to the command | | `-t`, `--tty` | | | Allocate a pseudo-TTY | | `-u`, `--user` | `string` | | Username or UID (format: `[:]`) | | [`-w`](#workdir), [`--workdir`](#workdir) | `string` | | Working directory inside the container | @@ -96,6 +96,10 @@ VAR_B=2 HOME=/root ``` +### Escalate container privileges (--privileged) + +See [`docker run --privileged`](container_run.md#privileged). + ### Set the working directory for the exec process (--workdir, -w) By default `docker exec` command runs in the same working directory set when diff --git a/docs/reference/commandline/container_run.md b/docs/reference/commandline/container_run.md index 706d43b57b5a..7356147056a9 100644 --- a/docs/reference/commandline/container_run.md +++ b/docs/reference/commandline/container_run.md @@ -326,7 +326,37 @@ are broken into multiple containers, you might need to share the IPC mechanisms of the containers, using `"shareable"` mode for the main (i.e. "donor") container, and `"container:"` for other containers. -### Full container capabilities (--privileged) +### Escalate container privileges (--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](https://docs.docker.com/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 @@ -348,11 +378,6 @@ Filesystem Size Used Avail Use% Mounted on none 1.9G 0 1.9G 0% /mnt ``` -The `--privileged` flag gives all capabilities to the container, and it also -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) ```console diff --git a/docs/reference/run.md b/docs/reference/run.md index ab4a4afceb03..e92b580886a2 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -813,11 +813,12 @@ by default a container is not allowed to access any devices, but a the documentation on [cgroups devices](https://www.kernel.org/doc/Documentation/cgroup-v1/devices.txt)). The `--privileged` flag gives all capabilities to the container. When the operator -executes `docker run --privileged`, Docker will enable access to all devices on -the host as well as set some configuration in AppArmor or SELinux to allow the -container nearly all the same access to the host as processes running outside -containers on the host. Additional information about running with `--privileged` -is available on the [Docker Blog](https://www.docker.com/blog/docker-can-now-run-within-docker/). +executes `docker run --privileged`, Docker enables access to all devices on +the host, and reconfigures AppArmor or SELinux to allow the container +nearly all the same access to the host as processes running outside +containers on the host. Use this flag with caution. +For more information about the `--privileged` flag, see the +[`docker run` reference](https://docs.docker.com/reference/cli/docker/container/run/#privileged). If you want to limit access to a specific device or devices you can use the `--device` flag. It allows you to specify one or more devices that