== Разработчику bootchain + altboot

=== Общий вспомогательный код

==== interactive-sh-functions

Общий код для обеспечения диалогов
и _<<_интерактивный_режим_работы,интерактивного взаимодействия>>_
с пользователем. Входит в подпакет *make-initrd-bootchain-interactive*.
_<<_библиотека_виджетов>>_ вынесена в отдельные скрипты, загружаемые
динамически, по мере необходимости. Данный модуль не зависит от *bootchain*
и *altboot*, есть смысл сделать его общей фичей в самом *make-initrd*, но
автору make-initrd не нравится идея работать с TTY.

.Синтаксис:
[,,subs="verbatim,quotes"]
----
. interactive-sh-functions
----

Глобальные переменные:

* *$IM_BACKTITLE* — содержит заголовок верхнего уровня, выводимый всеми
  виджетами;
* *$IM_WIDGET_ARGS* — можно передавать дополнительные аргументы команде
  dialog перед использованием виджета;
* *$NOASKUSER* — непустое значение, если запрещены диалоги ввода;
* *$NOLINES* — непустое значение, если нет поддержи символов псевдографики.

Функции:

* *IM_is_active()* — возвращает 0, если интерактивный режим уже активен;
* *IM_exec()* — переводит указанный процесс на передний план, на конкретный
  терминал TTY;
* *IM_activate()* — запрашивает немедленную или отложенную активацию
  интерактивного режима;
* *IM_load_widgets()* — динамически подгружает запрошенные виджеты
  из библиотеки;
* *IM_load_all()* — подгружает из библиотеки все доступные виджеты;
* *IM_start_output()* — сообщает модулю о начале вывода;
* *IM_start_input()* — сообщает модулю о начале ввода;
* *IM_show_bootsplash()* — разрешает видеть на переднем плане заставку
  plymouth, если доступна;
* *IM_hide_bootsplash()* — скрывает заставку plymoth, если она есть,
  и приостанавливает прогресс бар;
* *IM_update_bootsplash()* — сообщает демону plymouthd, если есть,
  о прохождении очередной стадии загрузки.

==== bootchain-sh-functions

Общий код, используемый всеми «шагами» *bootchain* и *altboot*. Также пригоден
и для «шагов» *pipeline*. Входит в подпакет *make-initrd-bootchain-core*.

.Синтаксис:
[,,subs="verbatim,quotes"]
----
. bootchain-sh-functions
----

.Конфигурационный файл:
[,,subs="verbatim,quotes"]
----
/etc/sysconfig/bootchain
----

Глобальные переменные:

* *$mntdir* — рабочий каталог демона для организации «входов» и «выходов»
  каждого «шага»;
* `*$pipeline_mode*` — непустое значение, если демон chaind работает
  в режиме «pipeline», а не в «родном» режиме;
* `*$BC_DEBUG*` — непустое значение, если включена расширенная диагностика;
* `*$BC_LOG_VT*` — если непустое значение, то порядковый номер TTY для
  вывода журнала;
* `*$BC_LOGFILE*` — путь к файлу журнала или устройство для вывода в него
  сообщений отладки;
* `*$BC_DEVICE_TIMEOUT*` — дефолтный таймаут для любых «шагов» bootchain;
* `*$BC_FGVT_ACTIVATE*` — если непустое значение, то через сколько секунд
  активировать интерактивный терминал.

Функции:

* *check_parameter()* — проверяет, чтобы обязательный параметр был
  не пуст или завершается через fatal();
* *get_parameter()* — вывод значения параметра текущего «шага» по
  индексу $callnum;
* *resolve_target()* — вывод пути к файлу, каталогу или устройству,
  в зависимости от параметра;
* `*resolve_devname()*` — вывод пути к специальному файлу устройства
  по указанному каталогу; обычно каталог «шага» содержит файл DEVNAME
  или dev, если устройство было результатом «шага», тогда функция вернёт
  читаемый /dev/УЗЕЛ;
* `*debug()*` — вывод текстового сообщения при расширенной диагностике;
* `*enter()*` — трассировка при расширенной диагностике: вход в указанную
  функцию;
* `*leave()*` — трассировка при расширенной диагностике: выход из указанной
  функции;
* `*run()*` — запуск внешней команды, при расширенной диагностике команда
  попадёт в журнал;
* `*fdump()*` — вывод содержимого указанного файла при расширенной диагностике;
* `*assign()*` — присвоение переменной указанного значения, попадающее
  в журнал;
* `*next_bootchain()*` — команда демону на смену последовательности
  следующих «шагов»;
* `*is_step_passed()*` — возвращает 0, если текущий «шаг» был пройден
  хотя бы один раз;
* `*launch_step_once()*` — если текущий «шаг» уже был пройден, завершает
  работу через вызов fatal();
* `*break_bc_loop()*` — сообщает демону о том, что текущий «шаг» последний
  и можно переходить в stage2;
* `*bc_reboot()*` — выполняет журналируемый перезапуск компьютера;
* `*bypass_results()*` — просит демон связать «выход» предыдущего «шага»
  со «входом» следующего «шага»;
* `*initrd_version()*` — вывод текущей версии make-initrd.

==== altboot-sh-functions

Общий код модуля *make-initrd-bootchain-altboot*, используемый всеми
«шагами» *altboot*.

.Синтаксис:
[,,subs="verbatim,quotes"]
----
. altboot-sh-functions
----

