名称

podman-create - 创建一个新容器

简介

podman create [options] image [command [arg …]]

podman container create [options] image [command [arg …]]

描述

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

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

标志的默认设置在 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 create 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 create 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 create 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 create docker-daemon:docker.io/library/fedora echo hello

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

oci-archive:path:tag 符合指定 path 处的“Open Container Image Layout Specification”并由 tag 指定的目录中的镜像。

$ podman save --format oci-archive fedora -o /tmp/fedora
$ podman create 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=weight

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

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

--blkio-weight-device=device:weight

块 IO 相对设备权重。

--cap-add=capability

添加 Linux 功能。

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

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

--cap-drop=capability

从默认的 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=mode

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

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

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

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

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

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

--cgroups=how

确定容器是否创建 CGroups。

默认为 enabled。

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

--chrootdirs=path

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

--cidfile=文件

将容器 ID 写入 file。该文件会随容器一起删除，但与 podman --remote run 配合使用在分离的容器上时除外。

--conmon-pidfile=file

将 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=microseconds

限制 CPU 实时周期（微秒）。

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

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

--cpu-rt-runtime=microseconds

限制 CPU 实时运行时间（微秒）。

限制容器的实时 CPU 使用率。此选项告诉内核限制给定 CPU 周期内实时任务可能消耗的时间。例如：周期为 1,000,000 微秒，运行时为 950,000 微秒，这意味着此容器可以消耗 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=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 的无根（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 可以指向密钥和/或证书。会尝试使用所有密钥进行解密。如果密钥受密码短语保护，则必须在参数中传递它，否则省略。

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

--device-read-iops=path:rate

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

--device-write-iops=path:rate

限制写入设备速率（每秒 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=[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

设置健康检查的间隔。interval 为 disable 表示不自动设置计时器。默认值为 30s。

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

--health-log-destination=directory_path

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

  • local: (默认) HealthCheck 日志存储在 overlay 容器中。(例如: $runroot/healthcheck.log)

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

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

--health-max-log-count=number of stored logs

设置 HealthCheck 日志文件中的最大尝试次数。（“0”值表示日志文件中无限次尝试）（默认：5 次尝试）

--health-max-log-size=size of stored logs

设置存储的 HealthCheck 日志的最大字符长度。（“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

设置启动健康检查的间隔。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。

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

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

--help

打印用法说明

--hostname, -h=name

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

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

--hosts-file=path | none | image

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

--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 样式容器，该容器在 infra 容器启动后但在常规 Pod 容器启动之前运行。Init 容器对于为 Pod 应用程序运行设置操作非常有用。

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

Init 容器只在 Pod start 时运行。重启 Pod 不会执行任何 Init 容器。此外，Init 容器只能在 Pod 未运行时创建。

--init-path=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: 在容器内使用主机的共享内存、信号量和消息队列。注意：host 模式授予容器对本地共享内存的完全访问权限，因此被认为是不安全的。

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

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

  • private: 私有 IPC 命名空间。

  • shareable: 具有与其他容器共享可能性的私有 IPC 命名空间。

--label, -l=key=value

向容器添加元数据。

--label-file=file

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

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

日志驱动特定选项。

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

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 地址必须是唯一的。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=number[unit]

内存软限制。unit 可以是 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=number

调整容器的内存交换行为。接受介于 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 而没有目标目录时，文件和目录将以其在容器内的完整路径进行挂载。当指定目标时，与目标目录中基本文件名上的 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，该 title 将与 org.opencontainers.image.title 注解进行比较。

  • name: 这可以用于覆盖我们在容器内部用于挂载的文件名。对于单个 blob 制品，如果 dst 是一个目录，则直接使用名称，否则忽略。对于多 blob 制品，名称将与索引后缀 <name>-x 一起使用，其中 x 是制品中从 0 开始的层索引。

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

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

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

特定于 type=volume 的选项

  • ro, readonly: true 或 false（未指定时的默认值：false）。

  • U, chown: true 或 false（未指定时的默认值：false）。根据容器的 UID 和 GID 递归更改源卷的所有者和组。

  • idmap: 如果指定，则在容器中的目标用户命名空间创建 idmap 挂载。idmap 选项仅在 rootful 模式下由 Podman 支持。Linux 内核不允许非特权用户使用 idmap 文件系统。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 选项仅由 Podman 在 rootful 模式下支持。

  • 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 的复制。默认使用。

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

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

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

  • host：将主机的网络命名空间用于容器，而不是创建隔离的命名空间。警告：这使容器可以完全访问抽象 Unix 域套接字和绑定到 localhost 的 TCP/UDP 套接字。由于这些机制通常用于防止访问敏感系统服务，从而将其与外部实体的访问隔离，因此使用此选项可能被视为安全漏洞。

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

  • private：为容器创建新的命名空间。这对于 rootful 容器使用 bridge 模式，对于 rootless 容器使用 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 接口名称，都从主机复制。端口转发保留原始源 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，启用 DNS 转发器，可在 10.0.2.3 访问，将 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 与设置为 none 或 container:id 的 --network 一起使用，则无效。

如果与 --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-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 命名空间用于容器。注意，host 模式授予容器对本地 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

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

--platform=OS/ARCH

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

--pod=name

在现有 Pod 中运行容器。如果 Pod 名称前缀为 new:，Podman 会自动创建 Pod。要使用更精细的选项创建 Pod，请在创建容器之前使用 podman pod create 命令。当容器在具有 infra-container 的 Pod 中运行时，infra-container 会首先启动。

--pod-id-file=file

在现有 pod 中运行容器，并从指定的 file 中读取 pod 的 ID。当容器在具有 infra-container 的 pod 中运行时，infra-container 会首先启动。

--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 端口，请将 --publish 设置两次，分别使用 tcp 和 udp 作为协议。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 必须使用 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。

--rootfs

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

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

Overlay 根文件系统 挂载

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

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

idmap

如果指定了 idmap，则在容器中的目标用户命名空间创建 idmapped 挂载。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 …]

