Merge pull request #10676 from Procyhon/13062021_manpage

[CI:DOCS] UPDATE manpages with MANPAGE_SYNTAX

9 files changed, 158 insertions, 129 deletions

diff --git a/docs/source/markdown/podman-attach.1.md b/docs/source/markdown/podman-attach.1.md
index 0a5948b4e..b86b981d2 100644
--- a/docs/source/markdown/podman-attach.1.md
+++ b/docs/source/markdown/podman-attach.1.md
@@ -15,11 +15,14 @@ The *container* can detached from (and leave it running) using a configurable ke
 ## OPTIONS
 #### **--detach-keys**=**sequence**
 
-Specify the key **sequence** for detaching a *container*. Format is a single character `[a-Z]` or one or more `ctrl-<value>` characters where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. Specifying "" will disable this feature. The default is `ctrl-p,ctrl-q`.
+Specify the key **sequence** for detaching a *container*. Format is a single character `[a-Z]` or one or more `ctrl-<value>` characters where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. Specifying "" will disable this feature.\
+The default is `ctrl-p,ctrl-q`.
 
 #### **--latest**, **-l**
-Instead of providing the *container name* or *ID*, use the last created *container*. If other methods are used than Podman to run containers such as `CRI-O`, the last started *container* could be from either of those methods. The default is **false**.\
-*IMPORTANT: This OPTION is not available with the remote Podman client.*
+
+Instead of providing the *container ID* or *name*, use the last created *container*. If other methods than Podman are used to run *containers* such as `CRI-O`, the last started *container* could be from either of those methods.\
+The default is **false**.\
+*IMPORTANT: This OPTION is not available with the remote Podman client. This OPTION does not need a container name or ID as input argument.*
 
 #### **--no-stdin**
 
@@ -27,10 +30,10 @@ Do not attach STDIN. The default is **false**.
 
 #### **--sig-proxy**
 
-Proxy received signals to the process (non-TTY mode only). SIGCHLD, SIGSTOP, and SIGKILL are not proxied. The default is **true**.
+Proxy received signals to the process (non-TTY mode only). SIGCHLD, SIGSTOP, and SIGKILL are not proxied.\
+The default is **true**.
 
 ## EXAMPLES
-
 Attach to a container called "foobar".
 ```
 $ podman attach foobar
diff --git a/docs/source/markdown/podman-auto-update.1.md b/docs/source/markdown/podman-auto-update.1.md
index 52a9a3fec..24b910470 100644
--- a/docs/source/markdown/podman-auto-update.1.md
+++ b/docs/source/markdown/podman-auto-update.1.md
@@ -9,8 +9,7 @@ podman\-auto-update - Auto update containers according to their auto-update poli
 ## DESCRIPTION
 **podman auto-update** looks up containers with a specified `io.containers.autoupdate` label (i.e., the auto-update policy).
 
-If the label is present and set to `registry`, Podman reaches out to the corresponding registry to check if the image has been updated.
-The label `image` is an alternative to `registry` maintained for backwards compatibility.
+If the label is present and set to `registry`, Podman reaches out to the corresponding registry to check if the image has been updated. The label `image` is an alternative to `registry` maintained for backwards compatibility.
 An image is considered updated if the digest in the local storage is different than the one of the remote image.
 If an image must be updated, Podman pulls it down and restarts the systemd unit executing the container.
 
@@ -35,7 +34,6 @@ Systemd units that start and stop a container cannot run a new image.
 Podman ships with a `podman-auto-update.service` systemd unit. This unit is triggered daily at midnight by the `podman-auto-update.timer` systemd timer.  The timer can be altered for custom time-based updates if desired.  The unit can further be invoked by other systemd units (e.g., via the dependency tree) or manually via **systemctl start podman-auto-update.service**.
 
 ## OPTIONS
-
 #### **--authfile**=*path*
 
 Path of the authentication file. Default is `${XDG_RUNTIME_DIR}/containers/auth.json`, which is set using **[podman login](podman-login.1.md)**.
@@ -44,7 +42,6 @@ If the authorization state is not found there, `$HOME/.docker/config.json` is ch
 Note: There is also the option to override the default path of the authentication file by setting the `REGISTRY_AUTH_FILE` environment variable. This can be done with **export REGISTRY_AUTH_FILE=_path_**.
 
 ## EXAMPLES
-
 Autoupdate with registry policy
 
 ```
