ansible-openwisp2-imagegenerator

Ce rôle Ansible permet de créer plusieurs images de firmware openwisp2 pour différentes organisations tout en gérant leurs configurations.

REMARQUE : ce rôle n'a pas encore été testé dans un environnement réel. Si vous envisagez de l'utiliser, essayez-le et si quelque chose ne fonctionne pas, veuillez signaler votre problème, mais gardez à l'esprit que vous devrez comprendre le processus de construction et son fonctionnement interne pour le faire fonctionner pour vous.

Variables de rôle requises

Les variables suivantes sont requises :

• openwisp2fw_source_dir : indique le répertoire de la source OpenWRT utilisé lors de la compilation
• openwisp2fw_generator_dir : indique le répertoire utilisé pour la préparation des générateurs
• openwisp2fw_bin_dir : indique le répertoire utilisé lors de la création des images finales
• openwisp2fw_organizations : une liste d'organisations ; voir le fichier exemple playbook.yml dans la section créer un fichier playbook pour comprendre sa structure

Utilisation (tutoriel)

Si vous ne savez pas comment utiliser Ansible, ne paniquez pas, cette procédure vous guidera étape par étape.

Si vous savez déjà comment utiliser Ansible, vous pouvez passer cette section et aller directement à la section "Installer ce rôle".

Tout d'abord, vous devez comprendre deux concepts clés :

• par "serveur de compilation", nous entendons un serveur utilisé pour compiler les images
• par "machine locale", nous entendons l'hôte depuis lequel vous lancez Ansible, par exemple : votre propre ordinateur portable ou serveur CI

Ansible est un outil de gestion de configuration/automatisation qui fonctionne en se connectant au serveur de compilation via SSH et en exécutant une série de commandes.

1. Installer Ansible

Installez Ansible sur votre machine locale si vous ne l'avez pas déjà fait, il existe plusieurs façons de le faire, mais nous préférons utiliser le gestionnaire de paquets Python officiel, par exemple :

sudo pip install ansible

Si vous n'avez pas pip installé, consultez Installation de pip sur le site de documentation de pip.

Installer Ansible d'autres manières est également acceptable, il suffit de s'assurer d'installer une version de la série 2.0.x (qui est la version avec laquelle nous avons testé ce playbook).

2. Installer ce rôle

Pour des raisons de simplicité, le plus facile est d'installer ce rôle sur votre machine locale via ansible-galaxy (qui a été installé lors de l'installation d'Ansible), exécutez donc :

sudo ansible-galaxy install openwisp.openwisp2-imagegenerator

3. Choisir un répertoire de travail

Choisissez un répertoire de travail sur votre machine locale où vous mettrez la configuration de vos images de firmware.

Exemple :

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

Mettre ce répertoire de travail sous contrôle de version est également une très bonne idée, cela vous aidera à suivre les changements, à revenir en arrière, à configurer un serveur CI pour construire automatiquement les images pour vous, etc.

4. Créer un fichier d'inventaire

Le fichier d'inventaire est l'endroit où les groupes de serveurs sont définis. Dans notre cas simple, nous pouvons nous en sortir avec la définition d'un groupe dans lequel nous allons mettre juste un serveur.

Créez un nouveau fichier hosts sur votre machine locale avec le contenu suivant :

[myserver]
mycompiler.mydomain.com ansible_user=<votre-utilisateur> ansible_become_pass=<mot-de-passe-sudo>

Remplacez mycompiler.mydomain.com par votre nom d'hôte (les adresses IP sont également acceptées).

Mettez également votre utilisateur SSH et votre mot de passe respectivement à la place de <votre-utilisateur> et <mot-de-passe-sudo> (doit être sudoer et non-root). Ces informations d'identification sont utilisées lors de l'étape Installation des dépendances.

5. Créer un fichier playbook

Créez un nouveau fichier playbook playbook.yml sur votre machine locale avec le contenu suivant :

# 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 # nom de l'org
          flavours: # saveurs prises en charge
            - standard
          luci_openwisp: # /etc/config/luci_openwisp
            # d'autres clés de configuration peuvent être ajoutées librement
            username: "operator"
            # mot de passe en texte clair qui sera crypté dans /etc/config/luci_openwisp
            password: "<CHANGE_ME>"
          openwisp: # /etc/config/openwisp
            # d'autres clés de configuration peuvent être ajoutées librement
            url: "https://my-openwisp2-instance.com"
            shared_secret: "my-openwisp2-secret"
            unmanaged: "{{ openwisp2fw_default_unmanaged }}"
          # mot de passe en texte clair qui sera crypté dans /etc/shadow
          root_password: "<CHANGE_ME>"

