portablectl 中文手册

名称

portablectl — 安装、卸载、查看便携式服务镜像

大纲

portablectl [OPTIONS...] {COMMAND} [NAME...]

描述

portablectl 用于安装(attach)、卸载(detach)、查看(inspect) 便携式服务(Portable Service)镜像，它是 systemd-portabled.service(8)服务的命令行接口。

便携式服务镜像中包含操作系统目录树以及systemd(1) 单元文件。便携式服务镜像可以被"安装"(attach)到本地系统中。安装之后，将会从镜像中复制一组单元文件到宿主机内，并通过自动生成单元配置片段的方式，将 service 单元的 RootDirectory= 或 RootImage=指向该镜像(一个目录或一个文件)，以确保服务单元只能运行在镜像内的文件系统范围内。

如果想把多个服务以及辅助单元打包在一起，作为一个整体在不同的主机之间部署，那么使用便携式服务镜像是一个非常有效的途径。被安装到宿主系统中的便携式服务镜像内的单元非常类似于原生安装在宿主系统上的常规系统单元，取决于所选 PROFILE 的不同，这些单元在运行时要么具有全部特权、要么被严格限制在沙盒中。

有效的便携式服务镜像可以是下列几种之一：

• 操作系统目录树，包含顶层目录 /usr/,/etc/,... 等等。

• 包含操作系统目录树的 btrfs 子卷。

• 包含 MBR 或 GPT 分区表以及 Linux 文件系统分区的二进制原始磁盘镜像文件。注意，镜像文件必须是一个后缀名为 .raw 的普通文件。

选项(OPTIONS)

能够识别的命令行选项如下：

-q, --quiet

禁止在运行时输出额外的信息。

-p PROFILE, --profile=PROFILE

在安装便携式服务镜像的同时选择所使用的 profile ，默认为 "default" 。详见后面的 Profile 小节。

--copy=

在安装便携式服务镜像时采用何种方式向宿主系统中安装单元文件。取值范围如下： "copy"(拷贝文件)； "symlink"(使用软连接)； "auto"(拷贝单元文件、软连接 profile 单元配置片段)。注意，此选项只是尽可能按照指定的方式完成单元文件的安装，如果实在无法创建软连接，例如当镜像是一个二进制原始磁盘镜像文件的时候，那么将无条件的使用拷贝方式完成单元文件的安装。

--runtime

将单元文件与单元配置片段安装到 /run/systemd/system.attached/ 目录中，而不是默认的 /etc/systemd/system.attached/ 目录中。使用此选项安装的便携式服务镜像仅是临时性的，在宿主系统重启之后就会消失。

--no-reload

在安装或卸载便携式服务镜像之后，禁止重新加载 systemd 服务管理器的配置信息。通常情况下，在安装或卸载便携式服务镜像之后，都会自动重新加载 systemd 服务管理器的配置信息，以确保即时了解单元文件的变动情况。

--cat

在查看便携式服务镜像时，显示镜像中元数据文件的原始内容，而不是仅显示一些简略的汇总信息。特别地，这将显示镜像中的 os-release(5) 文件与单元文件的具体内容。

-H, --host=

操作指定的远程主机。可以仅指定一个主机名(hostname)，也可以使用 "username@hostname" 格式。hostname 后面还可以加上SSH监听端口(以冒号":"分隔)与容器名(以正斜线"/"分隔)，也就是形如 "hostname:port/container" 的格式，以表示直接连接到指定主机的指定容器内。操作将通过SSH协议进行，以确保安全。可以通过machinectl -HHOST 命令列出远程主机上的所有容器名称。IPv6地址必须放在方括号([])内。

-M, --machine=

在本地容器内执行操作。必须明确指定容器的名称。

--no-pager

不将程序的输出内容管道(pipe)给分页程序。

--no-legend

不输出列标题，也就是不在输出列表的头部和尾部显示字段的名称。

--no-ask-password

在执行特权操作时不向用户索要密码。

-h, --help

显示简短的帮助信息并退出。

--version

显示简短的版本信息并退出。

命令(COMMAND)

能够识别的命令如下：

list

列出所有在便携式服务镜像搜索路径(详见"文件与目录"小节)中找到的镜像。此命令还会同时显示镜像的简要元数据与状态信息。注意，因为下面的许多命令都可以处理镜像搜索路径之外的便携式服务镜像，所以其他命令能够处理的镜像 并不只局限于此命令的输出列表。

