1.8 CGI-Erstellung für das httpd-Paket

Unterabschnitte

- 1.8.1 Allgemeines zum Webserver
- 1.8.2 Scriptnamen
- 1.8.3 Menü-Einträge
- 1.8.4 Aufbau eines CGI-Skriptes
  - 1.8.4.1 Die Kopfzeilen
  - 1.8.4.2 Das Hilfsskript cgi-helper
  - 1.8.4.3 Der Inhalt
  - 1.8.4.4 Die show_tab_header Funktion
  - 1.8.4.5 Mehrsprachfähigkeit
  - 1.8.4.6 Formular-Auswertung
- 1.8.5 Benutzerrechte
- 1.8.6 Sonstiges

# 1.8 CGI-Erstellung für das httpd-Paket

## 1.8.1 Allgemeines zum Webserver

Der Webserver, der bei FLI4L verwendet wird, ist der `mini_httpd` von ACME Labs. Die Quellen und Manpages können unter http://www.acme.com/software/mini_httpd/ heruntergeladen werden. Allerdings wurden für FLI4L in der aktuellen Version (1.19) ein paar Änderungen vorgenommen, der Patch befindet sich im SRC-Paket im Verzeichnis `src/fli4l/httpd`.

## 1.8.2 Scriptnamen

Der Scriptname sollte möglichst vielsagend sein, damit er von anderen Scripts leichter zu unterscheiden ist und es keine Namensüberschneidungen bei verschiedenen OPTs gibt.

Damit die Scripts ausführbar gemacht werden und DOS-Zeilenumbrücke in UNIX-Zeilenumbrüche umgewandelt werden, muss in der opt/euer_opt.txt ein entsprechender Eintrag gemacht werden (s.o.).

## 1.8.3 Menü-Einträge

Um eine Eintrag im Menü vorzunehmen, muß eine Eintragung in der Datei `/etc/httpd/menu` vorgenommen werden. Dies kann z.B. aus den Startscripts im Verzeichnis `/etc/rc.d/` heraus geschehen. Dieser Mechanismus erlaubt es den OPTs, auch im laufendem Betrieb Änderungen am Menü vorzunehmen. Das Menü ist in der Datei `/etc/httpd/menu` gespeichert, die folgenden Aufbau hat: Sie ist in drei Spalten eingeteilt. In der ersten Spalte steht ein Kennbuchstabe, in der zweiten Spalte das Link-Ziel und der ganze Rest der Zeile wird als beschreibung genommen.

Der Kennbuchstabe ist entweder ein 't', dann wird ein neuer Menüabschnitt begonnen oder ein 'e', dann handelt es sich um einen normalen Menüeintrag, der auf eine andere Seite verlinkt.

Ein Beispiel:

        t - Mein tolles OPT
        e meinopt1.cgi Mach was tolles
        e meinopt1.cgi?mehr=ja Mach mehr tolles

Um das Bearbeiten des Menüs zu vereinfachen, gibt es das Script httpd-menu.sh, es hat folgende Aufruf-Syntax:

        /usr/local/bin/httpd-menu.sh add <link> <name> [section]

So wird ein Eintrag mit dem Namen `<name>` in den Abschnitt `[section]` eingetragen. Wenn `[section]` weggelassen wird, wird es standardmäßig in den Abschnitt ,,Opt'' eingetragen. `<link>` gibt das Ziel des neuen Links an.

Beispiel:

        /usr/local/bin/httpd-menu.sh add "neuedatei.cgi" "Hier klicken" "Tools"

Dieses Beispiel erzeugt einen Link mit dem Titel ,,Hier klicken'' und dem Link-Ziel ,,neuedatei.cgi'' im Abschnitt ,,Tools'' und legt diesen Abschnitt bei Bedarf an.

Das Script kann auch Einträge aus dem Menü wieder entfernen:

        /usr/local/bin/httpd-menu.sh rem <link>

Mit diesem Aufruf wird der Eintrag mit dem Link `<link>` wieder entfernt. Achtung: Wenn mehrere Menüeinträge auf die gleiche Datei verweisen, werden alle diese Einträge aus dem Menü entfernt.

## 1.8.4 Aufbau eines CGI-Skriptes

### 1.8.4.1 Die Kopfzeilen

Alle Scripts des Webservers sind einfache Shell-Scripts (Interpreter wie z.B. Perl, PHP, etc. sind viel zu groß für FLI4L). Sie sollten mit dem obligatorischen Script-Header anfangen (Verweis auf den Interpreter, Name, Sinn des Scripts, Autor, Lizenz).

### 1.8.4.2 Das Hilfsskript cgi-helper

