安装

一行命令即可在 Linux 或 macOS 上安装 ironflock。它需要 root 权限，因为它会写入 /usr/local/bin。以后，ironflock self-update 会将它更新到最新的发布版本，ironflock version --check 会告诉您是否有更新的发布版本。

curl -fsSL https://instance-registry.ironflock.com/dl/cli/install.sh | sudo bash

安装命令做了什么

1. 它确定机器的系统（Linux 或 macOS）和架构：Linux 上为 amd64、arm64 或 32 位 ARM（v5 至 v7），macOS 上为 Apple 芯片或 Intel。在 Apple 芯片上，在 Rosetta 2 下运行的 shell 同样会得到 Apple 芯片的构建版本。
2. 它从 https://instance-registry.ironflock.com/dl/cli/ 下载 version.txt，以及该版本中适用于这台机器的 ironflock。
3. 它用脚本自带的 IronFlock 发布密钥检查这两个文件。在 Linux 上，它用 sqv 或 gpgv 检查 OpenPGP 签名（.asc）。在 macOS 上，它用系统自带的 /usr/bin/openssl 检查同一密钥的普通 RSA 签名（.sig），因此无需事先安装任何软件。
4. 它将二进制文件安装为 /usr/local/bin/ironflock，替换已有的同名文件。新文件先复制到旧文件旁边，再通过重命名覆盖旧文件，因此此刻正在运行的 ironflock 会继续使用它启动时的二进制文件。在没有 /usr/local/bin 的 Mac 上，脚本会创建该文件夹。
5. 它用 bash -s -- 之后给出的参数运行 ironflock。不带参数时，它只进行安装，并指出下一步。

在一台使用 amd64 CPU 的 Linux 机器上，输出如下：

Download base: https://instance-registry.ironflock.com/dl
Downloading ironflock 2.0.2 (linux/amd64)...
Signature verified (key F6C94D96CE315377ACA7C8EA4990543373212788).
Installed ironflock 2.0.2 as /usr/local/bin/ironflock.

Connect this machine to IronFlock with:
  sudo ironflock agent install -c /path/to/device.flock
All commands: ironflock --help
Tab completion in your shell: ironflock completion --help

在 Mac 上，它指出的下一步是 ironflock os flash，该命令将设备的 IronFlockOS 写入 U 盘或 SD 卡。如果它替换了已有的 ironflock，Installed 这一行会以 , in place of the one that was there. 结尾。

要求

• Root — 脚本会写入 /usr/local/bin。请用 sudo bash 运行它。
• curl 或 wget — 用于下载。
• Linux 上需要 base64，以及 sqv 或 gpgv — 用于检查签名。apt 依赖 sqv 和 gpgv 之一，因此每个 Debian 和 Ubuntu 系统都有其中一个。两者都没有时，脚本会停止，并提示运行 apt install gpgv。
• macOS 上无需额外软件：所需的一切都随系统提供。

脚本由 POSIX shell 运行：bash、sh、dash 或 BusyBox ash 均可。

签名缺失或错误

签名缺失或错误时，脚本会在安装任何内容之前停止，之前已安装的 ironflock 保持原样。脚本以退出码 1 结束，并在 stderr 上输出一行，例如：

install.sh: https://instance-registry.ironflock.com/dl/cli/linux/amd64/2.0.2/ironflock is not signed by IronFlock: not installing it

下载失败时，脚本同样会停止：不会安装任何内容。

用一行命令安装并运行命令

bash -s -- 之后的参数会在 ironflock 安装完成后传给它。下面这行命令安装 ironflock，并将机器作为设备配置文件（.flock）device.flock 所对应的设备连接到 IronFlock：

curl -fsSL https://instance-registry.ironflock.com/dl/cli/install.sh | sudo bash -s -- agent install -c device.flock