Ce playbook vous permettra de compiler des images de firmware pour une organisation nommée snakeoil en utilisant uniquement la saveur standard (qui inclut une image OpenWRT 19.07 par défaut avec les modules OpenWISP2 standards) pour deux architectures, ar71xx et x86.

Consultez la section Variables de rôle pour savoir comment personnaliser les configurations disponibles.

À ce stade, la structure de votre répertoire devrait ressembler à ceci :

.
├── hosts
└── playbook.yml

6. Exécuter le playbook

Il est maintenant temps de commencer la compilation du firmware OpenWISP2.

Lancez le playbook depuis votre machine locale avec :

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

Vous pouvez remplacer cores=4 par le nombre de cœurs dont vous disposez.

Lorsque le playbook a terminé de s'exécuter, vous trouverez les images sur le serveur de compilation situé dans le répertoire spécifié dans openwisp2fw_bin_dir, qui dans notre exemple est /home/user/openwisp2-firmware-builds avec une structure de répertoire comme suit :

/home/user/openwisp2-firmware-builds
├── snakeoil/                                      # (chaque org a son propre répertoire)
├── snakeoil/2016-12-02-094316/ar71xx/standard/    # (contient les images ar71xx pour la saveur standard)
├── snakeoil/2016-12-02-094316/x86/standard/       # (contient les images x86 pour la saveur standard)
└── snakeoil/latest/                               # (latest est un lien symbolique vers la dernière compilation)

Maintenant, si vous avez suivi ce tutoriel et que tout a fonctionné, vous êtes prêt à personnaliser votre configuration pour l'adapter à vos besoins ! Continuez à lire pour savoir comment y parvenir.

Variables de rôle

Il existe de nombreuses variables qui peuvent être personnalisées si nécessaire, consultez les valeurs par défaut pour une liste complète.

Certaines de ces variables sont également expliquées dans Organisations et Saveurs.

Organisations

Si vous travaillez avec OpenWISP, il y a des chances que vous compiliez des images pour différents groupes de personnes : clients à but lucratif, organisations à but non lucratif ou tout groupe de personnes qui peut être défini comme une "organisation".

Les organisations peuvent être définies librement dans openwisp2fw_organizations.

Pour un exemple de la façon de faire cela, référez-vous au "fichier playbook.yml d'exemple".

Si vous avez besoin d'ajouter des fichiers spécifiques dans l'arborescence du système de fichiers des images de chaque organisation, consultez "Ajouter des fichiers pour des organisations spécifiques".

Saveurs

Une saveur est une combinaison de packages inclus dans une image.

Vous pouvez vouloir créer différentes saveurs pour vos images, par exemple :

• standard : le cas d'utilisation le plus courant
• minimal : une image pour des appareils ayant peu d'espace de stockage disponible
• mesh : une image avec des packages nécessaires à la mise en œuvre d'un réseau maillé

Par défaut, seule une saveur standard est disponible.

Vous pouvez définir vos propres saveurs en configurant openwisp2fw_image_flavours - consultez les variables par défaut pour comprendre sa structure.

Processus de construction

Le processus de construction se compose des étapes suivantes.

1. Installation des dépendances

tag : install

Au cours de cette phase, les dépendances du système d'exploitation nécessaires aux étapes suivantes sont installées ou mises à jour.

2. Compilation

tag : compile

La source OpenWRT est compilée afin de produire ce qu'on appelle un "Image Generator". Le générateur d'image est une archive qui contient les packages précompilés et un Makefile spécial qui sera utilisé pour générer les images personnalisées pour chaque organisation.

La source est téléchargée et compilée dans le répertoire spécifié dans openwisp2fw_source_dir.

3. Préparation des générateurs

tag : generator

Pendant cette étape, les générateurs d'image sont extraits et préparés pour construire différentes images pour différentes organisations, chaque organisation pouvant construire des images pour différentes saveurs (ex : complet, minimal, maillé, etc.) ;

Les images sont extraites et préparées dans le répertoire spécifié dans openwisp2fw_generator_dir.

4. Construction des images finales

tag : build

Au cours de cette phase, une série d'images est produite.

Plusieurs images seront construites pour chaque architecture, organisation et saveur. Cela peut générer un grand nombre de fichiers, utilisez donc ce pouvoir avec précaution : il est probablement préférable de commencer avec moins d'options et d'ajouter plus de cas par la suite.

Par exemple, si vous choisissez d'utiliser 2 architectures (ar71xx et x86), 2 organisations (ex: A et B) et 2 saveurs (ex: standard et mini), vous obtiendrez 8 groupes d'images :

