Make the documentation of user namespace options in podman-run clearer

This proposes a more comprehensible man page.

A number of things have been lost in translation and this should be reviewed:
- the former docs from --userns say that it is disabled by default. I
  suppose that this is the same as --userns:host, but this should be confirmed.
  It also stated that is would use options like pid=host, which confuses me
  as pid namespaces are a totally different thing from user namespaces. It also
  mentions the enabling of --privileged. I think the difference between using
  --userns:host and not using any user namespace options at all is not clear
  and maybe not very logical. Also what would be the difference between using
  --userns:host and using --priveleged alone?
- I found the syntax for --gidmap at the bottom of the man page in the examples.
  In the example it doesn't use '=', eg. podman run `--gidmap 0:30000:2000`.
  For consistency with the other options I have used '=' for now, but if it is
  optional, I would remove it everywhere, as less tokens is usually improved
  readability. For now the inconsistency remains between the options doc and the
  examples section.
- It wasn't very clear to me whether one should hard wrap long lines or not as the
  contains a mix.
- I haven't for now looked at user namespace options on other commands, but
  that should be done surely before merging.
- I didn't know which command to run to generate the groff, so that needs doing still.

from issue #1374

Signed-off-by: Naja Melan <najamelan@autistici.org>

Signed-off-by: Naja Melan <najamelan@autistici.org>

Closes: #1380
Approved by: rhatdan

1 files changed, 23 insertions, 15 deletions

diff --git a/docs/podman-run.1.md b/docs/podman-run.1.md
index d01d5c100..41d37ee17 100644
--- a/docs/podman-run.1.md
+++ b/docs/podman-run.1.md
@@ -252,11 +252,12 @@ Read in a line delimited file of environment variables
 Expose a port, or a range of ports (e.g. --expose=3300-3310) to set up port redirection
 on the host system.
 
-**--gidmap**=map
+**--gidmap**=container_gid:host_gid:amount
+**--gidmap**=0:30000:2000
 
-GID map for the user namespace.  Using this flag will run the container with user namespace enabled.  It conflicts with the `--userns` and `--subgidname` flags.
-
-The following example maps uids 0-2000 in the container to the uids 30000-31999 on the host and gids 0-2000 in the container to the gids 30000-31999 on the host.
+Run the container in a new user namespace with the supplied mapping. This option conflicts with the --userns and --subgidname flags.
+This option can be passed several times to map different ranges. If calling podman run as an unprivileged user, the user needs to have the right to use the mapping. See `man subuid`.
+The example maps gids 0-2000 in the container to the gids 30000-31999 on the host.
 
 **--group-add**=[]
 
@@ -545,11 +546,14 @@ Signal to stop a container. Default is SIGTERM.
 Timeout (in seconds) to stop a container. Default is 10.
 
 **--subgidname**=name
-
-Name for GID map from the `/etc/subgid` file.  Using this flag will run the container with user namespace enabled.  This flag conflicts with `--userns` and `--gidmap`.
+Run the container in a new user namespace from 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 `man subgid`.
+This flag conflicts with `--userns` and `--gidmap`.
 
 **--subuidname**=name
-Name for UID map from the `/etc/subuid` file.  Using this flag will run the container with user namespace enabled.  This flag conflicts with `--userns` and `--uidmap`.
+Run the container in a new user namespace from the map with 'name' in the `/etc/subuid` file.
+If calling podman run as an unprivileged user, the user needs to have the right to use the mapping. See `man subuid`.
+This flag conflicts with `--userns` and `--uidmap`.
 
 **--sysctl**=SYSCTL
 
@@ -596,11 +600,12 @@ interactive shell. The default is false.
 **NOTE**: The **-t** option is incompatible with a redirection of the podman client
 standard input.
 
-**--uidmap**=map
-
-UID map for the user namespace.  Using this flag will run the container with user namespace enabled.  It conflicts with the `--userns` and `--subuidname` flags.
+**--uidmap**=container_uid:host_uid:amount
+**--uidmap**=0:30000:2000
 
-The following example maps uids 0-2000 in the container to the uids 30000-31999 on the host and gids 0-2000 in the container to the gids 30000-31999 on the host.
+Run the container in a new user namespace with the supplied mapping. This option conflicts with the --userns and --subuidname flags.
+This option can be passed several times to map different ranges. If calling podman run as an unprivileged user, the user needs to have the right to use the mapping. See `man subuid`.
+The example maps uids 0-2000 in the container to the uids 30000-31999 on the host.
 
 **--ulimit**=[]
 
@@ -615,12 +620,15 @@ The followings examples are all valid:
 
 Without this argument the command will be run as root in the container.
 
-**--userns**=""
+**--userns**=host
+**--userns**=ns:my_namespace
 
-Set the usernamespace mode for the container. The use of userns is disabled by default.
+Set the user namespace for the container.
 
-`host`: use the host usernamespace and enable all privileged options (e.g., `pid=host` or `--privileged`).
-`ns`: specify the usernamespace to use.
+- `host`: run in the user namespace of the caller. This is the default if no user namespace options are set. The processes running in the container will have the same privileges on the host as any other process launched by the calling user.
+- `ns`: run the container in the given existing user namespace.
+
+This option is incompatible with --gidmap, --uidmap, --subuid and --subgid
 
 **--uts**=*host*