名称¶

podman - 简单管理 Pod、容器和镜像的工具

简介¶

podman [选项] 命令

描述¶

Podman（Pod 管理器）是一个功能完备的容器引擎，是一个简单的无守护进程工具。Podman 提供了一个与 Docker-CLI 媲美的命令行，可以方便地从其他容器引擎过渡，并允许管理 Pod、容器和镜像。简单来说：alias docker=podman。大多数 Podman 命令都可以作为普通用户运行，无需额外权限。

Podman 内部使用 Buildah(1) 来创建容器镜像。这两个工具共享镜像（而非容器）存储，因此彼此都可以使用或操作对方创建的镜像（但不能操作容器）。

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

podman [全局选项]

全局选项¶

--cdi-spec-dir=路径¶

CDI 规范目录路径（可多次设置）。默认路径为 /etc/cdi。

--cgroup-manager=管理器¶

用于容器 cgroup 的 CGroup 管理器。支持的值为 cgroupfs 或 systemd。默认值为 systemd，除非在 containers.conf 文件中被覆盖。

注意：当对先前由其他 CGroup 管理器类型创建的容器调用某些命令时，设置此标志可能会导致命令中断。注意：当使用 CGroups V1 版本时，无根模式不支持 CGroup 管理器。

--config¶

配置文件位置。主要用于 Docker 兼容性，只支持配置的身份验证部分。

--conmon¶

conmon 二进制文件的路径（默认路径在 containers.conf 中配置）

--connection, -c¶

用于远程 Podman（包括 Mac 和 Windows（不包括 WSL2）机器）的连接（默认连接在 containers.conf 中配置）设置此选项会将 --remote 选项切换为 true。远程连接默认使用本地 containers.conf。

--events-backend=类型¶

用于存储事件的后端。允许的值为 file、journald 和 none。当指定 file 时，事件存储在 <tmpdir>/events/events.log 下（参见下面的 --tmpdir）。

--help, -h¶

打印用法说明

--hooks-dir=path¶

路径中的每个 *.json 文件都为 Podman 容器配置了一个钩子。有关 JSON 文件语法和钩子注入语义的更多详细信息，请参阅 oci-hooks(5)。Podman 和 libpod 目前支持 1.0.0 和 0.1.0 钩子模式，尽管 0.1.0 模式已被弃用。

此选项可以设置多次；后一个选项中的路径具有更高的优先级（oci-hooks(5) 讨论了目录优先级）。

对于注解条件，libpod 使用生成的 OCI 配置中设置的任何注解。

对于绑定挂载条件，只考虑调用者通过 --volume 显式请求的挂载。libpod 默认插入的绑定挂载（例如 /dev/shm）不予考虑。

如果未为 root 调用者设置 --hooks-dir，Podman 和 libpod 目前默认按优先级递增的顺序使用 /usr/share/containers/oci/hooks.d 和 /etc/containers/oci/hooks.d。使用这些默认值已被弃用。请迁移到显式设置 --hooks-dir。

Podman 和 libpod 目前支持一个额外的 precreate 状态，该状态在运行时 create 操作之前调用。与其他阶段（在标准输入上接收容器状态）不同，precreate 钩子在标准输入上接收建议的运行时配置。它们可以根据需要更改该配置，并将更改后的形式写入其标准输出。

警告：precreate 钩子允许进行强大的更改，例如向运行时配置添加额外的挂载。这种能力也使其很容易出错。在报告 libpod 错误之前，尝试禁用 precreate 钩子运行容器，以查看问题是否由其中一个钩子引起。

--identity=路径¶

SSH 身份文件的路径。如果身份文件已加密，podman 会提示用户输入密码。如果未提供身份文件且未提供用户，podman 默认为运行 podman 命令的用户。Podman 会提示输入远程服务器的登录密码。

身份值解析优先级

命令行值
环境变量 CONTAINER_SSHKEY，如果找到 CONTAINER_HOST
containers.conf 远程连接默认使用本地 containers.conf。