在 curl ... | bash 中，脚本的标准输入就是脚本本身。因此，脚本会让 ironflock 从您的终端读取输入，这样命令的询问仍然会显示给您，您照常回答即可。没有终端时（cloud-init 脚本、CI），ironflock 得不到任何输入：会询问的命令以退出码 4 结束，除非您加上 --yes。脚本以 ironflock 的退出码结束。ironflock agent install 介绍了该命令。

更新

sudo ironflock self-update 用最新的发布版本替换 ironflock，替换前进行同样的 IronFlock 发布密钥检查（ironflock self-update）。ironflock version --check 显示您当前的版本，以及是否有更新的发布版本（ironflock version）。

本页顶部的安装命令同样可以更新：再次运行它，它会用当前发布版本替换 /usr/local/bin/ironflock。

在 IronFlockOS 设备上，ironflock 随系统提供，由 ironflock os update 随系统一起更新。

先验证安装脚本

如果想在 install.sh 以 root 身份运行之前先检查它本身，请连同签名一起下载它，导入发布密钥，然后用 gpg 验证签名：

curl -fsSLO https://instance-registry.ironflock.com/dl/cli/install.sh
curl -fsSLO https://instance-registry.ironflock.com/dl/cli/install.sh.asc
curl -fsSL https://instance-registry.ironflock.com/dl/cli/ironflock-bootstrap.asc | gpg --import
gpg --verify install.sh.asc install.sh

gpg 必须报告签名有效，且签名密钥的指纹为 F6C9 4D96 CE31 5377 ACA7 C8EA 4990 5433 7321 2788。请将它与签名密钥页面上的 IronFlock Bootstrap 密钥进行比较。然后运行已验证的脚本，不带参数，或带上传给 ironflock 的参数：

sudo bash install.sh
sudo bash install.sh agent install -c device.flock

下载基址

ironflock 和安装脚本从 IronFlock 云 https://instance-registry.ironflock.com/dl 下载。可以用以下两种方式之一指定其他下载基址，例如您网络中的镜像站。对于 IronFlock Appliance 的设备，有几个命令会自行找到 Appliance 的下载镜像站：

在下载基址之下，安装脚本读取 cli/version.txt 和 cli/<system>/<arch>/<version>/ironflock，以及各自的 .asc 和 .sig 签名。无论下载基址是什么，它都用自带的发布密钥检查这些文件，因此镜像站原样提供 IronFlock 已签名的文件。ironflock 从 ironflockos/ 之下读取 IronFlockOS 目录和镜像，从 device-agent/ 之下读取设备代理程序，并从 cli/ 之下读取最新的发布版本（version.txt，用于 self-update 和 version --check）以及 ironflock 二进制文件（用于 self-update，以及为 --host 读取其他平台的二进制文件）。

默认情况下，sudo 不会传递您 shell 中的变量。请在 sudo 之后设置该变量，或者使用标志：

# 从镜像站安装 ironflock
curl -fsSL https://mirror.example.com/dl/cli/install.sh | sudo IRONFLOCK_DL_BASE=https://mirror.example.com/dl bash
 
# 用镜像站中的代理程序连接这台机器
sudo ironflock agent install -c device.flock --download-base https://mirror.example.com/dl

有两个命令以不同方式使用下载基址。agent update 让代理程序从它自己的更新服务器（其 .flock 文件中的 update_url）更新，下载基址不会改变这一点。os update 依次采用标志、变量，最后是代理程序 .flock 文件中的 update_url。通过 --host 运行时，下载基址会一并传给另一台机器；含有登录信息的下载基址（https://user:[email protected]/dl）会在连接任何机器之前以退出码 2 结束。

IronFlock Appliance 的设备

IronFlock Appliance 签发的 .flock 文件将 Appliance 的下载镜像站指定为代理程序的更新服务器（update_url），例如 http://10.0.0.5:15002/dl，或者在 Appliance 使用域名运行时为 https://registry.<domain>/dl。既没有设置 --download-base、也没有设置 IRONFLOCK_DL_BASE 时，agent install、doctor 和 os install 从该镜像站获取文件，因此能访问 Appliance、但无法访问 ironflock.com 的机器也可以被连接或转换。IronFlock 云的 .flock 文件指定的是云的主机，使用云。