attach IMAGE [PREFIX…]

向宿主系统中安装一个便携式服务镜像。IMAGE 必须是一个指向便携式服务镜像的文件系统路径，如果其中不含路径分隔符("/")，那么将被视为一个位于便携式服务镜像搜索路径(详见"文件与目录"小节)中的镜像名称([译者注]不含".raw"后缀)。如果想要安装当前工作目录中的镜像，那么应该在路径的开头使用 "./" 以避免混淆。

向宿主系统中安装一个便携式服务镜像时，将会执行如下四个操作：

1. 镜像内所有 .service, .socket, .target, .timer, .path 类型、 并且单元名称前缀与镜像名称前缀相同的单元文件，都将被安装(拷贝或软连接)到宿主系统的 /etc/systemd/system.attached/ 或 /run/systemd/system.attached/(使用了 --runtime 选项) 目录中。 而这两个目录都包含在 宿主系统的系统单元目录之中。

2. 对于 .service 类型的单元文件，自动在宿主系统中创建对应的单元配置片段， 并根据不同的镜像类型(目录或文件)，将 RootDirectory= 或 RootImage= (详见 systemd.unit(5) 手册)指向镜像的路径， 以确保被安装的服务单元仅运行在所属镜像内的文件系统之中。

3. 对于 .service 类型的单元文件，自动在宿主系统中以软连接方式引入"profile"单元配置片段， 从而对便携式服务施加额外的安全限制(可能还有其他限制)。除了软件包自带的预定义 profile 之外， 系统管理员还可以自定义其他的 profile (详见"Profile"小节)。

4. 如果被安装的镜像不在标准搜索路径中(详见"文件与目录"小节)， 那么将会在 /etc/portables/ 或 /run/portables/(使用了 --runtime 选项) 目录中创建一个指向该镜像的软连接，以确保该镜像被包含在标准搜索路径中。

如果省略了 PREFIX…(单元名称前缀)，那么镜像中所有单元名称前缀与镜像名称前缀相同的单元文件，都将被安装(拷贝或软连接)到宿主系统中。镜像名称前缀是指首先从镜像文件名中去除可能存在的后缀名(例如 .raw)、 然后再去除可能存在的第一个下划线("_")以及之后的部分，最终所得到的字符串。例如镜像文件 foobar_47.11.raw 的前缀是 foobar ([译者注]对应的镜像名称是"foobar_47.11")。单元名称前缀是指镜像内单元文件名称中第一个 "-", ".", "@" 字符之前的部分。例如，对于文件名为 foobar_47.11.raw 的镜像来说，该镜像内名为 foobar-quux-waldi.service, foobar.service, foobar@.service 的单元文件都将被安装到宿主系统中。如果明确指定了 PREFIX…(单元名称前缀)，那么将无视镜像名称，直接用指定的一组单元名称前缀进行匹配。

除非使用了 --no-reload 选项，否则，在安装便携式服务镜像之后，都会自动重新加载 systemd 服务管理器的配置信息，以确保宿主系统能够立即看到新安装的单元。

detach IMAGE

从宿主系统中卸载一个先前已安装的便携式服务镜像，也就是撤销 attach 命令所做的全部动作。IMAGE 必须是一个便携式服务镜像的名称或路径。注意，如果给出的是一个路径，那么实际只会根据路径末尾的文件名或目录名来确定镜像名称(去掉可能存在的 .raw 后缀)，因此不建议使用路径。

inspect IMAGE [PREFIX…]

查看便携式服务镜像中的各种元数据。也就是显示镜像内 os-release(5) 以及匹配单元的相关信息。默认只显示简要的关键信息以及匹配的单元文件(也就是会被 attach 安装到宿主系统中的单元文件)。如果指定了 --cat 选项，那么将会显示镜像内 os-release 文件以及匹配的单元文件的原始内容。此命令主要用于检查给定的镜像是否是一个合格的便携式服务镜像，以及镜像中包含了哪些单元文件。 IMAGE [PREFIX…] 的含义与 attach 命令完全相同。

is-attached IMAGE

检查指定的镜像当前是否已经被安装到宿主系统中。除非使用了 --quiet 选项，否则将会显示下列状态标识符之一：

表 1. 镜像的安装状态

