名称¶

podman-run - 在新容器中运行命令

简介¶

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

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

描述¶

在新容器中运行一个进程。podman run 启动一个拥有自己文件系统、自己网络和自己隔离进程树的进程。启动进程的镜像可以定义与将在容器中运行的进程、要暴露的网络等相关的默认值，但 podman run 将最终控制权交给从镜像启动容器的操作员或管理员。因此，podman run 比任何其他 Podman 命令都有更多选项。

如果镜像尚未加载，则 podman run 将从仓库中拉取该镜像及其所有镜像依赖项，其方式与运行 podman pull 镜像相同，然后再从该镜像启动容器。

容器内将自动创建几个文件。这些文件包括 /etc/hosts、/etc/hostname 和 /etc/resolv.conf 用于管理网络。这些文件将基于主机的版本，尽管可以通过选项进行自定义（例如，--dns 可以覆盖创建的 resolv.conf 中的主机 DNS 服务器）。此外，每个容器中都会创建一个容器环境文件，以指示程序正在容器中运行。此文件位于 /run/.containerenv（对于 FreeBSD 容器为 /var/run/.containerenv）。使用 --privileged 标志时，.containerenv 包含名称/值对，指示容器引擎版本、引擎是否以无根模式运行、容器名称和 ID，以及容器所基于的镜像名称和 ID。注意：当卷挂载到 /run 时，将不会创建 /run/.containerenv。

当从用户定义的网络命名空间运行时，如果 /etc/netns/NSNAME/resolv.conf 存在，则将使用它，否则将使用 /etc/resolv.conf。

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

镜像¶

镜像使用 transport:path 格式指定。如果未指定传输方式，则默认使用 docker（容器注册表）传输方式。对于远程 Podman，包括 Mac 和 Windows（不包括 WSL2）机器，docker 是唯一允许的传输方式。

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

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

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

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

docker-archive:path[:docker-reference] 存储在 docker save 格式文件中的镜像。docker-reference 仅在创建此类文件时使用，并且不得包含摘要。

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

注意：在远程客户端上，包括 Mac 和 Windows（不包括 WSL2）机器，不支持此传输方式。

docker-daemon:docker-reference 以 docker-reference 格式存储在 docker 守护程序内部存储中的镜像。docker-reference 也可以是镜像 ID (docker-daemon:algo:digest)。

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

注意：在远程客户端上，包括 Mac 和 Windows（不包括 WSL2）机器，不支持此传输方式。

oci-archive:path:tag 符合“开放容器镜像布局规范”并在指定路径和指定标签的目录中的镜像。

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

注意：在远程客户端上，包括 Mac 和 Windows（不包括 WSL2）机器，不支持此传输方式。

选项¶

--add-host=hostname[;hostname[;…]]:ip¶

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

该选项接受一个或多个以分号分隔的主机名，这些主机名将被映射到以冒号分隔的单个 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 地址。

Podman 还使用 host-gateway 地址自动将 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=key=value¶

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

--arch=ARCH¶

覆盖要拉取镜像的架构，默认为主机架构。例如，arm。除非被覆盖，否则后续在本地存储中查找同一镜像时将匹配此架构，无论主机如何。

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

附加到 STDIN、STDOUT 或 STDERR。

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

--authfile=path¶

认证文件的路径。在 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=path 完成。

--blkio-weight=权重¶

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

在 cgroups V1 的无根（rootless）系统上不支持此选项。

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

块 IO 相对设备权重。

--cap-add=能力¶

添加 Linux 能力。

授予额外的能力会增加容器内运行进程的权限，并可能允许其突破限制。CAP_SYS_ADMIN、CAP_SYS_PTRACE、CAP_MKNOD 和 CAP_SYS_MODULE 等能力在未在用户命名空间内使用时尤其危险。请参阅 user_namespaces(7) 以获取有关用户命名空间和能力之间交互的更详细解释。

在添加任何能力之前，请审查其安全隐患并确保其对于容器的功能确实必要。有关更多信息，请参阅 capabilities(7)。

--cap-drop=能力¶

从默认的 podman 能力集中删除这些能力，或者使用 all 删除所有能力。

这是一个以空格分隔的能力列表。

--cert-dir=path¶

使用 path (*.crt, *.cert, *.key) 中的证书连接到注册表。（默认值：/etc/containers/certs.d）有关详细信息，请参阅 containers-certs.d(5)。（此选项不适用于远程 Podman 客户端，包括 Mac 和 Windows（不包括 WSL2）机器）

--cgroup-conf=KEY=VALUE¶

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

--cgroup-parent=path¶

创建 cgroup 的 cgroup 路径。如果路径不是绝对路径，则该路径被视为相对于 init 进程的 cgroup 路径。如果 cgroup 不存在，则会创建它们。

--cgroupns=模式¶

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

host：在容器内使用主机的 cgroup 命名空间。
container:id：加入指定容器的命名空间。
private：创建一个新的 cgroup 命名空间。
ns:path：加入指定路径的命名空间。

如果主机使用 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，一个用于容器负载。不能将 --cgroup-parent 与 split 一起设置。

--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 的无根（rootless）系统上不支持此选项。

--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 的无根（rootless）系统上不支持此选项。

--cpu-rt-period=微秒¶

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

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

此选项仅在 cgroups V1 rootful 系统上受支持。

--cpu-rt-runtime=微秒¶

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

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

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