--imagestore=路径¶

存储镜像的 imagestore 路径。默认情况下，存储库将所有镜像存储在 graphroot 中，但如果提供了 imagestore，则存储库会将新拉取的镜像存储在提供的 imagestore 中，并继续使用 graphroot 存储其他所有内容。如果用户使用 overlay 驱动程序，则已经属于 graphroot 的镜像仍可访问。

这将覆盖 containers-storage.conf(5) 中的 imagestore 选项，有关更多详细信息，请参阅 containers-storage.conf(5)。

--log-level=级别¶

记录指定级别及以上级别的消息：debug、info、warn、error、fatal 或 panic（默认：warn）

--module=路径¶

加载指定的 containers.conf(5) 模块。可以是绝对路径或相对路径。请参阅 containers.conf(5) 了解详细信息。

远程客户端（包括 Mac 和 Windows（不包括 WSL2）机器）不支持此标志。此外，请注意该标志是根级标志，必须在任何 Podman 子命令之前指定。

--network-cmd-path=路径¶

用于设置 slirp4netns 网络的 slirp4netns(1) 命令二进制文件的路径。如果使用“”，则首先使用 containers.conf 中的 helper_binaries_dir 选项搜索二进制文件，其次使用 $PATH 环境变量。注意：此选项已弃用，并将在 Podman 6.0 中移除。请改用 containers.conf 中的 helper_binaries_dir 选项。

--network-config-dir=目录¶

网络配置文件所在的目录路径。对于 netavark 后端，root 用户使用 “/etc/containers/networks”，rootless 用户使用 “$graphroot/networks”。对于 CNI 后端，root 用户默认使用 “/etc/cni/net.d”，rootless 用户默认使用 “$HOME/.config/cni/net.d”。CNI 已弃用，并将在下一个主要 Podman 版本 5.0 中移除，以支持 Netavark。

--out=路径¶

将 podman 的输出重定向到指定路径，而不影响容器输出或其日志。此参数可用于将 podman 任何命令的输出直接捕获到文件中，并通过将 /dev/null 指定为路径来抑制 podman 的输出。要显式禁用容器日志记录，应使用 --log-driver 选项。

--remote, -r¶

当为 true 时，访问 Podman 服务是远程的。默认为 false。设置可在 containers.conf 文件中修改。如果设置了 CONTAINER_HOST 环境变量，则 --remote 选项默认为 true。

--root=值¶

存储根目录，其中存储数据（包括镜像）（UID 0 默认：“/var/lib/containers/storage”，其他用户默认：“$HOME/.local/share/containers/storage”）。默认根目录在 containers-storage.conf(5) 中配置。

覆盖此选项会导致 containers-storage.conf(5) 中的 storage-opt 设置被忽略。用户必须通过 --storage-opt 标志指定其他选项。

--runroot=值¶

存储状态目录，其中存储所有状态信息（UID 0 默认：“/run/containers/storage”，其他用户默认：“/run/user/$UID/run”）。默认状态目录在 containers-storage.conf(5) 中配置。

--runtime=值¶

containers.conf 中指定的 OCI 运行时名称或用于运行容器的 OCI 兼容二进制文件的绝对路径。

--runtime-flag=flag¶

为容器运行时添加全局标志。要列出支持的标志，请查阅所选容器运行时的手册页（runc 是默认运行时，要查阅的手册页是 runc(8)。当机器配置为 cgroup V2 时，默认运行时是 crun，要查阅的手册页是 crun(8)。）。

注意：不要将前导 -- 传递给标志。要将 runc 标志 --log-format json 传递给 podman build，给定的选项可以是 --runtime-flag log-format=json。

--ssh=值¶

此选项允许用户更改 ssh 模式，这意味着除了使用默认的 golang 模式外，还可以使用 --ssh=native 来使用已安装的 ssh 二进制文件和 containers.conf 中声明的配置文件。

--storage-driver=值¶

