ansible-openwisp2-imagegenerator

Diese Ansible-Rolle ermöglicht es, mehrere OpenWISP2-Firmware-Images für verschiedene Organisationen zu erstellen und deren Konfigurationen im Blick zu behalten.

HINWEIS: Diese Rolle wurde bisher noch nicht in der Praxis getestet. Wenn Sie vorhaben, sie zu nutzen, probieren Sie sie aus, und wenn etwas schiefgeht, melden Sie bitte Ihr Problem. Denken Sie daran, dass Sie bereit sein sollten, den Build-Prozess und dessen Funktionsweise zu verstehen, um ihn für sich nutzbar zu machen.

Erforderliche Rollenvariablen

Die folgenden Variablen sind erforderlich:

• openwisp2fw_source_dir: zeigt das Verzeichnis des OpenWRT Sources an, das während der Kompilation verwendet wird
• openwisp2fw_generator_dir: zeigt das Verzeichnis an, das für die Vorbereitung der Generatoren verwendet wird
• openwisp2fw_bin_dir: zeigt das Verzeichnis an, das beim Erstellen der finalen Images verwendet wird
• openwisp2fw_organizations: eine Liste von Organisationen; siehe die Beispieldatei playbook.yml im Abschnitt Playbook erstellen, um die Struktur zu verstehen

Verwendung (Tutorial)

Wenn Sie nicht wissen, wie man Ansible verwendet, machen Sie sich keine Sorgen, dieses Verfahren wird Sie Schritt für Schritt anleiten.

Wenn Sie bereits wissen, wie man Ansible verwendet, können Sie diesen Abschnitt überspringen und direkt zum Abschnitt „Diese Rolle installieren“ gehen.

Zuerst müssen Sie zwei Schlüsselkonzepte verstehen:

• Mit „Kompilierungsserver“ meinen wir einen Server, der zum Kompilieren der Images verwendet wird
• Mit „lokalem Rechner“ meinen wir den Host, von dem aus Sie Ansible ausführen, z.B.: Ihr eigenes Laptop oder CI-Server

Ansible ist ein Konfigurationsmanagement-/Automatisierungstool, das über SSH auf den Kompilierungsserver zugreift und eine Reihe von Befehlen ausführt.

1. Ansible installieren

Installieren Sie Ansible auf Ihrem lokalen Rechner, falls Sie dies noch nicht getan haben. Es gibt verschiedene Möglichkeiten, dies zu tun, aber wir bevorzugen die Verwendung des offiziellen Python-Paketmanagers, z.B.:

sudo pip install ansible

Wenn Sie pip nicht installiert haben, sehen Sie sich Installing pip auf der pip-Dokumentations-Website an.

Ansible auf andere Weise installieren ist ebenfalls in Ordnung, stellen Sie jedoch sicher, dass Sie eine Version der Serie 2.0.x installieren (das ist die Version, mit der wir dieses Playbook getestet haben).

2. Diese Rolle installieren

Um es einfach zu halten, ist es am besten, diese Rolle auf Ihrem lokalen Rechner über ansible-galaxy zu installieren (was während der Installation von Ansible installiert wurde). Führen Sie daher Folgendes aus:

sudo ansible-galaxy install openwisp.openwisp2-imagegenerator

3. Ein Arbeitsverzeichnis wählen

Wählen Sie ein Arbeitsverzeichnis auf Ihrem lokalen Rechner, in dem Sie die Konfiguration Ihrer Firmware-Images ablegen.

Zum Beispiel:

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

Es ist auch eine sehr gute Idee, dieses Arbeitsverzeichnis unter Versionskontrolle zu stellen. Es hilft Ihnen, Änderungen nachzuverfolgen, zurückzusetzen, einen CI-Server einzurichten, der die Images automatisch für Sie erstellt usw.

4. Inventar-Datei erstellen

Die Inventar-Datei ist der Ort, an dem Gruppen von Servern definiert sind. In unserem einfachen Fall können wir mit der Definition einer Gruppe auskommen, in der wir nur einen Server unterbringen.

Erstellen Sie eine neue Datei hosts auf Ihrem lokalen Rechner mit folgendem Inhalt:

[myserver]
mycompiler.mydomain.com ansible_user=<IhrBenutzer> ansible_become_pass=<sudo-passwort>

Ersetzen Sie mycompiler.mydomain.com durch Ihren Hostnamen (IP-Adressen sind ebenfalls zulässig).