状态	描述
detached	没有安装
attached	已经持久安装，并且该镜像的单元文件已经可以在宿主系统中持久使用。
attached-runtime	已经临时安装(执行 attach 命令时带有 --runtime 选项)，并且该镜像的单元文件已经可以在宿主系统中临时使用。
enabled	已经持久安装，并且至少有一个镜像中的单元已经被持久启用。
enabled-runtime	已经临时安装(执行 attach 命令时带有 --runtime 选项)，并且至少有一个镜像中的单元已经被临时启用。
running	已经持久安装，并且至少有一个镜像中的单元已经处于运行状态。
running-runtime	已经临时安装(执行 attach 命令时带有 --runtime 选项)，并且至少有一个镜像中的单元已经处于运行状态。

read-only IMAGE [BOOL]

设置或取消一个便携式服务镜像的只读标记。 IMAGE 是镜像的名称(不含".raw"后缀)或文件系统绝对路径。如果省略 BOOL 参数，那么表示使用其默认值 yes ，也就是设置为只读。

remove IMAGE…

删除一个或多个便携式服务镜像。IMAGE 是镜像的名称(不含".raw"后缀)或文件系统绝对路径。注意，对于通过软连接引入标准搜索路径中的镜像来说，如果只指定镜像名称，那么只会删除软连接，而不会删除实际的镜像本身。

set-limit [IMAGE] BYTES

为单个或全体便携式服务镜像设置最大磁盘用量(磁盘限额)。可选的 [IMAGE] 是镜像的名称(不含".raw"后缀)或文件系统绝对路径，若省略则表示设置全部镜像的磁盘限额总量。 BYTES 是字节数(可以使用 K, M, G, T 后缀)，特殊值 "-" 表示取消限额。

注意，针对单个镜像的磁盘限额仅在 btrfs 文件系统上才支持。虽然便携式服务单元内 BindPaths= 所引用的宿主系统目录在镜像内可见，但是并不计算在磁盘限额之中，磁盘限额仅作用于镜像自身。

文件与目录

便携式服务镜像首选的存放目录是 /var/lib/portables/ ，除此之外，还会自动依次搜索 /etc/portables/, /run/systemd/portables/,/usr/local/lib/portables/, /usr/lib/portables/ 目录。禁止将便携式服务镜像直接存放在 /etc/portables/ 或/run/systemd/portables/ 目录中(这两个目录一般不存储大文件与非文本文件)，这两个目录只用于以软连接的方式将不在标准搜索路径中的镜像添加到标准搜索路径中来。

在安装便携式服务镜像时，镜像中匹配的单元文件将会被安装(拷贝或软连接)到宿主系统的/etc/systemd/system.attached/ 或 /run/systemd/system.attached/目录中。卸载便携式服务镜像时，将会从宿主系统中删除之前安装的单元文件。

Profile

在安装便携式服务镜像时，对于服务单元，将会自动在宿主系统中以软连接方式引入"profile"单元配置片段，从而对便携式服务施加额外的安全限制(可能还有其他限制)。除了软件包自带的四个预定义 profile (位于/usr/lib/systemd/portable/profile/ 目录中)之外，系统管理员还可以在 /etc/systemd/portable/profile/ 目录中创建自定义的"profile"。四个预定义 profiles 的简介如下：

表 2. Profile

想要了解更多细节，可以直接查看例如 /usr/lib/systemd/portable/profile/default/service.conf 这样的文件。

退出状态

返回值为 0 表示成功，非零返回值表示失败代码。

环境变量

$SYSTEMD_PAGER

指定分页程序。仅在未指定 --no-pager 选项时有意义。此变量会覆盖 $PAGER 的值。如果 $SYSTEMD_PAGER 与 $PAGER 都未设置，那么将会依次尝试如下常见的分页程序：less(1),more(1),如果最终仍未找到分页程序，那么将不使用分页。将此变量设为空字符串或 "cat" 等价于使用 --no-pager 选项。

$SYSTEMD_LESS

用于覆盖默认传递给 less程序的命令行选项("FRSXMK")。

如果 $SYSTEMD_LESS 的值不含 "K" ，并且使用 less 作为分页程序，那么Ctrl+C 信号将会被忽略。这将允许 less 自己处理Ctrl+C 信号。

$SYSTEMD_LESSCHARSET

用于覆盖默认传递给 less 程序的字符集。(如果终端兼容 UTF-8 ，那么默认值是 "utf-8" )

参见

systemd(1),systemd-portabled.service(8)