存储驱动程序。UID 0 的默认存储驱动程序在 containers-storage.conf(5) 中配置（在无根模式下），当 fuse-overlayfs 不可用时，非 root 用户默认使用 vfs。STORAGE_DRIVER 环境变量会覆盖默认值。--storage-driver 指定的驱动程序会覆盖所有设置。

覆盖此选项会导致 containers-storage.conf(5) 中的 storage-opt 设置被忽略。用户必须通过 --storage-opt 标志指定其他选项。

--storage-opt=值¶

指定存储驱动程序选项。默认存储驱动程序选项在 containers-storage.conf(5) 中配置。STORAGE_OPTS 环境变量会覆盖默认值。--storage-opt 指定的选项会覆盖所有设置。指定 --storage-opt=”” 则不使用任何存储选项。

--syslog¶

将日志信息输出到 syslog 和控制台（默认 false）。

在远程客户端（包括 Mac 和 Windows（不包括 WSL2）机器）上，日志记录定向到文件 $HOME/.config/containers/podman.log。

--tmpdir=路径¶

libpod 运行时内容的临时目录路径。无根模式下默认为 $XDG_RUNTIME_DIR/libpod/tmp，有根模式下默认为 /run/libpod/tmp。

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

--transient-store¶

启用全局临时存储模式，其中所有容器元数据都存储在非持久性介质上（即，在 --runroot 指定的位置）。此模式可以更快地启动容器，并保证在不干净关机或其他问题发生时在启动时获得新鲜状态。但是，它与容器在重启后仍然存在的传统模型不兼容。

此默认值在 containers-storage.conf(5) 中配置。

--url=值¶

访问 Podman 服务的 URL（默认来自 containers.conf，无根 unix:///run/user/$UID/podman/podman.sock 或有根 unix:///run/podman/podman.sock）。设置此选项会将 --remote 选项切换为 true。

CONTAINER_HOST 的格式为 <schema>://[<user[:<password>]@]<host>[:<port>][<path>]

详细信息

schema 是以下之一
- ssh（默认）：在指定 host 和 port 上的本地 unix(7) socket，可通过 SSH 访问
- tcp：与指定 host 和 port 的未加密、未经验证的 TCP 连接
- unix：在指定 path 上的本地 unix(7) socket，或用户默认值
user 默认为 root 或当前运行用户（仅限 ssh）
password 没有默认值（仅限 ssh）
host 必须提供，并且是托管 Podman 服务的机器的 IP 或名称（ssh 和 tcp）
port 默认为 22（ssh 和 tcp）
path 默认为 /run/podman/podman.sock，如果以无根方式运行则为 /run/user/$UID/podman/podman.sock（unix），或者必须显式指定（ssh）

URL 值解析优先级

命令行值
环境变量 CONTAINER_HOST
containers.conf 中的 engine.service_destinations 表，不包括 /usr/share/containers 目录
unix:///run/podman/podman.sock

远程连接默认使用本地 containers.conf。

一些有效格式的 URL 示例

unix:///run/podman/podman.sock
unix:///run/user/$UID/podman/podman.sock
ssh://notroot@localhost:22/run/user/$UID/podman/podman.sock
ssh://root@localhost:22/run/podman/podman.sock
tcp://:34451
tcp://127.0.0.1:34451

--version, -v¶

打印版本

--volumepath=值¶

存储内置卷信息的卷目录（UID 0 默认：“/var/lib/containers/storage/volumes”，其他用户默认：“$HOME/.local/share/containers/storage/volumes”）。默认卷路径可在 containers.conf 中覆盖。

环境变量¶

Podman 可以从 containers.conf 中 [engine] 表的环境变量设置环境变量。这些变量可以通过在 podman 命令之前传递环境变量来覆盖。

CONTAINERS_CONF¶

设置 containers.conf 文件的默认位置

CONTAINERS_REGISTRIES_CONF¶

设置 registries.conf 文件的默认位置。

