设备代理程序命令

ironflock agent 命令将一台 Linux 机器作为设备连接到 IronFlock，并从此照管设备代理程序。您可以用它们安装代理程序，为其换用另一个设备配置或代理，更新、停止和启动它，查看其日志，以及再次移除它。

设备代理程序

设备代理程序是一个程序：它将机器作为设备连接到 IronFlock，并在 Docker 中运行设备所属项目的应用。机器成为哪台设备，由 IronFlock Studio 为每台设备提供的设备配置文件（.flock）决定（连接设备）。

每个代理程序命令都需要 root，并且只在 Linux 上运行。没有 root 时，命令以退出码 3 结束，自己不会调用 sudo（Root 权限）。在 macOS 上，代理程序命令会在检查任何内容之前以退出码 3 结束；请在 Linux 机器上运行它们，或者在 Mac 上借助 --host 运行。在 IronFlockOS 设备上，镜像的系统中已自带代理程序：agent install 和 agent remove 在那里会拒绝执行，而 agent configure -c 用另一个 .flock 注册设备。

每个命令还接受全局标志 --yes、--json、--download-base、--host、--hosts 和 --parallel（全局标志）。询问需要终端；没有终端时，请给出 --yes（询问与确认）。

借助 --host，命令通过 SSH 在另一台机器上运行（通过 SSH 管理远程机器）。同时在多台机器上运行时（多次给出 --host，或使用 --hosts），agent restart、agent start 和 agent logs 照常运行，但 agent logs --follow 不能与 --json 同用。agent stop、agent update、agent configure 和 agent remove 在那里需要 --yes，因为没有人会被询问；agent configure 在那里不接受 -c，因为一个 .flock 只指定一台设备。agent install 一次只在一台机器上运行。

已安装的代理程序包括什么

代理程序还会在每次启动时自行写入主机的几项设置：它所运行的 slice ironflock.slice（为它保留内存）、systemd 看门狗、内核的崩溃设置，以及 journal 大小的上限。

由早期 IronFlock 安装程序设置的机器可能仍以旧布局 /opt/reagent 存放代理程序（服务 reagent.service，日志 /var/log/reagent.log），代理程序会自行将其迁移到 /opt/ironflock/device-agent；ironflock status 显示机器采用哪种布局，下文的拒绝执行情况会指出布局在哪些情况下有影响。

ironflock agent install

将设备代理程序安装到 /opt/ironflock/device-agent，在缺少 Docker 时安装 Docker，设置设备的主机默认设置，并将机器作为该 .flock 所对应的设备连接到 IronFlock。代理程序立即启动，并从此自行更新。

ironflock agent install -c <device.flock> [flags]

运行平台： 基于 Debian 或 Ubuntu、带有 systemd 的 Linux；不支持 IronFlockOS。Root： 需要。询问： 在安装软件包和 Docker 之前询问，每项主机默认设置也会询问；--yes 以默认值回答每个询问。

机器需要能访问互联网，或者能访问用 --download-base 指定的下载服务器（下载基址），或者能访问 .flock 所指定的 Appliance 的下载镜像站（代理程序从哪里来）。设备必须能访问的主机列在网络要求中。

代理程序从哪里来

代理程序包括其通道映射、二进制文件，以及该二进制文件的 .sha256 和 .sig。命令按以下顺序获取它们：

1. --download-base，否则 IRONFLOCK_DL_BASE：只用该服务器。
2. 否则，用 .flock 指定为更新服务器（update_url）的 IronFlock Appliance 的下载镜像站，前提是其主机不属于 IronFlock 云。能访问 Appliance、但无法访问 ironflock.com 的机器就是这样安装的。IronFlock 云的 .flock 使用云。
3. 否则，用 IronFlock 云 https://instance-registry.ironflock.com/dl。

