Шаблоны

Справочник «Шаблоны» позволяет управлять шаблонами различных типов.

Подробно работа со справочником описана в документе «Руководство администратора» в разделе «Управление шаблонами конфигурационных файлов».

Рендеринг шаблонов

Модуль установки ОС поддерживает шаблоны, с помощью которых можно сформировать:

  • общий конфигурационный файл программы-загрузчика;

    Конфигурационный файл, который размещается в универсальном загрузочном образе в момент формирования образа и отвечает за инициализацию сетевого интерфейса устройства, а также обеспечивает скачивание устройство-специфичной конфигурации программы-загрузчика.

    Пример шаблона
    #!ipxe
    
    {% set ipxeScript = osmax_provisioner_base_url +  '/v1/boot_loaders/ipxe/config?mac=' %}
    
    echo LCM Bootdisk: Generic image
    
    {% for i in range(33) %}
    :net{{ i }}
    echo net{{ i }} - mac is ${net{{ i }}/mac}
    isset ${net{{ i }}/mac} || goto no_nic
    echo start dhcp for net{{ i }}
    dhcp net{{ i }} || goto net{{ i + 1 }}
    echo start chain for net{{ i }} - {{ ipxeScript }}${net{{ i + 1 }}/mac}
    chain {{ ipxeScript }}${net{{ i }}/mac} || goto net{{ i + 1 }}
    {% endfor %}
    
    :net33
    echo net33
    goto no_nic
    
    exit 0
    
    ifstat
    :no_nic
    echo -n Enter interface name to boot from (e.g. net0):  && read interface
    echo Selected ${interface} with mac ${interface}/mac
    isset ${interface}/mac && goto get_static_ip
    echo Interface ${interface} is not initialized, try again
    goto no_nic
    
    :get_static_ip
    ifopen ${interface}
    echo Please enter IP details for ${interface}
    echo
    echo -n IP address      :  && read ${interface}/ip
    echo -n Subnet mask     :  && read ${interface}/netmask
    echo -n Default gateway :  && read ${interface}/gateway
    echo -n DNS server      :  && read dns
    chain {{ ipxeScript }}${interface}/mac || goto boot_failure
    exit 0
    
    :boot_failure
    echo Cannot continue, spawning shell
    shell
  • устройство-специфичный конфигурационный файл;

    Индивидуальный конфигурационный файл программы-загрузчика для конкретного устройства, который скачивается на устройство в ходе выполнения скрипта конфигурационного файла программы-загрузчика для универсального загрузочного образа. Отвечает за скачивание на устройство и вызов на исполнение файлов kernel, initrd. Обеспечивает актуализацию статуса процесса установки (как позитивного, так и ошибочных), взаимодействуя с API модуля установки ОС.

    Пример шаблона
    #!ipxe
    
    {% set autoinstallScript = osmax_provisioner_base_url + unattended_install_file_url + '?mac=' %}
    
    echo Astra iPXE configuration loaded
    kernel {{ repository_url }}{{ kernel }} initrd=initrd.gz modprobe.blacklist=evbug priority=critical debian-installer/allow_unauthenticated_ssl=true auto-install/enable=true  netcfg/choose_interface=auto url={{ autoinstallScript }}${netX/mac} {{ kernel_options }} || goto failed_install_kernel
    initrd {{ repository_url }}{{ initrd }} || goto failed_install_initrd
    boot || goto failed_install_boot
    
    :failed_install_kernel
    params
    param step INSTALL_ERROR_KERNEL
    param additionalInfo kernel {{ repository_url }}{{ kernel }}x initrd=initrd.gz modprobe.blacklist=evbug priority=critical debian-installer/allow_unauthenticated_ssl=true auto-install/enable=true  netcfg/choose_interface=auto url={{ autoinstallScript }}${netX/mac} {{ kernel_options }}
    param status INSTALL_ERROR
    chain {{ osmax_provisioner_base_url }}/v1/unprovisioned_machines/{{machine_id}}/installation_process/status##params || goto error
    
    :failed_install_initrd
    params
    param step INSTALL_ERROR_INITRD
    param status INSTALL_ERROR
    param additionalInfo initrd {{ repository_url }}{{ initrd }}
    chain {{ osmax_provisioner_base_url }}/v1/unprovisioned_machines/{{machine_id}}/installation_process/status##params || goto error
    
    :failed_install_boot
    params
    param step INSTALL_ERROR_BOOT
    param status INSTALL_ERROR
    chain {{ osmax_provisioner_base_url }}/v1/unprovisioned_machines/{{machine_id}}/installation_process/status##params || goto error
    
    :error
    echo Cannot continue, spawning shell
    shell
  • файл ответов;

    Файл для автоматической установки ОС без участия пользователя. Обеспечивает актуализацию статуса процесса установки (как позитивного, так и ошибочных), взаимодействуя с API модуля установки ОС. Вызывает выполнение скрипта пост-установки.

    Пример шаблона
    # Выбор языка
    d-i debian-installer/locale string ru_RU
    d-i debian-installer/locale select ru_RU.UTF-8
    
    # Настройка раскладки клавиатуры
    d-i console-tools/archs               select at
    d-i console-keymaps-at/keymap         select ru
    d-i console-setup/toggle              string Alt+Shift
    d-i console-setup/layoutcode          string ru
    d-i keyboard-configuration/toggle     select Ctrl+Shift
    d-i keyboard-configuration/layoutcode string ru
    d-i keyboard-configuration/xkb-keymap select ru
    d-i languagechooser/language-name-fb  select Russian
    d-i countrychooser/country-name       select Russia
    
    # Конфигурирование сети
    d-i netcfg/enable        boolean true
    # Устанавливается переменная hostname
    d-i netcfg/hostname      string {{ hostname }}
    #d-i netcfg/get_hostname  string {{ hostname }}
    # Устанавливается переменная domain
    d-i netcfg/get_domain    string {{ domain }}
    
    # Выбор компонент репозитория
    d-i apt-setup/non-free        boolean true
    d-i apt-setup/contrib         boolean true
    d-i apt-setup/services-select none
    
    # Настройки зеркал репозиториев
    d-i apt-setup/use_mirror boolean false
    
    # Настройка инсталляционного репозитория
    d-i mirror/country        string manual
    d-i mirror/protocol       string http
    d-i mirror/http/hostname  string <<АДРЕС ИНСТАЛЛЯЦИОННОГО РЕПОЗИТОРИЯ>>
    d-i mirror/http/directory string <<КАТАЛОГ С ИНСТАЛЛЯЦИОННЫМИ ФАЙЛАМИ>>
    d-i mirror/http/proxy     string
    
    # Отключение выбора установки по ssh
    d-i network-console/enable boolean false
    
    # Разметка диска
    d-i partman-auto/method                string regular
    
    # QEMU specific fix - it places usb as /dev/sda and hdd as /dev/sdb but we
    # also need to support cd-rom where hdd is /dev/sda
    # https://github.com/turnkeylinux/di-live/blob/master/d-i/source/debian-installer-utils/list-devices-linux
    #d-i partman-auto/disk                  string /dev/sda
    d-i partman/early_command              string debconf-set partman-auto/disk "$(list-devices disk | head -n1)"
    
    d-i partman-auto/purge_lvm_from_device boolean true
    d-i partman-lvm/confirm                boolean true
    d-i partman-auto/choose_recipe         select boot-root
    d-i partman/confirm_write_new_label    boolean true
    d-i partman/choose_partition           select finish
    d-i partman/confirm                    boolean true
    d-i partman-auto-crypto/erase_disks    boolean true
    d-i partman-basicfilesystems/no_swap   boolean false
    d-i partman-target/mount_failed        boolean true
    d-i partman-partitioning/unknown_label boolean true
    d-i partman-lvm/vgdelete_confirm       boolean true
    d-i partman/confirm_nooverwrite        boolean true
    d-i partman-auto-lvm/no_boot           boolean false
    d-i partman-efi/non_efi_system         boolean true
    # Выбор способа монтирования
    d-i partman/mount_style                select uuid
    
    # Установка часов
    d-i clock-setup/utc  boolean true
    d-i time/zone string Europe/Moscow
    
    # Установка репозитория
    d-i apt-setup/non-free-firmware            boolean false
    d-i apt-setup/disable-cdrom-entries        boolean true
    d-i apt-setup/services-select              multiselect
    d-i debian-installer/allow_unauthenticated boolean true
    
    # Параметры пользователя root
    d-i passwd/root-login            boolean true
    # Установка переменной root_crypted_password
    d-i passwd/root-password-crypted password {{ root_crypted_password }}
    
    # Параметры локального пользователя
    d-i passwd/make-user             boolean {{ is_create_user }}
    # Установка переменной user_full_name
    d-i passwd/user-fullname         string {{ user_full_name }}
    # Установка переменной username
    d-i passwd/username              string {{ user_name }}
    # Пароль локального пользователя
    d-i passwd/user-password-crypted password {{ user_crypted_password}}
    d-i passwd/user-default-groups   string {{ user_name }} sudo
    
    # Установка базовой системы
    d-i base-installer/kernel/image string linux-image-generic
    
    # Установка программы-загрузчика
    d-i grub-installer/only_debian      boolean true
    d-i grub-installer/bootdev          string /dev/sda
    d-i grub-installer/with_other_os    boolean false
    # Пароль программы-загрузчика GRUB
    d-i grub-installer/password-crypted password $1$kc7j6jdt$WPn8SmeAna5Tz2dxaH5Ww0
    
    # Выбор ПО для установки
    tasksel tasksel/first                                   multiselect ssh-server
    d-i pkgsel/include                                      string open-vm-tools curl net-tools wget network-manager
    popularity-contest popularity-contest/participate       boolean false
    d-i astra-additional-setup/os-check                     select Advanced security level Voronezh
    d-i astra-additional-setup/additional-settings-voronezh multiselect Enable Mandatory Integrity Control, Disable ptrace capability
    
    # Завершение установки
    d-i finish-install/reboot_in_progress note
    
    # Регистрация старта установки (внутреннее использование, зарезервировано, удаление инструкции приведет к ошибкам регистрации статуса установки)
    d-i preseed/early_command string wget --method=post --body-data='status=IN_PROCESS&step=IN_PROCESS_EARLY' --header="content-type: application/x-www-form-urlencoded" -O- {{ osmax_provisioner_base_url }}/v1/unprovisioned_machines/{{ machine_id }}/installation_process/status
    
    # Финальные действия при установке
    # Для расширения шаблона можно добавлять действия перед командой "Вызов скрипта пост-инсталляции"
    d-i preseed/late_command string \
    # Вызов скрипта пост-инсталляции
    in-target wget {{ osmax_provisioner_base_url }}/v1/provisioning_scripts?machineId={{ machine_id }} -O /tmp/post_install.sh; \
    in-target chmod +x /tmp/post_install.sh; \
    in-target /tmp/post_install.sh; \
    # Формирование файла-метки
    in-target sh -c "mkdir -p {{ os_install_label_path }} && touch {{ os_install_label_path }}/{{ installation_label }}"; \
    # Регистрация завершения установки
    in-target wget --method=post --body-data='status=FINISHED&step=FINISHED' --header="content-type: application/x-www-form-urlencoded" -O- {{ osmax_provisioner_base_url }}/v1/unprovisioned_machines/{{ machine_id }}/installation_process/status;

    При регистрации шаблона явно укажите строки:

    # Настройка инсталляционного репозитория
    ..
    d-i mirror/http/hostname  string <<АДРЕС ИНСТАЛЛЯЦИОННОГО РЕПОЗИТОРИЯ>>
    d-i mirror/http/directory string <<КАТАЛОГ С ИНСТАЛЛЯЦИОННЫМИ ФАЙЛАМИ>>

    Для указания используйте конфигурируемые плейсхолдеры.

  • скрипт пост-установки.

    Скрипт, обеспечивающий выполнение необходимых действий после установки ОС.

    Пример шаблона
    #!/bin/bash
    {# Переменные шаблона пост-инсталляционного скрипта #}
    {# Для использования шаблона необходимо опредилить переменные, убрав комментари и указать для них (переменных) значения#}
    {# Публичные ключи apt репозитоария repository_keys. Ключи можно задать в явном виде, поместив содержимое в публичного ключа в поле data. #}
    {# Eсли планируется получать публичный ключ с http[s]- репозитория, то в поле url указать путь по которому можно получить ключ.#}
    {#{% set repository_keys = [
       {
            'keyring': '/etc/apt/trusted.gpg.d/apt-company-local.gpg',
            'data':'<публичный ключ>',
            'url':'<путь к репозиторию с публичным ключом>'
        }
    ]%}#}
    
    {# sources_list_repositories задает список репозиториев, которые необходимо добавить в /etc/apt/source.list #}
    {#{% set sources_list_repositories = [
        { 'repo': 'deb https://apt.local.reository/repository/astra-frozen/1.7_x86-64/1.7.5/repository-base/ 1.7_x86-64 main contrib non-free' },
        { 'repo': 'deb https://apt.local.reository/repository/astra-frozen/1.7_x86-64/1.7.5/repository-update/ 1.7_x86-64 main contrib non-free' },
        { 'repo': 'deb https://apt.local.reository/repository/astra-frozen/1.7_x86-64/1.7.5/repository-extended/ 1.7_x86-64 main contrib non-free' },
        { 'repo': 'deb https://apt.local.reository/repository/astra-frozen/1.7_x86-64/1.7.5/repository-main/ 1.7_x86-64 main contrib non-free' }
    ]%}#}
    
    {# login_configuration - задает список Apt login configuration файлов для добавления в /etc/apt/auth.conf.d/", в случае
    если не требуется данная настройка, то список остается пустой#}
    {#{% set login_configurations = [
        { 'filename': 'apt1-proxy-company-local',
          'machine': 'apt1-proxy-company-local/repository/apt-1/',
          'login': 'username',
          'password': 'password' },
        { 'filename': 'apt2-proxy-company-local',
          'machine': 'apt2-proxy.company.local/repository/apt-2/',
          'login': 'username',
          'password': 'password' }
    ]%}#}
    {# Список дополнительных apt - sources файлов, добавляемых в /etc/apt/auth.conf.d/, в случае если не требуется, то
    список должен быть пустым #}
    {#{% set repositories = [
        { 'filename': 'apt-company-local-osmax',
          'repo': 'deb https://apt.company.local/repository/osmax/ 1.7_x86-64 main' },
        { 'filename': 'apt-company-local-fluentbit',
          'repo': 'deb https://apt.company.local/repository/fluentbit/buster buster main' }
    ]%}#}
    
    {# Призанак необходимости ввод в домен #}
    {#{% set join_domain_enabled = false %}#}
    {# join_domain_script - способ получения скрипта, base64 - скрипт передается в шаблоне в бинарном виде в кодировке base64,
     скрипт располагается на http репозитории, url - url, по которому можно скачать скрипт ввода в домен#}
    {#{% set join_domain_script = {
        'base64': '<скрипт в бинароном виде в кодировке base64>',
        'url': '<url по которому можно получить бинарый скрипт ввода в домен>'
    }
    %}#}
    {# Дополнительные данные о подразделении, куда необходимо включить устройство (Organizational Unit) #}
    {% set join_domain_ou = '' %}
    
    set -e
    
    {% if repository_keys | length > 0  -%}
    echo "Добавление Apt keys"
    {%- for key_record in repository_keys -%}
    {% set key_tmp_file = "/tmp/" + ((key_record.keyring).split("/") | last) %}
    {% if key_record.data | length > 0%}
    cat <<EOL > {{ key_tmp_file }}
    {{key_record.data}}
    EOL
    {% else %}
    wget  -q {{key_record.url}} -O {{key_tmp_file}}
    {% endif %}
    apt-key --keyring {{ key_record.keyring }} add {{ key_tmp_file }}
    rm {{ key_tmp_file }}
    {% endfor %}
    {% endif -%}
    
    {% if sources_list_repositories | length > 0  -%}
    echo "Очистка /etc/apt/sources.list и добавление записей о репозиториях"
    cat /dev/null > /etc/apt/sources.list
    {% for repo_record in sources_list_repositories -%}
    echo "{{ repo_record.repo }}" >> /etc/apt/sources.list
    {% endfor %}
    {% endif -%}
    
    {% if login_configurations | length > 0  -%}
    echo "Добавление Apt login configuration файлов в /etc/apt/auth.conf.d/"
    {% for login_record in login_configurations -%}
    echo "machine {{ login_record.machine }} login {{ login_record.login }} password {{ login_record.password }}" > /etc/apt/auth.conf.d/{{ login_record.filename }}.conf
    {% endfor %}
    {% endif -%}
    
    {% if repositories | length > 0  -%}
    echo "Добавление Apt sources файлов в /etc/apt/sources.list.d/"
    {% for repo_record in repositories -%}
    echo "{{ repo_record.repo }}" > /etc/apt/sources.list.d/{{ repo_record.filename }}.list
    {% endfor %}
    {% endif -%}
    
    {% if join_domain_enabled %}
    echo "Получение скрипта ввода в домен"
    
    {% if join_domain_script.base64 | length > 0 %}
    cat <<EOL > /tmp/join_domain_script
    {{join_domain_script.base64}}
    EOL
    base64 -d /tmp/join_domain_script > /usr/bin/join_domain
    {% else %}
    wget  -q {{join_domain_script.url}} -O /usr/bin/join_domain
    {% endif-%}
    chmod a+x /usr/bin/join_domain
    
    cat <<EOL > /usr/bin/join_domain.env
    DomainName={{ domain }}
    {% if join_domain_ou | length > 0 %}
    ChangeComputerOU=true
    {% else %}
    ChangeComputerOU=false
    {% endif %}
    NewComputerOU={{join_domain_ou}}
    EOL
    
    {% endif-%}
    
    echo "Cоздание скрипта первичной загрузки"
    
    cat <<EOL > /usr/bin/first-boot.sh
    #!/bin/bash
    set -x
    echo "Синхронизация индексных файлов Apt"
    apt-get update
    {% if join_domain_enabled %}
    echo "Ввод устройства в домен"
    /usr/bin/join_domain
    rm -f /usr/bin/join_domain.env
    rm -f /usr/bin/join_domain
    {% endif -%}
    sudo rm -f  /etc/systemd/system/first-boot-service.service
    shutdown -r +1
    sleep 58
    rm -f /usr/bin/first-boot.sh
    EOL
    
    echo "Подготовка сервис-юнита для запуска скрипта первичной загрузки"
    cat <<EOL > /etc/systemd/system/first-boot-service.service
    [Unit]
    Description=PostInstall Auto-update system and Join Domain
    After=rc-local.service network-online.target
    Wants=network-online.target
    Before=getty.target
    Before=systemd-user-sessions.service
    
    [Service]
    StandardOutput=tty
    Type=oneshot
    ExecStart=/usr/bin/first-boot-script.sh
    
    [Install]
    WantedBy=multi-user.target
    EOL

    При регистрации шаблона явно укажите строки:

        'data':'<публичный ключ>',
        'url':'<путь к репозиторию с публичным ключом>'
    
        'base64': '<скрипт в бинароном виде в кодировке base64>',
        'url': '<url по которому можно получить бинарый скрипт ввода в домен>'

    Для указания используйте конфигурируемые плейсхолдеры.

Cистемные плейсхолдеры

Шаблоны установки ОС — это текстовые файлы с поддержкой движка шаблонизации Jinja. Помимо стандартных возможностей шаблонизации, модуль установки ОС поддерживает работу с предопределёнными (системными) и конфигурируемыми плейсхолдерами.

Предопределённые (системные) плейсхолдеры вычисляются динамически для конкретного устройства и могут быть использованы только для ограниченного набора шаблонов:

  • шаблон устройство-специфичной конфигурации программы-загрузчика;

  • шаблон файла ответов;

  • шаблон постинсталляционного скрипта.

Модуль установки ОС поддерживает следующие системные плейсхолдеры:

  • hostname — имя хоста устройства;

  • domain — домен устройства;

  • mac — MAC-адрес устройства;

  • architecture — архитектура процессора (определяется на основании дистрибутива для плана развертывания);

  • initrd — путь к файлу initrd (определяется на основании дистрибутива для плана развертывания);

  • kernel — путь к файлу ядра ОС (определяется на основании дистрибутива для плана развертывания);

  • repository_url — путь к HTTP(S)-серверу, где размещены файлы ядра и initrd;

  • kernel_options — опции ядра ОС (определяется на основании дистрибутива для плана развертывания);

  • is_create_user — признак необходимости создавать пользователя (помимо root) в процессе установки (определяется на основании дистрибутива для плана развертывания);

  • password_hash_algorithm — алгоритм хеширования пароля root\пользователя (определяется на основании дистрибутива для плана развертывания);

  • root_crypted_password — зашифрованный пароль root;

  • user_full_name — полное имя пользователя, создаваемого помимо root при установке ОС;

  • user_name — имя пользователя, создаваемого помимо root при установке ОС;

  • user_crypted_password — зашифрованный пароль пользователя, создаваемого помимо root при установке ОС;

  • machine_id — идентификатор нового устройства;

  • installation_label — метка, прописываемая на устройство после установки ОС (определяется на основании плана развертывания, либо на основании версии конфигурации для сценария переустановки ОС).

Конфигурируемые плейсхолдеры

Конфигурируемые плейсхолдеры можно добавить в конфигурацию модуля установки ОС и свободно использоваться в любом шаблоне.

Чтобы объявить конфигурируемый плейсхолдер, задайте новый параметр в группу osmax.provisioner.template-engine.template-placeholders, указав в суффиксе требуемое название плейсхолдера и задав необходимое значение.

Конфигурационный параметр в application.properties модуля установки ОС:

osmax.provisioner.template-engine.template-placeholders.osmax_provisioner_base_url=http://myhost:9080

Использование в Jinja-шаблоне:

some_address={{ osmax_provisioner_base_url }}

Результат рендеринга шаблона:

some_address=http://myhost:9080
При указании имен конфигурируемых плейсхолдеров рекомендуется использовать стиль написания snake_case (слова разделяются символом подчеркивания (_), и все буквы пишутся в нижнем регистре).

Модуль установки ОС содержит следующие конфигурируемые плейсхолдеры:

  • osmax_provisioner_base_url — базовый URL-адрес для доступа к модулю установки ОС;

  • unattended_install_file_url — URL-адрес API модуля установки ОС для получения файла автоответов;

  • repository_cert_url — путь к репозиторию с сертификатами.

    Опциональный параметр, который используется для доверенного режима работы.