Apache HTTP Server Version 2.0
Apache HTTP Server Version 2.0
Configuring Apache to listen on specific addresses and ports.
| Related Modules | Related Directives |
|---|---|
When Apache starts, it binds to some port and address on the local machine and waits for incoming requests. By default, it listens to all addresses on the machine. However, it needs to be told to listen on specific ports, or to listen on only selected addresses, or a combination. This is often combined with the Virtual Host feature which determines how Apache responds to different IP addresses, hostnames and ports.
The Listen
directive tells the server to accept
incoming requests only on the specified port or
address-and-port combinations. If only a port number is
specified in the Listen
directive, the server
listens to the given port on all interfaces. If an IP address
is given as well as a port, the server will listen on the given
port and interface. Multiple Listen directives may be used to
specify a number of addresses and ports to listen on. The
server will respond to requests from any of the listed
addresses and ports.
For example, to make the server accept connections on both port 80 and port 8000, use:
Listen 80
Listen 8000
To make the server accept connections on two specified interfaces and port numbers, use
Listen 192.170.2.1:80
Listen 192.170.2.5:8000
IPv6 addresses must be surrounded in square brackets, as in the following example:
Listen [2001:db8::a00:20ff:fea7:ccea]:80
A growing number of platforms implement IPv6, and APR supports IPv6 on most of these platforms, allowing Apache to allocate IPv6 sockets and handle requests which were sent over IPv6.
One complicating factor for Apache administrators is whether or
not an IPv6 socket can handle both IPv4 connections and IPv6
connections. Handling IPv4 connections with an IPv6 socket uses
IPv4-mapped IPv6 addresses, which are allowed by default on most
platforms but are disallowed by default on FreeBSD, NetBSD, and
OpenBSD in order to match the system-wide policy on those
platforms. But even on systems where it is disallowed by default, a
special configure parameter can change this behavior
for Apache.
If you want Apache to handle IPv4 and IPv6 connections with a
minimum of sockets, which requires using IPv4-mapped IPv6 addresses,
specify the --enable-v4-mapped configure
option and use generic Listen
directives like the following:
Listen 80
With --enable-v4-mapped, the Listen directives in the
default configuration file created by Apache will use this form.
--enable-v4-mapped is the default on all platforms but
FreeBSD, NetBSD, and OpenBSD, so this is probably how your Apache was
built.
If you want Apache to handle IPv4 connections only, regardless of
what your platform and APR will support, specify an IPv4 address on all
Listen directives, as in the
following examples:
Listen 0.0.0.0:80
Listen 192.170.2.1:80
If you want Apache to handle IPv4 and IPv6 connections on separate
sockets (i.e., to disable IPv4-mapped addresses), specify the
--disable-v4-mapped configure option and
use specific Listen directives like the following:
Listen [::]:80
Listen 0.0.0.0:80
With --disable-v4-mapped, the Listen directives in the
default configuration file created by Apache will use this form.
--disable-v4-mapped is the default on FreeBSD, NetBSD, and
OpenBSD.
Listen does not implement
Virtual Hosts. It only tells the main server what addresses and ports to
listen to. If no <VirtualHost> directives are used, the server will behave
the same for all accepted requests. However,
<VirtualHost>
can be used to specify a different behavior
for one or more of the addresses and ports. To implement a
VirtualHost, the server must first be told to listen to the
address and port to be used. Then a
<VirtualHost> section
should be created for a specified address and port to set the
behavior of this virtual host. Note that if the
<VirtualHost>
is set for an address and port that the
server is not listening to, it cannot be accessed.
Apache HTTP Server Version 2.0
This document describes the files used to configure the Apache HTTP server.
| Related Modules | Related Directives |
|---|---|
Apache is configured by placing directives in plain text
configuration files. The main configuration file is usually called
httpd.conf. The location of this file is set at
compile-time, but may be overridden with the -f
command line flag. In addition, other configuration files may be
added using the Include
directive, and wildcards can be used to include many configuration
files. Any directive may be placed in any of these configuration
files. Changes to the main configuration files are only
recognized by Apache when it is started or restarted.
The server also reads a file containing mime document types;
the filename is set by the TypesConfig directive,
and is mime.types by default.
Apache configuration files contain one directive per line. The back-slash "\" may be used as the last character on a line to indicate that the directive continues onto the next line. There must be no other characters or white space between the back-slash and the end of the line.
Directives in the configuration files are case-insensitive, but arguments to directives are often case sensitive. Lines that begin with the hash character "#" are considered comments, and are ignored. Comments may not be included on a line after a configuration directive. Blank lines and white space occurring before a directive are ignored, so you may indent directives for clarity.
You can check your configuration files for syntax errors
without starting the server by using apachectl
configtest or the -t command line
option.
| Related Modules | Related Directives |
|---|---|
Apache is a modular server. This implies that only the most
basic functionality is included in the core server. Extended
features are available through modules which can be loaded
into Apache. By default, a base set of modules is
included in the server at compile-time. If the server is
compiled to use dynamically loaded
modules, then modules can be compiled separately and added at
any time using the LoadModule
directive.
Otherwise, Apache must be recompiled to add or remove modules.
Configuration directives may be included conditional on a
presence of a particular module by enclosing them in an <IfModule> block.
To see which modules are currently compiled into the server,
you can use the -l command line option.
| Related Modules | Related Directives |
|---|---|
Directives placed in the main configuration files apply to
the entire server. If you wish to change the configuration for
only a part of the server, you can scope your directives by
placing them in <Directory>, <DirectoryMatch>, <Files>, <FilesMatch>, <Location>, and <LocationMatch>
sections. These sections limit the application of the
directives which they enclose to particular filesystem
locations or URLs. They can also be nested, allowing for very
fine grained configuration.
Apache has the capability to serve many different websites
simultaneously. This is called Virtual
Hosting. Directives can also be scoped by placing them
inside <VirtualHost>
sections, so that they will only apply to requests for a
particular website.
Although most directives can be placed in any of these sections, some directives do not make sense in some contexts. For example, directives controlling process creation can only be placed in the main server context. To find which directives can be placed in which sections, check the Context of the directive. For further information, we provide details on How Directory, Location and Files sections work.
| Related Modules | Related Directives |
|---|---|
Apache allows for decentralized management of configuration
via special files placed inside the web tree. The special files
are usually called .htaccess, but any name can be
specified in the AccessFileName
directive. Directives placed in .htaccess files
apply to the directory where you place the file, and all
sub-directories. The .htaccess files follow the
same syntax as the main configuration files. Since
.htaccess files are read on every request, changes
made in these files take immediate effect.
To find which directives can be placed in
.htaccess files, check the Context of the
directive. The server administrator further controls what
directives may be placed in .htaccess files by
configuring the AllowOverride
directive in the main configuration files.
For more information on .htaccess files, see
the .htaccess tutorial.
Apache HTTP Server Version 2.0
Apache supports content negotiation as described in the HTTP/1.1 specification. It can choose the best representation of a resource based on the browser-supplied preferences for media type, languages, character set and encoding. It also implements a couple of features to give more intelligent handling of requests from browsers that send incomplete negotiation information.
Content negotiation is provided by the
mod_negotiation module, which is compiled in
by default.
A resource may be available in several different representations. For example, it might be available in different languages or different media types, or a combination. One way of selecting the most appropriate choice is to give the user an index page, and let them select. However it is often possible for the server to choose automatically. This works because browsers can send, as part of each request, information about what representations they prefer. For example, a browser could indicate that it would like to see information in French, if possible, else English will do. Browsers indicate their preferences by headers in the request. To request only French representations, the browser would send
Accept-Language: fr
Note that this preference will only be applied when there is a choice of representations and they vary by language.
As an example of a more complex request, this browser has been configured to accept French and English, but prefer French, and to accept various media types, preferring HTML over plain text or other text types, and preferring GIF or JPEG over other media types, but also allowing any other media type as a last resort:
Accept-Language: fr; q=1.0, en; q=0.5
Accept: text/html; q=1.0, text/*; q=0.8, image/gif; q=0.6, image/jpeg; q=0.6, image/*; q=0.5, */*; q=0.1
Apache supports 'server driven' content negotiation, as
defined in the HTTP/1.1 specification. It fully supports the
Accept, Accept-Language,
Accept-Charset andAccept-Encoding
request headers. Apache also supports 'transparent'
content negotiation, which is an experimental negotiation
protocol defined in RFC 2295 and RFC 2296. It does not offer
support for 'feature negotiation' as defined in these RFCs.
A resource is a conceptual entity identified by a URI (RFC 2396). An HTTP server like Apache provides access to representations of the resource(s) within its namespace, with each representation in the form of a sequence of bytes with a defined media type, character set, encoding, etc. Each resource may be associated with zero, one, or more than one representation at any given time. If multiple representations are available, the resource is referred to as negotiable and each of its representations is termed a variant. The ways in which the variants for a negotiable resource vary are called the dimensions of negotiation.
In order to negotiate a resource, the server needs to be given information about each of the variants. This is done in one of two ways:
*.var
file) which names the files containing the variants
explicitly, orA type map is a document which is associated with the
handler named type-map (or, for
backwards-compatibility with older Apache configurations, the
MIME type application/x-type-map). Note that to
use this feature, you must have a handler set in the
configuration that defines a file suffix as
type-map; this is best done with
AddHandler type-map .var
in the server configuration file.
Type map files should have the same name as the resource
which they are describing, and have an entry for each available
variant; these entries consist of contiguous HTTP-format header
lines. Entries for different variants are separated by blank
lines. Blank lines are illegal within an entry. It is
conventional to begin a map file with an entry for the combined
entity as a whole (although this is not required, and if
present will be ignored). An example map file is shown below.
This file would be named foo.var, as it describes
a resource named foo.
URI: foo
URI: foo.en.html
Content-type: text/html
Content-language: en
URI: foo.fr.de.html
Content-type: text/html;charset=iso-8859-2
Content-language: fr, de
Note also that a typemap file will take precedence over the filename's extension, even when Multiviews is on. If the variants have different source qualities, that may be indicated by the "qs" parameter to the media type, as in this picture (available as JPEG, GIF, or ASCII-art):
URI: foo
URI: foo.jpeg
Content-type: image/jpeg; qs=0.8
URI: foo.gif
Content-type: image/gif; qs=0.5
URI: foo.txt
Content-type: text/plain; qs=0.01
qs values can vary in the range 0.000 to 1.000. Note that any variant with a qs value of 0.000 will never be chosen. Variants with no 'qs' parameter value are given a qs factor of 1.0. The qs parameter indicates the relative 'quality' of this variant compared to the other available variants, independent of the client's capabilities. For example, a JPEG file is usually of higher source quality than an ASCII file if it is attempting to represent a photograph. However, if the resource being represented is an original ASCII art, then an ASCII representation would have a higher source quality than a JPEG representation. A qs value is therefore specific to a given variant depending on the nature of the resource it represents.
The full list of headers recognized is available in the mod_negotation typemap documentation.
MultiViews is a per-directory option, meaning it
can be set with an Options
directive within a <Directory>, <Location> or <Files> section in
httpd.conf, or (if AllowOverride is properly set) in
.htaccess files. Note that Options All
does not set MultiViews; you have to ask for it by
name.
The effect of MultiViews is as follows: if the
server receives a request for /some/dir/foo, if
/some/dir has MultiViews enabled, and
/some/dir/foo does not exist, then the
server reads the directory looking for files named foo.*, and
effectively fakes up a type map which names all those files,
assigning them the same media types and content-encodings it
would have if the client had asked for one of them by name. It
then chooses the best match to the client's requirements.
MultiViews may also apply to searches for the file
named by the DirectoryIndex directive, if the
server is trying to index a directory. If the configuration files
specify
DirectoryIndex index
then the server will arbitrate between index.html
and index.html3 if both are present. If neither
are present, and index.cgi is there, the server
will run it.
If one of the files found when reading the directory does not
have an extension recognized by mod_mime to designate
its Charset, Content-Type, Language, or Encoding, then the result
depends on the setting of the MultiViewsMatch directive. This
directive determines whether handlers, filters, and other
extension types can participate in MultiViews negotiation.
After Apache has obtained a list of the variants for a given resource, either from a type-map file or from the filenames in the directory, it invokes one of two methods to decide on the 'best' variant to return, if any. It is not necessary to know any of the details of how negotiation actually takes place in order to use Apache's content negotiation features. However the rest of this document explains the methods used for those interested.
There are two negotiation methods:
| Dimension | Notes |
|---|---|
| Media Type | Browser indicates preferences with the Accept
header field. Each item can have an associated quality factor.
Variant description can also have a quality factor (the "qs"
parameter). |
| Language | Browser indicates preferences with the
Accept-Language header field. Each item can have
a quality factor. Variants can be associated with none, one or
more than one language. |
| Encoding | Browser indicates preference with the
Accept-Encoding header field. Each item can have
a quality factor. |
| Charset | Browser indicates preference with the
Accept-Charset header field. Each item can have a
quality factor. Variants can indicate a charset as a parameter
of the media type. |
Apache can use the following algorithm to select the 'best' variant (if any) to return to the browser. This algorithm is not further configurable. It operates as follows:
Accept
header with the quality-of-source factor for this variants
media type, and select the variants with the highest
value.Accept-Language header (if present), or else
the order of languages in the LanguagePriority
directive (if present).Accept-Charset
header line. Charset ISO-8859-1 is acceptable unless
explicitly excluded. Variants with a text/*
media type but not explicitly associated with a particular
charset are assumed to be in ISO-8859-1.Vary is set to indicate the dimensions of
negotiation (browsers and caches can use this information when
caching the resource). End.Vary header to
indicate the dimensions of variance.Apache sometimes changes the quality values from what would
be expected by a strict interpretation of the Apache
negotiation algorithm above. This is to get a better result
from the algorithm for browsers which do not send full or
accurate information. Some of the most popular browsers send
Accept header information which would otherwise
result in the selection of the wrong variant in many cases. If a
browser sends full and correct information these fiddles will not
be applied.
The Accept: request header indicates preferences
for media types. It can also include 'wildcard' media types, such
as "image/*" or "*/*" where the * matches any string. So a request
including:
Accept: image/*, */*
would indicate that any type starting "image/" is acceptable, as is any other type. Some browsers routinely send wildcards in addition to explicit types they can handle. For example:
Accept: text/html, text/plain, image/gif, image/jpeg, */*
The intention of this is to indicate that the explicitly listed types are preferred, but if a different representation is available, that is ok too. Using explicit quality values, what the browser really wants is something like:
Accept: text/html, text/plain, image/gif, image/jpeg, */*; q=0.01
The explicit types have no quality factor, so they default to a preference of 1.0 (the highest). The wildcard */* is given a low preference of 0.01, so other types will only be returned if no variant matches an explicitly listed type.
If the Accept: header contains no q
factors at all, Apache sets the q value of "*/*", if present, to
0.01 to emulate the desired behavior. It also sets the q value of
wildcards of the format "type/*" to 0.02 (so these are preferred
over matches against "*/*". If any media type on the
Accept: header contains a q factor, these special
values are not applied, so requests from browsers which
send the explicit information to start with work as expected.
New in Apache 2.0, some exceptions have been added to the negotiation algorithm to allow graceful fallback when language negotiation fails to find a match.
When a client requests a page on your server, but the server
cannot find a single page that matches the
Accept-language sent by
the browser, the server will return either a "No Acceptable
Variant" or "Multiple Choices" response to the client. To avoid
these error messages, it is possible to configure Apache to ignore
the Accept-language in these cases and provide a
document that does not explicitly match the client's request. The
ForceLanguagePriority
directive can be used to override one or both of these error
messages and substitute the servers judgement in the form of the
LanguagePriority
directive.
The server will also attempt to match language-subsets when no
other match can be found. For example, if a client requests
documents with the language en-GB for British
English, the server is not normally allowed by the HTTP/1.1
standard to match that against a document that is marked as simply
en. (Note that it is almost surely a configuration
error to include en-GB and not en in the
Accept-Language header, since it is very unlikely
that a reader understands British English, but doesn't understand
English in general. Unfortunately, many current clients have
default configurations that resemble this.) However, if no other
language match is possible and the server is about to return a "No
Acceptable Variants" error or fallback to the LanguagePriority, the server
will ignore the subset specification and match en-GB
against en documents. Implicitly, Apache will add
the parent language to the client's acceptable language list with
a very low quality value. But note that if the client requests
"en-GB; q=0.9, fr; q=0.8", and the server has documents
designated "en" and "fr", then the "fr" document will be returned.
This is necessary to maintain compliance with the HTTP/1.1
specification and to work effectively with properly configured
clients.
In order to support advanced techniques (such as cookies or
special URL-paths) to determine the user's preferred language,
since Apache 2.0.47 mod_negotiation recognizes
the environment variable
prefer-language. If it exists and contains an
appropriate language tag, mod_negotiation will
try to select a matching variant. If there's no such variant,
the normal negotiation process applies.
SetEnvIf Cookie "language=en" prefer-language=en
SetEnvIf Cookie "language=fr" prefer-language=fr
Apache extends the transparent content negotiation protocol (RFC
2295) as follows. A new {encoding ..} element is used in
variant lists to label variants which are available with a specific
content-encoding only. The implementation of the RVSA/1.0 algorithm
(RFC 2296) is extended to recognize encoded variants in the list, and
to use them as candidate variants whenever their encodings are
acceptable according to the Accept-Encoding request
header. The RVSA/1.0 implementation does not round computed quality
factors to 5 decimal places before choosing the best variant.
If you are using language negotiation you can choose between different naming conventions, because files can have more than one extension, and the order of the extensions is normally irrelevant (see the mod_mime documentation for details).
A typical file has a MIME-type extension (e.g.,
html), maybe an encoding extension (e.g.,
gz), and of course a language extension
(e.g., en) when we have different
language variants of this file.
Examples:
Here some more examples of filenames together with valid and invalid hyperlinks:
| Filename | Valid hyperlink | Invalid hyperlink |
|---|---|---|
| foo.html.en | foo foo.html |
- |
| foo.en.html | foo | foo.html |
| foo.html.en.gz | foo foo.html |
foo.gz foo.html.gz |
| foo.en.html.gz | foo | foo.html foo.html.gz foo.gz |
| foo.gz.html.en | foo foo.gz foo.gz.html |
foo.html |
| foo.html.gz.en | foo foo.html foo.html.gz |
foo.gz |
Looking at the table above, you will notice that it is always
possible to use the name without any extensions in a hyperlink
(e.g., foo). The advantage is that you
can hide the actual type of a document rsp. file and can change
it later, e.g., from html to
shtml or cgi without changing any
hyperlink references.
If you want to continue to use a MIME-type in your
hyperlinks (e.g. foo.html) the language
extension (including an encoding extension if there is one)
must be on the right hand side of the MIME-type extension
(e.g., foo.html.en).
When a cache stores a representation, it associates it with the request URL. The next time that URL is requested, the cache can use the stored representation. But, if the resource is negotiable at the server, this might result in only the first requested variant being cached and subsequent cache hits might return the wrong response. To prevent this, Apache normally marks all responses that are returned after content negotiation as non-cacheable by HTTP/1.0 clients. Apache also supports the HTTP/1.1 protocol features to allow caching of negotiated responses.
For requests which come from a HTTP/1.0 compliant client
(either a browser or a cache), the directive CacheNegotiatedDocs can be
used to allow caching of responses which were subject to
negotiation. This directive can be given in the server config or
virtual host, and takes no arguments. It has no effect on requests
from HTTP/1.1 clients.
For more information about content negotiation, see Alan J. Flavell's Language Negotiation Notes. But note that this document may not be updated to include changes in Apache 2.0.
Apache HTTP Server Version 2.0
Additional functionality allows webmasters to configure the response of Apache to some error or problem.
Customizable responses can be defined to be activated in the event of a server detected error or problem.
If a script crashes and produces a "500 Server Error" response, then this response can be replaced with either some friendlier text or by a redirection to another URL (local or external).
NCSA httpd 1.3 would return some boring old error/problem message which would often be meaningless to the user, and would provide no means of logging the symptoms which caused it.
The server can be asked to:
Redirecting to another URL can be useful, but only if some information can be passed which can then be used to explain and/or log the error/problem more clearly.
To achieve this, Apache will define new CGI-like environment variables:
REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/x-xbitmap,
image/jpeg
REDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX A.09.05
9000/712)
REDIRECT_PATH=.:/bin:/usr/local/bin:/etc
REDIRECT_QUERY_STRING=
REDIRECT_REMOTE_ADDR=121.345.78.123
REDIRECT_REMOTE_HOST=ooh.ahhh.com
REDIRECT_SERVER_NAME=crash.bang.edu
REDIRECT_SERVER_PORT=80
REDIRECT_SERVER_SOFTWARE=Apache/0.8.15
REDIRECT_URL=/cgi-bin/buggy.pl
Note the REDIRECT_ prefix.
At least REDIRECT_URL and
REDIRECT_QUERY_STRING will be passed to the
new URL (assuming it's a cgi-script or a cgi-include). The
other variables will exist only if they existed prior to
the error/problem. None of these will be
set if your ErrorDocument is an
external redirect (anything starting with a
scheme name like http:, even if it refers to the same host
as the server).
Use of ErrorDocument is enabled
for .htaccess files when the
AllowOverride is set accordingly.
Here are some examples...
ErrorDocument 500 /cgi-bin/crash-recover
ErrorDocument 500 "Sorry, our script crashed. Oh dear"
ErrorDocument 500 http://xxx/
ErrorDocument 404 /Lame_excuses/not_found.html
ErrorDocument 401 /Subscription/how_to_subscribe.html
The syntax is,
ErrorDocument <3-digit-code> <action>
where the action can be,
Apache's behavior to redirected URLs has been modified so that additional environment variables are available to a script/server-include.
Standard CGI vars were made available to a script which has been redirected to. No indication of where the redirection came from was provided.
A new batch of environment variables will be initialized
for use by a script which has been redirected to. Each new
variable will have the prefix REDIRECT_.
REDIRECT_ environment variables are created from
the CGI environment variables which existed prior to the
redirect, they are renamed with a REDIRECT_
prefix, i.e., HTTP_USER_AGENT becomes
REDIRECT_HTTP_USER_AGENT. In addition to these
new variables, Apache will define REDIRECT_URL
and REDIRECT_STATUS to help the script trace its
origin. Both the original URL and the URL being redirected to
can be logged in the access log.
If the ErrorDocument specifies a local redirect to a CGI
script, the script should include a "Status:"
header field in its output in order to ensure the propagation
all the way back to the client of the error condition that
caused it to be invoked. For instance, a Perl ErrorDocument
script might include the following:
...
print "Content-type: text/html\n";
printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"};
...
If the script is dedicated to handling a particular error
condition, such as 404 Not Found, it can
use the specific code and error text instead.
Note that the script must emit an appropriate
Status: header (such as 302 Found), if the
response contains a Location: header (in order to issue a
client side redirect). Otherwise the Location: header may
have no effect.
Apache HTTP Server Version 2.0
This document has not been updated to take into account changes made in the 2.0 version of the Apache HTTP Server. Some of the information may still be relevant, but please use it with care.
These are some notes on the Apache API and the data structures you have to deal with, etc. They are not yet nearly complete, but hopefully, they will help you get your bearings. Keep in mind that the API is still subject to change as we gain experience with it. (See the TODO file for what might be coming). However, it will be easy to adapt modules to any changes that are made. (We have more modules to adapt than you do).
A few notes on general pedagogical style here. In the interest of conciseness, all structure declarations here are incomplete -- the real ones have more slots that I'm not telling you about. For the most part, these are reserved to one component of the server core or another, and should be altered by modules with caution. However, in some cases, they really are things I just haven't gotten around to yet. Welcome to the bleeding edge.
Finally, here's an outline, to give you some bare idea of what's coming up, and in what order:
We begin with an overview of the basic concepts behind the API, and how they are manifested in the code.
Apache breaks down request handling into a series of steps, more or less the same way the Netscape server API does (although this API has a few more stages than NetSite does, as hooks for stuff I thought might be useful in the future). These are:
SetEnv, which don't really fit well elsewhere.These phases are handled by looking at each of a succession of modules, looking to see if each of them has a handler for the phase, and attempting invoking it if so. The handler can typically do one of three things:
OK.DECLINED. In this case, the server behaves in all
respects as if the handler simply hadn't been there.Most phases are terminated by the first module that handles them;
however, for logging, `fixups', and non-access authentication checking,
all handlers always run (barring an error). Also, the response phase is
unique in that modules may declare multiple handlers for it, via a
dispatch table keyed on the MIME type of the requested object. Modules may
declare a response-phase handler which can handle any request,
by giving it the key */* (i.e., a wildcard MIME type
specification). However, wildcard handlers are only invoked if the server
has already tried and failed to find a more specific response handler for
the MIME type of the requested object (either none existed, or they all
declined).
The handlers themselves are functions of one argument (a
request_rec structure. vide infra), which returns an integer,
as above.
At this point, we need to explain the structure of a module. Our
candidate will be one of the messier ones, the CGI module -- this handles
both CGI scripts and the ScriptAlias config file command. It's actually a great deal
more complicated than most modules, but if we're going to have only one
example, it might as well be the one with its fingers in every place.
Let's begin with handlers. In order to handle the CGI scripts, the
module declares a response handler for them. Because of ScriptAlias, it also has handlers for the
name translation phase (to recognize ScriptAliased URIs), the type-checking phase (any
ScriptAliased request is typed
as a CGI script).
The module needs to maintain some per (virtual) server information,
namely, the ScriptAliases in
effect; the module structure therefore contains pointers to a functions
which builds these structures, and to another which combines two of them
(in case the main server and a virtual server both have ScriptAliases declared).
Finally, this module contains code to handle the ScriptAlias command itself. This particular
module only declares one command, but there could be more, so modules have
command tables which declare their commands, and describe where
they are permitted, and how they are to be invoked.
A final note on the declared types of the arguments of some of these
commands: a pool is a pointer to a resource pool
structure; these are used by the server to keep track of the memory which
has been allocated, files opened, etc., either to service a
particular request, or to handle the process of configuring itself. That
way, when the request is over (or, for the configuration pool, when the
server is restarting), the memory can be freed, and the files closed,
en masse, without anyone having to write explicit code to track
them all down and dispose of them. Also, a cmd_parms
structure contains various information about the config file being read,
and other status information, which is sometimes of use to the function
which processes a config-file command (such as ScriptAlias). With no further ado, the
module itself:
/* Declarations of handlers. */
int translate_scriptalias (request_rec *);
int type_scriptalias (request_rec *);
int cgi_handler (request_rec *);
/* Subsidiary dispatch table for response-phase
* handlers, by MIME type */
handler_rec cgi_handlers[] = {
{ "application/x-httpd-cgi", cgi_handler },
{ NULL }
};
/* Declarations of routines to manipulate the
* module's configuration info. Note that these are
* returned, and passed in, as void *'s; the server
* core keeps track of them, but it doesn't, and can't,
* know their internal structure.
*/
void *make_cgi_server_config (pool *);
void *merge_cgi_server_config (pool *, void *, void *);
/* Declarations of routines to handle config-file commands */
extern char *script_alias(cmd_parms *, void *per_dir_config, char *fake,
char *real);
command_rec cgi_cmds[] = {
{ "ScriptAlias", script_alias, NULL, RSRC_CONF, TAKE2,
"a fakename and a realname"},
{ NULL }
};
module cgi_module = {
STANDARD_MODULE_STUFF, NULL, /* initializer */ NULL, /* dir config creator */ NULL, /* dir merger */ make_cgi_server_config, /* server config */ merge_cgi_server_config, /* merge server config */ cgi_cmds, /* command table */ cgi_handlers, /* handlers */ translate_scriptalias, /* filename translation */ NULL, /* check_user_id */ NULL, /* check auth */ NULL, /* check access */ type_scriptalias, /* type_checker */ NULL, /* fixups */ NULL, /* logger */ NULL /* header parser */ };
The sole argument to handlers is a request_rec structure.
This structure describes a particular request which has been made to the
server, on behalf of a client. In most cases, each connection to the
client generates only one request_rec structure.
The request_rec contains pointers to a resource pool
which will be cleared when the server is finished handling the request;
to structures containing per-server and per-connection information, and
most importantly, information on the request itself.
The most important such information is a small set of character strings describing attributes of the object being requested, including its URI, filename, content-type and content-encoding (these being filled in by the translation and type-check handlers which handle the request, respectively).
Other commonly used data items are tables giving the MIME headers on
the client's original request, MIME headers to be sent back with the
response (which modules can add to at will), and environment variables for
any subprocesses which are spawned off in the course of servicing the
request. These tables are manipulated using the ap_table_get
and ap_table_set routines.
Note that the Content-type header value cannot
be set by module content-handlers using the ap_table_*()
routines. Rather, it is set by pointing the content_type
field in the request_rec structure to an appropriate
string. e.g.,
r->content_type = "text/html";
Finally, there are pointers to two data structures which, in turn,
point to per-module configuration structures. Specifically, these hold
pointers to the data structures which the module has built to describe
the way it has been configured to operate in a given directory (via
.htaccess files or <Directory> sections), for private data it has built in the
course of servicing the request (so modules' handlers for one phase can
pass `notes' to their handlers for other phases). There is another such
configuration vector in the server_rec data structure pointed
to by the request_rec, which contains per (virtual) server
configuration data.
Here is an abridged declaration, giving the fields most commonly used:
struct request_rec {
pool *pool;
conn_rec *connection;
server_rec *server;
/* What object is being requested */
char *uri;
char *filename;
char *path_info;
char *args; /* QUERY_ARGS, if any */
struct stat finfo; /* Set by server core;
* st_mode set to zero if no such file */
char *content_type;
char *content_encoding;
/* MIME header environments, in and out. Also,
* an array containing environment variables to
* be passed to subprocesses, so people can write
* modules to add to that environment.
*
* The difference between headers_out and
* err_headers_out is that the latter are printed
* even on error, and persist across internal
* redirects (so the headers printed for
* ErrorDocument handlers will have
them).
*/
table *headers_in;
table *headers_out;
table *err_headers_out;
table *subprocess_env;
/* Info about the request itself... */
int header_only; /* HEAD request, as opposed to GET */ char *protocol; /* Protocol, as given to us, or HTTP/0.9 */ char *method; /* GET, HEAD, POST, etc. */ int method_number; /* M_GET, M_POST, etc. */
/* Info for logging */
char *the_request;
int bytes_sent;
/* A flag which modules can set, to indicate that
* the data being returned is volatile, and clients
* should be told not to cache it.
*/
int no_cache;
/* Various other config info which may change
* with .htaccess files
* These are config vectors, with one void*
* pointer for each module (the thing pointed
* to being the module's business).
*/
void *per_dir_config; /* Options set in config files, etc. */ void *request_config; /* Notes on *this* request */
};
Most request_rec structures are built by reading an HTTP
request from a client, and filling in the fields. However, there are a
few exceptions:
*.var file), or a CGI script which returned a local
`Location:', then the resource which the user requested is going to be
ultimately located by some URI other than what the client originally
supplied. In this case, the server does an internal redirect,
constructing a new request_rec for the new URI, and
processing it almost exactly as if the client had requested the new URI
directly.ErrorDocument
is in scope, the same internal redirect machinery comes into play.Finally, a handler occasionally needs to investigate `what would happen if' some other request were run. For instance, the directory indexing module needs to know what MIME type would be assigned to a request for each directory entry, in order to figure out what icon to use.
Such handlers can construct a sub-request, using the
functions ap_sub_req_lookup_file,
ap_sub_req_lookup_uri, and ap_sub_req_method_uri;
these construct a new request_rec structure and processes it
as you would expect, up to but not including the point of actually sending
a response. (These functions skip over the access checks if the
sub-request is for a file in the same directory as the original
request).
(Server-side includes work by building sub-requests and then actually
invoking the response handler for them, via the function
ap_run_sub_req).
As discussed above, each handler, when invoked to handle a particular
request_rec, has to return an int to indicate
what happened. That can either be
OK -- the request was handled successfully. This may or
may not terminate the phase.DECLINED -- no erroneous condition exists, but the module
declines to handle the phase; the server tries to find another.Note that if the error code returned is REDIRECT, then
the module should put a Location in the request's
headers_out, to indicate where the client should be
redirected to.
Handlers for most phases do their work by simply setting a few fields
in the request_rec structure (or, in the case of access
checkers, simply by returning the correct error code). However, response
handlers have to actually send a request back to the client.
They should begin by sending an HTTP response header, using the
function ap_send_http_header. (You don't have to do anything
special to skip sending the header for HTTP/0.9 requests; the function
figures out on its own that it shouldn't do anything). If the request is
marked header_only, that's all they should do; they should
return after that, without attempting any further output.
Otherwise, they should produce a request body which responds to the
client as appropriate. The primitives for this are ap_rputc
and ap_rprintf, for internally generated output, and
ap_send_fd, to copy the contents of some FILE *
straight to the client.
At this point, you should more or less understand the following piece
of code, which is the handler which handles GET requests
which have no more specific handler; it also shows how conditional
GETs can be handled, if it's desirable to do so in a
particular response handler -- ap_set_last_modified checks
against the If-modified-since value supplied by the client,
if any, and returns an appropriate code (which will, if nonzero, be
USE_LOCAL_COPY). No similar considerations apply for
ap_set_content_length, but it returns an error code for
symmetry.
int default_handler (request_rec *r)
{
int errstatus;
FILE *f;
if (r->method_number != M_GET) return DECLINED;
if (r->finfo.st_mode == 0) return NOT_FOUND;
if ((errstatus = ap_set_content_length (r, r->finfo.st_size))
||
(errstatus = ap_set_last_modified (r, r->finfo.st_mtime)))
return errstatus;
f = fopen (r->filename, "r");
if (f == NULL) {
log_reason("file permissions deny server access", r->filename, r);
return FORBIDDEN;
}
register_timeout ("send", r);
ap_send_http_header (r);
if (!r->header_only) send_fd (f, r);
ap_pfclose (r->pool, f);
return OK;
}
Finally, if all of this is too much of a challenge, there are a few
ways out of it. First off, as shown above, a response handler which has
not yet produced any output can simply return an error code, in which
case the server will automatically produce an error response. Secondly,
it can punt to some other handler by invoking
ap_internal_redirect, which is how the internal redirection
machinery discussed above is invoked. A response handler which has
internally redirected should always return OK.
(Invoking ap_internal_redirect from handlers which are
not response handlers will lead to serious confusion).
Stuff that should be discussed here in detail:
ap_auth_type,
ap_auth_name, and ap_requires.ap_get_basic_auth_pw, which sets the
connection->user structure field
automatically, and ap_note_basic_auth_failure,
which arranges for the proper WWW-Authenticate:
header to be sent back).When a request has internally redirected, there is the question of
what to log. Apache handles this by bundling the entire chain of redirects
into a list of request_rec structures which are threaded
through the r->prev and r->next pointers.
The request_rec which is passed to the logging handlers in
such cases is the one which was originally built for the initial request
from the client; note that the bytes_sent field will only be
correct in the last request in the chain (the one for which a response was
actually sent).
One of the problems of writing and designing a server-pool server is that of preventing leakage, that is, allocating resources (memory, open files, etc.), without subsequently releasing them. The resource pool machinery is designed to make it easy to prevent this from happening, by allowing resource to be allocated in such a way that they are automatically released when the server is done with them.
The way this works is as follows: the memory which is allocated, file opened, etc., to deal with a particular request are tied to a resource pool which is allocated for the request. The pool is a data structure which itself tracks the resources in question.
When the request has been processed, the pool is cleared. At that point, all the memory associated with it is released for reuse, all files associated with it are closed, and any other clean-up functions which are associated with the pool are run. When this is over, we can be confident that all the resource tied to the pool have been released, and that none of them have leaked.
Server restarts, and allocation of memory and resources for per-server configuration, are handled in a similar way. There is a configuration pool, which keeps track of resources which were allocated while reading the server configuration files, and handling the commands therein (for instance, the memory that was allocated for per-server module configuration, log files and other files that were opened, and so forth). When the server restarts, and has to reread the configuration files, the configuration pool is cleared, and so the memory and file descriptors which were taken up by reading them the last time are made available for reuse.
It should be noted that use of the pool machinery isn't generally
obligatory, except for situations like logging handlers, where you really
need to register cleanups to make sure that the log file gets closed when
the server restarts (this is most easily done by using the function ap_pfopen, which also arranges for the
underlying file descriptor to be closed before any child processes, such as
for CGI scripts, are execed), or in case you are using the
timeout machinery (which isn't yet even documented here). However, there are
two benefits to using it: resources allocated to a pool never leak (even if
you allocate a scratch string, and just forget about it); also, for memory
allocation, ap_palloc is generally faster than
malloc.
We begin here by describing how memory is allocated to pools, and then discuss how other resources are tracked by the resource pool machinery.
Memory is allocated to pools by calling the function
ap_palloc, which takes two arguments, one being a pointer to
a resource pool structure, and the other being the amount of memory to
allocate (in chars). Within handlers for handling requests,
the most common way of getting a resource pool structure is by looking at
the pool slot of the relevant request_rec; hence
the repeated appearance of the following idiom in module code:
int my_handler(request_rec *r)
{
struct my_structure *foo;
...
foo = (foo *)ap_palloc (r->pool, sizeof(my_structure));
}
Note that there is no ap_pfree --
ap_palloced memory is freed only when the associated resource
pool is cleared. This means that ap_palloc does not have to
do as much accounting as malloc(); all it does in the typical
case is to round up the size, bump a pointer, and do a range check.
(It also raises the possibility that heavy use of
ap_palloc could cause a server process to grow excessively
large. There are two ways to deal with this, which are dealt with below;
briefly, you can use malloc, and try to be sure that all of
the memory gets explicitly freed, or you can allocate a
sub-pool of the main pool, allocate your memory in the sub-pool, and clear
it out periodically. The latter technique is discussed in the section
on sub-pools below, and is used in the directory-indexing code, in order
to avoid excessive storage allocation when listing directories with
thousands of files).
There are functions which allocate initialized memory, and are
frequently useful. The function ap_pcalloc has the same
interface as ap_palloc, but clears out the memory it
allocates before it returns it. The function ap_pstrdup
takes a resource pool and a char * as arguments, and
allocates memory for a copy of the string the pointer points to, returning
a pointer to the copy. Finally ap_pstrcat is a varargs-style
function, which takes a pointer to a resource pool, and at least two
char * arguments, the last of which must be
NULL. It allocates enough memory to fit copies of each of
the strings, as a unit; for instance:
ap_pstrcat (r->pool, "foo", "/", "bar", NULL);
returns a pointer to 8 bytes worth of memory, initialized to
"foo/bar".
A pool is really defined by its lifetime more than anything else. There are some static pools in http_main which are passed to various non-http_main functions as arguments at opportune times. Here they are:
permanent_poolpconfptemppchildptransr->poolFor almost everything folks do, r->pool is the pool to
use. But you can see how other lifetimes, such as pchild, are useful to
some modules... such as modules that need to open a database connection
once per child, and wish to clean it up when the child dies.
You can also see how some bugs have manifested themself, such as
setting connection->user to a value from
r->pool -- in this case connection exists for the
lifetime of ptrans, which is longer than
r->pool (especially if r->pool is a
subrequest!). So the correct thing to do is to allocate from
connection->pool.
And there was another interesting bug in mod_include
/ mod_cgi. You'll see in those that they do this test
to decide if they should use r->pool or
r->main->pool. In this case the resource that they are
registering for cleanup is a child process. If it were registered in
r->pool, then the code would wait() for the
child when the subrequest finishes. With mod_include this
could be any old #include, and the delay can be up to 3
seconds... and happened quite frequently. Instead the subprocess is
registered in r->main->pool which causes it to be
cleaned up when the entire request is done -- i.e., after the
output has been sent to the client and logging has happened.
As indicated above, resource pools are also used to track other sorts
of resources besides memory. The most common are open files. The routine
which is typically used for this is ap_pfopen, which takes a
resource pool and two strings as arguments; the strings are the same as
the typical arguments to fopen, e.g.,
...
FILE *f = ap_pfopen (r->pool, r->filename, "r");
if (f == NULL) { ... } else { ... }
There is also a ap_popenf routine, which parallels the
lower-level open system call. Both of these routines arrange
for the file to be closed when the resource pool in question is
cleared.
Unlike the case for memory, there are functions to close files
allocated with ap_pfopen, and ap_popenf, namely
ap_pfclose and ap_pclosef. (This is because, on
many systems, the number of files which a single process can have open is
quite limited). It is important to use these functions to close files
allocated with ap_pfopen and ap_popenf, since to
do otherwise could cause fatal errors on systems such as Linux, which
react badly if the same FILE* is closed more than once.
(Using the close functions is not mandatory, since the
file will eventually be closed regardless, but you should consider it in
cases where your module is opening, or could open, a lot of files).
More text goes here. Describe the cleanup primitives in terms of
which the file stuff is implemented; also, spawn_process.
Pool cleanups live until clear_pool() is called:
clear_pool(a) recursively calls destroy_pool()
on all subpools of a; then calls all the cleanups for
a; then releases all the memory for a.
destroy_pool(a) calls clear_pool(a) and then
releases the pool structure itself. i.e.,
clear_pool(a) doesn't delete a, it just frees
up all the resources and you can start using it again immediately.
On rare occasions, too-free use of ap_palloc() and the
associated primitives may result in undesirably profligate resource
allocation. You can deal with such a case by creating a sub-pool,
allocating within the sub-pool rather than the main pool, and clearing or
destroying the sub-pool, which releases the resources which were
associated with it. (This really is a rare situation; the only
case in which it comes up in the standard module set is in case of listing
directories, and then only with very large directories.
Unnecessary use of the primitives discussed here can hair up your code
quite a bit, with very little gain).
The primitive for creating a sub-pool is ap_make_sub_pool,
which takes another pool (the parent pool) as an argument. When the main
pool is cleared, the sub-pool will be destroyed. The sub-pool may also be
cleared or destroyed at any time, by calling the functions
ap_clear_pool and ap_destroy_pool, respectively.
(The difference is that ap_clear_pool frees resources
associated with the pool, while ap_destroy_pool also
deallocates the pool itself. In the former case, you can allocate new
resources within the pool, and clear it again, and so forth; in the
latter case, it is simply gone).
One final note -- sub-requests have their own resource pools, which are
sub-pools of the resource pool for the main request. The polite way to
reclaim the resources associated with a sub request which you have
allocated (using the ap_sub_req_... functions) is
ap_destroy_sub_req, which frees the resource pool. Before
calling this function, be sure to copy anything that you care about which
might be allocated in the sub-request's resource pool into someplace a
little less volatile (for instance, the filename in its
request_rec structure).
(Again, under most circumstances, you shouldn't feel obliged to call
this function; only 2K of memory or so are allocated for a typical sub
request, and it will be freed anyway when the main request pool is
cleared. It is only when you are allocating many, many sub-requests for a
single main request that you should seriously consider the
ap_destroy_... functions).
One of the design goals for this server was to maintain external compatibility with the NCSA 1.3 server --- that is, to read the same configuration files, to process all the directives therein correctly, and in general to be a drop-in replacement for NCSA. On the other hand, another design goal was to move as much of the server's functionality into modules which have as little as possible to do with the monolithic server core. The only way to reconcile these goals is to move the handling of most commands from the central server into the modules.
However, just giving the modules command tables is not enough to divorce
them completely from the server core. The server has to remember the
commands in order to act on them later. That involves maintaining data which
is private to the modules, and which can be either per-server, or
per-directory. Most things are per-directory, including in particular access
control and authorization information, but also information on how to
determine file types from suffixes, which can be modified by
AddType and DefaultType directives, and so forth. In general,
the governing philosophy is that anything which can be made
configurable by directory should be; per-server information is generally
used in the standard set of modules for information like
Aliases and Redirects which come into play before the
request is tied to a particular place in the underlying file system.
Another requirement for emulating the NCSA server is being able to handle
the per-directory configuration files, generally called
.htaccess files, though even in the NCSA server they can
contain directives which have nothing at all to do with access control.
Accordingly, after URI -> filename translation, but before performing any
other phase, the server walks down the directory hierarchy of the underlying
filesystem, following the translated pathname, to read any
.htaccess files which might be present. The information which
is read in then has to be merged with the applicable information
from the server's own config files (either from the <Directory> sections in
access.conf, or from defaults in srm.conf, which
actually behaves for most purposes almost exactly like <Directory
/>).
Finally, after having served a request which involved reading
.htaccess files, we need to discard the storage allocated for
handling them. That is solved the same way it is solved wherever else
similar problems come up, by tying those structures to the per-transaction
resource pool.
Let's look out how all of this plays out in mod_mime.c,
which defines the file typing handler which emulates the NCSA server's
behavior of determining file types from suffixes. What we'll be looking
at, here, is the code which implements the AddType and AddEncoding commands. These commands can appear in
.htaccess files, so they must be handled in the module's
private per-directory data, which in fact, consists of two separate
tables for MIME types and encoding information, and is declared as
follows:
typedef struct {
table *forced_types; /* Additional AddTyped stuff */
table *encoding_types; /* Added with AddEncoding... */
} mime_dir_config;When the server is reading a configuration file, or <Directory> section, which includes
one of the MIME module's commands, it needs to create a
mime_dir_config structure, so those commands have something
to act on. It does this by invoking the function it finds in the module's
`create per-dir config slot', with two arguments: the name of the
directory to which this configuration information applies (or
NULL for srm.conf), and a pointer to a
resource pool in which the allocation should happen.
(If we are reading a .htaccess file, that resource pool
is the per-request resource pool for the request; otherwise it is a
resource pool which is used for configuration data, and cleared on
restarts. Either way, it is important for the structure being created to
vanish when the pool is cleared, by registering a cleanup on the pool if
necessary).
For the MIME module, the per-dir config creation function just
ap_pallocs the structure above, and a creates a couple of
tables to fill it. That looks like this:
void *create_mime_dir_config (pool *p, char *dummy)
{
mime_dir_config *new =
(mime_dir_config *) ap_palloc (p, sizeof(mime_dir_config));
new->forced_types = ap_make_table (p, 4);
new->encoding_types = ap_make_table (p, 4);
return new;
}
Now, suppose we've just read in a .htaccess file. We
already have the per-directory configuration structure for the next
directory up in the hierarchy. If the .htaccess file we just
read in didn't have any AddType
or AddEncoding commands, its
per-directory config structure for the MIME module is still valid, and we
can just use it. Otherwise, we need to merge the two structures
somehow.
To do that, the server invokes the module's per-directory config merge function, if one is present. That function takes three arguments: the two structures being merged, and a resource pool in which to allocate the result. For the MIME module, all that needs to be done is overlay the tables from the new per-directory config structure with those from the parent:
void *merge_mime_dir_configs (pool *p, void *parent_dirv, void *subdirv)
{
mime_dir_config *parent_dir = (mime_dir_config *)parent_dirv;
mime_dir_config *subdir = (mime_dir_config *)subdirv;
mime_dir_config *new =
(mime_dir_config *)ap_palloc (p, sizeof(mime_dir_config));
new->forced_types = ap_overlay_tables (p, subdir->forced_types,
parent_dir->forced_types);
new->encoding_types = ap_overlay_tables (p, subdir->encoding_types,
parent_dir->encoding_types);
return new;
}
As a note -- if there is no per-directory merge function present, the
server will just use the subdirectory's configuration info, and ignore
the parent's. For some modules, that works just fine (e.g., for
the includes module, whose per-directory configuration information
consists solely of the state of the XBITHACK), and for those
modules, you can just not declare one, and leave the corresponding
structure slot in the module itself NULL.
Now that we have these structures, we need to be able to figure out how
to fill them. That involves processing the actual AddType and AddEncoding commands. To find commands, the server looks in
the module's command table. That table contains information on how many
arguments the commands take, and in what formats, where it is permitted,
and so forth. That information is sufficient to allow the server to invoke
most command-handling functions with pre-parsed arguments. Without further
ado, let's look at the AddType
command handler, which looks like this (the AddEncoding command looks basically the same, and won't be
shown here):
char *add_type(cmd_parms *cmd, mime_dir_config *m, char *ct, char *ext)
{
if (*ext == '.') ++ext;
ap_table_set (m->forced_types, ext, ct);
return NULL;
}
This command handler is unusually simple. As you can see, it takes
four arguments, two of which are pre-parsed arguments, the third being the
per-directory configuration structure for the module in question, and the
fourth being a pointer to a cmd_parms structure. That
structure contains a bunch of arguments which are frequently of use to
some, but not all, commands, including a resource pool (from which memory
can be allocated, and to which cleanups should be tied), and the (virtual)
server being configured, from which the module's per-server configuration
data can be obtained if required.
Another way in which this particular command handler is unusually
simple is that there are no error conditions which it can encounter. If
there were, it could return an error message instead of NULL;
this causes an error to be printed out on the server's
stderr, followed by a quick exit, if it is in the main config
files; for a .htaccess file, the syntax error is logged in
the server error log (along with an indication of where it came from), and
the request is bounced with a server error response (HTTP error status,
code 500).
The MIME module's command table has entries for these commands, which look like this:
command_rec mime_cmds[] = {
{ "AddType", add_type, NULL, OR_FILEINFO, TAKE2,
"a mime type followed by a file extension" },
{ "AddEncoding", add_encoding, NULL, OR_FILEINFO, TAKE2,
"an encoding (e.g., gzip), followed by a file extension" },
{ NULL }
};
The entries in these tables are:
(void *) pointer, which is passed in the
cmd_parms structure to the command handler ---
this is useful in case many similar commands are handled by
the same function.AllowOverride option, and an additional mask
bit, RSRC_CONF, indicating that the command may
appear in the server's own config files, but not in
any .htaccess file.TAKE2 indicates two pre-parsed arguments. Other
options are TAKE1, which indicates one
pre-parsed argument, FLAG, which indicates that
the argument should be On or Off,
and is passed in as a boolean flag, RAW_ARGS,
which causes the server to give the command the raw, unparsed
arguments (everything but the command name itself). There is
also ITERATE, which means that the handler looks
the same as TAKE1, but that if multiple
arguments are present, it should be called multiple times,
and finally ITERATE2, which indicates that the
command handler looks like a TAKE2, but if more
arguments are present, then it should be called multiple
times, holding the first argument constant.NULL).Finally, having set this all up, we have to use it. This is ultimately
done in the module's handlers, specifically for its file-typing handler,
which looks more or less like this; note that the per-directory
configuration structure is extracted from the request_rec's
per-directory configuration vector by using the
ap_get_module_config function.
int find_ct(request_rec *r)
{
int i;
char *fn = ap_pstrdup (r->pool, r->filename);
mime_dir_config *conf = (mime_dir_config *)
ap_get_module_config(r->per_dir_config, &mime_module);
char *type;
if (S_ISDIR(r->finfo.st_mode)) {
r->content_type = DIR_MAGIC_TYPE;
return OK;
}
if((i=ap_rind(fn,'.')) < 0) return DECLINED;
++i;
if ((type = ap_table_get (conf->encoding_types, &fn[i])))
{
r->content_encoding = type;
/* go back to previous extension to try to use it as a type */
fn[i-1] = '\0';
if((i=ap_rind(fn,'.')) < 0) return OK;
++i;
}
if ((type = ap_table_get (conf->forced_types, &fn[i])))
{
r->content_type = type;
}
return OK;
}
The basic ideas behind per-server module configuration are basically the same as those for per-directory configuration; there is a creation function and a merge function, the latter being invoked where a virtual server has partially overridden the base server configuration, and a combined structure must be computed. (As with per-directory configuration, the default if no merge function is specified, and a module is configured in some virtual server, is that the base configuration is simply ignored).
The only substantial difference is that when a command needs to
configure the per-server private module data, it needs to go to the
cmd_parms data to get at it. Here's an example, from the
alias module, which also indicates how a syntax error can be returned
(note that the per-directory configuration argument to the command
handler is declared as a dummy, since the module doesn't actually have
per-directory config data):
char *add_redirect(cmd_parms *cmd, void *dummy, char *f, char *url)
{
server_rec *s = cmd->server;
alias_server_conf *conf = (alias_server_conf *)
ap_get_module_config(s->module_config,&alias_module);
alias_entry *new = ap_push_array (conf->redirects);
if (!ap_is_url (url)) return "Redirect to non-URL";
new->fake = f; new->real = url;
return NULL;
}
Apache HTTP Server Version 2.0
The allocation mechanism's within APR have a number of debugging modes that can be used to assist in finding memory problems. This document describes the modes available and gives instructions on activating them.
free()d memory and other such
nonsense.The theory is simple. The FILL_BYTE (0xa5)
is written over all malloc'd memory as we receive it, and
is written over everything that we free up during a
clear_pool. We check that blocks on the free list always
have the FILL_BYTE in them, and we check during
palloc() that the bytes still have FILL_BYTE
in them. If you ever see garbage URLs or whatnot containing lots
of 0xa5s then you know something used data that's been
freed or uninitialized.
malloc() and free()d appropriately at the
end.This is intended to be used with something like Electric
Fence or Purify to help detect memory problems. Note that if
you're using efence then you should also add in ALLOC_DEBUG.
But don't add in ALLOC_DEBUG if you're using Purify because
ALLOC_DEBUG would hide all the uninitialized read errors
that Purify can diagnose.
In particular, it causes the table_{set,add,merge}n
routines to check that their arguments are safe for the
apr_table_t they're being placed in. It currently only works
with the unix multiprocess model, but could be extended to others.
This requires a recent gcc which supports
__builtin_return_address(). The error_log output will be a
message such as:
table_push: apr_table_t created by 0x804d874 hit limit of 10
Use l *0x804d874 to find the
source that corresponds to. It indicates that a apr_table_t
allocated by a call at that address has possibly too small an
initial apr_table_t size guess.
This requires a bit of an understanding of how alloc.c works.
Not all the options outlined above can be activated at the same time. the following table gives more information.
| ALLOC DEBUG | ALLOC USE MALLOC | POOL DEBUG | MAKE TABLE PROFILE | ALLOC STATS | |
|---|---|---|---|---|---|
| ALLOC DEBUG | - | No | Yes | Yes | Yes |
| ALLOC USE MALLOC | No | - | No | No | No |
| POOL DEBUG | Yes | No | - | Yes | Yes |
| MAKE TABLE PROFILE | Yes | No | Yes | - | Yes |
| ALLOC STATS | Yes | No | Yes | Yes | - |
Additionally the debugging options are not suitable for multi-threaded versions of the server. When trying to debug with these options the server should be started in single process mode.
The various options for debugging memory are now enabled in
the apr_general.h header file in APR. The various options are
enabled by uncommenting the define for the option you wish to
use. The section of the code currently looks like this
(contained in srclib/apr/include/apr_pools.h)
/*
#define ALLOC_DEBUG
#define POOL_DEBUG
#define ALLOC_USE_MALLOC
#define MAKE_TABLE_PROFILE
#define ALLOC_STATS
*/
typedef struct ap_pool_t {
union block_hdr *first;
union block_hdr *last;
struct cleanup *cleanups;
struct process_chain *subprocesses;
struct ap_pool_t *sub_pools;
struct ap_pool_t *sub_next;
struct ap_pool_t *sub_prev;
struct ap_pool_t *parent;
char *free_first_avail;
#ifdef ALLOC_USE_MALLOC
void *allocation_list;
#endif
#ifdef POOL_DEBUG
struct ap_pool_t *joined;
#endif
int (*apr_abort)(int retcode);
struct datastruct *prog_data;
} ap_pool_t;
To enable allocation debugging simply move the #define
ALLOC_DEBUG above the start of the comments block and rebuild
the server.
In order to use the various options the server must be rebuilt after editing the header file.
Apache HTTP Server Version 2.0
Apache 2.0 uses Doxygen to document the APIs and global variables in the code. This will explain the basics of how to document using Doxygen.
To start a documentation block, use /**
To end a documentation block, use */
In the middle of the block, there are multiple tags we can use:
Description of this functions purpose
@param parameter_name description
@return description
@deffunc signature of the function
The deffunc is not always necessary. DoxyGen does not
have a full parser in it, so any prototype that use a macro in the
return type declaration is too complex for scandoc. Those functions
require a deffunc. An example (using > rather
than >):
/**
* return the final element of the pathname
* @param pathname The path to get the final element of
* @return the final element of the path
* @tip Examples:
* <pre>
* "/foo/bar/gum" -> "gum"
* "/foo/bar/gum/" -> ""
* "gum" -> "gum"
* "wi\\n32\\stuff" -> "stuff"
* </pre>
* @deffunc const char * ap_filename_of_pathname(const char *pathname)
*/
At the top of the header file, always include:
/**
* @package Name of library header
*/
Doxygen uses a new HTML file for each package. The HTML files are named {Name_of_library_header}.html, so try to be concise with your names.
For a further discussion of the possibilities please refer to the Doxygen site.
Apache HTTP Server Version 2.0
This is a cut 'n paste job from an email (<022501c1c529$f63a9550$7f00000a@KOJ>) and only reformatted for better readability. It's not up to date but may be a good start for further research.
There are three basic filter types (each of these is actually broken down into two categories, but that comes later).
CONNECTIONAP_FTYPE_CONNECTION, AP_FTYPE_NETWORK)PROTOCOLAP_FTYPE_PROTOCOL,
AP_FTYPE_TRANSCODE)RESOURCEPROTOCOL, but internal redirects and sub-requests can change
the content without ending the request. (AP_FTYPE_RESOURCE,
AP_FTYPE_CONTENT_SET)It is important to make the distinction between a protocol and a resource filter. A resource filter is tied to a specific resource, it may also be tied to header information, but the main binding is to a resource. If you are writing a filter and you want to know if it is resource or protocol, the correct question to ask is: "Can this filter be removed if the request is redirected to a different resource?" If the answer is yes, then it is a resource filter. If it is no, then it is most likely a protocol or connection filter. I won't go into connection filters, because they seem to be well understood. With this definition, a few examples might help:
The further breakdown of each category into two more filter types is
strictly for ordering. We could remove it, and only allow for one
filter type, but the order would tend to be wrong, and we would need to
hack things to make it work. Currently, the RESOURCE filters
only have one filter type, but that should change.
This is actually rather simple in theory, but the code is
complex. First of all, it is important that everybody realize that
there are three filter lists for each request, but they are all
concatenated together. So, the first list is
r->output_filters, then r->proto_output_filters,
and finally r->connection->output_filters. These correspond
to the RESOURCE, PROTOCOL, and
CONNECTION filters respectively. The problem previously, was
that we used a singly linked list to create the filter stack, and we
started from the "correct" location. This means that if I had a
RESOURCE filter on the stack, and I added a
CONNECTION filter, the CONNECTION filter would
be ignored. This should make sense, because we would insert the connection
filter at the top of the c->output_filters list, but the end
of r->output_filters pointed to the filter that used to be
at the front of c->output_filters. This is obviously wrong.
The new insertion code uses a doubly linked list. This has the advantage
that we never lose a filter that has been inserted. Unfortunately, it comes
with a separate set of headaches.
The problem is that we have two different cases were we use subrequests. The first is to insert more data into a response. The second is to replace the existing response with an internal redirect. These are two different cases and need to be treated as such.
In the first case, we are creating the subrequest from within a handler
or filter. This means that the next filter should be passed to
make_sub_request function, and the last resource filter in the
sub-request will point to the next filter in the main request. This
makes sense, because the sub-request's data needs to flow through the
same set of filters as the main request. A graphical representation
might help:
Default_handler --> includes_filter --> byterange --> ...
If the includes filter creates a sub request, then we don't want the data from that sub-request to go through the includes filter, because it might not be SSI data. So, the subrequest adds the following:
Default_handler --> includes_filter -/-> byterange --> ...
/
Default_handler --> sub_request_core
What happens if the subrequest is SSI data? Well, that's easy, the
includes_filter is a resource filter, so it will be added to
the sub request in between the Default_handler and the
sub_request_core filter.
The second case for sub-requests is when one sub-request is going to
become the real request. This happens whenever a sub-request is created
outside of a handler or filter, and NULL is passed as the next filter to
the make_sub_request function.
In this case, the resource filters no longer make sense for the new request, because the resource has changed. So, instead of starting from scratch, we simply point the front of the resource filters for the sub-request to the front of the protocol filters for the old request. This means that we won't lose any of the protocol filters, neither will we try to send this data through a filter that shouldn't see it.
The problem is that we are using a doubly-linked list for our filter stacks now. But, you should notice that it is possible for two lists to intersect in this model. So, you do you handle the previous pointer? This is a very difficult question to answer, because there is no "right" answer, either method is equally valid. I looked at why we use the previous pointer. The only reason for it is to allow for easier addition of new servers. With that being said, the solution I chose was to make the previous pointer always stay on the original request.
This causes some more complex logic, but it works for all cases. My concern in having it move to the sub-request, is that for the more common case (where a sub-request is used to add data to a response), the main filter chain would be wrong. That didn't seem like a good idea to me.
The final topic. :-) Mod_Asis is a bit of a hack, but the
handler needs to remove all filters except for connection filters, and
send the data. If you are using mod_asis, all other
bets are off.
The absolutely last point is that the reason this code was so hard to
get right, was because we had hacked so much to force it to work. I
wrote most of the hacks originally, so I am very much to blame.
However, now that the code is right, I have started to remove some
hacks. Most people should have seen that the reset_filters
and add_required_filters functions are gone. Those inserted
protocol level filters for error conditions, in fact, both functions did
the same thing, one after the other, it was really strange. Because we
don't lose protocol filters for error cases any more, those hacks went away.
The HTTP_HEADER, Content-length, and
Byterange filters are all added in the
insert_filters phase, because if they were added earlier, we
had some interesting interactions. Now, those could all be moved to be
inserted with the HTTP_IN, CORE, and
CORE_IN filters. That would make the code easier to
follow.
Apache HTTP Server Version 2.0
This document is still in development and may be partially out of date.
In general, a hook function is one that Apache will call at some point during the processing of a request. Modules can provide functions that are called, and specify when they get called in comparison to other modules.
In order to create a new hook, four things need to be done:
Use the AP_DECLARE_HOOK macro, which needs to be given
the return type of the hook function, the name of the hook, and the
arguments. For example, if the hook returns an int and
takes a request_rec * and an int and is
called do_something, then declare it like this:
AP_DECLARE_HOOK(int, do_something, (request_rec *r, int n))
This should go in a header which modules will include if they want to use the hook.
Each source file that exports a hook has a private structure which is used to record the module functions that use the hook. This is declared as follows:
APR_HOOK_STRUCT(
APR_HOOK_LINK(do_something)
...
)
The source file that exports the hook has to implement a
function that will call the hook. There are currently three
possible ways to do this. In all cases, the calling function is
called ap_run_hookname().
If the return value of a hook is void, then all the
hooks are called, and the caller is implemented like this:
AP_IMPLEMENT_HOOK_VOID(do_something, (request_rec *r, int n), (r, n))
The second and third arguments are the dummy argument declaration and the dummy arguments as they will be used when calling the hook. In other words, this macro expands to something like this:
void ap_run_do_something(request_rec *r, int n)
{
...
do_something(r, n);
}
If the hook returns a value, then it can either be run until the first hook that does something interesting, like so:
AP_IMPLEMENT_HOOK_RUN_FIRST(int, do_something, (request_rec *r, int n), (r, n), DECLINED)
The first hook that does not return DECLINED
stops the loop and its return value is returned from the hook
caller. Note that DECLINED is the tradition Apache
hook return meaning "I didn't do anything", but it can be
whatever suits you.
Alternatively, all hooks can be run until an error occurs. This boils down to permitting two return values, one of which means "I did something, and it was OK" and the other meaning "I did nothing". The first function that returns a value other than one of those two stops the loop, and its return is the return value. Declare these like so:
AP_IMPLEMENT_HOOK_RUN_ALL(int, do_something, (request_rec *r, int n), (r, n), OK, DECLINED)
Again, OK and DECLINED are the traditional
values. You can use what you want.
At appropriate moments in the code, call the hook caller, like so:
int n, ret;
request_rec *r;
ret=ap_run_do_something(r, n);
A module that wants a hook to be called needs to do two things.
Include the appropriate header, and define a static function of the correct type:
static int my_something_doer(request_rec *r, int n)
{
...
return OK;
}
During initialisation, Apache will call each modules hook registering function, which is included in the module structure:
static void my_register_hooks()
{
ap_hook_do_something(my_something_doer, NULL, NULL, HOOK_MIDDLE);
}
mode MODULE_VAR_EXPORT my_module =
{
...
my_register_hooks /* register hooks */
};
In the example above, we didn't use the three arguments in
the hook registration function that control calling order.
There are two mechanisms for doing this. The first, rather
crude, method, allows us to specify roughly where the hook is
run relative to other modules. The final argument control this.
There are three possible values: HOOK_FIRST,
HOOK_MIDDLE and HOOK_LAST.
All modules using any particular value may be run in any
order relative to each other, but, of course, all modules using
HOOK_FIRST will be run before HOOK_MIDDLE
which are before HOOK_LAST. Modules that don't care
when they are run should use HOOK_MIDDLE. (I spaced
these out so people could do stuff like HOOK_FIRST-2
to get in slightly earlier, but is this wise? - Ben)
Note that there are two more values,
HOOK_REALLY_FIRST and HOOK_REALLY_LAST. These
should only be used by the hook exporter.
The other method allows finer control. When a module knows that it must be run before (or after) some other modules, it can specify them by name. The second (third) argument is a NULL-terminated array of strings consisting of the names of modules that must be run before (after) the current module. For example, suppose we want "mod_xyz.c" and "mod_abc.c" to run before we do, then we'd hook as follows:
static void register_hooks()
{
static const char * const aszPre[] = { "mod_xyz.c", "mod_abc.c", NULL };
ap_hook_do_something(my_something_doer, aszPre, NULL, HOOK_MIDDLE);
}
Note that the sort used to achieve this is stable, so
ordering set by HOOK_ORDER is preserved, as far
as is possible.
Ben Laurie, 15th August 1999
Apache HTTP Server Version 2.0
Many of the documents on these Developer pages are lifted from Apache 1.3's documentation. While they are all being updated to Apache 2.0, they are in different stages of progress. Please be patient, and point out any discrepancies or errors on the developer/ pages directly to the dev@httpd.apache.org mailing list.
Apache HTTP Server Version 2.0
This is a first attempt at writing the lessons I learned
when trying to convert the mod_mmap_static module to Apache
2.0. It's by no means definitive and probably won't even be
correct in some ways, but it's a start.
These now need to be of type apr_status_t and return a
value of that type. Normally the return value will be
APR_SUCCESS unless there is some need to signal an error in
the cleanup. Be aware that even though you signal an error not all code
yet checks and acts upon the error.
These should now be renamed to better signify where they sit
in the overall process. So the name gets a small change from
mmap_init to mmap_post_config. The arguments
passed have undergone a radical change and now look like
apr_pool_t *papr_pool_t *plogapr_pool_t *ptempserver_rec *sA lot of the data types have been moved into the APR. This means that some have had a name change, such as the one shown above. The following is a brief list of some of the changes that you are likely to have to make.
pool becomes apr_pool_ttable becomes apr_table_tThe new architecture uses a series of hooks to provide for
calling your functions. These you'll need to add to your module
by way of a new function, static void register_hooks(void).
The function is really reasonably straightforward once you
understand what needs to be done. Each function that needs
calling at some stage in the processing of a request needs to
be registered, handlers do not. There are a number of phases
where functions can be added, and for each you can specify with
a high degree of control the relative order that the function
will be called in.
This is the code that was added to mod_mmap_static:
static void register_hooks(void)
{
static const char * const aszPre[]={ "http_core.c",NULL };
ap_hook_post_config(mmap_post_config,NULL,NULL,HOOK_MIDDLE);
ap_hook_translate_name(mmap_static_xlat,aszPre,NULL,HOOK_LAST);
};This registers 2 functions that need to be called, one in
the post_config stage (virtually every module will need this
one) and one for the translate_name phase. note that while
there are different function names the format of each is
identical. So what is the format?
ap_hook_phase_name(function_name,
predecessors, successors, position);
There are 3 hook positions defined...
HOOK_FIRSTHOOK_MIDDLEHOOK_LASTTo define the position you use the position and then modify it with the predecessors and successors. Each of the modifiers can be a list of functions that should be called, either before the function is run (predecessors) or after the function has run (successors).
In the mod_mmap_static case I didn't care about the
post_config stage, but the mmap_static_xlat
must be called after the core module had done it's name
translation, hence the use of the aszPre to define a modifier to the
position HOOK_LAST.
There are now a lot fewer stages to worry about when creating your module definition. The old defintion looked like
module MODULE_VAR_EXPORT module_name_module =
{
STANDARD_MODULE_STUFF,
/* initializer */
/* dir config creater */
/* dir merger --- default is to override */
/* server config */
/* merge server config */
/* command handlers */
/* handlers */
/* filename translation */
/* check_user_id */
/* check auth */
/* check access */
/* type_checker */
/* fixups */
/* logger */
/* header parser */
/* child_init */
/* child_exit */
/* post read-request */
};The new structure is a great deal simpler...
module MODULE_VAR_EXPORT module_name_module =
{
STANDARD20_MODULE_STUFF,
/* create per-directory config structures */
/* merge per-directory config structures */
/* create per-server config structures */
/* merge per-server config structures */
/* command handlers */
/* handlers */
/* register hooks */
};Some of these read directly across, some don't. I'll try to summarise what should be done below.
The stages that read directly across :
/* dir config creater *//* create per-directory config structures *//* server config *//* create per-server config structures *//* dir merger *//* merge per-directory config structures *//* merge server config *//* merge per-server config structures *//* command table *//* command apr_table_t *//* handlers *//* handlers */The remainder of the old functions should be registered as hooks. There are the following hook stages defined so far...
ap_hook_post_config_init routines get
registeredap_hook_http_methodap_hook_open_logsap_hook_auth_checkerap_hook_access_checkerap_hook_check_user_idap_hook_default_portap_hook_pre_connectionap_hook_process_connectionap_hook_child_initap_hook_create_requestap_hook_fixupsap_hook_handlerap_hook_header_parserpost_read_request for thisap_hook_insert_filterap_hook_log_transactionap_hook_optional_fn_retrieveap_hook_post_read_requestap_hook_quick_handlerap_hook_translate_nameap_hook_type_checkerApache HTTP Server Version 2.0
Warning - this is a first (fast) draft that needs further revision!
Several changes in Apache 2.0 affect the internal request processing mechanics. Module authors need to be aware of these changes so they may take advantage of the optimizations and security enhancements.
The first major change is to the subrequest and redirect
mechanisms. There were a number of different code paths in
Apache 1.3 to attempt to optimize subrequest or redirect
behavior. As patches were introduced to 2.0, these
optimizations (and the server behavior) were quickly broken due
to this duplication of code. All duplicate code has been folded
back into ap_process_request_internal() to prevent
the code from falling out of sync again.
This means that much of the existing code was 'unoptimized'. It is the Apache HTTP Project's first goal to create a robust and correct implementation of the HTTP server RFC. Additional goals include security, scalability and optimization. New methods were sought to optimize the server (beyond the performance of Apache 1.3) without introducing fragile or insecure code.
All requests pass through ap_process_request_internal()
in request.c, including subrequests and redirects. If a module
doesn't pass generated requests through this code, the author is cautioned
that the module may be broken by future changes to request
processing.
To streamline requests, the module author can take advantage of the hooks offered to drop out of the request cycle early, or to bypass core Apache hooks which are irrelevant (and costly in terms of CPU.)
The request's parsed_uri path is unescaped, once and only
once, at the beginning of internal request processing.
This step is bypassed if the proxyreq flag is set, or the
parsed_uri.path element is unset. The module has no further
control of this one-time unescape operation, either failing to
unescape or multiply unescaping the URL leads to security
reprecussions.
All /../ and /./ elements are
removed by ap_getparents(). This helps to ensure
the path is (nearly) absolute before the request processing
continues.
This step cannot be bypassed.
Every request is subject to an
ap_location_walk() call. This ensures that
<Location> sections
are consistently enforced for all requests. If the request is an internal
redirect or a sub-request, it may borrow some or all of the processing
from the previous or parent request's ap_location_walk, so this step
is generally very efficient after processing the main request.
Modules can determine the file name, or alter the given URI
in this step. For example, mod_vhost_alias will
translate the URI's path into the configured virtual host,
mod_alias will translate the path to an alias path,
and if the request falls back on the core, the DocumentRoot is prepended to the request resource.
If all modules DECLINE this phase, an error 500 is
returned to the browser, and a "couldn't translate name" error is logged
automatically.
After the file or correct URI was determined, the
appropriate per-dir configurations are merged together. For
example, mod_proxy compares and merges the appropriate
<Proxy> sections.
If the URI is nothing more than a local (non-proxy) TRACE
request, the core handles the request and returns DONE.
If no module answers this hook with OK or DONE,
the core will run the request filename against the <Directory> and <Files> sections. If the request
'filename' isn't an absolute, legal filename, a note is set for
later termination.
Every request is hardened by a second
ap_location_walk() call. This reassures that a
translated request is still subjected to the configured
<Location> sections.
The request again borrows some or all of the processing from its previous
location_walk above, so this step is almost always very
efficient unless the translated URI mapped to a substantially different
path or Virtual Host.
The main request then parses the client's headers. This prepares the remaining request processing steps to better serve the client's request.
Needs Documentation. Code is:
switch (ap_satisfies(r)) {
case SATISFY_ALL:
case SATISFY_NOSPEC:
if ((access_status = ap_run_access_checker(r)) != 0) {
return decl_die(access_status, "check access", r);
}
if (ap_some_auth_required(r)) {
if (((access_status = ap_run_check_user_id(r)) != 0)
|| !ap_auth_type(r)) {
return decl_die(access_status, ap_auth_type(r)
? "check user. No user file?"
: "perform authentication. AuthType not set!",
r);
}
if (((access_status = ap_run_auth_checker(r)) != 0)
|| !ap_auth_type(r)) {
return decl_die(access_status, ap_auth_type(r)
? "check access. No groups file?"
: "perform authentication. AuthType not set!",
r);
}
}
break;
case SATISFY_ANY:
if (((access_status = ap_run_access_checker(r)) != 0)) {
if (!ap_some_auth_required(r)) {
return decl_die(access_status, "check access", r);
}
if (((access_status = ap_run_check_user_id(r)) != 0)
|| !ap_auth_type(r)) {
return decl_die(access_status, ap_auth_type(r)
? "check user. No user file?"
: "perform authentication. AuthType not set!",
r);
}
if (((access_status = ap_run_auth_checker(r)) != 0)
|| !ap_auth_type(r)) {
return decl_die(access_status, ap_auth_type(r)
? "check access. No groups file?"
: "perform authentication. AuthType not set!",
r);
}
}
break;
}The modules have an opportunity to test the URI or filename
against the target resource, and set mime information for the
request. Both mod_mime and
mod_mime_magic use this phase to compare the file
name or contents against the administrator's configuration and set the
content type, language, character set and request handler. Some modules
may set up their filters or other request handling parameters at this
time.
If all modules DECLINE this phase, an error 500 is
returned to the browser, and a "couldn't find types" error is logged
automatically.
Many modules are 'trounced' by some phase above. The fixups phase is used by modules to 'reassert' their ownership or force the request's fields to their appropriate values. It isn't always the cleanest mechanism, but occasionally it's the only option.
This phase is not part of the processing in
ap_process_request_internal(). Many
modules prepare one or more subrequests prior to creating any
content at all. After the core, or a module calls
ap_process_request_internal() it then calls
ap_invoke_handler() to generate the request.
Modules that transform the content in some way can insert their values and override existing filters, such that if the user configured a more advanced filter out-of-order, then the module can move its order as need be. There is no result code, so actions in this hook better be trusted to always succeed.
The module finally has a chance to serve the request in its
handler hook. Note that not every prepared request is sent to
the handler hook. Many modules, such as mod_autoindex,
will create subrequests for a given URI, and then never serve the
subrequest, but simply lists it for the user. Remember not to
put required teardown from the hooks above into this module,
but register pool cleanups against the request pool to free
resources as required.
Apache HTTP Server Version 2.0
When using any of the threaded mpms in Apache 2.0 it is important that every function called from Apache be thread safe. When linking in 3rd party extensions it can be difficult to determine whether the resulting server will be thread safe. Casual testing generally won't tell you this either as thread safety problems can lead to subtle race conditons that may only show up in certain conditions under heavy load.
When writing your module or when trying to determine if a module or 3rd party library is thread safe there are some common things to keep in mind.
First, you need to recognize that in a threaded model each individual thread has its own program counter, stack and registers. Local variables live on the stack, so those are fine. You need to watch out for any static or global variables. This doesn't mean that you are absolutely not allowed to use static or global variables. There are times when you actually want something to affect all threads, but generally you need to avoid using them if you want your code to be thread safe.
In the case where you have a global variable that needs to be global and accessed by all threads, be very careful when you update it. If, for example, it is an incrementing counter, you need to atomically increment it to avoid race conditions with other threads. You do this using a mutex (mutual exclusion). Lock the mutex, read the current value, increment it and write it back and then unlock the mutex. Any other thread that wants to modify the value has to first check the mutex and block until it is cleared.
If you are using APR, have a look
at the apr_atomic_* functions and the
apr_thread_mutex_* functions.
This is a common global variable that holds the error number of the
last error that occurred. If one thread calls a low-level function that
sets errno and then another thread checks it, we are bleeding error
numbers from one thread into another. To solve this, make sure your
module or library defines _REENTRANT or is compiled with
-D_REENTRANT. This will make errno a per-thread variable
and should hopefully be transparent to the code. It does this by doing
something like this:
#define errno (*(__errno_location()))
which means that accessing errno will call
__errno_location() which is provided by the libc. Setting
_REENTRANT also forces redefinition of some other functions
to their *_r equivalents and sometimes changes
the common getc/putc macros into safer function
calls. Check your libc documentation for specifics. Instead of, or in
addition to _REENTRANT the symbols that may affect this are
_POSIX_C_SOURCE, _THREAD_SAFE,
_SVID_SOURCE, and _BSD_SOURCE.
Not only do things have to be thread safe, but they also have to be
reentrant. strtok() is an obvious one. You call it the first
time with your delimiter which it then remembers and on each subsequent
call it returns the next token. Obviously if multiple threads are
calling it you will have a problem. Most systems have a reentrant version
of of the function called strtok_r() where you pass in an
extra argument which contains an allocated char * which the
function will use instead of its own static storage for maintaining
the tokenizing state. If you are using APR you can use apr_strtok().
crypt() is another function that tends to not be reentrant,
so if you run across calls to that function in a library, watch out. On
some systems it is reentrant though, so it is not always a problem. If
your system has crypt_r() chances are you should be using
that, or if possible simply avoid the whole mess by using md5 instead.
The following is a list of common libraries that are used by 3rd party
Apache modules. You can check to see if your module is using a potentially
unsafe library by using tools such as ldd(1) and
nm(1). For PHP, for example,
try this:
% ldd libphp4.so
libsablot.so.0 => /usr/local/lib/libsablot.so.0 (0x401f6000)
libexpat.so.0 => /usr/lib/libexpat.so.0 (0x402da000)
libsnmp.so.0 => /usr/lib/libsnmp.so.0 (0x402f9000)
libpdf.so.1 => /usr/local/lib/libpdf.so.1 (0x40353000)
libz.so.1 => /usr/lib/libz.so.1 (0x403e2000)
libpng.so.2 => /usr/lib/libpng.so.2 (0x403f0000)
libmysqlclient.so.11 => /usr/lib/libmysqlclient.so.11 (0x40411000)
libming.so => /usr/lib/libming.so (0x40449000)
libm.so.6 => /lib/libm.so.6 (0x40487000)
libfreetype.so.6 => /usr/lib/libfreetype.so.6 (0x404a8000)
libjpeg.so.62 => /usr/lib/libjpeg.so.62 (0x404e7000)
libcrypt.so.1 => /lib/libcrypt.so.1 (0x40505000)
libssl.so.2 => /lib/libssl.so.2 (0x40532000)
libcrypto.so.2 => /lib/libcrypto.so.2 (0x40560000)
libresolv.so.2 => /lib/libresolv.so.2 (0x40624000)
libdl.so.2 => /lib/libdl.so.2 (0x40634000)
libnsl.so.1 => /lib/libnsl.so.1 (0x40637000)
libc.so.6 => /lib/libc.so.6 (0x4064b000)
/lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x80000000)
In addition to these libraries you will need to have a look at any
libraries linked statically into the module. You can use nm(1)
to look for individual symbols in the module.
Please drop a note to dev@httpd.apache.org if you have additions or corrections to this list.
| Library | Version | Thread Safe? | Notes |
|---|---|---|---|
| ASpell/PSpell | ? | ||
| Berkeley DB | 3.x, 4.x | Yes | Be careful about sharing a connection across threads. |
| bzip2 | Yes | Both low-level and high-level APIs are thread-safe. However, high-level API requires thread-safe access to errno. | |
| cdb | ? | ||
| C-Client | Perhaps | c-client uses strtok() and
gethostbyname() which are not thread-safe on most C
library implementations. c-client's static data is meant to be shared
across threads. If strtok() and
gethostbyname() are thread-safe on your OS, c-client
may be thread-safe. | |
| cpdflib | ? | ||
| libcrypt | ? | ||
| Expat | Yes | Need a separate parser instance per thread | |
| FreeTDS | ? | ||
| FreeType | ? | ||
| GD 1.8.x | ? | ||
| GD 2.0.x | ? | ||
| gdbm | No | Errors returned via a static gdbm_error
variable | |
| ImageMagick | 5.2.2 | Yes | ImageMagick docs claim it is thread safe since version 5.2.2 (see Change log). |
| Imlib2 | ? | ||
| libjpeg | v6b | ? | |
| libmysqlclient | Yes | Use mysqlclient_r library variant to ensure thread-safety. For more information, please read http://www.mysql.com/doc/en/Threaded_clients.html. | |
| Ming | 0.2a | ? | |
| Net-SNMP | 5.0.x | ? | |
| OpenLDAP | 2.1.x | Yes | Use ldap_r library variant to ensure
thread-safety. |
| OpenSSL | 0.9.6g | Yes | Requires proper usage of CRYPTO_num_locks,
CRYPTO_set_locking_callback,
CRYPTO_set_id_callback |
| liboci8 (Oracle 8+) | 8.x,9.x | ? | |
| pdflib | 5.0.x | Yes | PDFLib docs claim it is thread safe; changes.txt indicates it has been partially thread-safe since V1.91: http://www.pdflib.com/products/pdflib/index.html. |
| libpng | 1.0.x | ? | |
| libpng | 1.2.x | ? | |
| libpq (PostgreSQL) | 7.x | Yes | Don't share connections across threads and watch out for
crypt() calls |
| Sablotron | 0.95 | ? | |
| zlib | 1.1.4 | Yes | Relies upon thread-safe zalloc and zfree functions Default is to use libc's calloc/free which are thread-safe. |
Apache HTTP Server Version 2.0
This page could be summarized with the statement: don't configure Apache in such a way that it relies on DNS resolution for parsing of the configuration files. If Apache requires DNS resolution to parse the configuration files then your server may be subject to reliability problems (ie. it might not boot), or denial and theft of service attacks (including users able to steal hits from other users).
<VirtualHost www.abc.dom>
ServerAdmin webgirl@abc.dom
DocumentRoot /www/abc
</VirtualHost>
In order for Apache to function properly, it absolutely needs
to have two pieces of information about each virtual host: the
ServerName and at least one
IP address that the server will bind and respond to. The above
example does not include the IP address, so Apache must use DNS
to find the address of www.abc.dom. If for some
reason DNS is not available at the time your server is parsing
its config file, then this virtual host will not be
configured. It won't be able to respond to any hits
to this virtual host (prior to Apache version 1.2 the server
would not even boot).
Suppose that www.abc.dom has address 10.0.0.1.
Then consider this configuration snippet:
<VirtualHost 10.0.0.1>
ServerAdmin webgirl@abc.dom
DocumentRoot /www/abc
</VirtualHost>
This time Apache needs to use reverse DNS to find the
ServerName for this virtualhost. If that reverse
lookup fails then it will partially disable the virtualhost
(prior to Apache version 1.2 the server would not even boot).
If the virtual host is name-based then it will effectively be
totally disabled, but if it is IP-based then it will mostly
work. However, if Apache should ever have to generate a full
URL for the server which includes the server name, then it will
fail to generate a valid URL.
Here is a snippet that avoids both of these problems:
<VirtualHost 10.0.0.1>
ServerName www.abc.dom
ServerAdmin webgirl@abc.dom
DocumentRoot /www/abc
</VirtualHost>
There are (at least) two forms that denial of service
can come in. If you are running a version of Apache prior to
version 1.2 then your server will not even boot if one of the
two DNS lookups mentioned above fails for any of your virtual
hosts. In some cases this DNS lookup may not even be under your
control; for example, if abc.dom is one of your
customers and they control their own DNS, they can force your
(pre-1.2) server to fail while booting simply by deleting the
www.abc.dom record.
Another form is far more insidious. Consider this configuration snippet:
<VirtualHost www.abc.dom>
ServerAdmin webgirl@abc.dom
DocumentRoot /www/abc
</VirtualHost>
<VirtualHost www.def.dom>
ServerAdmin webguy@def.dom
DocumentRoot /www/def
</VirtualHost>
Suppose that you've assigned 10.0.0.1 to
www.abc.dom and 10.0.0.2 to
www.def.dom. Furthermore, suppose that
def.dom has control of their own DNS. With this
config you have put def.dom into a position where
they can steal all traffic destined to abc.dom. To
do so, all they have to do is set www.def.dom to
10.0.0.1. Since they control their own DNS you can't stop them
from pointing the www.def.dom record wherever they
wish.
Requests coming in to 10.0.0.1 (including all those where
users typed in URLs of the form
http://www.abc.dom/whatever) will all be served by
the def.dom virtual host. To better understand why
this happens requires a more in-depth discussion of how Apache
matches up incoming requests with the virtual host that will
serve it. A rough document describing this is available.
The addition of name-based
virtual host support in Apache 1.1 requires Apache to know
the IP address(es) of the host that httpd is running
on. To get this address it uses either the global
ServerName
(if present) or calls the C function gethostname
(which should return the same as typing "hostname" at the
command prompt). Then it performs a DNS lookup on this address.
At present there is no way to avoid this lookup.
If you fear that this lookup might fail because your DNS
server is down then you can insert the hostname in
/etc/hosts (where you probably already have it so
that the machine can boot properly). Then ensure that your
machine is configured to use /etc/hosts in the
event that DNS fails. Depending on what OS you are using this
might be accomplished by editing /etc/resolv.conf,
or maybe /etc/nsswitch.conf.
If your server doesn't have to perform DNS for any other
reason then you might be able to get away with running Apache
with the HOSTRESORDER environment variable set to
"local". This all depends on what OS and resolver libraries you
are using. It also affects CGIs unless you use
mod_env to control the environment. It's best
to consult the man pages or FAQs for your OS.
VirtualHost
Listen
ServerName
<VirtualHost _default_:*>
server that has no pages to serveThe situation regarding DNS is highly undesirable. For Apache 1.2 we've attempted to make the server at least continue booting in the event of failed DNS, but it might not be the best we can do. In any event, requiring the use of explicit IP addresses in configuration files is highly undesirable in today's Internet where renumbering is a necessity.
A possible work around to the theft of service attack described above would be to perform a reverse DNS lookup on the IP address returned by the forward lookup and compare the two names -- in the event of a mismatch, the virtualhost would be disabled. This would require reverse DNS to be configured properly (which is something that most admins are familiar with because of the common use of "double-reverse" DNS lookups by FTP servers and TCP wrappers).
In any event, it doesn't seem possible to reliably boot a virtual-hosted web server when DNS has failed unless IP addresses are used. Partial solutions such as disabling portions of the configuration might be worse than not booting at all depending on what the webserver is supposed to accomplish.
As HTTP/1.1 is deployed and browsers and proxies start
issuing the Host header it will become possible to
avoid the use of IP-based virtual hosts entirely. In this case,
a webserver has no requirement to do DNS lookups during
configuration. But as of March 1997 these features have not
been deployed widely enough to be put into use on critical
webservers.
Apache HTTP Server Version 2.0
The Apache HTTP Server is a modular program where the
administrator can choose the functionality to include in the
server by selecting a set of modules. The modules can be
statically compiled into the httpd binary when the
server is built. Alternatively, modules can be compiled as
Dynamic Shared Objects (DSOs) that exist separately from the
main httpd binary file. DSO modules may be
compiled at the time the server is built, or they may be
compiled and added at a later time using the Apache Extension
Tool (apxs).
This document describes how to use DSO modules as well as the theory behind their use.
| Related Modules | Related Directives |
|---|---|
The DSO support for loading individual Apache modules is based
on a module named mod_so which must be statically
compiled into the Apache core. It is the only module besides
core which cannot be put into a DSO
itself. Practically all other distributed Apache modules can then
be placed into a DSO by individually enabling the DSO build for
them via configure's
--enable-module=shared option as discussed
in the install documentation. After a
module is compiled into a DSO named mod_foo.so you
can use mod_so's LoadModule command in your
httpd.conf file to load this module at server startup
or restart.
To simplify this creation of DSO files for Apache modules
(especially for third-party modules) a new support program
named apxs (APache
eXtenSion) is available. It can be used to build DSO based
modules outside of the Apache source tree. The idea is
simple: When installing Apache the configure's
make install procedure installs the Apache C
header files and puts the platform-dependent compiler and
linker flags for building DSO files into the apxs
program. This way the user can use apxs to compile
his Apache module sources without the Apache distribution
source tree and without having to fiddle with the
platform-dependent compiler and linker flags for DSO
support.
To give you an overview of the DSO features of Apache 2.x, here is a short and concise summary:
mod_foo.c, into its own DSO
mod_foo.so:
$ ./configure --prefix=/path/to/install --enable-foo=shared
$ make install
mod_foo.c, into its own DSO
mod_foo.so:
$ ./configure --add-module=module_type:/path/to/3rdparty/mod_foo.c --enable-foo=shared
$ make install
$ ./configure --enable-so
$ make install
mod_foo.c, into its own DSO
mod_foo.so outside of the Apache
source tree using apxs:
$ cd /path/to/3rdparty
$ apxs -c mod_foo.c
$ apxs -i -a -n foo mod_foo.la
In all cases, once the shared module is compiled, you must
use a LoadModule
directive in httpd.conf to tell Apache to activate
the module.
On modern Unix derivatives there exists a nifty mechanism usually called dynamic linking/loading of Dynamic Shared Objects (DSO) which provides a way to build a piece of program code in a special format for loading it at run-time into the address space of an executable program.
This loading can usually be done in two ways: Automatically
by a system program called ld.so when an
executable program is started or manually from within the
executing program via a programmatic system interface to the
Unix loader through the system calls
dlopen()/dlsym().
In the first way the DSO's are usually called shared
libraries or DSO libraries and named
libfoo.so or libfoo.so.1.2. They
reside in a system directory (usually /usr/lib)
and the link to the executable program is established at
build-time by specifying -lfoo to the linker
command. This hard-codes library references into the executable
program file so that at start-time the Unix loader is able to
locate libfoo.so in /usr/lib, in
paths hard-coded via linker-options like -R or in
paths configured via the environment variable
LD_LIBRARY_PATH. It then resolves any (yet
unresolved) symbols in the executable program which are
available in the DSO.
Symbols in the executable program are usually not referenced
by the DSO (because it's a reusable library of general code)
and hence no further resolving has to be done. The executable
program has no need to do anything on its own to use the
symbols from the DSO because the complete resolving is done by
the Unix loader. (In fact, the code to invoke
ld.so is part of the run-time startup code which
is linked into every executable program which has been bound
non-static). The advantage of dynamic loading of common library
code is obvious: the library code needs to be stored only once,
in a system library like libc.so, saving disk
space for every program.
In the second way the DSO's are usually called shared
objects or DSO files and can be named with an
arbitrary extension (although the canonical name is
foo.so). These files usually stay inside a
program-specific directory and there is no automatically
established link to the executable program where they are used.
Instead the executable program manually loads the DSO at
run-time into its address space via dlopen(). At
this time no resolving of symbols from the DSO for the
executable program is done. But instead the Unix loader
automatically resolves any (yet unresolved) symbols in the DSO
from the set of symbols exported by the executable program and
its already loaded DSO libraries (especially all symbols from
the ubiquitous libc.so). This way the DSO gets
knowledge of the executable program's symbol set as if it had
been statically linked with it in the first place.
Finally, to take advantage of the DSO's API the executable
program has to resolve particular symbols from the DSO via
dlsym() for later use inside dispatch tables
etc. In other words: The executable program has to
manually resolve every symbol it needs to be able to use it.
The advantage of such a mechanism is that optional program
parts need not be loaded (and thus do not spend memory) until
they are needed by the program in question. When required,
these program parts can be loaded dynamically to extend the
base program's functionality.
Although this DSO mechanism sounds straightforward there is at least one difficult step here: The resolving of symbols from the executable program for the DSO when using a DSO to extend a program (the second way). Why? Because "reverse resolving" DSO symbols from the executable program's symbol set is against the library design (where the library has no knowledge about the programs it is used by) and is neither available under all platforms nor standardized. In practice the executable program's global symbols are often not re-exported and thus not available for use in a DSO. Finding a way to force the linker to export all global symbols is the main problem one has to solve when using DSO for extending a program at run-time.
The shared library approach is the typical one, because it is what the DSO mechanism was designed for, hence it is used for nearly all types of libraries the operating system provides. On the other hand using shared objects for extending a program is not used by a lot of programs.
As of 1998 there are only a few software packages available which use the DSO mechanism to actually extend their functionality at run-time: Perl 5 (via its XS mechanism and the DynaLoader module), Netscape Server, etc. Starting with version 1.3, Apache joined the crew, because Apache already uses a module concept to extend its functionality and internally uses a dispatch-list-based approach to link external modules into the Apache core functionality. So, Apache is really predestined for using DSO to load its modules at run-time.
The above DSO based features have the following advantages:
LoadModule
httpd.conf configuration commands instead of
configure options at build-time. For instance
this way one is able to run different server instances
(standard & SSL version, minimalistic & powered up
version [mod_perl, PHP3], etc.) with only one Apache
installation.apxs pair you can both work outside the
Apache source tree and only need an apxs -i
command followed by an apachectl restart to
bring a new version of your currently developed module into
the running Apache server.DSO has the following disadvantages:
ld -lfoo) on all platforms
(for instance a.out-based platforms usually don't provide
this functionality while ELF-based platforms do) you cannot
use the DSO mechanism for all types of modules. Or in other
words, modules compiled as DSO files are restricted to only
use symbols from the Apache core, from the C library
(libc) and all other dynamic or static libraries
used by the Apache core, or from static library archives
(libfoo.a) containing position independent code.
The only chances to use other code is to either make sure the
Apache core itself already contains a reference to it or
loading the code yourself via dlopen().Apache HTTP Server Version 2.0
The Apache HTTP Server provides a mechanism for storing information in named variables that are called environment variables. This information can be used to control various operations such as logging or access control. The variables are also used as a mechanism to communicate with external programs such as CGI scripts. This document discusses different ways to manipulate and use these variables.
Although these variables are referred to as environment variables, they are not the same as the environment variables controlled by the underlying operating system. Instead, these variables are stored and manipulated in an internal Apache structure. They only become actual operating system environment variables when they are provided to CGI scripts and Server Side Include scripts. If you wish to manipulate the operating system environment under which the server itself runs, you must use the standard environment manipulation mechanisms provided by your operating system shell.
| Related Modules | Related Directives |
|---|---|
The most basic way to set an environment variable in Apache
is using the unconditional SetEnv directive. Variables may also be passed from
the environment of the shell which started the server using the
PassEnv directive.
For additional flexibility, the directives provided by
mod_setenvif allow environment variables to be set on a
per-request basis, conditional on characteristics of particular
requests. For example, a variable could be set only when a
specific browser (User-Agent) is making a request, or only when
a specific Referer [sic] header is found. Even more flexibility
is available through the mod_rewrite's RewriteRule which uses the
[E=...] option to set environment variables.
Finally, mod_unique_id sets the environment variable
UNIQUE_ID for each request to a value which is
guaranteed to be unique across "all" requests under very
specific conditions.
In addition to all environment variables set within the Apache configuration and passed from the shell, CGI scripts and SSI pages are provided with a set of environment variables containing meta-information about the request as required by the CGI specification.
suexec is used to launch
CGI scripts, the environment will be cleaned down to a set of
safe variables before CGI scripts are launched. The
list of safe variables is defined at compile-time in
suexec.c.| Related Modules | Related Directives |
|---|---|
One of the primary uses of environment variables is to communicate information to CGI scripts. As discussed above, the environment passed to CGI scripts includes standard meta-information about the request in addition to any variables set within the Apache configuration. For more details, see the CGI tutorial.
Server-parsed (SSI) documents processed by mod_include's
INCLUDES filter can print environment variables
using the echo element, and can use environment
variables in flow control elements to makes parts of a page
conditional on characteristics of a request. Apache also
provides SSI pages with the standard CGI environment variables
as discussed above. For more details, see the SSI tutorial.
Access to the server can be controlled based on the value of
environment variables using the allow from env=
and deny from env= directives. In combination with
SetEnvIf, this
allows for flexible control of access to the server based on
characteristics of the client. For example, you can use these
directives to deny access to a particular browser (User-Agent).
Environment variables can be logged in the access log using
the LogFormat
option %e. In addition, the decision on whether
or not to log requests can be made based on the status of
environment variables using the conditional form of the
CustomLog
directive. In combination with SetEnvIf this allows for flexible control of which
requests are logged. For example, you can choose not to log
requests for filenames ending in gif, or you can
choose to only log requests from clients which are outside your
subnet.
The Header
directive can use the presence or
absence of an environment variable to determine whether or not
a certain HTTP header will be placed in the response to the
client. This allows, for example, a certain response header to
be sent only if a corresponding header is received in the
request from the client.
External filters configured by mod_ext_filter
using the ExtFilterDefine directive can
by activated conditional on an environment variable using the
disableenv= and enableenv= options.
The %{ENV:...} form of TestString in
the RewriteCond
allows mod_rewrite's rewrite
engine to make decisions conditional on environment variables.
Note that the variables accessible in mod_rewrite without the
ENV: prefix are not actually environment
variables. Rather, they are variables special to mod_rewrite
which cannot be accessed from other modules.
Interoperability problems have led to the introduction of
mechanisms to modify the way Apache behaves when talking to
particular clients. To make these mechanisms as flexible as
possible, they are invoked by defining environment variables,
typically with BrowserMatch,
though SetEnv and
PassEnv could also be used,
for example.
This forces the request to be treated as a HTTP/1.0 request even if it was in a later dialect.
This causes any Vary fields to be removed from
the response header before it is sent back to the client. Some
clients don't interpret this field correctly (see the known client
problems page); setting this variable can work around this
problem. Setting this variable also implies
force-response-1.0.
This forces an HTTP/1.0 response to clients making an HTTP/1.0 request. It was originally implemented as a result of a problem with AOL's proxies. Some HTTP/1.0 clients may not behave correctly when given an HTTP/1.1 response, and this can be used to interoperate with them.
When set to a value of "1", this variable disables the DEFLATE
output filter provided by mod_deflate for
content-types other than text/html.
When set, the DEFLATE filter of
mod_deflate will be turned off.
This disables KeepAlive when set.
This influences mod_negotiation's behaviour. If
it contains a language tag (such as en, ja
or x-klingon), mod_negotiation tries
to deliver a variant with that language. If there's no such variant,
the normal negotiation process
applies.
This forces the server to be more careful when sending a redirect to the client. This is typically used when a client has a known problem handling redirects. This was originally implemented as a result of a problem with Microsoft's WebFolders software which has a problem handling redirects on directory resources via DAV methods.
Available in versions after 2.0.54
When Apache issues a redirect in response to a client request, the response includes some actual text to be displayed in case the client can't (or doesn't) automatically follow the redirection. Apache ordinarily labels this text according to the character set which it uses, which is ISO-8859-1.
However, if the redirection is to a page that uses a different character set, some broken browser versions will try to use the character set from the redirection text rather than the actual page. This can result in Greek, for instance, being incorrectly rendered.
Setting this environment variable causes Apache to omit the character set for the redirection text, and these broken browsers will then correctly use that of the destination page.
We recommend that the following lines be included in httpd.conf to deal with known client problems.
# # The following directives modify normal HTTP response behavior. # The first directive disables keepalive for Netscape 2.x and browsers that # spoof it. There are known problems with these browser implementations. # The second directive is for Microsoft Internet Explorer 4.0b2 # which has a broken HTTP/1.1 implementation and does not properly # support keepalive when it is used on 301 or 302 (redirect) responses. # BrowserMatch "Mozilla/2" nokeepalive BrowserMatch "MSIE 4\.0b2;" nokeepalive downgrade-1.0 force-response-1.0 # # The following directive disables HTTP/1.1 responses to browsers which # are in violation of the HTTP/1.0 spec by not being able to grok a # basic 1.1 response. # BrowserMatch "RealPlayer 4\.0" force-response-1.0 BrowserMatch "Java/1\.0" force-response-1.0 BrowserMatch "JDK/1\.0" force-response-1.0
This example keeps requests for images from appearing in the access log. It can be easily modified to prevent logging of particular directories, or to prevent logging of requests coming from particular hosts.
SetEnvIf Request_URI \.gif image-request SetEnvIf Request_URI \.jpg image-request SetEnvIf Request_URI \.png image-request CustomLog logs/access_log common env=!image-request
This example shows how to keep people not on your server from using images on your server as inline-images on their pages. This is not a recommended configuration, but it can work in limited circumstances. We assume that all your images are in a directory called /web/images.
SetEnvIf Referer "^http://www.example.com/" local_referal # Allow browsers that do not send Referer info SetEnvIf Referer "^$" local_referal <Directory /web/images> Order Deny,Allow Deny from all Allow from env=local_referal </Directory>
For more information about this technique, see the ApacheToday tutorial " Keeping Your Images from Adorning Other Sites".
Apache HTTP Server Version 2.0
The latest version of this FAQ is always available from the main Apache web site, at <http://httpd.apache.org/docs/2.0/faq/>.
Since Apache 2.0 is quite new, we don't yet know what the Frequently Asked Questions will be. While this section fills up, you should also consult the Apache 1.3 FAQ to see if your question is answered there.
If you are having trouble with your Apache server software, you should take the following steps:
/usr/local/apache2/logs/error_log, but see the ErrorLog directive in your config files for the
location on your server.Apache has an active community of users who are willing to share their knowledge. Participating in this community is usually the best and fastest way to get answers to your questions and problems.
USENET newsgroups:
If you've gone through those steps above that are appropriate and have obtained no relief, then please do let the httpd developers know about the problem by logging a bug report.
If your problem involves the server crashing and generating a core dump, please include a backtrace (if possible). As an example,
# cd ServerRoot
# dbx httpd core
(dbx) where
(Substitute the appropriate locations for your ServerRoot
and your httpd and core files. You may have to use
gdb instead of dbx.)
With several million users and fewer than forty volunteer developers, we cannot provide personal support for Apache. For free support, we suggest participating in a user forum.
Professional, commercial support for Apache is available from a number of companies.
Apache uses the sendfile syscall on platforms
where it is available in order to speed sending of responses.
Unfortunately, on some systems, Apache will detect the presence of
sendfile at compile-time, even when it does not work
properly. This happens most frequently when using network or
other non-standard file-system.
Symptoms of this problem include the above message in the error
log and zero-length responses to non-zero-sized files. The
problem generally occurs only for static files, since dynamic
content usually does not make use of sendfile.
To fix this problem, simply use the EnableSendfile directive to disable
sendfile for all or part of your server. Also see
the EnableMMAP, which can
help with similar problems.
If you get error messages related to the AcceptEx syscall
on win32, see the Win32DisableAcceptEx
directive.
Most problems with CGI scripts result in this message written in the
error log together with an Internal Server Error delivered
to the browser. A guide to helping debug this type of problem is
available in the CGI
tutorial.
Apache HTTP Server Version 2.0
Apache uses the sendfile syscall on platforms
where it is available in order to speed sending of responses.
Unfortunately, on some systems, Apache will detect the presence of
sendfile at compile-time, even when it does not work
properly. This happens most frequently when using network or
other non-standard file-system.
Symptoms of this problem include the above message in the error
log and zero-length responses to non-zero-sized files. The
problem generally occurs only for static files, since dynamic
content usually does not make use of sendfile.
To fix this problem, simply use the EnableSendfile directive to disable
sendfile for all or part of your server. Also see
the EnableMMAP, which can
help with similar problems.
If you get error messages related to the AcceptEx syscall
on win32, see the Win32DisableAcceptEx
directive.
Most problems with CGI scripts result in this message written in the
error log together with an Internal Server Error delivered
to the browser. A guide to helping debug this type of problem is
available in the CGI
tutorial.
Apache HTTP Server Version 2.0
The latest version of this FAQ is always available from the main Apache web site, at <http://httpd.apache.org/docs/2.0/faq/>. In addition, you can view this FAQ all in one page for easy searching and printing.
Since Apache 2.0 is quite new, we don't yet know what the Frequently Asked Questions will be. While this section fills up, you should also consult the Apache 1.3 FAQ to see if your question is answered there.
Apache HTTP Server Version 2.0
If you are having trouble with your Apache server software, you should take the following steps:
/usr/local/apache2/logs/error_log, but see the ErrorLog directive in your config files for the
location on your server.Apache has an active community of users who are willing to share their knowledge. Participating in this community is usually the best and fastest way to get answers to your questions and problems.
USENET newsgroups:
If you've gone through those steps above that are appropriate and have obtained no relief, then please do let the httpd developers know about the problem by logging a bug report.
If your problem involves the server crashing and generating a core dump, please include a backtrace (if possible). As an example,
# cd ServerRoot
# dbx httpd core
(dbx) where
(Substitute the appropriate locations for your ServerRoot
and your httpd and core files. You may have to use
gdb instead of dbx.)
With several million users and fewer than forty volunteer developers, we cannot provide personal support for Apache. For free support, we suggest participating in a user forum.
Professional, commercial support for Apache is available from a number of companies.
Apache HTTP Server Version 2.0
This document describes the use of filters in Apache.
| Related Modules | Related Directives |
|---|---|
A filter is a process that is applied to data that is sent or received by the server. Data sent by clients to the server is processed by input filters while data sent by the server to the client is processed by output filters. Multiple filters can be applied to the data, and the order of the filters can be explicitly specified.
Filters are used internally by Apache to perform functions such
as chunking and byte-range request handling. In addition, modules
can provide filters that are selectable using run-time
configuration directives. The set of filters that apply to data
can be manipulated with the
SetInputFilter,
SetOutputFilter,
AddInputFilter,
AddOutputFilter,
RemoveInputFilter, and
RemoveOutputFilter
directives.
The following user-selectable filters are currently provided with the Apache HTTP Server distribution.
mod_includemod_deflate
In addition, the module mod_ext_filter allows
for external programs to be defined as filters.
Apache HTTP Server Version 2.0
This glossary defines some of the common terminology related to Apache in particular, and web serving in general. More information on each concept is provided in the links.
apxs
httpd binary that can be loaded on-demand.INCLUDES output filter
processes documents for → Server Side
Includes.www is a hostname, example.com is a domain name,
and www.example.com is a fully-qualified domain name.
cgi-script handler designates files to be processed as
→ CGIs./usr/local/apache2/conf/httpd.conf, but it may be moved using
run-time or compile-time configuration.GET, POST,
and PUT.
text/html,
image/gif, and application/octet-stream. In
HTTP, the MIME-type is transmitted in the Content-Type
→ header.httpd binary are
called static modules, while modules that are stored
separately and can be optionally loaded at run-time are called
dynamic modules or → DSOs.
Modules that are included by default
are called base modules. Many modules are available for Apache
that are not distributed as part of the Apache HTTP Server → tarball. These are referred to as
third-party modules./images/.*(jpg|gif)$". Apache uses Perl
Compatible Regular Expressions provided by the PCRE library.
tar utility.
Apache distributions are stored in compressed tar archives or using
pkzip.
http or
https, a hostname, and a path. A URL for this page is
http://httpd.apache.org/docs/2.0/glossary.html.
Apache HTTP Server Version 2.0
This document describes the use of Apache's Handlers.
| Related Modules | Related Directives |
|---|---|
A "handler" is an internal Apache representation of the action to be performed when a file is called. Generally, files have implicit handlers, based on the file type. Normally, all files are simply served by the server, but certain file types are "handled" separately.
Apache 1.1 adds the ability to use handlers explicitly. Based on either filename extensions or on location, handlers can be specified without relation to file type. This is advantageous both because it is a more elegant solution, and because it also allows for both a type and a handler to be associated with a file. (See also Files with Multiple Extensions.)
Handlers can either be built into the server or included in
a module, or they can be added with the Action directive. The
built-in handlers in the standard distribution are as
follows:
default_handler(), which is the handler used by
default to handle static content. (core)mod_asis)mod_cgi)mod_imap)mod_info)mod_status)mod_negotiation)The following directives will cause requests for files with
the html extension to trigger the launch of the
footer.pl CGI script.
Action add-footer /cgi-bin/footer.pl
AddHandler add-footer .html
Then the CGI script is responsible for sending the
originally requested document (pointed to by the
PATH_TRANSLATED environment variable) and making
whatever modifications or additions are desired.
The following directives will enable the
send-as-is handler, which is used for files which
contain their own HTTP headers. All files in the
/web/htdocs/asis/ directory will be processed by
the send-as-is handler, regardless of their
filename extensions.
<Directory /web/htdocs/asis>
SetHandler send-as-is
</Directory>
In order to implement the handler features, an addition has
been made to the Apache API that
you may wish to make use of. Specifically, a new record has
been added to the request_rec structure:
char *handler
If you wish to have your module engage a handler, you need
only to set r->handler to the name of the
handler at any time prior to the invoke_handler
stage of the request. Handlers are implemented as they were
before, albeit using the handler name instead of a content
type. While it is not necessary, the naming convention for
handlers is to use a dash-separated word, with no slashes, so
as to not invade the media type name-space.
Apache HTTP Server Version 2.0
Authentication is any process by which you verify that someone is who they claim they are. Authorization is any process by which someone is allowed to be where they want to go, or to have information that they want to have.
| Related Modules | Related Directives |
|---|---|
If you have information on your web site that is sensitive or intended for only a small group of people, the techniques in this article will help you make sure that the people that see those pages are the people that you wanted to see them.
This article covers the "standard" way of protecting parts of your web site that most of you are going to use.
The directives discussed in this article will need to go
either in your main server configuration file (typically in a
<Directory> section), or
in per-directory configuration files (.htaccess files).
If you plan to use .htaccess files, you will
need to have a server configuration that permits putting
authentication directives in these files. This is done with the
AllowOverride directive, which
specifies which directives, if any, may be put in per-directory
configuration files.
Since we're talking here about authentication, you will need
an AllowOverride directive like the
following:
AllowOverride AuthConfig
Or, if you are just going to put the directives directly in your main server configuration file, you will of course need to have write permission to that file.
And you'll need to know a little bit about the directory structure of your server, in order to know where some files are kept. This should not be terribly difficult, and I'll try to make this clear when we come to that point.
Here's the basics of password protecting a directory on your server.
You'll need to create a password file. This file should be
placed somewhere not accessible from the web. This is so that
folks cannot download the password file. For example, if your
documents are served out of /usr/local/apache/htdocs you
might want to put the password file(s) in
/usr/local/apache/passwd.
To create the file, use the htpasswd utility that
came with Apache. This will be located in the bin directory
of wherever you installed Apache. To create the file, type:
htpasswd -c /usr/local/apache/passwd/passwords rbowen
htpasswd will ask you for the password, and
then ask you to type it again to confirm it:
# htpasswd -c /usr/local/apache/passwd/passwords rbowen
New password: mypassword
Re-type new password: mypassword
Adding password for user rbowen
If htpasswd is not in your path, of course
you'll have to type the full path to the file to get it to run.
On my server, it's located at
/usr/local/apache/bin/htpasswd
Next, you'll need to configure the server to request a
password and tell the server which users are allowed access.
You can do this either by editing the httpd.conf
file or using an .htaccess file. For example, if
you wish to protect the directory
/usr/local/apache/htdocs/secret, you can use the
following directives, either placed in the file
/usr/local/apache/htdocs/secret/.htaccess, or
placed in httpd.conf inside a <Directory
/usr/local/apache/apache/htdocs/secret> section.
AuthType Basic
AuthName "Restricted Files"
AuthUserFile /usr/local/apache/passwd/passwords
Require user rbowen
Let's examine each of those directives individually. The AuthType directive selects
that method that is used to authenticate the user. The most
common method is Basic, and this is the method
implemented by mod_auth. It is important to be aware,
however, that Basic authentication sends the password from the client to
the browser unencrypted. This method should therefore not be used for
highly sensitive data. Apache supports one other authentication method:
AuthType Digest. This method is implemented by mod_auth_digest and is much more secure. Only the most recent
versions of clients are known to support Digest authentication.
The AuthName directive sets
the Realm to be used in the authentication. The realm serves
two major functions. First, the client often presents this information to
the user as part of the password dialog box. Second, it is used by the
client to determine what password to send for a given authenticated
area.
So, for example, once a client has authenticated in the
"Restricted Files" area, it will automatically
retry the same password for any area on the same server that is
marked with the "Restricted Files" Realm.
Therefore, you can prevent a user from being prompted more than
once for a password by letting multiple restricted areas share
the same realm. Of course, for security reasons, the client
will always need to ask again for the password whenever the
hostname of the server changes.
The AuthUserFile
directive sets the path to the password file that we just
created with htpasswd. If you have a large number
of users, it can be quite slow to search through a plain text
file to authenticate the user on each request. Apache also has
the ability to store user information in fast database files.
The mod_auth_dbm module provides the AuthDBMUserFile directive. These
files can be created and manipulated with the dbmmanage program. Many
other types of authentication options are available from third
party modules in the Apache Modules
Database.
Finally, the Require
directive provides the authorization part of the process by
setting the user that is allowed to access this region of the
server. In the next section, we discuss various ways to use the
Require directive.
The directives above only let one person (specifically
someone with a username of rbowen) into the
directory. In most cases, you'll want to let more than one
person in. This is where the AuthGroupFile comes in.
If you want to let more than one person in, you'll need to create a group file that associates group names with a list of users in that group. The format of this file is pretty simple, and you can create it with your favorite editor. The contents of the file will look like this:
GroupName: rbowen dpitts sungo rshersey
That's just a list of the members of the group in a long line separated by spaces.
To add a user to your already existing password file, type:
htpasswd /usr/local/apache/passwd/passwords dpitts
You'll get the same response as before, but it will be
appended to the existing file, rather than creating a new file.
(It's the -c that makes it create a new password
file).
Now, you need to modify your .htaccess file to
look like the following:
AuthType Basic
AuthName "By Invitation Only"
AuthUserFile /usr/local/apache/passwd/passwords
AuthGroupFile /usr/local/apache/passwd/groups
Require group GroupName
Now, anyone that is listed in the group GroupName,
and has an entry in the password file, will be let in, if
they type the correct password.
There's another way to let multiple users in that is less specific. Rather than creating a group file, you can just use the following directive:
Require valid-user
Using that rather than the Require user rbowen
line will allow anyone in that is listed in the password file,
and who correctly enters their password. You can even emulate
the group behavior here, by just keeping a separate password
file for each group. The advantage of this approach is that
Apache only has to check one file, rather than two. The
disadvantage is that you have to maintain a bunch of password
files, and remember to reference the right one in the
AuthUserFile directive.
Because of the way that Basic authentication is specified, your username and password must be verified every time you request a document from the server. This is even if you're reloading the same page, and for every image on the page (if they come from a protected directory). As you can imagine, this slows things down a little. The amount that it slows things down is proportional to the size of the password file, because it has to open up that file, and go down the list of users until it gets to your name. And it has to do this every time a page is loaded.
A consequence of this is that there's a practical limit to how many users you can put in one password file. This limit will vary depending on the performance of your particular server machine, but you can expect to see slowdowns once you get above a few hundred entries, and may wish to consider a different authentication method at that time.
Authentication by username and password is only part of the story. Frequently you want to let people in based on something other than who they are. Something such as where they are coming from.
The Allow and
Deny directives let
you allow and deny access based on the host name, or host
address, of the machine requesting a document. The
Order directive goes
hand-in-hand with these two, and tells Apache in which order to
apply the filters.
The usage of these directives is:
Allow from address
where address is an IP address (or a partial IP address) or a fully qualified domain name (or a partial domain name); you may provide multiple addresses or domain names, if desired.
For example, if you have someone spamming your message board, and you want to keep them out, you could do the following:
Deny from 10.252.46.165
Visitors coming from that address will not be able to see the content covered by this directive. If, instead, you have a machine name, rather than an IP address, you can use that.
Deny from host.example.com
And, if you'd like to block access from an entire domain, you can specify just part of an address or domain name:
Deny from 192.168.205
Deny from phishers.example.com moreidiots.example
Deny from ke
Using Order will let you be
sure that you are actually restricting things to the group that you want
to let in, by combining a Deny
and an Allow directive:
Order deny,allow
Deny from all
Allow from dev.example.com
Listing just the Allow
directive would not do what you want, because it will let folks from that
host in, in addition to letting everyone in. What you want is to let
only those folks in.
You should also read the documentation for mod_auth
and mod_access which contain some more information
about how this all works.
Apache HTTP Server Version 2.0
| Related Modules | Related Directives |
|---|---|
The CGI (Common Gateway Interface) defines a way for a web server to interact with external content-generating programs, which are often referred to as CGI programs or CGI scripts. It is the simplest, and most common, way to put dynamic content on your web site. This document will be an introduction to setting up CGI on your Apache web server, and getting started writing CGI programs.
In order to get your CGI programs to work properly, you'll need to have Apache configured to permit CGI execution. There are several ways to do this.
The
ScriptAlias
directive tells Apache that a particular directory is set
aside for CGI programs. Apache will assume that every file in
this directory is a CGI program, and will attempt to execute
it, when that particular resource is requested by a
client.
The ScriptAlias
directive looks like:
ScriptAlias /cgi-bin/ /usr/local/apache2/cgi-bin/
The example shown is from your default httpd.conf
configuration file, if you installed Apache in the default
location. The ScriptAlias
directive is much like the Alias directive, which defines a URL prefix that
is to mapped to a particular directory. Alias
and ScriptAlias are usually used for
directories that are outside of the DocumentRoot directory. The difference between
Alias and ScriptAlias
is that ScriptAlias has the added meaning
that everything under that URL prefix will be considered a CGI
program. So, the example above tells Apache that any request for a
resource beginning with /cgi-bin/ should be served from
the directory /usr/local/apache2/cgi-bin/, and should be
treated as a CGI program.
For example, if the URL
http://www.example.com/cgi-bin/test.pl
is requested, Apache will attempt to execute the file
/usr/local/apache2/cgi-bin/test.pl
and return the output. Of course, the file will have to
exist, and be executable, and return output in a particular
way, or Apache will return an error message.
CGI programs are often restricted to ScriptAlias'ed directories for security reasons.
In this way, administrators can tightly control who is allowed to
use CGI programs. However, if the proper security precautions are
taken, there is no reason why CGI programs cannot be run from
arbitrary directories. For example, you may wish to let users
have web content in their home directories with the
UserDir directive.
If they want to have their own CGI programs, but don't have access to
the main cgi-bin directory, they will need to be able to
run CGI programs elsewhere.
There are two steps to allowing CGI execution in an arbitrary
directory. First, the cgi-script handler must be
activated using the AddHandler or SetHandler directive. Second,
ExecCGI must be specified in the Options directive.
You could explicitly use the Options directive, inside your main server configuration
file, to specify that CGI execution was permitted in a particular
directory:
<Directory /usr/local/apache2/htdocs/somedir>
Options +ExecCGI
</Directory>
The above directive tells Apache to permit the execution
of CGI files. You will also need to tell the server what
files are CGI files. The following AddHandler directive tells the server to treat all
files with the cgi or pl extension as CGI
programs:
AddHandler cgi-script .cgi .pl
The .htaccess tutorial
shows how to activate CGI programs if you do not have
access to httpd.conf.
To allow CGI program execution for any file ending in
.cgi in users' directories, you can use the
following configuration.
<Directory /home/*/public_html>
Options +ExecCGI
AddHandler cgi-script .cgi
</Directory>
If you wish designate a cgi-bin subdirectory of
a user's directory where everything will be treated as a CGI
program, you can use the following.
<Directory /home/*/public_html/cgi-bin>
Options ExecCGI
SetHandler cgi-script
</Directory>
There are two main differences between ``regular'' programming, and CGI programming.
First, all output from your CGI program must be preceded by a MIME-type header. This is HTTP header that tells the client what sort of content it is receiving. Most of the time, this will look like:
Content-type: text/html
Secondly, your output needs to be in HTML, or some other format that a browser will be able to display. Most of the time, this will be HTML, but occasionally you might write a CGI program that outputs a gif image, or other non-HTML content.
Apart from those two things, writing a CGI program will look a lot like any other program that you might write.
The following is an example CGI program that prints one
line to your browser. Type in the following, save it to a
file called first.pl, and put it in your
cgi-bin directory.
#!/usr/bin/perl
print "Content-type: text/html\n\n";
print "Hello, World.";
Even if you are not familiar with Perl, you should be able
to see what is happening here. The first line tells Apache
(or whatever shell you happen to be running under) that this
program can be executed by feeding the file to the
interpreter found at the location /usr/bin/perl.
The second line prints the content-type declaration we
talked about, followed by two carriage-return newline pairs.
This puts a blank line after the header, to indicate the end
of the HTTP headers, and the beginning of the body. The third
line prints the string "Hello, World.". And that's the end
of it.
If you open your favorite browser and tell it to get the address
http://www.example.com/cgi-bin/first.pl
or wherever you put your file, you will see the one line
Hello, World. appear in your browser window.
It's not very exciting, but once you get that working, you'll
have a good chance of getting just about anything working.
There are four basic things that you may see in your browser when you try to access your CGI program from the web:
Content-Type set in your CGI program.Remember that the server does not run as you. That is,
when the server starts up, it is running with the permissions
of an unprivileged user - usually nobody, or
www - and so it will need extra permissions to
execute files that are owned by you. Usually, the way to give
a file sufficient permissions to be executed by nobody
is to give everyone execute permission on the file:
chmod a+x first.pl
Also, if your program reads from, or writes to, any other files, those files will need to have the correct permissions to permit this.
When you run a program from your command line, you have
certain information that is passed to the shell without you
thinking about it. For example, you have a PATH,
which tells the shell where it can look for files that you
reference.
When a program runs through the web server as a CGI program,
it may not have the same PATH. Any programs that you
invoke in your CGI program (like sendmail, for
example) will need to be specified by a full path, so that the
shell can find them when it attempts to execute your CGI
program.
A common manifestation of this is the path to the script
interpreter (often perl) indicated in the first
line of your CGI program, which will look something like:
#!/usr/bin/perl
Make sure that this is in fact the path to the interpreter.
In addition, if your CGI program depends on other environment variables, you will need to assure that those variables are passed by Apache.
Most of the time when a CGI program fails, it's because of a problem with the program itself. This is particularly true once you get the hang of this CGI stuff, and no longer make the above two mistakes. The first thing to do is to make sure that your program runs from the command line before testing it via the web server. For example, try:
cd /usr/local/apache2/cgi-bin
./first.pl
(Do not call the perl interpreter. The shell
and Apache should find the interpreter using the path information on the first line of
the script.)
The first thing you see written by your program should be
a set of HTTP headers, including the Content-Type,
followed by a blank line. If you see anything else, Apache will
return the Premature end of script headers error if
you try to run it through the server. See Writing a CGI program above for more
details.
The error logs are your friend. Anything that goes wrong generates message in the error log. You should always look there first. If the place where you are hosting your web site does not permit you access to the error log, you should probably host your site somewhere else. Learn to read the error logs, and you'll find that almost all of your problems are quickly identified, and quickly solved.
The suexec support program
allows CGI programs to be run under different user permissions,
depending on which virtual host or user home directory they are
located in. Suexec has very strict permission checking, and any
failure in that checking will result in your CGI programs
failing with Premature end of script headers.
To check if you are using suexec, run apachectl
-V and check for the location of SUEXEC_BIN.
If Apache finds an suexec binary there on startup,
suexec will be activated.
Unless you fully understand suexec, you should not be using it.
To disable suexec, simply remove (or rename) the suexec
binary pointed to by SUEXEC_BIN and then restart the
server. If, after reading about suexec,
you still wish to use it, then run suexec -V to find
the location of the suexec log file, and use that log file to
find what policy you are violating.
As you become more advanced in CGI programming, it will become useful to understand more about what's happening behind the scenes. Specifically, how the browser and server communicate with one another. Because although it's all very well to write a program that prints "Hello, World.", it's not particularly useful.
Environment variables are values that float around you as
you use your computer. They are useful things like your path
(where the computer searches for the actual file
implementing a command when you type it), your username, your
terminal type, and so on. For a full list of your normal,
every day environment variables, type
env at a command prompt.
During the CGI transaction, the server and the browser also set environment variables, so that they can communicate with one another. These are things like the browser type (Netscape, IE, Lynx), the server type (Apache, IIS, WebSite), the name of the CGI program that is being run, and so on.
These variables are available to the CGI programmer, and are half of the story of the client-server communication. The complete list of required variables is at http://hoohoo.ncsa.uiuc.edu/cgi/env.html.
This simple Perl CGI program will display all of the
environment variables that are being passed around. Two
similar programs are included in the
cgi-bin
directory of the Apache distribution. Note that some
variables are required, while others are optional, so you may
see some variables listed that were not in the official list.
In addition, Apache provides many different ways for you to
add your own environment variables
to the basic ones provided by default.
#!/usr/bin/perl
print "Content-type: text/html\n\n";
foreach $key (keys %ENV) {
print "$key --> $ENV{$key}<br>";
}
Other communication between the server and the client
happens over standard input (STDIN) and standard
output (STDOUT). In normal everyday context,
STDIN means the keyboard, or a file that a
program is given to act on, and STDOUT
usually means the console or screen.
When you POST a web form to a CGI program,
the data in that form is bundled up into a special format
and gets delivered to your CGI program over STDIN.
The program then can process that data as though it was
coming in from the keyboard, or from a file
The "special format" is very simple. A field name and its value are joined together with an equals (=) sign, and pairs of values are joined together with an ampersand (&). Inconvenient characters like spaces, ampersands, and equals signs, are converted into their hex equivalent so that they don't gum up the works. The whole data string might look something like:
name=Rich%20Bowen&city=Lexington&state=KY&sidekick=Squirrel%20Monkey
You'll sometimes also see this type of string appended to
a URL. When that is done, the server puts that string
into the environment variable called
QUERY_STRING. That's called a GET
request. Your HTML form specifies whether a GET
or a POST is used to deliver the data, by setting the
METHOD attribute in the FORM tag.
Your program is then responsible for splitting that string up into useful information. Fortunately, there are libraries and modules available to help you process this data, as well as handle other of the aspects of your CGI program.
When you write CGI programs, you should consider using a code library, or module, to do most of the grunt work for you. This leads to fewer errors, and faster development.
If you're writing CGI programs in Perl, modules are
available on CPAN. The most
popular module for this purpose is CGI.pm. You might
also consider CGI::Lite, which implements a minimal
set of functionality, which is all you need in most programs.
If you're writing CGI programs in C, there are a variety of
options. One of these is the CGIC library, from
http://www.boutell.com/cgic/.
There are a large number of CGI resources on the web. You can discuss CGI problems with other users on the Usenet group comp.infosystems.www.authoring.cgi. And the -servers mailing list from the HTML Writers Guild is a great source of answers to your questions. You can find out more at http://www.hwg.org/lists/hwg-servers/.
And, of course, you should probably read the CGI specification, which has all the details on the operation of CGI programs. You can find the original version at the NCSA and there is an updated draft at the Common Gateway Interface RFC project.
When you post a question about a CGI problem that you're having, whether to a mailing list, or to a newsgroup, make sure you provide enough information about what happened, what you expected to happen, and how what actually happened was different, what server you're running, what language your CGI program was in, and, if possible, the offending code. This will make finding your problem much simpler.
Note that questions about CGI problems should never be posted to the Apache bug database unless you are sure you have found a problem in the Apache source code.
Apache HTTP Server Version 2.0
.htaccess files provide a way to make configuration
changes on a per-directory basis.
| Related Modules | Related Directives |
|---|---|
.htaccess files (or "distributed configuration files")
provide a way to make configuration changes on a per-directory basis. A
file, containing one or more configuration directives, is placed in a
particular document directory, and the directives apply to that
directory, and all subdirectories thereof.
If you want to call your .htaccess file something
else, you can change the name of the file using the AccessFileName directive. For example,
if you would rather call the file .config then you
can put the following in your server configuration file:
AccessFileName .config
In general, .htaccess files use the same syntax as
the main configuration
files. What you can put in these files is determined by the
AllowOverride directive. This
directive specifies, in categories, what directives will be
honored if they are found in a .htaccess file. If a
directive is permitted in a .htaccess file, the
documentation for that directive will contain an Override section,
specifying what value must be in AllowOverride in order for that
directive to be permitted.
For example, if you look at the documentation for the AddDefaultCharset
directive, you will find that it is permitted in .htaccess
files. (See the Context line in the directive summary.) The Override line reads
FileInfo. Thus, you must have at least
AllowOverride FileInfo in order for this directive to be
honored in .htaccess files.
If you are unsure whether a particular directive is permitted in a
.htaccess file, look at the documentation for that
directive, and check the Context line for ".htaccess".
In general, you should never use .htaccess files unless
you don't have access to the main server configuration file. There is,
for example, a prevailing misconception that user authentication should
always be done in .htaccess files. This is simply not the
case. You can put user authentication configurations in the main server
configuration, and this is, in fact, the preferred way to do
things.
.htaccess files should be used in a case where the
content providers need to make configuration changes to the server on a
per-directory basis, but do not have root access on the server system.
In the event that the server administrator is not willing to make
frequent configuration changes, it might be desirable to permit
individual users to make these changes in .htaccess files
for themselves. This is particularly true, for example, in cases where
ISPs are hosting multiple user sites on a single machine, and want
their users to be able to alter their configuration.
However, in general, use of .htaccess files should be
avoided when possible. Any configuration that you would consider
putting in a .htaccess file, can just as effectively be
made in a <Directory> section in your main server
configuration file.
There are two main reasons to avoid the use of
.htaccess files.
The first of these is performance. When AllowOverride
is set to allow the use of .htaccess files, Apache will
look in every directory for .htaccess files. Thus,
permitting .htaccess files causes a performance hit,
whether or not you actually even use them! Also, the
.htaccess file is loaded every time a document is
requested.
Further note that Apache must look for .htaccess files
in all higher-level directories, in order to have a full complement of
directives that it must apply. (See section on how
directives are applied.) Thus, if a file is requested out of a
directory /www/htdocs/example, Apache must look for the
following files:
/.htaccess
/www/.htaccess
/www/htdocs/.htaccess
/www/htdocs/example/.htaccess
And so, for each file access out of that directory, there are 4
additional file-system accesses, even if none of those files are
present. (Note that this would only be the case if
.htaccess files were enabled for /, which
is not usually the case.)
The second consideration is one of security. You are permitting
users to modify server configuration, which may result in changes over
which you have no control. Carefully consider whether you want to give
your users this privilege. Note also that giving users less
privileges than they need will lead to additional technical support
requests. Make sure you clearly tell your users what level of
privileges you have given them. Specifying exactly what you have set
AllowOverride to, and pointing them
to the relevant documentation, will save yourself a lot of confusion
later.
Note that it is completely equivalent to put a .htaccess
file in a directory /www/htdocs/example containing a
directive, and to put that same directive in a Directory section
<Directory /www/htdocs/example> in your main server
configuration:
.htaccess file in /www/htdocs/example:
/www/htdocs/example
AddType text/example .exm
httpd.conf
file
<Directory /www/htdocs/example>
AddType text/example .exm
</Directory>
However, putting this configuration in your server configuration file will result in less of a performance hit, as the configuration is loaded once when Apache starts, rather than every time a file is requested.
The use of .htaccess files can be disabled completely
by setting the AllowOverride
directive to none:
AllowOverride None
The configuration directives found in a .htaccess file
are applied to the directory in which the .htaccess file
is found, and to all subdirectories thereof. However, it is important
to also remember that there may have been .htaccess files
in directories higher up. Directives are applied in the order that they
are found. Therefore, a .htaccess file in a particular
directory may override directives found in .htaccess files
found higher up in the directory tree. And those, in turn, may have
overridden directives found yet higher up, or in the main server
configuration file itself.
Example:
In the directory /www/htdocs/example1 we have a
.htaccess file containing the following:
Options +ExecCGI
(Note: you must have "AllowOverride Options" in effect
to permit the use of the "Options" directive in
.htaccess files.)
In the directory /www/htdocs/example1/example2 we have
a .htaccess file containing:
Options Includes
Because of this second .htaccess file, in the directory
/www/htdocs/example1/example2, CGI execution is not
permitted, as only Options Includes is in effect, which
completely overrides any earlier setting that may have been in
place.
As discussed in the documentation on Configuration Sections,
.htaccess files can override the <Directory> sections for
the corresponding directory, but will be overriden by other types
of configuration sections from the main configuration files. This
fact can be used to enforce certain configurations, even in the
presence of a liberal AllowOverride setting. For example, to
prevent script execution while allowing anything else to be set in
.htaccess you can use:
<Directory />
Allowoverride All
</Directory>
<Location />
Options +IncludesNoExec -ExecCGI
</Location>
If you jumped directly to this part of the document to find out how
to do authentication, it is important to note one thing. There is a
common misconception that you are required to use
.htaccess files in order to implement password
authentication. This is not the case. Putting authentication directives
in a <Directory>
section, in your main server configuration file, is the preferred way
to implement this, and .htaccess files should be used only
if you don't have access to the main server configuration file. See above for a discussion of when you should and should
not use .htaccess files.
Having said that, if you still think you need to use a
.htaccess file, you may find that a configuration such as
what follows may work for you.
You must have "AllowOverride AuthConfig" in effect for
these directives to be honored.
.htaccess file contents:
AuthType Basic
AuthName "Password Required"
AuthUserFile /www/passwords/password.file
AuthGroupFile /www/passwords/group.file
Require Group admins
Note that AllowOverride AuthConfig must be in effect
for these directives to have any effect.
Please see the authentication tutorial for a more complete discussion of authentication and authorization.
Another common use of .htaccess files is to enable
Server Side Includes for a particular directory. This may be done with
the following configuration directives, placed in a
.htaccess file in the desired directory:
Options +Includes
AddType text/html shtml
AddHandler server-parsed shtml
Note that AllowOverride Options and AllowOverride
FileInfo must both be in effect for these directives to have any
effect.
Please see the SSI tutorial for a more complete discussion of server-side includes.
Finally, you may wish to use a .htaccess file to permit
the execution of CGI programs in a particular directory. This may be
implemented with the following configuration:
Options +ExecCGI
AddHandler cgi-script cgi pl
Alternately, if you wish to have all files in the given directory be considered to be CGI programs, this may be done with the following configuration:
Options +ExecCGI
SetHandler cgi-script
Note that AllowOverride Options and AllowOverride
FileInfo must both be in effect for these directives to have any
effect.
Please see the CGI tutorial for a more complete discussion of CGI programming and configuration.
When you put configuration directives in a .htaccess
file, and you don't get the desired effect, there are a number of
things that may be going wrong.
Most commonly, the problem is that AllowOverride is not
set such that your configuration directives are being honored. Make
sure that you don't have a AllowOverride None in effect
for the file scope in question. A good test for this is to put garbage
in your .htaccess file and reload. If a server error is
not generated, then you almost certainly have AllowOverride
None in effect.
If, on the other hand, you are getting server errors when trying to
access documents, check your Apache error log. It will likely tell you
that the directive used in your .htaccess file is not
permitted. Alternately, it may tell you that you had a syntax error,
which you will then need to fix.
Apache HTTP Server Version 2.0
Authentication is any process by which you verify that someone is who they claim they are. Authorization is any process by which someone is allowed to be where they want to go, or to have information that they want to have.
The CGI (Common Gateway Interface) defines a way for a web server to interact with external content-generating programs, which are often referred to as CGI programs or CGI scripts. It is the simplest, and most common, way to put dynamic content on your web site. This document will be an introduction to setting up CGI on your Apache web server, and getting started writing CGI programs.
See: CGI: Dynamic Content
.htaccess files.htaccess files provide a way to make configuration
changes on a per-directory basis. A file, containing one or more
configuration directives, is placed in a particular document directory,
and the directives apply to that directory, and all subdirectories thereof.
See: .htaccess files
SSI (Server Side Includes) are directives that are placed in HTML pages, and evaluated on the server while the pages are being served. They let you add dynamically generated content to an existing HTML page, without having to serve the entire page via a CGI program, or other dynamic technology.
On systems with multiple users, each user can be permitted to have a
web site in their home directory using the UserDir directive. Visitors
to a URL http://example.com/~username/ will get content
out of the home directory of the user "username", out of
the subdirectory specified by the UserDir directive.
Apache HTTP Server Version 2.0
On systems with multiple users, each user can be permitted to have a
web site in their home directory using the UserDir directive. Visitors
to a URL http://example.com/~username/ will get content
out of the home directory of the user "username", out of
the subdirectory specified by the UserDir directive.
Per-user web directories Setting the file path with UserDir Restricting what users are permitted to use this
feature Enabling a cgi directory for each user Allowing users to alter configuration| Related Modules | Related Directives |
|---|---|
The UserDir
directive specifies a directory out of which per-user
content is loaded. This directive may take several different forms.
If a path is given which does not start with a leading slash, it is assumed to be a directory path relative to the home directory of the specified user. Given this configuration:
UserDir public_html
the URL http://example.com/~rbowen/file.html will be
translated to the file path
/home/rbowen/public_html/file.html
If a path is given starting with a slash, a directory path will be constructed using that path, plus the username specified. Given this configuration:
UserDir /var/html
the URL http://example.com/~rbowen/file.html will be
translated to the file path /var/html/rbowen/file.html
If a path is provided which contains an asterisk (*), a path is used in which the asterisk is replaced with the username. Given this configuration:
UserDir /var/www/*/docs
the URL http://example.com/~rbowen/file.html will be
translated to the file path
/var/www/rbowen/docs/file.html
Using the syntax shown in the UserDir documentation, you can restrict what users are permitted to use this functionality:
UserDir enabled
UserDir disabled root jro fish
The configuration above will enable the feature for all users
except for those listed in the disabled statement.
You can, likewise, disable the feature for all but a few users by
using a configuration like the following:
UserDir disabled
UserDir enabled rbowen krietz
See UserDir
documentation for additional examples.
In order to give each user their own cgi-bin directory, you can use
a <Directory>
directive to make a particular subdirectory of a user's home directory
cgi-enabled.
<Directory /home/*/public_html/cgi-bin/>
Options ExecCGI
SetHandler cgi-script
</Directory>
Then, presuming that UserDir is set to
public_html, a cgi program example.cgi
could be loaded from that directory as:
http://example.com/~rbowen/cgi-bin/example.cgi
If you want to allows users to modify the server configuration in
their web space, they will need to use .htaccess files to
make these changed. Ensure that you have set AllowOverride to a
value sufficient for the directives that you want to permit the users
to modify. See the .htaccess tutorial for
additional details on how this works.
Apache HTTP Server Version 2.0
Server-side includes provide a means to add dynamic content to existing HTML documents.
| Related Modules | Related Directives |
|---|---|
This article deals with Server Side Includes, usually called simply SSI. In this article, I'll talk about configuring your server to permit SSI, and introduce some basic SSI techniques for adding dynamic content to your existing HTML pages.
In the latter part of the article, we'll talk about some of the somewhat more advanced things that can be done with SSI, such as conditional statements in your SSI directives.
SSI (Server Side Includes) are directives that are placed in HTML pages, and evaluated on the server while the pages are being served. They let you add dynamically generated content to an existing HTML page, without having to serve the entire page via a CGI program, or other dynamic technology.
The decision of when to use SSI, and when to have your page entirely generated by some program, is usually a matter of how much of the page is static, and how much needs to be recalculated every time the page is served. SSI is a great way to add small pieces of information, such as the current time. But if a majority of your page is being generated at the time that it is served, you need to look for some other solution.
To permit SSI on your server, you must have the following
directive either in your httpd.conf file, or in a
.htaccess file:
Options +Includes
This tells Apache that you want to permit files to be parsed
for SSI directives. Note that most configurations contain
multiple Options directives
that can override each other. You will probably need to apply the
Options to the specific directory where you want SSI
enabled in order to assure that it gets evaluated last.
Not just any file is parsed for SSI directives. You have to
tell Apache which files should be parsed. There are two ways to
do this. You can tell Apache to parse any file with a
particular file extension, such as .shtml, with
the following directives:
AddType text/html .shtml
AddOutputFilter INCLUDES .shtml
One disadvantage to this approach is that if you wanted to
add SSI directives to an existing page, you would have to
change the name of that page, and all links to that page, in
order to give it a .shtml extension, so that those
directives would be executed.
The other method is to use the XBitHack directive:
XBitHack on
XBitHack
tells Apache to parse files for SSI
directives if they have the execute bit set. So, to add SSI
directives to an existing page, rather than having to change
the file name, you would just need to make the file executable
using chmod.
chmod +x pagename.html
A brief comment about what not to do. You'll occasionally
see people recommending that you just tell Apache to parse all
.html files for SSI, so that you don't have to
mess with .shtml file names. These folks have
perhaps not heard about XBitHack. The thing to
keep in mind is that, by doing this, you're requiring that
Apache read through every single file that it sends out to
clients, even if they don't contain any SSI directives. This
can slow things down quite a bit, and is not a good idea.
Of course, on Windows, there is no such thing as an execute bit to set, so that limits your options a little.
In its default configuration, Apache does not send the last modified date or content length HTTP headers on SSI pages, because these values are difficult to calculate for dynamic content. This can prevent your document from being cached, and result in slower perceived client performance. There are two ways to solve this:
XBitHack Full configuration. This
tells Apache to determine the last modified date by looking
only at the date of the originally requested file, ignoring
the modification date of any included files.mod_expires to set an explicit expiration
time on your files, thereby letting browsers and proxies
know that it is acceptable to cache them.SSI directives have the following syntax:
<!--#element attribute=value attribute=value ... -->
It is formatted like an HTML comment, so if you don't have SSI correctly enabled, the browser will ignore it, but it will still be visible in the HTML source. If you have SSI correctly configured, the directive will be replaced with its results.
The element can be one of a number of things, and we'll talk some more about most of these in the next installment of this series. For now, here are some examples of what you can do with SSI
<!--#echo var="DATE_LOCAL" -->
The echo element just spits out the value of a
variable. There are a number of standard variables, which
include the whole set of environment variables that are
available to CGI programs. Also, you can define your own
variables with the set element.
If you don't like the format in which the date gets printed,
you can use the config element, with a
timefmt attribute, to modify that formatting.
<!--#config timefmt="%A %B %d, %Y" -->
Today is <!--#echo var="DATE_LOCAL" -->
This document last modified <!--#flastmod file="index.html" -->
This element is also subject to timefmt format
configurations.
This is one of the more common uses of SSI - to output the results of a CGI program, such as everybody's favorite, a ``hit counter.''
<!--#include virtual="/cgi-bin/counter.pl" -->
Following are some specific examples of things you can do in your HTML documents with SSI.
Earlier, we mentioned that you could use SSI to inform the user when the document was most recently modified. However, the actual method for doing that was left somewhat in question. The following code, placed in your HTML document, will put such a time stamp on your page. Of course, you will have to have SSI correctly enabled, as discussed above.
<!--#config timefmt="%A %B %d, %Y" -->
This file last modified <!--#flastmod file="ssi.shtml" -->
Of course, you will need to replace the
ssi.shtml with the actual name of the file that
you're referring to. This can be inconvenient if you're just
looking for a generic piece of code that you can paste into any
file, so you probably want to use the
LAST_MODIFIED variable instead:
<!--#config timefmt="%D" -->
This file last modified <!--#echo var="LAST_MODIFIED" -->
For more details on the timefmt format, go to
your favorite search site and look for strftime. The
syntax is the same.
If you are managing any site that is more than a few pages, you may find that making changes to all those pages can be a real pain, particularly if you are trying to maintain some kind of standard look across all those pages.
Using an include file for a header and/or a footer can
reduce the burden of these updates. You just have to make one
footer file, and then include it into each page with the
include SSI command. The include
element can determine what file to include with either the
file attribute, or the virtual
attribute. The file attribute is a file path,
relative to the current directory. That means that it
cannot be an absolute file path (starting with /), nor can it
contain ../ as part of that path. The virtual
attribute is probably more useful, and should specify a URL
relative to the document being served. It can start with a /,
but must be on the same server as the file being served.
<!--#include virtual="/footer.html" -->
I'll frequently combine the last two things, putting a
LAST_MODIFIED directive inside a footer file to be
included. SSI directives can be contained in the included file,
and includes can be nested - that is, the included file can
include another file, and so on.
In addition to being able to config the time
format, you can also config two other things.
Usually, when something goes wrong with your SSI directive, you get the message
[an error occurred while processing this directive]
If you want to change that message to something else, you
can do so with the errmsg attribute to the
config element:
<!--#config errmsg="[It appears that you don't know how to use SSI]" -->
Hopefully, end users will never see this message, because you will have resolved all the problems with your SSI directives before your site goes live. (Right?)
And you can config the format in which file
sizes are returned with the sizefmt attribute. You
can specify bytes for a full count in bytes, or
abbrev for an abbreviated number in Kb or Mb, as
appropriate.
I expect that I'll have an article some time in the coming
months about using SSI with small CGI programs. For now, here's
something else that you can do with the exec
element. You can actually have SSI execute a command using the
shell (/bin/sh, to be precise - or the DOS shell,
if you're on Win32). The following, for example, will give you
a directory listing.
<pre>
<!--#exec cmd="ls" -->
</pre>
or, on Windows
<pre>
<!--#exec cmd="dir" -->
</pre>
You might notice some strange formatting with this directive
on Windows, because the output from dir contains
the string ``<dir>'' in it, which confuses
browsers.
Note that this feature is exceedingly dangerous, as it will
execute whatever code happens to be embedded in the
exec tag. If you have any situation where users
can edit content on your web pages, such as with a
``guestbook'', for example, make sure that you have this
feature disabled. You can allow SSI, but not the
exec feature, with the IncludesNOEXEC
argument to the Options directive.
In addition to spitting out content, Apache SSI gives you the option of setting variables, and using those variables in comparisons and conditionals.
Most of the features discussed in this article are only available to you if you are running Apache 1.2 or later. Of course, if you are not running Apache 1.2 or later, you need to upgrade immediately, if not sooner. Go on. Do it now. We'll wait.
Using the set directive, you can set variables
for later use. We'll need this later in the discussion, so
we'll talk about it here. The syntax of this is as follows:
<!--#set var="name" value="Rich" -->
In addition to merely setting values literally like that, you
can use any other variable, including environment variables or the variables
discussed above (like LAST_MODIFIED, for example) to
give values to your variables. You will specify that something is
a variable, rather than a literal string, by using the dollar sign
($) before the name of the variable.
<!--#set var="modified" value="$LAST_MODIFIED" -->
To put a literal dollar sign into the value of your variable, you need to escape the dollar sign with a backslash.
<!--#set var="cost" value="\$100" -->
Finally, if you want to put a variable in the midst of a longer string, and there's a chance that the name of the variable will run up against some other characters, and thus be confused with those characters, you can place the name of the variable in braces, to remove this confusion. (It's hard to come up with a really good example of this, but hopefully you'll get the point.)
<!--#set var="date" value="${DATE_LOCAL}_${DATE_GMT}" -->
Now that we have variables, and are able to set and compare
their values, we can use them to express conditionals. This
lets SSI be a tiny programming language of sorts.
mod_include provides an if,
elif, else, endif
structure for building conditional statements. This allows you
to effectively generate multiple logical pages out of one
actual page.
The structure of this conditional construct is:
<!--#if expr="test_condition" -->
<!--#elif expr="test_condition" -->
<!--#else -->
<!--#endif -->
A test_condition can be any sort of logical
comparison - either comparing values to one another, or testing
the ``truth'' of a particular value. (A given string is true if
it is nonempty.) For a full list of the comparison operators
available to you, see the mod_include
documentation. Here are some examples of how one might use this
construct.
In your configuration file, you could put the following line:
BrowserMatchNoCase macintosh Mac
BrowserMatchNoCase MSIE InternetExplorer
This will set environment variables ``Mac'' and ``InternetExplorer'' to true, if the client is running Internet Explorer on a Macintosh.
Then, in your SSI-enabled document, you might do the following:
<!--#if expr="${Mac} && ${InternetExplorer}" -->
Apologetic text goes here
<!--#else -->
Cool JavaScript code goes here
<!--#endif -->
Not that I have anything against IE on Macs - I just struggled for a few hours last week trying to get some JavaScript working on IE on a Mac, when it was working everywhere else. The above was the interim workaround.
Any other variable (either ones that you define, or normal
environment variables) can be used in conditional statements.
With Apache's ability to set environment variables with the
SetEnvIf directives, and other related directives,
this functionality can let you do some pretty involved dynamic
stuff without ever resorting to CGI.
SSI is certainly not a replacement for CGI, or other technologies used for generating dynamic web pages. But it is a great way to add small amounts of dynamic content to pages, without doing a lot of extra work.
á—ýÜÌ äˆ ä^Ýþ×máš180r Â2øcâ(þ9-â/CxÝ$"P0RÞ…?:L mÀŠŸ->Æ0ŽæüûÔ#{Ë%û¦Lš'¡±j÷àÙ“ÜFžàNÝô\ä@îà>äKn ?€0 ’Þ2S#…ŽP=
NÊ@Ð(02+t< L ÃÄkÄ¥dW غ=yQM—& §G®ŠÝÙÈ èbmçË-ÝÈ
ëËmÒBþêÍ=Ý‚îÍÛa±=_½ì¿ÞaÜøã ’áVŽ7Gõµ¥cÆP`WÎ^:1¦§¨ )…Ž:}TíÐãh‹OðšÍ0îÔŠ ÕIêp‚¶l9±ÎÞîÆ á^þáóîîÎÜé,ï.Ùë,ÏÇë[!’@UuHOFSr›á÷]0ÉÎ7*гÐë€÷X§&€7†žð-àí›ÎЯýâü„T¹½"Š9õ!ìB JŽç¾ òÿÞMþ 9墺?K-D)¥“tÊÞðЇ…®˜…@)†jß0eå&`Q ÞU ¬MÛiŽTÛ«8GünõWõY¯õ[Ïõ]Ïõ.Ÿû=Ùµ ·ÒQ~5òC,$#G»¥cKḙƒó‚9©¸A¢@ Apache HTTP Server Version 2.0 Apache HTTP Server Version 2.0 This document covers compilation and installation of Apache
on Unix and Unix-like systems only. For compiling and
installation on Windows, see Using Apache with Microsoft
Windows. For other platforms, see the platform documentation. Apache 2.0's configuration and installation environment has
changed completely from Apache 1.3. Apache 1.3 used a custom
set of scripts to achieve easy installation. Apache 2.0 now
uses If you are upgrading from one minor version to the next (for
example, 2.0.50 to 2.0.51), please skip down to the upgrading section. NN must be replaced with the current minor version
number, and PREFIX must be replaced with the
filesystem path under which the server should be installed. If
PREFIX is not specified, it defaults to
Each section of the compilation and installation process is
described in more detail below, beginning with the requirements
for compiling and installing Apache HTTPD. The following requirements exist for building Apache: Apache can be downloaded from the Apache HTTP Server
download site which lists several mirrors. Most users of
Apache on unix-like systems will be better off downloading and
compiling a source version. The build process (described below) is
easy, and it allows you to customize your server to suit your needs.
In addition, binary releases are often not up to date with the latest
source releases. If you do download a binary, follow the instructions
in the After downloading, it is important to verify that you have a
complete and unmodified version of the Apache HTTP Server. This
can be accomplished by testing the downloaded tarball against the
PGP signature. Details on how to do this are available on the download
page and an extended example is available describing the use of
PGP. Extracting the source from the Apache HTTPD tarball is a
simple matter of uncompressing, and then untarring: This will create a new directory under the current directory
containing the source code for the distribution. You should
The next step is to configure the Apache source tree for your
particular platform and personal requirements. This is done using
the script To configure the source tree using all the default options,
simply type The most important option is the location Also at this point, you can specify which features you
want included in Apache by enabling and disabling modules. Apache comes with a Base set of modules included by
default. Other modules are enabled using the
In addition, it is sometimes necessary to provide the
For a short impression of what possibilities you have, here
is a typical example which compiles Apache for the installation
tree When Details on all the different Now you can build the various parts which form the Apache
package by simply running the command: Please be patient here, since a base configuration takes
approximately 3 minutes to compile under a Pentium III/Linux
2.2 system, but this will vary widely depending on your
hardware and the number of modules which you have enabled. Now it's time to install the package under the configured
installation PREFIX (see If you are upgrading, the installation will not overwrite
your configuration files or documents. Next, you can customize your Apache HTTP server by editing
the configuration files under
Have a look at the Apache manual under docs/manual/ or consult http://httpd.apache.org/docs/2.0/ for the most recent
version of this manual and a complete reference of available configuration directives. Now you can start your Apache
HTTP server by immediately running: and then you should be able to request your first document
via URL The first step in upgrading is to read the release announcement
and the file Upgrading from one minor version to the next (for example, from
2.0.55 to 2.0.57) is easier. The To upgrade across minor versions, start by finding the file
Apache HTTP Server Version 2.0 On Windows, Apache is normally run as a service on Windows
NT, 2000 and XP, or as a console application on Windows 9x and
ME. For details, see Running Apache as a Service
and Running Apache as a
Console Application. On Unix, the If the The recommended method of invoking the The first thing that If all goes well during startup, the server will detach from
the terminal and the command prompt will return almost
immediately. This indicates that the server is up and running.
You can then use your browser to connect to the server and view
the test page in the If Apache suffers a fatal problem during startup, it will
write a message describing the problem either to the console or
to the For further trouble-shooting instructions, consult the
Apache FAQ. If you want your server to continue running after a system
reboot, you should add a call to The Additional information about the command-line options of Apache HTTP Server Version 2.0 Apache License "License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files. "Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work. You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your
work. To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives. Apache HTTP Server Version 2.0 In order to effectively manage a web server, it is necessary
to get feedback about the activity and performance of the
server as well as any problems that may be occurring. The Apache
HTTP Server provides very comprehensive and flexible logging
capabilities. This document describes how to configure its
logging capabilities, and how to understand what the logs
contain. Anyone who can write to the directory where Apache is
writing a log file can almost certainly gain access to the uid
that the server is started as, which is normally root. Do
NOT give people write access to the directory the logs
are stored in without being aware of the consequences; see the
security tips document
for details. In addition, log files may contain information supplied
directly by the client, without escaping. Therefore, it is
possible for malicious clients to insert control-characters in
the log files, so care must be taken in dealing with raw
logs. The server error log, whose name and location is set by the
The error log is usually written to a file (typically
The format of the error log is relatively free-form and
descriptive. But there is certain information that is contained
in most error log entries. For example, here is a typical
message. The first item in the log entry is the date and time of the
message. The second item lists the severity of the error being
reported. The A very wide variety of different messages can appear in the
error log. Most look similar to the example above. The error
log will also contain debugging output from CGI scripts. Any
information written to It is not possible to customize the error log by adding or
removing information. However, error log entries dealing with
particular requests have corresponding entries in the access log. For example, the above example
entry corresponds to an access log entry with status code 403.
Since it is possible to customize the access log, you can
obtain more information about error conditions using that log
file. During testing, it is often useful to continuously monitor
the error log for any problems. On Unix systems, you can
accomplish this using: The server access log records all requests processed by the
server. The location and content of the access log are
controlled by the Of course, storing the information in the access log is only
the start of log management. The next step is to analyze this
information to produce useful statistics. Log analysis in
general is beyond the scope of this document, and not really
part of the job of the web server itself. For more information
about this topic, and for applications which perform log
analysis, check the
Open Directory or
Yahoo. Various versions of Apache httpd have used other modules and
directives to control access logging, including
mod_log_referer, mod_log_agent, and the
The format of the access log is highly configurable. The format
is specified using a format string that looks much like a C-style
printf(1) format string. Some examples are presented in the next
sections. For a complete list of the possible contents of the
format string, see the A typical configuration for the access log might look as
follows. This defines the nickname The The above configuration will write log entries in a format
known as the Common Log Format (CLF). This standard format can
be produced by many different web servers and read by many log
analysis programs. The log file entries produced in CLF will
look something like this: Each part of this log entry is described below.
Another commonly used format string is called the Combined
Log Format. It can be used as follows. This format is exactly the same as the Common Log Format,
with the addition of two more fields. Each of the additional
fields uses the percent-directive
The additional fields are: Multiple access logs can be created simply by specifying
multiple This example also shows that it is not necessary to define a
nickname with the There are times when it is convenient to exclude certain
entries from the access logs based on characteristics of the
client request. This is easily accomplished with the help of environment variables. First, an
environment variable must be set to indicate that the request
meets certain conditions. This is usually accomplished with
As another example, consider logging requests from
english-speakers to one log file, and non-english speakers to a
different log file. Although we have just shown that conditional logging is very
powerful and flexible, it is not the only way to control the
contents of the logs. Log files are more useful when they
contain a complete record of server activity. It is often
easier to simply post-process the log files to remove requests
that you do not want to consider. On even a moderately busy server, the quantity of
information stored in the log files is very large. The access
log file typically grows 1 MB or more per 10,000 requests. It
will consequently be necessary to periodically rotate the log
files by moving or deleting the existing logs. This cannot be
done while the server is running, because Apache will continue
writing to the old log file as long as it holds the file open.
Instead, the server must be restarted after the log files are
moved or deleted so that it will open new log files. By using a graceful restart, the server can be
instructed to open new log files without losing any existing or
pending connections from clients. However, in order to
accomplish this, the server must continue to write to the old
log files while it finishes serving old requests. It is
therefore necessary to wait for some time after the restart
before doing any processing on the log files. A typical
scenario that simply rotates the logs and compresses the old
logs to save space is: Another way to perform log rotation is using piped logs as discussed in the next
section. Apache httpd is capable of writing error and access log
files through a pipe to another process, rather than directly
to a file. This capability dramatically increases the
flexibility of logging, without adding code to the main server.
In order to write logs to a pipe, simply replace the filename
with the pipe character " Piped log processes are spawned by the parent Apache httpd
process, and inherit the userid of that process. This means
that piped log programs usually run as root. It is therefore
very important to keep the programs simple and secure. One important use of piped logs is to allow log rotation
without having to restart the server. The Apache HTTP Server
includes a simple program called Notice that quotes are used to enclose the entire command
that will be called for the pipe. Although these examples are
for the access log, the same technique can be used for the
error log. A similar but much more flexible log rotation program
called cronolog
is available at an external site. As with conditional logging, piped logs are a very powerful
tool, but they should not be used where a simpler solution like
off-line post-processing is available. When running a server with many virtual
hosts, there are several options for dealing with log
files. First, it is possible to use logs exactly as in a
single-host server. Simply by placing the logging directives
outside the If For the access log, there is a very good compromise. By
adding information on the virtual host to the log format
string, it is possible to log all hosts to the same log, and
later split the log into individual files. For example,
consider the following directives. The On startup, Apache httpd saves the process id of the parent
httpd process to the file In order to aid in debugging, the
When using the powerful and complex features of mod_rewrite, it is almost
always necessary to use the Apache HTTP Server Version 2.0 This document has not been fully updated
to take into account changes made in the 2.0 version of the
Apache HTTP Server. Some of the information may still be
relevant, but please use it with care. This document describes an easy way to provide your Apache
HTTP Server with a set of customized error messages which take
advantage of Content
Negotiation and By using SSI, all Error documents can be shared across different servers, or
even hosts, because all varying information is inserted at the
time the error document is returned on behalf of a failed
request. Content Negotiation then selects the appropriate language
version of a particular error message text, honoring the
language preferences passed in the client's request. (Users
usually select their favorite languages in the preferences
options menu of today's browsers). When an error document in
the client's primary language version is unavailable, the
secondary languages are tried or a default (fallback) version
is used. You have full flexibility in designing your error documents
to your personal taste (or your company's conventions). For
demonstration purposes, we present a simple generic error
document scheme. For this hypothetic server, we assume that all
error messages... An example of a "document not found" message for a german
client might look like this: All links in the document as well as links to the server's
administrator mail address, and even the name and port of the
serving virtual host are inserted in the error document at
"run-time", i.e., when the error actually occurs. For this concept to work as easily as possible, we must take
advantage of as much server support as we can get: The resulting The directory for the error messages (here:
By defining the The names of the individual error documents are now
determined like this (I'm using 403 as an example, think of it
as a placeholder for any of the configured error
documents): By putting as much layout information in two special "include
files", the error documents can be reduced to a bare minimum. One of these layout files defines the HTML document header
and a configurable list of paths to the icons to be shown in
the resulting error document. These paths are exported as a set
of SSI environment variables and are later evaluated by the
"footer" special file. The title of the current error (which is
put into the TITLE tag and an H1 header) is simply passed in
from the main error document in a variable called
By changing this file, the layout of all generated
error messages can be changed in a second. (By
exploiting the features of SSI, you can easily define
different layouts based on the current virtual host, or even
based on the client's domain name). The second layout file describes the footer to be displayed
at the bottom of every error message. In this example, it shows
an apache logo, the current server time, the server version
string and adds a mail reference to the site's webmaster. For simplicity, the header file is simply called
Both files are included into the error document by using the
directives See the listings below to see an
actual HTML implementation of the discussed example. After all this preparation work, little remains to be said
about the actual documents. They all share a simple common
structure: In the listings section, you can see an
example of a [400 Bad Request] error document. Documents as
simple as that certainly cause no problems to translate or
expand. Do we need a special handling for languages other than those we
have translations for? We did set the LanguagePriority, didn't
we?! Well, the LanguagePriority directive is for the case where
the client does not express any language priority at all. But
what happens in the situation where the client wants one of the
languages we do not have, and none of those we do have? Without doing anything, the Apache server will usually
return a [406 no acceptable variant] error, listing the choices
from which the client may select. But we're in an error message
already, and important error information might get lost when
the client had to choose a language representation first. So, in this situation it appears to be easier to define a
fallback language (by copying or linking, e.g., the
english version to a language-less version). Because the
negotiation algorithm prefers "more specialized" variants over
"more generic" variants, these generic alternatives will only
be chosen when the normal negotiation did not succeed. A simple shell script to do it (execute within the
errordocs/ dir): As of Apache-1.3, it is possible to use the
Most proxy errors return an error code of [500 Internal
Server Error]. To find out whether a particular error document
was invoked on behalf of a proxy error or because of some other
server error, and what the reason for the failure was, you can
check the contents of the new The following excerpt demonstrates how to exploit the
So, to summarize our example, here's the complete listing of
the Here is the complete for browser types which support animated GIFs). and this is the If you have tips to contribute, send mail to martin@apache.org Apache HTTP Server Version 2.0 This document has not been fully updated
to take into account changes made in the 2.0 version of the
Apache HTTP Server. Some of the information may still be
relevant, but please use it with care. A descriptor, also commonly called a file
handle is an object that a program uses to read or write
an open file, or open network socket, or a variety of other
devices. It is represented by an integer, and you may be
familiar with The operating system enforces a limit on the number of
descriptors that a program can have open at a time. There are
typically three limits involved here. One is a kernel
limitation, depending on your operating system you will either
be able to tune the number of descriptors available to higher
numbers (this is frequently called FD_SETSIZE). Or you
may be stuck with a (relatively) low amount. The second limit
is called the hard resource limit, and it is sometimes
set by root in an obscure operating system file, but frequently
is the same as the kernel limit. The third limit is called the
soft resource limit. The soft limit is always less
than or equal to the hard limit. For example, the hard limit
may be 1024, but the soft limit only 64. Any user can raise
their soft limit up to the hard limit. Root can raise the hard
limit up to the system maximum limit. The soft limit is the
actual limit that is used when enforcing the maximum number of
files a process can have open. To summarize: You control the hard and soft limits using the
Unfortunately, it's not always this simple. As mentioned
above, you will probably run into some system limitations that
will need to be worked around somehow. Work was done in version
1.2.1 to improve the situation somewhat. Here is a partial list
of systems and workarounds (assuming you are using 1.2.1 or
later). Under BSDI 2.0 you can build Apache to support more
descriptors by adding Similar to the BSDI 2.0 case, you should define
By default Linux has a kernel maximum of 256 open
descriptors per process. There are several patches available
for the 2.0.x series which raise this to 1024 and beyond, and
you can find them in the "unofficial patches" section of the Linux Information HQ.
None of these patches are perfect, and an entirely different
approach is likely to be taken during the 2.1.x development.
Applying these patches will raise the FD_SETSIZE used to
compile all programs, and unless you rebuild all your
libraries you should avoid running any other program with a
soft descriptor limit above 256. As of this writing the
patches available for increasing the number of descriptors do
not take this into account. On a dedicated webserver you
probably won't run into trouble. Solaris has a kernel hard limit of 1024 (may be lower in
earlier versions). But it has a limitation that files using
the stdio library cannot have a descriptor above 255. Apache
uses the stdio library for the ErrorLog directive. When you
have more than approximately 110 virtual hosts (with an error
log and an access log each) you will need to build Apache
with AIX version 3.2?? appears to have a hard limit of 128
descriptors. End of story. Version 4.1.5 has a hard limit of
2000. Edit the If you have details on another operating system, please
submit it through our Bug Report
Page. In addition to the problems described above there are
problems with many libraries that Apache uses. The most common
example is the bind DNS resolver library that is used by pretty
much every unix, which fails if it ends up with a descriptor
above 256. We suspect there are other libraries that similar
limitations. So the code as of 1.2.1 takes a defensive stance
and tries to save descriptors less than 16 for use while
processing each request. This is called the low slack
line. Note that this shouldn't waste descriptors. If you really
are pushing the limits and Apache can't get a descriptor above
16 when it wants it, it will settle for one below 16. In extreme situations you may want to lower the low slack
line, but you shouldn't ever need to. For example, lowering it
can increase the limits 240 described above under Solaris and
BSDI 2.0. But you'll play a delicate balancing game with the
descriptors needed to serve a request. Should you want to play
this game, the compile time parameter is
Finally, if you suspect that all this slack stuff is causing
you problems, you can disable it. Add Apache HTTP Server Version 2.0 This document has not been fully updated
to take into account changes made in the 2.0 version of the
Apache HTTP Server. Some of the information may still be
relevant, but please use it with care. Starting with the Apache 1.2 betas, people are reporting
many more connections in the FIN_WAIT_2 state (as reported
by The FIN_WAIT_2 state is somewhat unusual in that there
is no timeout defined in the standard for it. This means
that on many operating systems, a connection in the
FIN_WAIT_2 state will stay around until the system is
rebooted. If the system does not have a timeout and too
many FIN_WAIT_2 connections build up, it can fill up the
space allocated for storing information about the
connections and crash the kernel. The connections in
FIN_WAIT_2 do not tie up an httpd process. There are numerous reasons for it happening, some of them
may not yet be fully clear. What is known follows. Several clients have a bug which pops up when dealing with
persistent connections (aka
keepalives). When the connection is idle and the server
closes the connection (based on the If you are lucky, this means that the buggy client will
fully close the connection and release the resources on
your server. However, there are some cases where the socket
is never fully closed, such as a dialup client
disconnecting from their provider before closing the
client. In addition, a client might sit idle for days
without making another connection, and thus may hold its
end of the socket open for days even though it has no
further use for it. This is a bug in the browser or
in its operating system's TCP implementation. The clients on which this problem has been verified to
exist: This does not appear to be a problem on: It is expected that many other clients have the same
problem. What a client should do is
periodically check its open socket(s) to see if they have
been closed by the server, and close their side of the
connection if the server has closed. This check need only
occur once every few seconds, and may even be detected by a
OS signal on some systems (e.g., Win95 and NT
clients have this capability, but they seem to be ignoring
it). Apache cannot avoid these FIN_WAIT_2
states unless it disables persistent connections for the
buggy clients, just like we recommend doing for Navigator
2.x clients due to other bugs. However, non-persistent
connections increase the total number of connections needed
per client and slow retrieval of an image-laden web page.
Since non-persistent connections have their own resource
consumptions and a short waiting period after each closure,
a busy server may need persistence in order to best serve
its clients. As far as we know, the client-caused FIN_WAIT_2 problem
is present for all servers that support persistent
connections, including Apache 1.1.x and 1.2. While the above bug is a problem, it is not the whole
problem. Some users have observed no FIN_WAIT_2 problems
with Apache 1.1.x, but with 1.2b enough connections build
up in the FIN_WAIT_2 state to crash their server. The most
likely source for additional FIN_WAIT_2 states is a
function called The code in There are several possible workarounds to the problem, some
of which work better than others. The obvious workaround is to simply have a timeout for the
FIN_WAIT_2 state. This is not specified by the RFC, and
could be claimed to be a violation of the RFC, but it is
widely recognized as being necessary. The following systems
are known to have a timeout: The following systems are known to not have a
timeout: There is a
patch available for adding a timeout to the FIN_WAIT_2
state; it was originally intended for BSD/OS, but should be
adaptable to most systems using BSD networking code. You
need kernel source code to be able to use it. It is possible to compile Apache 1.2 without using the
To compile without the On most systems, there is an option called
To try it, add The exact way to increase them may depend on your
OS; look for some reference to the number of "mbufs" or
"mbuf clusters". On many systems, this can be done by
adding the line If you are unable to do any of the above then you
should, as a last resort, disable KeepAlive. Edit your
httpd.conf and change "KeepAlive On" to "KeepAlive
Off". Below is a message from Roy Fielding, one of the authors
of HTTP/1.1. The need for a server to linger on a socket after a close
is noted a couple times in the HTTP specs, but not
explained. This explanation is based on discussions between
myself, Henrik Frystyk, Robert S. Thau, Dave Raggett, and
John C. Mallery in the hallways of MIT while I was at W3C. If a server closes the input side of the connection
while the client is sending data (or is planning to send
data), then the server's TCP stack will signal an RST
(reset) back to the client. Upon receipt of the RST, the
client will flush its own incoming TCP buffer back to the
un-ACKed packet indicated by the RST packet argument. If
the server has sent a message, usually an error response,
to the client just before the close, and the client
receives the RST packet before its application code has
read the error message from its incoming TCP buffer and
before the server has received the ACK sent by the client
upon receipt of that buffer, then the RST will flush the
error message before the client application has a chance to
see it. The result is that the client is left thinking that
the connection failed for no apparent reason. There are two conditions under which this is likely to
occur: The solution in all cases is to send the response, close
only the write half of the connection (what shutdown is
supposed to do), and continue reading on the socket until
it is either closed by the client (signifying it has
finally read the response) or a timeout occurs. That is
what the kernel is supposed to do if SO_LINGER is set.
Unfortunately, SO_LINGER has no effect on some systems; on
some other systems, it does not have its own timeout and
thus the TCP memory segments just pile-up until the next
reboot (planned or not). Please note that simply removing the linger code will
not solve the problem -- it only moves it to a different
and much harder one to detect. Apache HTTP Server Version 2.0 Below is a list of additional documentation pages that apply
to the Apache web server development project. Some of the documents below have not been fully updated
to take into account changes made in the 2.0 version of the
Apache HTTP Server. Some of the information may still be
relevant, but please use it with care. Describes a solution which uses XSSI and negotiation to
custom-tailor the Apache ErrorDocuments to taste, adding the
advantage of returning internationalized versions of the
error messages depending on the client's language
preferences. Describes how Apache uses file descriptors and talks
about various limits imposed on the number of descriptors
available by various operating systems. A description of the causes of Apache processes going
into the A list of problems in HTTP clients which can be mitigated
by Apache. Notes about how to (run-time and compile-time) configure
Apache for highest performance. Notes explaining why Apache
does some things, and why it doesn't do other things (which
make it slower/faster). Some "do"s - and "don't"s - for keeping your Apache web
site secure. This document supplements the A list of external resources which help to accomplish common
tasks with the Apache HTTP server. This document acts as a reference page for most of the relevant
standards that Apache follows. Apache HTTP Server Version 2.0 This document has not been fully updated
to take into account changes made in the 2.0 version of the
Apache HTTP Server. Some of the information may still be
relevant, but please use it with care. Over time the Apache Group has discovered or been notified
of problems with various clients which we have had to work
around, or explain. This document describes these problems and
the workarounds available. It's not arranged in any particular
order. Some familiarity with the standards is assumed, but not
necessary. For brevity, Navigator will refer to Netscape's
Navigator product (which in later versions was renamed
"Communicator" and various other names), and MSIE will
refer to Microsoft's Internet Explorer product. All trademarks
and copyrights belong to their respective companies. We welcome
input from the various client authors to correct
inconsistencies in this paper, or to provide us with exact
version numbers where things are broken/fixed. For reference, RFC1945
defines HTTP/1.0, and RFC2068
defines HTTP/1.1. Apache as of version 1.2 is an HTTP/1.1
server (with an optional HTTP/1.0 proxy). Various of these workarounds are triggered by environment
variables. The admin typically controls which are set, and for
which clients, by using This is a legacy issue. The CERN webserver required
Various clients have had broken implementations of
keepalive (persistent connections). In particular the
Windows versions of Navigator 2.0 get very confused when the
server times out an idle connection. The workaround is present
in the default config files: Note that this matches some earlier versions of MSIE, which
began the practice of calling themselves Mozilla in
their user-agent strings just like Navigator. MSIE 4.0b2, which claims to support HTTP/1.1, does not
properly support keepalive when it is used on 301 or 302
(redirect) responses. Unfortunately Apache's
To quote from section 3.1 of RFC1945: Since Apache is an HTTP/1.1 server, it indicates so as part of
its response. Many client authors mistakenly treat this part of
the response as an indication of the protocol that the response
is in, and then refuse to accept the response. The first major indication of this problem was with AOL's
proxy servers. When Apache 1.2 went into beta it was the first
wide-spread HTTP/1.1 server. After some discussion, AOL fixed
their proxies. In anticipation of similar problems, the
The pre-1.1 Java Development Kit (JDK) that is used in many
clients (including Navigator 3.x and MSIE 3.x) exhibits this
problem. As do some of the early pre-releases of the 1.1 JDK.
We think it is fixed in the 1.1 JDK release. In any event the
workaround: RealPlayer 4.0 from Progressive Networks also exhibits this
problem. However they have fixed it in version 4.01 of the
player, but version 4.01 uses the same MSIE 4.0b2 has this problem. Its Java VM makes requests in
HTTP/1.1 format but the responses must be in HTTP/1.0 format
(in particular, it does not understand chunked
responses). The workaround is to fool Apache into believing the
request came in HTTP/1.0 format. This workaround is available in 1.2.2, and in a
patch against 1.2.1. All versions of Navigator from 2.0 through 4.0b2 (and
possibly later) have a problem if the trailing CRLF of the
response header starts at offset 256, 257 or 258 of the
response. A BrowserMatch for this would match on nearly every
hit, so the workaround is enabled automatically on all
responses. The workaround implemented detects when this
condition would occur in a response and adds extra padding to
the header to push the trailing CRLF past offset 258 of the
response. On multipart responses some clients will not accept quotes
(") around the boundary string. The MIME standard recommends
that such quotes be used. But the clients were probably written
based on one of the examples in RFC2068, which does not include
quotes. Apache does not include quotes on its boundary strings
to workaround this problem. A byterange request is used when the client wishes to
retrieve a portion of an object, not necessarily the entire
object. There was a very old draft which included these
byteranges in the URL. Old clients such as Navigator 2.0b1 and
MSIE 3.0 for the MAC exhibit this behaviour, and it will appear
in the servers' access logs as (failed) attempts to retrieve a
URL with a trailing ";xxx-yyy". Apache does not attempt to
implement this at all. A subsequent draft of this standard defines a header
Navigator (versions 2 and 3) sends both The Adobe Acrobat Reader plugin makes extensive use of
byteranges and prior to version 3.01 supports only the
Netscape Communicator appears to not issue the non-standard
The HTTP specifications say that it is legal to merge
headers with duplicate names into one (separated by commas).
Some browsers that support Cookies don't like merged headers
and prefer that each Navigator versions 2 through 4 will erroneously re-request
GIF89A animations on each loop of the animation if the first
response included an In certain situations Navigator 3.01 through 3.03 appear to
incorrectly issue a POST without the request body. There is no
known workaround. It has been fixed in Navigator 3.04,
Netscapes provides some information.
There's also
some information about the actual problem. The http client in the JDK1.2beta2 and beta3 will throw away
the first part of the response body when both the headers and
the first part of the body are sent in the same network packet
AND keep-alive's are being used. If either condition is not met
then it works fine. See also Bug-ID's 4124329 and 4125538 at the java developer
connection. If you are seeing this bug yourself, you can add the
following BrowserMatch directive to work around it: We don't advocate this though since bending over backwards
for beta software is usually not a good idea; ideally it gets
fixed, new betas or a final release comes out, and no one uses
the broken old software anymore. In theory. Navigator (all versions?) will cache the
MSIE versions 3.00 and 3.02 (without the Y2K patch) do not
handle cookie expiry dates in the year 2000 properly. Years
after 2000 and before 2000 work fine. This is fixed in IE4.01
service pack 1, and in the Y2K patch for IE3.02. Users should
avoid using expiry dates in the year 2000. The Lynx browser versions 2.7 and 2.8 send a "negotiate:
trans" header in their requests, which is an indication the
browser supports transparent content negotiation (TCN). However
the browser does not support TCN. As of version 1.3.4, Apache
supports TCN, and this causes problems with these versions of
Lynx. As a workaround future versions of Apache will ignore
this header when sent by the Lynx client. MSIE 4.0 does not handle a Vary header properly. The Vary
header is generated by mod_rewrite in apache 1.3. The result is
an error from MSIE saying it cannot download the requested
file. There are more details in PR#4118. A workaround is to add the following to your server's
configuration files: (This workaround is only available with releases
after 1.3.6 of the Apache Web server.) Apache HTTP Server Version 2.0 Apache 2.x is a general-purpose webserver, designed to
provide a balance of flexibility, portability, and performance.
Although it has not been designed specifically to set benchmark
records, Apache 2.x is capable of high performance in many
real-world situations. Compared to Apache 1.3, release 2.x contains many additional
optimizations to increase throughput and scalability. Most of
these improvements are enabled by default. However, there are
compile-time and run-time configuration choices that can
significantly affect performance. This document describes the
options that a server administrator can configure to tune the
performance of an Apache 2.x installation. Some of these
configuration options enable the httpd to better take advantage
of the capabilities of the hardware and OS, while others allow
the administrator to trade functionality for speed. The single biggest hardware issue affecting webserver
performance is RAM. A webserver should never ever have to swap,
as swapping increases the latency of each request beyond a point
that users consider "fast enough". This causes users to hit
stop and reload, further increasing the load. You can, and
should, control the Beyond that the rest is mundane: get a fast enough CPU, a
fast enough network card, and fast enough disks, where "fast
enough" is something that needs to be determined by
experimentation. Operating system choice is largely a matter of local
concerns. But some guidelines that have proven generally
useful are: Run the latest stable release and patchlevel of the
operating system that you choose. Many OS suppliers have
introduced significant performance improvements to their
TCP stacks and thread libraries in recent years. If your OS supports a Prior to Apache 1.3, It is recommended that you do this sort of postprocessing of
your log files on some machine other than the production web
server machine, in order that this activity not adversely affect
server performance. If you use any Note that it's possible to scope the directives, such as
within a But even still, if you just need DNS names in some CGIs you
could consider doing the Wherever in your URL-space you do not have an and a request is made for the URI This at least avoids the extra checks for the
Wherever in your URL-space you allow overrides (typically
and a request is made for the URI If at all possible, avoid content-negotiation if you're
really interested in every last ounce of performance. In
practice the benefits of negotiation outweigh the performance
penalties. There's one case where you can speed up the server.
Instead of using a wildcard such as: Use a complete list of options: where you list the most common choice first. Also note that explicitly creating a If your site needs content negotiation consider using
In situations where Apache 2.x needs to look at the contents
of a file being delivered--for example, when doing server-side-include
processing--it normally memory-maps the file if the OS supports
some form of On some platforms, this memory-mapping improves performance.
However, there are cases where memory-mapping can hurt the performance
or even the stability of the httpd: On some operating systems, If you memory-map a file located on an NFS-mounted filesystem
and a process on another NFS client machine deletes or truncates
the file, your process may get a bus error the next time it tries
to access the mapped file content. For installations where either of these factors applies, you
should use In situations where Apache 2.x can ignore the contents of the file
to be delivered -- for example, when serving static file content --
it normally uses the kernel sendfile support the file if the OS
supports the On most platforms, using sendfile improves performance by eliminating
separate read and send mechanics. However, there are cases where using
sendfile can harm the stability of the httpd: Some platforms may have broken sendfile support that the build
system did not detect, especially if the binaries were built on
another box and moved to such a machine with broken sendfile support. With an NFS-mounted files, the kernel may be unable
to reliably serve the network file through it's own cache. For installations where either of these factors applies, you
should use Prior to Apache 1.3 the The one-per-second rule was implemented in an effort to
avoid swamping the machine with the startup of new children. If
the machine is busy spawning children it can't service
requests. But it has such a drastic effect on the perceived
performance of Apache that it had to be replaced. As of Apache
1.3, the code will relax the one-per-second rule. It will spawn
one, wait a second, then spawn two, wait a second, then spawn
four, and it will continue exponentially until it is spawning
32 children per second. It will stop whenever it satisfies the
This appears to be responsive enough that it's almost
unnecessary to twiddle the Related to process creation is process death induced by the
When keep-alives are in use, children will be kept busy
doing nothing waiting for more requests on the already open
connection. The default Apache 2.x supports pluggable concurrency models, called
Multi-Processing Modules (MPMs).
When building Apache, you must choose an MPM to use. There
are platform-specific MPMs for some platforms:
For more information on these and other MPMs, please
see the MPM documentation. Since memory usage is such an important consideration in
performance, you should attempt to eliminate modules that you are
not actually using. If you have built the modules as DSOs, eliminating modules is a simple
matter of commenting out the associated If, on the other hand, you have modules statically linked
into your Apache binary, you will need to recompile Apache in
order to remove unwanted modules. An associated question that arises here is, of course, what
modules you need, and which ones you don't. The answer here
will, of course, vary from one web site to another. However, the
minimal list of modules which you can get by with tends
to include Some modules, such as By default, APR implements these operations using the
most efficient mechanism available on each target
OS/CPU platform. Many modern CPUs, for example, have
an instruction that does an atomic compare-and-swap (CAS)
operation in hardware. On some platforms, however, APR
defaults to a slower, mutex-based implementation of the
atomic API in order to ensure compatibility with older
CPU models that lack such instructions. If you are
building Apache for one of these platforms, and you plan
to run only on newer CPUs, you can select a faster atomic
implementation at build time by configuring Apache with
the The If you include This section has not been fully updated
to take into account changes made in the 2.x version of the
Apache HTTP Server. Some of the information may still be
relevant, but please use it with care. This discusses a shortcoming in the Unix socket API. Suppose
your web server uses multiple But this naive implementation has a serious starvation problem.
Recall that multiple children execute this loop at the same
time, and so multiple children will block at
One solution is to make the sockets non-blocking. In this
case the Another solution, the one used by Apache, is to serialize
entry into the inner loop. The loop looks like this
(differences highlighted): The functions
The directive This method uses the This method uses the (1.3 or later) This method uses SysV-style semaphores to
implement the mutex. Unfortunately SysV-style semaphores have
some bad side-effects. One is that it's possible Apache will
die without cleaning up the semaphore (see the
(1.3 or later) This method uses POSIX mutexes and should
work on any architecture implementing the full POSIX threads
specification, however appears to only work on Solaris (2.5
or later), and even then only in certain configurations. If
you experiment with this you should watch out for your server
hanging and not responding. Static content only servers may
work just fine. (2.0 or later) This method uses POSIX semaphores. The
semaphore ownership is not recovered if a thread in the process
holding the mutex segfaults, resulting in a hang of the web
server. If your system has another method of serialization which
isn't in the above list then it may be worthwhile adding code
for it to APR. Another solution that has been considered but never
implemented is to partially serialize the loop -- that is, let
in a certain number of processes. This would only be of
interest on multiprocessor boxes where it's possible multiple
children could run simultaneously, and the serialization
actually doesn't take advantage of the full bandwidth. This is
a possible area of future investigation, but priority remains
low because highly parallel web servers are not the norm. Ideally you should run servers without multiple
The above is fine and dandy for multiple socket servers, but
what about single socket servers? In theory they shouldn't
experience any of these same problems because all children can
just block in For this reason we have found that many architectures behave
more "nicely" if we serialize even the single socket case. So
this is actually the default in almost all cases. Crude
experiments under Linux (2.0.30 on a dual Pentium pro 166
w/128Mb RAM) have shown that the serialization of the single
socket case causes less than a 3% decrease in requests per
second over unserialized single-socket. But unserialized
single-socket showed an extra 100ms latency on each request.
This latency is probably a wash on long haul lines, and only an
issue on LANs. If you want to override the single socket
serialization you can define
As discussed in
draft-ietf-http-connection-00.txt section 8, in order for
an HTTP server to reliably implement the
protocol it needs to shutdown each direction of the
communication independently (recall that a TCP connection is
bi-directional, each half is independent of the other). This
fact is often overlooked by other servers, but is correctly
implemented in Apache as of 1.2. When this feature was added to Apache it caused a flurry of
problems on various versions of Unix because of a
shortsightedness. The TCP specification does not state that the
There are two ways of accomplishing this. One is the socket
option For the most part, Apache implements this in a function
called This naturally adds some expense at the end of a connection,
but it is required for a reliable implementation. As HTTP/1.1
becomes more prevalent, and all connections are persistent,
this expense will be amortized over more requests. If you want
to play with fire and disable this feature you can define
Apache's parent and children communicate with each other
through something called the scoreboard. Ideally this should be
implemented in shared memory. For those operating systems that
we either have access to, or have been given detailed ports
for, it typically is implemented using shared memory. The rest
default to using an on-disk file. The on-disk file is not only
slow, but it is unreliable (and less featured). Peruse the
If you have no intention of using dynamically loaded modules
(you probably don't if you're reading this and tuning your
server for every last ounce of performance) then you should add
Here is a system call trace of Apache 2.0.38 with the worker MPM
on Solaris 8. This trace was collected using: The Other systems may have different system call tracing utilities
such as In this trace, a client has requested a 10KB static file
from the httpd. Traces of non-static requests or requests
with content negotiation look wildly different (and quite ugly
in some cases). In this trace, the listener thread is running within LWP #67. Upon accepting the connection, the listener thread wakes up
a worker thread to do the request processing. In this trace,
the worker thread that handles the request is mapped to LWP #65. In order to implement virtual hosts, Apache needs to know
the local socket address used to accept the connection. It
is possible to eliminate this call in many situations (such
as when there are no virtual hosts, or when
The Next, the worker thread puts the connection to the client (file
descriptor 9) in non-blocking mode. The The worker thread reads the request from the client. This httpd has been configured with In this example, the httpd is able to send the HTTP response
header and the requested file with a single This The worker thread does a lingering close of the connection. Finally the worker thread closes the file that it has just delivered
and blocks until the listener assigns it another connection. Meanwhile, the listener thread is able to accept another connection
as soon as it has dispatched this connection to a worker thread (subject
to some flow-control logic in the worker MPM that throttles the listener
if all the available workers are busy). Though it isn't apparent from
this trace, the next Apache HTTP Server Version 2.0 This page documents all the relevant standards that the
Apache HTTP Server follows, along with brief descriptions. In addition to the information listed below, the following resources
should be consulted: This document is not yet complete. Regardless of what modules are compiled and used, Apache as a
basic web server complies with the following IETF recommendations: Regarding the Hypertext Markup Language, Apache complies with
the following IETF and W3C recommendations: Concerning the different methods of authentication, Apache
follows the following IETF recommendations: The following links document ISO and other language and country
code information: Apache HTTP Server Version 2.0 Originally written by This document supplements the The Apache module In other words: With Here come a lot of practical solutions I've either invented
myself or collected from other people's solutions in the past.
Feel free to learn the black magic of URL rewriting from
these examples. On some webservers there are more than one URL for a
resource. Usually there are canonical URLs (which should be
actually used and distributed) and those which are just
shortcuts, internal ones, etc. Independent of which URL the
user supplied with the request he should finally see the
canonical one only. We do an external HTTP redirect for all non-canonical
URLs to fix them in the location view of the Browser and
for all subsequent requests. In the example ruleset below
we replace Usually the We redirect the URL Note that this can also be handled using the Every webmaster can sing a song about the problem of
the trailing slash on URLs referencing directories. If they
are missing, the server dumps an error, because if you say
The solution to this subtle problem is to let the server
add the trailing slash automatically. To do this
correctly we have to use an external redirect, so the
browser correctly requests subsequent images etc. If we
only did a internal rewrite, this would only work for the
directory page, but would go wrong when any images are
included into this page with relative URLs, because the
browser would request an in-lined object. For instance, a
request for So, to do this trick we write: The crazy and lazy can even do the following in the
top-level We want to create a homogeneous and consistent URL
layout over all WWW servers on a Intranet webcluster, i.e.
all URLs (per definition server local and thus server
dependent!) become actually server independent!
What we want is to give the WWW namespace a consistent
server-independent layout: no URL should have to include
any physically correct target server. The cluster itself
should drive us automatically to the physical target
host. First, the knowledge of the target servers come from
(distributed) external maps which contain information
where our users, groups and entities stay. The have the
form We put them into files to when the URL is not locally valid to a server. The
following ruleset does this for us by the help of the map
files (assuming that server0 is a default server which
will be used if a user has no entry in the map): Many webmasters have asked for a solution to the
following situation: They wanted to redirect just all
homedirs on a webserver to another webserver. They usually
need such things when establishing a newer webserver which
will replace the old one over time. The solution is trivial with Some sites with thousands of users usually use a
structured homedir layout, i.e. each homedir is in a
subdirectory which begins for instance with the first
character of the username. So, We use the following ruleset to expand the tilde URLs
into exactly the above layout. This really is a hardcore example: a killer application
which heavily uses per-directory
In July 1996 I decided to make this archive public to
the world via a nice Web interface. "Nice" means that I
wanted to offer an interface where you can browse
directly through the archive hierarchy. And "nice" means
that I didn't wanted to change anything inside this
hierarchy - not even by putting some CGI scripts at the
top of it. Why? Because the above structure should be
later accessible via FTP as well, and I didn't want any
Web or CGI stuff to be there. The solution has two parts: The first is a set of CGI
scripts which create all the pages at all directory
levels on-the-fly. I put them under
The The first rule is for requests which miss the trailing
slash! The second rule does the real thing. And then
comes the killer configuration which stays in the
per-directory config file
Some hints for interpretation: When switching from the NCSA webserver to the more
modern Apache webserver a lot of people want a smooth
transition. So they want pages which use their old NCSA
We use a global rule to remove the prefix on-the-fly for
all requests: Sometimes it is necessary to let the webserver search
for pages in more than one directory. Here MultiViews or
other techniques cannot help. We program a explicit ruleset which searches for the
files in the directories. Perhaps you want to keep status information between
requests and use the URL to encode it. But you don't want
to use a CGI wrapper for all pages just to strip out this
information. We use a rewrite rule to strip out the status information
and remember it via an environment variable which can be
later dereferenced from within XSSI or CGI. This way a
URL Assume that you want to provide
For HTTP/1.0 requests there is no solution, but for
HTTP/1.1 requests which contain a Host: HTTP header we
can use the following ruleset to rewrite
We want to redirect homedir URLs to another webserver
Just a rewrite condition: A typical FAQ about URL rewriting is how to redirect
failing requests on webserver A to webserver B. Usually
this is done via The first solution has the best performance but less
flexibility, and is less error safe: The problem here is that this will only work for pages
inside the This uses the URL look-ahead feature of Sometimes we need more control (concerning the
character escaping mechanism) of URLs on redirects.
Usually the Apache kernels URL escape function also
escapes anchors, i.e. URLs like " We have to use a kludge by the use of a NPH-CGI script
which does the redirect itself. Because here no escaping
is done (NPH=non-parseable headers). First we introduce a
new URL scheme This forces all URLs prefixed with
This provides you with the functionality to do
redirects to all URL schemes, i.e. including the one
which are not directly accepted by Do you know the great CPAN (Comprehensive Perl Archive
Network) under http://www.perl.com/CPAN?
This does a redirect to one of several FTP servers around
the world which carry a CPAN mirror and is approximately
near the location of the requesting client. Actually this
can be called an FTP access multiplexing service. While
CPAN runs via CGI scripts, how can a similar approach
implemented via First we notice that from version 3.0.0
When tricks like time-dependent content should happen a
lot of webmasters still use CGI scripts which do for
instance redirects to specialized pages. How can it be done
via There are a lot of variables named This provides the content of How can we make URLs backward compatible (still
existing virtually) after migrating We just rewrite the name to its basename and test for
existence of the new extension. If it exists, we take
that name, else we rewrite the URL to its original state. Assume we have recently renamed the page
We rewrite the old URL to the new one internally via the
following rule: Assume again that we have recently renamed the page
We force a HTTP redirect to the new URL which leads to a
change of the browsers and thus the users view: At least for important top-level pages it is sometimes
necessary to provide the optimum of browser dependent
content, i.e. one has to provide a maximum version for the
latest Netscape variants, a minimum version for the Lynx
browsers and a average feature version for all others. We cannot use content negotiation because the browsers do
not provide their type in that form. Instead we have to
act on the HTTP header "User-Agent". The following condig
does the following: If the HTTP header "User-Agent"
begins with "Mozilla/3", the page Assume there are nice webpages on remote hosts we want
to bring into our namespace. For FTP servers we would use
the To provide this feature we map the remote webpage or even
the complete remote webarea to our namespace by the use
of the Proxy Throughput feature
(flag This is a tricky way of virtually running a corporate
(external) Internet webserver
( First, we have to make sure that our firewall still
protects the internal webserver and that only the
external webserver is allowed to retrieve data from it.
For a packet-filtering firewall we could for instance
configure a firewall ruleset like the following: Just adjust it to your actual configuration syntax.
Now we can establish the Suppose we want to load balance the traffic to
There are a lot of possible solutions for this problem.
We will discuss first a commonly known DNS-based variant
and then the special one with The simplest method for load-balancing is to use
the DNS round-robin feature of Then you additionally add the following entry: Notice that this seems wrong, but is actually an
intended feature of A sophisticated DNS-based method for
load-balancing is to use the program
In this variant we use entry in the DNS. Then we convert
Then we write There is a hardware solution available, too. Cisco
has a beast called LocalDirector which does a load
balancing at the TCP/IP level. Actually this is some
sort of a circuit level gateway in front of a
webcluster. If you have enough money and really need
a solution with high performance, use this one. On the net there are a lot of nifty CGI programs. But
their usage is usually boring, so a lot of webmaster
don't use them. Even Apache's Action handler feature for
MIME-types is only appropriate when the CGI programs
don't need special URLs (actually Or assume we have some more nifty programs:
which is ugly. Because we have to hard-code
both the location of the area
and the location of the CGI inside the
hyperlink. When we have to reorganize the area, we spend a
lot of time changing the various hyperlinks. The solution here is to provide a special new URL format
which automatically leads to the proper CGI invocation.
We configure the following: Now the hyperlink to search at
which internally gets automatically transformed to The same approach leads to an invocation for the
access log CGI program when the hyperlink
How can we transform a static page
We just rewrite the URL to the CGI-script and force the
correct MIME-type so it gets really run as a CGI-script.
This way a request to Here comes a really esoteric feature: Dynamically
generated but statically served pages, i.e. pages should be
delivered as pure static pages (read from the filesystem
and just passed through), but they have to be generated
dynamically by the webserver if missing. This way you can
have CGI-generated pages which are statically served unless
one (or a cronjob) removes the static contents. Then the
contents gets refreshed. Here a request to Wouldn't it be nice while creating a complex webpage if
the webbrowser would automatically refresh the page every
time we write a new version from within our editor?
Impossible? No! We just combine the MIME multipart feature, the
webserver NPH feature and the URL manipulation power of
Now when we reference the URL this leads to the internal invocation of the URL The only missing part is the NPH-CGI script. Although
one would usually say "left as an exercise to the reader"
;-) I will provide this, too. The To provide this feature we map the remote webpage or even
the complete remote webarea to our namespace by the use
of the Proxy Throughput feature (flag How can we block a really annoying robot from
retrieving pages of a specific webarea? A
We use a ruleset which forbids the URLs of the webarea
Assume we have under While we cannot 100% protect the images from inclusion,
we can at least restrict the cases where the browser
sends a HTTP Referer header. How can we forbid a list of externally configured hosts
from using our server? For Apache >= 1.3b6: For Apache <= 1.3b6: How can we forbid a certain host or even a user of a
special host from using the Apache proxy? We first have to make sure ...and this one for a user@host-dependent deny: Sometimes a very special authentication is needed, for
instance a authentication which checks for a set of
explicitly configured users. Only these should receive
access and without explicit prompting (which would occur
when using the Basic Auth via We use a list of rewrite conditions to exclude all except
our friends: How can we program a flexible URL Deflector which acts
on the "Referer" HTTP header and can be configured with as
many referring pages as we like? Use the following really tricky ruleset... ... in conjunction with a corresponding rewrite
map: This automatically redirects the request back to the
referring page (when " A FAQ: How can we solve the FOO/BAR/QUUX/etc.
problem? There seems no solution by the use of
Use an external This is a demonstration-only example and just rewrites
all URLs Apache HTTP Server Version 2.0 Some hints and tips on security issues in setting up a web server.
Some of the suggestions will be general, others specific to Apache. The Apache HTTP Server has a good record for security and a
developer community highly concerned about security issues. But
it is inevitable that some problems -- small or large -- will be
discovered in software after it is released. For this reason, it
is crucial to keep aware of updates to the software. If you have
obtained your version of the HTTP Server directly from Apache, we
highly recommend you subscribe to the Apache
HTTP Server Announcements List where you can keep informed of
new releases and security updates. Similar services are available
from most third-party distributors of Apache software. Of course, most times that a web server is compromised, it is
not because of problems in the HTTP Server code. Rather, it comes
from problems in add-on code, CGI scripts, or the underlying
Operating System. You must therefore stay aware of problems and
updates with all the software on your system. In typical operation, Apache is started by the root user, and it
switches to the user defined by the It is assumed that /, /usr, and /usr/local are only modifiable by
root. When you install the You can create an htdocs subdirectory which is modifiable by other
users -- since root never executes any files out of there, and shouldn't
be creating files in there. If you allow non-root users to modify any files that root either
executes or writes on then you open your system to root compromises.
For example, someone could replace the Server Side Includes (SSI) present a server administrator with
several potential security risks. The first risk is the increased load on the server. All
SSI-enabled files have to be parsed by Apache, whether or not
there are any SSI directives included within the files. While this
load increase is minor, in a shared server environment it can become
significant. SSI files also pose the same risks that are associated with CGI
scripts in general. Using the "exec cmd" element, SSI-enabled files
can execute any CGI script or program under the permissions of the
user and group Apache runs as, as configured in httpd.conf. There are ways to enhance the security of SSI files while still
taking advantage of the benefits they provide. To isolate the damage a wayward SSI file can cause, a server
administrator can enable suexec as
described in the CGI in General section. Enabling SSI for files with .html or .htm extensions can be
dangerous. This is especially true in a shared, or high traffic,
server environment. SSI-enabled files should have a separate extension,
such as the conventional .shtml. This helps keep server load at a
minimum and allows for easier management of risk. Another solution is to disable the ability to run scripts and
programs from SSI pages. To do this replace First of all, you always have to remember that you must trust the
writers of the CGI scripts/programs or your ability to spot potential
security holes in CGI, whether they were deliberate or accidental. CGI
scripts can run essentially arbitrary commands on your system with the
permissions of the web server user and can therefore be extremely
dangerous if they are not carefully checked. All the CGI scripts will run as the same user, so they have potential
to conflict (accidentally or deliberately) with other scripts e.g. User
A hates User B, so he writes a script to trash User B's CGI database. One
program which can be used to allow scripts to run as different users is
suEXEC which is included with Apache as of
1.2 and is called from special hooks in the Apache server code. Another
popular way of doing this is with
CGIWrap. Allowing users to execute CGI scripts in any directory should only be
considered if: Limiting CGI to special directories gives the admin control over what
goes into those directories. This is inevitably more secure than non
script aliased CGI, but only if users with write access to the
directories are trusted or the admin is willing to test each
new CGI script/program for potential security holes. Most sites choose this option over the non script aliased CGI
approach.
Embedded scripting options which run as part of the server itself,
such as mod_php, mod_perl, mod_tcl, and mod_python, run under the
identity of the server itself (see the To run a really tight ship, you'll want to stop users from setting
up In the server configuration file, put This prevents the use of One aspect of Apache which is occasionally misunderstood is the
feature of default access. That is, unless you take steps to change it,
if the server can find its way to a file through normal URL mapping
rules, it can serve it to clients. For instance, consider the following example: This would allow clients to walk through the entire filesystem. To
work around this, add the following block to your server's
configuration: This will forbid default access to filesystem locations. Add
appropriate Pay particular attention to the interactions of Also be wary of playing games with the To keep up-to-date with what is actually going on against your server
you have to check the Log Files. Even though
the log files only reports what has already happened, they will give you
some understanding of what attacks is thrown against the server and
allow you to check if the necessary level of security is present. A couple of examples: The first example will list the number of attacks trying to exploit the
Apache Tomcat
Source.JSP Malformed Request Information Disclosure Vulnerability,
the second example will list the ten last denied clients, for example: As you can see, the log files only report what already has happened, so
if the client had been able to access the in your Access Log. This means
you probably commented out the following in your server configuration
file: Apache HTTP Server Version 2.0 This document has not been fully updated
to take into account changes made in the 2.0 version of the
Apache HTTP Server. Some of the information may still be
relevant, but please use it with care. The following documents give you step-by-step instructions
on how to accomplish common tasks with the Apache HTTP server.
Many of these documents are located at external sites and are
not the work of the Apache Software Foundation. Copyright to
documents on external sites is owned by the authors or their
assignees. Please consult the official Apache
Server documentation to verify what you read on external
sites. If you have a pointer to an accurate and well-written
tutorial not included here, please let us know by submitting it
to the Apache Bug
Database. Apache HTTP Server Version 2.0 This Multi-Processing Module (MPM) is the default for BeOS. It uses
a single control process which creates threads to handle requests. The Setting For Apache HTTP Server Version 2.0 This directive controls whether requests that contain trailing
pathname information that follows an actual filename (or
non-existent file in an existing directory) will be accepted or
rejected. The trailing pathname information can be made
available to scripts in the For example, assume the location The three possible arguments for the
The primary purpose of the While processing a request the server looks for
the first existing configuration file from this list of names in
every directory of the path to the document, if distributed
configuration files are enabled for that
directory. For example: before returning the document
This directive specifies a default value for the media type
charset parameter (the name of a character encoding) to be added
to a response if and only if the response's content-type is either
This directive activates a particular output filter for a request depending on the
response MIME-type. The following example uses the If you want the content to be processed by more than one filter, their
names have to be separated by semicolons. It's also possible to use one
The configuration below causes all script output labeled as
Enabling filters with However, if you want to make sure, that the filters will be
applied, assign the content type to a resource explicitly, for
example with The by-type output filters are never applied on proxy requests. The Turning Allowing encoded slashes does not imply decoding.
Occurrences of When the server finds an When this directive is set to When this directive is set to The directive-type can be one of the following
groupings of directives. Example: In the example above all directives that are neither in the group
This directive sets the name of the authorization realm for a
directory. This realm is given to the client so that the user
knows which username and password to send.
For example: The string provided for the This directive selects the type of user authentication for a
directory. Only This directive is used to control how Apache finds the
interpreter used to run CGI scripts. For example, setting
This directive enables the generation of
MD5 is an algorithm for computing a "message digest"
(sometimes called "fingerprint") of arbitrary-length data, with
a high degree of confidence that any alterations in the data
will be reflected in alterations in the message digest. The Note that this can cause performance problems on your server
since the message digest is computed on every request (the
values are not cached). There will be times when the server is asked to provide a
document whose type cannot be determined by its MIME types
mappings. The server must inform the client of the content-type of the
document, so in the event of an unknown type it uses the
would be appropriate for a directory which contained many GIF
images with filenames missing the Note that unlike Be careful with the directory-path arguments:
They have to literally match the filesystem path which Apache uses
to access the files. Directives applied to a particular
Extended regular
expressions can also be used, with the addition of the
would match directories in If multiple (non-regular expression) for access to the document Regular expressions are not considered until after all of the
normal sections have been applied. Then all of the regular
expressions are tested in the order they appeared in the
configuration file. For example, with the regular expression section won't be considered until after
all normal Note that the default Apache access for
and then override this for directories you
want accessible. See the Security Tips page for more
details. The directory sections occur in the would match directories in This directive sets the directory from which then an access to
The This directive controls whether the This memory-mapping sometimes yields a performance improvement.
But in some environments, it is better to disable the memory-mapping
to prevent operational problems: For server configurations that are vulnerable to these problems,
you should disable memory-mapping of delivered files by specifying: For NFS mounted files, this feature may be disabled explicitly for
the offending files by specifying: This directive controls whether This sendfile mechanism avoids separate read and send operations,
and buffer allocations. But on some platforms or within some
filesystems, it is better to disable this feature to avoid
operational problems: For server configurations that are vulnerable to these problems,
you should disable this feature by specifying: For NFS or SMB mounted files, this feature may be disabled explicitly
for the offending files by specifying: In the event of a problem or error, Apache can be configured
to do one of four things, The first option is the default, while options 2-4 are
configured using the URLs can begin with a slash (/) for local web-paths (relative
to the Additionally, the special value Note that when you specify an Microsoft Internet Explorer (MSIE) will by default ignore
server-generated error messages when they are "too small" and substitute
its own "friendly" error messages. The size threshold varies depending on
the type of error, but in general, if you make your error document
greater than 512 bytes, then MSIE will show the server-generated
error rather than masking it. More information is available in
Microsoft Knowledge Base article Q294807. Although most error messages can be overriden, there are certain
circumstances where the internal messages are used regardless of the
setting of Prior to version 2.0, messages were indicated by prefixing
them with a single unmatched double quote character. The If the file-path
begins with a pipe (|) then it is assumed to be a command to spawn
to handle the error log. Using SECURITY: See the security tips
document for details on why your security could be compromised
if the directory where log files are stored is writable by
anyone other than the user that starts the server. When entering a file path on non-Unix platforms, care should be taken
to make sure that only forward slashed are used even though the platform
may allow the use of back slashes. In general it is a good idea to always
use forward slashes throughout the configuration files.
The The If a directory's configuration includes
The The filename argument should include a filename, or
a wild-card string, where would match most common Internet graphics formats. Note that unlike The would match most common Internet graphics formats. When placed into an Note that unlike You can override any This directive enables DNS lookups so that host names can be
logged (and passed to CGIs/SSIs in Regardless of the setting, when The default is This directive enables RFC1413-compliant logging of the
remote user name for each connection, where the client machine
runs identd or something similar. This information is logged in
the access log. The information should not be trusted in any way except for
rudimentary usage tracking. Note that this can cause serious latency problems accessing
your server since every request requires one of these lookups
to be performed. When firewalls are involved each lookup might
possibly fail and add 30 seconds of latency to each hit. So in
general this is not very useful on public servers accessible
from the Internet. The The test in the In the former case, the directives between the start and end
markers are only processed if the parameter named
parameter-name is defined. The second format reverses
the test, and only processes the directives if
parameter-name is not defined. The parameter-name argument is a define as given on
the The The test in the In the former case, the directives between the start and end
markers are only processed if the module named module
name is included in Apache -- either compiled in or
dynamically loaded using The module name argument is the file name of the
module, at the time it was compiled. For example,
This directive allows inclusion of other configuration files
from within the server configuration files. Shell-style ( The file path specified may be an absolute path, or may be relative
to the Examples: Or, providing paths relative to your Running The Keep-Alive extension to HTTP/1.0 and the persistent
connection feature of HTTP/1.1 provide long-lived HTTP sessions
which allow multiple requests to be sent over the same TCP
connection. In some cases this has been shown to result in an
almost 50% speedup in latency times for HTML documents with
many images. To enable Keep-Alive connections, set
For HTTP/1.0 clients, Keep-Alive connections will only be
used if they are specifically requested by a client. In
addition, a Keep-Alive connection with an HTTP/1.0 client can
only be used when the length of the content is known in
advance. This implies that dynamic content such as CGI output,
SSI pages, and server-generated directory listings will
generally not use Keep-Alive connections to HTTP/1.0 clients.
For HTTP/1.1 clients, persistent connections are the default
unless otherwise specified. If the client requests it, chunked
encoding will be used in order to send content of unknown
length over persistent connections. The number of seconds Apache will wait for a subsequent
request before closing the connection. Once a request has been
received, the timeout value specified by the
Setting Access controls are normally effective for
all access methods, and this is the usual
desired behavior. In the general case, access control
directives should not be placed within a
The purpose of the The method names listed can be one or more of: For example: An internal redirect happens, for example, when using the The directive stores two different limits, which are evaluated on
per-request basis. The first number is the maximum number of
internal redirects, that may follow each other. The second number
determines, how deep subrequests may be nested. If you specify only one
number, it will be assigned to both limits. This directive specifies the number of bytes from 0
(meaning unlimited) to 2147483647 (2GB) that are allowed in a
request body. The This directive gives the server administrator greater
control over abnormal client request behavior, which may be
useful for avoiding some forms of denial-of-service
attacks. If, for example, you are permitting file upload to a particular
location, and wish to limit the size of the uploaded file to 100K,
you might use the following directive: Number is an integer from 0 (meaning unlimited) to
32767. The default value is defined by the compile-time
constant The This directive gives the server administrator greater
control over abnormal client request behavior, which may be
useful for avoiding some forms of denial-of-service attacks.
The value should be increased if normal clients see an error
response from the server that indicates too many fields were
sent in the request. For example: This directive specifies the number of bytes
that will be allowed in an HTTP request header. The This directive gives the server administrator greater
control over abnormal client request behavior, which may be
useful for avoiding some forms of denial-of-service attacks. For example: This directive sets the number of bytes from 0 to
the value of the compile-time constant
The This directive gives the server administrator greater
control over abnormal client request behavior, which may be
useful for avoiding some forms of denial-of-service attacks. For example: Limit (in bytes) on maximum size of an XML-based request
body. A value of Example: The Use For all origin (non-proxy) requests, the URL to be matched is a
URL-path of the form The URL may use wildcards. In a wild-card string, Extended regular
expressions can also be used, with the addition of the
would match URLs that contained the substring The The slash character has special meaning depending on where in a
URL it appears. People may be used to its behavior in the filesystem
where multiple adjacent slashes are frequently collapsed to a single
slash (i.e., For example, The would match URLs that contained the substring When a particular level is specified, messages from all
other levels of higher significance will be reported as well.
E.g., when Using a level of at least For example: When logging to a regular file messages of the level
The For example: The Although addr can be hostname it is recommended
that you always use an IP address, e.g. With the Note, that the "main server" and any Optionally you can specify a port number on which the
name-based virtual hosts should be used, e.g. IPv6 addresses must be enclosed in square brackets, as shown
in the following example: To receive requests on all interfaces, you can use an argument of
Note that the argument to the The option can be set to Even though the server follows the symlink it does not
change the pathname used to match against Note also, that this option gets ignored if set
inside a Normally, if multiple Mixing For example, without any then only then the options Using The default in the absence of any other settings is
This directive selects which authenticated users can access
a resource. The allowed syntaxes are: Access controls which are applied in this way are effective for
all methods. This is what is normally
desired. If you wish to apply access controls only to
specific methods, while leaving other methods unprotected, then
place the Takes 1 or 2 parameters. The first parameter sets the soft
resource limit for all processes and the second parameter sets
the maximum resource limit. Either parameter can be a number,
or This applies to processes forked off from Apache children
servicing requests, not the Apache children themselves. This
includes CGI scripts and SSI exec commands, but not any
processes forked off from the Apache parent such as piped
logs. CPU resource limits are expressed in seconds per
process. Takes 1 or 2 parameters. The first parameter sets the soft
resource limit for all processes and the second parameter sets
the maximum resource limit. Either parameter can be a number,
or This applies to processes forked off from Apache children
servicing requests, not the Apache children themselves. This
includes CGI scripts and SSI exec commands, but not any
processes forked off from the Apache parent such as piped
logs. Memory resource limits are expressed in bytes per
process. Takes 1 or 2 parameters. The first parameter sets the soft
resource limit for all processes and the second parameter sets
the maximum resource limit. Either parameter can be a number,
or This applies to processes forked off from Apache children
servicing requests, not the Apache children themselves. This
includes CGI scripts and SSI exec commands, but not any
processes forked off from the Apache parent such as piped
logs. Process limits control the number of processes per user. If CGI processes are not running
under user ids other than the web server user id, this directive
will limit the number of processes that the server itself can
create. Evidence of this situation will be indicated by
Access policy if both For example, if you wanted to let people on your network have
unrestricted access to a portion of your website, but require that
people outside of your network provide a password, you could use a
configuration similar to the following: Since version 2.0.51 This directive is used to control how Apache finds the
interpreter used to run CGI scripts. The default setting is
or, if Setting Be careful when using The option The It may be worth setting up a dedicated address for this, e.g. as users do not always mention that they are talking about the
server! The The If no If you are using name-based virtual hosts,
the See the description of the
The The The The After version 2.0.44, the details of the server version number
presented are controlled by the This directive controls whether This setting applies to the entire server, and cannot be
enabled or disabled on a virtualhost-by-virtualhost basis. After version 2.0.44, this directive also controls the
information presented by the When placed into an Another example: if you wanted to have the server display a
status report whenever a URL of
You can override an earlier defined The If more than one filter is specified, they must be separated
by semicolons in the order in which they should process the
content. The For example, the following configuration will process all files
in the If more than one filter is specified, they must be separated
by semicolons in the order in which they should process the
content. The We plan on making these separately configurable at some point
down the road. The timer used to default to 1200 before 1.2,
but has been lowered to 300 which is still far more than
necessary in most situations. It is not set any lower by
default because there may still be odd places in the code where
the timer is not reset when a packet is sent. This directive overrides the behavior of Finally, for testing and diagnostic purposes only, request
bodies may be allowed using the non-compliant In many situations Apache must construct a self-referential
URL -- that is, a URL that refers back to the same server. With
With An example where this may be useful is on an intranet server
where you have users connecting to the machine using short
names such as There is a third option, If CGIs make assumptions about the values of IPv6 addresses must be specified in square brackets because
the optional port number could not be determined otherwise. An
IPv6 example is shown below: Each Virtual Host must correspond to a different IP address,
different port number or a different host name for the server,
in the former case the server machine must be configured to
accept IP packets for multiple addresses. (If the machine does
not have multiple network interfaces, then this can be
accomplished with the The use of When using IP-based virtual hosting, the special name
You can specify a See the security tips
document for details on why your security could be compromised if the
directory where log files are stored is writable by anyone other
than the user that starts the server. Apache HTTP Server Version 2.0 This document describes the terms that are used to describe
each Apache configuration
directive. A brief description of the purpose of the directive. This indicates the format of the directive as it would
appear in a configuration file. This syntax is extremely
directive-specific, and is described in detail in the
directive's definition. Generally, the directive name is
followed by a series of one or more space-separated arguments.
If an argument contains a space, the argument must be enclosed
in double quotes. Optional arguments are enclosed in square
brackets. Where an argument can take on more than one possible
value, the possible values are separated by vertical bars "|".
Literal text is presented in the default font, while
argument-types for which substitution is necessary are
emphasized. Directives which can take a variable
number of arguments will end in "..." indicating that the last
argument is repeated. Directives use a great number of different argument types. A
few common ones are defined below. If the directive has a default value (i.e., if you
omit it from your configuration entirely, the Apache Web server
will behave as though you set it to a particular value), it is
described here. If there is no default value, this section
should say "None". Note that the default listed here
is not necessarily the same as the value the directive takes in
the default httpd.conf distributed with the server. This indicates where in the server's configuration files the
directive is legal. It's a comma-separated list of one or more
of the following values: The directive is only allowed within the designated
context; if you try to use it elsewhere, you'll get a
configuration error that will either prevent the server from
handling requests in that context correctly, or will keep the
server from operating at all -- i.e., the server won't
even start. The valid locations for the directive are actually the
result of a Boolean OR of all of the listed contexts. In other
words, a directive that is marked as being valid in
" This directive attribute indicates which configuration
override must be active in order for the directive to be
processed when it appears in a Overrides are activated by the This indicates how tightly bound into the Apache Web server
the directive is; in other words, you may need to recompile the
server with an enhanced set of modules in order to gain access
to the directive and its functionality. Possible values for
this attribute are: This quite simply lists the name of the source module which
defines the directive. If the directive wasn't part of the original Apache version
2 distribution, the version in which it was introduced should
be listed here. In addition, if the directive is available
only on certain platforms, it will be noted here. Apache HTTP Server Version 2.0
Each Apache directive available in the standard Apache
distribution is listed here. They are described using a
consistent format, and there is a dictionary of the terms used in their
descriptions available.
A Directive Quick-Reference
is also available giving details about each directive in a
summary form.
A | B | C | D | E | F | G | H | I | K | L | M | N | O | P | R | S | T | U | V | W | X Apache HTTP Server Version 2.0
Below is a list of all of the modules that come as part of
the Apache distribution. See also the complete
alphabetical list of all Apache
directives.
A | C | D | E | F | H | I | L | M | N | P | R | S | U | V Apache HTTP Server Version 2.0 This MPM is experimental, so it may or may not work
as expected. This is an experimental variant of the standard
To use the This MPM depends on APR's atomic compare-and-swap operations for
thread synchronization. If you are compiling for an x86 target
and you don't need to support 386s, or you are compiling for a
SPARC and you don't need to run on pre-UltraSPARC chips, add
Apache HTTP Server Version 2.0 The directives provided by Both host-based access restrictions and password-based
authentication may be implemented simultaneously. In that case,
the In general, access restriction directives apply to all
access methods ( The The first argument to this directive is always
Hosts whose names match, or end in, this string are allowed
access. Only complete components are matched, so the above
example will match An IP address of a host allowed access The first 1 to 3 bytes of an IP address, for subnet
restriction. A network a.b.c.d, and a netmask w.x.y.z. For more
fine-grained subnet restriction. Similar to the previous case, except the netmask consists of
nnn high-order 1 bits. Note that the last three examples above match exactly the
same set of hosts. IPv6 addresses and IPv6 subnets can be specified as shown
below: The third format of the arguments to the
In this case, browsers with a user-agent string beginning
with This directive allows access to the server to be restricted
based on hostname, IP address, or environment variables. The
arguments for the The Note that all Ordering is one of: Keywords may only be separated by a comma; no whitespace
is allowed between them. In the following example, all hosts in the apache.org domain
are allowed access; all other hosts are denied access. In the next example, all hosts in the apache.org domain are
allowed access, except for the hosts which are in the foo.apache.org
subdomain, who are denied access. All hosts not in the apache.org
domain are denied access because the default state is to On the other hand, if the The presence of an will The Apache HTTP Server Version 2.0 This module has two directives. The This directive adds an action, which will activate
cgi-script when action-type is triggered by the
request. The cgi-script is the URL-path to a resource
that has been designated as a CGI script using In the first example, requests for files with a MIME content
type of In the second example, requests for files with a file extension of
This directive adds an action, which will activate
cgi-script when a file is requested using the method of
method. The cgi-script is the URL-path to a
resource that has been designated as a CGI script using Note that the Script command defines default actions only.
If a CGI script is called, or some other resource that is
capable of handling the requested method internally, it will do
so. Also note that Script with a method of Apache HTTP Server Version 2.0 The directives contained in this module allow for manipulation
and control of URLs as requests arrive at the server. The
The Aliases and Redirects occuring in different contexts are processed
like other directives according to standard merging rules. But when multiple
Aliases or Redirects occur in the same context (for example, in the
same First, all Redirects are processed before Aliases are processed,
and therefore a request that matches a For this reason, when two or more of these directives apply to the
same sub-path, you must list the most specific path first in order for
all the directives to have an effect. For example, the following
configuration will work as expected: But if the above two directives were reversed in order, the
The A request for http://myserver/image/foo.gif would cause the
server to return the file /ftp/pub/image/foo.gif. Note that if you include a trailing / on the
url-path then the server will require a trailing / in
order to expand the alias. That is, if you use Note that you may need to specify additional In particular, if you are creating an This directive is equivalent to It is also possible to construct an alias with case-insensitive
matching of the url-path: The Redirect directive maps an old URL into a new one by asking
the client to refetch the resource at the new location. The old URL-path is a case-sensitive (%-decoded) path
beginning with a slash. A relative path is not allowed. The new
URL should be an absolute URL beginning with a scheme and
hostname, but a URL-path beginning with a slash may also be used,
in which case the scheme and hostname of the current server will
be added. If the client requests http://myserver/service/foo.txt, it
will be told to access http://foo2.bar.com/service/foo.txt
instead. Redirect directives take precedence over
Alias and ScriptAlias directives, irrespective of their ordering in
the configuration file. Also, URL-path must be a fully
qualified URL, not a relative path, even when used with .htaccess files or
inside of If no status argument is given, the redirect will
be "temporary" (HTTP status 302). This indicates to the client
that the resource has moved temporarily. The status
argument can be used to return other HTTP status codes: Other status codes can be returned by giving the numeric
status code as the value of status. If the status is
between 300 and 399, the URL argument must be present,
otherwise it must be omitted. Note that the status must be
known to the Apache code (see the function
This directive is equivalent to This directive makes the client know that the Redirect is
permanent (status 301). Exactly equivalent to This directive makes the client know that the Redirect is
only temporary (status 302). Exactly equivalent to
The A request for This directive is equivalent to Apache HTTP Server Version 2.0 This module provides the handler This can be used to send any kind of data from the server,
including redirects and other special HTTP responses, without
requiring a cgi-script or an nph script. For historical reasons, this module will also process any
file with the mime type This module provides no directives. In the server configuration file, associate files with the
The contents of any file with a Here's an example of a file whose contents are sent as
is so as to tell the client that a file has
redirected. The server always adds a Apache HTTP Server Version 2.0 This module allows the use of HTTP Basic Authentication to
restrict access by looking up users in plain text password and
group files. Similar functionality and greater scalability is
provided by Setting the So if a userID appears in the database of more than one module;
or if a valid A common use for this is in conjunction with one of the
database modules; such as By default control is not passed on and an unknown userID or
rule will result in an "Authentication Required" reply. Not setting
it thus keeps the system secure and forces an NCSA compliant
behaviour. Do consider the implications of allowing a user to allow
fall-through in his .htaccess file; and verify that this is really
what you want; Generally it is easier to just secure a single
.htpasswd file, than it is to secure a database such as mSQL.
Make sure that the The Each line of the group file contains a groupname followed by a
colon, followed by the member usernames separated by spaces. Note that searching large text files is very
inefficient; Make sure that the The Each line of the user file contains a username followed by
a colon, followed by the encrypted password. If the same user
ID is defined multiple times, The utility Create a password file Add or modify Note that searching large text files is very
inefficient; Make sure that the Apache HTTP Server Version 2.0 This module does access control in a manner similar to
anonymous-ftp sites; i.e. have a 'magic' user id
'anonymous' and the email address as a password. These email
addresses can be logged. Combined with other (database) access control methods, this
allows for effective user tracking and customization according
to a user profile while still keeping the site open for
'unregistered' users. One advantage of using Auth-based user
tracking is that, unlike magic-cookies and funny URL
pre/postfixes, it is completely browser independent and it
allows users to share URLs. The example below (when combined with the Auth directives of a
htpasswd-file based (or GDM, mSQL etc.) base access
control system allows users in as 'guests' with the following
properties: A list of one or more 'magic' userIDs which are allowed
access without password verification. The userIDs are space
separated. It is possible to use the ' and " quotes to allow a
space in a userID as well as the \ escape character. Please note that the comparison is
case-IN-sensitive. This would allow the user to enter without password
verification by using the userIDs "anonymous",
"AnonyMous", "Not Registered" and "I Don't Know". When set Be sure you know what you are doing when you decide to
switch it on. And remember that the order in which the Authentication
modules are queried is defined in the modules.c files at compile
time. When set Specifies whether the user must specify an email address as
the password. This prohibits blank passwords. When set When set Apache HTTP Server Version 2.0 This module provides for HTTP Basic Authentication, where
the usernames and passwords are stored in DBM type database
files. It is an alternative to the plain text password files
provided by Setting the So if a userID appears in the database of more than one module;
or if a valid A common use for this is in conjunction with one of the
basic auth modules; such as By default, control is not passed on and an unknown userID
or rule will result in an "Authentication Required" reply. Not
setting it thus keeps the system secure and forces an NCSA
compliant behaviour. Do consider the implications of allowing a user to allow
fall-through in his The The group file is keyed on the username. The value for a
user is a comma-separated list of the groups to which the users
belongs. There must be no whitespace within the value, and it
must never contain any colons. Security: make sure that the
Combining Group and Password DBM files: In some cases it is
easier to manage a single database which contains both the
password and group details for each user. This simplifies any
support programs that need to be written: they now only have to
deal with writing to and locking a single DBM file. This can be
accomplished by first setting the group and password files to
point to the same DBM: The key for the single DBM is the username. The value consists
of The password section contains the encrypted password as before.
This is followed by a colon and the comma separated list of groups.
Other data may optionally be left in the DBM file after another colon;
it is ignored by the authentication module. This is what
www.telescope.org uses for its combined password and group database. Sets the type of database file that is used to store the passwords.
The default database type is determined at compile time. The
availability of other types of database files also depends on
compile-time settings. It is crucial that whatever program you use to create your password
files is configured to use the same type of database. The The user file is keyed on the username. The value for a user is
the encrypted password, optionally followed by a colon and arbitrary
data. The colon and the data following it will be ignored by the
server. Make sure that the Important compatibility note: The implementation of
"dbmopen" in the apache modules reads the string length of the
hashed values from the DBM data structures, rather than relying
upon the string being NULL-appended. Some applications, such as
the Netscape web server, rely upon the string being
NULL-appended, so if you are having trouble using DBM files
interchangeably between applications this may be a part of the
problem. A perl script called
Apache HTTP Server Version 2.0 This module implements HTTP Digest Authentication. However, it
has not been extensively tested and is therefore marked
experimental. Using MD5 Digest authentication is very simple. Simply set
up authentication normally, using Appropriate user (text) files can be created using the
Digest authentication provides a more secure password system
than Basic authentication, but only works with supporting
browsers. As of November 2002, the major browsers that support digest
authentication are Opera, MS Internet
Explorer (fails when used with a query string - see "Working with MS Internet Explorer" below for a workaround), Amaya, Mozilla and Netscape since version 7. Since digest authentication is not
as widely implemented as basic authentication, you should use it only
in controlled environments. The Digest authentication implementation in previous Internet
Explorer for Windows versions (5 and 6) had issues, namely that
The first way is to use Since version 2.0.51 Apache also provides a workaround in the
This workaround is not necessary for MSIE 7, though enabling it does
not cause any compatibility issues or significant overhead. See the The The This directive should always be specified and
contain at least the (set of) root URI(s) for this space.
Omitting to do so will cause the client to send the
Authorization header for every request sent to this
server. Apart from increasing the size of the request, it may
also have a detrimental effect on performance if The URIs specified can also point to different servers, in
which case clients (which understand this) will then share
username/password info across multiple servers without
prompting the user each time. The The digest file uses a special format. Files in this format
can be created using the The Each line of the group file contains a groupname followed by
a colon, followed by the member usernames separated by spaces.
Example: Note that searching large text files is very
inefficient. Make sure that the The The The The size is normally expressed in Bytes, but you
may let the number follow a Apache HTTP Server Version 2.0 There are two phases in granting access to a user. The first
phase is authentication, in which During the authentication phase, The following directives are used during the search/bind
phase During the authorization phase, Apache's If this directive exists, The Because of the way that If the This directive specifies an LDAP group whose members are
allowed access. It takes the distinguished name of the LDAP
group. Note: Do not surround the group name with quotes.
For example, assume that the following entry existed in
the LDAP directory: The following directive would grant access to both Fred and
Barbara: Behavior of this directive is modified by the The The following directive would grant access to a specific
DN: Behavior of this directive is modified by the The The following directive would grant access to anyone with
the attribute employeeType = active Multiple attribute/value pairs can be specified on the same line
separated by spaces or they can be specified in multiple
The following directive would grant access to anyone with
the city attribute equal to "San Jose" or status equal to "Active" The next example demonstrates the power of using filters
to accomplish complicated administrative requirements.
Without filters, it would have been necessary to create a
new LDAP group and ensure that the group's members remain
synchronized with the pager users. This becomes trivial
with filters. The goal is to grant access to anyone who has
a filter, plus grant access to Joe Manager, who doesn't
have a pager, but does need to access the same
resource: This last may look confusing at first, so it helps to
evaluate what the search filter will look like based on who
connects, as shown below. The text in blue is the part that
is filled in using the attribute specified in the URL. The
text in red is the part that is filled in using the filter
specified in the URL. The text in green is filled in using
the information that is retrieved from the HTTP client. If
Fred User connects as The above search will only succeed if fuser has a
pager. When Joe Manager connects as jmanager, the
filter looks like The above search will succeed whether jmanager
has a pager or not. To use TLS, see the To use SSL, see the To specify a secure LDAP server, use ldaps:// in the
Normally, FrontPage uses FrontPage-web-specific user/group
files (i.e., the Once a FrontPage web has been created, adding LDAP
authentication to it is a matter of adding the following
directives to every FrontPage restricts access to a web by adding the Once directives have been added as specified above,
FrontPage users will be able to perform all management
operations from the FrontPage client. Set to An optional DN used to bind to the server when searching for
entries. If not provided, A bind password to use in conjunction with the bind DN. Note
that the bind password is probably sensitive data, and should be
properly protected. You should only use the The The file contains lines in the following format: The case of the extension does not matter. Blank lines, and lines
beginning with a hash character ( When set, This directive specifies when Set to See the section on using Microsoft
FrontPage with This directive specifies which LDAP attributes are used to
check for group membership. Multiple attributes can be used by
specifying this directive multiple times. If not specified,
then When set If this directive is set to on, the value of the
An RFC 2255 URL which specifies the LDAP search parameters
to use. The syntax of the URL is The name/port of the ldap server (defaults to
Once a connection has been made to a server, that
connection remains active for the life of the
If the LDAP server goes down and breaks an existing
connection, When doing searches, the attribute, filter and username passed
by the HTTP client are combined to create a search filter that
looks like
For example, consider an URL of
See above for examples of Apache HTTP Server Version 2.0 The index of a directory can come from one of two
sources: The two functions are separated so that you can completely
remove (or replace) automatic index generation should you want
to. Automatic index generation is enabled with using
If the Note that when the display is sorted by "Size", it's the
actual size of the files that's used, not the
displayed value - so a 1010-byte file will always be displayed
before a 1011-byte file (if in ascending order) even though
they both are shown as "1K". Apache 2.0.23 reorganized the Query Arguments for Column
Sorting, and introduced an entire group of new query options.
To effectively eliminate all client control over the output,
the The column sorting headers themselves are self-referencing
hyperlinks that add the sort query options shown below. Any
option below may be added to any request for the directory
resource. Note that the 'P'attern query argument is tested
after the usual The simple example below, which can be clipped and saved in
a header.html file, illustrates these query options. Note that
the unknown "X" argument, for the submit button, is listed last
to assure the arguments are all parsed before mod_autoindex
encounters the X=Go input. This sets the description to display for a file, for
The typical, default description field is 23 bytes wide. 6
more bytes are added by the See the DescriptionWidth Descriptive text defined with This sets the icon to display next to a file ending in
name for Name is either This sets the icon to display next to files with MIME-encoding is a wildcard expression matching
required the content-encoding. This sets the icon to display next to files of type
MIME-type for MIME-type is a wildcard expression matching
required the mime types. The The Both HeaderName and Filename must resolve to a document with a major
content type of Content negotiation
will be performed if If the file specified by The The If the number starts with a zero, then it is considered to
be a fraction: Apache 1.3.3 introduced some significant changes in the
handling of will be the equivalent of Whenever a '+' or '-' prefixed keyword is encountered, it
is applied to the current The net effect is equivalent to To unconditionally set the The You can force a directory listing to only be displayed in a
particular order by combining this directive with the The See also Apache HTTP Server Version 2.0 Content is stored in and retrieved from the cache using URI based keys. Content with
access protection is not cached. The The The In the event that the URL space overlaps between different
Ordinarily, if a request is cancelled while the response is being
cached and delivered to the client the processing of the response will
stop and the cache entry will be removed. The
The threshold is a percentage specified as a value between
Ordinarily, documents with no-cache or no-store header values will not be stored in the cache.
The According to RFC 2616, hop-by-hop HTTP headers are not stored in
the cache. The following HTTP headers are hop-by-hop headers and thus
do not get stored in the cache in any case regardless of the
setting of Ordinarily, documents without a last-modified date are not cached.
Under some circumstances the last-modified date is removed (during
In the event that a document does not provide an expiry date but does
provide a last-modified date, an expiry date can be calculated based on
the time since the document was last modified. The
The Apache HTTP Server Version 2.0 Emulate the CERN HTTPD Meta file semantics. Meta files are HTTP
headers that can be output in addition to the normal range of
headers for each file accessed. They appear rather like the
Apache .asis files, and are able to provide a crude way of
influencing the Expires: header, as well as providing other
curiosities. There are many ways to manage meta information,
this one was chosen because there is already a large number of
CERN users who can exploit this module. More information on the CERN metafile semantics is available. Specifies the name of the directory in which Apache can find
meta information files. The directory is usually a 'hidden'
subdirectory of the directory that contains the file being
accessed. Set to " Or, to set it to a subdirectory of the directory containing the
files: Turns on/off Meta file processing on a per-directory basis. Specifies the file name suffix for the file containing the
meta information. For example, the default values for the two
directives will cause a request to
Apache HTTP Server Version 2.0 Any file that has the mime type
When the server invokes a CGI script, it will add a variable
called For an introduction to using CGI scripts with Apache, see
our tutorial on Dynamic Content
With CGI. When using a multi-threaded MPM under unix, the module
The server will set the CGI environment variables as described
in the CGI
specification, with the following provisions: Debugging CGI scripts has traditionally been difficult, mainly
because it has not been possible to study the output (standard
output and error) for scripts which are failing to run
properly. These directives, included in Apache 1.2 and later,
provide more detailed logging of errors when they occur. When configured, the CGI error log logs any CGI which does not
execute properly. Each CGI script which fails to operate causes
several lines of information to be logged. The first two lines
are always of the format: If the error is that CGI script cannot be run, the log file
will contain an extra two lines: Alternatively, if the error is the result of the script
returning incorrect header information (often due to a bug in
the script), the following information is logged: (The %stdout and %stderr parts may be missing if the script did
not output anything on standard output or standard error). The This log will be opened as the user the child processes run
as, i.e. the user specified in the main Note that script logging is meant to be a debugging feature
when writing CGI scripts, and is not meant to be activated
continuously on running servers. It is not optimized for speed
or efficiency, and may have security problems if used in a
manner other than that for which it was designed. The size of any PUT or POST entity body that is logged to
the file is limited, to prevent the log file growing too big
too quickly if large bodies are being received. By default, up
to 1024 bytes are logged, but this can be changed with this
directive. Apache HTTP Server Version 2.0 Except for the optimizations and the additional On certain unix operating systems, forking a process from a
multi-threaded server is a very expensive operation because the
new process will replicate all the threads of the parent
process. In order to avoid incurring this expense on each CGI
invocation, This module is used by default instead of
This directive sets the name of the socket to use for
communication with the CGI daemon. The socket will be opened
using the permissions of the user who starts Apache (usually
root). To maintain the security of communications with CGI
scripts, it is important that no other user has permission to
write in the directory where the socket is located. Apache HTTP Server Version 2.0 This is an experimental module and should
be used with care. Experiment with your
This module provides a small subset of configuration
mechanisms implemented by Russian Apache and its associated
The character set name parameters of If the translation rules don't make sense for the content,
translation can fail in various ways, including: The The value of the charset argument must be accepted
as a valid character set name by the character set support in
APR. Generally, this means that it must be supported by
iconv. The The The value of the charset argument must be accepted
as a valid character set name by the character set support in
APR. Generally, this means that it must be supported by
iconv. The character set names in this example work with the iconv
translation support in Solaris 8. Apache HTTP Server Version 2.0 This module provides class 1 and class 2 WebDAV ('Web-based Distributed
Authoring and Versioning') functionality for Apache. This
extension to the HTTP protocol allows creating, moving,
copying, and deleting resources and collections on a remote web
server. To enable This enables the DAV file system provider, which is implemented
by the In addition, a location for the DAV lock database must be
specified in the global section of your The directory containing the lock database file must be
writable by the You may wish to add a Since DAV access methods allow remote clients to manipulate
files on the server, you must take particular care to assure that
your server is secure before enabling Any location on the server where DAV is enabled should be
protected by authentication. The use of HTTP Basic Authentication
is not recommended. You should use at least HTTP Digest
Authentication, which is provided by the
In order for One common request is to use With this setup, Use the The value Use the When a client requests a DAV resource lock, it can also
specify a time when the lock will be automatically removed by
the server. This value is only a request, and the server can
ignore it or inform the client of an arbitrary value. Use the Apache HTTP Server Version 2.0 This module requires the service of Since Use the The directory containing the lock database file must be
writable by the Apache HTTP Server Version 2.0 The This is a simple sample configuration for the impatient. The following configuration, while resulting in more compressed content,
is also much more complicated. Do not use this unless you fully understand
all the configuration details. Compression is implemented by the Some popular browsers cannot handle compression of all content
so you may want to set the If you want to restrict the compression to particular MIME types
in general, you may use the For browsers that have problems even with compression of all file
types, use the At first we probe for a The third The Now if a request contains a If you evaluate the request body yourself, don't trust
the The If you use some special exclusions dependent
on, for example, the If your decision about compression depends on other information
than request headers (e.g. HTTP version), you have to set the
The The The value must between 1 (less compression) and 9 (more compression). The If you want to extract more accurate values from your logs, you
can use the type argument to specify the type of data
left as note for logging. type can be one of: Thus you may log it this way: The The Apache HTTP Server Version 2.0 The index of a directory can come from one of two sources: The two functions are separated so that you can completely
remove (or replace) automatic index generation should you want
to. A "trailing slash" redirect is issued when the server
receives a request for a URL
The then a request for Note that the documents do not need to be relative to the
directory; would cause the CGI script The Typically if a user requests a resource without a trailing slash, which
points to a directory, Well, if you don't want this effect and the reasons above don't
apply to you, you can turn off the redirect with: Turning off the trailing slash redirect may result in an information
disclosure. Consider a situation where Apache HTTP Server Version 2.0 Content is stored in and retrieved from the cache using URI based
keys. Content with access protection is not cached. The The result of The The result of More detail will be added here, when the function is implemented. More detail will be added here, when the function is implemented. More detail will be added here, when the function is implemented. The More detail will be added here, when the function is implemented. More detail will be added here, when the function is implemented. More detail will be added here, when the function is implemented. The The The The More detail will be added here, when the function is implemented. Apache HTTP Server Version 2.0 The data logging is done right after SSL decoding (for
input) and right before SSL encoding (for output). As can
be expected, this can produce extreme volumes of data,
and should only be used when debugging problems. To enable the module, it should be compiled and
loaded in to your running Apache configuration. Logging
can then be enabled or disabled via the below directives. In order for dumping to work Enable dumping of all input. Enable dumping of all output. Apache HTTP Server Version 2.0 This module provides an example protocol module to illustrate the
concept. It provides a simple echo server. Telnet to it and type
stuff, and it will echo it. The Apache HTTP Server Version 2.0 This module allows for control of the environment that will
be provided to CGI scripts and SSI pages. Environment variables
may be passed from the shell which invoked the Specifies one or more environment variables to pass to CGI
scripts and SSI pages from the environment of the shell which
invoked the Sets an environment variable, which is then passed on to CGI
scripts and SSI pages. Removes one or more environment variables from those passed
on to CGI scripts and SSI pages. Apache HTTP Server Version 2.0 The files in the The main file is The example module is an actual working module. If you link
it into your server, enable the "example-handler" handler for a
location, and then browse to that location, you will see a
display of some of the tracing the example module did as the
various callbacks were made. To include the example module in your server, follow the
steps below: To add another module of your own: To activate the example module, include a block similar to
the following in your As an alternative, you can put the following into a After reloading/restarting your server, you should be able
to browse to this location and see the brief display mentioned
earlier. The Apache HTTP Server Version 2.0 This module controls the setting of the These HTTP headers are an instruction to the client about the
document's validity and persistence. If cached, the document may
be fetched from the cache rather than from the source until this
time has passed. After that, the cache copy is considered
"expired" and invalid, and a new copy must be obtained from the
source. To modify The where <base> is one of: The For example, any of the following directives can be used to
make documents expire 1 month after being accessed, by
default: The expiry time can be fine-tuned by adding several
'<num> <type>' clauses: Note that if you use a modification date based setting, the
Expires header will not be added to content
that does not come from a file on disk. This is due to the fact
that there is no modification time for such content. This directive enables or disables the generation of the
Note that this directive does not guarantee that an
This directive defines the value of the The base time is either the last modification time of the
file, or the time of the client's access to the document. Which
should be used is specified by the
The difference in effect is subtle. If Note that this directive only has effect if
You can also specify the expiration time calculation using
an alternate syntax, described earlier in
this document. This directive sets the default algorithm for calculating the
expiration time for all documents in the affected realm. It can be
overridden on a type-by-type basis by the Apache HTTP Server Version 2.0 Even when the performance characteristics are not suitable
for production use, Note: this gzip example is just for the purposes of illustration.
Please refer to The filtername specifies the name of the filter being
defined. This name can then be used in SetOutputFilter
directives. It must be unique among all registered filters.
At the present time, no error is reported by the
register-filter API, so a problem with duplicate names isn't
reported to the user. Subsequent parameters can appear in any order and define the
external command to run and certain other characteristics. The
only required parameter is The Note: The core directive Messages written to the filter's standard error will be stored
in the Apache error log. No debug messages will be generated by
Apache HTTP Server Version 2.0 Caching frequently requested files that change very
infrequently is a technique for reducing server load.
Notice: You cannot use this for speeding up CGI programs or
other files which are served by special content handlers. It
can only be used for regular files which are usually served by
the Apache core content handler. This module is an extension of and borrows heavily from the
Not all platforms support both directives. For example, Apache
on Windows does not currently support the The This The This file handle caching is done once at server start or
restart, only. So whenever one of the cached files changes on
the filesystem you have to restart the server (see the
Stopping and Restarting
documentation). To reiterate that point: if the files are
modified in place without restarting the server you
may end up serving requests that are completely bogus. You
should update files by unlinking the old copy and putting a new
copy in place. Most tools such as Don't bother asking for a directive which recursively
caches all the files in a directory. Try this instead... See the
The Be careful with the file-path arguments: They have
to literally match the filesystem path Apache's URL-to-filename
translation handlers create. We cannot compare inodes or other
stuff to match paths through symbolic links etc.
because that again would cost extra The Be careful with the file-path arguments: They have
to literally match the filesystem path Apache's URL-to-filename
translation handlers create. We cannot compare inodes or other
stuff to match paths through symbolic links etc.
because that again would cost extra Apache HTTP Server Version 2.0 This module provides directives to control and modify HTTP
request and response headers. Headers can be merged, replaced
or removed. The directives provided by The directives are processed in the following order: Order is important. These two headers have a different
effect if reversed: This way round, the results in this header being added to the response: results in this header being added to the response: If the header This directive can replace, merge or remove HTTP response
headers. The header is modified just after the content handler
and output filters are run, allowing outgoing headers to be
modified. The optional condition can be either The action it performs is determined by the second
argument. This can be one of the following values: This argument is followed by a header name, which
can include the final colon, but it is not required. Case is
ignored for For When the The This directive can replace, merge or remove HTTP request
headers. The header is modified just before the content handler
is run, allowing incoming headers to be modified. The action it
performs is determined by the first argument. This can be one
of the following values: This argument is followed by a header name, which can
include the final colon, but it is not required. Case is
ignored. For When the The Apache HTTP Server Version 2.0 This module processes The following directive will activate files ending with
Note that the following is still supported: However, we are trying to phase out "magic MIME types" so we
are deprecating this method. The imagemap module adds some new features that were not
possible with previously distributed imagemap programs. The lines in the imagemap files can have one of several
formats: The directive is one of There are six directives allowed in the imagemap file. The
directives can come in any order, but are processed in the
order they are found in the imagemap file. Has the effect of The values for each of the directives can any of the following: The URL can be relative or absolute URL. Relative URLs
can contain '..' syntax and will be resolved relative to the
After the value or after the coordinates, the line
optionally may contain text within double quotes. This string
is used as the text for the link if a menu is
generated: If no quoted text is present, the name of the link will be
used as the text: If you want to use double quotes within this text, you have to
write them as The The The Apache HTTP Server Version 2.0 This module provides a filter which will process files
before they are sent to the client. The processing is
controlled by specially formatted SGML comments, referred to as
elements. These elements allow conditional text, the
inclusion of other files or programs, as well as the setting and
printing of environment variables. Server Side Includes are implemented by the
The following directive must be given for the directories
containing the shtml files (typically in a
For backwards compatibility, the For more information, see our Tutorial on Server Side Includes. Files processed for server-side includes no longer accept
requests with The document is parsed as an HTML document, with special
commands embedded as SGML comments. A command has the syntax: The value will often be enclosed in double quotes, but single
quotes ( The allowed elements are listed in the following table: SSI elements may be defined by modules other than
This command controls various aspects of the parsing. The
valid attributes are: This command prints one of the include
variables, defined below. If the variable is unset, the result is
determined by the Attributes: Specifies how Apache should encode special characters
contained in the variable before outputting them. If set
to The The The value specifies a (%-encoded) URL-path to
the CGI script. If the path does not begin with a slash (/),
then it is taken to be relative to the current
document. The document referenced by this path is
invoked as a CGI script, even if the server would not
normally recognize it as such. However, the directory
containing the script must be enabled for CGI scripts
(with The CGI script is given the If the script returns a The The server will execute the given string using
The use of In addition, on some platforms, like Win32, and on unix when
using suexec, you cannot pass arguments
to a command in an This command prints the size of the specified file, subject
to the This command prints the last modification date of the
specified file, subject to the This command inserts the text of another document or file
into the parsed file. Any included file is subject to the
usual access control. If the directory containing the
parsed file has Options
An attribute defines the location of the document; the
inclusion is done for each attribute given to the include
command. The valid attributes are: The value is a (%-encoded) URL-path. The URL cannot contain a
scheme or hostname, only a path and an optional query string. If it
does not begin with a slash (/) then it is taken to be relative to the
current document. A URL is constructed from the attribute, and the output the
server would return if the URL were accessed by the client is
included in the parsed output. Thus included files can be nested. If the specified URL is a CGI program, the program will be
executed and its output inserted in place of the directive in the
parsed file. You may include a query string in a CGI url: This prints out a listing of all existing variables and
their values. Special characters are entity encoded (see the This sets the value of a variable. Attributes: In addition to the variables in the standard CGI environment,
these are available for the Variable substitution is done within quoted strings in most
cases where they may reasonably occur as an argument to an SSI
directive. This includes the If a variable reference needs to be substituted in the
middle of a character sequence that might otherwise be
considered a valid identifier in its own right, it can be
disambiguated by enclosing the reference in braces,
a la shell substitution: This will result in the The below example will print "in foo" if the
The basic flow control elements are: The The The test_condition is one of the following: Compare string1 with string2. If
string2 has the form If you are matching positive ( " The boolean operators Anything that's not recognized as a variable or an operator
is treated as a string. Strings can also be quoted:
This directive changes the string that The This directive has the same effect as the This directive changes the string that You may want to use this option if you have 2 servers parsing the
output of a file each processing different commands (possibly at
different times). The example given above, which also specifies a matching
This directive changes the format in which date strings are displayed
when echoing This directive has the same effect as the The above directive would cause times to be displayed in the
format "22:26, June 14, 2002". This directive changes the string that The You would not want to use the full option, unless you assure the
group-execute bit is unset for every SSI script which might Apache HTTP Server Version 2.0 To configure You may wish to use Once configured, the server information is obtained by
accessing It should also be noted that if
In particular, this module can leak sensitive information
from the configuration directives of other Apache modules such as
system paths, usernames/passwords, database names, etc. Due to
the way this module works there is no way to block information
from it. Therefore, this module should only be
used in a controlled environment and always with caution. This allows the content of string to be shown as
HTML interpreted, Additional Information for
the module module-name. Example: Apache HTTP Server Version 2.0 This module implements the Internet Server extension API. It
allows Internet Server extensions (e.g. ISAPI .dll
modules) to be served by Apache for Windows, subject to the
noted restrictions. ISAPI extension modules (.dll files) are written by third
parties. The Apache Group does not author these modules, so we
provide no support for them. Please contact the ISAPI's author
directly if you are experiencing problems running their ISAPI
extension. Please do not post such problems to
Apache's lists or bug reporting pages. In the server configuration file, use
the There is no capability within the Apache server to leave a
requested module loaded. However, you may preload and keep a
specific module loaded by using the following syntax in your
httpd.conf: Whether or not you have preloaded an ISAPI extension, all
ISAPI extensions are governed by the same permissions and
restrictions as CGI scripts. That is, Review the Additional Notes and the Programmer's Journal for additional details
and clarification of the specific ISAPI support offered by
Apache's ISAPI implementation conforms to all of the ISAPI
2.0 specification, except for some "Microsoft-specific"
extensions dealing with asynchronous I/O. Apache's I/O model
does not allow asynchronous reading and writing in a manner
that the ISAPI could access. If an ISA tries to access
unsupported features, including async I/O, a message is placed
in the error log to help with debugging. Since these messages
can become a flood, the directive Some servers, like Microsoft IIS, load the ISAPI extension
into the server and keep it loaded until memory usage is too
high, or unless configuration options are specified. Apache
currently loads and unloads the ISAPI extension each time it is
requested, unless the Also, remember that while Apache supports ISAPI Extensions,
it does not support ISAPI Filters. Support for
filters may be added at a later date, but no support is planned
at this time. If you are programming Apache 2.0 In their recent documentation, Microsoft appears to have
abandoned the distinction between the two
The first option, the Apache returns Apache 2.0 Record Record Specifies a space-separated list of file names to be loaded
when the Apache server is launched, and remain loaded until the
server is shut down. This directive may be repeated for every
ISAPI .dll file desired. The full path name of each file should
be specified. If the path name is not absolute, it will be treated
relative to While set to on, asynchronous support for ISAPI callbacks is
simulated. Logs all requests for unsupported features from ISAPI
extensions in the server error log. This may help administrators
to track down problems. Once set to on and all desired ISAPI modules
are functioning, it should be set back to off. Defines the maximum size of the Read Ahead Buffer sent to
ISAPI extensions when they are initially invoked. All remaining
data must be retrieved using the Apache HTTP Server Version 2.0 This module was created to improve the performance of
websites relying on backend connections to LDAP servers. In
addition to the functions provided by the standard LDAP
libraries, this module adds an LDAP connection pool and an LDAP
shared memory cache. To enable this module, LDAP support must be compiled into
apr-util. This is achieved by adding the SSL support requires that The following is an example configuration that uses
LDAP connections are pooled from request to request. This
allows the LDAP server to remain connected and bound ready for
the next request, without the need to unbind/connect/rebind.
The performance advantages are similar to the effect of HTTP
keepalives. On a busy server it is possible that many requests will try
and access the same LDAP server connection simultaneously.
Where an LDAP connection is in use, Apache will create a new
connection alongside the original one. This ensures that the
connection pool does not become a bottleneck. There is no need to manually enable connection pooling in
the Apache configuration. Any module using this module for
access to LDAP services will share the connection pool. For improved performance, The process of doing a search and then a bind is the
most time-consuming aspect of LDAP operation, especially if
the directory is large. The search/bind cache is used to
cache all searches that resulted in successful binds.
Negative results (i.e., unsuccessful searches, or searches
that did not result in a successful bind) are not cached.
The rationale behind this decision is that connections with
invalid credentials are only a tiny percentage of the total
number of connections, so by not caching invalid
credentials, the size of the cache is reduced. The search and bind cache is controlled with the During attribute and distinguished name comparison
functions, The behavior of both of these caches is controlled with
the By fetching the URL The ability to create an SSL connections to an LDAP server
is defined by the directives If Specifies the maximum size of the primary LDAP cache. This
cache contains successful search/binds. Set it to 0 to turn off
search/bind caching. The default size is 1024 cached
searches. Specifies the time (in seconds) that an item in the
search/bind cache remains valid. The default is 600 seconds (10
minutes). Specifies the timeout value (in seconds) in which the module will
attempt to connect to the LDAP server. If a connection is not
successful with the timeout period, either an error will be
returned or the module will attempt to connect to a secondary LDAP
server if one is specified. The default is 10 seconds. This specifies the number of entries Specifies the time (in seconds) that entries in the
operation cache remain valid. The default is 600 seconds. Specifies the directory path and file name of the shared memory
cache file. If not set, anonymous shared memory will be used if the
platform supports it. Specifies the number of bytes to allocate for the shared
memory cache. The default is 100kb. If set to 0, shared memory
caching will not be used. It specifies the directory path and file name of the trusted CA
The following types are supported: Apache HTTP Server Version 2.0 This module provides for flexible logging of client
requests. Logs are written in a customizable format, and may be
written directly to a file, or to an external program.
Conditional logging is provided so that individual requests may
be included or excluded from the logs based on characteristics
of the request. Three directives are provided by this module:
The format argument to the The characteristics of the request itself are logged by
placing " (This directive was The "..." can be nothing at all (e.g.,
The modifiers "<" and ">" can be used for requests that
have been internally redirected to choose whether the original or
final (respectively) request should be consulted. By default, the
Note that in httpd 2.0 versions prior to 2.0.46, no escaping was performed
on the strings from For security reasons, starting with 2.0.46, non-printable and
other special characters are escaped mostly by using
Note that in httpd 2.0, unlike 1.3, the Some commonly used log format strings are: Note that the canonical See the security tips
document for details on why your security could be compromised
if the directory where logfiles are stored is writable by
anyone other than the user that starts the server. The The The The first argument, which specifies the location to which
the logs will be written, can take one of the following two
types of values: If a program is used, then it will be run as the user who
started When entering a file path on non-Unix platforms, care should be taken
to make sure that only forward slashed are used even though the platform
may allow the use of back slashes. In general it is a good idea to always
use forward slashes throughout the configuration files. The second argument specifies what will be written to the
log file. It can specify either a nickname defined by
a previous For example, the following two sets of directives have
exactly the same effect: The third argument is optional and controls whether or
not to log a particular request based on the
presence or absence of a particular variable in the server
environment. If the specified environment
variable is set for the request (or is not set, in the case
of a ' Environment variables can be set on a per-request
basis using the Or, to reproduce the behavior of the old RefererIgnore
directive, you might use the following: This directive specifies the format of the access log
file. The The second form of the This directive has exactly the same arguments and effect as
the Apache HTTP Server Version 2.0 This module provides for forensic logging of client
requests. Logging is done before and after processing a request, so the
forensic log contains two log lines for each request.
The forensic logger is very strict, which means: The Each request is logged two times. The first time is before it's
processed further (that is, after receiving the headers). The second log
entry is written after the request processing at the same time
where normal logging occurs. In order to identify each request, a unique request ID is assigned.
This forensic ID can be cross logged in the normal transfer log using the
The first line logs the forensic ID, the request line and all received
headers, separated by pipe characters ( The plus character at the beginning indicates that this is the first log
line of this request. The second line just contains a minus character and
the ID again: The See the security tips
document for details on why your security could be compromised
if the directory where logfiles are stored is writable by
anyone other than the user that starts the server. The The argument, which specifies the location to which
the logs will be written, can take one of the following two
types of values: If a program is used, then it will be run as the user who
started When entering a file path on non-Unix platforms, care should be taken
to make sure that only forward slashed are used even though the platform
may allow the use of back slashes. In general it is a good idea to always
use forward slashes throughout the configuration files. Apache HTTP Server Version 2.0 This module provides the logging of input and output number of
bytes received/sent per request. The numbers reflect the actual bytes
as received on the network, which then takes into account the
headers and bodies of requests and responses. The counting is done
before SSL/TLS on input and after SSL/TLS on output, so the numbers
will correctly reflect any changes made by encryption. This module requires This module provides no directives. This modules adds two new logging directives. The characteristics of the
request itself are logged by placing " Usually, the functionality is used like this: Apache HTTP Server Version 2.0 This module requires the service of Content is stored in and retrieved from the cache using URI based
keys. Content with access protection is not cached. The The The value of The Using a nonzero value for The The The The Apache HTTP Server Version 2.0 This module is used to associate various bits of "meta
information" with files by their filename extensions. This
information relates the filename of the document to it's
mime-type, language, character set and encoding. This
information is sent to the browser, and participates in content
negotiation, so the user's preferences are respected when
choosing one of several possible files to serve. See
The directives In addition, While Note that changing the meta-information for a file does not
change the value of the Files can have more than one extension, and the order of the
extensions is normally irrelevant. For example, if the
file Languages and content encodings are treated accumulative, because one can assign
more than one language or encoding to a particular resource. For example,
the file Care should be taken when a file with multiple extensions
gets associated with both a MIME-type and a handler. This will
usually result in the request being by the module associated
with the handler. For example, if the A file of a particular MIME type can additionally be encoded a
particular way to simplify transmission over the Internet.
While this usually will refer to compression, such as
The HTTP/1.1
RFC, section 14.11 puts it this way: The Content-Encoding entity-header field is used as a modifier to
the media-type. When present, its value indicates what additional
content codings have been applied to the entity-body, and thus what
decoding mechanisms must be applied in order to obtain the media-type
referenced by the Content-Type header field. Content-Encoding is
primarily used to allow a document to be compressed without losing
the identity of its underlying media type. By using more than one file extension (see section above about multiple file
extensions), you can indicate that a file is of a
particular type, and also has a particular
encoding. For example, you may have a file which is a Microsoft Word
document, which is pkzipped to reduce its size. If the
Apache sends a In addition to file type and the file encoding,
another important piece of information is what language a
particular document is in, and in what character set the file
should be displayed. For example, the document might be written
in the Vietnamese alphabet, or in Cyrillic, and should be
displayed as such. This information, also, is transmitted in
HTTP headers. The character set, language, encoding and mime type are all
used in the process of content negotiation (See
To convey this further information, Apache optionally sends
a The language specification is the two-letter abbreviation
for the language. The The Then the document The extension argument is case-insensitive, and can
be specified with or without a leading dot. The This will cause filenames containing the Old clients expect The extension argument is case-insensitive, and can
be specified with or without a leading dot. Files having the name extension will be served by the
specified handler-name. This
mapping is added to any already in force, overriding any mappings that
already exist for the same extension. For example, to
activate CGI scripts with the file extension Once that has been put into your httpd.conf file, any file containing
the The extension argument is case-insensitive, and can
be specified with or without a leading dot. If more than one filter is specified, they must be separated
by semicolons in the order in which they should process the
content. Both the filter and extension arguments are
case-insensitive, and the extension may be specified with or
without a leading dot. The Then the document If multiple language assignments are made for the same
extension, the last one encountered is the one that is used.
That is, for the case of: documents with the extension The extension argument is case-insensitive, and can
be specified with or without a leading dot. The For example, the following configuration will process all
If more than one filter is specified, they must be separated
by semicolons in the order in which they should process the
content. Both the filter and extension arguments
are case-insensitive, and the extension may be specified with or
without a leading dot. The The extension argument is case-insensitive, and can
be specified with or without a leading dot. The If no The This directive is recommended when you have a virtual filesystem. If you have a request for The To include extensions associated with Handlers and/or Filters,
set the You may finally allow For example, the following configuration will allow handlers
and filters to participate in Multviews, but will exclude unknown
files: The The extension argument is case-insensitive, and can
be specified with or without a leading dot. The This will cause The extension argument is case-insensitive, and can
be specified with or without a leading dot. The This has the effect of returning The extension argument is case-insensitive, and can
be specified with or without a leading dot. The The extension argument is case-insensitive, and can
be specified with or without a leading dot. The The extension argument is case-insensitive, and can
be specified with or without a leading dot. The The extension argument is case-insensitive, and can
be specified with or without a leading dot. The This will remove any special handling of The extension argument is case-insensitive, and can
be specified with or without a leading dot. The The file contains lines in the format of the arguments to
an The case of the extension does not matter. Blank lines, and lines
beginning with a hash character ( Apache HTTP Server Version 2.0 This module determines the MIME type of files in the same
way the Unix This module is derived from a free version of the
The contents of the file are plain ASCII text in 4-5
columns. Blank lines are allowed but ignored. Commented lines
use a hash mark ( type of data to match For example, the following magic file lines would recognize
some audio formats: Or these would recognize the difference between An optional MIME encoding can be included as a fifth column.
For example, this can recognize gzipped files and set the
encoding for them. This module is not for every system. If your system is barely
keeping up with its load or if you're performing a web server
benchmark, you may not want to enable this because the
processing is not free. However, an effort was made to improve the performance of
the original The following notes apply to the mod_mime_magic: MIME type lookup via file magic numbers This software was submitted by Cisco Systems to the Apache Group
in July 1997. Future revisions and derivatives of this source code
must acknowledge Cisco Systems as the original contributor of this
module. All other licensing and usage conditions are those of the
Apache Group. Some of this code is derived from the free version of the file
command originally posted to comp.sources.unix. Copyright info for
that program is included below as required. - Copyright (c) Ian F. Darwin, 1987. Written by Ian F. Darwin. This software is not subject to any license of the American
Telephone and Telegraph Company or of the Regents of the University
of California. Permission is granted to anyone to use this software for any
purpose on any computer system, and to alter it and redistribute it
freely, subject to the following restrictions: For compliance with Mr Darwin's terms: this has been very
significantly modified from the free "file" command. The Apache HTTP Server Version 2.0 Content negotiation, or more accurately content selection, is
the selection of the document that best matches the clients
capabilities, from one of several available documents. There
are two implementations of this. A type map has a format similar to RFC822 mail headers. It
contains document descriptions separated by blank lines, with
lines beginning with a hash character ('#') treated as
comments. A document description consists of several header
records; records may be continued on multiple lines if the
continuation lines start with spaces. The leading space will be
deleted and the lines concatenated. A header record consists of
a keyword name, which always ends in a colon, followed by a
value. Whitespace is allowed between the header name and value,
and between the tokens of value. The headers allowed are: A MultiViews search is enabled by the The If set, this directive allows content-negotiated documents
to be cached by proxy servers. This could mean that clients
behind those proxys could retrieve versions of the documents
that are not the best match for their abilities, but it will
make caching more efficient. This directive only applies to requests which come from
HTTP/1.0 browsers. HTTP/1.1 provides much better control over
the caching of negotiated documents, and this directive has no
effect in responses to HTTP/1.1 requests. Prior to version 2.0,
The Both options, The For a request for Note that this directive only has an effect if a 'best'
language cannot be determined by any other means or the Apache HTTP Server Version 2.0 This module enables SSL encryption for a specified port. It
takes advantage of the SSL encryption functionality that is
built into the NetWare operating system. Specifies a list of client certificate files (DER format)
that are used when creating a proxied SSL connection. Each
client certificate used by a server must be listed separately
in its own Allow a connection that was created on the specified address
and/or port to be upgraded to an SSL connection upon request from
the client. The address and/or port must have already be defined
previously with a Specifies the port and the eDirectory based certificate name
that will be used to enable SSL encryption. An optional third
parameter also enables mutual authentication. Apache HTTP Server Version 2.0 Do not enable proxying with This module implements a proxy/gateway for Apache. It implements
proxying capability for Apache's proxy features are divided into several modules in
addition to In addition, extended features are provided by other modules.
Caching is provided by Apache can be configured in both a forward and
reverse proxy mode. An ordinary forward proxy is an intermediate
server that sits between the client and the origin
server. In order to get content from the origin server,
the client sends a request to the proxy naming the origin server
as the target and the proxy then requests the content from the
origin server and returns it to the client. The client must be
specially configured to use the forward proxy to access other
sites. A typical usage of a forward proxy is to provide Internet
access to internal clients that are otherwise restricted by a
firewall. The forward proxy can also use caching (as provided
by The forward proxy is activated using the A reverse proxy, by contrast, appears to the
client just like an ordinary web server. No special
configuration on the client is necessary. The client makes
ordinary requests for content in the name-space of the reverse
proxy. The reverse proxy then decides where to send those
requests, and returns the content as if it was itself the
origin. A typical usage of a reverse proxy is to provide Internet
users access to a server that is behind a firewall. Reverse
proxies can also be used to balance load among several back-end
servers, or to provide caching for a slower back-end server.
In addition, reverse proxies can be used simply to bring
several servers into the same URL space. A reverse proxy is activated using the The examples below are only a very basic idea to help you
get started. Please read the documentation on the individual
directives. In addition, if you wish to have caching enabled, consult
the documentation from You can control who can access your proxy via the For more information on access control directives, see
Strictly limiting access is essential if you are using a
forward proxy (using the You probably don't have that particular file type defined as
In the rare situation where you must download a specific file using the
FTP An FTP URI is interpreted relative to the home directory of the user
who is logging in. Alas, to reach higher directory levels you cannot
use /../, as the dots are interpreted by the browser and not actually
sent to the FTP server. To address this problem, the so called Squid
%2f hack was implemented in the Apache FTP proxy; it is a
solution which is also used by other popular proxy servers like the Squid Proxy Cache. By
prepending To log in to an FTP server by username and password, Apache uses
different strategies. In absense of a user name and password in the URL
altogether, Apache sends an anonymous login to the FTP server,
i.e., This works for all popular FTP servers which are configured for
anonymous access. For a personal login with a specific username, you can embed the user
name into the URL, like in: If the FTP server asks for a password when given this username (which
it should), then Apache will reply with a in the first place). The password which is transmitted in such a way is not encrypted on
its way. It travels between your browser and the Apache proxy server in
a base64-encoded cleartext string, and between the Apache proxy and the
FTP server as plaintext. You should therefore think twice before
accessing your FTP server via HTTP (or before accessing your personal
files via FTP at all!) When using unsecure channels, an eavesdropper
might intercept your password on its way. If you're using the An Apache proxy server situated in an intranet needs to forward
external requests through the company's firewall (for this, configure
the Users within an intranet tend to omit the local domain name from their
WWW requests, thus requesting "http://somehost/" instead of
For circumstances where you have a application server which doesn't
implement keepalives or HTTP/1.1 properly, there are 2 environment
variables which when set send a HTTP/1.0 with no keepalive. These are set
via the These are the The By default, only the default https port ( Note that you'll need to have This directive is only useful for Apache proxy servers within
intranets. The The host arguments to the A Domain is a partially qualified DNS domain name, preceded
by a period. It represents a list of hosts which logically belong to the
same DNS domain or zone (i.e., the suffixes of the hostnames are
all ending in Domain). To distinguish Domains from Hostnames (both syntactically and semantically; a DNS domain can
have a DNS A record, too!), Domains are always written with a
leading period. Domain name comparisons are done without regard to the case, and
Domains are always assumed to be anchored in the root of the
DNS tree, therefore two domains A SubNet is a partially qualified internet address in
numeric (dotted quad) form, optionally followed by a slash and the netmask,
specified as the number of significant bits in the SubNet. It is
used to represent a subnet of hosts which can be reached over a common
network interface. In the absence of the explicit net mask it is assumed
that omitted (or zero valued) trailing digits specify the mask. (In this
case, the netmask can only be multiples of 8 bits wide.) Examples: As a degenerate case, a SubNet with 32 valid bits is the
equivalent to an IPAddr, while a SubNet with zero
valid bits (e.g., 0.0.0.0/0) is the same as the constant
_Default_, matching any IP address. A IPAddr represents a fully qualified internet address in
numeric (dotted quad) form. Usually, this address represents a host, but
there need not necessarily be a DNS domain name connected with the
address. An IPAddr does not need to be resolved by the DNS system, so
it can result in more effective apache performance. A Hostname is a fully qualified DNS domain name which can
be resolved to one or more IPAddrs via the
DNS domain name service. It represents a logical host (in contrast to
Domains, see above) and must be resolvable
to at least one IPAddr (or often to a list
of hosts with different IPAddrs). In many situations, it is more effective to specify an IPAddr in place of a Hostname since a
DNS lookup can be avoided. Name resolution in Apache can take a remarkable
deal of time when the connection to the name server uses a slow PPP
link. Hostname comparisons are done without regard to the case,
and Hostnames are always assumed to be anchored in the root
of the DNS tree, therefore two hosts Directives placed in For example, the following will allow only hosts in
The following example will process all files in the The The Note that Note also that blocks connections to all sites. This directive is only useful for Apache proxy servers within
intranets. The This directive is useful for reverse-proxy setups, where you want to
have a common look and feel on the error pages seen by the end user.
This also allows for included files (via mod_include's SSI) to get
the error code and act accordingly (default behavior would display
the error page of the proxied server, turning this on shows the SSI
Error message). The The In almost every case there's no reason to change that value. The The This directive allows remote servers to be mapped into the space of
the local server; the local server does not act as a proxy in the
conventional sense, but appears to be a mirror of the remote
server. path is the name of a local virtual path; url
is a partial URL for the remote server and cannot include a query
string. Suppose the local server has address will cause a local request for
The will proxy all requests to Order is important. you need to put the exclusions before the
general proxypass directive. When used inside a If you require a more flexible reverse-proxy configuration, see the
This directive lets Apache adjust the URL in the Only the HTTP response headers specifically mentioned above
will be rewritten. Apache will not rewrite other response
headers, nor will it rewrite URL references inside HTML pages.
This means that if the proxied content contains absolute URL
references, they will by-pass the proxy. A third-party module
that will look inside the HTML and rewrite URL references is Nick
Kew's mod_proxy_html. path is the name of a local virtual path. url is a
partial URL for the remote server - the same way they are used for the
For example, suppose the local server has address
will not only cause a local request for the
Note that this When used inside a When enabled, this option will pass the Host: line from the incoming
request to the proxied host, instead of the hostname specified in the
proxypass line. This option should normally be turned The This defines remote proxies to this proxy. match is either the
name of a URL-scheme that the remote server supports, or a partial URL
for which the remote server should be used, or scheme is effectively the protocol that should be used to
communicate with the remote server; only In the last example, the proxy will forward FTP requests, encapsulated
as yet another HTTP proxy request, to another proxy which can handle
them. This option also supports reverse proxy configuration - a backend
webserver can be embedded within a virtualhost URL space even if that
server is hidden by another forward proxy. The This allows or prevents Apache from functioning as a forward proxy
server. (Setting ProxyRequests to In a typical reverse proxy configuration, this option should be set to
In order to get the functionality of proxying HTTP or FTP sites, you
need also Do not enable proxying with This directive allows a user to specifiy a timeout on proxy requests.
This is useful when you have a slow/buggy appserver which hangs, and you
would rather just return a timeout and fail gracefully instead of waiting
however long it takes the server to return. This directive controls the use of the Apache HTTP Server Version 2.0 This module requires the service of Thus, in order to get the ability of handling Do not enable proxying until you have secured your server. Open proxy
servers are dangerous both to your network and to the Internet at
large. Apache HTTP Server Version 2.0 This module requires the service of Thus, in order to get the ability of handling FTP proxy requests,
Do not enable proxying until you have secured your server. Open proxy
servers are dangerous both to your network and to the Internet at
large. Apache HTTP Server Version 2.0 This module requires the service of Thus, in order to get the ability of handling HTTP proxy requests,
Do not enable proxying until you have secured your server. Open proxy
servers are dangerous both to your network and to the Internet at
large. Apache HTTP Server Version 2.0 This module uses a rule-based rewriting engine (based on a
regular-expression parser) to rewrite requested URLs on the
fly. It supports an unlimited number of rules and an
unlimited number of attached rule conditions for each rule, to
provide a really flexible and powerful URL manipulation
mechanism. The URL manipulations can depend on various tests,
of server variables, environment variables, HTTP
headers, or time stamps. Even external database lookups in
various formats can be used to achieve highly granular URL
matching. This module operates on the full URLs (including the
path-info part) both in per-server context
( Further details, discussion, and examples, are provided in the
detailed mod_rewrite documentation. Apache processes a HTTP request in several phases.
A hook for each of these
phases is provided by the Apache API. Once a request comes in, and Apache has determined the
appropriate server (or virtual server), the rewrite engine
starts the URL-to-filename translation,
processing the mod_rewrite directives from the
per-server configuration. A few
steps later, when the final data directories are found, the
per-directory configuration directives of mod_rewrite are
triggered in the Fixup phase. When mod_rewrite is triggered during these two API phases, it
reads the relevant rulesets from its configuration
structure (which was either created on startup, for
per-server context, or during the directory traversal
for per-directory context). The URL rewriting
engine is started with the appropriate ruleset (one or more
rules together with their conditions), and its operation
is exactly the same for both
configuration contexts. Only the final result processing is
different. The order of rules in the ruleset is important because the
rewrite engine processes them in a particular (not always
obvious) order, as follows: The rewrite engine loops
through the rulesets (each ruleset being made up of
As above, first the URL is matched against the
Pattern of a rule. If it does not match, If Using parentheses in Pattern or in one of the
CondPatterns causes back-references to be internally
created.
These can later be referenced using the strings
As of Apache 1.3.20, special characters in
TestString and Substitution strings can be
escaped (that is, treated as normal characters without their
usual special meaning) by prefixing them with a slash ('\')
character. In other words, you can include an actual
dollar-sign character in a Substitution string by
using ' This module keeps track of two additional (non-standard)
CGI/SSI environment variables named Notice: These variables hold the URI/URL as they were
initially requested, that is, before any
rewriting. This is important to note because the rewriting process is
primarily used to rewrite logical URLs to physical
pathnames. For numerous examples of common, and not-so-common, uses for
mod_rewrite, see the Rewrite
Guide, and the Advanced Rewrite
Guide documents. The When a substitution occurs for a new URL, this module has
to re-inject the URL into the server processing. To be able
to do this it needs to know what the corresponding URL-prefix
or URL-base is. By default this prefix is the corresponding
filepath itself. However, for most websites, URLs are NOT
directly related to physical filename paths, so this
assumption will often be wrong! Therefore, you can
use the For example, assume the following per-directory config file: In the above example, a request to
The following list gives detailed information about
the internal processing steps: This seems very complicated, but is in fact
correct Apache internal processing. Because the
per-directory rewriting comes late in the
process, the rewritten request
has to be re-injected into the Apache kernel.
This is not the serious overhead it may seem to be -
this re-injection is completely internal to the
Apache server (and the same procedure is used by
many other operations within Apache). The TestString is a string which can contain the
following expanded constructs in addition to plain text: These variables all
correspond to the similarly named HTTP
MIME-headers, C variables of the Apache server or
Other things you should be aware of: For instance, to rewrite according to the
On the other hand, because mod_rewrite implements
its per-directory context ( CondPattern is the condition pattern,
a regular expression which is applied to the
current instance of the TestString.
TestString is first evaluated, before being matched against
CondPattern. Remember: CondPattern is a
perl compatible regular expression with some
additions: Example: To rewrite the Homepage of a site according to the
`` Explanation: If you use a browser which identifies itself
as 'Mozilla' (including Netscape Navigator, Mozilla etc), then you
get the max homepage (which could include frames, or other special
features).
If you use the Lynx browser (which is terminal-based), then
you get the min homepage (which could be a version designed for
easy, text-only browsing).
If neither of these conditions apply (you use any other browser,
or your browser identifies itself as something non-standard), you get
the std (standard) homepage. The Use this directive to disable the module instead of
commenting out all the Note that, by default, rewrite configurations are not
inherited. This means that you need to have a
This directive sets the filename for a synchronization
lockfile which mod_rewrite needs to communicate with The The To disable the logging of rewriting actions simply set
Level to 0. This disables all rewrite action
logs. The The MapName is
the name of the map and will be used to specify a
mapping-function for the substitution strings of a rewriting
rule via one of the following constructs:
When such a construct occurs, the map MapName is
consulted and the key LookupKey is looked-up. If the
key is found, the map-function construct is substituted by
SubstValue. If the key is not found then it is
substituted by DefaultValue or by the empty string
if no DefaultValue was specified. For example, you might define a
You would then be able to use this map in a
The following combinations for MapType and
MapSource can be used: This is the standard rewriting map feature where the
MapSource is a plain ASCII file containing
either blank lines, comment lines (starting with a '#'
character) or pairs like the following - one per
line.
MatchingKey
SubstValue
This is identical to the Standard Plain Text variant
above but with a special post-processing feature: After
looking up a value it is parsed according to contained
`` Example: Here the source is a binary format DBM file containing
the same contents as a Plain Text format file, but
in a special representation which is optimized for really
fast lookups. The type can be sdbm, gdbm, ndbm, or
db depending on compile-time
settings. If the type is ommitted, the
compile-time default will be chosen. You can create such a
file with any DBM tool or with the following Perl
script. Be sure to adjust it to create the appropriate
type of DBM. The example creates an NDBM file. Here, the source is an internal Apache function.
Currently you cannot create your own, but the following
functions already exist: Here the source is a program, not a map file. To
create it you can use a language of your choice, but
the result has to be an executable program (either
object-code or a script with the magic cookie trick
' This program is started once, when the Apache server
is started, and then communicates with the rewriting engine
via its But be very careful: The The The Pattern is
a perl compatible regular
expression, which is applied to the current URL.
``Current'' means the value of the URL when this rule is
applied. This may not be the originally requested URL,
which may already have matched a previous rule, and have
been altered. Some hints on the syntax of regular expressions: For more information about regular expressions, have a look at the
perl regular expression manpage ("perldoc
perlre"). If you are interested in more detailed
information about regular expressions and their variants
(POSIX regex etc.) the following book is dedicated to this topic:
Mastering Regular Expressions, 2nd Edition In mod_rewrite, the NOT character
(' The substitution of a
rewrite rule is the string which is substituted for (or
replaces) the original URL which Pattern
matched. In addition to plain text, it can include Back-references are identifiers of the form
As already mentioned, all rewrite rules are
applied to the Substitution (in the order in which
they are defined
in the config file). The URL is completely
replaced by the Substitution and the
rewriting process continues until all rules have been applied,
or it is explicitly terminated by a
There is a special substitution string named
' Additionally you can set special flags for Substitution by
appending Note: Note: You must use this flag if you want to
mix directives from different modules which allow
URL-to-filename translators. The typical example
is the use of When the substitution string begins with a string
resembling "/~user" (via explicit text or backreferences), mod_rewrite performs
home directory expansion independent of the presence or configuration
of This expansion does not occur when the PT
flag is used on the There is one exception: If a substitution string
starts with `` When you prefix a substitution field with
Remember: An unconditional external
redirect to your own server will not work with the prefix
The Pattern will not be matched against the query string.
Instead, you must use a Here are all possible substitution combinations and their
meanings: Inside per-server configuration
( Inside per-directory configuration for
Apache HTTP Server Version 2.0 The The directives are considered in the order they appear in
the configuration files. So more complex sequences can be used,
such as this example, which sets The Some additional examples: The The The The second argument (regex) is a Perl compatible regular expression.
This is similar to a POSIX.2 egrep-style regular expression.
If the regex matches against the attribute,
then the remainder of the arguments are evaluated. The rest of the arguments give the names of variables to set, and
optionally values to which they should be set. These take the form
of In the first form, the value will be set to "1". The second
will remove the given variable if already defined, and the
third will set the variable to the literal value given by
The first three will set the environment variable
The last example will set environment variable
The This will cause the Apache HTTP Server Version 2.0 On selected operating systems this module can be used to
load modules into Apache at runtime via the Dynamic Shared Object (DSO) mechanism,
rather than requiring a recompilation. On Unix, the loaded code typically comes from shared object
files (usually with Apache 1.3 modules cannot be directly used
with Apache 2.0 - the module must be modified to dynamically
load or compile into Apache 2.0. The module name format changed for Windows
with Apache 1.3.15 and 2.0 - the modules are now named as
mod_foo.so While mod_so still loads modules with
ApacheModuleFoo.dll names, the new naming convention is
preferred; if you are converting your loadable module for 2.0,
please fix the name to this 2.0 convention. The Apache module API is unchanged between the Unix and
Windows versions. Many modules will run on Windows with no or
little change from Unix, although others rely on aspects of the
Unix architecture which are not present in Windows, and will
not work. When a module does work, it can be added to the server in
one of two ways. As with Unix, it can be compiled into the
server. Because Apache for Windows does not have the
The second way is to compile the module as a DLL, a shared
library that can be loaded into the server at runtime, using
the To create a module DLL, a small change is necessary to the
module's source file: The module record must be exported from
the DLL (which will be created later; see below). To do this,
add the Replace the above with: Note that this will only be activated on Windows, so the
module can continue to be used, unchanged, with Unix if needed.
Also, if you are familiar with Now, create a DLL containing your module. You will need to
link this against the libhttpd.lib export library that is
created when the libhttpd.dll shared library is compiled. You
may also have to change the compiler settings to ensure that
the Apache header files are correctly located. You can find
this library in your server root's modules directory. It is
best to grab an existing module .dsp file from the tree to
assure the build environment is configured correctly, or
alternately compare the compiler and link options to your
.dsp. This should create a DLL version of your module. Now simply
place it in the The LoadFile directive links in the named object files or
libraries when the server is started or restarted; this is used
to load additional code which may be required for some module
to work. Filename is either an absolute path or
relative to ServerRoot. For example: The LoadModule directive links in the object file or library
filename and adds the module structure named
module to the list of active modules. Module
is the name of the external variable of type
loads the named module from the modules subdirectory of the
ServerRoot. Apache HTTP Server Version 2.0 Requests to documents sometimes cannot be served by the core
apache server because the request was misspelled or
miscapitalized. This module addresses this problem by trying to
find a matching document, even after all other modules gave up.
It does its work by comparing each document name in the
requested directory against the requested document name
without regard to case, and allowing
up to one misspelling (character insertion /
omission / transposition or wrong character). A list is built
with all document names which were matched using this
strategy. If, after scanning the directory, This directive enables or disables the spelling module. When
enabled, keep in mind that Apache HTTP Server Version 2.0 This module provides SSL v2/v3 and TLS v1 support for the Apache
HTTP Server. It was contributed by Ralf S. Engeschall based on his
mod_ssl project and originally derived from work by Ben Laurie. This module relies on OpenSSL
to provide the cryptography engine. Further details, discussion, and examples are provided in the
SSL documentation. This module provides a lot of SSL information as additional environment
variables to the SSI and CGI namespace. The generated variables are listed in
the table below. For backward compatibility the information can
be made available under different names, too. Look in the Compatibility chapter for details on the
compatibility variables. [ where x509 is a component of a X.509 DN:
When
For backward compatibility there is additionally a special
``
Example:
This directive sets the all-in-one file where you can assemble the
Certificates of Certification Authorities (CA) whose clients you deal
with. These are used for Client Authentication. Such a file is simply the
concatenation of the various PEM-encoded Certificate files, in order of
preference. This can be used alternatively and/or additionally to
This directive sets the directory where you keep the Certificates of
Certification Authorities (CAs) whose clients you deal with. These are used to
verify the client certificate on Client Authentication.
The files in this directory have to be PEM-encoded and are accessed through
hash filenames. So usually you can't just place the Certificate files
there: you also have to create symbolic links named
hash-value
This directive sets the all-in-one file where you can
assemble the Certificate Revocation Lists (CRL) of Certification
Authorities (CA) whose clients you deal with. These are used
for Client Authentication. Such a file is simply the concatenation of
the various PEM-encoded CRL files, in order of preference. This can be
used alternatively and/or additionally to
This directive sets the directory where you keep the Certificate Revocation
Lists (CRL) of Certification Authorities (CAs) whose clients you deal with.
These are used to revoke the client certificate on Client Authentication.
The files in this directory have to be PEM-encoded and are accessed through
hash filenames. So usually you have not only to place the CRL files there.
Additionally you have to create symbolic links named
hash-value
This directive sets the optional all-in-one file where you can
assemble the certificates of Certification Authorities (CA) which form the
certificate chain of the server certificate. This starts with the issuing CA
certificate of of the server certificate and can range up to the root CA
certificate. Such a file is simply the concatenation of the various
PEM-encoded CA Certificate files, usually in certificate chain order.
This should be used alternatively and/or additionally to
But be careful: Providing the certificate chain works only if you are using a
single (either RSA or DSA) based server certificate. If you are
using a coupled RSA+DSA certificate pair, this will work only if actually both
certificates use the same certificate chain. Else the browsers will be
confused in this situation.
This directive points to the PEM-encoded Certificate file for the server and
optionally also to the corresponding RSA or DSA Private Key file for it
(contained in the same file). If the contained Private Key is encrypted the
Pass Phrase dialog is forced at startup time. This directive can be used up to
two times (referencing different filenames) when both a RSA and a DSA based
server certificate is used in parallel.
This directive points to the PEM-encoded Private Key file for the
server. If the Private Key is not combined with the Certificate in the
This complex directive uses a colon-separated cipher-spec string
consisting of OpenSSL cipher specifications to configure the Cipher Suite the
client is permitted to negotiate in the SSL handshake phase. Notice that this
directive can be used both in per-server and per-directory context. In
per-server context it applies to the standard SSL handshake when a connection
is established. In per-directory context it forces a SSL renegotation with the
reconfigured Cipher Suite after the HTTP request was read but before the HTTP
response is sent.
An SSL cipher specification in cipher-spec is composed of 4 major
attributes plus a few extra minor ones: An SSL cipher can also be an export cipher and is either a SSLv2 or SSLv3/TLSv1
cipher (here TLSv1 is equivalent to SSLv3). To specify which ciphers to use,
one can either specify all the Ciphers, one at a time, or use aliases to
specify the preference and order for the ciphers (see Table
1).
Now where this becomes interesting is that these can be put together
to specify the order and ciphers you wish to use. To speed this up
there are also aliases ( A simpler way to look at all of this is to use the `` The complete list of particular RSA & DH ciphers for SSL is given in Table 2.
This directive toggles the usage of the SSL/TLS Protocol Engine. This
is usually used inside a
This configures the SSL engine's semaphore (aka. lock) which is used for mutual
exclusion of operations which have to be done in a synchronized way between the
pre-forked Apache server processes. This directive can only be used in the
global server context because it's only useful to have one global mutex.
This directive is designed to closely match the
AcceptMutex directive
The following Mutex types are available:
This is the default where no Mutex is used at all. Use it at your own
risk. But because currently the Mutex is mainly used for synchronizing
write access to the SSL Session Cache you can live without it as long
as you accept a sometimes garbled Session Cache. So it's not recommended
to leave this the default. Instead configure a real Mutex.
This is an elegant Mutex variant where a Posix Semaphore is used when possible.
It is only available when the underlying platform
and APR supports it.
This is a somewhat elegant Mutex variant where a SystemV IPC Semaphore is used when
possible. It is possible to "leak" SysV semaphores if processes crash before
the semaphore is removed. It is only available when the underlying platform
and APR supports it.
This directive tells the SSL Module to pick the "best" semaphore implementation
available to it, choosing between Posix and SystemV IPC, in that order. It is only
available when the underlying platform and APR supports at least one of the 2.
This directive tells the SSL Module to use Posix thread mutexes. It is only available
if the underlying platform and APR supports it.
This is a portable Mutex variant where a physical (lock-)file and the
This is similar to the
This directive tells the SSL Module to pick the "best" file locking implementation
available to it, choosing between
This directive tells the SSL Module to pick the default locking implementation
as determined by the platform and APR.
This directive can be used to control various run-time options on a
per-directory basis. Normally, if multiple
The available options are:
When this option is enabled, the standard set of SSL related CGI/SSI
environment variables are created. This per default is disabled for
performance reasons, because the information extraction step is a
rather expensive operation. So one usually enables this option for
CGI and SSI requests only.
When this option is enabled, additional CGI/SSI environment variables are
created for backward compatibility to other Apache SSL solutions. Look in
the Compatibility chapter for details
on the particular variables generated.
When this option is enabled, additional CGI/SSI environment variables are
created:
When this option is enabled, the Subject Distinguished Name (DN) of the
Client X509 Certificate is translated into a HTTP Basic Authorization
username. This means that the standard Apache authentication methods can
be used for access control. The user name is just the Subject of the
Client's X509 Certificate (can be determined by running OpenSSL's
This forces forbidden access when
This enables optimized SSL connection renegotiation handling when SSL
directives are used in per-directory context. By default a strict
scheme is enabled where every per-directory reconfiguration of
SSL parameters causes a full SSL renegotiation handshake. When this
option is used mod_ssl tries to avoid unnecessary handshakes by doing more
granular (but still safe) parameter checks. Nevertheless these granular
checks sometimes maybe not what the user expects, so enable this on a
per-directory basis only, please.
When Apache starts up it has to read the various Certificate (see
This is the default where an interactive terminal dialog occurs at startup
time just before Apache detaches from the terminal. Here the administrator
has to manually enter the Pass Phrase for each encrypted Private Key file.
Because a lot of SSL-enabled virtual hosts can be configured, the
following reuse-scheme is used to minimize the dialog: When a Private Key
file is encrypted, all known Pass Phrases (at the beginning there are
none, of course) are tried. If one of those known Pass Phrases succeeds no
dialog pops up for this particular Private Key file. If none succeeded,
another Pass Phrase is queried on the terminal and remembered for the next
round (where it perhaps can be reused).
This scheme allows mod_ssl to be maximally flexible (because for N encrypted
Private Key files you can use N different Pass Phrases - but then
you have to enter all of them, of course) while minimizing the terminal
dialog (i.e. when you use a single Pass Phrase for all N Private Key files
this Pass Phrase is queried only once).
Here an external program is configured which is called at startup for each
encrypted Private Key file. It is called with two arguments (the first is
of the form ``
Both these security checks, and the way the Pass Phrase is determined, can
be as complex as you like. Mod_ssl just defines the interface: an
executable program which provides the Pass Phrase on
The reuse-algorithm above is used here, too. In other words: The external
program is called only once per unique Pass Phrase.
Example:
This directive can be used to control the SSL protocol flavors mod_ssl should
use when establishing its server environment. Clients then can only connect
with one of the provided protocols.
The available (case-insensitive) protocols are:
This is the Secure Sockets Layer (SSL) protocol, version 2.0. It is the
original SSL protocol as designed by Netscape Corporation.
This is the Secure Sockets Layer (SSL) protocol, version 3.0. It is the
successor to SSLv2 and the currently (as of February 1999) de-facto
standardized SSL protocol from Netscape Corporation. It's supported by
almost all popular browsers.
This is the Transport Layer Security (TLS) protocol, version 1.0. It is the
successor to SSLv3 and currently (as of February 1999) still under
construction by the Internet Engineering Task Force (IETF). It's still
not supported by any popular browsers.
This is a shortcut for ``
This directive sets the all-in-one file where you can assemble the
Certificates of Certification Authorities (CA) whose remote servers you deal
with. These are used for Remote Server Authentication. Such a file is simply the
concatenation of the various PEM-encoded Certificate files, in order of
preference. This can be used alternatively and/or additionally to
This directive sets the directory where you keep the Certificates of
Certification Authorities (CAs) whose remote servers you deal with. These are used to
verify the remote server certificate on Remote Server Authentication.
The files in this directory have to be PEM-encoded and are accessed through
hash filenames. So usually you can't just place the Certificate files
there: you also have to create symbolic links named
hash-value
This directive sets the all-in-one file where you can
assemble the Certificate Revocation Lists (CRL) of Certification
Authorities (CA) whose remote servers you deal with. These are used
for Remote Server Authentication. Such a file is simply the concatenation of
the various PEM-encoded CRL files, in order of preference. This can be
used alternatively and/or additionally to
This directive sets the directory where you keep the Certificate Revocation
Lists (CRL) of Certification Authorities (CAs) whose remote servers you deal with.
These are used to revoke the remote server certificate on Remote Server Authentication.
The files in this directory have to be PEM-encoded and are accessed through
hash filenames. So usually you have not only to place the CRL files there.
Additionally you have to create symbolic links named
hash-value Equivalent to
This directive toggles the usage of the SSL/TLS Protocol Engine for proxy. This
is usually used inside a
This directive sets the all-in-one file where you keep the certificates and
keys used for authentication of the proxy server to remote servers.
This referenced file is simply the concatenation of the various PEM-encoded
certificate files, in order of preference. Use this directive alternatively
or additionally to Currently there is no support for encrypted private keys
Example:
This directive sets the directory where you keep the certificates and
keys used for authentication of the proxy server to remote servers.
The files in this directory must be PEM-encoded and are accessed through
hash filenames. Additionally, you must create symbolic links named
Currently there is no support for encrypted private keys
Example:
This directive can be used to control the SSL protocol flavors mod_ssl should
use when establishing its server environment for proxy . It will only connect
to servers using one of the provided protocols. Please refer to
This directive sets the Certificate verification level for the remote server
Authentication. Notice that this directive can be used both in per-server and
per-directory context. In per-server context it applies to the remote server
authentication process used in the standard SSL handshake when a connection is
established. In per-directory context it forces a SSL renegotation with the
reconfigured remote server verification level after the HTTP request was read but
before the HTTP response is sent.
The following levels are available for level: In practice only levels none and
require are really interesting, because level
optional doesn't work with all servers and level
optional_no_ca is actually against the idea of
authentication (but can be used to establish SSL test pages, etc.)
This directive sets how deeply mod_ssl should verify before deciding that the
remote server does not have a valid certificate. Notice that this directive can be
used both in per-server and per-directory context. In per-server context it
applies to the client authentication process used in the standard SSL
handshake when a connection is established. In per-directory context it forces
a SSL renegotation with the reconfigured remote server verification depth after the
HTTP request was read but before the HTTP response is sent.
The depth actually is the maximum number of intermediate certificate issuers,
i.e. the number of CA certificates which are max allowed to be followed while
verifying the remote server certificate. A depth of 0 means that self-signed
remote server certificates are accepted only, the default depth of 1 means
the remote server certificate can be self-signed or has to be signed by a CA
which is directly known to the server (i.e. the CA's certificate is under
This configures one or more sources for seeding the Pseudo Random Number
Generator (PRNG) in OpenSSL at startup time (context is
The following source variants are available: This is the always available builtin seeding source. It's usage
consumes minimum CPU cycles under runtime and hence can be always used
without drawbacks. The source used for seeding the PRNG contains of the
current time, the current process id and (when applicable) a randomly
choosen 1KB extract of the inter-process scoreboard structure of Apache.
The drawback is that this is not really a strong source and at startup
time (where the scoreboard is still not available) this source just
produces a few bytes of entropy. So you should always, at least for the
startup, use an additional seeding source.
This variant uses an external file
But be careful: Usually
On some platforms like FreeBSD one can even control how the entropy is
actually generated, i.e. by which system interrupts. More details one can
find under rndcontrol(8) on those platforms. Alternatively, when
your system lacks such a random device, you can use tool
like EGD
(Entropy Gathering Daemon) and run it's client program with the
This variant uses an external executable
This variant uses the Unix domain socket of the
external Entropy Gathering Daemon (EGD) (see http://www.lothar.com/tech
/crypto/) to seed the PRNG. Use this if no random device exists
on your platform.
This directive specifies a general access requirement which has to be
fulfilled in order to allow access. It's a very powerful directive because the
requirement specification is an arbitrarily complex boolean expression
containing any number of access checks.
The expression must match the following syntax (given as a BNF
grammar notation): while for
This function takes one string argument and expands to the contents of the
file. This is especially useful for matching this contents against a
regular expression, etc. Notice that expression is first parsed into an internal machine
representation and then evaluated in a second step. Actually, in Global and
Per-Server Class context expression is parsed at startup time and
at runtime only the machine representation is executed. For Per-Directory
context this is different: here expression has to be parsed and
immediately executed for every request. Standard CGI/1.0 and Apache variables: SSL-related variables:
This directive forbids access unless HTTP over SSL (i.e. HTTPS) is enabled for
the current connection. This is very handy inside the SSL-enabled virtual
host or directories for defending against configuration errors that expose
stuff that should be protected. When this directive is present all requests
are denied which are not using SSL.
This configures the storage type of the global/inter-process SSL Session
Cache. This cache is an optional facility which speeds up parallel request
processing. For requests to the same server process (via HTTP keep-alive),
OpenSSL already caches the SSL session information locally. But because modern
clients request inlined images and other data via parallel requests (usually
up to four parallel requests are common) those requests are served by
different pre-forked server processes. Here an inter-process cache
helps to avoid unneccessary session handshakes.
The following two storage types are currently supported:
This is the default and just disables the global/inter-process Session
Cache. There is no drawback in functionality, but a noticeable speed
penalty can be observed.
This makes use of a DBM hashfile on the local disk to synchronize the
local OpenSSL memory caches of the server processes. The slight increase
in I/O on the server results in a visible request speedup for your
clients, so this type of storage is generally recommended.
This makes use of a high-performance hash table (approx. size bytes
in size) inside a shared memory segment in RAM (established via
This directive sets the timeout in seconds for the information stored in the
global/inter-process SSL Session Cache and the OpenSSL internal memory cache.
It can be set as low as 15 for testing, but should be set to higher
values like 300 in real life.
This directive sets the "user" field in the Apache request object.
This is used by lower modules to identify the user with a character
string. In particular, this may cause the environment variable
This directive sets the Certificate verification level for the Client
Authentication. Notice that this directive can be used both in per-server and
per-directory context. In per-server context it applies to the client
authentication process used in the standard SSL handshake when a connection is
established. In per-directory context it forces a SSL renegotation with the
reconfigured client verification level after the HTTP request was read but
before the HTTP response is sent.
The following levels are available for level: In practice only levels none and
require are really interesting, because level
optional doesn't work with all browsers and level
optional_no_ca is actually against the idea of
authentication (but can be used to establish SSL test pages, etc.)
This directive sets how deeply mod_ssl should verify before deciding that the
clients don't have a valid certificate. Notice that this directive can be
used both in per-server and per-directory context. In per-server context it
applies to the client authentication process used in the standard SSL
handshake when a connection is established. In per-directory context it forces
a SSL renegotation with the reconfigured client verification depth after the
HTTP request was read but before the HTTP response is sent.
The depth actually is the maximum number of intermediate certificate issuers,
i.e. the number of CA certificates which are max allowed to be followed while
verifying the client certificate. A depth of 0 means that self-signed client
certificates are accepted only, the default depth of 1 means the client
certificate can be self-signed or has to be signed by a CA which is directly
known to the server (i.e. the CA's certificate is under
Apache HTTP Server Version 2.0 The Status module allows a server administrator to find out
how well their server is performing. A HTML page is presented
that gives the current server statistics in an easily readable
form. If required this page can be made to automatically
refresh (given a compatible browser). Another page gives a
simple machine-readable list of the current server state. The details given are: The lines marked "(*)" are only available if
To enable status reports only for browsers from the foo.com
domain add this code to your You can now access server statistics by using a Web browser
to access the page
You can get the status page to update itself automatically if
you have a browser that supports "refresh". Access the page
A machine-readable version of the status file is available by
accessing the page
This setting applies to the entire server, and cannot be
enabled or disabled on a virtualhost-by-virtualhost basis.
The collection of extended status information can slow down
the server. Apache HTTP Server Version 2.0 This module, in combination with the The Apache HTTP Server Version 2.0 This module provides a magic token for each request which is
guaranteed to be unique across "all" requests under very
specific conditions. The unique identifier is even unique
across multiple machines in a properly configured cluster of
machines. The environment variable First a brief recap of how the Apache server works on Unix
machines. This feature currently isn't supported on Windows NT.
On Unix machines, Apache creates several children, the children
process requests one at a time. Each child can serve multiple
requests in its lifetime. For the purpose of this discussion,
the children don't share any data with each other. We'll refer
to the children as httpd processes. Your website has one or more machines under your
administrative control, together we'll call them a cluster of
machines. Each machine can possibly run multiple instances of
Apache. All of these collectively are considered "the
universe", and with certain assumptions we'll show that in this
universe we can generate unique identifiers for each request,
without extensive communication between machines in the
cluster. The machines in your cluster should satisfy these
requirements. (Even if you have only one machine you should
synchronize its clock with NTP.) As far as operating system assumptions go, we assume that
pids (process ids) fit in 32-bits. If the operating system uses
more than 32-bits for a pid, the fix is trivial but must be
performed in the code. Given those assumptions, at a single point in time we can
identify any httpd process on any machine in the cluster from
all other httpd processes. The machine's IP address and the pid
of the httpd process are sufficient to do this. So in order to
generate unique identifiers for requests we need only
distinguish between different points in time. To distinguish time we will use a Unix timestamp (seconds
since January 1, 1970 UTC), and a 16-bit counter. The timestamp
has only one second granularity, so the counter is used to
represent up to 65536 values during a single second. The
quadruple ( ip_addr, pid, time_stamp, counter ) is
sufficient to enumerate 65536 requests per second per httpd
process. There are issues however with pid reuse over time, and
the counter is used to alleviate this issue. When an httpd child is created, the counter is initialized
with ( current microseconds divided by 10 ) modulo 65536 (this
formula was chosen to eliminate some variance problems with the
low order bits of the microsecond timers on some systems). When
a unique identifier is generated, the time stamp used is the
time the request arrived at the web server. The counter is
incremented every time an identifier is generated (and allowed
to roll over). The kernel generates a pid for each process as it forks the
process, and pids are allowed to roll over (they're 16-bits on
many Unixes, but newer systems have expanded to 32-bits). So
over time the same pid will be reused. However unless it is
reused within the same second, it does not destroy the
uniqueness of our quadruple. That is, we assume the system does
not spawn 65536 processes in a one second interval (it may even
be 32768 processes on some Unixes, but even this isn't likely
to happen). Suppose that time repeats itself for some reason. That is,
suppose that the system's clock is screwed up and it revisits a
past time (or it is too far forward, is reset correctly, and
then revisits the future time). In this case we can easily show
that we can get pid and time stamp reuse. The choice of
initializer for the counter is intended to help defeat this.
Note that we really want a random number to initialize the
counter, but there aren't any readily available numbers on most
systems (i.e., you can't use rand() because you need
to seed the generator, and can't seed it with the time because
time, at least at one second resolution, has repeated itself).
This is not a perfect defense. How good a defense is it? Suppose that one of your machines
serves at most 500 requests per second (which is a very
reasonable upper bound at this writing, because systems
generally do more than just shovel out static files). To do
that it will require a number of children which depends on how
many concurrent clients you have. But we'll be pessimistic and
suppose that a single child is able to serve 500 requests per
second. There are 1000 possible starting counter values such
that two sequences of 500 requests overlap. So there is a 1.5%
chance that if time (at one second resolution) repeats itself
this child will repeat a counter value, and uniqueness will be
broken. This was a very pessimistic example, and with real
world values it's even less likely to occur. If your system is
such that it's still likely to occur, then perhaps you should
make the counter 32 bits (by editing the code). You may be concerned about the clock being "set back" during
summer daylight savings. However this isn't an issue because
the times used here are UTC, which "always" go forward. Note
that x86 based Unixes may need proper configuration for this to
be true -- they should be configured to assume that the
motherboard clock is on UTC and compensate appropriately. But
even still, if you're running NTP then your UTC time will be
correct very shortly after reboot. The The ordering was chosen such that it's possible to change
the encoding in the future without worrying about collision
with an existing database of This we believe is a relatively portable solution to this
problem. It can be extended to multithreaded systems like
Windows NT, and can grow with future needs. The identifiers
generated have essentially an infinite life-time because future
identifiers can be made longer as required. Essentially no
communication is required between machines in the cluster (only
NTP synchronization is required, which is low overhead), and no
communication between httpd processes is required (the
communication is implicit in the pid value assigned by the
kernel). In very specific situations the identifier can be
shortened, but more information needs to be assumed (for
example the 32-bit IP address is overkill for any site, but
there is no portable shorter replacement for it). Apache HTTP Server Version 2.0 This module allows user-specific directories to be accessed using the
The If neither the The following directives will send redirects to the client: Additional examples: To allow a few users to have To allow most users to have It is also possible to specify alternative user directories.
If you use a command like: With a request for http://www.foo.com/~bob/one/two.html, will try to
find the page at ~bob/public_html/one/two.html first, then
/usr/web/bob/one/two.html, and finally it will send a redirect
to http://www.foo.com/bob/one/two.html. If you add a redirect, it must be the last alternative in the list.
Apache cannot determine if the redirect succeeded or not, so if you have
the redirect earlier in the list, that will always be the alternative
that is used. Apache HTTP Server Version 2.0 Previous releases of Apache have included a module which
generates a 'clickstream' log of user activity on a site using
cookies. This was called the "cookies" module, mod_cookies. In
Apache 1.2 and later this module has been renamed the "user
tracking" module, mod_usertrack. This module has been
simplified and new directives added. Previously, the cookies module (now the user tracking
module) did its own logging, using the For backward compatibility the configurable log module
implements the old (the following is from message
<022701bda43d$9d32bbb0$1201a8c0@christian.office.sane.com>
in the new-httpd archives) This directive controls the setting of the domain to which
the tracking cookie applies. If not present, no domain is
included in the cookie header field. The domain string must begin with a dot, and
must include at least one embedded dot. That is,
When used, this directive sets an expiry time on the cookie
generated by the usertrack module. The expiry-period
can be given either as a number of seconds, or in the format
such as "2 weeks 3 days 7 hours". Valid denominations are:
years, months, weeks, days, hours, minutes and seconds. If the expiry
time is in any format other than one number indicating the
number of seconds, it must be enclosed by double quotes. If this directive is not used, cookies last only for the
current browser session. This directive allows you to change the name of the cookie
this module uses for its tracking purposes. By default the
cookie is named " You must specify a valid cookie name; results are
unpredictable if you use a name containing unusual characters.
Valid characters include A-Z, a-z, 0-9, "_", and "-". This directive controls the format of the cookie header
field. The three formats allowed are: Not all clients can understand all of these formats. but you
should use the newest one that is generally acceptable to your
users' browsers. At the time of writing, most browsers only fully
support When Apache HTTP Server Version 2.0 This module is designed for the use in test suites and large
networks which have to deal with different httpd versions and
different configurations. It provides a new container -- See below for further possibilities. The Besides the numerical comparison it is possible to match a regular
expression against the httpd version. There are two ways to write it: In order to reverse the meaning, all operators can be preceded by an
exclamation mark ( If the operator is omitted, it is assumed to be
Apache HTTP Server Version 2.0 This module creates dynamically configured virtual hosts, by
allowing the IP address and/or the If All the directives in this module interpolate a string into
a pathname. The interpolated string (henceforth called the
"name") may be either the server name (see the If For simple name-based virtual hosts you might use the
following directives in your server configuration file: A request for
For a very large number of virtual hosts it is a good idea
to arrange the files to reduce the size of the
A request for
A more even spread of files can be achieved by hashing from the
end of the name, for example: The example request would come from
Alternatively you might use: The example request would come from
For IP-based virtual hosting you might use the following in
your configuration file: A request for
If you want to include the A request for
The The The The The Apache HTTP Server Version 2.0 This document describes the terms that are used to describe
each Apache module. A brief description of the purpose of the module. This indicates how tightly bound into the Apache Web server
the module is; in other words, you may need to recompile the
server in order to gain access to the module and its
functionality. Possible values for this attribute are: This quite simply lists the name of the source file which
contains the code for the module. This is also the name used by
the This is a string which identifies the module for use in the
If the module was not part of the original Apache version 2
distribution, the version in which it was introduced should be
listed here. In addition, if the module is limited to
particular platforms, the details will be listed here. Apache HTTP Server Version 2.0 The If this directive is set to If you want to find out the compile time chosen default
for your system, you may set your The Only one This controls the directory to which Apache attempts to
switch before dumping core. The default is in the
If Apache starts as root and switches to another user, the
Linux kernel disables core dumps even if the directory is
writable for the process. Apache (2.0.46 and later) reenables core dumps
on Linux 2.4 and beyond, but only if you explicitly configure a For safety reasons this directive is only available if the server was
configured with the There are already two modules, The It is recommended that you set up a new group specifically for
running the server. Some admins use user Don't set Special note: Use of this directive in The The Multiple For example, to make the server accept connections on both
port 80 and port 8000, use: To make the server accept connections on two specified
interfaces and port numbers, use IPv6 addresses must be surrounded in square brackets, as in the
following example: The maximum length of the queue of pending connections.
Generally no tuning is needed or desired, however on some
systems it is desirable to increase this when under a TCP SYN
flood attack. See the backlog parameter to the
This will often be limited to a smaller number by the
operating system. This varies from OS to OS. Also note that
many OSes do not use exactly what is specified as the backlog,
but use a number based on (but normally larger than) what is
set. The It is best to avoid putting this file in a world writable
directory such as The For non-threaded servers (i.e., For threaded and hybrid servers (e.g. The The The default value for Setting For Maximum number of idle threads. Different MPMs deal with this
directive differently. For For For The range of the Minimum number of idle threads to handle request spikes.
Different MPMs deal with this directive
differently. The It is often useful to be able to send the server a signal,
so that it closes and then re-opens its The As of Apache 2 it is recommended to use only the The server will set the TCP receive buffer size to the number of
bytes specified. If set to the value of Apache uses a scoreboard to communicate between its parent
and child processes. Some architectures require a file to facilitate
this communication. If the file is left unspecified, Apache first
attempts to create the scoreboard entirely in memory (using anonymous
shared memory) and, failing that, will attempt to create the file on
disk (using file-based shared memory). Specifying this directive causes
Apache to always create the file on the disk. File-based shared memory is useful for third-party applications
that require direct access to the scoreboard. If you use a The server will set the TCP send buffer size to the number of bytes
specified. Very useful to increase past standard OS defaults on
high speed high latency (i.e., 100ms or so, such as
transcontinental fast pipes). If set to the value of For the Special care must be taken when using this directive. If
With the With With the There is a hard limit of The The default value differs from MPM to MPM. For
Number of threads created on startup. As the
number of threads is dynamically controlled depending on the
load, there is usually little reason to adjust this
parameter. For For For This directive sets the maximum configured value for Special care must be taken when using this directive. If
The default value for There is a hard limit of This directive sets the number of threads created by each
child process. The child creates these threads at startup and
never creates more. If using an MPM like The default value for The The user should have no privileges that result in it being
able to access files that are not intended to be visible to the
outside world, and similarly, the user should not be able to
execute code that is not meant for HTTP requests. It is
recommended that you set up a new user and group specifically for
running the server. Some admins use user Don't set With the Special note: Use of this directive in Apache HTTP Server Version 2.0 This Multi-Processing Module (MPM) implements an exclusively
threaded web server that has been optimized for Novell
NetWare. The main thread is responsible for launching child
worker threads which listen for connections and serve them when they
arrive. Apache always tries to maintain several spare
or idle worker threads, which stand ready to serve incoming
requests. In this way, clients do not need to wait for a new
child threads to be spawned before their requests can be
served. The
install.html 100644 0 0 46672 11074462673 10612 0 ustar 0 0
Apache HTTP Server Version 2.0
Documentation
invoking.html 100644 0 0 21746 11074462673 10763 0 ustar 0 0
Compiling and Installing
libtool and autoconf
to create an environment that looks like many other Open Source
projects.
Overview for the
impatient Requirements Download Extract Configuring the source tree Build Install Customize Test UpgradingSee also
Overview for the
impatient
Download
$ lynx http://httpd.apache.org/download.cgi
Extract
$ gzip -d httpd-2_0_NN.tar.gz
$ tar xvf httpd-2_0_NN.tar
Configure
$ ./configure --prefix=PREFIX
Compile
$ make
Install
$ make install
Customize
$ vi PREFIX/conf/httpd.conf
Test
$ PREFIX/bin/apachectl start
/usr/local/apache2.
Requirements
PATH must contain
basic build tools such as make.ntpdate or xntpd programs are used for
this purpose which are based on the Network Time Protocol (NTP).
See the Usenet newsgroup comp.protocols.time.ntp
and the NTP
homepage for more details about NTP software and public
time servers.apxs or dbmmanage (which are
written in Perl) the Perl 5 interpreter is required (versions
5.003 or newer are sufficient). If you have multiple Perl
interpreters (for example, a systemwide install of Perl 4, and
your own install of Perl 5), you are advised to use the
--with-perl option (see below) to make sure the
correct one is used by configure.
If no Perl 5 interpreter is found by the
configure script, you will not be able to use
the affected support scripts. Of course, you will still be able to
build and use Apache 2.0.
Download
INSTALL.bindist file inside the distribution.
Extract
$ gzip -d httpd-2_0_NN.tar.gz
$ tar xvf httpd-2_0_NN.tar
cd into that directory before proceeding with
compiling the server.
Configuring the source tree
configure included in
the root directory of the distribution. (Developers downloading
the CVS version of the Apache source tree will need to have
autoconf and libtool installed and will
need to run buildconf before proceeding with the next
steps. This is not necessary for official releases.)./configure. To change the default
options, configure accepts a variety of variables
and command line options.--prefix
where Apache is to be installed later, because Apache has to be
configured for this location to work correctly. More fine-tuned
control of the location of files is possible with additional configure
options.--enable-module option, where
module is the name of the module with the
mod_ string removed and with any underscore converted
to a dash. You can also choose to compile modules as shared objects (DSOs) -- which can be loaded
or unloaded at runtime -- by using the option
--enable-module=shared. Similarly, you can
disable Base modules with the
--disable-module option. Be careful when
using these options, since configure cannot warn you
if the module you specify does not exist; it will simply ignore the
option.configure script with extra information about the
location of your compiler, libraries, or header files. This is
done by passing either environment variables or command line
options to configure. For more information, see the
configure manual page./sw/pkg/apache with a particular compiler and flags
plus the two additional modules mod_rewrite and
mod_speling for
later loading through the DSO mechanism:
$ CC="pgcc" CFLAGS="-O2" \
./configure --prefix=/sw/pkg/apache \
--enable-rewrite=shared \
--enable-speling=shared
configure is run it will take several minutes to
test for the availability of features on your system and build
Makefiles which will later be used to compile the server.configure options are
available on the configure manual page.
Build
$ make
Install
--prefix option
above) by running:$ make install
Customize
PREFIX/conf/.$ vi PREFIX/conf/httpd.conf
Test
$ PREFIX/bin/apachectl starthttp://localhost/. The web page you see is located
under the DocumentRoot
which will usually be PREFIX/htdocs/.
Then stop the server again by
running:$ PREFIX/bin/apachectl stop
Upgrading
CHANGES in the source distribution to
find any changes that may affect your site. When changing between
major releases (for example, from 1.3 to 2.0 or from 2.0 to 2.2),
there will likely be major differences in the compile-time and
run-time configuration that will require manual adjustments. All
modules will also need to be upgraded to accomodate changes in the
module API.make install
process will not overwrite any of your existing documents, log
files, or configuration files. In addition, the developers make
every effort to avoid incompatible changes in the
configure options, run-time configuration, or the
module API between minor versions. In most cases you should be able to
use an identical configure command line, an identical
configuration file, and all of your modules should continue to
work. (This is only valid for versions after 2.0.41; earlier
versions have incompatible changes.)config.nice in the build directory of
your installed server or at the root of the source tree for your
old install. This will contain the exact
configure command line that you used to
configure the source tree. Then to upgrade from one version to
the next, you need only copy the config.nice file to
the source tree of the new version, edit it to make any desired
changes, and then run:
$ ./config.nice
$ make
$ make install
$ PREFIX/bin/apachectl stop
$ PREFIX/bin/apachectl start
You should always test any new version in your
environment before putting it into production. For example, you
can install and run the new version along side the old one by
using a different
--prefix and a
different port (by adjusting the Listen directive) to test for any
incompatibilities before doing the final upgrade.
license.html 100644 0 0 32120 11074462673 10545 0 ustar 0 0
Starting Apache
httpd program
is run as a daemon that executes continuously in the
background to handle requests. This document describes how
to invoke httpd.See also
How Apache Starts
Listen
specified in the configuration file is default of 80 (or any other
port below 1024), then it is necessary to have root privileges in
order to start apache, so that it can bind to this privileged
port. Once the server has started and performed a few preliminary
activities such as opening its log files, it will launch several
child processes which do the work of listening for and
answering requests from clients. The main httpd
process continues to run as the root user, but the child processes
run as a less privileged user. This is controlled by the selected
Multi-Processing Module.httpd
executable is to use the apachectl control script. This
script sets certain environment variables that are necessary for
httpd to function correctly under some operating
systems, and then invokes the httpd binary.
apachectl will pass through any command line
arguments, so any httpd options may also be used with
apachectl. You may also directly edit the
apachectl script by changing the HTTPD
variable near the top to specify the correct location of the
httpd binary and any command-line arguments that you
wish to be always present.httpd does when it is
invoked is to locate and read the configuration file
httpd.conf. The location of this file is set at
compile-time, but it is possible to specify its location at run
time using the -f command-line option as in/usr/local/apache2/bin/apachectl -f
/usr/local/apache2/conf/httpd.confDocumentRoot directory
and the local copy of the documentation linked from that
page.
Errors During Start-up
ErrorLog before
exiting. One of the most common error messages is "Unable
to bind to Port ...". This message is usually caused by
either:
Starting at Boot-Time
apachectl to your
system startup files (typically rc.local or a file in
an rc.N directory). This will start Apache as
root. Before doing this ensure that your server is properly
configured for security and access restrictions.apachectl script is designed to act like a
standard SysV init script; it can take the arguments
start, restart, and stop
and translate them into the appropriate signals to
httpd. So you can often simply link
apachectl into the appropriate init directory. But be
sure to check the exact requirements of your system.
Additional Information
httpd and apachectl as well as other support
programs included with the server is available on the
Server and Supporting Programs page.
There is also documentation on all the modules included with the Apache distribution
and the directives that they
provide.
logs.html 100644 0 0 74012 11074462673 10075 0 ustar 0 0
The Apache License, Version 2.0
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
misc/custom_errordocs.html 100644 0 0 60202 11074462673 13454 0 ustar 0 0
Log Files
Security Warning
Error Log
Related Modules Related Directives ErrorLog directive, is the
most important log file. This is the place where Apache httpd
will send diagnostic information and record any errors that it
encounters in processing requests. It is the first place to
look when a problem occurs with starting the server or with the
operation of the server, since it will often contain details of
what went wrong and how to fix it.error_log on Unix systems and
error.log on Windows and OS/2). On Unix systems it
is also possible to have the server send errors to
syslog or pipe them to a
program.
[Wed Oct 11 14:32:52 2000] [error] [client 127.0.0.1]
client denied by server configuration:
/export/home/live/ap/htdocs/test
LogLevel
directive is used to control the types of errors that are sent
to the error log by restricting the severity level. The third
item gives the IP address of the client that generated the
error. Beyond that is the message itself, which in this case
indicates that the server has been configured to deny the
client access. The server reports the file-system path (as
opposed to the web path) of the requested document.stderr by a CGI script will
be copied directly to the error log.
tail -f error_log
Access Log
Related Modules Related Directives CustomLog
directive. The LogFormat
directive can be used to simplify the selection of
the contents of the logs. This section describes how to configure the server
to record information in the access log.TransferLog directive. The CustomLog directive now subsumes
the functionality of all the older directives.mod_log_config format strings.Common Log Format
LogFormat "%h %l %u %t \"%r\" %>s %b" common
CustomLog logs/access_log common
common and
associates it with a particular log format string. The format
string consists of percent directives, each of which tell the
server to log a particular piece of information. Literal
characters may also be placed in the format string and will be
copied directly into the log output. The quote character
(") must be escaped by placing a back-slash before
it to prevent it from being interpreted as the end of the
format string. The format string may also contain the special
control characters "\n" for new-line and
"\t" for tab.CustomLog
directive sets up a new log file using the defined
nickname. The filename for the access log is relative to
the ServerRoot unless it
begins with a slash.
127.0.0.1 - frank [10/Oct/2000:13:55:36 -0700] "GET
/apache_pb.gif HTTP/1.0" 200 2326
127.0.0.1 (%h)HostnameLookups is
set to On, then the server will try to determine
the hostname and log it in place of the IP address. However,
this configuration is not recommended since it can
significantly slow the server. Instead, it is best to use a
log post-processor such as logresolve to determine
the hostnames. The IP address reported here is not
necessarily the address of the machine at which the user is
sitting. If a proxy server exists between the user and the
server, this address will be the address of the proxy, rather
than the originating machine.- (%l)identd on the clients
machine. This information is highly unreliable and should
almost never be used except on tightly controlled internal
networks. Apache httpd will not even attempt to determine
this information unless IdentityCheck is set
to On.frank (%u)REMOTE_USER environment variable. If the status
code for the request (see below) is 401, then this value
should not be trusted because the user is not yet
authenticated. If the document is not password protected,
this part will be "-" just like the previous
one.[10/Oct/2000:13:55:36 -0700]
(%t)[day/month/year:hour:minute:second zone]
day = 2*digit
month = 3*letter
year = 4*digit
hour = 2*digit
minute = 2*digit
second = 2*digit
zone = (`+' | `-') 4*digit%{format}t in the log format
string, where format is as in
strftime(3) from the C standard library.
"GET /apache_pb.gif HTTP/1.0"
(\"%r\")GET. Second, the client requested the resource
/apache_pb.gif, and third, the client used the
protocol HTTP/1.0. It is also possible to log
one or more parts of the request line independently. For
example, the format string "%m %U%q %H" will log
the method, path, query-string, and protocol, resulting in
exactly the same output as "%r".200 (%>s)2326 (%b)-". To log "0" for no content, use
%B instead.Combined Log Format
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\"
\"%{User-agent}i\"" combined
CustomLog log/access_log combined
%{header}i, where header can be
any HTTP request header. The access log under this format will
look like:
127.0.0.1 - frank [10/Oct/2000:13:55:36 -0700] "GET
/apache_pb.gif HTTP/1.0" 200 2326
"http://www.example.com/start.html" "Mozilla/4.08 [en]
(Win98; I ;Nav)"
"http://www.example.com/start.html"
(\"%{Referer}i\")/apache_pb.gif)."Mozilla/4.08 [en] (Win98; I ;Nav)"
(\"%{User-agent}i\")Multiple Access Logs
CustomLog
directives in the configuration
file. For example, the following directives will create three
access logs. The first contains the basic CLF information,
while the second and third contain referer and browser
information. The last two CustomLog lines show how
to mimic the effects of the ReferLog and AgentLog directives.
LogFormat "%h %l %u %t \"%r\" %>s %b" common
CustomLog logs/access_log common
CustomLog logs/referer_log "%{Referer}i -> %U"
CustomLog logs/agent_log "%{User-agent}i"
LogFormat directive. Instead,
the log format can be specified directly in the CustomLog directive.Conditional Logs
SetEnvIf. Then the
env= clause of the CustomLog directive is used to
include or exclude requests where the environment variable is
set. Some examples:
# Mark requests from the loop-back interface
SetEnvIf Remote_Addr "127\.0\.0\.1" dontlog
# Mark requests for the robots.txt file
SetEnvIf Request_URI "^/robots\.txt$" dontlog
# Log what remains
CustomLog logs/access_log common env=!dontlog
SetEnvIf Accept-Language "en" english
CustomLog logs/english_log common env=english
CustomLog logs/non_english_log common env=!english
Log Rotation
mv access_log access_log.old
mv error_log error_log.old
apachectl graceful
sleep 600
gzip access_log.old error_log.old
Piped Logs
|", followed by the name
of the executable which should accept log entries on its
standard input. Apache will start the piped-log process when
the server starts, and will restart it if it crashes while the
server is running. (This last feature is why we can refer to
this technique as "reliable piped logging".)rotatelogs
for this purpose. For example, to rotate the logs every 24 hours, you
can use:
CustomLog "|/usr/local/apache/bin/rotatelogs
/var/log/access_log 86400" common
Virtual Hosts
<VirtualHost> sections in the
main server context, it is possible to log all requests in the
same access log and error log. This technique does not allow
for easy collection of statistics on individual virtual
hosts.CustomLog
or ErrorLog
directives are placed inside a
<VirtualHost>
section, all requests or errors for that virtual host will be
logged only to the specified file. Any virtual host which does
not have logging directives will still have its requests sent
to the main server logs. This technique is very useful for a
small number of virtual hosts, but if the number of hosts is
very large, it can be complicated to manage. In addition, it
can often create problems with insufficient file
descriptors.
LogFormat "%v %l %u %t \"%r\" %>s %b"
comonvhost
CustomLog logs/access_log comonvhost
%v is used to log the name of the virtual
host that is serving the request. Then a program like split-logfile can be used to
post-process the access log in order to split it into one file
per virtual host.
Other Log Files
Related Modules Related Directives PID File
logs/httpd.pid. This
filename can be changed with the PidFile directive. The
process-id is for use by the administrator in restarting and
terminating the daemon by sending signals to the parent
process; on Windows, use the -k command line option instead.
For more information see the Stopping
and Restarting page.Script Log
ScriptLog directive
allows you to record the input to and output from CGI scripts.
This should only be used in testing - not for live servers.
More information is available in the mod_cgi documentation.Rewrite Log
RewriteLog to help
in debugging. This log file produces a detailed analysis of how
the rewriting engine transforms requests. The level of detail
is controlled by the RewriteLogLevel directive.
misc/descriptors.html 100644 0 0 27306 11074462673 12431 0 ustar 0 0
International Customized Server Error Messages
Warning:
mod_include to return
error messages generated by the server in the client's native
language.
Introduction
ErrorDocument messages
can share a homogenous and consistent style and layout, and
maintenance work (changing images, changing links) is kept to a
minimum because all layout information can be kept in a single
file.
![[Needs graphics capability to display]](../images/custom_errordocs.gif)
Creating an ErrorDocument directory
Options, we
enable the language selection of the most appropriate
language alternative (content negotiation).LanguagePriority
directive we define a set of default fallback languages in
the situation where the client's browser did not express any
preference at all.mod_include
(and disallowing execution of cgi scripts for
security reasons), we allow the server to include building
blocks of the error message, and to substitute the value of
certain environment variables into the generated document
(dynamic HTML) or even to conditionally include or omit parts
of the text.AddHandler and AddType directives
are useful for automatically SSI-expanding all files with a
.shtml suffix to text/html.Alias directive, we
keep the error document directory outside of the document
tree because it can be regarded more as a server part than
part of the document tree.<Directory> block
restricts these "special" settings to the error document
directory and avoids an impact on any of the settings for the
regular document tree.src/main/http_protocol.c if you wish to see
apache's standard messages), an ErrorDocument in
the aliased /errordocs directory is defined.
Note that we only define the basename of the document here
because the MultiViews option will select the best candidate
based on the language suffixes and the client's preferences.
Any error situation with an error code not handled
by a custom document will be dealt with by the server in the
standard way (i.e., a plain error message in
english).AllowOverride directive tells
apache that it is not necessary to look for a .htaccess file
in the /errordocs directory: a minor speed optimization.httpd.conf configuration would then
look similar to this:Note
Note that you can define your own
error messages using this method for only part of the document
tree, e.g., a /~user/ subtree. In this case, the configuration
could as well be put into the .htaccess file at the root of the
subtree, and the <Directory> and </Directory>
directives -but not the contained directives- must be
omitted.
LanguagePriority en fr de
Alias /errordocs /usr/local/apache/errordocs
<Directory /usr/local/apache/errordocs>
AllowOverride none
Options MultiViews IncludesNoExec FollowSymLinks
AddType text/html .shtml
<FilesMatch "\.shtml[.$]">
SetOutputFilter INCLUDES
</FilesMatch>
</Directory>
# "400 Bad Request",
ErrorDocument 400 /errordocs/400
# "401 Authorization Required",
ErrorDocument 401 /errordocs/401
# "403 Forbidden",
ErrorDocument 403 /errordocs/403
# "404 Not Found",
ErrorDocument 404 /errordocs/404
# "500 Internal Server Error",
ErrorDocument 500 /errordocs/500
/usr/local/apache/errordocs/) must then be created
with the appropriate permissions (readable and executable by
the server uid or gid, only writable for the administrator).Naming the Individual Error Document files
MultiViews option, the server was
told to automatically scan the directory for matching variants
(looking at language and content type suffixes) when a
requested document was not found. In the configuration, we
defined the names for the error documents to be just their
error number (without any suffix).
errordocs/403.shtml.lang is created and
filled with the error text in that language (see below).errordocs/403.shtml is created, usually by
creating a symlink to the default language variant (see below).The Common Header and Footer Files
title.head.shtml because it contains server-parsed
content but no language specific information. The footer file
exists once for each language translation, plus a symlink for
the default language.
for English, French and German versions (default english)
foot.shtml.en,
foot.shtml.fr,
foot.shtml.de,
foot.shtml symlink to
foot.shtml.en
<!--#include virtual="head" -->
and <!--#include virtual="foot" -->
respectively: the rest of the magic occurs in mod_negotiation
and in mod_include.Creating ErrorDocuments in Different Languages
<!--#set var="title" value="error description title" -->
<!--#include virtual="head" -->
explanatory error text
<!--#include virtual="foot" -->
The Fallback Language
for f in *.shtml.en
do
ln -s $f `basename $f .en`
done
Customizing Proxy Error Messages
ErrorDocument mechanism for proxy error messages
as well (previous versions always returned fixed predefined
error messages).ERROR_NOTES CGI
environment variable: if invoked for a proxy error, this
variable will contain the actual proxy error message text in
HTML form.ERROR_NOTES variable within an error document:
<!--#if expr="$REDIRECT_ERROR_NOTES = ''" -->
<p>
The server encountered an unexpected condition
which prevented it from fulfilling the request.
</p>
<p>
<a href="mailto:<!--#echo var="SERVER_ADMIN" -->"
SUBJECT="Error message [<!--#echo var="REDIRECT_STATUS" -->] <!--#echo var="title" --> for <!--#echo var="REQUEST_URI" -->">
Please forward this error screen to <!--#echo var="SERVER_NAME" -->'s
WebMaster</a>; it includes useful debugging information about
the Request which caused the error.
<pre><!--#printenv --></pre>
</p>
<!--#else -->
<!--#echo var="REDIRECT_ERROR_NOTES" -->
<!--#endif -->
HTML Listing of the Discussed Example
400.shtml.en document. You will notice that it
contains almost nothing but the error text (with conditional
additions). Starting with this example, you will find it easy
to add more error documents, or to translate the error
documents to different languages.
<!--#set var="title" value="Bad Request"-->
<!--#include virtual="head" -->
<p>
Your browser sent a request that this server could not understand:
<blockquote>
<strong><!--#echo var="REQUEST_URI" --></strong>
</blockquote>
The request could not be understood by the server due to malformed
syntax. The client should not repeat the request without
modifications.
</p>
<p>
<!--#if expr="$HTTP_REFERER != ''" -->
Please inform the owner of
<a href="<!--#echo var="HTTP_REFERER" -->">the referring page</a> about
the malformed link.
<!--#else -->
Please check your request for typing errors and retry.
<!--#endif -->
</p>
<!--#include virtual="foot" -->
head.shtml.en file (the funny
line breaks avoid empty lines in the document after SSI
processing). Note the configuration section at top. That's
where you configure the images and logos as well as the apache
documentation directory. Look how this file displays two
different logos depending on the content of the virtual host
name ($SERVER_NAME), and that an animated apache logo is shown
if the browser appears to support it (the latter requires
server configuration lines of the form BrowserMatch "^Mozilla/[2-4]" anigif
<!--#if expr="$SERVER_NAME = /.*\.mycompany\.com/" -->
<!--#set var="IMG_CorpLogo" value="http://$SERVER_NAME:$SERVER_PORT/errordocs/CorpLogo.gif" -->
<!--#set var="ALT_CorpLogo" value="Powered by Linux!" -->
<!--#else -->
<!--#set var="IMG_CorpLogo" value="http://$SERVER_NAME:$SERVER_PORT/errordocs/PrivLogo.gif" -->
<!--#set var="ALT_CorpLogo" value="Powered by Linux!" -->
<!--#endif-->
<!--#set var="IMG_BgImage" value="http://$SERVER_NAME:$SERVER_PORT/errordocs/BgImage.gif" -->
<!--#set var="DOC_Apache" value="http://$SERVER_NAME:$SERVER_PORT/Apache/" -->
<!--#if expr="$anigif" -->
<!--#set var="IMG_Apache" value="http://$SERVER_NAME:$SERVER_PORT/icons/apache_anim.gif" -->
<!--#else-->
<!--#set var="IMG_Apache" value="http://$SERVER_NAME:$SERVER_PORT/icons/apache_pb.gif" -->
<!--#endif-->
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
<head>
<title>
[<!--#echo var="REDIRECT_STATUS" -->] <!--#echo var="title" -->
</title>
</head>
<body bgcolor="white" background="<!--#echo var="IMG_BgImage" -->">
<h1 align="center">
[<!--#echo var="REDIRECT_STATUS" -->]
<!--#echo var="title" -->
<img src="<!--#echo var="IMG_CorpLogo" -->"
alt="<!--#echo var="ALT_CorpLogo" -->" align="right">
</h1>
<hr />
<!-- ======================================================== -->
<div>
foot.shtml.en file:
</div>
<hr />
<div align="right">
<small>Local Server time:
<!--#echo var="DATE_LOCAL" --></small>
</div>
<div align="center">
<a href="<!--#echo var="DOC_Apache" -->">
<img src="<!--#echo var="IMG_Apache" -->" border="0" align="bottom"
alt="Powered by <!--#echo var="SERVER_SOFTWARE" -->"></a>
<br />
<small><!--#set var="var" value="Powered by $SERVER_SOFTWARE --
File last modified on $LAST_MODIFIED" -->
<!--#echo var="var" --></small>
</div>
<p>If the indicated error looks like a misconfiguration, please inform
<a href="mailto:<!--#echo var="SERVER_ADMIN" -->"
subject="Feedback about Error message [<!--#echo var="REDIRECT_STATUS" -->]
<!--#echo var="title" -->, req=<!--#echo var="REQUEST_URI" -->">
<!--#echo var="SERVER_NAME" -->'s WebMaster</a>.
</p>
</body>
</html>
misc/fin_wait_2.html 100644 0 0 47302 11074462673 12107 0 ustar 0 0
Descriptors and Apache
Warning:
stdin, stdout, and
stderr which are descriptors 0, 1, and 2
respectively. Apache needs a descriptor for each log file, plus
one for each network socket that it listens on, plus a handful
of others. Libraries that Apache uses may also require
descriptors. Normal programs don't open up many descriptors at
all, and so there are some latent problems that you may
experience should you start running Apache with many
descriptors (i.e., with many virtual hosts).
#open files <= soft limit <= hard limit <= kernel limit
limit (csh) or ulimit (sh)
directives. See the respective man pages for more information.
For example you can probably use ulimit -n
unlimited to raise your soft limit up to the hard limit.
You should include this command in a shell script which starts
your webserver.
BSDI 2.0
-DFD_SETSIZE=nnn to
EXTRA_CFLAGS (where nnn is the number of
descriptors you wish to support, keep it less than the hard
limit). But it will run into trouble if more than
approximately 240 Listen directives are used. This may be
cured by rebuilding your kernel with a higher
FD_SETSIZE.
FreeBSD 2.2, BSDI 2.1+
FD_SETSIZE and rebuild. But the extra Listen
limitation doesn't exist.
Linux
Solaris through 2.5.1
-DHIGH_SLACK_LINE=256 added to
EXTRA_CFLAGS. You will be limited to
approximately 240 error logs if you do this.
AIX
SCO OpenServer
/etc/conf/cf.d/stune file or use
/etc/conf/cf.d/configure choice 7 (User and
Group configuration) and modify the NOFILES
kernel parameter to a suitably higher value. SCO recommends a
number between 60 and 11000, the default is 110. Relink and
reboot, and the new number of descriptors will be
available.
Compaq Tru64 UNIX/Digital UNIX/OSF
open_max_soft and
open_max_hard to 4096 in the proc subsystem.
Do a man on sysconfig, sysconfigdb, and
sysconfigtab.max-vnodes to a large number which
is greater than the number of apache processes * 4096
(Setting it to 250,000 should be good for most people).
Do a man on sysconfig, sysconfigdb, and
sysconfigtab.NO_SLACK to work around a bug in the OS.
CFLAGS="-DNO_SLACK" ./configure
Others
LOW_SLACK_LINE and there's a tiny bit of
documentation in the header file httpd.h.-DNO_SLACK
to EXTRA_CFLAGS and rebuild. But please report it
to our Bug
Report Page so that we can investigate.
misc/index.html 100644 0 0 11470 11074462673 11172 0 ustar 0 0
Connections in the FIN_WAIT_2 state and Apache
Warning:
netstat) than they saw using older
versions. When the server closes a TCP connection, it sends
a packet with the FIN bit set to the client, which then
responds with a packet with the ACK bit set. The client
then sends a packet with the FIN bit set to the server,
which responds with an ACK and the connection is closed.
The state that the connection is in during the period
between when the server gets the ACK from the client and
the server gets the FIN from the client is known as
FIN_WAIT_2. See the TCP RFC for
the technical details of the state transitions.
Why Does It Happen?
Buggy Clients and Persistent
Connections
KeepAliveTimeout),
the client is programmed so that the client does not send
back a FIN and ACK to the server. This means that the
connection stays in the FIN_WAIT_2 state until one of the
following happens:
A necessary bit of code
introduced in 1.2
lingering_close() which was
added between 1.1 and 1.2. This function is necessary for
the proper handling of persistent connections and any
request which includes content in the message body
(e.g., PUTs and POSTs). What it does is read any
data sent by the client for a certain time after the server
closes the connection. The exact reasons for doing this are
somewhat complicated, but involve what happens if the
client is making a request at the same time the server
sends a response and closes the connection. Without
lingering, the client might be forced to reset its TCP
input buffer before it has a chance to read the server's
response, and thus understand why the connection has
closed. See the appendix for more
details.lingering_close() appears to
cause problems for a number of factors, including the
change in traffic patterns that it causes. The code has
been thoroughly reviewed and we are not aware of any bugs
in it. It is possible that there is some problem in the BSD
TCP stack, aside from the lack of a timeout for the
FIN_WAIT_2 state, exposed by the
lingering_close code that causes the observed
problems.
What Can I Do About it?
Add a timeout for FIN_WAIT_2
ndd to modify
tcp_fin_wait_2_flush_interval, but the
default should be appropriate for most servers and
improper tuning can have negative impacts.SO_LINGER socket option which is enabled by
Apache. This parameter can be adjusted by using
nettune to modify parameters such as
tcp_keepstart and tcp_keepstop.
In later revisions, there is an explicit timer for
connections in FIN_WAIT_2 that can be modified; contact
HP support for details.
Compile without using
lingering_close()lingering_close() function. This will result
in that section of code being similar to that which was in
1.1. If you do this, be aware that it can cause problems
with PUTs, POSTs and persistent connections, especially if
the client uses pipelining. That said, it is no worse than
on 1.1, and we understand that keeping your server running
is quite important.lingering_close()
function, add -DNO_LINGCLOSE to the end of the
EXTRA_CFLAGS line in your
Configuration file, rerun
Configure and rebuild the server.Use
SO_LINGER as
an alternative to lingering_close()SO_LINGER that can be set with
setsockopt(2). It does something very similar
to lingering_close(), except that it is broken
on many systems so that it causes far more problems than
lingering_close. On some systems, it could
possibly work better so it may be worth a try if you have
no other alternatives.-DUSE_SO_LINGER
-DNO_LINGCLOSE to the end of the
EXTRA_CFLAGS line in your
Configuration file, rerun
Configure and rebuild the server.NOTE
Attempting to use
SO_LINGER and lingering_close()
at the same time is very likely to do very bad things, so
don't.Increase the amount of memory
used for storing connection state
NMBCLUSTERS="n", where
n is the number of mbuf clusters you want
to your kernel config file and rebuilding your
kernel.Disable KeepAlive
Appendix
Why the lingering close
functionality is necessary with HTTP
misc/known_client_problems.html 100644 0 0 50431 11074462673 14460 0 ustar 0 0
Apache Miscellaneous Documentation
Warning
FIN_WAIT_2FIN_WAIT_2 state, and what you can do
about it.mod_rewrite
reference documentation.
It describes how one can use Apache's mod_rewrite
to solve typical URL-based problems webmasters are usually confronted
with in practice.
misc/perf-tuning.html 100644 0 0 144003 11074462673 12340 0 ustar 0 0
Known Problems in Clients
Warning:
mod_browser. Unless
otherwise noted all of these workarounds exist in versions 1.2
and later. Trailing CRLF on POSTs Broken KeepAlive Incorrect interpretation of
HTTP/1.1 in response Requests use HTTP/1.1 but
responses must be in HTTP/1.0 Boundary problems with
header parsing Multipart responses and
Quoted Boundary Strings Byterange Requests Set-Cookie header is
unmergeable Expires headers
and GIF89A animations POST without
Content-Length JDK 1.2 betas lose
parts of responses. Content-Type
change is not noticed after reload MSIE Cookie
problem with expiry date in the year 2000 Lynx incorrectly asking for
transparent content negotiation MSIE 4.0 mishandles Vary
response header
Trailing CRLF on POSTs
POST data to have an extra CRLF
following it. Thus many clients send an extra CRLF
that is not included in the Content-Length of the
request. Apache works around this problem by eating any empty
lines which appear before a request.
Broken KeepAlive
BrowserMatch Mozilla/2 nokeepalive
nokeepalive code prior to 1.2.2 would not work
with HTTP/1.1 clients. You must apply
this patch to version 1.2.1. Then add this to your
config:
BrowserMatch "MSIE 4\.0b2;" nokeepalive
Incorrect interpretation of
HTTP/1.1 in response
HTTP uses a "<MAJOR>.<MINOR>" numbering scheme to
indicate versions of the protocol. The protocol versioning
policy is intended to allow the sender to indicate the format
of a message and its capacity for understanding further HTTP
communication, rather than the features obtained via that
communication.
force-response-1.0 environment variable was added
to Apache. When present Apache will indicate "HTTP/1.0" in
response to an HTTP/1.0 client, but will not in any other way
change the response.
BrowserMatch Java/1.0 force-response-1.0
BrowserMatch JDK/1.0 force-response-1.0
User-Agent
as version 4.0. The workaround is still:
BrowserMatch "RealPlayer 4.0" force-response-1.0
Requests use HTTP/1.1 but
responses must be in HTTP/1.0
BrowserMatch "MSIE 4\.0b2;" downgrade-1.0
force-response-1.0
Boundary problems with
header parsing
Multipart responses and
Quoted Boundary Strings
Byterange Requests
Request-Range, and a response type
multipart/x-byteranges. The HTTP/1.1 standard
includes this draft with a few fixes, and it defines the header
Range and type
multipart/byteranges.Range
and Request-Range headers (with the same value),
but does not accept a multipart/byteranges
response. The response must be
multipart/x-byteranges. As a workaround, if Apache
receives a Request-Range header it considers it
"higher priority" than a Range header and in
response uses multipart/x-byteranges.multipart/x-byterange response. Unfortunately
there is no clue that it is the plugin making the request. If
the plugin is used with Navigator, the above workaround works
fine. But if the plugin is used with MSIE 3 (on Windows) the
workaround won't work because MSIE 3 doesn't give the
Range-Request clue that Navigator does. To
workaround this, Apache special cases "MSIE 3" in the
User-Agent and serves
multipart/x-byteranges. Note that the necessity
for this with MSIE 3 is actually due to the Acrobat plugin, not
due to the browser.Request-Range header. When an Acrobat plugin prior
to version 3.01 is used with it, it will not properly
understand byteranges. The user must upgrade their Acrobat
reader to 3.01.
Set-Cookie header is
unmergeableSet-Cookie header is sent
separately. When parsing the headers returned by a CGI, Apache
will explicitly avoid merging any Set-Cookie
headers.
Expires headers
and GIF89A animationsExpires header. This happens
regardless of how far in the future the expiry time is set.
There is no workaround supplied with Apache, however there are
hacks for
1.2 and for
1.3.
POST without
Content-Length
JDK 1.2 betas lose
parts of responses.
BrowserMatch "Java1\.2beta[23]" nokeepalive
Content-Type
change is not noticed after reloadcontent-type for an object "forever". Using reload
or shift-reload will not cause Navigator to notice a
content-type change. The only work-around is for
the user to flush their caches (memory and disk). By way of an
example, some folks may be using an old mime.types
file which does not map .htm to
text/html, in this case Apache will default to
sending text/plain. If the user requests the page
and it is served as text/plain. After the admin
fixes the server, the user will have to flush their caches
before the object will be shown with the correct
text/html type.
MSIE Cookie
problem with expiry date in the year 2000
Lynx incorrectly asking for
transparent content negotiation
MSIE 4.0 mishandles Vary
response header
BrowserMatch "MSIE 4\.0" force-no-vary
misc/relevant_standards.html 100644 0 0 21375 11074462673 13753 0 ustar 0 0
Apache Performance Tuning
Hardware and Operating System Issues
MaxClients setting so that your server
does not spawn so many children it starts swapping. This procedure
for doing this is simple: determine the size of your average Apache
process, by looking at your process list via a tool such as
top, and divide this into your total available memory,
leaving some room for other processes.
sendfile(2) system
call, make sure you install the release and/or patches
needed to enable it. (With Linux, for example, this means
using Linux 2.4 or later. For early releases of Solaris 8,
you may need to apply a patch.) On systems where it is
available, sendfile enables Apache 2 to deliver
static content faster and with lower CPU utilization.
Run-Time Configuration Issues
Related Modules Related Directives HostnameLookups and other DNS considerations
HostnameLookups defaulted to On.
This adds latency to every request because it requires a
DNS lookup to complete before the request is finished. In
Apache 1.3 this setting defaults to Off. If you need
to have addresses in your log files resolved to hostnames, use the
logresolve
program that comes with Apache, or one of the numerous log
reporting packages which are available.Allow
from domainDeny from domain<Location /server-status> section.
In this case the DNS lookups are only performed on requests
matching the criteria. Here's an example which disables lookups
except for .html and .cgi files:
HostnameLookups off
<Files ~ "\.(html|cgi)$">
HostnameLookups on
</Files>
gethostbyname call in the
specific CGIs that need it.FollowSymLinks and SymLinksIfOwnerMatch
Options
FollowSymLinks, or you do have an Options
SymLinksIfOwnerMatch Apache will have to issue extra
system calls to check up on symlinks. One extra call per
filename component. For example, if you had:
DocumentRoot /www/htdocs
<Directory />
Options SymLinksIfOwnerMatch
</Directory>
/index.html.
Then Apache will perform lstat(2) on
/www, /www/htdocs, and
/www/htdocs/index.html. The results of these
lstats are never cached, so they will occur on
every single request. If you really desire the symlinks
security checking you can do something like this:
DocumentRoot /www/htdocs
<Directory />
Options FollowSymLinks
</Directory>
<Directory /www/htdocs>
Options -FollowSymLinks +SymLinksIfOwnerMatch
</Directory>
DocumentRoot path.
Note that you'll need to add similar sections if you
have any Alias or
RewriteRule paths
outside of your document root. For highest performance,
and no symlink protection, set FollowSymLinks
everywhere, and never set SymLinksIfOwnerMatch.AllowOverride
.htaccess files) Apache will attempt to open
.htaccess for each filename component. For
example,
DocumentRoot /www/htdocs
<Directory />
AllowOverride all
</Directory>
/index.html.
Then Apache will attempt to open /.htaccess,
/www/.htaccess, and
/www/htdocs/.htaccess. The solutions are similar
to the previous case of Options FollowSymLinks.
For highest performance use AllowOverride None
everywhere in your filesystem.Negotiation
DirectoryIndex index
DirectoryIndex index.cgi index.pl index.shtml index.html
type-map
file provides better performance than using
MultiViews, as the necessary information can be
determined by reading this single file, rather than having to
scan the directory for files.type-map files, rather than the Options
MultiViews directive to accomplish the negotiation. See the
Content Negotiation
documentation for a full discussion of the methods of negotiation,
and instructions for creating type-map files.Memory-mapping
mmap(2).
mmap does not scale
as well as read(2) when the number of CPUs increases.
On multiprocessor Solaris servers, for example, Apache 2.x sometimes
delivers server-parsed files faster when mmap is disabled.EnableMMAP off to disable the memory-mapping
of delivered files. (Note: This directive can be overridden on
a per-directory basis.)Sendfile
sendfile(2) operation.
EnableSendfile off to disable sendfile
delivery of file contents. (Note: This directive can be overridden
on a per-directory basis.)Process Creation
MinSpareServers, MaxSpareServers, and StartServers settings all had drastic effects on
benchmark results. In particular, Apache required a "ramp-up"
period in order to reach a number of children sufficient to serve
the load being applied. After the initial spawning of
StartServers children,
only one child per second would be created to satisfy the
MinSpareServers
setting. So a server being accessed by 100 simultaneous
clients, using the default StartServers of 5 would take on
the order 95 seconds to spawn enough children to handle
the load. This works fine in practice on real-life servers,
because they aren't restarted frequently. But does really
poorly on benchmarks which might only run for ten minutes.MinSpareServers
setting.MinSpareServers, MaxSpareServers and StartServers knobs. When more than 4 children are
spawned per second, a message will be emitted to the
ErrorLog. If you
see a lot of these errors then consider tuning these settings.
Use the mod_status output as a guide.MaxRequestsPerChild
setting. By default this is 0,
which means that there is no limit to the number of requests
handled per child. If your configuration currently has this set
to some very low number, such as 30, you may want to bump this
up significantly. If you are running SunOS or an old version of
Solaris, limit this to 10000 or so because of memory leaks.KeepAliveTimeout of 15
seconds attempts to minimize this effect. The tradeoff here is
between network bandwidth and server resources. In no event
should you raise this above about 60 seconds, as
most of the benefits are lost.
Compile-Time Configuration Issues
Choosing an MPM
beos, mpm_netware,
mpmt_os2, and mpm_winnt. For
general Unix-type systems, there are several MPMs from which
to choose. The choice of MPM can affect the speed and scalability
of the httpd:
worker MPM uses multiple child
processes with many threads each. Each thread handles
one connection at a time. Worker generally is a good
choice for high-traffic servers because it has a smaller
memory footprint than the prefork MPM.prefork MPM uses multiple child
processes with one thread each. Each process handles
one connection at a time. On many systems, prefork is
comparable in speed to worker, but it uses more memory.
Prefork's threadless design has advantages over worker
in some situations: it can be used with non-thread-safe
third-party modules, and it is easier to debug on platforms
with poor thread debugging support.Modules
LoadModule directive for that module.
This allows you to experiment with removing modules, and seeing
if your site still functions in their absense.mod_mime, mod_dir,
and mod_log_config. mod_log_config is,
of course, optional, as you can run a web site without log
files. This is, however, not recommended.Atomic Operations
mod_cache and
recent development builds of the worker MPM, use APR's
atomic API. This API provides atomic operations that can
be used for lightweight thread synchronization.--enable-nonportable-atomics option:
./buildconf
./configure --with-mpm=worker --enable-nonportable-atomics=yes
--enable-nonportable-atomics option is
relevant for the following platforms:
By default, APR uses mutex-based atomics on Solaris/SPARC.
If you configure with --enable-nonportable-atomics,
however, APR generates code that uses a SPARC v8plus opcode for
fast hardware compare-and-swap. If you configure Apache with
this option, the atomic operations will be more efficient
(allowing for lower CPU utilization and higher concurrency),
but the resulting executable will run only on UltraSPARC
chips.
By default, APR uses mutex-based atomics on Linux. If you
configure with --enable-nonportable-atomics,
however, APR generates code that uses a 486 opcode for fast
hardware compare-and-swap. This will result in more efficient
atomic operations, but the resulting executable will run only
on 486 and later chips (and not on 386).
mod_status and ExtendedStatus On
mod_status and you also set
ExtendedStatus On when building and running
Apache, then on every request Apache will perform two calls to
gettimeofday(2) (or times(2)
depending on your operating system), and (pre-1.3) several
extra calls to time(2). This is all done so that
the status report contains timing indications. For highest
performance, set ExtendedStatus off (which is the
default).accept Serialization - multiple sockets
Warning:
Listen statements to listen on either multiple
ports or multiple addresses. In order to test each socket
to see if a connection is ready Apache uses
select(2). select(2) indicates that a
socket has zero or at least one connection
waiting on it. Apache's model includes multiple children, and
all the idle ones test for new connections at the same time. A
naive implementation looks something like this (these examples
do not match the code, they're contrived for pedagogical
purposes):
for (;;) {
for (;;) {
fd_set accept_fds;
FD_ZERO (&accept_fds);
for (i = first_socket; i <= last_socket; ++i) {
FD_SET (i, &accept_fds);
}
rc = select (last_socket+1, &accept_fds, NULL, NULL, NULL);
if (rc < 1) continue;
new_connection = -1;
for (i = first_socket; i <= last_socket; ++i) {
if (FD_ISSET (i, &accept_fds)) {
new_connection = accept (i, NULL, NULL);
if (new_connection != -1) break;
}
}
if (new_connection != -1) break;
}
process the new_connection;
}
select when they are in between requests. All
those blocked children will awaken and return from
select when a single request appears on any socket
(the number of children which awaken varies depending on the
operating system and timing issues). They will all then fall
down into the loop and try to accept the
connection. But only one will succeed (assuming there's still
only one connection ready), the rest will be blocked
in accept. This effectively locks those children
into serving requests from that one socket and no other
sockets, and they'll be stuck there until enough new requests
appear on that socket to wake them all up. This starvation
problem was first documented in PR#467. There
are at least two solutions.accept won't block the children, and they
will be allowed to continue immediately. But this wastes CPU
time. Suppose you have ten idle children in
select, and one connection arrives. Then nine of
those children will wake up, try to accept the
connection, fail, and loop back into select,
accomplishing nothing. Meanwhile none of those children are
servicing requests that occurred on other sockets until they
get back up to the select again. Overall this
solution does not seem very fruitful unless you have as many
idle CPUs (in a multiprocessor box) as you have idle children,
not a very likely situation.
for (;;) {
accept_mutex_on ();
for (;;) {
fd_set accept_fds;
FD_ZERO (&accept_fds);
for (i = first_socket; i <= last_socket; ++i) {
FD_SET (i, &accept_fds);
}
rc = select (last_socket+1, &accept_fds, NULL, NULL, NULL);
if (rc < 1) continue;
new_connection = -1;
for (i = first_socket; i <= last_socket; ++i) {
if (FD_ISSET (i, &accept_fds)) {
new_connection = accept (i, NULL, NULL);
if (new_connection != -1) break;
}
}
if (new_connection != -1) break;
}
accept_mutex_off ();
process the new_connection;
}
accept_mutex_on and accept_mutex_off
implement a mutual exclusion semaphore. Only one child can have
the mutex at any time. There are several choices for
implementing these mutexes. The choice is defined in
src/conf.h (pre-1.3) or
src/include/ap_config.h (1.3 or later). Some
architectures do not have any locking choice made, on these
architectures it is unsafe to use multiple
Listen
directives.AcceptMutex can be used to
change the selected mutex implementation at run-time.
AcceptMutex flockflock(2) system call to
lock a lock file (located by the LockFile directive).AcceptMutex fcntlfcntl(2) system call to
lock a lock file (located by the LockFile directive).AcceptMutex sysvsemipcs(8) man page). The other is that the
semaphore API allows for a denial of service attack by any
CGIs running under the same uid as the webserver
(i.e., all CGIs, unless you use something like
suexec or cgiwrapper). For these
reasons this method is not used on any architecture except
IRIX (where the previous two are prohibitively expensive
on most IRIX boxes).AcceptMutex pthreadAcceptMutex posixsemListen
statements if you want the highest performance.
But read on.accept Serialization - single socket
accept(2) until a connection
arrives, and no starvation results. In practice this hides
almost the same "spinning" behaviour discussed above in the
non-blocking solution. The way that most TCP stacks are
implemented, the kernel actually wakes up all processes blocked
in accept when a single connection arrives. One of
those processes gets the connection and returns to user-space,
the rest spin in the kernel and go back to sleep when they
discover there's no connection for them. This spinning is
hidden from the user-land code, but it's there nonetheless.
This can result in the same load-spiking wasteful behaviour
that a non-blocking solution to the multiple sockets case
can.SINGLE_LISTEN_UNSERIALIZED_ACCEPT and then
single-socket servers will not serialize at all.Lingering Close
FIN_WAIT_2 state has a timeout, but it doesn't prohibit it.
On systems without the timeout, Apache 1.2 induces many sockets
stuck forever in the FIN_WAIT_2 state. In many cases this
can be avoided by simply upgrading to the latest TCP/IP patches
supplied by the vendor. In cases where the vendor has never
released patches (i.e., SunOS4 -- although folks with
a source license can patch it themselves) we have decided to
disable this feature.SO_LINGER. But as fate would have it, this
has never been implemented properly in most TCP/IP stacks. Even
on those stacks with a proper implementation (i.e.,
Linux 2.0.31) this method proves to be more expensive (cputime)
than the next solution.lingering_close (in
http_main.c). The function looks roughly like
this:
void lingering_close (int s)
{
char junk_buffer[2048];
/* shutdown the sending side */
shutdown (s, 1);
signal (SIGALRM, lingering_death);
alarm (30);
for (;;) {
select (s for reading, 2 second timeout);
if (error) break;
if (s is ready for reading) {
if (read (s, junk_buffer, sizeof (junk_buffer)) <= 0) {
break;
}
/* just toss away whatever is here */
}
}
close (s);
}
NO_LINGCLOSE, but this is not recommended at all.
In particular, as HTTP/1.1 pipelined persistent connections
come into use lingering_close is an absolute
necessity (and
pipelined connections are faster, so you want to support
them).Scoreboard File
src/main/conf.h file for your architecture and
look for either USE_MMAP_SCOREBOARD or
USE_SHMGET_SCOREBOARD. Defining one of those two
(as well as their companions HAVE_MMAP and
HAVE_SHMGET respectively) enables the supplied
shared memory code. If your system has another type of shared
memory, edit the file src/main/http_main.c and add
the hooks necessary to use it in Apache. (Send us back a patch
too please.)Historical note: The Linux port of Apache didn't start to
use shared memory until version 1.2 of Apache. This oversight
resulted in really poor and unreliable behaviour of earlier
versions of Apache on Linux.
DYNAMIC_MODULE_LIMIT
-DDYNAMIC_MODULE_LIMIT=0 when building your
server. This will save RAM that's allocated only for supporting
dynamically loaded modules.
Appendix: Detailed Analysis of a Trace
truss -l -p httpd_child_pid.
-l option tells truss to log the ID of the
LWP (lightweight process--Solaris's form of kernel-level thread)
that invokes each system call.strace, ktrace, or par.
They all produce similar output./67: accept(3, 0x00200BEC, 0x00200C0C, 1) (sleeping...)
/67: accept(3, 0x00200BEC, 0x00200C0C, 1) = 9
Note the lack of
accept(2) serialization. On this
particular platform, the worker MPM uses an unserialized accept by
default unless it is listening on multiple ports./65: lwp_park(0x00000000, 0) = 0
/67: lwp_unpark(65, 1) = 0
/65: getsockname(9, 0x00200BA4, 0x00200BC4, 1) = 0
Listen directives
are used which do not have wildcard addresses). But
no effort has yet been made to do these optimizations. /65: brk(0x002170E8) = 0
/65: brk(0x002190E8) = 0
brk(2) calls allocate memory from the heap.
It is rare to see these in a system call trace, because the httpd
uses custom memory allocators (apr_pool and
apr_bucket_alloc) for most request processing.
In this trace, the httpd has just been started, so it must
call malloc(3) to get the blocks of raw memory
with which to create the custom memory allocators./65: fcntl(9, F_GETFL, 0x00000000) = 2
/65: fstat64(9, 0xFAF7B818) = 0
/65: getsockopt(9, 65535, 8192, 0xFAF7B918, 0xFAF7B910, 2190656) = 0
/65: fstat64(9, 0xFAF7B818) = 0
/65: getsockopt(9, 65535, 8192, 0xFAF7B918, 0xFAF7B914, 2190656) = 0
/65: setsockopt(9, 65535, 8192, 0xFAF7B918, 4, 2190656) = 0
/65: fcntl(9, F_SETFL, 0x00000082) = 0
setsockopt(2)
and getsockopt(2) calls are a side-effect of how
Solaris's libc handles fcntl(2) on sockets./65: read(9, " G E T / 1 0 k . h t m".., 8000) = 97
/65: stat("/var/httpd/apache/httpd-8999/htdocs/10k.html", 0xFAF7B978) = 0
/65: open("/var/httpd/apache/httpd-8999/htdocs/10k.html", O_RDONLY) = 10Options FollowSymLinks
and AllowOverride None. Thus it doesn't need to
lstat(2) each directory in the path leading up to the
requested file, nor check for .htaccess files.
It simply calls stat(2) to verify that the file:
1) exists, and 2) is a regular file, not a directory./65: sendfilev(0, 9, 0x00200F90, 2, 0xFAF7B53C) = 10269
sendfilev(2)
system call. Sendfile semantics vary among operating systems. On some other
systems, it is necessary to do a write(2) or
writev(2) call to send the headers before calling
sendfile(2)./65: write(4, " 1 2 7 . 0 . 0 . 1 - ".., 78) = 78
write(2) call records the request in the
access log. Note that one thing missing from this trace is a
time(2) call. Unlike Apache 1.3, Apache 2.x uses
gettimeofday(3) to look up the time. On some operating
systems, like Linux or Solaris, gettimeofday has an
optimized implementation that doesn't require as much overhead
as a typical system call./65: shutdown(9, 1, 1) = 0
/65: poll(0xFAF7B980, 1, 2000) = 1
/65: read(9, 0xFAF7BC20, 512) = 0
/65: close(9) = 0
/65: close(10) = 0
/65: lwp_park(0x00000000, 0) (sleeping...)
/67: accept(3, 0x001FEB74, 0x001FEB94, 1) (sleeping...)
accept(2) can (and usually does, under
high load conditions) occur in parallel with the worker thread's handling
of the just-accepted connection.
misc/rewriteguide.html 100644 0 0 212615 11074462673 12606 0 ustar 0 0
Relevant Standards
Notice
HTTP Recommendations
HTML Recommendations
Authentication
Language/Country Codes
misc/security_tips.html 100644 0 0 42164 11074462673 12775 0 ustar 0 0
URL Rewriting Guide
Ralf S. Engelschall <rse@apache.org>
December 1997mod_rewrite
reference documentation.
It describes how one can use Apache's mod_rewrite
to solve typical URL-based problems with which webmasters are
commonony confronted. We give detailed descriptions on how to
solve each problem by configuring URL rewriting rulesets.
Introduction to
mod_rewritemod_rewrite is a killer
one, i.e. it is a really sophisticated module which provides
a powerful way to do URL manipulations. With it you can do nearly
all types of URL manipulations you ever dreamed about.
The price you have to pay is to accept complexity, because
mod_rewrite's major drawback is that it is
not easy to understand and use for the beginner. And even
Apache experts sometimes discover new aspects where
mod_rewrite can help.mod_rewrite you either
shoot yourself in the foot the first time and never use it again
or love it for the rest of your life because of its power.
This paper tries to give you a few initial success events to
avoid the first case by presenting already invented solutions
to you.
Practical Solutions
ATTENTION: Depending on your server-configuration
it can be necessary to slightly change the examples for your
situation, e.g. adding the
[PT] flag when
additionally using mod_alias and
mod_userdir, etc. Or rewriting a ruleset
to fit in .htaccess context instead
of per-server context. Always try to understand what a
particular ruleset really does before you use it. It
avoid problems.
URL Layout
Canonical URLs
/~user by the canonical
/u/user and fix a missing trailing slash for
/u/user.
RewriteRule ^/~([^/]+)/?(.*) /u/$1/$2 [R]
RewriteRule ^/([uge])/([^/]+)$ /$1/$2/ [R]
Canonical Hostnames
# For sites running on a port other than 80
RewriteCond %{HTTP_HOST} !^www\.example\.com [NC]
RewriteCond %{HTTP_HOST} !^$
RewriteCond %{SERVER_PORT} !^80$
RewriteRule ^/(.*) http://www.example.com:%{SERVER_PORT}/$1 [L,R]
# And for a site running on port 80
RewriteCond %{HTTP_HOST} !^www\.example\.com [NC]
RewriteCond %{HTTP_HOST} !^$
RewriteRule ^/(.*) http://www.example.com/$1 [L,R]
Moved
DocumentRoot
DocumentRoot
of the webserver directly relates to the URL "/".
But often this data is not really of top-level priority, it is
perhaps just one entity of a lot of data pools. For instance at
our Intranet sites there are /e/www/
(the homepage for WWW), /e/sww/ (the homepage for
the Intranet) etc. Now because the data of the DocumentRoot stays at /e/www/ we had
to make sure that all inlined images and other stuff inside this
data pool work for subsequent requests./ to
/e/www/:
RewriteEngine on
RewriteRule ^/$ /e/www/ [R]
RedirectMatch directive:
RedirectMatch ^/$ http://example.com/e/www/
Trailing Slash Problem
/~quux/foo instead of /~quux/foo/
then the server searches for a file named
foo. And because this file is a directory it
complains. Actually it tries to fix it itself in most of
the cases, but sometimes this mechanism need to be emulated
by you. For instance after you have done a lot of
complicated URL rewritings to CGI scripts etc.image.gif in
/~quux/foo/index.html would become
/~quux/image.gif without the external
redirect!
RewriteEngine on
RewriteBase /~quux/
RewriteRule ^foo$ foo/ [R]
.htaccess file of their homedir.
But notice that this creates some processing
overhead.
RewriteEngine on
RewriteBase /~quux/
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^(.+[^/])$ $1/ [R]
Webcluster through Homogeneous URL Layout
user1 server_of_user1
user2 server_of_user2
: :
map.xxx-to-host.
Second we need to instruct all servers to redirect URLs
of the forms
/u/user/anypath
/g/group/anypath
/e/entity/anypath
http://physical-host/u/user/anypath
http://physical-host/g/group/anypath
http://physical-host/e/entity/anypath
RewriteEngine on
RewriteMap user-to-host txt:/path/to/map.user-to-host
RewriteMap group-to-host txt:/path/to/map.group-to-host
RewriteMap entity-to-host txt:/path/to/map.entity-to-host
RewriteRule ^/u/([^/]+)/?(.*) http://${user-to-host:$1|server0}/u/$1/$2
RewriteRule ^/g/([^/]+)/?(.*) http://${group-to-host:$1|server0}/g/$1/$2
RewriteRule ^/e/([^/]+)/?(.*) http://${entity-to-host:$1|server0}/e/$1/$2
RewriteRule ^/([uge])/([^/]+)/?$ /$1/$2/.www/
RewriteRule ^/([uge])/([^/]+)/([^.]+.+) /$1/$2/.www/$3\
Move Homedirs to Different Webserver
mod_rewrite.
On the old webserver we just redirect all
/~user/anypath URLs to
http://newserver/~user/anypath.
RewriteEngine on
RewriteRule ^/~(.+) http://newserver/~$1 [R,L]
Structured Homedirs
/~foo/anypath
is /home/f/foo/.www/anypath
while /~bar/anypath is
/home/b/bar/.www/anypath.
RewriteEngine on
RewriteRule ^/~(([a-z])[a-z0-9]+)(.*) /home/$2/$1/.www$3
Filesystem Reorganization
RewriteRules to get a smooth look and feel
on the Web while its data structure is never touched or
adjusted. Background: net.sw is
my archive of freely available Unix software packages,
which I started to collect in 1992. It is both my hobby
and job to to this, because while I'm studying computer
science I have also worked for many years as a system and
network administrator in my spare time. Every week I need
some sort of software so I created a deep hierarchy of
directories where I stored the packages:
drwxrwxr-x 2 netsw users 512 Aug 3 18:39 Audio/
drwxrwxr-x 2 netsw users 512 Jul 9 14:37 Benchmark/
drwxrwxr-x 12 netsw users 512 Jul 9 00:34 Crypto/
drwxrwxr-x 5 netsw users 512 Jul 9 00:41 Database/
drwxrwxr-x 4 netsw users 512 Jul 30 19:25 Dicts/
drwxrwxr-x 10 netsw users 512 Jul 9 01:54 Graphic/
drwxrwxr-x 5 netsw users 512 Jul 9 01:58 Hackers/
drwxrwxr-x 8 netsw users 512 Jul 9 03:19 InfoSys/
drwxrwxr-x 3 netsw users 512 Jul 9 03:21 Math/
drwxrwxr-x 3 netsw users 512 Jul 9 03:24 Misc/
drwxrwxr-x 9 netsw users 512 Aug 1 16:33 Network/
drwxrwxr-x 2 netsw users 512 Jul 9 05:53 Office/
drwxrwxr-x 7 netsw users 512 Jul 9 09:24 SoftEng/
drwxrwxr-x 7 netsw users 512 Jul 9 12:17 System/
drwxrwxr-x 12 netsw users 512 Aug 3 20:15 Typesetting/
drwxrwxr-x 10 netsw users 512 Jul 9 14:08 X11/
/e/netsw/.www/ as follows:
-rw-r--r-- 1 netsw users 1318 Aug 1 18:10 .wwwacl
drwxr-xr-x 18 netsw users 512 Aug 5 15:51 DATA/
-rw-rw-rw- 1 netsw users 372982 Aug 5 16:35 LOGFILE
-rw-r--r-- 1 netsw users 659 Aug 4 09:27 TODO
-rw-r--r-- 1 netsw users 5697 Aug 1 18:01 netsw-about.html
-rwxr-xr-x 1 netsw users 579 Aug 2 10:33 netsw-access.pl
-rwxr-xr-x 1 netsw users 1532 Aug 1 17:35 netsw-changes.cgi
-rwxr-xr-x 1 netsw users 2866 Aug 5 14:49 netsw-home.cgi
drwxr-xr-x 2 netsw users 512 Jul 8 23:47 netsw-img/
-rwxr-xr-x 1 netsw users 24050 Aug 5 15:49 netsw-lsdir.cgi
-rwxr-xr-x 1 netsw users 1589 Aug 3 18:43 netsw-search.cgi
-rwxr-xr-x 1 netsw users 1885 Aug 1 17:41 netsw-tree.cgi
-rw-r--r-- 1 netsw users 234 Jul 30 16:35 netsw-unlimit.lst
DATA/ subdirectory holds the above
directory structure, i.e. the real
net.sw stuff and gets
automatically updated via rdist from time to
time. The second part of the problem remains: how to link
these two structures together into one smooth-looking URL
tree? We want to hide the DATA/ directory
from the user while running the appropriate CGI scripts
for the various URLs. Here is the solution: first I put
the following into the per-directory configuration file
in the DocumentRoot
of the server to rewrite the announced URL
/net.sw/ to the internal path
/e/netsw:
RewriteRule ^net.sw$ net.sw/ [R]
RewriteRule ^net.sw/(.*)$ e/netsw/$1
/e/netsw/.www/.wwwacl:
Options ExecCGI FollowSymLinks Includes MultiViews
RewriteEngine on
# we are reached via /net.sw/ prefix
RewriteBase /net.sw/
# first we rewrite the root dir to
# the handling cgi script
RewriteRule ^$ netsw-home.cgi [L]
RewriteRule ^index\.html$ netsw-home.cgi [L]
# strip out the subdirs when
# the browser requests us from perdir pages
RewriteRule ^.+/(netsw-[^/]+/.+)$ $1 [L]
# and now break the rewriting for local files
RewriteRule ^netsw-home\.cgi.* - [L]
RewriteRule ^netsw-changes\.cgi.* - [L]
RewriteRule ^netsw-search\.cgi.* - [L]
RewriteRule ^netsw-tree\.cgi$ - [L]
RewriteRule ^netsw-about\.html$ - [L]
RewriteRule ^netsw-img/.*$ - [L]
# anything else is a subdir which gets handled
# by another cgi script
RewriteRule !^netsw-lsdir\.cgi.* - [C]
RewriteRule (.*) netsw-lsdir.cgi/$1
L (last) flag and no
substitution field ('-') in the forth part! (not) character and
the C (chain) flag at the first rule
in the last partNCSA imagemap to Apache
mod_imap
imagemap program to work under Apache with the
modern mod_imap. The problem is that there
are a lot of hyperlinks around which reference the
imagemap program via
/cgi-bin/imagemap/path/to/page.map. Under
Apache this has to read just
/path/to/page.map.
RewriteEngine on
RewriteRule ^/cgi-bin/imagemap(.*) $1 [PT]
Search pages in more than one directory
RewriteEngine on
# first try to find it in custom/...
# ...and if found stop and be happy:
RewriteCond /your/docroot/dir1/%{REQUEST_FILENAME} -f
RewriteRule ^(.+) /your/docroot/dir1/$1 [L]
# second try to find it in pub/...
# ...and if found stop and be happy:
RewriteCond /your/docroot/dir2/%{REQUEST_FILENAME} -f
RewriteRule ^(.+) /your/docroot/dir2/$1 [L]
# else go on for other Alias or ScriptAlias directives,
# etc.
RewriteRule ^(.+) - [PT]
Set Environment Variables According To URL Parts
/foo/S=java/bar/ gets translated to
/foo/bar/ and the environment variable named
STATUS is set to the value "java".
RewriteEngine on
RewriteRule ^(.*)/S=([^/]+)/(.*) $1/$3 [E=STATUS:$2]
Virtual User Hosts
www.username.host.domain.com
for the homepage of username via just DNS A records to the
same machine and without any virtualhosts on this
machine.http://www.username.host.com/anypath
internally to /home/username/anypath:
RewriteEngine on
RewriteCond %{HTTP_HOST} ^www\.[^.]+\.host\.com$
RewriteRule ^(.+) %{HTTP_HOST}$1 [C]
RewriteRule ^www\.([^.]+)\.host\.com(.*) /home/$1$2
Redirect Homedirs For Foreigners
www.somewhere.com when the requesting user
does not stay in the local domain
ourdomain.com. This is sometimes used in
virtual host contexts.
RewriteEngine on
RewriteCond %{REMOTE_HOST} !^.+\.ourdomain\.com$
RewriteRule ^(/~.+) http://www.somewhere.com/$1 [R,L]
Redirect Failing URLs To Other Webserver
ErrorDocument CGI-scripts in Perl, but
there is also a mod_rewrite solution.
But notice that this performs more poorly than using an
ErrorDocument
CGI-script!
RewriteEngine on
RewriteCond /your/docroot/%{REQUEST_FILENAME} !-f
RewriteRule ^(.+) http://webserverB.dom/$1
DocumentRoot. While you can add more
Conditions (for instance to also handle homedirs, etc.)
there is better variant:
RewriteEngine on
RewriteCond %{REQUEST_URI} !-U
RewriteRule ^(.+) http://webserverB.dom/$1
mod_rewrite.
The result is that this will work for all types of URLs
and is a safe way. But it does a performance impact on
the webserver, because for every request there is one
more internal subrequest. So, if your webserver runs on a
powerful CPU, use this one. If it is a slow machine, use
the first approach or better a ErrorDocument CGI-script.Extended Redirection
url#anchor".
You cannot use this directly on redirects with
mod_rewrite because the
uri_escape() function of Apache
would also escape the hash character.
How can we redirect to such a URL?xredirect: by the following
per-server config-line (should be one of the last rewrite
rules):
RewriteRule ^xredirect:(.+) /path/to/nph-xredirect.cgi/$1 \
[T=application/x-httpd-cgi,L]
xredirect: to be piped through the
nph-xredirect.cgi program. And this program
just looks like:
#!/path/to/perl
##
## nph-xredirect.cgi -- NPH/CGI script for extended redirects
## Copyright (c) 1997 Ralf S. Engelschall, All Rights Reserved.
##
$| = 1;
$url = $ENV{'PATH_INFO'};
print "HTTP/1.0 302 Moved Temporarily\n";
print "Server: $ENV{'SERVER_SOFTWARE'}\n";
print "Location: $url\n";
print "Content-type: text/html\n";
print "\n";
print "<html>\n";
print "<head>\n";
print "<title>302 Moved Temporarily (EXTENDED)</title>\n";
print "</head>\n";
print "<body>\n";
print "<h1>Moved Temporarily (EXTENDED)</h1>\n";
print "The document has moved <a HREF=\"$url\">here</a>.<p>\n";
print "</body>\n";
print "</html>\n";
##EOF##
mod_rewrite.
For instance you can now also redirect to
news:newsgroup via
RewriteRule ^anyurl xredirect:news:newsgroup
Notice: You have not to put
[R] or
[R,L] to the above rule because the
xredirect: need to be expanded later
by our special "pipe through" rule above.Archive Access Multiplexer
mod_rewrite?mod_rewrite can
also use the "ftp:" scheme on redirects.
And second, the location approximation can be done by a
RewriteMap
over the top-level domain of the client.
With a tricky chained ruleset we can use this top-level
domain as a key to our multiplexing map.
RewriteEngine on
RewriteMap multiplex txt:/path/to/map.cxan
RewriteRule ^/CxAN/(.*) %{REMOTE_HOST}::$1 [C]
RewriteRule ^.+\.([a-zA-Z]+)::(.*)$ ${multiplex:$1|ftp.default.dom}$2 [R,L]
##
## map.cxan -- Multiplexing Map for CxAN
##
de ftp://ftp.cxan.de/CxAN/
uk ftp://ftp.cxan.uk/CxAN/
com ftp://ftp.cxan.com/CxAN/
:
##EOF##
Time-Dependent Rewriting
mod_rewrite?TIME_xxx
for rewrite conditions. In conjunction with the special
lexicographic comparison patterns <STRING,
>STRING and =STRING we can
do time-dependent redirects:
RewriteEngine on
RewriteCond %{TIME_HOUR}%{TIME_MIN} >0700
RewriteCond %{TIME_HOUR}%{TIME_MIN} <1900
RewriteRule ^foo\.html$ foo.day.html
RewriteRule ^foo\.html$ foo.night.html
foo.day.html
under the URL foo.html from
07:00-19:00 and at the remaining time the
contents of foo.night.html. Just a nice
feature for a homepage...Backward Compatibility for YYYY to XXXX migration
document.YYYY
to document.XXXX, e.g. after translating a
bunch of .html files to .phtml?
# backward compatibility ruleset for
# rewriting document.html to document.phtml
# when and only when document.phtml exists
# but no longer document.html
RewriteEngine on
RewriteBase /~quux/
# parse out basename, but remember the fact
RewriteRule ^(.*)\.html$ $1 [C,E=WasHTML:yes]
# rewrite to document.phtml if exists
RewriteCond %{REQUEST_FILENAME}.phtml -f
RewriteRule ^(.*)$ $1.phtml [S=1]
# else reverse the previous basename cutout
RewriteCond %{ENV:WasHTML} ^yes$
RewriteRule ^(.*)$ $1.html
Content Handling
From Old to New (intern)
foo.html to bar.html and now want
to provide the old URL for backward compatibility. Actually
we want that users of the old URL even not recognize that
the pages was renamed.
RewriteEngine on
RewriteBase /~quux/
RewriteRule ^foo\.html$ bar.html
From Old to New (extern)
foo.html to bar.html and now want
to provide the old URL for backward compatibility. But this
time we want that the users of the old URL get hinted to
the new one, i.e. their browsers Location field should
change, too.
RewriteEngine on
RewriteBase /~quux/
RewriteRule ^foo\.html$ bar.html [R]
Browser Dependent Content
foo.html
is rewritten to foo.NS.html and and the
rewriting stops. If the browser is "Lynx" or "Mozilla" of
version 1 or 2 the URL becomes foo.20.html.
All other browsers receive page foo.32.html.
This is done by the following ruleset:
RewriteCond %{HTTP_USER_AGENT} ^Mozilla/3.*
RewriteRule ^foo\.html$ foo.NS.html [L]
RewriteCond %{HTTP_USER_AGENT} ^Lynx/.* [OR]
RewriteCond %{HTTP_USER_AGENT} ^Mozilla/[12].*
RewriteRule ^foo\.html$ foo.20.html [L]
RewriteRule ^foo\.html$ foo.32.html [L]
Dynamic Mirror
mirror program which actually maintains an
explicit up-to-date copy of the remote data on the local
machine. For a webserver we could use the program
webcopy which acts similar via HTTP. But both
techniques have one major drawback: The local copy is
always just as up-to-date as often we run the program. It
would be much better if the mirror is not a static one we
have to establish explicitly. Instead we want a dynamic
mirror with data which gets updated automatically when
there is need (updated data on the remote host).[P]):
RewriteEngine on
RewriteBase /~quux/
RewriteRule ^hotsheet/(.*)$ http://www.tstimpreso.com/hotsheet/$1 [P]
RewriteEngine on
RewriteBase /~quux/
RewriteRule ^usa-news\.html$ http://www.quux-corp.com/news/index.html [P]
Reverse Dynamic Mirror
RewriteEngine on
RewriteCond /mirror/of/remotesite/$1 -U
RewriteRule ^http://www\.remotesite\.com/(.*)$ /mirror/of/remotesite/$1
Retrieve Missing Data from Intranet
www.quux-corp.dom), while actually keeping
and maintaining its data on a (internal) Intranet webserver
(www2.quux-corp.dom) which is protected by a
firewall. The trick is that on the external webserver we
retrieve the requested data on-the-fly from the internal
one.
ALLOW Host www.quux-corp.dom Port >1024 --> Host www2.quux-corp.dom Port 80
DENY Host * Port * --> Host www2.quux-corp.dom Port 80
mod_rewrite
rules which request the missing data in the background
through the proxy throughput feature:
RewriteRule ^/~([^/]+)/?(.*) /home/$1/.www/$2
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^/home/([^/]+)/.www/?(.*) http://www2.quux-corp.dom/~$1/pub/$2 [P]
Load Balancing
www.foo.com over www[0-5].foo.com
(a total of 6 servers). How can this be done?mod_rewrite:
BIND.
Here you just configure www[0-9].foo.com
as usual in your DNS with A(address) records, e.g.
www0 IN A 1.2.3.1
www1 IN A 1.2.3.2
www2 IN A 1.2.3.3
www3 IN A 1.2.3.4
www4 IN A 1.2.3.5
www5 IN A 1.2.3.6
www IN CNAME www0.foo.com.
IN CNAME www1.foo.com.
IN CNAME www2.foo.com.
IN CNAME www3.foo.com.
IN CNAME www4.foo.com.
IN CNAME www5.foo.com.
IN CNAME www6.foo.com.
BIND and can be used
in this way. However, now when www.foo.com gets
resolved, BIND gives out www0-www6
- but in a slightly permutated/rotated order every time.
This way the clients are spread over the various
servers. But notice that this not a perfect load
balancing scheme, because DNS resolve information
gets cached by the other nameservers on the net, so
once a client has resolved www.foo.com
to a particular wwwN.foo.com, all
subsequent requests also go to this particular name
wwwN.foo.com. But the final result is
ok, because the total sum of the requests are really
spread over the various webservers.lbnamed which can be found at
http://www.stanford.edu/~schemers/docs/lbnamed/lbnamed.html.
It is a Perl 5 program in conjunction with auxilliary
tools which provides a real load-balancing for
DNS.mod_rewrite
and its proxy throughput feature. First we dedicate
www0.foo.com to be actually
www.foo.com by using a single
www IN CNAME www0.foo.com.
www0.foo.com to a proxy-only server,
i.e. we configure this machine so all arriving URLs
are just pushed through the internal proxy to one of
the 5 other servers (www1-www5). To
accomplish this we first establish a ruleset which
contacts a load balancing script lb.pl
for all URLs.
RewriteEngine on
RewriteMap lb prg:/path/to/lb.pl
RewriteRule ^/(.+)$ ${lb:$1} [P,L]
lb.pl:
#!/path/to/perl
##
## lb.pl -- load balancing script
##
$| = 1;
$name = "www"; # the hostname base
$first = 1; # the first server (not 0 here, because 0 is myself)
$last = 5; # the last server in the round-robin
$domain = "foo.dom"; # the domainname
$cnt = 0;
while (<STDIN>) {
$cnt = (($cnt+1) % ($last+1-$first));
$server = sprintf("%s%d.%s", $name, $cnt+$first, $domain);
print "http://$server/$_";
}
##EOF##
A last notice: Why is this useful? Seems like
www0.foo.com still is overloaded? The
answer is yes, it is overloaded, but with plain proxy
throughput requests, only! All SSI, CGI, ePerl, etc.
processing is completely done on the other machines.
This is the essential point.New MIME-type, New Service
PATH_INFO
and QUERY_STRINGS) as their input. First,
let us configure a new file type with extension
.scgi (for secure CGI) which will be processed
by the popular cgiwrap program. The problem
here is that for instance we use a Homogeneous URL Layout
(see above) a file inside the user homedirs has the URL
/u/user/foo/bar.scgi. But
cgiwrap needs the URL in the form
/~user/foo/bar.scgi/. The following rule
solves the problem:
RewriteRule ^/[uge]/([^/]+)/\.www/(.+)\.scgi(.*) ...
... /internal/cgi/user/cgiwrap/~$1/$2.scgi$3 [NS,T=application/x-http-cgi]
wwwlog (which displays the
access.log for a URL subtree and
wwwidx (which runs Glimpse on a URL
subtree). We have to provide the URL area to these
programs so they know on which area they have to act on.
But usually this ugly, because they are all the times
still requested from that areas, i.e. typically we would
run the swwidx program from within
/u/user/foo/ via hyperlink to
/internal/cgi/user/swwidx?i=/u/user/foo/
RewriteRule ^/([uge])/([^/]+)(/?.*)/\* /internal/cgi/user/wwwidx?i=/$1/$2$3/
RewriteRule ^/([uge])/([^/]+)(/?.*):log /internal/cgi/user/wwwlog?f=/$1/$2$3
/u/user/foo/ reads only
HREF="*"
/internal/cgi/user/wwwidx?i=/u/user/foo/
:log gets used.From Static to Dynamic
foo.html into a dynamic variant
foo.cgi in a seamless way, i.e. without notice
by the browser/user./~quux/foo.html
internally leads to the invocation of
/~quux/foo.cgi.
RewriteEngine on
RewriteBase /~quux/
RewriteRule ^foo\.html$ foo.cgi [T=application/x-httpd-cgi]
On-the-fly Content-Regeneration
RewriteCond %{REQUEST_FILENAME} !-s
RewriteRule ^page\.html$ page.cgi [T=application/x-httpd-cgi,L]
page.html leads to a
internal run of a corresponding page.cgi if
page.html is still missing or has filesize
null. The trick here is that page.cgi is a
usual CGI script which (additionally to its STDOUT)
writes its output to the file page.html.
Once it was run, the server sends out the data of
page.html. When the webmaster wants to force
a refresh the contents, he just removes
page.html (usually done by a cronjob).Document With Autorefresh
mod_rewrite. First, we establish a new
URL feature: Adding just :refresh to any
URL causes this to be refreshed every time it gets
updated on the filesystem.
RewriteRule ^(/[uge]/[^/]+/?.*):refresh /internal/cgi/apache/nph-refresh?f=$1
/u/foo/bar/page.html:refresh
/internal/cgi/apache/nph-refresh?f=/u/foo/bar/page.html
#!/sw/bin/perl
##
## nph-refresh -- NPH/CGI script for auto refreshing pages
## Copyright (c) 1997 Ralf S. Engelschall, All Rights Reserved.
##
$| = 1;
# split the QUERY_STRING variable
@pairs = split(/&/, $ENV{'QUERY_STRING'});
foreach $pair (@pairs) {
($name, $value) = split(/=/, $pair);
$name =~ tr/A-Z/a-z/;
$name = 'QS_' . $name;
$value =~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C", hex($1))/eg;
eval "\$$name = \"$value\"";
}
$QS_s = 1 if ($QS_s eq '');
$QS_n = 3600 if ($QS_n eq '');
if ($QS_f eq '') {
print "HTTP/1.0 200 OK\n";
print "Content-type: text/html\n\n";
print "<b>ERROR</b>: No file given\n";
exit(0);
}
if (! -f $QS_f) {
print "HTTP/1.0 200 OK\n";
print "Content-type: text/html\n\n";
print "<b>ERROR</b>: File $QS_f not found\n";
exit(0);
}
sub print_http_headers_multipart_begin {
print "HTTP/1.0 200 OK\n";
$bound = "ThisRandomString12345";
print "Content-type: multipart/x-mixed-replace;boundary=$bound\n";
&print_http_headers_multipart_next;
}
sub print_http_headers_multipart_next {
print "\n--$bound\n";
}
sub print_http_headers_multipart_end {
print "\n--$bound--\n";
}
sub displayhtml {
local($buffer) = @_;
$len = length($buffer);
print "Content-type: text/html\n";
print "Content-length: $len\n\n";
print $buffer;
}
sub readfile {
local($file) = @_;
local(*FP, $size, $buffer, $bytes);
($x, $x, $x, $x, $x, $x, $x, $size) = stat($file);
$size = sprintf("%d", $size);
open(FP, "<$file");
$bytes = sysread(FP, $buffer, $size);
close(FP);
return $buffer;
}
$buffer = &readfile($QS_f);
&print_http_headers_multipart_begin;
&displayhtml($buffer);
sub mystat {
local($file) = $_[0];
local($time);
($x, $x, $x, $x, $x, $x, $x, $x, $x, $mtime) = stat($file);
return $mtime;
}
$mtimeL = &mystat($QS_f);
$mtime = $mtime;
for ($n = 0; $n < $QS_n; $n++) {
while (1) {
$mtime = &mystat($QS_f);
if ($mtime ne $mtimeL) {
$mtimeL = $mtime;
sleep(2);
$buffer = &readfile($QS_f);
&print_http_headers_multipart_next;
&displayhtml($buffer);
sleep(5);
$mtimeL = &mystat($QS_f);
last;
}
sleep($QS_s);
}
}
&print_http_headers_multipart_end;
exit(0);
##EOF##
Mass Virtual Hosting
<VirtualHost> feature of Apache is nice
and works great when you just have a few dozens
virtual hosts. But when you are an ISP and have hundreds of
virtual hosts to provide this feature is not the best
choice.[P]):
##
## vhost.map
##
www.vhost1.dom:80 /path/to/docroot/vhost1
www.vhost2.dom:80 /path/to/docroot/vhost2
:
www.vhostN.dom:80 /path/to/docroot/vhostN
##
## httpd.conf
##
:
# use the canonical hostname on redirects, etc.
UseCanonicalName on
:
# add the virtual host in front of the CLF-format
CustomLog /path/to/access_log "%{VHOST}e %h %l %u %t \"%r\" %>s %b"
:
# enable the rewriting engine in the main server
RewriteEngine on
# define two maps: one for fixing the URL and one which defines
# the available virtual hosts with their corresponding
# DocumentRoot.
RewriteMap lowercase int:tolower
RewriteMap vhost txt:/path/to/vhost.map
# Now do the actual virtual host mapping
# via a huge and complicated single rule:
#
# 1. make sure we don't map for common locations
RewriteCond %{REQUEST_URI} !^/commonurl1/.*
RewriteCond %{REQUEST_URI} !^/commonurl2/.*
:
RewriteCond %{REQUEST_URI} !^/commonurlN/.*
#
# 2. make sure we have a Host header, because
# currently our approach only supports
# virtual hosting through this header
RewriteCond %{HTTP_HOST} !^$
#
# 3. lowercase the hostname
RewriteCond ${lowercase:%{HTTP_HOST}|NONE} ^(.+)$
#
# 4. lookup this hostname in vhost.map and
# remember it only when it is a path
# (and not "NONE" from above)
RewriteCond ${vhost:%1} ^(/.*)$
#
# 5. finally we can map the URL to its docroot location
# and remember the virtual host for logging puposes
RewriteRule ^/(.*)$ %1/$1 [E=VHOST:${lowercase:%{HTTP_HOST}}]
:
Access Restriction
Blocking of Robots
/robots.txt file containing entries of the
"Robot Exclusion Protocol" is typically not enough to get
rid of such a robot./~quux/foo/arc/ (perhaps a very deep
directory indexed area where the robot traversal would
create big server load). We have to make sure that we
forbid access only to the particular robot, i.e. just
forbidding the host where the robot runs is not enough.
This would block users from this host, too. We accomplish
this by also matching the User-Agent HTTP header
information.
RewriteCond %{HTTP_USER_AGENT} ^NameOfBadRobot.*
RewriteCond %{REMOTE_ADDR} ^123\.45\.67\.[8-9]$
RewriteRule ^/~quux/foo/arc/.+ - [F]
Blocked Inline-Images
http://www.quux-corp.de/~quux/
some pages with inlined GIF graphics. These graphics are
nice, so others directly incorporate them via hyperlinks to
their pages. We don't like this practice because it adds
useless traffic to our server.
RewriteCond %{HTTP_REFERER} !^$
RewriteCond %{HTTP_REFERER} !^http://www.quux-corp.de/~quux/.*$ [NC]
RewriteRule .*\.gif$ - [F]
RewriteCond %{HTTP_REFERER} !^$
RewriteCond %{HTTP_REFERER} !.*/foo-with-gif\.html$
RewriteRule ^inlined-in-foo\.gif$ - [F]
Host Deny
RewriteEngine on
RewriteMap hosts-deny txt:/path/to/hosts.deny
RewriteCond ${hosts-deny:%{REMOTE_HOST}|NOT-FOUND} !=NOT-FOUND [OR]
RewriteCond ${hosts-deny:%{REMOTE_ADDR}|NOT-FOUND} !=NOT-FOUND
RewriteRule ^/.* - [F]
RewriteEngine on
RewriteMap hosts-deny txt:/path/to/hosts.deny
RewriteRule ^/(.*)$ ${hosts-deny:%{REMOTE_HOST}|NOT-FOUND}/$1
RewriteRule !^NOT-FOUND/.* - [F]
RewriteRule ^NOT-FOUND/(.*)$ ${hosts-deny:%{REMOTE_ADDR}|NOT-FOUND}/$1
RewriteRule !^NOT-FOUND/.* - [F]
RewriteRule ^NOT-FOUND/(.*)$ /$1
##
## hosts.deny
##
## ATTENTION! This is a map, not a list, even when we treat it as such.
## mod_rewrite parses it for key/value pairs, so at least a
## dummy value "-" must be present for each entry.
##
193.102.180.41 -
bsdti1.sdm.de -
192.76.162.40 -
Proxy Deny
mod_rewrite
is below(!) mod_proxy in the Configuration
file when compiling the Apache webserver. This way it gets
called before mod_proxy. Then we
configure the following for a host-dependent deny...
RewriteCond %{REMOTE_HOST} ^badhost\.mydomain\.com$
RewriteRule !^http://[^/.]\.mydomain.com.* - [F]
RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} ^badguy@badhost\.mydomain\.com$
RewriteRule !^http://[^/.]\.mydomain.com.* - [F]
Special Authentication Variant
mod_auth).
RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} !^friend1@client1.quux-corp\.com$
RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} !^friend2@client2.quux-corp\.com$
RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} !^friend3@client3.quux-corp\.com$
RewriteRule ^/~quux/only-for-friends/ - [F]
Referer-based Deflector
RewriteMap deflector txt:/path/to/deflector.map
RewriteCond %{HTTP_REFERER} !=""
RewriteCond ${deflector:%{HTTP_REFERER}} ^-$
RewriteRule ^.* %{HTTP_REFERER} [R,L]
RewriteCond %{HTTP_REFERER} !=""
RewriteCond ${deflector:%{HTTP_REFERER}|NOT-FOUND} !=NOT-FOUND
RewriteRule ^.* ${deflector:%{HTTP_REFERER}} [R,L]
##
## deflector.map
##
http://www.badguys.com/bad/index.html -
http://www.badguys.com/bad/index2.html -
http://www.badguys.com/bad/index3.html http://somewhere.com/
-" is used as the value
in the map) or to a specific URL (when an URL is specified
in the map as the second argument).
Other
External Rewriting Engine
mod_rewrite...RewriteMap, i.e. a program which acts
like a RewriteMap. It is run once on startup of Apache
receives the requested URLs on STDIN and has
to put the resulting (usually rewritten) URL on
STDOUT (same order!).
RewriteEngine on
RewriteMap quux-map prg:/path/to/map.quux.pl
RewriteRule ^/~quux/(.*)$ /~quux/${quux-map:$1}
#!/path/to/perl
# disable buffered I/O which would lead
# to deadloops for the Apache server
$| = 1;
# read URLs one per line from stdin and
# generate substitution URL on stdout
while (<>) {
s|^foo/|bar/|;
print $_;
}
/~quux/foo/... to
/~quux/bar/.... Actually you can program
whatever you like. But notice that while such maps can be
used also by an average user, only the
system administrator can define it.
misc/tutorials.html 100644 0 0 23462 11074462673 12115 0 ustar 0 0
Security Tips
Keep up to Date
Permissions on ServerRoot Directories
User directive to serve hits. As is the
case with any command that root executes, you must take care that it is
protected from modification by non-root users. Not only must the files
themselves be writeable only by root, but so must the directories, and
parents of all directories. For example, if you choose to place
ServerRoot in /usr/local/apache then it is suggested that you create
that directory as root, with commands like these:
mkdir /usr/local/apache
cd /usr/local/apache
mkdir bin conf logs
chown 0 . bin conf logs
chgrp 0 . bin conf logs
chmod 755 . bin conf logs
httpd executable, you
should ensure that it is similarly protected:
cp httpd /usr/local/apache/bin
chown 0 /usr/local/apache/bin/httpd
chgrp 0 /usr/local/apache/bin/httpd
chmod 511 /usr/local/apache/bin/httpd
httpd binary so
that the next time you start it, it will execute some arbitrary code. If
the logs directory is writeable (by a non-root user), someone could replace
a log file with a symlink to some other system file, and then root
might overwrite that file with arbitrary data. If the log files
themselves are writeable (by a non-root user), then someone may be
able to overwrite the log itself with bogus data.
Server Side Includes
Includes
with IncludesNOEXEC in the Options directive. Note that users may
still use <--#include virtual="..." --> to execute CGI scripts if
these scripts are in directories designated by a ScriptAlias directive.
CGI in General
Non Script Aliased CGI
Script Aliased CGI
Other sources of dynamic content
User directive), and therefore
scripts executed by these engines potentially can access anything the
server user can. Some scripting engines may provide restrictions, but
it is better to be safe and assume not.
Protecting System Settings
.htaccess files which can override security features
you've configured. Here's one way to do it.
<Directory />
AllowOverride None
</Directory>
.htaccess files in all
directories apart from those specifically enabled.
Protect Server Files by Default
# cd /; ln -s / public_html
Accessing http://localhost/~root/
<Directory />
Order Deny,Allow
Deny from all
</Directory>
Directory blocks to
allow access only in those areas you wish. For example,
<Directory /usr/users/*/public_html>
Order Deny,Allow
Allow from all
</Directory>
<Directory /usr/local/httpd>
Order Deny,Allow
Allow from all
</Directory>
Location and Directory directives; for instance, even
if <Directory /> denies access, a
<Location /> directive might overturn it.UserDir directive; setting it to
something like "./" would have the same effect, for root, as the first
example above. If you are using Apache 1.3 or above, we strongly
recommend that you include the following line in your server
configuration files:
UserDir disabled root
Watching Your Logs
grep -c "/jsp/source.jsp?/jsp/ /jsp/source.jsp??" access_log
grep "client denied" error_log | tail -n 10
[Thu Jul 11 17:18:39 2002] [error] [client foo.bar.com] client denied
by server configuration: /usr/local/apache/htdocs/.htpasswd
.htpasswd file you
would have seen something similar to:
foo.bar.com - - [12/Jul/2002:01:59:13 +0200] "GET /.htpasswd HTTP/1.1"
<Files ~ "^\.ht">
Order allow,deny
Deny from all
</Files>
mod/beos.html 100644 0 0 14203 11074462673 10634 0 ustar 0 0
Apache Tutorials
Warning:
Installation & Getting Started
Basic Configuration
Security
Logging
CGI and SSI
Other Features
mod/core.html 100644 0 0 532576 11074462673 10676 0 ustar 0 0
Apache MPM beos
Description: This Multi-Processing Module is optimized for BeOS. Status: MPM Module Identifier: mpm_beos_module Source File: beos.c Summary
Directives
CoreDumpDirectory Group Listen ListenBacklog MaxClients MaxMemFree MaxRequestsPerThread MaxSpareThreads MinSpareThreads PidFile ReceiveBufferSize ScoreBoardFile SendBufferSize StartThreads UserSee also
MaxRequestsPerThread Directive
Description: Limit on the number of requests that an individual thread
will handle during its life Syntax: MaxRequestsPerThread numberDefault: MaxRequestsPerThread 0Context: server config Status: MPM Module: beos MaxRequestsPerThread directive sets
the limit on the number of requests that an individual server thread
will handle. After MaxRequestsPerThread
requests, the thread will die. If MaxRequestsPerThread is 0, then the thread
will never expire.MaxRequestsPerThread to a
non-zero limit has two beneficial effects:
Note:
KeepAlive requests, only
the first request is counted towards this limit. In effect, it
changes the behavior to limit the number of connections
per thread.
mod/directive-dict.html 100644 0 0 33651 11074462673 12613 0 ustar 0 0
Apache Core Features
Description: Core Apache HTTP Server features that are always
available Status: Core Directives
AcceptPathInfo AccessFileName AddDefaultCharset AddOutputFilterByType AllowEncodedSlashes AllowOverride AuthName AuthType CGIMapExtension ContentDigest DefaultType <Directory> <DirectoryMatch> DocumentRoot EnableMMAP EnableSendfile ErrorDocument ErrorLog FileETag <Files> <FilesMatch> ForceType HostnameLookups IdentityCheck <IfDefine> <IfModule> Include KeepAlive KeepAliveTimeout <Limit> <LimitExcept> LimitInternalRecursion LimitRequestBody LimitRequestFields LimitRequestFieldSize LimitRequestLine LimitXMLRequestBody <Location> <LocationMatch> LogLevel MaxKeepAliveRequests NameVirtualHost Options Require RLimitCPU RLimitMEM RLimitNPROC Satisfy ScriptInterpreterSource ServerAdmin ServerAlias ServerName ServerPath ServerRoot ServerSignature ServerTokens SetHandler SetInputFilter SetOutputFilter TimeOut TraceEnable UseCanonicalName <VirtualHost>AcceptPathInfo Directive
Description: Resources accept trailing pathname information Syntax: AcceptPathInfo On|Off|DefaultDefault: AcceptPathInfo DefaultContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Core Module: core Compatibility: Available in Apache 2.0.30 and later PATH_INFO environment
variable./test/ points to
a directory that contains only the single file
here.html. Then requests for
/test/here.html/more and
/test/nothere.html/more both collect
/more as PATH_INFO.AcceptPathInfo directive are:
Off/test/here.html/more in the above example will return
a 404 NOT FOUND error.On/test/here.html/more will be accepted if
/test/here.html maps to a valid file.DefaultPATH_INFO requests. Handlers that serve scripts, such as cgi-script and isapi-handler, generally accept
PATH_INFO by default.AcceptPathInfo
directive is to allow you to override the handler's choice of
accepting or rejecting PATH_INFO. This override is required,
for example, when you use a filter, such
as INCLUDES, to generate content
based on PATH_INFO. The core handler would usually reject
the request, so you can use the following configuration to enable
such a script:
<Files "mypaths.shtml">
Options +Includes
SetOutputFilter INCLUDES
AcceptPathInfo On
</Files>
AccessFileName Directive
Description: Name of the distributed configuration file Syntax: AccessFileName filename [filename] ...Default: AccessFileName .htaccessContext: server config, virtual host Status: Core Module: core
AccessFileName .acl
/usr/local/web/index.html, the server will read
/.acl, /usr/.acl,
/usr/local/.acl and /usr/local/web/.acl
for directives, unless they have been disabled with
<Directory />
AllowOverride None
</Directory>
See also
AddDefaultCharset Directive
Description: Default charset parameter to be added when a response
content-type is text/plain or text/htmlSyntax: AddDefaultCharset On|Off|charsetDefault: AddDefaultCharset OffContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Core Module: core text/plain or text/html. This should override
any charset specified in the body of the response via a META
element, though the exact behavior is often dependent on the user's client
configuration. A setting of AddDefaultCharset Off
disables this functionality. AddDefaultCharset On enables
a default charset of iso-8859-1. Any other value is assumed
to be the charset to be used, which should be one of the
IANA registered
charset values for use in MIME media types.
For example:
AddDefaultCharset utf-8
AddDefaultCharset should only be used when all
of the text resources to which it applies are known to be in that
character encoding and it is too inconvenient to label their charset
individually. One such example is to add the charset parameter
to resources containing generated content, such as legacy CGI
scripts, that might be vulnerable to cross-site scripting attacks
due to user-provided data being included in the output. Note, however,
that a better solution is to just fix (or delete) those scripts, since
setting a default charset does not protect users that have enabled
the "auto-detect character encoding" feature on their browser.See also
AddOutputFilterByType Directive
Description: assigns an output filter to a particular MIME-type Syntax: AddOutputFilterByType filter[;filter...]
MIME-type [MIME-type] ...Context: server config, virtual host, directory, .htaccess Override: FileInfo Status: Core Module: core Compatibility: Available in Apache 2.0.33 and later DEFLATE filter, which
is provided by mod_deflate. It will compress all
output (either static or dynamic) which is labeled as
text/html or text/plain before it is sent
to the client.
AddOutputFilterByType DEFLATE text/html text/plain
AddOutputFilterByType directive for each of
these filters.text/html to be processed at first by the
INCLUDES filter and then by the DEFLATE
filter.
<Location /cgi-bin/>
Options Includes
AddOutputFilterByType INCLUDES;DEFLATE text/html
</Location>
Note
AddOutputFilterByType
may fail partially or completely in some cases. For example, no
filters are applied if the MIME-type could not be determined and falls
back to the DefaultType setting,
even if the DefaultType is the
same.AddType or
ForceType. Setting the
content type within a (non-nph) CGI script is also safe.See also
AllowEncodedSlashes Directive
Description: Determines whether encoded path separators in URLs are allowed to
be passed through Syntax: AllowEncodedSlashes On|OffDefault: AllowEncodedSlashes OffContext: server config, virtual host Status: Core Module: core Compatibility: Available in Apache 2.0.46 and later AllowEncodedSlashes directive allows URLs
which contain encoded path separators (%2F for /
and additionally %5C for \ on according systems)
to be used. Normally such URLs are refused with a 404 (Not found) error.AllowEncodedSlashes On is
mostly useful when used in conjunction with PATH_INFO.Note
%2F or %5C (only on
according systems) will be left as such in the otherwise decoded URL
string.See also
AllowOverride Directive
Description: Types of directives that are allowed in
.htaccess filesSyntax: AllowOverride All|None|directive-type
[directive-type] ...Default: AllowOverride AllContext: directory Status: Core Module: core .htaccess file (as
specified by AccessFileName)
it needs to know which directives declared in that file can override
earlier configuration directives.Only available in <Directory> sections
AllowOverride is valid only in
<Directory>
sections specified without regular expressions, not in <Location>, <DirectoryMatch> or
<Files> sections.
None, then
.htaccess files are completely ignored.
In this case, the server will not even attempt to read
.htaccess files in the filesystem.All, then any
directive which has the .htaccess Context is allowed in
.htaccess files.
AuthDBMGroupFile,
AuthDBMUserFile,
AuthGroupFile,
AuthName,
AuthType, AuthUserFile, Require, etc.).DefaultType, ErrorDocument, ForceType, LanguagePriority,
SetHandler, SetInputFilter, SetOutputFilter, and
mod_mime Add* and Remove*
directives, etc.).AddDescription,
AddIcon, AddIconByEncoding,
AddIconByType,
DefaultIcon, DirectoryIndex, FancyIndexing, HeaderName, IndexIgnore, IndexOptions, ReadmeName,
etc.).Allow, Deny and Order).Options and
XBitHack).
AllowOverride AuthConfig Indexes
AuthConfig nor Indexes cause an internal
server error.See also
AuthName Directive
Description: Authorization realm for use in HTTP
authentication Syntax: AuthName auth-domainContext: directory, .htaccess Override: AuthConfig Status: Core Module: core AuthName takes a single argument; if the
realm name contains spaces, it must be enclosed in quotation
marks. It must be accompanied by AuthType and Require directives, and directives such
as AuthUserFile and
AuthGroupFile to
work.
AuthName "Top Secret"
AuthName is what will
appear in the password dialog provided by most browsers.See also
AuthType Directive
Description: Type of user authentication Syntax: AuthType Basic|DigestContext: directory, .htaccess Override: AuthConfig Status: Core Module: core Basic and Digest are
currently implemented.
It must be accompanied by AuthName and Require directives, and directives such
as AuthUserFile and
AuthGroupFile to
work.See also
CGIMapExtension Directive
Description: Technique for locating the interpreter for CGI
scripts Syntax: CGIMapExtension cgi-path .extensionContext: directory, .htaccess Override: FileInfo Status: Core Module: core Compatibility: NetWare only CGIMapExtension sys:\foo.nlm .foo will
cause all CGI script files with a .foo extension to
be passed to the FOO interpreter.ContentDigest Directive
Description: Enables the generation of Content-MD5 HTTP Response
headersSyntax: ContentDigest On|OffDefault: ContentDigest OffContext: server config, virtual host, directory, .htaccess Override: Options Status: Core Module: core Content-MD5 headers as defined in RFC1864
respectively RFC2068.Content-MD5 header provides an end-to-end
message integrity check (MIC) of the entity-body. A proxy or
client may check this header for detecting accidental
modification of the entity-body in transit. Example header:
Content-MD5: AuLb7Dp1rqtRtxz2m9kRpA==
Content-MD5 is only sent for documents served
by the core, and not by any module. For example,
SSI documents, output from CGI scripts, and byte range responses
do not have this header.DefaultType Directive
Description: MIME content-type that will be sent if the
server cannot determine a type in any other way Syntax: DefaultType MIME-typeDefault: DefaultType text/plainContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Core Module: core DefaultType. For example:
DefaultType image/gif
.gif extension.ForceType, this directive only
provides the default mime-type. All other mime-type definitions,
including filename extensions, that might identify the media type
will override this default.<Directory> Directive
Description: Enclose a group of directives that apply only to the
named file-system directory and sub-directories Syntax: <Directory directory-path>
... </Directory>Context: server config, virtual host Status: Core Module: core <Directory> and
</Directory> are used to enclose a group of
directives that will apply only to the named directory and
sub-directories of that directory. Any directive that is allowed
in a directory context may be used. Directory-path is
either the full path to a directory, or a wild-card string using
Unix shell-style matching. In a wild-card string, ? matches
any single character, and * matches any sequences of
characters. You may also use [] character ranges. None
of the wildcards match a `/' character, so <Directory
/*/public_html> will not match
/home/user/public_html, but <Directory
/home/*/public_html> will match. Example:
<Directory /usr/local/httpd/htdocs>
Options Indexes FollowSymLinks
</Directory>
<Directory> will not apply to files accessed from
that same directory via a different path, such as via different symbolic
links.~ character. For example:
<Directory ~ "^/www/.*/[0-9]{3}">
/www/ that consisted of
three numbers.<Directory> sections
match the directory (or one of its parents) containing a document,
then the directives are applied in the order of shortest match
first, interspersed with the directives from the .htaccess files. For example,
with
<Directory />
AllowOverride None
</Directory>
<Directory /home/>
AllowOverride FileInfo
</Directory>
/home/web/dir/doc.html
the steps are:
AllowOverride None
(disabling .htaccess files).AllowOverride FileInfo (for
directory /home).FileInfo directives in
/home/.htaccess, /home/web/.htaccess and
/home/web/dir/.htaccess in that order.
<Directory ~ abc$>
# ... directives here ...
</Directory>
<Directory>s and
.htaccess files have been applied. Then the regular
expression will match on /home/abc/public_html/abc and
the corresponding <Directory> will
be applied.<Directory /> is Allow from All.
This means that Apache will serve any file mapped from an URL. It is
recommended that you change this with a block such
as
<Directory />
Order Deny,Allow
Deny from All
</Directory>
httpd.conf file.
<Directory> directives
cannot nest, and cannot appear in a <Limit> or <LimitExcept> section.See also
<DirectoryMatch> Directive
Description: Enclose directives that apply to
file-system directories matching a regular expression and their
subdirectories Syntax: <DirectoryMatch regex>
... </DirectoryMatch>Context: server config, virtual host Status: Core Module: core <DirectoryMatch> and
</DirectoryMatch> are used to enclose a group
of directives which will apply only to the named directory and
sub-directories of that directory, the same as <Directory>. However, it
takes as an argument a regular expression. For example:
<DirectoryMatch "^/www/(.+/)?[0-9]{3}">
/www/ that consisted of three
numbers.See also
<Directory> for
a description of how regular expressions are mixed in with normal
<Directory>sDocumentRoot Directive
Description: Directory that forms the main document tree visible
from the web Syntax: DocumentRoot directory-pathDefault: DocumentRoot /usr/local/apache/htdocsContext: server config, virtual host Status: Core Module: core httpd
will serve files. Unless matched by a directive like Alias, the server appends the
path from the requested URL to the document root to make the
path to the document. Example:
DocumentRoot /usr/web
http://www.my.host.com/index.html refers to
/usr/web/index.html.DocumentRoot should be specified without
a trailing slash.See also
EnableMMAP Directive
Description: Use memory-mapping to read files during delivery Syntax: EnableMMAP On|OffDefault: EnableMMAP OnContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Core Module: core httpd may use
memory-mapping if it needs to read the contents of a file during
delivery. By default, when the handling of a request requires
access to the data within a file -- for example, when delivering a
server-parsed file using mod_include -- Apache
memory-maps the file if the OS supports it.
httpd.DocumentRoot,
the httpd may crash due to a segmentation fault if a file
is deleted or truncated while the httpd has it
memory-mapped.
EnableMMAP Off
<Directory "/path-to-nfs-files">
EnableMMAP Off
</Directory>
EnableSendfile Directive
Description: Use the kernel sendfile support to deliver files to the client Syntax: EnableSendfile On|OffDefault: EnableSendfile OnContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Core Module: core Compatibility: Available in version 2.0.44 and later httpd may use the
sendfile support from the kernel to transmit file contents to the client.
By default, when the handling of a request requires no access
to the data within a file -- for example, when delivering a
static file -- Apache uses sendfile to deliver the file contents
without ever reading the file if the OS supports it.
DocumentRoot (e.g., NFS or SMB),
the kernel may be unable to serve the network file through
its own cache.
EnableSendfile Off
<Directory "/path-to-nfs-files">
EnableSendfile Off
</Directory>
ErrorDocument Directive
Description: What the server will return to the client
in case of an error Syntax: ErrorDocument error-code documentContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Core Module: core Compatibility: Quoting syntax for text messages is different in Apache
2.0
ErrorDocument
directive, which is followed by the HTTP response code and a URL
or a message. Apache will sometimes offer additional information
regarding the problem/error.DocumentRoot), or be a
full URL which the client can resolve. Alternatively, a message
can be provided to be displayed by the browser. Examples:
ErrorDocument 500 http://foo.example.com/cgi-bin/tester
ErrorDocument 404 /cgi-bin/bad_urls.pl
ErrorDocument 401 /subscription_info.html
ErrorDocument 403 "Sorry can't allow you access today"
default can be used
to specify Apache's simple hardcoded message. While not required
under normal circumstances, default will restore
Apache's simple hardcoded message for configurations that would
otherwise inherit an existing ErrorDocument.
ErrorDocument 404 /cgi-bin/bad_urls.pl
<Directory /web/docs>
ErrorDocument 404 default
</Directory>
ErrorDocument
that points to a remote URL (ie. anything with a method such as
http in front of it), Apache will send a redirect to the
client to tell it where to find the document, even if the
document ends up being on the same server. This has several
implications, the most important being that the client will not
receive the original error status code, but instead will
receive a redirect status code. This in turn can confuse web
robots and other clients which try to determine if a URL is
valid using the status code. In addition, if you use a remote
URL in an ErrorDocument 401, the client will not
know to prompt the user for a password since it will not
receive the 401 status code. Therefore, if you use an
ErrorDocument 401 directive then it must refer to a local
document.ErrorDocument. In
particular, if a malformed request is detected, normal request processing
will be immediately halted and the internal error message returned.
This is necessary to guard against security problems caused by
bad requests.See also
ErrorLog Directive
Description: Location where the server will log errors Syntax: ErrorLog file-path|syslog[:facility]Default: ErrorLog logs/error_log (Unix) ErrorLog logs/error.log (Windows and OS/2)Context: server config, virtual host Status: Core Module: core ErrorLog directive sets the name of
the file to which the server will log any errors it encounters. If
the file-path is not absolute then it is assumed to be
relative to the ServerRoot.Example
ErrorLog /var/log/httpd/error_log
Example
ErrorLog "|/usr/local/bin/httpd_errors"
syslog instead of a filename enables logging
via syslogd(8) if the system supports it. The default is to use
syslog facility local7, but you can override this by
using the syslog:facility syntax where
facility can be one of the names usually documented in
syslog(1).Example
ErrorLog syslog:user
Note
See also
FileETag Directive
Description: File attributes used to create the ETag
HTTP response header Syntax: FileETag component ...Default: FileETag INode MTime SizeContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Core Module: core FileETag directive configures the file
attributes that are used to create the ETag (entity
tag) response header field when the document is based on a file.
(The ETag value is used in cache management to save
network bandwidth.) In Apache 1.3.22 and earlier, the
ETag value was always formed
from the file's inode, size, and last-modified time (mtime). The
FileETag directive allows you to choose
which of these -- if any -- should be used. The recognized keywords are:
FileETag INode MTime SizeETag field will be
included in the responseINode, MTime, and Size
keywords may be prefixed with either + or -,
which allow changes to be made to the default setting inherited
from a broader scope. Any keyword appearing without such a prefix
immediately and completely cancels the inherited setting.FileETag INode MTime Size, and a
subdirectory's includes FileETag -INode,
the setting for that subdirectory (which will be inherited by
any sub-subdirectories that don't override it) will be equivalent to
FileETag MTime Size.<Files> Directive
Description: Contains directives that apply to matched
filenames Syntax: <Files filename> ... </Files>Context: server config, virtual host, directory, .htaccess Override: All Status: Core Module: core <Files> directive
limits the scope of the enclosed directives by filename. It is comparable
to the <Directory>
and <Location>
directives. It should be matched with a </Files>
directive. The directives given within this section will be applied to
any object with a basename (last component of filename) matching the
specified filename. <Files>
sections are processed in the order they appear in the
configuration file, after the <Directory> sections and
.htaccess files are read, but before <Location> sections. Note
that <Files> can be nested
inside <Directory> sections to restrict the
portion of the filesystem they apply to.? matches any single character,
and * matches any sequences of characters. Extended regular
expressions can also be used, with the addition of the
~ character. For example:
<Files ~ "\.(gif|jpe?g|png)$">
<FilesMatch> is preferred,
however.<Directory> and <Location> sections, <Files> sections can be used inside
.htaccess files. This allows users to control access to
their own files, at a file-by-file level.See also
<FilesMatch> Directive
Description: Contains directives that apply to regular-expression matched
filenames Syntax: <FilesMatch regex> ... </FilesMatch>Context: server config, virtual host, directory, .htaccess Override: All Status: Core Module: core <FilesMatch> directive
limits the scope of the enclosed directives by filename, just as the
<Files> directive
does. However, it accepts a regular expression. For example:
<FilesMatch "\.(gif|jpe?g|png)$">
See also
ForceType Directive
Description: Forces all matching files to be served with the specified
MIME content-type Syntax: ForceType MIME-type|NoneContext: directory, .htaccess Override: FileInfo Status: Core Module: core Compatibility: Moved to the core in Apache 2.0 .htaccess file or a
<Directory>, or
<Location> or
<Files>
section, this directive forces all matching files to be served
with the content type identification given by
MIME-type. For example, if you had a directory full of
GIF files, but did not want to label them all with .gif,
you might want to use:
ForceType image/gif
DefaultType,
this directive overrides all mime-type associations, including
filename extensions, that might identify the media type.ForceType setting
by using the value of None:
# force all files to be image/gif:
<Location /images>
ForceType image/gif
</Location>
# but normal mime-type associations here:
<Location /images/mixed>
ForceType None
</Location>
HostnameLookups Directive
Description: Enables DNS lookups on client IP addresses Syntax: HostnameLookups On|Off|DoubleDefault: HostnameLookups OffContext: server config, virtual host, directory Status: Core Module: core REMOTE_HOST).
The value Double refers to doing double-reverse
DNS lookup. That is, after a reverse lookup is performed, a forward
lookup is then performed on that result. At least one of the IP
addresses in the forward lookup must match the original
address. (In "tcpwrappers" terminology this is called
PARANOID.)mod_access is
used for controlling access by hostname, a double reverse lookup
will be performed. This is necessary for security. Note that the
result of this double-reverse isn't generally available unless you
set HostnameLookups Double. For example, if only
HostnameLookups On and a request is made to an object
that is protected by hostname restrictions, regardless of whether
the double-reverse fails or not, CGIs will still be passed the
single-reverse result in REMOTE_HOST.Off in order to save the network
traffic for those sites that don't truly need the reverse
lookups done. It is also better for the end users because they
don't have to suffer the extra latency that a lookup entails.
Heavily loaded sites should leave this directive
Off, since DNS lookups can take considerable
amounts of time. The utility logresolve, compiled by
default to the bin subdirectory of your installation
directory, can be used to look up host names from logged IP addresses
offline.IdentityCheck Directive
Description: Enables logging of the RFC1413 identity of the remote
user Syntax: IdentityCheck On|OffDefault: IdentityCheck OffContext: server config, virtual host, directory Status: Core Module: core <IfDefine> Directive
Description: Encloses directives that will be processed only
if a test is true at startup Syntax: <IfDefine [!]parameter-name> ...
</IfDefine>Context: server config, virtual host, directory, .htaccess Override: All Status: Core Module: core <IfDefine test>...</IfDefine>
section is used to mark directives that are conditional. The
directives within an <IfDefine>
section are only processed if the test is true. If
test is false, everything between the start and end markers is
ignored.<IfDefine> section directive can be one of two forms:
!parameter-namehttpd command line via -Dparameter-
, at the time the server was started.<IfDefine> sections are
nest-able, which can be used to implement simple
multiple-parameter tests. Example:
httpd -DReverseProxy ...
# httpd.conf
<IfDefine ReverseProxy>
LoadModule rewrite_module modules/mod_rewrite.so
LoadModule proxy_module modules/libproxy.so
</IfDefine>
<IfModule> Directive
Description: Encloses directives that are processed conditional on the
presence or absence of a specific module Syntax: <IfModule [!]module-name> ...
</IfModule>Context: server config, virtual host, directory, .htaccess Override: All Status: Core Module: core <IfModule test>...</IfModule>
section is used to mark directives that are conditional on the presence of
a specific module. The directives within an <IfModule> section are only processed if the test
is true. If test is false, everything between the start and
end markers is ignored.<IfModule> section directive can be one of two forms:
LoadModule. The second format reverses the test,
and only processes the directives if module name is
not included.mod_rewrite.c. If a module consists of several
source files, use the name of the file containing the string
STANDARD20_MODULE_STUFF.<IfModule> sections are
nest-able, which can be used to implement simple multiple-module
tests.This section should only be used if you need to have one
configuration file that works whether or not a specific module
is available. In normal operation, directives need not be
placed in
<IfModule>
sections.Include Directive
Description: Includes other configuration files from within
the server configuration files Syntax: Include file-path|directory-pathContext: server config, virtual host, directory Status: Core Module: core Compatibility: Wildcard matching available in 2.0.41 and later fnmatch()) wildcard characters can be used to
include several files at once, in alphabetical order. In
addition, if Include points to a directory,
rather than a file, Apache will read all files in that directory
and any subdirectory. But including entire directories is not
recommended, because it is easy to accidentally leave temporary
files in a directory that can cause httpd to
fail.ServerRoot directory.
Include /usr/local/apache2/conf/ssl.conf
Include /usr/local/apache2/conf/vhosts/*.conf
ServerRoot directory:
Include conf/ssl.conf
Include conf/vhosts/*.conf
apachectl configtest will give you a list
of the files that are being processed during the configuration
check:
root@host# apachectl configtest
Processing config file: /usr/local/apache2/conf/ssl.conf
Processing config file: /usr/local/apache2/conf/vhosts/vhost1.conf
Processing config file: /usr/local/apache2/conf/vhosts/vhost2.conf
Syntax OK
See also
KeepAlive Directive
Description: Enables HTTP persistent connections Syntax: KeepAlive On|OffDefault: KeepAlive OnContext: server config, virtual host Status: Core Module: core KeepAlive On.See also
KeepAliveTimeout Directive
Description: Amount of time the server will wait for subsequent
requests on a persistent connection Syntax: KeepAliveTimeout secondsDefault: KeepAliveTimeout 15Context: server config, virtual host Status: Core Module: core Timeout directive applies.KeepAliveTimeout to a high value
may cause performance problems in heavily loaded servers. The
higher the timeout, the more server processes will be kept
occupied waiting on connections with idle clients.<Limit> Directive
Description: Restrict enclosed access controls to only certain HTTP
methods Syntax: <Limit method [method] ... > ...
</Limit>Context: server config, virtual host, directory, .htaccess Override: All Status: Core Module: core <Limit> section.<Limit>
directive is to restrict the effect of the access controls to the
nominated HTTP methods. For all other methods, the access
restrictions that are enclosed in the <Limit> bracket will have no
effect. The following example applies the access control
only to the methods POST, PUT, and
DELETE, leaving all other methods unprotected:
<Limit POST PUT DELETE>
Require valid-user
</Limit>
GET,
POST, PUT, DELETE,
CONNECT, OPTIONS,
PATCH, PROPFIND, PROPPATCH,
MKCOL, COPY, MOVE,
LOCK, and UNLOCK. The method name is
case-sensitive. If GET is used it will also
restrict HEAD requests. The TRACE method
cannot be limited.A
<LimitExcept> section should always be
used in preference to a <Limit> section when restricting access,
since a <LimitExcept> section provides protection
against arbitrary methods.<LimitExcept> Directive
Description: Restrict access controls to all HTTP methods
except the named ones Syntax: <LimitExcept method [method] ... > ...
</LimitExcept>Context: server config, virtual host, directory, .htaccess Override: All Status: Core Module: core <LimitExcept> and
</LimitExcept> are used to enclose
a group of access control directives which will then apply to any
HTTP access method not listed in the arguments;
i.e., it is the opposite of a <Limit> section and can be used to control
both standard and nonstandard/unrecognized methods. See the
documentation for <Limit> for more details.
<LimitExcept POST GET>
Require valid-user
</LimitExcept>
LimitInternalRecursion Directive
Description: Determine maximum number of internal redirects and nested
subrequests Syntax: LimitInternalRecursion number [number]Default: LimitInternalRecursion 10Context: server config, virtual host Status: Core Module: core Compatibility: Available in Apache 2.0.47 and later Action directive, which internally
redirects the original request to a CGI script. A subrequest is Apache's
mechanism to find out what would happen for some URI if it were requested.
For example, mod_dir uses subrequests to look for the
files listed in the DirectoryIndex
directive.LimitInternalRecursion prevents the server
from crashing when entering an infinite loop of internal redirects or
subrequests. Such loops are usually caused by misconfigurations.Example
LimitInternalRecursion 5
LimitRequestBody Directive
Description: Restricts the total size of the HTTP request body sent
from the client Syntax: LimitRequestBody bytesDefault: LimitRequestBody 0Context: server config, virtual host, directory, .htaccess Override: All Status: Core Module: core LimitRequestBody directive allows
the user to set a limit on the allowed size of an HTTP request
message body within the context in which the directive is given
(server, per-directory, per-file or per-location). If the client
request exceeds that limit, the server will return an error
response instead of servicing the request. The size of a normal
request message body will vary greatly depending on the nature of
the resource and the methods allowed on that resource. CGI scripts
typically use the message body for retrieving form information.
Implementations of the PUT method will require
a value at least as large as any representation that the server
wishes to accept for that resource.
LimitRequestBody 102400
LimitRequestFields Directive
Description: Limits the number of HTTP request header fields that
will be accepted from the client Syntax: LimitRequestFields numberDefault: LimitRequestFields 100Context: server config Status: Core Module: core DEFAULT_LIMIT_REQUEST_FIELDS (100 as
distributed).LimitRequestFields directive allows
the server administrator to modify the limit on the number of
request header fields allowed in an HTTP request. A server needs
this value to be larger than the number of fields that a normal
client request might include. The number of request header fields
used by a client rarely exceeds 20, but this may vary among
different client implementations, often depending upon the extent
to which a user has configured their browser to support detailed
content negotiation. Optional HTTP extensions are often expressed
using request header fields.
LimitRequestFields 50
LimitRequestFieldSize Directive
Description: Limits the size of the HTTP request header allowed from the
client Syntax: LimitRequestFieldsize bytesDefault: LimitRequestFieldsize 8190Context: server config Status: Core Module: core LimitRequestFieldSize directive
allows the server administrator to reduce or increase the limit
on the allowed size of an HTTP request header field. A server
needs this value to be large enough to hold any one header field
from a normal client request. The size of a normal request header
field will vary greatly among different client implementations,
often depending upon the extent to which a user has configured
their browser to support detailed content negotiation. SPNEGO
authentication headers can be up to 12392 bytes.
LimitRequestFieldSize 4094
Under normal conditions, the value should not be changed from
the default.
Apache 2.0.53 or higher is required for increasing the
limit above the compiled-in value of DEFAULT_LIMIT_REQUEST_FIELDSIZE
(8190 as distributed).
LimitRequestLine Directive
Description: Limit the size of the HTTP request line that will be accepted
from the client Syntax: LimitRequestLine bytesDefault: LimitRequestLine 8190Context: server config Status: Core Module: core DEFAULT_LIMIT_REQUEST_LINE (8190 as distributed)
that will be allowed on the HTTP request-line.LimitRequestLine directive allows
the server administrator to reduce the limit on the allowed size
of a client's HTTP request-line below the normal input buffer size
compiled with the server. Since the request-line consists of the
HTTP method, URI, and protocol version, the
LimitRequestLine directive places a
restriction on the length of a request-URI allowed for a request
on the server. A server needs this value to be large enough to
hold any of its resource names, including any information that
might be passed in the query part of a GET request.
LimitRequestLine 4094
Under normal conditions, the value should not be changed from
the default.
LimitXMLRequestBody Directive
Description: Limits the size of an XML-based request body Syntax: LimitXMLRequestBody bytesDefault: LimitXMLRequestBody 1000000Context: server config, virtual host, directory, .htaccess Override: All Status: Core Module: core 0 will disable any checking.
LimitXMLRequestBody 0
<Location> Directive
Description: Applies the enclosed directives only to matching
URLs Syntax: <Location
URL-path|URL> ... </Location>Context: server config, virtual host Status: Core Module: core <Location> directive
limits the scope of the enclosed directives by URL. It is similar to the
<Directory>
directive, and starts a subsection which is terminated with a
</Location> directive. <Location> sections are processed in the
order they appear in the configuration file, after the <Directory> sections and
.htaccess files are read, and after the <Files> sections.<Location> sections operate
completely outside the filesystem. This has several consequences.
Most importantly, <Location>
directives should not be used to control access to filesystem
locations. Since several different URLs may map to the same
filesystem location, such access controls may by circumvented.When to use
<Location><Location> to apply
directives to content that lives outside the filesystem. For
content that lives in the filesystem, use <Directory> and <Files>. An exception is
<Location />, which is an easy way to
apply a configuration to the entire server./path/. No scheme, hostname,
port, or query string may be included. For proxy requests, the
URL to be matched is of the form
scheme://servername/path, and you must include the
prefix.? matches
any single character, and * matches any sequences of
characters.~ character. For example:
<Location ~ "/(extra|special)/data">
/extra/data
or /special/data. The directive <LocationMatch> behaves
identical to the regex version of <Location>.<Location>
functionality is especially useful when combined with the
SetHandler
directive. For example, to enable status requests, but allow them
only from browsers at foo.com, you might use:
<Location /status>
SetHandler server-status
Order Deny,Allow
Deny from all
Allow from .foo.com
</Location>
Note about / (slash)
/home///foo is the same as
/home/foo). In URL-space this is not necessarily true.
The <LocationMatch>
directive and the regex version of <Location> require you to explicitly specify multiple
slashes if that is your intention.<LocationMatch ^/abc> would match
the request URL /abc but not the request URL
//abc. The (non-regex) <Location> directive behaves similarly when used for
proxy requests. But when (non-regex) <Location> is used for non-proxy requests it will
implicitly match multiple slashes with a single slash. For example,
if you specify <Location /abc/def> and the
request is to /abc//def then it will match.See also
<LocationMatch> Directive
Description: Applies the enclosed directives only to regular-expression
matching URLs Syntax: <LocationMatch
regex> ... </LocationMatch>Context: server config, virtual host Status: Core Module: core <LocationMatch> directive
limits the scope of the enclosed directives by URL, in an identical manner
to <Location>. However,
it takes a regular expression as an argument instead of a simple
string. For example:
<LocationMatch "/(extra|special)/data">
/extra/data
or /special/data.See also
LogLevel Directive
Description: Controls the verbosity of the ErrorLog Syntax: LogLevel levelDefault: LogLevel warnContext: server config, virtual host Status: Core Module: core LogLevel adjusts the verbosity of the
messages recorded in the error logs (see ErrorLog directive). The following
levels are available, in order of decreasing
significance:
Level
Description
Example
emerg Emergencies - system is unusable.
"Child cannot open lock file. Exiting"
alert Action must be taken immediately.
"getpwuid: couldn't determine user name from uid"
crit Critical Conditions.
"socket: Failed to get a socket, exiting child"
error Error conditions.
"Premature end of script headers"
warn Warning conditions.
"child process 1234 did not exit, sending another
SIGHUP"
notice Normal but significant condition.
"httpd: caught SIGBUS, attempting to dump core in
..."
info Informational.
"Server seems busy, (you may need to increase
StartServers, or Min/MaxSpareServers)..."
debug Debug-level messages
"Opening config file ..."
LogLevel info is specified,
then messages with log levels of notice and
warn will also be posted.crit is
recommended.
LogLevel notice
Note
notice cannot be suppressed and thus are always
logged. However, this doesn't apply when logging is done
using syslog.MaxKeepAliveRequests Directive
Description: Number of requests allowed on a persistent
connection Syntax: MaxKeepAliveRequests numberDefault: MaxKeepAliveRequests 100Context: server config, virtual host Status: Core Module: core MaxKeepAliveRequests directive
limits the number of requests allowed per connection when
KeepAlive is on. If it is
set to 0, unlimited requests will be allowed. We
recommend that this setting be kept to a high value for maximum
server performance.
MaxKeepAliveRequests 500
NameVirtualHost Directive
Description: Designates an IP address for name-virtual
hosting Syntax: NameVirtualHost addr[:port]Context: server config Status: Core Module: core NameVirtualHost directive is a
required directive if you want to configure name-based virtual hosts.
NameVirtualHost 111.22.33.44
NameVirtualHost directive you
specify the IP address on which the server will receive requests
for the name-based virtual hosts. This will usually be the address
to which your name-based virtual host names resolve. In cases
where a firewall or other proxy receives the requests and forwards
them on a different IP address to the server, you must specify the
IP address of the physical interface on the machine which will be
servicing the requests. If you have multiple name-based hosts on
multiple addresses, repeat the directive for each address.Note
_default_ servers
will never be served for a request to a
NameVirtualHost IP address (unless for some
reason you specify NameVirtualHost but then
don't define any VirtualHosts for that
address).
NameVirtualHost 111.22.33.44:8080
NameVirtualHost [2001:db8::a00:20ff:fea7:ccea]:8080
*
NameVirtualHost *
Argument to
<VirtualHost>
directive<VirtualHost> directive must
exactly match the argument to the NameVirtualHost directive.
NameVirtualHost 1.2.3.4
<VirtualHost 1.2.3.4>
# ...
</VirtualHost>
See also
Options Directive
Description: Configures what features are available in a particular
directory Syntax: Options
[+|-]option [[+|-]option] ...Default: Options AllContext: server config, virtual host, directory, .htaccess Override: Options Status: Core Module: core Options directive controls which
server features are available in a particular directory.None, in which
case none of the extra features are enabled, or one or more of
the following:
AllMultiViews. This is the default
setting.ExecCGImod_cgi
is permitted.FollowSymLinks
<Directory> sections.<Location>
section.Includesmod_include
are permitted.IncludesNOEXEC#exec
cmd and #exec cgi are disabled. It is still
possible to #include virtual CGI scripts from
ScriptAliased
directories.IndexesDirectoryIndex
(e.g., index.html) in that directory, then
mod_autoindex will return a formatted listing
of the directory.MultiViewsmod_negotiation.SymLinksIfOwnerMatchNote
This option gets ignored if
set inside a <Location> section.Options could
apply to a directory, then the most specific one is used and
others are ignored; the options are not merged. (See how sections are merged.)
However if all the options on the
Options directive are preceded by a
+ or - symbol, the options are
merged. Any options preceded by a + are added to the
options currently in force, and any options preceded by a
- are removed from the options currently in
force. Warning
Options with a + or
- with those without is not valid syntax, and is likely
to cause unexpected results.+ and - symbols:
<Directory /web/docs>
Options Indexes FollowSymLinks
</Directory>
<Directory /web/docs/spec>
Options Includes
</Directory>
Includes will be set for the
/web/docs/spec directory. However if the second
Options directive uses the + and
- symbols:
<Directory /web/docs>
Options Indexes FollowSymLinks
</Directory>
<Directory /web/docs/spec>
Options +Includes -Indexes
</Directory>
FollowSymLinks and
Includes are set for the /web/docs/spec
directory.Note
-IncludesNOEXEC or
-Includes disables server-side includes completely
regardless of the previous setting.All.Require Directive
Description: Selects which authenticated users can access
a resource Syntax: Require entity-name [entity-name] ...Context: directory, .htaccess Override: AuthConfig Status: Core Module: core
Require user userid [userid]
...Require group group-name [group-name]
...Require valid-userRequire must be accompanied by
AuthName and AuthType directives, and directives such
as AuthUserFile
and AuthGroupFile (to
define users and groups) in order to work correctly. Example:
AuthType Basic
AuthName "Restricted Resource"
AuthUserFile /web/users
AuthGroupFile /web/groups
Require group admin
Require statement into a
<Limit>
section.See also
RLimitCPU Directive
Description: Limits the CPU consumption of processes launched
by Apache children Syntax: RLimitCPU seconds|max [seconds|max]Default: Unset; uses operating system defaultsContext: server config, virtual host, directory, .htaccess Override: All Status: Core Module: core max to indicate to the server that the limit should
be set to the maximum allowed by the operating system
configuration. Raising the maximum resource limit requires that
the server is running as root, or in the initial startup
phase.See also
RLimitMEM Directive
Description: Limits the memory consumption of processes launched
by Apache children Syntax: RLimitMEM bytes|max [bytes|max]Default: Unset; uses operating system defaultsContext: server config, virtual host, directory, .htaccess Override: All Status: Core Module: core max to indicate to the server that the limit should
be set to the maximum allowed by the operating system
configuration. Raising the maximum resource limit requires that
the server is running as root, or in the initial startup
phase.See also
RLimitNPROC Directive
Description: Limits the number of processes that can be launched by
processes launched by Apache children Syntax: RLimitNPROC number|max [number|max]Default: Unset; uses operating system defaultsContext: server config, virtual host, directory, .htaccess Override: All Status: Core Module: core max to indicate to the server that the limit
should be set to the maximum allowed by the operating system
configuration. Raising the maximum resource limit requires that
the server is running as root, or in the initial startup
phase.Note
cannot fork messages in the
error_log.See also
Satisfy Directive
Description: Interaction between host-level access control and
user authentication Syntax: Satisfy Any|AllDefault: Satisfy AllContext: directory, .htaccess Override: AuthConfig Status: Core Module: core Compatibility: Influenced by <Limit> and <LimitExcept> in version 2.0.51 and
laterAllow and Require used. The parameter can be
either All or Any. This directive is only
useful if access to a particular area is being restricted by both
username/password and client host address. In this case
the default behavior (All) is to require that the client
passes the address access restriction and enters a valid
username and password. With the Any option the client will be
granted access if they either pass the host restriction or enter a
valid username and password. This can be used to password restrict
an area, but to let clients from particular addresses in without
prompting for a password.
Require valid-user
Allow from 192.168.1
Satisfy Any
Satisfy directives can
be restricted to particular methods by <Limit> and <LimitExcept> sections.See also
ScriptInterpreterSource Directive
Description: Technique for locating the interpreter for CGI
scripts Syntax: ScriptInterpreterSource Registry|Registry-Strict|ScriptDefault: ScriptInterpreterSource ScriptContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Core Module: core Compatibility: Win32 only;
option Registry-Strict is available in Apache 2.0 and
laterScript. This causes Apache to use the interpreter pointed to
by the shebang line (first line, starting with #!) in the
script. On Win32 systems this line usually looks like:
#!C:/Perl/bin/perl.exe
perl is in the PATH, simply:
#!perl
ScriptInterpreterSource Registry will
cause the Windows Registry tree HKEY_CLASSES_ROOT to be
searched using the script file extension (e.g., .pl) as a
search key. The command defined by the registry subkey
Shell\ExecCGI\Command or, if it does not exist, by the subkey
Shell\Open\Command is used to open the script file. If the
registry keys cannot be found, Apache falls back to the behavior of the
Script option.Security
ScriptInterpreterSource
Registry with ScriptAlias'ed directories, because
Apache will try to execute every file within this
directory. The Registry setting may cause undesired
program calls on files which are typically not executed. For
example, the default open command on .htm files on
most Windows systems will execute Microsoft Internet Explorer, so
any HTTP request for an .htm file existing within the
script directory would start the browser in the background on the
server. This is a good way to crash your system within a minute or
so.Registry-Strict which is new in Apache
2.0 does the same thing as Registry but uses only the
subkey Shell\ExecCGI\Command. The
ExecCGI key is not a common one. It must be
configured manually in the windows registry and hence prevents
accidental program calls on your system.ServerAdmin Directive
Description: Email address that the server includes in error
messages sent to the client Syntax: ServerAdmin email-addressContext: server config, virtual host Status: Core Module: core ServerAdmin sets the e-mail address
that the server includes in any error messages it returns to the
client.
ServerAdmin www-admin@foo.example.com
ServerAlias Directive
Description: Alternate names for a host used when matching requests
to name-virtual hosts Syntax: ServerAlias hostname [hostname] ...Context: virtual host Status: Core Module: core ServerAlias directive sets the
alternate names for a host, for use with name-based virtual hosts.
<VirtualHost *>
ServerName server.domain.com
ServerAlias server server2.domain.com server2
# ...
</VirtualHost>
See also
ServerName Directive
Description: Hostname and port that the server uses to identify
itself Syntax: ServerName fully-qualified-domain-name[:port]Context: server config, virtual host Status: Core Module: core Compatibility: In version 2.0, this
directive supersedes the functionality of the Port
directive from version 1.3.ServerName directive sets the hostname and
port that the server uses to identify itself. This is used when
creating redirection URLs. For example, if the name of the
machine hosting the web server is simple.example.com,
but the machine also has the DNS alias www.example.com
and you wish the web server to be so identified, the following
directive should be used:
ServerName www.example.com:80
ServerName is specified, then the
server attempts to deduce the hostname by performing a reverse
lookup on the IP address. If no port is specified in the
ServerName, then the server will use the port
from the incoming
request. For optimal reliability and predictability, you should
specify an explicit hostname and port using the
ServerName directive.ServerName inside a
<VirtualHost>
section specifies what hostname must appear in the request's
Host: header to match this virtual host.UseCanonicalName directive for
settings which determine whether self-referential URL's (e.g., by the
mod_dir module) will refer to the
specified port, or to the port number given in the client's request.
See also
ServerPath Directive
Description: Legacy URL pathname for a name-based virtual host that
is accessed by an incompatible browser Syntax: ServerPath URL-pathContext: virtual host Status: Core Module: core ServerPath directive sets the legacy
URL pathname for a host, for use with name-based virtual hosts.See also
ServerRoot Directive
Description: Base directory for the server installation Syntax: ServerRoot directory-pathDefault: ServerRoot /usr/local/apacheContext: server config Status: Core Module: core ServerRoot directive sets the
directory in which the server lives. Typically it will contain the
subdirectories conf/ and logs/. Relative
paths in other configuration directives (such as Include or LoadModule, for example) are taken as
relative to this directory.Example
ServerRoot /home/httpd
See also
-d
option to httpdServerRootServerSignature Directive
Description: Configures the footer on server-generated documents Syntax: ServerSignature On|Off|EMailDefault: ServerSignature OffContext: server config, virtual host, directory, .htaccess Override: All Status: Core Module: core ServerSignature directive allows the
configuration of a trailing footer line under server-generated
documents (error messages, mod_proxy ftp directory
listings, mod_info output, ...). The reason why you
would want to enable such a footer line is that in a chain of proxies,
the user often has no possibility to tell which of the chained servers
actually produced a returned error message.Off
setting, which is the default, suppresses the footer line (and is
therefore compatible with the behavior of Apache-1.2 and
below). The On setting simply adds a line with the
server version number and ServerName of the serving virtual host,
and the EMail setting additionally creates a
"mailto:" reference to the ServerAdmin of the referenced
document.ServerTokens directive.See also
ServerTokens Directive
Description: Configures the Server HTTP response
headerSyntax: ServerTokens Major|Minor|Min[imal]|Prod[uctOnly]|OS|FullDefault: ServerTokens FullContext: server config Status: Core Module: core Server response
header field which is sent back to clients includes a
description of the generic OS-type of the server as well as
information about compiled-in modules.
ServerTokens Prod[uctOnly]Server:
ApacheServerTokens MajorServer:
Apache/2ServerTokens MinorServer:
Apache/2.0ServerTokens Min[imal]Server:
Apache/2.0.41ServerTokens OSServer: Apache/2.0.41
(Unix)ServerTokens Full (or not specified)Server: Apache/2.0.41
(Unix) PHP/4.2.2 MyMod/1.2ServerSignature directive.See also
SetHandler Directive
Description: Forces all matching files to be processed by a
handler Syntax: SetHandler handler-name|NoneContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Core Module: core Compatibility: Moved into the core in Apache 2.0 .htaccess file or a
<Directory> or
<Location>
section, this directive forces all matching files to be parsed
through the handler given by
handler-name. For example, if you had a directory you
wanted to be parsed entirely as imagemap rule files, regardless
of extension, you might put the following into an
.htaccess file in that directory:
SetHandler imap-file
http://servername/status was called, you might put
the following into httpd.conf:
<Location /status>
SetHandler server-status
</Location>
SetHandler
directive by using the value None.See also
SetInputFilter Directive
Description: Sets the filters that will process client requests and POST
input Syntax: SetInputFilter filter[;filter...]Context: server config, virtual host, directory, .htaccess Override: FileInfo Status: Core Module: core SetInputFilter directive sets the
filter or filters which will process client requests and POST
input when they are received by the server. This is in addition to
any filters defined elsewhere, including the
AddInputFilter
directive.See also
SetOutputFilter Directive
Description: Sets the filters that will process responses from the
server Syntax: SetOutputFilter filter[;filter...]Context: server config, virtual host, directory, .htaccess Override: FileInfo Status: Core Module: core SetOutputFilter directive sets the filters
which will process responses from the server before they are
sent to the client. This is in addition to any filters defined
elsewhere, including the
AddOutputFilter
directive./www/data/ directory for server-side
includes.
<Directory /www/data/>
SetOutputFilter INCLUDES
</Directory>
See also
TimeOut Directive
Description: Amount of time the server will wait for
certain events before failing a request Syntax: TimeOut secondsDefault: TimeOut 300Context: server config, virtual host Status: Core Module: core TimeOut directive currently defines
the amount of time Apache will wait for three things:
TraceEnable Directive
Description: Determines the behaviour on TRACE
requestsSyntax: TraceEnable [on|off|extended]Default: TraceEnable onContext: server config Status: Core Module: core Compatibility: Available in Apache 1.3.34, 2.0.55 and later TRACE for both
the core server and mod_proxy. The default
TraceEnable on permits TRACE requests per
RFC 2616, which disallows any request body to accompany the request.
TraceEnable off causes the core server and
mod_proxy to return a 405 (Method not
allowed) error to the client.TraceEnable
extended directive. The core (as an origin server) will
restrict the request body to 64k (plus 8k for chunk headers if
Transfer-Encoding: chunked is used). The core will
reflect the full headers and all chunk headers with the response
body. As a proxy server, the request body is not restricted to 64k.UseCanonicalName Directive
Description: Configures how the server determines its own name and
port Syntax: UseCanonicalName On|Off|DNSDefault: UseCanonicalName OnContext: server config, virtual host, directory Status: Core Module: core UseCanonicalName On Apache will use the hostname and port
specified in the ServerName
directive to construct the canonical name for the server. This name
is used in all self-referential URLs, and for the values of
SERVER_NAME and SERVER_PORT in CGIs.UseCanonicalName Off Apache will form
self-referential URLs using the hostname and port supplied by
the client if any are supplied (otherwise it will use the
canonical name, as defined above). These values are the same
that are used to implement name based virtual hosts,
and are available with the same clients. The CGI variables
SERVER_NAME and SERVER_PORT will be
constructed from the client supplied values as well.www. You'll notice that if the users
type a shortname, and a URL which is a directory, such as
http://www/splat, without the trailing
slash then Apache will redirect them to
http://www.domain.com/splat/. If you have
authentication enabled, this will cause the user to have to
authenticate twice (once for www and once again
for www.domain.com -- see the
FAQ on this subject for more information). But if
UseCanonicalName is set Off, then
Apache will redirect to http://www/splat/.UseCanonicalName DNS,
which is intended for use with mass IP-based virtual hosting to
support ancient clients that do not provide a
Host: header. With this option Apache does a
reverse DNS lookup on the server IP address that the client
connected to in order to work out self-referential URLs.Warning
SERVER_NAME
they may be broken by this option. The client is essentially free
to give whatever value they want as a hostname. But if the CGI is
only using SERVER_NAME to construct self-referential URLs
then it should be just fine.See also
<VirtualHost> Directive
Description: Contains directives that apply only to a specific
hostname or IP address Syntax: <VirtualHost
addr[:port] [addr[:port]]
...> ... </VirtualHost>Context: server config Status: Core Module: core <VirtualHost> and
</VirtualHost> are used to enclose a group of
directives that will apply only to a particular virtual host. Any
directive that is allowed in a virtual host context may be
used. When the server receives a request for a document on a
particular virtual host, it uses the configuration directives
enclosed in the <VirtualHost>
section. Addr can be:
*, which is used only in combination with
NameVirtualHost * to match all IP addresses; or_default_, which is used only
with IP virtual hosting to catch unmatched IP addresses.Example
<VirtualHost 10.1.2.3>
ServerAdmin webmaster@host.foo.com
DocumentRoot /www/docs/host.foo.com
ServerName host.foo.com
ErrorLog logs/host.foo.com-error_log
TransferLog logs/host.foo.com-access_log
</VirtualHost>
<VirtualHost [2001:db8::a00:20ff:fea7:ccea]>
ServerAdmin webmaster@host.example.com
DocumentRoot /www/docs/host.example.com
ServerName host.example.com
ErrorLog logs/host.example.com-error_log
TransferLog logs/host.example.com-access_log
</VirtualHost>
ifconfig alias command -- if
your OS supports it).Note
<VirtualHost> does
not affect what addresses Apache listens on. You
may need to ensure that Apache is listening on the correct addresses
using Listen._default_ can be specified in
which case this virtual host will match any IP address that is
not explicitly listed in another virtual host. In the absence
of any _default_ virtual host the "main" server config,
consisting of all those definitions outside any VirtualHost
section, is used when no IP-match occurs. (But note that any IP
address that matches a NameVirtualHost directive will use neither
the "main" server config nor the _default_ virtual host.
See the name-based virtual hosting
documentation for further details.):port to change the port that is
matched. If unspecified then it defaults to the same port as the
most recent Listen
statement of the main server. You may also specify :*
to match all ports on that address. (This is recommended when used
with _default_.)Security
See also
mod/directives.html 100644 0 0 66344 11074462673 12062 0 ustar 0 0
Terms Used to Describe Directives
Description
Syntax
http://www.example.com/path/to/file.html/path/to/file.html. The
url-path represents a web-view of a resource, as
opposed to a file-system view./usr/local/apache/htdocs/path/to/file.html.
Unless otherwise specified, a file-path which does
not begin with a slash will be treated as relative to the ServerRoot./usr/local/apache/htdocs/path/to/.file.html.file.html.en
contains two extensions: .html and
.en. For Apache directives, you may specify
extensions with or without the leading dot. In
addition, extensions are not case sensitive.text/html.
Default
Context
httpd.conf), but
not within any
<VirtualHost>
or <Directory>
containers. It is not allowed in .htaccess files
at all.<VirtualHost>
containers in the server
configuration files.<Directory>,
<Location>,
and <Files>
containers in the server configuration files, subject to the
restrictions outlined in How
Directory, Location and Files sections work..htaccess files. It may not be processed, though
depending upon the overrides currently active.server config, .htaccess" can be used in the
httpd.conf file and in .htaccess
files, but not within any <Directory> or
<VirtualHost>
containers.
Override
.htaccess file. If
the directive's context
doesn't permit it to appear in .htaccess files,
then no context will be listed.AllowOverride directive, and apply
to a particular scope (such as a directory) and all
descendants, unless further modified by other
AllowOverride directives at
lower levels. The documentation for that directive also lists the
possible override names available.
Status
Module
Compatibility
Directive Index
mod/index.html 100644 0 0 30101 11074462673 11006 0 ustar 0 0
mod/leader.html 100644 0 0 13614 11074462673 11145 0 ustar 0 0
Module Index
See also
Core Features and Multi-Processing
Modules
worker
MPMworker MPMOther Modules
ls command or the
Win32 dir shell commandmod_davExpires and
Cache-Control HTTP headers according to user-specified
criteriamod_proxy extension for
CONNECT request handlingmod_proxymod_proxy
mod/mod_access.html 100644 0 0 46267 11074462673 12023 0 ustar 0 0
Apache MPM leader
Description: An experimental variant of the standard worker
MPMStatus: MPM Module Identifier: mpm_leader_module Source File: leader.c Summary
Warning
worker MPM. It uses a Leader/Followers design pattern
to coordinate work among threads. For more info, see http://deuce.doc.wustl.edu/doc/pspdfs/lf.pdf.leader MPM, add
--with-mpm=leader to the configure
script's arguments when building the httpd.--enable-nonportable-atomics=yes to the
configure script's arguments. This will cause
APR to implement atomic operations
using efficient opcodes not available in older CPUs.
mod/mod_actions.html 100644 0 0 17523 11074462673 12213 0 ustar 0 0
Apache Module mod_access
Description: Provides access control based on client hostname, IP
address, or other characteristics of the client request. Status: Base Module Identifier: access_module Source File: mod_access.c Compatibility: Available only in versions prior to 2.1 Summary
mod_access are used
in <Directory>,
<Files>, and
<Location> sections
as well as .htaccess
files to control access to particular parts of the server. Access
can be controlled based on the client hostname, IP address, or
other characteristics of the client request, as captured in environment variables. The Allow and Deny directives are used to
specify which clients are or are not allowed access to the server,
while the Order
directive sets the default access state, and configures how the
Allow and Deny directives interact with each
other.Satisfy directive is used
to determine how the two sets of restrictions interact.GET, PUT,
POST, etc). This is the desired behavior in most
cases. However, it is possible to restrict some methods, while
leaving other methods unrestricted, by enclosing the directives
in a <Limit> section.Allow Directive
Description: Controls which hosts can access an area of the
server Syntax: Allow from
all|host|env=env-variable
[host|env=env-variable] ...Context: directory, .htaccess Override: Limit Status: Base Module: mod_access Allow directive affects which hosts can
access an area of the server. Access can be controlled by
hostname, IP address, IP address range, or by other
characteristics of the client request captured in environment
variables.from. The subsequent arguments can take three
different forms. If Allow from all is specified, then
all hosts are allowed access, subject to the configuration of the
Deny and Order directives as discussed
below. To allow only particular hosts or groups of hosts to access
the server, the host can be specified in any of the
following formats:
Example:
Allow from apache.org
Allow from .net example.edu
foo.apache.org but it will not
match fooapache.org. This configuration will cause
Apache to perform a double reverse DNS lookup on the client IP
address, regardless of the setting of the HostnameLookups directive. It will do
a reverse DNS lookup on the IP address to find the associated
hostname, and then do a forward lookup on the hostname to assure
that it matches the original IP address. Only if the forward
and reverse DNS are consistent and the hostname matches will
access be allowed.Example:
Allow from 10.1.2.3
Allow from 192.168.1.104 192.168.1.205
Example:
Allow from 10.1
Allow from 10 172.20 192.168.2
Example:
Allow from 10.1.0.0/255.255.0.0
Example:
Allow from 10.1.0.0/16
Allow from 2001:db8::a00:20ff:fea7:ccea
Allow from 2001:db8::a00:20ff:fea7:ccea/10
Allow directive allows access to the server
to be controlled based on the existence of an environment variable. When Allow from
env=env-variable is specified, then the request is
allowed access if the environment variable env-variable
exists. The server provides the ability to set environment
variables in a flexible way based on characteristics of the client
request using the directives provided by
mod_setenvif. Therefore, this directive can be
used to allow access based on such factors as the clients
User-Agent (browser type), Referer, or
other HTTP request header fields.Example:
SetEnvIf User-Agent ^KnockKnock/2\.0 let_me_in
<Directory /docroot>
Order Deny,Allow
Deny from all
Allow from env=let_me_in
</Directory>
KnockKnock/2.0 will be allowed access, and all
others will be denied.Deny Directive
Description: Controls which hosts are denied access to the
server Syntax: Deny from all|host|env=env-variable
[host|env=env-variable] ...Context: directory, .htaccess Override: Limit Status: Base Module: mod_access Deny directive are
identical to the arguments for the Allow directive.Order Directive
Description: Controls the default access state and the order in which
Allow and Deny are
evaluated.Syntax: Order orderingDefault: Order Deny,AllowContext: directory, .htaccess Override: Limit Status: Base Module: mod_access Order directive, along with the
Allow and Deny directives, controls a
three-pass access control system. The first pass processes either
all Allow or all
Deny directives, as
specified by the Order directive. The second
pass parses the rest of the directives (Deny or Allow). The third pass applies to
all requests which do not match either of the first two.Allow
and Deny directives are
processed, unlike a typical firewall, where only the first match is
used. The last match is effective (also unlike a typical firewall).
Additionally, the order in which lines appear in the configuration
files is not significant -- all Allow lines are processed as one
group, all Deny lines are
considered as another, and the default state is considered by
itself.
Allow,DenyAllow
directives are evaluated; at least one must match, or the request
is rejected. Next, all Deny directives are evaluated. If
any matches, the request is rejected. Last, any requests which do
not match an Allow or a
Deny directive are
denied by default.Deny,AllowDeny
directives are evaluated; if any match, the request is denied
unless it also matches an Allow directive. Any requests
which do not match any Allow or Deny directives are
permitted.Mutual-failureOrder
Allow,Deny and is deprecated in its favor.
Match
Allow,Deny result
Deny,Allow result
Match Allow only
Request allowed
Request allowed
Match Deny only
Request denied
Request denied
No match
Default to second directive: Denied
Default to second directive: Allowed
Match both Allow & Deny
Final match controls: Denied
Final match controls: Allowed
Order Deny,Allow
Deny from all
Allow from apache.org
Deny access to the server.
Order Allow,Deny
Allow from apache.org
Deny from foo.apache.org
Order in the
last example is changed to Deny,Allow, all hosts will
be allowed access. This happens because, regardless of the actual
ordering of the directives in the configuration file, the
Allow from apache.org will be evaluated last and will
override the Deny from foo.apache.org. All hosts not in
the apache.org domain will also be allowed access
because the default state is Allow.Order directive can
affect access to a part of the server even in the absence of
accompanying Allow and
Deny directives because
of its effect on the default access state. For example,
<Directory /www>
Order Allow,Deny
</Directory>
Deny all access
to the /www directory because the default access state
is set to Deny.Order directive controls the order of
access directive processing only within each phase of the server's
configuration processing. This implies, for example, that an
Allow or Deny directive occurring in a
<Location> section
will always be evaluated after an Allow or Deny directive occurring in a
<Directory>
section or .htaccess file, regardless of the setting of
the Order directive. For details on the
merging of configuration sections, see the documentation on How Directory, Location and Files sections
work.
mod/mod_alias.html 100644 0 0 56110 11074462673 11637 0 ustar 0 0
Apache Module mod_actions
Description: This module provides for executing CGI scripts based on
media type or request method. Status: Base Module Identifier: actions_module Source File: mod_actions.c Summary
Action directive lets you run CGI
scripts whenever a file of a certain type is requested. The
Script directive lets
you run CGI scripts whenever a particular method is used in a
request. This makes it much easier to execute scripts that process
files.Action Directive
Description: Activates a CGI script for a particular handler or
content-type Syntax: Action action-type cgi-scriptContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_actions ScriptAlias or AddHandler. The
action-type can be either a handler or a MIME content type. It
sends the URL and file path of the requested document using the
standard CGI PATH_INFO and PATH_TRANSLATED environment
variables.Examples
# Requests for files of a particular type:
Action image/gif /cgi-bin/images.cgi
# Files of a particular file extension
AddHandler my-file-type .xyz
Action my-file-type /cgi-bin/program.cgi
image/gif will instead be handled by the
specified cgi script /cgi-bin/images.cgi..xyz are handled instead by the specified cgi script
/cgi-bin/program.cgi.See also
Script Directive
Description: Activates a CGI script for a particular request
method. Syntax: Script method cgi-scriptContext: server config, virtual host, directory Status: Base Module: mod_actions ScriptAlias or AddHandler. The URL and
file path of the requested document is sent using the standard CGI
PATH_INFO and PATH_TRANSLATED environment variables.
Any arbitrary method name may be used. Method names are
case-sensitive, so
Script PUT and
Script put have two entirely different
effects.
GET
will only be called if there are query arguments present
(e.g., foo.html?hi). Otherwise, the request will
proceed normally.Examples
# For <ISINDEX>-style searching
Script GET /cgi-bin/search
# A CGI PUT handler
Script PUT /~bob/put.cgi
mod/mod_asis.html 100644 0 0 12002 11074462673 11475 0 ustar 0 0
Apache Module mod_alias
Description: Provides for mapping different parts of the host
filesystem in the document tree and for URL redirection Status: Base Module Identifier: alias_module Source File: mod_alias.c Summary
Alias and ScriptAlias directives are used to
map between URLs and filesystem paths. This allows for content
which is not directly under the DocumentRoot served as part of the web
document tree. The ScriptAlias directive has the
additional effect of marking the target directory as containing
only CGI scripts.Redirect
directives are used to instruct clients to make a new request with
a different URL. They are often used when a resource has moved to
a new location.mod_alias is designed to handle simple URL
manipulation tasks. For more complicated tasks such as
manipulating the query string, use the tools provided by
mod_rewrite.Directives
Topics
See also
Order of Processing
<VirtualHost>
section) they are processed in a particular order.Redirect or RedirectMatch will never have Aliases
applied. Second, the Aliases and Redirects are processed in the order
they appear in the configuration files, with the first match taking
precedence.
Alias /foo/bar /baz
Alias /foo /gaq
/foo Alias
would always match before the /foo/bar Alias, so the latter directive would be
ignored.Alias Directive
Description: Maps URLs to filesystem locations Syntax: Alias URL-path
file-path|directory-pathContext: server config, virtual host Status: Base Module: mod_alias Alias directive allows documents to
be stored in the local filesystem other than under the
DocumentRoot. URLs with a
(%-decoded) path beginning with url-path will be mapped
to local files beginning with directory-path. The
url-path is case-sensitive, even on case-insenitive
file systems.Example:
Alias /image /ftp/pub/image
Alias
/icons/ /usr/local/apache/icons/ then the url
/icons will not be aliased.<Directory> sections which
cover the destination of aliases. Aliasing occurs before
<Directory> sections
are checked, so only the destination of aliases are affected.
(Note however <Location>
sections are run through once before aliases are performed, so
they will apply.)Alias to a
directory outside of your DocumentRoot, you may need to explicitly
permit access to the target directory.Example:
Alias /image /ftp/pub/image
<Directory /ftp/pub/image>
Order allow,deny
Allow from all
</Directory>
AliasMatch Directive
Description: Maps URLs to filesystem locations using regular
expressions Syntax: AliasMatch regex
file-path|directory-pathContext: server config, virtual host Status: Base Module: mod_alias Alias, but makes use of standard
regular expressions, instead of simple prefix matching. The
supplied regular expression is matched against the URL-path, and
if it matches, the server will substitute any parenthesized
matches into the given string and use it as a filename. For
example, to activate the /icons directory, one might
use:
AliasMatch ^/icons(.*) /usr/local/apache/icons$1
AliasMatch (?i)^/image(.*) /ftp/pub/image$1
Redirect Directive
Description: Sends an external redirect asking the client to fetch
a different URL Syntax: Redirect [status] URL-path
URLContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_alias Example:
Redirect /service http://foo2.bar.com/service
Note
<Directory>
sections.
send_error_response in http_protocol.c).Example:
Redirect permanent /one http://example.com/two
Redirect 303 /three http://example.com/other
RedirectMatch Directive
Description: Sends an external redirect based on a regular expression match
of the current URL Syntax: RedirectMatch [status] regex
URLContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_alias Redirect, but makes use of standard
regular expressions, instead of simple prefix matching. The
supplied regular expression is matched against the URL-path, and
if it matches, the server will substitute any parenthesized
matches into the given string and use it as a filename. For
example, to redirect all GIF files to like-named JPEG files on
another server, one might use:
RedirectMatch (.*)\.gif$ http://www.anotherserver.com$1.jpg
RedirectPermanent Directive
Description: Sends an external permanent redirect asking the client to fetch
a different URL Syntax: RedirectPermanent URL-path URLContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_alias Redirect
permanent.RedirectTemp Directive
Description: Sends an external temporary redirect asking the client to fetch
a different URL Syntax: RedirectTemp URL-path URLContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_alias Redirect temp.ScriptAlias Directive
Description: Maps a URL to a filesystem location and designates the
target as a CGI script Syntax: ScriptAlias URL-path
file-path|directory-pathContext: server config, virtual host Status: Base Module: mod_alias ScriptAlias directive has the same
behavior as the Alias
directive, except that in addition it marks the target directory
as containing CGI scripts that will be processed by mod_cgi's cgi-script handler. URLs with a case-sensitive
(%-decoded) path beginning with URL-path will be mapped
to scripts beginning with the second argument, which is a full
pathname in the local filesystem.Example:
ScriptAlias /cgi-bin/ /web/cgi-bin/
http://myserver/cgi-bin/foo would cause the
server to run the script /web/cgi-bin/foo. This configuration
is essentially equivalent to:
Alias /cgi-bin/ /web/cgi-bin/
<Location /cgi-bin >
SetHandler cgi-script
Options +ExecCGI
</Location>
It is safer to avoid placing CGI scripts under the
DocumentRoot in order to
avoid accidentally revealing their source code if the
configuration is ever changed. The
ScriptAlias makes this easy by mapping a
URL and designating CGI scripts at the same time. If you do
choose to place your CGI scripts in a directory already
accessible from the web, do not use
ScriptAlias. Instead, use <Directory>, SetHandler, and Options as in:
This is necessary since multiple URL-paths can map
to the same filesystem location, potentially bypassing the
<Directory /usr/local/apache2/htdocs/cgi-bin >
SetHandler cgi-script
Options ExecCGI
</Directory>
ScriptAlias and revealing the source code
of the CGI scripts if they are not restricted by a
Directory section.See also
ScriptAliasMatch Directive
Description: Maps a URL to a filesystem location using a regular expression
and designates the target as a CGI script Syntax: ScriptAliasMatch regex
file-path|directory-pathContext: server config, virtual host Status: Base Module: mod_alias ScriptAlias, but makes use of standard
regular expressions, instead of simple prefix matching. The
supplied regular expression is matched against the URL-path,
and if it matches, the server will substitute any parenthesized
matches into the given string and use it as a filename. For
example, to activate the standard /cgi-bin, one
might use:
ScriptAliasMatch ^/cgi-bin(.*) /usr/local/apache/cgi-bin$1
mod/mod_auth.html 100644 0 0 30033 11074462673 11503 0 ustar 0 0
Apache Module mod_asis
Description: Sends files that contain their own
HTTP headers Status: Base Module Identifier: asis_module Source File: mod_asis.c Summary
send-as-is
which causes Apache to send the document without adding most of
the usual HTTP headers.httpd/send-as-is.Directives
Topics
See also
Usage
send-as-is handler e.g.AddHandler send-as-is asis.asis extension
will then be sent by Apache to the client with almost no
changes. In particular, HTTP headers are derived from the file
itself according to mod_cgi rules, so an asis
file must include valid headers, and may also use the CGI
Status: header to determine the HTTP response code.
Status: 301 Now where did I leave that URL
Location: http://xyz.abc.com/foo/bar.html
Content-type: text/html
<html>
<head>
<title>Lame excuses'R'us</title>
</head>
<body>
<h1>Fred's exceptionally wonderful page has moved to
<a href="http://xyz.abc.com/foo/bar.html">Joe's</a>
site.
</h1>
</body>
</html>
Notes:
Date: and Server:
header to the data returned to the client, so these should not be
included in the file. The server does not add a
Last-Modified header; it probably should.
mod/mod_auth_anon.html 100644 0 0 33522 11074462673 12524 0 ustar 0 0
Apache Module mod_auth
Description: User authentication using text files Status: Base Module Identifier: auth_module Source File: mod_auth.c Compatibility: Available only in versions prior to 2.1 Summary
mod_auth_dbm. HTTP Digest
Authentication is provided by mod_auth_digest.AuthAuthoritative Directive
Description: Sets whether authorization and authentication are
passed to lower level modules Syntax: AuthAuthoritative On|OffDefault: AuthAuthoritative OnContext: directory, .htaccess Override: AuthConfig Status: Base Module: mod_auth AuthAuthoritative directive
explicitly to Off allows for both authentication and
authorization to be passed on to lower level modules (as defined in the
modules.c files) if there is no userID
or rule matching the supplied userID. If there is a
userID and/or rule specified; the usual password and access checks
will be applied and a failure will give an "Authentication Required"
reply.Require
directive applies to more than one module; then the first module
will verify the credentials; and no access is passed on;
regardless of the AuthAuthoritative setting.mod_auth_dbm,
mod_auth_msql, and mod_auth_anon.
These modules supply the bulk of the user credential checking; but
a few (administrator) related accesses fall through to a lower
level with a well protected AuthUserFile.Security
AuthUserFile and the AuthGroupFile are stored outside the document tree of
the web-server; do not put them in the directory that they
protect. Otherwise, clients will be able to download the AuthUserFile and the AuthGroupFile.AuthGroupFile Directive
Description: Sets the name of a text file containing the list
of user groups for authentication Syntax: AuthGroupFile file-pathContext: directory, .htaccess Override: AuthConfig Status: Base Module: mod_auth AuthGroupFile directive sets the
name of a textual file containing the list of user groups for user
authentication. File-path is the path to the group
file. If it is not absolute, it is treated as relative to the ServerRoot.Example:
mygroup: bob joe anne
AuthDBMGroupFile provides a much better performance.Security
AuthGroupFile is
stored outside the document tree of the web-server; do not
put it in the directory that it protects. Otherwise, clients may
be able to download the AuthGroupFile.AuthUserFile Directive
Description: Sets the name of a text file containing the list of users and
passwords for authentication Syntax: AuthUserFile file-pathContext: directory, .htaccess Override: AuthConfig Status: Base Module: mod_auth AuthUserFile directive sets the name
of a textual file containing the list of users and passwords for
user authentication. File-path is the path to the user
file. If it is not absolute (i.e., if it doesn't begin
with a slash), it is treated as relative to the ServerRoot.mod_auth will
use the first occurrence to verify the password.htpasswd
which is installed as part of the binary distribution, or which
can be found in src/support, is used to maintain
this password file. See the man
page for more details. In short:Filename with
username as the initial ID. It will prompt for the
password:
htpasswd -c Filename username
username2 in the password file
Filename:
htpasswd Filename username2
AuthDBMUserFile should be used
instead.Security
AuthUserFile is
stored outside the document tree of the web-server. Do
not put it in the directory that it protects.
Otherwise, clients may be able to download the
AuthUserFile.
mod/mod_auth_dbm.html 100644 0 0 32450 11074462673 12332 0 ustar 0 0
Apache Module mod_auth_anon
Description: Allows "anonymous" user access to authenticated
areas Status: Extension Module Identifier: auth_anon_module Source File: mod_auth_anon.c Compatibility: Available only in versions prior to 2.1 Summary
Directives
Anonymous Anonymous_Authoritative Anonymous_LogEmail Anonymous_MustGiveEmail Anonymous_NoUserID Anonymous_VerifyEmailTopics
Example
Anonymous_NoUserID)Anonymous_MustGiveEmail)Anonymous_VerifyEmail)anonymous guest www test
welcome and comparison is not case
sensitive. (Anonymous)Anonymous_LogEmail)Excerpt of httpd.conf:
Anonymous_NoUserID off
Anonymous_MustGiveEmail on
Anonymous_VerifyEmail on
Anonymous_LogEmail on
Anonymous anonymous guest www test welcome
AuthName "Use 'anonymous' & Email address for guest entry"
AuthType basic
# An
AuthUserFile/AuthDBUserFile/AuthDBMUserFile
# directive must be specified, or use
# Anonymous_Authoritative for public access.
# In the .htaccess for the public directory, add:
<Files *>
Order Deny,Allow
Allow from all
Require valid-user
</Files>
Anonymous Directive
Description: Specifies userIDs that are allowed access without
password verification Syntax: Anonymous user [user] ...Context: directory, .htaccess Override: AuthConfig Status: Extension Module: mod_auth_anon
I strongly suggest that the magic username
'anonymous' is always one of the allowed
userIDs.Example:
Anonymous anonymous "Not Registered" "I don't know"
Anonymous_Authoritative Directive
Description: Configures if authorization will fall-through
to other methods Syntax: Anonymous_Authoritative On|OffDefault: Anonymous_Authoritative OffContext: directory, .htaccess Override: AuthConfig Status: Extension Module: mod_auth_anon On, there is no fall-through to other
authentication methods. So if a userID does not match the values
specified in the Anonymous
directive, access is denied.Anonymous_LogEmail Directive
Description: Sets whether the password entered will be logged in the
error log Syntax: Anonymous_LogEmail On|OffDefault: Anonymous_LogEmail OnContext: directory, .htaccess Override: AuthConfig Status: Extension Module: mod_auth_anon On, the default, the 'password' entered
(which hopefully contains a sensible email address) is logged in
the error log.Anonymous_MustGiveEmail Directive
Description: Specifies whether blank passwords are allowed Syntax: Anonymous_MustGiveEmail On|OffDefault: Anonymous_MustGiveEmail OnContext: directory, .htaccess Override: AuthConfig Status: Extension Module: mod_auth_anon Anonymous_NoUserID Directive
Description: Sets whether the userID field may be empty Syntax: Anonymous_NoUserID On|OffDefault: Anonymous_NoUserID OffContext: directory, .htaccess Override: AuthConfig Status: Extension Module: mod_auth_anon On, users can leave the userID (and
perhaps the password field) empty. This can be very convenient for
MS-Explorer users who can just hit return or click directly on the
OK button; which seems a natural reaction.Anonymous_VerifyEmail Directive
Description: Sets whether to check the password field for a correctly
formatted email address Syntax: Anonymous_VerifyEmail On|OffDefault: Anonymous_VerifyEmail OffContext: directory, .htaccess Override: AuthConfig Status: Extension Module: mod_auth_anon On the 'password' entered is checked for
at least one '@' and a '.' to encourage users to enter valid email
addresses (see the above Anonymous_LogEmail).
mod/mod_auth_digest.html 100644 0 0 53657 11074462673 13063 0 ustar 0 0
Apache Module mod_auth_dbm
Description: Provides for user authentication using DBM
files Status: Extension Module Identifier: auth_dbm_module Source File: mod_auth_dbm.c Compatibility: Available only in versions prior to 2.1 Summary
mod_auth.Directives
See also
AuthDBMAuthoritative Directive
Description: Sets whether authentication and authorization will be
passed on to lower level modules Syntax: AuthDBMAuthoritative On|OffDefault: AuthDBMAuthoritative OnContext: directory, .htaccess Override: AuthConfig Status: Extension Module: mod_auth_dbm AuthDBMAuthoritative
directive explicitly to Off allows for both
authentication and authorization to be passed on to lower level
modules (as defined in the modules.c files) if there
is no userID or rule matching the
supplied userID. If there is a userID and/or rule specified; the
usual password and access checks will be applied and a failure will
give an "Authentication Required" reply.Require
directive applies to more than one module; then the first module
will verify the credentials; and no access is passed on;
regardless of the AuthDBMAuthoritative
setting.mod_auth. Whereas this
DBM module supplies the bulk of the user credential checking; a
few (administrator) related accesses fall through to a lower
level with a well protected .htpasswd file.Security:
.htaccess file; and verify that this
is really what you want; Generally it is easier to just secure
a single .htpasswd file, than it is to secure a
database which might have more access interfaces.AuthDBMGroupFile Directive
Description: Sets the name of the database file containing the list
of user groups for authentication Syntax: AuthDBMGroupFile file-pathContext: directory, .htaccess Override: AuthConfig Status: Extension Module: mod_auth_dbm AuthDBMGroupFile directive sets the
name of a DBM file containing the list of user groups for user
authentication. File-path is the absolute path to the
group file.AuthDBMGroupFile is stored outside the
document tree of the web-server; do not put it in the
directory that it protects. Otherwise, clients will be able to
download the AuthDBMGroupFile unless
otherwise protected.
AuthDBMGroupFile /www/userbase
AuthDBMUserFile /www/userbase
Unix Crypt-ed Password:List of Groups[:(ignored)]
AuthDBMType Directive
Description: Sets the type of database file that is used to
store passwords Syntax: AuthDBMType default|SDBM|GDBM|NDBM|DBDefault: AuthDBMType defaultContext: directory, .htaccess Override: AuthConfig Status: Extension Module: mod_auth_dbm Compatibility: Available in version 2.0.30 and later. AuthDBMUserFile Directive
Description: Sets thename of a database file containing the list of users and
passwords for authentication Syntax: AuthDBMUserFile file-pathContext: directory, .htaccess Override: AuthConfig Status: Extension Module: mod_auth_dbm AuthDBMUserFile directive sets the
name of a DBM file containing the list of users and passwords for
user authentication. File-path is the absolute path to
the user file.Security:
AuthDBMUserFile is stored
outside the document tree of the web-server; do not put it in
the directory that it protects. Otherwise, clients will be able to
download the AuthDBMUserFile.dbmmanage is included with
Apache. This program can be used to create and update DBM
format password files for use with this module.
mod/mod_auth_ldap.html 100644 0 0 137753 11074462673 12544 0 ustar 0 0
Apache Module mod_auth_digest
Description: User authentication using MD5
Digest Authentication. Status: Experimental Module Identifier: auth_digest_module Source File: mod_auth_digest.c Summary
Directives
AuthDigestAlgorithm AuthDigestDomain AuthDigestFile AuthDigestGroupFile AuthDigestNcCheck AuthDigestNonceFormat AuthDigestNonceLifetime AuthDigestQop AuthDigestShmemSizeTopics
See also
Using Digest Authentication
AuthType Digest and
AuthDigestFile instead
of the normal AuthType Basic and AuthUserFile; also, replace any AuthGroupFile with AuthDigestGroupFile. Then add a
AuthDigestDomain directive
containing at least the root URI(s) for this protection space.htdigest tool.Example:
<Location /private/>
AuthType Digest
AuthName "private area"
AuthDigestDomain /private/ http://mirror.my.dom/private2/
AuthDigestFile /web/auth/.digest_pw
Require valid-user
</Location>
Note
Working with MS Internet Explorer
GET requests with a query string were not RFC compliant.
There are a few ways to work around this issue.POST requests instead of
GET requests to pass data to your program. This method
is the simplest approach if your application can work with this
limitation.
AuthDigestEnableQueryStringHack environment variable.
If AuthDigestEnableQueryStringHack is set for the
request, Apache will take steps to work around the MSIE bug and
remove the query string from the digest comparison. Using this
method would look similar to the following.Using Digest Authentication with MSIE:
BrowserMatch "MSIE" AuthDigestEnableQueryStringHack=On
BrowserMatch
directive for more details on conditionally setting environment
variablesAuthDigestAlgorithm Directive
Description: Selects the algorithm used to calculate the challenge and
response hases in digest authentication Syntax: AuthDigestAlgorithm MD5|MD5-sessDefault: AuthDigestAlgorithm MD5Context: directory, .htaccess Override: AuthConfig Status: Experimental Module: mod_auth_digest AuthDigestAlgorithm directive
selects the algorithm used to calculate the challenge and response
hashes.
MD5-sess is not correctly implemented yet.
AuthDigestDomain Directive
Description: URIs that are in the same protection space for digest
authentication Syntax: AuthDigestDomain URI [URI] ...Context: directory, .htaccess Override: AuthConfig Status: Experimental Module: mod_auth_digest AuthDigestDomain directive allows
you to specify one or more URIs which are in the same protection
space (i.e. use the same realm and username/password info).
The specified URIs are prefixes, i.e. the client will assume
that all URIs "below" these are also protected by the same
username/password. The URIs may be either absolute URIs (i.e.
including a scheme, host, port, etc) or relative URIs.AuthDigestNcCheck is on.AuthDigestFile Directive
Description: Location of the text file containing the list
of users and encoded passwords for digest authentication Syntax: AuthDigestFile file-pathContext: directory, .htaccess Override: AuthConfig Status: Experimental Module: mod_auth_digest AuthDigestFile directive sets the
name of a textual file containing the list of users and encoded
passwords for digest authentication. File-path is the
absolute path to the user file.htdigest utility found in
the support/ subdirectory of the Apache distribution.AuthDigestGroupFile Directive
Description: Name of the text file containing the list of groups
for digest authentication Syntax: AuthDigestGroupFile file-pathContext: directory, .htaccess Override: AuthConfig Status: Experimental Module: mod_auth_digest AuthDigestGroupFile directive sets
the name of a textual file containing the list of groups and their
members (user names). File-path is the absolute path to
the group file.mygroup: bob joe anneSecurity:
AuthGroupFile is stored
outside the document tree of the web-server; do not put it in
the directory that it protects. Otherwise, clients may be able
to download the AuthGroupFile.AuthDigestNcCheck Directive
Description: Enables or disables checking of the nonce-count sent by the
server Syntax: AuthDigestNcCheck On|OffDefault: AuthDigestNcCheck OffContext: server config Status: Experimental Module: mod_auth_digest
Not implemented yet.
AuthDigestNonceFormat Directive
Description: Determines how the nonce is generated Syntax: AuthDigestNonceFormat formatContext: directory, .htaccess Override: AuthConfig Status: Experimental Module: mod_auth_digest Not implemented yet.
AuthDigestNonceLifetime Directive
Description: How long the server nonce is valid Syntax: AuthDigestNonceLifetime secondsDefault: AuthDigestNonceLifetime 300Context: directory, .htaccess Override: AuthConfig Status: Experimental Module: mod_auth_digest AuthDigestNonceLifetime directive
controls how long the server nonce is valid. When the client
contacts the server using an expired nonce the server will send
back a 401 with stale=true. If seconds is
greater than 0 then it specifies the amount of time for which the
nonce is valid; this should probably never be set to less than 10
seconds. If seconds is less than 0 then the nonce never
expires.
AuthDigestQop Directive
Description: Determines the quality-of-protection to use in digest
authentication Syntax: AuthDigestQop none|auth|auth-int [auth|auth-int]Default: AuthDigestQop authContext: directory, .htaccess Override: AuthConfig Status: Experimental Module: mod_auth_digest AuthDigestQop directive determines
the quality-of-protection to use. auth will only do
authentication (username/password); auth-int is
authentication plus integrity checking (an MD5 hash of the entity
is also computed and checked); none will cause the module
to use the old RFC-2069 digest algorithm (which does not include
integrity checking). Both auth and auth-int may
be specified, in which the case the browser will choose which of
these to use. none should only be used if the browser for
some reason does not like the challenge it receives otherwise.
auth-int is not implemented yet.
AuthDigestShmemSize Directive
Description: The amount of shared memory to allocate for keeping track
of clients Syntax: AuthDigestShmemSize sizeDefault: AuthDigestShmemSize 1000Context: server config Status: Experimental Module: mod_auth_digest AuthDigestShmemSize directive defines
the amount of shared memory, that will be allocated at the server
startup for keeping track of clients. Note that the shared memory
segment cannot be set less than the space that is neccessary for
tracking at least one client. This value is dependant on your
system. If you want to find out the exact value, you may simply
set AuthDigestShmemSize to the value of
0 and read the error message after trying to start the
server.K or an M to
express your value as KBytes or MBytes. For example, the following
directives are all equivalent:
AuthDigestShmemSize 1048576
AuthDigestShmemSize 1024K
AuthDigestShmemSize 1M
mod/mod_autoindex.html 100644 0 0 137635 11074462673 12602 0 ustar 0 0
Apache Module mod_auth_ldap
Description: Allows an LDAP directory to be used to store the database
for HTTP Basic authentication. Status: Experimental Module Identifier: auth_ldap_module Source File: mod_auth_ldap.c Compatibility: Available in version 2.0.41 and later Summary
mod_auth_ldap supports the following features:
Directives
AuthLDAPAuthoritative AuthLDAPBindDN AuthLDAPBindPassword AuthLDAPCharsetConfig AuthLDAPCompareDNOnServer AuthLDAPDereferenceAliases AuthLDAPEnabled AuthLDAPFrontPageHack AuthLDAPGroupAttribute AuthLDAPGroupAttributeIsDN AuthLDAPRemoteUserIsDN AuthLDAPUrlTopics
Contents Operation The Require Directives Examples Using TLS Using SSL Using Microsoft
FrontPage with mod_auth_ldapSee also
Operation
mod_auth_ldap
verifies that the user's credentials are valid. This also called
the search/bind phase. The second phase is
authorization, in which mod_auth_ldap determines
if the authenticated user is allowed access to the resource in
question. This is also known as the compare
phase.The Authentication
Phase
mod_auth_ldap
searches for an entry in the directory that matches the username
that the HTTP client passes. If a single unique match is found,
then mod_auth_ldap attempts to bind to the
directory server using the DN of the entry plus the password
provided by the HTTP client. Because it does a search, then a
bind, it is often referred to as the search/bind phase. Here are
the steps taken during the search/bind phase.
AuthLDAPURL directive with
the username passed by the HTTP client.
AuthLDAPURLSpecifies the LDAP server, the
base DN, the attribute to use in the search, as well as the
extra search filter to use.
AuthLDAPBindDNAn optional DN to bind with
during the search phase.
AuthLDAPBindPasswordAn optional password to bind
with during the search phase.
The Authorization
Phase
mod_auth_ldap
attempts to determine if the user is authorized to access the
resource. Many of these checks require
mod_auth_ldap to do a compare operation on the
LDAP server. This is why this phase is often referred to as the
compare phase. mod_auth_ldap accepts the
following Require
directives to determine if the credentials are acceptable:
Require
valid-user directive.Require user directive, and the
username in the directive matches the username passed by the
client.Require
dn directive, and the DN in the directive matches
the DN fetched from the LDAP directory.Require group directive, and
the DN fetched from the LDAP directory (or the username
passed by the client) occurs in the LDAP group.Require ldap-attribute
directive, and the attribute fetched from the LDAP directory
matches the given value.mod_auth_ldap uses the following directives during the
compare phase:
AuthLDAPURL The attribute specified in the
URL is used in compare operations for the
Require
user operation.
AuthLDAPCompareDNOnServerDetermines the behavior of the
Require dn directive.
AuthLDAPGroupAttributeDetermines the attribute to
use for comparisons in the
Require group
directive.
AuthLDAPGroupAttributeIsDNSpecifies whether to use the
user DN or the username when doing comparisons for the
Require group directive.
The Require Directives
Require
directives are used during the authorization phase to ensure that
a user is allowed to access a resource.Require
valid-user
mod_auth_ldap grants
access to any user that has successfully authenticated during the
search/bind phase.Require user
Require user directive specifies what
usernames can access the resource. Once
mod_auth_ldap has retrieved a unique DN from the
directory, it does an LDAP compare operation using the username
specified in the Require user to see if that username
is part of the just-fetched LDAP entry. Multiple users can be
granted access by putting multiple usernames on the line,
separated with spaces. If a username has a space in it, then it
must be surrounded with double quotes. Multiple users can also be
granted access by using multiple Require user
directives, with one user per line. For example, with a AuthLDAPURL of
ldap://ldap/o=Airius?cn (i.e., cn is
used for searches), the following Require directives could be used
to restrict access:
Require user "Barbara Jenson"
Require user "Fred User"
Require user "Joe Manager"
mod_auth_ldap handles this
directive, Barbara Jenson could sign on as Barbara
Jenson, Babs Jenson or any other cn that
she has in her LDAP entry. Only the single Require
user line is needed to support all values of the attribute
in the user's entry.uid attribute was used instead of the
cn attribute in the URL above, the above three lines
could be condensed toRequire user bjenson fuser jmanagerRequire group
dn: cn=Administrators, o=Airius
objectClass: groupOfUniqueNames
uniqueMember: cn=Barbara Jenson, o=Airius
uniqueMember: cn=Fred User, o=Airius
Require group cn=Administrators, o=AiriusAuthLDAPGroupAttribute and
AuthLDAPGroupAttributeIsDN
directives.Require dn
Require dn directive allows the administrator
to grant access based on distinguished names. It specifies a DN
that must match for access to be granted. If the distinguished
name that was retrieved from the directory server matches the
distinguished name in the Require dn, then
authorization is granted. Note: do not surround the distinguished
name with quotes.Require dn cn=Barbara Jenson, o=AiriusAuthLDAPCompareDNOnServer
directive.Require ldap-attribute
Require ldap-attribute directive allows the
administrator to grant access based on attributes of the authenticated
user in the LDAP directory. If the attribute in the directory
matches the value given in the configuration, access is granted.Require ldap-attribute employeeType=activeRequire ldap-attribute directives. The effect of listing
multiple attribute/values pairs is an OR operation. Access will be
granted if any of the listed attribute values match the value of a
corresponding attribute in the user object. If the value of the
attribute contains a space, only the value must be within double quotes.Require ldap-attribute city="San Jose" status=active
Examples
AuthLDAPURL ldap://ldap1.airius.com:389/ou=People, o=Airius?uid?sub?(objectClass=*)
Require valid-user
AuthLDAPURL ldap://ldap1.airius.com ldap2.airius.com/ou=People, o=Airius
Require valid-user
cn, because a search on cn
must return exactly one entry. That's why
this approach is not recommended: it's a better idea to
choose an attribute that is guaranteed unique in your
directory, such as uid.
AuthLDAPURL ldap://ldap.airius.com/ou=People, o=Airius?cn
Require valid-user
AuthLDAPURL ldap://ldap.airius.com/o=Airius?uid
Require group cn=Administrators, o=Airius
qpagePagerID. The example will grant access
only to people (authenticated via their UID) who have
alphanumeric pagers:
AuthLDAPURL ldap://ldap.airius.com/o=Airius?uid??(qpagePagerID=*)
Require valid-user
AuthLDAPURL ldap://ldap.airius.com/o=Airius?uid??(|(qpagePagerID=*)(uid=jmanager))
Require valid-user
fuser, the filter would look
like(&(|(qpagePagerID=*)(uid=jmanager))(uid=fuser))(&(|(qpagePagerID=*)(uid=jmanager))(uid=jmanager))
Using TLS
mod_ldap directives LDAPTrustedCA and LDAPTrustedCAType.
Using SSL
mod_ldap directives LDAPTrustedCA and LDAPTrustedCAType.AuthLDAPURL
directive, instead of ldap://.
Using Microsoft
FrontPage with mod_auth_ldap
mod_auth module) to handle all
authentication. Unfortunately, it is not possible to just
change to LDAP authentication by adding the proper directives,
because it will break the Permissions forms in
the FrontPage client, which attempt to modify the standard
text-based authorization files..htaccess file
that gets created in the web
AuthLDAPURL "the url"
AuthLDAPAuthoritative off
AuthLDAPFrontPageHack on
AuthLDAPAuthoritative must be
off to allow mod_auth_ldap to decline group
authentication so that Apache will fall back to file
authentication for checking group membership. This allows the
FrontPage-managed group file to be used.How It Works
Require
valid-user directive to the .htaccess
files. If AuthLDAPFrontPageHack is not
on, the Require valid-user directive will succeed for
any user who is valid as far as LDAP is
concerned. This means that anybody who has an entry in
the LDAP directory is considered a valid user, whereas FrontPage
considers only those people in the local user file to be
valid. The purpose of the hack is to force Apache to consult the
local user file (which is managed by FrontPage) - instead of LDAP
- when handling the Require valid-user directive.Caveats
mod_auth user file.
The user ID is ideal for this.mod_auth in order to
use FrontPage support. This is because Apache will still use
the mod_auth group file for determine the extent of a
user's access to the FrontPage web..htaccess
files. Attempting to put them inside <Location> or <Directory> directives won't work. This
is because mod_auth_ldap has to be able to grab
the AuthUserFile
directive that is found in FrontPage .htaccess
files so that it knows where to look for the valid user list. If
the mod_auth_ldap directives aren't in the same
.htaccess file as the FrontPage directives, then
the hack won't work, because mod_auth_ldap will
never get a chance to process the .htaccess file,
and won't be able to find the FrontPage-managed user file.AuthLDAPAuthoritative Directive
Description: Prevent other authentication modules from
authenticating the user if this one fails Syntax: AuthLDAPAuthoritative on|offDefault: AuthLDAPAuthoritative onContext: directory, .htaccess Override: AuthConfig Status: Experimental Module: mod_auth_ldap off if this module should let other
authentication modules attempt to authenticate the user, should
authentication with this module fail. Control is only passed on
to lower modules if there is no DN or rule that matches the
supplied user name (as passed by the client).AuthLDAPBindDN Directive
Description: Optional DN to use in binding to the LDAP server Syntax: AuthLDAPBindDN distinguished-nameContext: directory, .htaccess Override: AuthConfig Status: Experimental Module: mod_auth_ldap mod_auth_ldap will use
an anonymous bind.AuthLDAPBindPassword Directive
Description: Password used in conjuction with the bind DN Syntax: AuthLDAPBindPassword passwordContext: directory, .htaccess Override: AuthConfig Status: Experimental Module: mod_auth_ldap AuthLDAPBindDN and AuthLDAPBindPassword if you
absolutely need them to search the directory.AuthLDAPCharsetConfig Directive
Description: Language to charset conversion configuration file Syntax: AuthLDAPCharsetConfig file-pathContext: server config Status: Experimental Module: mod_auth_ldap AuthLDAPCharsetConfig directive sets the location
of the language to charset conversion configuration file. File-path is relative
to the ServerRoot. This file specifies
the list of language extensions to character sets.
Most administrators use the provided charset.conv
file, which associates common language extensions to character sets.
Language-Extension charset [Language-String] ...
#) are ignored.AuthLDAPCompareDNOnServer Directive
Description: Use the LDAP server to compare the DNs Syntax: AuthLDAPCompareDNOnServer on|offDefault: AuthLDAPCompareDNOnServer onContext: directory, .htaccess Override: AuthConfig Status: Experimental Module: mod_auth_ldap mod_auth_ldap will use the LDAP
server to compare the DNs. This is the only foolproof way to
compare DNs. mod_auth_ldap will search the
directory for the DN specified with the Require dn directive, then,
retrieve the DN and compare it with the DN retrieved from the user
entry. If this directive is not set,
mod_auth_ldap simply does a string comparison. It
is possible to get false negatives with this approach, but it is
much faster. Note the mod_ldap cache can speed up
DN comparison in most situations.AuthLDAPDereferenceAliases Directive
Description: When will the module de-reference aliases Syntax: AuthLDAPDereferenceAliases never|searching|finding|alwaysDefault: AuthLDAPDereferenceAliases AlwaysContext: directory, .htaccess Override: AuthConfig Status: Experimental Module: mod_auth_ldap mod_auth_ldap will
de-reference aliases during LDAP operations. The default is
always.AuthLDAPEnabled Directive
Description: Turn on or off LDAP authentication Syntax: AuthLDAPEnabled on|offDefault: AuthLDAPEnabled onContext: directory, .htaccess Override: AuthConfig Status: Experimental Module: mod_auth_ldap off to disable
mod_auth_ldap in certain directories. This is
useful if you have mod_auth_ldap enabled at or
near the top of your tree, but want to disable it completely in
certain locations.AuthLDAPFrontPageHack Directive
Description: Allow LDAP authentication to work with MS FrontPage Syntax: AuthLDAPFrontPageHack on|offDefault: AuthLDAPFrontPageHack offContext: directory, .htaccess Override: AuthConfig Status: Experimental Module: mod_auth_ldap mod_auth_ldap.AuthLDAPGroupAttribute Directive
Description: LDAP attributes used to check for group membership Syntax: AuthLDAPGroupAttribute attributeContext: directory, .htaccess Override: AuthConfig Status: Experimental Module: mod_auth_ldap mod_auth_ldap uses the member and
uniquemember attributes.AuthLDAPGroupAttributeIsDN Directive
Description: Use the DN of the client username when checking for
group membership Syntax: AuthLDAPGroupAttributeIsDN on|offDefault: AuthLDAPGroupAttributeIsDN onContext: directory, .htaccess Override: AuthConfig Status: Experimental Module: mod_auth_ldap on, this directive says to use the
distinguished name of the client username when checking for group
membership. Otherwise, the username will be used. For example,
assume that the client sent the username bjenson,
which corresponds to the LDAP DN cn=Babs Jenson,
o=Airius. If this directive is set,
mod_auth_ldap will check if the group has
cn=Babs Jenson, o=Airius as a member. If this
directive is not set, then mod_auth_ldap will
check if the group has bjenson as a member.AuthLDAPRemoteUserIsDN Directive
Description: Use the DN of the client username to set the REMOTE_USER
environment variable Syntax: AuthLDAPRemoteUserIsDN on|offDefault: AuthLDAPRemoteUserIsDN offContext: directory, .htaccess Override: AuthConfig Status: Experimental Module: mod_auth_ldap REMOTE_USER environment variable will be set to the full
distinguished name of the authenticated user, rather than just
the username that was passed by the client. It is turned off by
default.AuthLDAPUrl Directive
Description: URL specifying the LDAP search parameters Syntax: AuthLDAPUrl urlContext: directory, .htaccess Override: AuthConfig Status: Experimental Module: mod_auth_ldap ldap://host:port/basedn?attribute?scope?filter
ldap. For secure LDAP, use ldaps
instead. Secure LDAP is only available if Apache was linked
to an LDAP library with SSL support.localhost:389 for ldap, and
localhost:636 for ldaps). To
specify multiple, redundant LDAP servers, just list all
servers, separated by spaces. mod_auth_ldap
will try connecting to each server in turn, until it makes a
successful connection.httpd process, or until the LDAP server goes
down.mod_auth_ldap will attempt to
re-connect, starting with the primary server, and trying
each redundant server in turn. Note that this is different
than a true round-robin search.uid. It's a good
idea to choose an attribute that will be unique across all
entries in the subtree you will be using.one or
sub. Note that a scope of base is
also supported by RFC 2255, but is not supported by this
module. If the scope is not provided, or if base scope
is specified, the default is to use a scope of
sub.(objectClass=*), which
will search for all objects in the tree. Filters are
limited to approximately 8000 characters (the definition of
MAX_STRING_LEN in the Apache source code). This
should be than sufficient for any application.(&(filter)(attribute=username)).ldap://ldap.airius.com/o=Airius?cn?sub?(posixid=*). When
a client attempts to connect using a username of Babs
Jenson, the resulting search filter will be
(&(posixid=*)(cn=Babs Jenson)).AuthLDAPURL URLs.
mod/mod_cache.html 100644 0 0 62231 11074462673 11612 0 ustar 0 0
Apache Module mod_autoindex
Description: Generates directory indexes,
automatically, similar to the Unix ls command or the
Win32 dir shell commandStatus: Base Module Identifier: autoindex_module Source File: mod_autoindex.c Summary
index.html. The DirectoryIndex directive sets the
name of this file. This is controlled by
mod_dir.AddIcon, AddIconByEncoding and
AddIconByType are
used to set a list of icons to display for various file types;
for each file listed, the first icon listed that matches the
file is displayed. These are controlled by
mod_autoindex.Options +Indexes. See the
Options directive for
more details.FancyIndexing option is given with the IndexOptions directive,
the column headers are links that control the order of the
display. If you select a header link, the listing will be
regenerated, sorted by the values in that column. Selecting the
same header repeatedly toggles between ascending and descending
order. These column header links are suppressed with
IndexOptions directive's
SuppressColumnSorting option.Directives
AddAlt AddAltByEncoding AddAltByType AddDescription AddIcon AddIconByEncoding AddIconByType DefaultIcon HeaderName IndexIgnore IndexOptions IndexOrderDefault ReadmeNameTopics
Autoindex Request Query Arguments
IndexOptions
IgnoreClient option was introduced.
C=N sorts the directory by file nameC=M sorts the directory by last-modified
date, then file nameC=S sorts the directory by size, then file
nameC=D sorts the directory by description, then
file nameO=A sorts the listing in Ascending
OrderO=D sorts the listing in Descending
OrderF=0 formats the listing as a simple list
(not FancyIndexed)F=1 formats the listing as a FancyIndexed
listF=2 formats the listing as an
HTMLTable FancyIndexed listV=0 disables version sortingV=1 enables version sortingP=pattern lists only files matching
the given patternIndexIgnore directives are processed,
and all file names are still subjected to the same criteria as
any other autoindex listing. The Query Arguments parser in
mod_autoindex will stop abruptly when an unrecognized
option is encountered. The Query Arguments must be well formed,
according to the table above.
<form action="" method="get">
Show me a <select name="F">
<option value="0"> Plain list</option>
<option value="1" selected="selected"> Fancy list</option>
<option value="2"> Table list</option>
</select>
Sorted by <select name="C">
<option value="N" selected="selected"> Name</option>
<option value="M"> Date Modified</option>
<option value="S"> Size</option>
<option value="D"> Description</option>
</select>
<select name="O">
<option value="A" selected="selected"> Ascending</option>
<option value="D"> Descending</option>
</select>
<select name="V">
<option value="0" selected="selected"> in Normal order</option>
<option value="1"> in Version order</option>
</select>
Matching <input type="text" name="P" value="*" />
<input type="submit" name="X" value="Go" />
</form>
AddAlt Directive
Description: Alternate text to display for a file, instead of an
icon selected by filename Syntax: AddAlt string file [file] ...Context: server config, virtual host, directory, .htaccess Override: Indexes Status: Base Module: mod_autoindex AddAlt provides the alternate text to
display for a file, instead of an icon, for FancyIndexing.
File is a file extension, partial filename, wild-card
expression or full filename for files to describe.
If String contains any whitespace, you have to enclose it
in quotes (" or '). This alternate text
is displayed if the client is image-incapable, has image loading
disabled, or fails to retrieve the icon.Examples
AddAlt "PDF file" *.pdf
AddAlt Compressed *.gz *.zip *.Z
AddAltByEncoding Directive
Description: Alternate text to display for a file instead of an icon
selected by MIME-encoding Syntax: AddAltByEncoding string MIME-encoding
[MIME-encoding] ...Context: server config, virtual host, directory, .htaccess Override: Indexes Status: Base Module: mod_autoindex AddAltByEncoding provides the alternate
text to display for a file, instead of an icon, for FancyIndexing.
MIME-encoding is a valid content-encoding, such as
x-compress. If String contains any whitespace,
you have to enclose it in quotes (" or ').
This alternate text is displayed if the client is image-incapable,
has image loading disabled, or fails to retrieve the icon.Example
AddAltByEncoding gzip x-gzip
AddAltByType Directive
Description: Alternate text to display for a file, instead of an
icon selected by MIME content-type Syntax: AddAltByType string MIME-type
[MIME-type] ...Context: server config, virtual host, directory, .htaccess Override: Indexes Status: Base Module: mod_autoindex AddAltByType sets the alternate text to
display for a file, instead of an icon, for FancyIndexing.
MIME-type is a valid content-type, such as
text/html. If String contains any whitespace,
you have to enclose it in quotes (" or ').
This alternate text is displayed if the client is image-incapable,
has image loading disabled, or fails to retrieve the icon.Example
AddAltByType 'plain text' text/plain
AddDescription Directive
Description: Description to display for a file Syntax: AddDescription string file [file] ...Context: server config, virtual host, directory, .htaccess Override: Indexes Status: Base Module: mod_autoindex FancyIndexing.
File is a file extension, partial filename, wild-card
expression or full filename for files to describe.
String is enclosed in double quotes (").Example
AddDescription "The planet Mars" /web/pics/mars.gif
IndexOptions SuppressIcon option, 7 bytes are
added by the IndexOptions SuppressSize option, and 19 bytes are
added by the IndexOptions SuppressLastModified option.
Therefore, the widest default the description column is ever
assigned is 55 bytes.IndexOptions keyword for details on overriding the size
of this column, or allowing descriptions of unlimited length.Caution
AddDescription
may contain HTML markup, such as tags and character entities. If the
width of the description column should happen to truncate a tagged
element (such as cutting off the end of a bolded phrase), the
results may affect the rest of the directory listing.AddIcon Directive
Description: Icon to display for a file selected by name Syntax: AddIcon icon name [name]
...Context: server config, virtual host, directory, .htaccess Override: Indexes Status: Base Module: mod_autoindex FancyIndexing. Icon is either a (%-escaped)
relative URL to the icon, or of the format
(alttext,url) where alttext
is the text tag given for an icon for non-graphical browsers.^^DIRECTORY^^ for directories,
^^BLANKICON^^ for blank lines (to format the list
correctly), a file extension, a wildcard expression, a partial
filename or a complete filename.Examples
AddIcon (IMG,/icons/image.xbm) .gif .jpg .xbm
AddIcon /icons/dir.xbm ^^DIRECTORY^^
AddIcon /icons/backup.xbm *~
AddIconByType
should be used in preference to AddIcon,
when possible.AddIconByEncoding Directive
Description: Icon to display next to files selected by MIME
content-encoding Syntax: AddIconByEncoding icon MIME-encoding
[MIME-encoding] ...Context: server config, virtual host, directory, .htaccess Override: Indexes Status: Base Module: mod_autoindex FancyIndexing.
Icon is either a (%-escaped) relative URL to the icon,
or of the format (alttext,url)
where alttext is the text tag given for an icon for
non-graphical browsers.Example
AddIconByEncoding /icons/compress.xbm x-compress
AddIconByType Directive
Description: Icon to display next to files selected by MIME
content-type Syntax: AddIconByType icon MIME-type
[MIME-type] ...Context: server config, virtual host, directory, .htaccess Override: Indexes Status: Base Module: mod_autoindex FancyIndexing.
Icon is either a (%-escaped) relative URL to the icon,
or of the format (alttext,url)
where alttext is the text tag given for an icon for
non-graphical browsers.Example
AddIconByType (IMG,/icons/image.xbm) image/*
DefaultIcon Directive
Description: Icon to display for files when no specific icon is
configured Syntax: DefaultIcon url-pathContext: server config, virtual host, directory, .htaccess Override: Indexes Status: Base Module: mod_autoindex DefaultIcon directive sets the icon
to display for files when no specific icon is known, for FancyIndexing.
Url-path is a (%-escaped) relative URL to the icon.Example
DefaultIcon /icon/unknown.xbm
HeaderName Directive
Description: Name of the file that will be inserted at the top
of the index listing Syntax: HeaderName filenameContext: server config, virtual host, directory, .htaccess Override: Indexes Status: Base Module: mod_autoindex HeaderName directive sets the name
of the file that will be inserted at the top of the index
listing. Filename is the name of the file to include.Example
HeaderName HEADER.html
ReadmeName now treat
Filename as a URI path relative to the one used to
access the directory being indexed. If Filename begins
with a slash, it will be taken to be relative to the DocumentRoot.Example
HeaderName /include/HEADER.html
text/* (e.g.,
text/html, text/plain, etc.). This means
that filename may refer to a CGI script if the script's
actual file type (as opposed to its output) is marked as
text/html such as with a directive like:
AddType text/html .cgi
Options
MultiViews is in effect. If filename resolves
to a static text/html document (not a CGI script) and
either one of the options
Includes or IncludesNOEXEC is enabled,
the file will be processed for server-side includes (see the
mod_include documentation).HeaderName contains
the beginnings of an HTML document (<html>, <head>, etc.)
then you will probably want to set IndexOptions
+SuppressHTMLPreamble, so that these tags are not
repeated.IndexIgnore Directive
Description: Adds to the list of files to hide when listing
a directory Syntax: IndexIgnore file [file] ...Context: server config, virtual host, directory, .htaccess Override: Indexes Status: Base Module: mod_autoindex IndexIgnore directive adds to the
list of files to hide when listing a directory. File is a
shell-style wildcard expression or full
filename. Multiple IndexIgnore directives add
to the list, rather than the replacing the list of ignored
files. By default, the list contains . (the current
directory).
IndexIgnore README .htaccess *.bak *~
IndexOptions Directive
Description: Various configuration settings for directory
indexing Syntax: IndexOptions [+|-]option [[+|-]option]
...Context: server config, virtual host, directory, .htaccess Override: Indexes Status: Base Module: mod_autoindex IndexOptions directive specifies the
behavior of the directory indexing. Option can be one
of
Charset keyword allows you to
specify the character set of the generated page. The
default is either ISO-8859-1 or UTF-8,
depending on whether the underlying file system is unicode
or not.
Example:
IndexOptions Charset=UTF-8
Type keyword allows you to
specify the MIME content-type of the generated page. The default
is text/html.
Example:
IndexOptions Type=text/plain
DescriptionWidth keyword allows you to
specify the width of the description column in
characters.-DescriptionWidth (or unset) allows
mod_autoindex to calculate the best width.DescriptionWidth=n fixes the column width to
n bytes wide.DescriptionWidth=* grows the column to the
width necessary to accommodate the longest description
string.AddDescription for dangers
inherent in truncating descriptions.FoldersFirst is enabled, subdirectory
Zed will be listed before subdirectory
Beta, which will be listed before normal files
Gamma and Alpha. This option
only has an effect if FancyIndexing is also enabled.height and width
attributes in the img tag for the file icon. This allows
browser to precalculate the page layout without having to wait until
all the images have been loaded. If no value is given for the option,
it defaults to the standard height of the icons supplied with the Apache
software.IconHeight,
will cause the server to include height and
width attributes in the img tag for
the file icon. This allows browser to precalculate the page
layout without having to wait until all the images have been
loaded. If no value is given for the option, it defaults to
the standard width of the icons supplied with the Apache
software.mod_autoindex to ignore all
query variables from the client, including sort order (implies
SuppressColumnSorting.)NameWidth keyword allows you to specify the width
of the filename column in bytes.-NameWidth (or unset) allows mod_autoindex to calculate the best width.NameWidth=n fixes the column width to
n bytes wide.NameWidth=* grows the column to the necessary
width.AddDescription
then httpd will read the document for the value of the
title element. This is CPU and disk intensive.AddDescription for information about setting the file
description. See also the DescriptionWidth
index option to limit the size of the description column.HeaderName
directive, the module usually includes the contents of the file
after a standard HTML preamble (<html>,
<head>, et cetera). The
SuppressHTMLPreamble option disables this behaviour,
causing the module to start the display with the header file
contents. The header file must contain appropriate HTML instructions
in this case. If there is no header file, the preamble is generated
as usual.SuppressIcon and
SuppressRules yields proper HTML 3.2 output, which
by the final specification prohibits img and
hr elements from the pre block (used to
format FancyIndexed listings.)hr
elements) in directory listings. Combining both SuppressIcon and
SuppressRules yields proper HTML 3.2 output, which
by the final specification prohibits img and
hr elements from the pre block (used to
format FancyIndexed listings.)HEAD
request. Note some operating systems correctly track new and
removed files, but do not track changes for sizes or dates of
the files within the directory. Changes to the size
or date stamp of an existing file will not update the
Last-Modified header on all Unix platforms. If this
is a concern, leave this option disabled.VersionSort keyword causes files containing
version numbers to sort in a natural way. Strings are sorted as
usual, except that substrings of digits in the name and
description are compared according to their numeric value.
Example:
foo-1.7
foo-1.7.2
foo-1.7.12
foo-1.8.2
foo-1.8.2a
foo-1.12
foo-1.001
foo-1.002
foo-1.030
foo-1.04
XHTML keyword forces mod_autoindex
to emit XHTML 1.0 code instead of HTML 3.2.IndexOptions directives. In
particular:
IndexOptions directives for a
single directory are now merged together. The result of:
<Directory /foo>
IndexOptions HTMLTable
IndexOptions SuppressColumnsorting
</Directory>
IndexOptions HTMLTable SuppressColumnsorting
+ or -).IndexOptions
settings (which may have been inherited from an upper-level
directory). However, whenever an unprefixed keyword is processed, it
clears all inherited options and any incremental settings encountered
so far. Consider the following example:
IndexOptions +ScanHTMLTitles -IconsAreLinks FancyIndexing
IndexOptions +SuppressSize
IndexOptions FancyIndexing
+SuppressSize, because the unprefixed FancyIndexing
discarded the incremental keywords before it, but allowed them to
start accumulating again afterward.IndexOptions for
a particular directory, clearing the inherited settings, specify
keywords without any + or - prefixes.IndexOrderDefault Directive
Description: Sets the default ordering of the directory index Syntax: IndexOrderDefault Ascending|Descending
Name|Date|Size|DescriptionDefault: IndexOrderDefault Ascending NameContext: server config, virtual host, directory, .htaccess Override: Indexes Status: Base Module: mod_autoindex IndexOrderDefault directive is used
in combination with the FancyIndexing index option. By default, fancyindexed
directory listings are displayed in ascending order by filename; the
IndexOrderDefault allows you to change this
initial display order.IndexOrderDefault takes two
arguments. The first must be either Ascending or
Descending, indicating the direction of the sort.
The second argument must be one of the keywords Name,
Date, Size, or Description,
and identifies the primary key. The secondary key is
always the ascending filename.SuppressColumnSorting index option; this will prevent
the client from requesting the directory listing in a different
order.ReadmeName Directive
Description: Name of the file that will be inserted at the end
of the index listing Syntax: ReadmeName filenameContext: server config, virtual host, directory, .htaccess Override: Indexes Status: Base Module: mod_autoindex ReadmeName directive sets the name
of the file that will be appended to the end of the index
listing. Filename is the name of the file to include, and
is taken to be relative to the location being indexed. If
Filename begins with a slash, it will be taken to be
relative to the DocumentRoot.
Example
ReadmeName FOOTER.html
Example 2
ReadmeName /include/FOOTER.html
HeaderName, where this behavior is described in greater
detail.
mod/mod_cern_meta.html 100644 0 0 16652 11074462673 12512 0 ustar 0 0
Apache Module mod_cache
Description: Content cache keyed to URIs. Status: Experimental Module Identifier: cache_module Source File: mod_cache.c Summary
This module is experimental. Documentation is still under development...
mod_cache implements an RFC 2616 compliant HTTP
content cache that can be used to cache either local or proxied content.
mod_cache requires the services of one or more storage
management modules. Two storage management modules are included in
the base Apache distribution:
mod_disk_cachemod_mem_cachemod_mem_cache can be configured to operate in two
modes: caching open file descriptors or caching objects in heap storage.
mod_mem_cache can be used to cache locally generated content
or to cache backend server content for mod_proxy when
configured using ProxyPass
(aka reverse proxy)Directives
CacheDefaultExpire CacheDisable CacheEnable CacheForceCompletion CacheIgnoreCacheControl CacheIgnoreHeaders CacheIgnoreNoLastMod CacheLastModifiedFactor CacheMaxExpireTopics
Related Modules and Directives
Related Modules Related Directives
Sample Configuration
Sample httpd.conf
#
# Sample Cache Configuration
#
LoadModule cache_module modules/mod_cache.so
<IfModule mod_cache.c>
#LoadModule disk_cache_module modules/mod_disk_cache.so
<IfModule mod_disk_cache.c>
CacheRoot c:/cacheroot
CacheSize 256
CacheEnable disk /
CacheDirLevels 5
CacheDirLength 3
</IfModule>
LoadModule mem_cache_module modules/mod_mem_cache.so
<IfModule mod_mem_cache.c>
CacheEnable mem /
MCacheSize 4096
MCacheMaxObjectCount 100
MCacheMinObjectSize 1
MCacheMaxObjectSize 2048
</IfModule>
</IfModule>
CacheDefaultExpire Directive
Description: The default duration to cache a document when no expiry date is specified. Syntax: CacheDefaultExpire secondsDefault: CacheDefaultExpire 3600 (one hour)Context: server config, virtual host Status: Experimental Module: mod_cache CacheDefaultExpire directive specifies a default time,
in seconds, to cache a document if neither an expiry date nor last-modified date are provided
with the document. The value specified with the CacheMaxExpire
directive does not override this setting.
CacheDefaultExpire 86400
CacheDisable Directive
Description: Disable caching of specified URLs Syntax: CacheDisable url-stringContext: server config, virtual host Status: Experimental Module: mod_cache CacheDisable directive instructs
mod_cache to not cache urls at or below
url-string.Example
CacheDisable /local_files
CacheEnable Directive
Description: Enable caching of specified URLs using a specified storage
manager Syntax: CacheEnable cache_type url-stringContext: server config, virtual host Status: Experimental Module: mod_cache CacheEnable directive instructs
mod_cache to cache urls at or below
url-string. The cache storage manager is specified with the
cache_type argument. cache_type mem
instructs mod_cache to use the memory based storage
manager implemented by mod_mem_cache.
cache_type disk instructs
mod_cache to use the disk based storage manager
implemented by mod_disk_cache.
cache_type fd instructs
mod_cache to use the file descriptor cache implemented
by mod_mem_cache.CacheEnable directives (as in the example below),
each possible storage manager will be run until the first one that
actually processes the request. The order in which the storage managers are
run is determined by the order of the CacheEnable
directives in the configuration file.
CacheEnable mem /manual
CacheEnable fd /images
CacheEnable disk /
CacheForceCompletion Directive
Description: Percentage of document served, after which the server
will complete caching the file even if the request is cancelled. Syntax: CacheForceCompletion PercentageDefault: CacheForceCompletion 60Context: server config, virtual host Status: Experimental Module: mod_cache CacheForceCompletion directive specifies a
threshold beyond which the document will continue to be cached to
completion, even if the request is cancelled.1 and 100. A value of 0
specifies that the default be used. A value of 100
will only cache documents that are served in their entirety. A value
between 60 and 90 is recommended.
CacheForceCompletion 80
Note:
This feature is currently not implemented.
CacheIgnoreCacheControl Directive
Description: Ignore the fact that the client requested the content not be
cached. Syntax: CacheIgnoreCacheControl On|OffDefault: CacheIgnoreCacheControl OffContext: server config, virtual host Status: Experimental Module: mod_cache CacheIgnoreCacheControl directive allows this behavior to be overridden.
CacheIgnoreCacheControl On tells the server to attempt to cache the document
even if it contains no-cache or no-store header values. Documents requiring authorization will
never be cached.
CacheIgnoreCacheControl On
CacheIgnoreHeaders Directive
Description: Do not store the given HTTP header(s) in the cache.
Syntax: CacheIgnoreHeaders header-string [header-string] ...Default: CacheIgnoreHeaders NoneContext: server config, virtual host Status: Experimental Module: mod_cache CacheIgnoreHeaders:
ConnectionKeep-AliveProxy-AuthenticateProxy-AuthorizationTETrailersTransfer-EncodingUpgradeCacheIgnoreHeaders specifies additional HTTP
headers that should not to be stored in the cache. For example, it makes
sense in some cases to prevent cookies from being stored in the cache.CacheIgnoreHeaders takes a space separated list
of HTTP headers that should not be stored in the cache. If only hop-by-hop
headers not should be stored in the cache (the RFC 2616 compliant
behaviour), CacheIgnoreHeaders can be set to
None.Example 1
CacheIgnoreHeaders Set-Cookie
Example 2
CacheIgnoreHeaders None
Warning:
If headers like Expires which are needed for proper cache
management are not stored due to a
CacheIgnoreHeaders setting, the behaviour of
mod_cache is undefined.
CacheIgnoreNoLastMod Directive
Description: Ignore the fact that a response has no Last Modified
header. Syntax: CacheIgnoreNoLastMod On|OffDefault: CacheIgnoreNoLastMod OffContext: server config, virtual host Status: Experimental Module: mod_cache mod_include processing for example) or not provided
at all. The CacheIgnoreNoLastMod directive
provides a way to specify that documents without last-modified dates
should be considered for caching, even without a last-modified date.
If neither a last-modified date nor an expiry date are provided with
the document then the value specified by the
CacheDefaultExpire directive will be used to
generate an expiration date.
CacheIgnoreNoLastMod On
CacheLastModifiedFactor Directive
Description: The factor used to compute an expiry date based on the
LastModified date. Syntax: CacheLastModifiedFactor floatDefault: CacheLastModifiedFactor 0.1Context: server config, virtual host Status: Experimental Module: mod_cache CacheLastModifiedFactor directive specifies a
factor to be used in the generation of this expiry date
according to the following formula:
expiry-period = time-since-last-modified-date * factor
expiry-date = current-date + expiry-period
For example, if the document was last modified 10 hours ago, and
factor is 0.1 then the expiry-period will be set to
10*0.1 = 1 hour. If the current time was 3:00pm then the computed
expiry-date would be 3:00pm + 1hour = 4:00pm.
If the expiry-period would be longer than that set by
CacheMaxExpire, then the latter takes
precedence.
CacheLastModifiedFactor 0.5
CacheMaxExpire Directive
Description: The maximum time in seconds to cache a document Syntax: CacheMaxExpire secondsDefault: CacheMaxExpire 86400 (one day)Context: server config, virtual host Status: Experimental Module: mod_cache CacheMaxExpire directive specifies the maximum number of
seconds for which cachable HTTP documents will be retained without checking the origin
server. Thus, documents will be out of date at most this number of seconds. This maximum
value is enforced even if an expiry date was supplied with the document.
CacheMaxExpire 604800
mod/mod_cgi.html 100644 0 0 33264 11074462673 11315 0 ustar 0 0
Apache Module mod_cern_meta
Description: CERN httpd metafile semantics Status: Extension Module Identifier: cern_meta_module Source File: mod_cern_meta.c Summary
MetaDir Directive
Description: Name of the directory to find CERN-style meta information
files Syntax: MetaDir directoryDefault: MetaDir .webContext: server config, virtual host, directory, .htaccess Override: Indexes Status: Extension Module: mod_cern_meta ." to look in the same directory
as the file:MetaDir .MetaDir .metaMetaFiles Directive
Description: Activates CERN meta-file processing Syntax: MetaFiles on|offDefault: MetaFiles offContext: server config, virtual host, directory, .htaccess Override: Indexes Status: Extension Module: mod_cern_meta MetaSuffix Directive
Description: File name suffix for the file containg CERN-style
meta information Syntax: MetaSuffix suffixDefault: MetaSuffix .metaContext: server config, virtual host, directory, .htaccess Override: Indexes Status: Extension Module: mod_cern_meta DOCUMENT_ROOT/somedir/index.html to look in
DOCUMENT_ROOT/somedir/.web/index.html.meta and
will use its contents to generate additional MIME header
information.Example:
MetaSuffix .meta
mod/mod_cgid.html 100644 0 0 13650 11074462673 11456 0 ustar 0 0
Apache Module mod_cgi
Description: Execution of CGI scripts Status: Base Module Identifier: cgi_module Source File: mod_cgi.c Summary
application/x-httpd-cgi or handler
cgi-script (Apache 1.1 or later) will be treated
as a CGI script, and run by the server, with its output being
returned to the client. Files acquire this type either by
having a name containing an extension defined by the
AddType directive, or by being
in a ScriptAlias
directory.DOCUMENT_ROOT to the environment. This
variable will contain the value of the
DocumentRoot configuration
variable.mod_cgid should be used in place of
this module. At the user level, the two modules are essentially
identical.Directives
Topics
See also
CGI Environment variables
AcceptPathInfo directive is explicitly set to
off. The default behavior, if AcceptPathInfo is not given, is that mod_cgi will accept path info (trailing
/more/path/info following the script filename in the URI),
while the core server will return a 404 NOT FOUND error for requests
with additional path info. Omitting the AcceptPathInfo directive has the same effect as setting
it On for mod_cgi requests.HostnameLookups is set to on (it
is off by default), and if a reverse DNS lookup of the accessing
host's address indeed finds a host name.IdentityCheck is set to
on and the accessing host supports the ident
protocol. Note that the contents of this variable cannot be
relied upon because it can easily be faked, and if there is a
proxy between the client and the server, it is usually
totally useless.
CGI Debugging
CGI Logfile Format
%% [time] request-line
%% HTTP-status CGI-script-filename
%%error
error-message
%request
All HTTP request headers received
POST or PUT entity (if any)
%response
All headers output by the CGI script
%stdout
CGI standard output
%stderr
CGI standard error
ScriptLog Directive
Description: Location of the CGI script error logfile Syntax: ScriptLog file-pathContext: server config, virtual host Status: Base Module: mod_cgi, mod_cgidScriptLog directive sets the CGI
script error logfile. If no ScriptLog is given,
no error log is created. If given, any CGI errors are logged into the
filename given as argument. If this is a relative file or path it is
taken relative to the ServerRoot.
Example
ScriptLog logs/cgi_log
User directive. This means that
either the directory the script log is in needs to be writable
by that user or the file needs to be manually created and set
to be writable by that user. If you place the script log in
your main logs directory, do NOT change the
directory permissions to make it writable by the user the child
processes run as.ScriptLogBuffer Directive
Description: Maximum amount of PUT or POST requests that will be recorded
in the scriptlog Syntax: ScriptLogBuffer bytesDefault: ScriptLogBuffer 1024Context: server config, virtual host Status: Base Module: mod_cgi, mod_cgidScriptLogLength Directive
Description: Size limit of the CGI script logfile Syntax: ScriptLogLength bytesDefault: ScriptLogLength 10385760Context: server config, virtual host Status: Base Module: mod_cgi, mod_cgidScriptLogLength can be used to limit the
size of the CGI script logfile. Since the logfile logs a lot of
information per CGI error (all request headers, all script output)
it can grow to be a big file. To prevent problems due to unbounded
growth, this directive can be used to set an maximum file-size for
the CGI logfile. If the file exceeds this size, no more
information will be written to it.
mod/mod_charset_lite.html 100644 0 0 27267 11074462673 13227 0 ustar 0 0
Apache Module mod_cgid
Description: Execution of CGI scripts using an
external CGI daemon Status: Base Module Identifier: cgid_module Source File: mod_cgid.c Compatibility: Unix threaded MPMs only Summary
ScriptSock directive noted below,
mod_cgid behaves similarly to mod_cgi.
See the mod_cgi summary for additional details
about Apache and CGI.mod_cgid creates an external daemon that is
responsible for forking child processes to run CGI scripts. The
main server communicates with this daemon using a unix domain
socket.mod_cgi whenever a multi-threaded MPM
is selected during the compilation process. At the user level,
this module is identical in configuration and operation to
mod_cgi. The only exception is the
additional directive ScriptSock which gives the
name of the socket to use for communication with the cgi
daemon.Directives
See also
ScriptSock Directive
Description: The name of the socket to use for communication with
the cgi daemon Syntax: ScriptSock file-pathDefault: ScriptSock logs/cgisockContext: server config, virtual host Status: Base Module: mod_cgid Example
ScriptSock /var/run/cgid.sock
mod/mod_dav.html 100644 0 0 35466 11074462673 11333 0 ustar 0 0
Apache Module mod_charset_lite
Description: Specify character set translation or recoding Status: Experimental Module Identifier: charset_lite_module Source File: mod_charset_lite.c Summary
mod_charset_lite configuration to ensure that it
performs the desired function.mod_charset_lite allows the administrator to
specify the source character set of objects as well as the
character set they should be translated into before sending to the
client. mod_charset_lite does not translate the
data itself but instead tells Apache what translation to
perform. mod_charset_lite is applicable to EBCDIC
and ASCII host environments. In an EBCDIC environment, Apache
normally translates text content from the code page of the Apache
process locale to ISO-8859-1. mod_charset_lite
can be used to specify that a different translation is to be
performed. In an ASCII environment, Apache normally performs no
translation, so mod_charset_lite is needed in
order for any translation to take place.mod_charset.
Common Problems
Invalid character set names
CharsetSourceEnc and
CharsetDefault
must be acceptable to the translation mechanism used by APR on the
system where mod_charset_lite is deployed. These
character set names are not standardized and are usually not the
same as the corresponding values used in http headers. Currently,
APR can only use iconv(3), so you can easily test your character
set names using the iconv(1) program, as follows:
iconv -f charsetsourceenc-value -t charsetdefault-value
Mismatch between character set of content and translation
rules
CharsetDefault Directive
Description: Charset to translate into Syntax: CharsetDefault charsetContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Experimental Module: mod_charset_lite CharsetDefault directive specifies the
charset that content in the associated container should be
translated to.Example
<Directory /export/home/trawick/apacheinst/htdocs/convert>
CharsetSourceEnc UTF-16BE
CharsetDefault ISO-8859-1
</Directory>
CharsetOptions Directive
Description: Configures charset translation behavior Syntax: CharsetOptions option [option] ...Default: CharsetOptions DebugLevel=0 NoImplicitAddContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Experimental Module: mod_charset_lite CharsetOptions directive configures certain
behaviors of mod_charset_lite. Option can
be one of
DebugLevel=nDebugLevel keyword allows you to specify
the level of debug messages generated by
mod_charset_lite. By default, no messages are
generated. This is equivalent to DebugLevel=0.
With higher numbers, more debug messages are generated, and
server performance will be degraded. The actual meanings of
the numeric values are described with the definitions of the
DBGLVL_ constants near the beginning of
mod_charset_lite.c.ImplicitAdd | NoImplicitAddImplicitAdd keyword specifies that
mod_charset_lite should implicitly insert its
filter when the configuration specifies that the character
set of content should be translated. If the filter chain is
explicitly configured using the AddOutputFilter directive, NoImplicitAdd
should be specified so that mod_charset_lite
doesn't add its filter.CharsetSourceEnc Directive
Description: Source charset of files Syntax: CharsetSourceEnc charsetContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Experimental Module: mod_charset_lite CharsetSourceEnc directive specifies the
source charset of files in the associated container.Example
<Directory /export/home/trawick/apacheinst/htdocs/convert>
CharsetSourceEnc UTF-16BE
CharsetDefault ISO-8859-1
</Directory>
mod/mod_dav_fs.html 100644 0 0 12647 11074462673 12017 0 ustar 0 0
Apache Module mod_dav
Description: Distributed Authoring and Versioning
(WebDAV) functionality Status: Extension Module Identifier: dav_module Source File: mod_dav.c Summary
Directives
Topics
See also
Enabling WebDAV
mod_dav, add the following to a
container in your httpd.conf file:Dav Onmod_dav_fs module. Therefore, that module
must be compiled into the server or loaded at runtime using the
LoadModule directive.httpd.conf
file using the DavLockDB
directive:
DavLockDB /usr/local/apache2/var/DavLock
User
and Group under which
Apache is running.<Limit> clause inside the <Location> directive to limit access to
DAV-enabled locations. If you want to set the maximum amount of
bytes that a DAV client can send at one request, you have to use
the LimitXMLRequestBody
directive. The "normal" LimitRequestBody directive has no effect on DAV
requests.Full Example
DavLockDB /usr/local/apache2/var/DavLock
<Location /foo>
Dav On
AuthType Basic
AuthName DAV
AuthUserFile user.passwd
<LimitExcept GET OPTIONS>
require user admin
</LimitExcept>
</Location>
mod_dav is a descendent of Greg Stein's mod_dav for Apache 1.3. More
information about the module is available from that site.
Security Issues
mod_dav.mod_auth_digest module. Nearly all WebDAV clients
support this authentication method. An alternative is Basic
Authentication over an SSL enabled
connection.mod_dav to manage files, it must
be able to write to the directories and files under its control
using the User and
Group under which
Apache is running. New files created will also be owned by this
User and Group. For this reason, it is
important to control access to this account. The DAV repository
is considered private to Apache; modifying files outside of Apache
(for example using FTP or filesystem-level tools) should not be
allowed.mod_dav may be subject to various kinds of
denial-of-service attacks. The LimitXMLRequestBody directive can be
used to limit the amount of memory consumed in parsing large DAV
requests. The DavDepthInfinity directive can be
used to prevent PROPFIND requests on a very large
repository from consuming large amounts of memory. Another
possible denial-of-service attack involves a client simply filling
up all available disk space with many large files. There is no
direct way to prevent this in Apache, so you should avoid giving
DAV access to untrusted users.
Complex Configurations
mod_dav to
manipulate dynamic files (PHP scripts, CGI scripts, etc). This is
difficult because a GET request will always run the
script, rather than downloading its contents. One way to avoid
this is to map two different URLs to the content, one of which
will run the script, and one of which will allow it to be
downloaded and manipulated with DAV.
Alias /phparea /home/gstein/php_files
Alias /php-source /home/gstein/php_files
<Location /php-source>
DAV On
ForceType text/plain
</Location>
http://example.com/phparea can be
used to access the output of the PHP scripts, and
http://example.com/php-source can be used with a DAV
client to manipulate them.Dav Directive
Description: Enable WebDAV HTTP methods Syntax: Dav On|Off|provider-nameDefault: Dav OffContext: directory Status: Extension Module: mod_dav Dav directive to enable the
WebDAV HTTP methods for the given container:
<Location /foo>
Dav On
</Location>
On is actually an alias for the default
provider filesystem which is served by the mod_dav_fs module. Note, that once you have DAV enabled
for some location, it cannot be disabled for sublocations.
For a complete configuration example have a look at the section above.
Do not enable WebDAV until you have secured your server. Otherwise
everyone will be able to distribute files on your system.
DavDepthInfinity Directive
Description: Allow PROPFIND, Depth: Infinity requests Syntax: DavDepthInfinity on|offDefault: DavDepthInfinity offContext: server config, virtual host, directory Status: Extension Module: mod_dav DavDepthInfinity directive to
allow the processing of PROPFIND requests containing the
header 'Depth: Infinity'. Because this type of request could constitute
a denial-of-service attack, by default it is not allowed.DavMinTimeout Directive
Description: Minimum amount of time the server holds a lock on
a DAV resource Syntax: DavMinTimeout secondsDefault: DavMinTimeout 0Context: server config, virtual host, directory Status: Extension Module: mod_dav DavMinTimeout directive to specify, in
seconds, the minimum lock timeout to return to a client.
Microsoft Web Folders defaults to a timeout of 120 seconds; the
DavMinTimeout can override this to a higher value
(like 600 seconds) to reduce the chance of the client losing
the lock due to network latency.Example
<Location /MSWord>
DavMinTimeout 600
</Location>
mod/mod_deflate.html 100644 0 0 46227 11074462673 12162 0 ustar 0 0
Apache Module mod_dav_fs
Description: filesystem provider for mod_davStatus: Extension Module Identifier: dav_fs_module Source File: mod_dav_fs.c Summary
mod_dav. It acts as a support module for mod_dav and provides access to resources located in the
server's file system. The formal name of this provider is
filesystem. mod_dav backend providers
will be invoked by using the Dav
directive:Example
Dav filesystem
filesystem is the default provider for
mod_dav, you may simply use the value
On instead.DavLockDB Directive
Description: Location of the DAV lock database Syntax: DavLockDB file-pathContext: server config, virtual host Status: Extension Module: mod_dav_fs DavLockDB directive to specify
the full path to the lock database, excluding an extension. If
the path is not absolute, it will be taken relative to ServerRoot. The implementation of
mod_dav_fs uses a SDBM database to track user
locks.Example
DavLockDB var/DavLock
User
and Group under which
Apache is running. For security reasons, you should create a
directory for this purpose rather than changing the permissions on
an existing directory. In the above example, Apache will create
files in the var/ directory under the ServerRoot with the base filename
DavLock and extension name chosen by the server.
mod/mod_dir.html 100644 0 0 22307 11074462673 11325 0 ustar 0 0
Apache Module mod_deflate
Description: Compress content before it is delivered to the
client Status: Extension Module Identifier: deflate_module Source File: mod_deflate.c Summary
mod_deflate module provides
the DEFLATE output filter that allows output from
your server to be compressed before being sent to the client over
the network.Directives
Topics
See also
Sample Configurations
Compress only a few types
AddOutputFilterByType DEFLATE text/html text/plain text/xml
Compress everything except images
<Location />
# Insert filter
SetOutputFilter DEFLATE
# Netscape 4.x has some problems...
BrowserMatch ^Mozilla/4 gzip-only-text/html
# Netscape 4.06-4.08 have some more problems
BrowserMatch ^Mozilla/4\.0[678] no-gzip
# MSIE masquerades as Netscape, but it is fine
# BrowserMatch \bMSIE !no-gzip !gzip-only-text/html
# NOTE: Due to a bug in mod_setenvif up to Apache 2.0.48
# the above regex won't work. You can use the following
# workaround to get the desired effect:
BrowserMatch \bMSI[E] !no-gzip !gzip-only-text/html
# Don't compress images
SetEnvIfNoCase Request_URI \
\.(?:gif|jpe?g|png)$ no-gzip dont-vary
# Make sure proxies don't deliver the wrong content
Header append Vary User-Agent env=!dont-vary
</Location>
Enabling Compression
Output Compression
DEFLATE
filter. The following directive
will enable compression for documents in the container where it
is placed:
SetOutputFilter DEFLATE
gzip-only-text/html note to
1 to only allow html files to be compressed (see
below). If you set this to anything but 1 it
will be ignored.AddOutputFilterByType directive. Here is an example of
enabling compression only for the html files of the Apache
documentation:
<Directory "/your-server-root/manual">
AddOutputFilterByType DEFLATE text/html
</Directory>
BrowserMatch directive to set the no-gzip
note for that particular browser so that no compression will be
performed. You may combine no-gzip with gzip-only-text/html to get the best results. In that case
the former overrides the latter. Take a look at the following
excerpt from the configuration example
defined in the section above:
BrowserMatch ^Mozilla/4 gzip-only-text/html
BrowserMatch ^Mozilla/4\.0[678] no-gzip
BrowserMatch \bMSIE !no-gzip !gzip-only-text/html
User-Agent string that
indicates a Netscape Navigator version of 4.x. These versions
cannot handle compression of types other than
text/html. The versions 4.06, 4.07 and 4.08 also
have problems with decompressing html files. Thus, we completely
turn off the deflate filter for them.BrowserMatch
directive fixes the guessed identity of the user agent, because
the Microsoft Internet Explorer identifies itself also as "Mozilla/4"
but is actually able to handle requested compression. Therefore we
match against the additional string "MSIE" (\b means
"word boundary") in the User-Agent Header and turn off
the restrictions defined before.Note
The DEFLATE filter is always inserted after RESOURCE
filters like PHP or SSI. It never touches internal subrequests.
Input Decompression
mod_deflate module also provides a filter for
decompressing a gzip compressed request body . In order to activate
this feature you have to insert the DEFLATE filter into
the input filter chain using SetInputFilter or AddInputFilter, for example:
<Location /dav-area>
SetInputFilter DEFLATE
</Location>
Content-Encoding:
gzip header, the body will be automatically decompressed.
Few browsers have the ability to gzip request bodies. However,
some special applications actually do support request
compression, for instance some WebDAV clients.Note on Content-Length
Content-Length header!
The Content-Length header reflects the length of the
incoming data from the client and not the byte count of
the decompressed data stream.
Dealing with proxy servers
mod_deflate module sends a Vary:
Accept-Encoding HTTP response header to alert proxies that
a cached response should be sent only to clients that send the
appropriate Accept-Encoding request header. This
prevents compressed content from being sent to a client that will
not understand it.User-Agent header, you must
manually configure an addition to the Vary header
to alert proxies of the additional restrictions. For example,
in a typical configuration where the addition of the DEFLATE
filter depends on the User-Agent, you should add:
Header append Vary User-Agent
Vary header to the value *. This prevents
compliant proxies from caching entirely.Example
Header set Vary *
DeflateBufferSize Directive
Description: Fragment size to be compressed at one time by zlib Syntax: DeflateBufferSize valueDefault: DeflateBufferSize 8096Context: server config, virtual host Status: Extension Module: mod_deflate DeflateBufferSize directive specifies
the size in bytes of the fragments that zlib should compress at one
time.DeflateCompressionLevel Directive
Description: How much compression do we apply to the output Syntax: DeflateCompressionLevel valueDefault: Zlib's defaultContext: server config, virtual host Status: Extension Module: mod_deflate Compatibility: This directive is available since Apache 2.0.45 DeflateCompressionLevel directive specifies
what level of compression should be used, the higher the value,
the better the compression, but the more CPU time is required to
achieve this.DeflateFilterNote Directive
Description: Places the compression ratio in a note for logging Syntax: DeflateFilterNote [type] notenameContext: server config, virtual host Status: Extension Module: mod_deflate Compatibility: type is available since Apache 2.0.45 DeflateFilterNote directive
specifies that a note about compression ratios should be attached
to the request. The name of the note is the value specified for
the directive. You can use that note for statistical purposes by
adding the value to your access log.Example
DeflateFilterNote ratio
LogFormat '"%r" %b (%{ratio}n) "%{User-agent}i"' deflate
CustomLog logs/deflate_log deflate
InputOutputRatiooutput/input * 100)
in the note. This is the default, if the type argument
is omitted.Accurate Logging
DeflateFilterNote Input instream
DeflateFilterNote Output outstream
DeflateFilterNote Ratio ratio
LogFormat '"%r" %{outstream}n/%{instream}n (%{ratio}n%%)' deflate
CustomLog logs/deflate_log deflate
See also
DeflateMemLevel Directive
Description: How much memory should be used by zlib for compression Syntax: DeflateMemLevel valueDefault: DeflateMemLevel 9Context: server config, virtual host Status: Extension Module: mod_deflate DeflateMemLevel directive specifies
how much memory should be used by zlib for compression
(a value between 1 and 9).DeflateWindowSize Directive
Description: Zlib compression window size Syntax: DeflateWindowSize valueDefault: DeflateWindowSize 15Context: server config, virtual host Status: Extension Module: mod_deflate DeflateWindowSize directive specifies the
zlib compression window size (a value between 1 and 15). Generally, the
higher the window size, the higher can the compression ratio be expected.
mod/mod_disk_cache.html 100644 0 0 52334 11074462673 12627 0 ustar 0 0
Apache Module mod_dir
Description: Provides for "trailing slash" redirects and
serving directory index files Status: Base Module Identifier: dir_module Source File: mod_dir.c Summary
index.html. The DirectoryIndex directive sets the
name of this file. This is controlled by
mod_dir.mod_autoindex.http://servername/foo/dirname where
dirname is a directory. Directories require a
trailing slash, so mod_dir issues a redirect to
http://servername/foo/dirname/.Directives
DirectoryIndex Directive
Description: List of resources to look for when the client requests
a directory Syntax: DirectoryIndex
local-url [local-url] ...Default: DirectoryIndex index.htmlContext: server config, virtual host, directory, .htaccess Override: Indexes Status: Base Module: mod_dir DirectoryIndex directive sets the
list of resources to look for, when the client requests an index
of the directory by specifying a / at the end of the directory
name. Local-url is the (%-encoded) URL of a document on
the server relative to the requested directory; it is usually the
name of a file in the directory. Several URLs may be given, in
which case the server will return the first one that it finds. If
none of the resources exist and the Indexes option is
set, the server will generate its own listing of the
directory.Example
DirectoryIndex index.html
http://myserver/docs/ would
return http://myserver/docs/index.html if it
exists, or would list the directory if it did not.
DirectoryIndex index.html index.txt /cgi-bin/index.pl
/cgi-bin/index.pl to be
executed if neither index.html or index.txt
existed in a directory.DirectorySlash Directive
Description: Toggle trailing slash redirects on or off Syntax: DirectorySlash On|OffDefault: DirectorySlash OnContext: server config, virtual host, directory, .htaccess Override: Indexes Status: Base Module: mod_dir Compatibility: Available in version 2.0.51 and later DirectorySlash directive determines, whether
mod_dir should fixup URLs pointing to a directory or
not.mod_dir redirects him to the same
resource, but with trailing slash for some good reasons:
mod_autoindex works correctly. Since it doesn't emit
the path in the link, it would point to the wrong path.DirectoryIndex will be evaluated
only for directories requested with trailing slash.
# see security warning below!
<Location /some/path>
DirectorySlash Off
SetHandler some-handler
</Location>
Security Warning
mod_autoindex is
active (Options +Indexes) and DirectoryIndex is set to a valid resource (say,
index.html) and there's no other special handler defined for
that URL. In this case a request with a trailing slash would show the
index.html file. But a request without trailing slash
would list the directory contents.
mod/mod_dumpio.html 100644 0 0 13534 11074462673 12046 0 ustar 0 0
Apache Module mod_disk_cache
Description: Content cache storage manager keyed to URIs Status: Experimental Module Identifier: disk_cache_module Source File: mod_disk_cache.c Summary
This module is experimental. Documentation is still under development...
mod_disk_cache implements a disk based storage
manager. It is primarily of use in conjunction with
mod_proxy.Note:
mod_disk_cache requires the services of
mod_cache.Directives
CacheDirLength Directive
Description: The number of characters in subdirectory names Syntax: CacheDirLength lengthDefault: CacheDirLength 2Context: server config, virtual host Status: Experimental Module: mod_disk_cache CacheDirLength directive sets the number
of characters for each subdirectory name in the cache hierarchy.
CacheDirLevels* CacheDirLength
must not be higher than 20.
CacheDirLength 4
CacheDirLevels Directive
Description: The number of levels of subdirectories in the
cache. Syntax: CacheDirLevels levelsDefault: CacheDirLevels 3Context: server config, virtual host Status: Experimental Module: mod_disk_cache CacheDirLevels directive sets the number
of subdirectory levels in the cache. Cached data will be saved this
many directory levels below the CacheRoot directory.
CacheDirLevels*
CacheDirLength must
not be higher than 20.
CacheDirLevels 5
CacheExpiryCheck Directive
Description: Indicates if the cache observes Expires dates when seeking
files Syntax: CacheExpiryCheck On|OffDefault: CacheExpiryCheck OnContext: server config, virtual host Status: Experimental Module: mod_disk_cache
CacheExpiryCheck Off
The
CacheExpiryCheck directive is currently
not implemented.
CacheGcClean Directive
Description: The time to retain unchanged cached files that match a
URL Syntax: CacheGcClean hours url-stringDefault: CacheGcClean ?Context: server config, virtual host Status: Experimental Module: mod_disk_cache
CacheGcClean 12 /daily_scripts
The
CacheGcClean directive is currently
not implemented.
CacheGcDaily Directive
Description: The recurring time each day for garbage collection to be run.
(24 hour clock) Syntax: CacheGcDaily timeDefault: CacheGcDaily ?Context: server config, virtual host Status: Experimental Module: mod_disk_cache
CacheGcDaily 23:59
The
CacheGcDaily directive is currently
not implemented.
CacheGcInterval Directive
Description: The interval between garbage collection attempts. Syntax: CacheGcInterval hoursContext: server config, virtual host Status: Experimental Module: mod_disk_cache CacheGcInterval directive specifies the
number of hours to wait between attempts to free up disk space.
CacheGcInterval 24
The
CacheGcInterval directive is currently
not implemented.
CacheGcMemUsage Directive
Description: The maximum kilobytes of memory used for garbage
collection Syntax: CacheGcMemUsage KBytesDefault: CacheGcMemUsage ?Context: server config, virtual host Status: Experimental Module: mod_disk_cache
CacheGcMemUsage 16
The
CacheGcMemUsage directive is currently
not implemented.
CacheGcUnused Directive
Description: The time to retain unreferenced cached files that match a
URL. Syntax: CacheGcUnused hours url-stringDefault: CacheGcUnused ?Context: server config, virtual host Status: Experimental Module: mod_disk_cache
CacheGcUnused 12 /local_images
The
CacheGcUnused directive is currently
not implemented.
CacheMaxFileSize Directive
Description: The maximum size (in bytes) of a document to be placed in the
cache Syntax: CacheMaxFileSize bytesDefault: CacheMaxFileSize 1000000Context: server config, virtual host Status: Experimental Module: mod_disk_cache CacheMaxFileSize directive sets the
maximum size, in bytes, for a document to be considered for storage in
the cache.
CacheMaxFileSize 64000
CacheMinFileSize Directive
Description: The minimum size (in bytes) of a document to be placed in the
cache Syntax: CacheMinFileSize bytesDefault: CacheMinFileSize 1Context: server config, virtual host Status: Experimental Module: mod_disk_cache CacheMinFileSize directive sets the
minimum size, in bytes, for a document to be considered for storage
in the cache.
CacheMinFileSize 64
CacheRoot Directive
Description: The directory root under which cache files are
stored Syntax: CacheRoot directoryContext: server config, virtual host Status: Experimental Module: mod_disk_cache CacheRoot directive defines the name of
the directory on the disk to contain cache files. If the mod_disk_cache module has been loaded or compiled in to the
Apache server, this directive must be defined. Failing to
provide a value for CacheRoot will result in
a configuration file processing error. The CacheDirLevels and CacheDirLength directives define
the structure of the directories under the specified root directory.
CacheRoot c:/cacheroot
CacheSize Directive
Description: The maximum amount of disk space that will be used by the
cache in KBytes Syntax: CacheSize KBytesDefault: CacheSize 1000000Context: server config, virtual host Status: Experimental Module: mod_disk_cache CacheSize directive sets the desired
disk space usage of the cache, in KBytes (1024-byte units). This
directive does not put a hard limit on the size of the cache. The
garbage collector will delete files until the usage is at or below the
settings. Always use a value that is lower than the available disk
space.
CacheSize 5000000
CacheTimeMargin Directive
Description: The minimum time margin to cache a document Syntax: CacheTimeMargin ?Default: CacheTimeMargin ?Context: server config, virtual host Status: Experimental Module: mod_disk_cache
CacheTimeMargin X
The
CacheTimeMargin directive is currently
not implemented.
mod/mod_echo.html 100644 0 0 7474 11074462673 11455 0 ustar 0 0
Apache Module mod_dumpio
Description: Dumps all I/O to error log as desired. Status: Experimental Module Identifier: dumpio_module Source File: mod_dumpio.c Summary
mod_dumpio allows for the logging of
all input received by Apache and/or all output sent by
Apache to be logged (dumped) to the error.log file.
Enabling dumpio Support
LogLevel must be set to debug.DumpIOInput Directive
Description: Dump all input data to the error log Syntax: DumpIOInput On|OffDefault: DumpIOInput OffContext: server config Status: Experimental Module: mod_dumpio Compatibility: DumpIOInput is only available in Apache 2.0.53 and
later. Example
DumpIOInput On
DumpIOOutput Directive
Description: Dump all output data to the error log Syntax: DumpIOOutput On|OffDefault: DumpIOOutput OffContext: server config Status: Experimental Module: mod_dumpio Compatibility: DumpIOOutput is only available in Apache 2.0.53 and
later. Example
DumpIOOutput On
mod/mod_env.html 100644 0 0 14660 11074462673 11342 0 ustar 0 0
Apache Module mod_echo
Description: A simple echo server to illustrate protocol
modules Status: Experimental Module Identifier: echo_module Source File: mod_echo.c Compatibility: Available in Apache 2.0 and later Summary
Directives
ProtocolEcho Directive
Description: Turn the echo server on or off Syntax: ProtocolEcho On|OffContext: server config, virtual host Status: Experimental Module: mod_echo Compatibility: ProtocolEcho is only available in 2.0 and
later. ProtocolEcho directive enables or
disables the echo server.Example
ProtocolEcho On
mod/mod_example.html 100644 0 0 16267 11074462673 12212 0 ustar 0 0
Apache Module mod_env
Description: Modifies the environment which is passed to CGI scripts and
SSI pages Status: Base Module Identifier: env_module Source File: mod_env.c Summary
httpd
process. Alternatively, environment variables may be set or unset within
the configuration process.PassEnv Directive
Description: Passes environment variables from the shell Syntax: PassEnv env-variable [env-variable]
...Context: server config, virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_env httpd process.Example
PassEnv LD_LIBRARY_PATH
SetEnv Directive
Description: Sets environment variables Syntax: SetEnv env-variable valueContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_env Example
SetEnv SPECIAL_PATH /foo/bin
UnsetEnv Directive
Description: Removes variables from the environment Syntax: UnsetEnv env-variable [env-variable]
...Context: server config, virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_env Example
UnsetEnv LD_LIBRARY_PATH
mod/mod_expires.html 100644 0 0 31133 11074462673 12223 0 ustar 0 0
Apache Module mod_example
Description: Illustrates the Apache module API Status: Experimental Module Identifier: example_module Source File: mod_example.c Summary
This document has not been updated
to take into account changes made in the 2.0 version of the
Apache HTTP Server. Some of the information may still be
relevant, but please use it with care.
src/modules/example directory
under the Apache distribution directory tree are provided as an
example to those that wish to write modules that use the Apache
API.mod_example.c, which
illustrates all the different callback mechanisms and call
syntaxes. By no means does an add-on module need to include
routines for all of the callbacks - quite the contrary!
Compiling the example module
src/Configuration file.
If there isn't one, add it; it should look like this:
AddModule modules/example/mod_example.o
src/Configure script
("cd src; ./Configure"). This will
build the Makefile for the server itself, and update the
src/modules/Makefile for any additional modules
you have requested from beneath that subdirectory.make" in the
src directory).
mkdir src/modules/mymodulecp src/modules/example/*
src/modules/mymodule
Using the
mod_example Modulesrm.conf file:
<Location /example-info>
SetHandler example-handler
</Location>
.htaccess file
and then request the file "test.example" from that location:
AddHandler example-handler .example
Example Directive
Description: Demonstration directive to illustrate the Apache module
API Syntax: ExampleContext: server config, virtual host, directory, .htaccess Status: Experimental Module: mod_example Example directive just sets a demonstration
flag which the example module's content handler displays. It
takes no arguments. If you browse to an URL to which the
example content-handler applies, you will get a display of the
routines within the module and how and in what order they were
called to service the document request. The effect of this
directive one can observe under the point "Example
directive declared here: YES/NO".
mod/mod_ext_filter.html 100644 0 0 41404 11074462673 12713 0 ustar 0 0
Apache Module mod_expires
Description: Generation of Expires and
Cache-Control HTTP headers according to user-specified
criteriaStatus: Extension Module Identifier: expires_module Source File: mod_expires.c Summary
Expires
HTTP header and the max-age directive of the
Cache-Control HTTP header in server responses. The
expiration date can set to be relative to either the time the
source file was last modified, or to the time of the client
access.Cache-Control directives other than
max-age (see RFC
2616 section 14.9), you can use the Header directive.
Alternate Interval Syntax
ExpiresDefault and
ExpiresByType directives
can also be defined in a more readable syntax of the form:
ExpiresDefault "<base> [plus] {<num>
<type>}*"
ExpiresByType type/encoding "<base> [plus]
{<num> <type>}*"
accessnow (equivalent to
'access')modificationplus keyword is optional. <num>
should be an integer value [acceptable to atoi()],
and <type> is one of:
yearsmonthsweeksdayshoursminutesseconds
ExpiresDefault "access plus 1 month"
ExpiresDefault "access plus 4 weeks"
ExpiresDefault "access plus 30 days"
ExpiresByType text/html "access plus 1 month 15
days 2 hours"
ExpiresByType image/gif "modification plus 5 hours 3
minutes"
ExpiresActive Directive
Description: Enables generation of Expires
headersSyntax: ExpiresActive On|OffContext: server config, virtual host, directory, .htaccess Override: Indexes Status: Extension Module: mod_expires Expires and Cache-Control headers for
the document realm in question. (That is, if found in an
.htaccess file, for instance, it applies only to
documents generated from that directory.) If set to
Off, the headers will not be generated for any
document in the realm (unless overridden at a lower level, such as
an .htaccess file overriding a server config
file). If set to On, the headers will be added to
served documents according to the criteria defined by the
ExpiresByType and
ExpiresDefault
directives (q.v.).Expires or Cache-Control header will be
generated. If the criteria aren't met, no header will be sent, and
the effect will be as though this directive wasn't even
specified.ExpiresByType Directive
Description: Value of the Expires header configured
by MIME typeSyntax: ExpiresByType MIME-type
<code>secondsContext: server config, virtual host, directory, .htaccess Override: Indexes Status: Extension Module: mod_expires Expires
header and the max-age directive of the
Cache-Control header generated for documents of the
specified type (e.g., text/html). The second
argument sets the number of seconds that will be added to a base
time to construct the expiration date. The Cache-Control:
max-age is calculated by subtracting the request time from
the expiration date and expressing the result in seconds.<code> field; M
means that the file's last modification time should be used as
the base time, and A means the client's access
time should be used.M is used,
all current copies of the document in all caches will expire at
the same time, which can be good for something like a weekly
notice that's always found at the same URL. If A is
used, the date of expiration is different for each client; this
can be good for image files that don't change very often,
particularly for a set of related documents that all refer to
the same images (i.e., the images will be accessed
repeatedly within a relatively short timespan).Example:
# enable expirations
ExpiresActive On
# expire GIF images after a month in the client's cache
ExpiresByType image/gif A2592000
# HTML documents are good for a week from the
# time they were changed
ExpiresByType text/html M604800
ExpiresActive On has been specified. It overrides,
for the specified MIME type only, any expiration date
set by the ExpiresDefault
directive.ExpiresDefault Directive
Description: Default algorithm for calculating expiration time Syntax: ExpiresDefault <code>secondsContext: server config, virtual host, directory, .htaccess Override: Indexes Status: Extension Module: mod_expires ExpiresByType directive. See the
description of that directive for details about the syntax of the
argument, and the alternate syntax
description as well.
mod/mod_file_cache.html 100644 0 0 27711 11074462673 12615 0 ustar 0 0
Apache Module mod_ext_filter
Description: Pass the response body through an external program before
delivery to the client Status: Extension Module Identifier: ext_filter_module Source File: mod_ext_filter.c Summary
mod_ext_filter presents a simple and familiar
programming model for filters. With
this module, a program which reads from stdin and writes to stdout
(i.e., a Unix-style filter command) can be a filter for
Apache. This filtering mechanism is much slower than using a
filter which is specially written for the Apache API and runs
inside of the Apache server process, but it does have the
following benefits:
mod_ext_filter can be used as
a prototype environment for filters.
Examples
Generating HTML from some other type of response
# mod_ext_filter directive to define a filter
# to HTML-ize text/c files using the external
# program /usr/bin/enscript, with the type of
# the result set to text/html
ExtFilterDefine c-to-html mode=output \
intype=text/c outtype=text/html \
cmd="/usr/bin/enscript --color -W html -Ec -o - -"
<Directory "/export/home/trawick/apacheinst/htdocs/c">
# core directive to cause the new filter to
# be run on output
SetOutputFilter c-to-html
# mod_mime directive to set the type of .c
# files to text/c
AddType text/c .c
# mod_ext_filter directive to set the debug
# level just high enough to see a log message
# per request showing the configuration in force
ExtFilterOptions DebugLevel=1
</Directory>
Implementing a content encoding filter
mod_deflate for a practical
implementation.
# mod_ext_filter directive to define the external filter
ExtFilterDefine gzip mode=output cmd=/bin/gzip
<Location /gzipped>
# core directive to cause the gzip filter to be
# run on output
SetOutputFilter gzip
# mod_header directive to add
# "Content-Encoding: gzip" header field
Header set Content-Encoding gzip
</Location>
Slowing down the server
# mod_ext_filter directive to define a filter
# which runs everything through cat; cat doesn't
# modify anything; it just introduces extra pathlength
# and consumes more resources
ExtFilterDefine slowdown mode=output cmd=/bin/cat \
preservescontentlength
<Location />
# core directive to cause the slowdown filter to
# be run several times on output
#
SetOutputFilter slowdown;slowdown;slowdown
</Location>
Using sed to replace text in the response
# mod_ext_filter directive to define a filter which
# replaces text in the response
#
ExtFilterDefine fixtext mode=output intype=text/html \
cmd="/bin/sed s/verdana/arial/g"
<Location />
# core directive to cause the fixtext filter to
# be run on output
SetOutputFilter fixtext
</Location>
Tracing another filter
# Trace the data read and written by mod_deflate
# for a particular client (IP 192.168.1.31)
# experiencing compression problems.
# This filter will trace what goes into mod_deflate.
ExtFilterDefine tracebefore \
cmd="/bin/tracefilter.pl /tmp/tracebefore" \
EnableEnv=trace_this_client
# This filter will trace what goes after mod_deflate.
# Note that without the ftype parameter, the default
# filter type of AP_FTYPE_RESOURCE would cause the
# filter to be placed *before* mod_deflate in the filter
# chain. Giving it a numeric value slightly higher than
# AP_FTYPE_CONTENT_SET will ensure that it is placed
# after mod_deflate.
ExtFilterDefine traceafter \
cmd="/bin/tracefilter.pl /tmp/traceafter" \
EnableEnv=trace_this_client ftype=21
<Directory /usr/local/docs>
SetEnvIf Remote_Addr 192.168.1.31 trace_this_client
SetOutputFilter tracebefore;deflate;traceafter
</Directory>
Here is the filter which traces the data:
#!/usr/local/bin/perl -w
use strict;
open(SAVE, ">$ARGV[0]")
or die "can't open $ARGV[0]: $?";
while (<STDIN>) {
print SAVE $_;
print $_;
}
close(SAVE);
ExtFilterDefine Directive
Description: Define an external filter Syntax: ExtFilterDefine filtername parametersContext: server config Status: Extension Module: mod_ext_filter ExtFilterDefine directive defines the
characteristics of an external filter, including the program to
run and its arguments.cmd=. These parameters
are:
cmd=cmdlinecmd= keyword allows you to specify the
external command to run. If there are arguments after the
program name, the command line should be surrounded in
quotation marks (e.g., cmd="/bin/mypgm
arg1 arg2". Normal shell quoting is
not necessary since the program is run directly, bypassing the shell.
Program arguments are blank-delimited. A backslash can be used to
escape blanks which should be part of a program argument. Any
backslashes which are part of the argument must be escaped with
backslash themselves. In addition to the standard CGI environment
variables, DOCUMENT_URI, DOCUMENT_PATH_INFO, and
QUERY_STRING_UNESCAPED will also be set for the program.mode=modemode should be output for now (the
default). In the future, mode=input will be used to
specify a filter for request bodies.intype=imtintype= is
specified, the filter will be disabled for documents of other
types.outtype=imtPreservesContentLengthPreservesContentLength keyword specifies
that the filter preserves the content length. This is not the
default, as most filters change the content length. In the
event that the filter doesn't modify the length, this keyword
should be specified.ftype=filtertypedisableenv=envenableenv=envExtFilterOptions Directive
Description: Configure mod_ext_filter optionsSyntax: ExtFilterOptions option [option] ...Default: ExtFilterOptions DebugLevel=0 NoLogStderrContext: directory Status: Extension Module: mod_ext_filter ExtFilterOptions directive specifies
special processing options for mod_ext_filter.
Option can be one of
DebugLevel=nDebugLevel keyword allows you to specify
the level of debug messages generated by
mod_ext_filter. By default, no debug messages
are generated. This is equivalent to
DebugLevel=0. With higher numbers, more debug
messages are generated, and server performance will be
degraded. The actual meanings of the numeric values are
described with the definitions of the DBGLVL_ constants
near the beginning of mod_ext_filter.c.
LogLevel should be used to cause debug messages to
be stored in the Apache error log.LogStderr | NoLogStderrLogStderr keyword specifies that
messages written to standard error by the external filter
program will be saved in the Apache error log.
NoLogStderr disables this feature.Example
ExtFilterOptions LogStderr DebugLevel=0
mod_ext_filter.
mod/mod_headers.html 100644 0 0 37122 11074462673 12163 0 ustar 0 0
Apache Module mod_file_cache
Description: Caches a static list of files in memory Status: Experimental Module Identifier: file_cache_module Source File: mod_file_cache.c Summary
This module should be used with care. You can easily create a broken
site using
mod_file_cache, so read this document
carefully.
mod_file_cache provides two techniques for caching
frequently requested static files. Through configuration
directives, you can direct mod_file_cache to either
open then mmap() a file, or to pre-open a file and save
the file's open file handle. Both techniques reduce server
load when processing requests for these files by doing part of the work
(specifically, the file I/O) for serving the file when the
server is started rather than during each request.mod_mmap_static module in Apache 1.3.
Using mod_file_cache
mod_file_cache caches a list of statically
configured files via MMapFile or CacheFile directives in the main server configuration.MMapStatic directive, while
other platforms, like AIX, support both. You will receive an error
message in the server error log if you attempt to use an
unsupported directive. If given an unsupported directive, the
server will start but the file will not be cached. On platforms
that support both directives, you should experiment with both to
see which works best for you.MMapFile Directive
MMapFile
directive of mod_file_cache maps a list of
statically configured files into memory through the system call
mmap(). This system call is available on most modern
Unix derivates, but not on all. There are sometimes system-specific
limits on the size and number of files that can be
mmap()ed, experimentation is probably the easiest way
to find out.mmap()ing is done once at server start or
restart, only. So whenever one of the mapped files changes on the
filesystem you have to restart the server (see the Stopping and Restarting documentation).
To reiterate that point: if the files are modified in place
without restarting the server you may end up serving requests that
are completely bogus. You should update files by unlinking the old
copy and putting a new copy in place. Most tools such as
rdist and mv do this. The reason why this
modules doesn't take care of changes to the files is that this check
would need an extra stat() every time which is a waste
and against the intent of I/O reduction.CacheFile Directive
CacheFile
directive of mod_file_cache opens an active
handle or file descriptor to the file (or files)
listed in the configuration directive and places these open file
handles in the cache. When the file is requested, the server
retrieves the handle from the cache and passes it to the
sendfile() (or TransmitFile() on Windows),
socket API.rdist and
mv do this.Note
Include directive, and consider
this command:
find /www/htdocs -type f -print \
| sed -e 's/.*/mmapfile &/' > /www/conf/mmap.conf
CacheFile Directive
Description: Cache a list of file handles at startup time Syntax: CacheFile file-path [file-path] ...Context: server config Status: Experimental Module: mod_file_cache CacheFile directive opens handles to
one or more files (given as whitespace separated arguments) and
places these handles into the cache at server startup
time. Handles to cached files are automatically closed on a server
shutdown. When the files have changed on the filesystem, the
server should be restarted to to re-cache them.stat() system
calls which is not acceptable. This module may or may not work
with filenames rewritten by mod_alias or
mod_rewrite.Example
CacheFile /usr/local/apache/htdocs/index.html
MMapFile Directive
Description: Map a list of files into memory at startup time Syntax: MMapFile file-path [file-path] ...Context: server config Status: Experimental Module: mod_file_cache MMapFile directive maps one or more files
(given as whitespace separated arguments) into memory at server
startup time. They are automatically unmapped on a server
shutdown. When the files have changed on the filesystem at
least a HUP or USR1 signal should be send to
the server to re-mmap() them.stat() system
calls which is not acceptable. This module may or may not work
with filenames rewritten by mod_alias or
mod_rewrite.Example
MMapFile /usr/local/apache/htdocs/index.html
mod/mod_imap.html 100644 0 0 42674 11074462673 11506 0 ustar 0 0
Apache Module mod_headers
Description: Customization of HTTP request and response
headers Status: Extension Module Identifier: headers_module Source File: mod_headers.c Compatibility: RequestHeader
is available only in Apache 2.0Summary
Order of Processing
mod_headers can occur
almost anywhere within the server configuration. They are valid in the
main server config and virtual host sections, inside
<Directory>,
<Location> and
<Files> sections,
and within .htaccess files.
<Directory> sections and
.htaccess<Files><Location>
RequestHeader append MirrorID "mirror 12"
RequestHeader unset MirrorID
MirrorID header is not set. If
reversed, the MirrorID header is set to "mirror 12".
Examples
Header echo ^TS
MyHeader, to the response including a
timestamp for when the request was received and how long it
took to begin serving the request. This header can be used by
the client to intuit load on the server or in isolating
bottlenecks between the client and the server.
Header add MyHeader "%D %t"
MyHeader: D=3775428 t=991424704447256
Header add MyHeader "Hello Joe. It took %D microseconds \
for Apache to serve this request."
MyHeader: Hello Joe. It took D=3775428 microseconds for Apache
to serve this request.
MyHeader on the response if and
only if header "MyRequestHeader" is present on the request. This
is useful for constructing headers in response to some client
stimulus. Note that this example requires the services of the
mod_setenvif module.
SetEnvIf MyRequestHeader value HAVE_MyRequestHeader
Header add MyHeader "%D %t mytext" env=HAVE_MyRequestHeader
MyRequestHeader: value is present on
the HTTP request, the response will contain the following header:
MyHeader: D=3775428 t=991424704447256 mytext
Header Directive
Description: Configure HTTP response headers Syntax: Header [condition] set|append|add|unset|echo
header [value] [env=[!]variable]Context: server config, virtual host, directory, .htaccess Override: FileInfo Status: Extension Module: mod_headers Compatibility: Condition is available in version 2.0.51 and
later onsuccess
or always. It determines, which internal header table should be
operated on. onsuccess stands for 2xx
status codes and always for all status codes (including
2xx). Especially if you want to unset headers
set by certain modules, you should try out, which table is affected.
setappendaddunsetechoset, append, add
and unset. The header name for echo
is case sensitive and may be a regular expression.add, append and set a
value is specified as the third argument. If value
contains spaces, it should be surrounded by doublequotes.
value may be a character string, a string containing format
specifiers or a combination of both. The following format specifiers
are supported in value:
%tThe time the request was received in Universal Coordinated Time
since the epoch (Jan. 1, 1970) measured in microseconds. The value
is preceded by t=.%DThe time from when the request was received to the time the
headers are sent on the wire. This is a measure of the duration
of the request. The value is preceded by D=.%{FOOBAR}eThe contents of the environment
variable FOOBAR.Header directive is used with the
add, append, or set
argument, a fourth argument may be used to specify conditions
under which the action will be taken. If the environment variable specified in the
env=... argument exists (or if the environment
variable does not exist and env=!... is specified)
then the action specified by the Header directive
will take effect. Otherwise, the directive will have no effect
on the request.Header directives are processed just
before the response is sent to the network. These means that it is
possible to set and/or override most headers, except for those headers
added by the header filter.RequestHeader Directive
Description: Configure HTTP request headers Syntax: RequestHeader set|append|add|unset header
[value [env=[!]variable]]Context: server config, virtual host, directory, .htaccess Override: FileInfo Status: Extension Module: mod_headers
setappendaddappend should be
used instead.unsetadd, append and
set a value is given as the third argument. If
value contains spaces, it should be surrounded by double
quotes. For unset, no value should be given.RequestHeader directive is used with the
add, append, or set
argument, a fourth argument may be used to specify conditions
under which the action will be taken. If the environment variable specified in the
env=... argument exists (or if the environment
variable does not exist and env=!... is specified)
then the action specified by the RequestHeader directive
will take effect. Otherwise, the directive will have no effect
on the request.RequestHeader directive is processed
just before the request is run by its handler in the fixup phase.
This should allow headers generated by the browser, or by Apache
input filters to be overridden or modified.
mod/mod_include.html 100644 0 0 113711 11074462673 12212 0 ustar 0 0
Apache Module mod_imap
Description: Server-side imagemap processing Status: Base Module Identifier: imap_module Source File: mod_imap.c Summary
.map files, thereby
replacing the functionality of the imagemap CGI
program. Any directory or document type configured to use the
handler imap-file (using either
AddHandler or
SetHandler)
will be processed by this module..map as imagemap files:AddHandler imap-file mapAddType application/x-httpd-imap mapDirectives
Topics
New Features
<base> assignment through a new map
directive base.imagemap.conf file.
Imagemap File
directive value [x,y ...]
directive value "Menu text" [x,y
...]
directive value x,y ... "Menu text"
base,
default, poly, circle,
rect, or point. The value is an
absolute or relative URL, or one of the special values listed
below. The coordinates are x,y
pairs separated by whitespace. The quoted text is used as the text of
the link if a imagemap menu is generated. Lines beginning with '#' are
comments.Imagemap File Directives
base Directive<base href="value">
. The non-absolute URLs of the map-file are taken relative
to this value. The base directive overrides
ImapBase as set in a
.htaccess file or in the server configuration files.
In the absence of an ImapBase configuration
directive, base defaults to
http://server_name/.base_uri is synonymous with base.
Note that a trailing slash on the URL is significant.default Directivepoly, circle or
rect directives, and there are no
point directives. Defaults to nocontent
in the absence of an ImapDefault configuration setting, causing a status
code of 204 No Content to be returned. The client
should keep the same page displayed.poly Directivecirclerect Directivepoint Directivedefault will not be
followed if a point directive is present and
valid coordinates are given.Values
base value.base itself will not resolved according to the
current value. A statement base mailto: will
work properly, though.mapImapMenu is set to
none.menumap.refererhttp://servername/ if no Referer:
header was present.nocontent204 No Content,
telling the client to keep the same page displayed. Valid for
all but base.error500 Server Error. Valid for all
but base, but sort of silly for anything but
default.Coordinates
0,0 200,2000,0, it is as if no coordinate had been
selected.Quoted Text
"Menu Text"
<a href="http://foo.com/">Menu text</a>
<a href="http://foo.com/">http://foo.com</a>
".
Example Mapfile
#Comments are printed in a 'formatted' or 'semiformatted' menu.
#And can contain html tags. <hr>
base referer
poly map "Could I have a menu, please?" 0,0 0,10 10,10 10,0
rect .. 0,0 77,27 "the directory of the referer"
circle http://www.inetnebr.com/lincoln/feedback/ 195,0 305,27
rect another_file "in same directory as referer" 306,0 419,27
point http://www.zyzzyva.com/ 100,100
point http://www.tripod.com/ 200,200
rect mailto:nate@tripod.com 100,150 200,0 "Bugs?"
Referencing your mapfile
HTML example
<a href="/maps/imagemap1.map">
<img ismap src="/images/imagemap1.gif">
</a>
XHTML example
<a href="/maps/imagemap1.map">
<img ismap="ismap" src="/images/imagemap1.gif" />
</a>
ImapBase Directive
Description: Default base for imagemap filesSyntax: ImapBase map|referer|URLDefault: ImapBase http://servername/Context: server config, virtual host, directory, .htaccess Override: Indexes Status: Base Module: mod_imap ImapBase directive sets the default
base used in the imagemap files. Its value is
overridden by a base directive within the imagemap
file. If not present, the base defaults to
http://servername/.See also
ImapDefault Directive
Description: Default action when an imagemap is called with coordinates
that are not explicitly mapped Syntax: ImapDefault error|nocontent|map|referer|URLDefault: ImapDefault nocontentContext: server config, virtual host, directory, .htaccess Override: Indexes Status: Base Module: mod_imap ImapDefault directive sets the default
default used in the imagemap files. Its value is
overridden by a default directive within the
imagemap file. If not present, the default action
is nocontent, which means that a 204 No
Content is sent to the client. In this case, the client
should continue to display the original page.ImapMenu Directive
Description: Action if no coordinates are given when calling
an imagemap Syntax: ImapMenu none|formatted|semiformatted|unformattedContext: server config, virtual host, directory, .htaccess Override: Indexes Status: Base Module: mod_imap ImapMenu directive determines the
action taken if an imagemap file is called without valid
coordinates.
nonenone, no menu is generated,
and the default action is performed.formattedformatted menu is the simplest menu.
Comments in the imagemap file are ignored. A level one header
is printed, then an hrule, then the links each on a separate
line. The menu has a consistent, plain look close to that of
a directory listing.semiformattedsemiformatted menu, comments are
printed where they occur in the imagemap file. Blank lines
are turned into HTML breaks. No header or hrule is printed,
but otherwise the menu is the same as a
formatted menu.unformatted
mod/mod_info.html 100644 0 0 14356 11074462673 11507 0 ustar 0 0
Apache Module mod_include
Description: Server-parsed html documents (Server Side Includes) Status: Base Module Identifier: include_module Source File: mod_include.c Compatibility: Implemented as an output filter since Apache
2.0 Summary
Directives
Topics
Enabling Server-Side Includes PATH_INFO with Server Side Includes Basic Elements Include Variables Variable Substitution Flow Control ElementsSee also
Enabling Server-Side Includes
INCLUDES filter. If
documents containing server-side include directives are given
the extension .shtml, the following directives will make Apache
parse them and assign the resulting document the mime type of
text/html:
AddType text/html .shtml
AddOutputFilter INCLUDES .shtml
<Directory> section,
but this directive is also valid in .htaccess files if
AllowOverride Options
is set):
Options +Includes
server-parsed
handler also activates the
INCLUDES filter. As well, Apache will activate the INCLUDES
filter for any document with mime type
text/x-server-parsed-html or
text/x-server-parsed-html3 (and the resulting
output will have the mime type text/html).
PATH_INFO with Server Side Includes
PATH_INFO (trailing pathname information)
by default. You can use the AcceptPathInfo directive to
configure the server to accept requests with PATH_INFO.
Basic Elements
<!--#element attribute=value
attribute=value ... -->
') and backticks (`) are also
possible. Many commands only allow a single attribute-value pair.
Note that the comment terminator (-->) should be
preceded by whitespace to ensure that it isn't considered part of
an SSI token. Note that the leading <!--# is one
token and may not contain any whitespaces.
Element Description configconfigure output formats echoprint variables execexecute external programs fsizeprint size of a file flastmodprint last modification time of a file includeinclude a file printenvprint all available variables setset a value of a variable mod_include. In fact, the exec element is provided by
mod_cgi, and will only be available if this
module is loaded.The config Element
errmsgSSIErrorMsg directives.sizefmtbytes
for a count in bytes, or abbrev for a count
in Kb or Mb as appropriate, for example a size of 1024 bytes
will be printed as "1K".timefmtstrftime(3) library routine when printing
dates.The echo Element
SSIUndefinedEcho directive. Any dates printed are
subject to the currently configured timefmt.
varencodingnone, no encoding will be done. If set to
url, then URL encoding (also known as %-encoding;
this is appropriate for use within URLs in links, etc.) will be
performed. At the start of an echo element,
the default is set to entity, resulting in entity
encoding (which is appropriate in the context of a block-level
HTML element, e.g. a paragraph of text). This can be
changed by adding an encoding attribute, which will
remain in effect until the next encoding attribute
is encountered or the element ends, whichever comes first.encoding attribute must precede the
corresponding var attribute to be effective, and
only special characters as defined in the ISO-8859-1 character
encoding will be encoded. This encoding process may not have the
desired result if a different character encoding is in use.
In order to avoid cross-site scripting issues, you should
always encode user supplied data.
The exec Element
exec command executes a given shell command or
CGI script. It requires mod_cgi to be present
in the server. If Options
IncludesNOEXEC is set, this command is completely
disabled. The valid attributes are:
cgiScriptAlias
or Options
ExecCGI).PATH_INFO and query
string (QUERY_STRING) of the original request from the
client; these cannot be specified in the URL path. The
include variables will be available to the script in addition to
the standard CGI environment.Example
<!--#exec cgi="/cgi-bin/example.cgi" -->
Location: header instead of
output, then this will be translated into an HTML anchor.include virtual
element should be used in preference to exec cgi. In
particular, if you need to pass additional arguments to a CGI program,
using the query string, this cannot be done with exec
cgi, but can be done with include virtual, as
shown here:
<!--#include virtual="/cgi-bin/example.cgi?argument=value" -->
cmd/bin/sh. The include variables are available to the command, in addition
to the usual set of CGI variables.#include virtual is almost always prefered to using
either #exec cgi or #exec cmd. The former
(#include virtual) uses the standard Apache sub-request
mechanism to include files or scripts. It is much better tested and
maintained.exec directive, or otherwise include
spaces in the command. Thus, while the following will work under a
non-suexec configuration on unix, it will not produce the desired
result under Win32, or when running suexec:
<!--#exec cmd="perl /path/to/perlscript arg1 arg2" -->
The fsize Element
sizefmt format specification. Attributes:
filevirtualThe flastmod Element
timefmt format
specification. The attributes are the same as for the
fsize command.The include Element
IncludesNOEXEC set, then only documents with
a text MIME type (text/plain, text/html
etc.) will be included. Otherwise CGI scripts are invoked as normal
using the complete URL given in the command, including any query
string.
file../, nor can it be an absolute path.
Therefore, you cannot include files that are outside of the
document root, or above the current document in the directory
structure. The virtual attribute should always be
used in preference to this one.virtual
<!--#include virtual="/cgi-bin/example.cgi?argument=value" -->
include virtual should be used in preference
to exec cgi to include the output of CGI programs
into an HTML document.The printenv Element
echo element for details)
before being output. There are no attributes.Example
<!--#printenv -->
The set Element
varvalueExample
<!--#set var="category" value="help" -->
Include Variables
echo command, for
if and elif, and to any program
invoked by the document.
DATE_GMTDATE_LOCALDOCUMENT_NAMEDOCUMENT_URILAST_MODIFIEDQUERY_STRING_UNESCAPED& etc. are
preceded by backslashes).
Variable Substitution
config,
exec, flastmod, fsize,
include, echo, and set
directives, as well as the arguments to conditional operators.
You can insert a literal dollar sign into the string using backslash
quoting:
<!--#if expr="$a = \$test" -->
<!--#set var="Zed" value="${REMOTE_HOST}_${REQUEST_METHOD}" -->
Zed variable being set
to "X_Y" if REMOTE_HOST is
"X" and REQUEST_METHOD is
"Y".DOCUMENT_URI is /foo/file.html, "in bar"
if it is /bar/file.html and "in neither" otherwise:
<!--#if expr='"$DOCUMENT_URI" = "/foo/file.html"' -->
in foo
<!--#elif expr='"$DOCUMENT_URI" = "/bar/file.html"' -->
in bar
<!--#else -->
in neither
<!--#endif -->
Flow Control Elements
<!--#if expr="test_condition" -->
<!--#elif expr="test_condition" -->
<!--#else -->
<!--#endif -->
if element works like an if statement in a
programming language. The test condition is evaluated and if
the result is true, then the text until the next elif,
else or endif element is included in the
output stream.elif or else statements are be used
to put text into the output stream if the original
test_condition was false. These elements are optional.endif element ends the if element
and is required.
stringstring1 = string2
string1 != string2/string2/
then it is treated as a regular expression. Regular expressions are
implemented by the PCRE engine and
have the same syntax as those in perl
5.=), you can capture
grouped parts of the regular expression. The captured parts are
stored in the special variables $1 ..
$9.Example
<!--#if expr="$QUERY_STRING = /^sid=([a-zA-Z0-9]+)/" -->
<!--#set var="session" value="$1" -->
<!--#endif -->
string1 < string2
string1 <= string2
string1 > string2
string1 >= string2strcmp(3)). Therefore the string "100" is less than
"20".( test_condition )! test_conditiontest_condition1 &&
test_condition2test_condition1 ||
test_condition2=" and "!=" bind more tightly than
"&&" and "||". "!" binds
most tightly. Thus, the following are equivalent:
<!--#if expr="$a = test1 && $b = test2" -->
<!--#if expr="($a = test1) && ($b = test2)" -->
&& and ||
share the same priority. So if you want to bind such an operator more
tightly, you should use parentheses.'string'. Unquoted strings can't contain whitespace
(blanks and tabs) because it is used to separate tokens such as
variables. If multiple strings are found in a row, they are
concatenated using blanks. So,string1 string2 results in string1 string2
and
'string1 string2' results in string1 string2.SSIEndTag Directive
Description: String that ends an include element Syntax: SSIEndTag tagDefault: SSIEndTag "-->"Context: server config, virtual host Status: Base Module: mod_include Compatibility: Available in version 2.0.30 and later. mod_include
looks for to mark the end of an include element.Example
SSIEndTag "%>"
See also
SSIErrorMsg Directive
Description: Error message displayed when there is an SSI
error Syntax: SSIErrorMsg messageDefault: SSIErrorMsg "[an error occurred while processing this
directive]"Context: server config, virtual host, directory, .htaccess Override: All Status: Base Module: mod_include Compatibility: Available in version 2.0.30 and later. SSIErrorMsg directive changes the error
message displayed when mod_include encounters an
error. For production servers you may consider changing the default
error message to "<!-- Error -->" so that
the message is not presented to the user.<!--#config
errmsg=message --> element.Example
SSIErrorMsg "<!-- Error -->"
SSIStartTag Directive
Description: String that starts an include element Syntax: SSIStartTag tagDefault: SSIStartTag "<!--#"Context: server config, virtual host Status: Base Module: mod_include Compatibility: Available in version 2.0.30 and later. mod_include
looks for to mark an include element to process.Example
SSIStartTag "<%"
SSIEndTag "%>"
SSIEndTag, will
allow you to use SSI directives as shown in the example
below:SSI directives with alternate start and end tags
<%printenv %>
See also
SSITimeFormat Directive
Description: Configures the format in which date strings are
displayed Syntax: SSITimeFormat formatstringDefault: SSITimeFormat "%A, %d-%b-%Y %H:%M:%S %Z"Context: server config, virtual host, directory, .htaccess Override: All Status: Base Module: mod_include Compatibility: Available in version 2.0.30 and later. DATE environment variables. The
formatstring is as in strftime(3) from the
C standard library.<!--#config
timefmt=formatstring --> element.Example
SSITimeFormat "%R, %B %d, %Y"
SSIUndefinedEcho Directive
Description: String displayed when an unset variable is echoed Syntax: SSIUndefinedEcho stringDefault: SSIUndefinedEcho "(none)"Context: server config, virtual host Status: Base Module: mod_include Compatibility: Available in version 2.0.34 and later. mod_include
displays when a variable is not set and "echoed".Example
SSIUndefinedEcho "<!-- undef -->"
XBitHack Directive
Description: Parse SSI directives in files with the execute bit
set Syntax: XBitHack on|off|fullDefault: XBitHack offContext: server config, virtual host, directory, .htaccess Override: Options Status: Base Module: mod_include XBitHack directive controls the parsing
of ordinary html documents. This directive only affects files associated
with the MIME type text/html. XBitHack can take on the following values:
offontext/html file that has the user-execute bit
set will be treated as a server-parsed html document.fullon but also test the group-execute bit.
If it is set, then set the Last-modified date of the
returned file to be the last modified time of the file. If
it is not set, then no last-modified date is sent. Setting
this bit allows clients and proxies to cache the result of
the request.
Note
#include a CGI or otherwise produces different output on
each hit (or could potentially change on subsequent requests).
mod/mod_isapi.html 100644 0 0 47712 11074462673 11663 0 ustar 0 0
Apache Module mod_info
Description: Provides a comprehensive overview of the server
configuration Status: Extension Module Identifier: info_module Source File: mod_info.c Summary
mod_info, add the following to your
httpd.conf file.
<Location /server-info>
SetHandler server-info
</Location>
mod_access inside the
<Location>
directive to limit access to your server configuration
information:
<Location /server-info>
SetHandler server-info
Order deny,allow
Deny from all
Allow from yourcompany.com
</Location>
http://your.host.dom/server-info
Note that the configuration files are read by the
module at run-time, and therefore the display may
not reflect the running server's active
configuration if the files have been changed since the server
was last reloaded. Also, the configuration files must be
readable by the user as which the server is running (see the
User directive), or
else the directive settings will not be listed.
mod_info is compiled into the server, its
handler capability is available in all configuration
files, including per-directory files (e.g.,
.htaccess). This may have security-related
ramifications for your site.Directives
AddModuleInfo Directive
Description: Adds additional information to the module
information displayed by the server-info handler Syntax: AddModuleInfo module-name stringContext: server config, virtual host Status: Extension Module: mod_info Compatibility: Apache 1.3 and above
AddModuleInfo mod_auth.c 'See <a \
href="http://www.apache.org/docs/2.0/mod/mod_auth.html">\
http://www.apache.org/docs/2.0/mod/mod_auth.html</a>'
mod/mod_ldap.html 100644 0 0 57001 11074462673 11466 0 ustar 0 0
Apache Module mod_isapi
Description: ISAPI Extensions within Apache for Windows Status: Base Module Identifier: isapi_module Source File: mod_isapi.c Compatibility: Win32 only Summary
Directives
ISAPIAppendLogToErrors ISAPIAppendLogToQuery ISAPICacheFile ISAPIFakeAsync ISAPILogNotSupported ISAPIReadAheadBufferTopics
Usage
AddHandler directive to
associate ISAPI files with the isapi-handler handler, and map
it to them with their file extensions. To enable any .dll file to be
processed as an ISAPI extension, edit the httpd.conf file and add the
following line:
AddHandler isapi-handler .dll
In versions of the Apache server prior to 2.0.37, use
isapi-isa instead of isapi-handler. The new
handler name is not available prior to version 2.0.37. For compatibility,
configurations may continue using isapi-isa through all
versions of Apache prior to 2.3.0.
ISAPICacheFile c:/WebWork/Scripts/ISAPI/mytest.dll
Options ExecCGI must be set for the
directory that contains the ISAPI .dll file.mod_isapi.
Additional Notes
ISAPILogNotSupported
Off exists to quiet this noise.ISAPICacheFile directive is specified.
This is inefficient, but Apache's memory model makes this the
most effective method. Many ISAPI modules are subtly
incompatible with the Apache server, and unloading these
modules helps to ensure the stability of the server.
Programmer's Journal
mod_isapi
modules, you must limit your calls to ServerSupportFunction
to the following directives:
HSE_REQ_SEND_URL_REDIRECT_RESP
This must be a fully qualified URL (e.g.
http://server/location).HSE_REQ_SEND_URL
This cannot be a fully qualified URL, you are not allowed to
pass the protocol or a server name (e.g. simply
/location).
This redirection is handled by the server, not the
browser.
Warning
HSE_REQ_SEND_URL functions. Apache continues to treat
them as two distinct functions with different requirements
and behaviors.HSE_REQ_SEND_RESPONSE_HEADERHSE_REQ_DONE_WITH_SESSIONHSE_REQ_MAP_URL_TO_PATHHSE_APPEND_LOG_PARAMETER
\"%{isapi-parameter}n\" component in a
CustomLog
directive%q log component with the
ISAPIAppendLogToQuery
On directiveISAPIAppendLogToErrors On directive%{isapi-parameter}n component,
is always available and preferred.HSE_REQ_IS_KEEP_CONNHSE_REQ_SEND_RESPONSE_HEADER_EXfKeepConn
flag is ignored.HSE_REQ_IS_CONNECTEDFALSE to any unsupported call to
ServerSupportFunction, and sets the
GetLastError value to
ERROR_INVALID_PARAMETER.ReadClient retrieves the request body exceeding the
initial buffer (defined by ISAPIReadAheadBuffer). Based on the
ISAPIReadAheadBuffer setting (number of bytes
to buffer prior to calling the ISAPI handler) shorter requests are sent
complete to the extension when it is invoked. If the request is
longer, the ISAPI extension must use ReadClient to
retrieve the remaining request body.WriteClient is supported, but only with the
HSE_IO_SYNC flag or no option flag (value of
0). Any other WriteClient request
will be rejected with a return value of FALSE, and a
GetLastError value of
ERROR_INVALID_PARAMETER.GetServerVariable is supported, although extended server
variables do not exist (as defined by other servers.) All the
usual Apache CGI environment variables are available from
GetServerVariable, as well as the ALL_HTTP
and ALL_RAW values.mod_isapi supports additional
features introduced in later versions of the ISAPI specification,
as well as limited emulation of async I/O and the
TransmitFile semantics. Apache also supports preloading
ISAPI .dlls for performance, neither of which were not available under
Apache 1.3 mod_isapi.ISAPIAppendLogToErrors Directive
Description: Record HSE_APPEND_LOG_PARAMETER requests from
ISAPI extensions to the error logSyntax: ISAPIAppendLogToErrors on|offDefault: ISAPIAppendLogToErrors offContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_isapi HSE_APPEND_LOG_PARAMETER requests from ISAPI
extensions to the server error log.ISAPIAppendLogToQuery Directive
Description: Record HSE_APPEND_LOG_PARAMETER requests from
ISAPI extensions to the query fieldSyntax: ISAPIAppendLogToQuery on|offDefault: ISAPIAppendLogToQuery onContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_isapi HSE_APPEND_LOG_PARAMETER requests from ISAPI
extensions to the query field (appended to the CustomLog %q
component).ISAPICacheFile Directive
Description: ISAPI .dll files to be loaded at startup Syntax: ISAPICacheFile file-path [file-path]
...Context: server config, virtual host Status: Base Module: mod_isapi ServerRoot.ISAPIFakeAsync Directive
Description: Fake asynchronous support for ISAPI callbacks Syntax: ISAPIFakeAsync on|offDefault: ISAPIFakeAsync offContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_isapi ISAPILogNotSupported Directive
Description: Log unsupported feature requests from ISAPI
extensions Syntax: ISAPILogNotSupported on|offDefault: ISAPILogNotSupported offContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_isapi ISAPIReadAheadBuffer Directive
Description: Size of the Read Ahead Buffer sent to ISAPI
extensions Syntax: ISAPIReadAheadBuffer sizeDefault: ISAPIReadAheadBuffer 49152Context: server config, virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_isapi ReadClient callback; some
ISAPI extensions may not support the ReadClient function.
Refer questions to the ISAPI extension's author.
mod/mod_log_config.html 100644 0 0 63243 11074462673 12661 0 ustar 0 0
Apache Module mod_ldap
Description: LDAP connection pooling and result caching services for use
by other LDAP modules Status: Experimental Module Identifier: ldap_module Source File: util_ldap.c Compatibility: Available in version 2.0.41 and later Summary
--with-ldap
flag to the configure script when building
Apache.mod_ldap be linked
with one of the following LDAP SDKs:
OpenLDAP SDK (both 1.x and 2.x),
Novell LDAP SDK or the
iPlanet(Netscape) SDK.Directives
LDAPCacheEntries LDAPCacheTTL LDAPConnectionTimeout LDAPOpCacheEntries LDAPOpCacheTTL LDAPSharedCacheFile LDAPSharedCacheSize LDAPTrustedCA LDAPTrustedCATypeTopics
Example Configuration
mod_ldap to increase the performance of HTTP Basic
authentication provided by mod_auth_ldap.
# Enable the LDAP connection pool and shared
# memory cache. Enable the LDAP cache status
# handler. Requires that mod_ldap and mod_auth_ldap
# be loaded. Change the "yourdomain.example.com" to
# match your domain.
LDAPSharedCacheSize 200000
LDAPCacheEntries 1024
LDAPCacheTTL 600
LDAPOpCacheEntries 1024
LDAPOpCacheTTL 600
<Location /ldap-status>
SetHandler ldap-status
Order deny,allow
Deny from all
Allow from yourdomain.example.com
AuthLDAPEnabled on
AuthLDAPURL ldap://127.0.0.1/dc=example,dc=com?uid?one
AuthLDAPAuthoritative on
Require valid-user
</Location>
LDAP Connection Pool
LDAP Cache
mod_ldap uses an aggressive
caching strategy to minimize the number of times that the LDAP
server must be contacted. Caching can easily double or triple
the throughput of Apache when it is serving pages protected
with mod_auth_ldap. In addition, the load on the LDAP server
will be significantly decreased.mod_ldap supports two types of LDAP caching during
the search/bind phase with a search/bind cache and
during the compare phase with two operation
caches. Each LDAP URL that is used by the server has
its own set of these three caches.The Search/Bind Cache
mod_ldap stores the username, the DN
retrieved, the password used to bind, and the time of the bind
in the cache. Whenever a new connection is initiated with the
same username, mod_ldap compares the password
of the new connection with the password in the cache. If the
passwords match, and if the cached entry is not too old,
mod_ldap bypasses the search/bind phase.LDAPCacheEntries and LDAPCacheTTL directives.Operation Caches
mod_ldap uses two operation caches
to cache the compare operations. The first compare cache is
used to cache the results of compares done to test for LDAP
group membership. The second compare cache is used to cache
the results of comparisons done between distinguished
names.LDAPOpCacheEntries
and LDAPOpCacheTTL
directives.Monitoring the Cache
mod_ldap has a content handler that allows
administrators to monitor the cache performance. The name of
the content handler is ldap-status, so the
following directives could be used to access the
mod_ldap cache information:
<Location /server/cache-info>
SetHandler ldap-status
</Location>
http://servername/cache-info,
the administrator can get a status report of every cache that is used
by mod_ldap cache. Note that if Apache does not
support shared memory, then each httpd instance has its
own cache, so reloading the URL will result in different
information each time, depending on which httpd
instance processes the request.
Using SSL
LDAPTrustedCA and
LDAPTrustedCAType. These directives specify the certificate
file or database and the certificate type. Whenever the LDAP url
includes ldaps://, mod_ldap will establish
a secure connection to the LDAP server.
# Establish an SSL LDAP connection. Requires that
# mod_ldap and mod_auth_ldap be loaded. Change the
# "yourdomain.example.com" to match your domain.
LDAPTrustedCA /certs/certfile.der
LDAPTrustedCAType DER_FILE
<Location /ldap-status>
SetHandler ldap-status
Order deny,allow
Deny from all
Allow from yourdomain.example.com
AuthLDAPEnabled on
AuthLDAPURL ldaps://127.0.0.1/dc=example,dc=com?uid?one
AuthLDAPAuthoritative on
Require valid-user
</Location>
mod_ldap is linked against the
Netscape/iPlanet LDAP SDK, it will not talk to any SSL server
unless that server has a certificate signed by a known Certificate
Authority. As part of the configuration
mod_ldap needs to be told where it can find
a database containing the known CAs. This database is in the same
format as Netscape Communicator's cert7.db
database. The easiest way to get this file is to start up a fresh
copy of Netscape, and grab the resulting
$HOME/.netscape/cert7.db file.LDAPCacheEntries Directive
Description: Maximum number of entries in the primary LDAP cache Syntax: LDAPCacheEntries numberDefault: LDAPCacheEntries 1024Context: server config Status: Experimental Module: mod_ldap LDAPCacheTTL Directive
Description: Time that cached items remain valid Syntax: LDAPCacheTTL secondsDefault: LDAPCacheTTL 600Context: server config Status: Experimental Module: mod_ldap LDAPConnectionTimeout Directive
Description: Specifies the socket connection timeout in seconds Syntax: LDAPConnectionTimeout secondsContext: server config Status: Experimental Module: mod_ldap LDAPOpCacheEntries Directive
Description: Number of entries used to cache LDAP compare
operations Syntax: LDAPOpCacheEntries numberDefault: LDAPOpCacheEntries 1024Context: server config Status: Experimental Module: mod_ldap mod_ldap
will use to cache LDAP compare operations. The default is 1024
entries. Setting it to 0 disables operation caching.LDAPOpCacheTTL Directive
Description: Time that entries in the operation cache remain
valid Syntax: LDAPOpCacheTTL secondsDefault: LDAPOpCacheTTL 600Context: server config Status: Experimental Module: mod_ldap LDAPSharedCacheFile Directive
Description: Sets the shared memory cache file Syntax: LDAPSharedCacheFile directory-path/filenameContext: server config Status: Experimental Module: mod_ldap LDAPSharedCacheSize Directive
Description: Size in bytes of the shared-memory cache Syntax: LDAPSharedCacheSize bytesDefault: LDAPSharedCacheSize 102400Context: server config Status: Experimental Module: mod_ldap LDAPTrustedCA Directive
Description: Sets the file containing the trusted Certificate Authority certificate or database Syntax: LDAPTrustedCA directory-path/filenameContext: server config Status: Experimental Module: mod_ldap mod_ldap should use when establishing an SSL
connection to an LDAP server. If using the Netscape/iPlanet Directory
SDK, the file name should be cert7.db.LDAPTrustedCAType Directive
Description: Specifies the type of the Certificate Authority file Syntax: LDAPTrustedCAType typeContext: server config Status: Experimental Module: mod_ldap
DER_FILE - file in binary DER format
BASE64_FILE - file in Base64 format
CERT7_DB_PATH - Netscape certificate database file ")
mod/mod_log_forensic.html 100644 0 0 22525 11074462673 13222 0 ustar 0 0
Apache Module mod_log_config
Description: Logging of the requests made to the server Status: Base Module Identifier: log_config_module Source File: mod_log_config.c Summary
TransferLog to create
a log file, LogFormat
to set a custom format, and CustomLog to define a log file and format in one
step. The TransferLog and CustomLog directives can be used multiple times in each
server to cause each request to be logged to multiple files.Directives
Topics
See also
Custom Log Formats
LogFormat and CustomLog directives is a string. This string is
used to log each request to the log file. It can contain literal
characters copied into the log files and the C-style control
characters "\n" and "\t" to represent new-lines and tabs.
Literal quotes and back-slashes should be escaped with
back-slashes.%" directives in the format string, which are
replaced in the log file by the values as follows:Format String
Description %%The percent sign (Apache 2.0.44 and later) %...aRemote IP-address %...ALocal IP-address %...BSize of response in bytes, excluding HTTP headers. %...bSize of response in bytes, excluding HTTP headers. In CLF format, i.e.
a ' -' rather than a 0 when no bytes are sent.%...{Foobar}CThe contents of cookie Foobar in the request sent
to the server. %...DThe time taken to serve the request, in microseconds. %...{FOOBAR}eThe contents of the environment variable
FOOBAR %...fFilename %...hRemote host %...HThe request protocol %...{Foobar}iThe contents of Foobar: header line(s)
in the request sent to the server.%...lRemote logname (from identd, if supplied). This will return a
dash unless IdentityCheck is set
On.%...mThe request method %...{Foobar}nThe contents of note Foobar from another
module. %...{Foobar}oThe contents of Foobar: header line(s)
in the reply.%...pThe canonical port of the server serving the request %...PThe process ID of the child that serviced the request. %...{format}PThe process ID or thread id of the child that serviced the
request. Valid formats are pid and tid.
(Apache 2.0.46 and later)
%...qThe query string (prepended with a ? if a query
string exists, otherwise an empty string)%...rFirst line of request %...sStatus. For requests that got internally redirected, this is
the status of the *original* request --- %...>s
for the last.%...tTime the request was received (standard english
format) %...{format}tThe time, in the form given by format, which should be in
strftime(3) format. (potentially localized)%...TThe time taken to serve the request, in seconds. %...uRemote user (from auth; may be bogus if return status
( %s) is 401)%...UThe URL path requested, not including any query string. %...vThe canonical ServerName
of the server serving the request.%...VThe server name according to the UseCanonicalName setting.%...XConnection status when response is completed:
X =connection aborted before the response completed. + =connection may be kept alive after the response is
sent. - = connection will be closed after the response is
sent. %...c in late versions of Apache
1.3, but this conflicted with the historical ssl
%...{var}c syntax.)%...IBytes received, including request and headers, cannot be zero.
You need to enable mod_logio to use this.%...OBytes sent, including headers, cannot be zero. You need to
enable mod_logio to use this."%h %u %r %s %b"), or it can indicate conditions for
inclusion of the item (which will cause it to be replaced with "-" if
the condition is not met). The forms of condition are a list of
HTTP status codes, which may or may not be preceded by "!".
Thus, "%400,501{User-agent}i" logs User-agent: on 400
errors and 501 errors (Bad Request, Not Implemented) only;
"%!200,304,302{Referer}i" logs Referer: on all requests
which did not return some sort of normal status.% directives %s, %U, %T, %D, and
%r look at the original request while all others look
at the final request. So for example, %>s can be
used to record the final status of the request and
%<u can be used to record the original
authenticated user on a request that is internally redirected to an
unauthenticated resource.%...r, %...i and
%...o. This was mainly to comply with the requirements of
the Common Log Format. This implied that clients could insert control
characters into the log, so you had to be quite careful when dealing
with raw log files.\xhh sequences, where hh stands for
the hexadecimal representation of the raw byte. Exceptions from this
rule are " and \ which are escaped by prepending
a backslash, and all whitespace characters which are written in their
C-style notation (\n, \t etc).%b and
%B format strings do not represent the number of
bytes sent to the client, but simply the size in bytes of the HTTP
response (which will differ, for instance, if the connection is
aborted, or if SSL is used). The %O format provided
by mod_logio will log the actual number of bytes
sent over the network.
"%h %l %u %t \"%r\" %>s %b""%v %h %l %u %t \"%r\" %>s %b""%h %l %u %t \"%r\" %>s %b \"%{Referer}i\"
\"%{User-agent}i\"""%{Referer}i -> %U""%{User-agent}i"ServerName and Listen of the server serving the
request are used for %v and %p
respectively. This happens regardless of the UseCanonicalName setting
because otherwise log analysis programs would have to duplicate
the entire vhost matching algorithm in order to decide what
host really served the request.
Security Considerations
BufferedLogs Directive
Description: Buffer log entries in memory before writing to disk Syntax: BufferedLogs On|OffDefault: BufferedLogs OffContext: server config Status: Base Module: mod_log_config Compatibility: Available in versions 2.0.41 and later. BufferedLogs directive causes
mod_log_config to store several log entries in
memory and write them together to disk, rather than writing them
after each request. On some systems, this may result in more
efficient disk access and hence higher performance. It may be
set only once for the entire server; it cannot be configured
per virtual-host.This directive is experimental and should be used with
caution.
CookieLog Directive
Description: Sets filename for the logging of cookies Syntax: CookieLog filenameContext: server config, virtual host Status: Base Module: mod_log_config Compatibility: This directive is deprecated. CookieLog directive sets the
filename for logging of cookies. The filename is relative to the
ServerRoot. This directive is
included only for compatibility with mod_cookies,
and is deprecated.CustomLog Directive
Description: Sets filename and format of log file Syntax: CustomLog file|pipe
format|nickname
[env=[!]environment-variable]Context: server config, virtual host Status: Base Module: mod_log_config CustomLog directive is used to
log requests to the server. A log format is specified, and the
logging can optionally be made conditional on request
characteristics using environment variables.
ServerRoot.|", followed by the path
to a program to receive the log information on its standard
input.
Security:
httpd. This will be root if the server was
started by root; be sure that the program is secure.Note
LogFormat
directive, or it can be an explicit format string as
described in the log formats section.
# CustomLog with format nickname
LogFormat "%h %l %u %t \"%r\" %>s %b" common
CustomLog logs/access_log common
# CustomLog with explicit format string
CustomLog logs/access_log "%h %l %u %t \"%r\" %>s %b"
env=!name' clause), then the
request will be logged.mod_setenvif
and/or mod_rewrite modules. For
example, if you want to record requests for all GIF
images on your server in a separate logfile but not in your main
log, you can use:
SetEnvIf Request_URI \.gif$ gif-image
CustomLog gif-requests.log common env=gif-image
CustomLog nongif-requests.log common env=!gif-image
SetEnvIf Referer example\.com localreferer
CustomLog referer.log referer env=!localreferer
LogFormat Directive
Description: Describes a format for use in a log file Syntax: LogFormat format|nickname
[nickname]Default: LogFormat "%h %l %u %t \"%r\" %>s %b"Context: server config, virtual host Status: Base Module: mod_log_config LogFormat directive can take one of two
forms. In the first form, where only one argument is specified,
this directive sets the log format which will be used by logs
specified in subsequent TransferLog
directives. The single argument can specify an explicit
format as discussed in the custom log
formats section above. Alternatively, it can use a
nickname to refer to a log format defined in a
previous LogFormat directive as described
below.LogFormat
directive associates an explicit format with a
nickname. This nickname can then be used in
subsequent LogFormat or
CustomLog directives
rather than repeating the entire format string. A
LogFormat directive that defines a nickname
does nothing else -- that is, it only
defines the nickname, it doesn't actually apply the format and make
it the default. Therefore, it will not affect subsequent
TransferLog directives.
In addition, LogFormat cannot use one nickname
to define another nickname. Note that the nickname should not contain
percent signs (%).Example
LogFormat "%v %h %l %u %t \"%r\" %>s %b" vhost_common
TransferLog Directive
Description: Specify location of a log file Syntax: TransferLog file|pipeContext: server config, virtual host Status: Base Module: mod_log_config CustomLog
directive, with the exception that it does not allow the log format
to be specified explicitly or for conditional logging of requests.
Instead, the log format is determined by the most recently specified
LogFormat directive
which does not define a nickname. Common Log Format is used if no
other format has been specified.Example
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
TransferLog logs/access_log
mod/mod_logio.html 100644 0 0 10245 11074462673 11656 0 ustar 0 0
Apache Module mod_log_forensic
Description: Forensic Logging of the requests made to the server Status: Extension Module Identifier: log_forensic_module Source File: mod_log_forensic.c Compatibility: Available in version 2.0.50 and later Summary
CoreDumpDirectory
configuration).check_forensic script, which can be found in the
distribution's support directory, may be helpful in evaluating the
forensic log output.
This module was backported from version 2.1 which uses a more powerful
APR version in order to generate the forensic IDs. If you want to run
mod_log_forensic in version 2.0, you need to include
mod_unique_id as well.
Directives
Topics
See also
Forensic Log Format
%{forensic-id}n format string. If you're using
mod_unique_id, its generated ID will be used.|). A sample line
looks like the following (all on one line):
+yQtJf8CoAB4AAFNXBIEAAAAA|GET /manual/de/images/down.gif
HTTP/1.1|Host:localhost%3a8080|User-Agent:Mozilla/5.0 (X11;
U; Linux i686; en-US; rv%3a1.6) Gecko/20040216
Firefox/0.8|Accept:image/png, etc...
-yQtJf8CoAB4AAFNXBIEAAAAA
check_forensic script takes as its argument the name
of the logfile. It looks for those +/- ID pairs
and complains if a request was not completed.
Security Considerations
ForensicLog Directive
Description: Sets filename of the forensic log Syntax: ForensicLog filename|pipeContext: server config, virtual host Status: Extension Module: mod_log_forensic ForensicLog directive is used to
log requests to the server for forensic analysis. Each log entry
is assigned a unique ID which can be associated with the request
using the normal CustomLog
directive. mod_log_forensic takes the unique ID from
mod_unique_id, so you need to load this module as well.
(This requirement will not be necessary in version 2.1 and later, because
of a more powerful APR version.) The ID token is attached to the request
under the name forensic-id, which can be added to the
transfer log using the %{forensic-id}n format string.
ServerRoot.|", followed by the path
to a program to receive the log information on its standard
input. The program name can be specified relative to the ServerRoot directive.
Security:
httpd. This will be root if the server was
started by root; be sure that the program is secure or switches to a
less privileged user.Note
mod/mod_mem_cache.html 100644 0 0 35373 11074462673 12457 0 ustar 0 0
Apache Module mod_logio
Description: Logging of input and output bytes per request Status: Extension Module Identifier: logio_module Source File: mod_logio.c Summary
mod_log_config.Directives
Topics
See also
Custom Log Formats
%" directives in
the format string, which are replaced in the log file by the values as
follows:Format String
Description %...IBytes received, including request and headers, cannot be
zero. %...OBytes sent, including headers, cannot be zero.
"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\"
\"%{User-agent}i\" %I %O"
mod/mod_mime.html 100644 0 0 160471 11074462673 11523 0 ustar 0 0
Apache Module mod_mem_cache
Description: Content cache keyed to URIs Status: Experimental Module Identifier: mem_cache_module Source File: mod_mem_cache.c Summary
This module is experimental. Documentation is still under
development...
mod_cache. It acts as a support module for mod_cache and provides a memory based storage manager.
mod_mem_cache can be configured to operate in two
modes: caching open file descriptors or caching objects in heap storage.
mod_mem_cache is most useful when used to cache locally
generated content or to cache backend server content for mod_proxy configured for ProxyPass (aka reverse proxy).Directives
MCacheMaxObjectCount MCacheMaxObjectSize MCacheMaxStreamingBuffer MCacheMinObjectSize MCacheRemovalAlgorithm MCacheSizeSee also
MCacheMaxObjectCount Directive
Description: The maximum number of objects allowed to be placed in the
cache Syntax: MCacheMaxObjectCount valueDefault: MCacheMaxObjectCount 1009Context: server config Status: Experimental Module: mod_mem_cache MCacheMaxObjectCount directive sets the
maximum number of objects to be cached. The value is used to create the
open hash table. If a new object needs to be inserted in the cache and
the maximum number of objects has been reached, an object will be
removed to allow the new object to be cached. The object to be removed
is selected using the algorithm specified by MCacheRemovalAlgorithm.Example
MCacheMaxObjectCount 13001
MCacheMaxObjectSize Directive
Description: The maximum size (in bytes) of a document allowed in the
cache Syntax: MCacheMaxObjectSize bytesDefault: MCacheMaxObjectSize 10000Context: server config Status: Experimental Module: mod_mem_cache MCacheMaxObjectSize directive sets the
maximum allowable size, in bytes, of a document for it to be considered
cacheable.Example
MCacheMaxObjectSize 6400000
Note
MCacheMaxObjectSize must be
greater than the value specified by the MCacheMinObjectSize directive.MCacheMaxStreamingBuffer Directive
Description: Maximum amount of a streamed response to buffer in memory
before declaring the response uncacheable Syntax: MCacheMaxStreamingBuffer size_in_bytesDefault: MCacheMaxStreamingBuffer the smaller of 100000 or MCacheMaxObjectSizeContext: server config Status: Experimental Module: mod_mem_cache MCacheMaxStreamingBuffer directive
specifies the maximum number of bytes of a streamed response to
buffer before deciding that the response is too big to cache.
A streamed response is one in which the entire content is not
immediately available and in which the Content-Length
may not be known. Sources of streaming responses include proxied
responses and the output of CGI scripts. By default, a streamed
response will not be cached unless it has a
Content-Length header. The reason for this is to
avoid using a large amount of memory to buffer a partial response
that might end up being too large to fit in the cache.
The MCacheMaxStreamingBuffer directive allows
buffering of streamed responses that don't contain a
Content-Length up to the specified maximum amount of
space. If the maximum buffer space is reached, the buffered
content is discarded and the attempt to cache is abandoned.Note:
MCacheMaxStreamingBuffer
will not delay the transmission of the response to the client.
As soon as mod_mem_cache copies a block of streamed
content into a buffer, it sends the block on to the next output
filter for delivery to the client.
# Enable caching of streamed responses up to 64KB:
MCacheMaxStreamingBuffer 65536
MCacheMinObjectSize Directive
Description: The minimum size (in bytes) of a document to be allowed in the
cache Syntax: MCacheMinObjectSize bytesDefault: MCacheMinObjectSize 0Context: server config Status: Experimental Module: mod_mem_cache MCacheMinObjectSize directive sets the
minimum size in bytes of a document for it to be considered
cacheable.Example
MCacheMinObjectSize 10000
MCacheRemovalAlgorithm Directive
Description: The algorithm used to select documents for removal from the
cache Syntax: MCacheRemovalAlgorithm LRU|GDSFDefault: MCacheRemovalAlgorithm GDSFContext: server config Status: Experimental Module: mod_mem_cache MCacheRemovalAlgorithm directive specifies
the algorithm used to select documents for removal from the cache.
Two choices are available:
LRU (Least Recently Used)LRU removes the documents that have not been accessed
for the longest time.GDSF (GreadyDual-Size)GDSF assigns a priority to cached documents based
on the cost of a cache miss and the size of the document. Documents
with the lowest priority are removed first.Example
MCacheRemovalAlgorithm GDSF
MCacheRemovalAlgorithm LRU
MCacheSize Directive
Description: The maximum amount of memory used by the cache in
KBytes Syntax: MCacheSize KBytesDefault: MCacheSize 100Context: server config Status: Experimental Module: mod_mem_cache MCacheSize directive sets the maximum
amount of memory to be used by the cache, in KBytes (1024-byte units).
If a new object needs to be inserted in the cache and the size of the
object is greater than the remaining memory, objects will be removed
until the new object can be cached. The object to be removed is
selected using the algorithm specified by MCacheRemovalAlgorithm.Example
MCacheSize 700000
Note
MCacheSize value must be greater than
the value specified by the MCacheMaxObjectSize directive.
mod/mod_mime_magic.html 100644 0 0 32242 11074462673 12635 0 ustar 0 0
Apache Module mod_mime
Description: Associates the requested filename's extensions
with the file's behavior (handlers and filters)
and content (mime-type, language, character set and
encoding) Status: Base Module Identifier: mime_module Source File: mod_mime.c Summary
mod_negotiation for more information
about content negotiation.AddCharset, AddEncoding, AddLanguage and AddType are all used to map file
extensions onto the meta-information for that file. Respectively
they set the character set, content-encoding, content-language,
and MIME-type (content-type) of documents. The directive TypesConfig is used to specify a
file which also maps extensions onto MIME types. mod_mime may define the handler and filters that originate and process
content. The directives AddHandler, AddOutputFilter, and AddInputFilter control the modules
or scripts that serve the document. The MultiviewsMatch directive allows
mod_negotiation to consider these file extensions
to be included when testing Multiviews matches.mod_mime associates meta-information
with filename extensions, the core server
provides directives that are used to associate all the files in a
given container (e.g., <Location>, <Directory>, or <Files>) with particular
meta-information. These directives include ForceType, SetHandler, SetInputFilter, and SetOutputFilter. The core directives
override any filename extension mappings defined in
mod_mime.Last-Modified header.
Thus, previously cached copies may still be used by a client or
proxy, with the previous headers. If you change the
meta-information (language, content type, character set or
encoding) you may need to 'touch' affected files (updating
their last modified date) to ensure that all visitors are
receive the corrected content headers.Directives
AddCharset AddEncoding AddHandler AddInputFilter AddLanguage AddOutputFilter AddType DefaultLanguage ModMimeUsePathInfo MultiviewsMatch RemoveCharset RemoveEncoding RemoveHandler RemoveInputFilter RemoveLanguage RemoveOutputFilter RemoveType TypesConfigTopics
See also
Files with Multiple Extensions
welcome.html.fr maps onto content type
text/html and language French then the file
welcome.fr.html will map onto exactly the same information.
If more than one extension is given which maps onto the same
type of meta-information, then the one to the right will be
used, except for languages and content encodings. For example, if
.gif maps to the MIME-type image/gif and
.html maps to the MIME-type text/html, then the
file welcome.gif.html will be associated with the MIME-type
text/html.welcome.html.en.de will be delivered with
Content-Language: en, de and Content-Type:
text/html..imap
extension is mapped to the handler imap-file (from
mod_imap) and the .html extension is
mapped to the MIME-type text/html, then the file
world.imap.html will be associated with both the
imap-file handler and text/html MIME-type.
When it is processed, the imap-file handler will be used,
and so it will be treated as a mod_imap imagemap
file.
Content encoding
gzip, it can also refer to encryption, such a
pgp or to an encoding such as UUencoding, which is
designed for transmitting a binary file in an ASCII (text)
format.
.doc extension is associated with the Microsoft
Word file type, and the .zip extension is
associated with the pkzip file encoding, then the file
Resume.doc.zip would be known to be a pkzip'ed Word
document.Content-encoding header with the
resource, in order to tell the client browser about the
encoding method.Content-encoding: pkzip
Character sets and languages
mod_negotiation) to determine
which document to give to the client, when there are
alternative documents in more than one character set, language,
encoding or mime type. All filename extensions associations
created with AddCharset,
AddEncoding, AddLanguage and AddType directives
(and extensions listed in the MimeMagicFile) participate in this select process.
Filename extensions that are only associated using the AddHandler, AddInputFilter or AddOutputFilter directives may be included or excluded
from matching by using the MultiviewsMatch directive.Charset
Content-Language header, to specify the language
that the document is in, and can append additional information
onto the Content-Type header to indicate the
particular character set that should be used to correctly
render the information.
Content-Language: en, fr
Content-Type: text/plain; charset=ISO-8859-1
charset is the name of the
particular character set which should be used.AddCharset Directive
Description: Maps the given filename extensions to the specified content
charset Syntax: AddCharset charset extension
[extension] ...Context: server config, virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_mime AddCharset directive maps the given
filename extensions to the specified content charset. charset
is the MIME
charset parameter of filenames containing
extension. This mapping is added to any already in force,
overriding any mappings that already exist for the same
extension.Example
AddLanguage ja .ja
AddCharset EUC-JP .euc
AddCharset ISO-2022-JP .jis
AddCharset SHIFT_JIS .sjis
xxxx.ja.jis will be treated
as being a Japanese document whose charset is ISO-2022-JP
(as will the document xxxx.jis.ja). The
AddCharset directive is useful for both to
inform the client about the character encoding of the document so that
the document can be interpreted and displayed appropriately, and for content negotiation,
where the server returns one from several documents based on
the client's charset preference.See also
AddEncoding Directive
Description: Maps the given filename extensions to the specified encoding
type Syntax: AddEncoding MIME-enc extension
[extension] ...Context: server config, virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_mime AddEncoding directive maps the given
filename extensions to the specified encoding type. MIME-enc
is the MIME encoding to use for documents containing the
extension. This mapping is added to any already in force,
overriding any mappings that already exist for the same
extension.Example
AddEncoding x-gzip .gz
AddEncoding x-compress .Z
.gz extension
to be marked as encoded using the x-gzip encoding, and
filenames containing the .Z extension to be marked as
encoded with x-compress.x-gzip and x-compress,
however the standard dictates that they're equivalent to
gzip and compress respectively. Apache does
content encoding comparisons by ignoring any leading x-.
When responding with an encoding Apache will use whatever form
(i.e., x-foo or foo) the
client requested. If the client didn't specifically request a
particular form Apache will use the form given by the
AddEncoding directive. To make this long story
short, you should always use x-gzip and
x-compress for these two specific encodings. More
recent encodings, such as deflate should be
specified without the x-.AddHandler Directive
Description: Maps the filename extensions to the specified
handler Syntax: AddHandler handler-name extension
[extension] ...Context: server config, virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_mime .cgi, you
might use:
AddHandler cgi-script .cgi
.cgi extension will be treated as a CGI program.See also
AddInputFilter Directive
Description: Maps filename extensions to the filters that will process
client requests Syntax: AddInputFilter filter[;filter...]
extension [extension] ...Context: server config, virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_mime Compatibility: AddInputFilter is only available in Apache 2.0.26 and
later. AddInputFilter maps the filename extension
extension to the filters which
will process client requests and POST input when they are received by
the server. This is in addition to any filters defined elsewhere,
including the SetInputFilter
directive. This mapping is merged over any already in force, overriding
any mappings that already exist for the same extension.See also
AddLanguage Directive
Description: Maps the given filename extension to the specified content
language Syntax: AddLanguage MIME-lang extension
[extension] ...Context: server config, virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_mime AddLanguage directive maps the given
filename extension to the specified content language.
MIME-lang is the MIME language of filenames containing
extension. This mapping is added to any already in force,
overriding any mappings that already exist for the same
extension.Example
AddEncoding x-compress .Z
AddLanguage en .en
AddLanguage fr .fr
xxxx.en.Z will be treated as
being a compressed English document (as will the document
xxxx.Z.en). Although the content language is
reported to the client, the browser is unlikely to use this
information. The AddLanguage directive is
more useful for content
negotiation, where the server returns one from several documents
based on the client's language preference.
AddLanguage en .en
AddLanguage en-gb .en
AddLanguage en-us .en
.en would be treated as
being en-us.See also
AddOutputFilter Directive
Description: Maps filename extensions to the filters that will process
responses from the server Syntax: AddOutputFilter filter[;filter...]
extension [extension] ...Context: server config, virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_mime Compatibility: AddOutputFilter is only available in Apache 2.0.26 and
later. AddOutputFilter directive maps the
filename extension extension to the filters which will process responses
from the server before they are sent to the client. This is in
addition to any filters defined elsewhere, including SetOutputFilter and AddOutputFilterByType directive. This mapping is merged
over any already in force, overriding any mappings that already exist
for the same extension..shtml files for server-side includes and will then
compress the output using mod_deflate.
AddOutputFilter INCLUDES;DEFLATE shtml
See also
AddType Directive
Description: Maps the given filename extensions onto the specified content
type Syntax: AddType MIME-type extension
[extension] ...Context: server config, virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_mime AddType directive maps the given filename
extensions onto the specified content type. MIME-type is the
MIME type to use for filenames containing extension. This
mapping is added to any already in force, overriding any mappings that
already exist for the same extension. This directive can
be used to add mappings not listed in the MIME types file (see the
TypesConfig directive).Example
AddType image/gif .gif
It is recommended that new MIME types be added using the
AddType directive rather than changing the
TypesConfig file.
See also
DefaultLanguage Directive
Description: Sets all files in the given scope to the specified
language Syntax: DefaultLanguage MIME-langContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_mime DefaultLanguage directive tells Apache
that all files in the directive's scope (e.g., all files
covered by the current <Directory> container) that don't have an explicit language
extension (such as .fr or .de as configured
by AddLanguage) should be
considered to be in the specified MIME-lang language. This
allows entire directories to be marked as containing Dutch content, for
instance, without having to rename each file. Note that unlike using
extensions to specify languages, DefaultLanguage
can only specify a single language.DefaultLanguage directive is in force,
and a file does not have any language extensions as configured
by AddLanguage, then that file
will be considered to have no language attribute.Example
DefaultLanguage en
See also
ModMimeUsePathInfo Directive
Description: Tells mod_mime to treat path_info
components as part of the filenameSyntax: ModMimeUsePathInfo On|OffDefault: ModMimeUsePathInfo OffContext: directory Status: Base Module: mod_mime Compatibility: Available in Apache 2.0.41 and later ModMimeUsePathInfo directive is used to
combine the filename with the path_info URL component to
apply mod_mime's directives to the request. The default
value is Off - therefore, the path_info
component is ignored.Example
ModMimeUsePathInfo On
/bar/foo.shtml where
/bar is a Location and ModMimeUsePathInfo is On,
mod_mime will treat the incoming request as
/bar/foo.shtml and directives like AddOutputFilter
INCLUDES .shtml will add the INCLUDES filter to the
request. If ModMimeUsePathInfo is not set, the
INCLUDES filter will not be added.See also
MultiviewsMatch Directive
Description: The types of files that will be included when searching for
a matching file with MultiViews Syntax: MultiviewsMatch Any|NegotiatedOnly|Filters|Handlers
[Handlers|Filters]Default: MultiviewsMatch NegotiatedOnlyContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_mime Compatibility: Available in Apache 2.0.26 and later. MultiviewsMatch permits three different
behaviors for mod_negotiation's
Multiviews feature. Multiviews allows a request for a file,
e.g. index.html, to match any negotiated
extensions following the base request, e.g.
index.html.en, index.html.fr, or
index.html.gz.NegotiatedOnly option provides that every extension
following the base name must correlate to a recognized
mod_mime extension for content negotation, e.g.
Charset, Content-Type, Language, or Encoding. This is the strictest
implementation with the fewest unexpected side effects, and is the
default behavior.MultiviewsMatch directive to either
Handlers, Filters, or both option keywords.
If all other factors are equal, the smallest file will be served,
e.g. in deciding between index.html.cgi of 500
bytes and index.html.pl of 1000 bytes, the .cgi
file would win in this example. Users of .asis files
might prefer to use the Handler option, if .asis files are
associated with the asis-handler.Any extensions to match, even if
mod_mime doesn't recognize the extension. This was the
behavior in Apache 1.3, and can cause unpredicatable results, such as
serving .old or .bak files the webmaster never expected to be served.
MultiviewsMatch Handlers Filters
See also
RemoveCharset Directive
Description: Removes any character set associations for a set of file
extensions Syntax: RemoveCharset extension [extension]
...Context: virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_mime Compatibility: RemoveCharset is only available in Apache 2.0.24 and
later. RemoveCharset directive removes any
character set associations for files with the given extensions.
This allows .htaccess files in subdirectories to
undo any associations inherited from parent directories or the
server config files.Example
RemoveCharset .html .shtml
RemoveEncoding Directive
Description: Removes any content encoding associations for a set of file
extensions Syntax: RemoveEncoding extension [extension]
...Context: virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_mime RemoveEncoding directive removes any
encoding associations for files with the given extensions. This
allows .htaccess files in subdirectories to undo
any associations inherited from parent directories or the
server config files. An example of its use might be:/foo/.htaccess:
AddEncoding x-gzip .gz
AddType text/plain .asc
<Files *.gz.asc>
RemoveEncoding .gz
</Files>
foo.gz to be marked as being
encoded with the gzip method, but foo.gz.asc as an
unencoded plaintext file.Note
RemoveEncoding directives are processed
after any AddEncoding
directives, so it is possible they may undo the effects of the latter
if both occur within the same directory configuration.RemoveHandler Directive
Description: Removes any handler associations for a set of file
extensions Syntax: RemoveHandler extension [extension]
...Context: virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_mime RemoveHandler directive removes any
handler associations for files with the given extensions. This allows
.htaccess files in subdirectories to undo any
associations inherited from parent directories or the server
config files. An example of its use might be:/foo/.htaccess:
AddHandler server-parsed .html
/foo/bar/.htaccess:
RemoveHandler .html
.html files in
the /foo/bar directory to being treated as normal
files, rather than as candidates for parsing (see the mod_include module).RemoveInputFilter Directive
Description: Removes any input filter associations for a set of file
extensions Syntax: RemoveInputFilter extension [extension]
...Context: virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_mime Compatibility: RemoveInputFilter is only available in Apache 2.0.26 and
later. RemoveInputFilter directive removes any
input filter associations for files with
the given extensions.
This allows .htaccess files in subdirectories to
undo any associations inherited from parent directories or the
server config files.See also
RemoveLanguage Directive
Description: Removes any language associations for a set of file
extensions Syntax: RemoveLanguage extension [extension]
...Context: virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_mime Compatibility: RemoveLanguage is only available in Apache 2.0.24 and
later. RemoveLanguage directive removes any
language associations for files with the given extensions. This
allows .htaccess files in subdirectories to undo
any associations inherited from parent directories or the
server config files.RemoveOutputFilter Directive
Description: Removes any output filter associations for a set of file
extensions Syntax: RemoveOutputFilter extension [extension]
...Context: virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_mime Compatibility: RemoveOutputFilter is only available in Apache 2.0.26 and
later. RemoveOutputFilter directive removes any
output filter associations for files with
the given extensions.
This allows .htaccess files in subdirectories to
undo any associations inherited from parent directories or the
server config files.Example
RemoveOutputFilter shtml
See also
RemoveType Directive
Description: Removes any content type associations for a set of file
extensions Syntax: RemoveType extension [extension]
...Context: virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_mime RemoveType directive removes any MIME
type associations for files with the given extensions. This allows
.htaccess files in subdirectories to undo any
associations inherited from parent directories or the server
config files. An example of its use might be:/foo/.htaccess:
RemoveType .cgi
.cgi
files in the /foo/ directory and any beneath it,
causing the files to be treated as being of the DefaultType.Note
RemoveType directives are processed
after any AddType
directives, so it is possible they may undo the effects of the
latter if both occur within the same directory configuration.TypesConfig Directive
Description: The location of the mime.types fileSyntax: TypesConfig file-pathDefault: TypesConfig conf/mime.typesContext: server config Status: Base Module: mod_mime TypesConfig directive sets the location
of the MIME types configuration file. File-path is relative
to the ServerRoot. This file sets
the default list of mappings from filename extensions to content
types. Most administrators use the provided mime.types
file, which associates common filename extensions with IANA registered
content types. The current list is maintained at http://www.iana.org/assignments/media-types/index.html.
This simplifies the httpd.conf file by providing the
majority of media-type definitions, and may be overridden by
AddType directives as
needed. You should not edit the mime.types file, because
it may be replaced when you upgrade your server.AddType directive:
MIME-type [extension] ...
#) are ignored.
Please do not send requests to the Apache HTTP
Server Project to add any new entries in the distributed
mime.types file unless (1) they are already
registered with IANA, and (2) they use widely accepted,
non-conflicting filename extensions across platforms.
category/x-subtype requests will be automatically
rejected, as will any new two-letter extensions as they will
likely conflict later with the already crowded language and
character set namespace.
See also
mod/mod_negotiation.html 100644 0 0 40433 11074462673 13067 0 ustar 0 0
Apache Module mod_mime_magic
Description: Determines the MIME type of a file
by looking at a few bytes of its contents Status: Extension Module Identifier: mime_magic_module Source File: mod_mime_magic.c Summary
file(1) command works: it looks at the first
few bytes of the file. It is intended as a "second line of defense"
for cases that mod_mime can't resolve.file(1) command for Unix, which uses "magic
numbers" and other hints from a file's contents to figure out
what the contents are. This module is active only if the magic
file is specified by the MimeMagicFile directive.
Format of the Magic File
#). The remaining lines are parsed for
the following columns:Column Description 1
byte number to begin checking from
">" indicates a dependency upon the previous
non-">" line2
bytesingle character shortmachine-order 16-bit integer longmachine-order 32-bit integer stringarbitrary-length string datelong integer date (seconds since Unix epoch/1970) beshortbig-endian 16-bit integer belongbig-endian 32-bit integer bedatebig-endian 32-bit integer date leshortlittle-endian 16-bit integer lelonglittle-endian 32-bit integer ledatelittle-endian 32-bit integer date 3
contents of data to match 4
MIME type if matched 5
MIME encoding if matched (optional) # Sun/NeXT audio data
0 string .snd
>12 belong 1 audio/basic
>12 belong 2 audio/basic
>12 belong 3 audio/basic
>12 belong 4 audio/basic
>12 belong 5 audio/basic
>12 belong 6 audio/basic
>12 belong 7 audio/basic
>12 belong 23 audio/x-adpcm
*.doc
files containing Microsoft Word or FrameMaker documents. (These are
incompatible file formats which use the same file suffix.)# Frame
0 string \<MakerFile application/x-frame
0 string \<MIFFile application/x-frame
0 string \<MakerDictionary application/x-frame
0 string \<MakerScreenFon application/x-frame
0 string \<MML application/x-frame
0 string \<Book application/x-frame
0 string \<Maker application/x-frame
# MS-Word
0 string \376\067\0\043 application/msword
0 string \320\317\021\340\241\261 application/msword
0 string \333\245-\0\0\0 application/msword
# gzip (GNU zip, not to be confused with
# [Info-ZIP/PKWARE] zip archiver)
0 string \037\213 application/octet-stream x-gzip
Performance Issues
file(1) code to make it fit in a busy web
server. It was designed for a server where there are thousands of users
who publish their own documents. This is probably very common
on intranets. Many times, it's helpful if the server can make
more intelligent decisions about a file's contents than the
file name allows ...even if just to reduce the "why doesn't my
page work" calls when users improperly name their own files.
You have to decide if the extra work suits your
environment.
Notes
mod_mime_magic
module and are included here for compliance with contributors'
copyright restrictions that require their acknowledgment.
Copyright (c) 1996-1997 Cisco Systems, Inc.
realloc().MimeMagicFile Directive
Description: Enable MIME-type determination based on file contents
using the specified magic file Syntax: MimeMagicFile file-pathContext: server config, virtual host Status: Extension Module: mod_mime_magic MimeMagicFile directive can be used to
enable this module, the default file is distributed at
conf/magic. Non-rooted paths are relative to the
ServerRoot. Virtual hosts will use
the same file as the main server unless a more specific setting is
used, in which case the more specific setting overrides the main
server's file.Example
MimeMagicFile conf/magic
mod/mod_nw_ssl.html 100644 0 0 14164 11074462673 12056 0 ustar 0 0
Apache Module mod_negotiation
Description: Provides for content negotiation Status: Base Module Identifier: negotiation_module Source File: mod_negotiation.c Summary
type-map) which explicitly lists the files
containing the variants.MultiViews
Options), where the server does
an implicit filename pattern match, and choose from amongst the
results.Directives
Topics
See also
Type maps
Content-Encoding:AddEncoding directive.
This normally includes the encodings x-compress
for compress'd files, and x-gzip for gzip'd
files. The x- prefix is ignored for encoding
comparisons.Content-Language:en,
meaning English. If the variant contains more than one
language, they are separated by a comma.Content-Length:Content-Type:name=value. Common parameters include:
leveltext/html this defaults to 2, otherwise
0.qsqs values are therefore specific to a given
resource.Example
Content-Type: image/jpeg; qs=0.8
URI:Body:Example:
Body:----xyz----
<html>
<body>
<p>Content of the page.</p>
</body>
</html>
----xyz----
MultiViews
MultiViews
Options. If the server receives a
request for /some/dir/foo and
/some/dir/foo does not exist, then the
server reads the directory looking for all files named
foo.*, and effectively fakes up a type map which
names all those files, assigning them the same media types and
content-encodings it would have if the client had asked for one
of them by name. It then chooses the best match to the client's
requirements, and returns that document.MultiViewsMatch
directive configures whether Apache will consider files
that do not have content negotiation meta-information assigned
to them when choosing files.CacheNegotiatedDocs Directive
Description: Allows content-negotiated documents to be
cached by proxy servers Syntax: CacheNegotiatedDocs On|OffDefault: CacheNegotiatedDocs OffContext: server config, virtual host Status: Base Module: mod_negotiation Compatibility: The syntax changed in version 2.0. CacheNegotiatedDocs did not take an
argument; it was turned on by the presence of the directive by
itself.ForceLanguagePriority Directive
Description: Action to take if a single acceptable document is not
found Syntax: ForceLanguagePriority None|Prefer|Fallback [Prefer|Fallback]Default: ForceLanguagePriority PreferContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_negotiation Compatibility: Available in version 2.0.30 and later ForceLanguagePriority directive uses
the given LanguagePriority to satisfy
negotation where the server could otherwise not return a single
matching document.ForceLanguagePriority Prefer uses
LanguagePriority to serve a one valid result, rather
than returning an HTTP result 300 (MULTIPLE CHOICES) when there
are several equally valid choices. If the directives below were
given, and the user's Accept-Language header assigned
en and de each as quality .500
(equally acceptable) then the first matching variant, en,
will be served.
LanguagePriority en fr de
ForceLanguagePriority Prefer
ForceLanguagePriority Fallback uses
LanguagePriority to
serve a valid result, rather than returning an HTTP result 406
(NOT ACCEPTABLE). If the directives below were given, and the user's
Accept-Language only permitted an es
language response, but such a variant isn't found, then the first
variant from the LanguagePriority list below will be served.
LanguagePriority en fr de
ForceLanguagePriority Fallback
Prefer and Fallback, may be
specified, so either the first matching variant from LanguagePriority will be served if
more than one variant is acceptable, or first available document will
be served if none of the variants matched the client's acceptable list
of languages.See also
LanguagePriority Directive
Description: The precendence of language variants for cases where
the client does not express a preference Syntax: LanguagePriority MIME-lang [MIME-lang]
...Context: server config, virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_negotiation LanguagePriority sets the precedence
of language variants for the case where the client does not
express a preference, when handling a MultiViews request. The list
of MIME-lang are in order of decreasing preference.Example:
LanguagePriority en fr de
foo.html, where
foo.html.fr and foo.html.de both
existed, but the browser did not express a language preference,
then foo.html.fr would be returned.ForceLanguagePriority directive
is not None. In general, the client determines the
language preference, not the server.See also
mod/mod_proxy.html 100644 0 0 165423 11074462673 11757 0 ustar 0 0
Apache Module mod_nw_ssl
Description: Enable SSL encryption for NetWare Status: Base Module Identifier: nwssl_module Source File: mod_nw_ssl.c Compatibility: NetWare only Summary
Directives
NWSSLTrustedCerts Directive
Description: List of additional client certificates Syntax: NWSSLTrustedCerts filename [filename] ...Context: server config Status: Base Module: mod_nw_ssl .der file.NWSSLUpgradeable Directive
Description: Allows a connection to be upgraded to an SSL connection upon request Syntax: NWSSLUpgradeable [IP-address:]portnumberContext: server config Status: Base Module: mod_nw_ssl Listen
directive.SecureListen Directive
Description: Enables SSL encryption for the specified port Syntax: SecureListen [IP-address:]portnumber
Certificate-Name [MUTUAL]Context: server config Status: Base Module: mod_nw_ssl
mod/mod_proxy_connect.html 100644 0 0 6755 11074462673 13432 0 ustar 0 0
Apache Module mod_proxy
Description: HTTP/1.1 proxy/gateway server Status: Extension Module Identifier: proxy_module Source File: mod_proxy.c Summary
Warning
ProxyRequests until you have secured your server. Open proxy servers are dangerous both to your
network and to the Internet at large.FTP, CONNECT (for SSL),
HTTP/0.9, HTTP/1.0, and HTTP/1.1.
The module can be configured to connect to other proxy modules for these
and other protocols.mod_proxy:
mod_proxy_http, mod_proxy_ftp
and mod_proxy_connect. Thus, if you want to use
one or more of the particular proxy functions, load
mod_proxy and the appropriate module(s)
into the server (either statically at compile-time or dynamically
via the LoadModule
directive).mod_cache and related
modules. The ability to contact remote servers using the SSL/TLS
protocol is provided by the SSLProxy* directives of
mod_ssl. These additional modules will need
to be loaded and configured to take advantage of these features.Directives
AllowCONNECT NoProxy <Proxy> ProxyBadHeader ProxyBlock ProxyDomain ProxyErrorOverride ProxyFtpDirCharset ProxyIOBufferSize <ProxyMatch> ProxyMaxForwards ProxyPass ProxyPassReverse ProxyPreserveHost ProxyReceiveBufferSize ProxyRemote ProxyRemoteMatch ProxyRequests ProxyTimeout ProxyViaTopics
Forward and Reverse Proxies Basic Examples Controlling access to your proxy FTP Proxy Slow Startup Intranet Proxy Protocol AdjustmentsSee also
Forward and Reverse Proxies
mod_cache) to reduce network usage.ProxyRequests directive. Because
forward proxys allow clients to access arbitrary sites through
your server and to hide their true origin, it is essential that
you secure your server so that only
authorized clients can access the proxy before activating a
forward proxy.ProxyPass directive or the
[P] flag to the RewriteRule directive. It is
not necessary to turn ProxyRequests on in order to
configure a reverse proxy.
Basic Examples
mod_cache.Forward Proxy
ProxyRequests On
ProxyVia On
<Proxy *>
Order deny,allow
Deny from all
Allow from internal.example.com
</Proxy>
Reverse Proxy
ProxyRequests Off
<Proxy *>
Order deny,allow
Allow from all
</Proxy>
ProxyPass /foo http://foo.example.com/bar
ProxyPassReverse /foo http://foo.example.com/bar
Controlling access to your proxy
<Proxy> control block as in
the following example:
<Proxy *>
Order Deny,Allow
Deny from all
Allow from 192.168.0
</Proxy>
mod_access.ProxyRequests directive).
Otherwise, your server can be used by any client to access
arbitrary hosts while hiding his or her true identity. This is
dangerous both for your network and for the Internet at large.
When using a reverse proxy (using the ProxyPass directive with
ProxyRequests Off), access control is less
critical because clients can only contact the hosts that you
have specifically configured.
FTP Proxy
Why doesn't file type xxx
download via FTP?
application/octet-stream in your proxy's mime.types
configuration file. A useful line can beapplication/octet-stream bin dms lha lzh exe class tgz taz
How can I force an FTP ASCII download of
File xxx?
ASCII transfer method (while the default transfer is in
binary mode), you can override mod_proxy's
default by suffixing the request with ;type=a to force an
ASCII transfer. (FTP Directory listings are always executed in ASCII mode,
however.)How can I access FTP files outside
of my home directory?
/%2f to the path of your request, you can make
such a proxy change the FTP starting directory to / (instead
of the home directory). For example, to retrieve the file
/etc/motd, you would use the URL:
ftp://user@host/%2f/etc/motd
How can I hide the FTP cleartext password
in my browser's URL line?
user: anonymous
password: apache_proxy@
ftp://username@host/myfile
401 (Authorization
required) response, which causes the Browser to pop up the
username/password dialog. Upon entering the password, the connection
attempt is retried, and if successful, the requested resource is
presented. The advantage of this procedure is that your browser does not
display the password in cleartext (which it would if you had used
ftp://username:password@host/myfile
Note
Slow Startup
ProxyBlock directive, hostnames' IP addresses are looked up
and cached during startup for later match test. This may take a few
seconds (or more) depending on the speed with which the hostname lookups
occur.
Intranet Proxy
ProxyRemote directive
to forward the respective scheme to the firewall proxy).
However, when it has to
access resources within the intranet, it can bypass the firewall when
accessing hosts. The NoProxy
directive is useful for specifying which hosts belong to the intranet and
should be accessed directly.http://somehost.example.com/. Some commercial proxy servers
let them get away with this and simply serve the request, implying a
configured local domain. When the ProxyDomain directive is used and the server is configured for proxy service, Apache can return
a redirect response and send the client to the correct, fully qualified,
server address. This is the preferred method since the user's bookmark
files will then contain fully qualified hosts.
Protocol Adjustments
SetEnv directive.force-proxy-request-1.0 and
proxy-nokeepalive notes.
<Location /buggyappserver/>
ProxyPass http://buggyappserver:7001/foo/
SetEnv force-proxy-request-1.0 1
SetEnv proxy-nokeepalive 1
</Location>
AllowCONNECT Directive
Description: Ports that are allowed to CONNECT through the
proxySyntax: AllowCONNECT port [port] ...Default: AllowCONNECT 443 563Context: server config, virtual host Status: Extension Module: mod_proxy AllowCONNECT directive specifies a list
of port numbers to which the proxy CONNECT method may
connect. Today's browsers use this method when a https
connection is requested and proxy tunneling over HTTP is in effect.443) and the
default snews port (563) are enabled. Use the
AllowCONNECT directive to override this default and
allow connections to the listed ports only.mod_proxy_connect present
in the server in order to get the support for the CONNECT at
all.NoProxy Directive
Description: Hosts, domains, or networks that will be connected to
directly Syntax: NoProxy host [host] ...Context: server config, virtual host Status: Extension Module: mod_proxy NoProxy directive specifies a
list of subnets, IP addresses, hosts and/or domains, separated by
spaces. A request to a host which matches one or more of these is
always served directly, without forwarding to the configured
ProxyRemote proxy server(s).Example
ProxyRemote * http://firewall.mycompany.com:81
NoProxy .mycompany.com 192.168.112.0/21
NoProxy
directive are one of the following type list:
Examples
.com .apache.org.
Note
.MyDomain.com and
.mydomain.com. (note the trailing period) are considered
equal. Since a domain comparison does not involve a DNS lookup, it is much
more efficient than subnet comparison.
192.168 or 192.168.0.0255.255.0.0)192.168.112.0/21192.168.112.0/21 with a netmask of 21
valid bits (also used in the form 255.255.248.0)Example
192.168.123.7
Note
Examples
prep.ai.mit.edu
www.apache.org
Note
WWW.MyDomain.com
and www.mydomain.com. (note the trailing period) are
considered equal.See also
<Proxy> Directive
Description: Container for directives applied to proxied resources Syntax: <Proxy wildcard-url> ...</Proxy>Context: server config, virtual host Status: Extension Module: mod_proxy <Proxy>
sections apply only to matching proxied content. Shell-style wildcards are
allowed.yournetwork.example.com to access content via your proxy
server:
<Proxy *>
Order Deny,Allow
Deny from all
Allow from yournetwork.example.com
</Proxy>
foo
directory of example.com through the INCLUDES
filter when they are sent through the proxy server:
<Proxy http://example.com/foo/*>
SetOutputFilter INCLUDES
</Proxy>
ProxyBadHeader Directive
Description: Determines how to handle bad header lines in a
response Syntax: ProxyBadHeader IsError|Ignore|StartBodyDefault: ProxyBadHeader IsErrorContext: server config, virtual host Status: Extension Module: mod_proxy Compatibility: Available in Apache 2.0.44 and later ProxyBadHeader directive determines the
behaviour of mod_proxy if it receives syntactically invalid
header lines (i.e. containing no colon). The following arguments
are possible:
IsErrorIgnoreStartBodyProxyBlock Directive
Description: Words, hosts, or domains that are banned from being
proxied Syntax: ProxyBlock *|word|host|domain
[word|host|domain] ...Context: server config, virtual host Status: Extension Module: mod_proxy ProxyBlock directive specifies a list of
words, hosts and/or domains, separated by spaces. HTTP, HTTPS, and
FTP document requests to sites whose names contain matched words,
hosts or domains are blocked by the proxy server. The proxy
module will also attempt to determine IP addresses of list items which
may be hostnames during startup, and cache them for match test as
well. That may slow down the startup time of the server.Example
ProxyBlock joes-garage.com some-host.co.uk rocky.wotsamattau.edu
rocky.wotsamattau.edu would also be matched if referenced by
IP address.wotsamattau would also be sufficient to match
wotsamattau.edu.
ProxyBlock *
ProxyDomain Directive
Description: Default domain name for proxied requests Syntax: ProxyDomain DomainContext: server config, virtual host Status: Extension Module: mod_proxy ProxyDomain directive specifies
the default domain which the apache proxy server will belong to. If a
request to a host without a domain name is encountered, a redirection
response to the same host with the configured Domain appended
will be generated.Example
ProxyRemote * http://firewall.mycompany.com:81
NoProxy .mycompany.com 192.168.112.0/21
ProxyDomain .mycompany.com
ProxyErrorOverride Directive
Description: Override error pages for proxied content Syntax: ProxyErrorOverride On|OffDefault: ProxyErrorOverride OffContext: server config, virtual host Status: Extension Module: mod_proxy Compatibility: Available in version 2.0 and later ProxyFtpDirCharset Directive
Description: Define the character set for proxied FTP listings Syntax: ProxyFtpDirCharset character setDefault: ProxyFtpDirCharset ISO-8859-1Context: server config, virtual host, directory Status: Extension Module: mod_proxy Compatibility: Available in Apache 2.0.62 and later ProxyFtpDirCharset directive defines the
character set to be set for FTP directory listings in HTML generated by
mod_proxy_ftp.ProxyIOBufferSize Directive
Description: Determine size of internal data throughput buffer Syntax: ProxyIOBufferSize bytesDefault: ProxyIOBufferSize 8192Context: server config, virtual host Status: Extension Module: mod_proxy ProxyIOBufferSize directive adjusts the size
of the internal buffer, which is used as a scratchpad for the data between
input and output. The size must be less or equal 8192.<ProxyMatch> Directive
Description: Container for directives applied to regular-expression-matched
proxied resources Syntax: <ProxyMatch regex> ...</ProxyMatch>Context: server config, virtual host Status: Extension Module: mod_proxy <ProxyMatch> directive is
identical to the <Proxy> directive, except it matches URLs
using regular expressions.ProxyMaxForwards Directive
Description: Maximium number of proxies that a request can be forwarded
through Syntax: ProxyMaxForwards numberDefault: ProxyMaxForwards 10Context: server config, virtual host Status: Extension Module: mod_proxy Compatibility: Available in Apache 2.0 and later ProxyMaxForwards directive specifies the
maximum number of proxies through which a request may pass, if there's no
Max-Forwards header supplied with the request. This is
set to prevent infinite proxy loops, or a DoS attack.Example
ProxyMaxForwards 15
ProxyPass Directive
Description: Maps remote servers into the local server URL-space Syntax: ProxyPass [path] !|urlContext: server config, virtual host, directory Status: Extension Module: mod_proxy http://example.com/;
then
ProxyPass /mirror/foo/ http://backend.example.com/
http://example.com/mirror/foo/bar to be internally converted
into a proxy request to http://backend.example.com/bar.! directive is useful in situations where you don't want
to reverse-proxy a subdirectory, e.g.
ProxyPass /mirror/foo/i !
ProxyPass /mirror/foo http://backend.example.com
/mirror/foo to
backend.example.com except requests made to
/mirror/foo/i.Note
<Location> section, the first argument is omitted and the local
directory is obtained from the <Location>.The
ProxyRequests directive should
usually be set off when using
ProxyPass.RewriteRule directive with the
[P] flag.ProxyPassReverse Directive
Description: Adjusts the URL in HTTP response headers sent from a reverse
proxied server Syntax: ProxyPassReverse [path] urlContext: server config, virtual host, directory Status: Extension Module: mod_proxy Location,
Content-Location and URI headers on HTTP redirect
responses. This is essential when Apache is used as a reverse proxy to avoid
by-passing the reverse proxy because of HTTP redirects on the backend
servers which stay behind the reverse proxy.ProxyPass directive.http://example.com/; then
ProxyPass /mirror/foo/ http://backend.example.com/
ProxyPassReverse /mirror/foo/ http://backend.example.com/
http://example.com/mirror/foo/bar to be internally converted
into a proxy request to http://backend.example.com/bar
(the functionality ProxyPass provides here). It also takes care
of redirects the server backend.example.com sends: when
http://backend.example.com/bar is redirected by him to
http://backend.example.com/quux Apache adjusts this to
http://example.com/mirror/foo/quux before forwarding the HTTP
redirect response to the client. Note that the hostname used for
constructing the URL is chosen in respect to the setting of the UseCanonicalName directive.ProxyPassReverse directive can
also be used in conjunction with the proxy pass-through feature
(RewriteRule ... [P]) from mod_rewrite
because its doesn't depend on a corresponding ProxyPass directive.<Location> section, the first argument is omitted and the local
directory is obtained from the <Location>.ProxyPreserveHost Directive
Description: Use incoming Host HTTP request header for proxy
request Syntax: ProxyPreserveHost On|OffDefault: ProxyPreserveHost OffContext: server config, virtual host Status: Extension Module: mod_proxy Compatibility: Available in Apache 2.0.31 and later. Off. It is mostly
useful in special configurations like proxied mass name-based virtual
hosting, where the original Host header needs to be evaluated by the
backend server.ProxyReceiveBufferSize Directive
Description: Network buffer size for proxied HTTP and FTP
connections Syntax: ProxyReceiveBufferSize bytesDefault: ProxyReceiveBufferSize 0Context: server config, virtual host Status: Extension Module: mod_proxy ProxyReceiveBufferSize directive specifies an
explicit (TCP/IP) network buffer size for proxied HTTP and FTP connections,
for increased throughput. It has to be greater than 512 or set
to 0 to indicate that the system's default buffer size should
be used.Example
ProxyReceiveBufferSize 2048
ProxyRemote Directive
Description: Remote proxy used to handle certain requests Syntax: ProxyRemote match remote-serverContext: server config, virtual host Status: Extension Module: mod_proxy * to indicate
the server should be contacted for all requests. remote-server is
a partial URL for the remote server. Syntax:
remote-server =
scheme://hostname[:port]
http is supported by
this module.Example
ProxyRemote http://goodguys.com/ http://mirrorguys.com:8000
ProxyRemote * http://cleversite.com
ProxyRemote ftp http://ftpproxy.mydomain.com:8080
ProxyRemoteMatch Directive
Description: Remote proxy used to handle requests matched by regular
expressions Syntax: ProxyRemoteMatch regex remote-serverContext: server config, virtual host Status: Extension Module: mod_proxy ProxyRemoteMatch is identical to the
ProxyRemote directive, except the
first argument is a regular expression match against the requested URL.ProxyRequests Directive
Description: Enables forward (standard) proxy requests Syntax: ProxyRequests On|OffDefault: ProxyRequests OffContext: server config, virtual host Status: Extension Module: mod_proxy Off does not disable use of
the ProxyPass directive.)Off.mod_proxy_http or mod_proxy_ftp
(or both) present in the server.Warning
ProxyRequests until you have secured your server. Open proxy servers are dangerous
both to your network and to the Internet at large.ProxyTimeout Directive
Description: Network timeout for proxied requests Syntax: ProxyTimeout secondsDefault: ProxyTimeout 300Context: server config, virtual host Status: Extension Module: mod_proxy Compatibility: Available in Apache 2.0.31 and later ProxyVia Directive
Description: Information provided in the Via HTTP response
header for proxied requestsSyntax: ProxyVia On|Off|Full|BlockDefault: ProxyVia OffContext: server config, virtual host Status: Extension Module: mod_proxy Via: HTTP
header by the proxy. Its intended use is to control the flow of of
proxy requests along a chain of proxy servers. See RFC 2616 (HTTP/1.1), section
14.45 for an explanation of Via: header lines.
Off, which is the default, no special processing
is performed. If a request or reply contains a Via: header,
it is passed through unchanged.On, each request and reply will get a
Via: header line added for the current host.Full, each generated Via: header
line will additionally have the Apache server version shown as a
Via: comment field.Block, every proxy request will have all its
Via: header lines removed. No new Via: header will
be generated.
mod/mod_proxy_ftp.html 100644 0 0 6354 11074462673 12565 0 ustar 0 0
Apache Module mod_proxy_connect
Description: mod_proxy extension for
CONNECT request handlingStatus: Extension Module Identifier: proxy_connect_module Source File: proxy_connect.c Summary
mod_proxy. It provides support for the CONNECT
HTTP method. This method is mainly used to tunnel SSL requests
through proxy servers.CONNECT
requests, mod_proxy and
mod_proxy_connect have to be present in the server.Warning
mod/mod_proxy_http.html 100644 0 0 7320 11074462673 12745 0 ustar 0 0
Apache Module mod_proxy_ftp
Description: FTP support module for
mod_proxyStatus: Extension Module Identifier: proxy_ftp_module Source File: proxy_ftp.c Summary
mod_proxy. It provides support for the proxying
FTP sites.mod_proxy and mod_proxy_ftp
have to be present in the server.Warning
mod/mod_rewrite.html 100644 0 0 234567 11074462673 12265 0 ustar 0 0
Apache Module mod_proxy_http
Description: HTTP support module for
mod_proxyStatus: Extension Module Identifier: proxy_http_module Source File: proxy_http.c Summary
mod_proxy. It provides the features used for
proxying HTTP requests. mod_proxy_http
supports HTTP/0.9, HTTP/1.0 and HTTP/1.1. It does not
provide any caching abilities. If you want to set up a caching
proxy, you might want to use the additional service of the
mod_cache module.mod_proxy and mod_proxy_http
have to be present in the server.Warning
mod/mod_setenvif.html 100644 0 0 34574 11074462673 12403 0 ustar 0 0
Apache Module mod_rewrite
Description: Provides a rule-based rewriting engine to rewrite requested
URLs on the fly Status: Extension Module Identifier: rewrite_module Source File: mod_rewrite.c Compatibility: Available in Apache 1.3 and later Summary
httpd.conf) and per-directory context
(.htaccess) and can generate query-string
parts on result. The rewritten result can lead to internal
sub-processing, external request redirection or even to an
internal proxy throughput.Directives
RewriteBase RewriteCond RewriteEngine RewriteLock RewriteLog RewriteLogLevel RewriteMap RewriteOptions RewriteRuleTopics
API Phases
mod_rewrite uses two of
these hooks: the URL-to-filename translation hook
(used after the HTTP request has been read, but before any
authorization starts) and the Fixup hook (triggered
after the authorization phases, and after the per-directory
config files (.htaccess) have been read, but
before the content handler is activated).
Ruleset Processing
RewriteRule directives, with or without
RewriteConds), rule by rule.
When a particular rule is matched, mod_rewrite
also checks the corresponding conditions (RewriteCond
directives). For historical reasons the conditions are given
first, making the control flow a little bit long-winded. See
Figure 1 for more details.![[Needs graphics capability to display]](../images/mod_rewrite_fig1.gif)
Figure 1:The control flow of the rewrite engine through a
rewrite ruleset
mod_rewrite immediately stops processing that rule,
and goes on to the next rule. If the Pattern matches,
mod_rewrite checks for rule conditions.
If none are present, the URL will be replaced with a new string,
constructed from the Substitution string, and mod_rewrite goes on to the next rule.RewriteConds exist, an
inner loop is started, processing them in the order that they are
listed. Conditions are not matched against the current URL directly.
A TestString is constructed by expanding variables,
back-references, map lookups, etc., against which the
CondPattern is matched. If the pattern fails to match one
of the conditions, the complete set of rule and associated conditions
fails. If the pattern matches a given condition, then matching continues
to the next condition, until no more conditions are
available. If all conditions match, processing is continued
with the substitution of the Substitution string for the URL.
Regex Back-Reference Availability
$N and
%N (see below), for creating
the Substitution and TestString strings.
Figure 2 attempts to show how the back-references are
transferred through the process for later expansion.![[Needs graphics capability to display]](../images/mod_rewrite_fig2.gif)
Figure 2: The back-reference flow through a rule.
Quoting Special Characters
\$'; this keeps mod_rewrite from trying
to treat it as a backreference.
Environment Variables
SCRIPT_URL
and SCRIPT_URI. These contain the
logical Web-view to the current resource, while the
standard CGI/SSI variables SCRIPT_NAME and
SCRIPT_FILENAME contain the physical
System-view. Example
SCRIPT_NAME=/sw/lib/w3s/tree/global/u/rse/.www/index.html
SCRIPT_FILENAME=/u/rse/.www/index.html
SCRIPT_URL=/u/rse/
SCRIPT_URI=http://en1.engelschall.com/u/rse/
Practical Solutions
RewriteBase Directive
Description: Sets the base URL for per-directory rewrites Syntax: RewriteBase URL-pathDefault: See usage for information.Context: directory, .htaccess Override: FileInfo Status: Extension Module: mod_rewrite RewriteBase directive explicitly
sets the base URL for per-directory rewrites. As you will see
below, RewriteRule
can be used in per-directory config files
(.htaccess). In such a case, it will act locally,
stripping the local directory prefix before processing, and applying
rewrite rules only to the remainder. When processing is complete, the
prefix is automatically added back to the
path. The default setting is; RewriteBase physical-directory-pathRewriteBase directive to specify the
correct URL-prefix. If your webserver's URLs are not directly
related to physical file paths, you will need to use
RewriteBase in every .htaccess
file where you want to use RewriteRule directives.
#
# /abc/def/.htaccess -- per-dir config file for directory /abc/def
# Remember: /abc/def is the physical path of /xyz, i.e., the server
# has a 'Alias /xyz /abc/def' directive e.g.
#
RewriteEngine On
# let the server know that we were reached via /xyz and not
# via the physical path prefix /abc/def
RewriteBase /xyz
# now the rewriting rules
RewriteRule ^oldstuff\.html$ newstuff.html
/xyz/oldstuff.html gets correctly rewritten to
the physical file /abc/def/newstuff.html.For Apache Hackers
Request:
/xyz/oldstuff.html
Internal Processing:
/xyz/oldstuff.html -> /abc/def/oldstuff.html (per-server Alias)
/abc/def/oldstuff.html -> /abc/def/newstuff.html (per-dir RewriteRule)
/abc/def/newstuff.html -> /xyz/newstuff.html (per-dir RewriteBase)
/xyz/newstuff.html -> /abc/def/newstuff.html (per-server Alias)
Result:
/abc/def/newstuff.html
RewriteCond Directive
Description: Defines a condition under which rewriting will take place
Syntax: RewriteCond
TestString CondPatternContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Extension Module: mod_rewrite RewriteCond directive defines a
rule condition. One or more RewriteCond
can precede a RewriteRule
directive. The following rule is then only used if both
the current state of the URI matches its pattern, and if these conditions are met.
$N
(0 <= N <= 9), which provide access to the grouped
parts (in parentheses) of the pattern, from the
RewriteRule which is subject to the current
set of RewriteCond conditions..
%N
(1 <= N <= 9), which provide access to the grouped
parts (again, in parentheses) of the pattern, from the last matched
RewriteCond in the current set
of conditions.
${mapname:key|default}.
See the documentation for
RewriteMap for more details.
%{ NAME_OF_VARIABLE
}
where NAME_OF_VARIABLE can be a string taken
from the following list:
HTTP headers: connection & request:
HTTP_USER_AGENT
HTTP_REFERER
HTTP_COOKIE
HTTP_FORWARDED
HTTP_HOST
HTTP_PROXY_CONNECTION
HTTP_ACCEPT
REMOTE_ADDR
REMOTE_HOST
REMOTE_PORT
REMOTE_USER
REMOTE_IDENT
REQUEST_METHOD
SCRIPT_FILENAME
PATH_INFO
QUERY_STRING
AUTH_TYPE
server internals: system stuff: specials:
DOCUMENT_ROOT
SERVER_ADMIN
SERVER_NAME
SERVER_ADDR
SERVER_PORT
SERVER_PROTOCOL
SERVER_SOFTWARE
TIME_YEAR
TIME_MON
TIME_DAY
TIME_HOUR
TIME_MIN
TIME_SEC
TIME_WDAY
TIME
API_VERSION
THE_REQUEST
REQUEST_URI
REQUEST_FILENAME
IS_SUBREQ
HTTPS
struct tm fields of the Unix system.
Most are documented elsewhere in the Manual or in
the CGI specification. Those that are special to
mod_rewrite include those below.
IS_SUBREQAPI_VERSIONTHE_REQUESTGET
/index.html HTTP/1.1"). This does not
include any additional headers sent by the
browser.REQUEST_URIREQUEST_FILENAMEHTTPSmod_ssl is loaded).
filename field of the internal
request_rec structure of the Apache server.
The first name is the commonly known CGI variable name
while the second is the appropriate counterpart of
REQUEST_URI (which contains the value of the
uri field of request_rec).%{ENV:variable}, where variable can be
any environment variable, is also available.
This is looked-up via internal
Apache structures and (if not found there) via
getenv() from the Apache server process.%{SSL:variable}, where variable is the
name of an SSL environment
variable, can be used whether or not
mod_ssl is loaded, but will always expand to
the empty string if it is not. Example:
%{SSL:SSL_CIPHER_USEKEYSIZE} may expand to
128.%{HTTP:header}, where header can be
any HTTP MIME-header name, can always be used to obtain the
value of a header sent in the HTTP request.
Example: %{HTTP:Proxy-Connection} is
the value of the HTTP header
``Proxy-Connection:''.%{LA-U:variable} can be used for look-aheads which perform
an internal (URL-based) sub-request to determine the final
value of variable. This can be used to access
variable for rewriting which is not available at the current
stage, but will be set in a later phase.
REMOTE_USER variable from within the
per-server context (httpd.conf file) you must
use %{LA-U:REMOTE_USER} - this
variable is set by the authorization phases, which come
after the URL translation phase (during which mod_rewrite
operates)..htaccess file) via
the Fixup phase of the API and because the authorization
phases come before this phase, you just can use
%{REMOTE_USER} in that context.%{LA-F:variable} can be used to perform an internal
(filename-based) sub-request, to determine the final value
of variable. Most of the time, this is the same as
LA-U above.
!' character (exclamation mark) to specify a
non-matching pattern.
Treats the CondPattern as a plain string and
compares it lexicographically to TestString. True if
TestString lexicographically precedes
CondPattern.
Treats the CondPattern as a plain string and
compares it lexicographically to TestString. True if
TestString lexicographically follows
CondPattern.
Treats the CondPattern as a plain string and
compares it lexicographically to TestString. True if
TestString is lexicographically equal to
CondPattern (the two strings are exactly
equal, character for character). If CondPattern
is "" (two quotation marks) this
compares TestString to the empty string.
Treats the TestString as a pathname and tests
whether or not it exists, and is a directory.
Treats the TestString as a pathname and tests
whether or not it exists, and is a regular file.
Treats the TestString as a pathname and tests
whether or not it exists, and is a regular file with size greater
than zero.
Treats the TestString as a pathname and tests
whether or not it exists, and is a symbolic link.
Checks whether or not TestString is a valid file,
accessible via all the server's currently-configured
access controls for that path. This uses an internal
subrequest to do the check, so use it with care -
it can impact your server's performance!
Checks whether or not TestString is a valid URL,
accessible via all the server's currently-configured
access controls for that path. This uses an internal
subrequest to do the check, so use it with care -
it can impact your server's performance!Note
All of these tests can
also be prefixed by an exclamation mark ('!') to
negate their meaning.
[flags]
as the third argument to the RewriteCond
directive, where flags is a comma-separated list of any of the
following flags:
nocase|NC'
(no case)
This makes the test case-insensitive - differences
between 'A-Z' and 'a-z' are ignored, both in the
expanded TestString and the CondPattern.
This flag is effective only for comparisons between
TestString and CondPattern. It has no
effect on filesystem and subrequest checks.ornext|OR'
(or next condition)
Use this to combine rule conditions with a local OR
instead of the implicit AND. Typical example:
Without this flag you would have to write the condition/rule
pair three times.
RewriteCond %{REMOTE_HOST} ^host1.* [OR]
RewriteCond %{REMOTE_HOST} ^host2.* [OR]
RewriteCond %{REMOTE_HOST} ^host3.*
RewriteRule ...some special stuff for any of these hosts...
User-Agent:'' header of the request, you can
use the following:
RewriteCond %{HTTP_USER_AGENT} ^Mozilla.*
RewriteRule ^/$ /homepage.max.html [L]
RewriteCond %{HTTP_USER_AGENT} ^Lynx.*
RewriteRule ^/$ /homepage.min.html [L]
RewriteRule ^/$ /homepage.std.html [L]
RewriteEngine Directive
Description: Enables or disables runtime rewriting engine Syntax: RewriteEngine on|offDefault: RewriteEngine offContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Extension Module: mod_rewrite RewriteEngine directive enables or
disables the runtime rewriting engine. If it is set to
off this module does no runtime processing at
all. It does not even update the SCRIPT_URx
environment variables.RewriteRule directives!RewriteEngine on directive for each virtual host
in which you wish to use it.RewriteLock Directive
Description: Sets the name of the lock file used for RewriteMap
synchronizationSyntax: RewriteLock file-pathContext: server config Status: Extension Module: mod_rewrite RewriteMap
programs. Set this lockfile to a local path (not on a
NFS-mounted device) when you want to use a rewriting
map-program. It is not required for other types of rewriting
maps.RewriteLog Directive
Description: Sets the name of the file used for logging rewrite engine
processing Syntax: RewriteLog file-pathContext: server config, virtual host Status: Extension Module: mod_rewrite RewriteLog directive sets the name
of the file to which the server logs any rewriting actions it
performs. If the name does not begin with a slash
('/') then it is assumed to be relative to the
Server Root. The directive should occur only once per
server config. To disable the logging of
rewriting actions it is not recommended to set
Filename to
/dev/null, because
although the rewriting engine does not then output to a
logfile it still creates the logfile output internally.
This will slow down the server with no advantage
to the administrator! To disable logging either
remove or comment out the RewriteLog
directive or use RewriteLogLevel 0!
Security
See the Apache Security Tips
document for details on how your security could be compromised if the
directory where logfiles are stored is writable by anyone other than
the user that starts the server.
Example
RewriteLog "/usr/local/var/apache/logs/rewrite.log"
RewriteLogLevel Directive
Description: Sets the verbosity of the log file used by the rewrite
engine Syntax: RewriteLogLevel LevelDefault: RewriteLogLevel 0Context: server config, virtual host Status: Extension Module: mod_rewrite RewriteLogLevel directive sets the
verbosity level of the rewriting logfile. The default level 0
means no logging, while 9 or more means that practically all
actions are logged. Using a high value for
Level will slow down your Apache server
dramatically! Use the rewriting logfile at a
Level greater than 2 only for debugging!
Example
RewriteLogLevel 3
RewriteMap Directive
Description: Defines a mapping function for key-lookup Syntax: RewriteMap MapName MapType:MapSource
Context: server config, virtual host Status: Extension Module: mod_rewrite Compatibility: The choice of different dbm types is available in
Apache 2.0.41 and later RewriteMap directive defines a
Rewriting Map which can be used inside rule
substitution strings by the mapping-functions to
insert/substitute fields through a key lookup. The source of
this lookup can be of various types.${ MapName :
LookupKey }
${ MapName :
LookupKey | DefaultValue
}
RewriteMap as:
RewriteMap examplemap txt:/path/to/file/map.txt
RewriteRule as follows:
RewriteRule ^/ex/(.*) ${examplemap:$1}
MapType: txt, MapSource: Unix filesystem
path to valid regular file
Example
##
## map.txt -- rewriting map
##
Ralf.S.Engelschall rse # Bastard Operator From Hell
Mr.Joe.Average joe # Mr. Average
RewriteMap real-to-user txt:/path/to/file/map.txt
MapType: rnd, MapSource: Unix filesystem
path to valid regular file
|'' characters which have the meaning of
``or''. In other words they indicate a set of
alternatives from which the actual returned value is
chosen randomly. For example, you might use the following map
file and directives to provide a random load balancing between
several back-end server, via a reverse-proxy. Images are sent
to one of the servers in the 'static' pool, while everything
else is sent to one of the 'dynamic' pool.Rewrite map file
##
## map.txt -- rewriting map
##
static www1|www2|www3|www4
dynamic www5|www6
Configuration directives
RewriteMap servers rnd:/path/to/file/map.txt
RewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1
[NC,P,L]
RewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]
MapType:
dbm[=type], MapSource: Unix filesystem
path to valid regular file
#!/path/to/bin/perl
##
## txt2dbm -- convert txt map to dbm format
##
use NDBM_File;
use Fcntl;
($txtmap, $dbmmap) = @ARGV;
open(TXT, "<$txtmap") or die "Couldn't open $txtmap!\n";
tie (%DB, 'NDBM_File', $dbmmap,O_RDWR|O_TRUNC|O_CREAT, 0644)
or die "Couldn't create $dbmmap!\n";
while (<TXT>) {
next if (/^\s*#/ or /^\s*$/);
$DB{$1} = $2 if (/^\s*(\S+)\s+(\S+)/);
}
untie %DB;
close(TXT);
$ txt2dbm map.txt map.db
MapType: int, MapSource: Internal Apache
function
Converts the key to all upper case.
Converts the key to all lower case.
Translates special characters in the key to
hex-encodings.
Translates hex-encodings in the key back to
special characters.
MapType: prg, MapSource: Unix filesystem
path to valid regular file
#!/path/to/interpreter' as the first
line).stdin and stdout
file-handles. For each map-function lookup it will
receive the key to lookup as a newline-terminated string
on stdin. It then has to give back the
looked-up value as a newline-terminated string on
stdout or the four-character string
``NULL'' if it fails (i.e., there
is no corresponding value for the given key). A trivial
program which will implement a 1:1 map (i.e.,
key == value) could be:
#!/usr/bin/perl
$| = 1;
while (<STDIN>) {
# ...put here any transformations or lookups...
print $_;
}
stdout. Avoid this, as it will cause a deadloop!
``$|=1'' is used above, to prevent this.RewriteLock directive can
be used to define a lockfile which mod_rewrite can use to synchronize
communication with the mapping program. By default no such
synchronization takes place.RewriteMap directive can occur more than
once. For each mapping-function use one
RewriteMap directive to declare its rewriting
mapfile. While you cannot declare a map in
per-directory context it is of course possible to
use this map in per-directory context. Note
For plain text and DBM format files the
looked-up keys are cached in-core until the mtime of the
mapfile changes or the server does a restart. This way you can have
map-functions in rules which are used for every
request. This is no problem, because the external lookup only happens
once!
RewriteOptions Directive
Description: Sets some special options for the rewrite engine Syntax: RewriteOptions OptionsDefault: RewriteOptions MaxRedirects=10Context: server config, virtual host, directory, .htaccess Override: FileInfo Status: Extension Module: mod_rewrite Compatibility: MaxRedirects is available in Apache 2.0.45 and
laterRewriteOptions directive sets some
special options for the current per-server or per-directory
configuration. The Option strings can be one of the
following:
inherit.htaccess configuration are inherited.MaxRedirects=numberRewriteRules, mod_rewrite aborts
the request after reaching a maximum number of such redirects and
responds with an 500 Internal Server Error. If you really need
more internal redirects than 10 per request, you may increase
the default to the desired value.RewriteRule Directive
Description: Defines rules for the rewriting engine Syntax: RewriteRule
Pattern SubstitutionContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Extension Module: mod_rewrite Compatibility: The cookie-flag is available in Apache 2.0.40 and later. RewriteRule directive is the real
rewriting workhorse. The directive can occur more than once, with
each instance defining a single rewrite rule. The
order in which these rules are defined is important - this is the order
in which they will be applied at run-time.
Text:
. Any single character
[chars] Character class: Any character of the class ``chars''
[^chars] Character class: Not a character of the class ``chars''
text1|text2 Alternative: text1 or text2
Quantifiers:
? 0 or 1 occurrences of the preceding text
* 0 or N occurrences of the preceding text (N > 0)
+ 1 or N occurrences of the preceding text (N > 1)
Grouping:
(text) Grouping of text
(used either to set the borders of an alternative as above, or
to make backreferences, where the Nth group can
be referred to on the RHS of a RewriteRule as $N)
Anchors:
^ Start-of-line anchor
$ End-of-line anchor
Escaping:
\char escape the given char
(for instance, to specify the chars ".[]()" etc.)
Jeffrey E.F. Friedl
O'Reilly & Associates, Inc. 2002
ISBN 0-596-00289-0
!') is also available as a possible pattern
prefix. This enables you to negate a pattern; to say, for instance:
``if the current URL does NOT match this
pattern''. This can be used for exceptional cases, where
it is easier to match the negative pattern, or as a last
default rule.Note
When using the NOT character to negate a pattern, you cannot include
grouped wildcard parts in that pattern. This is because, when the
pattern does NOT match (ie, the negation matches), there are no
contents for the groups. Thus, if negated patterns are used, you
cannot use $N in the substitution string!
$N) to the RewriteRule
pattern%N) to the last matched
RewriteCond pattern%{VARNAME})${mapname:key|default})$N
(N=0..9), which will be replaced
by the contents of the Nth group of the
matched Pattern. The server-variables are the same
as for the TestString of a RewriteCond
directive. The mapping-functions come from the
RewriteMap directive and are explained there.
These three types of variables are expanded in the order above.L flag - see below.-' which means: NO
substitution! This is useful in providing
rewriting rules which only match
URLs but do not substitute anything for them. It is commonly used
in conjunction with the C (chain) flag, in order
to apply more than one pattern before substitution occurs.[flags]
as the third argument to the RewriteRule
directive. Flags is a comma-separated list of any of the
following flags:
chain|C'
(chained with next rule)
This flag chains the current rule with the next rule
(which itself can be chained with the following rule,
and so on). This has the following effect: if a rule
matches, then processing continues as usual -
the flag has no effect. If the rule does
not match, then all following chained
rules are skipped. For instance, it can be used to remove the
``.www'' part, inside a per-directory rule set,
when you let an external redirect happen (where the
``.www'' part should not occur!).cookie|CO=NAME:VAL:domain[:lifetime[:path]]'
(set cookie)
This sets a cookie in the client's browser. The cookie's name
is specified by NAME and the value is
VAL. The domain field is the domain of the
cookie, such as '.apache.org', the optional lifetime
is the lifetime of the cookie in minutes, and the optional
path is the path of the cookieenv|E=VAR:VAL'
(set environment variable)
This forces an environment variable named VAR to
be set to the value VAL, where VAL can
contain regexp backreferences ($N and
%N) which will be expanded. You can use this
flag more than once, to set more than one variable. The
variables can later be dereferenced in many situations, most commonly
from within XSSI (via <!--#echo
var="VAR"-->) or CGI ($ENV{'VAR'}).
You can also dereference the variable in a later RewriteCond pattern, using
%{ENV:VAR}. Use this to strip
information from URLs, while maintaining a record of that information.forbidden|F' (force URL
to be forbidden)
This forces the current URL to be forbidden - it immediately
sends back a HTTP response of 403 (FORBIDDEN).
Use this flag in conjunction with
appropriate RewriteConds to conditionally block some
URLs.gone|G' (force URL to be
gone)
This forces the current URL to be gone - it
immediately sends back a HTTP response of 410 (GONE). Use
this flag to mark pages which no longer exist as gone.last|L'
(last rule)
Stop the rewriting process here and don't apply any more
rewrite rules. This corresponds to the Perl
last command or the break command
in C. Use this flag to prevent the currently
rewritten URL from being rewritten further by following
rules. For example, use it to rewrite the root-path URL
('/') to a real one, e.g.,
'/e/www/'.next|N'
(next round)
Re-run the rewriting process (starting again with the
first rewriting rule). This time, the URL to match is no longer
the original URL, but rather the URL returned by the last rewriting rule.
This corresponds to the Perl next command or
the continue command in C. Use
this flag to restart the rewriting process -
to immediately go to the top of the loop.
Be careful not to create an infinite
loop!nocase|NC'
(no case)
This makes the Pattern case-insensitive,
ignoring difference between 'A-Z' and
'a-z' when Pattern is matched against the current
URL.noescape|NE'
(no URI escaping of
output)
This flag prevents mod_rewrite from applying the usual URI
escaping rules to the result of a rewrite. Ordinarily,
special characters (such as '%', '$', ';', and so on)
will be escaped into their hexcode equivalents ('%25',
'%24', and '%3B', respectively); this flag prevents this
from happening. This allows percent symbols to appear in
the output, as in
which would turn '
RewriteRule /foo/(.*) /bar?arg=P1\%3d$1 [R,NE]
/foo/zed' into a safe
request for '/bar?arg=P1=zed'.
nosubreq|NS' (
not for internal
sub-requests)
This flag forces the rewrite engine to skip a
rewrite rule if the current request is an internal
sub-request. For instance, sub-requests occur internally
in Apache when mod_include tries to find out
information about possible directory default files
(index.xxx). On sub-requests it is not
always useful, and can even cause errors, if
the complete set of rules are applied. Use this flag to
exclude some rules.
To decide whether or not to use this rule: if you
prefix URLs with CGI-scripts, to force them to be
processed by the CGI-script, it's likely that you
will run into problems (or significant overhead) on
sub-requests. In these cases, use this flag.
proxy|P' (force
proxy)
This flag forces the substitution part to be internally
sent as a proxy request and immediately (rewrite
processing stops here) put through the proxy module. You must make
sure that the substitution string is a valid URI
(typically starting with
http://hostname) which can be
handled by the Apache proxy module. If not, you will get an
error from the proxy module. Use this flag to achieve a
more powerful implementation of the ProxyPass directive,
to map remote content into the namespace of the local
server.
mod_proxy must be enabled in order
to use this flag.passthrough|PT'
(pass through to next
handler)
This flag forces the rewrite engine to set the
uri field of the internal
request_rec structure to the value of the
filename field. This flag is just a hack to
enable post-processing of the output of
RewriteRule directives, using
Alias, ScriptAlias,
Redirect, and other directives from
various URI-to-filename translators. For example, to rewrite
/abc to /def using
mod_rewrite, and then
/def to /ghi using
mod_alias:
If you omit the
RewriteRule ^/abc(.*) /def$1 [PT]
Alias /def /ghi
PT flag,
mod_rewrite will rewrite
uri=/abc/... to
filename=/def/... as a full API-compliant
URI-to-filename translator should do. Then
mod_alias will try to do a
URI-to-filename transition, which will fail.
mod_alias and
mod_rewrite.qsappend|QSA'
(query string
append)
This flag forces the rewrite engine to append a query
string part of the substitution string to the existing string,
instead of replacing it. Use this when you want to add more
data to the query string via a rewrite rule.redirect|R
[=code]' (force redirect)
Prefix Substitution with
http://thishost[:thisport]/ (which makes the
new URL a URI) to force a external redirection. If no
code is given, a HTTP response of 302 (MOVED
TEMPORARILY) will be returned. If you want to use other response
codes in the range 300-400, simply specify the appropriate number
or use one of the following symbolic names:
temp (default), permanent,
seeother. Use this for rules to
canonicalize the URL and return it to the client - to
translate ``/~'' into
``/u/'', or to always append a slash to
/u/user, etc.
Note: When you use this flag, make
sure that the substitution field is a valid URL! Otherwise,
you will be redirecting to an invalid location. Remember
that this flag on its own will only prepend
http://thishost[:thisport]/ to the URL, and rewriting
will continue. Usually, you will want to stop rewriting at this point,
and redirect immediately. To stop rewriting, you should add
the 'L' flag.
skip|S=num'
(skip next rule(s))
This flag forces the rewriting engine to skip the next
num rules in sequence, if the current rule
matches. Use this to make pseudo if-then-else constructs:
The last rule of the then-clause becomes
skip=N, where N is the number of rules in the
else-clause. (This is not the same as the
'chain|C' flag!)type|T=MIME-type'
(force MIME type)
Force the MIME-type of the target file to be
MIME-type. This can be used to
set up the content-type based on some conditions.
For example, the following snippet allows .php files to
be displayed by mod_php if they are called with
the .phps extension:
RewriteRule ^(.+\.php)s$ $1 [T=application/x-httpd-php-source]
Home directory expansion
mod_userdir.RewriteRule
directive.Note: Enabling rewrites in per-directory context
To enable the rewriting engine
for per-directory configuration files, you need to set
``RewriteEngine On'' in these files
and ``Options
FollowSymLinks'' must be enabled. If your
administrator has disabled override of
FollowSymLinks for a user's directory, then
you cannot use the rewriting engine. This restriction is
needed for security reasons.
Note: Pattern matching in per-directory context
Never forget that Pattern is
applied to a complete URL in per-server configuration
files. However, in per-directory configuration files, the
per-directory prefix (which always is the same for a specific
directory) is automatically removed for the pattern matching
and automatically added after the substitution has been
done. This feature is essential for many sorts of rewriting -
without this, you would always have to match the parent
directory which is not always possible.
http://'', then the directory
prefix will not be added, and an
external redirect or proxy throughput (if flag
P is used) is forced!Note: Substitution of Absolute URLs
http://thishost[:thisport],
mod_rewrite will automatically strip that
out. This auto-reduction on URLs with an implicit external redirect
is most useful in combination with
a mapping-function which generates the
hostname part.http://thishost because of this feature. To
achieve such a self-redirect, you have to use the
R-flag.Note: Query String
RewriteCond with the
%{QUERY_STRING} variable. You can, however, create
URLs in the substitution string, containing a query string
part. Simply use a question mark inside the substitution string, to
indicate that the following text should be re-injected into the
query string. When you want to erase an existing query string,
end the substitution string with just a question mark. To
combine a new query string with an old one, use the
[QSA] flag.httpd.conf)
for request ``GET
/somepath/pathinfo'':
Given Rule Resulting Substitution
---------------------------------------------- ----------------------------------
^/somepath(.*) otherpath$1 invalid, not supported
^/somepath(.*) otherpath$1 [R] invalid, not supported
^/somepath(.*) otherpath$1 [P] invalid, not supported
---------------------------------------------- ----------------------------------
^/somepath(.*) /otherpath$1 /otherpath/pathinfo
^/somepath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo
via external redirection
^/somepath(.*) /otherpath$1 [P] doesn't make sense, not supported
---------------------------------------------- ----------------------------------
^/somepath(.*) http://thishost/otherpath$1 /otherpath/pathinfo
^/somepath(.*) http://thishost/otherpath$1 [R] http://thishost/otherpath/pathinfo
via external redirection
^/somepath(.*) http://thishost/otherpath$1 [P] doesn't make sense, not supported
---------------------------------------------- ----------------------------------
^/somepath(.*) http://otherhost/otherpath$1 http://otherhost/otherpath/pathinfo
via external redirection
^/somepath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo
via external redirection
(the [R] flag is redundant)
^/somepath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo
via internal proxy
/somepath
(/physical/path/to/somepath/.htacccess, with
RewriteBase /somepath)
for request ``GET
/somepath/localpath/pathinfo'':
Given Rule Resulting Substitution
---------------------------------------------- ----------------------------------
^localpath(.*) otherpath$1 /somepath/otherpath/pathinfo
^localpath(.*) otherpath$1 [R] http://thishost/somepath/otherpath/pathinfo
via external redirection
^localpath(.*) otherpath$1 [P] doesn't make sense, not supported
---------------------------------------------- ----------------------------------
^localpath(.*) /otherpath$1 /otherpath/pathinfo
^localpath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo
via external redirection
^localpath(.*) /otherpath$1 [P] doesn't make sense, not supported
---------------------------------------------- ----------------------------------
^localpath(.*) http://thishost/otherpath$1 /otherpath/pathinfo
^localpath(.*) http://thishost/otherpath$1 [R] http://thishost/otherpath/pathinfo
via external redirection
^localpath(.*) http://thishost/otherpath$1 [P] doesn't make sense, not supported
---------------------------------------------- ----------------------------------
^localpath(.*) http://otherhost/otherpath$1 http://otherhost/otherpath/pathinfo
via external redirection
^localpath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo
via external redirection
(the [R] flag is redundant)
^localpath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo
via internal proxy
mod/mod_so.html 100644 0 0 22341 11074462673 11166 0 ustar 0 0
Apache Module mod_setenvif
Description: Allows the setting of environment variables based
on characteristics of the request Status: Base Module Identifier: setenvif_module Source File: mod_setenvif.c Summary
mod_setenvif module allows you to set
environment variables according to whether different aspects of
the request match regular expressions you specify. These
environment variables can be used by other parts of the server
to make decisions about actions to be taken.netscape if the
browser is mozilla but not MSIE.
BrowserMatch ^Mozilla netscape
BrowserMatch MSIE !netscape
Directives
See also
BrowserMatch Directive
Description: Sets environment variables conditional on HTTP User-Agent
Syntax: BrowserMatch regex [!]env-variable[=value]
[[!]env-variable[=value]] ...Context: server config, virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_setenvif BrowserMatch is a special cases of the
SetEnvIf directive that
sets environment variables conditional on the
User-Agent HTTP request header. The following two
lines have the same effect:
BrowserMatchNoCase Robot is_a_robot
SetEnvIfNoCase User-Agent Robot is_a_robot
BrowserMatch ^Mozilla forms jpeg=yes browser=netscape
BrowserMatch "^Mozilla/[2-3]" tables agif frames javascript
BrowserMatch MSIE !javascript
BrowserMatchNoCase Directive
Description: Sets environment variables conditional on User-Agent without
respect to case Syntax: BrowserMatchNoCase regex [!]env-variable[=value]
[[!]env-variable[=value]] ...Context: server config, virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_setenvif Compatibility: Apache 1.2 and
above (in Apache 1.2 this directive was found in the
now-obsolete mod_browser module) BrowserMatchNoCase directive is
semantically identical to the BrowserMatch directive.
However, it provides for case-insensitive matching. For
example:
BrowserMatchNoCase mac platform=macintosh
BrowserMatchNoCase win platform=windows
BrowserMatch and
BrowserMatchNoCase directives are special cases of
the SetEnvIf and SetEnvIfNoCase
directives. The following two lines have the same effect:
BrowserMatchNoCase Robot is_a_robot
SetEnvIfNoCase User-Agent Robot is_a_robot
SetEnvIf Directive
Description: Sets environment variables based on attributes of the request
Syntax: SetEnvIf attribute
regex [!]env-variable[=value]
[[!]env-variable[=value]] ...Context: server config, virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_setenvif SetEnvIf directive defines
environment variables based on attributes of the request. The
attribute specified in the first argument can be one of three
things:
Host,
User-Agent, Referer, and
Accept-Language. A regular expression may be
used to specify a set of request headers.
Remote_Host - the hostname (if available) of
the client making the requestRemote_Addr - the IP address of the client
making the requestServer_Addr - the IP address of the server
on which the request was received (only with versions later
than 2.0.43)Request_Method - the name of the method
being used (GET, POST, et
cetera)Request_Protocol - the name and version of
the protocol with which the request was made (e.g.,
"HTTP/0.9", "HTTP/1.1", etc.)Request_URI - the resource requested on the HTTP
request line -- generally the portion of the URL
following the scheme and host portion without the query stringSetEnvIf directives to test against the result
of prior matches. Only those environment variables defined by earlier
SetEnvIf[NoCase] directives are available for testing in
this manner. 'Earlier' means that they were defined at a broader scope
(such as server-wide) or previously in the current directive's scope.
Environment variables will be considered only if there was no match
among request characteristics and a regular expression was not
used for the attribute.
varname, or!varname, orvarname=valuevalue. Since version 2.0.51 Apache will
recognize occurrences of $1..$9 within
value and replace them by parenthesized subexpressions
of regex.Example:
SetEnvIf Request_URI "\.gif$" object_is_image=gif
SetEnvIf Request_URI "\.jpg$" object_is_image=jpg
SetEnvIf Request_URI "\.xbm$" object_is_image=xbm
:
SetEnvIf Referer www\.mydomain\.com intra_site_referral
:
SetEnvIf object_is_image xbm XBIT_PROCESSING=1
:
SetEnvIf ^TS* ^[a-z].* HAVE_TS
object_is_image if the request was for an image
file, and the fourth sets intra_site_referral if
the referring page was somewhere on the
www.mydomain.com Web site.HAVE_TS if the request contains any headers that
begin with "TS" whose values begins with any character in the
set [a-z].See also
SetEnvIfNoCase Directive
Description: Sets environment variables based on attributes of the request
without respect to case Syntax: SetEnvIfNoCase attribute regex
[!]env-variable[=value]
[[!]env-variable[=value]] ...Context: server config, virtual host, directory, .htaccess Override: FileInfo Status: Base Module: mod_setenvif Compatibility: Apache 1.3 and above SetEnvIfNoCase is semantically identical to
the SetEnvIf directive,
and differs only in that the regular expression matching is
performed in a case-insensitive manner. For example:
SetEnvIfNoCase Host Apache\.Org site=apache
site environment variable
to be set to "apache" if the HTTP request header
field Host: was included and contained
Apache.Org, apache.org, or any other
combination.
mod/mod_speling.html 100644 0 0 13567 11074462673 12220 0 ustar 0 0
Apache Module mod_so
Description: Loading of executable code and
modules into the server at start-up or restart time Status: Extension Module Identifier: so_module Source File: mod_so.c Compatibility: This is a Base module (always included) on
Windows Summary
.so extension), on Windows
this may either the .so or .dll
extension.Warning
Creating Loadable Modules for Windows
Note
Configure program of Apache for Unix, the module's
source file must be added to the ApacheCore project file, and
its symbols must be added to the
os\win32\modules.c file.LoadModuleAP_MODULE_DECLARE_DATA (defined in the
Apache header files) to your module's module record definition.
For example, if your module has:
module foo_module;
module AP_MODULE_DECLARE_DATA foo_module;
.DEF files, you can
export the module record with that method instead.modules directory of your server
root, and use the LoadModule
directive to load it.LoadFile Directive
Description: Link in the named object file or library Syntax: LoadFile filename [filename] ...Context: server config Status: Extension Module: mod_so LoadFile libexec/libxmlparse.soLoadModule Directive
Description: Links in the object file or library, and adds to the list
of active modules Syntax: LoadModule module filenameContext: server config Status: Extension Module: mod_so module in the file, and is listed as the Module Identifier
in the module documentation. Example:
LoadModule status_module modules/mod_status.so
mod/mod_ssl.html 100644 0 0 275456 11074462673 11407 0 ustar 0 0
Apache Module mod_speling
Description: Attempts to correct mistaken URLs that
users might have entered by ignoring capitalization and by
allowing up to one misspelling Status: Extension Module Identifier: speling_module Source File: mod_speling.c Summary
Directives
CheckSpelling Directive
Description: Enables the spelling
module Syntax: CheckSpelling on|offDefault: CheckSpelling OffContext: server config, virtual host, directory, .htaccess Override: Options Status: Extension Module: mod_speling Compatibility: CheckSpelling was available as a separately available
module for Apache 1.1, but was limited to miscapitalizations. As
of Apache 1.3, it is part of the Apache distribution. Prior to Apache
1.3.2, the CheckSpelling directive was only available in the
"server" and "virtual host" contexts.
http://my.host/~apahce/), just file names or
directory names.<Location /status> may
get incorrectly treated as the negotiated file
"/stats.html".
mod/mod_status.html 100644 0 0 16627 11074462673 12102 0 ustar 0 0
Apache Module mod_ssl
Description: Strong cryptography using the Secure Sockets
Layer (SSL) and Transport Layer Security (TLS) protocols Status: Extension Module Identifier: ssl_module Source File: mod_ssl.c Summary
Directives
SSLCACertificateFile SSLCACertificatePath SSLCARevocationFile SSLCARevocationPath SSLCertificateChainFile SSLCertificateFile SSLCertificateKeyFile SSLCipherSuite SSLEngine SSLMutex SSLOptions SSLPassPhraseDialog SSLProtocol SSLProxyCACertificateFile SSLProxyCACertificatePath SSLProxyCARevocationFile SSLProxyCARevocationPath SSLProxyCipherSuite SSLProxyEngine SSLProxyMachineCertificateFile SSLProxyMachineCertificatePath SSLProxyProtocol SSLProxyVerify SSLProxyVerifyDepth SSLRandomSeed SSLRequire SSLRequireSSL SSLSessionCache SSLSessionCacheTimeout SSLUserName SSLVerifyClient SSLVerifyDepthTopics
Environment Variables
Variable Name:
Value Type:
Description:
HTTPSflag HTTPS is being used. SSL_PROTOCOLstring The SSL protocol version (SSLv2, SSLv3, TLSv1) SSL_SESSION_IDstring The hex-encoded SSL session id SSL_CIPHERstring The cipher specification name SSL_CIPHER_EXPORTstring true if cipher is an export cipherSSL_CIPHER_USEKEYSIZEnumber Number of cipher bits (actually used) SSL_CIPHER_ALGKEYSIZEnumber Number of cipher bits (possible) SSL_VERSION_INTERFACEstring The mod_ssl program version SSL_VERSION_LIBRARYstring The OpenSSL program version SSL_CLIENT_M_VERSIONstring The version of the client certificate SSL_CLIENT_M_SERIALstring The serial of the client certificate SSL_CLIENT_S_DNstring Subject DN in client's certificate SSL_CLIENT_S_DN_x509string Component of client's Subject DN SSL_CLIENT_I_DNstring Issuer DN of client's certificate SSL_CLIENT_I_DN_x509string Component of client's Issuer DN SSL_CLIENT_V_STARTstring Validity of client's certificate (start time) SSL_CLIENT_V_ENDstring Validity of client's certificate (end time) SSL_CLIENT_A_SIGstring Algorithm used for the signature of client's certificate SSL_CLIENT_A_KEYstring Algorithm used for the public key of client's certificate SSL_CLIENT_CERTstring PEM-encoded client certificate SSL_CLIENT_CERT_CHAINnstring PEM-encoded certificates in client certificate chain SSL_CLIENT_VERIFYstring NONE, SUCCESS, GENEROUS or FAILED:reasonSSL_SERVER_M_VERSIONstring The version of the server certificate SSL_SERVER_M_SERIALstring The serial of the server certificate SSL_SERVER_S_DNstring Subject DN in server's certificate SSL_SERVER_S_DN_x509string Component of server's Subject DN SSL_SERVER_I_DNstring Issuer DN of server's certificate SSL_SERVER_I_DN_x509string Component of server's Issuer DN SSL_SERVER_V_STARTstring Validity of server's certificate (start time) SSL_SERVER_V_ENDstring Validity of server's certificate (end time) SSL_SERVER_A_SIGstring Algorithm used for the signature of server's certificate SSL_SERVER_A_KEYstring Algorithm used for the public key of server's certificate SSL_SERVER_CERTstring PEM-encoded server certificate C,ST,L,O,OU,CN,T,I,G,S,D,UID,Email ]
Custom Log Formats
mod_ssl is built into Apache or at least
loaded (under DSO situation) additional functions exist for the Custom Log Format of
mod_log_config. First there is an
additional ``%{varname}x''
eXtension format function which can be used to expand any variables
provided by any module, especially those provided by mod_ssl which can
you find in the above table.%{name}c'' cryptography format function
provided. Information about this function is provided in the Compatibility chapter.
CustomLog logs/ssl_request_log \
"%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"
SSLCACertificateFile Directive
Description: File of concatenated PEM-encoded CA Certificates
for Client Auth Syntax: SSLCACertificateFile file-pathContext: server config, virtual host Status: Extension Module: mod_ssl SSLCACertificatePath.Example
SSLCACertificateFile /usr/local/apache2/conf/ssl.crt/ca-bundle-client.crt
SSLCACertificatePath Directive
Description: Directory of PEM-encoded CA Certificates for
Client Auth Syntax: SSLCACertificatePath directory-pathContext: server config, virtual host Status: Extension Module: mod_ssl .N. And you should always make sure this directory
contains the appropriate symbolic links. Example
SSLCACertificatePath /usr/local/apache2/conf/ssl.crt/
SSLCARevocationFile Directive
Description: File of concatenated PEM-encoded CA CRLs for
Client Auth Syntax: SSLCARevocationFile file-pathContext: server config, virtual host Status: Extension Module: mod_ssl SSLCARevocationPath.Example
SSLCARevocationFile /usr/local/apache2/conf/ssl.crl/ca-bundle-client.crl
SSLCARevocationPath Directive
Description: Directory of PEM-encoded CA CRLs for
Client Auth Syntax: SSLCARevocationPath directory-pathContext: server config, virtual host Status: Extension Module: mod_ssl .rN. And you should always make sure this directory
contains the appropriate symbolic links. Example
SSLCARevocationPath /usr/local/apache2/conf/ssl.crl/
SSLCertificateChainFile Directive
Description: File of PEM-encoded Server CA Certificates Syntax: SSLCertificateChainFile file-pathContext: server config, virtual host Status: Extension Module: mod_ssl SSLCACertificatePath for explicitly
constructing the server certificate chain which is sent to the browser
in addition to the server certificate. It is especially useful to
avoid conflicts with CA certificates when using client
authentication. Because although placing a CA certificate of the
server certificate chain into SSLCACertificatePath has the same effect
for the certificate chain construction, it has the side-effect that
client certificates issued by this same CA certificate are also
accepted on client authentication. That's usually not one expect.Example
SSLCertificateChainFile /usr/local/apache2/conf/ssl.crt/ca.crt
SSLCertificateFile Directive
Description: Server PEM-encoded X.509 Certificate file Syntax: SSLCertificateFile file-pathContext: server config, virtual host Status: Extension Module: mod_ssl Example
SSLCertificateFile /usr/local/apache2/conf/ssl.crt/server.crt
SSLCertificateKeyFile Directive
Description: Server PEM-encoded Private Key file Syntax: SSLCertificateKeyFile file-pathContext: server config, virtual host Status: Extension Module: mod_ssl SSLCertificateFile, use this additional directive to
point to the file with the stand-alone Private Key. When
SSLCertificateFile is used and the file
contains both the Certificate and the Private Key this directive need
not be used. But we strongly discourage this practice. Instead we
recommend you to separate the Certificate and the Private Key. If the
contained Private Key is encrypted, the Pass Phrase dialog is forced
at startup time. This directive can be used up to two times
(referencing different filenames) when both a RSA and a DSA based
private key is used in parallel.Example
SSLCertificateKeyFile /usr/local/apache2/conf/ssl.key/server.key
SSLCipherSuite Directive
Description: Cipher Suite available for negotiation in SSL
handshake Syntax: SSLCipherSuite cipher-specDefault: SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXPContext: server config, virtual host, directory, .htaccess Override: AuthConfig Status: Extension Module: mod_ssl
RSA or Diffie-Hellman variants.
RSA, Diffie-Hellman, DSS or none.
DES, Triple-DES, RC4, RC2, IDEA or none.
MD5, SHA or SHA1.
Tag Description Key Exchange Algorithm: kRSARSA key exchange kDHrDiffie-Hellman key exchange with RSA key kDHdDiffie-Hellman key exchange with DSA key kEDHEphemeral (temp.key) Diffie-Hellman key exchange (no cert) Authentication Algorithm: aNULLNo authentication aRSARSA authentication aDSSDSS authentication aDHDiffie-Hellman authentication Cipher Encoding Algorithm: eNULLNo encoding DESDES encoding 3DESTriple-DES encoding RC4RC4 encoding RC2RC2 encoding IDEAIDEA encoding MAC Digest Algorithm: MD5MD5 hash function SHA1SHA1 hash function SHASHA hash function Aliases: SSLv2all SSL version 2.0 ciphers SSLv3all SSL version 3.0 ciphers TLSv1all TLS version 1.0 ciphers EXPall export ciphers EXPORT40all 40-bit export ciphers only EXPORT56all 56-bit export ciphers only LOWall low strength ciphers (no export, single DES) MEDIUMall ciphers with 128 bit encryption HIGHall ciphers using Triple-DES RSAall ciphers using RSA key exchange DHall ciphers using Diffie-Hellman key exchange EDHall ciphers using Ephemeral Diffie-Hellman key exchange ADHall ciphers using Anonymous Diffie-Hellman key exchange DSSall ciphers using DSS authentication NULLall ciphers using no encryption SSLv2, SSLv3, TLSv1, EXP, LOW, MEDIUM,
HIGH) for certain groups of ciphers. These tags can be joined
together with prefixes to form the cipher-spec. Available
prefixes are:
+: add ciphers to list and pull them to current location in list-: remove cipher from list (can be added later again)!: kill cipher from list completely (can not be added later again)openssl ciphers
-v'' command which provides a nice way to successively create the
correct cipher-spec string. The default cipher-spec string
is ``ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP'' which
means the following: first, remove from consideration any ciphers that do not
authenticate, i.e. for SSL only the Anonymous Diffie-Hellman ciphers. Next,
use ciphers using RC4 and RSA. Next include the high, medium and then the low
security ciphers. Finally pull all SSLv2 and export ciphers to the
end of the list.
$ openssl ciphers -v 'ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP'
NULL-SHA SSLv3 Kx=RSA Au=RSA Enc=None Mac=SHA1
NULL-MD5 SSLv3 Kx=RSA Au=RSA Enc=None Mac=MD5
EDH-RSA-DES-CBC3-SHA SSLv3 Kx=DH Au=RSA Enc=3DES(168) Mac=SHA1
... ... ... ... ...
EXP-RC4-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export
EXP-RC2-CBC-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC2(40) Mac=MD5 export
EXP-RC4-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export
Example
SSLCipherSuite RSA:!EXP:!NULL:+HIGH:+MEDIUM:-LOW
Cipher-Tag Protocol Key Ex. Auth. Enc. MAC Type RSA Ciphers: DES-CBC3-SHASSLv3 RSA RSA 3DES(168) SHA1 DES-CBC3-MD5SSLv2 RSA RSA 3DES(168) MD5 IDEA-CBC-SHASSLv3 RSA RSA IDEA(128) SHA1 RC4-SHASSLv3 RSA RSA RC4(128) SHA1 RC4-MD5SSLv3 RSA RSA RC4(128) MD5 IDEA-CBC-MD5SSLv2 RSA RSA IDEA(128) MD5 RC2-CBC-MD5SSLv2 RSA RSA RC2(128) MD5 RC4-MD5SSLv2 RSA RSA RC4(128) MD5 DES-CBC-SHASSLv3 RSA RSA DES(56) SHA1 RC4-64-MD5SSLv2 RSA RSA RC4(64) MD5 DES-CBC-MD5SSLv2 RSA RSA DES(56) MD5 EXP-DES-CBC-SHASSLv3 RSA(512) RSA DES(40) SHA1 export EXP-RC2-CBC-MD5SSLv3 RSA(512) RSA RC2(40) MD5 export EXP-RC4-MD5SSLv3 RSA(512) RSA RC4(40) MD5 export EXP-RC2-CBC-MD5SSLv2 RSA(512) RSA RC2(40) MD5 export EXP-RC4-MD5SSLv2 RSA(512) RSA RC4(40) MD5 export NULL-SHASSLv3 RSA RSA None SHA1 NULL-MD5SSLv3 RSA RSA None MD5 Diffie-Hellman Ciphers: ADH-DES-CBC3-SHASSLv3 DH None 3DES(168) SHA1 ADH-DES-CBC-SHASSLv3 DH None DES(56) SHA1 ADH-RC4-MD5SSLv3 DH None RC4(128) MD5 EDH-RSA-DES-CBC3-SHASSLv3 DH RSA 3DES(168) SHA1 EDH-DSS-DES-CBC3-SHASSLv3 DH DSS 3DES(168) SHA1 EDH-RSA-DES-CBC-SHASSLv3 DH RSA DES(56) SHA1 EDH-DSS-DES-CBC-SHASSLv3 DH DSS DES(56) SHA1 EXP-EDH-RSA-DES-CBC-SHASSLv3 DH(512) RSA DES(40) SHA1 export EXP-EDH-DSS-DES-CBC-SHASSLv3 DH(512) DSS DES(40) SHA1 export EXP-ADH-DES-CBC-SHASSLv3 DH(512) None DES(40) SHA1 export EXP-ADH-RC4-MD5SSLv3 DH(512) None RC4(40) MD5 export SSLEngine Directive
Description: SSL Engine Operation Switch Syntax: SSLEngine on|offDefault: SSLEngine offContext: server config, virtual host Status: Extension Module: mod_ssl <VirtualHost> section to enable SSL/TLS for a
particular virtual host. By default the SSL/TLS Protocol Engine is
disabled for both the main server and all configured virtual hosts.Example
<VirtualHost _default_:443>
SSLEngine on
...
</VirtualHost>
SSLMutex Directive
Description: Semaphore for internal mutual exclusion of
operations Syntax: SSLMutex typeDefault: SSLMutex noneContext: server config Status: Extension Module: mod_ssl
none | no
posixsem
sysvsem
sem
pthread
fcntl:/path/to/mutex
fcntl()
fucntion are used as the Mutex.
Always use a local disk filesystem for /path/to/mutex and never a file
residing on a NFS- or AFS-filesystem. It is only available when the underlying platform
and APR supports it. Note: Internally, the Process ID (PID) of the
Apache parent process is automatically appended to
/path/to/mutex to make it unique, so you don't have to worry
about conflicts yourself. Notice that this type of mutex is not available
under the Win32 environment. There you have to use the semaphore
mutex.flock:/path/to/mutex
fcntl:/path/to/mutex method with the
exception that the flock() function is used to provide file
locking. It is only available when the underlying platform
and APR supports it.file:/path/to/mutex
fcntl and flock,
in that order. It is only available when the underlying platform and APR supports
at least one of the 2.default | yes
Example
SSLMutex file:/usr/local/apache/logs/ssl_mutex
SSLOptions Directive
Description: Configure various SSL engine run-time options Syntax: SSLOptions [+|-]option ...Context: server config, virtual host, directory, .htaccess Override: Options Status: Extension Module: mod_ssl SSLOptions
could apply to a directory, then the most specific one is taken
completely; the options are not merged. However if all the
options on the SSLOptions directive are preceded by a
plus (+) or minus (-) symbol, the options
are merged. Any options preceded by a + are added to the
options currently in force, and any options preceded by a
- are removed from the options currently in force.
StdEnvVars
CompatEnvVars
ExportCertData
SSL_SERVER_CERT, SSL_CLIENT_CERT and
SSL_CLIENT_CERT_CHAINn (with n = 0,1,2,..).
These contain the PEM-encoded X.509 Certificates of server and client for
the current HTTPS connection and can be used by CGI scripts for deeper
Certificate checking. Additionally all other certificates of the client
certificate chain are provided, too. This bloats up the environment a
little bit which is why you have to use this option to enable it on
demand.FakeBasicAuth
openssl x509 command: openssl x509 -noout -subject -in
certificate.crt). Note that no password is
obtained from the user. Every entry in the user file needs this password:
``xxj31ZMTZzkVA'', which is the DES-encrypted version of the
word `password''. Those who live under MD5-based encryption
(for instance under FreeBSD or BSD/OS, etc.) should use the following MD5
hash of the same word: ``$1$OXLyS...$Owx8s2/m9/gfkcRVXzgoE/''.StrictRequire
SSLRequireSSL or
SSLRequire successfully decided that access should be
forbidden. Usually the default is that in the case where a ``Satisfy
any'' directive is used, and other access restrictions are passed,
denial of access due to SSLRequireSSL or
SSLRequire is overridden (because that's how the Apache
Satisfy mechanism should work.) But for strict access restriction
you can use SSLRequireSSL and/or SSLRequire in
combination with an ``SSLOptions +StrictRequire''. Then an
additional ``Satisfy Any'' has no chance once mod_ssl has
decided to deny access.OptRenegotiate
Example
SSLOptions +FakeBasicAuth -StrictRequire
<Files ~ "\.(cgi|shtml)$">
SSLOptions +StdEnvVars +CompatEnvVars -ExportCertData
<Files>
SSLPassPhraseDialog Directive
Description: Type of pass phrase dialog for encrypted private
keys Syntax: SSLPassPhraseDialog typeDefault: SSLPassPhraseDialog builtinContext: server config Status: Extension Module: mod_ssl SSLCertificateFile) and
Private Key (see SSLCertificateKeyFile) files of the
SSL-enabled virtual servers. Because for security reasons the Private
Key files are usually encrypted, mod_ssl needs to query the
administrator for a Pass Phrase in order to decrypt those files. This
query can be done in two ways which can be configured by
type:
builtin
exec:/path/to/program
servername:portnumber'', the second is either
``RSA'' or ``DSA''), which indicate for which
server and algorithm it has to print the corresponding Pass Phrase to
stdout. The intent is that this external program first runs
security checks to make sure that the system is not compromised by an
attacker, and only when these checks were passed successfully it provides
the Pass Phrase.stdout.
Nothing more or less! So, if you're really paranoid about security, here
is your interface. Anything else has to be left as an exercise to the
administrator, because local security requirements are so different.
SSLPassPhraseDialog exec:/usr/local/apache/sbin/pp-filter
SSLProtocol Directive
Description: Configure usable SSL protocol flavors Syntax: SSLProtocol [+|-]protocol ...Default: SSLProtocol allContext: server config, virtual host Override: Options Status: Extension Module: mod_ssl
SSLv2
SSLv3
TLSv1
All
+SSLv2 +SSLv3 +TLSv1'' and a
convinient way for enabling all protocols except one when used in
combination with the minus sign on a protocol as the example above
shows.Example
# enable SSLv3 and TLSv1, but not SSLv2
SSLProtocol all -SSLv2
SSLProxyCACertificateFile Directive
Description: File of concatenated PEM-encoded CA Certificates
for Remote Server Auth Syntax: SSLProxyCACertificateFile file-pathContext: server config, virtual host Status: Extension Module: mod_ssl SSLProxyCACertificatePath.Example
SSLProxyCACertificateFile /usr/local/apache2/conf/ssl.crt/ca-bundle-remote-server.crt
SSLProxyCACertificatePath Directive
Description: Directory of PEM-encoded CA Certificates for
Remote Server Auth Syntax: SSLProxyCACertificatePath directory-pathContext: server config, virtual host Status: Extension Module: mod_ssl .N. And you should always make sure this directory
contains the appropriate symbolic links. Use the Makefile which
comes with mod_ssl to accomplish this task.Example
SSLProxyCACertificatePath /usr/local/apache2/conf/ssl.crt/
SSLProxyCARevocationFile Directive
Description: File of concatenated PEM-encoded CA CRLs for
Remote Server Auth Syntax: SSLProxyCARevocationFile file-pathContext: server config, virtual host Status: Extension Module: mod_ssl SSLProxyCARevocationPath.Example
SSLProxyCARevocationFile /usr/local/apache2/conf/ssl.crl/ca-bundle-remote-server.crl
SSLProxyCARevocationPath Directive
Description: Directory of PEM-encoded CA CRLs for
Remote Server Auth Syntax: SSLProxyCARevocationPath directory-pathContext: server config, virtual host Status: Extension Module: mod_ssl .rN. And you should always make sure this directory
contains the appropriate symbolic links. Use the Makefile which
comes with mod_ssl to accomplish this task.Example
SSLProxyCARevocationPath /usr/local/apache2/conf/ssl.crl/
SSLProxyCipherSuite Directive
Description: Cipher Suite available for negotiation in SSL
proxy handshake Syntax: SSLProxyCipherSuite cipher-specDefault: SSLProxyCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXPContext: server config, virtual host, directory, .htaccess Override: AuthConfig Status: Extension Module: mod_ssl SSLCipherSuite, but for the proxy connection.
Please refer to SSLCipherSuite
for additional information.SSLProxyEngine Directive
Description: SSL Proxy Engine Operation Switch Syntax: SSLProxyEngine on|offDefault: SSLProxyEngine offContext: server config, virtual host Status: Extension Module: mod_ssl <VirtualHost> section to enable SSL/TLS for proxy
usage in a particular virtual host. By default the SSL/TLS Protocol Engine is
disabled for proxy image both for the main server and all configured virtual hosts.Example
<VirtualHost _default_:443>
SSLProxyEngine on
...
</VirtualHost>
SSLProxyMachineCertificateFile Directive
Description: File of concatenated PEM-encoded client certificates and keys to be used by the proxy Syntax: SSLProxyMachineCertificateFile filenameContext: server config Override: Not applicable Status: Extension Module: mod_ssl SSLProxyMachineCertificatePath.
SSLProxyMachineCertificateFile /usr/local/apache2/conf/ssl.crt/proxy.pem
SSLProxyMachineCertificatePath Directive
Description: Directory of PEM-encoded client certificates and keys to be used by the proxy Syntax: SSLProxyMachineCertificatePath directoryContext: server config Override: Not applicable Status: Extension Module: mod_ssl hash-value.N. And you should always make sure this
directory contains the appropriate symbolic links. Use the Makefile which
comes with mod_ssl to accomplish this task.
SSLProxyMachineCertificatePath /usr/local/apache2/conf/proxy.crt/
SSLProxyProtocol Directive
Description: Configure usable SSL protocol flavors for proxy usage Syntax: SSLProxyProtocol [+|-]protocol ...Default: SSLProxyProtocol allContext: server config, virtual host Override: Options Status: Extension Module: mod_ssl SSLProtocol
for additional information.
SSLProxyVerify Directive
Description: Type of remote server Certificate verification Syntax: SSLProxyVerify levelDefault: SSLProxyVerify noneContext: server config, virtual host, directory, .htaccess Override: AuthConfig Status: Extension Module: mod_ssl
but it need not to be (successfully) verifiable.Example
SSLProxyVerify require
SSLProxyVerifyDepth Directive
Description: Maximum depth of CA Certificates in Remote Server
Certificate verification Syntax: SSLProxyVerifyDepth numberDefault: SSLProxyVerifyDepth 1Context: server config, virtual host, directory, .htaccess Override: AuthConfig Status: Extension Module: mod_ssl SSLProxyCACertificatePath), etc.Example
SSLProxyVerifyDepth 10
SSLRandomSeed Directive
Description: Pseudo Random Number Generator (PRNG) seeding
source Syntax: SSLRandomSeed context source
[bytes]Context: server config Status: Extension Module: mod_ssl startup) and/or just before a new SSL connection is established
(context is connect). This directive can only be used
in the global server context because the PRNG is a global facility.
builtin
file:/path/to/source
/path/to/source as the
source for seeding the PRNG. When bytes is specified, only the
first bytes number of bytes of the file form the entropy (and
bytes is given to /path/to/source as the first
argument). When bytes is not specified the whole file forms the
entropy (and 0 is given to /path/to/source as
the first argument). Use this especially at startup time, for instance
with an available /dev/random and/or
/dev/urandom devices (which usually exist on modern Unix
derivates like FreeBSD and Linux)./dev/random provides only as
much entropy data as it actually has, i.e. when you request 512 bytes of
entropy, but the device currently has only 100 bytes available two things
can happen: On some platforms you receive only the 100 bytes while on
other platforms the read blocks until enough bytes are available (which
can take a long time). Here using an existing /dev/urandom is
better, because it never blocks and actually gives the amount of requested
data. The drawback is just that the quality of the received data may not
be the best.exec:/path/to/program/ variant (see below) or use
egd:/path/to/egd-socket (see below).exec:/path/to/program
/path/to/program as the source for seeding the
PRNG. When bytes is specified, only the first
bytes number of bytes of its stdout contents
form the entropy. When bytes is not specified, the
entirety of the data produced on stdout form the
entropy. Use this only at startup time when you need a very strong
seeding with the help of an external program (for instance as in
the example above with the truerand utility you can
find in the mod_ssl distribution which is based on the AT&T
truerand library). Using this in the connection context
slows down the server too dramatically, of course. So usually you
should avoid using external programs in that context.egd:/path/to/egd-socket (Unix only)
Example
SSLRandomSeed startup builtin
SSLRandomSeed startup file:/dev/random
SSLRandomSeed startup file:/dev/urandom 1024
SSLRandomSeed startup exec:/usr/local/bin/truerand 16
SSLRandomSeed connect builtin
SSLRandomSeed connect file:/dev/random
SSLRandomSeed connect file:/dev/urandom 1024
SSLRequire Directive
Description: Allow access only when an arbitrarily complex
boolean expression is true Syntax: SSLRequire expressionContext: directory, .htaccess Override: AuthConfig Status: Extension Module: mod_ssl
expr ::= "true" | "false"
| "!" expr
| expr "&&" expr
| expr "||" expr
| "(" expr ")"
| comp
comp ::= word "==" word | word "eq" word
| word "!=" word | word "ne" word
| word "<" word | word "lt" word
| word "<=" word | word "le" word
| word ">" word | word "gt" word
| word ">=" word | word "ge" word
| word "in" "{" wordlist "}"
| word "=~" regex
| word "!~" regex
wordlist ::= word
| wordlist "," word
word ::= digit
| cstring
| variable
| function
digit ::= [0-9]+
cstring ::= "..."
variable ::= "%{" varname "}"
function ::= funcname "(" funcargs ")"
varname any variable from Table 3 can be used. Finally for
funcname the following functions are available:
file(filename)
Example
SSLRequire ( %{SSL_CIPHER} !~ m/^(EXP|NULL)-/ \
and %{SSL_CLIENT_S_DN_O} eq "Snake Oil, Ltd." \
and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"} \
and %{TIME_WDAY} >= 1 and %{TIME_WDAY} <= 5 \
and %{TIME_HOUR} >= 8 and %{TIME_HOUR} <= 20 ) \
or %{REMOTE_ADDR} =~ m/^192\.76\.162\.[0-9]+$/
HTTP_USER_AGENT PATH_INFO AUTH_TYPE
HTTP_REFERER QUERY_STRING SERVER_SOFTWARE
HTTP_COOKIE REMOTE_HOST API_VERSION
HTTP_FORWARDED REMOTE_IDENT TIME_YEAR
HTTP_HOST IS_SUBREQ TIME_MON
HTTP_PROXY_CONNECTION DOCUMENT_ROOT TIME_DAY
HTTP_ACCEPT SERVER_ADMIN TIME_HOUR
HTTP:headername SERVER_NAME TIME_MIN
THE_REQUEST SERVER_PORT TIME_SEC
REQUEST_METHOD SERVER_PROTOCOL TIME_WDAY
REQUEST_SCHEME REMOTE_ADDR TIME
REQUEST_URI REMOTE_USER ENV:variablename
REQUEST_FILENAME
HTTPS SSL_CLIENT_M_VERSION SSL_SERVER_M_VERSION
SSL_CLIENT_M_SERIAL SSL_SERVER_M_SERIAL
SSL_PROTOCOL SSL_CLIENT_V_START SSL_SERVER_V_START
SSL_SESSION_ID SSL_CLIENT_V_END SSL_SERVER_V_END
SSL_CIPHER SSL_CLIENT_S_DN SSL_SERVER_S_DN
SSL_CIPHER_EXPORT SSL_CLIENT_S_DN_C SSL_SERVER_S_DN_C
SSL_CIPHER_ALGKEYSIZE SSL_CLIENT_S_DN_ST SSL_SERVER_S_DN_ST
SSL_CIPHER_USEKEYSIZE SSL_CLIENT_S_DN_L SSL_SERVER_S_DN_L
SSL_VERSION_LIBRARY SSL_CLIENT_S_DN_O SSL_SERVER_S_DN_O
SSL_VERSION_INTERFACE SSL_CLIENT_S_DN_OU SSL_SERVER_S_DN_OU
SSL_CLIENT_S_DN_CN SSL_SERVER_S_DN_CN
SSL_CLIENT_S_DN_T SSL_SERVER_S_DN_T
SSL_CLIENT_S_DN_I SSL_SERVER_S_DN_I
SSL_CLIENT_S_DN_G SSL_SERVER_S_DN_G
SSL_CLIENT_S_DN_S SSL_SERVER_S_DN_S
SSL_CLIENT_S_DN_D SSL_SERVER_S_DN_D
SSL_CLIENT_S_DN_UID SSL_SERVER_S_DN_UID
SSL_CLIENT_S_DN_Email SSL_SERVER_S_DN_Email
SSL_CLIENT_I_DN SSL_SERVER_I_DN
SSL_CLIENT_I_DN_C SSL_SERVER_I_DN_C
SSL_CLIENT_I_DN_ST SSL_SERVER_I_DN_ST
SSL_CLIENT_I_DN_L SSL_SERVER_I_DN_L
SSL_CLIENT_I_DN_O SSL_SERVER_I_DN_O
SSL_CLIENT_I_DN_OU SSL_SERVER_I_DN_OU
SSL_CLIENT_I_DN_CN SSL_SERVER_I_DN_CN
SSL_CLIENT_I_DN_T SSL_SERVER_I_DN_T
SSL_CLIENT_I_DN_I SSL_SERVER_I_DN_I
SSL_CLIENT_I_DN_G SSL_SERVER_I_DN_G
SSL_CLIENT_I_DN_S SSL_SERVER_I_DN_S
SSL_CLIENT_I_DN_D SSL_SERVER_I_DN_D
SSL_CLIENT_I_DN_UID SSL_SERVER_I_DN_UID
SSL_CLIENT_I_DN_Email SSL_SERVER_I_DN_Email
SSL_CLIENT_A_SIG SSL_SERVER_A_SIG
SSL_CLIENT_A_KEY SSL_SERVER_A_KEY
SSL_CLIENT_CERT SSL_SERVER_CERT
SSL_CLIENT_CERT_CHAINn
SSL_CLIENT_VERIFY
SSLRequireSSL Directive
Description: Deny access when SSL is not used for the
HTTP request Syntax: SSLRequireSSLContext: directory, .htaccess Override: AuthConfig Status: Extension Module: mod_ssl Example
SSLRequireSSL
SSLSessionCache Directive
Description: Type of the global/inter-process SSL Session
Cache Syntax: SSLSessionCache typeDefault: SSLSessionCache noneContext: server config Status: Extension Module: mod_ssl
none
dbm:/path/to/datafile
shm:/path/to/datafile[(size)]
/path/to/datafile) to synchronize the local OpenSSL memory
caches of the server processes. This storage type is not available on all
platforms.Examples
SSLSessionCache dbm:/usr/local/apache/logs/ssl_gcache_data
SSLSessionCache shm:/usr/local/apache/logs/ssl_gcache_data(512000)
SSLSessionCacheTimeout Directive
Description: Number of seconds before an SSL session expires
in the Session Cache Syntax: SSLSessionCacheTimeout secondsDefault: SSLSessionCacheTimeout 300Context: server config, virtual host Status: Extension Module: mod_ssl Example
SSLSessionCacheTimeout 600
SSLUserName Directive
Description: Variable name to determine user name Syntax: SSLUserName varnameContext: server config, directory, .htaccess Override: AuthConfig Status: Extension Module: mod_ssl Compatibility: Available in Apache 2.0.51 and later REMOTE_USER to be set. The varname can be
any of the SSL environment variables.Example
SSLUserName SSL_CLIENT_S_DN_CN
SSLVerifyClient Directive
Description: Type of Client Certificate verification Syntax: SSLVerifyClient levelDefault: SSLVerifyClient noneContext: server config, virtual host, directory, .htaccess Override: AuthConfig Status: Extension Module: mod_ssl
but it need not to be (successfully) verifiable.Example
SSLVerifyClient require
SSLVerifyDepth Directive
Description: Maximum depth of CA Certificates in Client
Certificate verification Syntax: SSLVerifyDepth numberDefault: SSLVerifyDepth 1Context: server config, virtual host, directory, .htaccess Override: AuthConfig Status: Extension Module: mod_ssl SSLCACertificatePath), etc.Example
SSLVerifyDepth 10
mod/mod_suexec.html 100644 0 0 10366 11074462673 12045 0 ustar 0 0
Apache Module mod_status
Description: Provides information on server activity and
performance Status: Base Module Identifier: status_module Source File: mod_status.c Summary
ExtendedStatus
is On.Directives
Topics
Enabling Status Support
httpd.conf
configuration file
<Location /server-status>
SetHandler server-status
Order Deny,Allow
Deny from all
Allow from .foo.com
</Location>
http://your.server.name/server-status
Automatic Updates
http://your.server.name/server-status?refresh=N to
refresh the page every N seconds.
Machine Readable Status File
http://your.server.name/server-status?auto. This
is useful when automatically run, see the Perl program in the
/support directory of Apache,
log_server_status.
It should be noted that if
mod_status is
compiled into the server, its handler capability is available
in all configuration files, including
per-directory files (e.g.,
.htaccess). This may have security-related
ramifications for your site.
ExtendedStatus Directive
Description: Keep track of extended status information for each
request Syntax: ExtendedStatus On|OffDefault: ExtendedStatus OffContext: server config Status: Base Module: mod_status Compatibility: ExtendedStatus is only available in Apache 1.3.2 and
later.
mod/mod_unique_id.html 100644 0 0 26276 11074462673 12542 0 ustar 0 0
Apache Module mod_suexec
Description: Allows CGI scripts to run as a specified user
and Group Status: Extension Module Identifier: suexec_module Source File: mod_suexec.c Compatibility: Available in Apache 2.0 and later Summary
suexec support program allows
CGI scripts to run as a specified user and Group.SuexecUserGroup Directive
Description: User and group permissions for CGI programs Syntax: SuexecUserGroup User GroupContext: server config, virtual host Status: Extension Module: mod_suexec Compatibility: SuexecUserGroup is only available in 2.0 and
later. SuexecUserGroup directive allows you
to specify a user and group for CGI programs to run as. Non-CGI
requests are still processes with the user specified in the User
directive. This directive replaces the Apache 1.3 configuration of
using the User and Group directives inside of VirtualHosts.Example
SuexecUserGroup nobody nogroup
mod/mod_userdir.html 100644 0 0 16736 11074462673 12235 0 ustar 0 0
Apache Module mod_unique_id
Description: Provides an environment variable with a unique
identifier for each request Status: Extension Module Identifier: unique_id_module Source File: mod_unique_id.c Summary
UNIQUE_ID is
set to the identifier for each request. Unique identifiers are
useful for various reasons which are beyond the scope of this
document.
Theory
UNIQUE_ID environment variable is
constructed by encoding the 112-bit (32-bit IP address, 32 bit
pid, 32 bit time stamp, 16 bit counter) quadruple using the
alphabet [A-Za-z0-9@-] in a manner similar to MIME
base64 encoding, producing 19 characters. The MIME base64
alphabet is actually [A-Za-z0-9+/] however
+ and / need to be specially encoded
in URLs, which makes them less desirable. All values are
encoded in network byte ordering so that the encoding is
comparable across architectures of different byte ordering. The
actual ordering of the encoding is: time stamp, IP address,
pid, counter. This ordering has a purpose, but it should be
emphasized that applications should not dissect the encoding.
Applications should treat the entire encoded
UNIQUE_ID as an opaque token, which can be
compared against other UNIQUE_IDs for equality
only.UNIQUE_IDs. The new
encodings should also keep the time stamp as the first element,
and can otherwise use the same alphabet and bit length. Since
the time stamps are essentially an increasing sequence, it's
sufficient to have a flag second in which all machines
in the cluster stop serving and request, and stop using the old
encoding format. Afterwards they can resume requests and begin
issuing the new encodings.
mod/mod_usertrack.html 100644 0 0 34653 11074462673 12561 0 ustar 0 0
Apache Module mod_userdir
Description: User-specific directories Status: Base Module Identifier: userdir_module Source File: mod_userdir.c Summary
http://example.com/~user/ syntax.UserDir Directive
Description: Location of the user-specific directories Syntax: UserDir directory-filenameDefault: UserDir public_htmlContext: server config, virtual host Status: Base Module: mod_userdir UserDir directive sets the real
directory in a user's home directory to use when a request for a
document for a user is received. Directory-filename is
one of the following:
disabled. This turns off
all username-to-directory translations except those
explicitly named with the enabled keyword (see
below).disabled followed by a
space-delimited list of usernames. Usernames that appear in
such a list will never have directory translation
performed, even if they appear in an enabled
clause.enabled followed by a
space-delimited list of usernames. These usernames will have
directory translation performed even if a global disable is
in effect, but not if they also appear in a
disabled clause.enabled nor the
disabled keywords appear in the
Userdir directive, the argument is treated as a
filename pattern, and is used to turn the name into a directory
specification. A request for
http://www.foo.com/~bob/one/two.html will be
translated to:
UserDir directive used
Translated path UserDir public_html ~bob/public_html/one/two.html UserDir /usr/web /usr/web/bob/one/two.html UserDir /home/*/www /home/bob/www/one/two.html
UserDir directive used
Translated path UserDir http://www.foo.com/users http://www.foo.com/users/bob/one/two.html UserDir
http://www.foo.com/*/usr http://www.foo.com/bob/usr/one/two.html UserDir
http://www.foo.com/~*/ http://www.foo.com/~bob/one/two.html
Be careful when using this directive; for instance,
"UserDir ./" would map "/~root" to
"/" - which is probably undesirable. It is strongly
recommended that your configuration include a "UserDir
disabled root" declaration. See also the Directory directive and the Security Tips page for
more information.
UserDir directories, but
not anyone else, use the following:
UserDir disabled
UserDir enabled user1 user2 user3
UserDir directories, but
deny this to a few, use the following:
UserDir enabled
UserDir disabled user4 user5 user6
Userdir public_html /usr/web http://www.foo.com/
See also
mod/mod_version.html 100644 0 0 15615 11074462673 12240 0 ustar 0 0
Apache Module mod_usertrack
Description:
Clickstream logging of user activity on a site
Status: Extension Module Identifier: usertrack_module Source File: mod_usertrack.c Summary
Directives
Topics
Logging
CookieLog
directive. In this release, this module does no logging at all.
Instead, a configurable log format file should be used to log
user click-streams. This is possible because the logging module
now allows multiple log files. The cookie itself is logged by
using the text %{cookie}n in the log file format. For
example:
CustomLog logs/clickstream "%{cookie}n %r %t"
CookieLog directive, but this
should be upgraded to the above CustomLog directive.
2-digit or 4-digit dates for cookies?
From: "Christian Allen" <christian@sane.com>
Subject: Re: Apache Y2K bug in mod_usertrack.c
Date: Tue, 30 Jun 1998 11:41:56 -0400
Did some work with cookies and dug up some info that might be useful.
True, Netscape claims that the correct format NOW is four digit dates, and
four digit dates do in fact work... for Netscape 4.x (Communicator), that
is. However, 3.x and below do NOT accept them. It seems that Netscape
originally had a 2-digit standard, and then with all of the Y2K hype and
probably a few complaints, changed to a four digit date for Communicator.
Fortunately, 4.x also understands the 2-digit format, and so the best way to
ensure that your expiration date is legible to the client's browser is to
use 2-digit dates.
However, this does not limit expiration dates to the year 2000; if you use
an expiration year of "13", for example, it is interpreted as 2013, NOT
1913! In fact, you can use an expiration year of up to "37", and it will be
understood as "2037" by both MSIE and Netscape versions 3.x and up (not sure
about versions previous to those). Not sure why Netscape used that
particular year as its cut-off point, but my guess is that it was in respect
to UNIX's 2038 problem. Netscape/MSIE 4.x seem to be able to understand
2-digit years beyond that, at least until "50" for sure (I think they
understand up until about "70", but not for sure).
Summary: Mozilla 3.x and up understands two digit dates up until "37"
(2037). Mozilla 4.x understands up until at least "50" (2050) in 2-digit
form, but also understands 4-digit years, which can probably reach up until
9999. Your best bet for sending a long-life cookie is to send it for some
time late in the year "37".
CookieDomain Directive
Description: The domain to which the tracking cookie applies Syntax: CookieDomain domainContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Extension Module: mod_usertrack .foo.com is legal, but foo.bar.com and
.com are not.Most browsers in use today will not allow cookies to be set
for a two-part top level domain, such as
.co.uk,
although such a domain ostensibly fulfills the requirements
above.
These domains are equivalent to top level domains such as
.com, and allowing such cookies may be a security
risk. Thus, if you are under a two-part top level domain, you
should still use your actual domain, as you would with any other top
level domain (for example, use .foo.co.uk).
CookieExpires Directive
Description: Expiry time for the tracking cookie Syntax: CookieExpires expiry-periodContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Extension Module: mod_usertrack CookieName Directive
Description: Name of the tracking cookie Syntax: CookieName tokenDefault: CookieName ApacheContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Extension Module: mod_usertrack Apache".CookieStyle Directive
Description: Format of the cookie header field Syntax: CookieStyle
Netscape|Cookie|Cookie2|RFC2109|RFC2965Default: CookieStyle NetscapeContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Extension Module: mod_usertrack
CookieStyle Netscape.CookieTracking Directive
Description: Enables tracking cookie Syntax: CookieTracking on|offDefault: CookieTracking offContext: server config, virtual host, directory, .htaccess Override: FileInfo Status: Extension Module: mod_usertrack mod_usertrack is loaded, and
CookieTracking on is set, Apache will send a
user-tracking cookie for all new requests. This directive can
be used to turn this behavior on or off on a per-server or
per-directory basis. By default, enabling
mod_usertrack will not
activate cookies.
mod/mod_vhost_alias.html 100644 0 0 37400 11074462673 13063 0 ustar 0 0
Apache Module mod_version
Description: Version dependent configuration Status: Extension Module Identifier: version_module Source File: mod_version.c Compatibility: Available in version 2.0.56 and later Summary
<IfVersion>, which
allows a flexible version checking including numeric comparisons and
regular expressions.Examples
<IfVersion 2.1.0>
# current httpd version is exactly 2.1.0
</IfVersion>
<IfVersion >= 2.2>
# use really new features :-)
</IfVersion>
Directives
<IfVersion> Directive
Description: contains version dependent configuration Syntax: <IfVersion [[!]operator] version> ...
</IfVersion>Context: server config, virtual host, directory, .htaccess Override: All Status: Extension Module: mod_version <IfVersion> section encloses
configuration directives which are executed only if the
httpd version
matches the desired criteria. For normal (numeric) comparisons the
version argument has the format
major[.minor[.patch]], e.g.
2.1.0 or 2.2. minor and
patch are optional. If these numbers are omitted, they are
assumed to be zero. The following numerical operators are
possible:operator description = or ==httpd version is equal >httpd version is greater than >=httpd version is greater or equal <httpd version is less than <=httpd version is less or equal Example
<IfVersion >= 2.1>
# this happens only in versions greater or
# equal 2.1.0.
</IfVersion>
operator description = or ==version has the form
/regex/~version has the form
regexExample
<IfVersion = /^2.1.[01234]$/>
# e.g. workaround for buggy versions
</IfVersion>
!):
<IfVersion !~ ^2.1.[01234]$>
# not for those versions
</IfVersion>
=.
mod/module-dict.html 100644 0 0 13345 11074462673 12120 0 ustar 0 0
Apache Module mod_vhost_alias
Description: Provides for dynamically configured mass virtual
hosting Status: Extension Module Identifier: vhost_alias_module Source File: mod_vhost_alias.c Summary
Host: header of
the HTTP request to be used as part of the pathname to
determine what files to serve. This allows for easy use of a
huge number of virtual hosts with similar configurations.Note
mod_alias or mod_userdir are
used for translating URIs to filenames, they will override the
directives of mod_vhost_alias described below. For
example, the following configuration will map
/cgi-bin/script.pl to
/usr/local/apache2/cgi-bin/script.pl in all cases:
ScriptAlias /cgi-bin/ /usr/local/apache2/cgi-bin/
VirtualScriptAlias /never/found/%0/cgi-bin/
Directives
Topics
See also
Directory Name Interpolation
UseCanonicalName
directive for details on how this is determined) or the IP
address of the virtual host on the server in dotted-quad
format. The interpolation is controlled by specifiers inspired
by printf which have a number of formats:
%%insert a %%pinsert the port number of the virtual host %N.Minsert (part of) the name N and M are used to specify
substrings of the name. N selects from the
dot-separated components of the name, and M
selects characters within whatever N has selected.
M is optional and defaults to zero if it isn't
present; the dot must be present if and only if M
is present. The interpretation is as follows:
0the whole name 1the first part 2the second part -1the last part -2the penultimate part 2+the second and all subsequent parts -2+the penultimate and all preceding parts 1+ and -1+the same as 0N or M is greater than the number
of parts available a single underscore is interpolated.
Examples
UseCanonicalName Off
VirtualDocumentRoot /usr/local/apache/vhosts/%0
http://www.example.com/directory/file.html will be
satisfied by the file
/usr/local/apache/vhosts/www.example.com/directory/file.html.
vhosts directory. To do this you might use the
following in your configuration file:
UseCanonicalName Off
VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2
http://www.domain.example.com/directory/file.html
will be satisfied by the file
/usr/local/apache/vhosts/example.com/d/o/m/domain/directory/file.html.
VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.-1/%2.-2/%2.-3/%2
/usr/local/apache/vhosts/example.com/n/i/a/domain/directory/file.html.
VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2.4+
/usr/local/apache/vhosts/example.com/d/o/m/ain/directory/file.html.
UseCanonicalName DNS
VirtualDocumentRootIP /usr/local/apache/vhosts/%1/%2/%3/%4/docs
VirtualScriptAliasIP /usr/local/apache/vhosts/%1/%2/%3/%4/cgi-bin
http://www.domain.example.com/directory/file.html
would be satisfied by the file
/usr/local/apache/vhosts/10/20/30/40/docs/directory/file.html
if the IP address of www.domain.example.com were
10.20.30.40. A request for
http://www.domain.example.com/cgi-bin/script.pl would
be satisfied by executing the program
/usr/local/apache/vhosts/10/20/30/40/cgi-bin/script.pl.. character in a
VirtualDocumentRoot directive, but it clashes with
a % directive, you can work around the problem in
the following way:
VirtualDocumentRoot /usr/local/apache/vhosts/%2.0.%3.0
http://www.domain.example.com/directory/file.html
will be satisfied by the file
/usr/local/apache/vhosts/domain.example/directory/file.html.LogFormat
directives %V and %A are useful
in conjunction with this module.VirtualDocumentRoot Directive
Description: Dynamically configure the location of the document root
for a given virtual host Syntax: VirtualDocumentRoot interpolated-directory|noneDefault: VirtualDocumentRoot noneContext: server config, virtual host Status: Extension Module: mod_vhost_alias VirtualDocumentRoot directive allows you to
determine where Apache will find your documents based on the
value of the server name. The result of expanding
interpolated-directory is used as the root of the
document tree in a similar manner to the DocumentRoot directive's argument.
If interpolated-directory is none then
VirtualDocumentRoot is turned off. This directive
cannot be used in the same context as VirtualDocumentRootIP.VirtualDocumentRootIP Directive
Description: Dynamically configure the location of the document root
for a given virtual host Syntax: VirtualDocumentRootIP interpolated-directory|noneDefault: VirtualDocumentRootIP noneContext: server config, virtual host Status: Extension Module: mod_vhost_alias VirtualDocumentRootIP directive is like the
VirtualDocumentRoot
directive, except that it uses the IP address of the server end
of the connection for directory interpolation instead of the server
name.VirtualScriptAlias Directive
Description: Dynamically configure the location of the CGI directory for
a given virtual host Syntax: VirtualScriptAlias interpolated-directory|noneDefault: VirtualScriptAlias noneContext: server config, virtual host Status: Extension Module: mod_vhost_alias VirtualScriptAlias directive allows you to
determine where Apache will find CGI scripts in a similar
manner to VirtualDocumentRoot does for other documents. It matches
requests for URIs starting /cgi-bin/, much like ScriptAlias
/cgi-bin/ would.VirtualScriptAliasIP Directive
Description: Dynamically configure the location of the cgi directory for
a given virtual host Syntax: VirtualScriptAliasIP interpolated-directory|noneDefault: VirtualScriptAliasIP noneContext: server config, virtual host Status: Extension Module: mod_vhost_alias VirtualScriptAliasIP directive is like the
VirtualScriptAlias
directive, except that it uses the IP address of the server end
of the connection for directory interpolation instead of the server
name.
mod/mpm_common.html 100644 0 0 203571 11074462673 12075 0 ustar 0 0
Terms Used to Describe Modules
Description
Status
Source File
<IfModule>
directive.
Module Identifier
LoadModule directive when
dynamically loading modules. In particular, it is the name of
the external variable of type module in the source file.
Compatibility
mod/mpm_netware.html 100644 0 0 17364 11074462673 12235 0 ustar 0 0
Apache MPM Common Directives
Description: A collection of directives that are implemented by
more than one multi-processing module (MPM) Status: MPM Directives
AcceptMutex BS2000Account CoreDumpDirectory EnableExceptionHook Group Listen ListenBackLog LockFile MaxClients MaxMemFree MaxRequestsPerChild MaxSpareThreads MinSpareThreads PidFile ReceiveBufferSize ScoreBoardFile SendBufferSize ServerLimit StartServers StartThreads ThreadLimit ThreadsPerChild UserAcceptMutex Directive
Description: Method that Apache uses to serialize multiple children
accepting requests on network sockets Syntax: AcceptMutex Default|methodDefault: AcceptMutex DefaultContext: server config Status: MPM Module: leader, perchild, prefork, threadpool, workerAcceptMutex directives sets the
method that Apache uses to serialize multiple children accepting
requests on network sockets. Prior to Apache 2.0, the method was
selectable only at compile time. The optimal method to use is
highly architecture and platform dependent. For further details,
see the performance tuning
documentation.Default, then the
compile-time selected default will be used. Other possible
methods are listed below. Note that not all methods are
available on all platforms. If a method is specified which is
not available, a message will be written to the error log
listing the available methods.
flockflock(2) system call to lock the
file defined by the LockFile directive.fcntlfcntl(2) system call to lock the
file defined by the LockFile directive.posixsempthreadsysvsemLogLevel to debug. Then the default AcceptMutex will be written into the ErrorLog.BS2000Account Directive
Description: Define the non-privileged account on BS2000
machines Syntax: BS2000Account accountContext: server config Status: MPM Module: perchild, preforkCompatibility: Only available for BS2000 machines BS2000Account directive is available for
BS2000 hosts only. It must be used to define the account number for
the non-privileged apache server user (which was configured using the
User directive). This is
required by the BS2000 POSIX subsystem (to change the underlying BS2000
task environment by performing a sub-LOGON) to prevent CGI scripts
from accessing resources of the privileged account which started the
server, usually SYSROOT.Note
BS2000Account directive can be used.See also
CoreDumpDirectory Directive
Description: Directory where Apache attempts to
switch before dumping core Syntax: CoreDumpDirectory directoryDefault: See usage for the default settingContext: server config Status: MPM Module: beos, leader, mpm_winnt, perchild, prefork, threadpool, workerServerRoot directory, however
since this should not be writable by the user the server runs
as, core dumps won't normally get written. If you want a core
dump for debugging, you can use this directive to place it in a
different location.Core Dumps on Linux
CoreDumpDirectory.EnableExceptionHook Directive
Description: Enables a hook that runs exception handlers
after a crash Syntax: EnableExceptionHook On|OffDefault: EnableExceptionHook OffContext: server config Status: MPM Module: leader, perchild, prefork, threadpool, workerCompatibility: Available in version 2.0.49 and later --enable-exception-hook option. It
enables a hook that allows external modules to plug in and do something
after a child crashed.mod_whatkilledus and
mod_backtrace that make use of this hook. Please have a
look at Jeff Trawick's EnableExceptionHook site for more information about these.Group Directive
Description: Group under which the server will answer
requests Syntax: Group unix-groupDefault: Group #-1Context: server config Status: MPM Module: beos, leader, mpmt_os2, perchild, prefork, threadpool, workerCompatibility: Only valid in global server config since Apache
2.0 Group directive sets the group under
which the server will answer requests. In order to use this
directive, the server must be run initially as root. If
you start the server as a non-root user, it will fail to change to the
specified group, and will instead continue to run as the group of the
original user. Unix-group is one of:
# followed by a group number.Example
Group www-group
nobody,
but this is not always possible or desirable.Security
Group (or User) to root unless
you know exactly what you are doing, and what the dangers are.<VirtualHost> is no longer supported. To
configure your server for suexec use
SuexecUserGroup.Listen Directive
Description: IP addresses and ports that the server
listens to Syntax: Listen [IP-address:]portnumberContext: server config Status: MPM Module: beos, leader, mpm_netware, mpm_winnt, mpmt_os2, perchild, prefork, threadpool, workerCompatibility: Required directive since Apache 2.0 Listen directive instructs Apache to
listen to only specific IP addresses or ports; by default it
responds to requests on all IP interfaces. Listen
is now a required directive. If it is not in the config file, the
server will fail to start. This is a change from previous versions
of Apache.Listen directive tells the server to
accept incoming requests on the specified port or address-and-port
combination. If only a port number is specified, the server listens to
the given port on all interfaces. If an IP address is given as well
as a port, the server will listen on the given port and
interface.Listen directives may be used to
specify a number of addresses and ports to listen to. The server will
respond to requests from any of the listed addresses and ports.
Listen 80
Listen 8000
Listen 192.170.2.1:80
Listen 192.170.2.5:8000
Listen [2001:db8::a00:20ff:fea7:ccea]:80
Error condition
Multiple Listen directives for the same ip
address and port will result in an Address already in use
error message.
See also
ListenBackLog Directive
Description: Maximum length of the queue of pending connections Syntax: ListenBacklog backlogDefault: ListenBacklog 511Context: server config Status: MPM Module: beos, leader, mpm_netware, mpm_winnt, mpmt_os2, perchild, prefork, threadpool, workerlisten(2) system call.LockFile Directive
Description: Location of the accept serialization lock file Syntax: LockFile filenameDefault: LockFile logs/accept.lockContext: server config Status: MPM Module: leader, perchild, prefork, threadpool, workerLockFile directive sets the path to
the lockfile used when Apache is used with an AcceptMutex value of either
fcntl or flock. This directive should
normally be left at its default value. The main reason for changing
it is if the logs directory is NFS mounted, since
the lockfile must be stored on a local disk. The PID
of the main server process is automatically appended to the
filename.Security
/var/tmp because someone could create
a denial of service attack and prevent the server from starting by
creating a lockfile with the same name as the one the server will try
to create.See also
MaxClients Directive
Description: Maximum number of child processes that will be created
to serve requests Syntax: MaxClients numberDefault: See usage for detailsContext: server config Status: MPM Module: beos, leader, prefork, threadpool, workerMaxClients directive sets the limit
on the number of simultaneous requests that will be served. Any
connection attempts over the MaxClients
limit will normally be queued, up to a number based on the
ListenBacklog
directive. Once a child process is freed at the end of a different
request, the connection will then be serviced.prefork),
MaxClients translates into the maximum
number of child processes that will be launched to serve requests.
The default value is 256; to increase it, you must also raise
ServerLimit.beos
or worker) MaxClients restricts
the total number of threads that will be available to serve clients.
The default value for beos is 50. For
hybrid MPMs the default value is 16 (ServerLimit) multiplied by the value of
25 (ThreadsPerChild). Therefore, to increase MaxClients to a value that requires more than 16 processes,
you must also raise ServerLimit.MaxMemFree Directive
Description: Maximum amount of memory that the main allocator is allowed
to hold without calling free()Syntax: MaxMemFree KBytesDefault: MaxMemFree 0Context: server config Status: MPM Module: beos, leader, mpm_netware, prefork, threadpool, worker, mpm_winntMaxMemFree directive sets the
maximum number of free Kbytes that the main allocator is allowed
to hold without calling free(). When not set, or when set
to zero, the threshold will be set to unlimited.MaxRequestsPerChild Directive
Description: Limit on the number of requests that an individual child server
will handle during its life Syntax: MaxRequestsPerChild numberDefault: MaxRequestsPerChild 10000Context: server config Status: MPM Module: leader, mpm_netware, mpm_winnt, mpmt_os2, perchild, prefork, threadpool, workerMaxRequestsPerChild directive sets
the limit on the number of requests that an individual child
server process will handle. After
MaxRequestsPerChild requests, the child
process will die. If MaxRequestsPerChild is
0, then the process will never expire.Different default values
mpm_netware and
mpm_winnt is 0.MaxRequestsPerChild to a
non-zero limit has two beneficial effects:
Note
KeepAlive requests, only
the first request is counted towards this limit. In effect, it
changes the behavior to limit the number of connections per
child.MaxSpareThreads Directive
Description: Maximum number of idle threads Syntax: MaxSpareThreads numberDefault: See usage for detailsContext: server config Status: MPM Module: beos, leader, mpm_netware, mpmt_os2, perchild, threadpool, workerperchild the default is
MaxSpareThreads 10. This MPM monitors the number of
idle threads on a per-child basis. If there are too many idle
threads in that child, the server will begin to kill threads
within that child.worker, leader and threadpool the default is MaxSpareThreads 250.
These MPMs deal with idle threads on a server-wide basis. If there
are too many idle threads in the server then child processes are
killed until the number of idle threads is less than this number.mpm_netware the default is
MaxSpareThreads 100. Since this MPM runs a
single-process, the spare thread count is also server-wide.beos and mpmt_os2 work
similar to mpm_netware. The default for
beos is MaxSpareThreads 50. For
mpmt_os2 the default value is 10.Restrictions
MaxSpareThreads value
is restricted. Apache will correct the given value automatically
according to the following rules:
perchild requires MaxSpareThreads to be less or equal than ThreadLimit.mpm_netware wants the value to be greater than
MinSpareThreads.leader, threadpool and
worker the value must be greater or equal than
the sum of MinSpareThreads
and ThreadsPerChild.See also
MinSpareThreads Directive
Description: Minimum number of idle threads available to handle request
spikes Syntax: MinSpareThreads numberDefault: See usage for detailsContext: server config Status: MPM Module: beos, leader, mpm_netware, mpmt_os2, perchild, threadpool, workerperchild uses a default of
MinSpareThreads 5 and monitors the number of idle
threads on a per-child basis. If there aren't enough idle threads
in that child, the server will begin to create new threads within
that child. Thus, if you set NumServers to 10 and a MinSpareThreads value of 5, you'll have
at least 50 idle threads on your system.worker, leader and
threadpool use a default of MinSpareThreads
75 and deal with idle threads on a server-wide basis. If
there aren't enough idle threads in the server then child
processes are created until the number of idle threads is greater
than number.mpm_netware uses a default of
MinSpareThreads 10 and, since it is a single-process
MPM, tracks this on a server-wide bases.beos and mpmt_os2 work
similar to mpm_netware. The default for
beos is MinSpareThreads 1. For
mpmt_os2 the default value is 5.See also
PidFile Directive
Description: File where the server records the process ID
of the daemon Syntax: PidFile filenameDefault: PidFile logs/httpd.pidContext: server config Status: MPM Module: beos, leader, mpm_winnt, mpmt_os2, perchild, prefork, threadpool, workerPidFile directive sets the file to
which the server records the process id of the daemon. If the
filename is not absolute then it is assumed to be relative to the
ServerRoot.Example
PidFile /var/run/apache.pid
ErrorLog and TransferLog, and
re-reads its configuration files. This is done by sending a
SIGHUP (kill -1) signal to the process id listed in the
PidFile.PidFile is subject to the same
warnings about log file placement and security.Note
apachectl script for (re-)starting or stopping the server.ReceiveBufferSize Directive
Description: TCP receive buffer size Syntax: ReceiveBufferSize bytesDefault: ReceiveBufferSize 0Context: server config Status: MPM Module: beos, leader, mpm_netware, mpm_winnt, mpmt_os2, perchild, prefork, threadpool, worker0, the server will use the
OS default.ScoreBoardFile Directive
Description: Location of the file used to store coordination data for
the child processes Syntax: ScoreBoardFile file-pathDefault: ScoreBoardFile logs/apache_statusContext: server config Status: MPM Module: beos, leader, mpm_winnt, perchild, prefork, threadpool, workerExample
ScoreBoardFile /var/run/apache_status
ScoreBoardFile then
you may see improved speed by placing it on a RAM disk. But be
careful that you heed the same warnings about log file placement
and security.See also
SendBufferSize Directive
Description: TCP buffer size Syntax: SendBufferSize bytesDefault: SendBufferSize 0Context: server config Status: MPM Module: beos, leader, mpm_netware, mpm_winnt, mpmt_os2, perchild, prefork, threadpool, worker0, the server will use the
OS default.ServerLimit Directive
Description: Upper limit on configurable number of processes Syntax: ServerLimit numberDefault: See usage for detailsContext: server config Status: MPM Module: leader, perchild, prefork, threadpool, workerprefork MPM, this directive sets the
maximum configured value for MaxClients for the lifetime of the
Apache process. For the worker MPM, this directive
in combination with ThreadLimit sets
the maximum configured value for MaxClients for the lifetime of the
Apache process. Any attempts to change this directive during a
restart will be ignored, but MaxClients can be modified during
a restart.ServerLimit is set to a value much higher
than necessary, extra, unused shared memory will be allocated. If
both ServerLimit and MaxClients are set to values
higher than the system can handle, Apache may not start or the
system may become unstable.prefork MPM, use this directive only
if you need to set MaxClients higher than 256 (default).
Do not set the value of this directive any higher than what you
might want to set MaxClients to.worker, leader and
threadpool use this directive only
if your MaxClients and
ThreadsPerChild
settings require more than 16 server processes (default). Do not set
the value of this directive any higher than the number of server
processes required by what you may want for MaxClients and ThreadsPerChild.perchild MPM, use this directive only
if you need to set NumServers higher than 8 (default).Note
ServerLimit 20000 compiled
into the server. This is intended to avoid nasty effects caused by
typos.See also
StartServers Directive
Description: Number of child server processes created at startup Syntax: StartServers numberDefault: See usage for detailsContext: server config Status: MPM Module: leader, mpmt_os2, prefork, threadpool, workerStartServers directive sets the
number of child server processes created on startup. As the number
of processes is dynamically controlled depending on the load,
there is usually little reason to adjust this parameter.leader, threadpool and
worker the default is StartServers 3.
For prefork defaults to 5 and for
mpmt_os2 to 2.StartThreads Directive
Description: Number of threads created on startup Syntax: StartThreads numberDefault: See usage for detailsContext: server config Status: MPM Module: beos, mpm_netware, perchildperchild the default is StartThreads
5 and this directive tracks the number of threads per
process at startup.mpm_netware the default is
StartThreads 50 and, since there is only a single
process, this is the total number of threads created at startup to
serve requests.beos the default is StartThreads
10. It also reflects the total number of threads created
at startup to serve requests.ThreadLimit Directive
Description: Sets the upper limit on the configurable number of threads
per child process Syntax: ThreadLimit numberDefault: See usage for detailsContext: server config Status: MPM Module: leader, mpm_winnt, perchild, threadpool, workerCompatibility: Available for mpm_winnt in Apache 2.0.41
and laterThreadsPerChild for the lifetime
of the Apache process. Any attempts to change this directive
during a restart will be ignored, but ThreadsPerChild can be modified
during a restart up to the value of this directive.ThreadLimit is set to a value much higher
than ThreadsPerChild,
extra unused shared memory will be allocated. If both
ThreadLimit and ThreadsPerChild are set to values
higher than the system can handle, Apache may not start or the
system may become unstable. Do not set the value of this directive
any higher than your greatest predicted setting of ThreadsPerChild for the
current run of Apache.ThreadLimit is
1920 when used with mpm_winnt and
64 when used with the others.Note
ThreadLimit 20000 (or
ThreadLimit 15000 with mpm_winnt)
compiled into the server. This is intended to avoid nasty effects
caused by typos.ThreadsPerChild Directive
Description: Number of threads created by each child process Syntax: ThreadsPerChild numberDefault: See usage for detailsContext: server config Status: MPM Module: leader, mpm_winnt, threadpool, workermpm_winnt,
where there is only one child process, this number should be high
enough to handle the entire load of the server. If using an MPM
like worker, where there are multiple child processes,
the total number of threads should be high enough to handle
the common load on the server.ThreadsPerChild is
64 when used with mpm_winnt and
25 when used with the others.User Directive
Description: The userid under which the server will answer
requests Syntax: User unix-useridDefault: User #-1Context: server config Status: MPM Module: leader, perchild, prefork, threadpool, workerCompatibility: Only valid in global server config since Apache
2.0 User directive sets the user ID as
which the server will answer requests. In order to use this
directive, the server must be run initially as root.
If you start the server as a non-root user, it will fail to change
to the lesser privileged user, and will instead continue to run as
that original user. If you do start the server as root,
then it is normal for the parent process to remain running as root.
Unix-userid is one of:
nobody, but
this is not always desirable, since the nobody user
can have other uses on the system.Security
User (or Group) to root unless
you know exactly what you are doing, and what the dangers are.perchild MPM, which is intended to
server virtual hosts run under different user IDs, the
User directive defines the user ID for the
main server and the fallback for <VirtualHost> sections without an
AssignUserID directive.<VirtualHost> is no longer supported. To
configure your server for suexec use
SuexecUserGroup.
Apache MPM netware
Description: Multi-Processing Module implementing an exclusively threaded web
server optimized for Novell NetWare Status: MPM Module Identifier: mpm_netware_module Source File: mpm_netware.c Summary
StartThreads,
MinSpareThreads,
MaxSpareThreads, and
MaxThreads
regulate how the main thread creates worker threads to serve
requests. In general, Apache is very self-regulat