Add example of fuse-overlay to podman system reset

A fairly common mistake users are hitting is running rootless podman without
installing fuse-overlay.  Then they want to reset storage.  Sometimes they
modify storage.conf first and `podman system reset` fails.

This PR attempts to explain how to convert properly.

Fixes: https://github.com/containers/podman/issues/7446

Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>

1 files changed, 26 insertions, 2 deletions

diff --git a/docs/source/markdown/podman-system-reset.1.md b/docs/source/markdown/podman-system-reset.1.md
index 3294bac9b..1e5ef7235 100644
--- a/docs/source/markdown/podman-system-reset.1.md
+++ b/docs/source/markdown/podman-system-reset.1.md
@@ -7,7 +7,15 @@ podman\-system\-reset - Reset storage back to initial state
 **podman system reset** [*options*]
 
 ## DESCRIPTION
-**podman system reset** removes all pods, containers, images and volumes. Must be run after changing any of the following values in the `containers.conf` file: `static_dir`, `tmp_dir` or `volume_path`.
+**podman system reset** removes all pods, containers, images and volumes.
+
+This command must be run **before** changing any of the following fields in the
+`containers.conf` or `storage.conf` files: `driver`, `static_dir`, `tmp_dir`
+or `volume_path`.
+
+`podman system reset` reads the current configuration and attempts to remove all
+of the relevant configurations. If the administrator modified the configuration files first,
+`podman system reset` might not be able to clean up the previous storage.
 
 ## OPTIONS
 **--force**, **-f**
@@ -18,8 +26,24 @@ Do not prompt for confirmation
 
 Print usage statement
 
+## EXAMPLES
+
+### Switching rootless user from VFS driver to overlay with fuse-overlayfs
+
+If the user ran rootless containers without having the `fuse-overlayfs` program
+installed, podman defaults to the `vfs` storage in their home directory. If they
+want to switch to use fuse-overlay, they must install the fuse-overlayfs
+package. The user needs to reset the storage to use overlayfs by default.
+Execute `podman system reset` as the user first to remove the VFS storage. Now
+the user can edit the `/etc/containers/storage.conf` to make any changes if
+necessary. If the system's default was already `overlay`, then no changes are
+necessary to switch to fuse-overlayfs. Podman looks for the existence of
+fuse-overlayfs to use it when set in the `overlay` driver, only falling back to vfs
+if the program does not exist. Users can run `podman info` to ensure Podman is
+using fuse-overlayfs and the overlay driver.
+
 ## SEE ALSO
-`podman(1)`, `podman-system(1)`
+`podman(1)`, `podman-system(1)`, `fuse-overlayfs(1)`, `containers-storage.conf(5)`
 
 ## HISTORY
 November 2019, Originally compiled by Dan Walsh (dwalsh at redhat dot com)