twms Homepage - FlI4L OPT-Developer HOWTO (deutsch)

Es gibt fuer FlI4L 2.x aktuellere Dokumente auf http://www.fli4l.de. Siehe dort den Link 'Dev-Doku' unter 'Hilfe'. Da diese Informationen von einem der Entwickler von FlI4L stammt und deshalb hoffentlich aktuell bleiben wird, werde ich die Pflege dieser Seite einstellen. Sie wird bis auf weiteres aber online bleiben.

Ich habe sie jetzt doch nochmal ueberarbeitet. Die folgenden Information gelten nur noch fuer FlI4L 2.x, die Referenzen fuer 1.6.x habe ich entfernt, da die neue Version inzwischen stabil genug ist, so dass es keinen Grund gibt, noch 1.6.x einzusetzen.

Einleitung

Dieses Howto soll Leuten helfen, die gerne ein OPT-Paket fuer FlI4L schreiben wollen, aber keine Lust haben, dafuer alle Scripte und Sourcen durchzulesen.

Es ist definitiv nicht vollstaendig, denn auch ich habe keine Lust gehabt, seitenweise Scripte zu lesen. Ich beschreibe hier nur, was ich selbst fuer meine eigenen OPT-Pakete

Ich setze alles voraus, was in der Installationsanleitung zu FlI4L bereits beschrieben ist. Ohne diese verstanden zu haben, ist es ziemlich witzlos ein OPT-Paket schreiben zu wollen.

Es ist natuerlich kein Fehler sich die schon erwaehnten Scripte anzusehen. Die Scripte sind nicht besonders schwer zu verstehen, also keine Angst!

Im folgenden steht "Executable" fuer jegliche Art ausfuehrbare Dateien, also z.B. Shell-Scripte, Programme etc, jedoch steht "Script" nur fuer Shell Scripte, es kann dort also kein Programm eingesetzt werden.

Welche Art von Executables wird unterstuetzt?

Das Hauptproblem bei FlI4L ist die Platzbeschraenkung durch die Diskette. Aus diesem Grund sind einige Einschraenkungen zu beachten:

Wohin mit den Executables?

Executables, die nicht zu einem OPT-Paket gehoeren, die man aber trotzdem gerne auf der Diskette haben will, kann man nach 'opt/files/usr/local/mybin' kopieren.

Diese Dateien werden unabhaengig von Configurationseinstellungen immer nach '/usr/local/bin' auf dem Router kopiert. Executables, die zu einem OPT-Paket gehoeren, sollten nicht nach 'mybin' kopiert werden.

Normale Executables, die von anderen oder manuell aufgerufen werden, gehoeren nach 'opt/files/usr/local/bin' (-> '/usr/local/bin' auf dem Router).

Scripte, die beim Start des Routers aufgerufen werden sollen, gehoeren nach 'opt/etc/rc.d' (-> '/etc/rc.d' auf dem Router), sie sollten 'rcnnn.paketname' genannt werden, wobei nnn fuer eine beliebige Zahl steht, mit der man die Reihenfolge der Ausfuehrung festlegen kann, und paketname fuer den Namen des OPT-Pakets. Die Zahl kann auch weggelassen werden (Beispiele: 'rc650.dyndns', 'rc.dyndns').

Solche Scripte werden von '/etc/rc.local' automatisch aufgerufen. Den so gestarteten Executables stehen alle Einstellungen aus der FlI4L Configuration als Environment-Variablen zur Verfuegung (siehe Configuration).

Achtung: Diese Scripte duerfen keine 'exit' Statements enthalten, da sonst der Bootvorgang abgebrochen wird.

Scripte, die beim Aufbau einer Internet-Verbindung aufgerufen werden sollen, gehoeren nach 'opt/etc/ppp' (-> '/etc/ppp' auf dem Router) und muessen 'ip-up.paketname' heissen. Sie werden dann automatisch von '/etc/ppp/ip-up' aufgerufen.

Executables, die so aufgerufen werden, koennen nicht mehr auf die Environment-Variablen aus 'config.txt' zugreifen, um das zu ermoeglichen, muss man zu einem Trick greifen (siehe <a href="#config">Configuration</a>).

Achtung: Diese Scripte duerfen keine 'exit' Statements enthalten, da sonst keine weiteren ip-up Scripte mehr aufgerufen werden.

Im Gegensatz zu frueuheren Versionen bekommen sie die IP-Adresse nicht mehr als Parameter uebergeben. Dafuer gibt es jetzt eine Variable $local, die sie enthaelt.

