名称¶
podman-system-service - 运行 API 服务
简介¶
podman system service [选项]
描述¶
podman system service 命令创建一个监听服务,用于响应 Podman 的 API 调用。此命令可在 Linux 系统上使用,通常在 systemd 服务中执行。当 Podman 命令直接在 Windows 或 macOS 主机上执行,或在 Podman 命令访问远程 Podman API 服务的其他情况下,此命令不可用。
podman system service 提供的 REST API 分为两部分:一个提供 Docker v1.40 API 支持的兼容层,以及一个 Podman 原生的 Libpod 层。后者的文档可在 https://docs.podman.org.cn/en/latest/_static/api.html 查看。两个 API 都有版本,但服务器不会拒绝版本设置不受支持的请求。
在 systemd 服务中运行命令¶
podman system service 命令支持 systemd 套接字激活。当此命令在 systemd 服务中运行时,API 服务可以按需提供。如果 systemd 服务尚未运行,一旦客户端连接到监听套接字,它就会被激活。然后 systemd 执行 podman system service 命令。在由 --time 选项定义的一段时间不活动后,命令终止。Systemd 将 podman.service 状态设置为不活动。此时没有 podman system service 进程在运行。不会浪费不必要的计算资源。一旦另一个客户端连接,systemd 会再次激活 systemd 服务。
声明 Podman API 服务供用户使用的 systemd 单元文件是
/usr/lib/systemd/user/podman.service
/usr/lib/systemd/user/podman.socket
在 podman.socket 文件中,监听 Unix 套接字的路径由以下定义
ListenStream=%t/podman/podman.sock
该路径包含 systemd 规范符 %t
,systemd 将其扩展为环境变量 XDG_RUNTIME_DIR
的值(请参阅 systemd.unit(5) 手册页中的 systemd 规范符)。
除了 systemd 用户服务,还有一个 systemd 系统服务 podman.service。它运行 rootful Podman,并从 Unix 套接字 /run/podman/podman.sock 访问。请参阅 systemd 单元文件
/usr/lib/systemd/system/podman.service
/usr/lib/systemd/system/podman.socket
podman system service 命令不支持 API 服务超过一个监听套接字。
注意:默认的 systemd 单元文件(系统和用户)将日志级别选项从 error 更改为 info。此更改为每个 API 调用提供了额外的信息。
直接运行命令¶
为了支持不使用 systemd 服务运行 API 服务,该命令还接受一个可选的 API 端点参数,其形式为 URI。例如,unix:///tmp/foobar.sock 或 tcp://:8080。如果未提供端点,则使用默认值。rootful 服务的默认端点是 unix:///run/podman/podman.sock,rootless 服务的默认端点是 unix://$XDG_RUNTIME_DIR/podman/podman.sock(例如 unix:///run/user/1000/podman/podman.sock)
从容器内部访问 Unix 套接字¶
要在容器内部访问 API 服务
将套接字挂载为卷
使用
--security-opt label=disable
运行容器
安全¶
请注意,API 授予对所有 Podman 功能的完全访问权限,因此允许以运行 API 的用户身份执行任意代码,并且无法限制或审计此访问。API 的安全模型基于通过 Unix 套接字进行访问,通过标准文件权限限制访问,确保只有运行服务的用户才能访问它。我们**强烈**建议不要通过网络提供 API 套接字(即,将服务绑定到 tcp URL)。即使通过 Localhost 访问也存在风险 - 任何有权访问系统的人都将能够访问 API。如果需要远程访问,我们建议通过 SSH 转发 API 套接字,并尽可能最大程度地限制远程机器上的访问。如果必须使用 tcp URL,建议使用 --cors 选项来提高安全性。
选项¶
--cors¶
要注入到 HTTP 响应中的 CORS 头。默认值为空字符串,表示禁用 CORS 头。
--help, -h¶
打印使用说明。
--time, -t¶
会话在 秒 内过期的时间。默认值为 5 秒。值为 0
表示无超时,因此会话不会过期。
默认超时可以通过 containers.conf 中的 service_timeout=VALUE
字段更改。有关更多信息,请参阅 containers.conf(5)。
示例¶
启动无根服务的用户 systemd 套接字。
systemctl --user start podman.socket
配置 DOCKER_HOST 环境变量指向 Podman 套接字,以便可以通过 Docker API 工具(如 docker-compose)使用它。
$ export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock
$ docker-compose up
配置 systemd 套接字在重启后自动启动,并以指定用户运行。
systemctl --user enable podman.socket
loginctl enable-linger <USER>
启动 rootful 服务的 systemd 套接字。
sudo systemctl start podman.socket
配置套接字在重启后自动启动。
sudo systemctl enable podman.socket
可以在不使用 systemd 套接字激活的情况下运行 API。在这种情况下,API 将不会按需提供,因为命令在不活动超时结束后将终止。运行一个不使用套接字激活且不活动超时为 5 秒的 API。
podman system service --time 5
由于未提供 URI 参数,因此使用了默认套接字。
使用自定义套接字路径运行 API 服务且无超时
podman system service --time 0 unix:///var/run/mypodman.sock
这将启动在自定义套接字 /var/run/mypodman.sock
上监听的 API 服务,且无不活动超时(无限期运行)。
另请参阅¶
历史¶
2020 年 1 月,由 Brent Baude <bbaude@redhat.com>
最初编译 2020 年 11 月,由 Jhon Honce (jhonce at redhat dot com) 更新