docs: add workaround for --device with rootless containers

Fixes #4477

Signed-off-by: Stefan Becker <chemobejk@gmail.com>

4 files changed, 29 insertions, 1 deletions

diff --git a/docs/source/markdown/podman-build.1.md b/docs/source/markdown/podman-build.1.md
index 6c8f239a6..fac8296ad 100644
--- a/docs/source/markdown/podman-build.1.md
+++ b/docs/source/markdown/podman-build.1.md
@@ -176,6 +176,10 @@ value can be entered.  The password is entered without echo.
 
 Add a host device to the container. The format is `<device-on-host>[:<device-on-container>][:<permissions>]` (e.g. --device=/dev/sdc:/dev/xvdc:rwm)
 
+Note: if the user only has access rights via a group then accessing the device
+from inside a rootless container will fail. The `crun` runtime offers a
+workaround for this by adding the option `--annotation io.crun.keep_original_groups=1`.
+
 **--disable-compression, -D**
 
 Don't compress filesystem layers when building the image unless it is required
diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md
index 82d2e8f6a..85aa81553 100644
--- a/docs/source/markdown/podman-create.1.md
+++ b/docs/source/markdown/podman-create.1.md
@@ -204,6 +204,10 @@ Specify the key sequence for detaching a container. Format is a single character
 
 Add a host device to the container. The format is `<device-on-host>[:<device-on-container>][:<permissions>]` (e.g. --device=/dev/sdc:/dev/xvdc:rwm)
 
+Note: if the user only has access rights via a group then accessing the device
+from inside a rootless container will fail. The `crun` runtime offers a
+workaround for this by adding the option `--annotation io.crun.keep_original_groups=1`.
+
 **--device-read-bps**=*path*
 
 Limit read rate (bytes per second) from a device (e.g. --device-read-bps=/dev/sda:1mb)
diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md
index e1177cb34..e8744de35 100644
--- a/docs/source/markdown/podman-run.1.md
+++ b/docs/source/markdown/podman-run.1.md
@@ -210,6 +210,10 @@ Specify the key sequence for detaching a container. Format is a single character
 
 Add a host device to the container. The format is `<device-on-host>[:<device-on-container>][:<permissions>]` (e.g. --device=/dev/sdc:/dev/xvdc:rwm)
 
+Note: if the user only has access rights via a group then accessing the device
+from inside a rootless container will fail. The `crun` runtime offers a
+workaround for this by adding the option `--annotation io.crun.keep_original_groups=1`.
+
 **--device-read-bps**=*path*
 
 Limit read rate (bytes per second) from a device (e.g. --device-read-bps=/dev/sda:1mb)
diff --git a/troubleshooting.md b/troubleshooting.md
index 432c0e32b..d122983d7 100644
--- a/troubleshooting.md
+++ b/troubleshooting.md
@@ -468,4 +468,20 @@ $ podman unshare cat /proc/self/uid_map
          1     100000      65536
 ```
 
-Reference [subuid](http://man7.org/linux/man-pages/man5/subuid.5.html) and [subgid](http://man7.org/linux/man-pages/man5/subgid.5.html) man pages for more detail.
\ No newline at end of file
+Reference [subuid](http://man7.org/linux/man-pages/man5/subuid.5.html) and [subgid](http://man7.org/linux/man-pages/man5/subgid.5.html) man pages for more detail.
+
+### 20) Passed-in device can't be accessed in rootless container
+
+As a non-root user you have group access rights to a device that you want to
+pass into a rootless container with `--device=...`.
+
+#### Symptom
+
+Any access inside the container is rejected with "Permission denied".
+
+#### Solution
+
+The runtime uses `setgroups(2)` hence the process looses all additional groups
+the non-root user has. If you use the `crun` runtime, 0.10.4 or newer,
+then you can enable a workaround by adding `--annotation io.crun.keep_original_groups=1`
+to the `podman` command line.