maschinenraum

..weiter geht's. Teil I war ein Rundumschlag mit allgemeinen Geplänkel und jetzt wird es konkreter.

Wir schauen uns an wie die Firmware an. Ziel soll sein selbst etwas an der Firmware ändern zu können. Wenn man da keinen Bock drauf hat, kann man auch direkt Meshkit benutzen und bekommt eine fertige Firmware für seinen Router!

Los geht's!

ein paar Grundlagen

...ist vielleicht das falsche Wort dafür, aber es gibt ein paar Ideen und Konzepte die immer wieder auftauchen und in etwa zu wissen womit man da zu tun hat macht alles sehr viel einfacher.

• Linux - Da wir durchgehend Tools auf Linux nutzen, die Firmware auf Linux läuft und der ganze Code auf Linux aufbaut sind ein paar Kenntnisse nötig. Das minimale Level an Sachen, die man wissen muss gibt es in als Tutorial in 30 Lektionen bei "Learn Linux The Hard Way". Der Name ist etwas unglücklich, so "hard" ist es wirklich nicht. Es handelt sich nur um eine Einführung in wesentliche Konzepte, die einem immer und immer wieder und überall begegnen.
• TCP/IP - Was ist eine IP-Adresse und was ist DNS und solche Dinge.. muss man nicht alles wissen, aber es ist nützlich eine Idee davon zu haben. Ist ja schließlich ein Netzwerk. Es gibt viele Tutorials im Netz dazu. Hier ist ein recht ausführliches.
• Shell-Scripting - Ein großer Teil von OpenWRT und kalua besteht aus Shell-Scripten und diese sind teilweise ziemlich kryptisch. Hier ist ein ausführliches Tutorial. Tools wie sed, awk und Reguläre Ausdrücke sind nützlich und tauchen oft im Quellcode auf. Da das alles noch nicht kompliziert genug zu sein scheint, ist es so, dass die Shell auf OpenWRT eine ash von busybox ist. Diese ist nur zu POSIX kompatibel (kann aber auch ein paar Sachen darüber hinaus und manches auch nicht :/). Da die meisten Tutorials für die Bash-Shell geschrieben sind laufen Beispiele oft nicht mit der ash auf OpenWRT. Hier gibt es einen Überlick über die Unterschiede. Beim Googlen hilft es explizit nach "Posix Shell" zu suchen.
• make - das OpenWRT-Buildsystem nutzt Makefiles, ebenso wird der  Linux-Kernel damit compiliert und fast alle OpenWRT-Pakete. Make ist mit ein paar Beispielen am besten erklärt. Das OpenWRT-Buildsystem ist eher schwarze Magie, aber wenn man sadistisch veranlagt ist, dann kann man hier anfangen in die Abgründe hinabzusteigen.
• git - Eine verteilte Versionsverwaltung, die hier noch keine größere Rolle spielt, aber die Sourcen für die diversen Projekte sind auf github zu finden oder in eigenen git-Repositories. Es ist nützlich ein wenig mit den üblichen Begriffen vertraut zu sein um sich orientieren zu können. Auf git-scm.com gibt es Tutorials... hier brauchen wir erstmal nur git checkout und eine Idee davon was ein commit ist und was branches sind.

..und das wichtigste:

Learn to Read the Source, Luke

echt jetzt! Das Problem ist, dass es kaum oder keine Dokumentation gibt. Dieser Blogpost ist auch nur aus dem Frust heraus entstanden keine Informationen über die Funktionsweise der Weimarnetz-Firmware zu haben. Im Zweifel hilft es nur den Quellcode zu lesen.

Okay - jetzt geht es aber los:

Das Buildsystem (besser: die Buildsysteme)

Ziel ist es für einen Router ein Image mit der Weimarnetz-Firmware aus dem Quellcode zu bauen. Dafür folgen wir erstmal der Anleitung aus dem git-Repository vom Weimarnetz:

# login as non-root user
export REPONAME="weimarnetz"
export REPOURL="git://github.com/weimarnetz/weimarnetz.git"

git clone $REPOURL
mkdir myrelease; cd myrelease

DO="../$REPONAME/openwrt-build/build_release.sh"

# choose your router-model and build, for example:
# build all ar71xx based hardware images
# with barrier breaker 14.07 final
$DO "HARDWARE.ar71xx" ffweimar_standard \ 
     patch:901-minstrel-try-all-rates.patch \
     patch:luci-remove-freifunk-firewall.patch \
     patch:openwrt-remove-ppp-firewall-from-deps.patch \
     patch:openwrt-remove-wpad-mini-from-deps.patch \
     ffweimar_luci_standard hostapd vtunnoZlibnoSSL \ 
     i18n_german https owm shrink tc use_bb1407

Alles klar? Hier auch nicht..

export VAR= setzt eine Umgebungsvariable in der Shell - diese Variablen werden später vom Script build_release.sh genutzt um das Repository zu clonen.

Das Build-Script selbst wird noch in eine 2. Umgebungsvariable $DO gepackt und in der letzten Zeile wird das Buildscript mit vielen mysteriösen Optionen ausgeführt zu denen wir gleich noch kommen...

