13 files changed, 71 insertions, 83 deletions
diff --git a/docs/libpod.conf.5.md b/docs/libpod.conf.5.md
index 2f0b3f303..cb08f0eb0 100644
--- a/docs/libpod.conf.5.md
+++ b/docs/libpod.conf.5.md
@@ -34,7 +34,7 @@ libpod to manage containers.
 
   Each `*.json` file in the path configures a hook for Podman containers.  For more details on the syntax of the JSON files and the semantics of hook injection, see `oci-hooks(5)`.  Podman and libpod currently support both the 1.0.0 and 0.1.0 hook schemas, although the 0.1.0 schema is deprecated.
 
-  Paths listed later in the array higher precedence (`oci-hooks(5)` discusses directory precedence).
+  Paths listed later in the array have higher precedence (`oci-hooks(5)` discusses directory precedence).
 
   For the annotation conditions, libpod uses any annotations set in the generated OCI configuration.
 
diff --git a/docs/podman-build.1.md b/docs/podman-build.1.md
index ccc8bd900..4a26c0981 100644
--- a/docs/podman-build.1.md
+++ b/docs/podman-build.1.md
@@ -36,7 +36,7 @@ Note: this information is not present in Docker image formats, so it is discarde
 **--authfile** *path*
 
 Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`.
-If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`.
+If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. (Not available for remote commands)
 
 Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE
 environment variable. `export REGISTRY_AUTH_FILE=path`
@@ -75,7 +75,7 @@ given.
 **--cert-dir** *path*
 
 Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry.
-Default certificates directory is _/etc/containers/certs.d_.
+Default certificates directory is _/etc/containers/certs.d_. (Not available for remote commands)
 
 **--cgroup-parent**=""
 
@@ -354,12 +354,6 @@ Size of `/dev/shm`. The format is `<number><unit>`. `number` must be greater tha
 Unit is optional and can be `b` (bytes), `k` (kilobytes), `m`(megabytes), or `g` (gigabytes).
 If you omit the unit, the system uses bytes. If you omit the size entirely, the system uses `64m`.
 
-**--signature-policy** *signaturepolicy*
-
-Pathname of a signature policy file to use.  It is not recommended that this
-option be used, as the default behavior of using the system-wide default policy
-(frequently */etc/containers/policy.json*) is most often preferred.
-
 **--squash**
 
 Squash all of the new image's layers (including those inherited from a base image) into a single new layer.
@@ -378,7 +372,7 @@ Commands after the target stage will be skipped.
 
 **--tls-verify** *bool-value*
 
-Require HTTPS and verify certificates when talking to container registries (defaults to true).
+Require HTTPS and verify certificates when talking to container registries (defaults to true). (Not available for remote commands)
 
 **--ulimit**=*type*=*soft-limit*[:*hard-limit*]
 
@@ -506,6 +500,8 @@ You can add the `:ro` or `:rw` suffix to a volume to mount it read-only or
 read-write mode, respectively. By default, the volumes are mounted read-write.
 See examples.
 
+  `Labeling Volume Mounts`
+
 Labeling systems like SELinux require that proper labels are placed on volume
 content mounted into a container. Without a label, the security system might
 prevent the processes running inside the container from using the content. By
@@ -519,6 +515,21 @@ content label. Shared volume labels allow all containers to read/write content.
 The `Z` option tells podman to label the content with a private unshared label.
 Only the current container can use a private volume.
 
+  `Overlay Volume Mounts`
+
+   The `:O` flag tells Buildah to mount the directory from the host as a temporary storage using the Overlay file system. The `RUN` command containers are allowed to modify contents within the mountpoint and are stored in the container storage in a separate directory.  In Ovelay FS terms the source directory will be the lower, and the container storage directory will be the upper. Modifications to the mount point are destroyed when the `RUN` command finishes executing, similar to a tmpfs mount point.
+
+  Any subsequent execution of `RUN` commands sees the original source directory content, any changes from previous RUN commands no longer exists.
+
+  One use case of the `overlay` mount is sharing the package cache from the host into the container to allow speeding up builds.
+
+  Note:
+
+     - Overlay mounts are not currently supported in rootless mode.
+     - The `O` flag is not allowed to be specified with the `Z` or `z` flags. Content mounted into the container is labeled with the private label.
+       On SELinux systems, labels in the source directory needs to be readable by the container label. If not, SELinux container separation must be disabled for the container to work.
+     - Modification of the directory volume mounted into the container with an overlay mount can cause unexpected failures.  It is recommended that you do not modify the directory until the container finishes running.
+
 By default bind mounted volumes are `private`. That means any mounts done
 inside container will not be visible on the host and vice versa. This behavior can
 be changed by specifying a volume mount propagation property.