.Конфигурационные файлы:
[,,subs="verbatim,quotes"]
----
**/etc/sysconfig/bootchain**: изначально используется общая конфигурация с bootchain;
/.initrd/bootchain/**altboot.conf**: конфигурация последующих «шагов», создаваемая altboot;
/.initrd/bootchain/**altboot.env**: окружение, экспортируемое «шагами» altboot в stage2;
/.initrd/bootchain/**altboot.auto**: сюда сохраняется метод загрузки, выбранный вручную.
----

Глобальные переменные:

* *$ALTBOOT_OLDROOT* — непустое значение, если «шаг» должен работать
  в режиме совместимости с пропагатором;
* *$OEM_WELCOME_TEXT* — используется в качестве заголовка верхнего уровня
  в диалогах altboot;
* *$OEM_DISTRIBUTION* — используется в качестве названия дистрибутива
  в диалогах altboot;
* *$OEM_CDROOT* — необязательный путь к корню ISO-образа внутри initramfs,
  в ОС Альт это /image;
* *$OEM_LIVE_STORAGE* — метка тома live_rw раздела, если указана;
* *$OEM_BAD_STORAGE* — метка тома, чтобы не использовать live_rw раздел
  на плохом или слишком медленном устройстве;
* *$OEM_SETUP_STORAGE* — метка тома раздела для обновления initramfs «на лету»;
* *$OEM_IMAGES_BASE* — куда в stage2 монтировать каталог с образами слоёв LiveCD;
* *$OEM_OVERLAYS_DIR* — куда в stage2 монтировать сами слои LiveCD;
* *$OEM_URL_NETINST* — значение по умолчанию компоненты directory для загрузки
  методами url, http и ftp;
* *$OEM_NFS_NETINST* — значение по умолчанию компоненты directory для загрузки
  методом nfs;
* *$OEM_CIFS_NETINST* — значение по умолчанию компоненты directory для загрузки
  методом cifs.

Функции:

* *get_bootarg()* — получает значение целого параметра загрузки текущего
  «шага» или указанного аргумента;
* *lomount()* — выполняет монтирование файла/устройства после выполнения
  losetup в стиле пропагатора;
* *stage2_setenv()* — устанавливает переменную окружения, экспортируемую
  в stage2;
* *stage2_getenv()* — выводит значение переменной окружения, ранее
  экспортированной в stage2;
* *get_free_ramdisk()* — присваивает указанной переменной имя устройства
  первого свободного RAM-диска;
* *mark_used_ramdisk()* — помечает указанный RAM-диск, как используемый;
* *mark_free_ramdisk()* — помечает указанный RAM-диск, как неиспользуемый;
* *use_hooks()* — запускает на выполнение указанный набор «хуков»;
* *altboot_restart()* — перезапускает все шаги altboot с самого начала.

==== altboot-net-functions

Общий код модуля *make-initrd-bootchain-waitnet*, используемый всеми
«шагами» *altboot* для сетевой загрузки, начиная с версии 0.1.5-alt1.

.Синтаксис:
[,,subs="verbatim,quotes"]
----
. altboot-net-functions
----

.Конфигурационный файл:
[,,subs="verbatim,quotes"]
----
/etc/sysconfig/bootchain
----

Глобальные переменные:

* *$OEM_SRV_NETINST* — значение по умолчанию компоненты server для загрузки
методами url, http и ftp, определяет IP-адрес или имя сервера сетевой загрузки.

Функции:

* *bits_to_mask4()* — конвертирует число бит сетевого адреса в сетевую маску,
  например, $(bits_to_mak4 24) = 255.255.255.0;
* *ip4_to_network()* — конвертирует IPv4-адрес хоста и сетевую маску в
  IPv4-адрес сети;
* *get_dhcp_next_server()* — извлекает IPv4-адрес next-server из опций DHCPv4,
  сохраняемых фичей «network» make-initrd;
* *get_dhcp_root_path()* — извлекает rootpath из опций DHCPv4, сохраняемых
  фичей «network» make-initrd;
* *get_dhcp_wins()* — извлекает IPv4-адрес первого сервера WINS из опций
  DHCPv4, сохраняемых фичей «network» make-initrd;
* *get_default_gateway()* — определяет шлюз по умолчанию;
* *get_first_dns()* — извлекает IPv4-адрес первого сервера DNS из файла
  /etc/resolv.conf.

==== scandev-sh-functions

Весьма объёмный общий код модуля *make-initrd-bootchain-localdev* между
«шагами» *localdev* и *oemsetup*, который также может использоваться в
иных разрабатываемых методах загрузки с локальных носителей.

.Синтаксис:
[,,subs="verbatim,quotes"]
----
. scandev-sh-functions
----

Глобальные переменные:

* *$disk* — название целого диска (sda, md0, dm-0, nvme0n1) для
  поиска соответствия;
* *$part* — название раздела (sda1, nvme0n1p2, c0d0p3) для поиска
  соответствия;
* *$uuid* — UUID раздела для поиска соответствия;
* *$label* — метка тома (LABEL) раздела для поиска соответствия;
* *$target* — используется для сохранения пути к найденному устройству;
* *$method* — один из методов сканирования: oem, disk или cdrom;
* *$devices* — массив названий обнаруженных устройств.

Функции:

* *scan_devices()* — сканирует устройства, заполняя переменные $devices
  и $target, с учётом указанных соответствий заданной спецификации;
* *device_choice()* — выводит меню выбора устройств, в зависимости от
  указанного метода загрузки.

<<<
=== machine-info

Утилитарный скрипт из подпакета *make-initrd-bootchain-core*, предназначенный
для сбора уникальной информации о «железе» и создании уникального хэша по этой
информации.

.Синтаксис:
[,,subs="verbatim,quotes"]
----
machine-info [<option>]
----

Ключи запуска:

* **-d**, **--drivers**: вывести уникальный хэш для привязки к типу машины;
* **-i**, **--instance**: вывести уникальный хэш для привязки к конкретному
  экземпляру машины;
* **без ключей**: вывести основную информацию о типе и экземпляре в виде текста.

