Merge pull request #3968 from TomSweeneyRedHat/dev/tsweeney/rootlessup

Add cgroup v2 info to rootless tutorial

2 files changed, 22 insertions, 13 deletions

diff --git a/docs/tutorials/rootless_tutorial.md b/docs/tutorials/rootless_tutorial.md
index c98e74c96..ed700485a 100644
--- a/docs/tutorials/rootless_tutorial.md
+++ b/docs/tutorials/rootless_tutorial.md
@@ -4,6 +4,17 @@
 
 Prior to allowing users without root privileges to run Podman, the administrator must install or build Podman and complete the following configurations.
 
+## cgroup V2 support
+
+The cgroup V2  Linux kernel feature allows the user to limit the amount of resources a rootless container can use.  If the Linux distribution that you are running Podman on is enabled with  cgroup V2 then you might need to change the default OCI Runtime.  The default runtime `runc` does not currently work with cgroup V2 enabled systems, so you have to switch to the alternative OCI runtime `crun`.
+
+The alternative OCI runtime support for cgroup V2 can  be turned on at the command line by using the `--runtime` option:
+
+```
+sudo podman --runtime /usr/bin/crun
+```
+or by changing the value for the "Default OCI runtime" in the libpod.conf file either at the system level or at the [#user-configuration-files](user level) from `runtime = "runc"` to `runtime = "crun"`.
+
 ## Administrator Actions
 
 ### Installing Podman
@@ -22,7 +33,7 @@ The [slirp4netns](https://github.com/rootless-containers/slirp4netns) package pr
 
 When using Podman in a rootless environment, it is recommended to use fuse-overlayfs rather than the VFS file system.  Installing the fuse3-devel package gives Podman the dependencies it needs to install, build and use fuse-overlayfs in a rootless environment for you.  The fuse-overlayfs project is also available from [GitHub](https://github.com/containers/fuse-overlayfs).  This especially needs to be checked on Ubuntu distributions as fuse-overlayfs is not generally installed by default.
 
-If podman is installed before fuse-overlayfs, it may be necessary to change the `driver` option under `[storage]` to `"overlay"`.
+If Podman is installed before fuse-overlayfs, it may be necessary to change the `driver` option under `[storage]` to `"overlay"`.
 
 ### Enable user namespaces (on RHEL7 machines)
 
@@ -48,7 +59,7 @@ The format of this file is USERNAME:UID:RANGE
 
 This means the user johndoe is allocated UIDS 100000-165535 as well as their standard UID in the /etc/passwd file.  NOTE: this is not currently supported with network installs.  These files must be available locally to the host machine.  It is not possible to configure this with LDAP or Active Directory.
 
-If you update either the /etc/subuid or the /etc/subgid file, you need to stop all the running containers owned by the user and kill the pause process that is running on the system for that user.  This can be done automatically by using the [`podman system migrate`](https://github.com/containers/libpod/blob/master/docs/podman-system-migrate.1.md) command which will stop all the containers for the user and will kill the pause process.
+If you update either the /etc/subuid or the /etc/subgid file, you need to stop all the running containers owned by the user and kill the pause process that is running on the system for that user.  This can be done automatically by using the `[podman system migrate](https://github.com/containers/libpod/blob/master/docs/podman-system-migrate.1.md)` command which will stop all the containers for the user and will kill the pause process.
 
 Rather than updating the files directly, the usermod program can be used to assign UIDs and GIDs to a user.
 
@@ -78,7 +89,7 @@ Once the Administrator has completed the setup on the machine and then the confi
 
 ### User Configuration Files.
 
-The Podman configuration files for root reside in /usr/share/containers with overrides in /etc/containers.  In the rootless environment they reside in ${XDG\_CONFIG\_HOME}/containers and are owned by each individual user.  The user can modify these files as they wish.
+The Podman configuration files for root reside in /usr/share/containers with overrides in /etc/containers.  In the rootless environment they reside in ${XDG\_CONFIG\_HOME}/containers and are owned by each individual user.  The main files are libpod.conf and storage.conf and the user can modify these files as they wish.
 
 The default authorization file used by the `podman login` and `podman logout` commands reside in ${XDG\_RUNTIME\_DIR}/containers/auth.json.
 
@@ -89,7 +100,6 @@ The default authorization file used by the `podman login` and `podman logout` co
 Description=nginx
 Requires=user@1001.service
 After=user@1001.service
-
 [Service]
 Type=simple
 KillMode=none
@@ -101,7 +111,6 @@ ExecStop=/usr/bin/podman stop nginx
 Restart=always
 User=nginx
 Group=nginx
-
 [Install]
 WantedBy=multi-user.target
 ```
diff --git a/rootless.md b/rootless.md
index c5033881b..7d5db3868 100644
--- a/rootless.md
+++ b/rootless.md
@@ -6,14 +6,14 @@ Contributors are more than welcomed to help with this work.  If you decide to ca
 
 * Podman can not create containers that bind to ports < 1024.
   * The kernel does not allow processes without CAP_NET_BIND_SERVICE to bind to low ports.
-* Lacking “How To” documentation or documentation in general
-* If /etc/subuid and /etc/subgid not setup for a user, then podman commands
+* “How To” documentation is in patchy at best.
+* If /etc/subuid and /etc/subgid are not setup for a user, then podman commands
 can easily fail
   * This can be a big issue on machines using Network Based Password information (FreeIPA, Active Directory, LDAP)
   * We are working to get support for NSSWITCH on the /etc/subuid and /etc/subgid files.
-* No cgroup Support (hopefully fixed when cgroups V2 happens).
-  * Cgroups V1 does not safely support cgroup delegation.
-  * Cgroups V2 development for container support is ongoing.
+* No cgroup V1 Support
+  * cgroup V1 does not safely support cgroup delegation.
+  * cgroup V2 is available on Fedora 29 and later and other Linux distributions.
 * Can not share container images with CRI-O or other users
 * Difficult to use additional stores for sharing content
 * Does not work on NFS or parallel filesystem homedirs (e.g. [GPFS](https://www.ibm.com/support/knowledgecenter/en/SSFKCN/gpfs_welcome.html))
@@ -28,13 +28,13 @@ can easily fail
 * No CNI Support
   * CNI wants to modify IPTables, plus other network manipulation that requires CAP_SYS_ADMIN.
   * There is potential we could probably do some sort of blacklisting of the relevant plugins, and add a new plugin for rootless networking - slirp4netns as one example and there may be others
-* Cannot use ping
+* Cannot use ping out of the box.
   * [(Can be fixed by setting sysctl on host)](https://github.com/containers/libpod/blob/master/troubleshooting.md#5-rootless-containers-cannot-ping-hosts)
-* Requires new shadow-utils (not found in older (RHEL7/Centos7 distros) Should be fixed in RHEL7.7 release
+* Requires new shadow-utils (not found in older (RHEL7/Centos7 distros) Should be fixed in RHEL7.7 release)
 * A few commands do not work.
   * mount/unmount (on fuse-overlay)
      * Only works if you enter the mount namespace with a tool like buildah unshare
-  * podman stats (Lack of Cgroup support)
+  * podman stats (Without cgroup V2 support)
   * Checkpoint and Restore (CRIU requires root)
   * Pause and Unpause (no freezer cgroup)
 * Issues with higher UIDs can cause builds to fail