Setzen Sie auch Ihren SSH-Benutzer und Ihr Passwort anstelle von <IhrBenutzer> und <sudo-passwort> (muss sudoer und kein Root sein). Diese Anmeldeinformationen werden während des Schrittes zur Installation der Abhängigkeiten verwendet.

5. Playbook-Datei erstellen

Erstellen Sie eine neue Playbook-Datei playbook.yml auf Ihrem lokalen Rechner mit folgendem Inhalt:

# 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 # Name der Organisation
          flavours: # Unterstützte Geschmäcker
            - standard
          luci_openwisp: # /etc/config/luci_openwisp
            # Weitere Konfigurationsschlüssel können beliebig hinzugefügt werden
            username: "operator"
            # Klartext-Passwort, das in /etc/config/luci_openwisp verschlüsselt wird
            password: "<ÄNDERN>"
          openwisp: # /etc/config/openwisp
            # Weitere Konfigurationsschlüssel können beliebig hinzugefügt werden
            url: "https://meine-openwisp2-instanz.com"
            shared_secret: "mein-openwisp2-geheimnis"
            unmanaged: "{{ openwisp2fw_default_unmanaged }}"
          # Klartext-Passwort, das in /etc/shadow verschlüsselt wird
          root_password: "<ÄNDERN>"

Dieses Playbook ermöglicht Ihnen das Kompilieren von Firmware-Images für eine Organisation namens snakeoil, die nur den standard-Geschmack (der ein Standard-OpenWRT 19.07-Image mit den Standardmodulen von OpenWISP2 enthält) für zwei Architekturen, ar71xx und x86, umfasst.

Siehe den Abschnitt Rollenvvariablen, um zu erfahren, wie Sie die verfügbaren Konfigurationen anpassen können.

An diesem Punkt sollte Ihre Verzeichnisstruktur folgendermaßen aussehen:

.
├── hosts
└── playbook.yml

6. Das Playbook ausführen

Jetzt ist es an der Zeit, die Kompilierung von OpenWISP2-Firmware zu starten.

Starten Sie das Playbook von Ihrem lokalen Rechner mit:

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

Sie können cores=4 durch die Anzahl der verfügbaren Kerne ersetzen.

Wenn das Playbook ausgeführt wurde, finden Sie die Images auf dem Kompilierungsserver im Verzeichnis, das in openwisp2fw_bin_dir angegeben ist, das in unserem Beispiel /home/user/openwisp2-firmware-builds ist, mit einer Verzeichnisstruktur wie folgt:

/home/user/openwisp2-firmware-builds
├── snakeoil/                                      # (jede Organisation hat ihr eigenes Verzeichnis)
├── snakeoil/2016-12-02-094316/ar71xx/standard/    # (enthält ar71xx-Images für den Standardgeschmack)
├── snakeoil/2016-12-02-094316/x86/standard/       # (enthält x86-Images für den Standardgeschmack)
└── snakeoil/latest/                               # (latest ist ein symbolischer Link zur letzten Kompilierung)

Wenn Sie diesem Tutorial gefolgt sind und alles geklappt hat, sind Sie bereit, Ihre Konfiguration nach Ihren Bedürfnissen anzupassen! Lesen Sie weiter, um zu erfahren, wie Sie dies erreichen können.

Rollenvvariablen

Es gibt viele Variablen, die bei Bedarf angepasst werden können. Werfen Sie einen Blick auf die Standardwerte für eine umfassende Liste.

Einige dieser Variablen werden auch in Organisationen und Geschmäckern erläutert.

Organisationen

Wenn Sie mit OpenWISP arbeiten, besteht die Möglichkeit, dass Sie Images für verschiedene Gruppen von Personen kompilieren: gewinnorientierte Kunden, gemeinnützige Organisationen oder jede Gruppe von Personen, die als „Organisation“ definiert werden kann.

Organisationen können frei in openwisp2fw_organizations definiert werden.

Für ein Beispiel, wie das geht, siehe die "Beispiel-Playbook.yml-Datei".

Wenn Sie spezifische Dateien im Dateisystembaum der Images jeder Organisation hinzufügen müssen, sehen Sie sich "Dateien für bestimmte Organisationen hinzufügen" an.

Geschmäcker

Ein Geschmack ist eine Kombination von Paketen, die in einem Image enthalten sind.

