ImmortalWrt Image Builder 使用说明

[1715173329]

什么是 Image Builder

Image Builder（原 Image Generator、简称 IB）是一个预编译环境，允许构建自定义固件映像而无需从源码编译。它支持下载预编译软件包并将其集成进固件中。

Image Builder 适用于：

• 在存储空间有限的设备中集成更多软件包
• 为内存/存储空间极其有限的设备进行内容裁剪
• 需要批量部署特定配置的固件，或自定义固件实现刷入即用
• 追新
• ...

Image Builder 不适用于：

• 编译/修改软件包（SDK）
• 自定义内核、设备树等任何需要重新编译的内容
• ...

依赖要求

要使用 Image Builder，需要预先安装对应的依赖，请参阅 Build system setup。

• 对于 Debian 系发行版，您可以执行以下命令完成最基础的依赖安装：

  sudo apt-get install -y build-essential libncurses5-dev libncursesw5-dev \
    zlib1g-dev gawk genisoimage git gettext libssl-dev xsltproc rsync wget \
    unzip python3

• 对于 Arch Linux 系发行版：

  sudo pacman -S --needed base-devel cdrtools ncurses zlib gawk git \
    gettext openssl libxslt wget unzip python

Important

上述软件包只包括使用 Image Builder 所必须的依赖。部分目标可能需要额外安装依赖，请善用搜索引擎。

---

获取 Image Builder

您可以下载由 ImmortalWrt 项目提供的预编译 Image Builder，也可以自行从源码构建，在 buildroot 中启用 CONFIG_IB 即可。预编译 Image Builder 与固件映像位于同一文件夹中。

如需下载 ImmortalWrt 项目提供的预编译 Image Builder，但不确定自己设备的目标平台，可以使用 固件选择器。
输入设备名称，并点击 链接 一栏的 文件夹 图标，将会自动跳转到下载页面。

Image Builder 统一命名为 immortalwrt-imagebuilder[-<version>]-<platform>.Linux-<ib_arch>.tar.xz
如 immortalwrt-imagebuilder-21.02.6-ath79-generic.Linux-x86_64.tar.xz

• 如果使用 docker，可以直接 pull 我们提供的镜像：

  docker run --rm -it immortalwrt/imagebuilder:ath79-generic-openwrt-21.02.6

  您可以在 此处 获取所有可用 tags。

Warning

ImmortalWrt 项目所提供的预编译 Image Builder 仅供 x86_64 / AMD64 平台使用，其他架构则需要自行构建。

Note

ImmortalWrt 目前拥有多个镜像站，您可以从最快的镜像中下载：
https://downloads.immortalwrt.org/acknowledgements.html

使用 Image Builder

Warning

以下所有操作必须以非特权用户（non-root）身份执行。

Note

可观看 Youtube 视频教程：Imagebuilder实用教程。

构建变量

可使用以下变量自定义构建固件：

变量名称	描述
PROFILE	指定需要构建的设备
PACKAGES	需要集成进固件的软件包列表
FILES	要集成的自定义文件的目录
BIN_DIR	固件输出文件夹（默认 bin）
EXTRA_IMAGE_NAME	自定义附加固件文件名
DISABLED_SERVICES	/etc/init.d 中要禁用的服务名称，如 dnsmasq 的 dhcp

确定设备

PROFILE 变量指定要构建的目标固件。

PROFILE="profile-name"

运行 make info 以获取可用的设备列表以及默认软件包配置。

Note

在 ath79、ramips 这样设备非常多的目标下，直接运行 make info 会污染整个屏幕且无法查看完整列表。
可以配合 less 等命令一起使用，如 make info | less。

确定软件包

PACKAGES 变量允许在固件中集成 和/或 去除软件包。

PACKAGES="pkg1 pkg2 pkg3 -pkg4 -pkg5 -pkg6"

上面的示例将集成 pkg1、pkg2、pkg3，并去除 pkg4、pkg5、pkg6。请注意在需要去除的软件包前添加 -。
您无需在此处指定目标软件包的依赖项，Image Builder 会自动使用 opkg 解析并安装它们。

可以通过以下命令获取当前设备上已安装的软件包：

echo $(opkg list-installed --strip-abi | sed -e "s/\s.*$//")

可以访问以下地址获取 ImmortalWrt 所有可用软件包：

• 目标软件包：https://downloads.immortalwrt.org/<version>/targets/<platform>/packages/Packages
• 架构软件包：https://downloads.immortalwrt.org/<version>/packages/<architecture>/<feed>/Packages

Note

在 Image Builder 中，opkg 不会自动安装翻译文件。如需安装 LuCI 插件，在存在翻译文件的情况下，请优先写翻译包的名称。
如 luci-app-zerotier 则填写 luci-i18n-zerotier-zh-cn。

