openwisp2-imagegenerator

ansible-openwisp2-imagegenerator

Эта роль Ansible позволяет создавать несколько прошивок openwisp2 для разных организаций, при этом отслеживая их конфигурации.

ПРИМЕЧАНИЕ: эта роль еще не была протестирована в реальных условиях. Если вы собираетесь ее использовать, попробуйте, а если что-то пойдет не так, сообщите о вашей проблеме. Имейте ввиду, что нужно будет разобраться с процессом сборки и его внутренней работой, чтобы она заработала для вас.

Требуемые переменные роли

Следующие переменные обязательны:

openwisp2fw_source_dir: указывает директорию с исходниками OpenWRT, которая используется во время компиляции.
openwisp2fw_generator_dir: указывает директорию, используемую для подготовки генераторов.
openwisp2fw_bin_dir: указывает директорию, используемую при создании финальных образов.
openwisp2fw_organizations: список организаций; посмотрите пример файла playbook.yml в разделе создание файла плейбука, чтобы понять его структуру.

Использование (учебник)

Если вы не знаете, как использовать Ansible, не паникуйте, эта процедура проведет вас шаг за шагом.

Если вы уже знаете, как использовать Ansible, вы можете пропустить этот раздел и перейти сразу к разделу "Установить эту роль".

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

Под "сервером компиляции" мы имеем в виду сервер, который используется для компиляции образов.
Под "локальной машиной" мы имеем в виду хост, с которого вы запускаете Ansible, например: ваш собственный ноутбук или CI-сервер.

Ansible — это инструмент для управления конфигурацией/автоматизации, который работает путем подключения к серверу компиляции через SSH и выполнения серии команд.

1. Установите Ansible

Установите Ansible на своей локальной машине, если вы этого еще не сделали. Существует несколько способов сделать это, но мы предпочитаем использовать официальный менеджер пакетов Python, например:

sudo pip install ansible

Если у вас не установлен pip, смотрите Установка pip на сайте документации по pip.

Установка ansible другими способами также допустима, просто убедитесь, что вы установили версию серии 2.0.x (это версия, с которой мы тестировали этот плейбук).

2. Установите эту роль

Для простоты, проще всего установить эту роль на своей локальной машине через ansible-galaxy (которая была установлена вместе с ansible), поэтому выполните команду:

sudo ansible-galaxy install openwisp.openwisp2-imagegenerator

3. Выберите рабочую директорию

Выберите рабочую директорию на своей локальной машине, где вы будете хранить конфигурацию ваших прошивок.

Например:

mkdir ~/my-openwisp2-firmware-conf
cd ~/my-openwisp2-firmware-conf

Хранение этой рабочей директории под управлением версий также очень хорошая идея; это поможет вам отслеживать изменения, откатываться, настраивать CI-сервер для автоматической сборки образов и так далее.

4. Создайте файл инвентаря

Файл инвентаря — это место, где определяются группы серверов. В нашем простом случае мы можем ограничиться определением группы, в которую мы поместим только один сервер.

Создайте новый файл hosts на своей локальной машине со следующим содержанием:

[myserver]
mycompiler.mydomain.com ansible_user=<youruser> ansible_become_pass=<sudo-password>

Замените mycompiler.mydomain.com на свое имя хоста (ip-адреса также допустимы).

Также укажите своего пользователя SSH и пароль соответственно вместо <youruser> и <sudo-password> (он должен иметь права sudo и не быть root). Эти учетные данные используются на этапе Установки зависимостей.

5. Создайте файл плейбука

Создайте новый файл плейбука playbook.yml на своей локальной машине со следующим содержанием:

