For a follow-up, we should make a pass at searching for --privileged examples. Using --privileged is a BIG hammer, and effectively disables all security that containers provide (making a privileged container effectively "not a container", or a container that "doesn't contain). For cases where we can we should document the minimum amount of (additional) privileges needed. (And have a canonical section on "privileged" with tons of ⚠️ warnings (don't use this unless you really, really need it, and know what you're doing ⚠️))

For this specific example, it looks like we need CAP_SYS_ADMIN, so the example can look like;

$ docker run -it --cap-add CAP_SYS_ADMIN ubuntu bash
root@50e3f57e16e6:/# mount -t tmpfs none /mnt
root@50e3f57e16e6:/# df -h
Filesystem      Size  Used Avail Use% Mounted on
none            1.9G     0  1.9G   0% /mnt

Or even (using alpine);

$ docker run -it --cap-add CAP_SYS_ADMIN alpine
/ # mount -t tmpfs none /mnt
/ # df -h
Filesystem                Size      Used Available Use% Mounted on
overlay                  58.4G     27.8G     27.6G  50% /
tmpfs                    64.0M         0     64.0M   0% /dev
shm                      64.0M         0     64.0M   0% /dev/shm
/dev/vda1                58.4G     27.8G     27.6G  50% /etc/resolv.conf
/dev/vda1                58.4G     27.8G     27.6G  50% /etc/hostname
/dev/vda1                58.4G     27.8G     27.6G  50% /etc/hosts
tmpfs                    64.0M         0     64.0M   0% /proc/kcore
tmpfs                    64.0M         0     64.0M   0% /proc/keys
tmpfs                    64.0M         0     64.0M   0% /proc/timer_list
tmpfs                     3.8G         0      3.8G   0% /sys/firmware
none                      3.8G         0      3.8G   0% /mnt

I should note that the existing example only shows the "essential" lines from the output (the mnt mount) for illustrational purposes.

• I guess we could make it df -h | grep mnt (so that the output matches actual output) but we'd loose the headers :thinking_face:
• Should we use a mount destination that more clearly stands out as "this is an example"? (mkdir /example-mount && mount -t tmpfs none /example-mount)? Note that the existing example uses /mnt (which already exists), but other locations won't (so users would run into an error).

Some other bits (for follow-ups);

• Review the "Runtime privilege and Linux capabilities" to check if the list of capabilities is complete (recent kernel versions added some new capabilities).
• While we accept both SYS_ADMIN and CAP_SYS_ADMIN (as well as lowercase variants), I know that internally (at least daemon-side) we normalize to CAP_SOME_CAPABILITY (see https://github.com/moby/moby/blob/58c027ac8ba19a3fa339c65274ea6704ccbec977/oci/caps/utils.go#L56-L79), so I wonder if we should update examples (and the table) to use the same for consistency
• Some examples use ubuntu (ubuntu:latest); there's two issues there (possibly worth considering);
  • depending on the example, ubuntu may not always be needed, and we could make the examples more lightweight by using alpine (alpine's apk add --no-cache install is super fast as well, which makes it great to provide quick examples that need additional packages installed), and we should probably prefer alpine over busybox (where we use it).
  • this might be a bit of a stretch, but :latest (while it reduces maintenance on our side) rarely is "best practice". Now, this is a bit of a grey area; for quick "one-off" things (such as docker run alpine echo hello), or other things one may do, I guess "it's fine" (don't want to be typing too much). On the other hand, building an image using ubuntu:latest (e.g.) is definitely not the way to go (latest may be a new version of Ubuntu "tomorrow", and break your image!) so we need to find the right balance between that (show best practices where needed to make users familiar with them).

@thaJeztah The existing text around this example says…

This doesn't work, because by default, Docker drops most potentially dangerous kernel
capabilities, including CAP_SYS_ADMIN (which is required to mount
filesystems).

So is that also wrong? As the proposed example uses something the text explicitly says won't work.

And noted for all the follow up.

@ChrisChinchilla the example is correct that it doesn't work. The issue here is a bit that we use --privileged to work around that, whereas (for this example) just adding the CAP_SYS_ADMIN capability would've worked.

--privileged is a bit of a big hammer (and should be avoided in most cases, as it removes all security that a container provides); granting CAP_SYS_ADMIN is just one thing it does (it grants "all capabilities", but also disables seccomp, selinux, apparmor, and grants access to some paths that are otherwise protected.

TL;DR it works, but should not be the recommended approach for this specific case

@ChrisChinchilla the example is correct that it doesn't work. The issue here is a bit that we use --privileged to work around that, whereas (for this example) just adding the CAP_SYS_ADMIN capability would've worked.

--privileged is a bit of a big hammer (and should be avoided in most cases, as it removes all security that a container provides); granting CAP_SYS_ADMIN is just one thing it does (it grants "all capabilities", but also disables seccomp, selinux, apparmor, and grants access to some paths that are otherwise protected.

TL;DR it works, but should not be the recommended approach for this specific case