名称

podman-create - 创建一个新的容器

概要

podman create [选项] 镜像 [命令 [参数 …]]

podman container create [选项] 镜像 [命令 [参数 …]]

描述

在指定的镜像上创建一个可写容器层，并准备运行指定的命令。 然后容器 ID 会被打印到标准输出。 这类似于 podman run -d，只是容器从未启动。 使用 podman start 容器 命令可以在任何时候启动容器。

使用 podman create 创建的容器的初始状态为“创建”。

标志的默认设置定义在 containers.conf 中。 除非在手册页中说明，否则大多数远程连接设置都使用服务器的 containers.conf。

镜像

镜像使用传输：路径格式指定。 如果未指定传输，则默认使用 docker (容器注册表) 传输。 对于远程 Podman，包括 Mac 和 Windows (不包括 WSL2) 机器，docker 是唯一允许的传输。

dir:路径 存储清单、层 tarball 和签名作为单独文件的现有本地目录 路径。 这是一个非标准格式，主要用于调试或非侵入性容器检查。

$ podman save --format docker-dir fedora -o /tmp/fedora
$ podman create dir:/tmp/fedora echo hello

docker://docker-引用 (默认) 存储在远程容器镜像注册表中的镜像引用。 示例：“quay.io/podman/stable:latest”。 引用可以包括指向特定注册表的路径； 如果没有，则会查询 registries.conf 中列出的注册表以查找匹配的镜像。 默认情况下，来自 podman login 的凭据（默认存储在 $XDG_RUNTIME_DIR/containers/auth.json 中）用于身份验证； 否则将回退使用 $HOME/.docker/config.json 中的凭据。

$ podman create registry.fedoraproject.org/fedora:latest echo hello

docker-archive:路径[:docker-引用] 以 docker save 格式存储的镜像文件。 docker-引用 仅在创建此类文件时使用，并且不能包含摘要。

$ podman save --format docker-archive fedora -o /tmp/fedora
$ podman create docker-archive:/tmp/fedora echo hello

docker-daemon:docker-引用 以 docker-引用 格式存储在 docker 守护进程内部存储中的镜像。 docker-引用 也可以是镜像 ID (docker-daemon:算法:摘要)。

$ sudo docker pull fedora
$ sudo podman create docker-daemon:docker.io/library/fedora echo hello

oci-archive:路径:标签 符合“开放容器镜像布局规范”的目录中的镜像，位于指定的 路径 并使用 标签 指定。

$ podman save --format oci-archive fedora -o /tmp/fedora
$ podman create oci-archive:/tmp/fedora echo hello

选项

--add-host=主机名[;主机名[;…]]:ip

将自定义主机到 IP 映射添加到容器的 /etc/hosts 文件中。

该选项接受一个或多个用分号分隔的主机名，这些主机名将映射到单个 IPv4 或 IPv6 地址，地址之间用冒号分隔。 它也可以用于覆盖 Podman 默认添加到 /etc/hosts 的主机名的 IP 地址（另请参见 --name 和 --hostname 选项）。 该选项可以多次指定，以向 /etc/hosts 添加额外的映射。 它与 --no-hosts 选项冲突，并且与 containers.conf 中的 no_hosts=true 冲突。

除了 IP 地址之外，还可以使用特殊标志 host-gateway。 这会解析到容器可用于连接到主机的 IP 地址。 所选的 IP 地址取决于您的网络设置，因此不能保证 Podman 可以自动确定 host-gateway 地址，这将导致 Podman 失败并显示错误消息。 您可以使用 containers.conf 中的 host_containers_internal_ip 选项覆盖此 IP 地址。

host-gateway 地址也被 Podman 用于自动将 host.containers.internal 和 host.docker.internal 主机名添加到 /etc/hosts。 您可以通过以下任一方式阻止这种情况：给出 --no-hosts 选项，或在 containers.conf 中设置 host_containers_internal_ip=”none”。 如果未手动配置 host-gateway 地址，并且 Podman 无法自动确定 IP 地址，则 Podman 将静默跳过将这些内部主机名添加到 /etc/hosts。 如果 Podman 在使用 podman machine 的虚拟机中运行（包括 Mac 和 Windows 主机），则 Podman 将静默跳过将内部主机名添加到 /etc/hosts，除非手动配置了 IP 地址； 内部主机名将由 gvproxy DNS 解析器解析。

Podman 默认情况下会使用主机的 /etc/hosts 文件作为基础，即此文件中存在的任何主机名也会存在于容器的 /etc/hosts 文件中。 可以使用 containers.conf 中的 base_hosts_file 配置使用不同的基础文件。

--annotation=键=值

向容器添加注释。 此选项可以多次设置。

--arch=架构

覆盖要拉取镜像的架构，默认为主机。 例如，arm。 除非覆盖，否则本地存储中对相同镜像的后续查找将匹配此架构，而与主机无关。

--attach, -a=stdin | stdout | stderr

附加到 STDIN、STDOUT 或 STDERR。

在前景模式下（当未指定 -d 时为默认值），podman run 可以启动容器中的进程并将控制台附加到进程的标准输入、输出和错误。 它甚至可以假装是 TTY（这是大多数命令行可执行文件所期望的），并将信号传递过去。 -a 选项可以为 stdin、stdout 和 stderr 中的每一个设置。

--authfile=路径

身份验证文件的路径。 默认情况下为 Linux 上的 ${XDG_RUNTIME_DIR}/containers/auth.json，以及 Windows/macOS 上的 $HOME/.config/containers/auth.json。 该文件由 podman login 创建。 如果在那里找不到授权状态，则会检查 $HOME/.docker/config.json，该状态使用 docker login 设置。

注意：还可以通过设置 REGISTRY_AUTH_FILE 环境变量来覆盖身份验证文件的默认路径。 这可以使用 export REGISTRY_AUTH_FILE=路径 来完成。

--blkio-weight=权重

块 IO 相对权重。 权重 是一个介于 10 和 1000 之间的数值。

此选项在 cgroups V1 无根系统上不受支持。

--blkio-weight-device=设备:权重

块 IO 相对设备权重。

--cap-add=功能

添加 Linux 功能。

--cap-drop=功能

删除 Linux 功能。

--cgroup-conf=键=值

在 cgroup v2 上运行时，指定要写入的 cgroup 文件及其值。 例如 --cgroup-conf=memory.high=1073741824 将 memory.high 限制设置为 1GB。

--cgroup-parent=路径

容器 cgroup 创建所在 cgroup 的路径。 如果路径不是绝对路径，则该路径被认为相对于 init 进程的 cgroups 路径。 如果 cgroups 不存在，则会创建 cgroups。

--cgroupns=模式

设置容器的 cgroup 命名空间模式。

• host：在容器内部使用主机的 cgroup 命名空间。

• container:id：加入指定容器的命名空间。

• private：创建一个新的 cgroup 命名空间。

• ns:路径：加入指定路径的命名空间。

如果主机使用 cgroups v1，则默认设置为 host。 在 cgroups v2 上，默认设置为 private。

--cgroups=如何

确定容器是否创建 CGroups。

默认值为 enabled。

enabled 选项在 cgroup-parent 下创建一个新的 cgroup。 disabled 选项强制容器不创建 CGroups，因此与 CGroup 选项（--cgroupns 和 --cgroup-parent）冲突。 no-conmon 选项仅为 conmon 进程禁用新的 CGroup。 split 选项将当前 CGroup 分割为两个子 cgroup：一个用于 conmon，一个用于容器有效负载。 无法使用 split 设置 --cgroup-parent。

--chrootdirs=路径

容器内部目录的路径，该目录被视为 chroot 目录。 任何 Podman 管理的文件（例如，/etc/resolv.conf、/etc/hosts、etc/hostname）都将被挂载到根目录，也会被挂载到该位置。 多个目录用逗号分隔。

--cidfile=文件

将容器 ID 写入 文件。 该文件会随着容器一起删除，除非与 podman --remote run 一起使用，用于分离容器。

--conmon-pidfile=文件

将 **conmon** 进程的 pid 写入文件。由于 **conmon** 在与 Podman 不同的进程中运行，因此在使用 systemd 重启 Podman 容器时，这很有必要。（此选项在远程 Podman 客户端不可用，包括 Mac 和 Windows（不包括 WSL2）机器）

--cpu-period=limit

设置完全公平调度程序 (CFS) 的 CPU 周期，该周期以微秒为单位。一旦容器的 CPU 配额用完，它将不会被调度运行，直到当前周期结束。默认为 100000 微秒。

在某些系统上，可能不允许非 root 用户更改资源限制。有关更多详细信息，请参阅 https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error

此选项在 cgroups V1 无根系统上不受支持。

--cpu-quota=limit

限制 CPU 完全公平调度程序 (CFS) 配额。

限制容器的 CPU 使用率。默认情况下，容器使用完整的 CPU 资源。限制以微秒为单位的数字。如果提供了一个数字，则允许容器使用那么多 CPU 时间，直到 CPU 周期结束（可以通过 **--cpu-period** 控制）。

在某些系统上，可能不允许非 root 用户更改资源限制。有关更多详细信息，请参阅 https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error

此选项在 cgroups V1 无根系统上不受支持。

--cpu-rt-period=microseconds

以微秒为单位限制 CPU 实时周期。

限制容器的实时 CPU 使用率。此选项告诉内核将容器的实时 CPU 使用率限制为指定的周期。

此选项仅在 cgroups V1 根目录系统上受支持。

--cpu-rt-runtime=microseconds

以微秒为单位限制 CPU 实时运行时间。

限制容器的实时 CPU 使用率。此选项告诉内核限制给定 CPU 周期中实时任务可以消耗的时间量。例如：周期为 1,000,000us，运行时间为 950,000us，意味着该容器可以消耗 95% 的可用 CPU，并将剩余的 5% 留给正常优先级任务。

跨容器的所有运行时间的总和不能超过分配给父 cgroup 的数量。

此选项仅在 cgroups V1 根目录系统上受支持。

--cpu-shares, -c=shares

CPU 份额（相对权重）。

默认情况下，所有容器都获得相同比例的 CPU 周期。可以通过更改容器的 CPU 份额权重（相对于所有正在运行的容器的组合权重）来修改此比例。默认权重为 **1024**。

此比例仅在 CPU 密集型进程运行时适用。当一个容器中的任务处于空闲状态时，其他容器可以使用剩余的 CPU 时间。实际的 CPU 时间量会根据系统上运行的容器数量而有所不同。

例如，考虑三个容器，一个容器的 cpu-share 为 1024，另外两个容器的 cpu-share 设置为 512。当三个容器中的进程都尝试使用 100% 的 CPU 时，第一个容器将接收 50% 的总 CPU 时间。如果添加第四个容器，其 cpu-share 为 1024，则第一个容器只获得 33% 的 CPU。其余容器分别获得 16.5%、16.5% 和 33% 的 CPU。

在多核系统上，CPU 时间的份额将分布在所有 CPU 内核上。即使容器被限制为小于 100% 的 CPU 时间，它也可以使用每个单个 CPU 内核的 100%。

例如，考虑一个具有三个以上内核的系统。如果容器 C0 以 **--cpu-shares=512** 启动，运行一个进程，另一个容器 C1 以 **--cpu-shares=1024** 启动，运行两个进程，这可能导致以下 CPU 份额的分配：

PID	容器	CPU	CPU 份额
100	C0	0	CPU0 的 100%
101	C1	1	CPU1 的 100%
102	C1	2	CPU2 的 100%

在某些系统上，可能不允许非 root 用户更改资源限制。有关更多详细信息，请参阅 https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error

此选项在 cgroups V1 无根系统上不受支持。

--cpus=number

CPU 数量。默认值为 0.0，表示没有限制。这是 **--cpu-period** 和 **--cpu-quota** 的简写，因此该选项不能与 **--cpu-period** 或 **--cpu-quota** 一起指定。

在某些系统上，可能不允许非 root 用户更改 CPU 限制。有关更多详细信息，请参阅 https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error