diff --git a/docs/source/markdown/podman-commit.1.md b/docs/source/markdown/podman-commit.1.md
index bb7d3ce70..87b7e8aea 100644
--- a/docs/source/markdown/podman-commit.1.md
+++ b/docs/source/markdown/podman-commit.1.md
@@ -15,7 +15,6 @@ If `image` does not begin with a registry name component, `localhost` will be ad
 If `image` is not provided, the values for the `REPOSITORY` and `TAG` values of the created image will each be set to `<none>`.
 
 ## OPTIONS
-
 #### **--author**, **-a**=*author*
 
 Set the author for the committed image.
@@ -39,7 +38,8 @@ Can be set multiple times.
 
 #### **--format**, **-f** =**oci** | *docker*
 
-Set the format of the image manifest and metadata.  The currently supported formats are **oci** and *docker*. The default is **oci**.
+Set the format of the image manifest and metadata.  The currently supported formats are **oci** and *docker*.\
+The default is **oci**.
 
 #### **--iidfile**=*ImageIDfile*
 
@@ -47,7 +47,8 @@ Write the image ID to the file.
 
 #### **--include-volumes**
 
-Include in the committed image any volumes added to the container by the **--volume** or **--mount** OPTIONS to the **[podman create](podman-create.1.md)** and **[podman run](podman-run.1.md)** commands. The default is **false**.
+Include in the committed image any volumes added to the container by the **--volume** or **--mount** OPTIONS to the **[podman create](podman-create.1.md)** and **[podman run](podman-run.1.md)** commands.\
+The default is **false**.
 
 #### **--message**, **-m**=*message*
 
@@ -56,14 +57,15 @@ Set commit message for committed image.\
 
 #### **--pause**, **-p**
 
-Pause the container when creating an image. The default is **false**.
+Pause the container when creating an image.\
+The default is **false**.
 
 #### **--quiet**, **-q**
 
-Suppresses output. The default is **false**.
+Suppresses output.\
+The default is **false**.
 
 ## EXAMPLES
