docs / Distro Profiles

Distro Profiles

Data-driven distro detection and boot params.

Руководство по профилям дистрибутивов#

Bootimus использует профили дистрибутивов для определения типа ISO и генерации правильных параметров загрузки. Профили основаны на данных — поддержку новых дистрибутивов можно добавить без правки кода.

Обзор#

Профили дистрибутивов определяют:

Как определить, к какому дистрибутиву относится ISO (сопоставление по шаблону имени файла)
Где искать kernel, initrd и squashfs внутри ISO
Какие параметры загрузки использовать при PXE-загрузке
Какой тип автоустановки поддерживается (preseed, kickstart, autoinstall и т. д.)

Типы профилей#

Тип	Описание
Built-in	Поставляется с Bootimus, обновляется из центрального репозитория
Custom	Создан пользователем, никогда не перезаписывается при обновлении

Пользовательские профили всегда имеют приоритет над встроенными при сопоставлении имён ISO.

Как это работает#

Когда ISO загружается или извлекается, Bootimus сопоставляет имя файла с шаблонами профилей
Пути kernel/initrd подходящего профиля используются для поиска загрузочных файлов внутри ISO
Параметры загрузки профиля становятся дефолтом (редактируются в Properties образа)
На момент загрузки плейсхолдеры в параметрах разрешаются в реальные URL

Жизненный цикл профилей#

Сборка:           distro-profiles.json встроен в бинарник
                        ↓
Первый запуск:    Профили засеваются в базу
                        ↓
«Check for Updates»:  Последние профили подтягиваются с GitHub
                        ↓
Создание пользователем:   Custom-профили хранятся в базе (никогда не перезаписываются)

Просмотр профилей#

Откройте Boot > Distro Profiles в админ-панели, чтобы увидеть все загруженные профили с их шаблонами имён, параметрами загрузки, типом (Built-in/Custom) и версией.

Обновление профилей#

Автоматическое (рекомендуется)#

Нажмите «Check for Updates» во вкладке Distro Profiles. Будут подтянуты последние профили с:

https://raw.githubusercontent.com/garybowers/bootimus/main/distro-profiles.json

Новые профили добавляются автоматически
Существующие встроенные профили обновляются до последней версии
Пользовательские профили никогда не модифицируются

Через API#

curl -H "Authorization: Bearer $TOKEN" -X POST http://localhost:8081/api/profiles/update

Ответ:

{
  "success": true,
  "message": "Updated to version 0.1.21 (2 added, 5 updated)"
}

Создание пользовательских профилей#

Через веб-интерфейс#

Откройте Boot > Distro Profiles
Нажмите «+ Add Custom Profile»
Заполните поля профиля
Нажмите «Create Profile»

Через API#

curl -H "Authorization: Bearer $TOKEN" -X POST http://localhost:8081/api/profiles/save \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "my-distro",
    "display_name": "My Custom Distro",
    "family": "debian",
    "filename_patterns": ["mydistro", "my-distro"],
    "kernel_paths": ["/live/vmlinuz", "/boot/vmlinuz"],
    "initrd_paths": ["/live/initrd.img", "/boot/initrd"],
    "squashfs_paths": ["/live/filesystem.squashfs"],
    "default_boot_params": "boot=live initrd=initrd ip=dhcp",
    "boot_params_with_squashfs": "boot=live initrd=initrd fetch={{SQUASHFS}}",
    "auto_install_type": "preseed"
  }'

Удаление пользовательских профилей#

Удалить можно только пользовательские профили. Встроенные восстанавливаются при следующем обновлении.

curl -H "Authorization: Bearer $TOKEN" -X DELETE "http://localhost:8081/api/profiles/delete?id=my-distro"

Поля профиля#

Поле	Обязательное	Описание
`profile_id`	Да	Уникальный идентификатор (например, `ubuntu`, `my-distro`)
`display_name`	Да	Человекочитаемое имя в UI
`family`	Нет	Семейство дистрибутивов (например, `debian`, `arch`, `redhat`) — для группировки
`filename_patterns`	Да	Подстроки для поиска в именах ISO-файлов (без учёта регистра)
`kernel_paths`	Нет	Пути для поиска kernel внутри ISO (например, `/casper/vmlinuz`)
`initrd_paths`	Нет	Пути для поиска initrd внутри ISO
`squashfs_paths`	Нет	Пути для поиска корневой ФС squashfs
`default_boot_params`	Нет	Параметры загрузки kernel по умолчанию (с поддержкой плейсхолдеров)
`boot_params_with_squashfs`	Нет	Альтернативные параметры загрузки, когда обнаружен squashfs
`auto_install_type`	Нет	Формат автоустановки: `preseed`, `kickstart`, `autoinstall`, `autounattend`
`boot_method`	Нет	Переопределение метода загрузки (например, `wimboot` для Windows)