CONTAINERS_STORAGE_CONF¶

设置 storage.conf 文件的默认位置。

CONTAINER_CONNECTION¶

覆盖默认的 --connection 值以访问 Podman 服务。自动启用 --remote 选项。

CONTAINER_HOST¶

设置默认的 --url 值以访问 Podman 服务。自动启用 --remote 选项。

CONTAINER_SSHKEY¶

设置默认的 --identity 路径以访问 Podman 服务的 ssh 密钥文件值。

PODMAN_CONNECTIONS_CONF¶

存储通过 podman system connection add 和 podman farm add 创建的系统连接和农场的文件的路径，默认使用 ~/.config/containers/podman-connections.json。

STORAGE_DRIVER¶

设置默认的 --storage-driver 值。

STORAGE_OPTS¶

设置默认的 --storage-opt 值。

TMPDIR¶

设置下载容器镜像的临时存储位置。Podman 默认使用 /var/tmp。

XDG_CONFIG_HOME¶

在无根模式下，配置文件在指定时从 XDG_CONFIG_HOME 读取，否则在用户主目录下的 $HOME/.config/containers 中读取。

XDG_DATA_HOME¶

在无根模式下，镜像在指定时拉取到 XDG_DATA_HOME 下，否则在用户主目录下的 $HOME/.local/share/containers/storage 中。

XDG_RUNTIME_DIR¶

在无根模式下，临时配置数据存储在 ${XDG_RUNTIME_DIR}/containers 中。

远程访问¶

Podman 命令可以通过 --remote 标志与远程服务一起使用。可以使用本地 Unix 域套接字、SSH 或直接 TCP 套接字进行连接。当指定 podman --remote 标志时，只使用全局选项 --url、--identity、--log-level、--connection。

连接信息也可以使用 containers.conf 文件进行管理。

退出码¶

来自 podman 的退出码提供了有关容器为何无法运行或为何退出的信息。当 podman 命令以非零代码退出时，退出码遵循 chroot 标准，请参见下文

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 返回 容器命令 的退出码

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

命令¶

命令	描述
podman-artifact(1)	管理 OCI 工件。
podman-attach(1)	附加到一个正在运行的容器。
podman-auto-update(1)	根据其自动更新策略自动更新容器
podman-build(1)	使用 Containerfile 构建容器镜像。
podman-farm(1)	将构建任务分配给运行不同架构 podman 的机器
podman-commit(1)	基于已更改的容器创建新镜像。
podman-completion(1)	生成 shell 补全脚本
podman-compose(1)	通过外部 compose 提供商运行 Compose 工作负载。
podman-container(1)	管理容器。
podman-cp(1)	在容器和本地文件系统之间复制文件/文件夹。
podman-create(1)	创建一个新容器。
podman-diff(1)	检查容器或镜像文件系统上的更改。
podman-events(1)	监控 Podman 事件
podman-exec(1)	在运行中的容器中执行命令。
podman-export(1)	将容器的文件系统内容导出为 tar 归档文件。
podman-generate(1)	根据容器、pod 或卷生成结构化数据。
podman-healthcheck(1)	管理容器的健康检查
podman-history(1)	显示镜像的历史记录。
podman-image(1)	管理镜像。
podman-images(1)	列出本地存储中的镜像。
podman-import(1)	导入 tarball 并将其保存为文件系统镜像。
podman-info(1)	显示 Podman 相关的系统信息。
podman-init(1)	初始化一个或多个容器
podman-inspect(1)	显示容器、镜像、卷、网络或 pod 的配置。
podman-kill(1)	杀死一个或多个容器中的主进程。
podman-load(1)	从 tar 归档加载镜像到容器存储中。
podman-login(1)	登录到容器注册表。
podman-logout(1)	注销容器注册表。
podman-logs(1)	显示一个或多个容器的日志。
podman-machine(1)	管理 Podman 的虚拟机
podman-manifest(1)	创建和操作清单列表和镜像索引。
podman-mount(1)	挂载工作容器的根文件系统。
podman-network(1)	管理 Podman 网络。
podman-pause(1)	暂停一个或多个容器。
podman-kube(1)	根据结构化输入文件播放容器、pod 或卷。
podman-pod(1)	管理容器组（称为 pod）的工具。
podman-port(1)	列出容器的端口映射。
podman-ps(1)	打印有关容器的信息。
podman-pull(1)	从注册表拉取镜像。
podman-push(1)	将镜像、清单列表或镜像索引从本地存储推送到其他位置。
podman-quadlet(1)	允许用户管理 Quadlet。
podman-rename(1)	重命名现有容器。
podman-restart(1)	重启一个或多个容器。
podman-rm(1)	移除一个或多个容器。
podman-rmi(1)	移除一个或多个本地存储的镜像。
podman-run(1)	在新容器中运行命令。
podman-save(1)	将镜像保存到归档中。
podman-search(1)	在注册表中搜索镜像。
podman-secret(1)	管理 podman 密钥。
podman-start(1)	启动一个或多个容器。
podman-stats(1)	显示一个或多个容器资源使用统计信息的实时流。
podman-stop(1)	停止一个或多个正在运行的容器。
podman-system(1)	管理 podman。
podman-tag(1)	为本地镜像添加额外的名称。
podman-top(1)	显示容器中正在运行的进程。
podman-unmount(1)	卸载工作容器的根文件系统。
podman-unpause(1)	取消暂停一个或多个容器。
podman-unshare(1)	在修改后的用户命名空间内运行命令。
podman-untag(1)	从本地存储的镜像中移除一个或多个名称。
podman-update(1)	更新给定容器的配置。
podman-version(1)	显示 Podman 版本信息。
podman-volume(1)	卷的简单管理工具。
podman-wait(1)	等待一个或多个容器停止并打印其退出码。