Sie möchten vielleicht verschiedene Geschmäcker für Ihre Images erstellen, zum Beispiel:

• standard: der häufigste Anwendungsfall
• minimal: ein Image für Geräte, die wenig Speicherplatz zur Verfügung haben
• mesh: ein Image mit Paketen, die benötigt werden, um ein Mesh-Netzwerk zu implementieren

Standardmäßig ist nur ein standard-Geschmack verfügbar.

Sie können Ihre eigenen Geschmäcker definieren, indem Sie openwisp2fw_image_flavours festlegen – schauen Sie sich die Standardvariablen an, um deren Struktur zu verstehen.

Build-Prozess

Der Build-Prozess setzt sich aus den folgenden Schritten zusammen.

1. Installation der Abhängigkeiten

Tag: install

In dieser Phase werden die Betriebssystemabhängigkeiten, die für die nachfolgenden Schritte benötigt werden, installiert oder aktualisiert.

2. Kompilierung

Tag: compile

Der OpenWRT-Sourcode wird kompiliert, um etwas zu produzieren, das "Image Generator" genannt wird. Der Image Generator ist ein Archiv, das die vorcompilierten Pakete und ein spezielles Makefile enthält, das zur Erstellung der angepassten Images für jede Organisation verwendet wird.

Der Source wird im Verzeichnis, das in openwisp2fw_source_dir angegeben ist, heruntergeladen und kompiliert.

3. Vorbereitung der Generatoren

Tag: generator

Während dieses Schrittes werden die Image-Generatoren extrahiert und vorbereitet, um verschiedene Images für verschiedene Organisationen zu erstellen. Jede Organisation kann Images für verschiedene Geschmäcker erstellen (z.B.: voll funktionsfähig, minimal, mesh usw.);

Die Images werden in dem Verzeichnis vorbereitet, das in openwisp2fw_generator_dir angegeben ist.

4. Erstellung der finalen Images

Tag: build

In dieser Phase wird eine Reihe von Images erstellt.

Für jede Architektur, Organisation und Geschmack werden mehrere Images erstellt. Dies kann eine Menge Dateien erzeugen, verwenden Sie diese Macht daher mit Bedacht: Es ist wahrscheinlich besser, mit weniger Optionen zu beginnen und im Laufe der Zeit mehr Fälle hinzuzufügen.

Wenn Sie beispielsweise beschließen, 2 Architekturen (ar71xx und x86), 2 Organisationen (z.B.: A und B) und 2 Geschmäcker (z.B.: standard und mini) zu verwenden, erhalten Sie 8 Gruppen von Images:

• Organisation: A / Geschmack: standard / Architektur: ar71xx
• Organisation: A / Geschmack: standard / Architektur: x86
• Organisation: A / Geschmack: mini / Architektur: ar71xx
• Organisation: A / Geschmack: mini / Architektur: x86
• Organisation: B / Geschmack: standard / Architektur: ar71xx
• Organisation: B / Geschmack: standard / Architektur: x86
• Organisation: B / Geschmack: mini / Architektur: ar71xx
• Organisation: B / Geschmack: mini / Architektur: x86

Die Images werden im Verzeichnis erstellt, das in openwisp2fw_bin_dir angegeben ist.

5. Hochladen der Images zum OpenWISP Firmware Upgrader

Der letzte Schritt besteht darin, die Images in das OpenWISP Firmware Upgrader-Modul hochzuladen. Dieser Schritt ist optional und standardmäßig deaktiviert.

Um diese Funktion zu aktivieren, müssen die Variablen openwisp2fw_uploader und openwisp2fw_organizations.categories wie im folgenden Beispiel konfiguriert werden:

- hosts:
    - myhost
  roles:
    - openwisp.openwisp2-imagegenerator
  vars:
    openwisp2fw_controller_url: "https://openwisp.meinprojekt.com"
    openwisp2fw_organizations:
      - name: staging
        flavours:
          - default
        openwisp:
          url: "{{ openwisp2fw_controller_url }}"
          shared_secret: "xxxxx"
        root_password: "xxxxx"
        categories:
          default: <KATEGORIE-UUID>
      - name: prod
        flavours:
          - default
        openwisp:
          url: "{{ openwisp2fw_controller_url }}"
          shared_secret: "xxxxx"
        root_password: "xxxxx"
        categories:
          default: <KATEGORIE-UUID>
    openwisp2fw_uploader:
        enabled: true
        url: "{{ openwisp2fw_controller_url }}"
        token: "<REST-API-BENUTZER-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