# playbook.yml
- hosts: your_host_here
  roles:
    - openwisp.openwisp2-imagegenerator
  vars:
    openwisp2fw_source_dir: /home/user/openwisp2-firmware-source
    openwisp2fw_generator_dir: /home/user/openwisp2-firmware-generator
    openwisp2fw_bin_dir: /home/user/openwisp2-firmware-builds
    openwisp2fw_source_targets:
        - system: ar71xx
          subtarget: generic
          profile: Default
        - system: x86
          subtarget: generic
          profile: Generic
    openwisp2fw_organizations:
        - name: snakeoil # имя организации
          flavours: # поддерживаемые версии
            - standard
          luci_openwisp: # /etc/config/luci_openwisp
            # другие ключи конфигурации могут быть добавлены по желанию
            username: "operator"
            # пароль в открытом виде будет зашифрован в /etc/config/luci_openwisp
            password: "<CHANGE_ME>"
          openwisp: # /etc/config/openwisp
            # другие ключи конфигурации могут быть добавлены по желанию
            url: "https://my-openwisp2-instance.com"
            shared_secret: "my-openwisp2-secret"
            unmanaged: "{{ openwisp2fw_default_unmanaged }}"
          # пароль в открытом виде будет зашифрован в /etc/shadow
          root_password: "<CHANGE_ME>"

Этот плейбук позволит вам компилировать образы прошивки для организации с именем snakeoil, используя только версию standard (которая включает в себя образ OpenWRT 19.07 с модулями стандартного OpenWISP2) для двух архитектур: ar71xx и x86.

Смотрите раздел Переменные роли, чтобы узнать, как настроить доступные конфигурации.

На этом этапе структура вашей директории должна выглядеть так:

.
├── hosts
└── playbook.yml

6. Запустите плейбук

Теперь время начать компиляцию прошивки OpenWISP2.

Запустите плейбук со своей локальной машины с помощью команды:

ansible-playbook -i hosts playbook.yml -e "recompile=1 cores=4"

Вы можете заменить cores=4 на количество доступных вам ядер.

Когда плейбук завершит выполнение, вы найдете образы на сервере компиляции в директории, указанной в openwisp2fw_bin_dir, которая, в нашем примере, находится по адресу /home/user/openwisp2-firmware-builds со следующей структурой директорий:

/home/user/openwisp2-firmware-builds
├── snakeoil/                                      # (каждая организация имеет свою директорию)
├── snakeoil/2016-12-02-094316/ar71xx/standard/    # (содержит образы ar71xx для стандартной версии)
├── snakeoil/2016-12-02-094316/x86/standard/       # (содержит образы x86 для стандартной версии)
└── snakeoil/latest/                               # (latest — это символическая ссылка на последнюю компиляцию)

Теперь, если вы следовали этому учебнику и все прошло успешно, вы готовы настроить вашу конфигурацию в соответствии с вашими потребностями! Продолжайте читать, чтобы узнать, как это сделать.

Переменные роли

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

Некоторые из этих переменных также объясняются в разделах Организации и Версии.

Организации

Если вы работаете с OpenWISP, есть шанс, что вы компилируете образы для разных групп людей: коммерческих клиентов, некоммерческих организаций или любой группы людей, которую можно определить как "организацию".

Организации могут быть определены произвольно в openwisp2fw_organizations.

Для примера, как это сделать, смотрите "пример файла playbook.yml".

Если вам нужно добавить специфические файлы в файловую систему образов каждой организации, смотрите "Добавление файлов для конкретных организаций".

Версии

Версия — это комбинация пакетов, которые включены в образ.

Вы можете создать разные версии для ваших образов, например:

standard: самый распространенный случай
minimal: образ для устройств с ограниченным объемом памяти
mesh: образ с пакетами, необходимыми для реализации сетевой топологии mesh

По умолчанию доступна только версия standard.

Вы можете определить свои собственные версии, установив openwisp2fw_image_flavours — посмотрите на переменные по умолчанию, чтобы понять их структуру.

Процесс сборки

Процесс сборки состоит из следующих шагов.

1. Установка зависимостей

метка: install

На этом этапе устанавливаются или обновляются операционные системы и зависимости, необходимые для последующих шагов.

2. Компиляция

метка: compile

