mod_include

Referenz der mod_include-Direktiven

Mit Hilfe von Server Side Includes können Sie auf einfache Weise dynamische Daten in Ihre Webseiten einfügen, beispielsweise den Inhalt von Umgebungsvariablen oder Datum und Uhrzeit. Hier wird zunächst erläutert, wie Sie Apache 2 für die Ausführung von SSI konfigurieren können. Anschließend werden alle SSI-Elemente vorgestellt und zum Schluss sämtliche mod_include-Konfigurationsdirektiven.

SSI aktivieren

Die erste Voraussetzung dafür, dass in einem bestimmten Kontext Ihrer Site SSI ausgeführt werden, besteht darin, diese Funktionalität mit Hilfe der Direktive Options freischalten. Im Server-Kontext müssen Sie Includes zu den vorhandenen Optionen hinzufügen; in einem untergeordneten Kontext können Sie Folgendes schreiben:

   Options +Includes

In der Optionsliste All ist Includes übrigens bereits enthalten. Eine sicherere Alternative ist die Option IncludesNOEXEC, bei der SSI zwar aktiviert wird, aber keine Ausführung externer Programme mittels exec zulässt. Setzen Sie für diese Variante im gewünschten Kontext folgende Direktive:

   Options +IncludesNOEXEC

Als Nächstes müssen Sie für die speziellen HTML-Dokumente, in denen Server Side Includes ausgeführt werden sollen, den Ausgabefilter INCLUDES setzen. Normalerweise werden Dateien mit der Endung .shtml als SSI-Dokumente konfiguriert. Dies geschieht mit Hilfe der folgenden beiden Direktiven:

   AddType text/html .shtml
   AddOutputFilter INCLUDES .shtml

Natürlich steht es Ihnen auch frei, alle HTML-Dokumente auf Server Side Includes zu untersuchen. Bedenken Sie aber, dass dieser zusätzliche Arbeitsschritt Ihren Server ein wenig verlangsamen kann.

In Apache-Versionen vor 2.0 gab es das Filter-Konzept noch nicht. Deshalb wird SSI in älteren Versionen als Handler namens server-parsed aktiviert. Apache 2 unterstützt diese Variante aus Kompatibilitätsgründen, sie sollte aber nicht mehr verwendet werden. Diese Schreibweise sieht folgendermaßen aus:

   AddType text/html .shtml
   SetHandler server-parsed .shtml

SSI-Elemente

Jedes SSI-Element wird standardmäßig von einem HTML-Kommentar mit dem zusätzlichen Startzeichen # umschlossen, sieht also schematisch folgendermaßen aus:

   <!--#element [Argument=Wert ...] -->

Mit Hilfe der Direktiven SSLStartTag und SSLEndTag können Sie die Sequenzen ändern, die das Server Side Include umschließen. Dies ist aber eigentlich nur nötig, wenn Sie gleichzeitig eine serverseitig dynamische Technologie eines Drittherstellers verwenden, die diese Zeichenfolgen verwendet.

Für die meisten Elemente sind einige benannte Argumente im Format Argument=Wert verfügbar. Die Werte werden üblicherweise in Anführungszeichen gesetzt; solange sie keine Leerzeichen enthalten, ist dies aber optional.

SSI definiert folgende Elemente:

• config – Definition von Ausgabeformaten
• echo – Ausgabe von Variablen
• exec – Ausführen eines externen Programms
• fsize – Ausgabe der Größe einer Datei
• flastmod – Ausgabe des letzten Änderungsdatums einer Datei
• include – Einfügen einer externen Datei
• printenv – Ausgabe aller Umgebungsvariablen
• set – Setzen einer Variablen
• if, elif, else, endif – Bedingte Ausführung beziehungsweise bedingte HTML-Blöcke

config

Dieses SSI-Element legt fest, wie die Ausgabe bestimmter anderer Elemente formatiert wird. Sie können eines oder mehrere der folgenden Argumente angeben:

• errmsg="Meldungstext". Dies legt die Meldung fest, die in das HTML-Argument geschrieben wird, wenn bei der SSI-Verarbeitung ein Fehler auftritt.
• sizefmt="byte"|"abbrev". Gibt an, wie das Element fsize die Größe einer Datei anzeigen soll. "byte" zeigt den Wert als einfache Zahl in Byte an; "abbrev" verwendet je nach Größe Kilobyte oder Megabyte mit der Abkürzung K beziehungsweise M.
• timefmt="...". Ein strftime()-kompatibles Datums- und Uhrzeitformat für die Ausgabe diverser Zeitvariablen.

Hier sehen Sie für jede Variante ein Beispiel:

   <!--#config errmsg="Bei der SSI-Verarbeitung ist ein Fehler aufgetreten." -->
   <!--#config sizefmt="abbrev" -->
<!--#config timefmt="%d.%m.%Y, %h:%i" -->

echo

Mit Hilfe dieses Elements können Sie den Wert einer Umgebungsvariablen ausgeben. Das Element besitzt zwei Attribute:

