8 files changed, 114 insertions, 14 deletions
diff --git a/docs/podman-build.1.md b/docs/podman-build.1.md
index 12e8c3bf0..120573235 100644
--- a/docs/podman-build.1.md
+++ b/docs/podman-build.1.md
@@ -172,7 +172,7 @@ value can be entered.  The password is entered without echo.
 
 This is a Docker specific option to disable image verification to a Docker
 registry and is not supported by Podman.  This flag is a NOOP and provided
-soley for scripting compatibility.
+solely for scripting compatibility.
 
 **--dns**=*dns*
 
diff --git a/docs/podman-commit.1.md b/docs/podman-commit.1.md
index bf0df0dda..a269d0fae 100644
--- a/docs/podman-commit.1.md
+++ b/docs/podman-commit.1.md
@@ -58,7 +58,7 @@ Suppress output
 ## EXAMPLES
 
 ```
-$ podman commit --change CMD=/bin/bash --change ENTRYPOINT=/bin/sh --change LABEL=blue=image reverent_golick image-commited
+$ podman commit --change CMD=/bin/bash --change ENTRYPOINT=/bin/sh --change LABEL=blue=image reverent_golick image-committed
 Getting image source signatures
 Copying blob sha256:b41deda5a2feb1f03a5c1bb38c598cbc12c9ccd675f438edc6acd815f7585b86
  25.80 MB / 25.80 MB [======================================================] 0s
@@ -70,17 +70,17 @@ e3ce4d93051ceea088d1c242624d659be32cf1667ef62f1d16d6b60193e2c7a8
 ```
 
 ```
-$ podman commit -q --message "committing container to image" reverent_golick image-commited
+$ podman commit -q --message "committing container to image" reverent_golick image-committed
 e3ce4d93051ceea088d1c242624d659be32cf1667ef62f1d16d6b60193e2c7a8
 ```
 
 ```
-$ podman commit -q --author "firstName lastName" reverent_golick image-commited
+$ podman commit -q --author "firstName lastName" reverent_golick image-committed
 e3ce4d93051ceea088d1c242624d659be32cf1667ef62f1d16d6b60193e2c7a8
 ```
 
 ```
-$ podman commit -q --pause=false containerID image-commited
+$ podman commit -q --pause=false containerID image-committed
 e3ce4d93051ceea088d1c242624d659be32cf1667ef62f1d16d6b60193e2c7a8
 ```
 
diff --git a/docs/podman-create.1.md b/docs/podman-create.1.md
index a4eebef4c..b08488d7b 100644
--- a/docs/podman-create.1.md
+++ b/docs/podman-create.1.md
@@ -55,11 +55,11 @@ Block IO weight (relative weight) accepts a weight value between 10 and 1000.
 
 Block IO weight (relative device weight, format: `DEVICE_NAME:WEIGHT`).
 
-**--cap-add**=*capabilitiy*
+**--cap-add**=*capability*
 
 Add Linux capabilities
 
-**--cap-drop**=*capabilitiy*
+**--cap-drop**=*capability*
 
 Drop Linux capabilities
 
@@ -382,7 +382,7 @@ Not implemented
 
 **--log-driver**="*k8s-file*"
 
-Logging driver for the container.  Currently not supported.  This flag is a NOOP provided soley for scripting compatibility.
+Logging driver for the container.  Currently available options are *k8s-file* and *journald*, with *json-file* aliased to *k8s-file* for scripting compatibility.
 
 **--log-opt**=*path*
 
