ipxe-tool/README.md
2025-10-18 23:26:25 +03:00

163 lines
7.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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
```bash
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` — подробный вывод
Пример:
```bash
sudo ./ipxe.sh image build --img /var/ipxe/disk.img --size-mb 768 --force
```
### 2) Вход в chroot (с сохранением изменений)
```bash
sudo ./ipxe.sh image chroot --img /var/ipxe/disk.img
```
Опционально можно выполнить команду сразу:
```bash
sudo ./ipxe.sh image chroot --img /var/ipxe/disk.img -- 'apk add htop'
```
### 3) Вход в chroot в режиме OverlayFS (изменения не сохраняются)
```bash
sudo ./ipxe.sh image overlay --img /var/ipxe/disk.img
```
Опционально задать размер tmpfs для верхнего слоя:
```bash
sudo ./ipxe.sh image overlay --img /var/ipxe/disk.img --overlay-size-mb 512
```
### 4) Сборка iPXE в overlay и копирование артефактов на хост
```bash
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`, например:
```bash
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 с копированием на хост:
```bash
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, с патчем и дефолтными опциями:
```bash
sudo ./ipxe.sh build --img /var/ipxe/disk.img --out-dir /srv/ipxe -- --efi --patch --default
```
Проверка окружения без сохранения изменений:
```bash
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`-устройств.