此选项仅在 cgroups V1 rootful 系统上受支持。

--cpu-shares, -c=shares¶

CPU 份额（相对权重）。

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

该比例仅在 CPU 密集型进程运行时适用。当一个容器中的任务处于空闲状态时，其他容器可以使用剩余的 CPU 时间。实际的 CPU 时间量取决于系统上运行的容器数量。

例如，考虑三个容器，一个的 cpu-share 为 1024，另外两个的 cpu-share 设置为 512。当所有三个容器中的进程都尝试使用 100% 的 CPU 时，第一个容器获得总 CPU 时间的 50%。如果添加第四个 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 的无根（rootless）系统上不支持此选项。

--cpus=数字¶

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 的无根（rootless）系统上不支持此选项。

--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 的无根（rootless）系统上不支持此选项。

--cpuset-mems=nodes¶

允许执行的内存节点（MEMs）（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 的无根（rootless）系统上不支持此选项。

--creds=[username[:password]]¶

用于向镜像仓库进行身份验证的 [username[:password]]（如果需要）。如果未提供一个或两个值，则会出现命令行提示，可以输入该值。密码输入时无回显。

请注意，指定的凭据仅用于针对目标注册表进行身份验证。它们不用于镜像或注册表被重写时（请参阅 containers-registries.conf(5)）；要针对这些注册表进行身份验证，请考虑使用 containers-auth.json(5) 文件。

--decryption-key=key[:passphrase]¶

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

--detach, -d¶

分离模式：在后台运行容器并打印新的容器 ID。默认值为 false。

随时在另一个 shell 中运行 podman ps 以查看正在运行的容器列表。使用 podman attach 命令重新连接到分离的容器。

通过 tty 模式连接时，使用可配置的按键序列从容器分离（并使其保持运行）。默认序列是 ctrl-p,ctrl-q。使用 --detach-keys 选项指定按键序列，或在 containers.conf 文件中配置：有关更多信息，请参阅 containers.conf(5)。

--detach-keys=序列¶

