An example configuration for mod_gzip
Author: Michael Schröpl
Description: An extensively documented example configuration for the Apache add-on module 'mod_gzip'
Keywords: Apache, HTTP, encoding, gzip, compression, configuration

# An example configuration for `mod_gzip`

The exact amount of the requested functions is to be described by additional Apache configuration directives which become available by the `mod_gzip` module integration.

A really complete documentation of the effect of these directives isn't available at the moment; in general assume that

- about everything can be used in every environment, i. e.
  - in the complete server scope,
  - in separate virtual hosts,
  - in directories or even
  - in `.htaccess` files
  and
- basically the standard overwriting procedures of Apache apply - except for the directives to specify the selection of contents to be compressed, where things become a bit more complicated.

The configuration described below really isn't meant for blindly copying into your own configuration - its intention rather is to give you a feeling about how many options are provided. And there are lots of options - at least if you 'just want to get compressed output data' ...

loading | responsibilities | precompressed | bureaucracy | data management | file sizes | requirements | filters | transfer encoding | logging | proxies

    #######################################
    ### Apache configuration directives ###
    ###   for mod_gzip 1.3.26.1a        ###
    #######################################

    ##########################
    ### loading the module ###
    ##########################

    # ---------------------------------------------------------------------
    # load DLL / Win32:
    # LoadModule gzip_module modules/ApacheModuleGzip.dll
    #
    # load DSO / UNIX:
    # LoadModule gzip_module modules/mod_gzip.so
    #
    # (none of both if module has been compiled in statically;
    #  the exact file name may depend upon the exact compilation method used
    #  for this module)
    # ---------------------------------------------------------------------

      <IfModule mod_gzip.c>

    ########################
    ### responsibilities ###
    ########################

    # ---------------------------------------------------------------------
    # use mod_gzip at all?
      mod_gzip_on                   Yes
    # (you can especially enable mod_gzip inside the central server
    #  configuration but disable it inside some directories ot virtual
    #  hosts by using this directive.)
    # ---------------------------------------------------------------------

    ######################################
    ### statically precompressed files ###
    ######################################

    # ---------------------------------------------------------------------
    # let mod_gzip perform 'partial content negotiation'?
      mod_gzip_can_negotiate        Yes
    # (if this option is active and a static file is to be served in com-
    #  pressed for, then mod_gzip will look for a static precompressed
    #  version of this file with a defined additional extension - see next
    #  directive - which would be delivered with priority. This would allow
    #  for avoiding to repeatedly compress the same static file and thus
    #  saving CPU time.
    #  No dynamic caching of this file is provided; currently the user
    #  himself is responsible for creating and updating the precompressed
    #  file's content.
    #  From version 1.3.19.2a mod_gzip automatically recognizes whether
    #  a statically precompressed file is older than its uncompressed
    #  original and in this case will serve the content of the original
    #  file in uncompressed form - as to rather serve correct data than
    #  outdated ones ...)
    # ---------------------------------------------------------------------
    # extension (suffix) for statically precompressed files
      mod_gzip_static_suffix        .gz
      AddEncoding              gzip .gz
    # (effect: see previous directive; this string will be appended to the
    #  name of the original file.
    #  be sure to configure the encoding 'gzip' for this extension as well,
    #  because mod_gzip doesn't serve the content itself but simply generates
    #  an Apache internal redirection to this URL. Therefore the remaining
    #  Apache configuration is responsible for setting the 'Content-Encoding'
    #  header properly ...
    #  prior to version 1.3.19.2a this value was not configurable.)
    # ---------------------------------------------------------------------
    # automatic updates for statically precompressed files
      mod_gzip_update_static        No
    # (if set to 'Yes', this directive (being new in version 1.3.26.1a) would
    # cause mod_gzip to automatically update an outdated version of any
    # statically precompressed file during the request, i. e. compress the
    # originally requested file and overwrite the precompressed variant
    # file with it!
    # for each automatic update of this type, mod_gzip will write a message
    # of the severity 'notice' into the Apache error_log.
    # while doing so, mod_gzip will directly read the original file's content.
    # therefore this content cannot be interpreted by any other Apache module
    # during the request. this might possibly not be what you want - hopefully
    # it will be what most users want, because it works fast this way.
    # use this configuration with a lot of care, and be sure that you don't
    # inadvertantly cause valuable files within the URL tree to be overwritten.
    # this isn't a feature to be used for mass hosting servers, especially
    # because mod_gzip might experience access control problems there - the
    # userid the Apache processes are running under need to have write access
    # to the precompressed files of all users, which may not automatically be
    # the case.)
    # [mod_gzip error handling in this situation??? what will be served?]
    # ---------------------------------------------------------------------

    ###################
    ### bureaucracy ###
    ###################

    # ---------------------------------------------------------------------
    # display status for mod_gzip
      mod_gzip_command_version      '/mod_gzip_status'
    # (defines an URL to display the status of mod_gzip; can be specified
    # individually for each installation and protected against access via
    # <Location> section for privacy reasons)
    # ---------------------------------------------------------------------
    # The status display will look like this:
    #       mod_gzip is available...
    #       mod_gzip_version = 1.3.26.1a
    #       mod_gzip_on = Yes/No
    # and thus will provide information about
    # - mod_gzip being installed at the server and working correctly,
    # - which version has been installed and
    # - whether mod_gzip has been set 'active' for this Location
    #   (-> mod_gzip_on)
    # ---------------------------------------------------------------------

    #######################
    ### data management ###
    #######################

    # ---------------------------------------------------------------------
    # Working directory for temporary files and the compression cache
    # if not specified, the following default values are used:
    # [Win32=c:\temp], [UNIX=/tmp]
    # mod_gzip_temp_dir             /tmp
    # (This directory must already exist and the userid being used for
    #  running the Apache server must have read and write access to this
    #  directory.
    #  Unlike other Apache directives an absolute path name must be specified
    #  here; a relative value will not be interpreted relatively to ServerRoot.
    #  This pastname must NOT be terminated with '/'.
    #  For maximum performance this directory should be located on a RAM disk,
    #  if the file system isn't already being cached efficiently
    # ---------------------------------------------------------------------
    # Save temporary work files [Yes, No]
      mod_gzip_keep_workfiles       No
    # (one file per HTTP request - set to 'yes' for debugging purpose only!)
    # ---------------------------------------------------------------------

    ##################
    ### file sizes ###
    ##################

    # ---------------------------------------------------------------------
    # minimum size (in bytes) for files to be compressed
      mod_gzip_minimum_file_size    500
    # (for very small files compression will produce only small absolute gains
    #  [you will still save about 50% of the content, but some additional
    #  500 bytes of HTTP and TCP headers will always remain uncompressed],
    #  but still produce CPU load for both client and server)
    # ---------------------------------------------------------------------
    # maximum size (in bytes) for files to be compressed
      mod_gzip_maximum_file_size    500000
    # (for very large files compression may eventually take rather long and
    #  thus delay the start of the transmission.
    #  Furthermode a limitation at this point prevents the server from
    #  producing output of unlimited size in case of some endless loop
    #  inside a CGI script - or even trying to compress streaming data -
    #  which might otherwise cause the creation of a temporary file of
    #  any size and even fill up the whole hard disk.
    #  On the other hand, compression will have a much more perceivable
    #  subjective effect for large files ... so be sure to fine-tune this
    #  according to your requirements.)
    # ---------------------------------------------------------------------
    # maximum size (in bytes) for files to be compressed in memory
      mod_gzip_maximum_inmem_size   60000
    # (larger files will be compressed into the temp file directory; adapt
    #  this value to your server's available main memory.
    #  In mod_gzip 1.3.19.x larger values will automatically be limited to
    #  60000 because some operating systems are said to have problems
    #  allocating more than 64 kb of memory at a time.
    # ---------------------------------------------------------------------

    ####################
    ### requirements ###
    ####################

    # (see chapter about caching for problems when using these directives.)
    # ---------------------------------------------------------------------
    # Required HTTP version of the client
    # Possible values: 1000 = HTTP/1.0, 1001 = HTTP/1.1, ...
    # This directive uses the same numeric protocol values as Apache does
    # internally
      mod_gzip_min_http             1000
    # (By using this directive you may exclude old browsers, search engines
    #  etc. from the compression procedure: if the user agent doesn't
    #  declare itself capable of understanding at least the HTTP level
    #  specified here, only uncompressed data will be delivered - no matter
    #  what else it claims to be able to. The value of '1001' will especially
    #  exclude Netscape 4.x. and a lot of proxy servers.)
    # ---------------------------------------------------------------------
    # HTTP methods to be handled
    # Possible values: 'GET', 'POST' or a list of both values.
      mod_gzip_handle_methods        GET POST
    # (By using this directive you may particularly exclude POST requests
    #  from the compression procedure. There are known cases where the
    #  handling of these requests by previous mod_gzip versions could cause
    #  problems.
    #  Before version 1.3.19.2a this value was not configurable.)
    # ---------------------------------------------------------------------

    ###############
    ### filters ###
    ###############

    # ---------------------------------------------------------------------
    # which files are to be compressed?
    #
    # The order of processing during each of both phases is not important,
    # but to trigger the compression of a request's content this request
    # a) must match at least one include rule in each of both phases and
    # b) must not match an exclude rule in any of both phases.
    # These rules are not minimal, they are meant to serve as example only.
    #
    # phase 1: (reqheader, uri, file, handler)
    # ========================================
    # (see chapter about caching for problems when using 'reqheader' type
    #  filter rules.)
    # NO:   special broken browsers which request for gzipped content
    #       but then aren't able to handle it correctly
      mod_gzip_item_exclude         reqheader  "User-agent: Mozilla/4.0[678]"
    #
    # JA:   HTML-Dokumente
      mod_gzip_item_include         file       \.html$
    #
    # NO:   include files / JavaScript & CSS (due to Netscape4 bugs)
      mod_gzip_item_exclude         file       \.js$
      mod_gzip_item_exclude         file       \.css$
    #
    # YES:  CGI scripts
      mod_gzip_item_include         file       \.pl$
      mod_gzip_item_include         handler    ^cgi-script$
    #
    # phase 2: (mime, rspheader)
    # ===========================
    # YES:  normal HTML files, normal text files, 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$
    #
    # NO:   images (GIF etc., will rarely ever save anything)
      mod_gzip_item_exclude         mime       ^image/
    # ---------------------------------------------------------------------
    # In fact mod_gzip is checking only the first 4 characters of the 1st
    # operand (in case of uri even the first 2 characters only, as to
    # allow for values like url).
    # ---------------------------------------------------------------------
    # The table for mod_gzip_item rules (include and exclude) cannot contain
    # more than 256 entries; when this number is exceeded mod_gzip will
    # output the message "mod_gzip: ERROR: Item index is full"
    # and report a configuration error to the Apache server.
    # ---------------------------------------------------------------------
    # The directive values described here are meant to describe the requests
    # elected for compression most exactly.
    # Especially for the mime rules it has to be made clear that the HTTP
    # header 'Content-Type' (that will be checked by mod_gzip for this rule)
    # in some cases may contain not only a MIME type but additionally a
    # character set description (charset) as well.
    # If this is the case for the requests to be handled then you need to
    # remove the '$' char at the end of the corresponding value so that now
    # only the prefix of this value will be tested for matching.
    # ---------------------------------------------------------------------

    ##########################
    ### transfer encodings ###
    ##########################

    # ---------------------------------------------------------------------
    # Allow mod_gzip to eliminate the HTTP header
    #    'Transfer-encoding: chunked'
    # and join the chunks to one (compressable) packet
      mod_gzip_dechunk              Yes
    # (this is required for handling several types of dynamically generated
    # contents, especially for CGI and SSI pages, but also for pages produced
    # by some Java Servlet interpreters.
    # ---------------------------------------------------------------------

    ###############
    ### logging ###
    ###############

    # ---------------------------------------------------------------------
    # Extended log format (for testing the compression effect)
      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 pct." common_with_mod_gzip_info2
    # ---------------------------------------------------------------------
    # Create additional log file
      CustomLog                     logs/mod_gzip.log common_with_mod_gzip_info2
    # (surely you can redefine your normal log file format, but you mal well
    #  keep its format standard compatible for evaluation by standard web
    #  analysis tools. So we just create another log file.)
    # ---------------------------------------------------------------------
    # Volume computation of the delivered files inside the Apache access_log:
    # count HTTP header size (in bytes) as part of total output size
      mod_gzip_add_header_count     Yes
    # (This will be more than the pure document content, but it will more
    #  realistically describe the total output traffic of the HTTP request)
    # ---------------------------------------------------------------------

    ###############
    ### proxies ###
    ###############

    # ---------------------------------------------------------------------
    # sending a 'Vary' HTTP header
      mod_gzip_send_vary            Yes
    # (see chapter about caching for this directive.)
    #  don't change this unless you absolutely know what you are doing!
    # ---------------------------------------------------------------------

      </IfModule>

When adding this module dynamically you have to keep in mind that `mod_gzip` should be specified as last one of several `LoadModule` directives to be used.

This is because Apache will internally build a stack from the `LoadModule` directives and later evaluate it in reverse order.

`mod_gzip` hooks itself into the internal `type_checker` routine of Apache; but only the first of all modules declaring itself as responsible for handling of a request (e. g. ColdFusion and SSL will try to) will really be activated by Apache. So `mod_gzip` has to be activated before those modules whose output it wants to redirect into itself and then postprocess - as long as these modules try to use the same `type_checker` interface ... if they don't, then it may work independently from this order of directives.

During Apache's start message (which can be found e. g. inside the Apache error log) modules having individual version specifications may be listed exactly in the order they appear inside the module chain; there `mod_gzip` has to be listed before other modules whose output it is intended to compress.

I myself statically compiled `mod_gzip` inside the subdirectory `src/modules/extra/` of the Apache source code; the Apache configuration script `configure` just knows what to do in this case.

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