Die folgenden Platzhalter im Beispiel müssen ersetzt werden:

• <KATEGORIE-UUID> ist die UUID der Firmware-Kategorie im OpenWISP Firmware Upgrader
• <REST-API-BENUTZER-TOKEN> ist das REST-Auth-Token eines Benutzers mit Berechtigungen zum Hochladen von Images

Sie können das REST-Auth-Token erhalten, indem Sie einen POST-Antrag über die durchsuchbare API-Weboberfläche von OpenWISP senden:

1. Öffnen Sie den Browser unter https://<openwisp-basis-url>/api/v1/user/token/.
2. Geben Sie Benutzername und Passwort im Formular am Ende der Seite ein.
3. Reichen Sie das Formular ein, und Sie erhalten das REST-Auth-Token in der Antwort.

Das Upload-Skript erstellt ein neues Build-Objekt und lädt dann die Firmware-Images hoch, die in image_types angegeben sind und die mit den Identifikatoren wie ar71xx-generic-tl-wdr4300-v1-il-squashfs-sysupgrade.bin im hardware.py-Dokument von OpenWISP Firmware Upgrader definiert sind.

Weitere wichtige Punkte, die Sie über das upload_firmware.py-Skript wissen sollten:

• Das Skript liest CONFIG_VERSION_DIST und CONFIG_VERSION_NUMBER aus der .config-Datei des OpenWRT-Source-Codes, um die Build-Version zu bestimmen.
• Das Skript findet heraus, ob bereits ein Build mit derselben Version und Kategorie existiert und versucht, Images zu diesem Build hinzuzufügen, anstatt ein neues zu erstellen. Wenn Duplikate gefunden werden, wird eine Fehlermeldung auf der Konsole angezeigt, aber das Skript wird nicht beendet; dies ermöglicht die Erstellung von Images für neue Hardwaremodelle und deren Hinzufügung zu bestehenden Builds.

Dateien zu Images hinzufügen

Sie können beliebige Dateien in jedes generierte Image hinzufügen, indem Sie diese Dateien in ein Verzeichnis namens files/ in Ihrem Playbook-Verzeichnis legen.

Beispiel:

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

files/etc/profile wird in jedem generierten Image hinzugefügt.

Dateien für spezifische Organisationen hinzufügen

Sie können auch Dateien zu den Images spezifischer Organisationen hinzufügen.

Angenommen, Sie haben eine Organisation namens snakeoil, und Sie möchten ein benutzerdefiniertes Banner hinzufügen, können Sie dies erreichen, indem Sie die folgende Verzeichnisstruktur erstellen:

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

Da dieser Schritt einer der letzten Schritte ist, die vor dem Erstellen der finalen Images ausgeführt werden, können Sie diese Funktion verwenden, um jede Datei zu überschreiben, die automatisch in den vorherigen Schritten erstellt wurde.

Zusätzliche Parameter

Sie können die folgenden zusätzlichen Parameter an ansible-playbook übergeben:

• recompile: ob der Kompilierungsschritt wiederholt werden soll
• cores: Anzahl der Kerne, die während des Kompilierungsschrittes verwendet werden sollen
• orgs: durch Kommas getrennte Liste von Organisationsnamen, falls Sie die Generierung der Images auf bestimmte Organisationen beschränken möchten

Beispiele

Kompilierung wiederholen mit 16 Kernen:

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

Generieren von Images nur für die Organisation foo:

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

Generieren von Images nur für die Organisationen foo und bar:

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

Bestimmte Schritte ausführen

Da jeder Schritt im Prozess mit Tags versehen ist, können Sie bestimmte Schritte ausführen, indem Sie Ansible-Tags verwenden.

Beispiel 1, nur die Vorbereitung der Generatoren ausführen:

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

Beispiel 2, nur die Vorbereitung der Generatoren und Build-Schritte ausführen:

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

Ziele ohne Subtarget

Dieses Beispiel zeigt, wie Sie openwisp2fw_source_targets ausfüllen, um Targets zu kompilieren, die kein Subtarget angeben (z.B.: sunxi, ARMv8, QEMU):

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

Unterstützung

Siehe OpenWISP Unterstützungs-Kanäle.