9 files changed, 170 insertions, 55 deletions
diff --git a/docs/source/markdown/podman-build.1.md b/docs/source/markdown/podman-build.1.md
index 71b92bcb3..bf710022e 100644
--- a/docs/source/markdown/podman-build.1.md
+++ b/docs/source/markdown/podman-build.1.md
@@ -576,27 +576,14 @@ While `podman build` is happy to use base images and build images for any
 platform that exists, `RUN` instructions will not be able to succeed without
 the help of emulation provided by packages like `qemu-user-static`.
 
-#### **--pull**
+#### **--pull**=**always**|**missing**|**never**|**newer**
 
-When the option is enabled or set explicitly to `true` (with *--pull=true*)
-pull the image from the first registry it is found in as listed in registries.conf.
-Raise an error if the image could not be pulled, even if the image is present locally.
+Pull image policy. The default is **always**.
 
-If the option is disabled (with *--pull=false*), pull the image from the
-registry only if the image is not present locally. Raise an error if the image is not
-in the registries and not present locally.
-
-If the pull option is set to `always` (with *--pull=always*),
-pull the image from the first registry it is found in as listed in registries.conf.
-Raise an error if not found in the registries, even if the image is present locally.
-
-If the pull option is set to `missing` (with *--pull=missing*),
-Pull the image only if it is not present in the local storage.  Raise an error if it
-could neither be found in the local storage or on a registry.
-
-If the pull option is set to `never` (with *--pull=never*),
-Do not pull the image from the registry, use only the local version. Raise an error
-if the image is not present locally.
+- **always**, **true**: Always pull the image and throw an error if the pull fails.
+- **missing**: Pull the image only if it could not be found in the local containers storage.  Throw an error if no image could be found and the pull fails.
+- **never**, **false**: Never pull the image but use the one from the local containers storage.  Throw an error if no image could be found.
+- **newer**: Pull if the image on the registry is newer than the one in the local containers storage.  An image is considered to be newer when the digests are different.  Comparing the time stamps is prone to errors.  Pull errors are suppressed if a local image was found.
 
 #### **--quiet**, **-q**
 
diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md
index 403327d82..09c7d99c1 100644
--- a/docs/source/markdown/podman-create.1.md
+++ b/docs/source/markdown/podman-create.1.md
@@ -368,9 +368,10 @@ on the host system.
 
 #### **--gidmap**=*container_gid:host_gid:amount*
 
-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. `--gidmap=0:30000:2000`
+Run the container in a new user namespace using the supplied GID mapping. This
+option conflicts with the **--userns** and **--subgidname** options. This
+option provides a way to map host GIDs to container GIDs in the same way as
+__--uidmap__ maps host UIDs to container UIDs. For details see __--uidmap__.
 
 Note: the **--gidmap** flag cannot be called in conjunction with the **--pod** flag as a gidmap cannot be set on the container level when in a pod.
 
@@ -866,14 +867,14 @@ port to a random port on the host within an *ephemeral port range* defined by
 `/proc/sys/net/ipv4/ip_local_port_range`. To find the mapping between the host
 ports and the exposed ports, use `podman port`.
 
-#### **--pull**=*missing*
+#### **--pull**=**always**|**missing**|**never**|**newer**
 
-Pull image before creating ("always"|"missing"|"never") (default "missing").
-       'missing': default value, attempt to pull the latest image from the registries listed in registries.conf if a local image does not exist.Raise an error if the image is not in any listed registry and is not present locally.
-       'always': Pull the image from the first registry it is found in as listed in  registries.conf. Raise an error if not found in the registries, even if the image is present locally.
-       'never': do not pull the image from the registry, use only the local version. Raise an error if the image is not present locally.
+Pull image policy. The default is **missing**.
 
-Defaults to *missing*.
+- **always**: Always pull the image and throw an error if the pull fails.
+- **missing**: Pull the image only if it could not be found in the local containers storage.  Throw an error if no image could be found and the pull fails.
+- **never**: Never pull the image but use the one from the local containers storage.  Throw an error if no image could be found.
+- **newer**: Pull if the image on the registry is newer than the one in the local containers storage.  An image is considered to be newer when the digests are different.  Comparing the time stamps is prone to errors.  Pull errors are suppressed if a local image was found.
 
 #### **--quiet**, **-q**
 
@@ -1120,7 +1121,7 @@ Remote connections use local containers.conf for defaults
 
 #### **--uidmap**=*container_uid*:*from_uid*:*amount*
 
-Run the container in a new user namespace using the supplied mapping. This
+Run the container in a new user namespace using the supplied UID mapping. This
 option conflicts with the **--userns** and **--subuidname** options. This
 option provides a way to map host UIDs to container UIDs. It can be passed
 several times to map different ranges.
