'\" t
.nh
.TH podman-update 1
.SH NAME
.PP
podman-update - Update the configuration of a given container

.SH SYNOPSIS
.PP
\fBpodman update\fP [\fIoptions\fP] \fIcontainer\fP

.PP
\fBpodman container update\fP [\fIoptions\fP] \fIcontainer\fP

.SH DESCRIPTION
.PP
Updates the configuration of an already existing container, allowing different resource limits to be set.
The currently supported options are a subset of the podman create/run resource limit options.

.SH OPTIONS
.SS \fB--blkio-weight\fP=\fIweight\fP
.PP
Block IO relative weight. The \fIweight\fP is a value between \fB10\fP and \fB1000\fP\&.

.PP
This option is not supported on cgroups V1 rootless systems.

.SS \fB--blkio-weight-device\fP=\fIdevice:weight\fP
.PP
Block IO relative device weight.

.SS \fB--cpu-period\fP=\fIlimit\fP
.PP
Set the CPU period for the Completely Fair Scheduler (CFS), which is a
duration in microseconds. Once the container's CPU quota is used up, it will not
be scheduled to run until the current period ends. Defaults to 100000
microseconds.

.PP
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

.PP
This option is not supported on cgroups V1 rootless systems.

.SS \fB--cpu-quota\fP=\fIlimit\fP
.PP
Limit the CPU Completely Fair Scheduler (CFS) quota.

.PP
Limit the container's CPU usage. By default, containers run with the full
CPU resource. The limit is a number in microseconds. If a number is provided,
the container is allowed to use that much CPU time until the CPU period
ends (controllable via \fB--cpu-period\fP).

.PP
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

.PP
This option is not supported on cgroups V1 rootless systems.

.SS \fB--cpu-rt-period\fP=\fImicroseconds\fP
.PP
Limit the CPU real-time period in microseconds.

.PP
Limit the container's Real Time CPU usage. This option tells the kernel to restrict the container's Real Time CPU usage to the period specified.

.PP
This option is only supported on cgroups V1 rootful systems.

.SS \fB--cpu-rt-runtime\fP=\fImicroseconds\fP
.PP
Limit the CPU real-time runtime in microseconds.

.PP
Limit the containers Real Time CPU usage. This option tells the kernel to limit the amount of time in a given CPU period Real Time tasks may consume. Ex:
Period of 1,000,000us and Runtime of 950,000us means that this container can consume 95% of available CPU and leave the remaining 5% to normal priority tasks.

.PP
The sum of all runtimes across containers cannot exceed the amount allotted to the parent cgroup.

.PP
This option is only supported on cgroups V1 rootful systems.

.SS \fB--cpu-shares\fP, \fB-c\fP=\fIshares\fP
.PP
CPU shares (relative weight).

.PP
By default, all containers get the same proportion of CPU cycles. This
proportion can be modified by changing the container's CPU share weighting
relative to the combined weight of all the running containers.
Default weight is \fB1024\fP\&.

.PP
The proportion only applies when CPU-intensive processes are running.
When tasks in one container are idle, other containers can use the
left-over CPU time. The actual amount of CPU time varies depending on
the number of containers running on the system.

.PP
For example, consider three containers, one has a cpu-share of 1024 and
two others have a cpu-share setting of 512. When processes in all three
containers attempt to use 100% of CPU, the first container receives
50% of the total CPU time. If a fourth container is added with a cpu-share
of 1024, the first container only gets 33% of the CPU. The remaining containers
receive 16.5%, 16.5% and 33% of the CPU.

.PP
On a multi-core system, the shares of CPU time are distributed over all CPU
cores. Even if a container is limited to less than 100% of CPU time, it can
use 100% of each individual CPU core.

.PP
For example, consider a system with more than three cores.
If the container \fIC0\fP is started with \fB--cpu-shares=512\fP running one process,
and another container \fIC1\fP with \fB--cpu-shares=1024\fP running two processes,
this can result in the following division of CPU shares:

.TS
allbox;
l l l l 
l l l l .
\fBPID\fP	\fBcontainer\fP	\fBCPU\fP	\fBCPU share\fP
100	C0	0	100% of CPU0
101	C1	1	100% of CPU1
102	C1	2	100% of CPU2
.TE

.PP
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

.PP
This option is not supported on cgroups V1 rootless systems.

.SS \fB--cpus\fP=\fInumber\fP
.PP
Number of CPUs. The default is \fI0.0\fP which means no limit. This is shorthand
for \fB--cpu-period\fP and \fB--cpu-quota\fP, therefore the option cannot be specified with
\fB--cpu-period\fP or \fB--cpu-quota\fP\&.

.PP
On some systems, changing the CPU limits may not be allowed for non-root
users. For more details, see
https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error

.PP
This option is not supported on cgroups V1 rootless systems.

.SS \fB--cpuset-cpus\fP=\fInumber\fP
.PP
CPUs in which to allow execution. Can be specified as a comma-separated list
(e.g. \fB0,1\fP), as a range (e.g. \fB0-3\fP), or any combination thereof
(e.g. \fB0-3,7,11-15\fP).

.PP
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

.PP
This option is not supported on cgroups V1 rootless systems.

.SS \fB--cpuset-mems\fP=\fInodes\fP
.PP
Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on
NUMA systems.

.PP
If there are four memory nodes on the system (0-3), use \fB--cpuset-mems=0,1\fP
then processes in the container only uses memory from the first
two memory nodes.

.PP
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

.PP
This option is not supported on cgroups V1 rootless systems.