• 镜像站没有提供的文件，从 IronFlock 云下载基址之下的相同路径获取，并给出警告：agent install 在 stderr 上输出一行 Warning:，并在 --json 结果的 warnings 中加一项；os install 在计划中给出警告；doctor 让检查项 download_tree 给出 warning。只有当镜像站和云都不提供某个文件时，agent install 和 os install 才会失败，错误会同时指出两者。
• agent install 和 os install 直接访问镜像站，经代理（如果有）访问云。
• 使用 Appliance 自有 CA 签发证书的 HTTPS 镜像站，只有在机器的系统信任该 CA 时才能使用。

有些下载仍然来自别处：

• install.sh 和 ironflock 二进制文件来自 ironflock.com。使用 --host 时，二进制文件从您的计算机传到该机器（通过 SSH 管理远程机器）。
• agent install 从发行版和 Docker 自己的服务器获取软件包和 Docker。
• self-update 和 version --check 依次读取标志、变量，否则使用 IronFlock 云，不使用 Appliance 的镜像站。

安装之后，代理程序从 Appliance 获取更新。参见边缘设备。

Tab 补全

ironflock completion 输出一段脚本，让您的 shell 在您按下 Tab 键时补全 ironflock 命令行。

ironflock completion <shell>

shell 可以是 bash、zsh 或 fish。可在 Linux 和 macOS 上运行。无需 root。不询问任何内容。该命令没有自己的标志；适用全局标志。

运行与您的 shell 对应的那一行，即可在当前输入命令的 shell 中启用补全。将该行添加到第三列所列的文件中，即可在每个新 shell 中启用补全：

该脚本可以补全：

• 命令及其标志；
• 只取少数几个值之一的标志的值：os images 的 --channel、--variant 和 --kernel，os update 的 --channel，以及 os flash 的 --installer-confirm、--installer-after 和 --installer-allow-usb；
• -c 的 .flock 文件；
• --hosts、--proxy-password-file、--wifi-password-file、--image-file、--output、--drive 和 --disk 的文件名，使用 shell 自己的文件名补全。

其他标志以及其他命令的参数不会补全。补全时，脚本向 ironflock 询问匹配的词，ironflock 根据自己的命令列表作答：补全不会运行任何命令、不会列出驱动器、不会下载任何内容，也不会连接其他机器，即使命令行中含有 --host 也是如此。带 --host 或 --hosts 时，ironflock completion 与 --help 一样在本机作答。

# 在当前输入命令的 bash 中启用补全
eval "$(ironflock completion bash)"
 
# 在每个新的 bash 中启用补全
echo 'eval "$(ironflock completion bash)"' >> ~/.bashrc

$ eval "$(ironflock completion bash)"
$ ironflock os images --kernel <Tab>
rt   std

使用 --json 时，结果是放在一个 JSON 对象中的脚本：

{"shell":"bash","script":"..."}

缺少 shell、shell 未知或给出多个 shell，都属于错误的命令行：退出码 2，错误信息会列出它接受的 shell。

ironflock version

输出 ironflock 二进制文件的版本及其构建所针对的平台。使用 --check 时，它还会询问下载服务器是否有更新的发布版本。

ironflock version [flags]

可在 Linux 和 macOS 上运行。无需 root。不询问任何内容。适用全局标志。

# 这台机器上 ironflock 的版本
ironflock version
 
# 以 JSON 形式输出同样的内容
ironflock version --json
 
# 通过 SSH 在另一台机器上运行的二进制文件：版本相同，平台为那台机器的平台
ironflock --host pi@device-17 version
 
# 有没有更新的发布版本？
ironflock version --check

ironflock 2.0.2 linux/amd64

{"version":"2.0.2","os":"linux","arch":"amd64"}

通过 --host 运行时，平台是另一台机器的平台，例如 ironflock 2.0.2 linux/arm64：另一台机器运行的是同一版本、针对其自身平台构建的二进制文件。

