Add rootless NFS and OverlayFS warnings to docs

Add warnings/work arounds about NFS and OverlayFS to the troubleshooting guide
and also the main podman page.  Verified that these warnings are on the rootless
page already.

Signed-off-by: TomSweeneyRedHat <tsweeney@redhat.com>

2 files changed, 59 insertions, 1 deletions

diff --git a/docs/podman.1.md b/docs/podman.1.md
index bfb5a9aec..12b7866ca 100644
--- a/docs/podman.1.md
+++ b/docs/podman.1.md
@@ -223,7 +223,7 @@ When Podman runs in rootless mode, the file `$HOME/.config/containers/mounts.con
 ## Rootless mode
 Podman can also be used as non-root user.  When podman runs in rootless mode, a user namespace is automatically created for the user, defined in /etc/subuid and /etc/subgid.
 
-Containers created by a non-root user are not visible to other users and are not seen or managed by podman running as root.
+Containers created by a non-root user are not visible to other users and are not seen or managed by Podman running as root.
 
 It is required to have multiple uids/gids set for an user.  Be sure the user is present in the files `/etc/subuid` and `/etc/subgid`.
 
@@ -244,6 +244,14 @@ Images are pulled under `XDG_DATA_HOME` when specified, otherwise in the home di
 
 Currently the slirp4netns package is required to be installed to create a network device, otherwise rootless containers need to run in the network namespace of the host.
 
+### **NOTE:** Unsupported file systems in rootless mode
+
+The Overlay file system (OverlayFS) is not supported in rootless mode.  The fuse-overlayfs package is a tool that provides the functionality of OverlayFS in user namespace that allows mounting file systems in rootless environments.  It is recommended to install the fuse-overlayfs package and to enable it by adding `mount_program = "/usr/bin/fuse-overlayfs"` under `[storage.options]` in the `~/.config/containers/storage.conf` file.
+
+The Network File System (NFS) and other distributed file systems (for example: Lustre, Spectrum Scale, the General Parallel File System (GPFS)) are not supported when running in rootless mode as these file systems do not understand user namespace.  However, rootless Podman can make use of an NFS Homedir by modifying the `~/.config/containers/storage.conf` to have the `graphroot` option point to a directory stored on local (Non NFS) storage.
+
+For more information, please refer to the [Podman Troubleshooting Page](https://github.com/containers/libpod/blob/master/troubleshooting.md).
+
 ## SEE ALSO
 `containers-mounts.conf(5)`, `containers-registries.conf(5)`, `containers-storage.conf(5)`, `buildah(1)`, `libpod.conf(5)`, `oci-hooks(5)`, `policy.json(5)`, `subuid(5)`, `subgid(5)`, `slirp4netns(1)`
 
diff --git a/troubleshooting.md b/troubleshooting.md
index 64aec475e..798d9cec4 100644
--- a/troubleshooting.md
+++ b/troubleshooting.md
@@ -315,3 +315,53 @@ Not doing this will cause Podman in the container to detect that temporary files
 This can cause Podman to reset container states and lose track of running containers.
 
 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.
+
+### 13) 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.
+NFS is also a problem for the file locks when the storage is on it.  Other distributed file systems (for example: Lustre, Spectrum Scale, the General Parallel File System (GPFS)) are also not supported when running in rootless mode as these file systems do not understand user namespace.
+
+#### Symptom
+```console
+$ podman build .
+ERRO[0014] Error while applying layer: ApplyLayer exit status 1 stdout:  stderr: open /root/.bash_logout: permission denied
+error creating build container: Error committing the finished image: error adding layer with blob "sha256:a02a4930cb5d36f3290eb84f4bfa30668ef2e9fe3a1fb73ec015fc58b9958b17": ApplyLayer exit status 1 stdout:  stderr: open /root/.bash_logout: permission denied
+```
+
+#### Solution
+Choose one of the following:
+  * Setup containers/storage in a different directory, not on an NFS share.
+    * Create a directory on a local file system.
+    * Edit `~/.config/containers/libpod.conf` and point the `volume_path` option to that local directory.
+  * Otherwise just run podman as root, via `sudo podman`
+
+### 14) 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.
+
+#### Symptom
+```console
+podman build --storage-driver overlay .
+STEP 1: FROM docker.io/ubuntu:xenial
+Getting image source signatures
+Copying blob edf72af6d627 done
+Copying blob 3e4f86211d23 done
+Copying blob 8d3eac894db4 done
+Copying blob f7277927d38a done
+Copying config 5e13f8dd4c done
+Writing manifest to image destination
+Storing signatures
+Error: error creating build container: Error committing the finished image: error adding layer with blob "sha256:8d3eac894db4dc4154377ad28643dfe6625ff0e54bcfa63e0d04921f1a8ef7f8": Error processing tar file(exit status 1): operation not permitted
+$ podman build .
+ERRO[0014] Error while applying layer: ApplyLayer exit status 1 stdout:  stderr: open /root/.bash_logout: permission denied
+error creating build container: Error committing the finished image: error adding layer with blob "sha256:a02a4930cb5d36f3290eb84f4bfa30668ef2e9fe3a1fb73ec015fc58b9958b17": ApplyLayer exit status 1 stdout:  stderr: open /root/.bash_logout: permission denied
+```
+
+#### Solution
+Choose one of the following:
+  * Complete the build operation as a privileged user.
+  * Install and configure fuse-overlayfs.
+    * 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.