.SS \fB--device-read-bps\fP=\fIpath:rate\fP
.PP
Limit read rate (in bytes per second) from a device (e.g. \fB--device-read-bps=/dev/sda:1mb\fP).

.PP
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

.PP
This option is not supported on cgroups V1 rootless systems.

.SS \fB--device-read-iops\fP=\fIpath:rate\fP
.PP
Limit read rate (in IO operations per second) from a device (e.g. \fB--device-read-iops=/dev/sda:1000\fP).

.PP
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

.PP
This option is not supported on cgroups V1 rootless systems.

.SS \fB--device-write-bps\fP=\fIpath:rate\fP
.PP
Limit write rate (in bytes per second) to a device (e.g. \fB--device-write-bps=/dev/sda:1mb\fP).

.PP
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

.PP
This option is not supported on cgroups V1 rootless systems.

.SS \fB--device-write-iops\fP=\fIpath:rate\fP
.PP
Limit write rate (in IO operations per second) to a device (e.g. \fB--device-write-iops=/dev/sda:1000\fP).

.PP
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

.PP
This option is not supported on cgroups V1 rootless systems.

.SS \fB--memory\fP, \fB-m\fP=\fInumber[unit]\fP
.PP
Memory limit. A \fIunit\fP can be \fBb\fP (bytes), \fBk\fP (kibibytes), \fBm\fP (mebibytes), or \fBg\fP (gibibytes).

.PP
Allows the memory available to a container to be constrained. If the host
supports swap memory, then the \fB-m\fP memory setting can be larger than physical
RAM. If a limit of 0 is specified (not using \fB-m\fP), 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 is very large, that's millions of trillions).

.PP
This option is not supported on cgroups V1 rootless systems.

.SS \fB--memory-reservation\fP=\fInumber[unit]\fP
.PP
Memory soft limit. A \fIunit\fP can be \fBb\fP (bytes), \fBk\fP (kibibytes), \fBm\fP (mebibytes), or \fBg\fP (gibibytes).

.PP
After setting memory reservation, when the system detects memory contention
or low memory, containers are forced to restrict their consumption to their
reservation. So always set the value below \fB--memory\fP, otherwise the
hard limit takes precedence. By default, memory reservation is the same
as memory limit.

.PP
This option is not supported on cgroups V1 rootless systems.

.SS \fB--memory-swap\fP=\fInumber[unit]\fP
.PP
A limit value equal to memory plus swap.
A \fIunit\fP can be \fBb\fP (bytes), \fBk\fP (kibibytes), \fBm\fP (mebibytes), or \fBg\fP (gibibytes).

.PP
Must be used with the \fB-m\fP (\fB--memory\fP) flag.
The argument value must be larger than that of
 \fB-m\fP (\fB--memory\fP) By default, it is set to double
the value of \fB--memory\fP\&.

.PP
Set \fInumber\fP to \fB-1\fP to enable unlimited swap.

.PP
This option is not supported on cgroups V1 rootless systems.

.SS \fB--memory-swappiness\fP=\fInumber\fP
.PP
Tune a container's memory swappiness behavior. Accepts an integer between \fI0\fP and \fI100\fP\&.

.PP
This flag is only supported on cgroups V1 rootful systems.

.SS \fB--pids-limit\fP=\fIlimit\fP
.PP
Tune the container's pids limit. Set to \fB-1\fP to have unlimited pids for the container. The default is \fB2048\fP on systems that support "pids" cgroup controller.

.SS \fB--restart\fP=\fIpolicy\fP
.PP
Restart policy to follow when containers exit.
Restart policy does not take effect if a container is stopped via the \fBpodman kill\fP or \fBpodman stop\fP commands.

.PP
Valid \fIpolicy\fP values are:

.RS
.IP \(bu 2
\fBno\fR                       : Do not restart containers on exit
.IP \(bu 2
\fBnever\fR                    : Synonym for \fBno\fP; do not restart containers on exit
.IP \(bu 2
\fBon-failure[:max_retries]\fR : Restart containers when they exit with a non-zero exit code, retrying indefinitely or until the optional \fImax_retries\fP count is hit
.IP \(bu 2
\fBalways\fR                   : Restart containers when they exit, regardless of status, retrying indefinitely
.IP \(bu 2
\fBunless-stopped\fR           : Identical to \fBalways\fP

.RE

.PP
Podman provides a systemd unit file, podman-restart.service, which restarts containers after a system reboot.

.PP
When running containers in systemd services, use the restart functionality provided by systemd.
In other words, do not use this option in a container unit, instead set the \fBRestart=\fR systemd directive in the \fB[Service]\fR section.
See \fBpodman-systemd.unit\fP(5) and \fBsystemd.service\fP(5).

.SH EXAMPLEs
.PP
Update a container with a new cpu quota and period.

.EX
podman update --cpus=5 myCtr
.EE

.PP
Update a container with all available options for cgroups v2.

.EX
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 --pids-limit 123 ctrID
.EE

.PP
Update a container with all available options for cgroups v1.

.EX
podman update --cpus 5 --cpuset-cpus 0 --cpu-shares 123 --cpuset-mems 0 --memory 1G --memory-swap 2G --memory-reservation 2G --memory-swappiness 50 --pids-limit 123 ctrID
.EE

.SH SEE ALSO
.PP
\fBpodman(1)\fP, \fBpodman-create(1)\fP, \fBpodman-run(1)\fP

.SH HISTORY
.PP
August 2022, Originally written by Charlie Doern cdoern@redhat.com
\[la]mailto:cdoern@redhat.com\[ra]