Wohin mit sonstigen Dateien?

Fuer sonstige Dateien gilt der Linux-Standard, also z.B. Config-Dateien gehoeren nach 'opt/etc' (-> '/etc' auf dem Router). Meist ist es jedoch sinnvoller, diese Dateien dynamisch aus den Eintraegen der Configuration zu erzeugen

Wie bekomme ich meine Dateien auf die Diskette?

Im Unterverzeichnis 'opt' des FlI4L-Verzeichnisses befinden sich Textdateien, welche fuer alle OPT-Pakete eine Liste aller Dateien enthaelt, die von 'mkfloppy.sh/bat' bzw. 'mktgz.sh/bat' auf die Diskette kopiert werden. Dort muss man fuer ein neues OPT-Paket eine Datei mit folgendem Inhalt angelegt werden.

                      
#------------------------------------------
# optional dyndns, used if OPT_DYNDNS='yes'
#------------------------------------------
opt     dyndns          files/usr/local/bin/netcat
opt     dyndns          files/usr/local/bin/dyndns.sh
opt	dyndns		etc/rc.d/rc.dyndns

Jede Zeile beginnt mit "opt", gefolgt von einem Tabulator oder Leerzeichen. Dann kommt der Paketname in Kleinschrift, wieder gefolgt von einem Tabulator oder Leerzeichen. Am Schluss steht der Name der Datei, die kopiert werden soll. Zu beachten ist, dass die Pfade relativ zum opt-Verzeichnis sein muessen. Beim Wechsel von FlI4L 1.6.x auf 2.0 muss man darauf achten, dass viele der Verzeichnisse jetzt im Unterverzeichnis 'opt/files' liegen und nicht mehr direkt in 'opt'.

Obiges Beispiel bedeutet, dass drei Dateien auf die Diskette kopiert werden sollen, wenn in der FlI4L Configuration das OPT-Paket OPT_DYNDNS aktiviert wurde.

Wie bekomme ich meine Configuration in config.txt?

Seit Version 2.0 ist FlI4L modular aufgebaut, d.h. es gibt keine zentrale 'config.txt' Datei mehr sondern jedes OPT-Paket bringt seine eigene Config-Datei mit. Diese Datei muss den Namen des OPT-Pakets tragen und in das Verzeichnis 'config' im FlI4L-Verzeichnis kopiert werden.

                    
#-----------------------------------------
# Optional package: dyndns
#-----------------------------------------
OPT_DYNDNS='yes'
# if you have registered for a subdomain called 'mydomain.homeip.net'
# fill in the following two variables like this:
DYNDNS_SUBDOMAIN='mydomain'
DYNDNS_DYNDOMAIN='homeip.net'
DYNDNS_SECRET='encrypted username and password from userencode.pl'

Die Konvention ist, dass es immer ein OPT_PAKETNAME='yes' geben muss, damit das Installationsprogramm ein neues Paket erkennt. Weitere Variablen muessen mit dem Paketnamen, gefolgt von einem Unterstrich, anfangen. Alle Variablen muessen gross geschrieben werden. Diese Konvention muss unbedingt eingehalten werden, denn das Programm, das die Diskette erzeugt, loescht die Variablen aller nicht aktvierten Pakete bevor es die Configuration fuer die Diskette erzeugt.

Ebenfalls seit FlI4L 2.0 gibt es im Unterverzeichnis 'check' eine weitere Textdatei, mit deren Hilfe die Eintraege in der Config-Datei ueberprueft werden. Siehe die o.g. Developer Doku fuer Details.

Wie kann ein Executable auf seine Configuration zugreifen?

Startup Scripts

Executables, die in '/etc/rc.d' stehen und deren Name den prefix "rc." hat, werden von '/etc/rc.local' aufgerufen und bekommen alle Config-Variablen im Environment uebergeben, ein Shell-Script koennte also z.B. folgendes machen:

                  
#-----------------------------------------
# Config-Variable DYNDNS_SUBDOMAIN ausgeben
#-----------------------------------------
echo "Die Subdomain ist $DYNDNS_SUBDOMAIN."

Andere Executables