命令在 stderr 上指出所用的下载基址：Download base: ... (from the device's .flock)，或者 (from --download-base)、(from IRONFLOCK_DL_BASE) 或 (from default)。

使用 Appliance 的镜像站时，文件先从镜像站获取；镜像站没有提供的文件，从 IronFlock 云下载基址之下的相同路径获取：

• 通道映射 — 镜像站当前不提供（没有响应、没有该文件、返回错误状态）时，一切都从云获取，版本取云的映射所指定的版本。镜像站提供了映射、但映射被拒绝（签名不符、没有版本）时，安装失败，与任何服务器的情况相同。
• 二进制文件及其 .sha256 和 .sig — 镜像站没有提供的每个文件都从云获取。镜像站的文件未通过检查（校验和、签名）时，三个文件全部从云获取。

每次回退都会在 stderr 上输出一行 Warning: ...，写明镜像站、文件和原因；使用 --json 时，结果的 warnings 中会有一项。镜像站和云都不提供某个文件时，安装失败，并给出一条错误，指出两个来源和两个原因（neither the appliance's mirror ... nor the IronFlock cloud gives ...）。

镜像站就是 .flock 的更新服务器，它不经过代理（代理）。使用 Appliance 自有 CA 签发证书的 HTTPS 镜像站，只有在机器的系统信任该 CA 时才能使用。发行版的软件包和 Docker 仍然来自它们自己的服务器，install.sh 和 ironflock 来自 ironflock.com；使用 --host 时，ironflock 从您的计算机传到该机器。

安装前的检查

在更改任何内容之前，命令会运行 ironflock doctor 中能判断安装能否成功的检查项：system、systemd、disk_space、clock、dns、proxy、download_tree、device_endpoint、docker_registry 和 update_server。它们针对 -c 的 .flock 运行，并使用本次安装的下载基址和代理标志。

其中四项检查失败时会停止安装，因为此时安装必定失败，或者会半途失败：

错误消息会指出该检查项、其结论和提示。其他所有结论都作为警告输出到 stderr，安装继续进行：一旦网络允许，代理程序就会连接、更新并拉取其应用。结果为 warning 或 skipped 绝不会停止安装。请在安装之前运行 ironflock doctor -c device.flock，查看每个检查项。

步骤

1. 列出要安装的软件包并询问。用 apt 安装它们。
2. 机器没有 Docker 时安装 Docker，并先询问。
3. 下载生产通道的代理程序，并对照其校验和与签名进行验证。得不到经过验证的代理程序时，安装在这里停止，不执行后面的任何步骤。
4. 配置 Docker：给出代理时配置代理；对于本次安装带来的 Docker 或尚未保存任何内容的 Docker，还会将 data-root 设在代理程序的文件夹中。已保存镜像或容器的 Docker 保留其配置和数据。
5. 设置主机默认设置（见下表）。每一项都在终端上供您选择；--yes 采用默认值。
6. 将代理程序安装到 /opt/ironflock/device-agent 并启动它。

安装还会添加登录横幅。安装所做的每项更改都写入 /opt/ironflock/device-init/installed.json。从第 4 步起的某一步失败时，错误会说明这次尝试已被记录，再次运行同一命令会先撤销它。命令发现之前有这样一次尝试时，会在检查通过后撤销它：列出要撤销的内容，询问，然后重新安装。

代理

代理标志为安装的下载、Docker 和代理程序设置企业代理。每项设置取自其标志，否则取自环境变量 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY（或它们的小写形式）。

代理 URL 形如 http://proxy.example.com:3128；https:// 和 socks5:// 同样可用，不带协议的 URL 视为 http://。代理需要登录时，URL 中写明用户但不写密码，即 http://[email protected]:3128，并由 --proxy-password-file 提供密码。命令会将密码填入标志中指定了用户的 URL。

警告：绝不要将代理密码写入 URL。命令行会出现在 ps 和 shell 历史记录中，因此带密码的 URL 会作为错误的命令行被拒绝，错误消息不会复述它。请将密码写在文件的一行中，或者用 --proxy-password-file /dev/stdin 通过管道传入（机密信息）。

除 --no-proxy 中的主机外，以下主机也不经过代理（NO_PROXY）：localhost、127.0.0.1 和 ::1，以及下载服务器和 .flock 中的更新服务器（其 update_url），前提是它们不是 IronFlock 云的主机，例如局域网中的 Appliance 或镜像站。IronFlock 云的主机（ironflock.com、ironflock.dev 及其下的主机，以及 storage.googleapis.com）位于互联网上，经过代理访问。

安装将 Docker 和代理程序的代理写入 /etc/ironflock/proxy.env，该文件只有 root 可读（权限 0600），Docker 会重启以使用它。docker.service 和 ironflock-device-agent.service 的 systemd drop-in ironflock-proxy.conf 只写明该文件，本身不含任何设置，因此 systemctl show 只会让每个用户看到该文件的名称，看不到其中的内容。主机自己的 Docker drop-in（docker.service.d/http-proxy.conf）保持不变；IronFlock 的设置优先于其中的 Environment= 行，并会有一条警告指出它。带有 proxies 的 daemon.json 保留这些代理，因为 Docker 优先采用它们。

以后要更改这些设置，请使用 agent configure。关于整个站点的代理，参见位于企业代理之后。

示例

# 安装代理程序；命令在每一步之前询问
sudo ironflock agent install -c device.flock
# 不询问地安装，并防止设备挂起
sudo ironflock agent install -c device.flock --yes --disable-suspend
# 在无需登录的代理之后安装
sudo ironflock agent install -c device.flock --https-proxy http://proxy.example.com:3128
# 在需要登录的代理之后安装；密码来自文件
sudo ironflock agent install -c device.flock --https-proxy http://[email protected]:3128 --proxy-password-file proxy-password.txt

结果

$ sudo ironflock agent install -c device.flock --yes
Done: the IronFlock device agent runs (systemctl status ironflock-device-agent).
The device appears online in IronFlock within a minute.

{"action":"installed","device":"demo-device","agent_version":"1.6.9"}

只有当某个文件来自 IronFlock 云、而不是 Appliance 的镜像站时，结果中才有 warnings：每个这样的文件一项，内容与 Warning: 行相同。

拒绝执行的情况

以下错误的命令行会在任何操作运行之前以退出码 2 结束：带密码的代理 URL；指定了用户、却没有 --proxy-password-file 的代理 URL；给出了 --proxy-password-file，却没有指定用户的代理 URL；不是代理 URL 的值。环境中不是代理 URL 的代理变量同样算在内；错误会指出该变量，而不是它的值。

在以下情况下，命令以退出码 3 拒绝执行，不做任何更改：

• 它不是以 root 身份运行，或者机器不是 Linux；
• 机器运行 IronFlockOS：无论是否为 root，这一项都最先检查。镜像的系统中已自带代理程序和 ironflock，每次操作系统更新都会整体替换系统。消息会说明设备会在下一次启动时用其 IRONFLOCKOS 分区上的 .flock 注册，而 agent configure -c 可以立即注册它。在 IronFlockOS 安装 U 盘上，消息会说明该 U 盘不是设备；
• 已经安装了代理程序，包括采用旧布局 /opt/reagent 的代理程序。消息会指出 agent configure 和 agent remove；
• 代理程序正在将机器从旧布局迁出；
• 之前的一次安装在设置好代理程序之前停止，当时已移动了 Docker 的 data-root，而此后 Docker 中保存了镜像或容器：撤销那次尝试会删除它们；
• 检查项 system、systemd、disk_space 或 download_tree 之一失败。--yes 不会改变这一点。

询问被回答为“否”，或者询问时没有终端且未给出 --yes，命令以退出码 4 结束。某一步失败时，命令以退出码 1 结束。

ironflock agent configure

更改安装所设置的内容：设备的 .flock、Docker 和代理程序的企业代理，或两者都改。随后重启需要应用这些更改的组件。

ironflock agent configure [-c <device.flock>] [flags]

运行平台： 已安装代理程序的 Linux；在 IronFlockOS 上仅限 -c。Root： 需要。询问： 在 Docker 因新的代理设置而重启之前；--yes 作答。

请给出 -c、某个代理标志，或两者都给出。两者都没有时，没有任何可更改的内容：属于错误的命令行（退出码 2）。

换用另一个 .flock

带 -c 时，代理程序得到所给的 .flock 并重启：机器成为该 .flock 所对应的设备。应用及其数据保持不变。如果安装时设置了 SSH 用户，SSH 用户会随 .flock 而变：

• 项目所有者相同，设备密钥不同 — 不再接受旧密钥，改为接受新密钥。
• 项目所有者不同 — 新所有者得到自己的 SSH 用户，第一位所有者的 SSH 用户按 agent remove 的方式移除：sudo 规则、密钥，以及该账户及其主目录（如果该账户是安装时创建的）。
• 不含设备密钥的 .flock — SSH 用户被移除，也不会有新的 SSH 用户。

设备易手时，运行命令的可能正是第一位所有者，而且是通过 SSH、用即将被移除的那个账户运行的，而移除账户会结束其会话。因此，命令按以下顺序工作：先设置新所有者的账户（用户、密钥、sudo 规则），再用新的 .flock 重启代理程序，然后才移除第一位所有者的 sudo 规则、会话和账户（对于同一所有者，则只移除旧密钥）。在旧的访问途径消失之前，设备已有新的访问途径，并且已经上线。会话结束之前，stderr 上会有一行说明，例如 Removing the account anna, ...: a session of anna ends here.

• 代理程序没有用新的 .flock 重启时，第一位所有者保留访问权限：必须有人能登录进去。
• 只有新所有者的 SSH 用户设置失败时，第一位所有者的访问权限照样会被移除：设备已经易手，并且已经上线。
• 谁的访问权限仍待移除，记录在 /opt/ironflock/device-init/installed.json（users_to_remove）中。之后的每次 agent configure -c 和 agent remove 都会再次尝试。
• 新的 .flock 再次设置的账户永远不会被移除（所有者 A，然后 B，然后又是 A）。
• 从第一处更改开始，终端或 SSH 会话丢失都不会停止命令。

通过 --host 运行时，机器上的 .flock 副本在命令读取后立即删除。如果 --host 的登录账户正是要移除的账户，SSH 会话会随该账户一起结束：此时您的运行以退出码 255 结束，与连接丢失后一样，而机器上的命令会继续运行到结束。运行所用的文件夹 ironflock.XXXXXXXXXX 及其中的二进制文件随后会留在机器上；位于临时文件夹中时，它会一直留到临时文件夹被清理，位于该账户的主目录中时，它随账户一起删除。

在 IronFlockOS 上

带 -c 时，命令注册设备的方式与 IronFlockOS 在每个新根槽位首次启动时注册设备的方式相同，无论设备是否已注册。所给的 .flock 成为代理程序的副本，即 /data 上的 /opt/ironflock/device-agent/device-config.flock，设备依据它按以下顺序进行设置：项目所有者的 SSH 用户、WiFi、取自设备名称的主机名（除非 /etc/ironflockos/enroll.conf 中写有 hostname-from-flock=no）、用新的 .flock 重启的代理程序，最后移除前一位所有者的访问权限。

下一次操作系统更新会用同一副本注册其新的根槽位。您给出的文件保留在原处。某一步失败不会妨碍代理程序用新的 .flock 重启，但第一位所有者的访问权限要等代理程序重启之后才会被移除。此时命令以退出码 1 结束，并指出每个失败的步骤；再次运行同一命令即可重做这些步骤。

在 IronFlockOS 上，代理标志会被拒绝。IronFlockOS 将 Docker、代理程序及其时钟所用的代理保存在 /data 上的 /etc/ironflockos/proxy.conf 中，其 IRONFLOCKOS 分区上的 proxy.conf 会在下一次启动时替换它。

代理设置

• 给出的每个代理标志替换其对应的设置，其他设置保持不变。只给出 --https-proxy 时，会更改 HTTPS 代理，并保留 HTTP 代理以及不经过代理的主机。
• --proxy-password-file 中的密码会填入所给的、指定了用户的 URL。没有给出 URL 时，它会填入设备设置中指定了用户的 URL，因此只用该文件即可设置新密码。
• --no-proxy，以及之前没有代理的设备的第一个代理，还会加上 localhost、127.0.0.1、::1，以及代理程序 .flock 中的更新服务器（当它不是 IronFlock 云的主机，即属于 Appliance 时）。
• --remove-proxy 删除这些设置。它不能与其他代理标志同用。
• 您环境中的代理变量在这里不起作用：只有标志才算数。

除非 --no-proxy 给出另一个列表，不经过代理的主机列表保持命令发现时的样子。当该列表中有 IronFlock 云的主机时，会有一条警告指出它，并给出去掉该主机后的列表所对应的 agent configure --no-proxy。只能通过代理访问互联网的设备，只要云的下载服务器 instance-registry.ironflock.com 在该列表中，就无法更新其代理程序。

这些设置保存在只有 root 可读的 /etc/ironflock/proxy.env 中，并由 docker.service 和 ironflock-device-agent.service 的 drop-in ironflock-proxy.conf 指明。设置发生变化时，命令会显示变化前后的设置，不显示密码。然后 Docker 和代理程序重启。重启 Docker 会让设备的应用短暂停止，因此命令会说明这一点并询问；--yes 作答。密码来自 stdin 时，没有可以询问的终端：请给出 --yes。

• 当 Docker 的 daemon.json 设置了 proxies（Docker 优先采用它们，而不是这些设置）时，以及没有任何变化时，Docker 不会重启，也不会询问任何内容。
• 只是缺少其 drop-in 的单元会得到该 drop-in，并且只有该单元重启。
• 主机自己的 Docker drop-in 保持原样。代理程序或 Docker 的其他设置了代理变量的 drop-in 会在警告中被指出；对于 IronFlock 设置的每个变量，IronFlock 的设置都会覆盖它。含有每个用户都能读取的代理密码的 drop-in 或 daemon.json 同样会在警告中被指出。
• Docker 重启失败时，代理程序照样重启，反之亦然。错误（退出码 1）会指出仍以旧设置运行的单元，以及应用新设置的 systemctl restart；第二次运行会发现设置已就位，不会重启任何内容。
• 无法写入设置时，不会重启任何内容，错误会提示再次运行命令。

旧版安装写在 http-proxy.conf drop-in 的 Environment= 行中的代理设置（每个用户都能用 systemctl show 读取它们，连同密码），会在任何一次 agent configure 运行时迁移到 /etc/ironflock/proxy.env，只带 -c 的运行也是如此。旧文件不保留副本。通常迁移会保留各项值，因此不会重启任何内容，也不会询问；如果迁移改变了某个单元所用的代理，命令会说明原因，显示该单元变化前后的代理，并询问。设置文件无法保存的值（主机或不经过代理的主机列表中的单引号、控制字符）不会迁移：不带代理标志的运行会保留它，给出警告，并指出用于重新给出该值的标志。

示例

# 让这台机器成为另一个 .flock 所对应的设备
sudo ironflock agent configure -c new-device.flock
# 设置需要登录的 HTTPS 代理；密码来自文件
sudo ironflock agent configure --https-proxy http://[email protected]:3128 --proxy-password-file proxy-password.txt
# 只设置新的代理密码，从 stdin 读取，不询问
sudo ironflock agent configure --proxy-password-file /dev/stdin --yes < proxy-password.txt
# 删除代理设置：Docker 和代理程序直接连接
sudo ironflock agent configure --remove-proxy

结果

$ sudo ironflock agent configure -c new-device.flock
Device configuration updated; the agent restarted.
$ sudo ironflock agent configure --https-proxy http://[email protected]:3128 --proxy-password-file proxy-password.txt
The proxy settings of Docker and the agent change:
  HTTP proxy:   none (unchanged)
  HTTPS proxy:  none -> http://[email protected]:3128 (with a password)
  No proxy for: localhost,127.0.0.1,::1
Docker restarts for the new settings: the apps of the device stop for a moment and start again.
? Continue? Yes
Proxy settings updated: HTTPS through http://[email protected]:3128 (with a password); not for localhost,127.0.0.1,::1.
Restarted: docker.service, ironflock-device-agent.service.

在 IronFlockOS 上，-c 会报告注册情况：

Device configuration updated: this device enrolled as new-device, as IronFlockOS enrolls it at every new root slot; the agent restarted.

{"action":"configured","device":"new-device","restarted":["ironflock-device-agent.service"]}

{"action":"configured","proxy":{"password":false,"changed":true,"moved":false},"restarted":["docker.service","ironflock-device-agent.service"]}

拒绝执行的情况

以下错误的命令行以退出码 2 结束：没有可更改的内容；--remove-proxy 与其他代理标志同用；带密码的代理 URL；指定了用户、却没有 --proxy-password-file 的代理 URL；给出了 --proxy-password-file，但没有任何 URL 指定了用户；不是代理 URL 或主机列表的值。

在以下情况下，命令以退出码 3 拒绝执行，不做任何更改：

• 没有安装代理程序（消息会指出 agent install），IronFlockOS 除外：在那里，-c 会注册尚未注册的设备；
• 代理程序正在将机器从旧布局迁出；
• 给出了代理标志，而代理程序仍以旧布局 /opt/reagent 运行。代理程序完成迁移后（ironflock status 显示布局），同一命令即可生效；
• 在 IronFlockOS 上给出了代理标志，无论是否带 -c；
• 在没有代理的设备上只给出了 --no-proxy 或 --proxy-password-file，或者设备的代理 URL 都没有指定用户时只给出了密码文件；
• 代理标志保留了一个 /etc/ironflock/proxy.env 无法保存的旧形式的值；消息会指出用于重新给出该值的标志。

在 IronFlockOS 上，当注册无法保留该 .flock 时，-c 会以退出码 3 被拒绝：

• 已请求恢复出厂设置但尚未开始（/boot/efi/factory-reset.conf，由 os reset 写入），或者已经开始（/boot/efi/factory-reset.keep）：下一次启动会擦除命令所设置的内容；
• 恢复出厂设置尚未结束或已放弃，并保留着随之而来的文件（/run/ironflockos/factory-reset-hold；ironflock status 会说明更多）；
• 无法挂载 /data，因此代理程序的副本会落在根槽位中。此时应使用 IRONFLOCKOS 分区上的 .flock；
• IRONFLOCKOS 分区上有一个 .flock；设备会在下一次启动时用它注册，消息会指出它；
• 命令在 IronFlockOS 安装 U 盘上运行，而安装 U 盘不是设备；
• 系统没有 /usr/lib/ironflock/image.json，或者有采用旧布局的代理程序。

ironflock agent update

让代理程序自行更新到其通道的发布版本，并跟踪它的操作。代理程序在每次启动时都会查找较新的发布版本：命令重启它，并报告结果。设备在 IronFlock 中会短暂离线；其应用继续运行。

ironflock agent update [flags]

运行平台： 已安装代理程序的 Linux。Root： 需要。询问： 是，在说明重启会造成什么影响之后；--yes 作答。

该命令没有自己的标志，也不接受版本。代理程序跟随其通道（production，或在 IronFlock 的测试平台上为 test），从其更新服务器获取更新：即其 .flock 中的 update_url（Appliance 的镜像站），否则为 IronFlock 云。--download-base 不会改变这一点。

代理程序按以下顺序执行：

1. 读取其通道的发布版本。在本设备上失败过两次的发布版本，在更新的发布版本推出之前不会再次下载。
2. 将较新的发布版本下载到其文件夹中，并检查其签名。
3. 在下载完成 10 秒后，将新版本放到位并重启进入新版本。如果它上一次连接到 IronFlock 是在 12 分钟到一天之前，它会暂缓更新：更新只从已知能够连接的版本激活。
4. 新版本处于试用期：它必须在启动后 10 分钟内连接到 IronFlock，并保持运行 2 分钟。如果做不到，或者在此之前停止了三次，代理程序会回到之前的版本。
5. 回滚之后，之前的版本必须能够连接。如果能，说明问题出在新版本：下一次更新时会再尝试一次，第二次失败后，它会被阻止，直到出现更新的发布版本。如果之前的版本在 10 分钟内同样无法连接，代理程序会归咎于网络，新版本会在下一次更新时再次尝试。

命令通过代理程序文件夹中的 update-state.json 和代理程序的日志跟踪这一过程；两者中重启之前的内容它都不读取。其进度以文本行的形式输出到 stderr，使用 --json 时也是如此。下载期间，每分钟显示一次目前已下载的量。

退出码为 1 时，结果照样写出，stderr 得到 Error: 行。使用 --json 时，之后不会有错误对象：stdout 中是结果。

示例

# 更新代理程序；命令在重启之前询问
sudo ironflock agent update
# 不询问地更新，并以 JSON 形式读取结果
sudo ironflock agent update --yes --json

结果

$ sudo ironflock agent update --yes
The agent 1.6.9 restarts now and looks for a newer release on its channel: the device is offline in IronFlock for a moment, its apps keep running.
A newer release is downloaded and started. It has to connect to IronFlock within 10 minutes and stay up for 2, or the agent goes back to 1.6.9.
The agent restarted; it looks for a newer release.
Its channel offers 1.7.0: the agent downloads it.
Activating 1.7.0: the agent restarts into it.
1.7.0 runs on probation: it has to connect to IronFlock within 10 minutes and stay up for 2.
The agent was updated from 1.6.9 to 1.7.0: 1.7.0 connected to IronFlock and passed its probation.

已是最新版本的代理程序，以及新版本被回滚的代理程序：

{"outcome":"current","version":"1.7.0","channel_version":"1.7.0"}

{"outcome":"rolled_back","version":"1.6.9","channel_version":"1.7.0","failed_version":"1.7.0","reason":"did not connect within 10m0s","retry":"next_update"}

拒绝执行的情况

在以下情况下，命令以退出码 3 拒绝执行：没有安装代理程序（消息会指出 agent install）；代理程序正在将机器从旧布局迁出；代理程序以旧布局运行（其更新不保存命令可以跟踪的状态）；代理程序早于 1.3.0，即第一个在其单元下自行更新的版本。

在以下情况下，命令以退出码 1 失败，错误会说明去哪里查看：重启失败；更新没有在代理程序的时限内推进，即重启后 3 分钟内的代理程序检查、30 分钟内的下载、3 分钟内的激活、处于试用期的新版本每次在 12 分钟内启动、回滚后 12 分钟内的代理程序判定，以及全部过程在 84 分钟内完成。代理程序会自行继续；ironflock status 显示它进行到了哪一步。

Ctrl-C 停止的是跟踪，而不是更新，并以退出码 130 结束命令。

ironflock agent remove

移除设备代理程序，并撤销其安装所记录的更改。Docker 本身和各软件包保持安装状态。

ironflock agent remove [flags]

运行平台： 已安装代理程序的 Linux；不支持 IronFlockOS。Root： 需要。询问： 是，在列出要移除的内容之后。该询问默认选中“No”：直接按 Enter 不会移除任何内容。

该命令没有自己的标志。它会移除：

• 代理程序 — 代理程序、其数据库和 /opt/ironflock/device-agent。如果 Docker 将设备的应用及其数据保存在代理程序的文件夹中，它们也会随之删除。
• SSH 用户 — 只有当账户是安装时创建的，才删除该账户。对于之前已存在的账户，只从其 authorized_keys 中删除设备密钥，该文件仍归该用户所有。如果之前 agent configure -c 未能移除前一位项目所有者的访问权限，这些访问权限也会一并移除，并标注“(a removal that had failed)”列出。
• 主机默认设置 — WiFi 配置文件、登录横幅和被屏蔽的休眠目标。
• 安装写入或替换的文件 — 原文件会恢复，连同其权限、所有者和组。
• 代理设置 — /etc/ironflock/proxy.env 及指明它的 drop-in，以及旧版安装留在 http-proxy.conf drop-in 中的代理设置。不会有任何内容取而代之：之后 Docker 不再有来自 IronFlock 的代理，命令也没有在任何地方写下代理密码。如果 Docker 原先有来自 IronFlock 的代理，询问之前的列表会说明这一点。
• 代理程序自行在主机上写入的设置 — slice ironflock.slice 及其单元的 drop-in 10-ironflock-resources.conf、systemd 看门狗（/etc/systemd/system.conf.d/10-ironflock-watchdog.conf）、内核的崩溃设置（/etc/sysctl.d/60-ironflock-crash-recovery.conf，内核会保留这些设置直到下次开机）以及 journal 的上限（/etc/systemd/journald.conf.d/10-ironflock.conf）。
• 代理程序的镜像仓库登录 — 代理程序停止后，命令会对 .flock 指定的镜像仓库（docker_registry_url）运行 docker logout；在 Appliance 的设备上，还会对 registry.<appliance_domain> 运行。/root/.docker/config.json 中的其他登录不受影响。缺少 Docker 或 Docker 出错不会停止移除；会有一行说明哪个登录没有删除。

主机自己的 Docker drop-in 保持原样。不因移除而重启的 Docker（其数据不在代理程序的文件夹中）会继续使用它启动时的代理，直到下次重启。

命令先在 stderr 上列出要移除的内容，然后询问。使用 --json 时，该列表是结果中的字段 removed。命令一旦开始移除，终端或 SSH 会话丢失都不会停止它：被移除的 SSH 用户会带走其会话（可能正是运行命令的那个会话），而移除会继续进行到结束。

示例

# 移除代理程序；命令列出要删除的内容并询问
sudo ironflock agent remove
# 不询问地移除代理程序
sudo ironflock agent remove --yes

结果

$ sudo ironflock agent remove --yes
This removes:
  - the agent, its database and /opt/ironflock/device-agent (with Docker's images and containers)
  - the user operator and its home directory
  - /etc/profile.d/ironflock-motd.sh
The IronFlock device agent was removed from this machine.

{"action":"removed","removed":["the agent, its database and /opt/ironflock/device-agent (with Docker's images and containers)","the user operator and its home directory","/etc/profile.d/ironflock-motd.sh"]}

拒绝执行的情况

在以下情况下，命令以退出码 3 拒绝执行：没有安装代理程序；代理程序正在将机器从旧布局迁出。在 IronFlockOS 上，无论是否为 root，它都会最先拒绝执行：镜像的系统中已自带代理程序，每次操作系统更新和下一次注册都会重新设置它。消息会指出 ironflock os reset，它将设备恢复为刚写入的 IronFlockOS，不带设备在 IronFlock 中的身份。在 IronFlockOS 安装 U 盘上，消息会说明该 U 盘不是设备。

回答“否”，或者询问时没有终端且未给出 --yes，命令以退出码 4 结束。

ironflock agent restart

重启代理程序的服务，并检查代理程序是否重新运行：其单元必须以一个进程运行五秒钟。在这几秒内，设备在 IronFlock 中处于离线状态；应用继续运行。

ironflock agent restart [flags]

运行平台： 已安装代理程序的 Linux。Root： 需要。询问： 无。

该命令没有自己的标志。服务为 ironflock-device-agent.service。如果在经由代理程序的终端中运行（IronFlock Studio 中设备的终端，或经由 IronFlock 的 SSH），重启会结束该会话；设备会在一分钟内恢复。

# 重启代理程序
sudo ironflock agent restart
# 重启代理程序，并以 JSON 形式读取新进程
sudo ironflock agent restart --json

$ sudo ironflock agent restart
The agent restarted: ironflock-device-agent.service runs, with process 4242.

{"action":"restarted","unit":"ironflock-device-agent.service","state":"running","main_pid":4242}

state 是重启之后单元的状态，名称与 ironflock status 中的相同。main_pid 是代理程序的进程，每次重启后都是新的进程。

拒绝执行的情况（退出码 3）：没有安装代理程序（消息会指出 agent install -c <file>）；代理程序正在将机器从旧布局迁出；systemd 不认识代理程序的单元（消息会指出 agent remove）。

失败的情况（退出码 1）：代理程序没有启动起来，即 systemd 无法启动该单元，或者其进程在五秒内结束。错误会指出该单元以及其最后几行日志的位置：代理程序的日志（agent logs）和 journal（journalctl -u <unit>）。

ironflock agent stop

停止代理程序的服务。设备在 IronFlock 中离线，经由 IronFlock 的远程访问也随代理程序一起中断：通过这种方式建立的会话（IronFlock Studio 中设备的终端、经由 IronFlock 的 SSH）会结束，在代理程序再次运行之前，IronFlock 无法访问该设备。应用继续运行，因为运行它们的是 Docker，而不是代理程序。

ironflock agent stop [flags]

运行平台： 已安装代理程序的 Linux。Root： 需要。询问： 是，在说明停止代理程序会终止哪些内容之后；--yes 作答。

该命令没有自己的标志。agent start 会再次启动代理程序，下次开机时代理程序也会启动。已停止的代理程序无法通过 IronFlock 再次启动。没有运行的代理程序无需停止；此时命令不询问任何内容，结果中没有 action。

# 停止代理程序；命令说明这会终止什么，然后询问
sudo ironflock agent stop
# 不询问地停止代理程序
sudo ironflock agent stop --yes

$ sudo ironflock agent stop --yes
Stopping the agent (ironflock-device-agent.service) takes this device offline in IronFlock.
The remote access through IronFlock goes with it: a session that came that way (the device's terminal in Studio, SSH through IronFlock) ends.
The apps keep running. 'sudo ironflock agent start' starts the agent again, and so does the next boot.
The agent is stopped (ironflock-device-agent.service): the device is offline in IronFlock, and its apps keep running. 'sudo ironflock agent start' starts the agent again.

{"action":"stopped","unit":"ironflock-device-agent.service","state":"stopped"}

拒绝执行的情况与 agent restart 相同，退出码为 3。回答“否”，或者询问时没有终端且未给出 --yes，命令以退出码 4 结束。

ironflock agent start

代理程序的服务没有运行时启动它，并像 agent restart 那样检查代理程序是否启动起来：其单元必须以一个进程运行五秒钟。已在运行的代理程序保持原样，此时结果中没有 action。

ironflock agent start [flags]

运行平台： 已安装代理程序的 Linux。Root： 需要。询问： 无。该命令没有自己的标志。

# 启动代理程序
sudo ironflock agent start
# 启动代理程序，并以 JSON 形式读取其进程
sudo ironflock agent start --json

$ sudo ironflock agent start
The agent started: ironflock-device-agent.service runs, with process 4242. The device appears online in IronFlock within a minute.

使用 --json 时，对于已在运行的代理程序：

{"unit":"ironflock-device-agent.service","state":"running","main_pid":4242}

拒绝执行和失败的情况与 agent restart 相同：没有安装代理程序、代理程序正在将机器从旧布局迁出，或 systemd 不认识代理程序的单元时，退出码为 3；代理程序没有启动起来时，退出码为 1。

ironflock agent logs

显示代理程序的日志 /var/log/ironflock/device-agent.log，以及代理程序将其轮转而成的文件。不做任何更改。

ironflock agent logs [flags]

运行平台： 已安装代理程序的 Linux；它读取文件，不需要 systemd。Root： 需要，因为代理程序写的日志只有 root 可读（权限 0600）。询问： 无。

日志达到 100 MB 时，代理程序将其重命名为同一文件夹中的 device-agent-<time>.log，并开始写新的日志；它保留两个这样的文件。命令读取日志和这些文件。

代理程序每行写一个 JSON 对象：条目的时间（精确到秒）、级别、消息以及更多字段。文本形式显示条目的方式与 IronFlock Studio 显示代理程序日志的方式相同：UTC 时间、级别、消息及其错误。不是条目的行（例如崩溃时的堆栈跟踪）原样显示。控制字符会被转义（\n、\x1b），因此一个条目在终端上就是一行，无法操控终端。使用 --json 时，每一行都是 stdout 上的一个 JSON 对象：即代理程序写下的条目，带有其全部字段；对于不是条目的行，则为 {"message":...}。

• --since 从该时间或之后的第一个条目开始。各行保持代理程序写入的顺序。没有时间的行属于它前面的条目。
• 带 --follow 时，一行写完整后才会显示。代理程序开始写新文件时，先显示旧文件的剩余部分，再从头显示新文件。尚不存在的日志会等待其出现。Ctrl-C 以退出码 0 结束命令；通过 --host 运行时，Ctrl-C 以退出码 130 结束运行。
• 代理程序尚未写入任何日志时，stderr 会说明这一点，stdout 保持为空，退出码为 0。

示例

# 最后 100 行
sudo ironflock agent logs
# 最近一小时的全部内容
sudo ironflock agent logs --since 1h
# 最后 20 行，然后显示每个新行，直到按下 Ctrl-C
sudo ironflock agent logs --follow --lines 20
# 最近十分钟的内容，以 JSON 形式输出，每行一个对象
sudo ironflock agent logs --since 10m --json

结果

$ sudo ironflock agent logs --lines 3
2026-11-10T11:58:02Z INFO connected to IronFlock
2026-11-10T11:58:03Z INFO 3 apps running
2026-11-10T11:59:40Z ERROR pulling demo-app:1.2 failed: context deadline exceeded

{"level":"info","time":"2026-11-10T11:58:02Z","caller":"agent.go:212","message":"connected to IronFlock"}

拒绝执行的情况

--since 既不是时长也不是时间、时长为负数、--lines 既不是数字也不是 all，都属于错误的命令行（退出码 2）。在以下情况下，命令以退出码 3 拒绝执行：它不是以 root 身份运行；没有安装代理程序（消息会指出 agent install -c <file>）。