• organisation : A / saveur : standard / arch : ar71xx
• organisation : A / saveur : standard / arch : x86
• organisation : A / saveur : mini / arch : ar71xx
• organisation : A / saveur : mini / arch : x86
• organisation : B / saveur : standard / arch : ar71xx
• organisation : B / saveur : standard / arch : x86
• organisation : B / saveur : mini / arch : ar71xx
• organisation : B / saveur : mini / arch : x86

Les images seront créées dans le répertoire spécifié dans openwisp2fw_bin_dir.

5. Télécharger les images dans l'upgrader de firmware OpenWISP

La dernière étape consiste à télécharger les images dans le module Upgrader de firmware OpenWISP. Cette étape est facultative et désactivée par défaut.

Pour activer cette fonctionnalité, les variables openwisp2fw_uploader et openwisp2fw_organizations.categories doivent être configurées comme dans l'exemple ci-dessous :

- 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

Les espaces réservés suivants dans l'exemple devront être remplacés :

• <CATEGORY-UUID> est l'UUID de la catégorie de firmware dans l'Upgrader de firmware OpenWISP
• <REST-API-USER-TOKEN> est le jeton d'authentification REST d'un utilisateur ayant les permissions nécessaires pour télécharger des images

Vous pouvez récupérer le jeton d'authentification REST en envoyant une requête POST en utilisant l'interface API Web Browsable d'OpenWISP :

1. Ouvrez le navigateur à l'adresse https://<openwisp-base-url>/api/v1/user/token/.
2. Entrez le nom d'utilisateur et le mot de passe dans le formulaire en bas de la page.
3. Soumettez le formulaire et vous obtiendrez le jeton d'authentification REST dans la réponse.

Le script de téléchargement crée un nouvel objet de construction, puis télécharge les images de firmware spécifiées dans image_types, qui doivent correspondre aux identifiants comme ar71xx-generic-tl-wdr4300-v1-il-squashfs-sysupgrade.bin définis dans le fichier hardware.py de l'Upgrader de firmware OpenWISP.

Autres points importants à connaître sur le script upload_firmware.py :

• Le script lit CONFIG_VERSION_DIST et CONFIG_VERSION_NUMBER depuis le fichier .config du code source d'OpenWRT pour déterminer la version de construction.
• Le script déterminera si une construction de la même version et de la même catégorie existe déjà et essaiera d'ajouter des images à cette construction au lieu d'en créer une nouvelle ; si des doublons sont trouvés, un message d'échec sera imprimé sur la console, mais le script ne se terminera pas ; cela permet de générer des images pour de nouveaux modèles matériels et de les ajouter à des constructions existantes.

Ajouter des fichiers aux images

Vous pouvez ajouter des fichiers arbitraires dans chaque image générée en plaçant ces fichiers dans un répertoire nommé files/ dans votre répertoire de playbook.

Exemple :

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

files/etc/profile sera ajouté dans chaque image générée.

Ajouter des fichiers pour des organisations spécifiques

Vous pouvez également ajouter des fichiers aux images de certaines organisations.

Disons que vous avez une organisation appelée snakeoil et que vous souhaitez ajouter une bannière personnalisée, vous pouvez le faire en créant la structure de répertoire suivante :

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

Étant donné que cette étape est l'une des dernières effectuées avant la construction des images finales, vous pouvez utiliser cette fonctionnalité pour écraser tout fichier construit automatiquement lors des étapes précédentes.

Paramètres supplémentaires

Vous pouvez passer les paramètres supplémentaires suivants à ansible-playbook :

• recompile : si vous souhaitez répéter l'étape de compilation
• cores : nombre de cœurs à utiliser lors de l'étape de compilation
• orgs : liste séparée par des virgules des noms d'organisation si vous devez limiter la génération d'images à des organisations spécifiques

Exemples

Recompiler avec 16 cœurs :

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

Générer des images uniquement pour l'organisation foo :

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

Générer des images uniquement pour les organisations foo et bar :

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

Exécuter des étapes spécifiques

Étant donné que chaque étape du processus est taguée, vous pouvez exécuter des étapes spécifiques en utilisant des tags Ansible.

Exemple 1, exécuter uniquement la préparation des générateurs :

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

Exemple 2, exécuter uniquement la préparation des générateurs et les étapes de construction :

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

Cibles sans sous-cible

Cet exemple montre comment remplir openwisp2fw_source_targets afin de compiler des cibles qui ne précisent pas de sous-cible (ex : sunxi, ARMv8, QEMU) :

openwisp2fw_source_targets:
    # SOC Allwinner, Lamobo R1
    - system: sunxi
      profile: sun7i-a20-lamobo-r1
    # Image virtuelle ARM QEMU
    - system: armvirt
      profile: Default

Soutien

Voir Canaux de support OpenWISP.