Andere Executables haben diesen Komfort nicht, sondern muessen sie sich aus einer Config-Datei zusammensuchen. Wie bereits oben erwaehnt, ist es jedoch nicht sehr sinnvoll, eine eigene Config-Datei statisch mit auf die Diskette packen zu lassen, denn dann muss der Anwender doch wieder mehr als eine Datei ('config.txt') editieren, um die Configuration anzupassen. Stattdessen kann man ein 'rc.meinpaket' nach '/etc/rc.d' packen, welches die benoetigten Variablen fuer anderweitig aufgerufene Programme sichert, z.B.

Je Wert eine Datei

                
#-----------------------------------------
# Config-Variablen DYNDNS_* merken
#-----------------------------------------
/usr/local/bin/colecho "Setting up dynamic hostname configuration ..." gn
echo $DYNDNS_SUBDOMAIN > /var/run/dyndns.subdomain
echo $DYNDNS_DYNDOMAIN > /var/run/dyndns.dyndomain
echo $DYNDNS_SECRET > /var/run/dyndns.secret

Dieses Script schreibt alle fuer OPT_DYNDNS wichtigen Config-Variablen in Dateien im Verzeichnis '/var/run', so dass sie spaeter einfach ausgelesen werden koennen, z.B.

              
#-----------------------------------------
# Config aus /var/run/dyndns.* auslesen
#-----------------------------------------
SUBDOMAIN=`cat /var/run/dyndns.subdomain`
DYNDOMAIN=`cat /var/run/dyndns.dyndomain`
SECRET=`cat /var/run/dyndns.secret`

Man beachte die "Backticks" um den cat-Befehl, der bewirkt, dass ein externes Programm gestartet wird und dessen Ausgabe der Variablen zugewiesen werden.

Eine Config-Datei fuer alle Werte

            
#-----------------------------------------
# Config-Variablen DYNDNS_* in config schreiben
#-----------------------------------------
/usr/local/bin/colecho "Setting up dynamic hostname configuration ..." gn
echo "SUBDOMAIN=$DYNDNS_SUBDOMAIN" > /etc/dyndns.conf
echo "DYNDOMAIN="$DYNDNS_DYNDOMAIN" >> /etc/dyndns.conf
echo "SECRET=$DYNDNS_SECRET" >> /etc/dyndns.conf

          
SUBDOMAIN=mydomain
DYNDOMAIN=homeip.net
SECRET=geheim

Um diese Datei auszulesen kann man sie z.B. einfach aufrufen, denn obiges sind kann die Shell als Zuweisungen zu Variablen verstehen:

        
#-----------------------------------------
# Config aus /etc/dyndns.conf auslesen
#-----------------------------------------
. /etc/dyndns.conf
echo Subdomain: $SUBDOMAIN

Man beachte den Punkt, der durch ein Leerzeichen getrennt vor dem Dateinamen steht. Er bewirkt, dass die Datei im selben Context wie das laufende Script ausgefuehrt wird und keine Subshell gestartet wird. Das ist wichtig, da sonst die Environment-Variablen nur in dieser Subshell zur Verfuegung stehen, nicht jedoch in der, welche das urspruengliche Script ausfuehrt.

Scripte dynamisch erzeugen

Eine dritte Moeglichkeit ist das dynamische Erzeugen von Scripten, wie ich das seit der Version 0.1.7 von opt_dyndns mache. Ich bin mir nicht sicher, ob das guter Stil ist, aber in diesem Fall hat es das Paket um einiges vereinfacht. Dabei nicht vergessen, am Ende das erzeugte Script auch ausfuehrbar zu machen mit

      
chmod 700 scriptname

Aufruf beim Shutdown (halt/reboot)

Seit FlI4L 2.0 ist es moeglich auch beim Herunterfahren Scripte ausfuehren zu lassen. Solche Scripte muessen 'rc0.*' heissen und im Verzeichnis 'opt/etc/rc0.d' (-> '/etc/rc0.d' auf dem Router) liegen.

Fuer FlI4L 1.6.x ist das nur moeglich, wenn man mein Paket OPT-OnShutdown installiert.

Zusaetzliche Webseiten auf dem Webserver

Ausser imonc gibt es noch die Moeglichkeit den Router per Webbrowser zu steuern bzw. den Zustand abzufragen. Man kann in das Hauptmenue auch eigene Webseiten einklinken, die dann im linken Frame aufgelistet werden. Dies geschieht einfach, indem man ein Script, dessen Name mit 'main_' beginnt und die Extension '.cgi' hat, in das Verzeichnis 'opt/files/usr/local/htdocs' (-> '/usr/local/htdocs' auf dem Router) legt. Dieses Script muss eine gueltige Webseite erzeugen. Das Verzeichnis enthaelt bereits einige andere Scripte die man als Beispiele nehmen kann.