diff --git a/docs/podman-generate-kube.1.md b/docs/podman-generate-kube.1.md
index 88d8e9627..76baad83a 100644
--- a/docs/podman-generate-kube.1.md
+++ b/docs/podman-generate-kube.1.md
@@ -20,7 +20,7 @@ Output to the given file, instead of STDOUT. If the file already exists, `genera
 
 **--service**, **-s**
 
-Generate a Kubernetes service object in addition to the Pods. Used to generate a Service specification for the corresponding Pod ouput. In particular, if the object has portmap bindings, the service specification will include a NodePort declaration to expose the service. A
+Generate a Kubernetes service object in addition to the Pods. Used to generate a Service specification for the corresponding Pod output. In particular, if the object has portmap bindings, the service specification will include a NodePort declaration to expose the service. A
 random port is assigned by Podman in the specification.
 
 ## Examples
diff --git a/docs/podman-run.1.md b/docs/podman-run.1.md
index eca98514b..042a7a561 100644
--- a/docs/podman-run.1.md
+++ b/docs/podman-run.1.md
@@ -395,7 +395,7 @@ Not implemented
 
 **--log-driver**="*k8s-file*"
 
-Logging driver for the container.  Currently not supported.  This flag is a NOOP provided soley for scripting compatibility.
+Logging driver for the container.  Currently available options are *k8s-file* and *journald*, with *json-file* aliased to *k8s-file* for scripting compatibility.
 
 **--log-opt**=*path*
 
@@ -669,7 +669,7 @@ Signal to stop a container. Default is SIGTERM.
 
 Timeout (in seconds) to stop a container. Default is 10.
 
-**--subuidname**=*name*
+**--subgidname**=*name*
 
 Run the container in a new user namespace using the map with 'name' in the `/etc/subgid` file.
 If calling podman run as an unprivileged user, the user needs to have the right to use the mapping. See `subgid(5)`.
diff --git a/docs/podman-system-migrate.1.md b/docs/podman-system-migrate.1.md
index 48f3bca8f..1efa779ce 100644
--- a/docs/podman-system-migrate.1.md
+++ b/docs/podman-system-migrate.1.md
@@ -11,11 +11,24 @@ podman\-system\-migrate - Migrate container to the latest version of podman
 
 **podman system migrate** takes care of migrating existing containers to the latest version of podman if any change is necessary.
 
+"Rootless Podman uses a pause process to keep the unprivileged
+namespaces alive. This prevents any change to the `/etc/subuid` and
+`/etc/subgid` files from being propagated to the rootless containers
+while the pause process is running.
+
+For these changes to be propagated, it is necessary to first stop all
+running containers associated with the user and to also stop the pause
+process and delete its pid file.  Instead of doing it manually, `podman
+system migrate` can be used to stop both the running containers and the
+pause process. The `/etc/subuid` and `/etc/subgid` files can then be
+edited or changed with usermod to recreate the user namespace with the
+newly configured mappings.
+
 ## SYNOPSIS
 **podman system migrate**
 
 ## SEE ALSO
-`podman(1)`, `libpod.conf(5)`
+`podman(1)`, `libpod.conf(5)`, `usermod(8)`
 
 ## HISTORY
 April 2019, Originally compiled by Giuseppe Scrivano (gscrivan at redhat dot com)
diff --git a/docs/podman.1.md b/docs/podman.1.md
index 3b682b10d..022514a80 100644
--- a/docs/podman.1.md
+++ b/docs/podman.1.md
@@ -93,6 +93,8 @@ Storage driver option, Default storage driver options are configured in /etc/con
 
 output logging information to syslog as well as the console
 
+On remote clients, logging is directed to the file ~/.config/containers/podman.log
+
 **--version**, **-v**
 
 Print the version
@@ -109,13 +111,13 @@ the exit codes follow the `chroot` standard, see below:
     Error: unknown flag: --foo
       125
 
-**_126_** if executing a **_contained command_** and the the **_command_** cannot be invoked
+**_126_** if executing a **_contained command_** and the **_command_** cannot be invoked
 
     $ podman run busybox /etc; echo $?
     Error: container_linux.go:346: starting container process caused "exec: \"/etc\": permission denied": OCI runtime error
       126
 
-**_127_** if executing a **_contained command_** and the the **_command_** cannot be found
+**_127_** if executing a **_contained command_** and the **_command_** cannot be found
     $ podman run busybox foo; echo $?
     Error: container_linux.go:346: starting container process caused "exec: \"foo\": executable file not found in $PATH": OCI runtime error
       127
diff --git a/docs/tutorials/rootless_tutorial.md b/docs/tutorials/rootless_tutorial.md
new file mode 100644
index 000000000..553e8d297
--- /dev/null
+++ b/docs/tutorials/rootless_tutorial.md
@@ -0,0 +1,85 @@
+![PODMAN logo](../../logo/podman-logo-source.svg)
+
+# Basic Setup and Use of Podman in a Rootless environment.
+
+Prior to allowing users without root privileges to run Podman, the administrator must install or build Podman and complete the following configurations.
+
+## Administrator Actions
+
+### Installing Podman
+
+For installing Podman, please see the [installation instructions](https://github.com/containers/libpod/blob/master/install.md).
+
+### Building Podman
+
+For building Podman, please see the [installation instructions](https://github.com/containers/libpod/blob/master/install.md#building-from-scratch).
+
+### Install slirp4netns
+
+The [slirp4netns](https://github.com/rootless-containers/slirp4netns) package provides user-mode networking for unprivileged network namespaces and must be installed on the machine in order for Podman to run in a rootless environment.  The package is available on most Linux distributions via their package distribution software such as yum, dnf, apt, zypper, etc.  If the package is not available, you can build and install slirp4netns from [GitHub](https://github.com/rootless-containers/slirp4netns).
+
+### Ensure fuse-overlayfs is installed
+
+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.
+
+### Enable user namespaces (on RHEL7 machines)
+
+The number of user namespaces that are allowed on the system is specified in the file `/proc/sys/user/max_user_namespaces`.  On most Linux platforms this is preset by default and no adjustment is necessary.  However on RHEL7 machines a user with root privileges may need to set that to a reasonable value by using this command:  `sysctl user.max_user_namespaces=15000`.
+
+### /etc/subuid and /etc/subgid configuration
+
+Rootless podman requires the user running it to have a range of UIDs listed in /etc/subuid and /etc/subgid files.  The `shadows-utils` or `newuid` package provides these files on different distributions and  they must be installed on the system.  These files will need someone with root privileges on the system to add or update the entries within them.  The following is a summarization from the [How does rootless Podman work?](https://opensource.com/article/19/2/how-does-rootless-podman-work) article by Dan Walsh on [opensource.com](https://opensource.com)
+
+Update the /etc/subuid and /etc/subgid with fields for each user that will be allowed to create containers that look like the following.  Note that the values for each user must be unique and without any overlap.  If there is an overlap, there is a potential for a user to use another’s namespace and they could corrupt it.
+
+```
+cat /etc/subuid
+johndoe:100000:65536
+test:165536:65536
+```
+
+The format of this file is USERNAME:UID:RANGE
+
+* username as listed in /etc/passwd or getpwent.
+* The initial uid allocated for the user.
+* The size of the range of UIDs allocated for the user.
+
+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.
+
+Rather than updating the files directly, the usermod program can be used to assign UIDs and GIDs to a user.
+
+```
+usermod --add-subuids 200000-201000 --add-subgids 200000-201000 johndoe
+grep johndoe /etc/subuid /etc/subgid
+/etc/subuid:johndoe:200000:1001
+/etc/subgid:johndoe:200000:1001
+```
+
+### Enable unprivileged `ping`
+
+Users running in a non-privileged container may not be able to use the `ping` utility from that container.
+
+If this is required, the administrator must verify that the UID of the user is part of the range in the `/proc/sys/net/ipv4/ping_group_range` file.
+
+To change its value the administrator can use a call similar to: `sysctl -w "net.ipv4.ping_group_range=0 2000000"`.
+
+To make the change persistent, the administrator will need to add a file in `/etc/sysctl.d` that contains `net.ipv4.ping_group_range=0 $MAX_UID`.
+
+
+## User Actions
+
+The majority of the work necessary to run Podman in a rootless environment is on the shoulders of the machine’s administrator.
+
+Once the Administrator has completed the setup on the machine and then the configurations for the user in /etc/subuid and /etc/subgid, the user can just start using any Podman command that they wish.
+
+### User Configuration Files.
+
+The Podman configuration files for root reside in /etc/containers.  In the rootless environment they reside in ${HOME}/.config/containers and are owned by each individual user.  The user can modify these files as they wish.
+
+## More information
+
+If you are still experiencing problems running Podman in a rootless environment, please refer to the [Shortcomings of Rootless Podman](https://github.com/containers/libpod/blob/master/rootless.md) page which lists known issues and solutions to known issues in this environment.
+
+For more information on Podman and its subcommands, checkout the asciiart demos on the [README.md](../../README.md#commands) page or the [podman.io](https://podman.io) web site.