Refactor common options in man pages

podman-create and -run have many options in common. To date,
these are copy-pasted and haphazardly maintained.

Solution: add an include mechanism, '@@option foo', such
that multiple md source files can fetch from one common file.

This is a Phase One commit, a very small subset of what's
possible. Purpose of this commit is ease of review. If this
passes review, much more (trickier stuff) will be forthcoming.

Signed-off-by: Ed Santiago <santiago@redhat.com>

20 files changed, 177 insertions, 0 deletions

diff --git a/docs/source/markdown/options/cgroup-conf.md b/docs/source/markdown/options/cgroup-conf.md
new file mode 100644
index 000000000..91d724ab6
--- /dev/null
+++ b/docs/source/markdown/options/cgroup-conf.md
@@ -0,0 +1,3 @@
+#### **--cgroup-conf**=*KEY=VALUE*
+
+When running on cgroup v2, specify the cgroup file to write to and its value. For example **--cgroup-conf=memory.high=1073741824** sets the memory.high limit to 1GB.
diff --git a/docs/source/markdown/options/chrootdirs.md b/docs/source/markdown/options/chrootdirs.md
new file mode 100644
index 000000000..624a10624
--- /dev/null
+++ b/docs/source/markdown/options/chrootdirs.md
@@ -0,0 +1,5 @@
+#### **--chrootdirs**=*path*
+
+Path to a directory inside the container that should be treated as a `chroot` directory.
+Any Podman managed file (e.g., /etc/resolv.conf, /etc/hosts, etc/hostname) that is mounted into the root directory will be mounted into that location as well.
+Multiple directories should be separated with a comma.
diff --git a/docs/source/markdown/options/env-host.md b/docs/source/markdown/options/env-host.md
new file mode 100644
index 000000000..665fca016
--- /dev/null
+++ b/docs/source/markdown/options/env-host.md
@@ -0,0 +1,3 @@
+#### **--env-host**
+
+Use host environment inside of the container. See **Environment** note below for precedence. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines)
diff --git a/docs/source/markdown/options/group-add.md b/docs/source/markdown/options/group-add.md
new file mode 100644
index 000000000..ac9ade3a7
--- /dev/null
+++ b/docs/source/markdown/options/group-add.md
@@ -0,0 +1,11 @@
+#### **--group-add**=*group* | *keep-groups*
+
+Assign additional groups to the primary user running within the container process.
+
+- `keep-groups` is a special flag that tells Podman to keep the supplementary group access.
+
+Allows container to use the user's supplementary group access. If file systems or
+devices are only accessible by the rootless user's group, this flag tells the OCI
+runtime to pass the group access into the container. Currently only available
+with the `crun` OCI runtime. Note: `keep-groups` is exclusive, you cannot add any other groups
+with this flag. (Not available for remote commands, including Mac and Windows (excluding WSL2) machines)
diff --git a/docs/source/markdown/options/hostuser.md b/docs/source/markdown/options/hostuser.md
new file mode 100644
index 000000000..d1d12c88f
--- /dev/null
+++ b/docs/source/markdown/options/hostuser.md
@@ -0,0 +1,4 @@
+#### **--hostuser**=*name*
+
+Add a user account to /etc/passwd from the host to the container. The Username
+or UID must exist on the host system.
diff --git a/docs/source/markdown/options/image-volume.md b/docs/source/markdown/options/image-volume.md
new file mode 100644
index 000000000..2a549ef3c
--- /dev/null
+++ b/docs/source/markdown/options/image-volume.md
@@ -0,0 +1,8 @@
+#### **--image-volume**=**bind** | *tmpfs* | *ignore*
+
+Tells Podman how to handle the builtin image volumes. Default is **bind**.
+
+- **bind**: An anonymous named volume will be created and mounted into the container.
+- **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.
+- **ignore**: All volumes are just ignored and no action is taken.
diff --git a/docs/source/markdown/options/init-path.md b/docs/source/markdown/options/init-path.md
new file mode 100644
index 000000000..c2be27874
--- /dev/null
+++ b/docs/source/markdown/options/init-path.md
@@ -0,0 +1,3 @@
+#### **--init-path**=*path*
+
+Path to the container-init binary.
diff --git a/docs/source/markdown/options/init.md b/docs/source/markdown/options/init.md
new file mode 100644
index 000000000..caf300efe
--- /dev/null
+++ b/docs/source/markdown/options/init.md
@@ -0,0 +1,5 @@
+#### **--init**
+
+Run an init inside the container that forwards signals and reaps processes.
+The container-init binary is mounted at `/run/podman-init`.
+Mounting over `/run` will hence break container execution.
diff --git a/docs/source/markdown/options/mount.md b/docs/source/markdown/options/mount.md
new file mode 100644
index 000000000..e81af539d
--- /dev/null
+++ b/docs/source/markdown/options/mount.md
@@ -0,0 +1,77 @@
+#### **--mount**=*type=TYPE,TYPE-SPECIFIC-OPTION[,...]*
+
+Attach a filesystem mount to the container
+
+Current supported mount TYPEs are **bind**, **volume**, **image**, **tmpfs** and **devpts**. <sup>[[1]](#Footnote1)</sup>
+
+       e.g.
+
+       type=bind,source=/path/on/host,destination=/path/in/container
+
+       type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared
+
+       type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared,U=true
+
+       type=volume,source=vol1,destination=/path/in/container,ro=true
+
+       type=tmpfs,tmpfs-size=512M,destination=/path/in/container
+
+       type=image,source=fedora,destination=/fedora-image,rw=true
+
+       type=devpts,destination=/dev/pts
+
+       Common Options:
+
+	      · src, source: mount source spec for bind and volume. Mandatory for bind.
+
+	      · dst, destination, target: mount destination spec.
+
+       Options specific to volume:
+
+	      · ro, readonly: true or false (default).
+
+	      . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container.
+
+	      · idmap: true or false (default).  If specified, create an idmapped mount to the target user namespace in the container.
+
+       Options specific to image:
+
+	      · rw, readwrite: true or false (default).
+
+       Options specific to bind:
+
+	      · ro, readonly: true or false (default).
+
+	      · bind-propagation: shared, slave, private, unbindable, rshared, rslave, runbindable, or rprivate(default). See also mount(2).
+
+	      . bind-nonrecursive: do not set up a recursive bind mount. By default it is recursive.
+
+	      . relabel: shared, private.
+
+	      · idmap: true or false (default).  If specified, create an idmapped mount to the target user namespace in the container.
+
+	      . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container.
+
+       Options specific to tmpfs:
+
+	      · ro, readonly: true or false (default).
+
+	      · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux.
+
+	      · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux.
+
+	      · tmpcopyup: Enable copyup from the image directory at the same location to the tmpfs. Used by default.
+
+	      · notmpcopyup: Disable copying files from the image to the tmpfs.
+
+	      . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container.
+
+       Options specific to devpts:
+
+	      · uid: UID of the file owner (default 0).
+
+	      · gid: GID of the file owner (default 0).
+
+	      · mode: permission mask for the file (default 600).
+
+	      · max: maximum number of PTYs (default 1048576).
diff --git a/docs/source/markdown/options/no-healthcheck.md b/docs/source/markdown/options/no-healthcheck.md
new file mode 100644
index 000000000..a722ac5b5
--- /dev/null
+++ b/docs/source/markdown/options/no-healthcheck.md
@@ -0,0 +1,3 @@
+#### **--no-healthcheck**
+
+Disable any defined healthchecks for container.
diff --git a/docs/source/markdown/options/oom-kill-disable.md b/docs/source/markdown/options/oom-kill-disable.md
new file mode 100644
index 000000000..24ed9a889
--- /dev/null
+++ b/docs/source/markdown/options/oom-kill-disable.md
@@ -0,0 +1,5 @@
+#### **--oom-kill-disable**
+
+Whether to disable OOM Killer for the container or not.
+
+This flag is not supported on cgroups V2 systems.
diff --git a/docs/source/markdown/options/passwd-entry.md b/docs/source/markdown/options/passwd-entry.md
new file mode 100644
index 000000000..33c179d12
--- /dev/null
+++ b/docs/source/markdown/options/passwd-entry.md
@@ -0,0 +1,5 @@
+#### **--passwd-entry**=*ENTRY*
+
+Customize the entry that is written to the `/etc/passwd` file within the container when `--passwd` is used.
+
+The variables $USERNAME, $UID, $GID, $NAME, $HOME are automatically replaced with their value at runtime.
diff --git a/docs/source/markdown/options/personality.md b/docs/source/markdown/options/personality.md
new file mode 100644
index 000000000..663f14782
--- /dev/null
+++ b/docs/source/markdown/options/personality.md
@@ -0,0 +1,3 @@
+#### **--personality**=*persona*
+
+Personality sets the execution domain via Linux personality(2).
diff --git a/docs/source/markdown/options/pidfile.md b/docs/source/markdown/options/pidfile.md
new file mode 100644
index 000000000..a494b522e
--- /dev/null
+++ b/docs/source/markdown/options/pidfile.md
@@ -0,0 +1,9 @@
+#### **--pidfile**=*path*
+
+When the pidfile location is specified, the container process' PID will be written to the pidfile. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines)
+If the pidfile option is not specified, the container process' PID will be written to /run/containers/storage/${storage-driver}-containers/$CID/userdata/pidfile.
+
+After the container is started, the location for the pidfile can be discovered with the following `podman inspect` command:
+
+    $ podman inspect --format '{{ .PidFile }}' $CID
+    /run/containers/storage/${storage-driver}-containers/$CID/userdata/pidfile
diff --git a/docs/source/markdown/options/sdnotify.md b/docs/source/markdown/options/sdnotify.md
new file mode 100644
index 000000000..d090cbf7c
--- /dev/null
+++ b/docs/source/markdown/options/sdnotify.md
@@ -0,0 +1,10 @@
+#### **--sdnotify**=**container** | *conmon* | *ignore*
+
+Determines how to use the NOTIFY_SOCKET, as passed with systemd and Type=notify.
+
+Default is **container**, which means allow the OCI runtime to proxy the socket into the
+container to receive ready notification. Podman will set the MAINPID to conmon's pid.
+The **conmon** option sets MAINPID to conmon's pid, and sends READY when the container
+has started. The socket is never passed to the runtime or the container.
+The **ignore** option removes NOTIFY_SOCKET from the environment for itself and child processes,
+for the case where some other process above Podman uses NOTIFY_SOCKET and Podman should not use it.
diff --git a/docs/source/markdown/options/seccomp-policy.md b/docs/source/markdown/options/seccomp-policy.md
new file mode 100644
index 000000000..3b2eb7553
--- /dev/null
+++ b/docs/source/markdown/options/seccomp-policy.md
@@ -0,0 +1,5 @@
+#### **--seccomp-policy**=*policy*
+
+Specify the policy to select the seccomp profile. If set to *image*, Podman will look for a "io.containers.seccomp.profile" label in the container-image config and use its value as a seccomp profile. Otherwise, Podman will follow the *default* policy by applying the default profile unless specified otherwise via *--security-opt seccomp* as described below.
+
+Note that this feature is experimental and may change in the future.
diff --git a/docs/source/markdown/options/timeout.md b/docs/source/markdown/options/timeout.md
new file mode 100644
index 000000000..731feb973
--- /dev/null
+++ b/docs/source/markdown/options/timeout.md
@@ -0,0 +1,5 @@
+#### **--timeout**=*seconds*
+
+Maximum time a container is allowed to run before conmon sends it the kill
+signal.  By default containers will run until they exit or are stopped by
+`podman stop`.
diff --git a/docs/source/markdown/options/tz.md b/docs/source/markdown/options/tz.md
new file mode 100644
index 000000000..0442e8a76
--- /dev/null
+++ b/docs/source/markdown/options/tz.md
@@ -0,0 +1,4 @@
+#### **--tz**=*timezone*
+
+Set timezone in container. This flag takes area-based timezones, GMT time, as well as `local`, which sets the timezone in the container to match the host machine. See `/usr/share/zoneinfo/` for valid timezones.
+Remote connections use local containers.conf for defaults
diff --git a/docs/source/markdown/options/umask.md b/docs/source/markdown/options/umask.md
new file mode 100644
index 000000000..55668b6da
--- /dev/null
+++ b/docs/source/markdown/options/umask.md
@@ -0,0 +1,4 @@
+#### **--umask**=*umask*
+
+Set the umask inside the container. Defaults to `0022`.
+Remote connections use local containers.conf for defaults
diff --git a/docs/source/markdown/options/unsetenv-all.md b/docs/source/markdown/options/unsetenv-all.md
new file mode 100644
index 000000000..3aad2e805
--- /dev/null
+++ b/docs/source/markdown/options/unsetenv-all.md
@@ -0,0 +1,5 @@
+#### **--unsetenv-all**
+
+Unset all default environment variables for the container. Default environment
+variables include variables provided natively by Podman, environment variables
+configured by the image, and environment variables from containers.conf.