Використання Image Builder
Дивіться також: Інтерфейси Image Builder, Використання тулчейну, Швидкий посібник зі створення прошивок
Image Builder (раніше називався Image Generator) — це попередньо скомпільоване середовище, призначене для створення користувацьких прошивок без необхідності компілювати їх із початкового коду. Він завантажує попередньо скомпільовані пакети та інтегрує їх в один прошиваний образ.
Це корисно, якщо:
- ви хочете вмістити більше пакетів у маленький розмір флеш-пам’яті
- ви хочете використовувати останні девелоперські збірки
- ваш пристрій має 32MB або менше оперативної пам’яті, і `opkg` не працює належним чином
- ви хочете масово прошивати десятки пристроїв зі специфічною конфігурацією прошивки
Образи, створені за допомогою Image Builder, не ідентичні офіційним образам, оскільки використовують попередньо згенеровані пакети. Якщо були внесені нещодавні/важливі зміни, може виникнути затримка в їх доступності — перевіряйте, щоб пакети були завантажені після дати зміни або створення образу.
Попередні вимоги
- Image Builder працює лише на 64-бітних системах Linux. Проте ви можете запустити 64-бітний Linux на ПК або у віртуальній машині, наприклад VirtualBox, навіть із 32-бітної Windows.
- Image Builder має схожі вимоги до залежностей, як і система збірки.
Приклади залежностей у найпопулярніших дистрибутивах:
Arch
sudo pacman -S --needed base-devel ncurses zlib gawk git gettext \ openssl libxslt wget unzip python python-distutils-extra
Fedora
sudo dnf install git gawk gettext ncurses-devel zlib-devel \ openssl-devel libxslt wget which @c-development @development-tools \ @development-libs zlib-static which python3 perl
Debian / Ubuntu / Mint
sudo apt install build-essential file libncurses-dev zlib1g-dev gawk git \ gettext libssl-dev xsltproc rsync wget unzip python3 python3-distutils
WSL
Цей метод НЕ підтримується офіційно.
Проте він працює. Налаштування системи збірки для WSL
Рекомендується використовувати VirtualBox з Debian або DietPi(Debian) — вони потребують менше ресурсів і налаштувань.
Отримання Image Builder
Ви можете завантажити архів із Image Builder — зазвичай він знаходиться на тій самій сторінці, що і прошивка для вашого пристрою.
Наприклад, ось сторінка для завантаження прошивок для пристроїв ath79/generic: https://downloads.openwrt.org/snapshots/targets/ath79/generic/ Тут ви знайдете архів openwrt-imagebuilder-ath79-generic.Linux-x86_64.tar.zst із Image Builder.
Крім того, Image Builder завжди створюється системою збірки, оскільки він необхідний для формування образів.
Якщо активовано опцію “Build the OpenWrt Image Builder”, імідж білдер буде згенеровано в тій самій папці, де розміщені прошивки (source/bin/targets/xxx
), і ви зможете створювати нові образи з наявних пакетів.
Використання
Усі дії слід виконувати під обліковим записом не root-користувача.
Розпакуйте архів і перейдіть до директорії:
tar --zstd -xvf openwrt-imagebuilder-*.tar.zst cd openwrt-imagebuilder-*/
Процес створення образу можна налаштувати за допомогою таких змінних:
Змінна | Опис |
---|---|
PROFILE | Вказує цільовий профіль для збірки образу |
PACKAGES | Список пакетів, які буде включено до образу |
FILES | Каталог із власними файлами, які треба включити |
BIN_DIR | Альтернативний вихідний каталог для образів |
EXTRA_IMAGE_NAME | Додається до імені файлу образу (санітизоване) |
DISABLED_SERVICES | Список служб, які будуть вимкнені |
Виконайте make help
, щоб отримати детальну довідку.
Вибір профілю
Змінна PROFILE
визначає цільовий профіль для збірки образу.
PROFILE="назва-профілю"
Використайте make info
, щоб отримати список доступних профілів.
Вибір пакетів
Змінна PACKAGES
дозволяє включати або виключати пакети в прошивку.
За замовчуванням (пуста змінна PACKAGES) Image Builder створює мінімальний образ із ядром і драйверами, специфічними для пристрою, а також з підтримкою uci, ssh, switch, firewall, ppp та ipv6.
PACKAGES="pkg1 pkg2 pkg3 -pkg4 -pkg5 -pkg6"
У наведеному прикладі буде включено пакети pkg1, pkg2, pkg3 та виключено pkg4, pkg5, pkg6 (зверніть увагу на знак «-» перед кожним виключеним пакетом).
Ви не зобов’язані вручну вказувати всі залежності потрібних пакетів — Image Builder використовує opkg
, щоб автоматично встановити всі необхідні залежності.
Щоб отримати список встановлених на пристрої пакетів, виконайте:
echo $(opkg list-installed | sed -e "s/\s.*$//")
Багато пристроїв мають обмежену ємність сховища, і система збірки не гарантує, що виявить перевищення цього розміру. Це може зробити пристрій непридатним для завантаження. Якщо сумніваєтесь — не перевантажуйте прошивку. Скористайтесь тим, що вже було встановлено раніше, як орієнтиром, або створіть мінімальний образ, прошийте пристрій і протестуйте потрібні вам пакети. Також варто видалити зайві пакети, щоб зекономити місце у прошивці.
Крім того, пакети з версією ABI (наприклад, libubus20191227
) можуть викликати проблеми при створенні образу.
Може виникати помилка компіляції, якщо ви явно вказуєте такі пакети.
Щоб уникнути проблем, не вказуйте їх вручну — потрібні версії буде встановлено через залежності.
Параметр --strip-abi
дозволяє експортувати нормалізований список пакетів.
Користувацькі пакети
Якщо ви хочете використати власний пакет (ipk), створіть каталог packages
, якщо його ще немає, і помістіть туди ваш ipk-файл.
Користувацькі файли
Змінна FILES
дозволяє включити власні конфігураційні файли в образ, створений за допомогою Image Builder.
Це особливо корисно, якщо вам потрібно змінити мережеві налаштування до прошивки, або якщо ви готуєте масову прошивку багатьох пристроїв.
FILES="files"
Каталог files
має знаходитися в кореневій директорії Image Builder, звідки виконується команда `make`, або вказуйте повний шлях.
Наполегливо рекомендується використовувати uci-defaults для поступового впровадження лише необхідних змін. Це допоможе уникнути конфліктів із автогенерованими налаштуваннями, які можуть змінюватися між версіями.
див. також: uci-default_example
Створення образу
Після того, як ви вибрали профіль, пакети та конфігураційні файли, передайте їх команді make image
.
make image \ PROFILE="profile-name" \ PACKAGES="pkg1 pkg2 pkg3 -pkg4 -pkg5 -pkg6" \ FILES="files" \ DISABLED_SERVICES="svc1 svc2 svc3"
Після завершення команди `make`, згенеровані образи зберігаються в каталозі `bin/архітектура-пристрою`, так само як і при компіляції зі вихідного коду.
Готовий образ можна знайти в підкаталозі ./bin/targets/<target>/generic
, або в каталозі .build_dir/
, де будуть файли виду *-squashfs-sysupgrade.bin
і *-squashfs-factory.bin
(наприклад:
/build_dir/target-mips_24kc_musl/linux-ar71xx_tiny/tmp/openwrt-18.06.2-ar71xx-tiny-tl-wr740n-v6-squashfs-factory.bin
)
Очищення
Щоб видалити тимчасові файли збірки та створені образи, використайте команду make clean
.
Приклади
Приклад нижче демонструє:
- Створення директорії для конфігураційних файлів
- Використання
scp
для копіювання налаштуваньuci
з маршрутизатора WL500GP до каталогуfiles/etc/config
- Генерацію образу для WL500GP з власними пакетами та конфігураціями
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="wl500gp" \ PACKAGES="nano openvpn -ppp -ppp-mod-pppoe" \ FILES="files" \ DISABLED_SERVICES="dnsmasq firewall odhcpd"
Виправлення помилок
- Ви запускали все під звичайним користувачем, не root?
- Перевірте лог: чи немає конфліктів пакетів або неправильних назв?
- Перевірте лог: чи не перевищили допустимий розміру прошивки?
- Перевірте лог: чи є інші очевидні помилки?
- Зачекайте кілька годин/днів — пакети з головної гілки або снапшотів можуть бути в неконсистентному стані
- Переконайтесь, що ви використовуєте ОС, що підтримується OpenWrt, виконали всі потрібні дії перед збіркою, а також правильно назвали файли та шляхи
Додатково
Наведені нижче теми виходять за межі базового використання і призначені для розробників та досвідчених користувачів.
Детальна довідка
Дивіться також: Makefile ImageBuilder
Щоб отримати детальну довідку:
# make help Доступні команди: help: Цей текст довідки info: Показати список доступних цільових профілів clean: Очистити тимчасові файли та створені образи image: Створити образ (деталі нижче) Створення образів: За замовчуванням `make image` створює образ із типовим профілем і набором пакетів. Ви можете змінити це за допомогою параметрів: make image PROFILE="<назва_профілю>" # перевизначити типовий профіль make image PACKAGES="<pkg1> [<pkg2> [<pkg3> ...]]" # додати додаткові пакети make image FILES="<шлях>" # включити додаткові файли із <шляху> make image BIN_DIR="<шлях>" # альтернативна директорія для збереження образів make image EXTRA_IMAGE_NAME="<рядок>" # додати цей рядок до імені образу make image DISABLED_SERVICES="<svc1> [<svc2> [<svc3> ..]]" # служби, які потрібно вимкнути у /etc/init.d/ make image ADD_LOCAL_KEY=1 # зберегти локальний ключ підпису в образах
Виведення маніфесту
Список всіх пакетів, які будуть встановлені в образ.
make manifest PROFILE="<назва_профілю>" # змінити профіль make manifest PACKAGES="<pkg1> [<pkg2> [<pkg3> ...]]" # додати додаткові пакети make manifest STRIP_ABI=1 # прибрати версію ABI з назв пакетів
Доступні профілі
Список доступних профілів:
# make info Доступні профілі: Default: Типовий профіль Пакети: kmod-usb-core kmod-usb2 kmod-usb-ohci kmod-usb-ledtrig-usbport ai-br100: Aigale Ai-BR100 Пакети: kmod-usb2 kmod-usb-ohci rp-n53: Asus RP-N53 Пакети: rt-n14u: Asus RT-N14u Пакети: whr-1166d: Buffalo WHR-1166D Пакети: whr-300hp2: Buffalo WHR-300HP2 Пакети: ...
Створення власного Image Builder із усіма пакетами всередині
Можна використати buildroot для створення власного Image Builder із включеними всіма пакетами, щоб формувати образи без потреби завантажувати щось додатково.
У графічному інтерфейсі конфігурації виберіть “Build the OpenWrt Image Builder”, а потім у Global Build Settings — Select all packages by default, збережіть і вийдіть.
Ви можете ігнорувати помилки збірки у непідтримуваних пакетах, якщо це не зачіпає ядро або критичні залежності.
Не виконуйте `make defconfig` і не залишайте старий файл `.config` у каталозі, інакше параметр “Select all packages by default” не застосується повністю: пакети без конфігурації буде встановлено як `[n]`, тобто не збирати.
Додавання репозиторіїв пакетів
Image Builder, завантажений із сайту OpenWrt, вже налаштований на використання офіційних репозиторіїв для неосновних пакетів.
Файл `repositories.conf` у розпакованій директорії визначає джерела пакетів у форматі, що використовується системою `opkg`.
Ви можете вказати як офіційні, так і власні (локальні або онлайн) репозиторії.
Приклад вмісту `repositories.conf` із openwrt-imagebuilder-18.06.0-rc2-ramips-mt7621.Linux-x86_64.tar.xz:
## Додайте власні репозиторії тут, вони мають відповідати архітектурі та версії # src/gz %n http://downloads.openwrt.org/releases/18.06.0-rc2 # src custom file:///usr/src/openwrt/bin/ramips/packages ## Віддалені офіційні репозиторії src/gz openwrt_core http://downloads.openwrt.org/releases/18.06.0-rc2/targets/ramips/mt7621/packages src/gz openwrt_base http://downloads.openwrt.org/releases/18.06.0-rc2/packages/mipsel_24kc/base src/gz openwrt_luci http://downloads.openwrt.org/releases/18.06.0-rc2/packages/mipsel_24kc/luci src/gz openwrt_packages http://downloads.openwrt.org/releases/18.06.0-rc2/packages/mipsel_24kc/packages src/gz openwrt_routing http://downloads.openwrt.org/releases/18.06.0-rc2/packages/mipsel_24kc/routing src/gz openwrt_telephony http://downloads.openwrt.org/releases/18.06.0-rc2/packages/mipsel_24kc/telephony ## Локальний репозиторій — не видаляйте! src imagebuilder file:packages
Якщо ви компілюєте Image Builder із початкових кодів, в `repositories.conf` не буде посилань на “Remote package repositories”.
Щоб додати локальний репозиторій, скопіюйте рядок `src custom file:///usr/src/openwrt/bin/ramips/packages` та змініть шлях на потрібний — там мають бути ваші `.ipk` пакети і файл `Packages`.
При помилці Signature check failed, видаліть рядок `option check_signature` із `repositories.conf`.
Якщо у вас є власні онлайн-репозиторії, скопіюйте та адаптуйте рядок типу: `src/gz reboot http://downloads.openwrt.org/snapshots`
Примітка: якщо ви хочете перевизначити пакети з офіційного джерела, ваш репозиторій має бути вище в `repositories.conf`, ніж той, з якого ви хочете їх замінити.
Обмеження доступу root
Створіть непривілейованого користувача-адміністратора та заблокуйте пароль для root. Налаштуйте підвищення прав через `sudo`. Увімкніть автентифікацію за SSH-ключем і вимкніть автентифікацію за паролем для Dropbear.
mkdir -p files/etc/uci-defaults cat << "EOF" > files/etc/uci-defaults/99-custom USER_NAME="admin" USER_SSHPUB="SSH_PUBLIC_KEY" USER_SHELL="/bin/ash" SUDO_USER="root" SUDO_GROUP="sudo" groupadd -r "${SUDO_GROUP}" useradd -m -G "${SUDO_GROUP}" -s "${USER_SHELL}" "${USER_NAME}" passwd -l "${SUDO_USER}" cat << EOI > /etc/sudoers.d/00-custom %${SUDO_GROUP} ALL=(ALL) ALL EOI USER_HOME="$(eval echo ~"${USER_NAME}")" mkdir -p "${USER_HOME}"/.ssh cat << EOI > "${USER_HOME}"/.ssh/authorized_keys ${USER_SSHPUB} EOI uci set dropbear.@dropbear[0].PasswordAuth="0" uci set dropbear.@dropbear[0].RootPasswordAuth="0" uci commit dropbear /etc/init.d/dropbear restart EOF make image \ FILES="files" \ PACKAGES="nano shadow sudo"
Додавання/редагування профілів
Приклади нижче можуть містити застарілу або версійно-залежну інформацію. Вони призначені для досвідчених користувачів, які добре знайомі з Image Builder і OpenWrt загалом.
Збірка образів прив’язана до імен профілів. Якщо ви додасте новий профіль, але не оновите відповідний макрос у Makefile, прошивка не буде згенерована для цього профілю.
Для оновлення вибору пакетів із профілю, потрібно видалити директорію /tmp
.
У прикладі з пакетом для brcm47xx-for-Linux-i686 профілі розміщувались у target/linux/brcm47xx/profiles/
Щоб додати новий профіль, достатньо створити новий файл у каталозі profiles.
У релізі 17.01 також потрібно вручну редагувати файл .targetinfo
.
Приклад профілю profiles/100-Broadcom-b43.mk:
define Profile/Broadcom-b43 NAME:=Broadcom BCM43xx WiFi (default) PACKAGES:=kmod-b43 kmod-b43legacy endef define Profile/Broadcom-b43/Description Package set compatible with hardware using Broadcom BCM43xx cards endef $(eval $(call Profile,Broadcom-b43))
Альтернативно, можна відредагувати прихований файл `.profile.mk` у кореневому каталозі Image Builder і вручну додати потрібні пакети для образу. Використайте `ls -a`, щоб переглянути приховані файли.
Видалення непотрібних файлів із прошивки
Це не стандартна функція Image Builder.
Наполегливо рекомендується ретельно протестувати видалення файлів перед інтеграцією цих змін на рівні образу. Без належних знань це може призвести до незавантажуваного пристрою.
Цей підхід базується на старому коді епохи Chaos Calmer і не застосовується безпосередньо до сучасних версій Image Builder, але може слугувати за орієнтир.
Створіть файл `files_remove` зі списком повних шляхів до файлів:
/lib/modules/3.10.49/ts_bm.ko /lib/modules/3.10.49/nf_nat_ftp.ko /lib/modules/3.10.49/nf_nat_irc.ko /lib/modules/3.10.49/nf_nat_tftp.ko
Внесіть зміни до Makefile:
ifneq ($(USER_FILES),) $(MAKE) copy_files endif + +ifneq ($(FILES_REMOVE),) + @echo + @echo Remove useless files + + while read filename; do \ + rm -rfv "$(TARGET_DIR)$$filename"; \ + done < $(FILES_REMOVE); +endif + $(MAKE) package_postinst $(MAKE) build_image
Перезберіть прошивку:
make image \ PROFILE="tlwr841" \ PACKAGES="igmpproxy ip iptraf kmod-ipt-nathelper-extra openvpn-polarssl tcpdump-mini -firewall -ip6tables -kmod-ip6tables -kmod-ipv6 -odhcp6c -ppp -ppp-mod-pppoe" \ FILES_REMOVE="files_remove"