<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>An example configuration for mod_gzip</title>
<meta name="author" content="Michael Schröpl" />
<meta name="description" content="An extensively documented example configuration for the Apache add-on module 'mod_gzip'" />
<meta name="keywords" content="Apache, HTTP, encoding, gzip, compression, configuration" />
<style type="text/css">
body{font-family:sans-serif;margin:0px 30px 0px 30px;}
h1{font-size:22px;margin-top:20px;}
h2{font-size:18px;margin-top:14px;}
small{font-size:80%;}
td{vertical-align:top;}
tt{font-weight:bold;}
code,tt{font-family:"Courier New",monospace;}
h1,h2{margin-bottom:1px;}
p,td{margin-top:3px;margin-bottom:3px;}
p,ul,ol,li{font-size:17px;line-height:22px;}
ul,ol,li{margin-top:0px;margin-bottom:0px;}
img{border-width:0;}
#nav{position:absolute;top:30px;left:0px;font-size:14px;width:170px;font-weight:bold;margin:2px 2px 2px 30px;}
#nav[id]{position:fixed;}
#nav img{margin:5px;}
#nav p, #nav a:hover, #nav a{display:block;padding:3px;margin:2px;width:150px;font-size:15px;line-height:18px;}
#content{position:absolute;left:220px;right:30px;}
#mail{text-align:right;}
#icon{width:190px;float:left;}
#mail,#icon{margin-top:30px;}
@media screen {
body{color:#000;background-color:#f8ebd9;}
h1{color:#666;}
h2{color:#840;}
code{color:#333;}
em{color:#900;}
tt{color:#909;}
h1,h2,code,em,tt{background-color:inherit;}
.new13192a{color:#inherit;background-color:#ffd;}
.new13261a{color:#inherit;background-color:#eff;}
.bugfix{color:#fff;background-color:#f00;font-weight:bold;padding:0px 4px;}
#nav a{color:#530;background-color:transparent;}
#nav a{text-decoration:none;}
#nav p, #nav a:hover{color:#000;background-color:#fff;}
#nav p {border:1px #660 solid;}
#nav a {border:1px #666 dotted;}
}
@media print {
#icon,#nav{display:none;}
#content{position:absolute;left:0px;right:0px;}
}
table.sections{margin-top:20px;}
table.sections td{border:solid 1px #55f;font-size:12px;padding:2px;}
table.sections td a{display:block;}
@screen {
table.sections td{color:#000;background-color:#eee;}
table.sections td a{color:#00f;background-color:transparent;}
}
pre{font-family:monospace;font-size:14px;}
pre strong{font-weight:bold;}
@media screen {
pre{color:#336;}
pre strong{color:#00c;}
pre, pre strong{background-color:inherit;}
}
</style>
</head>
<body>
<div id="nav">
<img src="mod_gzip_logo.gif" height="47" width="102" alt="mod_gzip logo" />
<a title="mod_gzip - what's that, anyway?" href="index.htm">mod_gzip</a>
<a title="Compression of HTTP content using Content-Encoding" href="encoding.htm">Content-Encoding</a>
<a title="Which browsers can handle 'Content-Encoding: gzip'?" href="browser.htm">Browsers</a>
<a title="How do Firewalls handle 'Content-Encoding:'?" href="firewalls.htm">Firewalls</a>
<p>Configuration</p>
<a title="Complete description of mod_gzip status codes" href="status.htm">Status Codes</a>
<a title="Possible enhancements in future versions of mod_gzip" href="enhancements.htm">Enhancements</a>
<a title="Caching of negotiated HTTP responses" href="cache.htm">Caching</a>
<a title="Version history and change log for mod_gzip" href="versions.htm">Versions</a>
<a title="Other ressources about mod_gzip" href="links.htm">Links</a>
</div>
<div id="content">
<h1>An example configuration for <tt>mod_gzip</tt></h1>
<p>The exact amount of the requested functions is to be described by additional <em>Apache configuration directives</em> which become available by the <tt>mod_gzip</tt> module integration.</p>
<p>A really complete documentation of the effect of these directives isn't available at the moment; in general assume that</p>
<ul>
<li>about everything can be used in every environment, i. e.
<ul>
<li>in the complete server scope,</li>
<li>in separate virtual hosts,</li>
<li>in directories or even</li>
<li>in <code>.htaccess</code> files</li>
</ul> and
</li>
<li>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.</li>
</ul>
<p>The configuration described below really <em>isn't</em> 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 <em>lots</em> of options - at least if you 'just want to get compressed output data' ...</p>
<table class="sections">
<tr>
<td><a href="#loading">loading</a></td>
<td><a href="#responsibilities">responsibilities</a></td>
<td><div class="new13261a"><a href="#precompressed">precompressed</a></div></td>
<td><a href="#bureaucracy">bureaucracy</a></td>
<td><a href="#data_management">data management</a></td>
<td><a href="#file_sizes">file sizes</a></td>
<td><div class="new13261a"><a href="#requirements">requirements</a></div></td>
<td><a href="#filters">filters</a></td>
<td><a href="#transfer_encoding">transfer encoding</a></td>
<td><a href="#logging">logging</a></td>
<td><div class="new13192a"><a href="#proxy">proxies</a></div></td>
</tr>
</table>
<pre>
#######################################
### Apache configuration directives ###
### for mod_gzip 1.3.26.1a ###
#######################################
<a id="loading"></a>
##########################
### 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;
<div class="new13192a"># the exact file name may depend upon the exact compilation method used
# for this module)
</div># ---------------------------------------------------------------------
<strong><IfModule mod_gzip.c></strong>
<a id="responsibilities"></a>
########################
### responsibilities ###
########################
# ---------------------------------------------------------------------
# use mod_gzip at all?
<strong>mod_gzip_on Yes</strong>
# (you can especially enable mod_gzip inside the central server
# configuration but disable it inside some directories ot virtual
# hosts by using this directive.)
# ---------------------------------------------------------------------
<a id="precompressed"></a>
######################################
### statically precompressed files ###
######################################
# ---------------------------------------------------------------------
# let mod_gzip perform 'partial content negotiation'?
<strong>mod_gzip_can_negotiate Yes</strong>
# (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.
<div class="new13192a"># 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 ...)
</div># ---------------------------------------------------------------------
<div class="new13192a"># extension (suffix) for statically precompressed files
<strong>mod_gzip_static_suffix .gz</strong>
<strong>AddEncoding gzip .gz</strong>
# (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.)
</div># ---------------------------------------------------------------------
<div class="new13261a"># automatic updates for statically precompressed files
<strong>mod_gzip_update_static No</strong>
# (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 <em>overwrite</em> 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 <em>cannot</em> be interpreted by any other Apache module
# during the request. this might possibly <em>not</em> be what you want - hopefully
# it will be what most users want, because it works <em>fast</em> 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 <em>isn't</em> 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?]
</div># ---------------------------------------------------------------------
<a id="bureaucracy"></a>
###################
### bureaucracy ###
###################
# ---------------------------------------------------------------------
# display status for mod_gzip
<strong>mod_gzip_command_version '/mod_gzip_status'</strong>
# (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)
# ---------------------------------------------------------------------
<a id="data_management"></a>
#######################
### 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]
# <strong>mod_gzip_temp_dir /tmp</strong>
# (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]
<strong>mod_gzip_keep_workfiles No</strong>
# (one file per HTTP request - set to 'yes' for debugging purpose only!)
# ---------------------------------------------------------------------
<a id="file_sizes"></a>
##################
### file sizes ###
##################
# ---------------------------------------------------------------------
# minimum size (in bytes) for files to be compressed
<strong>mod_gzip_minimum_file_size 500</strong>
# (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
<strong>mod_gzip_maximum_file_size 500000</strong>
# (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
<strong>mod_gzip_maximum_inmem_size 60000</strong>
# (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.
# ---------------------------------------------------------------------
<a id="requirements"></a>
####################
### requirements ###
####################
# (see chapter about <a href="cache.htm#vary-1.3.19.2a">caching</a> 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
<strong>mod_gzip_min_http 1000</strong>
# (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.)
# ---------------------------------------------------------------------
<div class="new13192a"># HTTP methods to be handled
# Possible values: 'GET', 'POST' or a list of both values.
<strong>mod_gzip_handle_methods GET POST</strong>
# (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.)
</div># ---------------------------------------------------------------------
<a id="filters"></a>
###############
### 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) <em>must match at least one include rule in each of both phases</em> and
# b) <em>must not match an exclude rule in any of both phases.</em>
# These rules are not minimal, they are meant to serve as example only.
#
# phase 1: (reqheader, uri, file, handler)
# ========================================
# (see chapter about <a href="cache.htm#useragent">caching</a> 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
<strong>mod_gzip_item_exclude reqheader "User-agent: Mozilla/4.0[678]"</strong>
#
# JA: HTML-Dokumente
<strong>mod_gzip_item_include file \.html$</strong>
#
# NO: include files / JavaScript & CSS (due to Netscape4 bugs)
<strong>mod_gzip_item_exclude file \.js$</strong>
<strong>mod_gzip_item_exclude file \.css$</strong>
#
# YES: CGI scripts
<strong>mod_gzip_item_include file \.pl$</strong>
<strong>mod_gzip_item_include handler ^cgi-script$</strong>
#
# phase 2: (mime, rspheader)
# ===========================
# YES: normal HTML files, normal text files, Apache directory listings
<strong>mod_gzip_item_include mime ^text/html$</strong>
<strong>mod_gzip_item_include mime ^text/plain$</strong>
<strong>mod_gzip_item_include mime ^httpd/unix-directory$</strong>
#
# NO: images (GIF etc., will rarely ever save anything)
<strong>mod_gzip_item_exclude mime ^image/</strong>
# ---------------------------------------------------------------------
# In fact mod_gzip is checking only the first 4 characters of the 1st
# operand (in case of <strong>uri</strong> even the first 2 characters only, as to
# allow for values like <strong>url</strong>).
# ---------------------------------------------------------------------
# The table for mod_gzip_item rules (<strong>include</strong> and <strong>exclude</strong>) cannot contain
# more than 256 entries; when this number is exceeded mod_gzip will
# output the message <cite>"mod_gzip: ERROR: Item index is full"</cite>
# and report a configuration error to the Apache server.
# ---------------------------------------------------------------------
# The directive values described here are meant to describe the requests
# elected for compression <em>most exactly</em>.
# Especially for the <strong>mime</strong> 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.
# ---------------------------------------------------------------------
<a id="transfer_encoding"></a>
##########################
### transfer encodings ###
##########################
# ---------------------------------------------------------------------
# Allow mod_gzip to eliminate the HTTP header
# 'Transfer-encoding: chunked'
# and join the chunks to one (compressable) packet
<strong>mod_gzip_dechunk Yes</strong>
# (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.
# ---------------------------------------------------------------------
<a id="logging"></a>
###############
### logging ###
###############
# ---------------------------------------------------------------------
# Extended log format (for testing the compression effect)
<strong>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</strong>
# ---------------------------------------------------------------------
# Create additional log file
<strong>CustomLog logs/mod_gzip.log common_with_mod_gzip_info2</strong>
# (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
<strong>mod_gzip_add_header_count Yes</strong>
# (This will be more than the pure document content, but it will more
# realistically describe the total output traffic of the HTTP request)
# ---------------------------------------------------------------------
<a id="proxy"></a>
<div class="new13192a">###############
### proxies ###
###############
# ---------------------------------------------------------------------
# sending a 'Vary' HTTP header
<strong>mod_gzip_send_vary Yes</strong>
# (see chapter about <a href="cache.htm#vary-1.3.19.2a">caching</a> for this directive.)
# <em>don't change this unless you absolutely know what you are doing!</em>
# ---------------------------------------------------------------------
</div>
<strong></IfModule></strong>
</pre>
<p><a id="LoadModule"></a>When adding this module dynamically you have to keep in mind that <tt>mod_gzip</tt> should be specified as <em>last one</em> of several <code>LoadModule</code> directives to be used.</p>
<p>This is because Apache will internally build a stack from the <code>LoadModule</code> directives and later evaluate it <em>in reverse order</em>.</p>
<p><tt>mod_gzip</tt> hooks itself into the internal <code>type_checker</code> routine of Apache; but only the <em>first</em> of all modules declaring itself as responsible for handling of a request <small>(e. g. ColdFusion and SSL will try to)</small> will really be activated by Apache. So <tt>mod_gzip</tt> has to be activated <em>before</em> those modules whose output it wants to redirect into itself and then postprocess - as long as these modules try to use the same <code>type_checker</code> interface ... if they don't, then it <em>may</em> work independently from this order of directives.</p>
<p>During Apache's start message <small>(which can be found e. g. inside the Apache error log)</small> modules having individual version specifications may be listed exactly in the order they appear inside the module chain; there <tt>mod_gzip</tt> has to be listed <em>before</em> other modules whose output it is intended to compress.</p>
<p>I myself statically compiled <tt>mod_gzip</tt> inside the subdirectory <code>src/modules/extra/</code> of the Apache source code; the Apache configuration script <code>configure</code> just knows what to do in this case.</p>
<div id="icon">
<a href="http://validator.w3.org/check/referer"><img alt="" title="valid XHTML 1.1" height="31" width="88" src="valid-xhtml11.png" /></a><a href="http://jigsaw.w3.org/css-validator/check/referer"><img alt="" title="valid CSS" height="31" width="88" src="valid-css.png" /></a>
</div>
<p id="mail">(<a href="mailto:michael.schroepl@gmx.de?subject=mod_gzip">Michael Schröpl</a>, 2002-09-30)</p>
</div>
</body>
</html>