开发构建会写明其提交：2.0.0-23-g5b38681 是提交 5b38681 的构建，位于发布版本 2.0.0 之后的第 23 个提交。

有没有更新的发布版本？

--check 读取下载基址（--download-base，否则 IRONFLOCK_DL_BASE，否则 IronFlock 云）中的 cli/version.txt，并用二进制文件自带的 IronFlock 发布密钥对照其签名（.asc）进行检查。它通过 agent configure 所设置的代理（/etc/ironflock/proxy.env）发出请求，否则通过环境中的代理。该文件只有 root 可读，因此没有 root 时它使用环境中的代理。只有 version --check 和 self-update 会查询最新的发布版本；没有任何命令会自行查询。

stdout 上的第二行说明查询结果，以及用什么安装更新的发布版本：self-update，在 IronFlockOS 上则是 os update。

$ ironflock version --check
ironflock 2.0.3 linux/amd64
ironflock 2.1.0 is out at https://instance-registry.ironflock.com/dl. 'sudo ironflock self-update' installs it.

version.txt 指定的正是这个二进制文件的版本时，第二行为 This is the newest release.。这个二进制文件更新（即发布版本之后的开发构建）时，该行会说明这一点。开发构建 x.y.z-N-g<commit> 视为比发布版本 x.y.z 新、比下一个发布版本旧；N = 0 时它与 x.y.z 相同，该行会说明没有更新的发布版本。

使用 --json 时，对象多出两个字段：latest_version，即 version.txt 所指定的版本；newer，即它是否比这个二进制文件新。

{"version":"2.0.3","os":"linux","arch":"amd64","latest_version":"2.1.0","newer":true}

无论是否有更新的发布版本，退出码都是 0。服务器没有响应、没有 version.txt，或者 version.txt 不是由该密钥签名时，退出码为 1。通过 --host 运行时，第一行与 version 一样指出本次构建的二进制文件，由另一台机器向服务器查询。

ironflock self-update

用最新的发布版本替换正在运行的 ironflock 二进制文件，或者替换为 --version 所指定的发布版本（也可以是较旧的版本）。在磁盘上的任何内容发生更改之前，会先用 IronFlock 发布密钥检查该发布版本。

ironflock self-update [flags]

运行平台： Linux 和 macOS；不支持 IronFlockOS。Root： 对 /usr/local/bin/ironflock 需要（谁可以替换二进制文件）。询问： 是，在说明哪个发布版本替换哪个之后询问；--yes 作答。

# 将 ironflock 更新到最新的发布版本；命令会先询问
sudo ironflock self-update
 
# 不询问地更新，并以 JSON 形式读取结果
sudo ironflock self-update --yes --json
 
# 退回较旧的发布版本
sudo ironflock self-update --version 2.0.3
 
# 更新另一台机器上安装的 ironflock
ironflock --host pi@device-17 self-update --yes

替换什么，用什么替换

• 文件。 正在运行的二进制文件，所有符号链接都会解析：被替换的是链接指向的文件，链接本身保留。命令最先指出该文件。代理程序安装所用的文件夹 /opt/ironflock/device-init 存放该安装的记录，其中没有 ironflock，命令不会触碰它。
• 发布版本。 不带 --version 时为最新版本：即下载基址（--download-base，否则 IRONFLOCK_DL_BASE，否则 IronFlock 云）中 cli/version.txt 所指定的版本，也就是安装命令所读取的文件。发布版本的二进制文件为 cli/<system>/<arch>/<version>/ironflock。没有通道：另一棵目录树就是另一个下载基址，例如镜像站。
• 代理。 下载通过 agent configure 所设置的代理（/etc/ironflock/proxy.env）进行，否则通过环境中的 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY。sudo 和通过 --host 运行的命令的环境中没有代理。该文件属于 root，因此没有 root 的运行使用环境中的代理，并会说明这一点。命令使用该文件中的代理时也会说明。
• 无需操作。 二进制文件已经是该发布版本，或者比它更新（即它之后的开发构建）时，命令会说明这一点并以退出码 0 结束，不询问也不下载；结果的 outcome 为 current。不带 --version 时，它绝不会退回较旧的发布版本。

