From d7f134d687459834e1b9c805fe30bf40b2df767a Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Mon, 8 Aug 2022 15:51:34 -0600 Subject: Refactor common man page options, phase 2 Followup to #15174. These are the options that are easy(ish) to review: those that have only drifted slightly, and need only minor tweaks to bring back to sanity. For the most part, I went with the text in podman-run because that was cleaned up in #5192 way back in 2020. These diffs primarily consist of using '**' (star star) instead of backticks, plus other formatting and punctuation changes. This PR also adds a README in the options dir, and a new convention: <> which tries to do the right thing based on whether the man page name includes "-pod-" or not. Since that's kind of hairy code, I've also added a test suite for it. Finally, since this is impossible to review by normal means, I'm temporarily committing hack/markdown-preprocess-review, a script that will diff option-by-option. I will remove it once we finish this cleanup, but be advised that there are still 130+ options left to examine, and some of those are going to be really hard to reunite. Review script usage: simply run it (you need to have 'diffuse' installed). It isn't exactly obvious, but it shouldn't take more than a minute to figure out. The rightmost column (zzz-chosen.md) is the "winner", the actual content that will be used henceforth. You really want an ultrawide screen here. Signed-off-by: Ed Santiago --- docs/source/markdown/options/README.md | 44 ++++++++++++ .../source/markdown/options/blkio-weight-device.md | 3 + docs/source/markdown/options/blkio-weight.md | 3 + docs/source/markdown/options/cap-add.md | 3 + docs/source/markdown/options/cap-drop.md | 3 + docs/source/markdown/options/destroy.md | 3 + docs/source/markdown/options/entrypoint.md | 17 +++++ docs/source/markdown/options/expose.md | 4 ++ docs/source/markdown/options/health-cmd.md | 8 +++ docs/source/markdown/options/health-interval.md | 3 + docs/source/markdown/options/health-retries.md | 3 + .../source/markdown/options/health-start-period.md | 4 ++ docs/source/markdown/options/health-timeout.md | 4 ++ docs/source/markdown/options/hostname.container.md | 5 ++ docs/source/markdown/options/hostname.pod.md | 3 + docs/source/markdown/options/infra-command.md | 3 + .../markdown/options/infra-conmon-pidfile.md | 3 + docs/source/markdown/options/infra-name.md | 3 + docs/source/markdown/options/label-file.md | 3 + docs/source/markdown/options/link-local-ip.md | 3 + docs/source/markdown/options/log-driver.md | 12 ++++ docs/source/markdown/options/mac-address.md | 11 +++ docs/source/markdown/options/memory-swappiness.md | 5 ++ docs/source/markdown/options/network-alias.md | 8 +++ docs/source/markdown/options/oom-score-adj.md | 3 + docs/source/markdown/options/pid.pod.md | 7 ++ docs/source/markdown/options/pids-limit.md | 3 + docs/source/markdown/options/platform.md | 4 ++ docs/source/markdown/options/pull.md | 8 +++ docs/source/markdown/options/read-only-tmpfs.md | 3 + docs/source/markdown/options/read-only.md | 7 ++ docs/source/markdown/options/replace.md | 3 + docs/source/markdown/options/requires.md | 5 ++ docs/source/markdown/options/secret.md | 22 ++++++ docs/source/markdown/options/stop-signal.md | 3 + docs/source/markdown/options/stop-timeout.md | 4 ++ docs/source/markdown/options/tmpfs.md | 14 ++++ docs/source/markdown/options/uidmap.container.md | 79 ++++++++++++++++++++++ docs/source/markdown/options/uidmap.pod.md | 6 ++ docs/source/markdown/options/ulimit.md | 3 + docs/source/markdown/options/unsetenv.md | 5 ++ docs/source/markdown/options/uts.container.md | 8 +++ docs/source/markdown/options/uts.pod.md | 7 ++ 43 files changed, 355 insertions(+) create mode 100644 docs/source/markdown/options/README.md create mode 100644 docs/source/markdown/options/blkio-weight-device.md create mode 100644 docs/source/markdown/options/blkio-weight.md create mode 100644 docs/source/markdown/options/cap-add.md create mode 100644 docs/source/markdown/options/cap-drop.md create mode 100644 docs/source/markdown/options/destroy.md create mode 100644 docs/source/markdown/options/entrypoint.md create mode 100644 docs/source/markdown/options/expose.md create mode 100644 docs/source/markdown/options/health-cmd.md create mode 100644 docs/source/markdown/options/health-interval.md create mode 100644 docs/source/markdown/options/health-retries.md create mode 100644 docs/source/markdown/options/health-start-period.md create mode 100644 docs/source/markdown/options/health-timeout.md create mode 100644 docs/source/markdown/options/hostname.container.md create mode 100644 docs/source/markdown/options/hostname.pod.md create mode 100644 docs/source/markdown/options/infra-command.md create mode 100644 docs/source/markdown/options/infra-conmon-pidfile.md create mode 100644 docs/source/markdown/options/infra-name.md create mode 100644 docs/source/markdown/options/label-file.md create mode 100644 docs/source/markdown/options/link-local-ip.md create mode 100644 docs/source/markdown/options/log-driver.md create mode 100644 docs/source/markdown/options/mac-address.md create mode 100644 docs/source/markdown/options/memory-swappiness.md create mode 100644 docs/source/markdown/options/network-alias.md create mode 100644 docs/source/markdown/options/oom-score-adj.md create mode 100644 docs/source/markdown/options/pid.pod.md create mode 100644 docs/source/markdown/options/pids-limit.md create mode 100644 docs/source/markdown/options/platform.md create mode 100644 docs/source/markdown/options/pull.md create mode 100644 docs/source/markdown/options/read-only-tmpfs.md create mode 100644 docs/source/markdown/options/read-only.md create mode 100644 docs/source/markdown/options/replace.md create mode 100644 docs/source/markdown/options/requires.md create mode 100644 docs/source/markdown/options/secret.md create mode 100644 docs/source/markdown/options/stop-signal.md create mode 100644 docs/source/markdown/options/stop-timeout.md create mode 100644 docs/source/markdown/options/tmpfs.md create mode 100644 docs/source/markdown/options/uidmap.container.md create mode 100644 docs/source/markdown/options/uidmap.pod.md create mode 100644 docs/source/markdown/options/ulimit.md create mode 100644 docs/source/markdown/options/unsetenv.md create mode 100644 docs/source/markdown/options/uts.container.md create mode 100644 docs/source/markdown/options/uts.pod.md (limited to 'docs/source/markdown/options') diff --git a/docs/source/markdown/options/README.md b/docs/source/markdown/options/README.md new file mode 100644 index 000000000..b737fabf7 --- /dev/null +++ b/docs/source/markdown/options/README.md @@ -0,0 +1,44 @@ +Common Man Page Options +======================= + +This subdirectory contains option (flag) names and descriptions +common to multiple podman man pages. Each file is one option. The +filename does not necessarily need to be identical to the option +name: for instance, `hostname.container.md` and `hostname.pod.md` +exist because the **--hostname** option is sufficiently different +between `podman-{create,run}` and `podman-pod-{create,run}` to +warrant living separately. + +How +=== + +The files here are included in `podman-*.md.in` files using the `@@option` +mechanism: + +``` +@@option foo ! will include options/foo.md +``` + +The tool that does this is `hack/markdown-preprocess`. It is a python +script because it needs to run on `readthedocs.io`. From a given `.md.in` +file, this script will create a `.md` file that can then be read by +`go-md2man`, `sphinx`, anything that groks markdown. This runs as +part of `make docs`. + +Special Substitutions +===================== + +Some options are almost identical except for 'pod' vs 'container' +differences. For those, use `<>`. +Order is immaterial: the important thing is the presence of the +string "`pod`" in one half but not the other. The correct string +will be chosen based on the filename: if the file contains `-pod`, +such as `podman-pod-create`, the string with `pod` (case-insensitive) +in it will be chosen. + +The string `<>` will be replaced with the podman subcommand +as determined from the filename, e.g., `create` for `podman-create.1.md.in`. +This allows the shared use of examples in the option file: +``` + Example: podman <> --foo --bar +``` diff --git a/docs/source/markdown/options/blkio-weight-device.md b/docs/source/markdown/options/blkio-weight-device.md new file mode 100644 index 000000000..55c5fd4fd --- /dev/null +++ b/docs/source/markdown/options/blkio-weight-device.md @@ -0,0 +1,3 @@ +#### **--blkio-weight-device**=*device:weight* + +Block IO relative device weight. diff --git a/docs/source/markdown/options/blkio-weight.md b/docs/source/markdown/options/blkio-weight.md new file mode 100644 index 000000000..eb8e94144 --- /dev/null +++ b/docs/source/markdown/options/blkio-weight.md @@ -0,0 +1,3 @@ +#### **--blkio-weight**=*weight* + +Block IO relative weight. The _weight_ is a value between **10** and **1000**. diff --git a/docs/source/markdown/options/cap-add.md b/docs/source/markdown/options/cap-add.md new file mode 100644 index 000000000..4476afebb --- /dev/null +++ b/docs/source/markdown/options/cap-add.md @@ -0,0 +1,3 @@ +#### **--cap-add**=*capability* + +Add Linux capabilities. diff --git a/docs/source/markdown/options/cap-drop.md b/docs/source/markdown/options/cap-drop.md new file mode 100644 index 000000000..8d7371ea2 --- /dev/null +++ b/docs/source/markdown/options/cap-drop.md @@ -0,0 +1,3 @@ +#### **--cap-drop**=*capability* + +Drop Linux capabilities. diff --git a/docs/source/markdown/options/destroy.md b/docs/source/markdown/options/destroy.md new file mode 100644 index 000000000..885c96201 --- /dev/null +++ b/docs/source/markdown/options/destroy.md @@ -0,0 +1,3 @@ +#### **--destroy** + +Remove the original <> that we are cloning once used to mimic the configuration. diff --git a/docs/source/markdown/options/entrypoint.md b/docs/source/markdown/options/entrypoint.md new file mode 100644 index 000000000..0da5e42af --- /dev/null +++ b/docs/source/markdown/options/entrypoint.md @@ -0,0 +1,17 @@ +#### **--entrypoint**=*"command"* | *'["command", "arg1", ...]'* + +Overwrite the default ENTRYPOINT of the image. + +This option allows you to overwrite the default entrypoint of the image. + +The ENTRYPOINT of an image is similar to a COMMAND +because it specifies what executable to run when the container starts, but it is +(purposely) more difficult to override. The ENTRYPOINT gives a container its +default nature or behavior, so that when you set an ENTRYPOINT you can run the +container as if it were that binary, complete with default options, and you can +pass in more options via the COMMAND. But, sometimes an operator may want to run +something else inside the container, so you can override the default ENTRYPOINT +at runtime by using a **--entrypoint** and a string to specify the new +ENTRYPOINT. + +You need to specify multi option commands in the form of a json string. diff --git a/docs/source/markdown/options/expose.md b/docs/source/markdown/options/expose.md new file mode 100644 index 000000000..04b5aad66 --- /dev/null +++ b/docs/source/markdown/options/expose.md @@ -0,0 +1,4 @@ +#### **--expose**=*port* + +Expose a port, or a range of ports (e.g. **--expose=3300-3310**) to set up port redirection +on the host system. diff --git a/docs/source/markdown/options/health-cmd.md b/docs/source/markdown/options/health-cmd.md new file mode 100644 index 000000000..df0474393 --- /dev/null +++ b/docs/source/markdown/options/health-cmd.md @@ -0,0 +1,8 @@ +#### **--health-cmd**=*"command"* | *'["command", "arg1", ...]'* + +Set or alter a healthcheck command for a container. The command is a command to be executed inside your +container that determines your container health. The command is required for other healthcheck options +to be applied. A value of **none** disables existing healthchecks. + +Multiple options can be passed in the form of a JSON array; otherwise, the command will be interpreted +as an argument to **/bin/sh -c**. diff --git a/docs/source/markdown/options/health-interval.md b/docs/source/markdown/options/health-interval.md new file mode 100644 index 000000000..581e35f65 --- /dev/null +++ b/docs/source/markdown/options/health-interval.md @@ -0,0 +1,3 @@ +#### **--health-interval**=*interval* + +Set an interval for the healthchecks. An _interval_ of **disable** results in no automatic timer setup. The default is **30s**. diff --git a/docs/source/markdown/options/health-retries.md b/docs/source/markdown/options/health-retries.md new file mode 100644 index 000000000..e96dd3033 --- /dev/null +++ b/docs/source/markdown/options/health-retries.md @@ -0,0 +1,3 @@ +#### **--health-retries**=*retries* + +The number of retries allowed before a healthcheck is considered to be unhealthy. The default value is **3**. diff --git a/docs/source/markdown/options/health-start-period.md b/docs/source/markdown/options/health-start-period.md new file mode 100644 index 000000000..e88e270c6 --- /dev/null +++ b/docs/source/markdown/options/health-start-period.md @@ -0,0 +1,4 @@ +#### **--health-start-period**=*period* + +The initialization time needed for a container to bootstrap. The value can be expressed in time format like +**2m3s**. The default value is **0s**. diff --git a/docs/source/markdown/options/health-timeout.md b/docs/source/markdown/options/health-timeout.md new file mode 100644 index 000000000..5102ea81b --- /dev/null +++ b/docs/source/markdown/options/health-timeout.md @@ -0,0 +1,4 @@ +#### **--health-timeout**=*timeout* + +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**. diff --git a/docs/source/markdown/options/hostname.container.md b/docs/source/markdown/options/hostname.container.md new file mode 100644 index 000000000..6c525ac5b --- /dev/null +++ b/docs/source/markdown/options/hostname.container.md @@ -0,0 +1,5 @@ +#### **--hostname**, **-h**=*name* + +Container host name + +Sets the container host name that is available inside the container. Can only be used with a private UTS namespace `--uts=private` (default). If `--pod` is specified and the pod shares the UTS namespace (default) the pod's hostname will be used. diff --git a/docs/source/markdown/options/hostname.pod.md b/docs/source/markdown/options/hostname.pod.md new file mode 100644 index 000000000..418e1e8a7 --- /dev/null +++ b/docs/source/markdown/options/hostname.pod.md @@ -0,0 +1,3 @@ +#### **--hostname**=*name* + +Set a hostname to the pod. diff --git a/docs/source/markdown/options/infra-command.md b/docs/source/markdown/options/infra-command.md new file mode 100644 index 000000000..24edcddfe --- /dev/null +++ b/docs/source/markdown/options/infra-command.md @@ -0,0 +1,3 @@ +#### **--infra-command**=*command* + +The command that will be run to start the infra container. Default: "/pause". diff --git a/docs/source/markdown/options/infra-conmon-pidfile.md b/docs/source/markdown/options/infra-conmon-pidfile.md new file mode 100644 index 000000000..f1c518682 --- /dev/null +++ b/docs/source/markdown/options/infra-conmon-pidfile.md @@ -0,0 +1,3 @@ +#### **--infra-conmon-pidfile**=*file* + +Write the pid of the infra container's **conmon** process to a file. As **conmon** runs in a separate process than Podman, this is necessary when using systemd to manage Podman containers and pods. diff --git a/docs/source/markdown/options/infra-name.md b/docs/source/markdown/options/infra-name.md new file mode 100644 index 000000000..d8cd3989d --- /dev/null +++ b/docs/source/markdown/options/infra-name.md @@ -0,0 +1,3 @@ +#### **--infra-name**=*name* + +The name that will be used for the pod's infra container. diff --git a/docs/source/markdown/options/label-file.md b/docs/source/markdown/options/label-file.md new file mode 100644 index 000000000..fe4bc9176 --- /dev/null +++ b/docs/source/markdown/options/label-file.md @@ -0,0 +1,3 @@ +#### **--label-file**=*file* + +Read in a line-delimited file of labels. diff --git a/docs/source/markdown/options/link-local-ip.md b/docs/source/markdown/options/link-local-ip.md new file mode 100644 index 000000000..5bedff01e --- /dev/null +++ b/docs/source/markdown/options/link-local-ip.md @@ -0,0 +1,3 @@ +#### **--link-local-ip**=*ip* + +Not implemented. diff --git a/docs/source/markdown/options/log-driver.md b/docs/source/markdown/options/log-driver.md new file mode 100644 index 000000000..195e1f284 --- /dev/null +++ b/docs/source/markdown/options/log-driver.md @@ -0,0 +1,12 @@ +#### **--log-driver**=*driver* + +Logging driver for the container. Currently available options are **k8s-file**, **journald**, **none** and **passthrough**, with **json-file** aliased to **k8s-file** for scripting compatibility. (Default **journald**). + +The podman info command below will display the default log-driver for the system. +``` +$ podman info --format '{{ .Host.LogDriver }}' +journald +``` +The **passthrough** driver passes down the standard streams (stdin, stdout, stderr) to the +container. It is not allowed with the remote Podman client, including Mac and Windows (excluding WSL2) machines, and on a tty, since it is +vulnerable to attacks via TIOCSTI. diff --git a/docs/source/markdown/options/mac-address.md b/docs/source/markdown/options/mac-address.md new file mode 100644 index 000000000..0939ceaad --- /dev/null +++ b/docs/source/markdown/options/mac-address.md @@ -0,0 +1,11 @@ +#### **--mac-address**=*address* + +<> network interface MAC address (e.g. 92:d0:c6:0a:29:33) +This option can only be used if the <> is joined to only a single network - i.e., **--network=_network-name_** is used at most once - +and if the <> is not joining another container's network namespace via **--network=container:_id_**. + +Remember that the MAC address in an Ethernet network must be unique. +The IPv6 link-local address will be based on the device's MAC address +according to RFC4862. + +To specify multiple static MAC addresses per <>, set multiple networks using the **--network** option with a static MAC address specified for each using the `mac` mode for that option. diff --git a/docs/source/markdown/options/memory-swappiness.md b/docs/source/markdown/options/memory-swappiness.md new file mode 100644 index 000000000..65f0ef310 --- /dev/null +++ b/docs/source/markdown/options/memory-swappiness.md @@ -0,0 +1,5 @@ +#### **--memory-swappiness**=*number* + +Tune a container's memory swappiness behavior. Accepts an integer between *0* and *100*. + +This flag is not supported on cgroups V2 systems. diff --git a/docs/source/markdown/options/network-alias.md b/docs/source/markdown/options/network-alias.md new file mode 100644 index 000000000..f48a1bb95 --- /dev/null +++ b/docs/source/markdown/options/network-alias.md @@ -0,0 +1,8 @@ +#### **--network-alias**=*alias* + +Add a network-scoped alias for the <>, setting the alias for all networks that the container joins. To set a +name only for a specific network, use the alias option as described under the **--network** option. +If the network has DNS enabled (`podman network inspect -f {{.DNSEnabled}} `), +these aliases can be used for name resolution on the given network. This option can be specified multiple times. +NOTE: When using CNI a <> will only have access to aliases on the first network that it joins. This limitation does +not exist with netavark/aardvark-dns. diff --git a/docs/source/markdown/options/oom-score-adj.md b/docs/source/markdown/options/oom-score-adj.md new file mode 100644 index 000000000..123e8e243 --- /dev/null +++ b/docs/source/markdown/options/oom-score-adj.md @@ -0,0 +1,3 @@ +#### **--oom-score-adj**=*num* + +Tune the host's OOM preferences for containers (accepts values from **-1000** to **1000**). diff --git a/docs/source/markdown/options/pid.pod.md b/docs/source/markdown/options/pid.pod.md new file mode 100644 index 000000000..4086736b6 --- /dev/null +++ b/docs/source/markdown/options/pid.pod.md @@ -0,0 +1,7 @@ +#### **--pid**=*pid* + +Set the PID mode for the pod. The default is to create a private PID namespace for the pod. Requires the PID namespace to be shared via --share. + + host: use the host’s PID namespace for the pod + ns: join the specified PID namespace + private: create a new namespace for the pod (default) diff --git a/docs/source/markdown/options/pids-limit.md b/docs/source/markdown/options/pids-limit.md new file mode 100644 index 000000000..efcaef2e2 --- /dev/null +++ b/docs/source/markdown/options/pids-limit.md @@ -0,0 +1,3 @@ +#### **--pids-limit**=*limit* + +Tune the container's pids limit. Set to **-1** to have unlimited pids for the container. The default is **4096** on systems that support "pids" cgroup controller. diff --git a/docs/source/markdown/options/platform.md b/docs/source/markdown/options/platform.md new file mode 100644 index 000000000..edfa428ff --- /dev/null +++ b/docs/source/markdown/options/platform.md @@ -0,0 +1,4 @@ +#### **--platform**=*OS/ARCH* + +Specify the platform for selecting the image. (Conflicts with --arch and --os) +The `--platform` option can be used to override the current architecture and operating system. diff --git a/docs/source/markdown/options/pull.md b/docs/source/markdown/options/pull.md new file mode 100644 index 000000000..ae0911507 --- /dev/null +++ b/docs/source/markdown/options/pull.md @@ -0,0 +1,8 @@ +#### **--pull**=*policy* + +Pull image policy. The default is **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. diff --git a/docs/source/markdown/options/read-only-tmpfs.md b/docs/source/markdown/options/read-only-tmpfs.md new file mode 100644 index 000000000..7e14f7fef --- /dev/null +++ b/docs/source/markdown/options/read-only-tmpfs.md @@ -0,0 +1,3 @@ +#### **--read-only-tmpfs** + +If container is running in **--read-only** mode, then mount a read-write tmpfs on _/run_, _/tmp_, and _/var/tmp_. The default is **true**. diff --git a/docs/source/markdown/options/read-only.md b/docs/source/markdown/options/read-only.md new file mode 100644 index 000000000..ae5244a22 --- /dev/null +++ b/docs/source/markdown/options/read-only.md @@ -0,0 +1,7 @@ +#### **--read-only** + +Mount the container's root filesystem as read-only. + +By default a container will have its root filesystem writable allowing processes +to write files anywhere. By specifying the **--read-only** flag, the container will have +its root filesystem mounted as read-only prohibiting any writes. diff --git a/docs/source/markdown/options/replace.md b/docs/source/markdown/options/replace.md new file mode 100644 index 000000000..6cd849fb4 --- /dev/null +++ b/docs/source/markdown/options/replace.md @@ -0,0 +1,3 @@ +#### **--replace** + +If another <> with the same name already exists, replace and remove it. The default is **false**. diff --git a/docs/source/markdown/options/requires.md b/docs/source/markdown/options/requires.md new file mode 100644 index 000000000..fa2e9a8f3 --- /dev/null +++ b/docs/source/markdown/options/requires.md @@ -0,0 +1,5 @@ +#### **--requires**=*container* + +Specify one or more requirements. +A requirement is a dependency container that will be started before this container. +Containers can be specified by name or ID, with multiple containers being separated by commas. diff --git a/docs/source/markdown/options/secret.md b/docs/source/markdown/options/secret.md new file mode 100644 index 000000000..ff2c0ab83 --- /dev/null +++ b/docs/source/markdown/options/secret.md @@ -0,0 +1,22 @@ +#### **--secret**=*secret[,opt=opt ...]* + +Give the container access to a secret. Can be specified multiple times. + +A secret is a blob of sensitive data which a container needs at runtime but +should not be stored in the image or in source control, such as usernames and passwords, +TLS certificates and keys, SSH keys or other important generic strings or binary content (up to 500 kb in size). + +When secrets are specified as type `mount`, the secrets are copied and mounted into the container when a container is created. +When secrets are specified as type `env`, the secret will be set as an environment variable within the container. +Secrets are written in the container at the time of container creation, and modifying the secret using `podman secret` commands +after the container is created will not affect the secret inside the container. + +Secrets and its storage are managed using the `podman secret` command. + +Secret Options + +- `type=mount|env` : How the secret will be exposed to the container. Default mount. +- `target=target` : Target of secret. Defaults to secret name. +- `uid=0` : UID of secret. Defaults to 0. Mount secret type only. +- `gid=0` : GID of secret. Defaults to 0. Mount secret type only. +- `mode=0` : Mode of secret. Defaults to 0444. Mount secret type only. diff --git a/docs/source/markdown/options/stop-signal.md b/docs/source/markdown/options/stop-signal.md new file mode 100644 index 000000000..e70d715b8 --- /dev/null +++ b/docs/source/markdown/options/stop-signal.md @@ -0,0 +1,3 @@ +#### **--stop-signal**=*signal* + +Signal to stop a container. Default is **SIGTERM**. diff --git a/docs/source/markdown/options/stop-timeout.md b/docs/source/markdown/options/stop-timeout.md new file mode 100644 index 000000000..2845e70ae --- /dev/null +++ b/docs/source/markdown/options/stop-timeout.md @@ -0,0 +1,4 @@ +#### **--stop-timeout**=*seconds* + +Timeout to stop a container. Default is **10**. +Remote connections use local containers.conf for defaults diff --git a/docs/source/markdown/options/tmpfs.md b/docs/source/markdown/options/tmpfs.md new file mode 100644 index 000000000..0d6652dcd --- /dev/null +++ b/docs/source/markdown/options/tmpfs.md @@ -0,0 +1,14 @@ +#### **--tmpfs**=*fs* + +Create a tmpfs mount. + +Mount a temporary filesystem (**tmpfs**) mount into a container, for example: + +``` +$ podman <> -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image +``` + +This command mounts a **tmpfs** at _/tmp_ within the container. The supported mount +options are the same as the Linux default mount flags. If you do not specify +any options, the system uses the following options: +**rw,noexec,nosuid,nodev**. diff --git a/docs/source/markdown/options/uidmap.container.md b/docs/source/markdown/options/uidmap.container.md new file mode 100644 index 000000000..9e21494dd --- /dev/null +++ b/docs/source/markdown/options/uidmap.container.md @@ -0,0 +1,79 @@ +#### **--uidmap**=*container_uid:from_uid:amount* + +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. + +The _from_uid_ value is based upon the user running the command, either rootful or rootless users. +* rootful user: *container_uid*:*host_uid*:*amount* +* rootless user: *container_uid*:*intermediate_uid*:*amount* + +When **podman <>** is called by a privileged user, the option **--uidmap** +works as a direct mapping between host UIDs and container UIDs. + +host UID -> container UID + +The _amount_ specifies the number of consecutive UIDs that will be mapped. +If for example _amount_ is **4** the mapping would look like: + +| host UID | container UID | +| - | - | +| _from_uid_ | _container_uid_ | +| _from_uid_ + 1 | _container_uid_ + 1 | +| _from_uid_ + 2 | _container_uid_ + 2 | +| _from_uid_ + 3 | _container_uid_ + 3 | + +When **podman <>** is called by an unprivileged user (i.e. running rootless), +the value _from_uid_ is interpreted as an "intermediate UID". In the rootless +case, host UIDs are not mapped directly to container UIDs. Instead the mapping +happens over two mapping steps: + +host UID -> intermediate UID -> container UID + +The **--uidmap** option only influences the second mapping step. + +The first mapping step is derived by Podman from the contents of the file +_/etc/subuid_ and the UID of the user calling Podman. + +First mapping step: + +| host UID | intermediate UID | +| - | - | +| UID for the user starting Podman | 0 | +| 1st subordinate UID for the user starting Podman | 1 | +| 2nd subordinate UID for the user starting Podman | 2 | +| 3rd subordinate UID for the user starting Podman | 3 | +| nth subordinate UID for the user starting Podman | n | + +To be able to use intermediate UIDs greater than zero, the user needs to have +subordinate UIDs configured in _/etc/subuid_. See **subuid**(5). + +The second mapping step is configured with **--uidmap**. + +If for example _amount_ is **5** the second mapping step would look like: + +| intermediate UID | container UID | +| - | - | +| _from_uid_ | _container_uid_ | +| _from_uid_ + 1 | _container_uid_ + 1 | +| _from_uid_ + 2 | _container_uid_ + 2 | +| _from_uid_ + 3 | _container_uid_ + 3 | +| _from_uid_ + 4 | _container_uid_ + 4 | + +When running as rootless, Podman will use all the ranges configured in the _/etc/subuid_ file. + +The current user ID is mapped to UID=0 in the rootless user namespace. +Every additional range is added sequentially afterward: + +| host |rootless user namespace | length | +| - | - | - | +| $UID | 0 | 1 | +| 1 | $FIRST_RANGE_ID | $FIRST_RANGE_LENGTH | +| 1+$FIRST_RANGE_LENGTH | $SECOND_RANGE_ID | $SECOND_RANGE_LENGTH| + +Even if a user does not have any subordinate UIDs in _/etc/subuid_, +**--uidmap** could still be used to map the normal UID of the user to a +container UID by running `podman <> --uidmap $container_uid:0:1 --user $container_uid ...`. + +Note: the **--uidmap** flag cannot be called in conjunction with the **--pod** flag as a uidmap cannot be set on the container level when in a pod. diff --git a/docs/source/markdown/options/uidmap.pod.md b/docs/source/markdown/options/uidmap.pod.md new file mode 100644 index 000000000..ad1f1658f --- /dev/null +++ b/docs/source/markdown/options/uidmap.pod.md @@ -0,0 +1,6 @@ +#### **--uidmap**=*container_uid:from_uid:amount* + +Run all containers in the pod in a new user namespace using the supplied 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/options/ulimit.md b/docs/source/markdown/options/ulimit.md new file mode 100644 index 000000000..c23163acc --- /dev/null +++ b/docs/source/markdown/options/ulimit.md @@ -0,0 +1,3 @@ +#### **--ulimit**=*option* + +Ulimit options. You can use **host** to copy the current configuration from the host. diff --git a/docs/source/markdown/options/unsetenv.md b/docs/source/markdown/options/unsetenv.md new file mode 100644 index 000000000..3f4d31d48 --- /dev/null +++ b/docs/source/markdown/options/unsetenv.md @@ -0,0 +1,5 @@ +#### **--unsetenv**=*env* + +Unset 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. diff --git a/docs/source/markdown/options/uts.container.md b/docs/source/markdown/options/uts.container.md new file mode 100644 index 000000000..74a5f33d1 --- /dev/null +++ b/docs/source/markdown/options/uts.container.md @@ -0,0 +1,8 @@ +#### **--uts**=*mode* + +Set the UTS namespace mode for the container. The following values are supported: + +- **host**: use the host's UTS namespace inside the container. +- **private**: create a new namespace for the container (default). +- **ns:[path]**: run the container in the given existing UTS namespace. +- **container:[container]**: join the UTS namespace of the specified container. diff --git a/docs/source/markdown/options/uts.pod.md b/docs/source/markdown/options/uts.pod.md new file mode 100644 index 000000000..6144e3f70 --- /dev/null +++ b/docs/source/markdown/options/uts.pod.md @@ -0,0 +1,7 @@ +#### **--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. -- cgit v1.2.3-54-g00ecf