Плейсхолдеры#

Параметры загрузки поддерживают эти плейсхолдеры, разрешаются на момент загрузки:

Плейсхолдер	Разрешается в	Пример
`{{BASE_URL}}`	HTTP-URL сервера	`http://192.168.1.10:8080`
`{{CACHE_DIR}}`	Директория извлечённых файлов	`ubuntu-24.04-server-amd64`
`{{FILENAME}}`	Имя ISO-файла (URL-кодированное)	`ubuntu-24.04-server-amd64.iso`
`{{SQUASHFS}}`	Полный URL файла squashfs	`http://192.168.1.10:8080/boot/ubuntu.../casper/filesystem.squashfs`

Пример с плейсхолдерами#

boot=live initrd=initrd fetch={{SQUASHFS}} ip=dhcp

Разрешается в:

boot=live initrd=initrd fetch=http://192.168.1.10:8080/boot/debian-live-13/live/filesystem.squashfs ip=dhcp

Примеры#

Live-ISO на базе Debian#

{
  "profile_id": "my-debian-live",
  "display_name": "My Debian Live Spin",
  "family": "debian",
  "filename_patterns": ["my-debian"],
  "kernel_paths": ["/live/vmlinuz"],
  "initrd_paths": ["/live/initrd.img"],
  "squashfs_paths": ["/live/filesystem.squashfs"],
  "default_boot_params": "initrd=initrd boot=live priority=critical",
  "boot_params_with_squashfs": "initrd=initrd boot=live priority=critical fetch={{SQUASHFS}}"
}

Дистрибутив на базе Arch#

{
  "profile_id": "my-arch-spin",
  "display_name": "My Arch Spin",
  "family": "arch",
  "filename_patterns": ["myarch"],
  "kernel_paths": ["/arch/boot/x86_64/vmlinuz-linux", "/boot/vmlinuz-linux"],
  "initrd_paths": ["/arch/boot/x86_64/initramfs-linux.img", "/boot/initramfs-linux.img"],
  "squashfs_paths": ["/arch/x86_64/airootfs.sfs"],
  "default_boot_params": "archisobasedir=arch archiso_http_srv={{BASE_URL}}/boot/{{CACHE_DIR}}/iso/ ip=dhcp"
}

Установщик на базе RHEL#

{
  "profile_id": "my-rhel-clone",
  "display_name": "My RHEL Clone",
  "family": "redhat",
  "filename_patterns": ["myrhel"],
  "kernel_paths": ["/images/pxeboot/vmlinuz"],
  "initrd_paths": ["/images/pxeboot/initrd.img"],
  "default_boot_params": "root=live:{{BASE_URL}}/isos/{{FILENAME}} rd.live.image inst.repo={{BASE_URL}}/boot/{{CACHE_DIR}}/iso/ rd.neednet=1 ip=dhcp",
  "auto_install_type": "kickstart"
}

Диагностика#

ISO не определяется как нужный дистрибутив#

Проверьте, совпадает ли имя ISO с каким-нибудь шаблоном профиля:

Откройте вкладку Distro Profiles
Посмотрите столбец «Filename Patterns»
Если ни один шаблон не подходит вашему имени ISO, создайте пользовательский профиль

Неправильные параметры загрузки после извлечения#

Откройте Properties образа
Нажмите «Re-detect» рядом с Boot Parameters
Или отредактируйте параметры вручную — они поддерживают плейсхолдеры

«Check for Updates» завершился ошибкой#

Обновление тянется с GitHub. Проверьте:

У сервера есть интернет
raw.githubusercontent.com не заблокирован
Попробуйте позже, если GitHub лежит

Пользовательский профиль не совпадает#

У пользовательских профилей приоритет над встроенными. Убедитесь:

В filename_patterns есть подстроки, совпадающие с именем вашего ISO (без учёта регистра)
ID профиля уникальный
Профиль успешно сохранён

Контрибьютинг профилей#

Чтобы добавить профиль в официальный список для всех пользователей:

Сделайте форк репозитория Bootimus
Отредактируйте distro-profiles.json в корне репозитория
Добавьте свой профиль в массив profiles
Отправьте pull request

Так все пользователи Bootimus получат новый профиль через «Check for Updates».