diff --git a/docs/source/markdown/podman-info.1.md b/docs/source/markdown/podman-info.1.md
index fc2d0fa60..28e4f3291 100644
--- a/docs/source/markdown/podman-info.1.md
+++ b/docs/source/markdown/podman-info.1.md
@@ -24,9 +24,10 @@ Show additional information
 Change output format to "json" or a Go template.
 
 
-## EXAMPLE
+## EXAMPLES
+
+Run `podman info` for a YAML formatted response:
 
-Run podman info with plain text response:
 ```
 $ podman info
 host:
@@ -149,7 +150,9 @@ version:
   OsArch: linux/amd64
   Version: 4.0.0
 ```
-Run podman info with JSON formatted response:
+
+Run `podman info --format json` for a JSON formatted response:
+
 ```
 $ podman info --format json
 {
@@ -289,11 +292,68 @@ $ podman info --format json
   }
 }
 ```
-Run podman info and only get the registries information.
+
+#### Extracting the list of container registries with a Go template
+
+If shell completion is enabled, type `podman info --format={{.` and then press `[TAB]` twice.
+
+```
+$ podman info --format={{.
+{{.Host.         {{.Plugins.      {{.Registries}}  {{.Store.        {{.Version.
+```
+
+Press `R` `[TAB]` `[ENTER]` to print the registries information.
+
+```
+$ podman info -f {{.Registries}}
+map[search:[registry.fedoraproject.org registry.access.redhat.com docker.io quay.io]]
+$
+```
+
+The output still contains a map and an array. The map value can be extracted with
+
+```
+$ podman info -f '{{index .Registries "search"}}'
+[registry.fedoraproject.org registry.access.redhat.com docker.io quay.io]
+```
+
+The array can be printed as one entry per line
+
+```
+$ podman info -f '{{range index .Registries "search"}}{{.}}\n{{end}}'
+registry.fedoraproject.org
+registry.access.redhat.com
+docker.io
+quay.io
+
 ```