Ablauf des Router Starts

Der Linux-Kernel wurde so modifiziert, dass er nicht wie ueblich das Programm 'init' startet, sondern '/etc/rc' aufruft. Dies ist ein Shell-Script, das alle notwendigen Initialisierungen vornimmt, Ramdisks anlegt und die Dateien aus 'opt.tgz' in diese Ramdisk entpackt. Dieses Script befindet sich im Root-Filesystem und kann nicht ohne weiters modifiziert werden. Zuletzt ruft diess Script '/etc/rc.local' auf.

Dieses Script befindet sich im Unterverzeichnis 'opt/etc' der FlI4L Installation, kann also ohne grossen Aufwand geaendert werden. (Was nicht heisst, dass man das unbedingt tun sollte, es ist sicherer eine 'rc.meinpaket' Datei in '/etc/rc.d' zu verwenden.) Es fuehrt nacheinander alle zu FlI4L gehoerenden Scripte in '/etc/rc.d' aus, d.h. die, die nicht mit 'rc.' beginnen. Diese Scripte initialisieren z.B. die Netzwerkkarte, pppoe, den DNS-Server etc. Zuletzt werden die mit 'rc.' beginnenden Scripte aufgerufen, welche zu OPT-Paketen gehoeren.

Aenderungen am Root-Filesystem

Fuer die ganz mutigen gibt es auch die Moeglichkeit, direkt das Root-Filesystem des Routers zu veraendern. Dies ist in der Regel nicht notwendig und man sollte wirklich wissen was man tut.

Im Unterverzeichnis 'src' der FlI4L Installation befindet sich eine Datei namens 'rootfs.gz' (ausgepackt 'rootfs.img'). Sie enthaelt das Root-Filesystem als gepackten Ramdisk-Inhalt. Es ist kein normales tar-gz-Archiv, sondern wirklich ein gueltiges ext2-Filesystem in einer Datei. Um es zu modifizieren benoetigt man ein Linux-System, in dem das loopback-Device aktiviert ist (wer schon jetzt nur noch Bahnhof versteht, sollte gar nicht erst weiterlesen).

Das Verzeichnis enthaelt auch zwei Shell-Scripte namens 'mount-rootfs.sh' und 'umount-rootfs.sh' sowie ein Unterverzeichnis 'rootfs'. Das erste dieser Scripte entpackt 'rootfs.gz' und mounted es nach 'rootfs'. Man kann dann Aenderungen vornehmen und mit dem zweiten Script das Root-Filesystem wieder einpacken. Es wird automatisch in eine neue Filesystem-Datei kopiert, komprimiert und in's 'img' Unterverzeichnis der FlI4L Installation kopiert, wo es dann beim naechsten Erstellen einer Bootdiskette automatisch verwendet wird.

Um es nochmal klipp und klar zu sagen: Wenn man am Root-Filesystem rumbastelt, sollte man wirklich wissen, was man tut. Man kann sich mit solchen Aenderungen seine FlI4L-Installation so zerschiessen, dass sie nicht einmal mehr bootfaehige Disketten erzeugt. Anders als bei Fehlern in den Config-Dateien genuegt es dann nicht, die entsprechende Option auszuschalten und eine neue Diskette zu erstellen.

Das Verzeichnis 'src' enthaelt auch eine 'README' Datei, die man sich zu Gemuete fuehren sollte. Als Beispiel fuer ein Feature, fuer das man das Root-Filesystem veraendern muss, siehe auch mein SCSI-Boot-HOWTO auf http://www.fli4l.de/english/howtos.htm oder meiner Homepage http://www.s2h.cx.

The worst part of programming

Ja, es geht um die Dokumentation. Das raffinierteste OPT-Paket ist voellig unbrauchbar, wenn es keine oder nur eine schlechte Anleitung enthaelt. Bitte nehmt Euch die Zeit auch fuer Linux-Laien verstaendlich zu erklaeren, wie man das Paket verwendet. Eine schlechte Anleitung hat zur Folge, dass Euch die Leute staendig per E-Mail fragen (ich spreche da aus Erfahrung). Wenn Ihr keine Zeit/Lust habt, eine Anleitung zu schreiben, dann fragt vielleicht mal in der Mailing-Liste nach, ob sich jemand bereit erklaert, dies zu uebernehmen. (Nicht, dass ich wirklich glaube, dass das jemand tut.)

