Eine Beispiel-Konfiguration für mod_gzip
Author: Michael Schröpl
Description: Eine ausführlich dokumentierte Beispiel-Konfiguration für das Apache-Zusatzmodul 'mod_gzip'
Keywords: Apache, HTTP, encoding, gzip, Komprimierung, Konfiguration

# Eine Beispiel-Konfiguration für `mod_gzip`

Der genaue Umfang der gewünschten Funktionen wird mit Hilfe zusätzlicher Apache-Konfigurationsanweisungen beschrieben, die durch die Einbindung des Moduls `mod_gzip` verfügbar werden.

Eine wirklich vollständige Dokumentation der Wirkung dieser Anweisungen existiert zur Zeit noch nicht; generell gilt, daß

- praktisch alles in jeder Umgebung einsetzbar ist, also wahlweise
  - im gesamten Server,
  - in Virtual Hosts,
  - in Verzeichnissen und sogar
  - in `.htaccess`-Dateien
  und
- im Wesentlichen die üblichen Überlagerungsverfahren von Apache gelten - ausgenommen die Anweisungen bezüglich der Auswahl zu komprimierender Inhalte, bei denen alles etwas komplizierter ist.

Die nachfolgende Konfiguration ist ausdrücklich nicht dafür gedacht, gedankenlos übernommen zu werden - sie soll vielmehr ein Gefühl dafür liefern, wie viele Optionen verfügbar sind. Und es sind viele Optionen - jedenfalls dafür, daß man eigentlich 'nur komprimierte Ausgabedaten haben will' ...