Gleich nach den Kopfzeilen sollte dann schon das Hilfsskript cgi-helper mit folgendem Aufruf eingebunden werden:

    . /srv/www/include/cgi-helper

Wichtig ist ein Leerzeichen zwischen Punkt und Slash!

Dieses Skript stellt diverse Hilfsfunktionen bereit, die das Erstellen von CGIs für fli4l wesentlich vereinfachen sollen. Außerdem werden mit dem Einbinden des cgi-helper auch noch Standardaufgaben ausgeführt, wie beispielsweise das parsen von Variablen, die mit Formularen oder über die URL übergebenen wurden, oder das laden von Sprach- und CSS-Dateien.

Hier eine kleine Funktionsübersicht:

Tabelle 1.3: Funktionen des cgi-helper Skriptes.

Name | Funktion
check_rights | Überprüfung der Benutzerrechte
http_header | Ausgabe eines Standard HTTP-Headers oder eines speziellen Headers, beispielsweise zum Download von Dateien
show_html_header | Ausgabe des kompletten Seitenheaders (inkl. HTTP-Header, Kopfzeile und Menü)
show_html_footer | Ausgabe des Abschlusses der HTML-Seite
show_tab_header | Ausgabe eines Inhalts-Fensters mit Tabs
show_tab_footer | Ausgabe des Abschlusses des Inhaltsfensters
show_error | Ausgabe eines Fensters für Fehlermeldungen (Farbe: rot)
show_info | Ausgabe eines Fensters für Informationen/ Erfolgsmeldungen (Farbe: grün)

### 1.8.4.3 Der Inhalt

Um ein einheitliches Design und vor allem die Kompatibilität mit zukünftigen fli4l-Versionen zu gewährleisten, ist es sehr zu empfehlen, die oben genannten Funktionen zu benutzen, auch wenn man in einem CGI theoretisch alle Ausgaben selbst generieren könnte.

Eine einfaches CGI-Skript könnte wie folgt aussehen:

       #!/bin/sh
       # --------------------
       # Header (c) Autor Datum
       # --------------------
       # get main helper functions
       . /srv/www/include/cgi-helper

        show_html_header "Mein erstes CGI"
        echo '   <h2>Willkommen</h2>'
        echo '   <h3>Dies ist ein Beispiel-CGI-Skript</h3>'
        show_html_footer

Der Parameter, welcher der Funktion show_html_header übergeben wird, wird dabei als Titel verwendet. Sie generiert automatisch das Menü und bindet ebenso automatisch zum Skript gehörende CSS und Sprachdateien ein. Voraussetzung dafür ist, dass diese sich in den Verzeichnissen /srv/www/css bzw. /srv/www/lang befinden und den selben Namen (aber natürlich eine andere Endung) wie das Skript haben. Ein Beispiel:

        /srv/www/admin/OpenVPN.cgi
        /srv/www/css/OpenVPN.css
        /srv/www/lang/OpenVPN.de

Sowohl das Benutzen von Sprachdateien als auch von CSS-Dateien ist optional. Immer Eingebunden werden css/main.css und lang/main.xx wobei 'xx' der gewählten Sprache entspricht.

Der Funktion show_html_header können aber neben dem Titel noch weitere Parameter übergeben werden. Ein Aufruf mit allen möglichen Parametern könnte so aussehen:

        show_html_header "Titel der Seite" "refresh=$time;url=$url;cssfile=$cssfile;showmenu=no"

Alle zusätzlichen Parameter müssen, wie im Beispiel gezeigt, mit Anführungszeichen umschlossen und durch ein Semikolon getrennt werden. Eine Überprüfung der Syntax erfolgt NICHT! Es ist also notwendig sehr genau auf die Parameterübergabe zu achten.

Hier eine kurze Übersicht über die Funktion der Parameter:

- refresh=$time: Zeit in Sekunden in der die Seite vom Browser neu geladen werden soll.
- url=$url: Die URL die bei einem Refresh neu geladen wird.
- cssfile=$file: Name einer CSS-Datei, wenn diese vom Namen des CGIs abeicht.
- showmenu=no: Damit kann die Anzeige des Menüs und des Headers unterdrückt werden.

Sontige Richtlinien zum Inhalt:

- Fasst euch kurz :-)
- Schreibt sauberes HTML (SelfHTML ist da ein guter Ansatzpunkt)
- Verzichtet auf hochmoderen Schnick-Schnack (JavaScript ist OK, wenn es nicht stört, sondern den Benutzer unterstützt, das ganze muß auch ohne JavaScript funktionieren)

### 1.8.4.4 Die show_tab_header Funktion