授予容器访问机密的权限。可以指定多次。

密钥是容器在运行时需要的敏感数据 Blob，但未存储在镜像或源代码控制中，例如用户名和密码、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。如果未设置 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 视为禁用，即使它在主机上已启用。容器被阻止设置任何标签。

  • 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的大小。一个单位可以是b（字节）、k（千字节）、m（兆字节）或g（千兆字节）。如果省略单位，系统将使用字节。如果省略大小，默认值为64m。当size为0时，此选项没有限制用于IPC的内存量。此选项与--ipc=host冲突。

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

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

--stop-signal=信号

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

--stop-timeout=秒

停止容器的超时时间。默认值为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文件系统是被拒绝的。在SELinux分离系统上，必须启用container_manage_cgroup布尔值才能允许此操作。

setsebool -P container_manage_cgroup true

--timeout=秒

在conmon发送终止信号之前，允许容器运行的最长时间。默认情况下，容器会一直运行直到它们退出或通过podman stop停止。

--tls-verify

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

--tmpfs=fs

创建tmpfs挂载。

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

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

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

--tty, -t

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

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

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

--tz=时区

在容器中设置时区。此标志接受基于区域的时区、GMT时间，以及local，后者将容器中的时区设置为与主机匹配。有关有效时区，请参阅/usr/share/zoneinfo/。远程连接使用local 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

第一个从属 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

在无根模式下运行时，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 将查找与主机ID2000对应的中间ID，并将其映射到容器ID100000。给定的主机ID必须已经处于从属状态（否则它最初就不会映射到中间空间）。

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

扩展先前的映射

一些映射修改可能很麻烦。例如，用户从--gidmap="0:0:65000"这样的映射开始，需要将其更改为将父ID1000映射到容器ID100000，而不是将容器ID1取消分配。相应的--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，并让Podman随意映射其余的从属ID时，这很方便。

仅传递 --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也可以通过运行podman  --uidmap $container_uid:0:1 --user $container_uid ...将用户的普通UID映射到容器UID。

Podman

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

--ulimit=选项

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，并带有未使用的从属用户ID范围，Podman容器被允许分配。示例：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使用用户的所有subuids和subgids。选项--userns=nomap使用用户的所有subuids和subgids，除了用户自己的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映射到容器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”

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

如果在新的用户命名空间中创建，容器中的 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术语中，源目录是lower，容器存储目录是upper。对挂载点的修改在执行结束后被销毁，类似于tmpfs挂载点被卸载。

对于高级用户，overlay选项还支持自定义非易失性upperdir和workdir用于overlay挂载。自定义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，则在容器中的目标用户命名空间创建 idmapped 挂载。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 create alpine ls

使用本地镜像创建容器并添加注释

$ podman create --annotation HELLO=WORLD alpine ls

使用本地镜像创建容器，分配伪TTY，保持stdin打开，并将其命名为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

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

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

创建具有外部rootfs挂载为overlay的容器

$ 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在大多数系统上以非root用户身份运行。此功能要求安装足够新版本的shadow-utils。shadow-utils软件包必须包含newuidmap和newgidmap可执行文件。

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

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

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

环境

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

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

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

  • --http-proxy：默认情况下，一些环境变量会从主机传递进来，例如http_proxy和no_proxy。详情请参阅--http-proxy。

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

  • --env-file：通过env-files指定的任何环境变量。如果指定了多个文件，则它们按输入的顺序相互覆盖。

  • --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 Runtime。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)。

历史

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

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

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

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

脚注

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