Erstellen einer GUI für Pakete in Freetz¶
Motivation¶
Ein großer Faktor für den Erfolg von Freetz ist die Tatsache, dass die
Pakete dort über eine GUI zu konfigurieren sind. Über den Aufbau und die
Vorgehensweise zur Erstellen einer solchen GUI soll es in diesem Beitrag
gehen. Als Grundlage nehmen wir ein virtuelles Paket mit Namen "hugo"
an, um einen Bezug zu haben
Grundlagen¶
Bevor man sich Gedanken über die GUI machen kann, sind ein paar
grundlegende Dinge über die Art und Weise zu sagen, wie in Freetz Pakete
funktionieren. Als grundlegende Information sei auf die Doku
von
Daniel
verwiesen, hier soll das ganze nur kurz wiedergegeben werden (ich hoffe
das "fast wortwörtliche direkte Kopieren" aus dem Thread von Daniel
ist mir hier erlaubt):
Eigene Pakete¶
An ein Paket stellen sich folgende Anforderungen:
- rc Skript:
etc/init.d/rc.<paketname> [start|stop|load|unload|restart|status]
Wenn konfigurierbar:
- Default Konfiguration:
etc/default.<paketname>/<paketname>.cfg - Optional: cgi Skript für die Weboberfläche:
usr/lib/cgi-bin/<paketname>.cgi - Optional: Extra cgi Skripte in
usr/lib/cgi-bin/<paketname>/
Sonstige Default Dateien sollten auch ins Verzeichnis
etc/default.\<paketname>/ gepackt werden.
/mod/etc/init.d/rc.<paketname>/mod/etc/default.<paketname>/*/mod/usr/lib/cgi-bin/<paketname>.cgi/mod/usr/lib/cgi-bin/<paketname>/*
sind immer gültig (sofern im Paket enthalten) und werden bei statischen
Paketen über Symlinks realisiert. Binaries sollten nach bin, sbin,
usr/bin oder usr/sbin, damit sie sowohl in statischen als auch
dynamischen Paketen aufrufbar sind (die PATH Variable enthält auch
/mod/bin, /mod/sbin, /mod/usr/bin und /mod/usr/sbin). Libraries
funktionieren mit statischen wie auch dynamischen Paketen in lib
(LD_LIBRARY_PATH=/mod/lib ⇒ Library wird in /lib und /mod/lib
gesucht)
Benötigt ein Daemon eines Paketes eine Konfigurationsdatei (z.B.
hugo.conf), die für diesen Daemon spezifisch ist, so wird sie in der
Regel im rc Skript vor dem Starten des Daemons erzeugt. Ich habe dafür
folgende Konvention gewählt (ist aber kein muss), welche am Beispiel der
bftpd.conf erläutert ist:
- Suche nach Skript
/tmp/flash/hugo_conf, welches diehugo.conf
als Ausgabe hat; existiert? → goto 3. - Führe Skript
/etc/default.hugo/hugo_confaus, die Ausgabe ergibt
wie bei 1. diehugo.conf(meistens ist dies der Fall) - Existiert
/tmp/flash/hugo.conf.extra? → füge sie an die in 1.
oder 2. generiertehugo.confan
Das sollte alle Möglichkeiten des "Feintunings" offen lassen. 3. macht
nicht immer Sinn, darum ist es optional. Wäre schön, wenn jeder, der ein
Paket erstellt, die Konventionen einhält. Das Skript hugo_conf muss
stets mit exportierten Variablen aus /mod/etc/conf/hugo.cfg aufgerufen
werden. So wird die hugo.conf je nach Paket-Konfiguration individuell
erstellt.
Konfiguration¶
Jedes Paket besitzt ein Konfigurationsdatei
/mod/etc/conf/<paketname>.cfg, welche wie folgt aufgebaut ist:
Sie enthält alle Optionen, die auch übers Webinterface eingestellt
werden können und ist in Shell Syntax. Damit kann die aktuelle
Konfiguration mit
eingelesen werden. In der Datei
/mod/etc/default.<paketname>/<paketname>.cfg sind die default
Einstellungen gespeichert. Beim Speichern werden nur die sich von den
Defaults unterscheidenden Variablen in die /tmp/flash/<paketname>.diff
transferiert und mit dem ganzen Verzeichnis /tmp/flash/ ins tffs
abgelegt. Die Basis-Konfiguration hat den Paketnamen 'mod'. Die
Befehle dazu sind:
modconf load <paketname>
# -> erzeugt die Datei /mod/etc/conf/<paketname>.cfg aus den Defaults und der <paketname>.diff
modconf save <paketname>
# -> erzeugt die Datei <paketname>.diff aus den Defaults und der /mod/etc/conf/<paketname>.cfg
modsave
# -> ruft unter anderem für alle Pakete 'modconf save' auf und speichert das Verzeichnis /tmp/flash ins tffs
modsave flash
# -> speichert nur das Verzeichnis /tmp/flash ins tffs
Das dauerhafte Abschalten des Webinterfaces geht damit so (Variable
MOD_HTTPD in der Basis-Konfiguration 'mod'):
vi /mod/etc/conf/mod.cfg # -> MOD_HTTPD='yes' durch MOD_HTTPD='no' ersetzen
modconf save mod # nun ist mod.diff up-to-date
modsave flash # damit ist mod.diff im tffs
# oder
vi /mod/etc/conf/mod.cfg # -> MOD_HTTPD='yes' durch MOD_HTTPD='no' ersetzen
modsave # erzeugt alle diff Dateien neu und speichert ins tffs
Soviel zur Veranschaulichung. Komfortabler ist folgendes:
modconf set mod MOD_HTTPD=no
modconf save mod
modsave flash
# bzw.
modconf set mod MOD_HTTPD=no
modsave
Wie funktioniert das mit der GUI?¶
Im vorigen Abschnitt wurde beschrieben, welche Dateien es gibt und wie
ich die Werte von Variablen direkt von der Shell aus ändern kann. Die
Freetz GUI's basieren auf dem Konzept des
Proccgi
von Frank Pilhofer. Hierzu bedienen sie sich Umgebungsvariablen, die wie
oben beschrieben dem Muster <Paketname>_<Variablenname> folgen. In den
HTML-Seiten der GUI werden Input-Felder mit dem Tag
name="<Variablenname>" versehen. Diese Felder korrespondieren dann mit
den Variablen. Alle GUI-Seiten sind in einen Rahmen-Formular von Freetz
untergebracht, das über den Button "Übernehmen" diese Variablen
ausliest und der Umgebungsvariable zuweist.
Ein Beispiel¶
Ich hoffe, ein kleines Beispiel macht das deutlicher, unser "Paket"
heisst wie schon gesagt "hugo". Als erstes legen wir das "default"
Verzeichnis und die hugo.cfg Datei an.
Im "default" Verzeichnis des Paketes /etc/default.hugo/hugo.cfg
werden die benutzten Variablen über einen export definiert und zugleich
auch mit einem "default-Wert" belegt. Wenn man später also im
Webinterface auf "Standard" klickt, werden die dort festgelegten Werte
aus der GUI übernommen. So eine Datei sähe dann in etwa so aus:
export HUGO_ACTION='ACCEPT'
export HUGO_CHAIN='INPUT'
export HUGO_DESTINATION='anywhere'
export HUGO_ENABLED='no'
Damit sind die Variablen ACTION, CHAIN, DESTINATION, ENABLED,
etc. definiert. Diese Variablennamen werden in der GUI, einem
"cgi-File" belegt (per Eingabe oder auch per javascript).
Der entsprechende Abschnitt dazu im Code
<p>DESTINATION: <input type="text" name="destination" value="$(html "$HUGO_DESTINATION")"></p>
man sieht hier auch, dass dieses "cgi"-File Shellauswertung nutzt, um
im HTML-Code den Wert von "DESTINATION" als Vorbelegung nutzt.
Beim "Übernehmen" werden diese Variablen mit den "default-Variablen"
verglichen und beim Abweichen direkt resetfest im Flash abgespeichert.
Gibt man hier nun in das Feld "Blabla" ein, erzeugt das "Übernehmen"
die Datei /var/tmp/flash/hugo.diff mit diesem Inhalt:
die mit modsave auch gleich gesichert wird. Auch wird aus der
Zusammenführung der default-Werte und der geänderten Werte im
diff-file die aktuelle Datei /mod/etc/conf/hugo.cfg erstellt, die
für jede Variable den aktuellen Wert zuweist (das alles macht übrigens
das cgi /usr/mww/cgi-bin/save.cgi, der beim Abschicken des Formulars
aufgerufen wird).
hat man also die hugo.cfg Datei im "default" Verzeichnis fertig
gestellt, so kopiert man diese nach /mod/etc/conf
Jetzt kommt die GUI Programmierung dran. Die Datei hugo.cgi wird im
Verzeichnis /mod/usr/lib/cgi-bin/ angelegt und sollte ungefähr so
aussehen.
#!/bin/sh
PATH=/bin:/usr/bin:/sbin:/usr/sbin
. /usr/lib/libmodcgi.sh
# setzt auto_chk oder man_chk auf ' checked', je nach Wert von HUGO_ENABLED
check "$HUGO_ENABLED" yes:auto "*":man
sec_begin 'Activation'
cat << EOF
<div style="float: right;"><font size="1">Version 1.0.3</font></div>
<p>
<input id="e1" type="radio" name="enabled" value="yes" $auto_chk><label for="e1"> Active</label>
<input id="e2" type="radio" name="enabled" value="no" $man_chk><label for="e2"> Inactive</label>
</p>
EOF
sec_end
sec_begin 'hugo Überschrift'
cat << EOF
...
<p>DESTINATION: <input type="text" name="destination" value="$(html "$HUGO_DESTINATION")"></p>
...
EOF
sec_end
Wollen wir eine zusätzliche Datei fest ins Flash speichern, so müssen
wir diese mit modreg file registrieren und eine Datei namens
hugo_file.def im Verzeichnis /mod/etc/default.hugo anlegen. Inhalt
muss so aussehen:
CAPTION='Überschrift'
DESCRIPTION='Beschreibung dieser Datei. Bla bla bla...'
CONFIG_FILE='/tmp/flash/hugo_file'
CONFIG_SAVE='modsave flash;'
CONFIG_TYPE='text'
(Falls die zu bearbeitende Datei zunächst generiert werden muss, kann
die nötige Anweisung in CONFIG_PREPARE angegeben werden.)
Der Daemon, der unsere Arbeiten ausführt, heisst rc.hugo und wird
unter /mod/etc/init.d angelegt. Die ersten Zeilen müssen so aussehen:
#!/bin/sh
DAEMON=hugo
# Liest Paketkonfiguration ein und definiert einige Hilsfunktionen
. /etc/init.d/modlibrc
start() {
# HIER KOMMEN DIE VERARBEITUNGEN REIN
echo "Starting hugo..."
}
stop() {
# HIER KOMMEN DIE VERARBEITUNGEN REIN
echo "Stopping hugo..."
}
case "$1" in
start)
start
;;
stop)
stop
;;
restart)
stop
start
;;
status)
if [ -z "$(pidof "$DAEMON")" ]; then
echo 'stopped'
else
echo 'running'
fi
;;
""|load)
# CGI registrieren
modreg cgi $DAEMON Bezeichnung
# File registrieren (wird resetfest ins flash gespeichert)
# modreg file <pkg> <id> <title> <sec-level> <desc-file (ohne Pfad und .def-Endung)>
modreg file 'hugo' 'config' 'HUGO: File' 0 "hugo_file"
if [ "$HUGO_ENABLED" != "yes" ]; then
echo "$DAEMON is disabled" 1>&2
exit 1
else
start
fi
;;
;;
unload)
stop
modunreg file 'hugo'
modunreg cgi 'hugo'
;;
*)
echo "Usage: $0 [start|stop|restart|status]" 1>&2
exit 1
;;
esac
exit 0
Jetzt löschen den cache und bauen wir den Menüpunkt "hugo" in das
Webmenü ein.
TIPP: Wenn man ein CGI entwickelt, sollte man seine Arbeiten auf
einen angeschlossenen USB-Stick ablegen und die entsprechenden Dateien
ins RAM von Freetz kopieren bzw. Softlinks setzen. Hier ein Beispiel für
ein kleines Script, welches die Dateien temporär ins RAM kopiert.