diff options
Diffstat (limited to 'docs')
80 files changed, 517 insertions, 529 deletions
diff --git a/docs/source/markdown/.gitignore b/docs/source/markdown/.gitignore index 6689b5b71..8a0d553ba 100644 --- a/docs/source/markdown/.gitignore +++ b/docs/source/markdown/.gitignore @@ -1,8 +1,28 @@ +podman-auto-update.1.md 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 +podman-login.1.md +podman-logout.1.md +podman-logs.1.md +podman-manifest-add.1.md +podman-manifest-push.1.md +podman-pause.1.md podman-pod-clone.1.md podman-pod-create.1.md +podman-pod-logs.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 podman-run.1.md +podman-search.1.md +podman-stop.1.md +podman-unpause.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/arch.md b/docs/source/markdown/options/arch.md index 005197707..76fb349a0 100644 --- a/docs/source/markdown/options/arch.md +++ b/docs/source/markdown/options/arch.md @@ -1,2 +1,3 @@ #### **--arch**=*ARCH* Override the architecture, defaults to hosts, of the image to be pulled. For example, `arm`. +Unless overridden, subsequent lookups of the same image in the local storage will match this architecture, regardless of the host. diff --git a/docs/source/markdown/options/authfile.md b/docs/source/markdown/options/authfile.md new file mode 100644 index 000000000..d6198aa24 --- /dev/null +++ b/docs/source/markdown/options/authfile.md @@ -0,0 +1,6 @@ +#### **--authfile**=*path* + +Path of the authentication file. Default is `${XDG_RUNTIME_DIR}/containers/auth.json`, which is set using **[podman login](podman-login.1.md)**. +If the authorization state is not found there, `$HOME/.docker/config.json` is checked, which is set using **docker login**. + +Note: There is also the option to override the default path of the authentication file by setting the `REGISTRY_AUTH_FILE` environment variable. This can be done with **export REGISTRY_AUTH_FILE=_path_**. 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/cert-dir.md b/docs/source/markdown/options/cert-dir.md new file mode 100644 index 000000000..4d05075cf --- /dev/null +++ b/docs/source/markdown/options/cert-dir.md @@ -0,0 +1,5 @@ +#### **--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)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)** for details. +(This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) diff --git a/docs/source/markdown/options/cidfile.read.md b/docs/source/markdown/options/cidfile.read.md new file mode 100644 index 000000000..414700fca --- /dev/null +++ b/docs/source/markdown/options/cidfile.read.md @@ -0,0 +1,4 @@ +#### **--cidfile**=*file* + +Read container ID from the specified *file* and <<subcommand>> the container. +Can be specified multiple times. diff --git a/docs/source/markdown/options/cidfile.write.md b/docs/source/markdown/options/cidfile.write.md new file mode 100644 index 000000000..b5e7435b2 --- /dev/null +++ b/docs/source/markdown/options/cidfile.write.md @@ -0,0 +1,3 @@ +#### **--cidfile**=*file* + +Write the container ID to *file*. diff --git a/docs/source/markdown/options/color.md b/docs/source/markdown/options/color.md new file mode 100644 index 000000000..343c79c88 --- /dev/null +++ b/docs/source/markdown/options/color.md @@ -0,0 +1,3 @@ +#### **--color** + +Output the containers with different colors in the log. diff --git a/docs/source/markdown/options/cpu-period.md b/docs/source/markdown/options/cpu-period.md index 8df6445e9..5c5eb56e7 100644 --- a/docs/source/markdown/options/cpu-period.md +++ b/docs/source/markdown/options/cpu-period.md @@ -5,6 +5,8 @@ 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 +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-cpu-limits-fails-with-a-permissions-error +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 67b9dee8c..81d5db3d2 100644 --- a/docs/source/markdown/options/cpu-quota.md +++ b/docs/source/markdown/options/cpu-quota.md @@ -7,6 +7,8 @@ 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 +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-cpu-limits-fails-with-a-permissions-error +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 a5aacd2ca..c0e2c3035 100644 --- a/docs/source/markdown/options/cpu-shares.md +++ b/docs/source/markdown/options/cpu-shares.md @@ -33,3 +33,9 @@ this can result in the following division of CPU shares: | 100 | C0 | 0 | 100% of CPU0 | | 101 | C1 | 1 | 100% of CPU1 | | 102 | C1 | 2 | 100% of CPU2 | + +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 d717516a0..8a2a82e9f 100644 --- a/docs/source/markdown/options/cpuset-cpus.md +++ b/docs/source/markdown/options/cpuset-cpus.md @@ -3,3 +3,9 @@ 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**). + +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 d2d13eb54..b86d0ef6b 100644 --- a/docs/source/markdown/options/cpuset-mems.md +++ b/docs/source/markdown/options/cpuset-mems.md @@ -6,3 +6,9 @@ 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. + +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/creds.md b/docs/source/markdown/options/creds.md new file mode 100644 index 000000000..23399dda4 --- /dev/null +++ b/docs/source/markdown/options/creds.md @@ -0,0 +1,5 @@ +#### **--creds**=*[username[:password]]* + +The [username[:password]] to use to authenticate with the registry if required. +If one or both values are not supplied, a command line prompt will appear and the +value can be entered. The password is entered without echo. 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/dns-opt.container.md b/docs/source/markdown/options/dns-opt.container.md new file mode 100644 index 000000000..ea26fd013 --- /dev/null +++ b/docs/source/markdown/options/dns-opt.container.md @@ -0,0 +1,3 @@ +#### **--dns-opt**=*option* + +Set custom DNS options. Invalid if using **--dns-opt** with **--network** that is set to **none** or **container:**_id_. diff --git a/docs/source/markdown/options/dns-search.container.md b/docs/source/markdown/options/dns-search.container.md new file mode 100644 index 000000000..5a803ba39 --- /dev/null +++ b/docs/source/markdown/options/dns-search.container.md @@ -0,0 +1,4 @@ +#### **--dns-search**=*domain* + +Set custom DNS search domains. Invalid if using **--dns-search** with **--network** that is set to **none** or **container:**_id_. +Use **--dns-search=.** if you don't wish to set the search domain. 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/follow.md b/docs/source/markdown/options/follow.md new file mode 100644 index 000000000..75b65cf49 --- /dev/null +++ b/docs/source/markdown/options/follow.md @@ -0,0 +1,7 @@ +#### **--follow**, **-f** + +Follow log output. Default is false. + +Note: If you are following a <<container|pod>> which is removed by `podman <<container|pod>> rm` +or removed on exit (`podman run --rm ...`), then there is a chance that the log +file will be removed before `podman<< pod|>> logs` reads the final content. 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/names.md b/docs/source/markdown/options/names.md new file mode 100644 index 000000000..54fda40ee --- /dev/null +++ b/docs/source/markdown/options/names.md @@ -0,0 +1,3 @@ +#### **--names**, **-n** + +Output the container names instead of the container IDs in the log. 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/platform.md b/docs/source/markdown/options/platform.md index edfa428ff..b66efdfb2 100644 --- a/docs/source/markdown/options/platform.md +++ b/docs/source/markdown/options/platform.md @@ -2,3 +2,4 @@ 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. +Unless overridden, subsequent lookups of the same image in the local storage will match this platform, regardless of the host. 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/since.md b/docs/source/markdown/options/since.md new file mode 100644 index 000000000..9f20722df --- /dev/null +++ b/docs/source/markdown/options/since.md @@ -0,0 +1,6 @@ +#### **--since**=*TIMESTAMP* + +Show logs since TIMESTAMP. The --since option can be Unix timestamps, date formatted timestamps, or Go duration +strings (e.g. 10m, 1h30m) computed relative to the client machine's time. Supported formats for date formatted +time stamps include RFC3339Nano, RFC3339, 2006-01-02T15:04:05, 2006-01-02T15:04:05.999999999, 2006-01-02Z07:00, +and 2006-01-02. diff --git a/docs/source/markdown/options/systemd.md b/docs/source/markdown/options/systemd.md new file mode 100644 index 000000000..a341edbc2 --- /dev/null +++ b/docs/source/markdown/options/systemd.md @@ -0,0 +1,29 @@ +#### **--systemd**=*true* | *false* | *always* + +Run container in systemd mode. The default is **true**. + +The value *always* enforces the systemd mode is enforced without +looking at the executable name. Otherwise, if set to true and the +command you are running inside the container is **systemd**, **/usr/sbin/init**, +**/sbin/init** or **/usr/local/sbin/init**. + +Running the container in systemd mode causes the following changes: + +* Podman mounts tmpfs file systems on the following directories + * _/run_ + * _/run/lock_ + * _/tmp_ + * _/sys/fs/cgroup/systemd_ + * _/var/lib/journal_ +* Podman sets the default stop signal to **SIGRTMIN+3**. +* Podman sets **container_uuid** environment variable in the container to the +first 32 characters of the container id. + +This allows systemd to run in a confined container without any modifications. + +Note that on **SELinux** systems, systemd attempts to write to the cgroup +file system. Containers writing to the cgroup file system are denied by default. +The **container_manage_cgroup** boolean must be enabled for this to be allowed on an SELinux separated system. +``` +setsebool -P container_manage_cgroup true +``` diff --git a/docs/source/markdown/options/tail.md b/docs/source/markdown/options/tail.md new file mode 100644 index 000000000..463b6fc3f --- /dev/null +++ b/docs/source/markdown/options/tail.md @@ -0,0 +1,4 @@ +#### **--tail**=*LINES* + +Output the specified number of LINES at the end of the logs. LINES must be an integer. Defaults to -1, +which prints all lines diff --git a/docs/source/markdown/options/timestamps.md b/docs/source/markdown/options/timestamps.md new file mode 100644 index 000000000..a449216aa --- /dev/null +++ b/docs/source/markdown/options/timestamps.md @@ -0,0 +1,3 @@ +#### **--timestamps**, **-t** + +Show timestamps in the log outputs. The default is false diff --git a/docs/source/markdown/options/until.md b/docs/source/markdown/options/until.md new file mode 100644 index 000000000..d656d976b --- /dev/null +++ b/docs/source/markdown/options/until.md @@ -0,0 +1,6 @@ +#### **--until**=*TIMESTAMP* + +Show logs until TIMESTAMP. The --until option can be Unix timestamps, date formatted timestamps, or Go duration +strings (e.g. 10m, 1h30m) computed relative to the client machine's time. Supported formats for date formatted +time stamps include RFC3339Nano, RFC3339, 2006-01-02T15:04:05, 2006-01-02T15:04:05.999999999, 2006-01-02Z07:00, +and 2006-01-02. 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-auto-update.1.md b/docs/source/markdown/podman-auto-update.1.md.in index 992c87432..bc92d6165 100644 --- a/docs/source/markdown/podman-auto-update.1.md +++ b/docs/source/markdown/podman-auto-update.1.md.in @@ -34,12 +34,8 @@ Systemd units that start and stop a container cannot run a new image. Podman ships with a `podman-auto-update.service` systemd unit. This unit is triggered daily at midnight by the `podman-auto-update.timer` systemd timer. The timer can be altered for custom time-based updates if desired. The unit can further be invoked by other systemd units (e.g., via the dependency tree) or manually via **systemctl start podman-auto-update.service**. ## OPTIONS -#### **--authfile**=*path* -Path of the authentication file. Default is `${XDG_RUNTIME_DIR}/containers/auth.json`, which is set using **[podman login](podman-login.1.md)**. -If the authorization state is not found there, `$HOME/.docker/config.json` is checked, which is set using **docker login**. - -Note: There is also the option to override the default path of the authentication file by setting the `REGISTRY_AUTH_FILE` environment variable. This can be done with **export REGISTRY_AUTH_FILE=_path_**. +@@option authfile #### **--dry-run** diff --git a/docs/source/markdown/podman-build.1.md.in b/docs/source/markdown/podman-build.1.md.in index c0cf08f3c..693e0d3b9 100644 --- a/docs/source/markdown/podman-build.1.md.in +++ b/docs/source/markdown/podman-build.1.md.in @@ -65,19 +65,11 @@ discarded when writing images in Docker formats. Set the architecture of the image to be built, and that of the base image to be pulled, if the build uses one, to the provided value instead of using the -architecture of the build host. (Examples: arm, arm64, 386, amd64, ppc64le, -s390x) +architecture of the build host. Unless overridden, subsequent lookups of the +same image in the local storage will match this architecture, regardless of the +host. (Examples: arm, arm64, 386, amd64, ppc64le, s390x) -#### **--authfile**=*path* - -Path of the authentication file. Default is -${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`. -If the authorization state is not found there, $HOME/.docker/config.json is -checked, which is set using `docker login`. - -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` +@@option authfile #### **--build-arg**=*arg=value* @@ -173,10 +165,7 @@ If a capability is specified to both the **--cap-add** and **--cap-drop** options, it will be dropped, regardless of the order in which the options were given. -#### **--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 cgroup-parent @@ -207,11 +196,7 @@ Set additional flags to pass to the C Preprocessor cpp(1). Containerfiles ending @@option cpuset-mems -#### **--creds**=*creds* - -The [username[:password]] to use to authenticate with the registry if required. -If one or both values are not supplied, a command line prompt will appear and -the value can be entered. The password is entered without echo. +@@option creds #### **--decryption-key**=*key[:passphrase]* @@ -245,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* @@ -312,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 @@ -463,7 +450,8 @@ do not include `History` information in their images. Set the OS of the image to be built, and that of the base image to be pulled, if the build uses one, instead of using the current operating system of the -build host. +build host. Unless overridden, subsequent lookups of the same image in the +local storage will match this OS, regardless of the host. #### **--os-feature**=*feature* @@ -515,9 +503,12 @@ process. Set the *os/arch* of the built image (and its base image, if your build uses one) to the provided value instead of using the current operating system and -architecture of the host (for example `linux/arm`). If `--platform` is set, -then the values of the `--arch`, `--os`, and `--variant` options will be -overridden. +architecture of the host (for example `linux/arm`). Unless overridden, +subsequent lookups of the same image in the local storage will match this +platform, regardless of the host. + +If `--platform` is set, then the values of the `--arch`, `--os`, and +`--variant` options will be overridden. The `--platform` option can be specified more than once, or given a comma-separated list of values as its argument. When more than one platform is 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 b/docs/source/markdown/podman-container-runlabel.1.md.in index 40e5392ce..f5fb8ca60 100644 --- a/docs/source/markdown/podman-container-runlabel.1.md +++ b/docs/source/markdown/podman-container-runlabel.1.md.in @@ -29,20 +29,12 @@ As specified by the `--name` option. The format is identical to the one of the Will be replaced with the current working directory. ## OPTIONS -#### **--authfile**=*path* -Path of the containers-auth.json(5) file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`. If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. +@@option authfile -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` +@@option cert-dir -#### **--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) - -#### **--creds**=*[username[:password]]* - -The [username[:password]] to use to authenticate with the registry if required. If one or both values are not supplied, a command line prompt will appear and the value can be entered. The password is entered without echo. +@@option creds #### **--display** diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index f5301c60a..0a880951d 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -83,12 +83,7 @@ error. It can even pretend to be a TTY (this is what most command line executables expect) and pass along signals. The **-a** option can be set for each of stdin, stdout, and stderr. -#### **--authfile**=*path* - -Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json - -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` +@@option authfile @@option blkio-weight @@ -110,9 +105,7 @@ Block IO relative device weight. @@option chrootdirs -#### **--cidfile**=*id* - -Write the container ID to the file +@@option cidfile.write @@option conmon-pidfile @@ -126,15 +119,7 @@ Write the container ID to the file @@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 @@ -159,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* @@ -200,13 +184,9 @@ is the case the **--dns** flag is necessary for every run. The special value **none** can be specified to disable creation of **/etc/resolv.conf** in the container by Podman. The **/etc/resolv.conf** file in the image will be used without changes. -#### **--dns-opt**=*option* - -Set custom DNS options. Invalid if using **--dns-opt** and **--network** that is set to 'none' or `container:<name|id>`. +@@option dns-opt.container -#### **--dns-search**=*domain* - -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) +@@option dns-search.container @@option entrypoint @@ -224,16 +204,11 @@ Read in a line delimited file of environment variables. See **Environment** note @@option env-host -@@option expose +@@option env-merge -#### **--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__. +@@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 @@ -319,18 +294,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* @@ -371,6 +335,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)) @@ -381,6 +347,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** @@ -392,6 +360,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 @@ -457,19 +427,13 @@ This option conflicts with **--add-host**. #### **--os**=*OS* Override the OS, defaults to hosts, of the image to be pulled. For example, `windows`. +Unless overridden, subsequent lookups of the same image in the local storage will match this OS, regardless of the host. @@option passwd-entry @@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 @@ -482,9 +446,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** @@ -666,34 +628,7 @@ Network Namespace - current sysctls allowed: Note: if you use the --network=host option these sysctls will not be allowed. -#### **--systemd**=*true* | *false* | *always* - -Run container in systemd mode. The default is *true*. - -The value *always* enforces the systemd mode is enforced without -looking at the executable name. Otherwise, if set to true and the -command you are running inside the container is **systemd**, **/usr/sbin/init**, -**/sbin/init** or **/usr/local/sbin/init**. - -Running the container in systemd mode causes the following changes: - -* Podman mounts tmpfs file systems on the following directories - * _/run_ - * _/run/lock_ - * _/tmp_ - * _/sys/fs/cgroup/systemd_ - * _/var/lib/journal_ -* Podman sets the default stop signal to **SIGRTMIN+3**. -* Podman sets **container_uuid** environment variable in the container to the -first 32 characters of the container id. - -This allows systemd to run in a confined container without any modifications. - -Note: On `SELinux` systems, systemd attempts to write to the cgroup -file system. Containers writing to the cgroup file system are denied by default. -The `container_manage_cgroup` boolean must be enabled for this to be allowed on an SELinux separated system. - -`setsebool -P container_manage_cgroup true` +@@option systemd @@option timeout @@ -986,13 +921,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-generate-systemd.1.md b/docs/source/markdown/podman-generate-systemd.1.md index fc2ce171e..88dff2a45 100644 --- a/docs/source/markdown/podman-generate-systemd.1.md +++ b/docs/source/markdown/podman-generate-systemd.1.md @@ -26,7 +26,7 @@ therefore the overridden default value._ A Kubernetes YAML can be executed in systemd via the `podman-kube@.service` systemd template. The template's argument is the path to the YAML file. Given a `workload.yaml` file in the home directory, it can be executed as follows: ``` -$ escaped=$(systemd-escape ~/sysadmin.yaml) +$ escaped=$(systemd-escape ~/workload.yaml) $ systemctl --user start podman-kube@$escaped.service $ systemctl --user is-active podman-kube@$escaped.service active diff --git a/docs/source/markdown/podman-image-sign.1.md b/docs/source/markdown/podman-image-sign.1.md.in index 035e10743..d5efabc1a 100644 --- a/docs/source/markdown/podman-image-sign.1.md +++ b/docs/source/markdown/podman-image-sign.1.md.in @@ -19,17 +19,9 @@ By default, the signature will be written into `/var/lib/containers/sigstore` fo Sign all the manifests of the multi-architecture image (default false). -#### **--authfile**=*path* +@@option authfile -Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json - -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` - -#### **--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-image-trust.1.md b/docs/source/markdown/podman-image-trust.1.md index 4e80bdcf5..2a7da82cc 100644 --- a/docs/source/markdown/podman-image-trust.1.md +++ b/docs/source/markdown/podman-image-trust.1.md @@ -32,7 +32,8 @@ Trust **type** provides a way to: Allowlist ("accept") or Denylist ("reject") registries or -Require signature (“signedBy”). +Require a simple signing signature (“signedBy”), +Require a sigstore signature ("sigstoreSigned"). Trust may be updated using the command **podman image trust set** for an existing trust scope. @@ -45,12 +46,14 @@ Trust may be updated using the command **podman image trust set** for an existin #### **--pubkeysfile**, **-f**=*KEY1* A path to an exported public key on the local system. Key paths will be referenced in policy.json. Any path to a file may be used but locating the file in **/etc/pki/containers** is recommended. Options may be used multiple times to - require an image be signed by multiple keys. The **--pubkeysfile** option is required for the **signedBy** type. + require an image be signed by multiple keys. The **--pubkeysfile** option is required for the **signedBy** and **sigstoreSigned** types. #### **--type**, **-t**=*value* The trust type for this policy entry. Accepted values: - **signedBy** (default): Require signatures with corresponding list of + **signedBy** (default): Require simple signing signatures with corresponding list of + public keys + **sigstoreSigned**: Require sigstore signatures with corresponding list of public keys **accept**: do not require any signatures for this registry scope diff --git a/docs/source/markdown/podman-kill.1.md b/docs/source/markdown/podman-kill.1.md.in index a4f80ac81..2788cc694 100644 --- a/docs/source/markdown/podman-kill.1.md +++ b/docs/source/markdown/podman-kill.1.md.in @@ -16,9 +16,7 @@ The main process inside each container specified will be sent SIGKILL, or any si Signal all running and paused containers. -#### **--cidfile** - -Read container ID from the specified file and remove the container. Can be specified multiple times. +@@option cidfile.read #### **--latest**, **-l** 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 5fc183ee2..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 @@ -112,22 +113,13 @@ and as a result environment variable `FOO` will be set to `bar` for container `c @@option annotation.container -#### **--authfile**=*path* - -Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`. -If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. - -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` +@@option authfile #### **--build** Build images even if they are found in the local storage. Use `--build=false` to completely disable builds. (This option is not available with the remote Podman client) -#### **--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 #### **--configmap**=*path* @@ -139,11 +131,7 @@ Note: The *--configmap* option can be used multiple times or a comma-separated l Use *path* as the build context directory for each image. Requires --build option be true. (This option is not available with the remote Podman client) -#### **--creds** - -The [username[:password]] to use to authenticate with the registry if required. -If one or both values are not supplied, a command line prompt will appear and the -value can be entered. The password is entered without echo. +@@option creds #### **--help**, **-h** @@ -313,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 b/docs/source/markdown/podman-login.1.md.in index c84b0cc99..4537988eb 100644 --- a/docs/source/markdown/podman-login.1.md +++ b/docs/source/markdown/podman-login.1.md.in @@ -28,17 +28,9 @@ For more details about format and configurations of the auth.json file, please r ## OPTIONS -#### **--authfile**=*path* +@@option authfile -Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json. - -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` - -#### **--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-logout.1.md b/docs/source/markdown/podman-logout.1.md.in index 96ac98f35..6997bb36e 100644 --- a/docs/source/markdown/podman-logout.1.md +++ b/docs/source/markdown/podman-logout.1.md.in @@ -25,12 +25,7 @@ All the cached credentials can be removed by setting the **all** flag. Remove the cached credentials for all registries in the auth file -#### **--authfile**=*path* - -Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json. - -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` +@@option authfile #### **--help**, **-h** diff --git a/docs/source/markdown/podman-logs.1.md b/docs/source/markdown/podman-logs.1.md.in index 6ce6c3812..7b0c45cf0 100644 --- a/docs/source/markdown/podman-logs.1.md +++ b/docs/source/markdown/podman-logs.1.md.in @@ -15,49 +15,24 @@ any logs at the time you execute podman logs). ## OPTIONS -#### **--color** +@@option color -Output the containers with different colors in the log. - -#### **--follow**, **-f** - -Follow log output. Default is false. - -Note: If you are following a container which is removed `podman container rm` -or removed on exit `podman run --rm ...`, then there is a chance that the log -file will be removed before `podman logs` reads the final content. +@@option follow #### **--latest**, **-l** Instead of providing the container name or ID, use the last created container. If you use methods other than Podman to run containers such as CRI-O, the last started container could be from either of those methods. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) -#### **--names**, **-n** - -Output the container name in the log - -#### **--since**=*TIMESTAMP* - -Show logs since TIMESTAMP. The --since option can be Unix timestamps, date formatted timestamps, or Go duration -strings (e.g. 10m, 1h30m) computed relative to the client machine's time. Supported formats for date formatted -time stamps include RFC3339Nano, RFC3339, 2006-01-02T15:04:05, 2006-01-02T15:04:05.999999999, 2006-01-02Z07:00, -and 2006-01-02. - -#### **--tail**=*LINES* - -Output the specified number of LINES at the end of the logs. LINES must be an integer. Defaults to -1, -which prints all lines +@@option names -#### **--timestamps**, **-t** +@@option since -Show timestamps in the log outputs. The default is false +@@option tail -#### **--until**=*TIMESTAMP* +@@option timestamps -Show logs until TIMESTAMP. The --until option can be Unix timestamps, date formatted timestamps, or Go duration -strings (e.g. 10m, 1h30m) computed relative to the client machine's time. Supported formats for date formatted -time stamps include RFC3339Nano, RFC3339, 2006-01-02T15:04:05, 2006-01-02T15:04:05.999999999, 2006-01-02Z07:00, -and 2006-01-02. +@@option until ## EXAMPLE diff --git a/docs/source/markdown/podman-manifest-add.1.md b/docs/source/markdown/podman-manifest-add.1.md.in index 5aa7f8341..e82c04985 100644 --- a/docs/source/markdown/podman-manifest-add.1.md +++ b/docs/source/markdown/podman-manifest-add.1.md.in @@ -33,24 +33,11 @@ the image. If *imageName* refers to a manifest list or image index, the architecture information will be retrieved from it. Otherwise, it will be retrieved from the image's configuration information. -#### **--authfile**=*path* +@@option authfile -Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`. -If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. +@@option cert-dir -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` - -#### **--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) - -#### **--creds**=*creds* - -The [username[:password]] to use to authenticate with the registry if required. -If one or both values are not supplied, a command line prompt will appear and the -value can be entered. The password is entered without echo. +@@option creds #### **--features** diff --git a/docs/source/markdown/podman-manifest-create.1.md b/docs/source/markdown/podman-manifest-create.1.md index 77a4b9db6..06a24da2b 100644 --- a/docs/source/markdown/podman-manifest-create.1.md +++ b/docs/source/markdown/podman-manifest-create.1.md @@ -22,11 +22,23 @@ If any of the images which should be added to the new list or index are themselves lists or indexes, add all of their contents. By default, only one image from such a list will be added to the newly-created list or index. +#### **--amend**, **-a** + +If a manifest list named *listnameorindexname* already exists, modify the +preexisting list instead of exiting with an error. The contents of +*listnameorindexname* are not modified if no *imagename*s are given. + +#### **--tls-verify** + +Require HTTPS and verify certificates when talking to container registries. (defaults to true) + ## EXAMPLES ``` podman manifest create mylist:v1.11 9cfd24048d5fc80903f088f1531a21bff01172abe66effa8941a4c2308dc745f +podman manifest create --amend mylist:v1.11 +9cfd24048d5fc80903f088f1531a21bff01172abe66effa8941a4c2308dc745f ``` ``` diff --git a/docs/source/markdown/podman-manifest-push.1.md b/docs/source/markdown/podman-manifest-push.1.md.in index cfe2b9230..88d070c3f 100644 --- a/docs/source/markdown/podman-manifest-push.1.md +++ b/docs/source/markdown/podman-manifest-push.1.md.in @@ -19,28 +19,15 @@ The list image's ID and the digest of the image's manifest. Push the images mentioned in the manifest list or image index, in addition to the list or index itself. (Default true) -#### **--authfile**=*path* +@@option authfile -Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`. -If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. - -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` - -#### **--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* Specifies the compression format to use. Supported values are: `gzip`, `zstd` and `zstd:chunked`. The default is `gzip` unless overridden in the containers.conf file. -#### **--creds**=*creds* - -The [username[:password]] to use to authenticate with the registry if required. -If one or both values are not supplied, a command line prompt will appear and the -value can be entered. The password is entered without echo. +@@option creds #### **--digestfile**=*Digestfile* diff --git a/docs/source/markdown/podman-pause.1.md b/docs/source/markdown/podman-pause.1.md.in index f374d96f3..af308f034 100644 --- a/docs/source/markdown/podman-pause.1.md +++ b/docs/source/markdown/podman-pause.1.md.in @@ -17,9 +17,7 @@ Pauses all the processes in one or more containers. You may use container IDs o Pause all running containers. -#### **--cidfile** - -Read container ID from the specified file and pause the container. Can be specified multiple times. +@@option cidfile.read #### **--filter**, **-f**=*filter* 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 73b634548..702780c65 100644 --- a/docs/source/markdown/podman-pod-create.1.md.in +++ b/docs/source/markdown/podman-pod-create.1.md.in @@ -89,14 +89,12 @@ Set custom DNS search domains in the /etc/resolv.conf file that will be shared b Set the exit policy of the pod when the last container exits. Supported policies are: -| Exit Policy | Description | -| ------------------ | --------------------------------------------------------------------------- | -| *continue* | The pod continues running when the last container exits. Used by default. | -| *stop* | The pod is stopped when the last container exits. Used in `kube play`. | +| Exit Policy | Description | +| ------------------ | -------------------------------------------------------------------------------------------------------------------------- | +| *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-logs.1.md b/docs/source/markdown/podman-pod-logs.1.md.in index 7fc1d4b90..391f620f8 100644 --- a/docs/source/markdown/podman-pod-logs.1.md +++ b/docs/source/markdown/podman-pod-logs.1.md.in @@ -13,51 +13,27 @@ Note: Long running command of `podman pod log` with a `-f` or `--follow` needs t ## OPTIONS -#### **--color** - -Output the containers with different colors in the log. +@@option color #### **--container**, **-c** By default `podman pod logs` retrieves logs for all the containers available within the pod differentiate by field `container`. However there are use-cases where user would want to limit the log stream only to a particular container of a pod for such cases `-c` can be used like `podman pod logs -c ctrNameorID podname`. -#### **--follow**, **-f** - -Follow log output. Default is false. - -Note: If you are following a pod which is removed `podman pod rm`, then there is a -chance that the log file will be removed before `podman pod logs` reads the final content. +@@option follow #### **--latest**, **-l** Instead of providing the pod name or id, get logs of the last created pod. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) -#### **--names**, **-n** - -Output the container names instead of the container IDs in the log. - -#### **--since**=*TIMESTAMP* - -Show logs since TIMESTAMP. The --since option can be Unix timestamps, date formatted timestamps, or Go duration -strings (e.g. 10m, 1h30m) computed relative to the client machine's time. Supported formats for date formatted -time stamps include RFC3339Nano, RFC3339, 2006-01-02T15:04:05, 2006-01-02T15:04:05.999999999, 2006-01-02Z07:00, -and 2006-01-02. - -#### **--tail**=*LINES* - -Output the specified number of LINES at the end of the logs. LINES must be an integer. Defaults to -1, -which prints all lines +@@option names -#### **--timestamps**, **-t** +@@option since -Show timestamps in the log outputs. The default is false +@@option tail -#### **--until**=*TIMESTAMP* +@@option timestamps -Show logs until TIMESTAMP. The --until option can be Unix timestamps, date formatted timestamps, or Go duration -strings (e.g. 10m, 1h30m) computed relative to the client machine's time. Supported formats for date formatted -time stamps include RFC3339Nano, RFC3339, 2006-01-02T15:04:05, 2006-01-02T15:04:05.999999999, 2006-01-02Z07:00, -and 2006-01-02. +@@option until ## EXAMPLE diff --git a/docs/source/markdown/podman-pod-restart.1.md b/docs/source/markdown/podman-pod-restart.1.md index 677eca3a3..51f13dbf8 100644 --- a/docs/source/markdown/podman-pod-restart.1.md +++ b/docs/source/markdown/podman-pod-restart.1.md @@ -24,17 +24,27 @@ Instead of providing the pod name or ID, restart the last created pod. (This opt ## EXAMPLE +Restart pod with a given name ``` podman pod restart mywebserverpod cc8f0bea67b1a1a11aec1ecd38102a1be4b145577f21fc843c7c83b77fc28907 +``` +Restart multiple pods with given IDs +``` podman pod restart 490eb 3557fb 490eb241aaf704d4dd2629904410fe4aa31965d9310a735f8755267f4ded1de5 3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab +``` +Restart the last created pod +``` podman pod restart --latest 3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab +``` +Restart all pods +``` podman pod restart --all 19456b4cd557eaf9629825113a552681a6013f8c8cad258e36ab825ef536e818 3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab @@ -42,7 +52,6 @@ podman pod restart --all 70c358daecf71ef9be8f62404f926080ca0133277ef7ce4f6aa2d5af6bb2d3e9 cc8f0bea67b1a1a11aec1ecd38102a1be4b145577f21fc843c7c83b77fc28907 ``` - ## SEE ALSO **[podman(1)](podman.1.md)**, **[podman-pod(1)](podman-pod.1.md)**, **[podman-restart(1)](podman-restart.1.md)** 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..abcc69e9e 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* @@ -35,20 +29,20 @@ Seconds to wait before forcibly stopping the containers in the pod. ## EXAMPLE -Stop a pod called *mywebserverpod* +Stop pod with a given name ``` $ podman pod stop mywebserverpod cc8f0bea67b1a1a11aec1ecd38102a1be4b145577f21fc843c7c83b77fc28907 ``` -Stop two pods by their short IDs. +Stop multiple pods with given IDs. ``` $ podman pod stop 490eb 3557fb 490eb241aaf704d4dd2629904410fe4aa31965d9310a735f8755267f4ded1de5 3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab ``` -Stop the most recent pod +Stop the last created pod ``` $ podman pod stop --latest 3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab @@ -71,7 +65,7 @@ $ podman pod stop --pod-id-file file1 --pod-id-file file2 cc8f0bea67b1a1a11aec1ecd38102a1be4b145577f21fc843c7c83b77fc28907 ``` -Stop all pods with a timeout of 1 second. +Stop all pods with a timeout of 1 second ``` $ podman pod stop -a -t 1 3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab diff --git a/docs/source/markdown/podman-pull.1.md.in b/docs/source/markdown/podman-pull.1.md.in index 29c4f865d..03f9b8fd7 100644 --- a/docs/source/markdown/podman-pull.1.md.in +++ b/docs/source/markdown/podman-pull.1.md.in @@ -51,30 +51,13 @@ All tagged images in the repository will be pulled. @@option arch -#### **--authfile**=*path* +@@option authfile -Path of the authentication file. If the authorization state is not found there, `$HOME/.docker/config.json` is checked, which is set using `docker login`. +@@option cert-dir -Default is `${XDG\_RUNTIME\_DIR}/containers/auth.json`, which is set using `podman login`. +@@option creds -*IMPORTANT: The default path of the authentication file can be overwritten by setting the `REGISTRY\_AUTH\_FILE` environment variable. `export REGISTRY_AUTH_FILE=path`* - -#### **--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)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)** for details. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -#### **--creds**=*[username[:password]]* - -The [username[:password]] to use to authenticate with the registry if required. -If one or both values are not supplied, a command line prompt will appear and the -value can be entered. The password is entered without echo. - -#### **--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** @@ -83,6 +66,7 @@ Print the usage statement. #### **--os**=*OS* Override the OS, defaults to hosts, of the image to be pulled. For example, `windows`. +Unless overridden, subsequent lookups of the same image in the local storage will match this OS, regardless of the host. @@option platform diff --git a/docs/source/markdown/podman-push.1.md b/docs/source/markdown/podman-push.1.md.in index d674975b0..a98964e45 100644 --- a/docs/source/markdown/podman-push.1.md +++ b/docs/source/markdown/podman-push.1.md.in @@ -47,18 +47,9 @@ $ podman push myimage oci-archive:/tmp/myimage ## OPTIONS -#### **--authfile**=*path* +@@option authfile -Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`. -If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. - -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` - -#### **--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,21 +60,13 @@ Note: This flag can only be set when using the **dir** transport Specifies the compression format to use. Supported values are: `gzip`, `zstd` and `zstd:chunked`. The default is `gzip` unless overridden in the containers.conf file. -#### **--creds**=*[username[:password]]* - -The [username[:password]] to use to authenticate with the registry if required. -If one or both values are not supplied, a command line prompt will appear and the -value can be entered. The password is entered without echo. +@@option creds #### **--digestfile**=*Digestfile* 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-rename.1.md b/docs/source/markdown/podman-rename.1.md index 4017db505..0a807e6de 100644 --- a/docs/source/markdown/podman-rename.1.md +++ b/docs/source/markdown/podman-rename.1.md @@ -19,18 +19,18 @@ At present, only containers are supported; pods and volumes cannot be renamed. ## EXAMPLES +Rename container with a given name ``` -# Rename a container by name $ podman rename oldContainer aNewName ``` +Rename container with a given ID ``` -# Rename a container by ID $ podman rename 717716c00a6b testcontainer ``` +Create an alias for container with a given ID ``` -# Use the container rename alias $ podman container rename 6e7514b47180 databaseCtr ``` diff --git a/docs/source/markdown/podman-restart.1.md b/docs/source/markdown/podman-restart.1.md index 323087069..b9da413f7 100644 --- a/docs/source/markdown/podman-restart.1.md +++ b/docs/source/markdown/podman-restart.1.md @@ -14,14 +14,46 @@ Containers will be stopped if they are running and then restarted. Stopped containers will not be stopped and will only be started. ## OPTIONS + #### **--all**, **-a** + Restart all containers regardless of their current state. +#### **--cidfile** + +Read container ID from the specified file and restart the container. Can be specified multiple times. + +#### **--filter**, **-f**=*filter* + +Filter what containers restart. +Multiple filters can be given with multiple uses of the --filter flag. +Filters with the same key work inclusive with the only exception being +`label` which is exclusive. Filters with different keys always work exclusive. + +Valid filters are listed below: + +| **Filter** | **Description** | +| --------------- | -------------------------------------------------------------------------------- | +| id | [ID] Container's ID (accepts regex) | +| name | [Name] Container's name (accepts regex) | +| label | [Key] or [Key=Value] Label assigned to a container | +| exited | [Int] Container's exit code | +| status | [Status] Container's status: 'created', 'exited', 'paused', 'running', 'unknown' | +| ancestor | [ImageName] Image or descendant used to create container | +| before | [ID] or [Name] Containers created before this container | +| since | [ID] or [Name] Containers created since this container | +| volume | [VolumeName] or [MountpointDestination] Volume mounted in container | +| health | [Status] healthy or unhealthy | +| pod | [Pod] name or full or partial ID of pod | +| network | [Network] name or full ID of network | + #### **--latest**, **-l** + Instead of providing the container name or ID, use the last created container. If you use methods other than Podman to run containers such as CRI-O, the last started container could be from either of those methods. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) #### **--running** + Restart all containers that are already in the *running* state. #### **--time**, **-t**=*seconds* @@ -59,6 +91,12 @@ Restart all containers $ podman restart --all ``` +Restart container using ID specified in a given files. +``` +$ podman restart --cidfile /home/user/cidfile-1 +$ podman restart --cidfile /home/user/cidfile-1 --cidfile ./cidfile-2 +``` + ## SEE ALSO **[podman(1)](podman.1.md)** diff --git a/docs/source/markdown/podman-rm.1.md b/docs/source/markdown/podman-rm.1.md.in index 1dbd1d0c3..9eb44dcc1 100644 --- a/docs/source/markdown/podman-rm.1.md +++ b/docs/source/markdown/podman-rm.1.md.in @@ -18,9 +18,7 @@ Running or unusable containers will not be removed without the **-f** option. Remove all containers. Can be used in conjunction with **-f** as well. -#### **--cidfile** - -Read container ID from the specified file and remove the container. Can be specified multiple times. +@@option cidfile.read #### **--depend** @@ -58,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** @@ -79,37 +73,37 @@ Remove anonymous volumes associated with the container. This does not include na created with **podman volume create**, or the **--volume** option of **podman run** and **podman create**. ## EXAMPLE -Remove a container by its name *mywebserver* +Remove container with a given name ``` $ podman rm mywebserver ``` -Remove a *mywebserver* container and all of the containers that depend on it +Remove container with a given name and all of the containers that depend on it ``` $ podman rm --depend mywebserver ``` -Remove several containers by name and container id. +Remove multiple containers with given names or IDs ``` $ podman rm mywebserver myflaskserver 860a4b23 ``` -Remove several containers reading their IDs from files. +Remove multiple containers with IDs read from files ``` $ podman rm --cidfile ./cidfile-1 --cidfile /home/user/cidfile-2 ``` -Forcibly remove a container by container ID. +Forcibly remove container with a given ID ``` $ podman rm -f 860a4b23 ``` -Remove all containers regardless of its run state. +Remove all containers regardless of the run state ``` $ podman rm -f -a ``` -Forcibly remove the latest container created. +Forcibly remove the last created container ``` $ podman rm -f --latest ``` diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index 81b635bc8..6798c65da 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -100,12 +100,7 @@ error. It can even pretend to be a TTY (this is what most commandline executables expect) and pass along signals. The **-a** option can be set for each of **stdin**, **stdout**, and **stderr**. -#### **--authfile**=*[path]* - -Path to the authentication file. Default is *${XDG_RUNTIME_DIR}/containers/auth.json*. - -Note: You can also override the default path of the authentication file by setting the **REGISTRY_AUTH_FILE** -environment variable. +@@option authfile @@option blkio-weight @@ -125,9 +120,7 @@ environment variable. @@option chrootdirs -#### **--cidfile**=*file* - -Write the container ID to *file*. +@@option cidfile.write @@option conmon-pidfile @@ -141,15 +134,7 @@ Write the container ID to *file*. @@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 @@ -193,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* @@ -231,14 +218,9 @@ is the case the **--dns** flag is necessary for every run. The special value **none** can be specified to disable creation of _/etc/resolv.conf_ in the container by Podman. The _/etc/resolv.conf_ file in the image will be used without changes. -#### **--dns-opt**=*option* - -Set custom DNS options. Invalid if using **--dns-opt** with **--network** that is set to **none** or **container:**_id_. +@@option dns-opt.container -#### **--dns-search**=*domain* - -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. +@@option dns-search.container @@option entrypoint @@ -256,16 +238,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 @@ -330,18 +307,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* @@ -382,6 +348,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). @@ -392,6 +360,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. @@ -404,6 +374,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 @@ -470,6 +442,7 @@ This option conflicts with **--add-host**. #### **--os**=*OS* Override the OS, defaults to hosts, of the image to be pulled. For example, `windows`. +Unless overridden, subsequent lookups of the same image in the local storage will match this OS, regardless of the host. #### **--passwd** @@ -480,15 +453,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 @@ -502,10 +467,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* @@ -715,35 +677,7 @@ For the network namespace, the following sysctls are allowed: Note: if you use the **--network=host** option, these sysctls will not be allowed. -#### **--systemd**=*true* | *false* | *always* - -Run container in systemd mode. The default is **true**. - -The value *always* enforces the systemd mode is enforced without -looking at the executable name. Otherwise, if set to true and the -command you are running inside the container is **systemd**, **/usr/sbin/init**, -**/sbin/init** or **/usr/local/sbin/init**. - -Running the container in systemd mode causes the following changes: - -* Podman mounts tmpfs file systems on the following directories - * _/run_ - * _/run/lock_ - * _/tmp_ - * _/sys/fs/cgroup/systemd_ - * _/var/lib/journal_ -* Podman sets the default stop signal to **SIGRTMIN+3**. -* Podman sets **container_uuid** environment variable in the container to the -first 32 characters of the container id. - -This allows systemd to run in a confined container without any modifications. - -Note that on **SELinux** systems, systemd attempts to write to the cgroup -file system. Containers writing to the cgroup file system are denied by default. -The **container_manage_cgroup** boolean must be enabled for this to be allowed on an SELinux separated system. -``` -setsebool -P container_manage_cgroup true -``` +@@option systemd @@option timeout @@ -1043,13 +977,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-search.1.md b/docs/source/markdown/podman-search.1.md.in index 5b49d7f8e..9dd8cebf8 100644 --- a/docs/source/markdown/podman-search.1.md +++ b/docs/source/markdown/podman-search.1.md.in @@ -30,12 +30,7 @@ Further note that searching without a search term will only work for registries ## OPTIONS -#### **--authfile**=*path* - -Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json - -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` +@@option authfile #### **--compatible** diff --git a/docs/source/markdown/podman-secret-create.1.md b/docs/source/markdown/podman-secret-create.1.md index e08afb388..39e0c6843 100644 --- a/docs/source/markdown/podman-secret-create.1.md +++ b/docs/source/markdown/podman-secret-create.1.md @@ -20,7 +20,7 @@ Secrets will not be committed to an image with `podman commit`, and will not be ## OPTIONS -#### **--driver**=*driver* +#### **--driver**, **-d**=*driver* Specify the secret driver (default **file**, which is unencrypted). diff --git a/docs/source/markdown/podman-secret-inspect.1.md b/docs/source/markdown/podman-secret-inspect.1.md index df16ba6fa..1a7115f63 100644 --- a/docs/source/markdown/podman-secret-inspect.1.md +++ b/docs/source/markdown/podman-secret-inspect.1.md @@ -15,7 +15,7 @@ Secrets can be queried individually by providing their full name or a unique par ## OPTIONS -#### **--format**=*format* +#### **--format**, **-f**=*format* Format secret output using Go template. diff --git a/docs/source/markdown/podman-secret-ls.1.md b/docs/source/markdown/podman-secret-ls.1.md index 3b8535b5d..dcd10c9cf 100644 --- a/docs/source/markdown/podman-secret-ls.1.md +++ b/docs/source/markdown/podman-secret-ls.1.md @@ -30,7 +30,11 @@ Format secret output using Go template. #### **--noheading** -Omit the table headings from the listing of secrets. . +Omit the table headings from the listing of secrets. + +#### **--quiet**, **-q** + +Print secret IDs only. ## EXAMPLES diff --git a/docs/source/markdown/podman-stats.1.md b/docs/source/markdown/podman-stats.1.md index d87da6a60..8d07be1a0 100644 --- a/docs/source/markdown/podman-stats.1.md +++ b/docs/source/markdown/podman-stats.1.md @@ -61,6 +61,10 @@ Do not clear the terminal/screen in between reporting intervals Disable streaming stats and only pull the first result, default setting is false +#### **--no-trunc** + +Do not truncate output + ## EXAMPLE ``` @@ -77,6 +81,12 @@ a9f807ffaacd frosty_hodgkin -- 3.092MB / 16.7GB 0.02% -- / -- -- ``` ``` +$ podman stats --no-trunc 3667 --format 'table {{ .ID }} {{ .MemUsage }}' +ID MEM USAGE / LIMIT +3667c6aacb06aac2eaffce914c01736420023d56ef9b0f4cfe58b6d6a78b7503 49.15kB / 67.17GB +``` + +``` # podman stats --no-stream --format=json a9f80 [ { diff --git a/docs/source/markdown/podman-stop.1.md b/docs/source/markdown/podman-stop.1.md.in index cfc49afa1..9aaccdfaa 100644 --- a/docs/source/markdown/podman-stop.1.md +++ b/docs/source/markdown/podman-stop.1.md.in @@ -21,9 +21,7 @@ container and also via command line when creating the container. Stop all running containers. This does not include paused containers. -#### **--cidfile** - -Read container ID from the specified file and remove the container. Can be specified multiple times. +@@option cidfile.read #### **--filter**, **-f**=*filter* @@ -49,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*) diff --git a/docs/source/markdown/podman-unpause.1.md b/docs/source/markdown/podman-unpause.1.md.in index b94ace89e..7bd46e171 100644 --- a/docs/source/markdown/podman-unpause.1.md +++ b/docs/source/markdown/podman-unpause.1.md.in @@ -17,9 +17,7 @@ Unpauses the processes in one or more containers. You may use container IDs or Unpause all paused containers. -#### **--cidfile** - -Read container ID from the specified file and unpause the container. Can be specified multiple times. +@@option cidfile.read #### **--filter**, **-f**=*filter* |