配置文件¶

containers.conf (/usr/share/containers/containers.conf, /etc/containers/containers.conf, $HOME/.config/containers/containers.conf)

Podman 为命令行选项内置了默认值。这些默认值可以通过 containers.conf 配置文件来覆盖。

发行版随附 /usr/share/containers/containers.conf 文件，其中包含其默认设置。管理员可以通过创建 /etc/containers/containers.conf 文件来覆盖此文件中的字段。用户可以通过创建 $HOME/.config/containers/containers.conf 文件来进一步修改默认值。Podman 将其内置默认值与这些文件中指定的字段合并（如果存在）。用户文件中指定的字段覆盖管理员文件，管理员文件覆盖发行版文件，发行版文件覆盖内置默认值。

如果未找到 containers.conf 文件，Podman 使用内置默认值。

如果设置了 CONTAINERS_CONF 环境变量，则其值将用于 containers.conf 文件，而不是默认值。

mounts.conf (/usr/share/containers/mounts.conf)

mounts.conf 文件指定了在执行 podman run 或 podman start 命令时自动挂载到容器内的卷挂载目录。管理员可以通过创建 /etc/containers/mounts.conf 来覆盖默认文件。

当 Podman 在无根模式下运行时，如果文件 $HOME/.config/containers/mounts.conf 存在，它将覆盖默认值。有关详细信息，请参阅 containers-mounts.conf(5)。

policy.json (/etc/containers/policy.json, $HOME/.config/containers/policy.json)

签名验证策略文件用于指定策略，例如可信密钥，适用于决定是否接受镜像或该镜像的单个签名作为有效。有关详细信息，请参阅 containers-policy.json(5)。

registries.conf (/etc/containers/registries.conf, $HOME/.config/containers/registries.conf)

registries.conf 是配置文件，它指定在完成不包含注册表或域部分的镜像名称时要查询的容器注册表。

Podman 的非 root 用户可以创建 $HOME/.config/containers/registries.conf 文件来代替系统默认值。

如果设置了 CONTAINERS_REGISTRIES_CONF 环境变量，则其值将用于 registries.conf 文件，而不是默认值。