Исходный код OpenWRT компилируется, чтобы получить так называемый "Image Generator". Генератор образов — это архив, который содержит предварительно собранные пакеты и специальный файл Makefile, который будет использоваться для создания настраиваемых образов для каждой организации.

Исходный код загружается и компилируется в директории, указанной в openwisp2fw_source_dir.

3. Подготовка генераторов

метка: generator

На этом этапе генераторы образов извлекаются и подготавливаются для сборки разных образов для разных организаций; каждая организация может создавать образы для разных версий (например: полнофункциональная, минимальная, mesh и т.д.);

Образа извлекаются и подготавливаются в директории, указанной в openwisp2fw_generator_dir.

4. Сборка финальных образов

метка: build

На этом этапе создается ряд образов.

Для каждой архитектуры, организации и версии будет построено несколько образов. Это может создать довольно много файлов, поэтому используйте эту мощность с осторожностью: вероятно, лучше начать с меньшего количества опций и добавлять больше по мере необходимости.

Например, если вы решили использовать 2 архитектуры (ar71xx и x86), 2 организации (например: A и B) и 2 версии (например: standard и mini), вы получите 8 групп образов:

организация: A / версия: standard / арх: ar71xx
организация: A / версия: standard / арх: x86
организация: A / версия: mini / арх: ar71xx
организация: A / версия: mini / арх: x86
организация: B / версия: standard / арх: ar71xx
организация: B / версия: standard / арх: x86
организация: B / версия: mini / арх: ar71xx
организация: B / версия: mini / арх: x86

Образы будут созданы в директории, указанной в openwisp2fw_bin_dir.

5. Загрузка образов в OpenWISP Firmware Upgrader

Последний шаг — загрузка образов в модуль OpenWISP Firmware Upgrader. Этап является необязательным и по умолчанию отключен.

Чтобы включить эту опцию, переменные openwisp2fw_uploader и openwisp2fw_organizations.categories необходимо настроить как в примере ниже:

- hosts:
    - myhost
  roles:
    - openwisp.openwisp2-imagegenerator
  vars:
    openwisp2fw_controller_url: "https://openwisp.myproject.com"
    openwisp2fw_organizations:
      - name: staging
        flavours:
          - default
        openwisp:
          url: "{{ openwisp2fw_controller_url }}"
          shared_secret: "xxxxx"
        root_password: "xxxxx"
        categories:
          default: <CATEGORY-UUID>
      - name: prod
        flavours:
          - default
        openwisp:
          url: "{{ openwisp2fw_controller_url }}"
          shared_secret: "xxxxx"
        root_password: "xxxxx"
        categories:
          default: <CATEGORY-UUID>
    openwisp2fw_uploader:
        enabled: true
        url: "{{ openwisp2fw_controller_url }}"
        token: "<REST-API-USER-TOKEN>"
        image_types:
            - ath79-generic-ubnt_airrouter-squashfs-sysupgrade.bin
            - ar71xx-generic-ubnt-bullet-m-xw-squashfs-sysupgrade.bin
            - ar71xx-generic-ubnt-bullet-m-squashfs-sysupgrade.bin
            - octeon-erlite-squashfs-sysupgrade.tar
            - ath79-generic-ubnt_nanostation-loco-m-xw-squashfs-sysupgrade.bin
            - ath79-generic-ubnt_nanostation-loco-m-squashfs-sysupgrade.bin
            - ath79-generic-ubnt_nanostation-m-xw-squashfs-sysupgrade.bin
            - ar71xx-generic-ubnt-nano-m-squashfs-sysupgrade.bin
            - ath79-generic-ubnt_unifiac-mesh-squashfs-sysupgrade.bin
            - x86-64-combined-squashfs.img.gz
            - x86-generic-combined-squashfs.img.gz
            - x86-geode-combined-squashfs.img.gz
            - ar71xx-generic-xd3200-squashfs-sysupgrade.bin

Следующие заполнители в примере должны быть заменены:

