Merge pull request #5839 from rhatdan/troubleshoot

 [CI:DOCS] Add SELinux volume information to troubleshoot.md

1 files changed, 51 insertions, 19 deletions

diff --git a/troubleshooting.md b/troubleshooting.md
index da7a9cb6a..ea85df58a 100644
--- a/troubleshooting.md
+++ b/troubleshooting.md
@@ -16,7 +16,39 @@ If they differ, please update your version of PODMAN to the latest possible
 and retry your command before reporting the issue.
 
 ---
-### 2) No such image or Bare keys cannot contain ':'
+### 2) Can't use volume mount, get permission denied
+
+$ podman run -v ~/mycontent:/content fedora touch /content/file
+touch: cannot touch '/content/file': Permission denied
+
+#### Solution
+
+This is usually caused by SELinux.
+
+Labeling systems like SELinux require that proper labels are placed on volume
+content mounted into a container. Without a label, the security system might
+prevent the processes running inside the container from using the content. By
+default, Podman does not change the labels set by the OS.
+
+To change a label in the container context, you can add either of two suffixes
+**:z** or **:Z** to the volume mount. These suffixes tell Podman to relabel file
+objects on the shared volumes. The **z** option tells Podman that two containers
+share the volume content. As a result, Podman labels the content with a shared
+content label. Shared volume labels allow all containers to read/write content.
+The **Z** option tells Podman to label the content with a private unshared label.
+Only the current container can use a private volume.
+
+$ podman run -v ~/mycontent:/content:Z fedora touch /content/file
+
+Make sure the content is private for the container.  Do not relabel system directories and content.
+Relabeling system content might cause other confined services on your machine to fail.  For these
+types of containers we recommmend that disable SELinux separation.  The option `--security-opt label=disable`
+will disable SELinux separation for the container.
+
+$ podman run --security-opt label=disable -v ~:/home/user fedora touch /home/user/file
+
+---
+### 3) No such image or Bare keys cannot contain ':'
 
 When doing a `podman pull` or `podman build` command and a "common" image cannot be pulled,
 it is likely that the `/etc/containers/registries.conf` file is either not installed or possibly
@@ -44,7 +76,7 @@ error pulling image "fedora": unable to pull fedora: error getting default regis
     *  i.e. `registries = ['registry.fedoraproject.org', 'quay.io', 'registry.access.redhat.com']`
 
 ---
-### 3) http: server gave HTTP response to HTTPS client
+### 4) http: server gave HTTP response to HTTPS client
 
 When doing a Podman command such as `build`, `commit`, `pull`, or `push` to a registry,
 tls verification is turned on by default.  If authentication is not used with
@@ -70,7 +102,7 @@ communicate with a registry and not use tls verification.
   * I.e. `podman push --tls-verify=false alpine docker://localhost:5000/myalpine:latest`
 
 ---
-### 4) Rootless: could not get runtime - database configuration mismatch
+### 5) Rootless: could not get runtime - database configuration mismatch
 
 In Podman release 0.11.1, a default path for rootless containers was changed,
 potentially causing rootless Podman to be unable to function. The new default
@@ -104,7 +136,7 @@ the first path in the error message Podman gave (in this case,
 `/run/user/1000/tmp`).
 
 ---
-### 5) rootless containers cannot ping hosts
+### 6) rootless containers cannot ping hosts
 
 When using the ping command from a non-root container, the command may
 fail because of a lack of privileges.
@@ -132,7 +164,7 @@ To make the change persistent, you'll need to add a file in
 `/etc/sysctl.d` that contains `net.ipv4.ping_group_range=0 $MAX_UID`.
 
 ---
-### 6) Build hangs when the Dockerfile contains the useradd command
+### 7) Build hangs when the Dockerfile contains the useradd command
 
 When the Dockerfile contains a command like `RUN useradd -u 99999000 -g users newuser` the build can hang.
 
@@ -144,7 +176,7 @@ If you are using a useradd command within a Dockerfile with a large UID/GID, it
 
 If the entry in the Dockerfile looked like: RUN useradd -u 99999000 -g users newuser then add the `--no-log-init` parameter to change it to: `RUN useradd --no-log-init -u 99999000 -g users newuser`. This option tells useradd to stop creating the lastlog file.
 
-### 7) Permission denied when running Podman commands
+### 8) Permission denied when running Podman commands
 
 When rootless Podman attempts to execute a container on a non exec home directory a permission error will be raised.
 