Modul laden | Zuständigkeiten | Vorkomprimiert | Bürokratisches | Datenverwaltung | Dateigrößen | Anforderungen | Filter | Transfer-Kodierung | Protokollierung | Proxies

    ########################################
    ### Apache-Konfigurationsanweisungen ###
    ###   für mod_gzip 1.3.26.1a         ###
    ########################################

    ###################
    ### Modul laden ###
    ###################

    # ---------------------------------------------------------------------
    # DLL laden / Win32:
    # LoadModule gzip_module modules/ApacheModuleGzip.dll
    #
    # DSO laden / UNIX:
    # LoadModule gzip_module modules/mod_gzip.so
    #
    # (keines von beiden, falls Modul statisch eingebunden;
    #  der genaue Dateiname kann von der verwendeten Kompilierungsmethode
    #  dieses Moduls abhängen)
    # ---------------------------------------------------------------------

      <IfModule mod_gzip.c>

    #######################
    ### Zuständigkeiten ###
    #######################

    # ---------------------------------------------------------------------
    # Soll mod_gzip überhaupt verwendet werden?
      mod_gzip_on                   Yes
    # (Insbesondere kann man mod_gzip in der zentralen Server-Konfiguration
    #  einschalten und durch diese Anweisung z. B. innerhalb bestimmter
    #  Verzeichnisse oder Virtual Hosts wieder ausschalten.)
    # ---------------------------------------------------------------------

    ########################################
    ### Statisch vorkomprimierte Dateien ###
    ########################################

    # ---------------------------------------------------------------------
    # Soll mod_gzip selbst einen Teilbereich von 'Content-Negotiation'
    # durchführen?
      mod_gzip_can_negotiate        Yes
    # (wenn diese Option aktiv ist und eine statische Datei in komprimierter
    #  Form ausgeliefert werden soll, dann sucht mod_gzip nach einer statisch
    #  vorkomprimierten Version dieser Datei mit einer definierten zusätz-
    #  lichen Endung - siehe nächste Direktive - welche vorrangig ausge-
    #  liefert würde. Dies würde es erlauben, die wiederholte
    #  Komprimierung derselben statischen Datei zu vermeiden und somit CPU-
    #  Zeit zu sparen.
    #  Es ist kein dynamisches Caching dieser Datei vorgesehen; der Anwender
    #  ist bisher selbst für die Erstellung und Aktualisierung des Inhalts
    #  der vorkomprimierten Datei verantwortlich.
    #  Seit Version 1.3.19.2a erkennt mod_gzip jedoch automatisch, ob eine
    #  statisch vorkomprimierte Datei älter ist als ihr unkomprimiertes
    #  Original und liefert in diesem Falle die Original-Datei aus - besser
    #  korrekte Daten liefern als veraltete ...)
    # ---------------------------------------------------------------------
    # Endung (Suffix) für statisch vorkomprimierte Dateien
      mod_gzip_static_suffix        .gz
      AddEncoding              gzip .gz
    # (Wirkung: siehe vorherige Direktive; diese Zeichenkette wird an den
    #  Namen der Original-Datei angefügt.
    #  Für die entsprechende Endung muß das Encoding 'gzip' explizit defi-
    #  niert werden; mod_gzip liefert diesen Wert nicht selbst aus, sondern
    #  erzeugt einfach eine Apache-interne Weiterleitung zu diesem URL.
    #  Deshalb ist die sonstige Apache-Konfiguration dafür zuständig, den
    #  Content-Encoding-Header passend zu setzen ...
    #  In Versionen vor 1.3.19.2a war dieser Wert nicht konfigurierbar.)
    # ---------------------------------------------------------------------
    # Automatische Aktualisierung statisch vorkomprimierter Dateien
      mod_gzip_update_static        No
    # (Falls auf 'Yes' gesetzt, bewirkt diese Direktive (neu seit Version
    #  1.3.26.1a), daß mod_gzip jede als veraltet erkannte statisch vor-
    #  komprimierte Datei während der Anforderung automatisch aktualisiert,
    #  d. h. den Inhalt der ursprünglich angeforderten Datei komprimiert
    #  und damit die vorkomprimierte Variantendatei überschreibt!
    #  Bei jeder solchen automatischen Aktualisierung gibt mod_gzip eine Meldung
    #  mit dem Gewicht 'notice' in das Apache-error_log aus.
    #  Dabei liest mod_gzip den Inhalt des Originals direkt aus dessen Datei;
    #  dieser kann also während der Anforderung nicht durch andere
    #  Apache-Module interpretiert werden. Das ist möglicherweise nicht,
    #  was der Anwender möchte - hoffentlich aber das, was die meisten An-
    #  wender wollen, weil es auf diese Weise schnell funktioniert.
    #  Diese Anweisung sollte nur mit äußerster Vorsicht eingesetzt werden.
    #  wobei sichergestellt werden sollte, daß dabei keine wertvollen Dateien
    #  innerhalb des URL-Baums überschrieben werden.
    #  Dies ist keine Funktion für den Einsatz auf Massen-Hosting-Servern,
    #  vor allem, weil mod_gzip Zugriffsprobleme haben könnte - die Benutzer-
    #  kennung, unter welche die Apache-Prozesse laufen, benötigt Schreib-
    #  recht auf die vorkomprimierten Dateien sämtlicher Benutzer, was nicht
    #  automatisch der Fall sein dürfte.)
    #  [Fehlerbehandlung durch mod_gzip in diesem Fall??? Was wird ausgeliefert?]
    # ---------------------------------------------------------------------

    ######################
    ### Bürokratisches ###
    ######################

    # ---------------------------------------------------------------------
    # Statusanzeige für mod_gzip
      mod_gzip_command_version      '/mod_gzip_status'
    # (definiert einen URL - bzw. einen Teil-String eines solchen - zur
    # Anzeige des Status von mod_gzip; aus Gründen der Geheimhaltung
    # kann dieser URL pro Installation individuell definiert und über
    # einen <Location>-Abschnitt zugriffsgeschützt werden)
    # ---------------------------------------------------------------------
    # Die Status-Anzeige hat folgendes Aussehen:
    #       mod_gzip is available...
    #       mod_gzip_version = 1.3.26.1a
    #       mod_gzip_on = Yes/No
    # Sie liefert also die Information,
    # - daß mod_gzip auf dem Server installiert ist und korrekt arbeitet,
    # - welche Version installiert ist und
    # - ob mod_gzip für diese Location auf 'aktiv' gesetzt wurde
    #   (-> mod_gzip_on)
    # ---------------------------------------------------------------------

    #######################
    ### Datenverwaltung ###
    #######################

    # ---------------------------------------------------------------------
    # Arbeitsverzeichnis für temporäre Dateien und den Komprimierungs-Cache
    # Falls nicht angegeben, werden als Defaultwerte verwendet:
    # [Win32=c:\temp], [UNIX=/tmp]
    # mod_gzip_temp_dir             /tmp
    # (Dieses Verzeichnis muß bereits existieren, und die Benutzerkennung,
    #  unter welcher der Apache-Server läuft, muß Lese- und Schreibrecht in
    #  diesem Verzeichnis haben.
    #  Anders als bei sonstigen Apache-Direktiven muß hier ein absoluter
    #  Pfadname angegeben werden; eine relative Angabe wird nicht auf
    #  ServerRoot bezogen interpretiert.
    #  Es darf KEIN '/' am Ende dieses Verzeichnis-Pfadnamens angegeben werden.
    #  Für optimale Performance sollte dieses Verzeichnis auf einer RAM-Disk
    #  liegen, falls das Dateisystem nicht bereits selbst gut cached.)
    # ---------------------------------------------------------------------
    # Aufheben temporärer Arbeitsdateien [Yes, No]
      mod_gzip_keep_workfiles       No
    # (eine Datei pro HTTP-Anforderung - nur für Debugging-Zwecke auf 'Yes'
    # setzen!)
    # ---------------------------------------------------------------------

    ###################
    ### Dateigrößen ###
    ###################

    # ---------------------------------------------------------------------
    # Minimalgröße (in Bytes) einer zu komprimierenden Datei
      mod_gzip_minimum_file_size    500
    # (Bei sehr kleinen Dateien bringt die Komprimierung an absolutem Betrag
    #  nur noch wenig Gewinn [es sind meistens immer noch 50% Einsparung
    #  beim Inhalt, aber weitere ca. 500 Bytes an HTTP- und TCP-Headers
    #  bleiben immer unkomprimiert], bedeuten aber dennoch sowohl für den
    #  Client als auch für den Server zusätzliche CPU-Last.)
    # ---------------------------------------------------------------------
    # Maximalgröße (in Bytes) einer zu komprimierenden Datei
      mod_gzip_maximum_file_size    500000
    # (Bei sehr großen Dateien kann die Komprimierung eventuell sehr lange
    #  dauern und damit den Beginn der Übertragung entsprechend verzögern.
    #  Außerdem verhindert eine Begrenzung an dieser Stelle, daß eine be-
    #  liebig große dynamische Ausgabe, etwa durch eine Endlossschleife in
    #  einem CGI-Skript - oder gar der Versuch, streaming data zu kompri-
    #  mieren - zu einer beliebig großen temporären Datei bei der
    #  Komprimierung führt und damit die gesamte Festplatte voll schreibt.
    #  Andererseits bewirkt die Komprimierung natürlich bei großen Dateien
    #  eine subjektiv deutlicher spürbare Verbesserung ... man sollte
    #  diesen Wert also sehr genau den eigenen Anforderungen anpassen.)
    # ---------------------------------------------------------------------
    # Maximalgröße (in Bytes) einer im Hauptspeicher zu komprimierenden Datei
      mod_gzip_maximum_inmem_size   60000
    # (größere Dateien werden ins Arbeitsverzeichnis komprimiert; diesen
    #  Wert ggf. dem verfügbaren RAM des Servers anpassen.
    #  In mod_gzip 1.3.19.x werden größere Werte automatisch auf 60000
    #  limitiert, weil manche Betriebssysteme Probleme bei Speicherzuweisungen
    #  von mehr als 64 kB am Stück haben sollen.)
    # ---------------------------------------------------------------------

    #####################
    ### Anforderungen ###
    #####################

    # (siehe Kapitel über Caching zu Problemen bei der Verwendung dieser
    # Direktiven.)
    # ---------------------------------------------------------------------
    # Mindestens verlangte HTTP-Version des Client
    # Erlaubte Werte: 1000 = HTTP/1.0, 1001 = HTTP/1.1, ...
    # Diese Anweisung verwendet dieselben numerischen Protokoll-Bezeichnungen
    # wie der Apache selbst intern
      mod_gzip_min_http             1000
    # (Damit kann man veraltete Browser, Suchmaschinen etc. vom Komprimie-
    #  rungsverfahren ausschließen: Wenn der User-Agent sich selbst nicht
    #  als fähig deklariert, mindestens den hier angegebenen HTTP-Level zu
    #  verstehen, dann werden nur unkomprimierten Daten an ihn versendet
    #  - egal, was er ansonsten über sich behauptet.
    #  Der Wert '1001' schließt insbesondere Netscape 4.x aus sowie
    #  eine Reihe von Proxy-Servern.)
    # ---------------------------------------------------------------------
    # Zu behandelnde HTTP-Methoden
    # Erlaubte Werte: 'GET', 'POST' oder beide Angaben.
      mod_gzip_handle_methods        GET POST
    # (Mit dieser Direktive kann man insbesondere POST-Requests von der
    #  Komprimierung ausschließen. Es sind Fälle bekannt, in denen
    #  die Verarbeitung solcher Anforderungen durch frühere mod_gzip-
    #  Versionen Probleme verursachen konnte.
    #  In Versionen vor 1.3.19.2a war dieser Wert nicht konfigurierbar.)
    # ---------------------------------------------------------------------

    ##############
    ### Filter ###
    ##############

    # ---------------------------------------------------------------------
    # Welche Dateien sollen komprimiert werden?
    #
    # Die Reihenfolge innerhalb jeder der beiden Phasen ist unwichtig,
    # aber um die Komprimierung des Inhalts eines Requests auszulösen,
    # a) muß der Request in jeder der beiden Phasen mindestens eine
    #    include-Regel erfüllen und
    # b) darf in keiner der beiden Phasen eine exclude-Regel erfüllen.
    # Dieser Regelsatz ist nicht minimal, sondern nur als Beispiel gedacht.
    #
    # Phase 1: (reqheader, uri, file, handler)
    # ========================================
    # (siehe Kapitel über Caching zu Problemen bei der Verwendung von
    #  Filterregeln des Typs 'reqheader'.)
    #
    # NEIN: Bestimmte defekte Browser, die zwar gzip-komprimierte Inhalte
    #       anfordern, aber dann den Inhalt nicht verstehen
      mod_gzip_item_exclude         reqheader  "User-agent: Mozilla/4.0[678]"
    #
    # JA:   HTML-Dokumente
      mod_gzip_item_include         file       \.html$
    #
    # NEIN: Include-Dateien/JavaScript & CSS (wegen Netscape4-bugs)
      mod_gzip_item_exclude         file       \.js$
      mod_gzip_item_exclude         file       \.css$
    #
    # JA:   CGI-Skripte
      mod_gzip_item_include         file       \.pl$
      mod_gzip_item_include         handler    ^cgi-script$
    #
    # Phase 2: (mime, rspheader)
    # ===========================
    # JA:   HTML, Textdateien, Apache-Directory-Listings
      mod_gzip_item_include         mime       ^text/html$
      mod_gzip_item_include         mime       ^text/plain$
      mod_gzip_item_include         mime       ^httpd/unix-directory$
    #
    # NEIN: Bilder (GIF etc., das bringt fast nie etwas)
      mod_gzip_item_exclude         mime       ^image/
    # ---------------------------------------------------------------------
    # Tatsächlich prüft mod_gzip jeweils nur die ersten 4 Zeichen
    # des 1. Operanden (im Falle von uri sogar nur die ersten 2 Zeichen,
    # um auch Werte wie url zu erlauben).
    # ---------------------------------------------------------------------
    # Die Tabelle der mod_gzip_item-Regeln (include und exclude) kann nicht
    # mehr als 256 Einträge aufnehmen; wird diese Anzahl überschritten,
    # dann gibt mod_gzip die Meldung "mod_gzip: ERROR: Item index is full"
    # aus und meldet einen Konfigurationsfehler an den Apache-Server.
    # ---------------------------------------------------------------------
    # Die hier beschriebenen Werte der Direktiven sind darauf ausgelegt,
    # die zu komprimierenden Anforderungen möglichst exakt zu beschreiben.
    # Gerade bei den mime-Regeln sei jedoch angemerkt, daß der (von
    # mod_gzip für diese Regel ausgewertete) HTTP-Header 'Content-Type' in
    # einigen Fällen nicht nur einen MIME-Type, sondern zusätzlich auch
    # eine Zeichensatzbeschreibung (charset) enthält.
    # Sollte dies bei den zu verarbeitenden Anforderungen der Fall sein,
    # dann muß das Zeichen '$' am Ende des jeweiligen Wertes entfernt
    # werden, so daß nun nur noch der Präfix dieses Wertes auf
    # Übereinstimmung geprüft wird.
    # ---------------------------------------------------------------------

    ##########################
    ### Transfer-Kodierung ###
    ##########################

    # ---------------------------------------------------------------------
    # Erlaube mod_gzip, den HTTP-Header-Eintrag
    #    'Transfer-encoding: chunked'
    # zu eliminieren und zu einem (komprimierbaren) Paket zusammenzufassen
      mod_gzip_dechunk              Yes
    # Das wird für diverse dynamisch generierte Inhalte benötigt, vor allem
    # für CGI- und SSI-Seiten, aber auch für Seiten, die durch Java-
    # Servlet-Interpretern etc. erzeugt werden.
    # ---------------------------------------------------------------------

    #######################
    ### Protokollierung ###
    #######################

    # ---------------------------------------------------------------------
    # erweiterte Protokoll-Format-Schablone (zum Test der Komprimierungswirkung)
      LogFormat                     "%h %l %u %t \"%V %r\" %<s %b mod_gzip: %{mod_gzip_result}n In:%{mod_gzip_input_size}n -< Out:%{mod_gzip_output_size}n = %{mod_gzip_compression_ratio}n Prozent." common_with_mod_gzip_info2
    # ---------------------------------------------------------------------
    # zusätzliche Protokolldatei erzeugen
      CustomLog                     logs/mod_gzip.log common_with_mod_gzip_info2
    # (man kann natürlich auch sein normales Logfile umdefinieren, aber
    #  das will man ggf. formatkompatibel für die Auswertung mit Standard-
    # Web-Analysetools behalten. Also machen wir uns einfach noch ein Logfile.)
    # ---------------------------------------------------------------------
    # Volumenberechnung der ausgelieferten Dateien im Apache-access_log:
    # Größe des HTTP-Headers in Bytes bei der Ausgabe mitzählen
      mod_gzip_add_header_count     Yes
    # (das ist dann mehr als der reine Dokument-Inhalt, es beschreibt aber
    #  den tatsächlich verursachten Traffic des gesamten HTTP-Requests
    #  realistischer)
    # ---------------------------------------------------------------------

    ###############
    ### Proxies ###
    ###############

    # ---------------------------------------------------------------------
    # Senden eines 'Vary'-HTTP-Headers
      mod_gzip_send_vary            Yes
    # (siehe Kapitel über Caching zu dieser Direktive.)
    #  Nicht ändern, ohne genau zu wissen, was man tut!
    # ---------------------------------------------------------------------

      </IfModule>

