diff options
Diffstat (limited to 'docs')
74 files changed, 693 insertions, 1216 deletions
diff --git a/docs/source/markdown/.gitignore b/docs/source/markdown/.gitignore index c441d74c5..6689b5b71 100644 --- a/docs/source/markdown/.gitignore +++ b/docs/source/markdown/.gitignore @@ -1,2 +1,8 @@ +podman-build.1.md +podman-container-clone.1.md podman-create.1.md +podman-kube-play.1.md +podman-pod-clone.1.md +podman-pod-create.1.md +podman-pull.1.md podman-run.1.md 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 `<<text for pods|text for containers>>`. +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 `<<subcommand>>` 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 <<subcommand>> --foo --bar +``` diff --git a/docs/source/markdown/options/add-host.md b/docs/source/markdown/options/add-host.md new file mode 100644 index 000000000..a6021cd3b --- /dev/null +++ b/docs/source/markdown/options/add-host.md @@ -0,0 +1,6 @@ +#### **--add-host**=*host:ip* + +Add a custom host-to-IP mapping (host:ip) + +Add a line to /etc/hosts. The format is hostname:ip. The **--add-host** +option can be set multiple times. Conflicts with the **--no-hosts** option. 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/cgroup-parent.md b/docs/source/markdown/options/cgroup-parent.md new file mode 100644 index 000000000..f376e4860 --- /dev/null +++ b/docs/source/markdown/options/cgroup-parent.md @@ -0,0 +1,5 @@ +#### **--cgroup-parent**=*path* + +Path to cgroups under which the cgroup for the <<container|pod>> will be created. If the +path is not absolute, the path is considered to be relative to the cgroups path +of the init process. Cgroups will be created if they do not already exist. diff --git a/docs/source/markdown/options/cgroupns.md b/docs/source/markdown/options/cgroupns.md new file mode 100644 index 000000000..6117b3fe1 --- /dev/null +++ b/docs/source/markdown/options/cgroupns.md @@ -0,0 +1,10 @@ +#### **--cgroupns**=*mode* + +Set the cgroup namespace mode for the container. + +- **host**: use the host's cgroup namespace inside the container. +- **container:**_id_: join the namespace of the specified container. +- **private**: create a new cgroup namespace. +- **ns:**_path_: join the namespace at the specified path. + +If the host uses cgroups v1, the default is set to **host**. On cgroups v2, the default is **private**. diff --git a/docs/source/markdown/options/cgroups.md b/docs/source/markdown/options/cgroups.md new file mode 100644 index 000000000..0dbbb15f3 --- /dev/null +++ b/docs/source/markdown/options/cgroups.md @@ -0,0 +1,10 @@ +#### **--cgroups**=*how* + +Determines whether the container will create CGroups. + +Default is **enabled**. + +The **enabled** option will create a new cgroup under the cgroup-parent. +The **disabled** option will force the container to not create CGroups, and thus conflicts with CGroup options (**--cgroupns** and **--cgroup-parent**). +The **no-conmon** option disables a new CGroup only for the **conmon** process. +The **split** option splits the current CGroup in two sub-cgroups: one for conmon and one for the container payload. It is not possible to set **--cgroup-parent** with **split**. diff --git a/docs/source/markdown/options/conmon-pidfile.md b/docs/source/markdown/options/conmon-pidfile.md new file mode 100644 index 000000000..e0e337cc8 --- /dev/null +++ b/docs/source/markdown/options/conmon-pidfile.md @@ -0,0 +1,4 @@ +#### **--conmon-pidfile**=*file* + +Write the pid of the **conmon** process to a file. As **conmon** runs in a separate process than Podman, this is necessary when using systemd to restart Podman containers. +(This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) diff --git a/docs/source/markdown/options/cpu-period.md b/docs/source/markdown/options/cpu-period.md new file mode 100644 index 000000000..8df6445e9 --- /dev/null +++ b/docs/source/markdown/options/cpu-period.md @@ -0,0 +1,10 @@ +#### **--cpu-period**=*limit* + +Set the CPU period for the Completely Fair Scheduler (CFS), which is a +duration in microseconds. Once the container's CPU quota is used up, it will +not be scheduled to run until the current period ends. Defaults to 100000 +microseconds. + +On some systems, changing the CPU limits may not be allowed for non-root +users. For more details, see +https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error diff --git a/docs/source/markdown/options/cpu-quota.md b/docs/source/markdown/options/cpu-quota.md new file mode 100644 index 000000000..67b9dee8c --- /dev/null +++ b/docs/source/markdown/options/cpu-quota.md @@ -0,0 +1,12 @@ +#### **--cpu-quota**=*limit* + +Limit the CPU Completely Fair Scheduler (CFS) quota. + +Limit the container's CPU usage. By default, containers run with the full +CPU resource. The limit is a number in microseconds. If a number is provided, +the container will be allowed to use that much CPU time until the CPU period +ends (controllable via **--cpu-period**). + +On some systems, changing the CPU limits may not be allowed for non-root +users. For more details, see +https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error diff --git a/docs/source/markdown/options/cpu-rt-period.md b/docs/source/markdown/options/cpu-rt-period.md new file mode 100644 index 000000000..9014beb33 --- /dev/null +++ b/docs/source/markdown/options/cpu-rt-period.md @@ -0,0 +1,7 @@ +#### **--cpu-rt-period**=*microseconds* + +Limit the CPU real-time period in microseconds. + +Limit the container's Real Time CPU usage. This option tells the kernel to restrict the container's Real Time CPU usage to the period specified. + +This option is not supported on cgroups V2 systems. diff --git a/docs/source/markdown/options/cpu-rt-runtime.md b/docs/source/markdown/options/cpu-rt-runtime.md new file mode 100644 index 000000000..05b1d3b96 --- /dev/null +++ b/docs/source/markdown/options/cpu-rt-runtime.md @@ -0,0 +1,10 @@ +#### **--cpu-rt-runtime**=*microseconds* + +Limit the CPU real-time runtime in microseconds. + +Limit the containers Real Time CPU usage. This option tells the kernel to limit the amount of time in a given CPU period Real Time tasks may consume. Ex: +Period of 1,000,000us and Runtime of 950,000us means that this container could consume 95% of available CPU and leave the remaining 5% to normal priority tasks. + +The sum of all runtimes across containers cannot exceed the amount allotted to the parent cgroup. + +This option is not supported on cgroups V2 systems. diff --git a/docs/source/markdown/options/cpu-shares.md b/docs/source/markdown/options/cpu-shares.md new file mode 100644 index 000000000..a5aacd2ca --- /dev/null +++ b/docs/source/markdown/options/cpu-shares.md @@ -0,0 +1,35 @@ +#### **--cpu-shares**, **-c**=*shares* + +CPU shares (relative weight). + +By default, all containers get the same proportion of CPU cycles. This +proportion can be modified by changing the container's CPU share weighting +relative to the combined weight of all the running containers. +Default weight is **1024**. + +The proportion will only apply when CPU-intensive processes are running. +When tasks in one container are idle, other containers can use the +left-over CPU time. The actual amount of CPU time will vary depending on +the number of containers running on the system. + +For example, consider three containers, one has a cpu-share of 1024 and +two others have a cpu-share setting of 512. When processes in all three +containers attempt to use 100% of CPU, the first container would receive +50% of the total CPU time. If a fourth container is added with a cpu-share +of 1024, the first container only gets 33% of the CPU. The remaining containers +receive 16.5%, 16.5% and 33% of the CPU. + +On a multi-core system, the shares of CPU time are distributed over all CPU +cores. Even if a container is limited to less than 100% of CPU time, it can +use 100% of each individual CPU core. + +For example, consider a system with more than three cores. +If the container _C0_ is started with **--cpu-shares=512** running one process, +and another container _C1_ with **--cpu-shares=1024** running two processes, +this can result in the following division of CPU shares: + +| PID | container | CPU | CPU share | +| ---- | ----------- | ------- | ------------ | +| 100 | C0 | 0 | 100% of CPU0 | +| 101 | C1 | 1 | 100% of CPU1 | +| 102 | C1 | 2 | 100% of CPU2 | diff --git a/docs/source/markdown/options/cpuset-cpus.md b/docs/source/markdown/options/cpuset-cpus.md new file mode 100644 index 000000000..d717516a0 --- /dev/null +++ b/docs/source/markdown/options/cpuset-cpus.md @@ -0,0 +1,5 @@ +#### **--cpuset-cpus**=*number* + +CPUs in which to allow execution. Can be specified as a comma-separated list +(e.g. **0,1**), as a range (e.g. **0-3**), or any combination thereof +(e.g. **0-3,7,11-15**). diff --git a/docs/source/markdown/options/cpuset-mems.md b/docs/source/markdown/options/cpuset-mems.md new file mode 100644 index 000000000..d2d13eb54 --- /dev/null +++ b/docs/source/markdown/options/cpuset-mems.md @@ -0,0 +1,8 @@ +#### **--cpuset-mems**=*nodes* + +Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on +NUMA systems. + +If there are four memory nodes on the system (0-3), use **--cpuset-mems=0,1** +then processes in the container will only use memory from the first +two memory nodes. 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 <<container|pod>> 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* + +<<Container|Pod>> network interface MAC address (e.g. 92:d0:c6:0a:29:33) +This option can only be used if the <<container|pod>> is joined to only a single network - i.e., **--network=_network-name_** is used at most once - +and if the <<container|pod>> 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 <<container|pod>>, 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 <<container|pod>>, 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}} <name>`), +these aliases can be used for name resolution on the given network. This option can be specified multiple times. +NOTE: When using CNI a <<container|pod>> 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/no-hosts.md b/docs/source/markdown/options/no-hosts.md new file mode 100644 index 000000000..5b1e95b86 --- /dev/null +++ b/docs/source/markdown/options/no-hosts.md @@ -0,0 +1,5 @@ +#### **--no-hosts** + +Do not create _/etc/hosts_ for the <<container|pod>>. +By default, Podman will manage _/etc/hosts_, adding the container's own IP address and any hosts from **--add-host**. +**--no-hosts** disables this, and the image's _/etc/hosts_ will be preserved unmodified. 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 <<container|pod>> 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 <<subcommand>> -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 <<subcommand>>** 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 <<subcommand>>** 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 <<subcommand>> --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. diff --git a/docs/source/markdown/podman-build.1.md b/docs/source/markdown/podman-build.1.md.in index ba7081ff5..34282e2d2 100644 --- a/docs/source/markdown/podman-build.1.md +++ b/docs/source/markdown/podman-build.1.md.in @@ -47,12 +47,7 @@ command to see these containers. External containers can be removed with the ## OPTIONS -#### **--add-host**=*host* - -Add a custom host-to-IP mapping (host:ip) - -Add a line to /etc/hosts. The format is hostname:ip. The **--add-host** option -can be set multiple times. Conflicts with the --no-hosts option. +@@option add-host #### **--all-platforms** @@ -120,8 +115,43 @@ The value of [name] is matched with the following priority order: #### **--cache-from** -Images to utilize as potential cache sources. Podman does not currently support -caching so this is a NOOP. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) +Repository to utilize as a potential cache source. When specified, Buildah will try to look for +cache images in the specified repository and will attempt to pull cache images instead of actually +executing the build steps locally. Buildah will only attempt to pull previously cached images if they +are considered as valid cache hits. + +Use the `--cache-to` option to populate a remote repository with cache content. + +Example + +```bash +# populate a cache and also consult it +buildah build -t test --layers --cache-to registry/myrepo/cache --cache-from registry/myrepo/cache . +``` + +Note: `--cache-from` option is ignored unless `--layers` is specified. + +#### **--cache-to** + +Set this flag to specify a remote repository that will be used to store cache images. Buildah will attempt to +push newly built cache image to the remote repository. + +Note: Use the `--cache-from` option in order to use cache content in a remote repository. + +Example + +```bash +# populate a cache and also consult it +buildah build -t test --layers --cache-to registry/myrepo/cache --cache-from registry/myrepo/cache . +``` + +Note: `--cache-to` option is ignored unless `--layers` is specified. + +#### **--cache-ttl** + +Limit the use of cached images to only consider images with created timestamps less than *duration* ago. +For example if `--cache-ttl=1h` is specified, Buildah will only consider intermediate cache images which are created +under the duration of one hour, and intermediate cache images outside this duration will be ignored. #### **--cap-add**=*CAP\_xxx* @@ -148,11 +178,7 @@ given. Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry. (Default: /etc/containers/certs.d) Please refer to containers-certs.d(5) for details. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) -#### **--cgroup-parent**=*path* - -Path to cgroups under which the cgroup for the container will be created. If the -path is not absolute, the path is considered to be relative to the cgroups path -of the init process. Cgroups will be created if they do not already exist. +@@option cgroup-parent #### **--cgroupns**=*how* @@ -171,80 +197,15 @@ Thus, compressing the data before sending it is irrelevant to Podman. (This opti Set additional flags to pass to the C Preprocessor cpp(1). Containerfiles ending with a ".in" suffix will be preprocessed via cpp(1). This option can be used to pass additional flags to cpp.Note: You can also set default CPPFLAGS by setting the BUILDAH_CPPFLAGS environment variable (e.g., export BUILDAH_CPPFLAGS="-DDEBUG"). -#### **--cpu-period**=*limit* - -Set the CPU period for the Completely Fair Scheduler (CFS), which is a -duration in microseconds. Once the container's CPU quota is used up, it will -not be scheduled to run until the current period ends. Defaults to 100000 -microseconds. - -On some systems, changing the CPU limits may not be allowed for non-root -users. For more details, see -https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error - -#### **--cpu-quota**=*limit* - -Limit the CPU Completely Fair Scheduler (CFS) quota. - -Limit the container's CPU usage. By default, containers run with the full -CPU resource. The limit is a number in microseconds. If you provide a number, -the container will be allowed to use that much CPU time until the CPU period -ends (controllable via **--cpu-period**). - -On some systems, changing the CPU limits may not be allowed for non-root -users. For more details, see -https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error - -#### **--cpu-shares**, **-c**=*shares* - -CPU shares (relative weight) - -By default, all containers get the same proportion of CPU cycles. This -proportion can be modified by changing the container's CPU share weighting -relative to the weighting of all other running containers. - -To modify the proportion from the default of 1024, use the **--cpu-shares** -option to set the weighting to 2 or higher. - -The proportion will only apply when CPU-intensive processes are running. -When tasks in one container are idle, other containers can use the -left-over CPU time. The actual amount of CPU time will vary depending on -the number of containers running on the system. - -For example, consider three containers, one has a cpu-share of 1024 and -two others have a cpu-share setting of 512. When processes in all three -containers attempt to use 100% of CPU, the first container would receive -50% of the total CPU time. If you add a fourth container with a cpu-share -of 1024, the first container only gets 33% of the CPU. The remaining containers -receive 16.5%, 16.5% and 33% of the CPU. - -On a multi-core system, the shares of CPU time are distributed over all CPU -cores. Even if a container is limited to less than 100% of CPU time, it can -use 100% of each individual CPU core. - -For example, consider a system with more than three cores. If you start one -container **{C0}** with **-c=512** running one process, and another container -**{C1}** with **-c=1024** running two processes, this can result in the -following -division of CPU shares: - - PID container CPU CPU share - 100 {C0} 0 100% of CPU0 - 101 {C1} 1 100% of CPU1 - 102 {C1} 2 100% of CPU2 - -#### **--cpuset-cpus**=*num* +@@option cpu-period - CPUs in which to allow execution (0-3, 0,1) +@@option cpu-quota -#### **--cpuset-mems**=*nodes* +@@option cpu-shares -Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on -NUMA systems. +@@option cpuset-cpus -If you have four memory nodes on your system (0-3), use `--cpuset-mems=0,1` -then processes in your container will only use memory from the first -two memory nodes. +@@option cpuset-mems #### **--creds**=*creds* @@ -485,11 +446,8 @@ considered insecure. Do not use existing cached images for the container build. Build from the start with a new set of cached layers. -#### **--no-hosts** +@@option no-hosts -Do not create _/etc/hosts_ for the container. -By default, Podman will manage _/etc/hosts_, adding the container's own IP address and any hosts from **--add-host**. -**--no-hosts** disables this, and the image's _/etc/hosts_ will be preserved unmodified. This option conflicts with **--add-host**. #### **--omit-history** diff --git a/docs/source/markdown/podman-container-clone.1.md b/docs/source/markdown/podman-container-clone.1.md.in index 9baedfd36..cf760d7a2 100644 --- a/docs/source/markdown/podman-container-clone.1.md +++ b/docs/source/markdown/podman-container-clone.1.md.in @@ -11,101 +11,25 @@ podman\-container\-clone - Creates a copy of an existing container ## OPTIONS -#### **--blkio-weight**=*weight* +@@option blkio-weight -Block IO weight (relative weight) accepts a weight value between 10 and 1000. +@@option blkio-weight-device -#### **--blkio-weight-device**=*weight* - -Block IO weight (relative device weight, format: `DEVICE_NAME:WEIGHT`). - -#### **--cpu-period**=*limit* - -Set the CPU period for the Completely Fair Scheduler (CFS), which is a -duration in microseconds. Once the container's CPU quota is used up, it will -not be scheduled to run until the current period ends. Defaults to 100000 -microseconds. - -On some systems, changing the CPU limits may not be allowed for non-root -users. For more details, see -https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error +@@option cpu-period If none is specified, the original container's cpu period is used -#### **--cpu-quota**=*limit* - -Limit the CPU Completely Fair Scheduler (CFS) quota. - -Limit the container's CPU usage. By default, containers run with the full -CPU resource. The limit is a number in microseconds. If a number is provided, -the container will be allowed to use that much CPU time until the CPU period -ends (controllable via **--cpu-period**). - -On some systems, changing the CPU limits may not be allowed for non-root -users. For more details, see -https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error +@@option cpu-quota If none is specified, the original container's CPU quota are used. -#### **--cpu-rt-period**=*microseconds* - -Limit the CPU real-time period in microseconds - -Limit the container's Real Time CPU usage. This option tells the kernel to restrict the container's Real Time CPU usage to the period specified. - -This option is not supported on cgroups V2 systems. +@@option cpu-rt-period If none is specified, the original container's CPU runtime period is used. +@@option cpu-rt-runtime -#### **--cpu-rt-runtime**=*microseconds* - -Limit the CPU real-time runtime in microseconds. - -Limit the containers Real Time CPU usage. This option tells the kernel to limit the amount of time in a given CPU period Real Time tasks may consume. Ex: -Period of 1,000,000us and Runtime of 950,000us means that this container could consume 95% of available CPU and leave the remaining 5% to normal priority tasks. - -The sum of all runtimes across containers cannot exceed the amount allotted to the parent cgroup. - -This option is not supported on cgroups V2 systems. - -#### **--cpu-shares**, **-c**=*shares* - -CPU shares (relative weight) - -By default, all containers get the same proportion of CPU cycles. This proportion -can be modified by changing the container's CPU share weighting relative -to the weighting of all other running containers. - -To modify the proportion from the default of 1024, use the **--cpu-shares** -option to set the weighting to 2 or higher. - -The proportion will only apply when CPU-intensive processes are running. -When tasks in one container are idle, other containers can use the -left-over CPU time. The actual amount of CPU time will vary depending on -the number of containers running on the system. - -For example, consider three containers, one has a cpu-share of 1024 and -two others have a cpu-share setting of 512. When processes in all three -containers attempt to use 100% of CPU, the first container would receive -50% of the total CPU time. If a fourth container is added with a cpu-share -of 1024, the first container only gets 33% of the CPU. The remaining containers -receive 16.5%, 16.5% and 33% of the CPU. - -On a multi-core system, the shares of CPU time are distributed over all CPU -cores. Even if a container is limited to less than 100% of CPU time, it can -use 100% of each individual CPU core. - -For example, consider a system with more than three cores. -If the container _C0_ is started with **--cpu-shares=512** running one process, -and another container _C1_ with **--cpu-shares=1024** running two processes, -this can result in the following division of CPU shares: - -| PID | container | CPU | CPU share | -| ---- | ----------- | ------- | ------------ | -| 100 | C0 | 0 | 100% of CPU0 | -| 101 | C1 | 1 | 100% of CPU1 | -| 102 | C1 | 2 | 100% of CPU2 | +@@option cpu-shares If none are specified, the original container's CPU shares are used. @@ -116,23 +40,15 @@ Set a number of CPUs for the container that overrides the original containers CP This is shorthand for **--cpu-period** and **--cpu-quota**, so only **--cpus** or either both the **--cpu-period** and **--cpu-quota** options can be set. -#### **--cpuset-cpus** - -CPUs in which to allow execution (0-3, 0,1). If none are specified, the original container's CPUset is used. - -#### **--cpuset-mems**=*nodes* +@@option cpuset-cpus -Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. +If none are specified, the original container's CPUset is used. -If there are four memory nodes on the system (0-3), use `--cpuset-mems=0,1` -then processes in the container will only use memory from the first -two memory nodes. +@@option cpuset-mems If none are specified, the original container's CPU memory nodes are used. -#### **--destroy** - -Remove the original container that we are cloning once used to mimic the configuration. +@@option destroy #### **--device-read-bps**=*path* @@ -179,11 +95,7 @@ The format of `LIMIT` is `<number>[<unit>]`. Unit can be `b` (bytes), `k` (kibibytes), `m` (mebibytes), or `g` (gibibytes). If you don't specify a unit, `b` is used. Set LIMIT to `-1` to enable unlimited swap. -#### **--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. +@@option memory-swappiness #### **--name** diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index 008c3c18f..5bb1dceca 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -66,12 +66,7 @@ and specified with a _tag_. ## OPTIONS -#### **--add-host**=*host* - -Add a custom host-to-IP mapping (host:ip) - -Add a line to /etc/hosts. The format is hostname:ip. The **--add-host** -option can be set multiple times. +@@option add-host #### **--annotation**=*key=value* @@ -99,47 +94,23 @@ Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE environment variable. `export REGISTRY_AUTH_FILE=path` -#### **--blkio-weight**=*weight* - -Block IO weight (relative weight) accepts a weight value between 10 and 1000. - -#### **--blkio-weight-device**=*weight* +@@option blkio-weight -Block IO weight (relative device weight, format: `DEVICE_NAME:WEIGHT`). +#### **--blkio-weight-device**=*device:weight* -#### **--cap-add**=*capability* +Block IO relative device weight. -Add Linux capabilities +@@option cap-add -#### **--cap-drop**=*capability* - -Drop Linux capabilities +@@option cap-drop @@option cgroup-conf -#### **--cgroup-parent**=*path* - -Path to cgroups under which the cgroup for the container will be created. If the path is not absolute, the path is considered to be relative to the cgroups path of the init process. Cgroups will be created if they do not already exist. - -#### **--cgroupns**=*mode* +@@option cgroup-parent -Set the cgroup namespace mode for the container. - **`host`**: use the host's cgroup namespace inside the container. - **`container:<NAME|ID>`**: join the namespace of the specified container. - **`ns:<PATH>`**: join the namespace at the specified path. - **`private`**: create a new cgroup namespace. +@@option cgroupns -If the host uses cgroups v1, the default is set to **host**. On cgroups v2 the default is **private**. - -#### **--cgroups**=*mode* - -Determines whether the container will create CGroups. -Valid values are *enabled*, *disabled*, *no-conmon*, *split*, with the default being *enabled*. - -The *enabled* option will create a new cgroup under the cgroup-parent. -The *disabled* option will force the container to not create CGroups, and thus conflicts with CGroup options (**--cgroupns** and **--cgroup-parent**). -The *no-conmon* option disables a new CGroup only for the conmon process. -The *split* option splits the current cgroup in two sub-cgroups: one for conmon and one for the container payload. It is not possible to set *--cgroup-parent* with *split*. +@@option cgroups @@option chrootdirs @@ -147,91 +118,17 @@ The *split* option splits the current cgroup in two sub-cgroups: one for conmon Write the container ID to the file -#### **--conmon-pidfile**=*path* - -Write the pid of the `conmon` process to a file. `conmon` runs in a separate process than Podman, so this is necessary when using systemd to restart Podman containers. -(This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -#### **--cpu-period**=*limit* - -Set the CPU period for the Completely Fair Scheduler (CFS), which is a -duration in microseconds. Once the container's CPU quota is used up, it will -not be scheduled to run until the current period ends. Defaults to 100000 -microseconds. - -On some systems, changing the CPU limits may not be allowed for non-root -users. For more details, see -https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error - -#### **--cpu-quota**=*limit* - -Limit the CPU Completely Fair Scheduler (CFS) quota. - -Limit the container's CPU usage. By default, containers run with the full -CPU resource. The limit is a number in microseconds. If you provide a number, -the container will be allowed to use that much CPU time until the CPU period -ends (controllable via **--cpu-period**). - -On some systems, changing the CPU limits may not be allowed for non-root -users. For more details, see -https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error - -#### **--cpu-rt-period**=*microseconds* - -Limit the CPU real-time period in microseconds - -Limit the container's Real Time CPU usage. This flag tell the kernel to restrict the container's Real Time CPU usage to the period you specify. - -This flag is not supported on cgroups V2 systems. +@@option conmon-pidfile -#### **--cpu-rt-runtime**=*microseconds* +@@option cpu-period -Limit the CPU real-time runtime in microseconds +@@option cpu-quota -Limit the containers Real Time CPU usage. This flag tells the kernel to limit the amount of time in a given CPU period Real Time tasks may consume. Ex: -Period of 1,000,000us and Runtime of 950,000us means that this container could consume 95% of available CPU and leave the remaining 5% to normal priority tasks. +@@option cpu-rt-period -The sum of all runtimes across containers cannot exceed the amount allotted to the parent cgroup. +@@option cpu-rt-runtime -This flag is not supported on cgroups V2 systems. - -#### **--cpu-shares**, **-c**=*shares* - -CPU shares (relative weight) - -By default, all containers get the same proportion of CPU cycles. This proportion -can be modified by changing the container's CPU share weighting relative -to the weighting of all other running containers. - -To modify the proportion from the default of 1024, use the **--cpu-shares** -flag to set the weighting to 2 or higher. - -The proportion will only apply when CPU-intensive processes are running. -When tasks in one container are idle, other containers can use the -left-over CPU time. The actual amount of CPU time will vary depending on -the number of containers running on the system. - -For example, consider three containers, one has a cpu-share of 1024 and -two others have a cpu-share setting of 512. When processes in all three -containers attempt to use 100% of CPU, the first container would receive -50% of the total CPU time. If you add a fourth container with a cpu-share -of 1024, the first container only gets 33% of the CPU. The remaining containers -receive 16.5%, 16.5% and 33% of the CPU. - -On a multi-core system, the shares of CPU time are distributed over all CPU -cores. Even if a container is limited to less than 100% of CPU time, it can -use 100% of each individual CPU core. - -For example, consider a system with more than three cores. -If the container _C0_ is started with **--cpu-shares=512** running one process, -and another container _C1_ with **--cpu-shares=1024** running two processes, -this can result in the following division of CPU shares: - -| PID | container | CPU | CPU share | -| ---- | ----------- | ------- | ------------ | -| 100 | C0 | 0 | 100% of CPU0 | -| 101 | C1 | 1 | 100% of CPU1 | -| 102 | C1 | 2 | 100% of CPU2 | +@@option cpu-shares #### **--cpus**=*number* @@ -243,17 +140,9 @@ On some systems, changing the CPU limits may not be allowed for non-root users. For more details, see https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error -#### **--cpuset-cpus**=*cpus* - -CPUs in which to allow execution (0-3, 0,1) - -#### **--cpuset-mems**=*nodes* +@@option cpuset-cpus -Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. - -If you have four memory nodes on your system (0-3), use `--cpuset-mems=0,1` -then processes in your container will only use memory from the first -two memory nodes. +@@option cpuset-mems #### **--device**=*host-device[:container-device][:permissions]* @@ -323,22 +212,7 @@ Set custom DNS options. Invalid if using **--dns-opt** and **--network** that is Set custom DNS search domains. Invalid if using **--dns-search** and **--network** that is set to 'none' or `container:<name|id>`. (Use --dns-search=. if you don't wish to set the search domain) -#### **--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. +@@option entrypoint #### **--env**, **-e**=*env* @@ -354,10 +228,7 @@ Read in a line delimited file of environment variables. See **Environment** note @@option env-host -#### **--expose**=*port* - -Expose a port, or a range of ports (e.g. --expose=3300-3310) to set up port redirection -on the host system. +@@option expose #### **--gidmap**=*container_gid:host_gid:amount* @@ -370,42 +241,21 @@ Note: the **--gidmap** flag cannot be called in conjunction with the **--pod** f @@option group-add -#### **--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`. - -#### **--health-interval**=*interval* - -Set an interval for the healthchecks (a value of `disable` results in no automatic timer setup) (default "30s") - -#### **--health-retries**=*retries* +@@option health-cmd -The number of retries allowed before a healthcheck is considered to be unhealthy. The default value is `3`. +@@option health-interval -#### **--health-start-period**=*period* +@@option health-retries -The initialization time needed for a container to bootstrap. The value can be expressed in time format like -`2m3s`. The default value is `0s` +@@option health-start-period -#### **--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`. +@@option health-timeout #### **--help** Print usage statement -#### **--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. +@@option hostname.container @@option hostuser @@ -490,26 +340,11 @@ a private IPC namespace. Add metadata to a container (e.g., --label com.example.key=value) -#### **--label-file**=*file* - -Read in a line delimited file of labels - -#### **--link-local-ip**=*ip* - -Not implemented - -#### **--log-driver**=*driver* +@@option label-file -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. +@@option link-local-ip -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. +@@option log-driver #### **--log-opt**=*name=value* @@ -528,17 +363,7 @@ It supports the same keys as **podman inspect --format**. This option is currently supported only by the **journald** log driver. -#### **--mac-address**=*address* - -Container network interface MAC address (e.g. 92:d0:c6:0a:29:33) -This option can only be used if the container is joined to only a single network - i.e., **--network=_network-name_** is used at most once - -and if the container 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 container, set multiple networks using the **--network** option with a static MAC address specified for each using the `mac` mode for that option. +@@option mac-address #### **--memory**, **-m**=*limit* @@ -571,11 +396,7 @@ The format of `LIMIT` is `<number>[<unit>]`. Unit can be `b` (bytes), `k` (kibibytes), `m` (mebibytes), or `g` (gibibytes). If you don't specify a unit, `b` is used. Set LIMIT to `-1` to enable unlimited swap. -#### **--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. +@@option memory-swappiness @@option mount @@ -626,29 +447,17 @@ Valid _mode_ values are: Note: Rootlesskit changes the source IP address of incoming packets to an IP address in the container network namespace, usually `10.0.2.100`. If your application requires the real source IP address, e.g. web server logs, use the slirp4netns port handler. The rootlesskit port handler is also used for rootless containers when connected to user-defined networks. - **port_handler=slirp4netns**: Use the slirp4netns port forwarding, it is slower than rootlesskit but preserves the correct source IP address. This port handler cannot be used for user-defined networks. -#### **--network-alias**=*alias* - -Add a network-scoped alias for the container, 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}} <name>`), -these aliases can be used for name resolution on the given network. This option can be specified multiple times. -NOTE: When using CNI a container will only have access to aliases on the first network that it joins. This limitation does -not exist with netavark/aardvark-dns. +@@option network-alias @@option no-healthcheck -#### **--no-hosts** +@@option no-hosts -Do not create _/etc/hosts_ for the container. -By default, Podman will manage _/etc/hosts_, adding the container's own IP address and any hosts from **--add-host**. -**--no-hosts** disables this, and the image's _/etc/hosts_ will be preserved unmodified. This option conflicts with **--add-host**. @@option oom-kill-disable -#### **--oom-score-adj**=*num* - -Tune the host's OOM preferences for containers (accepts -1000 to 1000) +@@option oom-score-adj #### **--os**=*OS* Override the OS, defaults to hosts, of the image to be pulled. For example, `windows`. @@ -668,14 +477,9 @@ Default is to create a private PID namespace for the container @@option pidfile -#### **--pids-limit**=*limit* - -Tune the container's pids limit. Set `-1` to have unlimited pids for the container. (default "4096" on systems that support PIDS cgroups). +@@option pids-limit -#### **--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. +@@option platform #### **--pod**=*name* @@ -742,40 +546,19 @@ 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**=*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. +@@option pull #### **--quiet**, **-q** Suppress output information when pulling images -#### **--read-only** +@@option read-only -Mount the container's root filesystem as read-only. +@@option read-only-tmpfs -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. +@@option replace -#### **--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* - -#### **--replace** - -If another container with the same name already exists, replace and remove it. The default is **false**. - -#### **--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. +@@option requires #### **--restart**=*policy* @@ -818,28 +601,7 @@ finishes executing, similar to a tmpfs mount point being unmounted. @@option seccomp-policy -#### **--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. +@@option secret #### **--security-opt**=*option* @@ -880,14 +642,9 @@ Size of `/dev/shm` (format: `<number>[<unit>]`, where unit = b (bytes), k (kibib If you omit the unit, the system uses bytes. If you omit the size entirely, the system uses `64m`. When size is `0`, there is no limit on the amount of memory used for IPC by the container. -#### **--stop-signal**=*SIGTERM* +@@option stop-signal -Signal to stop a container. Default is SIGTERM. - -#### **--stop-timeout**=*seconds* - -Timeout (in seconds) to stop a container. Default is 10. -Remote connections use local containers.conf for defaults +@@option stop-timeout #### **--subgidname**=*name* @@ -948,18 +705,7 @@ The `container_manage_cgroup` boolean must be enabled for this to be allowed on Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true, then TLS verification will be used. If set to false, then TLS verification will not be used. If not specified, TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf. -#### **--tmpfs**=*fs* - -Create a tmpfs mount - -Mount a temporary filesystem (`tmpfs`) mount into a container, for example: - -$ podman create -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 systems uses the following options: -`rw,noexec,nosuid,nodev`. +@@option tmpfs #### **--tty**, **-t** @@ -974,97 +720,13 @@ standard input. @@option tz -#### **--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 create** 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 create** 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: +@@option uidmap.container -| 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 | - -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 create --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. - -#### **--ulimit**=*option* - -Ulimit options - -You can pass `host` to copy the current configuration from the host. +@@option ulimit @@option umask -#### **--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. +@@option unsetenv @@option unsetenv-all @@ -1120,14 +782,7 @@ Podman allocates unique ranges of UIDs and GIDs from the `containers` subordinat This option is incompatible with **--gidmap**, **--uidmap**, **--subuidname** and **--subgidname**. -#### **--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. +@@option uts.container #### **--variant**=*VARIANT* Use _VARIANT_ instead of the default architecture variant of the container image. Some images can use multiple variants of the arm architectures, such as arm/v5 and arm/v7. diff --git a/docs/source/markdown/podman-kube-play.1.md b/docs/source/markdown/podman-kube-play.1.md.in index b3c385fe9..9e9fc7f38 100644 --- a/docs/source/markdown/podman-kube-play.1.md +++ b/docs/source/markdown/podman-kube-play.1.md.in @@ -214,11 +214,8 @@ Valid _mode_ values are: Note: Rootlesskit changes the source IP address of incoming packets to an IP address in the container network namespace, usually `10.0.2.100`. If your application requires the real source IP address, e.g. web server logs, use the slirp4netns port handler. The rootlesskit port handler is also used for rootless containers when connected to user-defined networks. - **port_handler=slirp4netns**: Use the slirp4netns port forwarding, it is slower than rootlesskit but preserves the correct source IP address. This port handler cannot be used for user-defined networks. -#### **--no-hosts** +@@option no-hosts -Do not create /etc/hosts for the pod. -By default, Podman will manage /etc/hosts, adding the container's own IP address and any hosts from **--add-host**. -**--no-hosts** disables this, and the image's **/etc/host** will be preserved unmodified. This option conflicts with host added in the Kubernetes YAML. #### **--quiet**, **-q** diff --git a/docs/source/markdown/podman-pod-clone.1.md b/docs/source/markdown/podman-pod-clone.1.md.in index 5473407b0..a5746fd84 100644 --- a/docs/source/markdown/podman-pod-clone.1.md +++ b/docs/source/markdown/podman-pod-clone.1.md.in @@ -11,75 +11,25 @@ podman\-pod\-clone - Creates a copy of an existing pod ## OPTIONS -#### **--blkio-weight**=*weight* +@@option blkio-weight -Block IO weight (relative weight) accepts a weight value between 10 and 1000. +@@option blkio-weight-device -#### **--blkio-weight-device**=*weight* +@@option cgroup-parent -Block IO weight (relative device weight, format: `DEVICE_NAME:WEIGHT`). - -#### **--cgroup-parent**=*path* - -Path to cgroups under which the cgroup for the pod will be created. If the path is not absolute, the path is considered to be relative to the cgroups path of the init process. Cgroups will be created if they do not already exist. - -#### **--cpu-shares**, **-c**=*shares* - -CPU shares (relative weight) - -By default, all containers get the same proportion of CPU cycles. This proportion -can be modified by changing the container's CPU share weighting relative -to the weighting of all other running containers. - -To modify the proportion from the default of 1024, use the **--cpu-shares** -flag to set the weighting to 2 or higher. - -The proportion will only apply when CPU-intensive processes are running. -When tasks in one container are idle, other containers can use the -left-over CPU time. The actual amount of CPU time will vary depending on -the number of containers running on the system. - -For example, consider three containers, one has a cpu-share of 1024 and -two others have a cpu-share setting of 512. When processes in all three -containers attempt to use 100% of CPU, the first container would receive -50% of the total CPU time. If you add a fourth container with a cpu-share -of 1024, the first container only gets 33% of the CPU. The remaining containers -receive 16.5%, 16.5% and 33% of the CPU. - -On a multi-core system, the shares of CPU time are distributed over all CPU -cores. Even if a container is limited to less than 100% of CPU time, it can -use 100% of each individual CPU core. - -For example, consider a system with more than three cores. If you start one -container **{C0}** with **-c=512** running one process, and another container -**{C1}** with **-c=1024** running two processes, this can result in the following -division of CPU shares: - -PID container CPU CPU share -100 {C0} 0 100% of CPU0 -101 {C1} 1 100% of CPU1 -102 {C1} 2 100% of CPU2 +@@option cpu-shares #### **--cpus** Set a number of CPUs for the pod that overrides the original pods CPU limits. If none are specified, the original pod's Nano CPUs are used. -#### **--cpuset-cpus** - -CPUs in which to allow execution (0-3, 0,1). If none are specified, the original pod's CPUset is used. - +@@option cpuset-cpus -#### **--cpuset-mems**=*nodes* +If none are specified, the original pod's CPUset is used. -Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. +@@option cpuset-mems -If there are four memory nodes on the system (0-3), use `--cpuset-mems=0,1` -then processes in the container will only use memory from the first -two memory nodes. - -#### **--destroy** - -Remove the original pod that we are cloning once used to mimic the configuration. +@@option destroy #### **--device**=*host-device[:container-device][:permissions]* @@ -114,29 +64,19 @@ GID map for the user namespace. Using this flag will run all containers in the p Print usage statement. -#### **--hostname**=*name* - -Set a hostname to the pod. - -#### **--infra-command**=*command* +@@option hostname.pod -The command that will be run to start the infra container. Default: "/pause". +@@option infra-command -#### **--infra-conmon-pidfile**=*file* +@@option infra-conmon-pidfile -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. - -#### **--infra-name**=*name* - -The name that will be used for the pod's infra container. +@@option infra-name #### **--label**, **-l**=*label* Add metadata to a pod (e.g., --label com.example.key=value). -#### **--label-file**=*label* - -Read in a line delimited file of labels. +@@option label-file #### **--memory**, **-m**=*limit* @@ -163,13 +103,7 @@ unit, `b` is used. Set LIMIT to `-1` to enable unlimited swap. Set a custom name for the cloned pod. The default if not specified is of the syntax: **<ORIGINAL_NAME>-clone** -#### **--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) +@@option pid.pod #### **--security-opt**=*option* @@ -244,12 +178,7 @@ For the network namespace, only sysctls beginning with net.\* are allowed. Note: if the network namespace is not shared within the pod, these sysctls are not allowed. -#### **--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. +@@option uidmap.pod #### **--userns**=*mode* @@ -280,14 +209,7 @@ 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. - +@@option uts.pod #### **--volume**, **-v**=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]* diff --git a/docs/source/markdown/podman-pod-create.1.md b/docs/source/markdown/podman-pod-create.1.md.in index 7b63ac51d..73b634548 100644 --- a/docs/source/markdown/podman-pod-create.1.md +++ b/docs/source/markdown/podman-pod-create.1.md.in @@ -28,85 +28,25 @@ which by default, is the cgroup parent for all containers joining the pod. Conta ## OPTIONS -#### **--add-host**=*host:ip* +@@option add-host -Add a custom host-to-IP mapping (host:ip) - -Add a line to /etc/hosts. The format is hostname:ip. The **--add-host** -option can be set multiple times. The /etc/hosts file is shared between all containers in the pod. -#### **--blkio-weight**=*weight* - -Block IO weight (relative weight) accepts a weight value between 10 and 1000. - -#### **--blkio-weight-device**=*weight* - -Block IO weight (relative device weight, format: `DEVICE_NAME:WEIGHT`). - -#### **--cgroup-parent**=*path* - -Path to cgroups under which the cgroup for the pod will be created. If the path is not absolute, the path is considered to be relative to the cgroups path of the init process. Cgroups will be created if they do not already exist. - -#### **--cpu-shares**, **-c**=*shares* - -CPU shares (relative weight) - -By default, all containers get the same proportion of CPU cycles. This proportion -can be modified by changing the container's CPU share weighting relative -to the weighting of all other running containers. +@@option blkio-weight -To modify the proportion from the default of 1024, use the **--cpu-shares** -flag to set the weighting to 2 or higher. +@@option blkio-weight-device -The proportion will only apply when CPU-intensive processes are running. -When tasks in one container are idle, other containers can use the -left-over CPU time. The actual amount of CPU time will vary depending on -the number of containers running on the system. +@@option cgroup-parent -For example, consider three containers, one has a cpu-share of 1024 and -two others have a cpu-share setting of 512. When processes in all three -containers attempt to use 100% of CPU, the first container would receive -50% of the total CPU time. If you add a fourth container with a cpu-share -of 1024, the first container only gets 33% of the CPU. The remaining containers -receive 16.5%, 16.5% and 33% of the CPU. - -On a multi-core system, the shares of CPU time are distributed over all CPU -cores. Even if a container is limited to less than 100% of CPU time, it can -use 100% of each individual CPU core. - -For example, consider a system with more than three cores. If you start one -container **{C0}** with **-c=512** running one process, and another container -**{C1}** with **-c=1024** running two processes, this can result in the following -division of CPU shares: - -PID container CPU CPU share -100 {C0} 0 100% of CPU0 -101 {C1} 1 100% of CPU1 -102 {C1} 2 100% of CPU2 +@@option cpu-shares #### **--cpus**=*amount* Set the total number of CPUs delegated to the pod. Default is 0.000 which indicates that there is no limit on computation power. -#### **--cpuset-cpus**=*amount* - -Limit the CPUs to support execution. First CPU is numbered 0. Unlike --cpus this is of type string and parsed as a list of numbers - -Format is 0-3,0,1 - -Examples of the List Format: - -0-4,9 # bits 0, 1, 2, 3, 4, and 9 set -0-2,7,12-14 # bits 0, 1, 2, 7, 12, 13, and 14 set - -#### **--cpuset-mems**=*nodes* +@@option cpuset-cpus -Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. - -If there are four memory nodes on the system (0-3), use `--cpuset-mems=0,1` -then processes in the container will only use memory from the first -two memory nodes. +@@option cpuset-mems #### **--device**=_host-device_[**:**_container-device_][**:**_permissions_] @@ -162,29 +102,21 @@ GID map for the user namespace. Using this flag will run the container with user Print usage statement. -#### **--hostname**=*name* - -Set a hostname to the pod +@@option hostname.pod #### **--infra** Create an infra container and associate it with the pod. An infra container is a lightweight container used to coordinate the shared kernel namespace of a pod. Default: true. -#### **--infra-command**=*command* - -The command that will be run to start the infra container. Default: "/pause". +@@option infra-command -#### **--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. +@@option infra-conmon-pidfile #### **--infra-image**=*image* The custom image that will be used for the infra container. Unless specified, Podman builds a custom local image which does not require pulling down an image. -#### **--infra-name**=*name* - -The name that will be used for the pod's infra container. +@@option infra-name #### **--ip**=*ip* @@ -208,21 +140,9 @@ To specify multiple static IPv6 addresses per pod, set multiple networks using t Add metadata to a pod (e.g., --label com.example.key=value). -#### **--label-file**=*label* - -Read in a line delimited file of labels. - -#### **--mac-address**=*address* - -Pod network interface MAC address (e.g. 92:d0:c6:0a:29:33) -This option can only be used if the pod is joined to only a single network - i.e., **--network=_network-name_** is used at most once - -and if the pod is not joining another container's network namespace via **--network=container:_id_**. +@@option label-file -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 pod, set multiple networks using the **--network** option with a static MAC address specified for each using the `mac` mode for that option. +@@option mac-address #### **--memory**, **-m**=*limit* @@ -282,29 +202,13 @@ Valid _mode_ values are: Note: Rootlesskit changes the source IP address of incoming packets to an IP address in the container network namespace, usually `10.0.2.100`. If your application requires the real source IP address, e.g. web server logs, use the slirp4netns port handler. The rootlesskit port handler is also used for rootless containers when connected to user-defined networks. - **port_handler=slirp4netns**: Use the slirp4netns port forwarding, it is slower than rootlesskit but preserves the correct source IP address. This port handler cannot be used for user-defined networks. -#### **--network-alias**=*alias* - -Add a network-scoped alias for the pod, 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}} <name>`), -these aliases can be used for name resolution on the given network. This option can be specified multiple times. -NOTE: When using CNI a pod will only have access to aliases on the first network that it joins. This limitation does -not exist with netavark/aardvark-dns. +@@option network-alias -#### **--no-hosts** +@@option no-hosts -Do not create _/etc/hosts_ for the pod. -By default, Podman will manage _/etc/hosts_, adding the container's own IP address and any hosts from **--add-host**. -**--no-hosts** disables this, and the image's _/etc/hosts_ will be preserved unmodified. This option conflicts with **--add-host**. -#### **--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) +@@option pid.pod #### **--pod-id-file**=*path* @@ -335,9 +239,7 @@ but only by the pod itself. **Note:** This cannot be modified once the pod is created. -#### **--replace** - -If another pod with the same name already exists, replace and remove it. The default is **false**. +@@option replace #### **--security-opt**=*option* @@ -418,12 +320,7 @@ For the network namespace, only sysctls beginning with net.\* are allowed. Note: if the network namespace is not shared within the pod, these sysctls are not allowed. -#### **--uidmap**=*container_uid:from_uid:amount* - -Run the container 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. +@@option uidmap.pod #### **--userns**=*mode* @@ -454,13 +351,7 @@ 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. +@@option uts.pod #### **--volume**, **-v**=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]* diff --git a/docs/source/markdown/podman-pull.1.md b/docs/source/markdown/podman-pull.1.md.in index 99e227226..4321cb364 100644 --- a/docs/source/markdown/podman-pull.1.md +++ b/docs/source/markdown/podman-pull.1.md.in @@ -85,11 +85,7 @@ Print the usage statement. Override the OS, defaults to hosts, of the image to be pulled. For example, `windows`. -#### **--platform**=*OS/ARCH* - -Specify the platform for selecting the image. The `--platform` option can be used to override the current architecture and operating system. - -*IMPORTANT: Conflicts with --arch and --os* +@@option platform #### **--quiet**, **-q** diff --git a/docs/source/markdown/podman-rmi.1.md b/docs/source/markdown/podman-rmi.1.md index 8d0e5e500..93658daaf 100644 --- a/docs/source/markdown/podman-rmi.1.md +++ b/docs/source/markdown/podman-rmi.1.md @@ -28,6 +28,9 @@ This option will cause podman to remove all containers that are using the image If a specified image does not exist in the local storage, ignore it and do not throw an error. +#### **--no-prune** + +This options will not remove dangling parents of specified image Remove an image by its short ID ``` diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index df4c43c41..21ce566ce 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -83,12 +83,7 @@ and specified with a _tag_. $ podman run oci-archive:/tmp/fedora echo hello ## OPTIONS -#### **--add-host**=*host:ip* - -Add a custom host-to-IP mapping (host:ip) - -Add a line to /etc/hosts. The format is hostname:ip. The **--add-host** -option can be set multiple times. +@@option add-host #### **--annotation**=*key=value* @@ -116,49 +111,21 @@ Path to the authentication file. Default is *${XDG_RUNTIME_DIR}/containers/auth. Note: You can also override the default path of the authentication file by setting the **REGISTRY_AUTH_FILE** environment variable. -#### **--blkio-weight**=*weight* - -Block IO relative weight. The _weight_ is a value between **10** and **1000**. - -#### **--blkio-weight-device**=*device:weight* +@@option blkio-weight -Block IO relative device weight. +@@option blkio-weight-device -#### **--cap-add**=*capability* +@@option cap-add -Add Linux capabilities. - -#### **--cap-drop**=*capability* - -Drop Linux capabilities. +@@option cap-drop @@option cgroup-conf -#### **--cgroup-parent**=*path* - -Path to cgroups under which the cgroup for the container will be created. If the path is not absolute, the path is considered to be relative to the cgroups path of the init process. Cgroups will be created if they do not already exist. - -#### **--cgroupns**=*mode* +@@option cgroup-parent -Set the cgroup namespace mode for the container. +@@option cgroupns -- **host**: use the host's cgroup namespace inside the container. -- **container:**_id_: join the namespace of the specified container. -- **private**: create a new cgroup namespace. -- **ns:**_path_: join the namespace at the specified path. - -If the host uses cgroups v1, the default is set to **host**. On cgroups v2, the default is **private**. - -#### **--cgroups**=*how* - -Determines whether the container will create CGroups. - -Default is **enabled**. - -The **enabled** option will create a new cgroup under the cgroup-parent. -The **disabled** option will force the container to not create CGroups, and thus conflicts with CGroup options (**--cgroupns** and **--cgroup-parent**). -The **no-conmon** option disables a new CGroup only for the **conmon** process. -The **split** option splits the current CGroup in two sub-cgroups: one for conmon and one for the container payload. It is not possible to set **--cgroup-parent** with **split**. +@@option cgroups @@option chrootdirs @@ -166,88 +133,17 @@ The **split** option splits the current CGroup in two sub-cgroups: one for conmo Write the container ID to *file*. -#### **--conmon-pidfile**=*file* - -Write the pid of the **conmon** process to a file. As **conmon** runs in a separate process than Podman, this is necessary when using systemd to restart Podman containers. -(This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -#### **--cpu-period**=*limit* - -Set the CPU period for the Completely Fair Scheduler (CFS), which is a -duration in microseconds. Once the container's CPU quota is used up, it will -not be scheduled to run until the current period ends. Defaults to 100000 -microseconds. - -On some systems, changing the CPU limits may not be allowed for non-root -users. For more details, see -https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error - -#### **--cpu-quota**=*limit* - -Limit the CPU Completely Fair Scheduler (CFS) quota. - -Limit the container's CPU usage. By default, containers run with the full -CPU resource. The limit is a number in microseconds. If you provide a number, -the container will be allowed to use that much CPU time until the CPU period -ends (controllable via **--cpu-period**). - -On some systems, changing the CPU limits may not be allowed for non-root -users. For more details, see -https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error - -#### **--cpu-rt-period**=*microseconds* - -Limit the CPU real-time period in microseconds. - -Limit the container's Real Time CPU usage. This flag tell the kernel to restrict the container's Real Time CPU usage to the period you specify. +@@option conmon-pidfile -This flag is not supported on cgroups V2 systems. +@@option cpu-period -#### **--cpu-rt-runtime**=*microseconds* +@@option cpu-quota -Limit the CPU real-time runtime in microseconds. +@@option cpu-rt-period -Limit the containers Real Time CPU usage. This flag tells the kernel to limit the amount of time in a given CPU period Real Time tasks may consume. Ex: -Period of 1,000,000us and Runtime of 950,000us means that this container could consume 95% of available CPU and leave the remaining 5% to normal priority tasks. +@@option cpu-rt-runtime -The sum of all runtimes across containers cannot exceed the amount allotted to the parent cgroup. - -This flag is not supported on cgroups V2 systems. - -#### **--cpu-shares**, **-c**=*shares* - -CPU shares (relative weight). - -By default, all containers get the same proportion of CPU cycles. This proportion -can be modified by changing the container's CPU share weighting relative -to the combined weight of all the running containers. Default weight is **1024**. - -The proportion will only apply when CPU-intensive processes are running. -When tasks in one container are idle, other containers can use the -left-over CPU time. The actual amount of CPU time will vary depending on -the number of containers running on the system. - -For example, consider three containers, one has a cpu-share of 1024 and -two others have a cpu-share setting of 512. When processes in all three -containers attempt to use 100% of CPU, the first container would receive -50% of the total CPU time. If you add a fourth container with a cpu-share -of 1024, the first container only gets 33% of the CPU. The remaining containers -receive 16.5%, 16.5% and 33% of the CPU. - -On a multi-core system, the shares of CPU time are distributed over all CPU -cores. Even if a container is limited to less than 100% of CPU time, it can -use 100% of each individual CPU core. - -For example, consider a system with more than three cores. -If the container _C0_ is started with **--cpu-shares=512** running one process, -and another container _C1_ with **--cpu-shares=1024** running two processes, -this can result in the following division of CPU shares: - -| PID | container | CPU | CPU share | -| ---- | ----------- | ------- | ------------ | -| 100 | C0 | 0 | 100% of CPU0 | -| 101 | C1 | 1 | 100% of CPU1 | -| 102 | C1 | 2 | 100% of CPU2 | +@@option cpu-shares #### **--cpus**=*number* @@ -259,18 +155,9 @@ On some systems, changing the CPU limits may not be allowed for non-root users. For more details, see https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error -#### **--cpuset-cpus**=*number* - -CPUs in which to allow execution. Can be specified as a comma-separated list -(e.g. **0,1**), as a range (e.g. **0-3**), or any combination thereof -(e.g. **0-3,7,11-15**). - -#### **--cpuset-mems**=*nodes* - -Memory nodes (MEMs) in which to allow execution. Only effective on NUMA systems. +@@option cpuset-cpus -For example, if you have four memory nodes (0-3) on your system, use **--cpuset-mems=0,1** -to only use memory from the first two memory nodes. +@@option cpuset-mems #### **--detach**, **-d** @@ -357,23 +244,7 @@ Set custom DNS options. Invalid if using **--dns-opt** with **--network** that i Set custom DNS search domains. Invalid if using **--dns-search** and **--network** that is set to **none** or **container:**_id_. Use **--dns-search=.** if you don't wish to set the search domain. -#### **--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. +@@option entrypoint #### **--env**, **-e**=*env* @@ -389,10 +260,7 @@ Read in a line delimited file of environment variables. See **Environment** note @@option env-host -#### **--expose**=*port* - -Expose a port, or a range of ports (e.g. **--expose=3300-3310**) to set up port redirection -on the host system. +@@option expose #### **--gidmap**=*container_gid:host_gid:amount* @@ -405,42 +273,21 @@ Note: the **--gidmap** flag cannot be called in conjunction with the **--pod** f @@option group-add -#### **--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**. - -#### **--health-interval**=*interval* - -Set an interval for the healthchecks. An _interval_ of **disable** results in no automatic timer setup. The default is **30s**. - -#### **--health-retries**=*retries* +@@option health-cmd -The number of retries allowed before a healthcheck is considered to be unhealthy. The default value is **3**. +@@option health-interval -#### **--health-start-period**=*period* +@@option health-retries -The initialization time needed for a container to bootstrap. The value can be expressed in time format like -**2m3s**. The default value is **0s**. +@@option health-start-period -#### **--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**. +@@option health-timeout #### **--help** Print usage statement -#### **--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. +@@option hostname.container @@option hostuser @@ -504,27 +351,11 @@ a private IPC namespace. Add metadata to a container. -#### **--label-file**=*file* - -Read in a line-delimited file of labels. - -#### **--link-local-ip**=*ip* - -Not implemented. - -#### **--log-driver**=*driver* +@@option label-file -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. +@@option link-local-ip +@@option log-driver #### **--log-opt**=*name=value* @@ -543,17 +374,7 @@ Set custom logging configuration. The following *name*s are supported: This option is currently supported only by the **journald** log driver. -#### **--mac-address**=*address* - -Container network interface MAC address (e.g. 92:d0:c6:0a:29:33) -This option can only be used if the container is joined to only a single network - i.e., **--network=_network-name_** is used at most once - -and if the container 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 container, set multiple networks using the **--network** option with a static MAC address specified for each using the `mac` mode for that option. +@@option mac-address #### **--memory**, **-m**=*number[unit]* @@ -587,11 +408,7 @@ the value of **--memory**. Set _number_ to **-1** to enable unlimited swap. -#### **--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. +@@option memory-swappiness @@option mount @@ -643,29 +460,17 @@ Valid _mode_ values are: Note: Rootlesskit changes the source IP address of incoming packets to an IP address in the container network namespace, usually `10.0.2.100`. If your application requires the real source IP address, e.g. web server logs, use the slirp4netns port handler. The rootlesskit port handler is also used for rootless containers when connected to user-defined networks. - **port_handler=slirp4netns**: Use the slirp4netns port forwarding, it is slower than rootlesskit but preserves the correct source IP address. This port handler cannot be used for user-defined networks. -#### **--network-alias**=*alias* - -Add a network-scoped alias for the container, 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}} <name>`), -these aliases can be used for name resolution on the given network. This option can be specified multiple times. -NOTE: When using CNI a container will only have access to aliases on the first network that it joins. This limitation does -not exist with netavark/aardvark-dns. +@@option network-alias @@option no-healthcheck -#### **--no-hosts** +@@option no-hosts -Do not create _/etc/hosts_ for the container. -By default, Podman will manage _/etc/hosts_, adding the container's own IP address and any hosts from **--add-host**. -**--no-hosts** disables this, and the image's _/etc/hosts_ will be preserved unmodified. This option conflicts with **--add-host**. @@option oom-kill-disable -#### **--oom-score-adj**=*num* - -Tune the host's OOM preferences for containers (accepts values from **-1000** to **1000**). +@@option oom-score-adj #### **--os**=*OS* Override the OS, defaults to hosts, of the image to be pulled. For example, `windows`. @@ -691,14 +496,9 @@ The default is to create a private PID namespace for the container. @@option pidfile -#### **--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. +@@option pids-limit -#### **--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. +@@option platform #### **--pod**=*name* @@ -772,40 +572,19 @@ 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**=*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. +@@option pull #### **--quiet**, **-q** Suppress output information when pulling images -#### **--read-only** +@@option read-only -Mount the container's root filesystem as read-only. +@@option read-only-tmpfs -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. +@@option replace -#### **--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**. - -#### **--replace** - -If another container with the same name already exists, replace and remove it. The default is **false**. - -#### **--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. +@@option requires #### **--restart**=*policy* @@ -856,28 +635,7 @@ Note: On **SELinux** systems, the rootfs needs the correct label, which is by de @@option seccomp-policy -#### **--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. +@@option secret #### **--security-opt**=*option* @@ -921,14 +679,9 @@ When _size_ is **0**, there is no limit on the amount of memory used for IPC by Sets whether the signals sent to the **podman run** command are proxied to the container process. SIGCHLD, SIGSTOP, and SIGKILL are not proxied. The default is **true**. -#### **--stop-signal**=*signal* - -Signal to stop a container. Default is **SIGTERM**. +@@option stop-signal -#### **--stop-timeout**=*seconds* - -Timeout to stop a container. Default is **10**. -Remote connections use local containers.conf for defaults +@@option stop-timeout #### **--subgidname**=*name* @@ -1002,20 +755,7 @@ setsebool -P container_manage_cgroup true Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true, then TLS verification will be used. If set to false, then TLS verification will not be used. If not specified, TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf. -#### **--tmpfs**=*fs* - -Create a tmpfs mount. - -Mount a temporary filesystem (**tmpfs**) mount into a container, for example: - -``` -$ podman run -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**. +@@option tmpfs #### **--tty**, **-t** @@ -1033,97 +773,13 @@ echo "asdf" | podman run --rm -i someimage /bin/cat @@option tz -#### **--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 run** 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 run** 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: +@@option uidmap.container -| 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 run --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. - -#### **--ulimit**=*option* - -Ulimit options. You can use **host** to copy the current configuration from the host. +@@option ulimit @@option umask -#### **--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. +@@option unsetenv @@option unsetenv-all @@ -1179,14 +835,7 @@ The rootless option `--userns=keep-id` uses all the subuids and subgids of the u **private**: create a new namespace for the container. This option is incompatible with **--gidmap**, **--uidmap**, **--subuidname** and **--subgidname**. -#### **--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. +@@option uts.container #### **--variant**=*VARIANT* Use _VARIANT_ instead of the default architecture variant of the container image. Some images can use multiple variants of the arm architectures, such as arm/v5 and arm/v7. diff --git a/docs/source/markdown/podman.1.md b/docs/source/markdown/podman.1.md index 4c019ae97..d1192b6d2 100644 --- a/docs/source/markdown/podman.1.md +++ b/docs/source/markdown/podman.1.md @@ -133,6 +133,12 @@ for cgroup V2, the default runtime is `crun`, the manpage to consult is `crun(8) Note: Do not pass the leading `--` to the flag. To pass the runc flag `--log-format json` to podman build, the option given would be `--runtime-flag log-format=json`. + +#### **--ssh**=*value* + +This option allows the user to change the ssh mode, meaning that rather than using the default **golang** mode, one can instead use **--ssh=native** +to use the installed ssh binary and config file declared in containers.conf. + #### **--storage-driver**=*value* Storage driver. The default storage driver for UID 0 is configured in /etc/containers/storage.conf (`$HOME/.config/containers/storage.conf` in rootless mode), and is *vfs* for non-root users when *fuse-overlayfs* is not available. The `STORAGE_DRIVER` environment variable overrides the default. The --storage-driver specified driver overrides all. diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md index 2cdb86fa0..69f55673d 100644 --- a/docs/tutorials/README.md +++ b/docs/tutorials/README.md @@ -1,4 +1,4 @@ - + # Podman Tutorials diff --git a/docs/tutorials/basic_networking.md b/docs/tutorials/basic_networking.md index 05c3a731e..7ffc8bcd3 100644 --- a/docs/tutorials/basic_networking.md +++ b/docs/tutorials/basic_networking.md @@ -1,4 +1,4 @@ - + # Basic Networking Guide for Podman diff --git a/docs/tutorials/podman-derivative-api.md b/docs/tutorials/podman-derivative-api.md index e38c2b13d..9de355883 100644 --- a/docs/tutorials/podman-derivative-api.md +++ b/docs/tutorials/podman-derivative-api.md @@ -1,4 +1,4 @@ - + # How to use libpod for custom/derivative projects diff --git a/docs/tutorials/podman-for-windows.md b/docs/tutorials/podman-for-windows.md index 48f9c1ab5..bb37f4a48 100644 --- a/docs/tutorials/podman-for-windows.md +++ b/docs/tutorials/podman-for-windows.md @@ -1,4 +1,4 @@ - + Podman for Windows ================== diff --git a/docs/tutorials/podman_tutorial.md b/docs/tutorials/podman_tutorial.md index a371189e9..e978d0fb2 100644 --- a/docs/tutorials/podman_tutorial.md +++ b/docs/tutorials/podman_tutorial.md @@ -1,4 +1,4 @@ - + # Basic Setup and Use of Podman Podman is a utility provided as part of the libpod library. It can be used to create and maintain diff --git a/docs/tutorials/podman_tutorial_cn.md b/docs/tutorials/podman_tutorial_cn.md index 36e83e16f..37608dddd 100644 --- a/docs/tutorials/podman_tutorial_cn.md +++ b/docs/tutorials/podman_tutorial_cn.md @@ -1,6 +1,6 @@ > - 译文出自：[掘金翻译计划](https://juejin.cn/translate) - + Podman是由libpod库提供一个实用的程序，可以被用于创建和管理容器。 diff --git a/docs/tutorials/rootless_tutorial.md b/docs/tutorials/rootless_tutorial.md index d9cf68a20..67434ed3c 100644 --- a/docs/tutorials/rootless_tutorial.md +++ b/docs/tutorials/rootless_tutorial.md @@ -1,4 +1,4 @@ - + # Basic Setup and Use of Podman in a Rootless environment. |