podman - 用于pods、容器和镜像的简单管理工具
摘要
podman [选项] 命令
描述
Podman(Pod管理器)是一个功能全面的容器引擎,它是一个简单的无守护进程工具。
Podman提供了一个与Docker-CLI兼容的命令行界面,可以简化从其他容器引擎的过渡,并允许管理pods、容器和镜像。简而言之:alias docker=podman
。
大多数Podman命令都可以作为普通用户运行,而无需额外的权限。
Podman内部使用Buildah(1)来创建容器镜像。这两个工具共享镜像(不是容器)存储,因此每个工具都可以使用或操作由另一个工具创建的镜像(但不是容器)。
标志的默认设置定义在containers.conf
中。远程连接的大多数设置使用服务器的containers.conf,除非在手册页面中另有说明。
podman[全局选项]
全局选项
# --cgroup-manager=manager
用于容器cgroups的CGroup管理器。支持的值有cgroupfs
或systemd
。默认是systemd
,除非在containers.conf文件中进行了覆盖。
注意:设置此标志可能会导致对先前由另一种CGroup管理器类型创建的容器调用某些命令时出错。 注意:在CGroups版本V1的rootless模式下不支持CGroup管理器。
--config
配置文件的位置。主要是为了与Docker兼容,只支持配置文件的身份验证部分。
--conmon
conmon二进制文件的路径(默认路径在containers.conf
中配置)
--connection, -c
用于远程podman的连接,包括Mac和Windows(不包括WSL2)机器(默认连接在containers.conf
中配置)
设置此选项会将--remote选项切换为true。
远程连接默认使用本地的containers.conf。
--events-backend=type
用于存储事件的后端。允许的值有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=path
ssh身份文件的路径。如果身份文件已加密,podman会提示用户输入密钥短语。 如果没有提供身份文件且没有给出用户,podman默认使用运行podman命令的用户。 Podman会提示在远程服务器上输入登录密码。
身份值解析优先级:
-命令行值
-如果找到CONTAINER
HOST,则使用环境变量
CONTAINERSSHKEY
-containers.conf
远程连接默认使用本地的containers.conf。
--imagestore=path
图像存储的路径,即存储图像的位置。默认情况下,存储库将所有图像存储在graphroot中,但如果提供了imagestore,则存储库将新拉取的图像存储在提供的imagestore中,并继续使用graphroot存储其他所有内容。如果用户正在使用overlay驱动程序,则graphroot中已经存在的图像仍然可以访问。
这将覆盖containers-storage.conf(5)
中的imagestore选项,有关更多详细信息,请参阅containers-storage.conf(5)
。
--log-level=level
在指定级别及以上记录日志消息:debug
.info
.warn
.error
.fatal
或panic
(默认:warn
)
--module=path
加载指定的containers.conf(5)
模块。可以是绝对路径或相对路径。有关详细信息,请参阅containers.conf(5)
。
此标志在远程客户端上不受支持,包括Mac和Windows(不包括WSL2)机器。 此外,请注意,该标志是根级别的标志,必须在任何Podman子命令之前指定。
--network-cmd-path=path
用于设置slirp4netns网络的slirp4netns(1)
命令二进制文件的路径。
如果使用"",则首先使用containers.conf
中的helper
binariesdir
选项搜索二进制文件,其次使用$PATH
环境变量。
注意:此选项已弃用,将在Podman 5.0中删除。请使用containers.conf
中的helper
binariesdir
选项代替。
--network-config-dir=directory
网络配置文件所在的目录路径。 对于netavark后端,根用户使用的是"/etc/containers/networks",非根用户使用的是"$graphroot/networks"。 对于CNI后端,默认值是"/etc/cni/net.d"(根用户)和"$HOME/.config/cni/net.d"(非根用户)。 CNI已被弃用,并将在下一个主要Podman版本5.0中被移除,以支持Netavark。
--out=path
将podman的输出重定向到指定的路径,而不影响容器输出或日志。此参数可用于将podman的任何命令的输出直接捕获到文件中,并通过指定/dev/null作为路径来禁止podman的输出。要显式禁用容器日志记录,应使用--log-driver选项。
--remote, -r
当为true时,对Podman服务的访问是远程的。默认为false。 可以在containers.conf文件中修改设置。如果设置了CONTAINER`HOST环境变量,则--remote选项默认为true。
--root=value
存储根目录,用于存储数据,包括镜像(默认为UID 0的"/var/lib/containers/storage",其他用户的"$HOME/.local/share/containers/storage")。
该默认根目录在containers-storage.conf(5)
中配置。
覆盖此选项会导致containers-storage.conf(5)
中的storage-opt设置被忽略。用户必须通过--storage-opt
标志指定其他选项。
--runroot=value
存储状态目录,用于存储所有状态信息(默认为UID 0的"/run/containers/storage",其他用户的"/run/user/$UID/run")。
该默认状态目录在containers-storage.conf(5)
中配置。
--runtime=value
在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=value
此选项允许用户更改ssh模式,这意味着除了使用默认的golang模式外,还可以使用--ssh=native来使用在containers.conf中声明的已安装ssh二进制文件和配置文件。
--storage-driver=value
存储驱动。UID 0的默认存储驱动在containers-storage.conf(5)
中配置(在无根模式下),如果fuse-overlayfs不可用,非root用户的默认存储驱动是vfs。STORAGE
DRIVER环境变量会覆盖默认值。通过
--storage-driver`指定的驱动会覆盖所有其他设置。
覆盖此选项会导致containers-storage.conf(5)
中的storage-opt设置被忽略。用户必须通过--storage-opt
标志指定其他选项。
--storage-opt=value
指定存储驱动选项。默认存储驱动选项在containers-storage.conf(5)
中配置。STORAGE
OPTS环境变量会覆盖默认值。通过
--storage-opt指定的选项会覆盖所有其他设置。如果需要不使用任何存储选项,可以指定
--storage-opt=""`。
--syslog
将日志信息输出到syslog以及控制台(默认为false)。
在远程客户端上,包括Mac和Windows(不包括WSL2)机器,日志会被定向到$HOME/.config/containers/podman.log文件。
--tmpdir=path
libpod运行时内容的临时目录路径。无根用户的默认值为$XDG
RUNTIMEDIR/libpod/tmp
,root用户的默认值为/run/libpod/tmp
。
注意:--tmpdir
不用于存储下载的镜像的临时文件。要更改下载容器镜像的临时存储位置,请使用环境变量TMPDIR
。Podman默认使用/var/tmp
。
--transient-store
启用全局瞬态存储模式,其中所有容器元数据都存储在非持久性介质上(即--runroot
指定的位置)。
这种模式允许更快地启动容器,并保证在启动时的干净状态,以防发生非正常关机或其他问题。然而,它与传统的模型不兼容,在传统的模型中,容器会在重启后持续存在。
此选项的默认值在containers-storage.conf(5)
中配置。
--url=value
Podman服务的访问URL(默认来自containers.conf
,无根用户为unix:///run/user/$UID/podman/podman.sock
,root用户为unix:///run/podman/podman.sock
)。
设置此选项会将--remote选项切换为true。
CONTAINER
HOST的格式为(
schema.
user.
password.
host.
port.
path`)
细节:
schema
可以是以下之一:ssh
(默认):一个位于指定host
和port
上的本地unix(7)套接字,可通过SSH访问tcp
:一个未加密、未认证的TCP连接到指定的host
和port
*unix
:位于指定path
的本地unix(7)套接字,或者用户的默认套接字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://localhost:34451
- tcp://127.0.0.1:34451
--version, -v
打印版本信息
--volumepath=value
内置卷信息存储的卷目录(默认:对于UID 0为"/var/lib/containers/storage/volumes",对于其他用户为"$HOME/.local/share/containers/storage/volumes")。默认卷路径可以在containers.conf
中覆盖。
Environment Variables
Podman 可以从 containers.conf 文件中的 [engine] 表的 env 字段设置环境变量。这些变量可以通过在 podman
命令之前传递环境变量来覆盖。
# CONTAINERS`CONF
设置 containers.conf 文件的默认位置。
CONTAINERSREGISTRIES
CONF
设置 registries.conf 文件的默认位置。
CONTAINERSSTORAGE
CONF
设置 storage.conf 文件的默认位置。
CONTAINER`CONNECTION
覆盖默认的 --connection
值以访问 Podman 服务。这会自动启用 --remote 选项。
CONTAINER`HOST
设置默认的 --url
值以访问 Podman 服务。这会自动启用 --remote 选项。
CONTAINER`SSHKEY
设置默认的 --identity
路径,这是用于访问 Podman 服务的 ssh 密钥文件的值。
PODMANCONNECTIONS
CONF
此路径指向存储使用 podman system connection add
和 podman farm add
创建的系统连接和农场的文件,默认情况下,它使用 ~/.config/containers/podman-connections.json
。
STORAGE`DRIVER
设置默认的 --storage-driver
值。
STORAGE`OPTS
设置默认的 --storage-opts
值。
TMPDIR
设置下载的容器镜像的临时存储位置。Podman 默认使用 /var/tmp
。
XDGCONFIG
HOME
在无根模式下,当指定了 XDG
CONFIGHOME
时,配置文件将从该位置读取,否则将在用户的家目录下的 $HOME/.config/containers
中读取。
XDGDATA
HOME
在无根模式下,当指定了 XDG
DATAHOME
时,镜像将拉取到该位置,否则将拉取到用户的家目录下的 $HOME/.local/share/containers/storage
中。
XDGRUNTIME
DIR
在无根模式下,临时配置数据将存储在 ${XDG
RUNTIMEDIR}/containers
中。
这些环境变量提供了灵活的配置方式,允许用户根据需要调整 Podman 的行为,而无需修改配置文件或每次都提供命令行参数。它们对于自动化脚本和容器化应用程序的部署特别有用,因为它们可以确保一致性和可预测性。同时,这些环境变量也提供了一种覆盖默认配置的方法,以满足特定的使用场景和需求。
远程访问
使用 --remote
标志,Podman 命令可以与远程服务一起使用。连接可以通过本地 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 命令为容器和镜像管理提供了广泛而深入的功能,包括在用户命名空间中运行命令、管理镜像标签、更新容器配置、查看版本信息、管理存储卷、等待容器停止等。通过这些命令,用户可以轻松执行容器的创建、启动、停止、删除等操作,也可以对镜像进行搜索、拉取、保存、删除等管理。此外,Podman 还提供了与容器仓库的交互、查看容器日志、管理网络、暂停和恢复容器状态、重命名容器以及推送和拉取镜像等高级功能。每个命令都拥有特定的选项和用法,通过查看相应的 man 页面或使用 --help
选项,用户可以获取详细的命令说明和用法示例,以满足不同场景下的容器管理需求。Podman 的这些功能使其成为一个功能强大且灵活的容器管理工具,适用于各种复杂的容器应用场景。
配置文件
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
)
签名验证策略文件用于指定策略,例如可信密钥,这些策略在决定是否接受某个镜像或其个别签名时适用。
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 看到或管理。
为用户设置多个 UID/GID 是必需的。请确保用户存在于 /etc/subuid
和 /etc/subgid
文件中。
要为用户添加范围,请执行以下命令:
# 为用户添加UID范围
echo "username:100000:65536" | sudo tee -a /etc/subuid
# 为用户添加GID范围
echo "username:100000:65536" | sudo tee -a /etc/subgid
请将 username
替换为实际的用户名,100000
是起始 UID/GID(通常是基于系统配置的),而 65536
是该范围的大小(即分配给用户的 UID/GID 数量)。这些值应该根据系统上的现有配置进行调整,以确保不会与现有的 UID/GID 冲突。在添加后,用户应该能够使用 Podman 的无根模式来创建和管理容器。
查看 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 在拉取镜像时忽略 chown 错误,当尝试将容器镜像中的文件更改为与镜像中的非 root UID 匹配时。这意味着所有文件都将以用户的 UID 保存。请注意,这可能会在运行容器时导致问题。
注意: 无根模式下不支持的文件系统
在内核版本低于 5.12.9 的情况下,Overlay 文件系统(OverlayFS)在无根模式下不受支持。fuse-overlayfs 包是一个在用户命名空间中提供 OverlayFS 功能的工具,允许在无根环境中挂载文件系统。建议安装 fuse-overlayfs 包。在无根模式下,如果 $HOME/.config/containers/storage.conf
文件之前未创建,Podman 会自动使用 fuse-overlayfs 程序作为挂载程序。如果 homedir 中存在 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 主目录。
更多信息,请参见 Podman 故障排除页面。
另请参阅
- containers-mounts.conf(5): 这是与容器挂载相关的配置文件。它定义了容器在运行时应该挂载哪些文件系统、目录或设备。
- containers.conf(5): 这是Podman和Buildah等容器工具的默认配置文件。它包含了许多用于配置容器运行时的选项和参数。
- containers-registries.conf(5): 这个配置文件用于定义容器镜像的注册表和认证信息。它允许用户配置如何拉取和推送容器镜像到不同的注册表。
- containers-storage.conf(5): 这个配置文件用于定义容器的存储后端和相关的选项。它允许用户配置如何存储容器镜像、容器状态和其他相关数据。
- buildah(1): Buildah是一个用于构建OCI(Open Container Initiative)容器镜像的工具。它允许用户从源代码或其他容器镜像创建新的容器镜像。
- oci-hooks(5): OCI钩子是一种机制,允许在容器生命周期的不同阶段执行自定义操作。这些钩子可以在容器创建、启动、停止等时刻触发。
- containers-policy.json(5): 这个文件定义了容器镜像的签名和验证策略。它允许用户配置如何验证从注册表拉取的容器镜像的完整性和来源。
- crun(1): crun是一个符合OCI运行时规范的容器运行时工具。它用于启动和管理容器实例。
- runc(8): runc是另一个流行的OCI容器运行时工具。它与Docker等容器引擎紧密集成,用于启动和管理容器。
- subuid(5) 和 subgid(5): 这两个配置文件用于定义用户和用户组的子UID和子GID范围。在容器环境中,这些范围用于隔离容器内的进程,以避免UID和GID冲突。
- slirp4netns(1): slirp4netns是一个用于为rootless容器提供网络功能的工具。它允许非特权用户运行容器并访问主机网络。
- pasta(1): 根据提供的链接,pasta似乎是一个与passt项目相关的工具或命令。不过,我无法直接访问该链接以获取更多详细信息。
- conmon(8): conmon是容器监控工具,通常与容器运行时(如runc或crun)一起使用。它负责监控容器的状态,并在容器退出时执行清理操作。
这些工具和配置文件共同构成了容器技术的生态系统,使得用户可以更方便地创建、管理和运行容器。
历史
2016年12月,最初由Dan Walsh编译整理。