diff options
Diffstat (limited to 'docs/source/markdown')
181 files changed, 881 insertions, 1643 deletions
diff --git a/docs/source/markdown/.gitignore b/docs/source/markdown/.gitignore index 8a0d553ba..74e7fc075 100644 --- a/docs/source/markdown/.gitignore +++ b/docs/source/markdown/.gitignore @@ -15,6 +15,7 @@ podman-manifest-push.1.md podman-pause.1.md podman-pod-clone.1.md podman-pod-create.1.md +podman-pod-kill.1.md podman-pod-logs.1.md podman-pod-rm.1.md podman-pod-start.1.md @@ -26,3 +27,4 @@ podman-run.1.md podman-search.1.md podman-stop.1.md podman-unpause.1.md +podman-update.1.md diff --git a/docs/source/markdown/links/podman-container-update.1 b/docs/source/markdown/links/podman-container-update.1 new file mode 100644 index 000000000..e903b5c06 --- /dev/null +++ b/docs/source/markdown/links/podman-container-update.1 @@ -0,0 +1 @@ +.so man1/podman-update.1 diff --git a/docs/source/markdown/options/README.md b/docs/source/markdown/options/README.md index 92f3d374e..d8b608fb7 100644 --- a/docs/source/markdown/options/README.md +++ b/docs/source/markdown/options/README.md @@ -43,4 +43,5 @@ This allows the shared use of examples in the option file: Example: podman <<subcommand>> --foo --bar ``` As a special case, `podman-pod-X` becomes just `X` (the "pod" is removed). -This makes the `pod-id-file` man page more useful. +This makes the `pod-id-file` man page more useful. To get the full +subcommand including 'pod', use `<<fullsubcommand>>`. diff --git a/docs/source/markdown/options/device-read-bps.md b/docs/source/markdown/options/device-read-bps.md new file mode 100644 index 000000000..f6617ab77 --- /dev/null +++ b/docs/source/markdown/options/device-read-bps.md @@ -0,0 +1,9 @@ +#### **--device-read-bps**=*path:rate* + +Limit read rate (in bytes per second) from a device (e.g. **--device-read-bps=/dev/sda:1mb**). + +On some systems, changing the resource limits may not be allowed for non-root +users. For more details, see +https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error + +This option is not supported on cgroups V1 rootless systems. diff --git a/docs/source/markdown/options/device-read-iops.md b/docs/source/markdown/options/device-read-iops.md new file mode 100644 index 000000000..944c66441 --- /dev/null +++ b/docs/source/markdown/options/device-read-iops.md @@ -0,0 +1,9 @@ +#### **--device-read-iops**=*path:rate* + +Limit read rate (in IO operations per second) from a device (e.g. **--device-read-iops=/dev/sda:1000**). + +On some systems, changing the resource limits may not be allowed for non-root +users. For more details, see +https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error + +This option is not supported on cgroups V1 rootless systems. diff --git a/docs/source/markdown/options/device-write-bps.md b/docs/source/markdown/options/device-write-bps.md new file mode 100644 index 000000000..ebcda0181 --- /dev/null +++ b/docs/source/markdown/options/device-write-bps.md @@ -0,0 +1,9 @@ +#### **--device-write-bps**=*path:rate* + +Limit write rate (in bytes per second) to a device (e.g. **--device-write-bps=/dev/sda:1mb**). + +On some systems, changing the resource limits may not be allowed for non-root +users. For more details, see +https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error + +This option is not supported on cgroups V1 rootless systems. diff --git a/docs/source/markdown/options/device-write-iops.md b/docs/source/markdown/options/device-write-iops.md new file mode 100644 index 000000000..6de273d18 --- /dev/null +++ b/docs/source/markdown/options/device-write-iops.md @@ -0,0 +1,9 @@ +#### **--device-write-iops**=*path:rate* + +Limit write rate (in IO operations per second) to a device (e.g. **--device-write-iops=/dev/sda:1000**). + +On some systems, changing the resource limits may not be allowed for non-root +users. For more details, see +https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error + +This option is not supported on cgroups V1 rootless systems. diff --git a/docs/source/markdown/options/device.md b/docs/source/markdown/options/device.md new file mode 100644 index 000000000..619c70a9b --- /dev/null +++ b/docs/source/markdown/options/device.md @@ -0,0 +1,14 @@ +#### **--device**=*host-device[:container-device][:permissions]* + +Add a host device to the <<container|pod>>. Optional *permissions* parameter +can be used to specify device permissions by combining +**r** for read, **w** for write, and **m** for **mknod**(2). + +Example: **--device=/dev/sdc:/dev/xvdc:rwm**. + +Note: if *host-device* is a symbolic link then it will be resolved first. +The <<container|pod>> will only store the major and minor numbers of the host device. + +Podman may load kernel modules required for using the specified +device. The devices that Podman will load modules for when necessary are: +/dev/fuse. diff --git a/docs/source/markdown/options/digestfile.md b/docs/source/markdown/options/digestfile.md new file mode 100644 index 000000000..de013e287 --- /dev/null +++ b/docs/source/markdown/options/digestfile.md @@ -0,0 +1,4 @@ +#### **--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) 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/health-on-failure.md b/docs/source/markdown/options/health-on-failure.md new file mode 100644 index 000000000..c25a1c574 --- /dev/null +++ b/docs/source/markdown/options/health-on-failure.md @@ -0,0 +1,8 @@ +#### **--health-on-failure**=*action* + +Action to take once the container transitions to an unhealthy state. The default is **none**. + +- **none**: Take no action. +- **kill**: Kill the container. +- **restart**: Restart the container. Do not combine the `restart` action with the `--restart` flag. When running inside of a systemd unit, consider using the `kill` or `stop` action instead to make use of systemd's restart policy. +- **stop**: Stop the container. diff --git a/docs/source/markdown/options/http-proxy.md b/docs/source/markdown/options/http-proxy.md new file mode 100644 index 000000000..f83dcde4a --- /dev/null +++ b/docs/source/markdown/options/http-proxy.md @@ -0,0 +1,15 @@ +#### **--http-proxy** + +By default proxy environment variables are passed into the container if set +for the Podman process. This can be disabled by setting the value to **false**. +The environment variables passed in include **http_proxy**, +**https_proxy**, **ftp_proxy**, **no_proxy**, and also the upper case versions of +those. This option is only needed when the host system must use a proxy but +the container should not use any proxy. Proxy environment variables specified +for the container in any other way will override the values that would have +been passed through from the host. (Other ways to specify the proxy for the +container include passing the values with the **--env** flag, or hard coding the +proxy environment at container build time.) +(This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + +Defaults to **true**. diff --git a/docs/source/markdown/options/label.md b/docs/source/markdown/options/label.md new file mode 100644 index 000000000..629aa82e6 --- /dev/null +++ b/docs/source/markdown/options/label.md @@ -0,0 +1,3 @@ +#### **--label**, **-l**=*key=value* + +Add metadata to a <<container|pod>>. diff --git a/docs/source/markdown/options/memory-reservation.md b/docs/source/markdown/options/memory-reservation.md new file mode 100644 index 000000000..410f1dd7c --- /dev/null +++ b/docs/source/markdown/options/memory-reservation.md @@ -0,0 +1,11 @@ +#### **--memory-reservation**=*number[unit]* + +Memory soft limit. A _unit_ can be **b** (bytes), **k** (kibibytes), **m** (mebibytes), or **g** (gibibytes). + +After setting memory reservation, when the system detects memory contention +or low memory, containers are forced to restrict their consumption to their +reservation. So you should always set the value below **--memory**, otherwise the +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. diff --git a/docs/source/markdown/options/memory-swap.md b/docs/source/markdown/options/memory-swap.md new file mode 100644 index 000000000..08ee8b1a0 --- /dev/null +++ b/docs/source/markdown/options/memory-swap.md @@ -0,0 +1,13 @@ +#### **--memory-swap**=*number[unit]* + +A limit value equal to memory plus swap. +A _unit_ can be **b** (bytes), **k** (kibibytes), **m** (mebibytes), or **g** (gibibytes). + +Must be used with the **-m** (**--memory**) flag. +The argument value should always be larger than that of + **-m** (**--memory**) By default, it is set to double +the value of **--memory**. + +Set _number_ to **-1** to enable unlimited swap. + +This option is not supported on cgroups V1 rootless systems. diff --git a/docs/source/markdown/options/memory.md b/docs/source/markdown/options/memory.md new file mode 100644 index 000000000..1be9159c3 --- /dev/null +++ b/docs/source/markdown/options/memory.md @@ -0,0 +1,11 @@ +#### **--memory**, **-m**=*number[unit]* + +Memory limit. A _unit_ can be **b** (bytes), **k** (kibibytes), **m** (mebibytes), or **g** (gibibytes). + +Allows the memory available to a container to be constrained. If the host +supports swap memory, then the **-m** memory setting can be larger than physical +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. diff --git a/docs/source/markdown/options/name.container.md b/docs/source/markdown/options/name.container.md new file mode 100644 index 000000000..0c3df6ef1 --- /dev/null +++ b/docs/source/markdown/options/name.container.md @@ -0,0 +1,14 @@ +#### **--name**=*name* + +Assign a name to the container. + +The operator can identify a container in three ways: + +- UUID long identifier (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”); +- UUID short identifier (“f78375b1c487”); +- Name (“jonah”). + +Podman generates a UUID for each container, and if a name is not assigned +to the container with **--name** then it will generate a random +string name. The name is useful any place you need to identify a container. +This works for both background and foreground containers. diff --git a/docs/source/markdown/options/privileged.md b/docs/source/markdown/options/privileged.md new file mode 100644 index 000000000..8d9746d6b --- /dev/null +++ b/docs/source/markdown/options/privileged.md @@ -0,0 +1,14 @@ +#### **--privileged** + +Give extended privileges to this container. The default is **false**. + +By default, Podman containers are unprivileged (**=false**) and cannot, for +example, modify parts of the operating system. This is because by default a +container is only allowed limited access to devices. A "privileged" container +is given the same access to devices as the user launching the container. + +A privileged container turns off the security features that isolate the +container from the host. Dropped Capabilities, limited devices, read-only mount +points, Apparmor/SELinux separation, and Seccomp filters are all disabled. + +Rootless containers cannot have more privileges than the account that launched them. diff --git a/docs/source/markdown/options/restart.md b/docs/source/markdown/options/restart.md new file mode 100644 index 000000000..825ae613f --- /dev/null +++ b/docs/source/markdown/options/restart.md @@ -0,0 +1,15 @@ +#### **--restart**=*policy* + +Restart policy to follow when containers exit. +Restart policy will not take effect if a container is stopped via the **podman kill** or **podman stop** commands. + +Valid _policy_ values are: + +- `no` : Do not restart containers on exit +- `on-failure[:max_retries]` : Restart containers when they exit with a non-zero exit code, retrying indefinitely or until the optional *max_retries* count is hit +- `always` : Restart containers when they exit, regardless of status, retrying indefinitely +- `unless-stopped` : Identical to **always** + +Please note that restart will not restart containers after a system reboot. +If this functionality is required in your environment, you can invoke Podman from a **systemd.unit**(5) file, or create an init script for whichever init system is in use. +To generate systemd unit files, please see **podman generate systemd**. diff --git a/docs/source/markdown/options/signal.md b/docs/source/markdown/options/signal.md new file mode 100644 index 000000000..6e6c03657 --- /dev/null +++ b/docs/source/markdown/options/signal.md @@ -0,0 +1,4 @@ +#### **--signal**, **-s**=**signal** + +Signal to send to the container<<|s in the pod>>. For more information on Linux signals, refer to *signal(7)*. +The default is **SIGKILL**. diff --git a/docs/source/markdown/options/subgidname.md b/docs/source/markdown/options/subgidname.md new file mode 100644 index 000000000..1ca0496d0 --- /dev/null +++ b/docs/source/markdown/options/subgidname.md @@ -0,0 +1,5 @@ +#### **--subgidname**=*name* + +Run the container in a new user namespace using the map with _name_ in the _/etc/subgid_ file. +If running rootless, the user needs to have the right to use the mapping. See **subgid**(5). +This flag conflicts with **--userns** and **--gidmap**. diff --git a/docs/source/markdown/options/subuidname.md b/docs/source/markdown/options/subuidname.md new file mode 100644 index 000000000..bd7b61575 --- /dev/null +++ b/docs/source/markdown/options/subuidname.md @@ -0,0 +1,5 @@ +#### **--subuidname**=*name* + +Run the container in a new user namespace using the map with _name_ in the _/etc/subuid_ file. +If running rootless, the user needs to have the right to use the mapping. See **subuid**(5). +This flag conflicts with **--userns** and **--uidmap**. diff --git a/docs/source/markdown/options/sysctl.md b/docs/source/markdown/options/sysctl.md new file mode 100644 index 000000000..6fc1bbebe --- /dev/null +++ b/docs/source/markdown/options/sysctl.md @@ -0,0 +1,21 @@ +#### **--sysctl**=*name=value* + +Configure namespaced kernel parameters <<at runtime|for all containers in the pod>>. + +For the IPC namespace, the following sysctls are allowed: + +- kernel.msgmax +- kernel.msgmnb +- kernel.msgmni +- kernel.sem +- kernel.shmall +- kernel.shmmax +- kernel.shmmni +- kernel.shm_rmid_forced +- Sysctls beginning with fs.mqueue.\* + +Note: <<if you use the **--ipc=host** option|if the ipc namespace is not shared within the pod>>, the above sysctls are not allowed. + +For the network namespace, only sysctls beginning with net.\* are allowed. + +Note: <<if you use the **--network=host** option|if the network namespace is not shared within the pod>>, the above sysctls are not allowed. 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/userns.container.md b/docs/source/markdown/options/userns.container.md new file mode 100644 index 000000000..8f96892df --- /dev/null +++ b/docs/source/markdown/options/userns.container.md @@ -0,0 +1,47 @@ +#### **--userns**=*mode* + +Set the user namespace mode for the container. It defaults to the **PODMAN_USERNS** environment variable. An empty value ("") means user namespaces are disabled unless an explicit mapping is set with the **--uidmap** and **--gidmap** options. + +This option is incompatible with **--gidmap**, **--uidmap**, **--subuidname** and **--subgidname**. + +Rootless user --userns=Key mappings: + +Key | Host User | Container User +----------|---------------|--------------------- +"" |$UID |0 (Default User account mapped to root user in container.) +keep-id |$UID |$UID (Map user account to same UID within container.) +auto |$UID | nil (Host User UID is not mapped into container.) +nomap |$UID | nil (Host User UID is not mapped into container.) + +Valid _mode_ values are: + +**auto**[:_OPTIONS,..._]: automatically create a unique user namespace. + +The `--userns=auto` flag, requires that the user name `containers` and a range of subordinate user ids that the Podman container is allowed to use be specified in the /etc/subuid and /etc/subgid files. + +Example: `containers:2147483647:2147483648`. + +Podman allocates unique ranges of UIDs and GIDs from the `containers` subordinate user ids. The size of the ranges is based on the number of UIDs required in the image. The number of UIDs and GIDs can be overridden with the `size` option. + +The rootless option `--userns=keep-id` uses all the subuids and subgids of the user. Using `--userns=auto` when starting new containers will not work as long as any containers exist that were started with `--userns=keep-id`. + + Valid `auto` options: + + - *gidmapping*=_CONTAINER_GID:HOST_GID:SIZE_: to force a GID mapping to be present in the user namespace. + - *size*=_SIZE_: to specify an explicit size for the automatic user namespace. e.g. `--userns=auto:size=8192`. If `size` is not specified, `auto` will estimate a size for the user namespace. + - *uidmapping*=_CONTAINER_UID:HOST_UID:SIZE_: to force a UID mapping to be present in the user namespace. + +**container:**_id_: join the user namespace of the specified container. + +**host**: run in the user namespace of the caller. The processes running in the container will have the same privileges on the host as any other process launched by the calling user (default). + +**keep-id**: creates a user namespace where the current rootless user's UID:GID are mapped to the same values in the container. This option is not allowed for containers created by the root user. + + Valid `keep-id` options: + + - *uid*=UID: override the UID inside the container that will be used to map the current rootless user to. + - *gid*=GID: override the GID inside the container that will be used to map the current rootless user to. + +**nomap**: creates a user namespace where the current rootless user's UID:GID are not mapped into the container. This option is not allowed for containers created by the root user. + +**ns:**_namespace_: run the <<container|pod>> in the given existing user namespace. diff --git a/docs/source/markdown/options/userns.pod.md b/docs/source/markdown/options/userns.pod.md new file mode 100644 index 000000000..389f47bd5 --- /dev/null +++ b/docs/source/markdown/options/userns.pod.md @@ -0,0 +1,28 @@ +#### **--userns**=*mode* + +Set the user namespace mode for all the containers in a pod. It defaults to the **PODMAN_USERNS** environment variable. An empty value ("") means user namespaces are disabled. + +Rootless user --userns=Key mappings: + +Key | Host User | Container User +----------|---------------|--------------------- +"" |$UID |0 (Default User account mapped to root user in container.) +keep-id |$UID |$UID (Map user account to same UID within container.) +auto |$UID | nil (Host User UID is not mapped into container.) +nomap |$UID | nil (Host User UID is not mapped into container.) + +Valid _mode_ values are: + + - *auto[:*_OPTIONS,..._*]*: automatically create a namespace. It is possible to specify these options to `auto`: + + - *gidmapping=*_CONTAINER_GID:HOST_GID:SIZE_ to force a GID mapping to be present in the user namespace. + + - *size=*_SIZE_: to specify an explicit size for the automatic user namespace. e.g. `--userns=auto:size=8192`. If `size` is not specified, `auto` will estimate a size for the user namespace. + + - *uidmapping=*_CONTAINER_UID:HOST_UID:SIZE_ to force a UID mapping to be present in the user namespace. + + - *host*: run in the user namespace of the caller. The processes running in the container will have the same privileges on the host as any other process launched by the calling user (default). + + - *keep-id*: creates a user namespace where the current rootless user's UID:GID are mapped to the same values in the container. This option is not allowed for containers created by the root user. + + - *nomap*: creates a user namespace where the current rootless user's UID:GID are not mapped into the container. This option is not allowed for containers created by the root user. diff --git a/docs/source/markdown/options/volume.md b/docs/source/markdown/options/volume.md new file mode 100644 index 000000000..6d0d9a4b3 --- /dev/null +++ b/docs/source/markdown/options/volume.md @@ -0,0 +1,176 @@ +#### **--volume**, **-v**=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]* + +Create a bind mount. If `-v /HOST-DIR:/CONTAINER-DIR` is specified, Podman +bind mounts `/HOST-DIR` in the host to `/CONTAINER-DIR` in the Podman +container. Similarly, `-v SOURCE-VOLUME:/CONTAINER-DIR` will mount the named +volume from the host into the container. If no such named volume exists, Podman will +create one. (Note when using the remote client, including Mac and Windows (excluding WSL2) machines, the volumes will be mounted from the remote server, not necessarily the client machine.) + +The _OPTIONS_ is a comma-separated list and can be: <sup>[[1]](#Footnote1)</sup> + +* **rw**|**ro** +* **z**|**Z** +* [**O**] +* [**U**] +* [**no**]**copy** +* [**no**]**dev** +* [**no**]**exec** +* [**no**]**suid** +* [**r**]**bind** +* [**r**]**shared**|[**r**]**slave**|[**r**]**private**[**r**]**unbindable** + +The `CONTAINER-DIR` must be an absolute path such as `/src/docs`. The volume +will be mounted into the container at this directory. + +Volumes may specify a source as well, as either a directory on the host +or the name of a named volume. If no source is given, the volume will be created as an +anonymously named volume with a randomly generated name, and will be removed when +the <<container|pod>> is removed via the `--rm` flag or the `podman rm --volumes` command. + +If a volume source is specified, it must be a path on the host or the name of a +named volume. Host paths are allowed to be absolute or relative; relative paths +are resolved relative to the directory Podman is run in. If the source does not +exist, Podman will return an error. Users must pre-create the source files or +directories. + +Any source that does not begin with a `.` or `/` will be treated as the name of +a named volume. If a volume with that name does not exist, it will be created. +Volumes created with names are not anonymous, and they are not removed by the `--rm` +option and the `podman rm --volumes` command. + +Specify multiple **-v** options to mount one or more volumes into a +<<container|pod>>. + + `Write Protected Volume Mounts` + +Add **:ro** or **:rw** option to mount a volume in read-only or +read-write mode, respectively. By default, the volumes are mounted read-write. +See examples. + + `Chowning Volume Mounts` + +By default, Podman does not change the owner and group of source volume +directories mounted into containers. If a <<container|pod>> is created in a new user +namespace, the UID and GID in the container may correspond to another UID and +GID on the host. + +The `:U` suffix tells Podman to use the correct host UID and GID based on the +UID and GID within the <<container|pod>>, to change recursively the owner and group of +the source volume. + +**Warning** use with caution since this will modify the host filesystem. + + `Labeling Volume Mounts` + +Labeling systems like SELinux require that proper labels are placed on volume +content mounted into a <<container|pod>>. Without a label, the security system might +prevent the processes running inside the <<container|pod>> from using the content. By +default, Podman does not change the labels set by the OS. + +To change a label in the <<container|pod>> context, add either of two suffixes +**:z** or **:Z** to the volume mount. These suffixes tell Podman to relabel file +objects on the shared volumes. The **z** option tells Podman that two <<containers|pods>> +share the volume content. As a result, Podman labels the content with a shared +content label. Shared volume labels allow all containers to read/write content. +The **Z** option tells Podman to label the content with a private unshared label. +Only the current <<container|pod>> can use a private volume. + +Note: Do not relabel system files and directories. Relabeling system content +might cause other confined services on your machine to fail. For these types +of containers we recommend disabling SELinux separation. The option +**--security-opt label=disable** disables SELinux separation for the <<container|pod>>. +For example if a user wanted to volume mount their entire home directory into a +<<container|pod>>, they need to disable SELinux separation. + + $ podman <<fullsubcommand>> --security-opt label=disable -v $HOME:/home/user fedora touch /home/user/file + + `Overlay Volume Mounts` + + The `:O` flag tells Podman to mount the directory from the host as a +temporary storage using the `overlay file system`. The <<container|pod>> processes +can modify content within the mountpoint which is stored in the +container storage in a separate directory. In overlay terms, the source +directory will be the lower, and the container storage directory will be the +upper. Modifications to the mount point are destroyed when the <<container|pod>> +finishes executing, similar to a tmpfs mount point being unmounted. + +For advanced users, the **overlay** option also supports custom non-volatile +**upperdir** and **workdir** for the overlay mount. Custom **upperdir** and +**workdir** can be fully managed by the users themselves, and Podman will not +remove it on lifecycle completion. +Example **:O,upperdir=/some/upper,workdir=/some/work** + + Subsequent executions of the container will see the original source directory +content, any changes from previous <<container|pod>> executions no longer exist. + + One use case of the overlay mount is sharing the package cache from the +host into the container to allow speeding up builds. + + Note: + + - The `O` flag conflicts with other options listed above. +Content mounted into the container is labeled with the private label. + On SELinux systems, labels in the source directory must be readable +by the <<|pod infra>> container label. Usually containers can read/execute `container_share_t` +and can read/write `container_file_t`. If unable to change the labels on a +source volume, SELinux container separation must be disabled for the <<|pod or infra>> container +to work. + - The source directory mounted into the <<container|pod>> with an overlay mount +should not be modified, it can cause unexpected failures. It is recommended +to not modify the directory until the container finishes running. + + `Mounts propagation` + +By default bind mounted volumes are `private`. That means any mounts done +inside the <<container|pod>> will not be visible on host and vice versa. One can change +this behavior by specifying a volume mount propagation property. Making a +volume shared mounts done under that volume inside the <<container|pod>> will be +visible on host and vice versa. Making a volume **slave** enables only one +way mount propagation and that is mounts done on host under that volume +will be visible inside container but not the other way around. <sup>[[1]](#Footnote1)</sup> + +To control mount propagation property of a volume one can use the [**r**]**shared**, +[**r**]**slave**, [**r**]**private** or the [**r**]**unbindable** propagation flag. +Propagation property can be specified only for bind mounted volumes and not for +internal volumes or named volumes. For mount propagation to work the source mount +point (the mount point where source dir is mounted on) has to have the right propagation +properties. For shared volumes, the source mount point has to be shared. And for +slave volumes, the source mount point has to be either shared or slave. +<sup>[[1]](#Footnote1)</sup> + +To recursively mount a volume and all of its submounts into a +<<container|pod>>, use the **rbind** option. By default the bind option is +used, and submounts of the source directory will not be mounted into the +<<container|pod>>. + +Mounting the volume with the **nosuid** options means that SUID applications on +the volume will not be able to change their privilege. By default volumes +are mounted with **nosuid**. + +Mounting the volume with the **noexec** option means that no executables on the +volume will be able to be executed within the <<container|pod>>. + +Mounting the volume with the **nodev** option means that no devices on the volume +will be able to be used by processes within the <<container|pod>>. By default volumes +are mounted with **nodev**. + +If the _HOST-DIR_ is a mount point, then **dev**, **suid**, and **exec** options are +ignored by the kernel. + +Use **df HOST-DIR** to figure out the source mount, then use +**findmnt -o TARGET,PROPAGATION _source-mount-dir_** to figure out propagation +properties of source mount. If **findmnt**(1) utility is not available, then one +can look at the mount entry for the source mount point in _/proc/self/mountinfo_. Look +at the "optional fields" and see if any propagation properties are specified. +In there, **shared:N** means the mount is shared, **master:N** means mount +is slave, and if nothing is there, the mount is private. <sup>[[1]](#Footnote1)</sup> + +To change propagation properties of a mount point, use **mount**(8) command. For +example, if one wants to bind mount source directory _/foo_, one can do +**mount --bind /foo /foo** and **mount --make-private --make-shared /foo**. This +will convert /foo into a shared mount point. Alternatively, one can directly +change propagation properties of source mount. Say _/_ is source mount for +_/foo_, then use **mount --make-shared /** to convert _/_ into a shared mount. + +Note: if the user only has access rights via a group, accessing the volume +from inside a rootless <<container|pod>> will fail. diff --git a/docs/source/markdown/podman-attach.1.md b/docs/source/markdown/podman-attach.1.md index 985cfa0e8..c073fccf8 100644 --- a/docs/source/markdown/podman-attach.1.md +++ b/docs/source/markdown/podman-attach.1.md @@ -1,4 +1,4 @@ -% podman-attach(1) +% podman-attach 1 ## NAME podman\-attach - Attach to a running container diff --git a/docs/source/markdown/podman-auto-update.1.md.in b/docs/source/markdown/podman-auto-update.1.md.in index bc92d6165..cd9a08a78 100644 --- a/docs/source/markdown/podman-auto-update.1.md.in +++ b/docs/source/markdown/podman-auto-update.1.md.in @@ -1,4 +1,4 @@ -% podman-auto-update(1) +% podman-auto-update 1 ## NAME podman\-auto-update - Auto update containers according to their auto-update policy @@ -29,6 +29,18 @@ This data is then being used in the auto-update sequence to instruct systemd (vi Note that **podman auto-update** relies on systemd. The systemd units are expected to be generated with **[podman-generate-systemd --new](podman-generate-systemd.1.md#--new)**, or similar units that create new containers in order to run the updated images. Systemd units that start and stop a container cannot run a new image. +### Auto Updates and Kubernetes YAML + +Podman supports auto updates for Kubernetes workloads. As mentioned above, `podman auto-update` requires the containers to be running systemd. Podman ships with a systemd template that can be instantiated with a Kubernetes YAML file, see podman-generate-systemd(1). + +To enable auto updates for containers running in a Kubernetes workload, set the following Podman-specific annotations in the YAML: + * `io.containers.autoupdate: "registry|local"` to apply the auto-update policy to all containers + * `io.containers.autoupdate/$container: "registry|local"` to apply the auto-update policy to `$container` only + * `io.containers.sdnotify: "conmon|container"` to apply the sdnotify policy to all containers + * `io.containers.sdnotify/$container: "conmon|container"` to apply the sdnotify policy to `$container` only + +By default, the autoupdate policy is set to "disabled", the sdnotify policy is set to "conmon". + ### Systemd Unit and Timer 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**. diff --git a/docs/source/markdown/podman-build.1.md.in b/docs/source/markdown/podman-build.1.md.in index 693e0d3b9..ab31c492c 100644 --- a/docs/source/markdown/podman-build.1.md.in +++ b/docs/source/markdown/podman-build.1.md.in @@ -1,4 +1,4 @@ -% podman-build(1) +% podman-build 1 ## NAME podman\-build - Build a container image using a Containerfile @@ -156,8 +156,8 @@ more. When executing RUN instructions, run the command specified in the instruction with the specified capability removed from its capability set. -The CAP\_AUDIT\_WRITE, CAP\_CHOWN, CAP\_DAC\_OVERRIDE, CAP\_FOWNER, -CAP\_FSETID, CAP\_KILL, CAP\_MKNOD, CAP\_NET\_BIND\_SERVICE, CAP\_SETFCAP, +The CAP\_CHOWN, CAP\_DAC\_OVERRIDE, CAP\_FOWNER, +CAP\_FSETID, CAP\_KILL, CAP\_NET\_BIND\_SERVICE, CAP\_SETFCAP, CAP\_SETGID, CAP\_SETPCAP, CAP\_SETUID, and CAP\_SYS\_CHROOT capabilities are granted by default; this option can be used to remove them. @@ -205,16 +205,7 @@ keys and/or certificates. Decryption will be tried with all keys. If the key is protected by a passphrase, it is required to be passed in the argument and omitted otherwise. -#### **--device**=*host-device[:container-device][:permissions]* - -Add a host device to the container. Optional *permissions* parameter -can be used to specify device permissions, it is combination of -**r** for read, **w** for write, and **m** for **mknod**(2). - -Example: **--device=/dev/sdc:/dev/xvdc:rwm**. - -Note: if *host-device* is a symbolic link then it will be resolved first. -The container will only store the major and minor numbers of the host device. +@@option device Note: if the user only has access rights via a group, accessing the device from inside a rootless container will fail. The **[crun(1)](https://github.com/containers/crun/tree/main/crun.1.md)** runtime offers a @@ -391,28 +382,9 @@ This option is not supported on the remote client, including Mac and Windows Name of the manifest list to which the image will be added. Creates the manifest list if it does not exist. This option is useful for building multi architecture images. -#### **--memory**, **-m**=*LIMIT* - -Memory limit (format: `<number>[<unit>]`, where unit = b (bytes), k (kibibytes), -m (mebibytes), or g (gibibytes)) - -Allows you to constrain the memory available to a container. If the host -supports swap memory, then the **-m** memory setting can be larger than physical -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). - -#### **--memory-swap**=*LIMIT* +@@option memory -A limit value equal to memory plus swap. Must be used with the **-m** -(**--memory**) option. The swap `LIMIT` should always be larger than **-m** -(**--memory**) value. By default, the swap `LIMIT` will be set to double -the value of --memory. - -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. +@@option memory-swap #### **--network**=*mode*, **--net** @@ -540,6 +512,16 @@ Suppress output messages which indicate which instruction is being processed, and of progress when pulling images from a registry, and when writing the output image. +#### **--retry**=*attempts* + +Number of times to retry in case of failure when performing pull of +images from registry. Default is **3**. + +#### **--retry-delay**=*duration* + +Duration of delay between retry attempts in case of failure when performing +pull of images from registry. Default is **2s**. + #### **--rm** Remove intermediate containers after a successful build (default true). diff --git a/docs/source/markdown/podman-commit.1.md b/docs/source/markdown/podman-commit.1.md index b7b52e3a7..82243c557 100644 --- a/docs/source/markdown/podman-commit.1.md +++ b/docs/source/markdown/podman-commit.1.md @@ -1,4 +1,4 @@ -% podman-commit(1) +% podman-commit 1 ## NAME podman\-commit - Create new image based on the changed container diff --git a/docs/source/markdown/podman-completion.1.md b/docs/source/markdown/podman-completion.1.md index 538bb9e60..14e196587 100644 --- a/docs/source/markdown/podman-completion.1.md +++ b/docs/source/markdown/podman-completion.1.md @@ -1,4 +1,4 @@ -% podman-completion(1) +% podman-completion 1 ## NAME podman\-completion - Generate shell completion scripts diff --git a/docs/source/markdown/podman-container-checkpoint.1.md b/docs/source/markdown/podman-container-checkpoint.1.md index a11897081..b68dffc8a 100644 --- a/docs/source/markdown/podman-container-checkpoint.1.md +++ b/docs/source/markdown/podman-container-checkpoint.1.md @@ -1,4 +1,4 @@ -% podman-container-checkpoint(1) +% podman-container-checkpoint 1 ## NAME podman\-container\-checkpoint - Checkpoints one or more running containers diff --git a/docs/source/markdown/podman-container-cleanup.1.md b/docs/source/markdown/podman-container-cleanup.1.md index 0ad09efd3..744f7b41b 100644 --- a/docs/source/markdown/podman-container-cleanup.1.md +++ b/docs/source/markdown/podman-container-cleanup.1.md @@ -1,4 +1,4 @@ -% podman-container-cleanup(1) +% podman-container-cleanup 1 ## NAME podman\-container\-cleanup - Clean up the container's network and mountpoints diff --git a/docs/source/markdown/podman-container-clone.1.md.in b/docs/source/markdown/podman-container-clone.1.md.in index 26f414b62..d4add19fd 100644 --- a/docs/source/markdown/podman-container-clone.1.md.in +++ b/docs/source/markdown/podman-container-clone.1.md.in @@ -1,4 +1,4 @@ -% podman-container-clone(1) +% podman-container-clone 1 ## NAME podman\-container\-clone - Creates a copy of an existing container @@ -52,60 +52,27 @@ If none are specified, the original container's CPU memory nodes are used. @@option destroy -#### **--device-read-bps**=*path* +@@option device-read-bps -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. +@@option device-write-bps #### **--force**, **-f** Force removal of the original container that we are cloning. Can only be used in conjunction with **--destroy**. -#### **--memory**, **-m**=*limit* - -Memory limit (format: `<number>[<unit>]`, where unit = b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes)) - -Allows the memory available to a container to be constrained. If the host -supports swap memory, then the **-m** memory setting can be larger than physical -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). +@@option memory 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)) - -After setting memory reservation, when the system detects memory contention -or low memory, containers are forced to restrict their consumption to their -reservation. So you should always set the value below **--memory**, otherwise the -hard limit will take precedence. By default, memory reservation will be the same -as memory limit from the container being cloned. +@@option memory-reservation -This option is not supported on cgroups V1 rootless systems. - -#### **--memory-swap**=*limit* +If unspecified, memory reservation will be the same as memory limit from the +container being cloned. -A limit value equal to memory plus swap. Must be used with the **-m** -(**--memory**) flag. The swap `LIMIT` should always be larger than **-m** -(**--memory**) value. By default, the swap `LIMIT` will be set to double -the value of --memory if specified. Otherwise, the container being cloned will be used to derive the swap value. +@@option memory-swap -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. +If unspecified, the container being cloned will be used to derive +the swap value. @@option memory-swappiness diff --git a/docs/source/markdown/podman-container-diff.1.md b/docs/source/markdown/podman-container-diff.1.md index f09bc4896..261c6f878 100644 --- a/docs/source/markdown/podman-container-diff.1.md +++ b/docs/source/markdown/podman-container-diff.1.md @@ -1,4 +1,4 @@ -% podman-container-diff(1) +% podman-container-diff 1 ## NAME podman\-container\-diff - Inspect changes on a container's filesystem diff --git a/docs/source/markdown/podman-container-exists.1.md b/docs/source/markdown/podman-container-exists.1.md index cc5defe6b..49b74f1ee 100644 --- a/docs/source/markdown/podman-container-exists.1.md +++ b/docs/source/markdown/podman-container-exists.1.md @@ -1,4 +1,4 @@ -% podman-container-exists(1) +% podman-container-exists 1 ## NAME podman\-container\-exists - Check if a container exists in local storage diff --git a/docs/source/markdown/podman-container-inspect.1.md b/docs/source/markdown/podman-container-inspect.1.md index 4e45bcc40..f92eea7bd 100644 --- a/docs/source/markdown/podman-container-inspect.1.md +++ b/docs/source/markdown/podman-container-inspect.1.md @@ -1,4 +1,4 @@ -% podman-container-inspect(1) +% podman-container-inspect 1 ## NAME podman\-container\-inspect - Display a container's configuration diff --git a/docs/source/markdown/podman-container-prune.1.md b/docs/source/markdown/podman-container-prune.1.md index b20936c15..66519b96d 100644 --- a/docs/source/markdown/podman-container-prune.1.md +++ b/docs/source/markdown/podman-container-prune.1.md @@ -1,4 +1,4 @@ -% podman-container-prune(1) +% podman-container-prune 1 ## NAME podman\-container\-prune - Remove all stopped containers from local storage diff --git a/docs/source/markdown/podman-container-restore.1.md b/docs/source/markdown/podman-container-restore.1.md index a70cc30d1..a5347fa48 100644 --- a/docs/source/markdown/podman-container-restore.1.md +++ b/docs/source/markdown/podman-container-restore.1.md @@ -1,4 +1,4 @@ -% podman-container-restore(1) +% podman-container-restore 1 ## NAME podman\-container\-restore - Restores one or more containers from a checkpoint diff --git a/docs/source/markdown/podman-container-runlabel.1.md.in b/docs/source/markdown/podman-container-runlabel.1.md.in index f5fb8ca60..36e021ce4 100644 --- a/docs/source/markdown/podman-container-runlabel.1.md.in +++ b/docs/source/markdown/podman-container-runlabel.1.md.in @@ -1,4 +1,4 @@ -% podman-container-runlabel(1) +% podman-container-runlabel 1 ## NAME podman-container-runlabel - Executes a command as described by a container-image label diff --git a/docs/source/markdown/podman-container.1.md b/docs/source/markdown/podman-container.1.md index a66e2789d..1662000ed 100644 --- a/docs/source/markdown/podman-container.1.md +++ b/docs/source/markdown/podman-container.1.md @@ -1,4 +1,4 @@ -% podman-container(1) +% podman-container 1 ## NAME podman\-container - Manage containers @@ -46,6 +46,7 @@ The container command allows you to manage containers | top | [podman-top(1)](podman-top.1.md) | Display the running processes of a container. | | unmount | [podman-unmount(1)](podman-unmount.1.md) | Unmount a working container's root filesystem.(Alias unmount) | | unpause | [podman-unpause(1)](podman-unpause.1.md) | Unpause one or more containers. | +| update | [podman-update(1)](podman-update.1.md) | Updates the cgroup configuration of a given container. | | wait | [podman-wait(1)](podman-wait.1.md) | Wait on one or more containers to stop and print their exit codes. | ## SEE ALSO diff --git a/docs/source/markdown/podman-cp.1.md b/docs/source/markdown/podman-cp.1.md index bb86e3f13..49a3a8cd8 100644 --- a/docs/source/markdown/podman-cp.1.md +++ b/docs/source/markdown/podman-cp.1.md @@ -1,4 +1,4 @@ -% podman-cp(1) +% podman-cp 1 ## NAME podman\-cp - Copy files/folders between a container and the local filesystem diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index 4dbc75551..17ef704e6 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -1,4 +1,4 @@ -% podman-create(1) +% podman-create 1 ## NAME podman\-create - Create a new container @@ -87,9 +87,7 @@ each of stdin, stdout, and stderr. @@option blkio-weight -#### **--blkio-weight-device**=*device:weight* - -Block IO relative device weight. +@@option blkio-weight-device @@option cap-add @@ -125,50 +123,21 @@ Block IO relative device weight. @@option cpuset-mems -#### **--device**=*host-device[:container-device][:permissions]* - -Add a host device to the container. Optional *permissions* parameter -can be used to specify device permissions, it is combination of -**r** for read, **w** for write, and **m** for **mknod**(2). - -Example: **--device=/dev/sdc:/dev/xvdc:rwm**. - -Note: if *host-device* is a symbolic link then it will be resolved first. -The container will only store the major and minor numbers of the host device. +@@option device Note: if the user only has access rights via a group, accessing the device from inside a rootless container will fail. Use the `--group-add keep-groups` flag to pass the user's supplementary group access into the container. -Podman may load kernel modules required for using the specified -device. The devices that podman will load modules when necessary are: -/dev/fuse. - @@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. +@@option device-read-bps -#### **--device-read-iops**=*path* +@@option device-read-iops -Limit read rate (IO per second) from a device (e.g. --device-read-iops=/dev/sda:1000) +@@option device-write-bps -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) - -This option is not supported on cgroups V1 rootless systems. +@@option device-write-iops @@option disable-content-trust @@ -184,13 +153,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 @@ -220,6 +185,8 @@ Read in a line delimited file of environment variables. See **Environment** note @@option health-interval +@@option health-on-failure + @@option health-retries @@option health-start-period @@ -234,25 +201,7 @@ Print usage statement @@option hostuser -#### **--http-proxy** - -By default proxy environment variables are passed into the container if set -for the Podman process. This can be disabled by setting the `--http-proxy` -option to `false`. The environment variables passed in include `http_proxy`, -`https_proxy`, `ftp_proxy`, `no_proxy`, and also the upper case versions of -those. This option is only needed when the host system must use a proxy but -the container should not use any proxy. Proxy environment variables specified -for the container in any other way will override the values that would have -been passed through from the host. (Other ways to specify the proxy for the -container include passing the values with the `--env` flag, or hard coding the -proxy environment at container build time.) (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -For example, to disable passing these environment variables from host to -container: - -`--http-proxy=false` - -Defaults to `true` +@@option http-proxy @@option image-volume @@ -300,9 +249,7 @@ To specify multiple static IPv6 addresses per container, set multiple networks u @@option ipc -#### **--label**, **-l**=*label* - -Add metadata to a container (e.g., --label com.example.key=value) +@@option label @@option label-file @@ -329,60 +276,17 @@ This option is currently supported only by the **journald** log driver. @@option mac-address -#### **--memory**, **-m**=*limit* - -Memory limit (format: `<number>[<unit>]`, where unit = b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes)) - -Allows you to constrain the memory available to a container. If the host -supports swap memory, then the **-m** memory setting can be larger than physical -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)) - -After setting memory reservation, when the system detects memory contention -or low memory, containers are forced to restrict their consumption to their -reservation. So you should always set the value below **--memory**, otherwise the -hard limit will take precedence. By default, memory reservation will be the same -as memory limit. +@@option memory -This option is not supported on cgroups V1 rootless systems. +@@option memory-reservation -#### **--memory-swap**=*limit* - -A limit value equal to memory plus swap. Must be used with the **-m** -(**--memory**) flag. The swap `LIMIT` should always be larger than **-m** -(**--memory**) value. By default, the swap `LIMIT` will be set to double -the value of --memory. - -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-swap @@option memory-swappiness @@option mount -#### **--name**=*name* - -Assign a name to the container - -The operator can identify a container in three ways: -UUID long identifier (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”) -UUID short identifier (“f78375b1c487”) -Name (“jonah”) - -podman generates a UUID for each container, and if a name is not assigned -to the container with **--name** then it will generate a random -string name. The name is useful any place you need to identify a container. -This works for both background and foreground containers. +@@option name.container #### **--network**=*mode*, **--net** @@ -452,21 +356,7 @@ To make a pod with more granular options, use the `podman pod create` command be @@option pod-id-file.container -#### **--privileged** - -Give extended privileges to this container. The default is *false*. - -By default, Podman containers are -“unprivileged” (=false) and cannot, for example, modify parts of the operating system. -This is because by default a container is not allowed to access any devices. -A “privileged” container is given access to all devices. - -When the operator executes a privileged container, Podman enables access -to all devices on the host, turns off graphdriver mount options, as well as -turning off most of the security measures protecting the host from the -container. - -Rootless containers cannot have more privileges than the account that launched them. +@@option privileged #### **--publish**, **-p**=*[[ip:][hostPort]:]containerPort[/protocol]* @@ -522,21 +412,7 @@ Suppress output information when pulling images @@option requires -#### **--restart**=*policy* - -Restart policy to follow when containers exit. -Restart policy will not take effect if a container is stopped via the `podman kill` or `podman stop` commands. - -Valid values are: - -- `no` : Do not restart containers on exit -- `on-failure[:max_retries]` : Restart containers when they exit with a non-0 exit code, retrying indefinitely or until the optional max_retries count is hit -- `always` : Restart containers when they exit, regardless of status, retrying indefinitely -- `unless-stopped` : Identical to **always** - -Please note that restart will not restart containers after a system reboot. -If this functionality is required in your environment, you can invoke Podman from a systemd unit file, or create an init script for whichever init system is in use. -To generate systemd unit files, please see *podman generate systemd* +@@option restart #### **--rm** @@ -608,58 +484,13 @@ When size is `0`, there is no limit on the amount of memory used for IPC by the @@option stop-timeout -#### **--subgidname**=*name* - -Name for GID map from the `/etc/subgid` file. Using this flag will run the container with user namespace enabled. This flag conflicts with `--userns` and `--gidmap`. - -#### **--subuidname**=*name* - -Name for UID map from the `/etc/subuid` file. Using this flag will run the container with user namespace enabled. This flag conflicts with `--userns` and `--uidmap`. - -#### **--sysctl**=*SYSCTL* - -Configure namespaced kernel parameters at runtime - -IPC Namespace - current sysctls allowed: - -kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, kernel.shmall, kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced -Sysctls beginning with fs.mqueue.* - -Note: if you use the --ipc=host option these sysctls will not be allowed. - -Network Namespace - current sysctls allowed: - Sysctls beginning with net.* - -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*. +@@option subgidname -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**. +@@option subuidname -Running the container in systemd mode causes the following changes: +@@option sysctl -* 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 @@ -701,223 +532,16 @@ The following examples are all valid: Without this argument the command will be run as root in the container. -#### **--userns**=*mode* - -Set the user namespace mode for the container. It defaults to the **PODMAN_USERNS** environment variable. An empty value ("") means user namespaces are disabled unless an explicit mapping is set with the **--uidmap** and **--gidmap** options. - -Rootless user --userns=Key mappings: - -Key | Host User | Container User -----------|---------------|--------------------- -"" |$UID |0 (Default User account mapped to root user in container.) -keep-id |$UID |$UID (Map user account to same UID within container.) -auto |$UID | nil (Host User UID is not mapped into container.) -nomap |$UID | nil (Host User UID is not mapped into container.) - -Valid _mode_ values are: - -**auto**[:_OPTIONS,..._]: automatically create a unique user namespace. - -The `--userns=auto` flag, requires that the user name `containers` and a range of subordinate user ids that the Podman container is allowed to use be specified in the /etc/subuid and /etc/subgid files. - -Example: `containers:2147483647:2147483648`. - -Podman allocates unique ranges of UIDs and GIDs from the `containers` subordinate user ids. The size of the ranges is based on the number of UIDs required in the image. The number of UIDs and GIDs can be overridden with the `size` option. The `auto` options currently does not work in rootless mode - - Valid `auto` options: - - - *gidmapping*=_CONTAINER_GID:HOST_GID:SIZE_: to force a GID mapping to be present in the user namespace. - - *size*=_SIZE_: to specify an explicit size for the automatic user namespace. e.g. `--userns=auto:size=8192`. If `size` is not specified, `auto` will estimate a size for the user namespace. - - *uidmapping*=_CONTAINER_UID:HOST_UID:SIZE_: to force a UID mapping to be present in the user namespace. - -**container:**_id_: join the user namespace of the specified container. - -**host**: run in the user namespace of the caller. The processes running in the container will have the same privileges on the host as any other process launched by the calling user (default). - -**keep-id**: creates a user namespace where the current rootless user's UID:GID are mapped to the same values in the container. This option is not allowed for containers created by the root user. - -**nomap**: creates a user namespace where the current rootless user's UID:GID are not mapped into the container. This option is not allowed for containers created by the root user. - -**ns:**_namespace_: run the container in the given existing user namespace. - -**private**: create a new namespace for the container. - -This option is incompatible with **--gidmap**, **--uidmap**, **--subuidname** and **--subgidname**. +@@option userns.container @@option uts.container #### **--variant**=*VARIANT* Use _VARIANT_ instead of the default architecture variant of the container image. Some images can use multiple variants of the arm architectures, such as arm/v5 and arm/v7. -#### **--volume**, **-v**=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]* - -Create a bind mount. If you specify, ` -v /HOST-DIR:/CONTAINER-DIR`, Podman -bind mounts `/HOST-DIR` in the host to `/CONTAINER-DIR` in the Podman -container. Similarly, `-v SOURCE-VOLUME:/CONTAINER-DIR` will mount the volume -in the host to the container. If no such named volume exists, Podman will -create one. The `OPTIONS` are a comma-separated list and can be: <sup>[[1]](#Footnote1)</sup> (Note when using the remote client, including Mac and Windows (excluding WSL2) machines, the volumes will be mounted from the remote server, not necessarily the client machine.) - -The _options_ is a comma-separated list and can be: - -* **rw**|**ro** -* **z**|**Z** -* [**O**] -* [**U**] -* [**no**]**copy** -* [**no**]**dev** -* [**no**]**exec** -* [**no**]**suid** -* [**r**]**bind** -* [**r**]**shared**|[**r**]**slave**|[**r**]**private**[**r**]**unbindable** - -The `CONTAINER-DIR` must be an absolute path such as `/src/docs`. The volume -will be mounted into the container at this directory. - -Volumes may specify a source as well, as either a directory on the host -or the name of a named volume. If no source is given, the volume will be created as an -anonymously named volume with a randomly generated name, and will be removed when -the container is removed via the `--rm` flag or `podman rm --volumes`. +@@option volume -If a volume source is specified, it must be a path on the host or the name of a -named volume. Host paths are allowed to be absolute or relative; relative paths -are resolved relative to the directory Podman is run in. If the source does not -exist, Podman will return an error. Users must pre-create the source files or -directories. - -Any source that does not begin with a `.` or `/` will be treated as the name of -a named volume. If a volume with that name does not exist, it will be created. -Volumes created with names are not anonymous, and they are not removed by the `--rm` -option and the `podman rm --volumes` command. - -You can specify multiple **-v** options to mount one or more volumes into a -container. - - `Write Protected Volume Mounts` - -You can add `:ro` or `:rw` suffix to a volume to mount it read-only or -read-write mode, respectively. By default, the volumes are mounted read-write. -See examples. - - `Chowning Volume Mounts` - -By default, Podman does not change the owner and group of source volume -directories mounted into containers. If a container is created in a new user -namespace, the UID and GID in the container may correspond to another UID and -GID on the host. - -The `:U` suffix tells Podman to use the correct host UID and GID based on the -UID and GID within the container, to change recursively the owner and group of -the source volume. - -**Warning** use with caution since this will modify the host filesystem. - - `Labeling Volume Mounts` - -Labeling systems like SELinux require that proper labels are placed on volume -content mounted into a container. Without a label, the security system might -prevent the processes running inside the container from using the content. By -default, Podman does not change the labels set by the OS. - -To change a label in the container context, you can add either of two suffixes -`:z` or `:Z` to the volume mount. These suffixes tell Podman to relabel file -objects on the shared volumes. The `z` option tells Podman that two containers -share the volume content. As a result, Podman labels the content with a shared -content label. Shared volume labels allow all containers to read/write content. -The `Z` option tells Podman to label the content with a private unshared label. -Only the current container can use a private volume. - -Note: Do not relabel system files and directories. Relabeling system content -might cause other confined services on your machine to fail. For these types -of containers we recommend disabling SELinux separation. The option -`--security-opt label=disable` disables SELinux separation for containers used in the build. -For example if a user wanted to volume mount their entire home directory into a -container, they need to disable SELinux separation. - - $ podman create --security-opt label=disable -v $HOME:/home/user fedora touch /home/user/file - - `Overlay Volume Mounts` - - The `:O` flag tells Podman to mount the directory from the host as a -temporary storage using the `overlay file system`. The container processes -can modify content within the mountpoint which is stored in the -container storage in a separate directory. In overlay terms, the source -directory will be the lower, and the container storage directory will be the -upper. Modifications to the mount point are destroyed when the container -finishes executing, similar to a tmpfs mount point being unmounted. - - Subsequent executions of the container will see the original source directory -content, any changes from previous container executions no longer exist. - - One use case of the overlay mount is sharing the package cache from the -host into the container to allow speeding up builds. - - Note: - - - The `O` flag conflicts with other options listed above. -Content mounted into the container is labeled with the private label. - On SELinux systems, labels in the source directory must be readable -by the container label. Usually containers can read/execute `container_share_t` -and can read/write `container_file_t`. If you cannot change the labels on a -source volume, SELinux container separation must be disabled for the container -to work. - - The source directory mounted into the container with an overlay mount -should not be modified, it can cause unexpected failures. It is recommended -that you do not modify the directory until the container finishes running. - - `Mounts propagation` - -By default bind mounted volumes are `private`. That means any mounts done -inside container will not be visible on host and vice versa. One can change -this behavior by specifying a volume mount propagation property. Making a -volume `shared` mounts done under that volume inside container will be -visible on host and vice versa. Making a volume `slave` enables only one -way mount propagation and that is mounts done on host under that volume -will be visible inside container but not the other way around. <sup>[[1]](#Footnote1)</sup> - -To control mount propagation property of a volume one can use the [**r**]**shared**, -[**r**]**slave**, [**r**]**private** or the [**r**]**unbindable** propagation flag. -For mount propagation to work the source mount point (the mount point where source dir -is mounted on) has to have the right propagation properties. For shared volumes, the -source mount point has to be shared. And for slave volumes, the source mount point -has to be either shared or slave. <sup>[[1]](#Footnote1)</sup> - -If you want to recursively mount a volume and all of its submounts into a -container, then you can use the `rbind` option. By default the bind option is -used, and submounts of the source directory will not be mounted into the -container. - -Mounting the volume with the `nosuid` options means that SUID applications on -the volume will not be able to change their privilege. By default volumes -are mounted with `nosuid`. - -Mounting the volume with the noexec option means that no executables on the -volume will be able to be executed within the container. - -Mounting the volume with the nodev option means that no devices on the volume -will be able to be used by processes within the container. By default volumes -are mounted with `nodev`. - -If the `<source-dir>` is a mount point, then "dev", "suid", and "exec" options are -ignored by the kernel. - -Use `df <source-dir>` to figure out the source mount and then use -`findmnt -o TARGET,PROPAGATION <source-mount-dir>` to figure out propagation -properties of source mount. If `findmnt` utility is not available, then one -can look at mount entry for source mount point in `/proc/self/mountinfo`. Look -at `optional fields` and see if any propagation properties are specified. -`shared:X` means mount is `shared`, `master:X` means mount is `slave` and if -nothing is there that means mount is `private`. <sup>[[1]](#Footnote1)</sup> - -To change propagation properties of a mount point use `mount` command. For -example, if one wants to bind mount source directory `/foo` one can do -`mount --bind /foo /foo` and `mount --make-private --make-shared /foo`. This -will convert /foo into a `shared` mount point. Alternatively one can directly -change propagation properties of source mount. Say `/` is source mount for -`/foo`, then use `mount --make-shared /` to convert `/` into a `shared` mount. - -Note: if the user only has access rights via a group, accessing the volume -from inside a rootless container will fail. Use the `--group-add keep-groups` -flag to pass the user's supplementary group access into the container. +Use the **--group-add keep-groups** option to pass the user's supplementary group access into the container. #### **--volumes-from**=*CONTAINER[:OPTIONS]]* diff --git a/docs/source/markdown/podman-diff.1.md b/docs/source/markdown/podman-diff.1.md index 66675de93..0a086c20e 100644 --- a/docs/source/markdown/podman-diff.1.md +++ b/docs/source/markdown/podman-diff.1.md @@ -1,4 +1,4 @@ -% podman-diff(1) +% podman-diff 1 ## NAME podman\-diff - Inspect changes on a container or image's filesystem diff --git a/docs/source/markdown/podman-events.1.md b/docs/source/markdown/podman-events.1.md index 526a7fa10..d0c95fe06 100644 --- a/docs/source/markdown/podman-events.1.md +++ b/docs/source/markdown/podman-events.1.md @@ -1,4 +1,4 @@ -% podman-events(1) +% podman-events 1 ## NAME podman\-events - Monitor Podman events diff --git a/docs/source/markdown/podman-exec.1.md.in b/docs/source/markdown/podman-exec.1.md.in index 4f78f1c31..0d161ef66 100644 --- a/docs/source/markdown/podman-exec.1.md.in +++ b/docs/source/markdown/podman-exec.1.md.in @@ -1,4 +1,4 @@ -% podman-exec(1) +% podman-exec 1 ## NAME podman\-exec - Execute a command in a running container @@ -44,21 +44,7 @@ to run containers such as CRI-O, the last started container could be from either Pass down to the process N additional file descriptors (in addition to 0, 1, 2). The total FDs will be 3+N. -#### **--privileged** - -Give extended privileges to this container. The default is *false*. - -By default, Podman containers are -"unprivileged" and cannot, for example, modify parts of the operating system. -This is because by default a container is only allowed limited access to devices. -A "privileged" container is given the same access to devices as the user launching the container. - -A privileged container turns off the security features that isolate the -container from the host. Dropped Capabilities, limited devices, read/only mount -points, Apparmor/SELinux separation, and Seccomp filters are all disabled. - -Rootless containers cannot have more privileges than the account that launched them. - +@@option privileged #### **--tty**, **-t** diff --git a/docs/source/markdown/podman-export.1.md b/docs/source/markdown/podman-export.1.md index 53d7e425e..d024d0256 100644 --- a/docs/source/markdown/podman-export.1.md +++ b/docs/source/markdown/podman-export.1.md @@ -1,4 +1,4 @@ -% podman-export(1) +% podman-export 1 ## NAME podman\-export - Export a container's filesystem contents as a tar archive diff --git a/docs/source/markdown/podman-generate-spec.1.md b/docs/source/markdown/podman-generate-spec.1.md index 08c939698..73924df6c 100644 --- a/docs/source/markdown/podman-generate-spec.1.md +++ b/docs/source/markdown/podman-generate-spec.1.md @@ -1,4 +1,4 @@ -% podman-generate-spec(1) +% podman-generate-spec 1 ## NAME podman\-generate\-spec - Generate Specgen JSON based on containers or pods diff --git a/docs/source/markdown/podman-generate-systemd.1.md b/docs/source/markdown/podman-generate-systemd.1.md index fc2ce171e..ee649c95b 100644 --- a/docs/source/markdown/podman-generate-systemd.1.md +++ b/docs/source/markdown/podman-generate-systemd.1.md @@ -1,4 +1,4 @@ -% podman-generate-systemd(1) +% podman-generate-systemd 1 ## NAME podman\-generate\-systemd - Generate systemd unit file(s) for a container or pod @@ -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 @@ -44,6 +44,12 @@ User-defined dependencies will be appended to the generated unit file, but any e Set the systemd unit name prefix for containers. The default is *container*. +#### **--env**, **-e**=*env* + +Set environment variables to the systemd unit files. + +If an environment variable is specified without a value, Podman will check the host environment for a value and set the variable only if it is set on the host. As a special case, if an environment variable ending in __*__ is specified without a value, Podman will search the host environment for variables starting with the prefix and will add those variables to the systemd unit files. + #### **--files**, **-f** Generate files instead of printing to stdout. The generated files are named {container,pod}-{ID,name}.service and will be placed in the current working directory. diff --git a/docs/source/markdown/podman-generate.1.md b/docs/source/markdown/podman-generate.1.md index d84a9e098..dab9a866b 100644 --- a/docs/source/markdown/podman-generate.1.md +++ b/docs/source/markdown/podman-generate.1.md @@ -1,4 +1,4 @@ -% podman-generate(1) +% podman-generate 1 ## NAME podman\-generate - Generate structured data based on containers, pods or volumes diff --git a/docs/source/markdown/podman-healthcheck-run.1.md b/docs/source/markdown/podman-healthcheck-run.1.md index dbaf87a0b..b2ef3110b 100644 --- a/docs/source/markdown/podman-healthcheck-run.1.md +++ b/docs/source/markdown/podman-healthcheck-run.1.md @@ -1,4 +1,4 @@ -% podman-healthcheck-run(1) +% podman-healthcheck-run 1 ## NAME podman\-healthcheck\-run - Run a container healthcheck diff --git a/docs/source/markdown/podman-healthcheck.1.md b/docs/source/markdown/podman-healthcheck.1.md index eae71eba9..4caf65501 100644 --- a/docs/source/markdown/podman-healthcheck.1.md +++ b/docs/source/markdown/podman-healthcheck.1.md @@ -1,4 +1,4 @@ -% podman-healthcheck(1) +% podman-healthcheck 1 ## NAME podman\-healthcheck - Manage healthchecks for containers diff --git a/docs/source/markdown/podman-history.1.md b/docs/source/markdown/podman-history.1.md index d114e0523..fb186127a 100644 --- a/docs/source/markdown/podman-history.1.md +++ b/docs/source/markdown/podman-history.1.md @@ -1,4 +1,4 @@ -% podman-history(1) +% podman-history 1 ## NAME podman\-history - Show the history of an image diff --git a/docs/source/markdown/podman-image-diff.1.md b/docs/source/markdown/podman-image-diff.1.md index c5c62c751..0e6747ee0 100644 --- a/docs/source/markdown/podman-image-diff.1.md +++ b/docs/source/markdown/podman-image-diff.1.md @@ -1,4 +1,4 @@ -% podman-image-diff(1) +% podman-image-diff 1 ## NAME podman-image-diff - Inspect changes on an image's filesystem diff --git a/docs/source/markdown/podman-image-exists.1.md b/docs/source/markdown/podman-image-exists.1.md index b585d16f1..7c08205bf 100644 --- a/docs/source/markdown/podman-image-exists.1.md +++ b/docs/source/markdown/podman-image-exists.1.md @@ -1,4 +1,4 @@ -% podman-image-exists(1) +% podman-image-exists 1 ## NAME podman-image-exists - Check if an image exists in local storage diff --git a/docs/source/markdown/podman-image-inspect.1.md b/docs/source/markdown/podman-image-inspect.1.md index eb8d75786..7297b136f 100644 --- a/docs/source/markdown/podman-image-inspect.1.md +++ b/docs/source/markdown/podman-image-inspect.1.md @@ -1,4 +1,4 @@ -% podman-image-inspect(1) +% podman-image-inspect 1 ## NAME podman\-image\-inspect - Display an image's configuration diff --git a/docs/source/markdown/podman-image-mount.1.md b/docs/source/markdown/podman-image-mount.1.md index 453266f8c..3808a4c9a 100644 --- a/docs/source/markdown/podman-image-mount.1.md +++ b/docs/source/markdown/podman-image-mount.1.md @@ -1,4 +1,4 @@ -% podman-image-mount(1) +% podman-image-mount 1 ## NAME podman\-image\-mount - Mount an image's root filesystem diff --git a/docs/source/markdown/podman-image-prune.1.md b/docs/source/markdown/podman-image-prune.1.md index db17f97fb..2a9d215a3 100644 --- a/docs/source/markdown/podman-image-prune.1.md +++ b/docs/source/markdown/podman-image-prune.1.md @@ -1,4 +1,4 @@ -% podman-image-prune(1) +% podman-image-prune 1 ## NAME podman-image-prune - Remove all unused images from the local store diff --git a/docs/source/markdown/podman-image-scp.1.md b/docs/source/markdown/podman-image-scp.1.md index b6b610a7d..b6a55bef2 100644 --- a/docs/source/markdown/podman-image-scp.1.md +++ b/docs/source/markdown/podman-image-scp.1.md @@ -1,4 +1,4 @@ -% podman-image-scp(1) +% podman-image-scp 1 ## NAME podman-image-scp - Securely copy an image from one host to another diff --git a/docs/source/markdown/podman-image-sign.1.md.in b/docs/source/markdown/podman-image-sign.1.md.in index d5efabc1a..580f7e6dc 100644 --- a/docs/source/markdown/podman-image-sign.1.md.in +++ b/docs/source/markdown/podman-image-sign.1.md.in @@ -1,4 +1,4 @@ -% podman-image-sign(1) +% podman-image-sign 1 ## NAME podman-image-sign - Create a signature for an image diff --git a/docs/source/markdown/podman-image-tree.1.md b/docs/source/markdown/podman-image-tree.1.md index 78f1b1004..28eaf0609 100644 --- a/docs/source/markdown/podman-image-tree.1.md +++ b/docs/source/markdown/podman-image-tree.1.md @@ -1,4 +1,4 @@ -% podman-image-tree(1) +% podman-image-tree 1 ## NAME podman\-image\-tree - Prints layer hierarchy of an image in a tree format diff --git a/docs/source/markdown/podman-image-trust.1.md b/docs/source/markdown/podman-image-trust.1.md index 4e80bdcf5..9dce3d890 100644 --- a/docs/source/markdown/podman-image-trust.1.md +++ b/docs/source/markdown/podman-image-trust.1.md @@ -1,4 +1,4 @@ -% podman-image-trust(1) +% podman-image-trust 1 ## NAME podman\-image\-trust - Manage container registry image trust policy @@ -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-image-unmount.1.md b/docs/source/markdown/podman-image-unmount.1.md index 394811bd4..bffb5ff1d 100644 --- a/docs/source/markdown/podman-image-unmount.1.md +++ b/docs/source/markdown/podman-image-unmount.1.md @@ -1,4 +1,4 @@ -% podman-image-unmount(1) +% podman-image-unmount 1 ## NAME podman\-image\-unmount - Unmount an image's root filesystem diff --git a/docs/source/markdown/podman-image.1.md b/docs/source/markdown/podman-image.1.md index 356369007..a74890cf2 100644 --- a/docs/source/markdown/podman-image.1.md +++ b/docs/source/markdown/podman-image.1.md @@ -1,4 +1,4 @@ -% podman-image(1) +% podman-image 1 ## NAME podman\-image - Manage images diff --git a/docs/source/markdown/podman-images.1.md b/docs/source/markdown/podman-images.1.md index d005db23d..63e447960 100644 --- a/docs/source/markdown/podman-images.1.md +++ b/docs/source/markdown/podman-images.1.md @@ -1,4 +1,4 @@ -% podman-images(1) +% podman-images 1 ## NAME podman\-images - List images in local storage diff --git a/docs/source/markdown/podman-import.1.md b/docs/source/markdown/podman-import.1.md index 8d482b961..60b34013c 100644 --- a/docs/source/markdown/podman-import.1.md +++ b/docs/source/markdown/podman-import.1.md @@ -1,4 +1,4 @@ -% podman-import(1) +% podman-import 1 ## NAME podman\-import - Import a tarball and save it as a filesystem image diff --git a/docs/source/markdown/podman-info.1.md b/docs/source/markdown/podman-info.1.md index fc7e1f0e2..b0e4d68c0 100644 --- a/docs/source/markdown/podman-info.1.md +++ b/docs/source/markdown/podman-info.1.md @@ -1,4 +1,4 @@ -% podman-info(1) +% podman-info 1 ## NAME podman\-info - Displays Podman related system information diff --git a/docs/source/markdown/podman-init.1.md b/docs/source/markdown/podman-init.1.md index 9525f610c..019e3d4a7 100644 --- a/docs/source/markdown/podman-init.1.md +++ b/docs/source/markdown/podman-init.1.md @@ -1,4 +1,4 @@ -% podman-init(1) +% podman-init 1 ## NAME podman\-init - Initialize one or more containers diff --git a/docs/source/markdown/podman-inspect.1.md b/docs/source/markdown/podman-inspect.1.md index a67604ab5..ddd7ec972 100644 --- a/docs/source/markdown/podman-inspect.1.md +++ b/docs/source/markdown/podman-inspect.1.md @@ -1,4 +1,4 @@ -% podman-inspect(1) +% podman-inspect 1 ## NAME podman\-inspect - Display a container, image, volume, network, or pod's configuration diff --git a/docs/source/markdown/podman-kill.1.md.in b/docs/source/markdown/podman-kill.1.md.in index 2788cc694..852784caf 100644 --- a/docs/source/markdown/podman-kill.1.md.in +++ b/docs/source/markdown/podman-kill.1.md.in @@ -1,4 +1,4 @@ -% podman-kill(1) +% podman-kill 1 ## NAME podman\-kill - Kill the main process in one or more containers @@ -23,10 +23,7 @@ Signal all running and paused containers. 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) -#### **--signal**, **-s** - -Signal to send to the container. For more information on Linux signals, refer to *man signal(7)*. - +@@option signal ## EXAMPLE diff --git a/docs/source/markdown/podman-kube-down.1.md b/docs/source/markdown/podman-kube-down.1.md index c345abbd1..898188d2b 100644 --- a/docs/source/markdown/podman-kube-down.1.md +++ b/docs/source/markdown/podman-kube-down.1.md @@ -1,4 +1,4 @@ -% podman-kube-down(1) +% podman-kube-down 1 ## NAME podman-kube-down - Remove containers and pods based on Kubernetes YAML diff --git a/docs/source/markdown/podman-kube-play.1.md.in b/docs/source/markdown/podman-kube-play.1.md.in index f0b404057..6bf3acc9b 100644 --- a/docs/source/markdown/podman-kube-play.1.md.in +++ b/docs/source/markdown/podman-kube-play.1.md.in @@ -1,4 +1,4 @@ -% podman-kube-play(1) +% podman-kube-play 1 ## NAME podman-kube-play - Create containers, pods and volumes based on Kubernetes YAML @@ -21,7 +21,7 @@ Currently, the supported Kubernetes kinds are: `Kubernetes Pods or Deployments` -Only two volume types are supported by kube play, the *hostPath* and *persistentVolumeClaim* volume types. For the *hostPath* volume type, only the *default (empty)*, *DirectoryOrCreate*, *Directory*, *FileOrCreate*, *File*, *Socket*, *CharDevice* and *BlockDevice* subtypes are supported. Podman interprets the value of *hostPath* *path* as a file path when it contains at least one forward slash, otherwise Podman treats the value as the name of a named volume. When using a *persistentVolumeClaim*, the value for *claimName* is the name for the Podman named volume. +Only three volume types are supported by kube play, the *hostPath*, *emptyDir*, and *persistentVolumeClaim* volume types. For the *hostPath* volume type, only the *default (empty)*, *DirectoryOrCreate*, *Directory*, *FileOrCreate*, *File*, *Socket*, *CharDevice* and *BlockDevice* subtypes are supported. Podman interprets the value of *hostPath* *path* as a file path when it contains at least one forward slash, otherwise Podman treats the value as the name of a named volume. When using a *persistentVolumeClaim*, the value for *claimName* is the name for the Podman named volume. When using an *emptyDir* volume, podman creates an anonymous volume that is attached the containers running inside the pod and is deleted once the pod is removed. Note: When playing a kube YAML with init containers, the init container will be created with init type value `once`. To change the default type, use the `io.podman.annotations.init.container.type` annotation to set the type to `always`. @@ -225,45 +225,7 @@ Require HTTPS and verify certificates when contacting registries (default: true) then TLS verification will be used. If set to false, then TLS verification will not be used. If not specified, TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf. -#### **--userns**=*mode* - -Set the user namespace mode for the container. It defaults to the **PODMAN_USERNS** environment variable. An empty value ("") means user namespaces are disabled unless an explicit mapping is set with the **--uidmap** and **--gidmap** options. - -Rootless user --userns=Key mappings: - -Key | Host User | Container User -----------|---------------|--------------------- -"" |$UID |0 (Default User account mapped to root user in container.) -keep-id |$UID |$UID (Map user account to same UID within container.) -auto |$UID | nil (Host User UID is not mapped into container.) -nomap |$UID | nil (Host User UID is not mapped into container.) - -Valid _mode_ values are: - -**auto**[:_OPTIONS,..._]: automatically create a unique user namespace. - -The `--userns=auto` flag, requires that the user name `containers` and a range of subordinate user ids that the Podman container is allowed to use be specified in the /etc/subuid and /etc/subgid files. - -Example: `containers:2147483647:2147483648`. - -Podman allocates unique ranges of UIDs and GIDs from the `containers` subordinate user ids. The size of the ranges is based on the number of UIDs required in the image. The number of UIDs and GIDs can be overridden with the `size` option. The `auto` options currently does not work in rootless mode - - Valid `auto` options: - - - *gidmapping*=_CONTAINER_GID:HOST_GID:SIZE_: to force a GID mapping to be present in the user namespace. - - *size*=_SIZE_: to specify an explicit size for the automatic user namespace. e.g. `--userns=auto:size=8192`. If `size` is not specified, `auto` will estimate a size for the user namespace. - - *uidmapping*=_CONTAINER_UID:HOST_UID:SIZE_: to force a UID mapping to be present in the user namespace. - -**container:**_id_: join the user namespace of the specified container. - -**host**: create a new namespace for the container. - -**keep-id**: creates a user namespace where the current rootless user's UID:GID are mapped to the same values in the container. This option is not allowed for containers created by the root user. - -**nomap**: creates a user namespace where the current rootless user's UID:GID are not mapped into the container. This option is not allowed for containers created by the root user. - -**ns:**_namespace_: run the pod in the given existing user namespace. - +@@option userns.container ## EXAMPLES Recreate the pod and containers as described in a file called `demo.yml` diff --git a/docs/source/markdown/podman-kube.1.md b/docs/source/markdown/podman-kube.1.md index 0d3654011..f70a61f47 100644 --- a/docs/source/markdown/podman-kube.1.md +++ b/docs/source/markdown/podman-kube.1.md @@ -1,4 +1,4 @@ -% podman-kube(1) +% podman-kube 1 ## NAME podman\-kube - Play containers, pods or volumes based on a structured input file diff --git a/docs/source/markdown/podman-load.1.md b/docs/source/markdown/podman-load.1.md index ad32df854..8d0efb1a4 100644 --- a/docs/source/markdown/podman-load.1.md +++ b/docs/source/markdown/podman-load.1.md @@ -1,4 +1,4 @@ -% podman-load(1) +% podman-load 1 ## NAME podman\-load - Load image(s) from a tar archive into container storage diff --git a/docs/source/markdown/podman-login.1.md.in b/docs/source/markdown/podman-login.1.md.in index 4537988eb..c309395fb 100644 --- a/docs/source/markdown/podman-login.1.md.in +++ b/docs/source/markdown/podman-login.1.md.in @@ -1,4 +1,4 @@ -% podman-login(1) +% podman-login 1 ## NAME podman\-login - Login to a container registry diff --git a/docs/source/markdown/podman-logout.1.md.in b/docs/source/markdown/podman-logout.1.md.in index 6997bb36e..0f4180416 100644 --- a/docs/source/markdown/podman-logout.1.md.in +++ b/docs/source/markdown/podman-logout.1.md.in @@ -1,4 +1,4 @@ -% podman-logout(1) +% podman-logout 1 ## NAME podman\-logout - Logout of a container registry diff --git a/docs/source/markdown/podman-logs.1.md.in b/docs/source/markdown/podman-logs.1.md.in index 7b0c45cf0..63144bec3 100644 --- a/docs/source/markdown/podman-logs.1.md.in +++ b/docs/source/markdown/podman-logs.1.md.in @@ -1,4 +1,4 @@ -% podman-logs(1) +% podman-logs 1 ## NAME podman\-logs - Display the logs of one or more containers diff --git a/docs/source/markdown/podman-machine-info.1.md b/docs/source/markdown/podman-machine-info.1.md index 926d3d8b3..cdb8c7295 100644 --- a/docs/source/markdown/podman-machine-info.1.md +++ b/docs/source/markdown/podman-machine-info.1.md @@ -1,4 +1,4 @@ -% podman-machine-info(1) +% podman-machine-info 1 ## NAME podman\-machine\-info - Display machine host info diff --git a/docs/source/markdown/podman-machine-init.1.md b/docs/source/markdown/podman-machine-init.1.md index 07273a111..7a23faf59 100644 --- a/docs/source/markdown/podman-machine-init.1.md +++ b/docs/source/markdown/podman-machine-init.1.md @@ -1,4 +1,4 @@ -% podman-machine-init(1) +% podman-machine-init 1 ## NAME podman\-machine\-init - Initialize a new virtual machine @@ -76,6 +76,12 @@ Set the timezone for the machine and containers. Valid values are `local` or a `timezone` such as `America/Chicago`. A value of `local`, which is the default, means to use the timezone of the machine host. +#### **--username** + +Username to use for executing commands in remote VM. Default value is `core` +for FCOS and `user` for Fedora (default on Windows hosts). Should match the one +used inside the resulting VM image. + #### **--volume**, **-v**=*source:target[:options]* Mounts a volume from source to target. diff --git a/docs/source/markdown/podman-machine-inspect.1.md b/docs/source/markdown/podman-machine-inspect.1.md index 29cd775c2..79611f65d 100644 --- a/docs/source/markdown/podman-machine-inspect.1.md +++ b/docs/source/markdown/podman-machine-inspect.1.md @@ -1,4 +1,4 @@ -% podman-machine-inspect(1) +% podman-machine-inspect 1 ## NAME podman\-machine\-inspect - Inspect one or more virtual machines diff --git a/docs/source/markdown/podman-machine-list.1.md b/docs/source/markdown/podman-machine-list.1.md index a25aae090..351e8cf1b 100644 --- a/docs/source/markdown/podman-machine-list.1.md +++ b/docs/source/markdown/podman-machine-list.1.md @@ -1,4 +1,4 @@ -% podman-machine-ls(1) +% podman-machine-ls 1 ## NAME podman\-machine\-list - List virtual machines diff --git a/docs/source/markdown/podman-machine-rm.1.md b/docs/source/markdown/podman-machine-rm.1.md index d90b615ce..43c9d5813 100644 --- a/docs/source/markdown/podman-machine-rm.1.md +++ b/docs/source/markdown/podman-machine-rm.1.md @@ -1,4 +1,4 @@ -% podman-machine-rm(1) +% podman-machine-rm 1 ## NAME podman\-machine\-rm - Remove a virtual machine diff --git a/docs/source/markdown/podman-machine-set.1.md b/docs/source/markdown/podman-machine-set.1.md index 52338cedb..a5ca5033e 100644 --- a/docs/source/markdown/podman-machine-set.1.md +++ b/docs/source/markdown/podman-machine-set.1.md @@ -1,4 +1,4 @@ -% podman-machine-set(1) +% podman-machine-set 1 ## NAME podman\-machine\-set - Sets a virtual machine setting diff --git a/docs/source/markdown/podman-machine-ssh.1.md b/docs/source/markdown/podman-machine-ssh.1.md index 5432f0e9f..2d827df3d 100644 --- a/docs/source/markdown/podman-machine-ssh.1.md +++ b/docs/source/markdown/podman-machine-ssh.1.md @@ -1,4 +1,4 @@ -% podman-machine-ssh(1) +% podman-machine-ssh 1 ## NAME podman\-machine\-ssh - SSH into a virtual machine diff --git a/docs/source/markdown/podman-machine-start.1.md b/docs/source/markdown/podman-machine-start.1.md index b92494dda..aa356a374 100644 --- a/docs/source/markdown/podman-machine-start.1.md +++ b/docs/source/markdown/podman-machine-start.1.md @@ -1,4 +1,4 @@ -% podman-machine-start(1) +% podman-machine-start 1 ## NAME podman\-machine\-start - Start a virtual machine diff --git a/docs/source/markdown/podman-machine-stop.1.md b/docs/source/markdown/podman-machine-stop.1.md index 29f3e81f4..6ec4ba989 100644 --- a/docs/source/markdown/podman-machine-stop.1.md +++ b/docs/source/markdown/podman-machine-stop.1.md @@ -1,4 +1,4 @@ -% podman-machine-stop(1) +% podman-machine-stop 1 ## NAME podman\-machine\-stop - Stop a virtual machine diff --git a/docs/source/markdown/podman-machine.1.md b/docs/source/markdown/podman-machine.1.md index 6197b8d4e..a3d04c776 100644 --- a/docs/source/markdown/podman-machine.1.md +++ b/docs/source/markdown/podman-machine.1.md @@ -1,4 +1,4 @@ -% podman-machine(1) +% podman-machine 1 ## NAME podman\-machine - Manage Podman's virtual machine diff --git a/docs/source/markdown/podman-manifest-add.1.md.in b/docs/source/markdown/podman-manifest-add.1.md.in index e82c04985..0d957cd1e 100644 --- a/docs/source/markdown/podman-manifest-add.1.md.in +++ b/docs/source/markdown/podman-manifest-add.1.md.in @@ -1,4 +1,4 @@ -% podman-manifest-add(1) +% podman-manifest-add 1 ## NAME podman\-manifest\-add - Add an image to a manifest list or image index diff --git a/docs/source/markdown/podman-manifest-annotate.1.md b/docs/source/markdown/podman-manifest-annotate.1.md index 36c35c7c8..a6f82aa9a 100644 --- a/docs/source/markdown/podman-manifest-annotate.1.md +++ b/docs/source/markdown/podman-manifest-annotate.1.md @@ -1,4 +1,4 @@ -% podman-manifest-annotate(1) +% podman-manifest-annotate 1 ## NAME podman\-manifest\-annotate - Add or update information about an entry in a manifest list or image index diff --git a/docs/source/markdown/podman-manifest-create.1.md b/docs/source/markdown/podman-manifest-create.1.md index 06a24da2b..cb8ad41fb 100644 --- a/docs/source/markdown/podman-manifest-create.1.md +++ b/docs/source/markdown/podman-manifest-create.1.md @@ -1,4 +1,4 @@ -% podman-manifest-create(1) +% podman-manifest-create 1 ## NAME podman\-manifest\-create - Create a manifest list or image index diff --git a/docs/source/markdown/podman-manifest-exists.1.md b/docs/source/markdown/podman-manifest-exists.1.md index dd344046d..b87559f8b 100644 --- a/docs/source/markdown/podman-manifest-exists.1.md +++ b/docs/source/markdown/podman-manifest-exists.1.md @@ -1,4 +1,4 @@ -% podman-manifest-exists(1) +% podman-manifest-exists 1 ## NAME podman\-manifest\-exists - Check if the given manifest list exists in local storage diff --git a/docs/source/markdown/podman-manifest-inspect.1.md b/docs/source/markdown/podman-manifest-inspect.1.md index b2c6b1935..4b7fc3a40 100644 --- a/docs/source/markdown/podman-manifest-inspect.1.md +++ b/docs/source/markdown/podman-manifest-inspect.1.md @@ -1,4 +1,4 @@ -% podman-manifest-inspect(1) +% podman-manifest-inspect 1 ## NAME podman\-manifest\-inspect - Display a manifest list or image index diff --git a/docs/source/markdown/podman-manifest-push.1.md.in b/docs/source/markdown/podman-manifest-push.1.md.in index 88d070c3f..e3d578d10 100644 --- a/docs/source/markdown/podman-manifest-push.1.md.in +++ b/docs/source/markdown/podman-manifest-push.1.md.in @@ -1,4 +1,4 @@ -% podman-manifest-push(1) +% podman-manifest-push 1 ## NAME podman\-manifest\-push - Push a manifest list or image index to a registry @@ -29,9 +29,7 @@ Specifies the compression format to use. Supported values are: `gzip`, `zstd` a @@option creds -#### **--digestfile**=*Digestfile* - -After copying the image, write the digest of the resulting image to the file. +@@option digestfile #### **--format**, **-f**=*format* diff --git a/docs/source/markdown/podman-manifest-remove.1.md b/docs/source/markdown/podman-manifest-remove.1.md index 256d5a5b5..32fc5892e 100644 --- a/docs/source/markdown/podman-manifest-remove.1.md +++ b/docs/source/markdown/podman-manifest-remove.1.md @@ -1,4 +1,4 @@ -% podman-manifest-remove(1) +% podman-manifest-remove 1 ## NAME podman\-manifest\-remove - Remove an image from a manifest list or image index diff --git a/docs/source/markdown/podman-manifest.1.md b/docs/source/markdown/podman-manifest.1.md index cc716b2a0..74c59b657 100644 --- a/docs/source/markdown/podman-manifest.1.md +++ b/docs/source/markdown/podman-manifest.1.md @@ -1,4 +1,4 @@ -% podman-manifest(1) +% podman-manifest 1 ## NAME podman\-manifest - Create and manipulate manifest lists and image indexes diff --git a/docs/source/markdown/podman-mount.1.md b/docs/source/markdown/podman-mount.1.md index 82c7fe804..8229b1390 100644 --- a/docs/source/markdown/podman-mount.1.md +++ b/docs/source/markdown/podman-mount.1.md @@ -1,4 +1,4 @@ -% podman-mount(1) +% podman-mount 1 ## NAME podman\-mount - Mount a working container's root filesystem diff --git a/docs/source/markdown/podman-network-connect.1.md b/docs/source/markdown/podman-network-connect.1.md index d1718b812..dc238fced 100644 --- a/docs/source/markdown/podman-network-connect.1.md +++ b/docs/source/markdown/podman-network-connect.1.md @@ -1,4 +1,4 @@ -% podman-network-connect(1) +% podman-network-connect 1 ## NAME podman\-network\-connect - Connect a container to a network diff --git a/docs/source/markdown/podman-network-create.1.md b/docs/source/markdown/podman-network-create.1.md index 3836ea05c..6fd31dd4d 100644 --- a/docs/source/markdown/podman-network-create.1.md +++ b/docs/source/markdown/podman-network-create.1.md @@ -1,4 +1,4 @@ -% podman-network-create(1) +% podman-network-create 1 ## NAME podman\-network-create - Create a Podman network diff --git a/docs/source/markdown/podman-network-disconnect.1.md b/docs/source/markdown/podman-network-disconnect.1.md index f3ca059a1..9685cf400 100644 --- a/docs/source/markdown/podman-network-disconnect.1.md +++ b/docs/source/markdown/podman-network-disconnect.1.md @@ -1,4 +1,4 @@ -% podman-network-disconnect(1) +% podman-network-disconnect 1 ## NAME podman\-network\-disconnect - Disconnect a container from a network diff --git a/docs/source/markdown/podman-network-exists.1.md b/docs/source/markdown/podman-network-exists.1.md index 44c145cd9..f014b14ef 100644 --- a/docs/source/markdown/podman-network-exists.1.md +++ b/docs/source/markdown/podman-network-exists.1.md @@ -1,4 +1,4 @@ -% podman-network-exists(1) +% podman-network-exists 1 ## NAME podman\-network\-exists - Check if the given network exists diff --git a/docs/source/markdown/podman-network-inspect.1.md b/docs/source/markdown/podman-network-inspect.1.md index 2ba4a63cb..f812542db 100644 --- a/docs/source/markdown/podman-network-inspect.1.md +++ b/docs/source/markdown/podman-network-inspect.1.md @@ -1,4 +1,4 @@ -% podman-network-inspect(1) +% podman-network-inspect 1 ## NAME podman\-network\-inspect - Displays the network configuration for one or more networks diff --git a/docs/source/markdown/podman-network-ls.1.md b/docs/source/markdown/podman-network-ls.1.md index c7ea24b9b..83d1365ec 100644 --- a/docs/source/markdown/podman-network-ls.1.md +++ b/docs/source/markdown/podman-network-ls.1.md @@ -1,4 +1,4 @@ -% podman-network-ls(1) +% podman-network-ls 1 ## NAME podman\-network\-ls - Display a summary of networks diff --git a/docs/source/markdown/podman-network-prune.1.md b/docs/source/markdown/podman-network-prune.1.md index b0a81646d..806f5c8a1 100644 --- a/docs/source/markdown/podman-network-prune.1.md +++ b/docs/source/markdown/podman-network-prune.1.md @@ -1,4 +1,4 @@ -% podman-network-prune(1) +% podman-network-prune 1 ## NAME podman\-network\-prune - Remove all unused networks diff --git a/docs/source/markdown/podman-network-reload.1.md b/docs/source/markdown/podman-network-reload.1.md index 31d10829e..4ecce17f8 100644 --- a/docs/source/markdown/podman-network-reload.1.md +++ b/docs/source/markdown/podman-network-reload.1.md @@ -1,4 +1,4 @@ -% podman-network-reload(1) +% podman-network-reload 1 ## NAME podman\-network\-reload - Reload network configuration for containers diff --git a/docs/source/markdown/podman-network-rm.1.md b/docs/source/markdown/podman-network-rm.1.md index 880f1d0c7..714fea8fb 100644 --- a/docs/source/markdown/podman-network-rm.1.md +++ b/docs/source/markdown/podman-network-rm.1.md @@ -1,4 +1,4 @@ -% podman-network-rm(1) +% podman-network-rm 1 ## NAME podman\-network\-rm - Remove one or more networks diff --git a/docs/source/markdown/podman-network.1.md b/docs/source/markdown/podman-network.1.md index f58bd5d5c..6ab7013e1 100644 --- a/docs/source/markdown/podman-network.1.md +++ b/docs/source/markdown/podman-network.1.md @@ -1,4 +1,4 @@ -% podman-network(1) +% podman-network 1 ## NAME podman\-network - Manage Podman networks diff --git a/docs/source/markdown/podman-pause.1.md.in b/docs/source/markdown/podman-pause.1.md.in index af308f034..a228f7107 100644 --- a/docs/source/markdown/podman-pause.1.md.in +++ b/docs/source/markdown/podman-pause.1.md.in @@ -1,4 +1,4 @@ -% podman-pause(1) +% podman-pause 1 ## NAME podman\-pause - Pause one or more containers diff --git a/docs/source/markdown/podman-pod-clone.1.md.in b/docs/source/markdown/podman-pod-clone.1.md.in index c040f1c27..1d7b1f259 100644 --- a/docs/source/markdown/podman-pod-clone.1.md.in +++ b/docs/source/markdown/podman-pod-clone.1.md.in @@ -1,4 +1,4 @@ -% podman-pod-clone(1) +% podman-pod-clone 1 ## NAME podman\-pod\-clone - Creates a copy of an existing pod @@ -31,30 +31,13 @@ If none are specified, the original pod's CPUset is used. @@option destroy -#### **--device**=*host-device[:container-device][:permissions]* - -Add a host device to the pod. Optional *permissions* parameter -can be used to specify device permissions. It is a combination of -**r** for read, **w** for write, and **m** for **mknod**(2). - -Example: **--device=/dev/sdc:/dev/xvdc:rwm**. - -Note: if _host_device_ is a symbolic link then it will be resolved first. -The pod will only store the major and minor numbers of the host device. +@@option device Note: the pod implements devices by storing the initial configuration passed by the user and recreating the device on each container added to the pod. -Podman may load kernel modules required for using the specified -device. The devices that Podman will load modules for when necessary are: -/dev/fuse. - -#### **--device-read-bps**=*path* +@@option device-read-bps -Limit read rate (bytes per second) from a device (e.g. --device-read-bps=/dev/sda:1mb). - -#### **--device-write-bps**=*path* - -Limit write rate (bytes per second) to a device (e.g. --device-write-bps=/dev/sda:1mb) +@@option device-write-bps @@option gidmap.pod @@ -70,32 +53,13 @@ Print usage statement. @@option infra-name -#### **--label**, **-l**=*label* - -Add metadata to a pod (e.g., --label com.example.key=value). +@@option label @@option label-file -#### **--memory**, **-m**=*limit* +@@option memory -Memory limit (format: `<number>[<unit>]`, where unit = b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes)) - -Constrains the memory available to a container. If the host -supports swap memory, then the **-m** memory setting can be larger than physical -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). - -#### **--memory-swap**=*limit* - -A limit value equal to memory plus swap. Must be used with the **-m** -(**--memory**) flag. The swap `LIMIT` should always be larger than **-m** -(**--memory**) value. By default, the swap `LIMIT` will be set to double -the value of --memory. - -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. +@@option memory-swap #### **--name**, **-n** @@ -146,229 +110,19 @@ When size is `0`, there is no limit on the amount of memory used for IPC by the When set to true, this flag starts the newly created pod after the clone process has completed. All containers within the pod are started. -#### **--subgidname**=*name* - -Name for GID map from the `/etc/subgid` file. Using this flag will run the container with user namespace enabled. This flag conflicts with `--userns` and `--gidmap`. - -#### **--subuidname**=*name* +@@option subgidname -Name for UID map from the `/etc/subuid` file. Using this flag will run the container with user namespace enabled. This flag conflicts with `--userns` and `--uidmap`. +@@option subuidname -#### **--sysctl**=*name=value* - -Configure namespace kernel parameters for all containers in the new pod. - -For the IPC namespace, the following sysctls are allowed: - -- kernel.msgmax -- kernel.msgmnb -- kernel.msgmni -- kernel.sem -- kernel.shmall -- kernel.shmmax -- kernel.shmmni -- kernel.shm_rmid_forced -- Sysctls beginning with fs.mqueue.\* - -Note: if the ipc namespace is not shared within the pod, these sysctls are not allowed. - -For the network namespace, only sysctls beginning with net.\* are allowed. - -Note: if the network namespace is not shared within the pod, these sysctls are not allowed. +@@option sysctl @@option uidmap.pod -#### **--userns**=*mode* - -Set the user namespace mode for all the containers in a pod. It defaults to the **PODMAN_USERNS** environment variable. An empty value ("") means user namespaces are disabled. - -Rootless user --userns=Key mappings: - -Key | Host User | Container User -----------|---------------|--------------------- -"" |$UID |0 (Default User account mapped to root user in container.) -keep-id |$UID |$UID (Map user account to same UID within container.) -auto |$UID | nil (Host User UID is not mapped into container.) -nomap |$UID | nil (Host User UID is not mapped into container.) - -Valid _mode_ values are: - - - *auto[:*_OPTIONS,..._*]*: automatically create a namespace. It is possible to specify these options to `auto`: - - - *gidmapping=*_CONTAINER_GID:HOST_GID:SIZE_ to force a GID mapping to be present in the user namespace. - - - *size=*_SIZE_: to specify an explicit size for the automatic user namespace. e.g. `--userns=auto:size=8192`. If `size` is not specified, `auto` will estimate a size for the user namespace. - - - *uidmapping=*_CONTAINER_UID:HOST_UID:SIZE_ to force a UID mapping to be present in the user namespace. - - - *host*: run in the user namespace of the caller. The processes running in the container will have the same privileges on the host as any other process launched by the calling user (default). - - - *keep-id*: creates a user namespace where the current rootless user's UID:GID are mapped to the same values in the container. This option is ignored for containers created by the root user. - - - *nomap*: creates a user namespace where the current rootless user's UID:GID are not mapped into the container. This option is ignored for containers created by the root user. +@@option userns.pod @@option uts.pod -#### **--volume**, **-v**=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]* - -Create a bind mount. If ` -v /HOST-DIR:/CONTAINER-DIR` is specified, Podman -bind mounts `/HOST-DIR` in the host to `/CONTAINER-DIR` in the Podman -container. Similarly, `-v SOURCE-VOLUME:/CONTAINER-DIR` will mount the volume -in the host to the container. If no such named volume exists, Podman will -create one. The `OPTIONS` are a comma-separated list and can be: <sup>[[1]](#Footnote1)</sup> (Note when using the remote client, including Mac and Windows (excluding WSL2) machines, the volumes will be mounted from the remote server, not necessarily the client machine.) - -The _options_ is a comma-separated list and can be: - -* **rw**|**ro** -* **z**|**Z** -* [**r**]**shared**|[**r**]**slave**|[**r**]**private**[**r**]**unbindable** -* [**r**]**bind** -* [**no**]**exec** -* [**no**]**dev** -* [**no**]**suid** -* [**O**] -* [**U**] - -The `CONTAINER-DIR` must be an absolute path such as `/src/docs`. The volume -will be mounted into the container at this directory. - -Volumes may specify a source as well, as either a directory on the host -or the name of a named volume. If no source is given, the volume will be created as an -anonymously named volume with a randomly generated name, and will be removed when -the pod is removed via the `--rm` flag or `podman rm --volumes` commands. - -If a volume source is specified, it must be a path on the host or the name of a -named volume. Host paths are allowed to be absolute or relative; relative paths -are resolved relative to the directory Podman is run in. If the source does not -exist, Podman will return an error. Users must pre-create the source files or -directories. - -Any source that does not begin with a `.` or `/` will be treated as the name of -a named volume. If a volume with that name does not exist, it will be created. -Volumes created with names are not anonymous, and they are not removed by the `--rm` -option and the `podman rm --volumes` command. - -Specify multiple **-v** options to mount one or more volumes into a -pod. - - `Write Protected Volume Mounts` - -Add `:ro` or `:rw` suffix to a volume to mount it read-only or -read-write mode, respectively. By default, the volumes are mounted read-write. -See examples. - - `Chowning Volume Mounts` - -By default, Podman does not change the owner and group of source volume -directories mounted into containers. If a pod is created in a new user -namespace, the UID and GID in the container may correspond to another UID and -GID on the host. - -The `:U` suffix tells Podman to use the correct host UID and GID based on the -UID and GID within the pod, to change recursively the owner and group of -the source volume. - -**Warning** use with caution since this will modify the host filesystem. - - `Labeling Volume Mounts` - -Labeling systems like SELinux require that proper labels are placed on volume -content mounted into a pod. Without a label, the security system might -prevent the processes running inside the pod from using the content. By -default, Podman does not change the labels set by the OS. - -To change a label in the pod context, add either of two suffixes -`:z` or `:Z` to the volume mount. These suffixes tell Podman to relabel file -objects on the shared volumes. The `z` option tells Podman that two pods -share the volume content. As a result, Podman labels the content with a shared -content label. Shared volume labels allow all containers to read/write content. -The `Z` option tells Podman to label the content with a private unshared label. -Only the current pod can use a private volume. - - `Overlay Volume Mounts` - - The `:O` flag tells Podman to mount the directory from the host as a -temporary storage using the `overlay file system`. The pod processes -can modify content within the mountpoint which is stored in the -container storage in a separate directory. In overlay terms, the source -directory will be the lower, and the container storage directory will be the -upper. Modifications to the mount point are destroyed when the pod -finishes executing, similar to a tmpfs mount point being unmounted. - - Subsequent executions of the container will see the original source directory -content, any changes from previous pod executions no longer exist. - - One use case of the overlay mount is sharing the package cache from the -host into the container to allow speeding up builds. - - Note: - - - The `O` flag conflicts with other options listed above. -Content mounted into the container is labeled with the private label. - On SELinux systems, labels in the source directory must be readable -by the infra container label. Usually containers can read/execute `container_share_t` -and can read/write `container_file_t`. If unable to change the labels on a -source volume, SELinux container separation must be disabled for the infra container/pod -to work. - - The source directory mounted into the pod with an overlay mount -should not be modified, it can cause unexpected failures. It is recommended -to not modify the directory until the container finishes running. - - `Mounts propagation` - -By default bind mounted volumes are `private`. That means any mounts done -inside pod will not be visible on host and vice versa. One can change -this behavior by specifying a volume mount propagation property. Making a -volume `shared` mounts done under that volume inside pod will be -visible on host and vice versa. Making a volume `slave` enables only one -way mount propagation and that is mounts done on host under that volume -will be visible inside container but not the other way around. <sup>[[1]](#Footnote1)</sup> - -To control mount propagation property of a volume one can use the [**r**]**shared**, -[**r**]**slave**, [**r**]**private** or the [**r**]**unbindable** propagation flag. -Propagation property can be specified only for bind mounted volumes and not for -internal volumes or named volumes. For mount propagation to work the source mount -point (the mount point where source dir is mounted on) has to have the right propagation -properties. For shared volumes, the source mount point has to be shared. And for -slave volumes, the source mount point has to be either shared or slave. -<sup>[[1]](#Footnote1)</sup> - -To recursively mount a volume and all of its submounts into a -pod, use the `rbind` option. By default the bind option is -used, and submounts of the source directory will not be mounted into the -pod. - -Mounting the volume with the `nosuid` options means that SUID applications on -the volume will not be able to change their privilege. By default volumes -are mounted with `nosuid`. - -Mounting the volume with the noexec option means that no executables on the -volume will be able to executed within the pod. - -Mounting the volume with the nodev option means that no devices on the volume -will be able to be used by processes within the pod. By default volumes -are mounted with `nodev`. - -If the `<source-dir>` is a mount point, then "dev", "suid", and "exec" options are -ignored by the kernel. - -Use `df <source-dir>` to figure out the source mount and then use -`findmnt -o TARGET,PROPAGATION <source-mount-dir>` to figure out propagation -properties of source mount. If `findmnt` utility is not available, then one -can look at the mount entry for the source mount point in `/proc/self/mountinfo`. Look -at `optional fields` and see if any propagation properties are specified. -`shared:X` means mount is `shared`, `master:X` means mount is `slave` and if -nothing is there that means mount is `private`. <sup>[[1]](#Footnote1)</sup> - -To change propagation properties of a mount point use `mount` command. For -example, if one wants to bind mount source directory `/foo` one can do -`mount --bind /foo /foo` and `mount --make-private --make-shared /foo`. This -will convert /foo into a `shared` mount point. Alternatively one can directly -change propagation properties of source mount. Say `/` is source mount for -`/foo`, then use `mount --make-shared /` to convert `/` into a `shared` mount. - -Note: if the user only has access rights via a group, accessing the volume -from inside a rootless pod will fail. +@@option volume #### **--volumes-from**=*container[:options]]* @@ -430,3 +184,6 @@ d0cf1f782e2ed67e8c0050ff92df865a039186237a4df24d7acba5b1fa8cc6e7 ## HISTORY May 2022, Originally written by Charlie Doern <cdoern@redhat.com> + +## FOOTNOTES +<a name="Footnote1">1</a>: The Podman project is committed to inclusivity, a core value of open source. The `master` and `slave` mount propagation terminology used here is problematic and divisive, and should be changed. However, these terms are currently used within the Linux kernel and must be used as-is at this time. When the kernel maintainers rectify this usage, Podman will follow suit immediately. diff --git a/docs/source/markdown/podman-pod-create.1.md.in b/docs/source/markdown/podman-pod-create.1.md.in index 702780c65..3a3909340 100644 --- a/docs/source/markdown/podman-pod-create.1.md.in +++ b/docs/source/markdown/podman-pod-create.1.md.in @@ -1,4 +1,4 @@ -% podman-pod-create(1) +% podman-pod-create 1 ## NAME podman\-pod\-create - Create a new pod @@ -48,30 +48,13 @@ Set the total number of CPUs delegated to the pod. Default is 0.000 which indica @@option cpuset-mems -#### **--device**=_host-device_[**:**_container-device_][**:**_permissions_] - -Add a host device to the pod. Optional *permissions* parameter -can be used to specify device permissions. It is a combination of -**r** for read, **w** for write, and **m** for **mknod**(2). - -Example: **--device=/dev/sdc:/dev/xvdc:rwm**. - -Note: if *host-device* is a symbolic link then it will be resolved first. -The pod will only store the major and minor numbers of the host device. +@@option device Note: the pod implements devices by storing the initial configuration passed by the user and recreating the device on each container added to the pod. -Podman may load kernel modules required for using the specified -device. The devices that Podman will load modules for when necessary are: -/dev/fuse. - -#### **--device-read-bps**=*path* +@@option device-read-bps -Limit read rate (bytes per second) from a device (e.g. --device-read-bps=/dev/sda:1mb) - -#### **--device-write-bps**=*path* - -Limit write rate (bytes per second) to a device (e.g. --device-write-bps=/dev/sda:1mb) +@@option device-write-bps #### **--dns**=*ipaddr* @@ -134,34 +117,15 @@ The address must be within the network's IPv6 address pool. To specify multiple static IPv6 addresses per pod, set multiple networks using the **--network** option with a static IPv6 address specified for each using the `ip6` mode for that option. -#### **--label**, **-l**=*label* - -Add metadata to a pod (e.g., --label com.example.key=value). +@@option label @@option label-file @@option mac-address -#### **--memory**, **-m**=*limit* +@@option memory -Memory limit (format: `<number>[<unit>]`, where unit = b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes)) - -Constrains the memory available to a container. If the host -supports swap memory, then the **-m** memory setting can be larger than physical -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). - -#### **--memory-swap**=*limit* - -A limit value equal to memory plus swap. Must be used with the **-m** -(**--memory**) flag. The swap `LIMIT` should always be larger than **-m** -(**--memory**) value. By default, the swap `LIMIT` will be set to double -the value of --memory. - -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. +@@option memory-swap #### **--name**, **-n**=*name* @@ -287,228 +251,19 @@ Size of `/dev/shm` (format: `<number>[<unit>]`, where unit = b (bytes), k (kibib If the unit is omitted, the system uses bytes. If the size is omitted, the system uses `64m`. When size is `0`, there is no limit on the amount of memory used for IPC by the pod. This option conflicts with **--ipc=host** when running containers. -#### **--subgidname**=*name* - -Name for GID map from the `/etc/subgid` file. Using this flag will run the container with user namespace enabled. This flag conflicts with `--userns` and `--gidmap`. - -#### **--subuidname**=*name* - -Name for UID map from the `/etc/subuid` file. Using this flag will run the container with user namespace enabled. This flag conflicts with `--userns` and `--uidmap`. +@@option subgidname +@@option subuidname -#### **--sysctl**=*name=value* - -Configure namespace kernel parameters for all containers in the pod. - -For the IPC namespace, the following sysctls are allowed: - -- kernel.msgmax -- kernel.msgmnb -- kernel.msgmni -- kernel.sem -- kernel.shmall -- kernel.shmmax -- kernel.shmmni -- kernel.shm_rmid_forced -- Sysctls beginning with fs.mqueue.\* - -Note: if the ipc namespace is not shared within the pod, these sysctls are not allowed. - -For the network namespace, only sysctls beginning with net.\* are allowed. - -Note: if the network namespace is not shared within the pod, these sysctls are not allowed. +@@option sysctl @@option uidmap.pod -#### **--userns**=*mode* - -Set the user namespace mode for all the containers in a pod. It defaults to the **PODMAN_USERNS** environment variable. An empty value ("") means user namespaces are disabled. - -Rootless user --userns=Key mappings: - -Key | Host User | Container User -----------|---------------|--------------------- -"" |$UID |0 (Default User account mapped to root user in container.) -keep-id |$UID |$UID (Map user account to same UID within container.) -auto |$UID | nil (Host User UID is not mapped into container.) -nomap |$UID | nil (Host User UID is not mapped into container.) - -Valid _mode_ values are: - - - *auto[:*_OPTIONS,..._*]*: automatically create a namespace. It is possible to specify these options to `auto`: - - - *gidmapping=*_CONTAINER_GID:HOST_GID:SIZE_ to force a GID mapping to be present in the user namespace. - - - *size=*_SIZE_: to specify an explicit size for the automatic user namespace. e.g. `--userns=auto:size=8192`. If `size` is not specified, `auto` will estimate a size for the user namespace. - - - *uidmapping=*_CONTAINER_UID:HOST_UID:SIZE_ to force a UID mapping to be present in the user namespace. - - - *host*: run in the user namespace of the caller. The processes running in the container will have the same privileges on the host as any other process launched by the calling user (default). - - - *keep-id*: creates a user namespace where the current rootless user's UID:GID are mapped to the same values in the container. This option is not allowed for containers created by the root user. - - - *nomap*: creates a user namespace where the current rootless user's UID:GID are not mapped into the container. This option is not allowed for containers created by the root user. +@@option userns.pod @@option uts.pod -#### **--volume**, **-v**=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]* - -Create a bind mount. If you specify, ` -v /HOST-DIR:/CONTAINER-DIR`, Podman -bind mounts `/HOST-DIR` in the host to `/CONTAINER-DIR` in the Podman -container. Similarly, `-v SOURCE-VOLUME:/CONTAINER-DIR` will mount the volume -in the host to the container. If no such named volume exists, Podman will -create one. The `OPTIONS` are a comma-separated list and can be: <sup>[[1]](#Footnote1)</sup> (Note when using the remote client, including Mac and Windows (excluding WSL2) machines, the volumes will be mounted from the remote server, not necessarily the client machine.) - -The _options_ is a comma-separated list and can be: - -* **rw**|**ro** -* **z**|**Z** -* [**r**]**shared**|[**r**]**slave**|[**r**]**private**[**r**]**unbindable** -* [**r**]**bind** -* [**no**]**exec** -* [**no**]**dev** -* [**no**]**suid** -* [**O**] -* [**U**] - -The `CONTAINER-DIR` must be an absolute path such as `/src/docs`. The volume -will be mounted into the container at this directory. - -Volumes may specify a source as well, as either a directory on the host -or the name of a named volume. If no source is given, the volume will be created as an -anonymously named volume with a randomly generated name, and will be removed when -the pod is removed via the `--rm` flag or `podman rm --volumes` commands. - -If a volume source is specified, it must be a path on the host or the name of a -named volume. Host paths are allowed to be absolute or relative; relative paths -are resolved relative to the directory Podman is run in. If the source does not -exist, Podman will return an error. Users must pre-create the source files or -directories. - -Any source that does not begin with a `.` or `/` will be treated as the name of -a named volume. If a volume with that name does not exist, it will be created. -Volumes created with names are not anonymous, and they are not removed by the `--rm` -option and the `podman rm --volumes` command. - -You can specify multiple **-v** options to mount one or more volumes into a -pod. - - `Write Protected Volume Mounts` - -You can add `:ro` or `:rw` suffix to a volume to mount it read-only or -read-write mode, respectively. By default, the volumes are mounted read-write. -See examples. - - `Chowning Volume Mounts` - -By default, Podman does not change the owner and group of source volume -directories mounted into containers. If a pod is created in a new user -namespace, the UID and GID in the container may correspond to another UID and -GID on the host. - -The `:U` suffix tells Podman to use the correct host UID and GID based on the -UID and GID within the pod, to change recursively the owner and group of -the source volume. - -**Warning** use with caution since this will modify the host filesystem. - - `Labeling Volume Mounts` - -Labeling systems like SELinux require that proper labels are placed on volume -content mounted into a pod. Without a label, the security system might -prevent the processes running inside the pod from using the content. By -default, Podman does not change the labels set by the OS. - -To change a label in the pod context, you can add either of two suffixes -`:z` or `:Z` to the volume mount. These suffixes tell Podman to relabel file -objects on the shared volumes. The `z` option tells Podman that two pods -share the volume content. As a result, Podman labels the content with a shared -content label. Shared volume labels allow all containers to read/write content. -The `Z` option tells Podman to label the content with a private unshared label. -Only the current pod can use a private volume. - - `Overlay Volume Mounts` - - The `:O` flag tells Podman to mount the directory from the host as a -temporary storage using the `overlay file system`. The pod processes -can modify content within the mountpoint which is stored in the -container storage in a separate directory. In overlay terms, the source -directory will be the lower, and the container storage directory will be the -upper. Modifications to the mount point are destroyed when the pod -finishes executing, similar to a tmpfs mount point being unmounted. - - Subsequent executions of the container will see the original source directory -content, any changes from previous pod executions no longer exist. - - One use case of the overlay mount is sharing the package cache from the -host into the container to allow speeding up builds. - - Note: - - - The `O` flag conflicts with other options listed above. -Content mounted into the container is labeled with the private label. - On SELinux systems, labels in the source directory must be readable -by the infra container label. Usually containers can read/execute `container_share_t` -and can read/write `container_file_t`. If you cannot change the labels on a -source volume, SELinux container separation must be disabled for the infra container/pod -to work. - - The source directory mounted into the pod with an overlay mount -should not be modified, it can cause unexpected failures. It is recommended -that you do not modify the directory until the container finishes running. - - `Mounts propagation` - -By default bind mounted volumes are `private`. That means any mounts done -inside pod will not be visible on host and vice versa. One can change -this behavior by specifying a volume mount propagation property. Making a -volume `shared` mounts done under that volume inside pod will be -visible on host and vice versa. Making a volume `slave` enables only one -way mount propagation and that is mounts done on host under that volume -will be visible inside container but not the other way around. <sup>[[1]](#Footnote1)</sup> - -To control mount propagation property of a volume one can use the [**r**]**shared**, -[**r**]**slave**, [**r**]**private** or the [**r**]**unbindable** propagation flag. -For mount propagation to work the source mount point (the mount point where source dir -is mounted on) has to have the right propagation properties. For shared volumes, the -source mount point has to be shared. And for slave volumes, the source mount point -has to be either shared or slave. <sup>[[1]](#Footnote1)</sup> - -If you want to recursively mount a volume and all of its submounts into a -pod, then you can use the `rbind` option. By default the bind option is -used, and submounts of the source directory will not be mounted into the -pod. - -Mounting the volume with the `nosuid` options means that SUID applications on -the volume will not be able to change their privilege. By default volumes -are mounted with `nosuid`. - -Mounting the volume with the noexec option means that no executables on the -volume will be able to executed within the pod. - -Mounting the volume with the nodev option means that no devices on the volume -will be able to be used by processes within the pod. By default volumes -are mounted with `nodev`. - -If the `<source-dir>` is a mount point, then "dev", "suid", and "exec" options are -ignored by the kernel. - -Use `df <source-dir>` to figure out the source mount and then use -`findmnt -o TARGET,PROPAGATION <source-mount-dir>` to figure out propagation -properties of source mount. If `findmnt` utility is not available, then one -can look at the mount entry for the source mount point in `/proc/self/mountinfo`. Look -at `optional fields` and see if any propagation properties are specified. -`shared:X` means mount is `shared`, `master:X` means mount is `slave` and if -nothing is there that means mount is `private`. <sup>[[1]](#Footnote1)</sup> - -To change propagation properties of a mount point use `mount` command. For -example, if one wants to bind mount source directory `/foo` one can do -`mount --bind /foo /foo` and `mount --make-private --make-shared /foo`. This -will convert /foo into a `shared` mount point. Alternatively one can directly -change propagation properties of source mount. Say `/` is source mount for -`/foo`, then use `mount --make-shared /` to convert `/` into a `shared` mount. - -Note: if the user only has access rights via a group, accessing the volume -from inside a rootless pod will fail. +@@option volume #### **--volumes-from**=*container[:options]]* @@ -570,3 +325,6 @@ $ podman pod create --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10 ## HISTORY July 2018, Originally compiled by Peter Hunt <pehunt@redhat.com> + +## FOOTNOTES +<a name="Footnote1">1</a>: The Podman project is committed to inclusivity, a core value of open source. The `master` and `slave` mount propagation terminology used here is problematic and divisive, and should be changed. However, these terms are currently used within the Linux kernel and must be used as-is at this time. When the kernel maintainers rectify this usage, Podman will follow suit immediately. diff --git a/docs/source/markdown/podman-pod-exists.1.md b/docs/source/markdown/podman-pod-exists.1.md index 201dfbefd..eea4633d7 100644 --- a/docs/source/markdown/podman-pod-exists.1.md +++ b/docs/source/markdown/podman-pod-exists.1.md @@ -1,4 +1,4 @@ -% podman-pod-exists(1) +% podman-pod-exists 1 ## NAME podman-pod-exists - Check if a pod exists in local storage diff --git a/docs/source/markdown/podman-pod-inspect.1.md b/docs/source/markdown/podman-pod-inspect.1.md index d0a165b05..e100256af 100644 --- a/docs/source/markdown/podman-pod-inspect.1.md +++ b/docs/source/markdown/podman-pod-inspect.1.md @@ -1,4 +1,4 @@ -% podman-pod-inspect(1) +% podman-pod-inspect 1 ## NAME podman\-pod\-inspect - Displays information describing a pod diff --git a/docs/source/markdown/podman-pod-kill.1.md b/docs/source/markdown/podman-pod-kill.1.md.in index 96ced68a7..64425bb4d 100644 --- a/docs/source/markdown/podman-pod-kill.1.md +++ b/docs/source/markdown/podman-pod-kill.1.md.in @@ -1,4 +1,4 @@ -% podman-pod-kill(1) +% podman-pod-kill 1 ## NAME podman\-pod\-kill - Kill the main process of each container in one or more pods @@ -19,10 +19,7 @@ Sends signal to all containers associated with a pod. Instead of providing the pod name or ID, use the last created pod. If you use methods other than Podman to run pods such as CRI-O, the last started pod could be from either of those methods. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) -#### **--signal**, **-s** - -Signal to send to the containers in the pod. For more information on Linux signals, refer to *man signal(7)*. - +@@option signal ## EXAMPLE diff --git a/docs/source/markdown/podman-pod-logs.1.md.in b/docs/source/markdown/podman-pod-logs.1.md.in index 391f620f8..cc224eee3 100644 --- a/docs/source/markdown/podman-pod-logs.1.md.in +++ b/docs/source/markdown/podman-pod-logs.1.md.in @@ -1,4 +1,4 @@ -% podman-pod-logs(1) +% podman-pod-logs 1 ## NAME podman\-pod\-logs - Displays logs for pod with one or more containers diff --git a/docs/source/markdown/podman-pod-pause.1.md b/docs/source/markdown/podman-pod-pause.1.md index 2d2fac00d..6519ae2e7 100644 --- a/docs/source/markdown/podman-pod-pause.1.md +++ b/docs/source/markdown/podman-pod-pause.1.md @@ -1,4 +1,4 @@ -% podman-pod-pause(1) +% podman-pod-pause 1 ## NAME podman\-pod\-pause - Pause one or more pods diff --git a/docs/source/markdown/podman-pod-prune.1.md b/docs/source/markdown/podman-pod-prune.1.md index 6cc9babf1..5dfb14517 100644 --- a/docs/source/markdown/podman-pod-prune.1.md +++ b/docs/source/markdown/podman-pod-prune.1.md @@ -1,4 +1,4 @@ -% podman-pod-prune(1) +% podman-pod-prune 1 ## NAME podman-pod-prune - Remove all stopped pods and their containers diff --git a/docs/source/markdown/podman-pod-ps.1.md b/docs/source/markdown/podman-pod-ps.1.md index 34f49173a..ae249ecf0 100644 --- a/docs/source/markdown/podman-pod-ps.1.md +++ b/docs/source/markdown/podman-pod-ps.1.md @@ -1,4 +1,4 @@ -% podman-pod-ps(1) +% podman-pod-ps 1 ## NAME podman\-pod\-ps - Prints out information about pods diff --git a/docs/source/markdown/podman-pod-restart.1.md b/docs/source/markdown/podman-pod-restart.1.md index 677eca3a3..1e309be9f 100644 --- a/docs/source/markdown/podman-pod-restart.1.md +++ b/docs/source/markdown/podman-pod-restart.1.md @@ -1,4 +1,4 @@ -% podman-pod-restart(1) +% podman-pod-restart 1 ## NAME podman\-pod\-restart - Restart one or more pods @@ -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.in b/docs/source/markdown/podman-pod-rm.1.md.in index 82e28acb1..5d708b65c 100644 --- a/docs/source/markdown/podman-pod-rm.1.md.in +++ b/docs/source/markdown/podman-pod-rm.1.md.in @@ -1,4 +1,4 @@ -% podman-pod-rm(1) +% podman-pod-rm 1 ## NAME podman\-pod\-rm - Remove one or more stopped pods and containers diff --git a/docs/source/markdown/podman-pod-start.1.md.in b/docs/source/markdown/podman-pod-start.1.md.in index 6a47ce1b9..aec67b009 100644 --- a/docs/source/markdown/podman-pod-start.1.md.in +++ b/docs/source/markdown/podman-pod-start.1.md.in @@ -1,4 +1,4 @@ -% podman-pod-start(1) +% podman-pod-start 1 ## NAME podman\-pod\-start - Start one or more pods diff --git a/docs/source/markdown/podman-pod-stats.1.md b/docs/source/markdown/podman-pod-stats.1.md index 389540fdf..c71159f09 100644 --- a/docs/source/markdown/podman-pod-stats.1.md +++ b/docs/source/markdown/podman-pod-stats.1.md @@ -1,4 +1,4 @@ -% podman-pod-stats(1) +% podman-pod-stats 1 ## NAME podman\-pod\-stats - Display a live stream of resource usage stats for containers in one or more pods diff --git a/docs/source/markdown/podman-pod-stop.1.md.in b/docs/source/markdown/podman-pod-stop.1.md.in index 3655c3938..575a5fa30 100644 --- a/docs/source/markdown/podman-pod-stop.1.md.in +++ b/docs/source/markdown/podman-pod-stop.1.md.in @@ -1,4 +1,4 @@ -% podman-pod-stop(1) +% podman-pod-stop 1 ## NAME podman\-pod\-stop - Stop one or more pods @@ -29,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 @@ -65,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-pod-top.1.md b/docs/source/markdown/podman-pod-top.1.md index 3f4c24117..6a2077656 100644 --- a/docs/source/markdown/podman-pod-top.1.md +++ b/docs/source/markdown/podman-pod-top.1.md @@ -1,4 +1,4 @@ -% podman-pod-top(1) +% podman-pod-top 1 ## NAME podman\-pod\-top - Display the running processes of containers in a pod diff --git a/docs/source/markdown/podman-pod-unpause.1.md b/docs/source/markdown/podman-pod-unpause.1.md index d6645d69c..f4b50275e 100644 --- a/docs/source/markdown/podman-pod-unpause.1.md +++ b/docs/source/markdown/podman-pod-unpause.1.md @@ -1,4 +1,4 @@ -% podman-pod-unpause(1) +% podman-pod-unpause 1 ## NAME podman\-pod\-unpause - Unpause one or more pods diff --git a/docs/source/markdown/podman-pod.1.md b/docs/source/markdown/podman-pod.1.md index c38235e89..680324316 100644 --- a/docs/source/markdown/podman-pod.1.md +++ b/docs/source/markdown/podman-pod.1.md @@ -1,4 +1,4 @@ -% podman-pod(1) +% podman-pod 1 ## NAME podman\-pod - Management tool for groups of containers, called pods diff --git a/docs/source/markdown/podman-port.1.md b/docs/source/markdown/podman-port.1.md index ebfeeccd7..c1c67a28d 100644 --- a/docs/source/markdown/podman-port.1.md +++ b/docs/source/markdown/podman-port.1.md @@ -1,4 +1,4 @@ -% podman-port(1) +% podman-port 1 ## NAME podman\-port - List port mappings for a container diff --git a/docs/source/markdown/podman-ps.1.md b/docs/source/markdown/podman-ps.1.md index 6e2a8616c..3b5a2a508 100644 --- a/docs/source/markdown/podman-ps.1.md +++ b/docs/source/markdown/podman-ps.1.md @@ -1,4 +1,4 @@ -% podman-ps(1) +% podman-ps 1 ## NAME podman\-ps - Prints out information about containers diff --git a/docs/source/markdown/podman-pull.1.md.in b/docs/source/markdown/podman-pull.1.md.in index 03f9b8fd7..5405d7a45 100644 --- a/docs/source/markdown/podman-pull.1.md.in +++ b/docs/source/markdown/podman-pull.1.md.in @@ -1,4 +1,4 @@ -% podman-pull(1) +% podman-pull 1 ## NAME podman\-pull - Pull an image from a registry diff --git a/docs/source/markdown/podman-push.1.md.in b/docs/source/markdown/podman-push.1.md.in index a98964e45..6e6eecfa2 100644 --- a/docs/source/markdown/podman-push.1.md.in +++ b/docs/source/markdown/podman-push.1.md.in @@ -1,4 +1,4 @@ -% podman-push(1) +% podman-push 1 ## NAME podman\-push - Push an image, manifest list or image index from local storage to elsewhere @@ -62,9 +62,7 @@ Specifies the compression format to use. Supported values are: `gzip`, `zstd` a @@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) +@@option digestfile @@option disable-content-trust diff --git a/docs/source/markdown/podman-remote.1.md b/docs/source/markdown/podman-remote.1.md index e87129e38..6369eea56 100644 --- a/docs/source/markdown/podman-remote.1.md +++ b/docs/source/markdown/podman-remote.1.md @@ -1,4 +1,4 @@ -% podman-remote(1) +% podman-remote 1 ## NAME podman-remote - A remote CLI for Podman: A Simple management tool for pods, containers and images. diff --git a/docs/source/markdown/podman-rename.1.md b/docs/source/markdown/podman-rename.1.md index 4017db505..a91ac2666 100644 --- a/docs/source/markdown/podman-rename.1.md +++ b/docs/source/markdown/podman-rename.1.md @@ -1,4 +1,4 @@ -% podman-rename(1) +% podman-rename 1 ## NAME podman\-rename - Rename an existing container @@ -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 b9da413f7..513b9a1bf 100644 --- a/docs/source/markdown/podman-restart.1.md +++ b/docs/source/markdown/podman-restart.1.md @@ -1,4 +1,4 @@ -% podman-restart(1) +% podman-restart 1 ## NAME podman\-restart - Restart one or more containers diff --git a/docs/source/markdown/podman-rm.1.md.in b/docs/source/markdown/podman-rm.1.md.in index c0fa94d82..6f4366ce9 100644 --- a/docs/source/markdown/podman-rm.1.md.in +++ b/docs/source/markdown/podman-rm.1.md.in @@ -1,4 +1,4 @@ -% podman-rm(1) +% podman-rm 1 ## NAME podman\-rm - Remove one or more containers @@ -73,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-rmi.1.md b/docs/source/markdown/podman-rmi.1.md index 93658daaf..08e6742c9 100644 --- a/docs/source/markdown/podman-rmi.1.md +++ b/docs/source/markdown/podman-rmi.1.md @@ -1,4 +1,4 @@ -% podman-rmi(1) +% podman-rmi 1 ## NAME podman\-rmi - Removes one or more locally stored images diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index c7985d7e1..493a7494a 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -1,4 +1,4 @@ -% podman-run(1) +% podman-run 1 ## NAME podman\-run - Run a command in a new container @@ -159,50 +159,21 @@ Specify the key sequence for detaching a container. Format is a single character This option can also be set in **containers.conf**(5) file. -#### **--device**=*host-device[:container-device][:permissions]* - -Add a host device to the container. Optional *permissions* parameter -can be used to specify device permissions by combining -**r** for read, **w** for write, and **m** for **mknod**(2). - -Example: **--device=/dev/sdc:/dev/xvdc:rwm**. - -Note: if _host_device_ is a symbolic link then it will be resolved first. -The container will only store the major and minor numbers of the host device. +@@option device Note: if the user only has access rights via a group, accessing the device from inside a rootless container will fail. Use the `--group-add keep-groups` flag to pass the user's supplementary group access into the container. -Podman may load kernel modules required for using the specified -device. The devices that Podman will load modules when necessary are: -/dev/fuse. - @@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* +@@option device-read-bps -Limit read rate (in IO operations per second) from a device (e.g. **--device-read-iops=/dev/sda:1000**). +@@option device-read-iops -This option is not supported on cgroups V1 rootless systems. +@@option device-write-bps -#### **--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**). - -This option is not supported on cgroups V1 rootless systems. +@@option device-write-iops @@option disable-content-trust @@ -218,14 +189,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_. - -#### **--dns-search**=*domain* +@@option dns-opt.container -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 @@ -255,6 +221,8 @@ Read in a line delimited file of environment variables. See **Environment** note @@option health-interval +@@option health-on-failure + @@option health-retries @@option health-start-period @@ -269,20 +237,7 @@ Print usage statement @@option hostuser -#### **--http-proxy** - -By default proxy environment variables are passed into the container if set -for the Podman process. This can be disabled by setting the value to **false**. -The environment variables passed in include **http_proxy**, -**https_proxy**, **ftp_proxy**, **no_proxy**, and also the upper case versions of -those. This option is only needed when the host system must use a proxy but -the container should not use any proxy. Proxy environment variables specified -for the container in any other way will override the values that would have -been passed through from the host. (Other ways to specify the proxy for the -container include passing the values with the **--env** flag, or hard coding the -proxy environment at container build time.) (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -Defaults to **true**. +@@option http-proxy @@option image-volume @@ -314,9 +269,7 @@ To specify multiple static IPv6 addresses per container, set multiple networks u @@option ipc -#### **--label**, **-l**=*key=value* - -Add metadata to a container. +@@option label @@option label-file @@ -343,62 +296,17 @@ This option is currently supported only by the **journald** log driver. @@option mac-address -#### **--memory**, **-m**=*number[unit]* - -Memory limit. A _unit_ can be **b** (bytes), **k** (kibibytes), **m** (mebibytes), or **g** (gibibytes). - -Allows you to constrain the memory available to a container. If the host -supports swap memory, then the **-m** memory setting can be larger than physical -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). - -After setting memory reservation, when the system detects memory contention -or low memory, containers are forced to restrict their consumption to their -reservation. So you should always set the value below **--memory**, otherwise the -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. -A _unit_ can be **b** (bytes), **k** (kibibytes), **m** (mebibytes), or **g** (gibibytes). +@@option memory -Must be used with the **-m** (**--memory**) flag. -The argument value should always be larger than that of - **-m** (**--memory**) By default, it is set to double -the value of **--memory**. +@@option memory-reservation -Set _number_ to **-1** to enable unlimited swap. - -This option is not supported on cgroups V1 rootless systems. +@@option memory-swap @@option memory-swappiness @@option mount -#### **--name**=*name* - -Assign a name to the container. - -The operator can identify a container in three ways: - -- UUID long identifier (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”); -- UUID short identifier (“f78375b1c487”); -- Name (“jonah”). - -Podman generates a UUID for each container, and if a name is not assigned -to the container with **--name** then it will generate a random -string name. The name is useful any place you need to identify a container. -This works for both background and foreground containers. +@@option name.container #### **--network**=*mode*, **--net** @@ -479,20 +387,7 @@ If a container is run with a pod, and the pod has an infra-container, the infra- Pass down to the process N additional file descriptors (in addition to 0, 1, 2). The total FDs will be 3+N. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) -#### **--privileged** - -Give extended privileges to this container. The default is **false**. - -By default, Podman containers are unprivileged (**=false**) and cannot, for -example, modify parts of the operating system. This is because by default a -container is only allowed limited access to devices. A "privileged" container -is given the same access to devices as the user launching the container. - -A privileged container turns off the security features that isolate the -container from the host. Dropped Capabilities, limited devices, read-only mount -points, Apparmor/SELinux separation, and Seccomp filters are all disabled. - -Rootless containers cannot have more privileges than the account that launched them. +@@option privileged #### **--publish**, **-p**=*[[ip:][hostPort]:]containerPort[/protocol]* @@ -549,21 +444,7 @@ Suppress output information when pulling images @@option requires -#### **--restart**=*policy* - -Restart policy to follow when containers exit. -Restart policy will not take effect if a container is stopped via the **podman kill** or **podman stop** commands. - -Valid _policy_ values are: - -- `no` : Do not restart containers on exit -- `on-failure[:max_retries]` : Restart containers when they exit with a non-zero exit code, retrying indefinitely or until the optional *max_retries* count is hit -- `always` : Restart containers when they exit, regardless of status, retrying indefinitely -- `unless-stopped` : Identical to **always** - -Please note that restart will not restart containers after a system reboot. -If this functionality is required in your environment, you can invoke Podman from a **systemd.unit**(5) file, or create an init script for whichever init system is in use. -To generate systemd unit files, please see **podman generate systemd**. +@@option restart #### **--rm** @@ -646,71 +527,13 @@ Sets whether the signals sent to the **podman run** command are proxied to the c @@option stop-timeout -#### **--subgidname**=*name* - -Run the container in a new user namespace using the map with _name_ in the _/etc/subgid_ file. -If calling **podman run** as an unprivileged user, the user needs to have the right to use the mapping. See **subgid**(5). -This flag conflicts with **--userns** and **--gidmap**. - -#### **--subuidname**=*name* - -Run the container in a new user namespace using the map with _name_ in the _/etc/subuid_ file. -If calling **podman run** as an unprivileged user, the user needs to have the right to use the mapping. See **subuid**(5). -This flag conflicts with **--userns** and **--uidmap**. - -#### **--sysctl**=*name=value* - -Configure namespaced kernel parameters at runtime. - -For the IPC namespace, the following sysctls are allowed: - -- kernel.msgmax -- kernel.msgmnb -- kernel.msgmni -- kernel.sem -- kernel.shmall -- kernel.shmmax -- kernel.shmmni -- kernel.shm_rmid_forced -- Sysctls beginning with fs.mqueue.\* - -Note: if you use the **--ipc=host** option, the above sysctls will not be allowed. - -For the network namespace, the following sysctls are allowed: - -- Sysctls beginning with net.\* - -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**. +@@option subgidname -Running the container in systemd mode causes the following changes: +@@option subuidname -* 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. +@@option sysctl -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 @@ -754,228 +577,16 @@ Without this argument, the command will run as the user specified in the contain When a user namespace is not in use, the UID and GID used within the container and on the host will match. When user namespaces are in use, however, the UID and GID in the container may correspond to another UID and GID on the host. In rootless containers, for example, a user namespace is always used, and root in the container will by default correspond to the UID and GID of the user invoking Podman. -#### **--userns**=*mode* - -Set the user namespace mode for the container. It defaults to the **PODMAN_USERNS** environment variable. An empty value ("") means user namespaces are disabled unless an explicit mapping is set with the **--uidmap** and **--gidmap** options. - -Rootless user --userns=Key mappings: - -Key | Host User | Container User -----------|---------------|--------------------- -"" |$UID |0 (Default User account mapped to root user in container.) -keep-id |$UID |$UID (Map user account to same UID within container.) -auto |$UID | nil (Host User UID is not mapped into container.) -nomap |$UID | nil (Host User UID is not mapped into container.) - -Valid _mode_ values are: - -**auto**[:_OPTIONS,..._]: automatically create a unique user namespace. - -The `--userns=auto` flag, requires that the user name `containers` and a range of subordinate user ids that the Podman container is allowed to use be specified in the /etc/subuid and /etc/subgid files. - -Example: `containers:2147483647:2147483648`. - -Podman allocates unique ranges of UIDs and GIDs from the `containers` subordinate user ids. The size of the ranges is based on the number of UIDs required in the image. The number of UIDs and GIDs can be overridden with the `size` option. - -The rootless option `--userns=keep-id` uses all the subuids and subgids of the user. Using `--userns=auto` when starting new containers will not work as long as any containers exist that were started with `--userns=keep-id`. - - Valid `auto` options: - - - *gidmapping*=_CONTAINER_GID:HOST_GID:SIZE_: to force a GID mapping to be present in the user namespace. - - *size*=_SIZE_: to specify an explicit size for the automatic user namespace. e.g. `--userns=auto:size=8192`. If `size` is not specified, `auto` will estimate a size for the user namespace. - - *uidmapping*=_CONTAINER_UID:HOST_UID:SIZE_: to force a UID mapping to be present in the user namespace. - -**container:**_id_: join the user namespace of the specified container. - -**host**: run in the user namespace of the caller. The processes running in the container will have the same privileges on the host as any other process launched by the calling user (default). - -**keep-id**: creates a user namespace where the current rootless user's UID:GID are mapped to the same values in the container. This option is not allowed for containers created by the root user. - -**nomap**: creates a user namespace where the current rootless user's UID:GID are not mapped into the container. This option is not allowed for containers created by the root user. - -**ns:**_namespace_: run the container in the given existing user namespace. - -**private**: create a new namespace for the container. -This option is incompatible with **--gidmap**, **--uidmap**, **--subuidname** and **--subgidname**. +@@option userns.container @@option uts.container #### **--variant**=*VARIANT* Use _VARIANT_ instead of the default architecture variant of the container image. Some images can use multiple variants of the arm architectures, such as arm/v5 and arm/v7. -#### **--volume**, **-v**=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]* - -Create a bind mount. If you specify _/HOST-DIR_:_/CONTAINER-DIR_, Podman -bind mounts _host-dir_ in the host to _CONTAINER-DIR_ in the Podman -container. Similarly, _SOURCE-VOLUME_:_/CONTAINER-DIR_ will mount the volume -in the host to the container. If no such named volume exists, Podman will -create one. (Note when using the remote client, including Mac and Windows (excluding WSL2) machines, the volumes will be mounted from the remote server, not necessarily the client machine.) - -The _options_ is a comma-separated list and can be: <sup>[[1]](#Footnote1)</sup> - -* **rw**|**ro** -* **z**|**Z** -* [**O**] -* [**U**] -* [**no**]**copy** -* [**no**]**dev** -* [**no**]**exec** -* [**no**]**suid** -* [**r**]**bind** -* [**r**]**shared**|[**r**]**slave**|[**r**]**private**[**r**]**unbindable** - -The `CONTAINER-DIR` must be an absolute path such as `/src/docs`. The volume -will be mounted into the container at this directory. - -Volumes may specify a source as well, as either a directory on the host -or the name of a named volume. If no source is given, the volume will be created as an -anonymously named volume with a randomly generated name, and will be removed when -the container is removed via the `--rm` flag or `podman rm --volumes`. +@@option volume -If a volume source is specified, it must be a path on the host or the name of a -named volume. Host paths are allowed to be absolute or relative; relative paths -are resolved relative to the directory Podman is run in. If the source does not -exist, Podman will return an error. Users must pre-create the source files or -directories. - -Any source that does not begin with a `.` or `/` will be treated as the name of -a named volume. If a volume with that name does not exist, it will be created. -Volumes created with names are not anonymous, and they are not removed by the `--rm` -option and the `podman rm --volumes` command. - -You can specify multiple **-v** options to mount one or more volumes into a -container. - - `Write Protected Volume Mounts` - -You can add **:ro** or **:rw** option to mount a volume in read-only or -read-write mode, respectively. By default, the volumes are mounted read-write. - - `Chowning Volume Mounts` - -By default, Podman does not change the owner and group of source volume -directories mounted into containers. If a container is created in a new user -namespace, the UID and GID in the container may correspond to another UID and -GID on the host. - -The `:U` suffix tells Podman to use the correct host UID and GID based on the -UID and GID within the container, to change recursively the owner and group of -the source volume. - -**Warning** use with caution since this will modify the host filesystem. - - `Labeling Volume Mounts` - -Labeling systems like SELinux require that proper labels are placed on volume -content mounted into a container. Without a label, the security system might -prevent the processes running inside the container from using the content. By -default, Podman does not change the labels set by the OS. - -To change a label in the container context, you can add either of two suffixes -**:z** or **:Z** to the volume mount. These suffixes tell Podman to relabel file -objects on the shared volumes. The **z** option tells Podman that two containers -share the volume content. As a result, Podman labels the content with a shared -content label. Shared volume labels allow all containers to read/write content. -The **Z** option tells Podman to label the content with a private unshared label. - -Note: Do not relabel system files and directories. Relabeling system content -might cause other confined services on your machine to fail. For these types -of containers we recommend disabling SELinux separation. The option -`--security-opt label=disable` disables SELinux separation for the container. -For example if a user wanted to volume mount their entire home directory into a -container, they need to disable SELinux separation. - - $ podman run --security-opt label=disable -v $HOME:/home/user fedora touch /home/user/file - - `Overlay Volume Mounts` - - The `:O` flag tells Podman to mount the directory from the host as a -temporary storage using the `overlay file system`. The container processes -can modify content within the mountpoint which is stored in the -container storage in a separate directory. In overlay terms, the source -directory will be the lower, and the container storage directory will be the -upper. Modifications to the mount point are destroyed when the container -finishes executing, similar to a tmpfs mount point being unmounted. - - For advanced users overlay option also supports custom non-volatile `upperdir` and `workdir` -for the overlay mount. Custom `upperdir` and `workdir` can be fully managed by the users themselves -and `podman` will not remove it on lifecycle completion. Example `:O,upperdir=/some/upper,workdir=/some/work` - - Subsequent executions of the container will see the original source directory -content, any changes from previous container executions no longer exist. - - One use case of the overlay mount is sharing the package cache from the -host into the container to allow speeding up builds. - - Note: - - - The `O` flag conflicts with other options listed above. -Content mounted into the container is labeled with the private label. - On SELinux systems, labels in the source directory must be readable -by the container label. Usually containers can read/execute `container_share_t` -and can read/write `container_file_t`. If you cannot change the labels on a -source volume, SELinux container separation must be disabled for the container -to work. - - The source directory mounted into the container with an overlay mount -should not be modified, it can cause unexpected failures. It is recommended -that you do not modify the directory until the container finishes running. - -Only the current container can use a private volume. - - `Mounts propagation` - -By default bind mounted volumes are `private`. That means any mounts done -inside container will not be visible on host and vice versa. One can change -this behavior by specifying a volume mount propagation property. Making a -volume shared mounts done under that volume inside container will be -visible on host and vice versa. Making a volume **slave** enables only one -way mount propagation and that is mounts done on host under that volume -will be visible inside container but not the other way around. <sup>[[1]](#Footnote1)</sup> - -To control mount propagation property of a volume one can use the [**r**]**shared**, -[**r**]**slave**, [**r**]**private** or the [**r**]**unbindable** propagation flag. -For mount propagation to work the source mount point (the mount point where source dir -is mounted on) has to have the right propagation properties. For shared volumes, the -source mount point has to be shared. And for slave volumes, the source mount point -has to be either shared or slave. <sup>[[1]](#Footnote1)</sup> - -If you want to recursively mount a volume and all of its submounts into a -container, then you can use the **rbind** option. By default the bind option is -used, and submounts of the source directory will not be mounted into the -container. - -Mounting the volume with the **nosuid** options means that SUID applications on -the volume will not be able to change their privilege. By default volumes -are mounted with **nosuid**. - -Mounting the volume with the **noexec** option means that no executables on the -volume will be able to be executed within the container. - -Mounting the volume with the **nodev** option means that no devices on the volume -will be able to be used by processes within the container. By default volumes -are mounted with **nodev**. - -If the _host-dir_ is a mount point, then **dev**, **suid**, and **exec** options are -ignored by the kernel. - -Use **df $hostdir** to figure out the source mount, and then use -**findmnt -o TARGET,PROPAGATION _source-mount-dir_** to figure out propagation -properties of source mount. If **findmnt**(1) utility is not available, then one -can look at mount entry for source mount point in _/proc/self/mountinfo_. Look -at the "optional fields" and see if any propagation properties are specified. -In there, **shared:N** means the mount is shared, **master:N** means mount -is slave, and if nothing is there, the mount is private. <sup>[[1]](#Footnote1)</sup> - -To change propagation properties of a mount point, use **mount**(8) command. For -example, if one wants to bind mount source directory _/foo_, one can do -**mount --bind /foo /foo** and **mount --make-private --make-shared /foo**. This -will convert /foo into a shared mount point. Alternatively, one can directly -change propagation properties of source mount. Say, if _/_ is source mount for -_/foo_, then use **mount --make-shared /** to convert _/_ into a shared mount. - -Note: if the user only has access rights via a group, accessing the volume -from inside a rootless container will fail. Use the `--group-add keep-groups` -flag to pass the user's supplementary group access into the container. +Use the **--group-add keep-groups** option to pass the user's supplementary group access into the container. #### **--volumes-from**=*CONTAINER[:OPTIONS]* diff --git a/docs/source/markdown/podman-save.1.md b/docs/source/markdown/podman-save.1.md index aa4900e25..088d9dc21 100644 --- a/docs/source/markdown/podman-save.1.md +++ b/docs/source/markdown/podman-save.1.md @@ -1,4 +1,4 @@ -% podman-save(1) +% podman-save 1 ## NAME podman\-save - Save image(s) to an archive diff --git a/docs/source/markdown/podman-search.1.md.in b/docs/source/markdown/podman-search.1.md.in index 9dd8cebf8..102cf7ad7 100644 --- a/docs/source/markdown/podman-search.1.md.in +++ b/docs/source/markdown/podman-search.1.md.in @@ -1,4 +1,4 @@ -% podman-search(1) +% podman-search 1 ## NAME podman\-search - Search a registry for an image diff --git a/docs/source/markdown/podman-secret-create.1.md b/docs/source/markdown/podman-secret-create.1.md index 39e0c6843..1aafc6c11 100644 --- a/docs/source/markdown/podman-secret-create.1.md +++ b/docs/source/markdown/podman-secret-create.1.md @@ -1,4 +1,4 @@ -% podman-secret-create(1) +% podman-secret-create 1 ## NAME podman\-secret\-create - Create a new secret diff --git a/docs/source/markdown/podman-secret-inspect.1.md b/docs/source/markdown/podman-secret-inspect.1.md index 1a7115f63..0e0d16120 100644 --- a/docs/source/markdown/podman-secret-inspect.1.md +++ b/docs/source/markdown/podman-secret-inspect.1.md @@ -1,4 +1,4 @@ -% podman-secret-inspect(1) +% podman-secret-inspect 1 ## NAME podman\-secret\-inspect - Display detailed information on one or more secrets diff --git a/docs/source/markdown/podman-secret-ls.1.md b/docs/source/markdown/podman-secret-ls.1.md index dcd10c9cf..6f82f562b 100644 --- a/docs/source/markdown/podman-secret-ls.1.md +++ b/docs/source/markdown/podman-secret-ls.1.md @@ -1,4 +1,4 @@ -% podman-secret-ls(1) +% podman-secret-ls 1 ## NAME podman\-secret\-ls - List all available secrets diff --git a/docs/source/markdown/podman-secret-rm.1.md b/docs/source/markdown/podman-secret-rm.1.md index ceab3df60..820c8515c 100644 --- a/docs/source/markdown/podman-secret-rm.1.md +++ b/docs/source/markdown/podman-secret-rm.1.md @@ -1,4 +1,4 @@ -% podman-secret-rm(1) +% podman-secret-rm 1 ## NAME podman\-secret\-rm - Remove one or more secrets diff --git a/docs/source/markdown/podman-secret.1.md b/docs/source/markdown/podman-secret.1.md index 671a0c43b..f6c0a945f 100644 --- a/docs/source/markdown/podman-secret.1.md +++ b/docs/source/markdown/podman-secret.1.md @@ -1,4 +1,4 @@ -% podman-secret(1) +% podman-secret 1 ## NAME podman\-secret - Manage podman secrets diff --git a/docs/source/markdown/podman-start.1.md b/docs/source/markdown/podman-start.1.md index 6b0433483..fd24c6bf4 100644 --- a/docs/source/markdown/podman-start.1.md +++ b/docs/source/markdown/podman-start.1.md @@ -1,4 +1,4 @@ -% podman-start(1) +% podman-start 1 ## NAME podman\-start - Start one or more containers diff --git a/docs/source/markdown/podman-stats.1.md b/docs/source/markdown/podman-stats.1.md index 8d07be1a0..a1a0f6a93 100644 --- a/docs/source/markdown/podman-stats.1.md +++ b/docs/source/markdown/podman-stats.1.md @@ -1,4 +1,4 @@ -% podman-stats(1) +% podman-stats 1 ## NAME podman\-stats - Display a live stream of one or more container's resource usage statistics diff --git a/docs/source/markdown/podman-stop.1.md.in b/docs/source/markdown/podman-stop.1.md.in index 9aaccdfaa..7b32ca4b0 100644 --- a/docs/source/markdown/podman-stop.1.md.in +++ b/docs/source/markdown/podman-stop.1.md.in @@ -1,4 +1,4 @@ -% podman-stop(1) +% podman-stop 1 ## NAME podman\-stop - Stop one or more running containers diff --git a/docs/source/markdown/podman-system-connection-add.1.md b/docs/source/markdown/podman-system-connection-add.1.md index d608ab7a7..f06cd2780 100644 --- a/docs/source/markdown/podman-system-connection-add.1.md +++ b/docs/source/markdown/podman-system-connection-add.1.md @@ -1,4 +1,4 @@ -% podman-system-connection-add(1) +% podman-system-connection-add 1 ## NAME podman\-system\-connection\-add - Record destination for the Podman service diff --git a/docs/source/markdown/podman-system-connection-default.1.md b/docs/source/markdown/podman-system-connection-default.1.md index 49f165e81..574625cef 100644 --- a/docs/source/markdown/podman-system-connection-default.1.md +++ b/docs/source/markdown/podman-system-connection-default.1.md @@ -1,4 +1,4 @@ -% podman-system-connection-default(1) +% podman-system-connection-default 1 ## NAME podman\-system\-connection\-default - Set named destination as default for the Podman service diff --git a/docs/source/markdown/podman-system-connection-list.1.md b/docs/source/markdown/podman-system-connection-list.1.md index 23784a319..325c78a5c 100644 --- a/docs/source/markdown/podman-system-connection-list.1.md +++ b/docs/source/markdown/podman-system-connection-list.1.md @@ -1,4 +1,4 @@ -% podman-system-connection-list(1) +% podman-system-connection-list 1 ## NAME podman\-system\-connection\-list - List the destination for the Podman service(s) diff --git a/docs/source/markdown/podman-system-connection-remove.1.md b/docs/source/markdown/podman-system-connection-remove.1.md index 348b49876..45fede021 100644 --- a/docs/source/markdown/podman-system-connection-remove.1.md +++ b/docs/source/markdown/podman-system-connection-remove.1.md @@ -1,4 +1,4 @@ -% podman-system-connection-remove(1) +% podman-system-connection-remove 1 ## NAME podman\-system\-connection\-remove - Delete named destination diff --git a/docs/source/markdown/podman-system-connection-rename.1.md b/docs/source/markdown/podman-system-connection-rename.1.md index 5b5930738..ed10c1cd6 100644 --- a/docs/source/markdown/podman-system-connection-rename.1.md +++ b/docs/source/markdown/podman-system-connection-rename.1.md @@ -1,4 +1,4 @@ -% podman-system-connection-rename(1) +% podman-system-connection-rename 1 ## NAME podman\-system\-connection\-rename - Rename the destination for Podman service diff --git a/docs/source/markdown/podman-system-connection.1.md b/docs/source/markdown/podman-system-connection.1.md index df9d8d248..007fb0d22 100644 --- a/docs/source/markdown/podman-system-connection.1.md +++ b/docs/source/markdown/podman-system-connection.1.md @@ -1,4 +1,4 @@ -% podman-system-connection(1) +% podman-system-connection 1 ## NAME podman\-system\-connection - Manage the destination(s) for Podman service(s) diff --git a/docs/source/markdown/podman-system-df.1.md b/docs/source/markdown/podman-system-df.1.md index eb2c79b96..ac37d5e4d 100644 --- a/docs/source/markdown/podman-system-df.1.md +++ b/docs/source/markdown/podman-system-df.1.md @@ -1,4 +1,4 @@ -% podman-system-df(1) +% podman-system-df 1 ## NAME podman\-system\-df - Show podman disk usage diff --git a/docs/source/markdown/podman-system-migrate.1.md b/docs/source/markdown/podman-system-migrate.1.md index dbdd24132..2e9cf02e3 100644 --- a/docs/source/markdown/podman-system-migrate.1.md +++ b/docs/source/markdown/podman-system-migrate.1.md @@ -1,4 +1,4 @@ -% podman-system-migrate(1) +% podman-system-migrate 1 ## NAME podman\-system\-migrate - Migrate existing containers to a new podman version diff --git a/docs/source/markdown/podman-system-prune.1.md b/docs/source/markdown/podman-system-prune.1.md index c4c17fbe5..cb6603791 100644 --- a/docs/source/markdown/podman-system-prune.1.md +++ b/docs/source/markdown/podman-system-prune.1.md @@ -1,4 +1,4 @@ -% podman-system-prune(1) +% podman-system-prune 1 ## NAME podman\-system\-prune - Remove all unused pods, containers, images, networks, and volume data diff --git a/docs/source/markdown/podman-system-renumber.1.md b/docs/source/markdown/podman-system-renumber.1.md index 61e26242b..845fc2c53 100644 --- a/docs/source/markdown/podman-system-renumber.1.md +++ b/docs/source/markdown/podman-system-renumber.1.md @@ -1,4 +1,4 @@ -% podman-system-renumber(1) +% podman-system-renumber 1 ## NAME podman\-system\-renumber - Migrate lock numbers to handle a change in maximum number of locks diff --git a/docs/source/markdown/podman-system-reset.1.md b/docs/source/markdown/podman-system-reset.1.md index 11ce11d07..8eee416c7 100644 --- a/docs/source/markdown/podman-system-reset.1.md +++ b/docs/source/markdown/podman-system-reset.1.md @@ -1,4 +1,4 @@ -% podman-system-reset(1) +% podman-system-reset 1 ## NAME podman\-system\-reset - Reset storage back to initial state @@ -37,6 +37,7 @@ WARNING! This will remove: - all networks - all build cache - all machines + - all volumes Are you sure you want to continue? [y/N] y ``` diff --git a/docs/source/markdown/podman-system-service.1.md b/docs/source/markdown/podman-system-service.1.md index 3e7a00362..2ec48aeb4 100644 --- a/docs/source/markdown/podman-system-service.1.md +++ b/docs/source/markdown/podman-system-service.1.md @@ -1,4 +1,4 @@ -% podman-service(1) +% podman-service 1 ## NAME podman\-system\-service - Run an API service diff --git a/docs/source/markdown/podman-system.1.md b/docs/source/markdown/podman-system.1.md index 7469eb79d..0a9ef4f49 100644 --- a/docs/source/markdown/podman-system.1.md +++ b/docs/source/markdown/podman-system.1.md @@ -1,4 +1,4 @@ -% podman-system(1) +% podman-system 1 ## NAME podman\-system - Manage podman diff --git a/docs/source/markdown/podman-tag.1.md b/docs/source/markdown/podman-tag.1.md index 23dd3b60b..38ccfaec8 100644 --- a/docs/source/markdown/podman-tag.1.md +++ b/docs/source/markdown/podman-tag.1.md @@ -1,4 +1,4 @@ -% podman-tag(1) +% podman-tag 1 ## NAME podman\-tag - Add an additional name to a local image diff --git a/docs/source/markdown/podman-top.1.md b/docs/source/markdown/podman-top.1.md index 6b9433b89..ceefe84e9 100644 --- a/docs/source/markdown/podman-top.1.md +++ b/docs/source/markdown/podman-top.1.md @@ -1,4 +1,4 @@ -% podman-top(1) +% podman-top 1 ## NAME podman\-top - Display the running processes of a container diff --git a/docs/source/markdown/podman-unmount.1.md b/docs/source/markdown/podman-unmount.1.md index 3f45e8114..5493f3c1e 100644 --- a/docs/source/markdown/podman-unmount.1.md +++ b/docs/source/markdown/podman-unmount.1.md @@ -1,4 +1,4 @@ -% podman-unmount(1) +% podman-unmount 1 ## NAME podman\-unmount - Unmount a working container's root filesystem diff --git a/docs/source/markdown/podman-unpause.1.md.in b/docs/source/markdown/podman-unpause.1.md.in index 7bd46e171..85852708a 100644 --- a/docs/source/markdown/podman-unpause.1.md.in +++ b/docs/source/markdown/podman-unpause.1.md.in @@ -1,4 +1,4 @@ -% podman-unpause(1) +% podman-unpause 1 ## NAME podman\-unpause - Unpause one or more containers diff --git a/docs/source/markdown/podman-unshare.1.md b/docs/source/markdown/podman-unshare.1.md index db1bc5387..a88e514d3 100644 --- a/docs/source/markdown/podman-unshare.1.md +++ b/docs/source/markdown/podman-unshare.1.md @@ -1,4 +1,4 @@ -% podman-unshare(1) +% podman-unshare 1 ## NAME podman\-unshare - Run a command inside of a modified user namespace diff --git a/docs/source/markdown/podman-untag.1.md b/docs/source/markdown/podman-untag.1.md index 0dd882a92..f9ea2b644 100644 --- a/docs/source/markdown/podman-untag.1.md +++ b/docs/source/markdown/podman-untag.1.md @@ -1,4 +1,4 @@ -% podman-untag(1) +% podman-untag 1 ## NAME podman\-untag - Removes one or more names from a locally-stored image diff --git a/docs/source/markdown/podman-update.1.md.in b/docs/source/markdown/podman-update.1.md.in new file mode 100644 index 000000000..49f356d25 --- /dev/null +++ b/docs/source/markdown/podman-update.1.md.in @@ -0,0 +1,78 @@ +% podman-update 1 + +## NAME +podman\-update - Updates the cgroup configuration of a given container + +## SYNOPSIS +**podman update** [*options*] *container* + +**podman container update** [*options*] *container* + +## DESCRIPTION + +Updates the cgroup configuration of an already existing container. The currently supported options are a subset of the +podman create/run resource limits options. These new options are non-persistent and only last for the current execution of the container; the configuration will be honored on its next run. +This means that this command can only be executed on an already running container and the changes made will be erased the next time the container is stopped and restarted, this is to ensure immutability. +This command takes one argument, a container name or ID, alongside the resource flags to modify the cgroup. + +## OPTIONS + +@@option blkio-weight + +@@option blkio-weight-device + +@@option cpu-period + +@@option cpu-quota + +@@option cpu-rt-period + +@@option cpu-rt-runtime + +@@option cpu-shares + +@@option cpus.container + +@@option cpuset-cpus + +@@option cpuset-mems + +@@option device-read-bps + +@@option device-read-iops + +@@option device-write-bps + +@@option device-write-iops + +@@option memory + +@@option memory-reservation + +@@option memory-swap + +@@option memory-swappiness + + +## EXAMPLEs + +update a container with a new cpu quota and period +``` +podman update --cpus=5 myCtr +``` + +update a container with all available options for cgroups v2 +``` +podman update --cpus 5 --cpuset-cpus 0 --cpu-shares 123 --cpuset-mems 0 --memory 1G --memory-swap 2G --memory-reservation 2G --blkio-weight-device /dev/zero:123 --blkio-weight 123 --device-read-bps /dev/zero:10mb --device-write-bps /dev/zero:10mb --device-read-iops /dev/zero:1000 --device-write-iops /dev/zero:1000 ctrID +``` + +update a container with all available options for cgroups v1 +``` +podman update --cpus 5 --cpuset-cpus 0 --cpu-shares 123 --cpuset-mems 0 --memory 1G --memory-swap 2G --memory-reservation 2G --memory-swappiness 50 ctrID +``` + +## SEE ALSO +**[podman(1)](podman.1.md)**, **[podman-create(1)](podman-create.1.md)**, **[podman-run(1)](podman-run.1.md)** + +## HISTORY +August 2022, Originally written by Charlie Doern <cdoern@redhat.com> diff --git a/docs/source/markdown/podman-version.1.md b/docs/source/markdown/podman-version.1.md index 94fa0fb21..3062d10ab 100644 --- a/docs/source/markdown/podman-version.1.md +++ b/docs/source/markdown/podman-version.1.md @@ -1,4 +1,4 @@ -% podman-version(1) +% podman-version 1 ## NAME podman\-version - Display the Podman version information diff --git a/docs/source/markdown/podman-volume-create.1.md b/docs/source/markdown/podman-volume-create.1.md index 65b788851..934488111 100644 --- a/docs/source/markdown/podman-volume-create.1.md +++ b/docs/source/markdown/podman-volume-create.1.md @@ -1,4 +1,4 @@ -% podman-volume-create(1) +% podman-volume-create 1 ## NAME podman\-volume\-create - Create a new volume diff --git a/docs/source/markdown/podman-volume-exists.1.md b/docs/source/markdown/podman-volume-exists.1.md index 28d42e987..37aa2b61a 100644 --- a/docs/source/markdown/podman-volume-exists.1.md +++ b/docs/source/markdown/podman-volume-exists.1.md @@ -1,4 +1,4 @@ -% podman-volume-exists(1) +% podman-volume-exists 1 ## NAME podman\-volume\-exists - Check if the given volume exists diff --git a/docs/source/markdown/podman-volume-export.1.md b/docs/source/markdown/podman-volume-export.1.md index 57b707ae5..8b2959036 100644 --- a/docs/source/markdown/podman-volume-export.1.md +++ b/docs/source/markdown/podman-volume-export.1.md @@ -1,4 +1,4 @@ -% podman-volume-export(1) +% podman-volume-export 1 ## NAME podman\-volume\-export - Exports volume to external tar diff --git a/docs/source/markdown/podman-volume-import.1.md b/docs/source/markdown/podman-volume-import.1.md index ec5d5ebfc..a69ac991b 100644 --- a/docs/source/markdown/podman-volume-import.1.md +++ b/docs/source/markdown/podman-volume-import.1.md @@ -1,4 +1,4 @@ -% podman-volume-import(1) +% podman-volume-import 1 ## NAME podman\-volume\-import - Import tarball contents into an existing podman volume diff --git a/docs/source/markdown/podman-volume-inspect.1.md b/docs/source/markdown/podman-volume-inspect.1.md index 9be0f9c2d..45c39c23a 100644 --- a/docs/source/markdown/podman-volume-inspect.1.md +++ b/docs/source/markdown/podman-volume-inspect.1.md @@ -1,4 +1,4 @@ -% podman-volume-inspect(1) +% podman-volume-inspect 1 ## NAME podman\-volume\-inspect - Get detailed information on one or more volumes diff --git a/docs/source/markdown/podman-volume-ls.1.md b/docs/source/markdown/podman-volume-ls.1.md index 86896b0a2..69e999251 100644 --- a/docs/source/markdown/podman-volume-ls.1.md +++ b/docs/source/markdown/podman-volume-ls.1.md @@ -1,4 +1,4 @@ -% podman-volume-ls(1) +% podman-volume-ls 1 ## NAME podman\-volume\-ls - List all the available volumes diff --git a/docs/source/markdown/podman-volume-mount.1.md b/docs/source/markdown/podman-volume-mount.1.md index a5f35a34d..2066ec19f 100644 --- a/docs/source/markdown/podman-volume-mount.1.md +++ b/docs/source/markdown/podman-volume-mount.1.md @@ -1,4 +1,4 @@ -% podman-volume-mount(1) +% podman-volume-mount 1 ## NAME podman\-volume\-mount - Mount a volume filesystem diff --git a/docs/source/markdown/podman-volume-prune.1.md b/docs/source/markdown/podman-volume-prune.1.md index 0127cc12a..ab0479b84 100644 --- a/docs/source/markdown/podman-volume-prune.1.md +++ b/docs/source/markdown/podman-volume-prune.1.md @@ -1,4 +1,4 @@ -% podman-volume-prune(1) +% podman-volume-prune 1 ## NAME podman\-volume\-prune - Remove all unused volumes diff --git a/docs/source/markdown/podman-volume-reload.1.md b/docs/source/markdown/podman-volume-reload.1.md index 5b9e9b9ac..4e2d97b91 100644 --- a/docs/source/markdown/podman-volume-reload.1.md +++ b/docs/source/markdown/podman-volume-reload.1.md @@ -1,4 +1,4 @@ -% podman-volume-reload(1) +% podman-volume-reload 1 ## NAME podman\-volume\-reload - Reload all volumes from volumes plugins diff --git a/docs/source/markdown/podman-volume-rm.1.md b/docs/source/markdown/podman-volume-rm.1.md index 8274eaaf3..744b322b1 100644 --- a/docs/source/markdown/podman-volume-rm.1.md +++ b/docs/source/markdown/podman-volume-rm.1.md @@ -1,4 +1,4 @@ -% podman-volume-rm(1) +% podman-volume-rm 1 ## NAME podman\-volume\-rm - Remove one or more volumes diff --git a/docs/source/markdown/podman-volume-unmount.1.md b/docs/source/markdown/podman-volume-unmount.1.md index c489af6c9..3c4634835 100644 --- a/docs/source/markdown/podman-volume-unmount.1.md +++ b/docs/source/markdown/podman-volume-unmount.1.md @@ -1,4 +1,4 @@ -% podman-volume-unmount(1) +% podman-volume-unmount 1 ## NAME podman\-volume\-unmount - Unmount a volume diff --git a/docs/source/markdown/podman-volume.1.md b/docs/source/markdown/podman-volume.1.md index a437590b3..3971b485d 100644 --- a/docs/source/markdown/podman-volume.1.md +++ b/docs/source/markdown/podman-volume.1.md @@ -1,4 +1,4 @@ -% podman-volume(1) +% podman-volume 1 ## NAME podman\-volume - Simple management tool for volumes diff --git a/docs/source/markdown/podman-wait.1.md b/docs/source/markdown/podman-wait.1.md index e307e4528..a6aadf28c 100644 --- a/docs/source/markdown/podman-wait.1.md +++ b/docs/source/markdown/podman-wait.1.md @@ -1,4 +1,4 @@ -% podman-wait(1) +% podman-wait 1 ## NAME podman\-wait - Wait on one or more containers to stop and print their exit codes diff --git a/docs/source/markdown/podman.1.md b/docs/source/markdown/podman.1.md index d1192b6d2..3b3974dcc 100644 --- a/docs/source/markdown/podman.1.md +++ b/docs/source/markdown/podman.1.md @@ -1,4 +1,4 @@ -% podman(1) +% podman 1 ## NAME podman - Simple management tool for pods, containers and images @@ -355,6 +355,7 @@ the exit codes follow the `chroot` standard, see below: | [podman-unpause(1)](podman-unpause.1.md) | Unpause one or more containers. | | [podman-unshare(1)](podman-unshare.1.md) | Run a command inside of a modified user namespace. | | [podman-untag(1)](podman-untag.1.md) | Removes one or more names from a locally-stored image. | +| [podman-update(1)](podman-update.1.md) | Updates the cgroup configuration of a given container. | | [podman-version(1)](podman-version.1.md) | Display the Podman version information. | | [podman-volume(1)](podman-volume.1.md) | Simple management tool for volumes. | | [podman-wait(1)](podman-wait.1.md) | Wait on one or more containers to stop and print their exit codes. | |