Warning

通常硬路由的存储空间有限，请不要无限制地添加软件包。
确保所集成的软件包不会超出存储空间大小，否则将导致设备无法启动。
如设备空间极其有限，请考虑 移除不必要的软件包。

自定义软件包

如果您想集成 ImmortalWrt 中没有的软件包，可以在 Image Builder 根目录下新建一个名为 packages 的文件夹，将 ipk 文件放置其中，并将其添加到 PACKAGES 变量 。

自定义文件

FILES 变量允许将自定义文件集成进 Image Builder 构建的固件中。如果您需要修改默认网络配置，或批量部署固件，则此功能非常实用。

FILES="files"

Note

files 文件夹应放置在 Image Builder 根目录，或指定绝对路径。
files 文件夹中的内容将 1:1 覆盖并集成进最终固件文件中。

Important

强烈建议使用 uci-defaults 完成对已有配置文件的“增量”修改。这有助于减少与默认配置的冲突，因为它们可能在不同的版本之间发生变化。
参阅：uci-default_example。

自定义配置

部分配置无法通过变量指定，如 x86/64 平台的构建固件类型以及固件 rootfs 大小，需要通过手动修改 .config 文件实现。

修改默认 rootfs 大小（单位：MiB）：

CONFIG_TARGET_ROOTFS_PARTSIZE=800

取消构建 ISO 固件：

# CONFIG_ISO_IMAGES is not set

自定义软件源

默认 Image Builder 配置为从官方源下载所有非默认软件包。软件源配置在根目录的 repositories.conf 文件中。

如需添加外部软件源，请确保将对应的公钥放置在根目录的 keys 文件夹中，或注释掉 repositories.conf 中的 option check_signature（不推荐）。

Important

如需覆盖 ImmortalWrt 软件源中已有的软件包，请确保将您自己的源放置在默认源上方。

Note

ImmortalWrt 目前拥有多个镜像站，您可以配置从最快的镜像中下载：
https://downloads.immortalwrt.org/acknowledgements.html
https://help.mirrorz.org/immortalwrt/

构建固件

当您确定以上构建内容后，将其传递到 make image 后：

make image PROFILE="profile-name" PACKAGES="pkg1 pkg2 pkg3 -pkg4 -pkg5 -pkg6" FILES="files"

make 命令完成后，生成的固件文件将存放在 $BIN_DIR/targets/<platform> 目录中，就像编译它们一样。

清理构建文件

要清理临时构建文件和生成的固件文件，请使用 make clean 命令。

构建示例

本示例将为 x86/64 固件集成自定义网络配置文件和 zerotier。

mkdir -p files/etc/config
scp root@192.168.1.1:/etc/config/network files/etc/config/
scp root@192.168.1.1:/etc/config/wireless files/etc/config/
scp root@192.168.1.1:/etc/config/firewall files/etc/config/

make image PROFILE="generic" PACKAGES="luci-i18n-zerotier-zh-cn" FILES="files"

最终固件存放在 bin/targets/x86/64 文件夹下。

---

参考

• [OpenWrt Wiki] Using the Image Builder

[0xffffharry]

是否可以根据dts调整布局

[EkkoG]

多谢博主的教程，很有启发，本来打算在 GitHub actions 上使用 ib 的 docker 镜像构建，奈何权限问题恶心。

给友友们来个示例吧：https://github.com/douglarek/build-immortalwrt 。

可以选择用 ImageBuilder 的 docker 镜像来构建，不用处理依赖 https://github.com/EkkoG/OpenWrt/blob/master/.github/workflows/main.yml

[GoogleBeEvil]

有一个问题： uci-defaults 这里 想设置路由默认登陆ip为192.168.111.1，是需要在files文件夹下创建对应的层级目录
files/etc/uci-defaults/99-custom然后把一下内容写入99-custom么

lan_ip_address="192.168.111.1"
if [ -n "$lan_ip_address" ]; then
  uci set network.lan.ipaddr="$lan_ip_address"
  uci commit network
fi
echo "All done!"

[lambdaplus]

有一个问题： uci-defaults 这里 想设置路由默认登陆ip为192.168.111.1，是需要在files文件夹下创建对应的层级目录 files/etc/uci-defaults/99-custom然后把一下内容写入99-custom么

lan_ip_address="192.168.111.1"
if [ -n "$lan_ip_address" ]; then
  uci set network.lan.ipaddr="$lan_ip_address"
  uci commit network
fi
echo "All done!"

我是这样写的

# set lan ip
uci batch << EOF

set network.lan.ipaddr='192.168.111.1'

commit
EOF