Freifunk Fulda/Firmware

Die Firmware für Freifunk Fulda basiert auf Gluon. Dabei wird Gluon durch eigene Pakete erweitert und mit einer eigenen Konfiguration versehen.

Quellen und Versionskontrolle

Die Software und die Konfiguration auf GitHub/Freifunk Fulda verwaltet und besteht aus folgenden Repositories:

Konfiguration

Die für Freifunk Fulda erstellte Konfiguration.

Dies ist auch der Einstiegspunkt für die Entwicklung und das Erzeugen der Firmware-Images.

Pakete

Für Freifunk Fulda spezifische Pakete, die Teil der fertigen Firmware-Images werden.

Das Repository und die jeweiligen Pakete werden in der Konfiguration angegeben.

In jedem der Repositories gibt es mindestens die Branches stable, testing und development:

stable

Dieser Code ist zur allgemeinen Verwendung gedacht und soll stabil laufen.

testing

Diese Firmware sind release candidates für das nächste stable Release. Änderungen werden nur für Bug fixes ausgeführt. Die Firmware wenn sie installiert wird sollte lauffähig sein.

development

Aktueller Stand der Entwicklung. Hier werden neue Funktionen ausprobiert und Tests durchgeführt. Es ist nicht sicher gestellt, dass die Firmware auf jeden Fall funktioniert und ist bleeding edge.

Wenn die Firmware in den development Branches eine gewisse Reife erreicht hat und für stabil empfunden wird, wird die aktuelle Version nach testing übernommen. Diese <testing> Firmware sollte von versierten Benutzern verwendet und getestet werden und letzte Fehler behoben. Anschliessend wird das Release von <testing> nach <stable> verschoben und wird entsprechend ausgerollt.

Erstellen eines Firmware-Images

Zuerst muss der Branch ausgewählt werden, aus dem das Firmware-Image erstellt werden soll:

MY_BRANCH=stable # oder auch development

Nun kann das Projekt geklont werden:

git clone https://github.com/freifunk-fulda/site-fffd.git --branch ${MY_BRANCH} --recurse-submodules && cd site-fffd

Zum Bauen des Images können folgende Befehle verwendet werden:

./build.sh -d -b "${GIT_BRANCH}" -c update -n "${BUILD_NUMBER}-${BUILD_DATE}" -w "${WORKSPACE}" -m "V=s"
./build.sh -d -b "${GIT_BRANCH}" -c download -n "${BUILD_NUMBER}-${BUILD_DATE}" -w "${WORKSPACE}" -m "V=s"
./build.sh -d -b "${GIT_BRANCH}" -c build -n "${BUILD_NUMBER}-${BUILD_DATE}" -w "${WORKSPACE}"

Die Images liegen nun unterhalb des Ordners images. In dem Unterordner factory befinden sich volle Image-Dateien, die zum Flashen einer Node verwendet werden können. Der Unterordner sysupgrade beinhaltet Dateien, die für den Update-Prozess benötigt werden.

Automatische Updates

Gluon erlaubt die Verteilung und Installation Updates.

Erzeugen des Manifests

Das Manifest beinhaltet eine Liste der Firmware-Images für die unterstützte Hardware sowie jeweils die Version, die Checksumme und den Dateinamen. Die Manifest-Datei muss im Ordner sysupgrade gespeichert werden und wird von den Nodes verwendet um Updates zu finden.

Signieren des Manifests

Das Manifest-File kann durch die Entwickler signiert werden. Die Signatur wird durch die Nodes geprüft - welche Schlüssel gültig sind und wie viele gültige Signaturen benötigt werden wird in der Konfiguration festgelegt.

Ein existierendes Manifest kann mit folgendem Befehl signiert werden:

./build.sh -d -b "${GIT_BRANCH}" -c sign -n "${BUILD_NUMBER}-${BUILD_DATE}" -w "${WORKSPACE}"

Der Befehl kann mit unterschiedlichen Schlüsseln wiederholt werden um jeweils eine Signatur anzuhängen.

Da die Nodes das Manifest in der Datei manifest erwarten, muss die Datei noch umbenannt werden:

mv images/sysupgrade/${MY_BRANCH}.manifest images/sysupgrade/manifest

Veröffentlichen der Updates

Die Firmware-Images (alle Dateien im Ordner images müssen auf den Update-Server kopiert werden. Der Zielordner wird dabei nach folgendem Muster benannt:

${MY_BRANCH}/${BUILD_NR}-${BUILD_DATE}

Wobei ${BUILD_NR} eine fortlaufende Nummer ist und ${BUILD_DATE} das Datum im Format YYYYMMDD.

Anschließend muss ein Symlink vom Zielordner zum Ordner ${MY_BRANCH}/current erstellt werden.

Zum hochladen des Images kann folgender Befehl verwendet werden:

./build.sh -d -b "${GIT_BRANCH}" -c upload -n "${BUILD_NUMBER}-${BUILD_DATE}" -w "${WORKSPACE}"

Firmware Tests

Das Bauen und Bereitstellen von Firmware ist ein aufwändiges und komplexes Unterfangen. Da die Firmware maßgeblich für den problemfreien Betrieb unserer Infrastruktur verantworlich ist, sollte sie vor einem endgültigen Release ausgiebig getestet werden.