此选项在 cgroups V1 无根系统上不受支持。

--cpuset-cpus=number

允许执行的 CPU。可以指定为逗号分隔列表（例如 **0,1**）、范围（例如 **0-3**）或它们的任意组合（例如 **0-3,7,11-15**）。

在某些系统上，可能不允许非 root 用户更改资源限制。有关更多详细信息，请参阅 https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error

此选项在 cgroups V1 无根系统上不受支持。

--cpuset-mems=nodes

允许执行的内存节点 (MEM) (0-3, 0,1)。仅在 NUMA 系统上有效。

如果系统上有四个内存节点 (0-3)，使用 **--cpuset-mems=0,1**，则容器中的进程只使用来自前两个内存节点的内存。

在某些系统上，可能不允许非 root 用户更改资源限制。有关更多详细信息，请参阅 https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error

此选项在 cgroups V1 无根系统上不受支持。

--decryption-key=key[:passphrase]

用于解密镜像的 [key[:passphrase]]。Key 可以指向密钥和/或证书。使用所有密钥尝试解密。如果密钥受密码保护，则需要在参数中传递密码，否则需要省略。

--device=host-device[:container-device][:permissions]

将主机设备添加到容器。可选的 permissions 参数可用于通过组合 **r**（读取）、**w**（写入）和 **m**（**mknod**(2)）来指定设备权限。

示例：**--device=/dev/sdc:/dev/xvdc:rwm**。

注意：如果 host-device 是符号链接，则会首先解析它。容器仅存储主机设备的主设备号和次设备号。

Podman 可能会加载使用指定设备所需的内核模块。Podman 在必要时加载模块的设备是：/dev/fuse。

在无根模式下，新设备从主机绑定挂载到容器，而不是 Podman 在容器空间内创建它。由于绑定挂载保留了 SELinux 系统上的 SELinux 标签，因此容器在访问挂载的设备时可能会获得权限被拒绝的错误。修改 SELinux 设置以允许容器通过以下命令使用所有设备标签：

$ sudo setsebool -P container_use_devices=true

注意：如果用户只通过组拥有访问权限，则从无根容器内部访问设备会失败。使用 --group-add keep-groups 标志将用户的辅助组访问权限传递到容器中。

--device-cgroup-rule=”type major:minor mode”

在 cgroup 允许的设备列表中添加一条规则。该规则应采用 Linux 内核文档中指定的格式 admin-guide/cgroup-v1/devices

• type: a (all)、c (char) 或 b (block)；

• major 和 minor: 数字或 * 表示所有；

• mode: r (read)、w (write) 和 m (mknod(2)) 的组合。

--device-read-bps=path:rate

限制从设备读取的速率（以每秒字节为单位）（例如 **--device-read-bps=/dev/sda:1mb**）。

在某些系统上，可能不允许非 root 用户更改资源限制。有关更多详细信息，请参阅 https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error

此选项在 cgroups V1 无根系统上不受支持。

--device-read-iops=path:rate

限制从设备读取的速率（以每秒 I/O 操作为单位）（例如 **--device-read-iops=/dev/sda:1000**）。

在某些系统上，可能不允许非 root 用户更改资源限制。有关更多详细信息，请参阅 https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error

此选项在 cgroups V1 无根系统上不受支持。

--device-write-bps=path:rate

限制写入设备的速率（以每秒字节为单位）（例如 **--device-write-bps=/dev/sda:1mb**）。

在某些系统上，可能不允许非 root 用户更改资源限制。有关更多详细信息，请参阅 https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error

此选项在 cgroups V1 无根系统上不受支持。

--device-write-iops=path:rate

限制写入设备的速率（以每秒 I/O 操作为单位）（例如 **--device-write-iops=/dev/sda:1000**）。

在某些系统上，可能不允许非 root 用户更改资源限制。有关更多详细信息，请参阅 https://github.com/containers/podman/blob/main/troubleshooting.md#26-running-containers-with-resource-limits-fails-with-a-permissions-error

此选项在 cgroups V1 无根系统上不受支持。

--disable-content-trust

这是一个 Docker 特定选项，用于禁用对容器注册表的镜像验证，Podman 不支持它。此选项是一个 NOOP，仅为了脚本兼容性而提供。

--dns=ipaddr

设置自定义 DNS 服务器。

此选项可用于覆盖传递给容器的 DNS 配置。通常，当主机 DNS 配置对容器无效时（例如，**127.0.0.1**），这很有必要。在这种情况下，每次运行都需要使用 **--dns** 标志。

可以指定特殊值 **none** 以禁用 Podman 在容器中创建 /etc/resolv.conf。镜像中的 /etc/resolv.conf 文件将被使用，不会进行更改。

此选项不能与 **--network** 结合使用，**--network** 设置为 **none** 或 **container:****id**。

--dns-option=option

设置自定义 DNS 选项。如果使用 **--dns-option** 以及 **--network** 设置为 **none** 或 **container:****id**，则无效。

--dns-search=domain

设置自定义 DNS 搜索域。如果使用 **--dns-search** 以及 **--network** 设置为 **none** 或 **container:****id**，则无效。使用 **--dns-search=.** 删除搜索域。

--entrypoint=”command” | ‘[“command”, “arg1”, …]’

覆盖镜像中的默认 ENTRYPOINT。

镜像的 ENTRYPOINT 与 COMMAND 类似，因为它指定了容器启动时要运行的可执行文件，但它（有意地）更难覆盖。ENTRYPOINT 为容器提供了其默认性质或行为。当设置 ENTRYPOINT 时，容器运行方式类似于该二进制文件，包含默认选项。可以通过 COMMAND 传递更多选项。但是，如果用户想要在容器中运行其他内容，则 **--entrypoint** 选项允许指定新的 ENTRYPOINT。

以 json 字符串的形式指定多选项命令。

--env, -e=env

设置环境变量。

此选项允许为在容器内启动的进程提供任意环境变量。如果指定的环境变量没有值，Podman 会检查主机环境以获取值，并且仅在主机上设置了该变量时才设置该变量。作为一个特殊情况，如果指定了一个以 **\*** 结尾的环境变量，并且没有值，Podman 会搜索主机环境以获取以该前缀开头的变量，并将这些变量添加到容器中。

有关优先级和示例，请参见下面的 环境 说明。

--env-file=file

读取一个以换行符分隔的环境变量文件。

有关优先级和示例，请参见下面的 环境 说明。

--env-host

在容器内部使用主机环境。有关优先级，请参见下面的环境说明。（此选项不适用于远程 Podman 客户端，包括 Mac 和 Windows（不包括 WSL2）机器）

--env-merge=env

预处理容器的默认环境变量。例如，如果映像包含环境变量 hello=world，用户可以使用 --env-merge hello=${hello}-some 对其进行预处理，以便新值为 hello=world-some。

请注意，如果映像中不存在环境变量 hello，则它将被替换为空字符串，因此使用 --env-merge hello=${hello}-some 将导致新值为 hello=-some，请注意前导 - 分隔符。

--expose=port[/protocol]

公开一个端口或一个端口范围（例如 --expose=3300-3310）。协议可以是 tcp、udp 或 sctp，如果未给出，则假定为 tcp。此选项与映像构建的 EXPOSE 指令匹配，并且对实际网络规则没有影响，除非使用 -P/--publish-all 将所有公开端口从随机主机端口转发。要将特定端口从主机转发到容器，请使用 -p/--publish 选项。

--gidmap=[flags]container_uid:from_uid[:amount]

使用提供的 GID 映射在新用户命名空间中运行容器。此选项与 --userns 和 --subgidname 选项冲突。此选项提供了一种将主机 GID 映射到容器 GID 的方法，就像 --uidmap 将主机 UID 映射到容器 UID 一样。有关详细信息，请参见 --uidmap。

注意：--gidmap 选项不能与 --pod 选项一起调用，因为在 pod 中时，gidmap 无法在容器级别设置。

--gpus=ENTRY

要添加到容器的 GPU 设备（“all” 表示传递所有 GPU）目前仅支持 Nvidia 设备。

--group-add=group | keep-groups

将附加组分配给在容器进程中运行的主用户。

• keep-groups 是一个特殊标志，它指示 Podman 保持辅助组访问权限。

允许容器使用用户的辅助组访问权限。如果文件系统或设备仅可由无根用户的组访问，则此标志指示 OCI 运行时将组访问权限传递到容器。目前仅适用于 crun OCI 运行时。注意：keep-groups 是排他的，其他组不能与此标志一起指定。（不适用于远程命令，包括 Mac 和 Windows（不包括 WSL2）机器）

--group-entry=ENTRY

自定义在使用 --user 时写入容器内的 /etc/group 文件的条目。

如果存在，变量 $GROUPNAME、$GID 和 $USERLIST 会在运行时自动替换为其值。

--health-cmd=”command” | ‘[“command”, “arg1”, …]’

设置或更改容器的健康检查命令。该命令是在容器内部执行的命令，用于确定容器的健康状况。该命令是应用其他健康检查选项的必要条件。值为 none 会禁用现有的健康检查。

可以在 JSON 数组的形式中传递多个选项；否则，该命令将被解释为 /bin/sh -c 的参数。

--health-interval=interval

设置健康检查的间隔。disable 的间隔会导致没有自动计时器设置。默认值为 30s。

--health-log-destination=directory_path

设置健康检查日志的目标。目录路径，本地或 events_logger（本地使用容器状态文件）（默认：本地）

• local： (默认) 健康检查日志存储在覆盖容器中。（例如：$runroot/healthcheck.log)

• directory： 在指定的目录中创建一个名为 <container-ID>-healthcheck.log 的日志文件，其中包含健康检查日志。

• events_logger： 该日志将使用 events_logger 设置的日志记录机制写入。它还将日志保存到默认目录，以提高具有大量日志的系统的性能。

--health-max-log-count=存储的日志数

设置健康检查日志文件中允许的尝试次数。（“0”值表示日志文件中允许无限次尝试）（默认：5 次尝试）

--health-max-log-size=存储的日志大小

