459 lines
19 KiB
Groff
459 lines
19 KiB
Groff
'\" t
|
|
.nh
|
|
.TH podman-update 1
|
|
.SH NAME
|
|
podman-update \- Update the configuration of a given container
|
|
|
|
.SH SYNOPSIS
|
|
\fBpodman update\fP [\fIoptions\fP] \fIcontainer\fP
|
|
|
|
.PP
|
|
\fBpodman container update\fP [\fIoptions\fP] \fIcontainer\fP
|
|
|
|
.SH DESCRIPTION
|
|
Updates the configuration of an existing container, allowing changes to resource limits and healthchecks.
|
|
|
|
.SH OPTIONS
|
|
.SS \fB--blkio-weight\fP=\fIweight\fP
|
|
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
|
|
Block IO relative device weight.
|
|
|
|
.SS \fB--cpu-period\fP=\fIlimit\fP
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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--env\fP, \fB-e\fP=\fIenv\fP
|
|
Add a value (e.g. env=\fIvalue\fP) to the container. Can be used multiple times.
|
|
If the value already exists in the container, it is overridden.
|
|
To remove an environment variable from the container, use the \fB--unsetenv\fR
|
|
option.
|
|
|
|
.PP
|
|
Note that the env updates only affect the main container process after
|
|
the next start.
|
|
|
|
.SS \fB--health-cmd\fP=\fI"command"\fP | \fI\&'["command", "arg1", ...]'\fP
|
|
Set or alter a healthcheck command for a container. The command is a command to be executed inside the
|
|
container that determines the container health. The command is required for other healthcheck options
|
|
to be applied. A value of \fBnone\fP disables existing healthchecks.
|
|
|
|
.PP
|
|
Multiple options can be passed in the form of a JSON array; otherwise, the command is interpreted
|
|
as an argument to \fB/bin/sh -c\fP\&.
|
|
|
|
.PP
|
|
Note: The default values are used even if healthcheck is configured in the image.
|
|
|
|
.SS \fB--health-interval\fP=\fIinterval\fP
|
|
Set an interval for the healthchecks. An \fIinterval\fP of \fBdisable\fP results in no automatic timer setup. The default is \fB30s\fP\&.
|
|
|
|
.PP
|
|
Note: This parameter will overwrite related healthcheck configuration from the image.
|
|
|
|
.PP
|
|
Changing this setting resets the timer.
|
|
|
|
.SS \fB--health-log-destination\fP=\fIdirectory_path\fP
|
|
Set the destination of the HealthCheck log. Directory path, local or events_logger (local use container state file) (Default: local)
|
|
.IP \(bu 2
|
|
\fBlocal\fR: (default) HealthCheck logs are stored in overlay containers. (For example: \fB$runroot/healthcheck.log\fR)
|
|
.IP \(bu 2
|
|
\fBdirectory\fR: creates a log file named \fB<container-ID>-healthcheck.log\fR with HealthCheck logs in the specified directory.
|
|
.IP \(bu 2
|
|
\fBevents_logger\fR: The log will be written with logging mechanism set by events_logger. It also saves the log to a default directory, for performance on a system with a large number of logs.
|
|
|
|
.PP
|
|
Warning: Changing this setting may cause the loss of previous logs.
|
|
|
|
.SS \fB--health-max-log-count\fP=\fInumber of stored logs\fP
|
|
Set maximum number of attempts in the HealthCheck log file. ('0' value means an infinite number of attempts in the log file) (Default: 5 attempts)
|
|
|
|
.SS \fB--health-max-log-size\fP=\fIsize of stored logs\fP
|
|
Set maximum length in characters of stored HealthCheck log. ("0" value means an infinite log length) (Default: 500 characters)
|
|
|
|
.SS \fB--health-on-failure\fP=\fIaction\fP
|
|
Action to take once the container transitions to an unhealthy state. The default is \fBnone\fP\&.
|
|
.IP \(bu 2
|
|
\fBnone\fP: Take no action.
|
|
.IP \(bu 2
|
|
\fBkill\fP: Kill the container.
|
|
.IP \(bu 2
|
|
\fBrestart\fP: Restart the container. Do not combine the \fBrestart\fR action with the \fB--restart\fR flag. When running inside of a systemd unit, consider using the \fBkill\fR or \fBstop\fR action instead to make use of systemd's restart policy.
|
|
.IP \(bu 2
|
|
\fBstop\fP: Stop the container.
|
|
|
|
.SS \fB--health-retries\fP=\fIretries\fP
|
|
The number of retries allowed before a healthcheck is considered to be unhealthy. The default value is \fB3\fP\&.
|
|
|
|
.PP
|
|
Note: This parameter can overwrite the healthcheck configuration from the image.
|
|
|
|
.SS \fB--health-start-period\fP=\fIperiod\fP
|
|
The initialization time needed for a container to bootstrap. The value can be expressed in time format like
|
|
\fB2m3s\fP\&. The default value is \fB0s\fP\&.
|
|
|
|
.PP
|
|
Note: The health check command is executed as soon as a container is started, if the health check is successful
|
|
the container's health state will be updated to \fBhealthy\fR\&. However, if the health check fails, the health state will
|
|
stay as \fBstarting\fR until either the health check is successful or until the \fB--health-start-period\fR time is over. If the
|
|
health check command fails after the \fB--health-start-period\fR time is over, the health state will be updated to \fBunhealthy\fR\&.
|
|
The health check command is executed periodically based on the value of \fB--health-interval\fR\&.
|
|
|
|
.PP
|
|
Note: This parameter will overwrite related healthcheck configuration from the image.
|
|
|
|
.SS \fB--health-startup-cmd\fP=\fI"command"\fP | \fI\&'["command", "arg1", ...]'\fP
|
|
Set a startup healthcheck command for a container. This command is executed inside the container and is used to gate the regular
|
|
healthcheck. When the startup command succeeds, the regular healthcheck begins and the startup healthcheck ceases. Optionally,
|
|
if the command fails for a set number of attempts, the container is restarted. A startup healthcheck can be used to ensure that
|
|
containers with an extended startup period are not marked as unhealthy until they are fully started. Startup healthchecks can only be
|
|
used when a regular healthcheck (from the container's image or the \fB--health-cmd\fP option) is also set.
|
|
|
|
.SS \fB--health-startup-interval\fP=\fIinterval\fP
|
|
Set an interval for the startup healthcheck. An \fIinterval\fP of \fBdisable\fP results in no automatic timer setup. The default is \fB30s\fP\&.
|
|
|
|
.PP
|
|
Changing this setting resets the timer, depending on the state of the container.
|
|
|
|
.SS \fB--health-startup-retries\fP=\fIretries\fP
|
|
The number of attempts allowed before the startup healthcheck restarts the container. If set to \fB0\fP, the container is never restarted. The default is \fB0\fP\&.
|
|
|
|
.SS \fB--health-startup-success\fP=\fIretries\fP
|
|
The number of successful runs required before the startup healthcheck succeeds and the regular healthcheck begins. A value
|
|
of \fB0\fP means that any success begins the regular healthcheck. The default is \fB0\fP\&.
|
|
|
|
.SS \fB--health-startup-timeout\fP=\fItimeout\fP
|
|
The maximum time a startup healthcheck command has to complete before it is marked as failed. The value can be expressed in a time
|
|
format like \fB2m3s\fP\&. The default value is \fB30s\fP\&.
|
|
|
|
.SS \fB--health-timeout\fP=\fItimeout\fP
|
|
The maximum time allowed to complete the healthcheck before an interval is considered failed. Like start-period, the
|
|
value can be expressed in a time format such as \fB1m22s\fP\&. The default value is \fB30s\fP\&.
|
|
|
|
.PP
|
|
Note: A timeout marks the healthcheck as failed. If the healthcheck command itself runs longer than the specified \fItimeout\fP,
|
|
it will be sent a \fBSIGKILL\fR signal.
|
|
|
|
.PP
|
|
Note: This parameter will overwrite related healthcheck configuration from the image.
|
|
|
|
.SS \fB--latest\fP, \fB-l\fP
|
|
Instead of providing the container name or ID, use the last created container.
|
|
Note: the last started container can be from other users of Podman on the host machine.
|
|
(This option is not available with the remote Podman client, including Mac and Windows
|
|
(excluding WSL2) machines)
|
|
|
|
.SS \fB--memory\fP, \fB-m\fP=\fInumber[unit]\fP
|
|
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
|
|
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
|
|
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
|
|
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--no-healthcheck\fP
|
|
Disable any defined healthchecks for container.
|
|
|
|
.SS \fB--pids-limit\fP=\fIlimit\fP
|
|
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
|
|
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:
|
|
.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
|
|
|
|
.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).
|
|
|
|
.SS \fB--unsetenv\fP=\fIenv\fP
|
|
Unset environment variables from the container.
|
|
|
|
.PP
|
|
Note that the env updates only affect the main container process after
|
|
the next start.
|
|
|
|
.SH EXAMPLES
|
|
Update a container with a new cpu quota and period:
|
|
|
|
.EX
|
|
podman update --cpus=0.5 ctrID
|
|
.EE
|
|
|
|
.PP
|
|
Update the latest container with a new cpu value:
|
|
|
|
.EX
|
|
podman update --latest --cpus=1
|
|
.EE
|
|
|
|
.PP
|
|
Update a container with multiple options at ones:
|
|
|
|
.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/sda:123 --blkio-weight 123 \\
|
|
--device-read-bps /dev/sda:10mb --device-write-bps /dev/sda:10mb \\
|
|
--device-read-iops /dev/sda:1000 --device-write-iops /dev/sda:1000 \\
|
|
--pids-limit 123 ctrID
|
|
.EE
|
|
|
|
.SH SEE ALSO
|
|
\fBpodman(1)\fP, \fBpodman-create(1)\fP, \fBpodman-run(1)\fP
|
|
|
|
.SH HISTORY
|
|
June 2025, Latest option added by Hayato Kihara kai.21banana@gmail.com
|
|
\[la]mailto:kai.21banana@gmail.com\[ra]
|
|
August 2022, Originally written by Charlie Doern cdoern@redhat.com
|
|
\[la]mailto:cdoern@redhat.com\[ra]
|