• var="Variable". Dieses Attribut gibt die Variable an, deren Wert Sie ausgeben möchten. Zusätzlich zu den Standard-CGI-Umgebungsvariablen definiert SSI die folgenden eigenen Variablen:
• DATE_GMT. Datum und Uhrzeit in Greenwich Mean Time.
• DATE_LOCAL. Datum und Uhrzeit der lokalen Zeitzone.
• DOCUMENT_NAME. Dateiname des angeforderten Dokuments.
• DOCUMENT_URI. URL-Pfad des angeforderten Dokuments.
• LAST_MODIFIED. Datum und Uhrzeit der letzten Änderung des angeforderten Dokuments.
• QUERY_STRING_UNESCAPED. Query-String der Anfrage; die URL-codierten %-Sequenzen werden aufgelöst, während Shell-relevante Zeichen mit vorangestellten Backslashes versehen werden.
Wenn Sie versuchen, eine Variable zu verwenden, die nicht gesetzt ist, bestimmt die Direktive SSIUndefinedEcho, was geschieht.
• encoding="none" | "url" | "entity". Dieses optionale Argument bestimmt, auf welche Weise der Ausgabewert codiert wird. Wenn Sie es verwenden möchten, muss encoding vor dem Argument var stehen. Die drei möglichen Werte bedeuten Folgendes:
• "none". Es wird keine Codierung verwendet. Dies ist aus Sicherheitsgründen normalerweise nicht zu empfehlen – unter Umständen könnte ein Angreifer auf diese Weise schädlichen Code einschmuggeln.
• "url". Der Wert wird URL-codiert, das heißt, die meisten Sonderzeichen werden durch ein Prozentzeichen und den hexadezimalen Zeichencode ersetzt.
• "entity". Diese Einstellung sorgt dafür, dass HTML-relevante Sonderzeichen durch die entsprechenden Entity-Referenzen ersetzt werden (zum Beispiel &lt; für < oder &amp; für &). Da echo letztendlich statischen HTML-Code für den Browser erzeugt, ist dies normalerweise die richtige Wahl; deshalb ist es auch der Standardwert von encoding.

Das folgende Beispiel gibt den Namen des Browsers aus, mit dem der entfernte Benutzer die Anfrage gesendet hat:

   <!--#echo var="HTTP_USER_AGENT" -->

exec

Dieses Element führt ein externes Programm oder CGI-Skript aus und fügt dessen Ausgabe an der aktuellen Position in das HTML-Dokument ein. Beachten Sie, dass exec nur verfügbar ist, wenn Sie die Option Includes gesetzt haben, nicht aber bei IncludesNOEXEC.

Sie können eines der folgenden beiden Argumente verwenden:

• cgi="URL-Pfad". Das angegebene CGI-Skript wird ausgeführt. Wenn der Pfad relativ ist, bezieht er sich auf das Verzeichnis des aktuellen Dokuments. Wenn das Skript statt eines Dokuments nur einen Location-Header zur Weiterleitung produziert, wird dieser in einen Hyperlink umgewandelt.
• cmd="Dateipfad". Der angegebene Befehl wird unter UNIX durch /bin/sh ausgeführt, gilt also als Shell-Kommando; unter Windows wird der enthaltene Befehl ebenfalls durch das Betriebssystem ausgeführt.

In den meisten Fällen sollten Sie statt exec cgi das Element include mit dem Attribut virtual verwenden.

Hier zwei Beispiele:

   <!--#exec cgi="/cgi-bin/test.cgi" -->
   <!--#exec cmd="ls /usr/local/apache2/htdocs" -->

fsize

Dies gibt die Größe der angegebenen Datei in dem durch sizefmt definierten Format an. Das Element ist sehr praktisch für Linklisten oder Bildergalerien. Es gibt zwei mögliche Argumente:

• file="Dateipfad". Diese Option gibt den Pfad einer Datei an; er muss relativ zum Verzeichnis des aktuellen Dokuments angegeben werden.
• virtual="URL-Pfad". Bei dieser Variante ist der Wert ein URL-Pfad; falls er nicht mit / beginnt, ist er relativ zum aktuellen Dokument. Das bedeutet, dass Apache daraus zunächst eine URL konstruiert und diese als Datei betrachtet, deren Größe ermittelt wird.

Beispiel:

   <!--#fsize file="bild.jpg" -->

flastmod

Dieses Element liefert Datum und Uhrzeit der letzten Änderung der angegebenen Datei; das Format folgt der timefmt-Einstellung. Sie können genau wie bei fsize eines der Argumente file oder virtual verwenden. Beispiel:

   <!--#flastmod virtual="/cgi-bin/test.cgi" -->

include

Das Element include fügt den Inhalt der angegebenen Datei an der aktuellen Position ein. Dies ist beispielsweise nützlich, um stets wiederkehrende Elemente wie Kopf- oder Fußzeilen auszulagern. Wenn für das Verzeichnis, in dem die einzufügende Datei liegt, die Option IncludesNOEXEC gesetzt ist, können Sie nur Dokumente mit Text-MIME-Types einfügen. Andernfalls sind auch CGI-Skripte möglich; in diesem Fall wird deren Ausgabe eingebettet. Sie können wiederum eines der Argumente file oder virtual (siehe oben) wählen; der Dateipfad bei file muss hier relativ zum aktuellen Verzeichnis sein und darf auch nicht den Bestandteil ../ für einen Wechsel in das übergeordnete Verzeichnis enthalten.

