Merge pull request #6309 from cortopy/nonroot_vol_docs

add section on rootless volumes in the docs

1 files changed, 40 insertions, 0 deletions

diff --git a/docs/tutorials/rootless_tutorial.md b/docs/tutorials/rootless_tutorial.md
index 8e048c746..93726b3b1 100644
--- a/docs/tutorials/rootless_tutorial.md
+++ b/docs/tutorials/rootless_tutorial.md
@@ -110,6 +110,46 @@ The Podman configuration files for root reside in `/usr/share/containers` with o
 
 The default authorization file used by the `podman login` and `podman logout` commands reside in `${XDG_RUNTIME_DIR}/containers/auth.json`.
 
+### Using volumes
+
+Rootless Podman is not, and will never be, root; it's not a setuid binary, and gains no privileges when it runs. Instead, Podman makes use of a user namespace to shift the UIDs and GIDs of a block of users it is given access to on the host (via the newuidmap and newgidmap executables) and your own user within the containers that podman creates.
+
+If your container runs with the root user, then `root` in the container is actually your user on the host. UID/GID 1 is the first UID/GID specified in your user's mapping in `/etc/subuid` and `/etc/subgid`, etc. If you mount a directory from the host into a container as a rootless user, and create a file in that directory as root in the container, you'll see it's actually owned by your user on the host.
+
+So, for example,
+
+```
+> whoami
+john
+
+# a folder which is empty
+host> ls /home/john/folder
+host> podman run -v /home/john/folder:/container/volume mycontainer /bin/bash
+
+# Now I'm in the container
+root@container> whoami
+root
+root@container> touch /container/volume/test
+root@container> ls -l /container/volume
+total 0
+-rw-r--r-- 1 root root 0 May 20 21:47 test
+root@container> exit
+
+# I check again
+host> ls -l /home/john/folder
+total 0
+-rw-r--r-- 1 john john 0 May 20 21:47 test
+```
+
+We do recognize that this doesn't really match how many people intend to use rootless Podman - they want their UID inside and outside the container to match. Thus, we provide the `--userns=keep-id` flag, which ensures that your user is mapped to its own UID and GID inside the container.
+
+It is also helpful to distinguish between running podman as a rootless user, and a container which is built to run rootless. If the container you're trying you run has a `USER` which is not root, then when mounting volumes you **must** use `--userns=keep-id`. This is because the container user would not be able to become `root` and access the mounted volumes.
+
+Other considerations in regards to volumes:
+
+- You should always give the full path to the volume you'd like to mount
+- The mount point must exist in the container
+
 ## More information
 
 If you are still experiencing problems running Podman in a rootless environment, please refer to the [Shortcomings of Rootless Podman](https://github.com/containers/libpod/blob/master/rootless.md) page which lists known issues and solutions to known issues in this environment.