指定分离容器的按键序列。格式为单个字符 [a-Z] 或一个或多个 ctrl-<value> 字符，其中 <value> 是以下之一：a-z、@、^、[、, 或 _。指定 “” 会禁用此功能。默认值为 ctrl-p,ctrl-q。

此选项也可以在 containers.conf(5) 文件中设置。

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

向容器添加一个主机设备。格式为 HOST-DEVICE[:CONTAINER-DEVICE][:PERMISSIONS]，其中 HOST-DEVICE 是主机上设备节点的路径，CONTAINER-DEVICE 是容器中设备节点的路径，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（全部）、c（字符）或 b（块）；
major 和 minor：数字，或 * 表示全部；
mode：由 r（读取）、w（写入）和 m（mknod(2)）组成的。

--device-read-bps=路径:速率¶

限制从设备读取速率（每秒字节数）（例如 --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 的无根（rootless）系统上不支持此选项。

--device-read-iops=路径:速率¶

限制从设备读取速率（每秒 IO 操作数）（例如 --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 的无根（rootless）系统上不支持此选项。

--device-write-bps=路径:速率¶

限制写入设备的速率（每秒字节数）（例如 --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 的无根（rootless）系统上不支持此选项。

--device-write-iops=路径:速率¶

限制写入设备的速率（每秒 IO 操作数）（例如 --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 的无根（rootless）系统上不支持此选项。

--disable-content-trust¶

这是一个 Docker 特定的选项，用于禁用对容器仓库的镜像验证，Podman 不支持此选项。此选项是一个空操作（NOOP），仅为脚本兼容性而提供。

--dns=ipaddr¶

设置自定义 DNS 服务器。

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

可以指定特殊值 none 来禁止 Podman 在容器中创建 /etc/resolv.conf。然后，镜像中的 /etc/resolv.conf 文件将不加修改地使用。

请注意，ipaddr 可以直接添加到容器的 /etc/resolv.conf。但这并非必然。例如，将 dns_enabled 设置为 true 的自定义网络传递给 --network 将导致 /etc/resolv.conf 仅引用 aardvark-dns 服务器。然后 aardvark-dns 会将所有非容器名称查询转发到提供的 ipaddr。

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

--dns-option=option¶

设置自定义 DNS 选项。如果将 --dns-option 与设置为 none 或 container:id 的 --network 一起使用，则无效。

--dns-search=domain¶

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

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

覆盖镜像的默认 ENTRYPOINT。

镜像的 ENTRYPOINT 类似于 COMMAND，因为它指定容器启动时要运行的可执行文件，但它（有意地）更难覆盖。ENTRYPOINT 赋予容器其默认性质或行为。设置 ENTRYPOINT 后，容器就像那个二进制文件一样运行，带有默认选项。可以通过 COMMAND 传递更多选项。但是，如果用户想在容器内运行其他内容，**--entrypoint=.**选项允许指定新的 ENTRYPOINT。

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

--env, -e=环境变量¶

设置环境变量。

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

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

--env-file=文件¶

读取包含一行一个环境变量的文件。

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

--env-host¶

在容器内部使用主机环境。有关优先级，请参见下面的 Environment 说明。（此选项不适用于远程 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=[标志]容器_uid:起始_uid[:数量]¶

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

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

--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=间隔¶

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

注意：此参数将覆盖镜像中相关的健康检查配置。

--health-log-destination=目录路径¶

设置健康检查日志的目标。目录路径，本地或 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=操作¶

容器转换为不健康状态后要执行的操作。默认值为 none。

none：不采取任何行动。
kill：终止容器。
restart：重新启动容器。请勿将 restart 操作与 --restart 标志结合使用。在 systemd 单元内部运行时，请考虑使用 kill 或 stop 操作，以利用 systemd 的重启策略。
stop：停止容器。

--health-retries=重试次数¶

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

注意：此参数可以覆盖镜像中的健康检查配置。

--health-start-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=间隔¶

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

--health-startup-retries=重试次数¶

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

--health-startup-success=重试次数¶

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

--health-startup-timeout=超时¶

启动健康检查命令完成前的最长时间，超过此时间将被标记为失败。该值可以以时间格式表示，例如 2m3s。默认值为 30s。

--health-timeout=超时¶

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

注意：超时会将健康检查标记为失败。如果健康检查命令本身运行时间超过指定的超时，它将被发送 SIGKILL 信号。

注意：此参数将覆盖镜像中相关的健康检查配置。

--help¶

打印用法说明

--hostname, -h=名称¶

设置容器内部的主机名。

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

--hosts-file=路径 | none | image¶

在容器内部创建 /etc/hosts 文件的基础文件。这必须是主机系统上文件的绝对路径，或者是以下特殊标志之一：“”遵循 containers.conf 中的 base_hosts_file 配置（默认）none 不使用基础文件（即从空文件开始）image 使用容器镜像的 /etc/hosts 文件作为基础文件

--hostuser=名称¶

将主机上的用户帐户添加到容器中的 /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-path=路径¶

container-init 二进制文件的路径。

--interactive, -i¶

设置为 true 时，使 stdin 可用于所包含的进程。如果为 false，所包含进程的 stdin 将为空并立即关闭。

如果已附加，stdin 将管道传输到所包含的进程。如果已分离，读取 stdin 将阻塞，直到稍后附加。

注意： Podman 会在 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=键=值¶

为容器添加元数据。

--label-file=文件¶

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

--link-local-ip=ip¶

未实现。

--log-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=名称=值¶

日志驱动程序特定选项。

设置自定义日志配置。支持以下名称：

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=地址¶

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

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

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

--memory, -m=number[unit]¶

内存限制。unit 可以是 b (字节)，k (千字节)，m (兆字节)，或 g (吉字节)。

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

在 cgroups V1 的无根（rootless）系统上不支持此选项。

--memory-reservation=数字[单位]¶

内存软限制。单位可以是 b（字节）、k（千字节）、m（兆字节）或 g（吉字节）。

设置内存预留后，当系统检测到内存争用或内存不足时，容器将被强制将其消耗限制在其预留范围内。因此，始终将值设置在 --memory 以下，否则硬限制优先。默认情况下，内存预留与内存限制相同。

在 cgroups V1 的无根（rootless）系统上不支持此选项。

--memory-swap=number[unit]¶

一个等于内存加交换空间的限制值。unit 可以是 b (字节)，k (千字节)，m (兆字节)，或 g (吉字节)。

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

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

在 cgroups V1 的无根（rootless）系统上不支持此选项。

--memory-swappiness=数字¶

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

此标志仅在 cgroups V1 rootful 系统上受支持。

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

将文件系统挂载到容器。

当前支持的挂载类型有 artifact、bind、devpts、glob、image、ramfs、tmpfs 和 volume。

所有挂载类型通用的选项

src、source：bind、glob 和 volume 的挂载源规范。对于 artifact、bind、glob、image 和 volume 来说是强制性的。
dst、dest、destination、target：挂载目标规范。

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

特定于 type=artifact 的选项

digest：如果 artifact source 包含多个 blob，可以指定 digest 以仅挂载具有该 digest 的特定 blob。
title：如果 artifact source 包含多个 blob，可以设置一个 title，它将与 org.opencontainers.image.title 注释进行比较。
name：这可以用于覆盖我们在容器内部用于挂载的文件名。对于单个 blob artifact，如果 dst 是目录，则名称按原样使用，否则忽略。对于多 blob artifact，名称将与索引后缀 <name>-x 一起使用，其中 x 是 artifact 中的层索引，从 0 开始。

src 参数包含 artifact 的名称，该 artifact 必须已在本地存在。dst 参数包含目标路径，如果容器中的路径是目录，则 blob 标题（org.opencontainers.image.title 注释）将用作文件名并连接到路径。如果注释不存在，则 digest 将用作文件名。这会导致 artifact 的所有 blob 都挂载到容器中给定路径。

但是，如果 dst 路径是容器中已有的文件，那么 blob 将直接挂载到该文件上。这仅在 artifact 包含单个 blob 或指定了 digest 或 title 时才有效。

如果 dst 路径在容器中尚不存在，则如果 artifact 包含单个 blob，它将像现有文件情况一样直接挂载到该路径。如果 artifact 具有多个 blob，它将像现有目录情况一样将每个 blob 作为文件挂载到 dst 路径中。

特定于 type=volume 的选项

ro, readonly：true 或 false（未指定时的默认值：false）。
U, chown：true 或 false（未指定时的默认值：false）。根据容器的 UID 和 GID 递归更改源卷的所有者和组。
idmap：如果指定，则在容器中的目标用户命名空间创建 idmapped 挂载。idmap 选项仅在 rootful 模式下由 Podman 支持。Linux 内核不允许非特权用户使用 idmapped 文件系统。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，则在容器中的目标用户命名空间创建 idmapped 挂载。idmap 选项仅在 rootful 模式下由 Podman 支持。
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 启用 copyup。默认使用。
noatime：读取文件时禁用更新文件访问时间。
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=artifact,src=quay.io/libpod/testartifact:20250206-single,dst=/data
type=artifact,src=quay.io/libpod/testartifact:20250206-multi,dst=/data,title=test1

--name=名称¶

为容器分配一个名称。

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

UUID 长标识符（“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”）；
UUID 短标识符（“f78375b1c487”）；
名称（“jonah”）。

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

--network=mode, --net¶

设置容器的网络模式。

有效的 mode 值为：

bridge[:OPTIONS,…]：在默认网桥上创建网络堆栈。这是 rootful 容器的默认设置。可以指定以下附加选项：
- alias=名称：为容器添加网络范围别名。
- ip=IPv4：为该容器指定静态 IPv4 地址。
- ip6=IPv6：为该容器指定静态 IPv6 地址。
- mac=MAC：为该容器指定静态 MAC 地址。
- interface_name=名称：为容器内创建的网络接口指定名称。
- host_interface_name=名称：为容器外创建的网络接口指定名称。
任何其他选项将不经验证地直接传递给 netavark。这对于向 netavark 插件传递参数可能很有用。

例如，要设置静态 ipv4 地址和静态 mac 地址，请使用 --network bridge:ip=10.88.0.10,mac=44:33:22:11:00:99。
<网络名称或 ID>[:选项,...]：连接到用户定义网络；这是由 podman network create 创建的网络名称或 ID。可以指定与上述 bridge 模式下描述的相同选项。多次使用 --network 选项以指定附加网络。
为了向后兼容，也可以在第一个 --network 参数上指定以逗号分隔的网络，但这会阻止您使用上面 bridge 部分描述的选项。
none：为容器创建一个网络命名空间，但不为其配置网络接口，因此容器没有网络连接。
container:id：重用另一个容器的网络堆栈。
host：为容器使用主机的网络命名空间，而不是创建隔离的命名空间。警告：这会使容器完全访问抽象的 Unix 域套接字和绑定到 localhost 的 TCP/UDP 套接字。由于这些机制通常用于防止访问敏感系统服务，从而将其与外部实体访问隔离，因此使用此选项可能被视为安全漏洞。
ns:path：要加入的网络命名空间的路径。
private：为容器创建一个新的命名空间。这会为 rootful 容器使用 bridge 模式，为 rootless 容器使用 slirp4netns。
slirp4netns[:选项,...]：使用 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=接口：指定 slirp 绑定到的出站接口（仅限 ipv4 流量）。
- outbound_addr=IPv4：指定 slirp 绑定到的出站 ipv4 地址。
- outbound_addr6=接口：指定 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 接口名称，都从主机复制。端口转发保留了原始源 IP 地址。pasta(1) 中描述的选项可以作为逗号分隔的参数指定。
在 pasta(1) 选项方面，默认情况下给出 --config-net，以便在容器启动时配置网络，并且默认也假设 --no-map-gw，以避免容器通过网关地址直接访问主机。后者可以通过在 pasta 特定选项中传递 --map-gw 来覆盖（尽管它不是一个实际的 pasta(1) 选项）。
为了更好地与DNS处理集成，传递了--dns-forward 169.254.1.1，此地址将作为第一个解析器添加到resolv.conf(5)中。如果需要使用不同的IP地址，可以显式传递--dns-forward。为了使host.containers.internal /etc/hosts条目生效并允许连接到主机，传递了--map-guest-addr 169.254.1.2。同样，可以显式设置以选择不同的IP地址。
此外，如果未配置从主机到容器的TCP或UDP端口转发（通过Podman的--publish或直接传递pasta的-t/-u选项），则分别传递-t none和-u none以禁用基于绑定端口的自动端口转发。类似地，给出-T none和-U none以禁用从容器到主机的相同功能。
所有选项都可以在containers.conf(5)中设置；请参阅该文件中网络部分下的pasta_options键。
一些示例：
- 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 接口以提高性能

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

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

--network-alias=alias¶

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

--no-healthcheck¶

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

--no-hostname¶

不在容器中创建 /etc/hostname 文件。

默认情况下，Podman 管理 /etc/hostname 文件，添加容器自己的主机名。当设置 --no-hostname 选项时，如果镜像的 /etc/hostname 文件存在，它将保持不变。

--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¶

与--user选项结合使用时，允许Podman向/etc/passwd和/etc/group添加条目。这用于覆盖Podman提供的用户设置，以支持libnss-extrausers等入口点配置。

--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中运行时，基础容器会首先启动。

--preserve-fd=FD1[,FD2,…]¶

将逗号分隔列表中指定的额外文件描述符传递给进程。它可以指定多次。此选项仅在crun OCI运行时支持。在其他OCI运行时使用此选项可能存在安全风险。

（此选项不适用于远程Podman客户端，包括Mac和Windows（WSL2除外）机器）

--preserve-fds=N¶

将N个额外的文件描述符（除了0、1、2之外）传递给进程。总共的FD为3+N。（此选项不适用于远程Podman客户端，包括Mac和Windows（WSL2除外）机器）

--privileged¶

为此容器赋予扩展权限。默认值为 false。

默认情况下，Podman容器是非特权的（=false），例如无法修改操作系统的一部分。这是因为默认情况下，容器只允许有限地访问设备。“特权”容器被授予与启动容器的用户相同的设备访问权限，但在systemd模式下（--systemd=always），虚拟控制台（/dev/tty\d+）除外。

特权容器会关闭将容器与主机隔离的安全功能。禁用了丢弃的能力、受限的设备、只读挂载点、Apparmor/SELinux隔离和Seccomp过滤器。由于禁用了安全功能，几乎不应设置特权字段，因为容器很容易突破限制。

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

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

将容器的一个端口或一系列端口发布到主机。

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

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

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

无需指定主机端口（例如podman run -p 127.0.0.1::80）。如果未指定，则容器端口将随机分配主机上的一个端口。

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

端口发布仅支持通过bridge网络或pasta和slirp4netns网络模式使用其自己的网络命名空间的容器。

注意：如果容器在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）。基于Intel资源目录技术（RDT）功能集中的缓存分配技术（CAT）功能，所有容器进程都将在预配置的COS中运行，该COS代表缓存的一部分。COS必须使用resctrl内核驱动程序提供的伪文件系统（通常挂载在/sys/fs/resctrl）创建和配置。将容器分配给COS需要root权限，因此在无根环境中无法工作。目前，该功能仅支持使用runc作为运行时。有关在将容器分配给COS之前创建COS的更多详细信息，请参阅https://docs.linuxkernel.org.cn/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-quadlet(7)和systemd.service(5)。

--retry=attempts¶

在仓库和本地存储之间拉取或推送镜像失败时重试的次数。默认为 3。

--retry-delay=duration¶

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

--rm¶

容器退出时自动移除容器及其所有匿名未命名卷。默认值为false。

--rmi¶

容器退出后，移除镜像，除非有其他容器正在使用它。隐含对新容器的--rm。默认值为false。

--rootfs¶

如果指定，第一个参数指的是文件系统上已解压的容器。

这对于运行不需要任何镜像管理的容器很有用，容器的rootfs假定由外部管理。

Overlay 根文件系统挂载

:O标志告诉Podman使用overlay file system将rootfs路径中的目录作为存储挂载。容器进程可以修改挂载点内的内容，这些内容存储在容器存储中的单独目录中。在overlay术语中，源目录是下层，容器存储目录是上层。挂载点的修改在容器执行完成后被销毁，类似于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选项从Podman自身及其子进程的环境中移除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密钥或其他重要的通用字符串或二进制内容（大小不超过512 KB）。

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

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

机密选项

type=mount|env：机密如何暴露给容器。mount将机密作为文件挂载到容器中。env将机密作为环境变量暴露。默认为mount。
target=target：机密的目标。对于挂载的机密，这是容器内机密的路径。如果提供了完全限定路径，则机密将挂载到该位置。否则，机密将挂载到Linux容器的/run/secrets/target或FreeBSD容器的/var/run/secrets/target。如果未设置目标，机密默认挂载到/run/secrets/secretname。对于env机密，这是环境变量键。默认为secretname。
uid=0：机密的UID。默认为0。仅限挂载机密类型。
gid=0：机密的GID。默认为0。仅限挂载机密类型。
mode=0：机密的模式。默认为0444。仅限挂载机密类型。

示例

以UID 1挂载到/my/location/mysecret

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

以模式0777挂载到/run/secrets/customtarget

--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，容器也会将SELinux视为禁用。容器被阻止设置任何标签。
mask=/path/1:/path/2：用冒号分隔的掩码路径。容器内无法访问掩码路径。
no-new-privileges：禁用容器进程通过execve(2)系统调用（例如通过setuid或setgid位，或通过文件功能）获取额外权限。依赖于其可执行文件上设置的setuid/setgid位来更改用户ID或组ID的程序将无法再这样做，并且添加到可执行文件的任何文件功能（例如通过setcap）都不会添加到允许的功能集中。有关详细信息，请参阅：https://docs.linuxkernel.org.cn/userspace-api/no_new_privs.html。
seccomp=unconfined：关闭容器的seccomp限制。
seccomp=profile.json：用作seccomp过滤器的JSON文件。请注意，io.podman.annotations.seccomp注释将设置为指定值，如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（千字节）、m（兆字节）或g（千兆字节）。如果省略单位，系统将使用字节。如果省略大小，默认值为64m。当size为0时，对容器用于IPC的内存量没有限制。此选项与--ipc=host冲突。

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

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

--sig-proxy¶

将接收到的信号代理到容器进程。SIGCHLD、SIGURG、SIGSTOP 和 SIGKILL 不会代理。

默认值为true。

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

注意：不允许上述sysctls。

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

注意：不允许上述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个字符。
使用--privileged运行时，Podman不挂载虚拟控制台（/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发送终止信号之前的最大运行时间。默认情况下，容器会一直运行直到退出或被podman stop停止。

--tls-verify¶

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

--tmpfs=fs¶

创建tmpfs挂载。

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

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

此命令将tmpfs挂载到容器内的/tmp。支持的挂载选项与Linux默认挂载标志相同。如果未指定任何选项，系统将使用以下选项：rw,noexec,nosuid,nodev。

--tty, -t¶

分配一个伪 TTY。默认值为 false。

当设置为 true 时，Podman 分配一个伪 TTY 并将其附加到容器的标准输入。例如，这可以用于运行一次性交互式 shell。

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

echo "asdf" | podman run --rm -i someimage /bin/cat

--tz=timezone¶

在容器中设置时区。此标志接受基于区域的时区、GMT时间以及local，后者将容器中的时区设置为与主机匹配。有关有效时区，请参阅/usr/share/zoneinfo/。远程连接使用本地containers.conf中的默认值

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

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

可选flags的可能值在本页下方进一步讨论。amount值是可选的，如果未给出则假定为1。

from_uid值基于运行命令的用户，无论是rootful用户还是rootless用户。

rootful用户：[flags]container_uid:host_uid[:amount]
rootless用户：[flags]container_uid:intermediate_uid[:amount]

Rootful 映射

当特权用户调用**podman**时，选项--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

无根映射

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

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

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

第一个映射步骤由Podman从文件/etc/subuid的内容和调用Podman的用户的UID派生。

第一个映射步骤

主机UID	中间UID
Podman用户的UID	0
第1个辅助UID	1
第2个辅助UID	2
第3个辅助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

在无根模式下运行时，Podman使用/etc/subuid文件中配置的所有范围。

当前用户ID映射到无根用户命名空间中的UID=0。每个附加范围随后按顺序添加

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

引用父命名空间中的主机ID

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

Podman可以通过在映射中的主机ID前加上@符号来执行此操作。例如，通过指定--gidmap 100000:@2000:1，podman将查找与主机ID 2000对应的中间ID，并将其映射到容器ID 100000。给定的主机ID必须已分配了辅助ID（否则它最初不会被映射到中间空间）。

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

扩展先前的映射

一些映射修改可能很麻烦。例如，用户从映射--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"

此标志的一个特定用例是在无根用户的上下文中。无根用户可以指定带有+标志的映射，例如--gidmap="+100000:1:1"。Podman随后将从零开始“填补空白”，填充所有剩余的中间ID。当用户想要将特定的中间ID映射到容器ID，而将其余辅助ID留给Podman随意映射时，这很方便。

仅传递 --uidmap 或 --gidmap 之一

通常，辅助用户ID和组ID同时分配，并且对于任何用户，辅助用户ID都与辅助组ID匹配。为方便起见，如果仅给出--uidmap或--gidmap之一，podman假定映射同时指UID和GID，并将给定映射应用于两者。如果只需要更改其中一个值，映射应包含u或g标志以指定它们仅适用于UID或GID，而不应复制。

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

例如，给定命令

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

由于未给出--uidmap，因此--gidmap被复制到--uidmap，得到等效命令

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

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

无根附加主机GID映射

无根用户可能希望映射一个已在/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" ...

无辅助UID

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

Podman

--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=用户[:组]¶

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

如果没有此参数，命令将以容器镜像中指定的用户身份运行。除非被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=Key 映射

键	主机用户	容器用户
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范围。示例：containers:2147483647:2147483648。
rootless mode：将使用/etc/subuid和/etc/subgid文件中的用户范围。请注意，在不使用--userns=auto的情况下运行单个容器将使用整个UID范围，并且不允许进一步细分。请参阅subuid(5)。

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

选项--userns=keep-id使用用户的所有辅助UID和辅助GID。选项--userns=nomap使用用户的所有辅助UID和辅助GID，除了用户自己的ID。在启动新容器时，只要存在使用--userns=nomap或--userns=keep-id且未限制用户命名空间大小的容器，则使用--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。有关详细信息，请参阅--uidmap。

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

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

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

有效的keep-id选项

uid=UID：覆盖容器内部的UID，用于映射当前用户。
gid=GID：覆盖容器内部的GID，用于映射当前用户。
size=SIZE：覆盖配置用户命名空间的大小。这对于避免耗尽所有可用ID很有用。在以root身份运行时不支持。

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选项，分别以只读或读写模式挂载卷。默认情况下，卷以读写模式挂载。请参阅示例。

Chowning Volume Mounts（更改卷挂载的属主）

当命名卷首次挂载到容器时，Podman在容器初始化期间会自动调整卷挂载点的所有权。此chown操作在以下条件下发生

卷尚未使用（NeedsChown设置为true）
卷为空或尚未复制
卷不受外部卷驱动程序管理
卷驱动程序不是“image”

对于具有id映射挂载（使用idmap选项）的卷，所有权更改会考虑容器的用户命名空间映射，但id映射卷保留正确的UID/GID映射。对于没有id映射的卷，挂载点会更改所有权以匹配容器的进程用户和组，如果启用了用户命名空间重新映射，则映射到主机用户命名空间。

如果在新的用户命名空间中创建容器，容器中的UID和GID可能与主机上的另一个UID和GID相对应。

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

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

Labeling Volume Mounts（为卷挂载添加标签）

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  --security-opt label=disable -v $HOME:/home/user fedora touch /home/user/file

Overlay Volume Mounts（覆盖卷挂载）

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

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

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

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

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

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

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

挂载传播

默认情况下，绑定挂载的卷是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 / 将 / 转换为共享挂载。

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

ID映射挂载

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

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

--volumes-from=容器[:选项]¶

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

rw|ro
z

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

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

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

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

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

--workdir, -w=目录¶

容器内的工作目录。

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

退出状态¶

podman run 的退出代码提供了容器运行失败或退出的原因信息。当 podman run 以非零代码退出时，退出代码遵循 chroot(1) 标准，请参见下文

125 错误出在 Podman 本身

$ podman run --foo busybox; echo $?
Error: unknown flag: --foo
125

126 容器化命令 无法调用

$ podman run busybox /etc; echo $?
Error: container_linux.go:346: starting container process caused "exec: \"/etc\": permission denied": OCI runtime error
126

127 容器化命令 找不到

$ podman run busybox foo; echo $?
Error: container_linux.go:346: starting container process caused "exec: \"foo\": executable file not found in $PATH": OCI runtime error
127

退出代码 包含的命令退出代码

$ podman run busybox /bin/sh -c 'exit 3'; echo $?
3

示例¶

以只读模式运行容器¶

在容器镜像开发过程中，容器通常需要写入镜像内容。例如，将软件包安装到 /usr。在生产环境中，应用程序很少需要写入镜像。如果容器应用程序需要写入文件系统，则会写入卷。通过使用 --read-only 开关以只读模式运行应用程序，可以提高其安全性。这可以保护容器镜像免受修改。默认情况下，只读容器可以写入临时数据。Podman 在容器内的 /run 和 /tmp 上挂载一个 tmpfs。

$ podman run --read-only -i -t fedora /bin/bash

如果容器不写入容器内的任何文件系统，包括 tmpfs，请设置 --read-only-tmpfs=false。

$ podman run --read-only --read-only-tmpfs=false --tmpfs /run -i -t fedora /bin/bash

使用 glob 将共享库暴露为只读¶

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

将容器的日志消息暴露给主机的日志¶

绑定挂载 /dev/log 目录，以便容器中记录的消息显示在主机的 syslog/journal 中。

$ podman run -v /dev/log:/dev/log -i -t fedora /bin/bash

从容器内部通过发送消息到日志来测试此功能。

(bash)# logger "Hello from my container"

然后退出并检查日志。

(bash)# exit

$ journalctl -b | grep Hello

这列出了发送到日志记录器的消息。

连接到一个或多个 STDIN、STDOUT、STDERR¶

如果不指定 -a 选项，Podman 会连接所有内容（stdin、stdout、stderr）。通过指定 -a（stdin、stdout、stderr）来覆盖默认值，例如

$ podman run -a stdin -a stdout -i -t fedora /bin/bash

映射端口以供外部使用¶

应用程序的暴露端口可以使用 -p 标志映射到主机端口。例如，httpd 的端口 80 可以使用以下命令映射到主机端口 8080

$ podman run -p 8080:80 -d -i -t fedora/httpd

挂载外部卷¶

要将主机目录挂载为容器卷，请指定目录的绝对路径和容器目录的绝对路径，并用冒号分隔。如果源是 Podman 维护的命名卷，建议使用其名称而不是卷的路径。否则，该卷将被视为孤立卷，并被 podman volume prune 命令清除。

$ podman run -v /var/db:/data1 -i -t fedora bash

$ podman run -v data:/data2 -i -t fedora bash

$ podman run -v /var/cache/dnf:/var/cache/dnf:O -ti fedora dnf -y update

如果容器需要一个由容器内非 root 用户可写的挂载卷，请使用 U 选项。此选项告诉 Podman 将源卷 chown 为与容器内使用的默认 UID 和 GID 匹配。

$ podman run -d -e MARIADB_ROOT_PASSWORD=root --user mysql --userns=keep-id -v ~/data:/var/lib/mysql:Z,U mariadb

或者，如果容器需要一个由容器内的非 root 用户可写的卷，--userns=keep-id 选项允许用户指定执行 Podman 的用户的 UID 和 GID 到容器内的特定 UID 和 GID。由于在容器中运行的进程以用户的 UID 运行，它们可以读写用户拥有的文件。

$ podman run -d -e MARIADB_ROOT_PASSWORD=root --user mysql --userns=keep-id:uid=999,gid=999 -v ~/data:/var/lib/mysql:Z mariadb

使用 --mount 标志将主机目录挂载为容器文件夹，指定目录的绝对路径或卷名称，以及容器目录内的绝对路径

$ podman run --mount type=bind,src=/var/db,target=/data1 busybox sh

$ podman run --mount type=bind,src=volume-name,target=/data1 busybox sh

使用 SELinux 时，请注意主机不了解容器的 SELinux 策略。因此，在上述示例中，如果强制执行 SELinux 策略，则 /var/db 目录对容器不可写。将出现“Permission Denied”消息，并且 avc: 消息将添加到主机的 syslog 中。

为了解决这个问题，在编写本手册页时，需要运行以下命令才能将正确的 SELinux 策略类型标签附加到主机目录。

$ chcon -Rt svirt_sandbox_file_t /var/db

现在，允许写入容器中的 /data1 卷，并且更改会反映在主机上的 /var/db 中。

使用替代安全标签¶

通过指定 --security-opt 标志来覆盖每个容器的默认标签方案。例如，指定 MCS/MLS 级别，这是 MLS 系统的要求。在以下命令中指定级别允许在容器之间共享相同的内容。

podman run --security-opt label=level:s0:c100,c200 -i -t fedora bash

一个 MLS 示例可能是

$ podman run --security-opt label=level:TopSecret -i -t rhel7 bash

要禁用此容器的安全标签，而不是使用

--permissive 标志运行，请使用以下命令：¶

$ podman run --security-opt label=disable -i -t fedora bash

通过为容器指定替代类型来收紧容器内进程的安全策略。例如，通过执行以下命令运行一个只允许监听 Apache 端口的容器

$ podman run --security-opt label=type:svirt_apache_t -i -t centos bash

请注意，必须编写定义 svirt_apache_t 类型的 SELinux 策略。

要屏蔽容器中额外的特定路径，请使用 --security-opt 标志的 mask 选项，并用冒号分隔路径。

$ podman run --security-opt mask=/foo/bar:/second/path fedora bash

要取消屏蔽所有默认被屏蔽的路径，将 unmask 选项设置为 ALL。或者只取消屏蔽特定路径，如上所示使用 mask 选项指定路径。

$ podman run --security-opt unmask=ALL fedora bash

要取消屏蔽所有以 /proc 开头的路径，请将 unmask 选项设置为 /proc/*。

$ podman run --security-opt unmask=/proc/* fedora bash

$ podman run --security-opt unmask=/foo/bar:/sys/firmware fedora bash

通过 --blkio-weight-device 标志设置设备权重。¶

$ podman run -it --blkio-weight-device "/dev/sda:200" ubuntu

使用从管道输入数据的 podman 容器¶

$ echo "asdf" | podman run --rm -i --entrypoint /bin/cat someimage
asdf

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

# podman run --userns=auto:size=65536 ubi8-micro cat /proc/self/uid_map
0 2147483647      65536
# podman run --userns=auto:size=65536 ubi8-micro cat /proc/self/uid_map
0 2147549183      65536

设置命名空间内核参数 (Sysctls)¶

--sysctl 在容器中设置命名空间内核参数 (sysctls)。例如，要在容器网络命名空间中启用 IP 转发，请运行此命令

$ podman run --sysctl net.ipv4.ip_forward=1 someimage

请注意，并非所有 sysctls 都具有命名空间。Podman 不支持更改容器内同时修改主机系统的 sysctls。随着内核的发展，我们预计会有更多的 sysctls 成为命名空间。

有关当前支持的 sysctls 列表，请参见上面 --sysctl 选项的定义。

在新用户命名空间中设置 UID/GID 映射¶

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

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

从命令行配置存储选项¶

Podman 允许通过更改 /etc/containers/storage.conf 中的值或使用全局选项来配置存储。这展示了如何使用全局选项一次性运行 busybox 的额外镜像存储。

podman --log-level=debug --storage-opt "additionalimagestore=/tmp/readonly-images" run busybox /bin/sh

在容器中配置时区¶

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

添加依赖容器¶

第一个容器 container1 最初不会启动，但必须在 container2 启动之前运行。podman run 命令会在启动 container2 之前自动启动该容器。

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

可能需要多个容器。

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

配置保持补充组以访问卷¶

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

使用 personality 标志配置容器的执行域¶

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

以 overlay 方式挂载外部 rootfs 运行容器¶

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

在容器中处理 Java 应用程序的时区。¶

为了在容器内运行 Java 应用程序时使用 UTC 以外的时区，必须在容器内设置 TZ 环境变量。Java 应用程序会忽略使用 --tz 选项设置的值。

# Example run
podman run -ti --rm  -e TZ=EST mytzimage
lrwxrwxrwx. 1 root root 29 Nov  3 08:51 /etc/localtime -> ../usr/share/zoneinfo/Etc/UTC
Now with default timezone:
Fri Nov 19 18:10:55 EST 2021
Java default sees the following timezone:
2021-11-19T18:10:55.651130-05:00
Forcing UTC:
Fri Nov 19 23:10:55 UTC 2021

运行一个连接到两个网络（net1 和 net2）并具有静态 IP 的容器¶

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

无根容器¶

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

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

如果安装了 fuse-overlayfs 和 slirp4netns 软件包，无根 Podman 会运行得更好。fuse-overlayfs 软件包提供了一个用户空间 overlay 存储驱动，否则用户需要使用 vfs 存储驱动，这可能会占用大量磁盘空间且性能低于其他驱动。

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

环境变量¶

容器内的环境变量可以使用多种不同的选项进行设置，按以下优先级顺序（后面的条目覆盖前面的条目）：

容器镜像：容器镜像中指定的任何环境变量。
--http-proxy：默认情况下，一些环境变量从主机传递进来，例如 http_proxy 和 no_proxy。有关详细信息，请参见 --http-proxy。
--env-host：添加执行 Podman 进程的主机环境。
--env-file：通过 env-files 指定的任何环境变量。如果指定了多个文件，它们将按条目顺序相互覆盖。
--env：指定的任何环境变量都会覆盖之前的设置。

运行容器并设置以 * 结尾的环境变量。尾随的 * glob 功能仅在未指定值时才有效。

$ export ENV1=a
$ podman run --env 'ENV*' alpine env | grep ENV
ENV1=a
$ podman run --env 'ENV*=b' alpine env | 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)。

有关无根（rootless）问题，请参阅 podman-rootless(7)。

历史¶

2018年9月，Kunal Kushwaha <kushwaha_kunal_v7@lab.ntt.co.jp> 更新

2017年10月，由 Dan Walsh 为 Podman <dwalsh@redhat.com> 从 Docker 文档转换为 Podman

2015年11月，Sally O’Malley <somalley@redhat.com> 更新

2014年6月，Sven Dowideit <SvenDowideit@home.org.au> 更新

2014年4月，最初由 William Henry <whenry@redhat.com> 根据 docker.com 源材料和内部工作编写。

脚注¶

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