== Разработчику 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_fatal()* — выводит сообщение о фатальной ошибке и предлагает
  перезагрузиться либо выйти в rdshell (начиная с версии *0.1.5-alt15*);
* *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_TEST*` — непустое значение, если через параметры или конфигурацию
  передано название проводимого авто-теста;
* `*$BC_TMPFS_SIZE*` — непустое значение размера TMPFS, иначе используется
  дефолтное значение «50%» (начиная с версии *0.1.5-alt27*);
* `*$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()*` — выполняет журналируемый перезапуск компьютера;
* `*bc_seconds()*` — записывает в указанную переменную текущее число секунд
  от начала загрузки (начиная с версии *0.1.6-alt1*);
* `*longtermop_start()*` — приостанавливает ограничительный таймер загрузки
  на время выполнения длительной операции или работы с диалогом ввода данных,
  допускаются и учитываются вложенные вызовы (начиная с версии *0.1.5-alt32*);
* `*longtermop_end()*` — возобновляет работу ограничительного таймера загрузки
  после работы с диалогом ввода данных или выполнения длительной операции,
  допускаются и учитываются вложенные вызовы (начиная с версии *0.1.5-alt32*);
* `*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_CDROOT* — необязательный путь к корню ISO-образа внутри initramfs,
  в ОС Альт это /image;
* *$OEM_WELCOME_TEXT* — используется в качестве заголовка верхнего уровня
  в диалогах altboot;
* *$OEM_DISTRIBUTION* — используется в качестве названия дистрибутива
  в диалогах altboot;
* *$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()* — получает значение целого параметра загрузки текущего
  «шага» или указанного аргумента;
* *mediacheck()* — выполняет проверку указанного устройства или файла
  с ISO-образом программой checkisomd5 (начиная с *0.1.5-alt32*);
* *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 раздела для поиска соответствия;
* *$fuid* — используется для проверки одноимённого файла рядом со сквошом,
  а в отсутствии $uuid используется для поиска соответствия UUID, но не
  исключает раздел, если не окажется совпадения (начиная с *0.1.5-alt30*);
* *$label* — метка тома раздела (VOLUME LABEL) для поиска соответствия;
* *$whole* — название устройства целого диска: заполняется автоматически
  некоторыми функциями, если обнаруженный раздел находится на носителе
  ISO Hybrid или если найденное устройство является оптическим диском
  в формате ISO-9660 (начиная с *0.1.6-alt1*);
* *$target* — найденное загрузочное устройство (диск или раздел);
* *$method* — один из методов сканирования: oem, disk или cdrom;
* *squash* — название файла со сквошом второй стадии загрузки: используется
  только в форме выбора накопителя, если указано (начиная с *0.1.6-alt1*,
  ранее для тех же целей использовался глобальный параметр stagename);
* *$devices* — массив названий обнаруженных, потенциально пригодных для
  загрузки устройств, без учёта заданной спецификации;
* *$__scandev_last* — массив предварительно отфильтрованных, но детально ещё
  не изученных устройств, получаемый на первом этапе чтения /proc/partitions:
  достаточно очистить эту переменную, чтобы добиться полного пересканирования
  дисков (начиная с *0.1.6-alt1*);

Функции:

* *start_dev_scan()* — визуально сообщает пользователю виджетом ponder
  о начале сканирования дисков (начиная с *0.1.6-alt1*, ранее не
  документировалась и имела другое имя);
* *stop_dev_scan()* — визуально сообщает пользователю виджетом ponder
  об окончании сканирования дисков (начиная с *0.1.6-alt1*);
* *devname2target()* — из полученного имени устройства, такого, как sda3
  или nvme0n1, заполняет переменные $target и $whole: 1) для метода oem,
  обычных дисков и разделов $whole будет пустым, а $target равен /dev/$1;
  2) для целого оптического диска $whole будет равен $target и будет
  указывать на весь диск; 3) для методов disk и cdrom, если указанный диск
  или раздел относится к ISO Hybrid, $whole будет указывать на родительский
  диск, а $target на первый раздел этого диска (начиная с *0.1.6-alt1*);
* *debug_found_target()* — в режиме отладки выводит в журнал информацию
  о найденных устройствах $target и $whole (начиная с *0.1.6-alt1*);
* *scan_devices()* — сканирует устройства, заполняя переменные $devices,
   $__scandev_last, $target и $whole, с учётом соответствия указанной
   спецификации;
* *device_choice()* — выводит меню выбора устройств, в зависимости от
  указанного метода загрузки.

==== localdev-sh-functions

Функции для работы с дисками более общего характера, которые можно
использовать и за пределами модуля *make-initrd-bootchain-localdev*
(начиная с *0.1.6-alt1*).

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

Функции:

* *read_udev_field()* — читает указанное поле из указанного устройства
  средствами udevadm, в режиме отладки выполняемое действие журналируется;
* *read_blkid_field()* — читает указанное поле из указанного устройства
  средствами blkid, в режиме отладки выполняемое действие журналируется;
* *read_fstype()* — читает и возвращает тип файловой системы для указанного
  устройства при помощи udevadm или blkid;
* *devname2sysfs()* — определяет и возвращает путь в sysfs для указанного
  (существующего) устройства;
* *parent_disk()* — определяет и возвращает имя целого диска для указанного
  (существующего) устройства раздела или пустой результат, если родительского
  устройства не удастся обнаружить.

=== machine-info

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

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

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

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