Ein Blick in das Build-Script erklärt vielleicht die langatmigen Ausführungen zu Shell-Scripten und Quellcode lesen am Anfang des Artikels: build-release.sh. Es stellt sich heraus, dass in diesem Script im wesentlichen nur die Repositories gecloned werden und einige Vorbereitende Konfigurationen unternommen werden und die eigentliche Magic in einem 2. Script passiert. Dieses Script heißt mybuild.sh und es wird in build-release.sh in Zeile 197 mit dem Argument make aufgerufen sowie - und das passiert automatisch den Argumenten, die wir weiter oben schon build_release.sh mitgegeben haben.

In mybuild.sh werden viele Funktionen definiert aber in Zeile 44 wird es interessant:

case "$ACTION" in
    "")
        show_help
        exit 1
    ;;
    make)
        ACTION="mymake"
    ;;
esac

Jetzt wird die Funktion mymake() aufgerufen... hier die nach besten unwissen kommentierte Version:

mymake()
{
        # Parameter der Funktion werden
        # in die Variable $option gepackt
	local option="$1" # e.g. V=99
        # Zähle die CPU Kerne 
        # und packe sie in die Variable $cpu_count
	local cpu_count="$( grep -c ^processor /proc/cpuinfo )"
        # lege ein paar Variablen an
	local t1 t2 date1 date2 hardware
	local filelist file

        # [... ein paar Zeilen gekürzt]

        # lösche alte Firmware Dateien
	filelist="$( get_firmware_filenames )"

	for file in $filelist; do {
		[ -e "bin/$( get_arch )/$file" ] &&
                 rm "bin/$( get_arch )/$file"
	} done

        # Optionen für make werden vorbereit: 
        # -j (Anzahl der Kerne die make nutzt) also z.B. -j4
        # und nach die mitgegeben Optionen - siehe weiter oben.
	option="-j$(( $cpu_count + 1 ))${option:+ }$option"	
	echo "executing: 'make $option'"

        # Hier passiert der eigentliche Build.. 
        # make von OpenWRT wird aufgerufen... 
        # Hier wird das Image gebaut!!!
	make $option || return 1

        # Es hat geklappt!
        [...
	echo "\"Jauchzet und frohlocket...\" \ 
         ob der Bytes die erschaffen wurden: \ 
         (revision: $( scripts/getver.sh ))" 

# [...]
}

Die Eigentliche Arbeit wird von OpenWRT geleistet. Wie feeds.conf und make menuconfig und .config Files funktionieren würde noch einen weiteren Blogpost füllen. Mit den Infos hier und dem OpenWRT-Wiki bekommt man das aber schnell heraus. Entweder durch Source lesen oder zum Treffen kommen :)

Jetzt kann man sich durch die Dokumentation auf der Weimarnetz github-Seite wühlen und herausbekommen wie man seine eigene Firmware ändert. Am besten erstmal auf dem Router testen.

Momentan gaukelt einem das Buildsystem auch noch vor man würde die lokal veränderten Dateien ins Image einbauen. Dem ist nicht so. Es wird ein Paket aus dem github-Sourcen gebaut über einen Package-Feed der den aktuellen Master-Branch nutzt.

Die Makefile für das Paket sieht so aus:

include $(TOPDIR)/rules.mk

PKG_NAME:=kalua
PKG_VERSION:=2014-09
PKG_RELEASE=$(PKG_SOURCE_VERSION)

PKG_SOURCE_PROTO:=git
PKG_SOURCE_URL:=git://github.com/weimarnetz/weimarnetz.git
PKG_SOURCE_SUBDIR:=$(PKG_NAME)-$(PKG_VERSION)
PKG_SOURCE_VERSION:=master
PKG_SOURCE:=$(PKG_NAME)-$(PKG_VERSION)-$(PKG_SOURCE_VERSION).tar.gz

include $(INCLUDE_DIR)/package.mk

define Package/kalua
  SECTION:=utils
  CATEGORY:=Utilities
  MAINTAINER:=Andreas Bräu <freifunk@andi95.de>
  TITLE:=Kalua extensions
  URL:=http://kalua.org/trac/wiki
endef


define Package/kalua/description
 Kalua extensions used in weimarnetz.
endef

define Package/kalua/compile
endef

define Package/kalua/install
	$(INSTALL_DIR) $(1)/etc
	$(INSTALL_BIN) $(PKG_INSTALL_DIR)/etc/kalua_* $(1)/etc/
	$(INSTALL_BIN) $(PKG_INSTALL_DIR)/etc/local* $(1)/etc/
	$(INSTALL_BIN) $(PKG_INSTALL_DIR)/etc/variables* $(1)/etc/
        [...gekürzt]
endef

$(eval $(call BuildPackage,kalua))

Dieses Paket wird über die feeds.conf (die im Build-System auch auftaucht, grep -r ist immer nützlich) eingebunden. Details über Package-Feeds findet man im OpenWRT-Wiki

Soweit erstmal... leider auch mehr eine Linkliste als ein Tutorial, aber mit den Infos sollte man erstmal reicht weit kommen. Am besten zum Treffen kommen oder die Mailingliste fragen.

Links und Tutorials

Es gibt noch weitere gute Tutorials. Bernd hat mich auf zwei gute Bücher mit freien Lizenzen aufmerksam gemacht, die Freifunk allgemein behandeln:

WLAN für alle – Freie Funknetze in der Praxis

Wireless Networking in the Developing World ist ein guter - wenn auch etwas älterer Einstieg.

Die Dokumentation (und der Quellcode) anderer Firmware-Versionen ist auch lesenswert und teilweise auf die Weimarnetz-Firmware übertragbar:

Freifunk Gluon Dokumentation
Meshkit Dokumentation

Have Phun!