Damit der Inhalt eurer mithilfe des CGI erzeugten Webseite auch hübsch geordnet aussieht könnt ihr die cgi-helper Funktion show_tab_header nutzen. Sie erzeugt dann anklickbare 'Tabs', so dass ihr eure Seite in mehrere Bereiche unterteilen könnt, oder einfach nur eine Titelzeile (ein Tab).

Der show_tab_header Funktion werden Parameter immer in Paaren übergeben entgegen. Der erste Wert entspricht dem Titel eines Tabs, der 2. dem Link. Wird als Link die Zeichenkette 'no' übergeben, wird lediglich der Titel ausgegeben und der Tab ist nicht anklickbar (und blau).

Im folgenen Beispiel wir ein 'Fenster' mit dem Titel 'Ein tolles Fenster' erzeugt. Im Fenster steht 'foo bar':

        show_tab_header "Ein tolles Fenster" "no"
        echo "foo"
        echo "bar"
        show_tab_footer

In diesem Beispiel werden zwei anklickbare Auswahltabs generiert, die dem Skript die Variable action mit verschiedenen Werten übergibt.

        show_tab_header "1. Auswahltab" "$myname?action=machdas" \
                        "2. Auswahltab" "$myname?action=machdies"
        echo "foo"
        echo "bar"
        show_tab_footer

Nun kann das Skript den Inhalt der Variablen FORM_action (siehe weiter unten zur Variablenauswertung) auswerten und je nach dem unterschiedliche Inhalte bereitstellen. Damit der angeklickte Tab auch ausgewählt erscheint und nicht mehr angeklickt werden kann, müsste der Funktion statt dem Link wie schon erwähnt ein 'no' übergeben werden. Das geht aber auch einfacher, wenn man sich an die Konvention in folgendem Beispiel hält:

        _opt_machdas="1. Auswahltab"
        _opt_machdies="2. Auswahltab"
        show_tab_header "$_opt_machdas" "$myname?action=opt_machdas" \
                        "$_opt_machdies" "$myname?action=opt_machdies"
        case $FORM_action in
            opt_machdas) echo "foo" ;;
            opt_machdies) echo "bar" ;;
        esac
        show_tab_footer

Wird also dem Titel eine Variable übergeben, deren Namen dem Inhalt der Variablen action mit führendem '_' entspricht, wird der entsprechende Tab ausgewählt dargestellt.

### 1.8.4.5 Mehrsprachfähigkeit

Das Hilfsskript enthält auch alles, um CGI-Skripte mehrsprachfähig zu machen. Dazu müsst ihr 'nur' für alle Textausgaben Variablen mit führenden '_' verwenden und diese Variablen in den entsprechenden Sprachdateien definieren.

Beispiel:

lang/opt.de:

        _opt_machdas="Eine Ausgabe"

lang/opt.en:

        _opt_machdas="An Output"

admin/opt.cgi

        ...
        echo $_opt_machdas
        ...

### 1.8.4.6 Formular-Auswertung

Um Formulare zu verarbeiten, muss man noch einige Dinge wissen. Egal ob die Formular-Methode GET oder POST verwendet wird, die Variablen finden sich nach dem Einbinden des cgi-helpers (welches wiederum das Hilfsprogramm proccgi aufruft) als shell-variable wieder, mit dem Prefix ,,FORM_''. gespeichert. Wenn das Formularfeld also den Namen ,,eingabe'' hatte, kann im Shell-Script mit `$FORM_eingabe` darauf zugegriffen werden.

Weitere Infos zum Programm proccgi: http://www.fpx.de/fp/Software/ProcCGI.html

## 1.8.5 Benutzerrechte

Um die Rechteverwaltung zu verwenden, müssen am Anfang des Scripts folgende Zeile eingefügt werden:

        check_rights "misc" "test"

Dieses Script wird dann nur ausgeführt wenn der aktuelle Benutzer alle Rechte (`HTTPD_RIGHTS_x='all'`), alle Rechte in diesem Bereich (`misc`) (`HTTPD_RIGHTS_x='misc:all'`) oder das Recht hat, diese spezielle Aktion (`SEC_ACTION`) (`HTTPD_RIGHTS_x='misc:test'`) auszuführen.

## 1.8.6 Sonstiges

Dies und das (Ja, das ist auch noch wichtig!):

- Der `mini_httpd` schützt Unterverzeichnisse nicht mit Passwort. Es muß für jedes Verzeichniss eine eigene `.htaccess` angelegt werden oder ein Link auf eine andere htaccess-Datei angelegt werden.
- KISS - Keep it simple, stupid!
- Diese Angaben können sich jederzeit ohne Vorankündigung ändern!

Das Fli4l-Team
23. Februar 2006