ipxe-tool/README.md

iPXE tool

Скрипт выполняет два основных набора задач:

1. Работа с образом Alpine (disk.img) — команда image с подкомандами:

   • image build — создание и первичное наполнение образа;
   • image chroot — вход в chroot;
   • image overlay — вход в chroot с наложением OverlayFS (изменения не сохраняются).

2. Сборка iPXE в режиме overlay с временными изменениями и копированием артефактов на хост — команда build.

Все команды требуют прав root.

---

Требования

• Поддержка loop-устройств и доступ к утилитам: losetup, parted, mkfs.ext4, mount, umount, curl, tar, chroot.

• Для создания файла: одна из утилит fallocate/truncate/dd.

• Для OverlayFS: поддержка overlay в ядре (/proc/filesystems) и доступен modprobe (если модуль загружается динамически).

• Интернет-доступ для загрузки alpine-minirootfs.

• Доступные каталоги:

  • Образ по умолчанию: /var/ipxe/disk.img

  • Внутри образа при первой сборке создаётся /develop с файлами:

    • /develop/build.sh — сценарий сборки iPXE;
    • /develop/certtrust.patch — патч к исходникам iPXE (по необходимости).

---

Быстрый старт

1) Создание образа Alpine

sudo ./ipxe.sh image build

По умолчанию:

• URL minirootfs: https://dl-cdn.alpinelinux.org/.../alpine-minirootfs-3.22.2-x86_64.tar.gz
• Путь к образу: /var/ipxe/disk.img
• Размер: 512 МБ (диапазон: 512..1024 МБ)

Полезные флаги:

• --url URL — другой источник minirootfs
• --img PATH — другой путь к образу
• --size-mb N — размер образа (512..1024)
• --no-bootstrap — без установки пакетов/репозитория iPXE
• --force — перезапись существующего файла
• --debug — подробный вывод

Пример:

sudo ./ipxe.sh image build --img /var/ipxe/disk.img --size-mb 768 --force

2) Вход в chroot (с сохранением изменений)

sudo ./ipxe.sh image chroot --img /var/ipxe/disk.img

Опционально можно выполнить команду сразу:

sudo ./ipxe.sh image chroot --img /var/ipxe/disk.img -- 'apk add htop'

3) Вход в chroot в режиме OverlayFS (изменения не сохраняются)

sudo ./ipxe.sh image overlay --img /var/ipxe/disk.img

Опционально задать размер tmpfs для верхнего слоя:

sudo ./ipxe.sh image overlay --img /var/ipxe/disk.img --overlay-size-mb 512

4) Сборка iPXE в overlay и копирование артефактов на хост

sudo ./ipxe.sh build --img /var/ipxe/disk.img --out-dir /tmp/out -- --efi --legacy --iso --default --patch

• Все флаги после -- передаются внутреннему /develop/build.sh.

• Артефакты копируются в --out-dir (по умолчанию текущий каталог) только если были собраны:

  • ipxe.efi → /root/ipxe/src/bin-x86_64-efi/ipxe.efi
  • undionly.kpxe → /root/ipxe/src/bin-i386-pcbios/undionly.kpxe
  • ipxe.iso → /root/ipxe/src/bin/ipxe.iso

---

Поведение и детали

• Логи скрипта нейтральные: «создание образа», «монтирование», «скачивание», «распаковка» и т. п.

• При image build выполняется разметка msdos, создаётся один раздел ext4, монтируется и наполняется содержимым minirootfs.

• При первой сборке внутрь образа добавляется /develop/build.sh и /develop/certtrust.patch.

• image chroot и image overlay автоматически монтируют необходимые файловые системы (/dev, proc, sys, run, devpts, shm), а при выходе — размонтируют.

• В overlay-режиме нижний слой (disk.img) монтируется только для чтения, верхний слой — во временный tmpfs; все изменения теряются при выходе.

• Команда build:

  • Разворачивает overlay, выполняет /develop/build.sh с переданными флагами;
  • По коду возврата определяет, была ли сборка успешной, и при наличии артефактов копирует их на хост в --out-dir;
  • После завершения всё размонтирует автоматически.

---

Часто используемые флаги /develop/build.sh

Передаются через -- в команду build, например:

sudo ./ipxe.sh build -- --efi --default

• --efi — сборка bin-x86_64-efi/ipxe.efi
• --legacy — сборка bin-i386-pcbios/undionly.kpxe
• --iso — сборка bin/ipxe.iso
• Без флагов собираются все цели.
• --default — включение набора опций в config/general.h (PING_CMD, IPSTAT_CMD, CONSOLE_CMD и т. д.)
• --patch — применение /develop/certtrust.patch и включение HTTPS/CERT_CMD

---

Примеры

Создание образа и последующая сборка всех артефактов iPXE в overlay с копированием на хост:

sudo ./ipxe.sh image build --img /var/ipxe/disk.img --size-mb 512
sudo ./ipxe.sh build --img /var/ipxe/disk.img --out-dir /srv/ipxe -- --efi --legacy --iso

Минимальная сборка только EFI, с патчем и дефолтными опциями:

sudo ./ipxe.sh build --img /var/ipxe/disk.img --out-dir /srv/ipxe -- --efi --patch --default

Проверка окружения без сохранения изменений:

sudo ./ipxe.sh image overlay --img /var/ipxe/disk.img --overlay-size-mb 256 -- 'apk info -vv'

---

Диагностика

• «образ не найден» — проверьте путь --img и выполните image build.
• «минимальный/максимальный размер» — скорректируйте --size-mb (диапазон 512..1024).
• «отсутствие поддержки overlayfs» — убедитесь в наличии модуля overlay в ядре и/или возможности загрузки через modprobe.
• При сетевых операциях используйте актуальный URL minirootfs (--url).

При любой ошибке скрипт выполняет автоматическую очистку: размонтирование файловых систем и отвязку loop-устройств.