Merge pull request docker#4929 from dvdksn/privileged-flag

docs: clarify what the --privileged flag does

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: `<name\|uid>[:<group\|gid>]`) |
 | [`-w`](#workdir), [`--workdir`](#workdir) | `string` |         | Working directory inside the container                 |
@@ -96,6 +96,10 @@ VAR_B=2
 HOME=/root
 ```
 
+### <a name="privileged"></a> Escalate container privileges (--privileged)
+
+See [`docker run --privileged`](container_run.md#privileged).
+
 ### <a name="workdir"></a> Set the working directory for the exec process (--workdir, -w)
 
 By default `docker exec` command runs in the same working directory set when

docs/reference/commandline/container_run.md

@@ -341,7 +341,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:<donor-name-or-ID>"` for other containers.
 
-### <a name="privileged"></a> Full container capabilities (--privileged)
+### <a name="privileged"></a> 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
@@ -363,11 +393,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.
-
 ### <a name="workdir"></a> Set working directory (-w, --workdir)
 
 ```console

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