-$ podman info --format={{".Registries"}}
-map[registries:[docker.io quay.io registry.fedoraproject.org registry.access.redhat.com]]
+
+#### Extracting the list of container registries from JSON with jq
+
+The command-line JSON processor [__jq__](https://stedolan.github.io/jq/) can be used to extract the list
+of container registries.
+
 ```
+$ podman info -f json | jq '.registries["search"]'
+[
+  "registry.fedoraproject.org",
+  "registry.access.redhat.com",
+  "docker.io",
+  "quay.io"
+]
+```
+
+The array can be printed as one entry per line
+
+```
+$ podman info -f json | jq -r '.registries["search"] | .[]'
+registry.fedoraproject.org
+registry.access.redhat.com
+docker.io
+quay.io
+```
+
+Note, the Go template struct fields start with upper case. When running `podman info` or `podman info --format=json`, the same names start with lower case.
 
 ## SEE ALSO
 **[podman(1)](podman.1.md)**, **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)**, **[containers-storage.conf(5)](https://github.com/containers/storage/blob/main/docs/containers-storage.conf.5.md)**
diff --git a/docs/source/markdown/podman-machine-info.1.md b/docs/source/markdown/podman-machine-info.1.md
new file mode 100644
index 000000000..33c207d32
--- /dev/null
+++ b/docs/source/markdown/podman-machine-info.1.md
@@ -0,0 +1,36 @@
+% podman-machine-info(1)
+
+## NAME
+podman\-machine\-info - Display machine host info
+
+## SYNOPSIS
+**podman machine info**
+
+## DESCRIPTION
+
+Display information pertaining to the machine host.
+Rootless only, as all `podman machine` commands can be only be used with rootless Podman.
+
+## OPTIONS
+
+#### **--format**=*format*, **-f**
+
+Change output format to "json" or a Go template.
+
+#### **--help**
+
+Print usage statement.
+
+## EXAMPLES
+
+```
+$ podman machine info
+$ podman machine info --format json
+$ podman machine info --format {{.Host.Arch}}
+```
+
+## SEE ALSO
+**[podman(1)](podman.1.md)**, **[podman-machine(1)](podman-machine.1.md)**
+
+## HISTORY
+June 2022, Originally compiled by Ashley Cui <acui@redhat.com>
diff --git a/docs/source/markdown/podman-machine-init.1.md b/docs/source/markdown/podman-machine-init.1.md
index 2adb15e6a..21c98b2c7 100644
--- a/docs/source/markdown/podman-machine-init.1.md
+++ b/docs/source/markdown/podman-machine-init.1.md
@@ -76,15 +76,33 @@ Set the timezone for the machine and containers.  Valid values are `local` or
 a `timezone` such as `America/Chicago`.  A value of `local`, which is the default,
 means to use the timezone of the machine host.
 
-#### **--volume**, **-v**=*source:target*
+#### **--volume**, **-v**=*source:target[:options]*
 
 Mounts a volume from source to target.
 
 Create a mount. If /host-dir:/machine-dir is specified as the `*source:target*`,
 Podman mounts _host-dir_ in the host to _machine-dir_ in the Podman machine.
 
-The root filesystem is mounted read-only in the default operating system,
-so mounts must be created under the /mnt directory.
+Additional options may be specified as a comma-separated string. Recognized
+options are:
+* **ro**: mount volume read-only
+* **rw**: mount volume read/write (default)
+* **security_model=[model]**: specify 9p security model (see below)
+
+The 9p security model [determines] https://wiki.qemu.org/Documentation/9psetup#Starting_the_Guest_directly
+if and how the 9p filesystem translates some filesystem operations before
+actual storage on the host. The
+default value of *mapped-xattr* specifies that 9p store symlinks and some file
+attributes as extended attributes on the host. This is suitable when the host
+and the guest do not need to interoperate on the shared filesystem, but has
+caveats for actual shared access; notably, symlinks on the host are not usable
+on the guest and vice versa. If interoperability is required, then choose
+*none* instead, but keep in mind that the guest will not be able to do things
+that the user running the virtual machine cannot do, e.g. create files owned by
+another user. Using *none* is almost certainly the best choice for read-only
+volumes.
+
+Example: `-v "$HOME/git:$HOME/git:ro,security_model=none"`
 
 Default volume mounts are defined in *containers.conf*.  Unless changed, the default values
 is `$HOME:$HOME`.
diff --git a/docs/source/markdown/podman-machine.1.md b/docs/source/markdown/podman-machine.1.md
index c55226e02..6197b8d4e 100644
--- a/docs/source/markdown/podman-machine.1.md
+++ b/docs/source/markdown/podman-machine.1.md
@@ -20,6 +20,7 @@ All `podman machine` commands are rootless only.
 
 | Command | Man Page                                             | Description                       |
 |---------|------------------------------------------------------|-----------------------------------|
+| info    | [podman-machine-info(1)](podman-machine-info.1.md)   | Display machine host info         |
 | init    | [podman-machine-init(1)](podman-machine-init.1.md)   | Initialize a new virtual machine  |
 | inspect | [podman-machine-inspect(1)](podman-machine-inspect.1.md)  | Inspect one or more virtual machines |
 | list    | [podman-machine-list(1)](podman-machine-list.1.md)   | List virtual machines             |
@@ -30,7 +31,7 @@ All `podman machine` commands are rootless only.
 | stop    | [podman-machine-stop(1)](podman-machine-stop.1.md)   | Stop a virtual machine            |
 
 ## SEE ALSO
-**[podman(1)](podman.1.md)**, **[podman-machine-init(1)](podman-machine-init.1.md)**, **[podman-machine-list(1)](podman-machine-list.1.md)**, **[podman-machine-rm(1)](podman-machine-rm.1.md)**, **[podman-machine-ssh(1)](podman-machine-ssh.1.md)**, **[podman-machine-start(1)](podman-machine-start.1.md)**, **[podman-machine-stop(1)](podman-machine-stop.1.md)**, **[podman-machine-inspect(1)](podman-machine-inspect.1.md)**
+**[podman(1)](podman.1.md)**, **[podman-machine-info(1)](podman-machine-info.1.md)**, **[podman-machine-init(1)](podman-machine-init.1.md)**, **[podman-machine-list(1)](podman-machine-list.1.md)**, **[podman-machine-rm(1)](podman-machine-rm.1.md)**, **[podman-machine-ssh(1)](podman-machine-ssh.1.md)**, **[podman-machine-start(1)](podman-machine-start.1.md)**, **[podman-machine-stop(1)](podman-machine-stop.1.md)**, **[podman-machine-inspect(1)](podman-machine-inspect.1.md)**
 
 ## HISTORY
 March 2021, Originally compiled by Ashley Cui <acui@redhat.com>
diff --git a/docs/source/markdown/podman-pod-clone.1.md b/docs/source/markdown/podman-pod-clone.1.md
index a18f7dbfe..d90d1efb9 100644
--- a/docs/source/markdown/podman-pod-clone.1.md
+++ b/docs/source/markdown/podman-pod-clone.1.md
@@ -211,6 +211,15 @@ Valid _mode_ values are:
 
   - *nomap*: creates a user namespace where the current rootless user's UID:GID are not mapped into the container. This option is ignored for containers created by the root user.
 
+#### **--uts**=*mode*
+
+Set the UTS namespace mode for the pod. The following values are supported:
+
+- **host**: use the host's UTS namespace inside the pod.
+- **private**: create a new namespace for the pod (default).
+- **ns:[path]**: run the pod in the given existing UTS namespace.
+
+
 #### **--volume**, **-v**[=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]*]
 
 Create a bind mount. If ` -v /HOST-DIR:/CONTAINER-DIR` is specified, Podman
diff --git a/docs/source/markdown/podman-pod-create.1.md b/docs/source/markdown/podman-pod-create.1.md
index 75d2bb611..53d1e3327 100644
--- a/docs/source/markdown/podman-pod-create.1.md
+++ b/docs/source/markdown/podman-pod-create.1.md
@@ -381,6 +381,14 @@ Valid _mode_ values are:
 
   - *nomap*: creates a user namespace where the current rootless user's UID:GID are not mapped into the container. This option is not allowed for containers created by the root user.
 
+#### **--uts**=*mode*
+
+Set the UTS namespace mode for the pod. The following values are supported:
+
+- **host**: use the host's UTS namespace inside the pod.
+- **private**: create a new namespace for the pod (default).
+- **ns:[path]**: run the pod in the given existing UTS namespace.
+
 #### **--volume**, **-v**[=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]*]
 
 Create a bind mount. If you specify, ` -v /HOST-DIR:/CONTAINER-DIR`, Podman
diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md
index 8f71c3706..e628a806a 100644
--- a/docs/source/markdown/podman-run.1.md
+++ b/docs/source/markdown/podman-run.1.md
@@ -404,16 +404,10 @@ on the host system.
 
 #### **--gidmap**=*container_gid*:*host_gid*:*amount*
 
-Run the container in a new user namespace using 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 **subuid**(5).
-The example maps gids **0-1999** in the container to the gids **30000-31999** on the host: **--gidmap=0:30000:2000**.
-
-**Important note:** The new user namespace mapping based on **--gidmap** is based on the initial mapping made in the  _/etc/subgid_  file.
-Assuming there is a  _/etc/subgid_  mapping **groupname:100000:65536**, then **groupname** is initially mapped to a namespace starting with
-gid **100000** for **65536** ids. From here the **--gidmap** mapping to the new namespace starts from **0** again, but is based on the initial mapping.
-Meaning **groupname** is initially mapped to gid **100000** which is referenced as **0** in the following **--gidmap** mapping. In terms of the example
-above: The group **groupname** is mapped to group **100000** of the initial namespace then the
-**30000**st id of this namespace (which is gid 130000 in this namespace) is mapped to container namespace group id **0**. (groupname -> 100000 / 30000 -> 0)
+Run the container in a new user namespace using the supplied GID mapping. This
+option conflicts with the **--userns** and **--subgidname** options. This
+option provides a way to map host GIDs to container GIDs in the same way as
+__--uidmap__ maps host UIDs to container UIDs. For details see __--uidmap__.
 
 Note: the **--gidmap** flag cannot be called in conjunction with the **--pod** flag as a gidmap cannot be set on the container level when in a pod.
 
@@ -905,13 +899,14 @@ When using this option, Podman will bind any exposed port to a random port on th
 within an ephemeral port range defined by */proc/sys/net/ipv4/ip_local_port_range*.
 To find the mapping between the host ports and the exposed ports, use **podman port**.
 
-#### **--pull**=**always**|**missing**|**never**
+#### **--pull**=**always**|**missing**|**never**|**newer**
 
-Pull image before running. The default is **missing**.
+Pull image policy. The default is **missing**.
 
-- **missing**: attempt to pull the latest image from the registries listed in registries.conf if a local image does not exist.Raise an error if the image is not in any listed registry and is not present locally.
-- **always**: Pull the image from the first registry it is found in as listed in registries.conf. Raise an error if not found in the registries, even if the image is present locally.
-- **never**: do not pull the image from the registry, use only the local version. Raise an error if the image is not present locally.
+- **always**: Always pull the image and throw an error if the pull fails.
+- **missing**: Pull the image only if it could not be found in the local containers storage.  Throw an error if no image could be found and the pull fails.
+- **never**: Never pull the image but use the one from the local containers storage.  Throw an error if no image could be found.
+- **newer**: Pull if the image on the registry is newer than the one in the local containers storage.  An image is considered to be newer when the digests are different.  Comparing the time stamps is prone to errors.  Pull errors are suppressed if a local image was found.
 
 #### **--quiet**, **-q**
 
@@ -1187,7 +1182,7 @@ Remote connections use local containers.conf for defaults
 
 #### **--uidmap**=*container_uid*:*from_uid*:*amount*
 
-Run the container in a new user namespace using the supplied mapping. This
+Run the container in a new user namespace using the supplied UID mapping. This
 option conflicts with the **--userns** and **--subuidname** options. This
 option provides a way to map host UIDs to container UIDs. It can be passed
 several times to map different ranges.