-
 Create image from container with entrypoint and label
 ```
 $ podman commit --change CMD=/bin/bash --change ENTRYPOINT=/bin/sh --change "LABEL blue=image" reverent_golick image-committed
diff --git a/docs/source/markdown/podman-completion.1.md b/docs/source/markdown/podman-completion.1.md
index f8589ce68..639332365 100644
--- a/docs/source/markdown/podman-completion.1.md
+++ b/docs/source/markdown/podman-completion.1.md
@@ -20,7 +20,8 @@ Write the generated output to a file.
 
 #### **--no-desc**
 
-Do not provide description in the completions. The default is **false**.
+Do not provide description in the completions.\
+The default is **false**.
 
 ## Installation
 
diff --git a/docs/source/markdown/podman-container-checkpoint.1.md b/docs/source/markdown/podman-container-checkpoint.1.md
index a86389f59..56fd848ac 100644
--- a/docs/source/markdown/podman-container-checkpoint.1.md
+++ b/docs/source/markdown/podman-container-checkpoint.1.md
@@ -12,17 +12,19 @@ podman\-container\-checkpoint - Checkpoints one or more running containers
 ## OPTIONS
 #### **--all**, **-a**
 
-Checkpoint all running *containers*. The default is **false**.
+Checkpoint all running *containers*.\
+The default is **false**.\
+*IMPORTANT: This OPTION does not need a container name or ID as input argument.*
 
 #### **--compress**, **-c**=**zstd** | *none* | *gzip*
 
 Specify the compression algorithm used for the checkpoint archive created
 with the **--export, -e** OPTION. Possible algorithms are **zstd**, *none*
-and *gzip*. The default is **zstd**.
-
+and *gzip*.\
 One possible reason to use *none* is to enable faster creation of checkpoint
 archives. Not compressing the checkpoint archive can result in faster checkpoint
-archive creation.
+archive creation.\
+The default is **zstd**.
 
 #### **--export**, **-e**=*archive*
 
@@ -33,50 +35,55 @@ root file-system, if not explicitly disabled using **--ignore-rootfs**.
 
 #### **--ignore-rootfs**
 
-This only works in combination with **--export, -e**. If a checkpoint is
-exported to a tar.gz file it is possible with the help of **--ignore-rootfs**
-to explicitly disable including changes to the root file-system into
-the checkpoint archive file. The default is **false**.
+If a checkpoint is exported to a tar.gz file it is possible with the help of **--ignore-rootfs** to explicitly disable including changes to the root file-system into the checkpoint archive file.\
+The default is **false**.\
+*IMPORTANT: This OPTION only works in combination with **--export, -e**.*
 
 #### **--ignore-volumes**
 
 This OPTION must be used in combination with the **--export, -e** OPTION.
 When this OPTION is specified, the content of volumes associated with
-the *container* will not be included into the checkpoint tar.gz file. The default is **false**.
+the *container* will not be included into the checkpoint tar.gz file.\
+The default is **false**.
 
 #### **--keep**, **-k**
 
-Keep all temporary log and statistics files created by CRIU during checkpointing. These files are not deleted if checkpointing fails for further debugging. If checkpointing succeeds these files are theoretically not needed, but if these files are needed Podman can keep the files for further analysis. The default is **false**.
+Keep all temporary log and statistics files created by CRIU during checkpointing. These files are not deleted if checkpointing fails for further debugging. If checkpointing succeeds these files are theoretically not needed, but if these files are needed Podman can keep the files for further analysis.\
+The default is **false**.
 
 #### **--latest**, **-l**
 
-Instead of providing the *container ID* or *name*, use the last created *container*. If you use methods other than Podman to run *containers* such as `CRI-O`, the last started *container* could be from either of those methods. The default is **false**.\
-*IMPORTANT: This OPTION is not available with the remote Podman client.*
+Instead of providing the *container ID* or *name*, use the last created *container*. If other methods than Podman are used to run *containers* such as `CRI-O`, the last started *container* could be from either of those methods.\
+The default is **false**.\
+*IMPORTANT: This OPTION is not available with the remote Podman client. This OPTION does not need a container name or ID as input argument.*
 
 #### **--leave-running**, **-R**
 
-Leave the *container* running after checkpointing instead of stopping it. The default is **false**.
+Leave the *container* running after checkpointing instead of stopping it.\
+The default is **false**.
 
 #### **--pre-checkpoint**, **-P**
 
 Dump the *container's* memory information only, leaving the *container* running. Later
-operations will supersede prior dumps. It only works on `runc 1.0-rc3` or `higher`. The default is **false**.
+operations will supersede prior dumps. It only works on `runc 1.0-rc3` or `higher`.\
+The default is **false**.
 
 #### **--tcp-established**
 
 Checkpoint a *container* with established TCP connections. If the checkpoint
 image contains established TCP connections, this OPTION is required during
 restore. Defaults to not checkpointing *containers* with established TCP
-connections. The default is **false**.
+connections.\
+The default is **false**.
 
 #### **--with-previous**
 
-Check out the *container* with previous criu image files in pre-dump. It only works on `runc 1.0-rc3` or `higher`. The default is **false**.\
+Check out the *container* with previous criu image files in pre-dump. It only works on `runc 1.0-rc3` or `higher`.\
+The default is **false**.\
 *IMPORTANT: This OPTION is not available with **--pre-checkpoint***.
 
 
 ## EXAMPLES
-
 Make a checkpoint for the container "mywebserver".
 ```
 # podman container checkpoint mywebserver
diff --git a/docs/source/markdown/podman-container-cleanup.1.md b/docs/source/markdown/podman-container-cleanup.1.md
index f33b68a1c..29e34f1cf 100644
--- a/docs/source/markdown/podman-container-cleanup.1.md
+++ b/docs/source/markdown/podman-container-cleanup.1.md
@@ -8,13 +8,14 @@ podman\-container\-cleanup - Cleanup the container's network and mountpoints
 
 ## DESCRIPTION
 **podman container cleanup** cleans up exited *containers* by removing all mountpoints and network configuration from the host. The *container name* or *ID* can be used. The cleanup command does not remove the *containers*. Running *containers* will not be cleaned up.\
