Begin wiring in USERNS Support into podman

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

Closes: #690
Approved by: mheon

3 files changed, 70 insertions, 7 deletions

diff --git a/docs/podman-create.1.md b/docs/podman-create.1.md
index 457f54edd..1291f39c6 100644
--- a/docs/podman-create.1.md
+++ b/docs/podman-create.1.md
@@ -209,6 +209,11 @@ inside of the container.
    Expose a port, or a range of ports (e.g. --expose=3300-3310) to set up port redirection
    on the host system.
 
+**--gidmap**=map
+   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.
+
 **--group-add**=[]
    Add additional groups to run as
 
@@ -223,9 +228,9 @@ inside of the container.
 **--image-volume**, **builtin-volume**=*bind*|*tmpfs*|*ignore*
     Tells podman how to handle the builtin image volumes. The options are: 'bind', 'tmpfs', or 'ignore' (default 'bind').
     bind: A directory is created inside the container state directory and bind mounted into
-        the container for the volumes.
+	the container for the volumes.
     tmpfs: The volume is mounted onto the container as a tmpfs, which allows the users to create
-        content that disappears when the container is stopped.
+	content that disappears when the container is stopped.
     ignore: All volumes are just ignored and no action is taken.
 
 **-i**, **--interactive**=*true*|*false*
@@ -424,6 +429,12 @@ its root filesystem mounted as read only prohibiting any writes.
 **--stop-timeout**=*10*
   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`.
+
+**--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`.
+
 **--sysctl**=SYSCTL
   Configure namespaced kernel parameters at runtime
 
@@ -460,6 +471,11 @@ 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.
+
+   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.
+
 **--ulimit**=[]
    Ulimit options
 
@@ -472,7 +488,8 @@ standard input.
    Without this argument the command will be run as root in the container.
 
 **--userns**=""
-   Set the usernamespace mode for the container when `userns-remap` option is enabled.
+   Set the usernamespace mode for the container. The use of userns is disabled by default.
+
      **host**: use the host usernamespace and enable all privileged options (e.g., `pid=host` or `--privileged`).
 
 **--uts**=*host*
@@ -556,6 +573,21 @@ can override the working directory by using the **-w** option.
 
 ## EXAMPLES
 
+### Set UID/GID mapping in a new user namespace
+
+If you want to run the container in a new user namespace and define the mapping of
+the uid and gid from the host.
+
+    # podman create --uidmap 0:30000:7000 --gidmap 0:30000:7000 fedora echo hello
+
+## FILES
+
+**/etc/subuid**
+**/etc/subgid**
+
+## SEE ALSO
+SUBGID(5), SUBUID(5),
+
 ## HISTORY
 August 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
 September 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
diff --git a/docs/podman-run.1.md b/docs/podman-run.1.md
index a198fd9d4..df79114f6 100644
--- a/docs/podman-run.1.md
+++ b/docs/podman-run.1.md
@@ -214,6 +214,11 @@ inside of the container.
    Expose a port, or a range of ports (e.g. --expose=3300-3310) to set up port redirection
    on the host system.
 
+**--gidmap**=map
+   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.
+
 **--group-add**=[]
    Add additional groups to run as
 
@@ -228,9 +233,9 @@ inside of the container.
 **--image-volume**, **builtin-volume**=*bind*|*tmpfs*|*ignore*
     Tells podman how to handle the builtin image volumes. The options are: 'bind', 'tmpfs', or 'ignore' (default 'bind')
     bind: A directory is created inside the container state directory and bind mounted into
-        the container for the volumes.
+	the container for the volumes.
     tmpfs: The volume is mounted onto the container as a tmpfs, which allows the users to create
-        content that disappears when the container is stopped.
+	content that disappears when the container is stopped.
     ignore: All volumes are just ignored and no action is taken.
 
 **-i**, **--interactive**=*true*|*false*
@@ -435,6 +440,12 @@ its root filesystem mounted as read only prohibiting any writes.
 **--stop-timeout**=*10*
   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`.
+
+**--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`.
+
 **--sysctl**=SYSCTL
   Configure namespaced kernel parameters at runtime
 
@@ -471,6 +482,11 @@ 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.
+
+   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.
+
 **--ulimit**=[]
     Ulimit options
 
@@ -483,7 +499,8 @@ standard input.
    Without this argument the command will be run as root in the container.
 
 **--userns**=""
-   Set the usernamespace mode for the container when `userns-remap` option is enabled.
+   Set the usernamespace mode for the container. The use of userns is disabled by default.
+
      **host**: use the host usernamespace and enable all privileged options (e.g., `pid=host` or `--privileged`).
 
 **--uts**=*host*
@@ -793,6 +810,21 @@ evolves we expect to see more sysctls become namespaced.
 See the definition of the `--sysctl` option above for the current list of
 supported sysctls.
 
+### Set UID/GID mapping in a new user namespace
+
+If you want to run the container in a new user namespace and define the mapping of
+the uid and gid from the host.
+
+    # podman run --uidmap 0:30000:7000 --gidmap 0:30000:7000 fedora echo hello
+
+## FILES
+
+**/etc/subuid**
+**/etc/subgid**
+
+## SEE ALSO
+SUBGID(5), SUBUID(5),
+
 ## HISTORY
 April 2014, Originally compiled by William Henry (whenry at redhat dot com)
 based on docker.com source material and internal work.
diff --git a/docs/podman.1.md b/docs/podman.1.md
index 1ea6603a7..3e0c59232 100644
--- a/docs/podman.1.md
+++ b/docs/podman.1.md
@@ -96,7 +96,6 @@ has the capability to debug pods/images created by crio.
 
 ## FILES
 
-
 **libpod.conf** (`/etc/containers/libpod.conf`)
 
 	libpod.conf is the configuration file for all tools using libpod to manage containers