diff options
Diffstat (limited to 'docs')
28 files changed, 289 insertions, 389 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/device-read-bps.md b/docs/source/markdown/options/device-read-bps.md new file mode 100644 index 000000000..e0c610061 --- /dev/null +++ b/docs/source/markdown/options/device-read-bps.md @@ -0,0 +1,5 @@ +#### **--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. 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..9cd0f9030 --- /dev/null +++ b/docs/source/markdown/options/device-read-iops.md @@ -0,0 +1,5 @@ +#### **--device-read-iops**=*path:rate* + +Limit read rate (in IO operations per second) from a device (e.g. **--device-read-iops=/dev/sda:1000**). + +This option is not supported on cgroups V1 rootless systems. 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..3dacc4515 --- /dev/null +++ b/docs/source/markdown/options/device-write-bps.md @@ -0,0 +1,5 @@ +#### **--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. 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..cf5ce3859 --- /dev/null +++ b/docs/source/markdown/options/device-write-iops.md @@ -0,0 +1,5 @@ +#### **--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. 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/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/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/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/podman-container-clone.1.md.in b/docs/source/markdown/podman-container-clone.1.md.in index 26f414b62..3e31389d2 100644 --- a/docs/source/markdown/podman-container-clone.1.md.in +++ b/docs/source/markdown/podman-container-clone.1.md.in @@ -52,36 +52,18 @@ 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)) @@ -92,8 +74,6 @@ reservation. So you should always set the value below **--memory**, otherwise th hard limit will take precedence. By default, memory reservation will be the same as memory limit from the container being cloned. -This option is not supported on cgroups V1 rootless systems. - #### **--memory-swap**=*limit* A limit value equal to memory plus swap. Must be used with the **-m** diff --git a/docs/source/markdown/podman-container.1.md b/docs/source/markdown/podman-container.1.md index a66e2789d..593cd3c42 100644 --- a/docs/source/markdown/podman-container.1.md +++ b/docs/source/markdown/podman-container.1.md @@ -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-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index 0a880951d..987f10181 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -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 @@ -148,27 +146,11 @@ device. The devices that podman will load modules when necessary are: #### **--device-read-bps**=*path* -Limit read rate (bytes per second) from a device (e.g. --device-read-bps=/dev/sda:1mb) - -This option is not supported on cgroups V1 rootless systems. - -#### **--device-read-iops**=*path* - -Limit read rate (IO per second) from a device (e.g. --device-read-iops=/dev/sda:1000) - -This option is not supported on cgroups V1 rootless systems. - -#### **--device-write-bps**=*path* - -Limit write rate (bytes per second) to a device (e.g. --device-write-bps=/dev/sda:1mb) +@@option device-read-iops -This option is not supported on cgroups V1 rootless systems. +@@option device-write-bps -#### **--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 @@ -230,25 +212,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 @@ -325,60 +289,17 @@ This option is currently supported only by the **journald** log driver. @@option mac-address -#### **--memory**, **-m**=*limit* +@@option memory -Memory limit (format: `<number>[<unit>]`, where unit = b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes)) +@@option memory-reservation -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. - -This option is not supported on cgroups V1 rootless systems. - -#### **--memory-swap**=*limit* - -A limit value equal to memory plus swap. Must be used with the **-m** -(**--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** @@ -518,21 +439,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** @@ -604,13 +511,9 @@ 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* +@@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**=*SYSCTL* @@ -670,48 +573,7 @@ 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 diff --git a/docs/source/markdown/podman-kill.1.md.in b/docs/source/markdown/podman-kill.1.md.in index 2788cc694..46d7f5c6b 100644 --- a/docs/source/markdown/podman-kill.1.md.in +++ b/docs/source/markdown/podman-kill.1.md.in @@ -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-play.1.md.in b/docs/source/markdown/podman-kube-play.1.md.in index f0b404057..bcd5687ca 100644 --- a/docs/source/markdown/podman-kube-play.1.md.in +++ b/docs/source/markdown/podman-kube-play.1.md.in @@ -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-machine-init.1.md b/docs/source/markdown/podman-machine-init.1.md index 07273a111..cf2eeca0b 100644 --- a/docs/source/markdown/podman-machine-init.1.md +++ b/docs/source/markdown/podman-machine-init.1.md @@ -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-pod-clone.1.md.in b/docs/source/markdown/podman-pod-clone.1.md.in index c040f1c27..24edc44ec 100644 --- a/docs/source/markdown/podman-pod-clone.1.md.in +++ b/docs/source/markdown/podman-pod-clone.1.md.in @@ -48,13 +48,9 @@ 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 @@ -146,13 +142,9 @@ 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* diff --git a/docs/source/markdown/podman-pod-create.1.md.in b/docs/source/markdown/podman-pod-create.1.md.in index 702780c65..35d06fa00 100644 --- a/docs/source/markdown/podman-pod-create.1.md.in +++ b/docs/source/markdown/podman-pod-create.1.md.in @@ -65,13 +65,9 @@ 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* @@ -287,14 +283,9 @@ 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* diff --git a/docs/source/markdown/podman-pod-kill.1.md b/docs/source/markdown/podman-pod-kill.1.md.in index 96ced68a7..7f37661b0 100644 --- a/docs/source/markdown/podman-pod-kill.1.md +++ b/docs/source/markdown/podman-pod-kill.1.md.in @@ -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-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index 6798c65da..64affa238 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -180,29 +180,13 @@ device. The devices that Podman will load modules when necessary are: @@option device-cgroup-rule -#### **--device-read-bps**=*path:rate* +@@option device-read-bps -Limit read rate (in bytes per second) from a device (e.g. **--device-read-bps=/dev/sda:1mb**). +@@option device-read-iops -This option is not supported on cgroups V1 rootless systems. +@@option device-write-bps -#### **--device-read-iops**=*path:rate* - -Limit read rate (in IO operations per second) from a device (e.g. **--device-read-iops=/dev/sda:1000**). - -This option is not supported on cgroups V1 rootless systems. - -#### **--device-write-bps**=*path:rate* - -Limit write rate (in bytes per second) to a device (e.g. **--device-write-bps=/dev/sda:1mb**). - -This option is not supported on cgroups V1 rootless systems. - -#### **--device-write-iops**=*path:rate* - -Limit write rate (in IO operations per second) to a device (e.g. **--device-write-iops=/dev/sda:1000**). - -This option is not supported on cgroups V1 rootless systems. +@@option device-write-iops @@option disable-content-trust @@ -264,20 +248,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 @@ -348,52 +319,15 @@ 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). +@@option memory-reservation -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). - -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. +@@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** @@ -544,21 +478,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** @@ -641,17 +561,9 @@ Sets whether the signals sent to the **podman run** command are proxied to the c @@option stop-timeout -#### **--subgidname**=*name* +@@option subgidname -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**. +@@option subuidname #### **--sysctl**=*name=value* @@ -721,49 +633,7 @@ 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 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..2928379f3 --- /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.1.md b/docs/source/markdown/podman.1.md index d1192b6d2..8c3af2561 100644 --- a/docs/source/markdown/podman.1.md +++ b/docs/source/markdown/podman.1.md @@ -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. | |