@@ -174,7 +206,7 @@ cat ~/.config/containers/storage.conf
     mount_program = "/bin/fuse-overlayfs"
 ```
 
-### 8) Permission denied when running systemd within a Podman container
+### 9) Permission denied when running systemd within a Podman container
 
 When running systemd as PID 1 inside of a container on an SELinux
 separated machine, it needs to write to the cgroup file system.
@@ -192,7 +224,7 @@ processes to write to the cgroup file system. Turn on this boolean, on SELinux s
 
 `setsebool -P container_manage_cgroup true`
 
-### 9) Newuidmap missing when running rootless Podman commands
+### 10) Newuidmap missing when running rootless Podman commands
 
 Rootless Podman requires the newuidmap and newgidmap programs to be installed.
 
@@ -210,7 +242,7 @@ cannot find newuidmap: exec: "newuidmap": executable file not found in $PATH
 
 Install a version of shadow-utils that includes these executables.  Note RHEL7 and Centos 7 will not have support for this until RHEL7.7 is released.
 
-### 10) rootless setup user: invalid argument
+### 11) rootless setup user: invalid argument
 
 Rootless Podman requires the user running it to have a range of UIDs listed in /etc/subuid and /etc/subgid.
 
@@ -259,7 +291,7 @@ grep johndoe /etc/subuid /etc/subgid
 /etc/subgid:johndoe:200000:1001
 ```
 
-### 11) Changing the location of the Graphroot leads to permission denied
+### 12) Changing the location of the Graphroot leads to permission denied
 
 When I change the graphroot storage location in storage.conf, the next time I
 run Podman I get an error like:
@@ -298,7 +330,7 @@ tells SELinux to apply the labels to the actual content.
 Now all new content created in these directories will automatically be created
 with the correct label.
 
-### 12) Anonymous image pull fails with 'invalid username/password'
+### 13) Anonymous image pull fails with 'invalid username/password'
 
 Pulling an anonymous image that doesn't require authentication can result in an
 `invalid username/password` error.
@@ -324,7 +356,7 @@ are established locally and then the password is updated later in the container
 Depending upon which container tool was used to establish the credentials, use `podman logout`
 or `docker logout` to remove the credentials from the authentication file.
 
-### 13) Running Podman inside a container causes container crashes and inconsistent states
+### 14) Running Podman inside a container causes container crashes and inconsistent states
 
 Running Podman in a container and forwarding some, but not all, of the required host directories can cause inconsistent container behavior.
 
@@ -342,7 +374,7 @@ This can cause Podman to reset container states and lose track of running contai
 
 For running containers on the host from inside a container, we also recommend the [Podman remote client](remote_client.md), which only requires a single socket to be mounted into the container.
 
-### 14) Rootless 'podman build' fails EPERM on NFS:
+### 15) Rootless 'podman build' fails EPERM on NFS:
 
 NFS enforces file creation on different UIDs on the server side and does not understand user namespace, which rootless Podman requires.
 When a container root process like YUM attempts to create a file owned by a different UID, NFS Server denies the creation.
@@ -362,7 +394,7 @@ Choose one of the following:
     * Edit `~/.config/containers/libpod.conf` and point the `volume_path` option to that local directory.
   * Otherwise just run Podman as root, via `sudo podman`
 
-### 15) Rootless 'podman build' fails when using OverlayFS:
+### 16) Rootless 'podman build' fails when using OverlayFS:
 
 The Overlay file system (OverlayFS) requires the ability to call the `mknod` command when creating whiteout files
 when extracting an image.  However, a rootless user does not have the privileges to use `mknod` in this capacity.
@@ -392,7 +424,7 @@ Choose one of the following:
     * Install the fuse-overlayfs package for your Linux Distribution.
     * Add `mount_program = "/usr/bin/fuse-overlayfs"` under `[storage.options]` in your `~/.config/containers/storage.conf` file.
 
-### 16) rhel7-init based images don't work with cgroups v2
+### 17) rhel7-init based images don't work with cgroups v2
 
 The systemd version shipped in rhel7-init doesn't have support for cgroups v2.  You'll need at least systemd 230.
 
@@ -411,7 +443,7 @@ You'll need to either:
 * configure the host to use cgroups v1
 * update the image to use an updated version of systemd.
 
-### 17) rootless containers exit once the user session exits
+### 18) rootless containers exit once the user session exits
 
 You need to set lingering mode through loginctl to prevent user processes to be killed once
 the user session completed.
@@ -429,7 +461,7 @@ or as root if your user has not enough privileges.
 
 * sudo loginctl enable-linger $UID
 
-### 18) `podman run` fails with "bpf create: permission denied error"
+### 19) `podman run` fails with "bpf create: permission denied error"
 
 The Kernel Lockdown patches deny eBPF programs when Secure Boot is enabled in the BIOS. [Matthew Garrett's post](https://mjg59.dreamwidth.org/50577.html) describes the relationship between Lockdown and Secure Boot and [Jan-Philip Gehrcke's](https://gehrcke.de/2019/09/running-an-ebpf-program-may-require-lifting-the-kernel-lockdown/) connects this with eBPF. [RH bug 1768125](https://bugzilla.redhat.com/show_bug.cgi?id=1768125) contains some additional details.
 
@@ -443,7 +475,7 @@ Attempts to run podman result in
 
 One workaround is to disable Secure Boot in your BIOS.
 
-### 19) error creating libpod runtime: there might not be enough IDs available in the namespace
+### 20) error creating libpod runtime: there might not be enough IDs available in the namespace
 
 Unable to pull images
 
@@ -470,7 +502,7 @@ $ podman unshare cat /proc/self/uid_map
 
 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
+### 21) 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=...`.