<CATEGORY-UUID> — это UUID категории прошивки в OpenWISP Firmware Upgrader.
<REST-API-USER-TOKEN> — это токен аутентификации REST пользователя с правами на загрузку образов.

Вы можете получить токен аутентификации REST, отправив POST-запрос с помощью браузера API OpenWISP:

Откройте браузер по адресу https://<openwisp-base-url>/api/v1/user/token/.
Введите имя пользователя и пароль в форме внизу страницы.
Отправьте форму, и токен аутентификации REST будет получен в ответе.

Скрипт загрузки создает новый объект сборки и затем загружает образы прошивки, указанные в image_types, которые должны соответствовать идентификаторам, таким как ar71xx-generic-tl-wdr4300-v1-il-squashfs-sysupgrade.bin, определенным в файле hardware.py модуля OpenWISP Firmware Upgrader.

Другие важные моменты, о которых следует знать в скрипте upload_firmware.py:

Скрипт считывает CONFIG_VERSION_DIST и CONFIG_VERSION_NUMBER из файла .config исходного кода OpenWrt, чтобы определить версию сборки.
Скрипт узнает, существует ли сборка с той же версией и категорией, и пытается добавить образы в эту сборку вместо создания новой, если найдены дублираты. Сообщение ошибки будет выведено в консоль, но скрипт не остановится; это позволяет генерировать образы для новых аппаратных моделей и добавлять их в существующие сборки.

Добавление файлов в образы

Вы можете добавлять произвольные файлы в каждый созданный образ, помещая эти файлы в директорию с именем files/ в директории вашего плейбука.

Пример:

.
├── hosts
├── playbook.yml
└── files/etc/profile

files/etc/profile будет добавлен в каждый созданный образ.

Добавление файлов для конкретных организаций

Вы также можете добавлять файлы в образы конкретных организаций.

Допустим, у вас есть организация под названием snakeoil, и вы хотите добавить нестандартный баннер, вы можете сделать это, создав следующую структуру директорий:

.
├── hosts
├── playbook.yml
└── organizations/snakeoil/etc/banner

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

Дополнительные параметры

Вы можете передать следующие дополнительные параметры в ansible-playbook:

recompile: нужно ли повторить шаг компиляции
cores: количество ядер, используемых во время шага компиляции
orgs: список имен организаций, разделенных запятыми, если вам нужно ограничить генерацию образов конкретными организациями

Примеры

Повторная компиляция с 16 ядрами:

ansible-playbook -i hosts playbook.yml -e "recompile=1 cores=16"

Сгенерировать образы только для организации foo:

ansible-playbook -i hosts playbook.yml -e "orgs=foo"

Сгенерировать образы только для организаций foo и bar:

ansible-playbook -i hosts playbook.yml -e "orgs=foo,bar"

Запуск определенных шагов

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

Пример 1, запустить только подготовку генераторов:

ansible-playbook -i hosts playbook.yml -t generator

Пример 2, запустить только подготовку генераторов и этап сборки:

ansible-playbook -i hosts playbook.yml -t generator,build

Цели без подцели

Этот пример показывает, как заполнить openwisp2fw_source_targets для компиляции целей, которые не указывают подцель (например: sunxi, ARMv8, QEMU):

openwisp2fw_source_targets:
    # SOC Allwinner, Lamobo R1
    - system: sunxi
      profile: sun7i-a20-lamobo-r1
    # Виртуальный образ QEMU ARM
    - system: armvirt
      profile: Default

Поддержка

Смотрите Каналы поддержки OpenWISP.

О проекте

Generate different OpenWISP2 firmware images for several organizations

role networking

Установить

ansible-galaxy install openwisp/ansible-openwisp2-imagegenerator

GitHub репозиторий

120 звезд(ы)

12 форк(ов)

2 открытых задач

Лицензия

bsd-3-clause

Загрузки

929

Владелец

OpenWISP

Modular and Programmable Open Source Network Management System for Linux OpenWrt.