163 lines
7.4 KiB
Markdown
163 lines
7.4 KiB
Markdown
# 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`-устройств.
|
||
|