storage.conf (/etc/containers/storage.conf, $HOME/.config/containers/storage.conf)

storage.conf 是所有使用 containers/storage 的工具的存储配置文件

存储配置文件指定了所有使用共享容器存储的工具可用的容器存储选项。

当 Podman 在无根模式下运行时，将使用文件 $HOME/.config/containers/storage.conf 而不是系统默认值。

如果设置了 CONTAINERS_STORAGE_CONF 环境变量，则其值将用于 storage.conf 文件，而不是默认值。

无根模式¶

Podman 也可以作为非 root 用户使用。当 podman 在无根模式下运行时，会自动为用户创建一个用户命名空间，定义在 /etc/subuid 和 /etc/subgid 中。

非 root 用户创建的容器对其他用户不可见，也不会被作为 root 运行的 Podman 看到或管理。

要求为用户设置多个 UIDS/GIDS。请确保用户存在于文件 /etc/subuid 和 /etc/subgid 中。

执行以下命令将范围添加到文件中

$ sudo usermod --add-subuids 10000-75535 USERNAME
$ sudo usermod --add-subgids 10000-75535 USERNAME

或者手动添加内容。

$ echo USERNAME:10000:65536 >> /etc/subuid
$ echo USERNAME:10000:65536 >> /etc/subgid

有关更多信息，请参阅 subuid(5) 和 subgid(5) 手册页。

注意：/etc/subuid 或 /etc/subgid 中任何行中的空格，包括尾随空格，可能会导致条目失败。

镜像在指定时拉取到 XDG_DATA_HOME 下，否则在用户主目录下的 .local/share/containers/storage 中。

目前需要安装 slirp4netns 或 pasta 才能创建网络设备，否则无根容器需要在主机的网络命名空间中运行。

在某些环境（如 HPC（高性能计算））中，用户无法利用 /etc/subuid 和 /etc/subgid 系统中的额外 UID 和 GID。但是，在这种环境下，无根 Podman 可以使用单个 UID 运行。为了实现这一点，请在 containers-storage.conf(5) 文件中设置 ignore_chown_errors 选项。此选项告诉 Podman 在拉取镜像时，当尝试更改容器镜像中的文件以匹配镜像中的非 root UID 时忽略 chown 错误。这意味着所有文件都以用户的 UID 保存。请注意，这可能会在运行容器时导致问题。

注意：无根模式下不支持的文件系统¶

Overlay 文件系统（OverlayFS）在内核版本低于 5.12.9 的无根模式下不受支持。fuse-overlayfs 包是一个工具，它在用户命名空间中提供 OverlayFS 的功能，允许在无根环境中挂载文件系统。建议安装 fuse-overlayfs 包。在无根模式下，如果安装了 fuse-overlayfs 程序，Podman 会自动将其用作 mount_program，只要之前没有创建 $HOME/.config/containers/storage.conf 文件。如果 storage.conf 存在于主目录中，请在 [storage.options.overlay] 下添加 mount_program = "/usr/bin/fuse-overlayfs" 以启用此功能。

网络文件系统 (NFS) 和其他分布式文件系统（例如：Lustre、Spectrum Scale、通用并行文件系统 (GPFS)）在无根模式下运行时不受支持，因为这些文件系统不理解用户命名空间。但是，无根 Podman 可以通过修改 $HOME/.config/containers/storage.conf 将 graphroot 选项指向存储在本地（非 NFS）存储上的目录来利用 NFS 主目录。

另请参阅¶

containers-mounts.conf(5), containers.conf(5), containers-registries.conf(5), containers-storage.conf(5), buildah(1), oci-hooks(5), containers-policy.json(5), crun(1), runc(8), subuid(5), subgid(5), slirp4netns(1), pasta(1), conmon(8)

故障排除¶

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

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

历史¶

2016 年 12 月，最初由 Dan Walsh dwalsh@redhat.com 编写

名称¶

简介¶

描述¶