@@ -583,6 +594,8 @@ $ podman build --security-opt label=level:s0:c100,c200 --cgroup-parent /path/to/
 
 $ podman build --volume /home/test:/myvol:ro,Z -t imageName .
 
+$ podman build -v /var/lib/yum:/var/lib/yum:O -t imageName .
+
 $ podman build --layers -t imageName .
 
 $ podman build --no-cache -t imageName .
diff --git a/docs/podman-container-runlabel.1.md b/docs/podman-container-runlabel.1.md
index 39d798804..a54d5c68e 100644
--- a/docs/podman-container-runlabel.1.md
+++ b/docs/podman-container-runlabel.1.md
@@ -55,7 +55,7 @@ Any additional arguments will be appended to the command.
 **--authfile**
 
 Path of the authentication file. Default is ${XDG_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`.
-If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`.
+If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. (Not available for remote commands)
 
 Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE
 environment variable. `export REGISTRY_AUTH_FILE=path`
@@ -68,7 +68,7 @@ The runlabel command will not execute if --display is specified.
 **--cert-dir** *path*
 
 Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry.
-Default certificates directory is _/etc/containers/certs.d_.
+Default certificates directory is _/etc/containers/certs.d_. (Not available for remote commands)
 
 **--creds**
 
@@ -92,17 +92,11 @@ Suppress output information when pulling images
 If a container exists of the default or given name, as needed it will be stopped, deleted and a new container will be
 created from this image.
 
-**--signature-policy="PATHNAME"**
-
-Pathname of a signature policy file to use.  It is not recommended that this
-option be used, as the default behavior of using the system-wide default policy
-(frequently */etc/containers/policy.json*) is most often preferred
-
 **--tls-verify**
 
 Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true,
 then TLS verification will be used. If set to false, then TLS verification will not be used. If not specified,
-TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf
+TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf (Not available for remote commands)
 
 ## Examples ##
 
diff --git a/docs/podman-create.1.md b/docs/podman-create.1.md
index cf36106e8..cbd6d9a99 100644
--- a/docs/podman-create.1.md
+++ b/docs/podman-create.1.md
@@ -40,6 +40,13 @@ error. It can even pretend to be a TTY (this is what most commandline
 executables expect) and pass along signals. The **-a** option can be set for
 each of stdin, stdout, and stderr.
 
+**--authfile**
+
+Path of the authentication file. Default is ${XDG_\RUNTIME\_DIR}/containers/auth.json
+
+Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE
+environment variable. `export REGISTRY_AUTH_FILE=path` (Not available for remote commands)
+
 **--blkio-weight**=*0*
 
 Block IO weight (relative weight) accepts a weight value between 10 and 1000.
@@ -720,11 +727,13 @@ The followings examples are all valid:
 Without this argument the command will be run as root in the container.
 
 **--userns**=host
+**--userns**=keep-id
 **--userns**=ns:my_namespace
 
-Set the user namespace mode for the container. The use of userns is disabled by default.
+Set the user namespace mode for the container.  It defaults to the **PODMAN_USERNS** environment variable.  An empty value means user namespaces are disabled.
 
 - `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.
+- `keep-id`: creates a user namespace where the current rootless user's UID:GID are mapped to the same values in the container. This option is ignored for containers created by the root user.
 - `ns`: run the container in the given existing user namespace.
 
 This option is incompatible with --gidmap, --uidmap, --subuid and --subgid
diff --git a/docs/podman-load.1.md b/docs/podman-load.1.md
index d156a7682..a3443a229 100644
--- a/docs/podman-load.1.md
+++ b/docs/podman-load.1.md
@@ -32,12 +32,6 @@ The remote client requires the use of this option.
 
 Suppress the progress output
 
-**--signature-policy="PATHNAME"**
-
-Pathname of a signature policy file to use.  It is not recommended that this
-option be used, as the default behavior of using the system-wide default policy
-(frequently */etc/containers/policy.json*) is most often preferred
-
 **--help**, **-h**
 
 Print usage statement
@@ -49,7 +43,7 @@ $ podman load --quiet -i fedora.tar
 ```
 
 ```
-$ podman load -q --signature-policy /etc/containers/policy.json -i fedora.tar
+$ podman load -q -i fedora.tar
 ```
 
 ```
diff --git a/docs/podman-login.1.md b/docs/podman-login.1.md
index a3fcd1eea..f96803c58 100644
--- a/docs/podman-login.1.md
+++ b/docs/podman-login.1.md
@@ -35,7 +35,7 @@ Username for registry
 
 **--authfile**
 
-Path of the authentication file. Default is ${XDG_\RUNTIME\_DIR}/containers/auth.json
+Path of the authentication file. Default is ${XDG_\RUNTIME\_DIR}/containers/auth.json (Not available for remote commands)
 
 Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE
 environment variable. `export REGISTRY_AUTH_FILE=path`
@@ -47,13 +47,13 @@ Return the logged-in user for the registry.  Return error if no login is found.
 **--cert-dir** *path*
 
 Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry.
-Default certificates directory is _/etc/containers/certs.d_.
+Default certificates directory is _/etc/containers/certs.d_. (Not available for remote commands)
 
 **--tls-verify**
 
 Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true,
 then TLS verification will be used. If set to false, then TLS verification will not be used. If not specified,
-TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf.
+TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf. (Not available for remote commands)
 
 **--help**, **-h**
 
diff --git a/docs/podman-logout.1.md b/docs/podman-logout.1.md
index b848fcdee..b30328d5b 100644
--- a/docs/podman-logout.1.md
+++ b/docs/podman-logout.1.md
@@ -22,7 +22,7 @@ All the cached credentials can be removed by setting the **all** flag.
 
 **--authfile**
 
-Path of the authentication file. Default is ${XDG_\RUNTIME\_DIR}/containers/auth.json
+Path of the authentication file. Default is ${XDG_\RUNTIME\_DIR}/containers/auth.json (Not available for remote commands)
 
 Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE
 environment variable. `export REGISTRY_AUTH_FILE=path`
diff --git a/docs/podman-play-kube.1.md b/docs/podman-play-kube.1.md
index a38abf35a..a3a6abbe7 100644
--- a/docs/podman-play-kube.1.md
+++ b/docs/podman-play-kube.1.md
@@ -11,7 +11,6 @@ podman-play-kube - Create pods and containers based on Kubernetes YAML
 [**--cert-dir**]
 [**--creds**]
 [***-q** | **--quiet**]
-[**--signature-policy**]
 [**--tls-verify**]
 kubernetes_input.yml
 
@@ -29,7 +28,7 @@ Note: HostPath volume types created by play kube will be given an SELinux privat
 **--authfile**
 
 Path of the authentication file. Default is ${XDG_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`.
-If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`.
+If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. (Not available for remote commands)
 
 Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE
 environment variable. `export REGISTRY_AUTH_FILE=path`
@@ -37,7 +36,7 @@ environment variable. `export REGISTRY_AUTH_FILE=path`
 **--cert-dir** *path*
 
 Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry.
-Default certificates directory is _/etc/containers/certs.d_.
+Default certificates directory is _/etc/containers/certs.d_. (Not available for remote commands)
 
 **--creds**
 
@@ -49,17 +48,11 @@ value can be entered.  The password is entered without echo.
 
 Suppress output information when pulling images
 
-**--signature-policy="PATHNAME"**
-
-Pathname of a signature policy file to use.  It is not recommended that this
-option be used, as the default behavior of using the system-wide default policy
-(frequently */etc/containers/policy.json*) is most often preferred.
-
 **--tls-verify**
 
 Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true,
 then TLS verification will be used. If set to false, then TLS verification will not be used. If not specified,
-TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf.
+TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf. (Not available for remote commands)
 
 **--help**, **-h**
 
diff --git a/docs/podman-pull.1.md b/docs/podman-pull.1.md
index ab01bb40d..f5b6539e9 100644
--- a/docs/podman-pull.1.md
+++ b/docs/podman-pull.1.md
@@ -54,7 +54,7 @@ Note: When using the all-tags flag, Podman will not iterate over the search regi
 **--authfile**
 
 Path of the authentication file. Default is ${XDG_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`.
-If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`.
+If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. (Not available for remote commands)
 
 Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE
 environment variable. `export REGISTRY_AUTH_FILE=path`
@@ -62,7 +62,7 @@ environment variable. `export REGISTRY_AUTH_FILE=path`
 **--cert-dir** *path*
 
 Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry.
-Default certificates directory is _/etc/containers/certs.d_.
+Default certificates directory is _/etc/containers/certs.d_. (Not available for remote commands)
 
 **--creds**
 
@@ -74,17 +74,11 @@ value can be entered.  The password is entered without echo.
 
 Suppress output information when pulling images
 
-**--signature-policy="PATHNAME"**
-
-Pathname of a signature policy file to use.  It is not recommended that this
-option be used, as the default behavior of using the system-wide default policy
-(frequently */etc/containers/policy.json*) is most often preferred
-
 **--tls-verify**
 
 Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true,
 then TLS verification will be used. If set to false, then TLS verification will not be used. If not specified,
-TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf.
+TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf. (Not available for remote commands)
 
 **--help**, **-h**
 
@@ -93,7 +87,7 @@ Print usage statement
 ## EXAMPLES
 
 ```
-$ podman pull --signature-policy /etc/containers/policy.json alpine:latest
+$ podman pull alpine:latest
 Trying to pull registry.access.redhat.com/alpine:latest... Failed
 Trying to pull registry.fedoraproject.org/alpine:latest... Failed
 Trying to pull docker.io/library/alpine:latest...Getting image source signatures
diff --git a/docs/podman-push.1.md b/docs/podman-push.1.md
index 73fdd625e..ceb42fa28 100644
--- a/docs/podman-push.1.md
+++ b/docs/podman-push.1.md
@@ -47,7 +47,7 @@ Image stored in local container/storage
 **--authfile**
 
 Path of the authentication file. Default is ${XDG_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`.
-If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`.
+If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. (Not available for remote commands)
 
 Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE
 environment variable. `export REGISTRY_AUTH_FILE=path`
@@ -61,7 +61,7 @@ value can be entered.  The password is entered without echo.
 **--cert-dir** *path*
 
 Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry.
-Default certificates directory is _/etc/containers/certs.d_.
+Default certificates directory is _/etc/containers/certs.d_. (Not available for remote commands) (Not available for remote commands)
 
 **--compress**
 
@@ -81,12 +81,6 @@ When writing the output image, suppress progress output
 
 Discard any pre-existing signatures in the image
 
-**--signature-policy="PATHNAME"**
-
-Pathname of a signature policy file to use.  It is not recommended that this
-option be used, as the default behavior of using the system-wide default policy
-(frequently */etc/containers/policy.json*) is most often preferred
-
 **--sign-by="KEY"**
 
 Add a signature at the destination using the specified key
@@ -95,7 +89,7 @@ Add a signature at the destination using the specified key
 
 Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true,
 then TLS verification will be used. If set to false, then TLS verification will not be used. If not specified,
-TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf.
+TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf. (Not available for remote commands)
 
 ## EXAMPLE
 
diff --git a/docs/podman-run.1.md b/docs/podman-run.1.md
index 1840e0f0b..78e8a5d6e 100644
--- a/docs/podman-run.1.md
+++ b/docs/podman-run.1.md
@@ -54,6 +54,13 @@ error. It can even pretend to be a TTY (this is what most commandline
 executables expect) and pass along signals. The **-a** option can be set for
 each of stdin, stdout, and stderr.
 
+**--authfile**
+
+Path of the authentication file. Default is ${XDG_\RUNTIME\_DIR}/containers/auth.json (Not available for remote commands)
+
+Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE
+environment variable. `export REGISTRY_AUTH_FILE=path`
+
 **--blkio-weight**=*0*
 
 Block IO weight (relative weight) accepts a weight value between 10 and 1000.
@@ -291,16 +298,16 @@ The initialization time needed for a container to bootstrap. The value can be ex
 The maximum time allowed to complete the healthcheck before an interval is considered failed.  Like start-period, the
 value can be expressed in a time format such as `1m22s`.  The default value is `30s`.
 
+**--help**
+
+Print usage statement
+
 **--hostname**=""
 
 Container host name
 
 Sets the container host name that is available inside the container.
 
-**--help**
-
-Print usage statement
-
 **--http-proxy**=*true*|*false*
 
 By default proxy environment variables are passed into the container if set
@@ -756,11 +763,13 @@ The followings examples are all valid:
 Without this argument the command will be run as root in the container.
 
 **--userns**=host
+**--userns**=keep-id
 **--userns**=ns:my_namespace
 
-Set the user namespace mode for the container. The use of userns is disabled by default.
+Set the user namespace mode for the container.  It defaults to the **PODMAN_USERNS** environment variable.  An empty value means user namespaces are disabled.
 
 - `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.
+- `keep-id`: creates a user namespace where the current rootless user's UID:GID are mapped to the same values in the container. This option is ignored for containers created by the root user.
 - `ns`: run the container in the given existing user namespace.
 
 This option is incompatible with --gidmap, --uidmap, --subuid and --subgid
@@ -769,25 +778,11 @@ This option is incompatible with --gidmap, --uidmap, --subuid and --subgid
 
 Set the UTS mode for the container
 
-`host`: use the host's UTS namespace inside the container.
-`ns`: specify the user namespace to use.
+- `host`: use the host's UTS namespace inside the container.
+- `ns`: specify the user namespace to use.
 
 **NOTE**: the host mode gives the container access to changing the host's hostname and is therefore considered insecure.
 
-**--userns**=""
-
-Set the user namespace mode for the container. The use of userns is disabled by default.
-
-    **host**: use the host user namespace and enable all privileged options (e.g., `pid=host` or `--privileged`).
-    **ns**: specify the user namespace to use.
-
-**--uts**=*host*
-
-Set the UTS mode for the container
-    **host**: use the host's UTS namespace inside the container.
-    **ns**: specify the user namespace to use.
-    Note: the host mode gives the container access to changing the host's hostname and is therefore considered insecure.
-
 **--volume**, **-v**[=*[HOST-DIR:CONTAINER-DIR[:OPTIONS]]*]
 
 Create a bind mount. If you specify, ` -v /HOST-DIR:/CONTAINER-DIR`, podman
diff --git a/docs/podman-search.1.md b/docs/podman-search.1.md
index 312cdae59..8d315086e 100644
--- a/docs/podman-search.1.md
+++ b/docs/podman-search.1.md
@@ -27,7 +27,7 @@ Note, searching without a search term will only work for registries that impleme
 
 **--authfile**
 
-Path of the authentication file. Default is ${XDG_\RUNTIME\_DIR}/containers/auth.json
+Path of the authentication file. Default is ${XDG_\RUNTIME\_DIR}/containers/auth.json (Not available for remote commands)
 
 Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE
 environment variable. `export REGISTRY_AUTH_FILE=path`
@@ -74,7 +74,7 @@ Do not truncate the output
 Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true,
 then TLS verification will be used. If set to false, then TLS verification will not be used if needed. If not specified,
 default registries will be searched through (in /etc/containers/registries.conf), and TLS will be skipped if a default
-registry is listed in the insecure registries.
+registry is listed in the insecure registries. (Not available for remote commands)
 
 **--help**, **-h**
 
diff --git a/docs/varlink/apidoc.go b/docs/varlink/apidoc.go
index 7f1d60bc8..884ce54fe 100644
--- a/docs/varlink/apidoc.go
+++ b/docs/varlink/apidoc.go
@@ -44,6 +44,8 @@ func typeToString(input *idl.Type) string {
 		return "map[string]"
 	case idl.TypeInt:
 		return "int"
+	case idl.TypeMaybe:
+		return fmt.Sprintf("?%s", typeToString(input.ElementType))
 	}
 	return ""
 }