Hướng dẫn sử dụng OpenWrt ImageBuilder

Bản draft để review: ImageBuilder chỉ phù hợp khi đã có ImageBuilder đúng phiên bản, target, subtarget và profile. Tuyệt đối không dùng ImageBuilder của model khác.

ImageBuilder là gì?

ImageBuilder là môi trường đã biên dịch sẵn, dùng để tạo firmware tùy biến nhanh từ các package đã có trong repository. Nó phù hợp để thêm hoặc bỏ package, thêm file cấu hình và tạo image flashable mà không phải biên dịch toàn bộ OpenWrt từ source.[15]

Nếu cần sửa kernel, driver, target hoặc biên dịch package chưa có binary tương ứng, hãy dùng build system từ source.

Chọn đúng ImageBuilder

Bạn cần xác định chính xác:

• Phiên bản OpenWrt.
• Target System.
• Subtarget.
• Target Profile.
• Kiến trúc CPU.

Các thông tin này phải khớp với router. Có thể bắt đầu từ trang download chính thức:

1

https://downloads.openwrt.org/

Sau đó đi theo đường dẫn dạng:

1

releases/<version>/targets/<target>/<subtarget>/

Tên file ImageBuilder thường chứa phiên bản, target và kiến trúc. Không chọn chỉ dựa vào tên thương mại của router.

Giải nén ImageBuilder

Ví dụ với archive dạng .tar.zst:

1
2
3
4
5
6

mkdir -p ~/openwrt-imagebuilder
cd ~/openwrt-imagebuilder

tar --use-compress-program=unzstd \
  -xf openwrt-imagebuilder-*.tar.zst
cd openwrt-imagebuilder-*/

Nếu hệ thống chưa có unzstd:

1
2

sudo apt update
sudo apt install -y zstd

Xem profile và package có sẵn

Chạy:

1

make info

Lệnh này giúp xem profile mà ImageBuilder hỗ trợ và các package hiện có trong repository tương ứng. Nếu model không xuất hiện, dừng lại và tải đúng ImageBuilder.

Thêm package vào firmware

Ví dụ tạo image có LuCI và một số package mạng:

1
2
3

make image \
  PROFILE="<profile-cua-router>" \
  PACKAGES="luci luci-ssl htop tcpdump"

Thay <profile-cua-router> bằng profile chính xác lấy từ make info.

Để loại bỏ package mặc định, dùng dấu - trước tên package:

1
2
3

make image \
  PROFILE="<profile-cua-router>" \
  PACKAGES="luci -ppp"

Không nên loại bỏ package khi chưa biết package đó có phải dependency của network, storage hoặc cơ chế recovery hay không.

Thêm file cấu hình bằng FILES

Tạo cây thư mục files/ trong thư mục ImageBuilder:

1
2

mkdir -p files/etc/uci-defaults
mkdir -p files/etc/config

Ví dụ thêm một file cấu hình:

1
2
3

cat > files/etc/banner <<'EOF'
AIoT.IO.VN - OpenWrt custom image
EOF

Sau đó build:

1
2
3
4

make image \
  PROFILE="<profile-cua-router>" \
  PACKAGES="luci" \
  FILES="files"

Trong thực tế, nên tạo file bằng editor và kiểm tra lại nội dung trước khi build. Với script trong etc/uci-defaults, cần kiểm tra quyền thực thi và idempotency để script không phá cấu hình khi chạy lại.

Đặt tên output và kiểm tra log

Có thể dùng BIN_DIR để gom image vào thư mục riêng:

1
2
3
4
5
6

mkdir -p output
make image \
  PROFILE="<profile-cua-router>" \
  PACKAGES="luci" \
  FILES="files" \
  BIN_DIR="output"

Nếu build lỗi, chạy verbose:

1

make V=s image PROFILE="<profile-cua-router>" PACKAGES="luci"

Firmware được tạo trong thư mục output/ hoặc bin/ tùy ImageBuilder và tùy chọn đã dùng.

ImageBuilder khác build từ source thế nào?

Checklist trước khi flash

• Đúng phiên bản OpenWrt.
• Đúng target/subtarget.
• Đúng profile.
• Đúng loại image: factory, sysupgrade hoặc recovery.
• Có backup cấu hình.
• Đọc hướng dẫn flash riêng của router.
• Có phương án recovery khi image không boot.

Nguồn chính thức

• OpenWrt — Using the Image Builder
• OpenWrt — Build system usage
• OpenWrt downloads

Bài này được AIoT.IO.VN biên soạn lại từ tài liệu OpenWrt, có bổ sung ví dụ và cảnh báo phù hợp với người mới.