设置存储的健康检查日志的最大长度（以字符为单位）。(“0”值表示无限日志长度）（默认：500 个字符）

--health-on-failure=action

容器过渡到不健康状态后要采取的操作。默认值为 none。

• none： 不采取任何操作。

• kill： 杀死容器。

• restart： 重新启动容器。不要将 restart 操作与 --restart 标志结合使用。在 systemd 单位内运行时，请考虑使用 kill 或 stop 操作，以利用 systemd 的重启策略。

• stop： 停止容器。

--health-retries=retries

在健康检查被认为是不健康之前允许的重试次数。默认值为 3。

--health-start-period=period

容器启动所需的初始化时间。该值可以用时间格式表示，例如 2m3s。默认值为 0s。

注意：健康检查命令将在容器启动后立即执行，如果健康检查成功，则容器的健康状态将更新为 healthy。但是，如果健康检查失败，则健康状态将保持为 starting，直到健康检查成功或 --health-start-period 时间结束。如果健康检查命令在 --health-start-period 时间结束之后失败，则健康状态将更新为 unhealthy。健康检查命令会根据 --health-interval 的值定期执行。

--health-startup-cmd=”command” | ‘[“command”, “arg1”, …]’

为容器设置启动健康检查命令。此命令在容器内部执行，用于控制常规健康检查。当启动命令成功时，常规健康检查将开始，而启动健康检查将停止。可选地，如果命令连续几次失败，则容器将重新启动。启动健康检查可用于确保具有扩展启动时间的容器在完全启动之前不被标记为不健康。只有在也设置了常规健康检查（来自容器的映像或 --health-cmd 选项）时，才能使用启动健康检查。

--health-startup-interval=interval

设置启动健康检查的间隔。disable 的间隔会导致没有自动计时器设置。默认值为 30s。

--health-startup-retries=retries

启动健康检查在重新启动容器之前允许的尝试次数。如果设置为 0，则容器永远不会重新启动。默认值为 0。

--health-startup-success=retries

启动健康检查成功之前所需的成功运行次数。值为 0 表示任何成功都将启动常规健康检查。默认值为 0。

--health-startup-timeout=timeout

启动健康检查命令在被标记为失败之前必须完成的最大时间。该值可以用时间格式表示，例如 2m3s。默认值为 30s。

--health-timeout=timeout

在间隔被认为失败之前允许完成健康检查的最大时间。与 start-period 一样，该值可以用时间格式表示，例如 1m22s。默认值为 30s。

--help

打印用法说明

--hostname, -h=name

在容器内设置容器的主机名。

此选项仅可与私有的 UTS 命名空间一起使用 --uts=private（默认）。如果 --pod 被指定且 pod 共享相同的 UTS 命名空间（默认），则使用 pod 的主机名。给定的主机名也会使用容器的主 IP 地址添加到 /etc/hosts 文件中（另请参见 --add-host 选项）。

--hostuser=name

从主机将用户帐户添加到容器中的 /etc/passwd。用户名或 UID 必须存在于主机系统上。

--http-proxy

默认情况下，如果为 Podman 进程设置了代理环境变量，则会将其传递到容器中。可以通过将值设置为 false 来禁用此功能。传递的环境变量包括 http_proxy、https_proxy、ftp_proxy、no_proxy，以及这些变量的大写版本。只有在主机系统必须使用代理而容器不使用任何代理时才需要此选项。以任何其他方式为容器指定代理环境变量会覆盖从主机传递的值。（为容器指定代理的其他方法包括使用 --env 标志传递值，或在容器构建时对代理环境进行硬编码。）当与远程客户端一起使用时，它会使用在服务器进程上设置的代理环境变量。

默认为 true。

--image-volume=bind | tmpfs | ignore

告诉 Podman 如何处理内置镜像卷。默认值为 bind。

• bind：将创建一个匿名命名卷并将其挂载到容器中。

• tmpfs：该卷被挂载到容器中作为 tmpfs，这允许用户创建在容器停止时消失的内容。

• ignore：所有卷都将被忽略，不采取任何操作。

--init

在容器内部运行一个 init，它转发信号并收集进程。container-init 二进制文件被挂载到 /run/podman-init。挂载到 /run 会破坏容器执行。

--init-ctr=type

（仅限 Pod）。当使用 pod 时，创建 init 样式的容器，它在基础设施容器启动后但常规 pod 容器启动之前运行。init 容器对于运行 pod 应用程序的设置操作很有用。

init-ctr 类型的有效值为 always 或 once。always 值表示容器在每次 pod start 时运行，而 once 值表示容器仅在 pod 启动时运行一次，然后容器被删除。

init 容器仅在 pod start 时运行。重启 pod 不会执行任何 init 容器。此外，只有在 pod 未运行时才能在 pod 中创建 init 容器。

--init-path=path

container-init 二进制文件路径。

--interactive, -i

当设置为 true 时，使 stdin 可用于容器化进程。如果为 false，则容器化进程的 stdin 为空并立即关闭。

如果已附加，则 stdin 将被管道传输到容器化进程。如果已分离，则读取 stdin 将阻塞，直到以后附加。

注意事项：Podman 将在 stdin 可用时立即从 stdin 消费输入，即使容器化进程没有请求它。

--ip=ipv4

为容器指定一个静态 IPv4 地址，例如 10.88.64.128。此选项仅可用于将容器加入到单个网络时，即 --network=network-name 最多使用一次，并且容器不通过 --network=container:id 加入另一个容器的网络命名空间。该地址必须位于网络的 IP 地址池中（默认值为 10.88.0.0/16）。

要为每个容器指定多个静态 IP 地址，请使用 --network 选项设置多个网络，并为每个网络使用 ip 模式指定一个静态 IP 地址。

--ip6=ipv6

为容器指定一个静态 IPv6 地址，例如 fd46:db93:aa76:ac37::10。此选项仅可用于将容器加入到单个网络时，即 --network=network-name 最多使用一次，并且容器不通过 --network=container:id 加入另一个容器的网络命名空间。该地址必须位于网络的 IPv6 地址池中。

要为每个容器指定多个静态 IPv6 地址，请使用 --network 选项设置多个网络，并为每个网络使用 ip6 模式指定一个静态 IPv6 地址。

--ipc=ipc

设置容器的 IPC 命名空间模式。默认情况下会创建一个私有 IPC 命名空间。

• “”: 使用 Podman 的默认值，在 containers.conf 中定义。

• container:id：重用另一个容器的共享内存、信号量和消息队列

• host：在容器内部使用主机的共享内存、信号量和消息队列。注意：主机模式允许容器完全访问本地共享内存，因此被认为是不安全的。

• none：私有 IPC 命名空间，不挂载 /dev/shm。

• ns:path：要加入的 IPC 命名空间的路径。

• private：私有 IPC 命名空间。

• shareable：私有 IPC 命名空间，可以与其他容器共享。

--label, -l=key=value

向容器添加元数据。

--label-file=file

读取以换行符分隔的标签文件。

--link-local-ip=ip

未实现。

--log-driver=driver

容器的日志驱动程序。当前可用的选项包括 k8s-file、journald、none、passthrough 和 passthrough-tty，其中 json-file 被别名为 k8s-file 以实现脚本兼容性。（默认值为 journald）。

下面的 podman info 命令显示系统默认的日志驱动程序。

$ podman info --format '{{ .Host.LogDriver }}'
journald

passthrough 驱动程序将标准流（stdin、stdout、stderr）传递给容器。它不允许使用远程 Podman 客户端，包括 Mac 和 Windows（不包括 WSL2）机器，以及 tty，因为它容易受到通过 TIOCSTI 的攻击。

passthrough-tty 驱动程序与 passthrough 相同，只是它也允许在 TTY 上使用，如果用户确实想要它。

--log-opt=name=value

日志驱动程序特定选项。

设置自定义日志配置。以下 name 被支持

path：指定日志文件路径（例如 --log-opt path=/var/log/container/mycontainer.json）；

max-size：指定日志文件的最大大小（例如 --log-opt max-size=10mb）；

tag：为容器指定一个自定义日志标签（例如 --log-opt tag=”{{.ImageName}}”。它支持与 podman inspect --format 相同的键。此选项目前仅被 journald 日志驱动程序支持。

--mac-address=address

容器网络接口 MAC 地址（例如 92:d0:c6:0a:29:33）此选项仅可用于将容器加入到单个网络时，即 --network=network-name 最多使用一次，并且容器不通过 --network=container:id 加入另一个容器的网络命名空间。

请记住，以太网网络中的 MAC 地址必须是唯一的。根据 RFC4862，IPv6 链接本地地址基于设备的 MAC 地址。

要为每个容器指定多个静态 MAC 地址，请使用 --network 选项设置多个网络，并为每个网络使用 mac 模式指定一个静态 MAC 地址。

--memory, -m=number[unit]

内存限制。unit 可以是 b（字节）、k（Kibibytes）、m（Mebibytes）或 g（Gibibytes）。

允许限制容器可用的内存。如果主机支持交换内存，则 -m 内存设置可以大于物理 RAM。如果指定了 0 的限制（不使用 -m），则容器的内存不受限制。实际限制可能会向上舍入到操作系统页面大小的倍数（该值非常大，即百万兆兆字节）。

此选项在 cgroups V1 无根系统上不受支持。

--memory-reservation=number[unit]

内存软限制。unit 可以是 b（字节）、k（Kibibytes）、m（Mebibytes）或 g（Gibibytes）。

设置内存预留后，当系统检测到内存竞争或内存不足时，容器将被强制限制其消耗至其预留量。因此，始终将该值设置为低于 **--memory**，否则硬限制将优先。默认情况下，内存预留与内存限制相同。

此选项在 cgroups V1 无根系统上不受支持。

**--memory-swap**=number[unit]

等于内存加交换空间的限制值。unit 可以是 **b**（字节）、**k**（Kibibytes）、**m**（Mebibytes）或 **g**（Gibibytes）。

必须与 **-m**（**--memory**）标志一起使用。参数值必须大于 **-m**（**--memory**）的值。默认情况下，它设置为 **--memory** 值的两倍。

将 number 设置为 **-1** 以启用无限交换空间。

此选项在 cgroups V1 无根系统上不受支持。

**--memory-swappiness**=number

调整容器的内存交换行为。接受介于 0 和 100 之间的整数。

此标志仅在 cgroups V1 根目录系统上支持。

**--mount**=type=TYPE,TYPE-SPECIFIC-OPTION[,…]

将文件系统挂载附加到容器

当前支持的挂载 TYPE 为 **bind**、**devpts**、**glob**、**image**、**ramfs**、**tmpfs** 和 **volume**。

所有挂载类型共有的选项

• src、source：bind、glob 和 volume 的挂载源规范。对于 **bind** 和 **glob** 来说是强制性的。

• dst、destination、target：挂载目标规范。

当源通配符在没有指定目标目录的情况下指定时，文件和目录将在容器内以其完整路径挂载。当指定目标时，与目标目录上的基本文件名匹配的通配符上的文件和目录将被挂载。选项 type=glob,src=/foo*,destination=/tmp/bar 告诉容器引擎将匹配 /foo* 的主机文件挂载到容器中的 /tmp/bar/ 目录。

特定于 type=volume 的选项

• ro、readonly：true 或 false（默认情况下，如果未指定：false）。

• U、chown：true 或 false（默认情况下，如果未指定：false）。基于容器的 UID 和 GID，递归地更改源卷的所有者和组。

• idmap：如果指定，则在容器中创建一个映射到目标用户命名空间的 id 映射挂载。idmap 选项支持与容器使用的用户命名空间不同的自定义映射。可以在 idmap 选项之后指定映射，例如：idmap=uids=0-1-10#10-11-10;gids=0-100-10。对于每个三元组，第一个值是映射到主机上的第二个值的备份文件系统 ID 的起始位置。此映射的长度在第三个值中给出。多个范围用 # 分隔。如果指定的映射以 ‘@’ 开头，则该映射被认为相对于容器用户命名空间。映射的主机 ID 会发生变化，以考虑容器用户在容器用户命名空间中的相对位置。

特定于 type=image 的选项

• rw、readwrite：true 或 false（默认情况下，如果未指定：false）。

• subpath：仅挂载映像内的特定路径，而不是整个映像。

特定于 bind 和 glob 的选项

• ro、readonly：true 或 false（默认情况下，如果未指定：false）。

• bind-propagation：shared、slave、private、unbindable、rshared、rslave、runbindable 或 rprivate（默认值）。^[1] 另请参阅 mount(2)。

• bind-nonrecursive：不设置递归绑定挂载。默认情况下它是递归的。

• relabel：shared、private。

• idmap：true 或 false（默认情况下，如果未指定：false）。如果为 true，则在容器中创建一个映射到目标用户命名空间的 id 映射挂载。

• U、chown：true 或 false（默认情况下，如果未指定：false）。基于容器的 UID 和 GID，递归地更改源卷的所有者和组。

• no-dereference：不取消对符号链接的引用，而是将链接源复制到挂载目标。

特定于 type=tmpfs 和 ramfs 的选项

• ro、readonly：true 或 false（默认情况下，如果未指定：false）。

• tmpfs-size：tmpfs/ramfs 挂载的大小，以字节为单位。在 Linux 中默认情况下无限制。

• tmpfs-mode：tmpfs/ramfs 的八进制文件模式（例如 700 或 0700）。

• tmpcopyup：启用从图像目录中相同位置到 tmpfs/ramfs 的复制。默认情况下使用。

• notmpcopyup：禁用将文件从映像复制到 tmpfs/ramfs。

• U、chown：true 或 false（默认情况下，如果未指定：false）。基于容器的 UID 和 GID，递归地更改源卷的所有者和组。

特定于 type=devpts 的选项

• uid：文件所有者的数字 UID（默认值：0）。

• gid：文件所有者的数字 GID（默认值：0）。

• mode：文件的八进制权限掩码（默认值：600）。

• max：PTY 的最大数量（默认值：1048576）。

示例

• type=bind,source=/path/on/host,destination=/path/in/container

• type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared

• type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared,U=true

• type=devpts,destination=/dev/pts

• type=glob,src=/usr/lib/libfoo*,destination=/usr/lib,ro=true

• type=image,source=fedora,destination=/fedora-image,rw=true

• type=ramfs,tmpfs-size=512M,destination=/path/in/container

• type=tmpfs,tmpfs-size=512M,destination=/path/in/container

• type=tmpfs,destination=/path/in/container,noswap

• type=volume,source=vol1,destination=/path/in/container,ro=true

**--name**=name

为容器分配一个名称。

操作员可以通过三种方式识别容器

• UUID 长标识符（“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”）；

• UUID 短标识符（“f78375b1c487”）；

• 名称（“jonah”）。

Podman 为每个容器生成一个 UUID，如果未使用 **--name** 为容器分配名称，Podman 将生成一个随机字符串名称。名称可以作为一种更人性化的方式来识别容器。这适用于后台和前台容器。容器的名称也会使用容器的主 IP 地址添加到 /etc/hosts 文件中（另请参阅 **--add-host** 选项）。

**--network**=mode, --net

设置容器的网络模式。

有效的 mode 值为

• bridge[:OPTIONS,…]：在默认桥接器上创建网络堆栈。这是根目录容器的默认值。可以指定以下附加选项

  • alias=name：为容器添加网络范围别名。

  • ip=IPv4：为该容器指定一个静态 IPv4 地址。

  • ip6=IPv6：为该容器指定一个静态 IPv6 地址。

  • mac=MAC：为该容器指定一个静态 MAC 地址。

  • interface_name=name：为容器内部创建的网络接口指定一个名称。

  例如，要设置静态 ipv4 地址和静态 mac 地址，请使用 --network bridge:ip=10.88.0.10,mac=44:33:22:11:00:99。

• <network name or ID>[:OPTIONS,…]：连接到用户定义的网络；这是由 **podman network create** 创建的网络的网络名称或 ID。可以指定桥接模式下描述的相同选项。多次使用 **--network** 选项来指定其他网络。
  为了向后兼容，也可以在第一个 **--network** 参数上指定逗号分隔的网络，但是这样做会阻止您使用桥接部分中描述的选项。

• none：为容器创建网络命名空间，但不为其配置网络接口，因此容器没有网络连接。

• container:id：重用另一个容器的网络堆栈。

• host：不创建网络命名空间，容器使用主机的网络。注意：主机模式使容器能够完全访问本地系统服务，例如 D-bus，因此被认为不安全。

• ns:path：要加入的网络命名空间的路径。

• private：为容器创建一个新的命名空间。这将对根目录容器使用 **bridge** 模式，对无根容器使用 **slirp4netns**。

• slirp4netns[:OPTIONS,…]：使用 slirp4netns(1) 创建用户网络堆栈。可以指定以下附加选项，它们也可以使用 containers.conf 中的 network_cmd_options 设置

  • allow_host_loopback=true|false：允许 slirp4netns 访问主机环回 IP（默认值为 10.0.2.2 或更改时来自 slirp4netns cidr 子网的第二个 IP，请参阅下面的 cidr 选项）。默认值为 false。

  • mtu=MTU：指定要用于此网络的 MTU。（默认值为 65520）。

  • cidr=CIDR：指定要用于此网络的 ip 范围。（默认值为 10.0.2.0/24）。

  • enable_ipv6=true|false：启用 IPv6。默认值为 true。（对于 outbound_addr6 来说是必需的）。

  • outbound_addr=INTERFACE：指定 slirp 绑定到的出站接口（仅 ipv4 流量）。

  • outbound_addr=IPv4：指定 slirp 绑定到的出站 ipv4 地址。

  • outbound_addr6=INTERFACE：指定 slirp 绑定到的出站接口（仅 ipv6 流量）。

  • outbound_addr6=IPv6：指定 slirp 绑定到的出站 ipv6 地址。

  • port_handler=rootlesskit：使用 rootlesskit 进行端口转发。默认值。
    注意：Rootlesskit 将传入数据包的源 IP 地址更改为容器网络命名空间中的 IP 地址，通常为 10.0.2.100。如果应用程序需要真实的源 IP 地址，例如 Web 服务器日志，请使用 slirp4netns 端口处理程序。当连接到用户定义的网络时，rootlesskit 端口处理程序也用于无根容器。

  • port_handler=slirp4netns：使用 slirp4netns 端口转发，它比 rootlesskit 慢，但保留了正确的源 IP 地址。此端口处理程序不能用于用户定义的网络。

• pasta[:OPTIONS,…]：使用 pasta(1) 创建用户模式网络堆栈。
  这是无根容器的默认值，并且仅在无根模式下支持。
  默认情况下，IPv4 和 IPv6 地址和路由，以及 pod 接口名称，都从主机复制。如果未配置端口转发，则端口将根据两端（init 命名空间或容器命名空间）上绑定的服务动态转发。端口转发保留了原始源 IP 地址。pasta(1) 中描述的选项可以作为逗号分隔的参数指定。
  在 pasta(1) 选项方面，--config-net 默认情况下会给出，以便在容器启动时配置网络，并且 --no-map-gw 也是默认情况下假设的，以避免容器直接使用网关地址访问主机。可以通过在 pasta 特定选项中传递 --map-gw 来覆盖后者（尽管这不是实际的 pasta(1) 选项）。
  此外，如果分别未配置从主机到容器的 TCP 或 UDP 端口转发，则将传递 -t none 和 -u none，以禁用基于绑定端口的自动端口转发。类似地，-T none 和 -U none 用于禁用从容器到主机的相同功能。
  一些示例

  • pasta:--map-gw：允许容器直接使用网关地址访问主机。

  • pasta:--mtu,1500: 为容器中的 *tap* 接口指定 1500 字节的 MTU。

  • pasta:--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-forward,10.0.2.3,-m,1500,--no-ndp,--no-dhcpv6,--no-dhcp，等同于默认的 slirp4netns(1) 选项：禁用 IPv6，将 10.0.2.0/24 分配给容器中的 tap0 接口，网关为 10.0.2.3，启用可通过 10.0.2.3 访问的 DNS 转发器，将 MTU 设置为 1500 字节，禁用 NDP、DHCPv6 和 DHCP 支持。

  • pasta:-I,tap0,--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-forward,10.0.2.3,--no-ndp,--no-dhcpv6,--no-dhcp，等同于带有 Podman 覆盖的默认 slirp4netns(1) 选项：与上述相同，但将 MTU 保持为 65520 字节。

  • pasta:-t,auto,-u,auto,-T,auto,-U,auto: 基于主机和容器两端观察到的绑定端口，启用自动端口转发。

  • pasta:-T,5201: 启用将容器中的 TCP 端口 5201 转发到主机，使用回环接口而不是 tap 接口，以提高性能。

如果将 --dns、--dns-option 或 --dns-search 与 --network 设置为 none 或 container:id 一起使用，则无效。

如果与 --pod 一起使用，则容器不会加入 pod 的网络命名空间。

--network-alias=alias

为容器添加一个网络范围的别名，为容器加入的所有网络设置别名。要为特定网络设置名称，请使用别名选项，如 --network 选项下所述。如果网络启用了 DNS (podman network inspect -f {{.DNSEnabled}} <name>)，则这些别名可用于在给定网络上进行名称解析。此选项可以多次指定。注意：使用 CNI 时，容器只能访问它加入的第一个网络上的别名。此限制在 netavark/aardvark-dns 中不存在。

--no-healthcheck

禁用容器的任何定义的健康检查。

--no-hosts

不要修改容器中的 /etc/hosts 文件。

默认情况下，Podman 控制容器的 /etc/hosts 文件，并添加容器名称（参见 --name 选项）和主机名（参见 --hostname 选项）、内部 host.containers.internal 和 host.docker.internal 主机以及使用 --add-host 选项添加的任何主机名的条目。有关详细信息，请参阅 --add-host 选项。传递 --no-hosts 会禁用此功能，因此镜像的 /etc/hosts 文件保持不变。通过在 containers.conf 中设置 no_hosts=true，可以在全局范围内实现相同的效果。

此选项与 --add-host 冲突。

--oom-kill-disable

是否禁用容器的 OOM Killer。

此标志在 cgroups V2 系统上不受支持。

--oom-score-adj=num

调整主机对容器的 OOM 偏好设置（接受从 -1000 到 1000 的值）。

在无根模式下运行时，指定的值不能低于当前进程的 oom_score_adj。在这种情况下，oom-score-adj 会被限制为当前进程的值。

--os=OS

覆盖要拉取的镜像的操作系统，默认为主机，例如，windows。除非覆盖，否则本地存储中相同镜像的后续查找会匹配此操作系统，无论主机如何。

--passwd-entry=ENTRY

自定义使用 --passwd 时写入容器内 /etc/passwd 文件的条目。

变量 $USERNAME、$UID、$GID、$NAME、$HOME 会在运行时自动替换为它们的值。

--personality=persona

Personality 通过 Linux personality(2) 设置执行域。

--pid=mode

设置容器的 PID 命名空间模式。默认情况下，为容器创建一个私有 PID 命名空间。

• container:id: 加入另一个容器的 PID 命名空间；

• host: 对容器使用主机 的 PID 命名空间。请注意，主机模式会使容器完全访问本地 PID，因此被认为是不安全的；

• ns:path: 加入指定的 PID 命名空间；

• private: 为容器创建一个新的命名空间（默认）。

--pidfile=path

当指定 pidfile 位置时，容器进程的 PID 将写入 pidfile。（此选项在远程 Podman 客户端不可用，包括 Mac 和 Windows（不包括 WSL2）机器。）如果未指定 pidfile 选项，则容器进程的 PID 将写入 /run/containers/storage/${storage-driver}-containers/$CID/userdata/pidfile。

容器启动后，可以使用以下 podman inspect 命令发现 pidfile 的位置

$ podman inspect --format '{{ .PidFile }}' $CID
/run/containers/storage/${storage-driver}-containers/$CID/userdata/pidfile

--pids-limit=limit

调整容器的 pids 限制。设置为 -1 表示容器的 pids 无限制。在支持“pids”cgroup 控制器的系统上，默认值为 2048。

--platform=OS/ARCH

指定用于选择镜像的平台。（与 --arch 和 --os 冲突）--platform 选项可用于覆盖当前体系结构和操作系统。除非覆盖，否则本地存储中相同镜像的后续查找会匹配此平台，无论主机如何。

--pod=name

在现有 pod 中运行容器。如果 pod 名称以 new: 开头，Podman 会自动创建该 pod。要使用更细致的选项创建 pod，请在创建容器之前使用 podman pod create 命令。当容器在具有基础设施容器的 pod 中运行时，基础设施容器会先启动。

--pod-id-file=file

在现有 pod 中运行容器，并从指定的 *file* 中读取 pod 的 ID。当容器在具有基础设施容器的 pod 中运行时，基础设施容器会先启动。

--privileged

为该容器授予扩展权限。默认值为 false。

默认情况下，Podman 容器是无特权的 (=false)，并且无法修改操作系统的一部分。这是因为默认情况下，容器仅允许对设备进行有限的访问。一个“特权”容器被授予与启动容器的用户相同的设备访问权限，但系统模式 (--systemd=always) 下运行时除外，虚拟控制台 (/dev/tty\d+) 除外。

特权容器会关闭隔离容器与主机之间的安全功能。已删除的功能、有限的设备、只读挂载点、Apparmor/SELinux 隔离以及 Seccomp 过滤器都已禁用。由于安全功能已禁用，因此几乎永远不应该设置 privileged 字段，因为容器很容易突破隔离。

在用户命名空间中运行的容器（例如，无根容器）不能拥有超过启动它们的用户的权限。

--publish, -p=[[ip:][hostPort]:]containerPort[/protocol]

将容器的端口或端口范围发布到主机。

*hostPort* 和 *containerPort* 都可以指定为端口范围。当为两者指定范围时，范围中的容器端口数必须与范围中的主机端口数匹配。

如果主机 IP 设置为 0.0.0.0 或根本没有设置，则端口将在主机的所有 IP 上绑定。

默认情况下，Podman 发布 TCP 端口。要发布 UDP 端口，请将 udp 作为协议提供。要发布 TCP 和 UDP 端口，请分别使用 tcp 和 udp 作为协议两次设置 --publish。有根容器还可以使用 sctp 协议发布端口。

不必指定主机端口（例如，podman run -p 127.0.0.1::80）。如果未指定，则容器端口会在主机上随机分配一个端口。

使用 podman port 查看实际映射：podman port $CONTAINER $CONTAINERPORT。

请注意，网络驱动程序 macvlan 和 ipvlan 不支持端口转发，它对这些网络没有影响。

注意：如果容器在 Pod 中运行，则无需为 Pod 中的容器发布端口。端口只需要由 Pod 本身发布。Pod 网络栈就像主机上的网络栈一样——当 Pod 中有各种容器和容器中的程序时，它们共享一个接口和 IP 地址以及关联的端口。如果一个容器绑定到一个端口，那么在该端口使用期间，Pod 中的任何其他容器都不能使用该端口。Pod 中的容器还可以通过让一个容器绑定到 Pod 中的 localhost，而另一个容器连接到该端口，在 localhost 上进行通信。

--publish-all, -P

将所有公开的端口发布到主机接口上的随机端口。默认值为 false。

设置为 true 时，将所有公开的端口发布到主机接口。如果操作员使用 -P（或 -p），则 Podman 使公开的端口在主机上可访问，并且这些端口可供可以访问主机的任何客户端使用。

使用此选项时，Podman 将任何公开端口绑定到主机上 /proc/sys/net/ipv4/ip_local_port_range 定义的短暂端口范围内的随机端口。要查找主机端口和公开端口之间的映射，请使用 podman port。

--pull=policy

拉取镜像策略。默认值为 missing。

• always：始终拉取镜像，如果拉取失败则抛出错误。

• missing：仅当本地容器存储中没有镜像时才拉取镜像。如果找不到镜像并且拉取失败，则抛出错误。

• never：从不拉取镜像，但使用本地容器存储中的镜像。如果找不到镜像，则抛出错误。

• newer：如果注册表上的镜像比本地容器存储中的镜像更新，则拉取。当摘要不同时，镜像被认为是更新的。比较时间戳很容易出错。如果找到了本地镜像，则会抑制拉取错误。

--quiet, -q

拉取镜像时抑制输出信息。

--rdt-class=intel-rdt-class-of-service

Rdt-class 为要运行的容器设置服务等级（CLOS 或 COS）。基于英特尔资源目录技术（RDT）功能集的一部分的缓存分配技术（CAT）功能，所有容器进程将在预配置的 COS 中运行，表示缓存的一部分。COS 必须使用 resctrl 内核驱动程序提供的伪文件系统（通常挂载在 /sys/fs/resctrl）进行创建和配置。将容器分配给 COS 需要 root 权限，因此在无根环境中不起作用。目前，该功能仅支持使用 runc 作为运行时。有关在将容器分配给 COS 之前创建 COS 的更多详细信息，请参阅 https://docs.kernel.org/arch/x86/resctrl.html。

--read-only

以只读方式挂载容器的根文件系统。

默认情况下，容器根文件系统是可写的，允许进程在任何地方写入文件。通过指定 --read-only 标志，容器的根文件系统将以只读方式挂载，禁止任何写入操作。

--read-only-tmpfs

在运行 --read-only 容器时，在 /dev、/dev/shm、/run、/tmp 和 /var/tmp 上挂载一个可写 tmpfs。默认值为 true。

--read-only	--read-only-tmpfs	/	/run, /tmp, /var/tmp
true	true	r/o	r/w
true	false	r/o	r/o
false	false	r/w	r/w
false	true	r/w	r/w

当 --read-only=true 并且 --read-only-tmpfs=true 时，会在 /tmp、/run 和 /var/tmp 目录上挂载额外的 tmpfs。

当 --read-only=true 并且 --read-only-tmpfs=false 时，/dev 和 /dev/shm 被标记为只读，并且不会在 /tmp、/run 和 /var/tmp 上挂载 tmpfs。这些目录是从底层镜像中公开的，这意味着它们默认是只读的。这使容器完全只读。容器中不存在可写目录。在此模式下，需要通过外部卷或挂载添加可写目录。

默认情况下，当 --read-only=false 时，/dev 和 /dev/shm 是可读写的，而 /tmp、/run 和 /var/tmp 是来自容器镜像的可读写目录。

--replace

如果另一个具有相同名称的容器已经存在，则替换并删除它。默认值为 false。

--requires=container

指定一个或多个要求。要求是一个依赖容器，它在该容器之前启动。容器可以通过名称或 ID 指定，多个容器用逗号分隔。

--restart=policy

容器退出时要遵循的重启策略。如果容器通过 podman kill 或 podman stop 命令停止，则重启策略不会生效。

有效的 policy 值为

• no：容器退出时不重启。

• never：no 的同义词；容器退出时不重启。

• on-failure[:max_retries]：当容器以非零退出代码退出时重启容器，无限次重试或直到达到可选的 max_retries 计数。

• always：当容器退出时重启容器，无论状态如何，无限次重试。

• unless-stopped：与 always 相同。

Podman 提供了一个 systemd 单元文件 podman-restart.service，它在系统重启后重启容器。

在 systemd 服务中运行容器时，使用 systemd 提供的重启功能。换句话说，不要在容器单元中使用此选项，而是在 [Service] 部分中设置 Restart= systemd 指令。参见 podman-systemd.unit(5) 和 systemd.service(5)。

--retry=attempts

在注册表和本地存储之间拉取或推送镜像时，在出现故障的情况下重试的次数。默认值为 3。

--retry-delay=duration

在注册表和本地存储之间拉取或推送镜像时，在出现故障的情况下，重试尝试之间延迟的持续时间。默认值是从两秒开始，然后呈指数级退避。当设置此值时，将使用延迟，并且不会发生指数级退避。

--rm

当容器退出时，自动删除容器和与容器关联的任何匿名未命名卷。默认值为 false。

--rootfs

如果指定，则第一个参数引用文件系统上的已展开容器。

这对于在不进行任何镜像管理的情况下运行容器很有用，容器的 rootfs 被假定为外部管理。

Overlay Rootfs Mounts

:O 标志告诉 Podman 使用 overlay file system 将 rootfs 路径中的目录作为存储挂载。容器进程可以修改挂载点内的内容，这些内容存储在容器存储的单独目录中。在覆盖方面，源目录是较低的，容器存储目录是较高的。对挂载点的修改在容器执行完毕时会被销毁，类似于卸载 tmpfs 挂载点。

注意：在 SELinux 系统上，rootfs 需要正确的标签，默认情况下为 unconfined_u:object_r:container_file_t:s0。

idmap

如果指定了 idmap，则创建一个到容器中目标用户命名空间的 id 映射挂载。idmap 选项支持自定义映射，它可能与容器使用的用户命名空间不同。映射可以在 idmap 选项之后指定，例如：idmap=uids=0-1-10#10-11-10;gids=0-100-10。对于每个三元组，第一个值是映射到主机上的第二个值的备份文件系统 ID 的开始。此映射的长度在第三个值中给出。多个范围用 # 分隔。

--sdnotify=container | conmon | healthy | ignore

确定如何使用 NOTIFY_SOCKET，如 systemd 和 Type=notify 传递。

默认值为 container，这意味着允许 OCI 运行时将套接字代理到容器中以接收就绪通知。Podman 将 MAINPID 设置为 conmon 的 pid。conmon 选项将 MAINPID 设置为 conmon 的 pid，并在容器启动时发送 READY。套接字从不传递给运行时或容器。healthy 选项将 MAINPID 设置为 conmon 的 pid，并在容器变为健康时发送 READY；要求设置健康检查。套接字从不传递给运行时或容器。ignore 选项从自身和子进程的环境中删除 NOTIFY_SOCKET，用于在 Podman 上方的一些其他进程使用 NOTIFY_SOCKET 并且 Podman 不使用它时。

--seccomp-policy=policy

指定策略以选择 seccomp 配置文件。如果设置为 image，则 Podman 会在容器镜像配置中查找 “io.containers.seccomp.profile” 标签并使用其值作为 seccomp 配置文件。否则，Podman 会按照 default 策略执行，通过应用默认配置文件来实现，除非通过 --security-opt seccomp（如下所述）另有指定。

请注意，此功能是实验性的，将来可能会发生变化。

--secret=secret[,opt=opt …]

允许容器访问机密。可以多次指定。

机密是容器在运行时需要但未存储在镜像或源代码控制中的敏感数据块，例如用户名和密码、TLS 证书和密钥、SSH 密钥或其他重要的通用字符串或二进制内容（大小不超过 500 kb）。

当秘密被指定为类型 mount 时，秘密将在创建容器时被复制并挂载到容器中。当秘密被指定为类型 env 时，秘密将作为容器内的环境变量设置。秘密在容器创建时写入容器，使用 podman secret 命令在容器创建后修改秘密会影响容器内部的秘密。

秘密及其存储使用 podman secret 命令进行管理。

秘密选项

• type=mount|env : 秘密如何暴露给容器。 mount 将秘密作为文件挂载到容器中。 env 将秘密作为环境变量暴露。默认为 mount。

• target=target : 秘密的目标。对于挂载的秘密，这是容器内秘密的路径。如果提供完全限定路径，则秘密将挂载到该位置。否则，秘密将挂载到 /run/secrets/target （对于 Linux 容器）或 /var/run/secrets/target （对于 FreeBSD 容器）。如果未设置目标，则秘密默认挂载到 /run/secrets/secretname 。对于 env 秘密，这是环境变量键。默认为 secretname。

• uid=0 : 秘密的 UID。默认为 0。仅限挂载秘密类型。

• gid=0 : 秘密的 GID。默认为 0。仅限挂载秘密类型。

• mode=0 : 秘密的模式。默认为 0444。仅限挂载秘密类型。

示例

挂载到 /my/location/mysecret ，UID 为 1

--secret mysecret,target=/my/location/mysecret,uid=1

挂载到 /run/secrets/customtarget ，模式为 0777

--secret mysecret,target=customtarget,mode=0777

创建一个名为 ENVSEC 的秘密环境变量

--secret mysecret,type=env,target=ENVSEC

--security-opt=option

安全选项

• apparmor=unconfined : 关闭容器的 AppArmor 限制

• apparmor=alternate-profile : 设置容器的 AppArmor 限制配置文件

• label=user:USER: 设置容器进程的标签用户

• label=role:ROLE: 设置容器进程的标签角色

• label=type:TYPE: 设置容器进程的标签进程类型

• label=level:LEVEL: 设置容器进程的标签级别

• label=filetype:TYPE: 设置容器文件的标签文件类型

• label=disable: 关闭容器的标签分离

注意：可以通过在 containers.conf (/etc/containers/containers.conf 或 $HOME/.config/containers/containers.conf) 文件中设置 label=false 来为所有容器禁用标签。

• label=nested: 允许在容器内进行 SELinux 修改。只要 SELinux 策略允许，容器就可以修改文件和进程上的 SELinux 标签。如果没有 nested，容器将 SELinux 视为已禁用，即使它在主机上已启用。容器将被阻止设置任何标签。

• mask=/path/1:/path/2: 用冒号分隔的要屏蔽的路径。容器内无法访问屏蔽的路径。

• no-new-privileges: 禁用容器进程获取额外权限。

• seccomp=unconfined: 关闭容器的 Seccomp 限制。

• seccomp=profile.json: 用作 Seccomp 过滤器的 JSON 文件。请注意， io.podman.annotations.seccomp 注释将设置使用指定的 value，如 podman inspect 中所示。

• proc-opts=OPTIONS : 用于 /proc 挂载的以逗号分隔的选项列表。有关可能挂载选项的更多详细信息，请参阅 proc(5) 手册页。

• unmask=ALL 或 /path/1:/path/2，或 shell 展开的路径 (/proc/*)：用冒号分隔的要取消屏蔽的路径。如果设置为 ALL，它将取消屏蔽所有默认情况下被屏蔽或设为只读的路径。默认屏蔽的路径是 /proc/acpi, /proc/kcore, /proc/keys, /proc/latency_stats, /proc/sched_debug, /proc/scsi, /proc/timer_list, /proc/timer_stats, /sys/firmware, 和 /sys/fs/selinux, /sys/devices/virtual/powercap。默认情况下设为只读的路径是 /proc/asound, /proc/bus, /proc/fs, /proc/irq, /proc/sys, /proc/sysrq-trigger, /sys/fs/cgroup。

注意：可以通过在 containers.conf(5) 文件中设置 label=false 来为所有容器禁用标签。

--shm-size=number[unit]

/dev/shm 的大小。unit 可以是 b（字节）、k（KiB）、m（MiB）或 g（GiB）。如果省略单位，则系统使用字节。如果省略大小，则默认值为 64m。当 size 为 0 时，容器用于 IPC 的内存量没有限制。此选项与 --ipc=host 冲突。

--shm-size-systemd=number[unit]

系统特定 tmpfs 挂载的大小，例如 /run、/run/lock、/var/log/journal 和 /tmp。unit 可以是 b（字节）、k（KiB）、m（MiB）或 g（GiB）。如果省略单位，则系统使用字节。如果省略大小，则默认值为 64m。当 size 为 0 时，使用量限制为主机可用内存的 50%。

--stop-signal=signal

停止容器的信号。默认值为 SIGTERM。

--stop-timeout=seconds

停止容器的超时时间。默认值为 10。远程连接使用本地 containers.conf 中的默认值。

--subgidname=name

在新的用户命名空间中运行容器，使用 /etc/subgid 文件中具有 name 的映射。如果以无根模式运行，用户需要有权使用该映射。请参阅 subgid(5)。此标志与 --userns 和 --gidmap 冲突。

--subuidname=name

在新的用户命名空间中运行容器，使用 /etc/subuid 文件中具有 name 的映射。如果以无根模式运行，用户需要有权使用该映射。请参阅 subuid(5)。此标志与 --userns 和 --uidmap 冲突。

--sysctl=name=value

在运行时配置命名空间内核参数。

对于 IPC 命名空间，允许以下 sysctls

• kernel.msgmax

• kernel.msgmnb

• kernel.msgmni

• kernel.sem

• kernel.shmall

• kernel.shmmax

• kernel.shmmni

• kernel.shm_rmid_forced

• 以 fs.mqueue.* 开头的 Sysctls

注意：如果使用 --ipc=host 选项，则不允许使用上述 sysctls。

对于网络命名空间，只允许以 net.* 开头的 Sysctls。

注意：如果使用 --network=host 选项，则不允许使用上述 sysctls。

--systemd=true | false | always

在 systemd 模式下运行容器。默认值为 true。

• true 仅在容器内执行的命令为 systemd、/usr/sbin/init、/sbin/init 或 /usr/local/sbin/init 时启用 systemd 模式。

• false 禁用 systemd 模式。

• always 强制启用 systemd 模式。

在 systemd 模式下运行容器会导致以下更改

• Podman 在以下目录上挂载 tmpfs 文件系统

  • /run

  • /run/lock

  • /tmp

  • /sys/fs/cgroup/systemd（在 cgroup v1 系统上）

  • /var/lib/journal

• Podman 将默认停止信号设置为 SIGRTMIN+3。

• Podman 在容器中设置 container_uuid 环境变量，该变量为容器 ID 的前 32 个字符。

• Podman 在使用 --privileged 运行时不会挂载虚拟控制台（/dev/tty\d+）。

• 在 cgroup v2 上，/sys/fs/cgroup 以可写方式挂载。

这使得 systemd 可以在没有任何修改的情况下在受限容器中运行。

请注意，在 SELinux 系统上，systemd 尝试写入 cgroup 文件系统。默认情况下，写入 cgroup 文件系统的容器会被拒绝。必须启用 container_manage_cgroup 布尔值才能在 SELinux 分隔的系统上允许这样做。

setsebool -P container_manage_cgroup true

--timeout=seconds

容器允许运行的最大时间，在此时间之后，conmon 会向其发送 kill 信号。默认情况下，容器会一直运行，直到它们退出或被 podman stop 停止。

--tls-verify

与注册表联系时要求 HTTPS 并验证证书（默认值：true）。如果明确设置为 true，则使用 TLS 验证。如果设置为 false，则不使用 TLS 验证。如果未指定，则使用 TLS 验证，除非目标注册表在 containers-registries.conf(5) 中列为不安全的注册表。

--tmpfs=fs

创建一个 tmpfs 挂载。

将临时文件系统（tmpfs）挂载到容器中，例如

$ podman create -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image

此命令在容器内的 * /tmp* 中挂载一个**tmpfs**。支持的挂载选项与 Linux 默认挂载标志相同。如果没有指定选项，系统将使用以下选项：**rw,noexec,nosuid,nodev**。

**--tty**，**-t**

分配一个伪终端。默认值为**false**。

设置为**true**时，Podman 会分配一个伪终端并连接到容器的标准输入。例如，这可以用来运行一个临时的交互式 shell。

**注意**：--tty 标志会阻止标准输出的重定向。它会将 STDOUT 和 STDERR 合并，可能会插入控制字符，并且可能会挂起管道。此选项仅在交互式终端中运行时使用。向 Podman 提供输入时，请仅使用 -i，不要使用 -it。

**--tz**=timezone

在容器中设置时区。此标志接受基于区域的时区、GMT 时间，以及local，它会将容器中的时区设置为与主机相同。有关有效时区，请参见 /usr/share/zoneinfo/。远程连接使用本地容器的配置文件来设置默认值。

**--uidmap**=[flags]container_uid:from_uid[:amount]

使用提供的 UID 映射在新用户命名空间中运行容器。此选项与 **--userns** 和 **--subuidname** 选项冲突。此选项提供了一种将主机 UID 映射到容器 UID 的方法。它可以传递多次来映射不同的范围。

可选 *flags* 的可能值将在本页面的下方讨论。*amount* 值是可选的，如果没有给出，则假设为 **1**。

*from_uid* 值基于运行命令的用户，无论是具有 root 权限的用户还是没有 root 权限的用户。

• 具有 root 权限的用户： [flags]container_uid:host_uid[:amount]

• 没有 root 权限的用户： [flags]container_uid:intermediate_uid[:amount]

  Rootful mappings

当 **podman create** 由特权用户调用时，选项 **--uidmap** 作为主机 UID 和容器 UID 之间的直接映射工作。

主机 UID -> 容器 UID

*amount* 指定映射的连续 UID 的数量。例如，如果 *amount* 为 **4**，则映射如下所示：

主机 UID	容器 UID
from_uid	container_uid
from_uid + 1	container_uid + 1
from_uid + 2	container_uid + 2
from_uid + 3	container_uid + 3

Rootless mappings

当 **podman create** 由非特权用户（即运行无 root 权限）调用时，*from_uid* 值将被解释为“中间 UID”。在无 root 权限的情况下，主机 UID 不会直接映射到容器 UID。相反，映射将通过两个映射步骤进行：

主机 UID -> 中间 UID -> 容器 UID

**--uidmap** 选项仅影响第二个映射步骤。

第一个映射步骤由 Podman 从 * /etc/subuid* 文件的内容和调用 Podman 的用户的 UID 中推断出来。

第一个映射步骤

主机 UID	中间 UID
Podman 用户的 UID	0
第一个从属 UID	1
第二个从属 UID	2
第三个从属 UID	3
第 n 个从属 UID	n

要能够使用大于零的中间 UID，用户需要在 * /etc/subuid* 中配置从属 UID。请参阅 **subuid** (5)。

第二个映射步骤使用 **--uidmap** 进行配置。

例如，如果 *amount* 为 **5**，则第二个映射步骤如下所示：

中间 UID	容器 UID
from_uid	container_uid
from_uid + 1	container_uid + 1
from_uid + 2	container_uid + 2
from_uid + 3	container_uid + 3
from_uid + 4	container_uid + 4

在无 root 权限的情况下运行时，Podman 会使用 * /etc/subuid* 文件中配置的所有范围。

当前用户 ID 映射到无 root 权限用户命名空间中的 UID=0。每个额外的范围都会在之后依次添加。

主机	无 root 权限用户命名空间	长度
$UID	0	1
1	$FIRST_RANGE_ID	$FIRST_RANGE_LENGTH
1+$FIRST_RANGE_LENGTH	$SECOND_RANGE_ID	$SECOND_RANGE_LENGTH

Referencing a host ID from the parent namespace

作为无 root 权限的用户，**--uidmap** 或 **--gidmap** 中给定的主机 ID 从 Podman 生成的 *中间命名空间* 中映射。有时，直接引用 *主机命名空间* 也是可取的。可以通过手动执行 podman unshare cat /proc/self/gid_map，找到输出的第二列中所需的主机 ID，并从第一列中获取相应的中间 ID 来手动完成此操作。

Podman 可以通过在映射中的主机 ID 前面加上 @ 符号来执行所有这些操作。例如，通过指定 --gidmap 100000:@2000:1，podman 会查找与主机 ID 2000 相对应的中间 ID，并将找到的中间 ID 映射到容器 ID 100000。给定的主机 ID 必须是已从属的（否则它将不会在第一步中被映射到中间空间）。

如果长度大于 1，例如使用 --gidmap 100000:@2000:2，Podman 会将主机 ID 2000 和 2001 分别映射到 100000 和 100001，而不管中间映射是如何定义的。

Extending previous mappings

某些映射修改可能很麻烦。例如，用户从一个映射开始，例如 --gidmap="0:0:65000"，需要将其更改为父 ID 1000 映射到容器 ID 100000，而容器 ID 1 未分配。相应的 --gidmap 变为 --gidmap="0:0:1" --gidmap="2:2:65534" --gidmap="100000:1:1"。

可以使用 + 标志简化此表示法，该标志负责拆分之前的映射，并删除与给定映射冲突的任何分配。该标志在容器 ID 之前给出，如下所示： --gidmap="0:0:65000" --gidmap="+100000:1:1"

标志	示例	描述
+	+100000:1:1	扩展之前的映射

此表示法会导致分配中的间隙，因此之后可能需要填充这些间隙： --gidmap="0:0:65000" --gidmap="+100000:1:1" --gidmap="1:65001:1"

此标志的一个具体用例是在无 root 权限用户的上下文中。无 root 权限用户可以像在 --gidmap="+100000:1:1" 中一样使用 + 标志指定映射。Podman 然后会从零开始“填充间隙”，使用所有剩余的中间 ID。当用户想要将特定的中间 ID 映射到容器 ID，并让 Podman 自行映射其余的从属 ID 时，这将非常方便。

Passing only one of --uidmap or --gidmap

通常，从属用户和组 ID 会同时分配，并且对于任何用户，从属用户 ID 都与从属组 ID 相匹配。为了方便起见，如果只给出了 **--uidmap** 或 **--gidmap** 之一，podman 会假设映射指的是 UID 和 GID 两种，并将给定的映射应用于两者。如果只需要更改两个值中的一个，则映射应包含 u 或 g 标志来指定它们仅应用于 UID 或 GID，并且不应该被复制到另一方。

标志	示例	描述
u	u20000:2000:1	映射仅应用于 UID
g	g10000:1000:1	映射仅应用于 GID

例如，给定以下命令：

podman create --gidmap "0:0:1000" --gidmap "g2000:2000:1"

由于没有给出 **--uidmap**，因此 **--gidmap** 被复制到 **--uidmap**，得到与以下命令等效的命令：

podman create --gidmap "0:0:1000" --gidmap "2000:2000:1" --uidmap "0:0:1000"

--gidmap "g2000:2000:1" 使用了 g 标志，因此它没有被复制到 **--uidmap**。

Rootless mapping of additional host GIDs

无 root 权限的用户可能希望映射一个特定的主机组，该主机组已经从属到 * /etc/subgid* 中，而无需指定其余的映射。

这可以使用 **--gidmap “+gcontainer_gid:@host_gid”** 完成。

其中

• 主机 GID 通过 @ 符号给出。

• 由于 g 标志的存在，此 GID 的映射不会被复制到 **--usermap**。

• 由于 + 标志的存在，其余的容器 ID 将从 0 开始映射到 n，使用所有剩余的从属 GID。

例如，如果用户属于组 2000，并且该组从属到该用户（使用 usermod --add-subgids 2000-2000 $USER），则用户可以使用以下命令将该组映射到容器中：**--gidmap=+g100000:@2000**。

如果此映射与选项 **--group-add=keep-groups** 结合使用，则容器中的进程将属于组 100000，主机中属于组 2000 的文件将在容器中显示为由组 100000 拥有。

podman run --group-add=keep-groups --gidmap="+g100000:@2000" ...

No subordinate UIDs

即使用户在 * /etc/subuid* 中没有任何从属 UID，也可以使用 **--uidmap** 将用户的普通 UID 映射到容器 UID，方法是运行 podman create --uidmap $container_uid:0:1 --user $container_uid ...。

Pods

**--uidmap** 选项不能与 **--pod** 选项一起调用，因为在 pod 中时，无法在容器级别设置 uidmap。

**--ulimit**=option

Ulimit 选项。设置容器内的 ulimit 值。

--ulimit 具有软限制和硬限制，格式为=[:]。例如

$ podman run --ulimit nofile=1024:1024 --rm ubi9 ulimit -n 1024

将软或硬限制设置为 -1，表示将限制设置为当前进程的最大限制。在 rootful 模式下，这通常是无限的。

如果 nofile 和 nproc 未设置，则将使用默认值 1048576，除非在 containers.conf(5) 中被覆盖。但是，如果默认值超过当前无根用户的硬限制，则将改为应用当前的硬限制。

使用 **host** 从主机复制当前配置。

不要将 nproc 与 ulimit 标志一起使用，因为 Linux 使用 nproc 设置用户可用的最大进程数，而不是容器。

使用 --pids-limit 选项修改 cgroup 控制以限制容器内的进程数量。

--umask=umask

设置容器内的 umask。默认为 0022。远程连接使用本地 containers.conf 作为默认值

--unsetenv=env

取消设置容器的默认环境变量。默认环境变量包括 Podman 本机提供的变量、镜像配置的环境变量以及 containers.conf 中的环境变量。

--unsetenv-all

取消设置容器的所有默认环境变量。默认环境变量包括 Podman 本机提供的变量、镜像配置的环境变量以及 containers.conf 中的环境变量。

--user, -u=user[:group]

设置用于指定命令的用户名或 UID，以及可选的组名或 GID。user 和 group 都可以是符号或数字。

如果没有此参数，则命令将以容器镜像中指定的用户身份运行。除非被 Containerfile 中的 USER 命令或传递给此选项的值覆盖，否则此用户通常默认为 root。

当未使用用户命名空间时，容器内部和主机上使用的 UID 和 GID 匹配。但是，当使用用户命名空间时，容器内的 UID 和 GID 可能对应于主机上的另一个 UID 和 GID。例如，在无根容器中，始终使用用户命名空间，并且容器中的 root 默认情况下对应于调用 Podman 的用户的 UID 和 GID。

--userns=mode

设置容器的用户命名空间模式。

如果未设置 --userns，则默认值按以下方式确定。

• 如果设置了 --pod，则忽略 --userns 并使用 pod 的用户命名空间。

• 如果设置了环境变量 **PODMAN_USERNS**，则使用其值。

• 如果在 containers.conf 中指定了 userns，则使用此值。

• 否则，假定 --userns=host。

--userns=""（即空字符串）是 --userns=host 的别名。

此选项与 --gidmap、--uidmap、--subuidname 和 --subgidname 不兼容。

无根用户 --userns=键映射

键	主机用户	容器用户
auto	$UID	nil（主机用户 UID 未映射到容器中。）
主机	$UID	0（默认用户帐户映射到容器中的 root 用户。）
keep-id	$UID	$UID（将用户帐户映射到容器内的相同 UID。）
keep-id:uid=200,gid=210	$UID	200:210（将用户帐户映射到容器内的指定 UID、GID 值。）
nomap	$UID	nil（主机用户 UID 未映射到容器中。）

有效的 mode 值为

auto[:OPTIONS,…]: 自动创建唯一的用户命名空间。

• rootful mode: --userns=auto 标志要求在 /etc/subuid 和 /etc/subgid 文件中指定用户名 **containers**，并提供 Podman 容器允许分配的未使用子用户 ID 范围。

   Example: `containers:2147483647:2147483648`.
  

• rootless mode: 将使用 /etc/subuid 和 /etc/subgid 文件中的用户范围。注意，在不使用 --userns=auto 的情况下运行单个容器将使用整个 UID 范围，并且不允许进一步细分。请参阅 subuid(5)。

Podman 从 containers 子用户 ID 中分配唯一的 UID 和 GID 范围。范围的大小基于镜像中所需的 UID 数量。可以使用 size 选项覆盖 UID 和 GID 的数量。

选项 --userns=keep-id 使用用户的全部子 UID 和子 GID。选项 --userns=nomap 使用用户的全部子 UID 和子 GID，除了用户自己的 ID。只要存在任何使用 --userns=keep-id 或 --userns=nomap 启动的容器，在启动新容器时使用 --userns=auto 就不起作用。

有效的 auto 选项

• gidmapping=CONTAINER_GID:HOST_GID:SIZE: 强制在用户命名空间中存在 GID 映射。

• size=SIZE: 指定自动用户命名空间的显式大小。例如 --userns=auto:size=8192。如果未指定 size，则 auto 会估计用户命名空间的大小。

• uidmapping=CONTAINER_UID:HOST_UID:SIZE: 强制在用户命名空间中存在 UID 映射。

gidmapping 和 uidmapping 中的主机 UID 和 GID 可以选择性地以 @ 符号为前缀。在这种情况下，podman 将查找与主机 ID 对应的中间 ID，并将找到的中间 ID 映射到容器 ID。有关详细信息，请参阅 --uidmap。

container:id: 加入指定容器的用户命名空间。

host 或 “”（空字符串）：在调用者的用户命名空间中运行。在容器中运行的进程在主机上的权限与调用者启动的任何其他进程相同。

keep-id: 创建一个用户命名空间，其中当前用户的 UID:GID 映射到容器中的相同值。对于 root 创建的容器，当前映射被创建到新的用户命名空间中。

有效的 keep-id 选项

• uid=UID: 覆盖容器内部用于将当前用户映射到的 UID。

• gid=GID: 覆盖容器内部用于将当前用户映射到的 GID。

nomap: 创建一个用户命名空间，其中当前无根用户的 UID:GID 未映射到容器中。此选项不允许 root 用户创建的容器使用。

ns:namespace: 在给定的现有用户命名空间中运行容器。

--uts=mode

设置容器的 UTS 命名空间模式。支持以下值

• host: 在容器内使用主机的 UTS 命名空间。

• private: 为容器创建一个新的命名空间（默认）。

• ns:[path]: 在给定的现有 UTS 命名空间中运行容器。

• container:[container]: 加入指定容器的 UTS 命名空间。

--variant=VARIANT

使用 VARIANT 代替容器镜像的默认体系结构变体。一些镜像可以使用 arm 体系结构的多个变体，例如 arm/v5 和 arm/v7。

--volume, -v=[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]

创建绑定挂载。如果指定了 -v /HOST-DIR:/CONTAINER-DIR，则 Podman 将主机上的 /HOST-DIR 绑定挂载到 Podman 容器中的 /CONTAINER-DIR。类似地，-v SOURCE-VOLUME:/CONTAINER-DIR 将主机上的命名卷挂载到容器中。如果没有这样的命名卷，则 Podman 将创建一个。如果未给出源，则卷将作为匿名命名卷创建，具有随机生成的名称，并在容器通过 --rm 标志或 podman rm --volumes 命令删除时被删除。

（注意，当使用远程客户端（包括 Mac 和 Windows（不包括 WSL2）机器）时，卷是从远程服务器挂载的，不一定是客户端机器。）

OPTIONS 是一个用逗号分隔的列表，可以是以下一项或多项

• rw|ro

• z|Z

• [O]

• [U]

• [no]copy

• [no]dev

• [no]exec

• [no]suid

• [r]bind

• [r]shared|[r]slave|[r]private[r]unbindable ^[1]

• idmap[=options]

CONTAINER-DIR 必须是绝对路径，例如 /src/docs。卷被挂载到容器中的此目录。

如果指定了卷源，则它必须是主机上的路径或命名卷的名称。主机路径可以是绝对路径或相对路径；相对路径相对于运行 Podman 的目录解析。如果源不存在，则 Podman 返回错误。用户必须预先创建源文件或目录。

任何不以 . 或 / 开头的源都将被视为命名卷的名称。如果不存在具有该名称的卷，则会创建它。使用名称创建的卷不是匿名的，并且不会被 --rm 选项和 podman rm --volumes 命令删除。

指定多个 -v 选项将一个或多个卷挂载到容器中。

写 保护 卷 挂载

添加 :ro 或 :rw 选项以分别以只读或读写模式挂载卷。默认情况下，卷以读写模式挂载。请参阅示例。

改变所有者 卷 挂载

默认情况下，Podman 不会更改挂载到容器中的源卷目录的所有者和组。如果在新的用户命名空间中创建容器，则容器内的 UID 和 GID 可能对应于主机上的另一个 UID 和 GID。

:U 后缀告诉 Podman 使用基于容器内的 UID 和 GID 的正确主机 UID 和 GID，递归地更改源卷的所有者和组。改变所有者会遍历卷下的文件系统并在每个文件上更改 UID/GID。如果卷有数千个 inode，则此过程需要很长时间，从而延迟容器的启动。

警告 谨慎使用，因为这会修改主机文件系统。

标签 卷 挂载

像 SELinux 这样的标签系统要求在挂载到容器中的卷内容上放置正确的标签。如果没有标签，安全系统可能会阻止容器内部运行的进程使用该内容。默认情况下，Podman 不会更改操作系统设置的标签。

要在容器上下文中更改标签，请在卷挂载中添加两个后缀之一：:z 或 :Z。这些后缀告诉 Podman 重新标记共享卷上的文件对象。z 选项告诉 Podman 两个或多个容器共享卷内容。因此，Podman 使用共享内容标签标记内容。共享卷标签允许所有容器读写内容。Z 选项告诉 Podman 使用私有未共享标签标记内容，只有当前容器可以使用私有卷。注意：pod 中的所有容器共享相同的 SELinux 标签。这意味着该 pod 中的所有容器都可以读写使用 :Z 创建的容器中共享的卷。重新标记会遍历卷下的文件系统并更改每个文件上的标签，如果卷有数千个 inode，此过程需要很长时间，从而延迟容器的启动。如果以前使用 z 选项重新标记了卷，则 Podman 经过优化，不会第二次重新标记。如果将文件移入卷，则可以使用 chcon -Rt container_file_t PATH 命令手动更改标签。

注意：不要重新标记系统文件和目录。重新标记系统内容可能会导致机器上的其他受限服务失败。对于这些类型的容器，我们建议禁用 SELinux 隔离。选项 --security-opt label=disable 禁用容器的 SELinux 隔离。例如，如果用户想将整个主目录挂载到容器中，则需要禁用 SELinux 隔离。

$ podman create --security-opt label=disable -v $HOME:/home/user fedora touch /home/user/file

覆盖 卷 挂载

:O 标志告诉 Podman 使用 overlay file system 将主机上的目录挂载为临时存储。容器进程可以修改挂载点内的内容，这些内容存储在容器存储中的单独目录中。在覆盖方面，源目录是下层，容器存储目录是上层。对挂载点的修改在容器完成执行后会销毁，类似于取消挂载 tmpfs 挂载点。

对于高级用户，overlay 选项还支持覆盖挂载的自定义非易失性 upperdir 和 workdir。自定义 upperdir 和 workdir 可以由用户自己完全管理，Podman 不会在生命周期完成后删除它们。例如 :O,upperdir=/some/upper,workdir=/some/work

容器的后续执行将看到原始源目录内容，以前容器执行的任何更改都不复存在。

覆盖挂载的一个用例是将主机上的包缓存共享到容器中，以加速构建。

注意：O 标志与上面列出的其他选项冲突。

挂载到容器中的内容使用私有标签标记。在 SELinux 系统上，源目录中的标签必须可供容器标签读取。通常，容器可以读/执行 container_share_t 并可以读/写 container_file_t。如果无法更改源卷上的标签，则必须禁用 SELinux 容器隔离才能使容器正常工作。

不要修改使用覆盖挂载挂载到容器中的源目录，这会导致意外故障。仅在容器完成运行后修改目录。

挂载 传播

默认情况下，绑定挂载的卷是 private。这意味着在容器内部完成的任何挂载在主机上不可见，反之亦然。可以通过指定卷挂载传播属性来更改此行为。当卷是 shared 时，在容器内部该卷下完成的挂载在主机上可见，反之亦然。将卷设为 slave^[1] 仅启用单向挂载传播：在主机上该卷下完成的挂载在容器内部可见，但反之则不可见。

要控制卷的挂载传播属性，可以使用 [r]shared、[r]slave、[r]private 或 [r]unbindable 传播标志。传播属性只能为绑定挂载的卷指定，而不能为内部卷或命名卷指定。为了使挂载传播工作，源挂载点（源目录在其中挂载的挂载点）必须具有正确的传播属性。对于共享卷，源挂载点必须是共享的。对于从属卷，源挂载点必须是共享的或从属的。^[1]

要递归地将卷及其所有子挂载挂载到容器中，请使用 rbind 选项。默认情况下使用 bind 选项，源目录的子挂载不会挂载到容器中。

使用 copy 选项挂载卷会告诉 podman 将内容从底层目标目录复制到新创建的内部卷中。copy 仅在卷的初始创建时发生。当卷随后用于不同的容器时，内容不会被复制。copy 选项在绑定挂载上被忽略，没有任何效果。

使用 nosuid 选项挂载卷意味着卷上的 SUID 可执行文件不能由应用程序用来更改其权限。默认情况下，卷使用 nosuid 挂载。

使用 noexec 选项挂载卷意味着卷上的任何可执行文件都不能在容器内执行。

使用 nodev 选项挂载卷意味着卷上的任何设备都不能由容器内的进程使用。默认情况下，卷使用 nodev 挂载。

如果 HOST-DIR 是一个挂载点，那么内核会忽略 dev、suid 和 exec 选项。

使用 df HOST-DIR 找出源挂载，然后使用 findmnt -o TARGET,PROPAGATION source-mount-dir 找出源挂载的传播属性。如果 findmnt(1) 实用程序不可用，那么可以查看 /proc/self/mountinfo 中源挂载点的挂载条目。查看“可选字段”并查看是否指定了任何传播属性。在那里，shared:N 表示挂载是共享的，master:N 表示挂载是从属的，如果没有，则挂载是私有的。^[1]

要更改挂载点的传播属性，请使用 mount(8) 命令。例如，如果要绑定挂载源目录 /foo，可以执行 mount --bind /foo /foo 和 mount --make-private --make-shared /foo。这会将 /foo 转换为共享挂载点。或者，可以直接更改源挂载的传播属性。假设 / 是 /foo 的源挂载，那么使用 mount --make-shared / 将 / 转换为共享挂载。

注意：如果用户只通过组拥有访问权限，则从无根容器内部访问卷会失败。

Idmapped 挂载

如果指定了 idmap，则创建一个到容器中目标用户命名空间的 id 映射挂载。idmap 选项支持自定义映射，它可能与容器使用的用户命名空间不同。映射可以在 idmap 选项之后指定，例如：idmap=uids=0-1-10#10-11-10;gids=0-100-10。对于每个三元组，第一个值是映射到主机上的第二个值的备份文件系统 ID 的开始。此映射的长度在第三个值中给出。多个范围用 # 分隔。

使用 --group-add keep-groups 选项将用户的补充组访问权限传递到容器中。

--volumes-from=CONTAINER[:OPTIONS]

从指定的容器挂载卷。用于在容器之间共享卷。options 是一个逗号分隔的列表，包含以下可用元素

• rw|ro

• z

将已从源容器挂载的卷挂载到另一个容器上。CONTAINER 可以是名称或 ID。要共享卷，请在运行目标容器时使用 --volumes-from 选项。即使源容器未运行，也可以共享卷。

默认情况下，Podman 以与在源容器中挂载相同的模式（读写或只读）挂载卷。可以通过添加 ro 或 rw option 来更改此设置。

像 SELinux 这样的标签系统要求在挂载到容器中的卷内容上放置正确的标签。如果没有标签，安全系统可能会阻止容器内部运行的进程使用该内容。默认情况下，Podman 不会更改操作系统设置的标签。

要在容器上下文中更改标签，请在卷挂载中添加 z。此后缀告诉 Podman 重新标记共享卷上的文件对象。z 选项告诉 Podman 两个实体共享卷内容。因此，Podman 使用共享内容标签标记内容。共享卷标签允许所有容器读写内容。

如果源容器中的卷位置与目标容器上驻留的数据重叠，则该卷会隐藏目标容器上的该数据。

--workdir, -w=dir

容器内的工作目录。

在容器内运行二进制文件的默认工作目录是根目录 (/)。映像开发者可以使用 WORKDIR 指令设置不同的默认值。操作员可以使用 -w 选项覆盖工作目录。

示例

使用本地映像创建容器

$ podman create alpine ls

使用本地映像创建容器并对其进行注释

$ podman create --annotation HELLO=WORLD alpine ls

使用本地映像创建容器，分配一个伪终端，保持标准输入打开并将其命名为 myctr

  podman create -t -i --name myctr alpine ls

在新用户命名空间中运行容器需要映射主机上的 UID 和 GID

$ podman create --uidmap 0:30000:7000 --gidmap 0:30000:7000 fedora echo hello

设置自动用户命名空间分离容器

# podman create --userns=auto:size=65536 ubi8-init

在容器中配置时区

$ podman create --tz=local alpine date
$ podman create --tz=Asia/Shanghai alpine date
$ podman create --tz=US/Eastern alpine date

确保第一个容器 (container1) 运行后才启动第二个容器 (container2)

$ podman create --name container1 -t -i fedora bash
$ podman create --name container2 --requires container1 -t -i fedora bash
$ podman start --attach container2

创建需要多个容器的容器

$ podman create --name container1 -t -i fedora bash
$ podman create --name container2 -t -i fedora bash
$ podman create --name container3 --requires container1,container2 -t -i fedora bash
$ podman start --attach container3

使用通配符将容器内部的共享库公开为只读

$ podman create --mount type=glob,src=/usr/lib64/libnvidia\*,ro -i -t fedora /bin/bash

创建一个允许补充组访问卷的容器

$ podman create -v /var/lib/design:/var/lib/design --group-add keep-groups ubi8

使用 personality 选项配置容器的执行域

$ podman create --name container1 --personality=LINUX32 fedora bash

创建使用外部根文件系统作为覆盖挂载的容器

$ podman create --name container1 --rootfs /path/to/rootfs:O bash

创建一个连接到两个网络（称为 net1 和 net2）并具有静态 IP 的容器

$ podman create --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10 alpine ip addr

无根容器

Podman 在大多数系统上以非根用户身份运行。此功能要求安装新版本的 shadow-utils。shadow-utils 包必须包含 newuidmap 和 newgidmap 可执行文件。

为了让用户运行无根，必须在 /etc/subuid 和 /etc/subgid 中为其用户名创建一个条目，其中列出了其用户命名空间的 UID。

如果安装了 fuse-overlayfs 和 slirp4netns 包，则无根 Podman 的效果更好。fuse-overlayfs 包提供了一个用户空间覆盖存储驱动程序，否则用户需要使用 vfs 存储驱动程序，这在磁盘空间上可能很昂贵，并且性能不如其他驱动程序。

要在容器上启用 VPN，需要指定 slirp4netns 或 pasta；如果没有，则需要使用 --network=host 标志运行容器。

环境

可以使用多种不同的选项设置容器内的环境变量：本节描述优先级。

优先级顺序（后面的条目覆盖前面的条目）

• --env-host : 添加执行 Podman 的进程的主机环境。

• --http-proxy: 默认情况下，一些环境变量会从主机传递进来，例如 http_proxy 和 no_proxy。查看 --http-proxy 获取更多详细信息。

• 容器镜像：容器镜像中指定的任何环境变量。

• --env-file: 通过 env 文件指定的任何环境变量。如果指定了多个文件，则它们会按顺序覆盖彼此。

• --env: 指定的任何环境变量都会覆盖之前的设置。

创建容器并设置以 * 结尾的环境变量。当没有指定值时，尾部的 * 通配符功能才会生效。

$ export ENV1=a
$ podman create --name ctr1 --env 'ENV*' alpine env
$ podman start --attach ctr1 | grep ENV
ENV1=a
$ podman create --name ctr2 --env 'ENV*=b' alpine env
$ podman start --attach ctr2 | grep ENV
ENV*=b

CONMON

当 Podman 启动容器时，它实际上会执行 conmon 程序，然后 conmon 程序会执行 OCI 运行时。Conmon 是容器监控器。它是一个小程序，其作用是监视容器的主进程，如果容器退出，则保存退出代码。它还会保持容器的 tty 打开，以便以后可以连接到它。这使 Podman 能够以分离模式（后台运行）运行，因此 Podman 可以退出，但 conmon 继续运行。每个容器都有自己的 conmon 实例。Conmon 等待容器退出，收集并保存退出代码，然后启动一个 Podman 进程来完成容器清理，方法是关闭网络和存储。有关 conmon 的更多信息，请参阅 conmon(8) 手册页。

文件

/etc/subuid /etc/subgid

注意：使用环境变量 TMPDIR 来更改下载的容器镜像的临时存储位置。Podman 默认使用 /var/tmp。

另请参见

podman(1), podman-save(1), podman-ps(1), podman-attach(1), podman-pod-create(1), podman-port(1), podman-start(1), podman-kill(1), podman-stop(1), podman-generate-systemd(1), podman-rm(1), subgid(5), subuid(5), containers.conf(5), systemd.unit(5), setsebool(8), slirp4netns(1), pasta(1), fuse-overlayfs(1), proc(5), conmon(8), personality(2)

故障排除

有关常见问题的解决方案，请参阅 podman-troubleshooting(7)。

有关无根问题的解决方案，请参阅 podman-rootless(7)。

历史

2017 年 10 月，由 Dan Walsh 将 Docker 文档转换为 Podman，用于 Podman <[email protected]>

2014 年 11 月，由 Sven Dowideit 更新 <[email protected]>

2014 年 9 月，由 Sven Dowideit 更新 <[email protected]>

2014 年 8 月，由 Sven Dowideit 更新 <[email protected]>

脚注

1: Podman 项目致力于包容性，这是开源的核心价值观。这里使用的 master 和 slave 挂载传播术语存在问题，并且具有争议性，需要更改。但是，这些术语当前在 Linux 内核中使用，因此目前必须按原样使用。当内核维护者纠正此用法时，Podman 将立即随之改变。