-Sometimes container mount points and network stacks can remain if the podman command was killed or the *container* ran in daemon mode. This command is automatically executed when you run *containers* in daemon mode by the `conmon process` when the *container* exits.
+Sometimes container mount points and network stacks can remain if the podman command was killed or the *container* ran in daemon mode. This command is automatically executed when *containers* are run in daemon mode by the `conmon process` when the *container* exits.
 
 ## OPTIONS
-
 #### **--all**, **-a**
 
-Cleanup all *containers*. The default is **false**.
+Cleanup all *containers*.\
+The default is **false**.\
+*IMPORTANT: This OPTION does not need a container name or ID as input argument.*
 
 #### **--exec**=*session*
 
@@ -24,19 +25,21 @@ Can only be specified if a single *container* is being cleaned up (conflicts wit
 
 #### **--latest**, **-l**
 
-Instead of providing the *container ID* or *name*, use the last created *container*. If you use methods other than Podman to run *containers* such as `CRI-O`, the last started *container* could be from either of those methods. The default is **false**.\
-*IMPORTANT: This OPTION is not available with the remote Podman client.*
+Instead of providing the *container ID* or *name*, use the last created *container*. If other methods than Podman are used to run *containers* such as `CRI-O`, the last started *container* could be from either of those methods.\
+The default is **false**.\
+*IMPORTANT: This OPTION is not available with the remote Podman client. This OPTION does not need a container name or ID as input argument.*
 
 #### **--rm**
 
-After cleanup, remove the *container* entirely. The default is **false**.
+After cleanup, remove the *container* entirely.\
+The default is **false**.
 
 #### **--rmi**
 
-After cleanup, remove the image entirely. The default is **false**.
+After cleanup, remove the image entirely.\
+The default is **false**.
 
 ## EXAMPLES
-
 Cleanup the container "mywebserver".
 ```
 $ podman container cleanup mywebserver
diff --git a/docs/source/markdown/podman-container-exists.1.md b/docs/source/markdown/podman-container-exists.1.md
index e42489d63..d059276d7 100644
--- a/docs/source/markdown/podman-container-exists.1.md
+++ b/docs/source/markdown/podman-container-exists.1.md
@@ -11,12 +11,15 @@ podman\-container\-exists - Check if a container exists in local storage
 of `0` when the container is found.  A `1` will be returned otherwise. An exit code of `125` indicates there was an issue accessing the local storage.
 
 ## OPTIONS
-
 #### **--external**
-Check for external *containers* as well as Podman *containers*. These external *containers* are generally created via other container technology such as `Buildah` or `CRI-O`. The default is **false**.
+
+Check for external *containers* as well as Podman *containers*. These external *containers* are generally created via other container technology such as `Buildah` or `CRI-O`.\
+The default is **false**.
 
 **-h**, **--help**
-Prints usage statement.
+
+Prints usage statement.\
+The default is **false**.
 
 ## EXAMPLES
 
diff --git a/docs/source/markdown/podman-container-prune.1.md b/docs/source/markdown/podman-container-prune.1.md
index b199f9ebb..06014897f 100644
--- a/docs/source/markdown/podman-container-prune.1.md
+++ b/docs/source/markdown/podman-container-prune.1.md
@@ -1,7 +1,7 @@
 % podman-container-prune(1)
 
 ## NAME
-podman-container-prune - Remove all stopped containers from local storage
+podman\-container\-prune - Remove all stopped containers from local storage
 
 ## SYNOPSIS
 **podman container prune** [*options*]
@@ -10,35 +10,37 @@ podman-container-prune - Remove all stopped containers from local storage
 **podman container prune** removes all stopped containers from local storage.
 
 ## OPTIONS
-
 #### **--filter**=*filters*
 
 Provide filter values.
 
-The --filter flag format is of “key=value”. If there is more than one filter, then pass multiple flags (e.g., --filter "foo=bar" --filter "bif=baz")
+The *filters* argument format is of `key=value`. If there is more than one *filter*, then pass multiple OPTIONS: **--filter** *foo=bar* **--filter** *bif=baz*.
 
 Supported filters:
 
-- `until` (_timestamp_) - only remove containers and images created before given timestamp
-- `label` (label=_key_, label=_key=value_, label!=_key_, or label!=_key=value_) - only remove containers and images, with (or without, in case label!=... is used) the specified labels.
+| Filter             | Description                                                                 |
+| :----------------: | --------------------------------------------------------------------------- |
+| *until*            | Only remove containers and images created before given timestamp.           |
+| *label*            | Only remove containers and images, with (or without, in case label!=[...] is used) the specified labels.                  |
 
-The until filter can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. 10m, 1h30m) computed relative to the machine’s time.
+The `until` *filter* can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. 10m, 1h30m) computed relative to the machine’s time.
 
-The label filter accepts two formats. One is the label=... (label=_key_ or label=_key=value_), which removes containers with the specified labels. The other format is the label!=... (label!=_key_ or label!=_key=value_), which removes containers without the specified labels.
+The `label` *filter* accepts two formats. One is the `label`=*key*, `label`=*key*=*value*, which removes containers with the specified labels. The other format is the `label!`=*key*, or `label!`=*key*=*value*, which removes containers without the specified labels.
 
 #### **--force**, **-f**
 
-Do not provide an interactive prompt for container removal.
+Do not provide an interactive prompt for container removal.\
+The default is **false**.
 
 **-h**, **--help**
 
-Print usage statement
+Print usage statement.\
+The default is **false**.
 
 ## EXAMPLES
-
 Remove all stopped containers from local storage
 ```
-$ sudo podman container prune
+$ podman container prune
 WARNING! This will remove all stopped containers.
 Are you sure you want to continue? [y/N] y
 878392adf2e6c5c9bb1fc19b69d37d2e98c8abf9d539c0bce4b15b46bbcce471
@@ -51,7 +53,7 @@ fff1c5b6c3631746055ec40598ce8ecaa4b82aef122f9e3a85b03b55c0d06c23
 
 Remove all stopped containers from local storage without confirmation.
 ```
-$ sudo podman container prune -f
+$ podman container prune -f
 878392adf2e6c5c9bb1fc19b69d37d2e98c8abf9d539c0bce4b15b46bbcce471
 37664467fbe3618bf9479c34393ac29c02696675addf1750f9e346581636cde7
 ed0c6468b8e1cb641b4621d1fe30cb477e1fefc5c0bceb66feaf2f7cb50e5962
@@ -63,15 +65,15 @@ fff1c5b6c3631746055ec40598ce8ecaa4b82aef122f9e3a85b03b55c0d06c23
 
 Remove all stopped containers from local storage created within last 10 minutes
 ```
-$ sudo podman container prune --filter until="10m"
+$ podman container prune --filter until="10m"
 WARNING! This will remove all stopped containers.
 Are you sure you want to continue? [y/N] y
 3d366295e33d8cc612c4d873199bacadd55088d90d17dcafaa9a2d317ad50b4e
 ```
 
 ## SEE ALSO
-podman(1), podman-ps
+**[podman(1)](podman.1.md)**, **[podman-ps](podman-ps.1.md)**
 
 ## HISTORY
-December 2018, Originally compiled by Brent Baude (bbaude at redhat dot com)
-December 2020, converted filter information from docs.docker.com documentation by Dan Walsh (dwalsh at redhat dot com)
+December 2018, Originally compiled by Brent Baude <bbaude@redhat.com>\
+December 2020, converted filter information from docs.docker.com documentation by Dan Walsh <dwalsh@redhat.com>
diff --git a/docs/source/markdown/podman-container-restore.1.md b/docs/source/markdown/podman-container-restore.1.md
index 82bf76d1e..21021b952 100644
--- a/docs/source/markdown/podman-container-restore.1.md
+++ b/docs/source/markdown/podman-container-restore.1.md
@@ -4,120 +4,131 @@
 podman\-container\-restore - Restores one or more containers from a checkpoint
 
 ## SYNOPSIS
-**podman container restore** [*options*] *container* ...
+**podman container restore** [*options*] *container* [*container* ...]
 
 ## DESCRIPTION
-Restores a container from a checkpoint. You may use container IDs or names as input.
+**podman container restore** restores a container from a checkpoint. The *container IDs* or *names* are used as input.
 
 ## OPTIONS
+#### **--all**, **-a**
+
+Restore all checkpointed *containers*.\
+The default is **false**.\
+*IMPORTANT: This OPTION does not need a container name or ID as input argument.*
+
 #### **--keep**, **-k**
 
-Keep all temporary log and statistics files created by CRIU during
+Keep all temporary log and statistics files created by `CRIU` during
 checkpointing as well as restoring. These files are not deleted if restoring
 fails for further debugging. If restoring succeeds these files are
 theoretically not needed, but if these files are needed Podman can keep the
 files for further analysis. This includes the checkpoint directory with all
 files created during checkpointing. The size required by the checkpoint
 directory is roughly the same as the amount of memory required by the
-processes in the checkpointed container.
-
-Without the **-k**, **--keep** option the checkpoint will be consumed and cannot be used
-again.
-
-#### **--all**, **-a**
-
-Restore all checkpointed containers.
+processes in the checkpointed *container*.\
+Without the **--keep**, **-k** option the checkpoint will be consumed and cannot be used again.\
+The default is **false**.
 
 #### **--latest**, **-l**
 
-Instead of providing the container name or ID, restore the last created container. (This option is not available with the remote Podman client)
-
-#### **--tcp-established**
-
-Restore a container with established TCP connections. If the checkpoint image
-contains established TCP connections, this option is required during restore.
-If the checkpoint image does not contain established TCP connections this
-option is ignored. Defaults to not restoring containers with established TCP
-connections.
-
-#### **--import**, **-i**
-
-Import a checkpoint tar.gz file, which was exported by Podman. This can be used
-to import a checkpointed container from another host. Do not specify a *container*
-argument when using this option.
-
-#### **--import-previous**
-
-Import a pre-checkpoint tar.gz file which was exported by Podman. This option
-must be used with **-i** or **--import**. It only works on runc 1.0-rc3 or higher.
-
-#### **--name**, **-n**
-
-This is only available in combination with **--import, -i**. If a container is restored
-from a checkpoint tar.gz file it is possible to rename it with **--name, -n**. This
-way it is possible to restore a container from a checkpoint multiple times with different
-names.
-
-If the **--name, -n** option is used, Podman will not attempt to assign the same IP
-address to the container it was using before checkpointing as each IP address can only
-be used once and the restored container will have another IP address. This also means
-that **--name, -n** cannot be used in combination with **--tcp-established**.
+Instead of providing the *container ID* or *name*, use the last created *container*. If other methods than Podman are used to run *containers* such as `CRI-O`, the last started *container* could be from either of those methods.\
+The default is **false**.\
+*IMPORTANT: This OPTION is not available with the remote Podman client. This OPTION does not need a container name or ID as input argument.*
 
 #### **--ignore-rootfs**
 
-This is only available in combination with **--import, -i**. If a container is restored
-from a checkpoint tar.gz file it is possible that it also contains all root file-system
-changes. With **--ignore-rootfs** it is possible to explicitly disable applying these
-root file-system changes to the restored container.
+If a *container* is restored from a checkpoint tar.gz file it is possible that it also contains all root file-system changes. With **--ignore-rootfs** it is possible to explicitly disable applying these root file-system changes to the restored *container*.\
+The default is **false**.\
+*IMPORTANT: This OPTION is only available in combination with **--import, -i**.*
 
 #### **--ignore-static-ip**
 
-If the container was started with **--ip** the restored container also tries to use that
+If the *container* was started with **--ip** the restored *container* also tries to use that
 IP address and restore fails if that IP address is already in use. This can happen, if
-a container is restored multiple times from an exported checkpoint with **--name, -n**.
+a *container* is restored multiple times from an exported checkpoint with **--name, -n**.
 
 Using **--ignore-static-ip** tells Podman to ignore the IP address if it was configured
-with **--ip** during container creation.
+with **--ip** during *container* creation.
+
+The default is **false**.
 
 #### **--ignore-static-mac**
 
-If the container was started with **--mac-address** the restored container also
+If the *container* was started with **--mac-address** the restored *container* also
 tries to use that MAC address and restore fails if that MAC address is already
-in use. This can happen, if a container is restored multiple times from an
+in use. This can happen, if a *container* is restored multiple times from an
 exported checkpoint with **--name, -n**.
 
 Using **--ignore-static-mac** tells Podman to ignore the MAC address if it was
-configured with **--mac-address** during container creation.
+configured with **--mac-address** during *container* creation.
+
+The default is **false**.
 
 #### **--ignore-volumes**
 
 This option must be used in combination with the **--import, -i** option.
-When restoring containers from a checkpoint tar.gz file with this option,
-the content of associated volumes will not be restored.
+When restoring *containers* from a checkpoint tar.gz file with this option,
+the content of associated volumes will not be restored.\
+The default is **false**.
 
-#### **--publish**, **-p**
+#### **--import**, **-i**=*file*
 
-Replaces the ports that the container publishes, as configured during the
-initial container start, with a new set of port forwarding rules.
+Import a checkpoint tar.gz file, which was exported by Podman. This can be used
+to import a checkpointed *container* from another host.\
+*IMPORTANT: This OPTION does not need a container name or ID as input argument.*
 
-```
-# podman run --rm -p 2345:80 -d webserver
-# podman container checkpoint -l --export=dump.tar
-# podman container restore -p 5432:8080 --import=dump.tar
-```
+#### **--import-previous**=*file*
 
-For more details please see **podman run --publish**.
+Import a pre-checkpoint tar.gz file which was exported by Podman. This option
+must be used with **-i** or **--import**. It only works on `runc 1.0-rc3` or `higher`.
 
-## EXAMPLE
+#### **--name**, **-n**=*name*
+
+If a *container* is restored from a checkpoint tar.gz file it is possible to rename it with **--name, -n**. This way it is possible to restore a *container* from a checkpoint multiple times with different
+names.
+
+If the **--name, -n** option is used, Podman will not attempt to assign the same IP
+address to the *container* it was using before checkpointing as each IP address can only
+be used once and the restored *container* will have another IP address. This also means
+that **--name, -n** cannot be used in combination with **--tcp-established**.\
+*IMPORTANT: This OPTION is only available in combination with **--import, -i**.*
+
+#### **--publish**, **-p**=*port*
+
+Replaces the ports that the *container* publishes, as configured during the
+initial *container* start, with a new set of port forwarding rules.
+
+For more details please see **[podman run --publish](podman-run.1.md#--publish)**.
+
+#### **--tcp-established**
 
-podman container restore mywebserver
+Restore a *container* with established TCP connections. If the checkpoint image
+contains established TCP connections, this option is required during restore.
+If the checkpoint image does not contain established TCP connections this
+option is ignored. Defaults to not restoring *containers* with established TCP
+connections.\
+The default is **false**.
 
-podman container restore 860a4b23
+## EXAMPLE
+Restores the container "mywebserver".
+```
+# podman container restore mywebserver
+```
 
-podman container restore --import-previous pre-checkpoint.tar.gz --import checkpoint.tar.gz
+Import a checkpoint file and a pre-checkpoint file.
+```
+# podman container restore --import-previous pre-checkpoint.tar.gz --import checkpoint.tar.gz
+```
+
+Remove the container "mywebserver". Make a checkpoint of the container and export it. Restore the container with other port ranges from the exported file.
+```
+$ podman run --rm -p 2345:80 -d webserver
+# podman container checkpoint -l --export=dump.tar
+# podman container restore -p 5432:8080 --import=dump.tar
+```
 
 ## SEE ALSO
-podman(1), podman-container-checkpoint(1), podman-run(1)
+**[podman(1)](podman.1.md)**, **[podman-container-checkpoint(1)](podman-container-checkpoint.1.md)**, **[podman-run(1)](podman-run.1.md)**
 
 ## HISTORY
 September 2018, Originally compiled by Adrian Reber <areber@redhat.com>