Hier sehen Sie zwei Beispiele:

   <!--#include file="start.html" -->
   <!--#include virtual="/cgi-bin/test.cgi" -->

printenv

Dieses Element gibt eine vollständige Liste aller Umgebungsvariablen aus; es besitzt keine Argumente. Beispiel:

   <!--#printenv -->

set

Mit Hilfe dieser SSI-Anweisung können Sie eine eigene Variable definieren. Sie müssen die beiden folgenden Argumente verwenden:

• var="Variablenname". Dies ist der Name der Variablen.
• value="Variablenwert". Dieses Argument gibt den Wert an, den Sie der Variablen zuweisen möchten.

Hier ein Beispiel:

   <!--#set var="gruss" value="Hallo Welt!" -->

if, elif, else und endif

Mit Hilfe dieser Elemente können Sie in Ihre Server Side Includes Fallentscheidungen einfügen. Schematisch betrachtet gilt folgender Ablauf (eckige Klammern bezeichnen optionale Bestandteile):

   <!--#if expr="Bedingung" -->
      ... beliebiger HTML/SSI-Code ...
   [<!--#elif expr="Bedingung" -->
      ... beliebiger HTML/SSI-Code ...
   [<!--#elif expr="Bedingung" -->
      ... beliebiger HTML/SSI-Code ...
   ] ... ]
   [<!--#else -->
      ... beliebiger HTML/SSI-Code ...
   ]
   <!--#endif -->

if enthält die erste Bedingung; der nachfolgende HTML- und / oder SSI-Code wird ausgeführt, wenn Sie zutrifft. Anschließend können Sie optional ein elif-Element (»else if«) einfügen, dessen Bedingung nur überprüft wird, falls die if-Bedingung nicht zutrifft. Entsprechend lassen sich beliebig viele elif-Bedingungen ineinander verschachteln. Ein anschließendes, ebenfalls optionales else (ohne Bedingung) leitet Code ein, der nur übernommen wird, wenn keine der Bedingungen wahr ist. Die gesamte Sequenz muss schließlich durch endif abgeschlossen werden.

Die Bedingungen für if und elif werden als Werte des Arguments expr gesetzt und können aus folgenden Komponenten bestehen:

• Literale. Jede einfache Zeichenkombination wird wörtlich genommen.
• Variablen. Zeichenfolgen, denen Sie ein Dollarzeichen voranstellen, werden als Variablen ausgewertet. Dies können sowohl Umgebungsvariablen als auch selbst definierte Variablen sein. Beispiele: $test oder $SERVER_NAME.
• Reguläre Ausdrücke. Zeichenfolgen, die durch zwei Slashes umschlossen werden, werden als Perl-kompatible reguläre Ausdrücke (PCRE) interpretiert. Beispiel: /^[a-z]/ – alles, was mit einem Kleinbuchstaben beginnt.
• Vergleichsoperatoren. Definiert sind =, !=, <, >, <= und >=; sie dürften selbsterklärend sein.
• Logische Verknüpfungen. && (logisches Und), || (logisches Oder) und ! (logisches Nicht).
• Klammern. Um die Priorität der Auswertung von Teilausdrücken zu beeinflussen, können Sie Klammern setzen.

Das folgende Beispiel führt eine Art »Content-Negotiation light« durch: Es überprüft den Anfrage-Header Accept-Language (die bevorzugte Sprache, die der Client wünscht) und gibt eine Begrüßung in der ersten Sprache aus dieser Liste aus. Wenn die Sprache nicht den Bedingungen entspricht, wird Englisch verwendet:

   <!--#if expr="$HTTP_ACCEPT_LANGUAGE = /^de/" -->
      Guten Tag!
   <!--#elif expr="$HTTP_ACCEPT_LANGUAGE = /^en/" -->
      Good Afternoon!
   <!--#elif expr="$HTTP_ACCEPT_LANGUAGE = /^fr/" -->
      Bonjour!
   <!--#elif expr="$HTTP_ACCEPT_LANGUAGE = /^it/" -->
      Buongiorno!
   <!--#else -->
      Good Afternoon!
   <!--#endif -->

Die regulären Ausdrücke, die jeweils den Beginn des Variablenwertes untersuchen, sind notwendig, weil der Header meist mehrere Sprachen enthält.

Rechtlicher Hinweis

Dieser Text ist ein Auszug aus dem Buch "Apache 2" von Sascha Kersken (Bonn 2005, Galileo Computing). Ohne ausdrückliche Genehmigung von Autor und Verlag darf er weder insgesamt noch in Teilen auf anderen Websites oder in sonstigen Medien veröffentlicht werden. Links auf diese Seite sind dagegen gestattet und ausdrücklich erwünscht.