Bei dynamischer Einbindung dieses Moduls ist vor allem zu beachten, daß `mod_gzip` bei mehreren vorliegenden `LoadModule`-Anweisungen als letzte angegeben werden sollte.

Apache baut nämlich aus den `LoadModule`-Anweisungen intern einen Stapel, der später in umgekehrter Reihenfolge ausgewertet wird.

`mod_gzip` hängt sich in die interne `type_checker`-Routine des Apache; von allen Modulen, die dies tun (z. B. auch ColdFusion und SSL), wird aber nur die erste, die sich selbst als zuständig für die Bearbeitung einer Anforderung erklärt, wirklich von Apache aufgerufen. `mod_gzip` muß also inbesondere vor denjenigen Modulen aktiviert werden, deren Ausgabe es zu sich selbst umleiten und dann nachverarbeiten können soll - sofern diese Module selbst ebenfalls die `type_checker`-Schnittstelle benutzen ... tun sie das nicht, dann kann es auch unabhängig von der Reihenfolge dieser Anweisungen funktionieren.

In der Startmeldung von Apache (die u. a. im Apache-Error-Log zu finden ist) werden Module, welche eine eigene Versionskennung besitzen, ggf. aufgezählt, und zwar in derjenigen Reihenfolge, in der sie in der Modul-Kette vorliegen; dort muß `mod_gzip` also vor anderen Modulen auftauchen, deren Ausgaben es komprimieren soll.

Ich selbst habe `mod_gzip` im Unterverzeichnis `src/modules/extra/` des Apache-Quelltext statisch übersetzt; das Apache-Konfigurationsskript `configure` weiß, was es in diesem Fall zu tun hat.

(Michael Schröpl, 2002-09-28)