uroottest/test-image-amd64

u-root

镜像概述和主要用途

u-root是一个综合性工具集，包含四个核心项目：

• 采用Go语言实现的众多标准Linux工具（如ls、cp、shutdown等）
• 可将多个Go程序编译为单一二进制文件的busybox模式
• 用于创建可嵌入固件的initramfs（文件归档）
• 基于kexec的Go bootloaders，支持引导Linux或多引导内核（如ESXi、Xen、tboot），适用于LinuxBoot

核心功能和特性

主要功能

• Go语言工具集：提供core目录下的标准Linux命令Go实现
• 单一二进制编译：通过busybox模式将多个工具打包为单个可执行文件
• initramfs生成：创建用于Linux内核的初始内存文件系统
• 灵活的引导功能：支持网络引导、本地磁盘引导及多种配置文件解析（GRUB、syslinux等）
• 跨平台支持：支持amd64、x86、mipsle、armv7、arm64、ppc64le等架构

特性

• 轻量级设计，适合嵌入式环境
• 可定制化init系统，支持initcmd和uinitcmd配置
• 支持额外文件添加及依赖自动包含
• 兼容LinuxBoot项目，可嵌入固件
• 完善的测试支持，包括CI/CD集成

使用场景和适用范围

• LinuxBoot固件开发：作为引导加载器组件
• 嵌入式系统：提供精简的工具集和initramfs
• 系统救援：创建轻量级救援环境
• 虚拟化测试：配合QEMU进行内核和引导测试
• 定制化Linux发行版：构建最小化系统环境

详细使用方法和配置说明

环境要求

• Go版本 ≥ 1.19

安装方法

通过Git安装

shell
git clone https://github.com/u-root/u-root
cd u-root
go build

直接通过Go安装

shell
go install github.com/u-root/u-root

注意：u-root命令将安装在$GOPATH/bin/u-root，需确保$GOPATH/bin已添加到$PATH。

基本使用

模板

可使用templates.go中定义的模板快速指定命令集，如core（核心工具集）、boot（引导工具集）等。

构建示例

shell
# 构建包含./cmds/core/...下所有Go命令的initramfs（默认）
u-root

# 在仓库根目录外执行构建
(cd /tmp && GBB_PATH=$UROOT_PATH u-root)

# 生成包含引导加载器的归档
u-root core boot

# 仅包含指定命令
u-root ./cmds/core/{init,ls,ip,dhclient,wget,cat,elvish}

# 包含核心工具集，排除部分命令
u-root core -cmds/core/{ls,losetup}

# 包含外部工具
git clone https://github.com/u-root/cpu
u-root ./cmds/core/{init,ls,elvish} ./cpu/cmds/cpud

GBB_PATH配置

GBB_PATH用于指定命令搜索路径，冒号分隔的路径元素将与命令行模式拼接：

shell
GBB_PATH=$HOME/u-root:$HOME/u-bmc u-root \
    cmds/core/init \
    cmds/core/elvish \
    cmd/socreset

上述命令将匹配：

• $HOME/u-root/cmds/core/init
• $HOME/u-root/cmds/core/elvish
• $HOME/u-bmc/cmd/socreset

额外文件

使用-files标志在initramfs中包含额外文件，自动包含ldd依赖：

shell
# 添加内核模块（将放在initramfs的$HOME目录）
u-root -files $HOME/hello.ko -files $HOME/hello2.ko

# 指定目标路径
u-root -files "root-fs/usr/bin/runc:usr/bin/run"

Init和Uinit配置

u-root提供可配置的init系统，通过以下标志控制：

• -initcmd：指定/init符号链接目标（命令名或路径）
• -uinitcmd：在基础文件系统设置后运行的初始化命令（可带参数）
• -defaultsh：指定默认shell

示例

bash
# 设置uinitcmd执行echo命令
u-root -uinitcmd="echo Go Gopher" ./cmds/core/{init,echo,elvish}

# 通过内核参数传递uinit参数
qemu-system-x86_64 -kernel $KERNEL -initrd /tmp/initramfs.linux_amd64.cpio -nographic -append "console=ttyS0 uroot.uinitargs=Go"

# 直接启动shell（绕过默认init）
u-root -initcmd=elvish ./cmds/core/{elvish,ls}

交叉编译

利用Go的交叉编译能力：

shell
# 为ARM架构编译
GOARCH=arm u-root

# 在OSX上为Linux/amd64编译
GOOS=linux GOARCH=amd64 u-root

QEMU测试

shell
# 基本测试
qemu-system-x86_64 -nographic -kernel /boot/vmlinuz-$(uname -r) -initrd /tmp/initramfs.linux_amd64.cpio

# 帧缓冲支持
qemu-system-x86_64 -kernel path/to/kernel -initrd /tmp/initramfs.linux_amd64.cpio -append "vga=786"

# 随机数生成器支持
qemu-system-x86_64 -device virtio-rng-pci -kernel vmlinuz -initrd /tmp/initramfs.linux_amd64.cpio

SystemBoot引导加载器

SystemBoot是一组Go编写的引导加载器，使用kexec引导系统，命令位于cmds/boot：

• pxeboot：网络引导客户端，支持DHCP/HTTP/TFTP
• boot：本地磁盘引导，支持GRUB/syslinux配置
• fbnetboot：基于HTTP的网络引导客户端
• localboot：本地磁盘引导工具
• systemboot：模拟BIOS/UEFI BDS行为的引导包装器

构建SystemBoot

shell
u-root -uinitcmd=systemboot core ./cmds/boot/{systemboot,localboot,fbnetboot}

压缩initramfs

建议使用xz压缩并对齐512字节边界：

shell
xz --check=crc32 -9 --lzma2=dict=1MiB \
   --stdout /tmp/initramfs.linux_amd64.cpio \
   | dd conv=sync bs=512 \
   of=/tmp/initramfs.linux_amd64.cpio.xz

构建模式

u-root支持两种构建模式（通过-build指定）：

• gbb模式：所有工具编译为单一busybox-like二进制
• binary模式：每个工具单独编译并添加到initramfs

无网络构建

shell
# 设置GOPATH
export GOPATH=$(mktemp -d)

# 获取代码
mkdir -p ${GOPATH}/src/github.com/u-root/
cd ${GOPATH}/src/github.com/u-root/
git clone https://github.com/u-root/u-root.git
cd u-root

# 无网络构建
GO111MODULE=off GOPROXY=off go build
GO111MODULE=off GOPROXY=off ./u-root

硬件支持

推荐使用PC Engines APU2开发板进行硬件测试。

贡献

贡献指南详见CONTRIBUTING.md，欢迎改进现有命令或实现路线图中的功能（参见roadmap.md）。