检查

在替换二进制文件之前：

1. 用正在运行的二进制文件自带的 IronFlock 发布密钥，对照签名检查 version.txt。
2. 用同一密钥对照签名检查新的二进制文件，并检查其构建信息：程序为 ironflock，针对本平台，由未经修改的源代码树构建。
3. 将它写到旧文件旁边的同一文件夹中，采用旧文件的权限、所有者和组，并运行一次（version --json）。它必须说明自己是所请求的发布版本、针对本平台。签名并不绑定版本，因此用较旧的已签名二进制文件冒充最新版本时，会在这一步被拒绝。
4. 只有这时，才会通过一次重命名将它覆盖旧文件。

不需要 sqv 或 gpgv：ironflock 自己检查签名。

未通过检查的文件绝不会替换二进制文件，旁边的新文件也会被再次删除。失败、被拒绝或被中断的运行会让旧的二进制文件保持原样。替换文件时正在运行的 ironflock 命令会继续使用它启动时的文件。在写入和重命名之间第二次按下 Ctrl-C 或断电，可能会留下新文件（二进制文件旁边的 .ironflock.new-*）；请手动删除它。

谁可以替换二进制文件

命令需要对二进制文件所在文件夹的写权限，并且必须以二进制文件的所有者身份运行、属于其所属组，或者以 root 身份运行，这样新文件才能保留所有者和组。对于安装命令放置的 /usr/local/bin/ironflock，这意味着需要 root。否则，命令在下载任何内容之前以退出码 3 结束，指出所有者或组，并给出带 sudo 的命令行。

IronFlockOS 与其他机器

• IronFlockOS 随系统提供 ironflock，每次操作系统更新都会整体替换系统。在那里，命令在检查任何内容之前以退出码 3 结束，并指出 os update。在 IronFlockOS 安装 U 盘上，它像 agent 命令一样拒绝执行。
• 通过 --host 运行时，正在运行的二进制文件是本次运行的副本，命令结束时会被删除。因此，命令改为更新该机器上的 /usr/local/bin/ironflock。没有该文件时，它以退出码 3 结束，并指出安装命令。已安装的 ironflock 无法运行或无法说明其版本时，同样会在下载任何内容之前以退出码 3 结束：请用安装命令重新安装 ironflock。
• 在多台机器上（多次给出 --host，或使用 --hosts）带 --yes 运行时，每台机器更新自己的 /usr/local/bin/ironflock。

结果

$ sudo ironflock self-update
This ironflock is 2.0.3, at /usr/local/bin/ironflock.
Download base: https://instance-registry.ironflock.com/dl (from default)
The downloads go through the proxy of the install's record (/etc/ironflock/proxy.env).
The newest release at https://instance-registry.ironflock.com/dl is ironflock 2.1.0 (its version.txt is signed by key F6C94D96CE315377ACA7C8EA4990543373212788).
ironflock 2.1.0 replaces 2.0.3 at /usr/local/bin/ironflock.
A command of ironflock that runs now goes on with 2.0.3; the next one runs 2.1.0.
? Install ironflock 2.1.0? Yes
Downloading ironflock 2.1.0 for linux/amd64 from https://instance-registry.ironflock.com/dl.
Signature verified (key F6C94D96CE315377ACA7C8EA4990543373212788): the program ironflock for linux/amd64.
The new file says it is ironflock 2.1.0 linux/amd64; it is in place.
ironflock at /usr/local/bin/ironflock is updated from 2.0.3 to 2.1.0.

二进制文件在回答之后才下载。没有终端或使用 --json 时，命令需要 --yes。使用 --json 时，对于已经是最新发布版本的二进制文件：

{"outcome":"current","path":"/usr/local/bin/ironflock","version":"2.1.0","latest_version":"2.1.0"}

退出码