Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision Next revisionBoth sides next revision | ||
| zh:docs:guide-user:additional-software:imagebuilder [2021/10/15 08:27] – ↷ Links adapted because of a move operation bobafetthotmail | zh:docs:guide-user:additional-software:imagebuilder [2024/11/30 14:58] – [详细帮助] starsfall | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ====== 使用ImageBuilder | + | ====== 使用Image Builder |
| - | Image Builder(以前称为Image Generator)是一个预编译环境,适用在不从源代码编译的情况创建自定义镜像文件。 | + | 另请参阅: |
| - | 它下载预编译的软件包并集成在一个可擦写的镜像中。 | + | [[docs: |
| + | [[docs: | ||
| + | [[docs: | ||
| - | 适用于以下场景: | + | Image Builder (以前称为 Image Generator) 是一个预编译环境, |
| - | * 您想在有限闪存中放入更多软件包。 | + | 它下载预编译的软件包并将它们集成到单个可闪存映像中. |
| - | * 您想跟进用于开发的“快照版”。 | + | |
| - | * 您的设备只有32MB或更低的内存,以至于opkg无法很好的工作。 | + | |
| - | * 您想要将特殊定制的固件刷入大量设备。 | + | |
| - | 实现相同目标的替代指南有: | + | 在以下情况下, |
| - | [[docs: | + | * 您想在较小的闪存中容纳更多的封装 |
| - | [[docs: | + | * 你想关注开发快照 |
| + | * 您的设备具有 32MB 或更少的 RAM 并且 opkg 无法正常工作 | ||
| + | * 你想批量刷新几十个设备,你需要一个特定的映像设置 | ||
| - | 如果您的设备拥有很小的固件空间,您可以考虑移除一些软件包以[[docs: | + | <WRAP important> |
| + | Image Builder 映像与官方映像不同, | ||
| + | 在进行 recent/ | ||
| + | </ | ||
| - | ===== 基于imagebuilder的前端 ===== | ||
| - | 已有一系列工具为imagebuilder提供基于页面或配置模版的前端,详情查阅[[zh: | ||
| ===== 先决条件 ===== | ===== 先决条件 ===== | ||
| - | :!: Image Builder仅可运行在64位Linux环境下,您甚至可以在32位Windows系统的虚拟机(如virtualbox)中运行64位的Linux。\\ | + | <WRAP important> |
| - | :!: Image Builder具有构建系统的一些相同先决条件[[docs: | + | * Image Builder 仅在 64 位 Linux 中运行. 但您可以在 |
| + | | ||
| + | </ | ||
| - | 最常见的发行版中的依赖关系示例: | + | 最常见发行版中的示例依赖项: |
| - | < | + | |
| - | < | + | ==== Arch ==== |
| - | yum group install " | + | < |
| + | sudo pacman -S --needed base-devel | ||
| + | openssl libxslt wget unzip python python-distutils-extra | ||
| + | </ | ||
| - | < | + | ==== Fedora |
| - | ===== 获取镜像生成工具 ===== | + | < |
| - | 您可以下载包含**Image Builder**的压缩文件,它通常在您找到设备固件映像文件的同一下载页面中。 | + | sudo dnf install |
| - | 例如,您在以下页面可以下载**ar71xx/ | + | openssl-devel libxslt wget which @c-development @development-tools |
| - | https:// | + | @development-libs zlib-static which python3 perl |
| + | </ | ||
| - | 当然,**Image Builder**也可以由构建系统生成,因为需要创建映像文件。如果启用了'' | + | ==== Debian |
| + | <code bash> | ||
| + | sudo apt install build-essential libncurses-dev zlib1g-dev gawk git \ | ||
| + | gettext libssl-dev xsltproc rsync wget unzip python3 python3-distutils | ||
| + | </code> | ||
| - | ===== 配置软件包存储库 ===== | + | ==== WSL ==== |
| - | 您从OpenWrt页面下载的'' | + | 此方法未得到官方支持。 |
| - | 软件包源在解压目录中的'' | + | |
| - | **openwrt-imagebuilder-18.06.0-rc2-ramips-mt7621.Linux-x86_64.tar.xz**中'' | + | 但它有效。 [[docs: |
| - | < | + | 建议使用 VirtualBox 配合 Debian 或 DietPi(Debian) 使用,以减少资源和配置。 |
| - | # src/gz %n http:// | + | |
| - | # src custom file:/// | + | |
| - | ## Remote package repositories | + | ===== 获取 Image Builder ===== |
| - | src/gz openwrt_core http:// | + | 您可以下载包含 **Image Builder** 的存档, 它通常位于您找到设备固件映像的同一下载页面中. |
| - | src/gz openwrt_base http:// | + | |
| - | src/gz openwrt_luci http:// | + | |
| - | src/gz openwrt_packages http:// | + | |
| - | src/gz openwrt_routing http:// | + | |
| - | src/gz openwrt_telephony http:// | + | |
| - | ## This is the local package repository, do not remove! | + | 例如, 这是您可以下载 **ath79/ |
| - | src imagebuilder | + | [[https:// |
| + | 您会找到一个 **openwrt-imagebuilder-ath79-generic.Linux-x86_64.tar.xz** 包含映像生成器的存档. | ||
| + | 此外, 它始终由构建系统创建, | ||
| + | 如果启用了 " | ||
| + | |||
| + | ===== 用法 ===== | ||
| + | <WRAP important> | ||
| + | 所有操作都应使用非 root 用户帐户执行. | ||
| + | </ | ||
| + | |||
| + | 解压存档并更改工作目录: | ||
| + | |||
| + | <code bash> | ||
| + | tar -J -x -f openwrt-imagebuilder-*.tar.xz | ||
| + | cd openwrt-imagebuilder-*/ | ||
| </ | </ | ||
| - | 您从源代码编译而来的'' | + | 可以使用以下变量自定义映像构建: |
| - | 如果您要添加自定义本地存储库,请复制以下代码: < | + | ^ 变量 ^ 描述 ^ |
| - | 并将其修改为指向您拥有软件包和软件包列表的本地文件夹。 | + | | '' |
| - | 如果您有在线的自定义存储库,请复制以下代码并替换修改:< | + | | '' |
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | | '' | ||
| + | 运行 '' | ||
| - | ===== 用法 ===== | + | ==== 选择配置文件 |
| - | **生成映像(make image)** | + | 该 '' |
| - | 为了改善默认配置不尽如人意的表现,你可以尝试传递参数改变以下三个变量: | + | <code bash> |
| + | PROFILE=" | ||
| + | </ | ||
| - | * //'' | + | 运行 |
| - | * //'' | + | |
| - | * //'' | + | |
| - | 首先给出简单的命令示例: | + | ==== 选择插件 ==== |
| - | < | + | 该 '' |
| + | 默认情况下( PACKAGES 变量值为空), | ||
| - | 接着结合以下部分来做更详尽的解释。在make命令完成后,生成的映像就会被存在bin/// | + | <code bash> |
| + | PACKAGES=" | ||
| + | </code> | ||
| - | 这是**make help**输出的结果:\\ | + | 上面的例子将安装 |
| - | Available Commands: | + | |
| - | help: This help text | + | |
| - | info: Show a list of available target profiles | + | |
| - | clean: | + | |
| - | image: | + | |
| - | + | ||
| - | Building images: | + | |
| - | By default 'make image' will create an image with the default | + | |
| - | target profile and package set. You can use the following parameters | + | |
| - | to change that: | + | |
| - | + | ||
| - | make image PROFILE="< | + | |
| - | make image PACKAGES="< | + | |
| - | make image FILES="< | + | |
| - | make image BIN_DIR="< | + | |
| - | make image EXTRA_IMAGE_NAME="< | + | |
| - | The built image will be found under the subdirectory | + | 您无需在此列表中列出您需要的插件的所有依赖项,Image Builder 使用 |
| - | ==== PROFILE Variable ===== | + | |
| - | Syntax:< | + | |
| - | === Pre-defined Profiles | + | 可以使用以下命令获取设备上当前安装的插件列表: |
| - | Run '' | + | |
| - | Example output from '' | + | <code bash> |
| + | echo $(opkg list-installed | sed -e " | ||
| + | </ | ||
| + | |||
| + | <WRAP important> | ||
| + | 许多设备的存储容量有限,并且不能保证构建系统会检测到何时添加了过多的软件包以至于超出设备存储空间。如果安装过多软件包,可能会导致设备无法启动。如果有疑问,不要过度添加。以设备上安装成功的内容为指导,或者先创建一个最小的镜像,安装到设备上并首先测试要添加的内容。考虑删除不必要的软件包以 [[docs: | ||
| + | </ | ||
| + | |||
| + | 此外,诸如 '' | ||
| + | 当这些作为插件提供时, | ||
| + | 为避免出现问题, | ||
| + | 该 '' | ||
| + | |||
| + | ==== 添加额外插件 ==== | ||
| + | |||
| + | 如果有你喜欢使用的插件或 '' | ||
| + | |||
| + | ==== 自定义文件夹 ==== | ||
| + | 该 '' | ||
| + | 如果您需要在刷机前更改默认网络配置, | ||
| + | |||
| + | <code bash> | ||
| + | FILES=" | ||
| + | </ | ||
| + | |||
| + | 该 '' | ||
| + | |||
| + | 强烈建议使用 [[docs: | ||
| + | 这有助于最大限度地减少与自动生成的设置的冲突, | ||
| + | |||
| + | 参考: [[: | ||
| + | |||
| + | ==== Building image ==== | ||
| + | 选择适当的配置文件, | ||
| + | |||
| + | <code bash> | ||
| + | make image \ | ||
| + | PROFILE=" | ||
| + | PACKAGES=" | ||
| + | FILES=" | ||
| + | DISABLED_SERVICES=" | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | 构建的固件将在子目录下找到 '' | ||
| + | |||
| + | ==== 清理编译 ==== | ||
| + | 要清理临时构建文件和生成的固件,请使用该 '' | ||
| + | |||
| + | ==== 例子 ==== | ||
| + | 以下示例显示: | ||
| + | * 为配置文件创建目录. | ||
| + | * 使用 '' | ||
| + | * 使用自定义插件和 '' | ||
| + | |||
| + | <code bash> | ||
| + | mkdir -p files/ | ||
| + | scp root@192.168.1.1:/ | ||
| + | scp root@192.168.1.1:/ | ||
| + | scp root@192.168.1.1:/ | ||
| + | make image PROFILE=" | ||
| + | </ | ||
| + | |||
| + | ===== 故障排除 ===== | ||
| + | - 您是否以非 root 用户身份运行所有内容? | ||
| + | - 检查日志输出, | ||
| + | - 检查日志输出, | ||
| + | - 每天等待几个小时上游 packages 可能处于不一致状态, | ||
| + | - 验证您拥有受支持的操作系统, | ||
| + | |||
| + | ===== 附加功能 ===== | ||
| + | T以下主题不仅限于简单的使用,而且面向开发人员和高级用户. | ||
| + | |||
| + | ==== 详细帮助 ==== | ||
| + | 另请参阅 [[https:// | ||
| + | |||
| + | 获取详细帮助: | ||
| - | == ar71xx-generic Profiles == | ||
| < | < | ||
| + | # make help | ||
| + | |||
| + | 可用命令参数: | ||
| + | help: | ||
| + | info: | ||
| + | clean: | ||
| + | image: | ||
| + | |||
| + | 构建镜像: | ||
| + | 默认情况下 'make image' 将使用默认的目标配置文件和包集创建一个镜像. | ||
| + | 您可以使用以下参数进行更改: | ||
| + | |||
| + | make image PROFILE="< | ||
| + | make image PACKAGES="< | ||
| + | make image FILES="< | ||
| + | make image BIN_DIR="< | ||
| + | make image EXTRA_IMAGE_NAME="< | ||
| + | make image DISABLED_SERVICES="< | ||
| + | make image ADD_LOCAL_KEY=1 # 在构建的映像中存储本地生成的签名密钥 | ||
| + | make image ROOTFS_PARTSIZE="< | ||
| + | |||
| + | 打印清单: | ||
| + | 列出安装到固件映像中的 " | ||
| + | 您可以使用以下参数: | ||
| + | |||
| + | make manifest PROFILE="< | ||
| + | make manifest PACKAGES="< | ||
| + | make manifest STRIP_ABI=1 # 从打印的插件名中删除 ABI 版本 | ||
| + | </ | ||
| + | |||
| + | <color # | ||
| + | ==== 可用配置文件 ==== | ||
| + | 列出可用的配置文件: | ||
| + | |||
| + | < | ||
| + | # make info | ||
| + | |||
| Available Profiles: | Available Profiles: | ||
| Line 116: | Line 236: | ||
| rp-n53: | rp-n53: | ||
| Asus RP-N53 | Asus RP-N53 | ||
| - | Packages: | + | Packages: |
| rt-n14u: | rt-n14u: | ||
| Asus RT-N14u | Asus RT-N14u | ||
| - | Packages: | + | Packages: |
| whr-1166d: | whr-1166d: | ||
| Buffalo WHR-1166D | Buffalo WHR-1166D | ||
| - | Packages: | + | Packages: |
| whr-300hp2: | whr-300hp2: | ||
| Buffalo WHR-300HP2 | Buffalo WHR-300HP2 | ||
| Packages: | Packages: | ||
| - | -and many many more- | + | ... |
| </ | </ | ||
| - | After you find the appropriate profile pass it to the '' | + | ==== 构建包含所有插件的 Image Builder ==== |
| + | 可以使用 buildroot 来创建您自己的 Image Builder 并将所有插件集成到其中, | ||
| - | For example, if we wanted to generate a default image for for Asus RT-N14u (from above). | + | 在图形配置中, 选择 " |
| + | 如果遇到无法编译的未维护插件, | ||
| - | < | + | 不要在路径中调用 '' |
| - | $ make image PROFILE=rt-n14u | + | |
| + | ==== Adding package repositories ==== | ||
| + | The Image Builder you download from the OpenWrt pages is already configured to download any non-default packages from official repositories. | ||
| + | The package sources are configured in the '' | ||
| + | Sources are specified in //opkg// native config format. | ||
| + | This can be either the official package repositories or custom generated repositories. | ||
| + | |||
| + | An example of the contents of the '' | ||
| + | |||
| + | < | ||
| + | ## Place your custom repositories here, they must match the architecture and version. | ||
| + | # src/gz %n http:// | ||
| + | # src custom file:/// | ||
| + | |||
| + | ## Remote package repositories | ||
| + | src/gz openwrt_core http:// | ||
| + | src/gz openwrt_base http:// | ||
| + | src/gz openwrt_luci http:// | ||
| + | src/gz openwrt_packages http:// | ||
| + | src/gz openwrt_routing http:// | ||
| + | src/gz openwrt_telephony http:// | ||
| + | |||
| + | ## This is the local package repository, do not remove! | ||
| + | src imagebuilder file: | ||
| </ | </ | ||
| - | ==== PACKAGES Variable ==== | + | The '' |
| - | The '' | + | |
| - | Syntax:< | + | If you want to add a custom local repository, copy the '' |
| - | The example above will include pkg1, pkg2, pkg3, and exclude pkg4, pkg5, pkg6, note the "-" | + | If you have problems with using you local repository because |
| - | You don't need to list all dependencies of the packages | + | If you have custom repositories online, copy and modify |
| - | **Tip:** The list of currently installed | + | NOTE: if you want to override |
| - | < | + | |
| - | ==== FILES Variable | + | ==== Restricting root access |
| - | The '' | + | Create a non-privileged admin user and lock root password. |
| + | Configure privilege elevation | ||
| + | Set up key-based authentication and disable password authentication for Dropbear. | ||
| - | Syntax: | + | < |
| - | < | + | mkdir -p files/ |
| + | cat << " | ||
| + | USER_NAME=" | ||
| + | USER_GROUP=" | ||
| + | USER_SSHPUB=" | ||
| + | USER_SHELL="/ | ||
| + | SUDO_USER=" | ||
| + | SUDO_GROUP=" | ||
| + | SUDO_GID=" | ||
| + | uci set dropbear.@dropbear[0].PasswordAuth=" | ||
| + | uci set dropbear.@dropbear[0].RootPasswordAuth=" | ||
| + | uci commit dropbear | ||
| + | / | ||
| + | passwd -l "${SUDO_USER}" | ||
| + | groupadd -r -g " | ||
| + | touch / | ||
| + | cat << EOI > / | ||
| + | %${SUDO_GROUP} ALL=(ALL) ALL | ||
| + | EOI | ||
| + | groupadd " | ||
| + | useradd -m -g " | ||
| + | -s " | ||
| + | passwd -d " | ||
| + | USER_HOME=" | ||
| + | mkdir -p " | ||
| + | cat << EOI > " | ||
| + | ${USER_SSHPUB} | ||
| + | EOI | ||
| + | chown -R " | ||
| + | chmod -R go= " | ||
| + | EOF | ||
| + | make image FILES="files" PACKAGES=" | ||
| + | </ | ||
| - | **Note:** The '' | + | ==== Adding/modifying profiles ==== |
| + | <WRAP important> | ||
| + | Examples below may contain version dependent / legacy information and are for informational purposes. They are very low level so expect to have a good level of skill and familiarity with the ImageBuilder / OpenWrt in general. | ||
| + | </ | ||
| - | ==== Examples ==== | + | The image building is tied to the profile names. |
| - | The following example shows: | + | If you add a new profile without also adding an appropriate macro to the image-generation Makefile, no suitable firmware file will get generated when using the custom profile. |
| + | Remove the ''/ | ||
| - | -Creating | + | The location of the profiles |
| - | | + | |
| - | | + | |
| - | < | + | Remarkably, all that needs to be done to add a new profile, is to add a new file to the //profiles// directory. |
| - | scp root@192.168.1.1: | + | //While this may have been the case in earlier releases, for 17.01, it appears that manual editing of '' |
| - | scp root@192.168.1.1:/etc/config/wireless files/etc/config/ | + | |
| - | scp root@192.168.1.1:/etc/config/ | + | Here is what the //profiles/100-Broadcom-b43.mk// profile file looks like: |
| - | make image PROFILE=wl500gp | + | |
| + | <code bash> | ||
| + | define Profile/Broadcom-b43 | ||
| + | NAME:=Broadcom BCM43xx WiFi (default) | ||
| + | PACKAGES:=kmod-b43 kmod-b43legacy | ||
| + | endef | ||
| + | |||
| + | define Profile/ | ||
| + | Package set compatible with hardware using Broadcom BCM43xx cards | ||
| + | endef | ||
| + | $(eval $(call Profile, | ||
| </ | </ | ||
| - | =====清除===== | + | Alternately edit the hidden .profile.mk file at the top level directory of the image builder and manually add the names of the desired packages to be added to the output image. |
| - | 您可以使用**make clean**命令来清除临时构建文件和已生成的镜像文件。 | + | An "ls -a" will reveal the files hidden in the various directories. |
| - | =====移除固件中无用的文件===== | + | |
| - | < | + | ==== Removing useless files from firmware |
| - | This is not a standard feature of the Image Builder. | + | <WRAP important> |
| + | This is not a standard feature of the Image Builder. | ||
| + | |||
| + | It is highly recommended that you test file removal prior to incorporating such changes at the image builder level or that you have low level means to recover a device before attempting this type of mod, as bricking / non booting may result. | ||
| Note that it requires patching of the '' | Note that it requires patching of the '' | ||
| + | |||
| + | It is based on older Chaos Calmer era code... and not applicable to modern ImageBuilders but useful as a reference... | ||
| </ | </ | ||
| - | 1. 创建一个包含了文件完整径名为' | + | Create file '' |
| - | < | + | |
| + | < | ||
| / | / | ||
| / | / | ||
| Line 188: | Line 383: | ||
| </ | </ | ||
| - | 2. 给Makefile打补丁 | + | Patch Makefile: |
| - | < | + | |
| + | < | ||
| ifneq ($(USER_FILES), | ifneq ($(USER_FILES), | ||
| | | ||
| Line 198: | Line 394: | ||
| + @echo Remove useless files | + @echo Remove useless files | ||
| + | + | ||
| - | + while read filename; do \ | + | + while read filename; do \ |
| - | + rm -rfv " | + | + rm -rfv " |
| + done < $(FILES_REMOVE); | + done < $(FILES_REMOVE); | ||
| +endif | +endif | ||
| Line 207: | Line 403: | ||
| </ | </ | ||
| - | 3. 重构固件 | + | Rebuild firmware: |
| - | < | + | |
| - | # make image \ | + | |
| - | PROFILE=tlwr841 \ | + | |
| - | PACKAGES=" | + | |
| - | FILES_REMOVE=" | + | |
| - | </ | + | |
| - | + | <code bash> | |
| - | ===== Building the Image Generator with all packages inside ===== | + | make image \ |
| - | It is possible to build the Image Generator and integrate in it all packages so it will be able to generate images without downloading packages: | + | PROFILE="tlwr841" |
| - | + | PACKAGES=" | |
| - | In the graphical configuration, | + | FILES_REMOVE=" |
| - | Then build the image, including '' | + | |
| - | + | ||
| - | Enabling '' | + | |
| - | + | ||
| - | < | + | |
| </ | </ | ||
| - | |||
| - | **Note:** Don't call '' | ||
| - | |||
| - | |||
| - | ===== Adding/ | ||
| - | The image generation is tied to the profile names. If you add a new profile without also adding an appropriate macro to the image-generation Makefile, no suitable firmware file will get generated when using the custom profile. | ||
| - | :!: Make sure to remove the /tmp directory to get modified package selection from profiles to work. | ||
| - | |||
| - | The location of the profiles for the pre-compiled package for // | ||
| - | |||
| - | Remarkably, all that needs to be done to add a new profile, is to add a new file to the // | ||
| - | |||
| - | Here is what the // | ||
| - | |||
| - | < | ||
| - | < | ||
| - | define Profile/ | ||
| - | NAME: | ||
| - | PACKAGES: | ||
| - | endef | ||
| - | |||
| - | define Profile/ | ||
| - | Package set compatible with hardware using Broadcom BCM43xx cards | ||
| - | endef | ||
| - | $(eval $(call Profile, | ||
| - | </ | ||
| - | </ | ||