diff options
Diffstat (limited to 'docs/source')
45 files changed, 225 insertions, 204 deletions
diff --git a/docs/source/markdown/.gitignore b/docs/source/markdown/.gitignore index 5a30aab78..85aed3be0 100644 --- a/docs/source/markdown/.gitignore +++ b/docs/source/markdown/.gitignore @@ -3,6 +3,7 @@ podman-build.1.md podman-container-clone.1.md podman-container-runlabel.1.md podman-create.1.md +podman-exec.1.md podman-image-sign.1.md podman-kill.1.md podman-kube-play.1.md @@ -13,6 +14,9 @@ podman-manifest-push.1.md podman-pause.1.md podman-pod-clone.1.md podman-pod-create.1.md +podman-pod-rm.1.md +podman-pod-start.1.md +podman-pod-stop.1.md podman-pull.1.md podman-push.1.md podman-rm.1.md diff --git a/docs/source/markdown/options/annotation.container.md b/docs/source/markdown/options/annotation.container.md index bd561a15f..0d155e5e4 100644 --- a/docs/source/markdown/options/annotation.container.md +++ b/docs/source/markdown/options/annotation.container.md @@ -1,3 +1,3 @@ #### **--annotation**=*key=value* -Add an annotation to the container<| or pod>. This option can be set multiple times. +Add an annotation to the container<<| or pod>>. This option can be set multiple times. diff --git a/docs/source/markdown/options/blkio-weight.md b/docs/source/markdown/options/blkio-weight.md index eb8e94144..04a1071c0 100644 --- a/docs/source/markdown/options/blkio-weight.md +++ b/docs/source/markdown/options/blkio-weight.md @@ -1,3 +1,5 @@ #### **--blkio-weight**=*weight* Block IO relative weight. The _weight_ is a value between **10** and **1000**. + +This option is not supported on cgroups V1 rootless systems. diff --git a/docs/source/markdown/options/cpu-period.md b/docs/source/markdown/options/cpu-period.md index efbe6c2ab..5c5eb56e7 100644 --- a/docs/source/markdown/options/cpu-period.md +++ b/docs/source/markdown/options/cpu-period.md @@ -8,3 +8,5 @@ microseconds. On some systems, changing the resource 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-resource-limits-fails-with-a-permissions-error + +This option is not supported on cgroups V1 rootless systems. diff --git a/docs/source/markdown/options/cpu-quota.md b/docs/source/markdown/options/cpu-quota.md index 753797bad..81d5db3d2 100644 --- a/docs/source/markdown/options/cpu-quota.md +++ b/docs/source/markdown/options/cpu-quota.md @@ -10,3 +10,5 @@ ends (controllable via **--cpu-period**). On some systems, changing the resource 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-resource-limits-fails-with-a-permissions-error + +This option is not supported on cgroups V1 rootless systems. diff --git a/docs/source/markdown/options/cpu-rt-period.md b/docs/source/markdown/options/cpu-rt-period.md index 9014beb33..36e88632e 100644 --- a/docs/source/markdown/options/cpu-rt-period.md +++ b/docs/source/markdown/options/cpu-rt-period.md @@ -4,4 +4,4 @@ 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. +This option is only supported on cgroups V1 rootful systems. diff --git a/docs/source/markdown/options/cpu-rt-runtime.md b/docs/source/markdown/options/cpu-rt-runtime.md index 05b1d3b96..64f0ec38b 100644 --- a/docs/source/markdown/options/cpu-rt-runtime.md +++ b/docs/source/markdown/options/cpu-rt-runtime.md @@ -7,4 +7,4 @@ Period of 1,000,000us and Runtime of 950,000us means that this container could c 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. +This option is only supported on cgroups V1 rootful systems. diff --git a/docs/source/markdown/options/cpu-shares.md b/docs/source/markdown/options/cpu-shares.md index c2115c1bf..c0e2c3035 100644 --- a/docs/source/markdown/options/cpu-shares.md +++ b/docs/source/markdown/options/cpu-shares.md @@ -37,3 +37,5 @@ this can result in the following division of CPU shares: On some systems, changing the resource 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-resource-limits-fails-with-a-permissions-error + +This option is not supported on cgroups V1 rootless systems. diff --git a/docs/source/markdown/options/cpus.container.md b/docs/source/markdown/options/cpus.container.md new file mode 100644 index 000000000..63f243e11 --- /dev/null +++ b/docs/source/markdown/options/cpus.container.md @@ -0,0 +1,11 @@ +#### **--cpus**=*number* + +Number of CPUs. The default is *0.0* which means no limit. This is shorthand +for **--cpu-period** and **--cpu-quota**, so you may only set either +**--cpus** or **--cpu-period** and **--cpu-quota**. + +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-resource-limits-fails-with-a-permissions-error + +This option is not supported on cgroups V1 rootless systems. diff --git a/docs/source/markdown/options/cpuset-cpus.md b/docs/source/markdown/options/cpuset-cpus.md index a67766897..8a2a82e9f 100644 --- a/docs/source/markdown/options/cpuset-cpus.md +++ b/docs/source/markdown/options/cpuset-cpus.md @@ -7,3 +7,5 @@ CPUs in which to allow execution. Can be specified as a comma-separated list On some systems, changing the resource 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-resource-limits-fails-with-a-permissions-error + +This option is not supported on cgroups V1 rootless systems. diff --git a/docs/source/markdown/options/cpuset-mems.md b/docs/source/markdown/options/cpuset-mems.md index 1eeab7b13..b86d0ef6b 100644 --- a/docs/source/markdown/options/cpuset-mems.md +++ b/docs/source/markdown/options/cpuset-mems.md @@ -10,3 +10,5 @@ two memory nodes. On some systems, changing the resource 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-resource-limits-fails-with-a-permissions-error + +This option is not supported on cgroups V1 rootless systems. diff --git a/docs/source/markdown/options/device-cgroup-rule.md b/docs/source/markdown/options/device-cgroup-rule.md new file mode 100644 index 000000000..0ba3d4668 --- /dev/null +++ b/docs/source/markdown/options/device-cgroup-rule.md @@ -0,0 +1,6 @@ +#### **--device-cgroup-rule**=*"type major:minor mode"* + +Add a rule to the cgroup allowed devices list. The rule is expected to be in the format specified in the Linux kernel documentation (Documentation/cgroup-v1/devices.txt): + - type: a (all), c (char), or b (block); + - major and minor: either a number, or * for all; + - mode: a composition of r (read), w (write), and m (mknod(2)). diff --git a/docs/source/markdown/options/disable-content-trust.md b/docs/source/markdown/options/disable-content-trust.md new file mode 100644 index 000000000..a2d1d8ad7 --- /dev/null +++ b/docs/source/markdown/options/disable-content-trust.md @@ -0,0 +1,5 @@ +#### **--disable-content-trust** + +This is a Docker-specific option to disable image verification to a container +registry and is not supported by Podman. This option is a NOOP and provided +solely for scripting compatibility. diff --git a/docs/source/markdown/options/env-merge.md b/docs/source/markdown/options/env-merge.md new file mode 100644 index 000000000..aa1aa003d --- /dev/null +++ b/docs/source/markdown/options/env-merge.md @@ -0,0 +1,5 @@ +#### **--env-merge**=*env* + +Preprocess default environment variables for the containers. For example +if image contains environment variable `hello=world` user can preprocess +it using `--env-merge hello=${hello}-some` so new value will be `hello=world-some`. diff --git a/docs/source/markdown/options/gidmap.container.md b/docs/source/markdown/options/gidmap.container.md new file mode 100644 index 000000000..a3c9df33d --- /dev/null +++ b/docs/source/markdown/options/gidmap.container.md @@ -0,0 +1,8 @@ +#### **--gidmap**=*container_gid:host_gid:amount* + +Run the container in a new user namespace using the supplied GID mapping. This +option conflicts with the **--userns** and **--subgidname** options. This +option provides a way to map host GIDs to container GIDs in the same way as +__--uidmap__ maps host UIDs to container UIDs. For details see __--uidmap__. + +Note: the **--gidmap** flag cannot be called in conjunction with the **--pod** flag as a gidmap cannot be set on the container level when in a pod. diff --git a/docs/source/markdown/options/gidmap.pod.md b/docs/source/markdown/options/gidmap.pod.md new file mode 100644 index 000000000..0d58cc527 --- /dev/null +++ b/docs/source/markdown/options/gidmap.pod.md @@ -0,0 +1,4 @@ +#### **--gidmap**=*pod_gid:host_gid:amount* + +GID map for the user namespace. Using this flag will run all containers in the pod with user namespace enabled. +It conflicts with the **--userns** and **--subgidname** flags. diff --git a/docs/source/markdown/options/ignore.md b/docs/source/markdown/options/ignore.md new file mode 100644 index 000000000..231d75957 --- /dev/null +++ b/docs/source/markdown/options/ignore.md @@ -0,0 +1,5 @@ +#### **--ignore**, **-i** + +Ignore errors when specified <<containers|pods>> are not in the container store. A user +might have decided to manually remove a <<container|pod>> which would lead to a failure +during the ExecStop directive of a systemd service referencing that <<container|pod>>. diff --git a/docs/source/markdown/options/ipc.md b/docs/source/markdown/options/ipc.md new file mode 100644 index 000000000..699b64eec --- /dev/null +++ b/docs/source/markdown/options/ipc.md @@ -0,0 +1,12 @@ +#### **--ipc**=*ipc* + +Set the IPC namespace mode for a container. The default is to create +a private IPC namespace. + +- "": Use Podman's default, defined in containers.conf. +- **container:**_id_: reuses another container's shared memory, semaphores, and message queues +- **host**: use the host's shared memory, semaphores, and message queues inside the container. Note: the host mode gives the container full access to local shared memory and is therefore considered insecure. +- **none**: private IPC namespace, with /dev/shm not mounted. +- **ns:**_path_: path to an IPC namespace to join. +- **private**: private IPC namespace. += **shareable**: private IPC namespace with a possibility to share it with other containers. diff --git a/docs/source/markdown/options/memory-swappiness.md b/docs/source/markdown/options/memory-swappiness.md index 65f0ef310..1e6a51188 100644 --- a/docs/source/markdown/options/memory-swappiness.md +++ b/docs/source/markdown/options/memory-swappiness.md @@ -2,4 +2,4 @@ Tune a container's memory swappiness behavior. Accepts an integer between *0* and *100*. -This flag is not supported on cgroups V2 systems. +This flag is only supported on cgroups V1 rootful systems. diff --git a/docs/source/markdown/options/pid.md b/docs/source/markdown/options/pid.md new file mode 100644 index 000000000..d0cbef1d5 --- /dev/null +++ b/docs/source/markdown/options/pid.md @@ -0,0 +1,9 @@ +#### **--pid**=*mode* + +Set the PID namespace mode for the container. +The default is to create a private PID namespace for the container. + +- **container:**_id_: join another container's PID namespace; +- **host**: use the host's PID namespace for the container. Note the host mode gives the container full access to local PID and is therefore considered insecure; +- **ns:**_path_: join the specified PID namespace; +- **private**: create a new namespace for the container (default). diff --git a/docs/source/markdown/options/pod-id-file.container.md b/docs/source/markdown/options/pod-id-file.container.md new file mode 100644 index 000000000..1c102dc6b --- /dev/null +++ b/docs/source/markdown/options/pod-id-file.container.md @@ -0,0 +1,4 @@ +#### **--pod-id-file**=*file* + +Run container in an existing pod and read the pod's ID from the specified *file*. +If a container is run within a pod, and the pod has an infra-container, the infra-container will be started before the container is. diff --git a/docs/source/markdown/options/pod-id-file.pod.md b/docs/source/markdown/options/pod-id-file.pod.md new file mode 100644 index 000000000..69e2ac6e9 --- /dev/null +++ b/docs/source/markdown/options/pod-id-file.pod.md @@ -0,0 +1,3 @@ +#### **--pod-id-file**=*file* + +Read pod ID from the specified *file* and <<subcommand>> the pod. Can be specified multiple times. diff --git a/docs/source/markdown/options/workdir.md b/docs/source/markdown/options/workdir.md new file mode 100644 index 000000000..12f3ddd44 --- /dev/null +++ b/docs/source/markdown/options/workdir.md @@ -0,0 +1,7 @@ +#### **--workdir**, **-w**=*dir* + +Working directory inside the container. + +The default working directory for running binaries within a container is the root directory (**/**). +The image developer can set a different default with the WORKDIR instruction. The operator +can override the working directory by using the **-w** option. diff --git a/docs/source/markdown/podman-build.1.md.in b/docs/source/markdown/podman-build.1.md.in index dab705f94..693e0d3b9 100644 --- a/docs/source/markdown/podman-build.1.md.in +++ b/docs/source/markdown/podman-build.1.md.in @@ -230,11 +230,7 @@ registries, and images being written to local storage would only need to be decompressed again to be stored. Compression can be forced in all cases by specifying **--disable-compression=false**. -#### **--disable-content-trust** - -This is a Docker specific option to disable image verification to a container -registry and is not supported by Podman. This option is a NOOP and provided -solely for scripting compatibility. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) +@@option disable-content-trust #### **--dns**=*dns* @@ -297,6 +293,12 @@ environment variable. `export BUILDAH_FORMAT=docker` Overrides the first `FROM` instruction within the Containerfile. If there are multiple FROM instructions in a Containerfile, only the first is changed. +With the remote podman client, not all container transports will work as +expected. For example, oci-archive:/x.tar will reference /x.tar on the remote +machine instead of on the client. If you need to support remote podman clients, +it is best to restrict yourself to containers-storage: and docker:// +transports. + #### **--help**, **-h** Print usage statement diff --git a/docs/source/markdown/podman-container-clone.1.md.in b/docs/source/markdown/podman-container-clone.1.md.in index cf760d7a2..26f414b62 100644 --- a/docs/source/markdown/podman-container-clone.1.md.in +++ b/docs/source/markdown/podman-container-clone.1.md.in @@ -40,6 +40,8 @@ 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. +This option is not supported on cgroups V1 rootless systems. + @@option cpuset-cpus If none are specified, the original container's CPUset is used. @@ -54,10 +56,14 @@ If none are specified, the original container's CPU memory nodes are used. Limit read rate (bytes per second) from a device (e.g. --device-read-bps=/dev/sda:1mb). +This option is not supported on cgroups V1 rootless systems. + #### **--device-write-bps**=*path* Limit write rate (bytes per second) to a device (e.g. --device-write-bps=/dev/sda:1mb) +This option is not supported on cgroups V1 rootless systems. + #### **--force**, **-f** Force removal of the original container that we are cloning. Can only be used in conjunction with **--destroy**. @@ -74,6 +80,8 @@ system's page size (the value would be very large, that's millions of trillions) If no memory limits are specified, the original container's will be used. +This option is not supported on cgroups V1 rootless systems. + #### **--memory-reservation**=*limit* Memory soft limit (format: `<number>[<unit>]`, where unit = b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes)) @@ -84,6 +92,8 @@ reservation. So you should always set the value below **--memory**, otherwise th hard limit will take precedence. By default, memory reservation will be the same as memory limit from the container being cloned. +This option is not supported on cgroups V1 rootless systems. + #### **--memory-swap**=*limit* A limit value equal to memory plus swap. Must be used with the **-m** @@ -95,6 +105,8 @@ 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. +This option is not supported on cgroups V1 rootless systems. + @@option memory-swappiness #### **--name** diff --git a/docs/source/markdown/podman-container-runlabel.1.md.in b/docs/source/markdown/podman-container-runlabel.1.md.in index 59eb48fd3..f5fb8ca60 100644 --- a/docs/source/markdown/podman-container-runlabel.1.md.in +++ b/docs/source/markdown/podman-container-runlabel.1.md.in @@ -32,10 +32,7 @@ Will be replaced with the current working directory. @@option authfile -#### **--cert-dir**=*path* - -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) +@@option cert-dir @@option creds diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index 2827964f7..4dbc75551 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -119,15 +119,7 @@ Block IO relative device weight. @@option cpu-shares -#### **--cpus**=*number* - -Number of CPUs. The default is *0.0* which means no limit. This is shorthand -for **--cpu-period** and **--cpu-quota**, so you may only set either -**--cpus** or **--cpu-period** and **--cpu-quota**. - -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 +@@option cpus.container @@option cpuset-cpus @@ -152,34 +144,33 @@ Podman may load kernel modules required for using the specified device. The devices that podman will load modules when necessary are: /dev/fuse. -#### **--device-cgroup-rule**=*"type major:minor mode"* - -Add a rule to the cgroup allowed devices list. The rule is expected to be in the format specified in the Linux kernel documentation (Documentation/cgroup-v1/devices.txt): - - type: a (all), c (char), or b (block); - - major and minor: either a number, or * for all; - - mode: a composition of r (read), w (write), and m (mknod(2)). +@@option device-cgroup-rule #### **--device-read-bps**=*path* Limit read rate (bytes per second) from a device (e.g. --device-read-bps=/dev/sda:1mb) +This option is not supported on cgroups V1 rootless systems. + #### **--device-read-iops**=*path* Limit read rate (IO per second) from a device (e.g. --device-read-iops=/dev/sda:1000) +This option is not supported on cgroups V1 rootless systems. + #### **--device-write-bps**=*path* Limit write rate (bytes per second) to a device (e.g. --device-write-bps=/dev/sda:1mb) +This option is not supported on cgroups V1 rootless systems. + #### **--device-write-iops**=*path* Limit write rate (IO per second) to a device (e.g. --device-write-iops=/dev/sda:1000) -#### **--disable-content-trust** +This option is not supported on cgroups V1 rootless systems. -This is a Docker specific option to disable image verification to a Docker -registry and is not supported by Podman. This flag is a NOOP and provided -solely for scripting compatibility. +@@option disable-content-trust #### **--dns**=*dns* @@ -217,16 +208,11 @@ Read in a line delimited file of environment variables. See **Environment** note @@option env-host -@@option expose - -#### **--gidmap**=*container_gid:host_gid:amount* +@@option env-merge -Run the container in a new user namespace using the supplied GID mapping. This -option conflicts with the **--userns** and **--subgidname** options. This -option provides a way to map host GIDs to container GIDs in the same way as -__--uidmap__ maps host UIDs to container UIDs. For details see __--uidmap__. +@@option expose -Note: the **--gidmap** flag cannot be called in conjunction with the **--pod** flag as a gidmap cannot be set on the container level when in a pod. +@@option gidmap.container @@option group-add @@ -312,18 +298,7 @@ The address must be within the network's IPv6 address pool. To specify multiple static IPv6 addresses per container, set multiple networks using the **--network** option with a static IPv6 address specified for each using the `ip6` mode for that option. -#### **--ipc**=*ipc* - -Set the IPC namespace mode for a container. The default is to create -a private IPC namespace. - -- "": Use Podman's default, defined in containers.conf. -- **container:**_id_: reuses another container's shared memory, semaphores, and message queues -- **host**: use the host's shared memory, semaphores, and message queues inside the container. Note: the host mode gives the container full access to local shared memory and is therefore considered insecure. -- **none**: private IPC namespace, with /dev/shm not mounted. -- **ns:**_path_: path to an IPC namespace to join. -- **private**: private IPC namespace. -= **shareable**: private IPC namespace with a possibility to share it with other containers. +@@option ipc #### **--label**, **-l**=*label* @@ -364,6 +339,8 @@ RAM. If a limit of 0 is specified (not using **-m**), the container's memory is not limited. The actual limit may be rounded up to a multiple of the operating system's page size (the value would be very large, that's millions of trillions). +This option is not supported on cgroups V1 rootless systems. + #### **--memory-reservation**=*limit* Memory soft limit (format: `<number>[<unit>]`, where unit = b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes)) @@ -374,6 +351,8 @@ reservation. So you should always set the value below **--memory**, otherwise th hard limit will take precedence. By default, memory reservation will be the same as memory limit. +This option is not supported on cgroups V1 rootless systems. + #### **--memory-swap**=*limit* A limit value equal to memory plus swap. Must be used with the **-m** @@ -385,6 +364,8 @@ 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. +This option is not supported on cgroups V1 rootless systems. + @@option memory-swappiness @@option mount @@ -456,14 +437,7 @@ Unless overridden, subsequent lookups of the same image in the local storage wil @@option personality -#### **--pid**=*pid* - -Set the PID mode for the container -Default is to create a private PID namespace for the container -- `container:<name|id>`: join another container's PID namespace -- `host`: use the host's PID namespace for the container. Note: the host mode gives the container full access to local PID and is therefore considered insecure. -- `ns`: join the specified PID namespace -- `private`: create a new namespace for the container (default) +@@option pid @@option pidfile @@ -476,9 +450,7 @@ Default is to create a private PID namespace for the container Run container in an existing pod. If you want Podman to make the pod for you, preference the pod name with `new:`. To make a pod with more granular options, use the `podman pod create` command before creating a container. -#### **--pod-id-file**=*path* - -Run container in an existing pod and read the pod's ID from the specified file. If a container is run within a pod, and the pod has an infra-container, the infra-container will be started before the container is. +@@option pod-id-file.container #### **--privileged** @@ -980,13 +952,7 @@ If the location of the volume from the source container overlaps with data residing on a target container, then the volume hides that data on the target. -#### **--workdir**, **-w**=*dir* - -Working directory inside the container - -The default working directory for running binaries within a container is the root directory (/). -The image developer can set a different default with the WORKDIR instruction. The operator -can override the working directory by using the **-w** option. +@@option workdir ## EXAMPLES diff --git a/docs/source/markdown/podman-exec.1.md b/docs/source/markdown/podman-exec.1.md.in index da61f3456..4f78f1c31 100644 --- a/docs/source/markdown/podman-exec.1.md +++ b/docs/source/markdown/podman-exec.1.md.in @@ -70,13 +70,7 @@ Sets the username or UID used and optionally the groupname or GID for the specif The following examples are all valid: --user [user | user:group | uid | uid:gid | user:gid | uid:group ] -#### **--workdir**, **-w**=*path* - -Working directory inside the container - -The default working directory for running binaries within a container is the root directory (/). -The image developer can set a different default with the WORKDIR instruction, which can be overridden -when creating the container. +@@option workdir ## Exit Status diff --git a/docs/source/markdown/podman-image-sign.1.md.in b/docs/source/markdown/podman-image-sign.1.md.in index 340cdbd21..d5efabc1a 100644 --- a/docs/source/markdown/podman-image-sign.1.md.in +++ b/docs/source/markdown/podman-image-sign.1.md.in @@ -21,10 +21,7 @@ Sign all the manifests of the multi-architecture image (default false). @@option authfile -#### **--cert-dir**=*path* - -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) +@@option cert-dir #### **--directory**, **-d**=*dir* diff --git a/docs/source/markdown/podman-kube-down.1.md b/docs/source/markdown/podman-kube-down.1.md index 92abd4ba3..c345abbd1 100644 --- a/docs/source/markdown/podman-kube-down.1.md +++ b/docs/source/markdown/podman-kube-down.1.md @@ -4,10 +4,14 @@ podman-kube-down - Remove containers and pods based on Kubernetes YAML ## SYNOPSIS -**podman kube down** *file.yml|-* +**podman kube down** *file.yml|-|https://website.io/file.yml* ## DESCRIPTION -**podman kube down** reads a specified Kubernetes YAML file, tearing down pods that were created by the `podman kube play` command via the same Kubernetes YAML file. Any volumes that were created by the previous `podman kube play` command remain intact. If the YAML file is specified as `-`, `podman kube down` reads the YAML from stdin. +**podman kube down** reads a specified Kubernetes YAML file, tearing down pods that were created by the `podman kube play` command via the same Kubernetes YAML +file. Any volumes that were created by the previous `podman kube play` command remain intact. If the YAML file is specified as `-`, `podman kube down` reads the +YAML from stdin. The input can also be a URL that points to a YAML file such as https://podman.io/demo.yml. `podman kube down` will then teardown the pods and +containers created by `podman kube play` via the same Kubernetes YAML from the URL. However, `podman kube down` will not work with a URL if the YAML file the URL +points to has been changed or altered since the creation of the pods and containers using `podman kube play`. ## EXAMPLES @@ -30,14 +34,31 @@ spec: Remove the pod and containers as described in the `demo.yml` file ``` $ podman kube down demo.yml +Pods stopped: +52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6 +Pods removed: 52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6 ``` -Remove the pod and containers as described in the`demo.yml` file YAML sent to stdin +Remove the pod and containers as described in the `demo.yml` file YAML sent to stdin ``` $ cat demo.yml | podman kube play - +Pods stopped: +52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6 +Pods removed: +52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6 +``` + +Remove the pods and containers as described in the `demo.yml` file YAML read from a URL +``` +$ podman kube down https://podman.io/demo.yml +Pods stopped: +52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6 +Pods removed: 52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6 ``` +`podman kube down` will not work with a URL if the YAML file the URL points to has been changed +or altered since it was used to create the pods and containers. ## SEE ALSO **[podman(1)](podman.1.md)**, **[podman-kube(1)](podman-kube.1.md)**, **[podman-kube-play(1)](podman-kube-play.1.md)**, **[podman-kube-generate(1)](podman-kube-generate.1.md)**, **[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)** diff --git a/docs/source/markdown/podman-kube-play.1.md.in b/docs/source/markdown/podman-kube-play.1.md.in index 1b9544fb6..f0b404057 100644 --- a/docs/source/markdown/podman-kube-play.1.md.in +++ b/docs/source/markdown/podman-kube-play.1.md.in @@ -4,13 +4,14 @@ podman-kube-play - Create containers, pods and volumes based on Kubernetes YAML ## SYNOPSIS -**podman kube play** [*options*] *file.yml|-* +**podman kube play** [*options*] *file.yml|-|https://website.io/file.yml* ## DESCRIPTION **podman kube play** will read in a structured file of Kubernetes YAML. It will then recreate the containers, pods or volumes described in the YAML. Containers within a pod are then started and the ID of the new Pod or the name of the new Volume is output. If the yaml file is specified as "-" then `podman kube play` will read the YAML file from stdin. Using the `--down` command line option, it is also capable of tearing down the pods created by a previous run of `podman kube play`. Using the `--replace` command line option, it will tear down the pods(if any) created by a previous run of `podman kube play` and recreate the pods with the Kubernetes YAML file. Ideally the input file would be one created by Podman (see podman-kube-generate(1)). This would guarantee a smooth import and expected results. +The input can also be a URL that points to a YAML file such as https://podman.io/demo.yml. `podman kube play` will read the YAML from the URL and create pods and containers from it. Currently, the supported Kubernetes kinds are: - Pod @@ -300,8 +301,23 @@ Create a pod connected to two networks (called net1 and net2) with a static ip $ podman kube play demo.yml --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10 52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6 ``` - Please take into account that networks must be created first using podman-network-create(1). +Create and teardown from a URL pointing to a YAML file +``` +$ podman kube play https://podman.io/demo.yml +52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6 + +$ podman kube play --down https://podman.io/demo.yml +Pods stopped: +52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6 +Pods removed: +52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6 +``` +`podman kube play --down` will not work with a URL if the YAML file the URL points to +has been changed or altered. + + + ## SEE ALSO **[podman(1)](podman.1.md)**, **[podman-kube(1)](podman-kube.1.md)**, **[podman-kube-down(1)](podman-kube-down.1.md)**, **[podman-network-create(1)](podman-network-create.1.md)**, **[podman-kube-generate(1)](podman-kube-generate.1.md)**, **[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)** diff --git a/docs/source/markdown/podman-login.1.md.in b/docs/source/markdown/podman-login.1.md.in index 6ec207a1e..4537988eb 100644 --- a/docs/source/markdown/podman-login.1.md.in +++ b/docs/source/markdown/podman-login.1.md.in @@ -30,10 +30,7 @@ For more details about format and configurations of the auth.json file, please r @@option authfile -#### **--cert-dir**=*path* - -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) +@@option cert-dir #### **--get-login** diff --git a/docs/source/markdown/podman-manifest-add.1.md.in b/docs/source/markdown/podman-manifest-add.1.md.in index adffe1875..e82c04985 100644 --- a/docs/source/markdown/podman-manifest-add.1.md.in +++ b/docs/source/markdown/podman-manifest-add.1.md.in @@ -35,10 +35,7 @@ retrieved from the image's configuration information. @@option authfile -#### **--cert-dir**=*path* - -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) +@@option cert-dir @@option creds diff --git a/docs/source/markdown/podman-manifest-push.1.md.in b/docs/source/markdown/podman-manifest-push.1.md.in index 515f07207..88d070c3f 100644 --- a/docs/source/markdown/podman-manifest-push.1.md.in +++ b/docs/source/markdown/podman-manifest-push.1.md.in @@ -21,10 +21,7 @@ the list or index itself. (Default true) @@option authfile -#### **--cert-dir**=*path* - -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) +@@option cert-dir #### **--compression-format**=**gzip** | *zstd* | *zstd:chunked* diff --git a/docs/source/markdown/podman-pod-clone.1.md.in b/docs/source/markdown/podman-pod-clone.1.md.in index a5746fd84..c040f1c27 100644 --- a/docs/source/markdown/podman-pod-clone.1.md.in +++ b/docs/source/markdown/podman-pod-clone.1.md.in @@ -56,9 +56,7 @@ Limit read rate (bytes per second) from a device (e.g. --device-read-bps=/dev/sd Limit write rate (bytes per second) to a device (e.g. --device-write-bps=/dev/sda:1mb) -#### **--gidmap**=*pod_gid:host_gid:amount* - -GID map for the user namespace. Using this flag will run all containers in the pod with user namespace enabled. It conflicts with the `--userns` and `--subgidname` flags. +@@option gidmap.pod #### **--help**, **-h** diff --git a/docs/source/markdown/podman-pod-create.1.md.in b/docs/source/markdown/podman-pod-create.1.md.in index c12f296b4..702780c65 100644 --- a/docs/source/markdown/podman-pod-create.1.md.in +++ b/docs/source/markdown/podman-pod-create.1.md.in @@ -94,9 +94,7 @@ Set the exit policy of the pod when the last container exits. Supported policie | *continue* | The pod continues running, by keeping its infra container alive, when the last container exits. Used by default. | | *stop* | The pod (including its infra container) is stopped when the last container exits. Used in `kube play`. | -#### **--gidmap**=*container_gid:host_gid:amount* - -GID map for the user namespace. Using this flag will run the container with user namespace enabled. It conflicts with the `--userns` and `--subgidname` flags. +@@option gidmap.pod #### **--help**, **-h** diff --git a/docs/source/markdown/podman-pod-rm.1.md b/docs/source/markdown/podman-pod-rm.1.md.in index befab6791..82e28acb1 100644 --- a/docs/source/markdown/podman-pod-rm.1.md +++ b/docs/source/markdown/podman-pod-rm.1.md.in @@ -19,19 +19,13 @@ Remove all pods. Can be used in conjunction with \-f as well. Stop running containers and delete all stopped containers before removal of pod. -#### **--ignore**, **-i** - -Ignore errors when specified pods are not in the container store. A user might -have decided to manually remove a pod which would lead to a failure during the -ExecStop directive of a systemd service referencing that pod. +@@option ignore #### **--latest**, **-l** Instead of providing the pod name or ID, remove the last created pod. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) -#### **--pod-id-file** - -Read pod ID from the specified file and remove the pod. Can be specified multiple times. +@@option pod-id-file.pod #### **--time**, **-t**=*seconds* diff --git a/docs/source/markdown/podman-pod-start.1.md b/docs/source/markdown/podman-pod-start.1.md.in index 45fc50c51..6a47ce1b9 100644 --- a/docs/source/markdown/podman-pod-start.1.md +++ b/docs/source/markdown/podman-pod-start.1.md.in @@ -20,9 +20,7 @@ Starts all pods Instead of providing the pod name or ID, start the last created pod. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) -#### **--pod-id-file** - -Read pod ID from the specified file and start the pod. Can be specified multiple times. +@@option pod-id-file.pod ## EXAMPLE diff --git a/docs/source/markdown/podman-pod-stop.1.md b/docs/source/markdown/podman-pod-stop.1.md.in index bded0ba7d..3655c3938 100644 --- a/docs/source/markdown/podman-pod-stop.1.md +++ b/docs/source/markdown/podman-pod-stop.1.md.in @@ -15,19 +15,13 @@ Stop containers in one or more pods. You may use pod IDs or names as input. Stops all pods -#### **--ignore**, **-i** - -Ignore errors when specified pods are not in the container store. A user might -have decided to manually remove a pod which would lead to a failure during the -ExecStop directive of a systemd service referencing that pod. +@@option ignore #### **--latest**, **-l** Instead of providing the pod name or ID, stop the last created pod. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) -#### **--pod-id-file** - -Read pod ID from the specified file and stop the pod. Can be specified multiple times. +@@option pod-id-file.pod #### **--time**, **-t**=*seconds* diff --git a/docs/source/markdown/podman-pull.1.md.in b/docs/source/markdown/podman-pull.1.md.in index db041298e..03f9b8fd7 100644 --- a/docs/source/markdown/podman-pull.1.md.in +++ b/docs/source/markdown/podman-pull.1.md.in @@ -57,11 +57,7 @@ All tagged images in the repository will be pulled. @@option creds -#### **--disable-content-trust** - -This is a Docker specific option to disable image verification to a Docker -registry and is not supported by Podman. This flag is a NOOP and provided -solely for scripting compatibility. +@@option disable-content-trust #### **--help**, **-h** diff --git a/docs/source/markdown/podman-push.1.md.in b/docs/source/markdown/podman-push.1.md.in index f32261bab..a98964e45 100644 --- a/docs/source/markdown/podman-push.1.md.in +++ b/docs/source/markdown/podman-push.1.md.in @@ -49,10 +49,7 @@ $ podman push myimage oci-archive:/tmp/myimage @@option authfile -#### **--cert-dir**=*path* - -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) +@@option cert-dir #### **--compress** @@ -69,11 +66,7 @@ Specifies the compression format to use. Supported values are: `gzip`, `zstd` a After copying the image, write the digest of the resulting image to the file. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) -#### **--disable-content-trust** - -This is a Docker specific option to disable image verification to a Docker -registry and is not supported by Podman. This flag is a NOOP and provided -solely for scripting compatibility. +@@option disable-content-trust #### **--format**, **-f**=*format* diff --git a/docs/source/markdown/podman-rm.1.md.in b/docs/source/markdown/podman-rm.1.md.in index fa3031b29..c0fa94d82 100644 --- a/docs/source/markdown/podman-rm.1.md.in +++ b/docs/source/markdown/podman-rm.1.md.in @@ -56,11 +56,7 @@ Containers could have been created by a different container engine. In addition, forcing can be used to remove unusable containers, e.g. containers whose OCI runtime has become unavailable. -#### **--ignore**, **-i** - -Ignore errors when specified containers are not in the container store. A user -might have decided to manually remove a container which would lead to a failure -during the ExecStop directive of a systemd service referencing that container. +@@option ignore #### **--latest**, **-l** diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index cdfa9366a..c7985d7e1 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -134,15 +134,7 @@ each of **stdin**, **stdout**, and **stderr**. @@option cpu-shares -#### **--cpus**=*number* - -Number of CPUs. The default is *0.0* which means no limit. This is shorthand -for **--cpu-period** and **--cpu-quota**, so you may only set either -**--cpus** or **--cpu-period** and **--cpu-quota**. - -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 +@@option cpus.container @@option cpuset-cpus @@ -186,31 +178,33 @@ Podman may load kernel modules required for using the specified device. The devices that Podman will load modules when necessary are: /dev/fuse. -#### **--device-cgroup-rule**=*rule* - -Add a rule to the cgroup allowed devices list +@@option device-cgroup-rule #### **--device-read-bps**=*path:rate* Limit read rate (in bytes per second) from a device (e.g. **--device-read-bps=/dev/sda:1mb**). +This option is not supported on cgroups V1 rootless systems. + #### **--device-read-iops**=*path:rate* Limit read rate (in IO operations per second) from a device (e.g. **--device-read-iops=/dev/sda:1000**). +This option is not supported on cgroups V1 rootless systems. + #### **--device-write-bps**=*path:rate* Limit write rate (in bytes per second) to a device (e.g. **--device-write-bps=/dev/sda:1mb**). +This option is not supported on cgroups V1 rootless systems. + #### **--device-write-iops**=*path:rate* Limit write rate (in IO operations per second) to a device (e.g. **--device-write-iops=/dev/sda:1000**). -#### **--disable-content-trust** +This option is not supported on cgroups V1 rootless systems. -This is a Docker specific option to disable image verification to a Docker -registry and is not supported by Podman. This flag is a NOOP and provided -solely for scripting compatibility. +@@option disable-content-trust #### **--dns**=*ipaddr* @@ -249,16 +243,11 @@ Read in a line delimited file of environment variables. See **Environment** note @@option env-host -@@option expose - -#### **--gidmap**=*container_gid:host_gid:amount* +@@option env-merge -Run the container in a new user namespace using the supplied GID mapping. This -option conflicts with the **--userns** and **--subgidname** options. This -option provides a way to map host GIDs to container GIDs in the same way as -__--uidmap__ maps host UIDs to container UIDs. For details see __--uidmap__. +@@option expose -Note: the **--gidmap** flag cannot be called in conjunction with the **--pod** flag as a gidmap cannot be set on the container level when in a pod. +@@option gidmap.container @@option group-add @@ -323,18 +312,7 @@ The address must be within the network's IPv6 address pool. To specify multiple static IPv6 addresses per container, set multiple networks using the **--network** option with a static IPv6 address specified for each using the `ip6` mode for that option. -#### **--ipc**=*mode* - -Set the IPC namespace mode for a container. The default is to create -a private IPC namespace. - -- "": Use Podman's default, defined in containers.conf. -- **container:**_id_: reuses another container shared memory, semaphores and message queues -- **host**: use the host shared memory,semaphores and message queues inside the container. Note: the host mode gives the container full access to local shared memory and is therefore considered insecure. -- **none**: private IPC namespace, with /dev/shm not mounted. -- **ns:**_path_: path to an IPC namespace to join. -- **private**: private IPC namespace. -= **shareable**: private IPC namespace with a possibility to share it with other containers. +@@option ipc #### **--label**, **-l**=*key=value* @@ -375,6 +353,8 @@ RAM. If a limit of 0 is specified (not using **-m**), the container's memory is not limited. The actual limit may be rounded up to a multiple of the operating system's page size (the value would be very large, that's millions of trillions). +This option is not supported on cgroups V1 rootless systems. + #### **--memory-reservation**=*number[unit]* Memory soft limit. A _unit_ can be **b** (bytes), **k** (kibibytes), **m** (mebibytes), or **g** (gibibytes). @@ -385,6 +365,8 @@ reservation. So you should always set the value below **--memory**, otherwise th hard limit will take precedence. By default, memory reservation will be the same as memory limit. +This option is not supported on cgroups V1 rootless systems. + #### **--memory-swap**=*number[unit]* A limit value equal to memory plus swap. @@ -397,6 +379,8 @@ the value of **--memory**. Set _number_ to **-1** to enable unlimited swap. +This option is not supported on cgroups V1 rootless systems. + @@option memory-swappiness @@option mount @@ -474,15 +458,7 @@ This is used to override the Podman provided user setup in favor of entrypoint c @@option personality -#### **--pid**=*mode* - -Set the PID namespace mode for the container. -The default is to create a private PID namespace for the container. - -- **container:**_id_: join another container's PID namespace; -- **host**: use the host's PID namespace for the container. Note the host mode gives the container full access to local PID and is therefore considered insecure; -- **private**: create a new namespace for the container (default) -- **ns:**_path_: join the specified PID namespace. +@@option pid @@option pidfile @@ -496,10 +472,7 @@ Run container in an existing pod. If you want Podman to make the pod for you, pr To make a pod with more granular options, use the **podman pod create** command before creating a container. If a container is run with a pod, and the pod has an infra-container, the infra-container will be started before the container is. -#### **--pod-id-file**=*path* - -Run container in an existing pod and read the pod's ID from the specified file. -If a container is run within a pod, and the pod has an infra-container, the infra-container will be started before the container is. +@@option pod-id-file.container #### **--preserve-fds**=*N* @@ -1037,13 +1010,7 @@ If the location of the volume from the source container overlaps with data residing on a target container, then the volume hides that data on the target. -#### **--workdir**, **-w**=*dir* - -Working directory inside the container. - -The default working directory for running binaries within a container is the root directory (**/**). -The image developer can set a different default with the WORKDIR instruction. The operator -can override the working directory by using the **-w** option. +@@option workdir ## Exit Status diff --git a/docs/source/markdown/podman-stop.1.md.in b/docs/source/markdown/podman-stop.1.md.in index 04fc9387f..9aaccdfaa 100644 --- a/docs/source/markdown/podman-stop.1.md.in +++ b/docs/source/markdown/podman-stop.1.md.in @@ -47,11 +47,7 @@ Valid filters are listed below: | pod | [Pod] name or full or partial ID of pod | | network | [Network] name or full ID of network | -#### **--ignore**, **-i** - -Ignore errors when specified containers are not in the container store. A user -might have decided to manually remove a container which would lead to a failure -during the ExecStop directive of a systemd service referencing that container. +@@option ignore #### **--latest**, **-l** diff --git a/docs/source/markdown/podman-system-service.1.md b/docs/source/markdown/podman-system-service.1.md index 99fde8ce4..3e7a00362 100644 --- a/docs/source/markdown/podman-system-service.1.md +++ b/docs/source/markdown/podman-system-service.1.md @@ -8,7 +8,7 @@ podman\-system\-service - Run an API service ## DESCRIPTION The **podman system service** command creates a listening service that will answer API calls for Podman. You may -optionally provide an endpoint for the API in URI form. For example, *unix:///tmp/foobar.sock* or *tcp:localhost:8080*. +optionally provide an endpoint for the API in URI form. For example, *unix:///tmp/foobar.sock* or *tcp://localhost:8080*. If no endpoint is provided, defaults will be used. The default endpoint for a rootful service is *unix:///run/podman/podman.sock* and rootless is *unix://$XDG_RUNTIME_DIR/podman/podman.sock* (for example *unix:///run/user/1000/podman/podman.sock*) |