Ganz toll waere es, wenn es nicht nur eine deutsche sondern auch eine englische Anleitung gaebe, denn der Anwenderkreis von FlI4L beschraenkt sich inzwischen nicht mehr nur auf den deutschsprachigen Raum. "Mein Englisch ist so schlecht, das versteht doch sowieso keiner." ist zwar ein verstaendlicher Standpunkt, aber jemand, der kein Deutsch kann, wird fuer noch so schlechtes Englisch dankbar sein. Ausserdem ist auch das Englisch der anderen nicht perfekt. Auch hier finden sich in der Mailing-Liste vielleicht Leute, die helfen oder korrekturlesen.

Kleiner Hinweis am Rande: Es gibt ein Tool namens aft (almost free text), welches aus einem normalen Text mit ein paar wenigen Formatierungsangaben ein HTML-Dokument wie dieses erzeugt. Ich kann es sehr empfehlen. Zu bekommen ist es auf http://www.maplefish.com/todd/aft.html.

Rechtliches

Eine Sache, die ich bisher selbst straeflich vernachlaessigt habe, ist der rechtliche Aspekt.

Lizenzen anderer Programme

Wenn in einem OPT-Paket Programme Dritter verwendet werden, so muss unbedingt deren Lizenz geprueft werden,

Lizenz des OPT-Pakets

Und dann gibt es natuerlich noch die Lizenz des OPT-Paketes selbst. Man sollte sich hier nicht einfach auf den Standpunkt stellen, dass es einem voellig wurscht ist, was mit dem Paket passiert, denn es koennte irgendwann jemand kommen und von einem Schadenersatz fordern wollen (auch wenn er sich noch so bloed angestellt hat, so gibt es in Deutschland gewisse Rechte).

In diesem Fall waere z.B. die GPL eine Lizenz, mit der man zumindest theoretisch aus dem Schneider ist, da sie explizit jegliche Haftung ausschliesst. ("theoretisch" deshalb, weil meines Wissens bisher noch niemand versucht hat, gegen diese Klausel zu klagen, so dass ich mir nicht so sicher bin, ob sie insbesondere in Deutschland rechtsgueltig ist. Ein weiteres Problem ist, dass die GPL in Englisch vorliegt und aus rechtlichen Gruenden nur im Original und nicht als Uebersetzung gilt. Auch das koennte in Deutschland im Falle eines Falles zu Problemen fuehren.)

Wichtig: Bitte immer die GPL im englischen Original verwenden, da die Uebersetzungen nicht rechtlich geprueft wurden. Es koennte sein, dass durch einen Uebersetzungsfehler Teile ungueltig sind.

Wohin mit dem OPT-Paket?

Ok, das Paket ist fertig, Du hast es getestet und willst es jetzt gerne auch anderen FlI4L-Usern zur Verfuegung stellen.

Du koenntest es jetzt natuerlich auf Deine Homepage legen und in der Mailing-Liste bekanntgeben, dass es existiert (wenn, dann bitte mit einer aussagekraeftigen Beschreibung). Das hilft erstmal allen, die diese Mail auch lesen, und den wenigen, die auch spaeter das Mailing-List-Archiv durchsehen. Aber es wird schnell in Vergessenheit geraten und damit ist der Zweck verfehlt.

Es ist sinnvoll, es auch ueber www.fli4l.de anzubieten, so dass es eine zentrale Stelle gibt, wo man OPT-Pakete finden kann. Carsten Cerny (webmaster at fli4l.de), der die Seite pflegt, nimmt solche Pakete gerne entgegen.

Er setzt auch einen Link auf Deine Homepage, wenn Du unbedingt Leute dorthin locken willst. ;-)

Ich habe eine Ergaenzung zu diesem Howto, wohin schicke ich sie?

Na, an mich, Thomas Mueller (fli4l at s2h.cx). Unter derselben Adresse nehme ich auch Bugreports entgegen. Dies gilt uebrigens fuer inhaltliche Fehler genauso wie fuer Rechtschreibfehler (Dieses Dokument sollte der neuen deutschen Rechtschreibung entsprechen.).

Dieses Howto ist so schlecht, ich muss mich gleich uebergeben

Ich habe das dringende Beduerfnis, jemandem Geld zu geben, weil dieses Howto so toll ist. Was mache ich?

Wende Dich vertrauensvoll an die Macher von FlI4L, ich selbst bin reich genug. ;-)