From 07050bb5be522bbf66bb8f053b53beefa295ee68 Mon Sep 17 00:00:00 2001 From: Ken Coar Date: Mon, 26 Jan 1998 16:54:35 +0000 Subject: [PATCH] A truly mighty mod normalising HTML tags to uppercase, and 'i' and 'b' to 'EM' and 'STRONG' respectively. Been threatening to do this for months.. no-one need try to maintain this when writing/modifiying the docs. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@80021 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/bind.html | 72 +- docs/manual/bind.html.en | 72 +- docs/manual/cgi_path.html | 68 +- docs/manual/cgi_path.html.en | 68 +- docs/manual/content-negotiation.html | 388 ++--- docs/manual/content-negotiation.html.en | 388 ++--- docs/manual/custom-error.html | 74 +- docs/manual/custom-error.html.en | 74 +- docs/manual/developer/API.html | 632 +++---- docs/manual/dns-caveats.html | 134 +- docs/manual/env.html | 4 +- docs/manual/env.html.en | 4 +- docs/manual/handler.html | 140 +- docs/manual/handler.html.en | 140 +- docs/manual/install.html | 12 +- docs/manual/install.html.en | 12 +- docs/manual/invoking.html | 86 +- docs/manual/invoking.html.en | 86 +- docs/manual/location.html | 34 +- docs/manual/misc/API.html | 632 +++---- docs/manual/misc/FAQ.html | 6 +- docs/manual/misc/client_block_api.html | 42 +- docs/manual/misc/compat_notes.html | 30 +- docs/manual/misc/descriptors.html | 102 +- docs/manual/misc/fin_wait_2.html | 2 +- docs/manual/misc/howto.html | 58 +- docs/manual/misc/index.html | 2 +- docs/manual/misc/known_client_problems.html | 176 +- docs/manual/misc/perf-tuning.html | 500 +++--- docs/manual/misc/security_tips.html | 62 +- docs/manual/mod/core.html | 1726 +++++++++---------- docs/manual/mod/directives.html | 346 ++-- docs/manual/mod/index.html | 170 +- docs/manual/mod/mod_access.html | 224 +-- docs/manual/mod/mod_actions.html | 66 +- docs/manual/mod/mod_alias.html | 214 +-- docs/manual/mod/mod_asis.html | 54 +- docs/manual/mod/mod_auth.html | 110 +- docs/manual/mod/mod_auth_anon.html | 278 +-- docs/manual/mod/mod_auth_db.html | 114 +- docs/manual/mod/mod_auth_dbm.html | 114 +- docs/manual/mod/mod_autoindex.html | 374 ++-- docs/manual/mod/mod_cern_meta.html | 78 +- docs/manual/mod/mod_cgi.html | 122 +- docs/manual/mod/mod_dir.html | 60 +- docs/manual/mod/mod_env.html | 68 +- docs/manual/mod/mod_example.html | 2 +- docs/manual/mod/mod_expires.html | 18 +- docs/manual/mod/mod_headers.html | 58 +- docs/manual/mod/mod_imap.html | 326 ++-- docs/manual/mod/mod_include.html | 246 +-- docs/manual/mod/mod_info.html | 18 +- docs/manual/mod/mod_isapi.html | 42 +- docs/manual/mod/mod_log_agent.html | 42 +- docs/manual/mod/mod_log_config.html | 182 +- docs/manual/mod/mod_log_referer.html | 62 +- docs/manual/mod/mod_mime.html | 220 +-- docs/manual/mod/mod_mime_magic.html | 126 +- docs/manual/mod/mod_negotiation.html | 112 +- docs/manual/mod/mod_proxy.html | 462 ++--- docs/manual/mod/mod_rewrite.html | 1422 +++++++-------- docs/manual/mod/mod_speling.html | 46 +- docs/manual/mod/mod_status.html | 62 +- docs/manual/mod/mod_unique_id.html | 64 +- docs/manual/mod/mod_userdir.html | 40 +- docs/manual/mod/mod_usertrack.html | 60 +- docs/manual/platform/perf-bsd44.html | 118 +- docs/manual/platform/perf-dec.html | 4 +- docs/manual/platform/perf-hp.html | 12 +- docs/manual/platform/perf.html | 26 +- docs/manual/platform/unixware.html | 22 +- docs/manual/platform/windows.html | 256 +-- docs/manual/process-model.html | 2 +- docs/manual/sections.html | 122 +- docs/manual/sections.html.en | 122 +- docs/manual/stopping.html | 84 +- docs/manual/stopping.html.en | 84 +- docs/manual/suexec.html | 24 +- docs/manual/suexec.html.en | 24 +- docs/manual/vhosts/details.html | 252 +-- docs/manual/vhosts/details_1_2.html | 262 +-- docs/manual/vhosts/examples.html | 350 ++-- docs/manual/vhosts/fd-limits.html | 44 +- docs/manual/vhosts/fd-limits.html.en | 44 +- docs/manual/vhosts/host.html | 148 +- docs/manual/vhosts/index.html | 10 +- docs/manual/vhosts/index.html.en | 10 +- docs/manual/vhosts/ip-based.html | 52 +- docs/manual/vhosts/name-based.html | 122 +- docs/manual/vhosts/name-based.html.en | 122 +- docs/manual/vhosts/vhosts-in-depth.html | 262 +-- docs/manual/vhosts/virtual-host.html | 138 +- 92 files changed, 7272 insertions(+), 7272 deletions(-) diff --git a/docs/manual/bind.html b/docs/manual/bind.html index 2398082a14..3b31b437a2 100644 --- a/docs/manual/bind.html +++ b/docs/manual/bind.html @@ -1,7 +1,7 @@ - -Setting which addresses and ports Apache uses - + +Setting which addresses and ports Apache uses + -

Setting which addresses and ports Apache uses

+

Setting which addresses and ports Apache uses

-
+
When Apache starts, it connects to some port and address on the local machine and waits for incoming requests. By default, it listens to all addresses on the machine, and to the port -as specified by the Port directive in the server configuration. +as specified by the Port directive in the server configuration. However, it can be told to listen to more the one port, or to listen to 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.

+responds to different IP addresses, hostnames and ports.

There are two directives used to restrict or specify which addresses and ports Apache listens to. -

-

BindAddress

-Syntax: BindAddress [ * | IP-address | hostname ]
-Default: BindAddress *
-Context: server config
-Status: Core

+

BindAddress

+Syntax: BindAddress [ * | IP-address | hostname ]
+Default: BindAddress *
+Context: server config
+Status: Core

Makes the server listen to just the specified address. If the argument is *, the server listens to all addresses. The port listened to -is set with the Port directive. Only one BindAddress +is set with the Port directive. Only one BindAddress should be used. -

Listen

-Syntax: Listen [ port | IP-address:port ]
-Default: none
-Context: server config
-Status: Core

+

Listen

+Syntax: Listen [ port | IP-address:port ]
+Default: none
+Context: server config
+Status: Core

-Listen can be used instead of BindAddress and -Port. It tells the server to accept incoming requests on the +Listen can be used instead of BindAddress and +Port. It tells the server to accept incoming requests on the specified port or address-and-port combination. If the first format is used, with a port number only, the server listens to the given port on -all interfaces, instead of the port given by the Port +all interfaces, instead of the port given by the Port directive. If an IP address is given as well as a port, the server -will listen on the given port and interface.

Multiple Listen +will listen on the given port and interface.

Multiple 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.

+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
-

+

How this works with Virtual Hosts

@@ -95,12 +95,12 @@ not listening to, it cannot be accessed.

See also

See also the documentation on -Virtual Hosts, -BindAddress directive, -Port directive, -DNS Issues +Virtual Hosts, +BindAddress directive, +Port directive, +DNS Issues and -<VirtualHost> section. +<VirtualHost> section. diff --git a/docs/manual/bind.html.en b/docs/manual/bind.html.en index 2398082a14..3b31b437a2 100644 --- a/docs/manual/bind.html.en +++ b/docs/manual/bind.html.en @@ -1,7 +1,7 @@ - -Setting which addresses and ports Apache uses - + +Setting which addresses and ports Apache uses + -

Setting which addresses and ports Apache uses

+

Setting which addresses and ports Apache uses

-
+
When Apache starts, it connects to some port and address on the local machine and waits for incoming requests. By default, it listens to all addresses on the machine, and to the port -as specified by the Port directive in the server configuration. +as specified by the Port directive in the server configuration. However, it can be told to listen to more the one port, or to listen to 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.

+responds to different IP addresses, hostnames and ports.

There are two directives used to restrict or specify which addresses and ports Apache listens to. -

-

BindAddress

-Syntax: BindAddress [ * | IP-address | hostname ]
-Default: BindAddress *
-Context: server config
-Status: Core

+

BindAddress

+Syntax: BindAddress [ * | IP-address | hostname ]
+Default: BindAddress *
+Context: server config
+Status: Core

Makes the server listen to just the specified address. If the argument is *, the server listens to all addresses. The port listened to -is set with the Port directive. Only one BindAddress +is set with the Port directive. Only one BindAddress should be used. -

Listen

-Syntax: Listen [ port | IP-address:port ]
-Default: none
-Context: server config
-Status: Core

+

Listen

+Syntax: Listen [ port | IP-address:port ]
+Default: none
+Context: server config
+Status: Core

-Listen can be used instead of BindAddress and -Port. It tells the server to accept incoming requests on the +Listen can be used instead of BindAddress and +Port. It tells the server to accept incoming requests on the specified port or address-and-port combination. If the first format is used, with a port number only, the server listens to the given port on -all interfaces, instead of the port given by the Port +all interfaces, instead of the port given by the Port directive. If an IP address is given as well as a port, the server -will listen on the given port and interface.

Multiple Listen +will listen on the given port and interface.

Multiple 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.

+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
-

+

How this works with Virtual Hosts

@@ -95,12 +95,12 @@ not listening to, it cannot be accessed.

See also

See also the documentation on -Virtual Hosts, -BindAddress directive, -Port directive, -DNS Issues +Virtual Hosts, +BindAddress directive, +Port directive, +DNS Issues and -<VirtualHost> section. +<VirtualHost> section. diff --git a/docs/manual/cgi_path.html b/docs/manual/cgi_path.html index 8ac3bc0dd1..ed95efcd42 100644 --- a/docs/manual/cgi_path.html +++ b/docs/manual/cgi_path.html @@ -1,7 +1,7 @@ - -PATH_INFO Changes in the CGI Environment - + +PATH_INFO Changes in the CGI Environment + -

PATH_INFO Changes in the CGI Environment

+

PATH_INFO Changes in the CGI Environment

-
+
-

Overview

+

Overview

-

As implemented in Apache 1.1.1 and earlier versions, the method +

As implemented in Apache 1.1.1 and earlier versions, the method Apache used to create PATH_INFO in the CGI environment was counterintuitive, and could result in crashes in certain cases. In Apache 1.2 and beyond, this behavior has changed. Although this results in some compatibility problems with certain legacy CGI applications, the Apache 1.2 behavior is still compatible with the -CGI/1.1 specification, and CGI scripts can be easily modified (see below). +CGI/1.1 specification, and CGI scripts can be easily modified (see below). -

The Problem

+

The Problem

-

Apache 1.1.1 and earlier implemented the PATH_INFO and SCRIPT_NAME +

Apache 1.1.1 and earlier implemented the PATH_INFO and SCRIPT_NAME environment variables by looking at the filename, not the URL. While this resulted in the correct values in many cases, when the filesystem path was overloaded to contain path information, it could result in errant behavior. For example, if the following appeared in a config file: -

+
      Alias /cgi-ralph /usr/local/httpd/cgi-bin/user.cgi/ralph
-

-
In this case, user.cgi is the CGI script, the "/ralph"
+
+

In this case, user.cgi is the CGI script, the "/ralph" is information to be passed onto the CGI. If this configuration was in -place, and a request came for "/cgi-ralph/script/", the -code would set PATH_INFO to "/ralph/script", and -SCRIPT_NAME to "/cgi-". Obviously, the latter is +place, and a request came for "/cgi-ralph/script/", the +code would set PATH_INFO to "/ralph/script", and +SCRIPT_NAME to "/cgi-". Obviously, the latter is incorrect. In certain cases, this could even cause the server to -crash.

+crash.

-

The Solution

+

The Solution

-

Apache 1.2 and later now determine SCRIPT_NAME and PATH_INFO by +

Apache 1.2 and later now determine SCRIPT_NAME and PATH_INFO by looking directly at the URL, and determining how much of the URL is client-modifiable, and setting PATH_INFO to it. To use the above -example, PATH_INFO would be set to "/script", and -SCRIPT_NAME to "/cgi-ralph". This makes sense and results +example, PATH_INFO would be set to "/script", and +SCRIPT_NAME to "/cgi-ralph". This makes sense and results in no server behavior problems. It also permits the script to be guaranteed that -"http://$SERVER_NAME:$SERVER_PORT$SCRIPT_NAME$PATH_INFO" +"http://$SERVER_NAME:$SERVER_PORT$SCRIPT_NAME$PATH_INFO" will always be an accessible URL that points to the current script, something which was not necessarily true with previous versions of Apache. -

However, the "/ralph" -information from the Alias directive is lost. This is +

However, the "/ralph" +information from the Alias directive is lost. This is unfortunate, but we feel that using the filesystem to pass along this sort of information is not a recommended method, and a script making use of it "deserves" not to work. Apache 1.2b3 and later, however, do -provide a workaround. +provide a workaround. -

Compatibility with Previous Servers

+

Compatibility with Previous Servers

-

It may be necessary for a script that was designed for earlier +

It may be necessary for a script that was designed for earlier versions of Apache or other servers to need the information that the old PATH_INFO variable provided. For this purpose, Apache 1.2 (1.2b3 and later) sets an additional variable, FILEPATH_INFO. This environment variable contains the value that PATH_INFO would have had -with Apache 1.1.1.

+with Apache 1.1.1.

-

A script that wishes to work with both Apache 1.2 and earlier +

A script that wishes to work with both Apache 1.2 and earlier versions can simply test for the existence of FILEPATH_INFO, and use it if available. Otherwise, it can use PATH_INFO. For example, in Perl, one might use: -

+
     $path_info = $ENV{'FILEPATH_INFO'} || $ENV{'PATH_INFO'};
-

+
-

By doing this, a script can work with all servers supporting the -CGI/1.1 specification, including all versions of Apache.

+

By doing this, a script can work with all servers supporting the +CGI/1.1 specification, including all versions of Apache.

diff --git a/docs/manual/cgi_path.html.en b/docs/manual/cgi_path.html.en index 8ac3bc0dd1..ed95efcd42 100644 --- a/docs/manual/cgi_path.html.en +++ b/docs/manual/cgi_path.html.en @@ -1,7 +1,7 @@ - -PATH_INFO Changes in the CGI Environment - + +PATH_INFO Changes in the CGI Environment + -

PATH_INFO Changes in the CGI Environment

+

PATH_INFO Changes in the CGI Environment

-
+
-

Overview

+

Overview

-

As implemented in Apache 1.1.1 and earlier versions, the method +

As implemented in Apache 1.1.1 and earlier versions, the method Apache used to create PATH_INFO in the CGI environment was counterintuitive, and could result in crashes in certain cases. In Apache 1.2 and beyond, this behavior has changed. Although this results in some compatibility problems with certain legacy CGI applications, the Apache 1.2 behavior is still compatible with the -CGI/1.1 specification, and CGI scripts can be easily modified (see below). +CGI/1.1 specification, and CGI scripts can be easily modified (see below). -

The Problem

+

The Problem

-

Apache 1.1.1 and earlier implemented the PATH_INFO and SCRIPT_NAME +

Apache 1.1.1 and earlier implemented the PATH_INFO and SCRIPT_NAME environment variables by looking at the filename, not the URL. While this resulted in the correct values in many cases, when the filesystem path was overloaded to contain path information, it could result in errant behavior. For example, if the following appeared in a config file: -

+
      Alias /cgi-ralph /usr/local/httpd/cgi-bin/user.cgi/ralph
-

-
In this case, user.cgi is the CGI script, the "/ralph"
+
+

In this case, user.cgi is the CGI script, the "/ralph" is information to be passed onto the CGI. If this configuration was in -place, and a request came for "/cgi-ralph/script/", the -code would set PATH_INFO to "/ralph/script", and -SCRIPT_NAME to "/cgi-". Obviously, the latter is +place, and a request came for "/cgi-ralph/script/", the +code would set PATH_INFO to "/ralph/script", and +SCRIPT_NAME to "/cgi-". Obviously, the latter is incorrect. In certain cases, this could even cause the server to -crash.

+crash.

-

The Solution

+

The Solution

-

Apache 1.2 and later now determine SCRIPT_NAME and PATH_INFO by +

Apache 1.2 and later now determine SCRIPT_NAME and PATH_INFO by looking directly at the URL, and determining how much of the URL is client-modifiable, and setting PATH_INFO to it. To use the above -example, PATH_INFO would be set to "/script", and -SCRIPT_NAME to "/cgi-ralph". This makes sense and results +example, PATH_INFO would be set to "/script", and +SCRIPT_NAME to "/cgi-ralph". This makes sense and results in no server behavior problems. It also permits the script to be guaranteed that -"http://$SERVER_NAME:$SERVER_PORT$SCRIPT_NAME$PATH_INFO" +"http://$SERVER_NAME:$SERVER_PORT$SCRIPT_NAME$PATH_INFO" will always be an accessible URL that points to the current script, something which was not necessarily true with previous versions of Apache. -

However, the "/ralph" -information from the Alias directive is lost. This is +

However, the "/ralph" +information from the Alias directive is lost. This is unfortunate, but we feel that using the filesystem to pass along this sort of information is not a recommended method, and a script making use of it "deserves" not to work. Apache 1.2b3 and later, however, do -provide a workaround. +provide a workaround. -

Compatibility with Previous Servers

+

Compatibility with Previous Servers

-

It may be necessary for a script that was designed for earlier +

It may be necessary for a script that was designed for earlier versions of Apache or other servers to need the information that the old PATH_INFO variable provided. For this purpose, Apache 1.2 (1.2b3 and later) sets an additional variable, FILEPATH_INFO. This environment variable contains the value that PATH_INFO would have had -with Apache 1.1.1.

+with Apache 1.1.1.

-

A script that wishes to work with both Apache 1.2 and earlier +

A script that wishes to work with both Apache 1.2 and earlier versions can simply test for the existence of FILEPATH_INFO, and use it if available. Otherwise, it can use PATH_INFO. For example, in Perl, one might use: -

+
     $path_info = $ENV{'FILEPATH_INFO'} || $ENV{'PATH_INFO'};
-

+
-

By doing this, a script can work with all servers supporting the -CGI/1.1 specification, including all versions of Apache.

+

By doing this, a script can work with all servers supporting the +CGI/1.1 specification, including all versions of Apache.

diff --git a/docs/manual/content-negotiation.html b/docs/manual/content-negotiation.html index c6b096a688..2a0abb5ccd 100644 --- a/docs/manual/content-negotiation.html +++ b/docs/manual/content-negotiation.html @@ -13,25 +13,25 @@ ALINK="#FF0000" > -

Content Negotiation

+

Content Negotiation

-

+

Apache's support for content negotiation has been updated to meet 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 is also implements a couple of features to give more intelligent handling of requests from -browsers which send incomplete negotiation information.

+browsers which send incomplete negotiation information.

Content negotiation is provided by the -mod_negotiation module, +mod_negotiation module, which is compiled in by default. -

+

About Content Negotiation

-

+

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 @@ -44,14 +44,14 @@ 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 @@ -59,54 +59,54 @@ 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 1.2 supports 'server driven' content negotiation, as defined in the HTTP/1.1 specification. It fully supports the Accept, Accept-Language, Accept-Charset and Accept-Encoding request headers. -

+

-The terms used in content negotiation are: a resource is an +The terms used in content negotiation are: a resource is an item which can be requested of a server, which might be selected as the result of a content negotiation algorithm. If a resource is -available in several formats, these are called representations -or variants. The ways in which the variants for a particular -resource vary are called the dimensions of negotiation. +available in several formats, these are called representations +or variants. The ways in which the variants for a particular +resource vary are called the dimensions of negotiation.

Negotiation in Apache

-

+

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: -

Using a type-map file

-

+

A type map is a document which is associated with the handler -named type-map (or, for backwards-compatibility with +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've got to have a SetHandler some place which defines a -file suffix as type-map; this is best done with a -

+application/x-type-map).  Note that to use this feature,
+you've got to have a SetHandler some place which defines a
+file suffix as type-map; this is best done with a
+
 
   AddHandler type-map var
 
-

-in srm.conf.  See comments in the sample config files for
-details. 

+
+in srm.conf. See comments in the sample config files for +details.

Type map files have an entry for each available variant; these entries consist of contiguous RFC822-format header lines. Entries for @@ -115,7 +115,7 @@ 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: -

+
 
   URI: foo
 
@@ -126,12 +126,12 @@ map file is:
   URI: foo.fr.de.html
   Content-type: text/html; charset=iso-8859-2
   Content-language: fr, de
-

+
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
@@ -143,83 +143,83 @@ as jpeg, gif, or ASCII-art):
   URI: foo.txt
   Content-type: text/plain; qs=0.01
 
-

-

+
+

qs values can vary between 0.000 and 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.

+parameter value are given a qs factor of 1.0.

The full list of headers recognized is: -

-
URI: -
uri of the file containing the variant (of the given media +
+
URI: +
uri of the file containing the variant (of the given media type, encoded with the given content encoding). These are interpreted as URLs relative to the map file; they must be on the same server (!), and they must refer to files to which the client would be granted access if they were to be requested directly. -
Content-type: -
media type --- charset, level and "qs" parameters may be given. These +
Content-type: +
media type --- charset, level and "qs" parameters may be given. These are often referred to as MIME types; typical media types are - image/gif, text/plain, or - text/html; level=3. -
Content-language: -
The languages of the variant, specified as an Internet standard - language code (e.g., en for English, - kr for Korean, etc.). -
Content-encoding: -
If the file is compressed, or otherwise encoded, rather than + image/gif, text/plain, or + text/html; level=3. +
Content-language: +
The languages of the variant, specified as an Internet standard + language code (e.g., en for English, + kr for Korean, etc.). +
Content-encoding: +
If the file is compressed, or otherwise encoded, rather than containing the actual raw data, this says how that was done. For compressed files (the only case where this generally comes up), content encoding should be - x-compress, or x-gzip, as appropriate. -
Content-length: -
The size of the file. Clients can ask to receive a given media + x-compress, or x-gzip, as appropriate. +
Content-length: +
The size of the file. Clients can ask to receive a given media type only if the variant isn't too big; specifying a content length in the map allows the server to compare against these thresholds without checking the actual file. -
+

Multiviews

-

+

This is a per-directory option, meaning it can be set with an -Options directive within a <Directory>, -<Location> or <Files> -section in access.conf, or (if AllowOverride -is properly set) in .htaccess files. Note that -Options All does not set MultiViews; you +Options directive within a <Directory>, +<Location> or <Files> +section in access.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. (Fixing this is a one-line change to -http_core.h). +http_core.h). -

+

-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 +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, and forwards them along. -

+

This applies to searches for the file named by the -DirectoryIndex directive, if the server is trying to +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.
+
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 directive is a CGI script, it's not obvious what should happen. The code gives that case @@ -238,7 +238,7 @@ any. To do this it calculates a quality value for each variant in each of the dimensions of variance. 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 in detail the algorithm used for those interested.

+explains in detail the algorithm used for those interested.

In some circumstances, Apache can 'fiddle' the quality factor of a particular dimension to achieve a better result. The ways Apache can @@ -246,93 +246,93 @@ fiddle quality factors is explained in more detail below.

Dimensions of Negotiation

- -
Dimension -Notes -
Media Type -Browser indicates preferences on Accept: header. Each item + +
Dimension +Notes +
Media Type +Browser indicates preferences on Accept: header. Each item can have an associated quality factor. Variant description can also have a quality factor. -
Language -Browser indicates preferences on Accept-Language: header. Each +
Language +Browser indicates preferences on Accept-Language: header. Each item can have a quality factor. Variants can be associated with none, one or more languages. -
Encoding -Browser indicates preference with Accept-Encoding: header. -
Charset -Browser indicates preference with Accept-Charset: header. Variants +
Encoding +Browser indicates preference with Accept-Encoding: header. +
Charset +Browser indicates preference with Accept-Charset: header. Variants can indicate a charset as a parameter of the media type. -
+

Apache Negotiation Algorithm

-

+

Apache uses an algorithm to select the 'best' variant (if any) to return to the browser. This algorithm is not configurable. It operates like this: -

    -
  1. +
      +
    1. Firstly, for each dimension of the negotiation, the appropriate Accept header is checked and a quality assigned to this each variant. If the Accept header for any dimension means that this variant is not acceptable, eliminate it. If no variants remain, go to step 4. -
    2. Select the 'best' variant by a process of elimination. Each of +
    3. Select the 'best' variant by a process of elimination. Each of the following tests is applied in order. Any variants not selected at each stage are eliminated. After each test, if only one variant remains, it is selected as the best match. If more than one variant remains, move onto the next test. -
        -
      1. Multiply the quality factor from the Accept header with the +
          +
        1. Multiply the quality factor from the Accept header with the quality-of-source factor for this variant's media type, and select the variants with the highest value -
        2. Select the variants with the highest language quality factor +
        3. Select the variants with the highest language quality factor -
        4. Select the variants with the best language match, using either the - order of languages on the LanguagePriority directive (if present), +
        5. Select the variants with the best language match, using either the + order of languages on the LanguagePriority directive (if present), else the order of languages on the Accept-Language header. -
        6. Select the variants with the highest 'level' media parameter +
        7. Select the variants with the highest 'level' media parameter (used to give the version of text/html media types). -
        8. Select only unencoded variants, if there is a mix of encoded +
        9. Select only unencoded variants, if there is a mix of encoded and non-encoded variants. If either all variants are encoded or all variants are not encoded, select all. -
        10. Select only variants with acceptable charset media parameters, +
        11. Select only variants with acceptable charset media parameters, as given on the Accept-Charset header line. Charset ISO-8859-1 is always acceptable. Variants not associated with a particular charset are assumed to be in ISO-8859-1. -
        12. Select the variants with the smallest content length +
        13. Select the variants with the smallest content length -
        14. Select the first variant of those remaining (this will be either the +
        15. Select the first variant of those remaining (this will be either the first listed in the type-map file, or the first read from the directory) and go to stage 3. -
        +
      -
    4. The algorithm has now selected one 'best' variant, so return +
    5. The algorithm has now selected one 'best' variant, so return it as the response. The HTTP response header Vary is set to indicate the dimensions of negotiation (browsers and caches can use this information when caching the resource). End. -
    6. To get here means no variant was selected (because non are acceptable +
    7. To get here means no variant was selected (because non are acceptable to the browser). Return a 406 status (meaning "No acceptable representation") with a response body consisting of an HTML document listing the available variants. Also set the HTTP Vary header to indicate the dimensions of variance. -
    +
-

Fiddling with Quality Values

+

Fiddling with Quality Values

-

+

Apache sometimes changes the quality values from what would be expected by a strict interpretation of the algorithm above. This is to get a better result from the algorithm for browsers which do not send @@ -341,25 +341,25 @@ 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. -

+

Media Types and Wildcards

-

+

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 (so the first "image/*" is redundant). 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 @@ -368,30 +368,30 @@ above, the */* wildcard has exactly equal preference to all the other types, so they are not being preferred. The browser should really have sent a request with a lower quality (preference) value for *.*, such as: -
+
   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 +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 +these special values are not applied, so requests from browsers which send the correct information to start with work as expected.

Variants with no Language

-

+

If some of the variants for a particular resource have a language attribute, and some do not, those variants with no language -are given a very low language quality factor of 0.001.

+are given a very low language quality factor of 0.001.

The reason for setting this language quality factor for variant with no language to a very low value is to allow @@ -400,13 +400,13 @@ other variants match the browser's language preferences. For example, consider the situation with three variants: -

+ -

+

The meaning of a variant with no language is that it is always acceptable to the browser. If the request Accept-Language header includes either en or fr (or both) one of foo.en.html @@ -415,94 +415,94 @@ either en or fr as acceptable, foo.html will be returned instead.

Note on hyperlinks and naming conventions

-

+

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 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 +(see 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: -

+

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FilenameValid hyperlinkInvalid hyperlink
foo.html.enfoo
- foo.html		-
foo.en.htmlfoofoo.html
foo.html.en.gzfoo
- foo.html		foo.gz
- foo.html.gz
foo.en.html.gzfoofoo.html
- foo.html.gz
- foo.gz
foo.gz.html.enfoo
- foo.gz
- foo.gz.html		foo.html
foo.html.gz.enfoo
- foo.html
- foo.html.gz		foo.gz
- -

+ + 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 an hyperlink (e.g. foo). +use the name without any extensions in an 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 +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 +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). +(e.g. foo.html.en).

Note on Caching

-

+

When a cache stores a document, it associates it with the request URL. The next time that URL is requested, the cache can use the stored document, provided it is still within date. But if the resource is @@ -514,7 +514,7 @@ 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 +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 diff --git a/docs/manual/content-negotiation.html.en b/docs/manual/content-negotiation.html.en index c6b096a688..2a0abb5ccd 100644 --- a/docs/manual/content-negotiation.html.en +++ b/docs/manual/content-negotiation.html.en @@ -13,25 +13,25 @@ ALINK="#FF0000" > -

Content Negotiation

+

Content Negotiation

-

+

Apache's support for content negotiation has been updated to meet 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 is also implements a couple of features to give more intelligent handling of requests from -browsers which send incomplete negotiation information.

+browsers which send incomplete negotiation information.

Content negotiation is provided by the -mod_negotiation module, +mod_negotiation module, which is compiled in by default. -

+

About Content Negotiation

-

+

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 @@ -44,14 +44,14 @@ 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 @@ -59,54 +59,54 @@ 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 1.2 supports 'server driven' content negotiation, as defined in the HTTP/1.1 specification. It fully supports the Accept, Accept-Language, Accept-Charset and Accept-Encoding request headers. -

+

-The terms used in content negotiation are: a resource is an +The terms used in content negotiation are: a resource is an item which can be requested of a server, which might be selected as the result of a content negotiation algorithm. If a resource is -available in several formats, these are called representations -or variants. The ways in which the variants for a particular -resource vary are called the dimensions of negotiation. +available in several formats, these are called representations +or variants. The ways in which the variants for a particular +resource vary are called the dimensions of negotiation.

Negotiation in Apache

-

+

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: -

Using a type-map file

-

+

A type map is a document which is associated with the handler -named type-map (or, for backwards-compatibility with +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've got to have a SetHandler some place which defines a -file suffix as type-map; this is best done with a -

+application/x-type-map).  Note that to use this feature,
+you've got to have a SetHandler some place which defines a
+file suffix as type-map; this is best done with a
+
 
   AddHandler type-map var
 
-

-in srm.conf.  See comments in the sample config files for
-details. 

+
+in srm.conf. See comments in the sample config files for +details.

Type map files have an entry for each available variant; these entries consist of contiguous RFC822-format header lines. Entries for @@ -115,7 +115,7 @@ 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: -

+
 
   URI: foo
 
@@ -126,12 +126,12 @@ map file is:
   URI: foo.fr.de.html
   Content-type: text/html; charset=iso-8859-2
   Content-language: fr, de
-

+
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
@@ -143,83 +143,83 @@ as jpeg, gif, or ASCII-art):
   URI: foo.txt
   Content-type: text/plain; qs=0.01
 
-

-

+
+

qs values can vary between 0.000 and 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.

+parameter value are given a qs factor of 1.0.

The full list of headers recognized is: -

-
URI: -
uri of the file containing the variant (of the given media +
+
URI: +
uri of the file containing the variant (of the given media type, encoded with the given content encoding). These are interpreted as URLs relative to the map file; they must be on the same server (!), and they must refer to files to which the client would be granted access if they were to be requested directly. -
Content-type: -
media type --- charset, level and "qs" parameters may be given. These +
Content-type: +
media type --- charset, level and "qs" parameters may be given. These are often referred to as MIME types; typical media types are - image/gif, text/plain, or - text/html; level=3. -
Content-language: -
The languages of the variant, specified as an Internet standard - language code (e.g., en for English, - kr for Korean, etc.). -
Content-encoding: -
If the file is compressed, or otherwise encoded, rather than + image/gif, text/plain, or + text/html; level=3. +
Content-language: +
The languages of the variant, specified as an Internet standard + language code (e.g., en for English, + kr for Korean, etc.). +
Content-encoding: +
If the file is compressed, or otherwise encoded, rather than containing the actual raw data, this says how that was done. For compressed files (the only case where this generally comes up), content encoding should be - x-compress, or x-gzip, as appropriate. -
Content-length: -
The size of the file. Clients can ask to receive a given media + x-compress, or x-gzip, as appropriate. +
Content-length: +
The size of the file. Clients can ask to receive a given media type only if the variant isn't too big; specifying a content length in the map allows the server to compare against these thresholds without checking the actual file. -
+

Multiviews

-

+

This is a per-directory option, meaning it can be set with an -Options directive within a <Directory>, -<Location> or <Files> -section in access.conf, or (if AllowOverride -is properly set) in .htaccess files. Note that -Options All does not set MultiViews; you +Options directive within a <Directory>, +<Location> or <Files> +section in access.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. (Fixing this is a one-line change to -http_core.h). +http_core.h). -

+

-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 +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, and forwards them along. -

+

This applies to searches for the file named by the -DirectoryIndex directive, if the server is trying to +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.
+
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 directive is a CGI script, it's not obvious what should happen. The code gives that case @@ -238,7 +238,7 @@ any. To do this it calculates a quality value for each variant in each of the dimensions of variance. 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 in detail the algorithm used for those interested.

+explains in detail the algorithm used for those interested.

In some circumstances, Apache can 'fiddle' the quality factor of a particular dimension to achieve a better result. The ways Apache can @@ -246,93 +246,93 @@ fiddle quality factors is explained in more detail below.

Dimensions of Negotiation

- -
Dimension -Notes -
Media Type -Browser indicates preferences on Accept: header. Each item + +
Dimension +Notes +
Media Type +Browser indicates preferences on Accept: header. Each item can have an associated quality factor. Variant description can also have a quality factor. -
Language -Browser indicates preferences on Accept-Language: header. Each +
Language +Browser indicates preferences on Accept-Language: header. Each item can have a quality factor. Variants can be associated with none, one or more languages. -
Encoding -Browser indicates preference with Accept-Encoding: header. -
Charset -Browser indicates preference with Accept-Charset: header. Variants +
Encoding +Browser indicates preference with Accept-Encoding: header. +
Charset +Browser indicates preference with Accept-Charset: header. Variants can indicate a charset as a parameter of the media type. -
+

Apache Negotiation Algorithm

-

+

Apache uses an algorithm to select the 'best' variant (if any) to return to the browser. This algorithm is not configurable. It operates like this: -

    -
  1. +
      +
    1. Firstly, for each dimension of the negotiation, the appropriate Accept header is checked and a quality assigned to this each variant. If the Accept header for any dimension means that this variant is not acceptable, eliminate it. If no variants remain, go to step 4. -
    2. Select the 'best' variant by a process of elimination. Each of +
    3. Select the 'best' variant by a process of elimination. Each of the following tests is applied in order. Any variants not selected at each stage are eliminated. After each test, if only one variant remains, it is selected as the best match. If more than one variant remains, move onto the next test. -
        -
      1. Multiply the quality factor from the Accept header with the +
          +
        1. Multiply the quality factor from the Accept header with the quality-of-source factor for this variant's media type, and select the variants with the highest value -
        2. Select the variants with the highest language quality factor +
        3. Select the variants with the highest language quality factor -
        4. Select the variants with the best language match, using either the - order of languages on the LanguagePriority directive (if present), +
        5. Select the variants with the best language match, using either the + order of languages on the LanguagePriority directive (if present), else the order of languages on the Accept-Language header. -
        6. Select the variants with the highest 'level' media parameter +
        7. Select the variants with the highest 'level' media parameter (used to give the version of text/html media types). -
        8. Select only unencoded variants, if there is a mix of encoded +
        9. Select only unencoded variants, if there is a mix of encoded and non-encoded variants. If either all variants are encoded or all variants are not encoded, select all. -
        10. Select only variants with acceptable charset media parameters, +
        11. Select only variants with acceptable charset media parameters, as given on the Accept-Charset header line. Charset ISO-8859-1 is always acceptable. Variants not associated with a particular charset are assumed to be in ISO-8859-1. -
        12. Select the variants with the smallest content length +
        13. Select the variants with the smallest content length -
        14. Select the first variant of those remaining (this will be either the +
        15. Select the first variant of those remaining (this will be either the first listed in the type-map file, or the first read from the directory) and go to stage 3. -
        +
      -
    4. The algorithm has now selected one 'best' variant, so return +
    5. The algorithm has now selected one 'best' variant, so return it as the response. The HTTP response header Vary is set to indicate the dimensions of negotiation (browsers and caches can use this information when caching the resource). End. -
    6. To get here means no variant was selected (because non are acceptable +
    7. To get here means no variant was selected (because non are acceptable to the browser). Return a 406 status (meaning "No acceptable representation") with a response body consisting of an HTML document listing the available variants. Also set the HTTP Vary header to indicate the dimensions of variance. -
    +
-

Fiddling with Quality Values

+

Fiddling with Quality Values

-

+

Apache sometimes changes the quality values from what would be expected by a strict interpretation of the algorithm above. This is to get a better result from the algorithm for browsers which do not send @@ -341,25 +341,25 @@ 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. -

+

Media Types and Wildcards

-

+

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 (so the first "image/*" is redundant). 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 @@ -368,30 +368,30 @@ above, the */* wildcard has exactly equal preference to all the other types, so they are not being preferred. The browser should really have sent a request with a lower quality (preference) value for *.*, such as: -
+
   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 +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 +these special values are not applied, so requests from browsers which send the correct information to start with work as expected.

Variants with no Language

-

+

If some of the variants for a particular resource have a language attribute, and some do not, those variants with no language -are given a very low language quality factor of 0.001.

+are given a very low language quality factor of 0.001.

The reason for setting this language quality factor for variant with no language to a very low value is to allow @@ -400,13 +400,13 @@ other variants match the browser's language preferences. For example, consider the situation with three variants: -

+ -

+

The meaning of a variant with no language is that it is always acceptable to the browser. If the request Accept-Language header includes either en or fr (or both) one of foo.en.html @@ -415,94 +415,94 @@ either en or fr as acceptable, foo.html will be returned instead.

Note on hyperlinks and naming conventions

-

+

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 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 +(see 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: -

+

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FilenameValid hyperlinkInvalid hyperlink
foo.html.enfoo
- foo.html		-
foo.en.htmlfoofoo.html
foo.html.en.gzfoo
- foo.html		foo.gz
- foo.html.gz
foo.en.html.gzfoofoo.html
- foo.html.gz
- foo.gz
foo.gz.html.enfoo
- foo.gz
- foo.gz.html		foo.html
foo.html.gz.enfoo
- foo.html
- foo.html.gz		foo.gz
- -

+ + 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 an hyperlink (e.g. foo). +use the name without any extensions in an 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 +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 +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). +(e.g. foo.html.en).

Note on Caching

-

+

When a cache stores a document, it associates it with the request URL. The next time that URL is requested, the cache can use the stored document, provided it is still within date. But if the resource is @@ -514,7 +514,7 @@ 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 +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 diff --git a/docs/manual/custom-error.html b/docs/manual/custom-error.html index cdd4ac9b54..802bd5cbe3 100644 --- a/docs/manual/custom-error.html +++ b/docs/manual/custom-error.html @@ -55,28 +55,28 @@

To achieve this, Apache will define new CGI-like environment variables, e.g. -

-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 +

+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 (i.e. anything starting with a protocol name - like http:, even if it refers to the same host as the - server).

+ None of these will be set if your ErrorDocument is an + external redirect (i.e. anything starting with a protocol name + like http:, even if it refers to the same host as the + server).

Configuration @@ -85,25 +85,25 @@ REDIRECT_URL=/cgi-bin/buggy.pl

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 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 +

ErrorDocument <3-digit-code> action

where the action can be,

  1. Text to be displayed. Prefix the text with a quote ("). Whatever - follows the quote is displayed. Note: the (") prefix isn't - displayed. + follows the quote is displayed. Note: the (") prefix isn't + displayed.
  2. An external URL to redirect to. @@ -121,27 +121,27 @@ ErrorDocument 401 /Subscription/how_to_subscribe.html
    Purpose
    Apache's behavior to redirected URLs has been modified so that additional - environment variables are available to a script/server-include.

    + environment variables are available to a script/server-include.

    Old behavior
    Standard CGI vars were made available to a script which has been redirected to. No indication of where the redirection came from was provided. -

    +

    New behavior
    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 +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. +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. diff --git a/docs/manual/custom-error.html.en b/docs/manual/custom-error.html.en index cdd4ac9b54..802bd5cbe3 100644 --- a/docs/manual/custom-error.html.en +++ b/docs/manual/custom-error.html.en @@ -55,28 +55,28 @@

    To achieve this, Apache will define new CGI-like environment variables, e.g. -

    -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 +

    +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 (i.e. anything starting with a protocol name - like http:, even if it refers to the same host as the - server).

    + None of these will be set if your ErrorDocument is an + external redirect (i.e. anything starting with a protocol name + like http:, even if it refers to the same host as the + server).

    Configuration @@ -85,25 +85,25 @@ REDIRECT_URL=/cgi-bin/buggy.pl

    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 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 +

    ErrorDocument <3-digit-code> action

    where the action can be,

    1. Text to be displayed. Prefix the text with a quote ("). Whatever - follows the quote is displayed. Note: the (") prefix isn't - displayed. + follows the quote is displayed. Note: the (") prefix isn't + displayed.
    2. An external URL to redirect to. @@ -121,27 +121,27 @@ ErrorDocument 401 /Subscription/how_to_subscribe.html
      Purpose
      Apache's behavior to redirected URLs has been modified so that additional - environment variables are available to a script/server-include.

      + environment variables are available to a script/server-include.

      Old behavior
      Standard CGI vars were made available to a script which has been redirected to. No indication of where the redirection came from was provided. -

      +

      New behavior
      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 +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. +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. diff --git a/docs/manual/developer/API.html b/docs/manual/developer/API.html index dba84c18d5..fdcd8737a3 100644 --- a/docs/manual/developer/API.html +++ b/docs/manual/developer/API.html @@ -1,7 +1,7 @@ - -Apache API notes - + +Apache API notes + -

      Apache API notes

      +

      Apache API notes

      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, +(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 @@ -28,77 +28,77 @@ 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.

      +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: -

      - -

      Basic concepts.

      + + +

      Basic concepts.

      We begin with an overview of the basic concepts behind the API, and how they are manifested in the code. -

      Handlers, Modules, and Requests

      +

      Handlers, Modules, and Requests

      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: -
        -
      • URI -> Filename translation -
      • Auth ID checking [is the user who they say they are?] -
      • Auth access checking [is the user authorized here?] -
      • Access checking other than auth -
      • Determining MIME type of the object requested -
      • `Fixups' --- there aren't any of these yet, but the phase is +
          +
        • URI -> Filename translation +
        • Auth ID checking [is the user who they say they are?] +
        • Auth access checking [is the user authorized here?] +
        • Access checking other than auth +
        • Determining MIME type of the object requested +
        • `Fixups' --- there aren't any of these yet, but the phase is intended as a hook for possible extensions like - SetEnv, which don't really fit well elsewhere. -
        • Actually sending a response back to the client. -
        • Logging the request -
        + SetEnv, which don't really fit well elsewhere. +
      • Actually sending a response back to the client. +
      • Logging the request +
      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 +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: -
        -
      • Handle the request, and indicate that it has done so - by returning the magic constant OK. -
      • Decline to handle the request, by returning the magic - integer constant DECLINED. In this case, the +
          +
        • Handle the request, and indicate that it has done so + by returning the magic constant OK. +
        • Decline to handle the request, by returning the magic + integer constant DECLINED. In this case, the server behaves in all respects as if the handler simply hadn't been there. -
        • Signal an error, by returning one of the HTTP error codes. +
        • Signal an error, by returning one of the HTTP error codes. This terminates normal handling of the request, although an ErrorDocument may be invoked to try to mop up, and it will be logged in any case. -
        +
      Most phases are terminated by the first module that handles them; however, for logging, `fixups', and non-access authentication @@ -106,62 +106,62 @@ 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 +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).

      +(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.

      +request_rec structure. vide infra), which returns an +integer, as above.

      -

      A brief tour of a module

      +

      A brief tour of a module

      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 +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.

      +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).

      +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; +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).

      +ScriptAliases declared).

      Finally, this module contains code to handle the -ScriptAlias command itself. This particular module only +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.

      +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 +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 +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 +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). +(such as ScriptAlias). With no further ado, the module itself: -

      +
       /* Declarations of handlers. */
 
 int translate_scriptalias (request_rec *);
@@ -213,34 +213,34 @@ module cgi_module = {
    NULL,                     /* logger */
    NULL                      /* header parser */
 };
-
      
+
      -

      How handlers work

      +

      How handlers work

      -The sole argument to handlers is a request_rec structure. +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 client generates only one request_rec structure.

      -

      A brief tour of the request_rec

      +

      A brief tour of the request_rec

      -The request_rec contains pointers to a resource pool +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.

      +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).

      +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 -table_get and table_set routines.

      +table_get and table_set routines.

      Note that the Content-type header value cannot be set by module content-handlers using the table_*() @@ -255,17 +255,17 @@ 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 +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.

      +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:

      +Here is an abridged declaration, giving the fields most commonly used:

      -

      +
       struct request_rec {
 
   pool *pool;
@@ -327,101 +327,101 @@ struct request_rec {
 
 };
 
-
      
+
      -

      Where request_rec structures come from

      +

      Where request_rec structures come from

      -Most request_rec structures are built by reading an HTTP +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: -
        -
      • If the request is to an imagemap, a type map (i.e., a - *.var file), or a CGI script which returned a +
          +
        • If the request is to an imagemap, a type map (i.e., a + *.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 + 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.

          + directly.

          -

        • If some handler signaled an error, and an - ErrorDocument is in scope, the same internal - redirect machinery comes into play.

          +

        • If some handler signaled an error, and an + ErrorDocument is in scope, the same internal + redirect machinery comes into play.

          -

        • Finally, a handler occasionally needs to investigate `what +
        • 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.

          + order to figure out what icon to use.

          - Such handlers can construct a sub-request, using the - functions sub_req_lookup_file and - sub_req_lookup_uri; this constructs a new - request_rec structure and processes it as you + Such handlers can construct a sub-request, using the + functions sub_req_lookup_file and + sub_req_lookup_uri; this constructs 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).

          + as the original request).

          (Server-side includes work by building sub-requests and then actually invoking the response handler for them, via the - function run_sub_request). -

        + function run_sub_request). +
      -

      Handling requests, declining, and returning error codes

      +

      Handling requests, declining, and returning error codes

      As discussed above, each handler, when invoked to handle a particular -request_rec, has to return an int to +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 +
          +
        • OK --- the request was handled successfully. This may or may not terminate the phase. -
        • DECLINED --- no erroneous condition exists, but the module +
        • DECLINED --- no erroneous condition exists, but the module declines to handle the phase; the server tries to find another. -
        • an HTTP error code, which aborts handling of the request. -
        +
      • an HTTP error code, which aborts handling of the request. +
      -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.

      +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.

      -

      Special considerations for response handlers

      +

      Special considerations for response handlers

      Handlers for most phases do their work by simply setting a few fields -in the request_rec structure (or, in the case of access +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.

      +response handlers have to actually send a request back to the client.

      They should begin by sending an HTTP response header, using the -function send_http_header. (You don't have to do +function 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 +the request is marked header_only, that's all they should do; they should return after that, without attempting any further -output.

      +output.

      Otherwise, they should produce a request body which responds to the -client as appropriate. The primitives for this are rputc -and rprintf, for internally generated output, and -send_fd, to copy the contents of some FILE * -straight to the client.

      +client as appropriate. The primitives for this are rputc +and rprintf, for internally generated output, and +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 +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 --- set_last_modified checks -against the If-modified-since value supplied by the +GETs can be handled, if it's desirable to do so in a +particular response handler --- 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 -set_content_length, but it returns an error code for -symmetry.

      +set_content_length, but it returns an error code for +symmetry.

      -

      +
       int default_handler (request_rec *r)
 {
     int errstatus;
@@ -449,96 +449,96 @@ int default_handler (request_rec *r)
     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 -internal_redirect, which is how the internal redirection +internal_redirect, which is how the internal redirection machinery discussed above is invoked. A response handler which has -internally redirected should always return OK.

      +internally redirected should always return OK.

      -(Invoking internal_redirect from handlers which are -not response handlers will lead to serious confusion). +(Invoking internal_redirect from handlers which are +not response handlers will lead to serious confusion). -

      Special considerations for authentication handlers

      +

      Special considerations for authentication handlers

      Stuff that should be discussed here in detail: -
        -
      • Authentication-phase handlers not invoked unless auth is +
          +
        • Authentication-phase handlers not invoked unless auth is configured for the directory. -
        • Common auth configuration stored in the core per-dir - configuration; it has accessors auth_type, - auth_name, and requires. -
        • Common routines, to handle the protocol end of things, at least - for HTTP basic authentication (get_basic_auth_pw, - which sets the connection->user structure field - automatically, and note_basic_auth_failure, which - arranges for the proper WWW-Authenticate: header +
        • Common auth configuration stored in the core per-dir + configuration; it has accessors auth_type, + auth_name, and requires. +
        • Common routines, to handle the protocol end of things, at least + for HTTP basic authentication (get_basic_auth_pw, + which sets the connection->user structure field + automatically, and note_basic_auth_failure, which + arranges for the proper WWW-Authenticate: header to be sent back). -
        +
      -

      Special considerations for logging handlers

      +

      Special considerations for logging handlers

      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 +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). -

      Resource allocation and resource pools

      +

      Resource allocation and resource pools

      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.

      +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.

      +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 +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.

      +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 +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.

      +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 pfopen, which also +function pfopen, which also arranges for the underlying file descriptor to be closed before any -child processes, such as for CGI scripts, are execed), or +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, palloc is generally faster than -malloc.

      +allocation, 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 @@ -547,15 +547,15 @@ machinery.

      Allocation of memory in pools

      Memory is allocated to pools by calling the function -palloc, which takes two arguments, one being a pointer to +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 +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 +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;
@@ -563,20 +563,20 @@ int my_handler(request_rec *r)
 
     foo = (foo *)palloc (r->pool, sizeof(my_structure));
 }
-
      
+
      -Note that there is no pfree --- -palloced memory is freed only when the associated -resource pool is cleared. This means that palloc does not -have to do as much accounting as malloc(); all it does in +Note that there is no pfree --- +palloced memory is freed only when the associated +resource pool is cleared. This means that 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.

      +range check.

      -(It also raises the possibility that heavy use of palloc +(It also raises the possibility that heavy use of 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 +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 @@ -586,107 +586,107 @@ thousands of files).

      Allocating initialized memory

      There are functions which allocate initialized memory, and are -frequently useful. The function pcalloc has the same -interface as palloc, but clears out the memory it -allocates before it returns it. The function pstrdup -takes a resource pool and a char * as arguments, and +frequently useful. The function pcalloc has the same +interface as palloc, but clears out the memory it +allocates before it returns it. The function 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 pstrcat is a +returning a pointer to the copy. Finally 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 +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: -
      +
            pstrcat (r->pool, "foo", "/", "bar", NULL);
-
      
+
      returns a pointer to 8 bytes worth of memory, initialized to -"foo/bar". +"foo/bar". -

      Tracking open files, etc.

      +

      Tracking open files, etc.

      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 pfopen, which +routine which is typically used for this is pfopen, which takes a resource pool and two strings as arguments; the strings are -the same as the typical arguments to fopen, e.g., +the same as the typical arguments to fopen, e.g., -
      +
            ...
      FILE *f = pfopen (r->pool, r->filename, "r");
 
      if (f == NULL) { ... } else { ... }
-
      
+
      -There is also a popenf routine, which parallels the -lower-level open system call. Both of these routines +There is also a 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.

      +is cleared.

      -Unlike the case for memory, there are functions to close -files allocated with pfopen, and popenf, -namely pfclose and pclosef. (This is +Unlike the case for memory, there are functions to close +files allocated with pfopen, and popenf, +namely pfclose and 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 pfopen and -popenf, since to do otherwise could cause fatal errors on +functions to close files allocated with pfopen and +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.

      +FILE* is closed more than once.

      -(Using the close functions is not mandatory, since the +(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).

      Other sorts of resources --- cleanup functions

      More text goes here. Describe the the cleanup primitives in terms of -which the file stuff is implemented; also, spawn_process. +which the file stuff is implemented; also, spawn_process.

      Fine control --- creating and dealing with sub-pools, with a note on sub-requests

      -On rare occasions, too-free use of palloc() and the +On rare occasions, too-free use of 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 +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 +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 +very large directories. Unnecessary use of the primitives discussed here can hair up your code quite a bit, with very little -gain).

      +gain).

      -The primitive for creating a sub-pool is make_sub_pool, +The primitive for creating a sub-pool is 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 -clear_pool and destroy_pool, respectively. -(The difference is that clear_pool frees resources -associated with the pool, while destroy_pool also +clear_pool and destroy_pool, respectively. +(The difference is that clear_pool frees resources +associated with the pool, while 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).

      +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 sub_req_lookup_... functions) -is destroy_sub_request, which frees the resource pool. +have allocated (using the sub_req_lookup_... functions) +is destroy_sub_request, 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).

      +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 -destroy... functions). +destroy... functions). -

      Configuration, commands and the like

      +

      Configuration, commands and the like

      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 @@ -696,7 +696,7 @@ 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.

      +modules.

      However, just giving the modules command tables is not enough to divorce them completely from the server core. The server has to @@ -705,77 +705,77 @@ 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 +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 +Aliases and Redirects which come into play before the request is tied to a particular place in the underlying -file system.

      +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 +.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 +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 />).

      +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 +.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.

      +per-transaction resource pool.

      -

      Per-directory configuration structures

      +

      Per-directory configuration structures

      -Let's look out how all of this plays out in mod_mime.c, +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 +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 +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 +<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.

      +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 +(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).

      +pool if necessary).

      For the MIME module, the per-dir config creation function just -pallocs the structure above, and a creates a couple of -tables to fill it. That looks like this: +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 =
@@ -786,15 +786,15 @@ void *create_mime_dir_config (pool *p, char *dummy)
 
     return new;
 }
-
      
+
      -Now, suppose we've just read in a .htaccess file. We +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 +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.

      +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: @@ -803,7 +803,7 @@ 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;
@@ -818,63 +818,63 @@ void *merge_mime_dir_configs (pool *p, void *parent_dirv, void *subdirv)
 
     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 +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.

      +corresponding structure slot in the module itself NULL.

      -

      Command handling

      +

      Command handling

      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. +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 +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;
     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. +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.

      +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 +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).

      +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" },
@@ -882,54 +882,54 @@ command_rec mime_cmds[] = {
     "an encoding (e.g., gzip), followed by a file extension" },
 { NULL }
 };
-
      
+
      The entries in these tables are: -
        -
      • The name of the command -
      • The function which handles it -
      • a (void *) pointer, which is passed in the - cmd_parms structure to the command handler --- +
          +
        • The name of the command +
        • The function which handles it +
        • a (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. -
        • A bit mask indicating where the command may appear. There are - mask bits corresponding to each AllowOverride - option, and an additional mask bit, RSRC_CONF, +
        • A bit mask indicating where the command may appear. There are + mask bits corresponding to each 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 + config files, but not in any .htaccess file. -
        • A flag indicating how many arguments the command handler wants +
        • A flag indicating how many arguments the command handler wants pre-parsed, and how they should be passed in. - 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 + 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 + 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 + 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. -
        • Finally, we have a string which describes the arguments that +
        • Finally, we have a string which describes the arguments that should be present. If the arguments in the actual config file are not as required, this string will be used to help give a more specific error message. (You can safely leave this - NULL). -
        + 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 get_module_config function. +request_rec's per-directory configuration vector by using +the get_module_config function. -
      +
       int find_ct(request_rec *r)
 {
     int i;
@@ -965,9 +965,9 @@ int find_ct(request_rec *r)
     return OK;
 }
 
-
      
+
      -

      Side notes --- per-server configuration, virtual servers, etc.

      +

      Side notes --- per-server configuration, virtual servers, etc.

      The basic ideas behind per-server module configuration are basically the same as those for per-directory configuration; there is a creation @@ -976,17 +976,17 @@ 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).

      +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 +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;
@@ -999,6 +999,6 @@ char *add_redirect(cmd_parms *cmd, void *dummy, char *f, char *url)
     new->fake = f; new->real = url;
     return NULL;
 }
-
      
+
      - + diff --git a/docs/manual/dns-caveats.html b/docs/manual/dns-caveats.html index 66d0c22c99..4e9719df3b 100644 --- a/docs/manual/dns-caveats.html +++ b/docs/manual/dns-caveats.html @@ -1,7 +1,7 @@ - -Issues Regarding DNS and Apache - + +Issues Regarding DNS and Apache + -

      Issues Regarding DNS and Apache

      +

      Issues Regarding DNS and Apache

      -

      This page could be summarized with the statement: don't require -Apache to use DNS for any parsing of the configuration files. +

      This page could be summarized with the statement: don't require +Apache to use DNS for any parsing of the configuration files. If Apache has to use DNS to parse the configuration files then your server may be subject to reliability problems (it might not boot), or denial and theft of service attacks (including users able to steal hits @@ -25,35 +25,35 @@ from other users). Consider this configuration snippet: -

      +
           <VirtualHost www.abc.dom>
     ServerAdmin webgirl@abc.dom
     DocumentRoot /www/abc
     </VirtualHost>
-
      
+
      -

      In order for Apache to function properly it absolutely needs +

      In order for Apache to function properly it absolutely needs to have two pieces of information about each virtual host: the -ServerName +ServerName and at least one IP address that the server responds to. This example does not include the IP address, so Apache -must use DNS to find the address of www.abc.dom. If for +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 +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 +

      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>
-
      
+
      -

      Now Apache needs to use reverse DNS to find the ServerName +

      Now 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 @@ -61,108 +61,108 @@ 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. +

      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>
-
      
+

      Denial of Service

      -

      There are (at least) two forms that denial of service can come in. +

      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 +not even be under your control. For example, if abc.dom is one of your customers and they control their own DNS then they can force your (pre-1.2) server to fail while booting simply by deleting the -www.abc.dom record. +www.abc.dom record. -

      Another form is far more insidious. Consider this configuration +

      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.com has control of their own DNS.  With this config
-you have put def.com into a position where they can steal
-all traffic destined to abc.com.  To do so, all they have to
-do is set www.def.dom to 10.0.0.1.
+
      + +

      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.com has control of their own DNS. With this config +you have put def.com into a position where they can steal +all traffic destined to abc.com. 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.com record wherever they wish. +www.def.com 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.com virtual host. To better understand why +

      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.com 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. +document describing this is available.

      The "main server" Address

      -

      The addition of name-based virtual host -support in Apache 1.1 requires Apache to know the IP address(es) of +

      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 +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 +

      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 +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. +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 +

      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 +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 +CGIs unless you use mod_env to control the environment. It's best to consult the man pages or FAQs for your OS. -

      Tips to Avoid these problems

      +

      Tips to Avoid these problems

      -
        -
      • use IP addresses in <VirtualHost> -
      • use IP addresses in Listen -
      • use IP addresses in BindAddress -
      • ensure all virtual hosts have an explicit ServerName -
      • create a <VirtualHost _default_:*> server that +
          +
        • use IP addresses in <VirtualHost> +
        • use IP addresses in Listen +
        • use IP addresses in BindAddress +
        • ensure all virtual hosts have an explicit ServerName +
        • create a <VirtualHost _default_:*> server that has no pages to serve -
        +

      Appendix: Future Directions

      -

      The situation regarding DNS is highly undesirable. For Apache +

      The 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. +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 +

      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 @@ -170,14 +170,14 @@ 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 +

      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 +

      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 event 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 diff --git a/docs/manual/env.html b/docs/manual/env.html index 0ea86178a6..6fd778adaa 100644 --- a/docs/manual/env.html +++ b/docs/manual/env.html @@ -13,7 +13,7 @@ ALINK="#FF0000" > -

      Special Purpose Environment Variables

      +

      Special Purpose Environment Variables

      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 @@ -38,7 +38,7 @@ when given an HTTP/1.1 response, and this can be used to interoperate with them.

      downgrade-1.0

      -

      This forces the request to be treated as a HTTP/1.0 request even if it +

      This forces the request to be treated as a HTTP/1.0 request even if it was in a later dialect. diff --git a/docs/manual/env.html.en b/docs/manual/env.html.en index 0ea86178a6..6fd778adaa 100644 --- a/docs/manual/env.html.en +++ b/docs/manual/env.html.en @@ -13,7 +13,7 @@ ALINK="#FF0000" > -

      Special Purpose Environment Variables

      +

      Special Purpose Environment Variables

      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 @@ -38,7 +38,7 @@ when given an HTTP/1.1 response, and this can be used to interoperate with them.

      downgrade-1.0

      -

      This forces the request to be treated as a HTTP/1.0 request even if it +

      This forces the request to be treated as a HTTP/1.0 request even if it was in a later dialect. diff --git a/docs/manual/handler.html b/docs/manual/handler.html index 8059216112..504dd09ebf 100644 --- a/docs/manual/handler.html +++ b/docs/manual/handler.html @@ -13,127 +13,127 @@ ALINK="#FF0000" > -

      Apache's Handler Use

      +

      Apache's Handler Use

      What is a Handler

      -

      A "handler" is an internal Apache representation of the action to be +

      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 typed are "handled" separately. For example, you may use a type of -"application/x-httpd-cgi" to invoke CGI scripts.

      +"application/x-httpd-cgi" to invoke CGI scripts.

      -

      Apache 1.1 adds the additional ability to use handlers +

      Apache 1.1 adds the additional ability to use handlers explicitly. Either based on filename extensions or on location, these handlers are unrelated to file type. This is advantageous both because it is a more elegant solution, but it also allows for both a type -and a handler to be associated with a file.

      +and a handler to be associated with a file.

      -

      Handlers can either be built into the server or to a module, or -they can be added with the Action directive. The built-in -handlers in the standard distribution are as follows:

      +

      Handlers can either be built into the server or to a module, or +they can be added with the Action directive. The built-in +handlers in the standard distribution are as follows:

      - -

      +

      Directives

      - + -
      +
      -

      AddHandler

      +

      AddHandler

      -Syntax: <AddHandler handler-name extension>
      -Context: server config, virtual host, directory, .htaccess
      -Status: Base
      -Module: mod_mime +Syntax: <AddHandler handler-name extension>
      +Context: server config, virtual host, directory, .htaccess
      +Status: Base
      +Module: mod_mime -

      AddHandler maps the filename extension extension to the -handler handler-name. For example, to activate CGI scripts -with the file extension ".cgi", you might use: -

      +
      AddHandler maps the filename extension extension to the
+handler handler-name. For example, to activate CGI scripts
+with the file extension ".cgi", you might use:
+
           AddHandler cgi-script cgi
-
      
+
      -

      Once that has been put into your srm.conf or httpd.conf file, any -file ending with ".cgi" will be treated as a CGI -program.

      +

      Once that has been put into your srm.conf or httpd.conf file, any +file ending with ".cgi" will be treated as a CGI +program.

      -
      +
      -

      SetHandler

      +

      SetHandler

      -Syntax: <SetHandler handler-name>
      -Context: directory, .htaccess
      -Status: Base
      -Module: mod_mime +Syntax: <SetHandler handler-name>
      +Context: directory, .htaccess
      +Status: Base
      +Module: mod_mime -

      When placed into an .htaccess file or a -<Directory> or <Location> section, +

      When placed into an .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 +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: -

      +.htaccess file in that directory:
+
           SetHandler imap-file
-
      
-
      Another example: if you wanted to have the server display a status
-report whenever a URL of http://servername/status was
+
      +

      Another example: if you wanted to have the server display a status +report whenever a URL of http://servername/status was called, you might put the following into access.conf: -

      +
           <Location /status>
     SetHandler server-status
     </Location>
-
      
+
      -

      +

      Programmer's Note

      -

      In order to implement the handler features, an addition has been -made to the Apache API that you may wish to +

      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:

      -
      +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
+
      +

      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.

      +type name-space.

      diff --git a/docs/manual/handler.html.en b/docs/manual/handler.html.en index 8059216112..504dd09ebf 100644 --- a/docs/manual/handler.html.en +++ b/docs/manual/handler.html.en @@ -13,127 +13,127 @@ ALINK="#FF0000" > -

      Apache's Handler Use

      +

      Apache's Handler Use

      What is a Handler

      -

      A "handler" is an internal Apache representation of the action to be +

      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 typed are "handled" separately. For example, you may use a type of -"application/x-httpd-cgi" to invoke CGI scripts.

      +"application/x-httpd-cgi" to invoke CGI scripts.

      -

      Apache 1.1 adds the additional ability to use handlers +

      Apache 1.1 adds the additional ability to use handlers explicitly. Either based on filename extensions or on location, these handlers are unrelated to file type. This is advantageous both because it is a more elegant solution, but it also allows for both a type -and a handler to be associated with a file.

      +and a handler to be associated with a file.

      -

      Handlers can either be built into the server or to a module, or -they can be added with the Action directive. The built-in -handlers in the standard distribution are as follows:

      +

      Handlers can either be built into the server or to a module, or +they can be added with the Action directive. The built-in +handlers in the standard distribution are as follows:

      - -

      +

      Directives

      - + -
      +
      -

      AddHandler

      +

      AddHandler

      -Syntax: <AddHandler handler-name extension>
      -Context: server config, virtual host, directory, .htaccess
      -Status: Base
      -Module: mod_mime +Syntax: <AddHandler handler-name extension>
      +Context: server config, virtual host, directory, .htaccess
      +Status: Base
      +Module: mod_mime -

      AddHandler maps the filename extension extension to the -handler handler-name. For example, to activate CGI scripts -with the file extension ".cgi", you might use: -

      +
      AddHandler maps the filename extension extension to the
+handler handler-name. For example, to activate CGI scripts
+with the file extension ".cgi", you might use:
+
           AddHandler cgi-script cgi
-
      
+
      -

      Once that has been put into your srm.conf or httpd.conf file, any -file ending with ".cgi" will be treated as a CGI -program.

      +

      Once that has been put into your srm.conf or httpd.conf file, any +file ending with ".cgi" will be treated as a CGI +program.

      -
      +
      -

      SetHandler

      +

      SetHandler

      -Syntax: <SetHandler handler-name>
      -Context: directory, .htaccess
      -Status: Base
      -Module: mod_mime +Syntax: <SetHandler handler-name>
      +Context: directory, .htaccess
      +Status: Base
      +Module: mod_mime -

      When placed into an .htaccess file or a -<Directory> or <Location> section, +

      When placed into an .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 +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: -

      +.htaccess file in that directory:
+
           SetHandler imap-file
-
      
-
      Another example: if you wanted to have the server display a status
-report whenever a URL of http://servername/status was
+
      +

      Another example: if you wanted to have the server display a status +report whenever a URL of http://servername/status was called, you might put the following into access.conf: -

      +
           <Location /status>
     SetHandler server-status
     </Location>
-
      
+
      -

      +

      Programmer's Note

      -

      In order to implement the handler features, an addition has been -made to the Apache API that you may wish to +

      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:

      -
      +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
+
      +

      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.

      +type name-space.

      diff --git a/docs/manual/install.html b/docs/manual/install.html index 6052841af2..e799ad0bac 100644 --- a/docs/manual/install.html +++ b/docs/manual/install.html @@ -36,7 +36,7 @@ for how to compile the server.

      Compiling Apache

      Compiling Apache consists of three steps: Firstly select which Apache -modules you want to include into the server. Secondly create a +modules you want to include into the server. Secondly create a configuration for your operating system. Thirdly compile the executable.

      @@ -111,7 +111,7 @@ The modules we place in the Apache distribution are the ones we have tested and are used regularly by various members of the Apache development group. Additional modules contributed by members or third parties with specific needs or functions are available at <URL:http://www.apache.org/dist/contrib/modules/>. +HREF="http://www.apache.org/dist/contrib/modules/"><URL:http://www.apache.org/dist/contrib/modules/>. There are instructions on that page for linking these modules into the core Apache code. @@ -126,11 +126,11 @@ designed to be configured and run from the same set of directories where it is compiled. If you want to run it from somewhere else, make a directory and copy the conf, logs and icons directories into it. In either case you should -read the security tips +read the security tips describing how to set the permissions on the server root directory.

      The next step is to edit the configuration files for the server. This -consists of setting up various directives in up to three +consists of setting up various directives in up to three central configuration files. By default, these files are located in the conf directory and are called srm.conf, access.conf and httpd.conf. To help you get @@ -188,7 +188,7 @@ port of 80, a suitable URL to enter into your browser is

      Note that when the server starts it will create a number of -child processes to handle the requests. If you started Apache +child processes to handle the requests. If you started Apache as the root user, the parent process will continue to run as root while the children will change to the user as given in the httpd.conf file. @@ -214,7 +214,7 @@ this will be located in the file error_log in the If you want your server to continue running after a system reboot, you should add a call to httpd to your system startup files (typically rc.local or a file in an -rc.N directory). This will start Apache as root. +rc.N directory). This will start Apache as root. Before doing this ensure that your server is properly configured for security and access restrictions. diff --git a/docs/manual/install.html.en b/docs/manual/install.html.en index 6052841af2..e799ad0bac 100644 --- a/docs/manual/install.html.en +++ b/docs/manual/install.html.en @@ -36,7 +36,7 @@ for how to compile the server.

      Compiling Apache

      Compiling Apache consists of three steps: Firstly select which Apache -modules you want to include into the server. Secondly create a +modules you want to include into the server. Secondly create a configuration for your operating system. Thirdly compile the executable.

      @@ -111,7 +111,7 @@ The modules we place in the Apache distribution are the ones we have tested and are used regularly by various members of the Apache development group. Additional modules contributed by members or third parties with specific needs or functions are available at <URL:http://www.apache.org/dist/contrib/modules/>. +HREF="http://www.apache.org/dist/contrib/modules/"><URL:http://www.apache.org/dist/contrib/modules/>. There are instructions on that page for linking these modules into the core Apache code. @@ -126,11 +126,11 @@ designed to be configured and run from the same set of directories where it is compiled. If you want to run it from somewhere else, make a directory and copy the conf, logs and icons directories into it. In either case you should -read the security tips +read the security tips describing how to set the permissions on the server root directory.

      The next step is to edit the configuration files for the server. This -consists of setting up various directives in up to three +consists of setting up various directives in up to three central configuration files. By default, these files are located in the conf directory and are called srm.conf, access.conf and httpd.conf. To help you get @@ -188,7 +188,7 @@ port of 80, a suitable URL to enter into your browser is

      Note that when the server starts it will create a number of -child processes to handle the requests. If you started Apache +child processes to handle the requests. If you started Apache as the root user, the parent process will continue to run as root while the children will change to the user as given in the httpd.conf file. @@ -214,7 +214,7 @@ this will be located in the file error_log in the If you want your server to continue running after a system reboot, you should add a call to httpd to your system startup files (typically rc.local or a file in an -rc.N directory). This will start Apache as root. +rc.N directory). This will start Apache as root. Before doing this ensure that your server is properly configured for security and access restrictions. diff --git a/docs/manual/invoking.html b/docs/manual/invoking.html index 708c63de29..d718c2f89c 100644 --- a/docs/manual/invoking.html +++ b/docs/manual/invoking.html @@ -13,84 +13,84 @@ ALINK="#FF0000" > -

      Starting Apache

      +

      Starting Apache

      Invoking Apache

      -The httpd program is usually run as a daemon which executes +The httpd program is usually run as a daemon which executes continuously, handling requests. It is possible to invoke Apache by -the Internet daemon inetd each time a connection to the HTTP +the Internet daemon inetd each time a connection to the HTTP service is made (use the ServerType directive) but this is not recommended.

      Command line options

      The following options are recognized on the httpd command line: -
      -
      -d serverroot -
      Set the initial value for the +
      +
      -d serverroot +
      Set the initial value for the ServerRoot variable to -serverroot. This can be overridden by the ServerRoot command in the -configuration file. The default is /usr/local/apache. +serverroot. This can be overridden by the ServerRoot command in the +configuration file. The default is /usr/local/apache. -
      -f config -
      Execute the commands in the file config on startup. If -config does not begin with a /, then it is taken to be a +
      -f config +
      Execute the commands in the file config on startup. If +config does not begin with a /, then it is taken to be a path relative to the ServerRoot. The -default is conf/httpd.conf. +default is conf/httpd.conf. -
      -X -
      Run in single-process mode, for internal debugging purposes only; the -daemon does not detach from the terminal or fork any children. Do NOT +
      -X +
      Run in single-process mode, for internal debugging purposes only; the +daemon does not detach from the terminal or fork any children. Do NOT use this mode to provide ordinary web service. -
      -v -
      Print the version of httpd and its build date, and then exit. +
      -v +
      Print the version of httpd and its build date, and then exit. -
      -V -
      Print the base version of httpd, its sub-version if defined, its +
      -V +
      Print the base version of httpd, its sub-version if defined, its build date, and a list of compile time settings which influence the behavior and performance of the apache server (e.g., -D USE_MMAP_FILES), then exit. -
      -h -
      Give a list of directives together with expected arguments and +
      -h +
      Give a list of directives together with expected arguments and places where the directive is valid. (New in Apache 1.2) -
      -l -
      Give a list of all modules compiled into the server. +
      -l +
      Give a list of all modules compiled into the server. -
      -? -
      Print a list of the httpd options, and then exit. -
      +
      -? +
      Print a list of the httpd options, and then exit. +

      Configuration files

      The server will read three files for configuration directives. Any directive may appear in any of these files. The the names of these files are taken to be relative to the server root; this is set by the ServerRoot directive, or the --d command line flag. +-d command line flag. Conventionally, the files are: -
      -
      conf/httpd.conf -
      Contains directives that control the operation of the server daemon. -The filename may be overridden with the -f command line flag. +
      +
      conf/httpd.conf +
      Contains directives that control the operation of the server daemon. +The filename may be overridden with the -f command line flag. -
      conf/srm.conf -
      Contains directives that control the specification of documents that +
      conf/srm.conf +
      Contains directives that control the specification of documents that the server can provide to clients. The filename may be overridden with the ResourceConfig directive. -
      conf/access.conf -
      Contains directives that control access to documents. +
      conf/access.conf +
      Contains directives that control access to documents. The filename may be overridden with the AccessConfig directive. -
      +
      However, these conventions need not be adhered to. -

      +

      The server also reads a file containing mime document types; the filename is set by the TypesConfig directive, -and is conf/mime.types by default. +and is conf/mime.types by default.

      Log files

      security warning

      @@ -102,25 +102,25 @@ the consequences; see the security tips document for details.

      pid file

      On daemon startup, it saves the process id of the parent httpd process to -the file logs/httpd.pid. This filename can be changed with the +the 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; A HUP or USR1 signal causes the daemon to re-read its configuration files and a TERM signal causes it to die gracefully. For more information -see the Stopping and Restarting page. -

      +see the Stopping and Restarting page. +

      If the process dies (or is killed) abnormally, then it will be necessary to kill the children httpd processes.

      Error log

      -The server will log error messages to a log file, logs/error_log +The server will log error messages to a log file, logs/error_log by default. The filename can be set using the ErrorLog directive; different error logs can be set for different virtual hosts.

      Transfer log

      The server will typically log each request to a transfer file, -logs/access_log by default. The filename can be set using a +logs/access_log by default. The filename can be set using a TransferLog directive; different transfer logs can be set for different virtual hosts. diff --git a/docs/manual/invoking.html.en b/docs/manual/invoking.html.en index 708c63de29..d718c2f89c 100644 --- a/docs/manual/invoking.html.en +++ b/docs/manual/invoking.html.en @@ -13,84 +13,84 @@ ALINK="#FF0000" > -

      Starting Apache

      +

      Starting Apache

      Invoking Apache

      -The httpd program is usually run as a daemon which executes +The httpd program is usually run as a daemon which executes continuously, handling requests. It is possible to invoke Apache by -the Internet daemon inetd each time a connection to the HTTP +the Internet daemon inetd each time a connection to the HTTP service is made (use the ServerType directive) but this is not recommended.

      Command line options

      The following options are recognized on the httpd command line: -
      -
      -d serverroot -
      Set the initial value for the +
      +
      -d serverroot +
      Set the initial value for the ServerRoot variable to -serverroot. This can be overridden by the ServerRoot command in the -configuration file. The default is /usr/local/apache. +serverroot. This can be overridden by the ServerRoot command in the +configuration file. The default is /usr/local/apache. -
      -f config -
      Execute the commands in the file config on startup. If -config does not begin with a /, then it is taken to be a +
      -f config +
      Execute the commands in the file config on startup. If +config does not begin with a /, then it is taken to be a path relative to the ServerRoot. The -default is conf/httpd.conf. +default is conf/httpd.conf. -
      -X -
      Run in single-process mode, for internal debugging purposes only; the -daemon does not detach from the terminal or fork any children. Do NOT +
      -X +
      Run in single-process mode, for internal debugging purposes only; the +daemon does not detach from the terminal or fork any children. Do NOT use this mode to provide ordinary web service. -
      -v -
      Print the version of httpd and its build date, and then exit. +
      -v +
      Print the version of httpd and its build date, and then exit. -
      -V -
      Print the base version of httpd, its sub-version if defined, its +
      -V +
      Print the base version of httpd, its sub-version if defined, its build date, and a list of compile time settings which influence the behavior and performance of the apache server (e.g., -D USE_MMAP_FILES), then exit. -
      -h -
      Give a list of directives together with expected arguments and +
      -h +
      Give a list of directives together with expected arguments and places where the directive is valid. (New in Apache 1.2) -
      -l -
      Give a list of all modules compiled into the server. +
      -l +
      Give a list of all modules compiled into the server. -
      -? -
      Print a list of the httpd options, and then exit. -
      +
      -? +
      Print a list of the httpd options, and then exit. +

      Configuration files

      The server will read three files for configuration directives. Any directive may appear in any of these files. The the names of these files are taken to be relative to the server root; this is set by the ServerRoot directive, or the --d command line flag. +-d command line flag. Conventionally, the files are: -
      -
      conf/httpd.conf -
      Contains directives that control the operation of the server daemon. -The filename may be overridden with the -f command line flag. +
      +
      conf/httpd.conf +
      Contains directives that control the operation of the server daemon. +The filename may be overridden with the -f command line flag. -
      conf/srm.conf -
      Contains directives that control the specification of documents that +
      conf/srm.conf +
      Contains directives that control the specification of documents that the server can provide to clients. The filename may be overridden with the ResourceConfig directive. -
      conf/access.conf -
      Contains directives that control access to documents. +
      conf/access.conf +
      Contains directives that control access to documents. The filename may be overridden with the AccessConfig directive. -
      +
      However, these conventions need not be adhered to. -

      +

      The server also reads a file containing mime document types; the filename is set by the TypesConfig directive, -and is conf/mime.types by default. +and is conf/mime.types by default.

      Log files

      security warning

      @@ -102,25 +102,25 @@ the consequences; see the security tips document for details.

      pid file

      On daemon startup, it saves the process id of the parent httpd process to -the file logs/httpd.pid. This filename can be changed with the +the 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; A HUP or USR1 signal causes the daemon to re-read its configuration files and a TERM signal causes it to die gracefully. For more information -see the Stopping and Restarting page. -

      +see the Stopping and Restarting page. +

      If the process dies (or is killed) abnormally, then it will be necessary to kill the children httpd processes.

      Error log

      -The server will log error messages to a log file, logs/error_log +The server will log error messages to a log file, logs/error_log by default. The filename can be set using the ErrorLog directive; different error logs can be set for different virtual hosts.

      Transfer log

      The server will typically log each request to a transfer file, -logs/access_log by default. The filename can be set using a +logs/access_log by default. The filename can be set using a TransferLog directive; different transfer logs can be set for different virtual hosts. diff --git a/docs/manual/location.html b/docs/manual/location.html index 96ab3a8544..b5c3fd5e30 100644 --- a/docs/manual/location.html +++ b/docs/manual/location.html @@ -15,43 +15,43 @@

      Access Control by URL

      -

      The <Location> Directive

      +

      The <Location> Directive

      -Syntax: <Location URL prefix>
      -Context: server config, virtual host
      -Status: core
      +Syntax: <Location URL prefix>
      +Context: server config, virtual host
      +Status: core
      -

      The <Location> directive provides for access control by -URL. It is comparable to the <Directory> directive, and +

      The <Location> directive provides for access control by +URL. It is comparable to the <Directory> directive, and should be matched with a </Location> directive. Directives that apply to the URL given should be listen -within. <Location> sections are processed in the +within. <Location> sections are processed in the order they appear in the configuration file, after the -<Directory> sections and .htaccess files are -read.

      +<Directory> sections and .htaccess files are +read.

      -

      Note that, due to the way HTTP functions, URL prefix -should, save for proxy requests, be of the form /path/, -and should not include the http://servername. It doesn't +

      Note that, due to the way HTTP functions, URL prefix +should, save for proxy requests, be of the form /path/, +and should not include the http://servername. It doesn't necessarily have to protect a directory (it can be an individual file, or a number of files), and can include wild-cards. In a wild-card string, `?' matches any single character, and `*' matches any sequences of characters. -

      This functionality is especially useful when combined with the -SetHandler +

      This 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>
-
      
+
      diff --git a/docs/manual/misc/API.html b/docs/manual/misc/API.html index dba84c18d5..fdcd8737a3 100644 --- a/docs/manual/misc/API.html +++ b/docs/manual/misc/API.html @@ -1,7 +1,7 @@ - -Apache API notes - + +Apache API notes + -

      Apache API notes

      +

      Apache API notes

      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, +(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 @@ -28,77 +28,77 @@ 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.

      +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: -

      - -

      Basic concepts.

      + + +

      Basic concepts.

      We begin with an overview of the basic concepts behind the API, and how they are manifested in the code. -

      Handlers, Modules, and Requests

      +

      Handlers, Modules, and Requests

      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: -
        -
      • URI -> Filename translation -
      • Auth ID checking [is the user who they say they are?] -
      • Auth access checking [is the user authorized here?] -
      • Access checking other than auth -
      • Determining MIME type of the object requested -
      • `Fixups' --- there aren't any of these yet, but the phase is +
          +
        • URI -> Filename translation +
        • Auth ID checking [is the user who they say they are?] +
        • Auth access checking [is the user authorized here?] +
        • Access checking other than auth +
        • Determining MIME type of the object requested +
        • `Fixups' --- there aren't any of these yet, but the phase is intended as a hook for possible extensions like - SetEnv, which don't really fit well elsewhere. -
        • Actually sending a response back to the client. -
        • Logging the request -
        + SetEnv, which don't really fit well elsewhere. +
      • Actually sending a response back to the client. +
      • Logging the request +
      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 +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: -
        -
      • Handle the request, and indicate that it has done so - by returning the magic constant OK. -
      • Decline to handle the request, by returning the magic - integer constant DECLINED. In this case, the +
          +
        • Handle the request, and indicate that it has done so + by returning the magic constant OK. +
        • Decline to handle the request, by returning the magic + integer constant DECLINED. In this case, the server behaves in all respects as if the handler simply hadn't been there. -
        • Signal an error, by returning one of the HTTP error codes. +
        • Signal an error, by returning one of the HTTP error codes. This terminates normal handling of the request, although an ErrorDocument may be invoked to try to mop up, and it will be logged in any case. -
        +
      Most phases are terminated by the first module that handles them; however, for logging, `fixups', and non-access authentication @@ -106,62 +106,62 @@ 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 +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).

      +(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.

      +request_rec structure. vide infra), which returns an +integer, as above.

      -

      A brief tour of a module

      +

      A brief tour of a module

      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 +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.

      +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).

      +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; +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).

      +ScriptAliases declared).

      Finally, this module contains code to handle the -ScriptAlias command itself. This particular module only +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.

      +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 +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 +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 +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). +(such as ScriptAlias). With no further ado, the module itself: -

      +
       /* Declarations of handlers. */
 
 int translate_scriptalias (request_rec *);
@@ -213,34 +213,34 @@ module cgi_module = {
    NULL,                     /* logger */
    NULL                      /* header parser */
 };
-
      
+
      -

      How handlers work

      +

      How handlers work

      -The sole argument to handlers is a request_rec structure. +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 client generates only one request_rec structure.

      -

      A brief tour of the request_rec

      +

      A brief tour of the request_rec

      -The request_rec contains pointers to a resource pool +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.

      +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).

      +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 -table_get and table_set routines.

      +table_get and table_set routines.

      Note that the Content-type header value cannot be set by module content-handlers using the table_*() @@ -255,17 +255,17 @@ 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 +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.

      +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:

      +Here is an abridged declaration, giving the fields most commonly used:

      -

      +
       struct request_rec {
 
   pool *pool;
@@ -327,101 +327,101 @@ struct request_rec {
 
 };
 
-
      
+
      -

      Where request_rec structures come from

      +

      Where request_rec structures come from

      -Most request_rec structures are built by reading an HTTP +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: -
        -
      • If the request is to an imagemap, a type map (i.e., a - *.var file), or a CGI script which returned a +
          +
        • If the request is to an imagemap, a type map (i.e., a + *.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 + 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.

          + directly.

          -

        • If some handler signaled an error, and an - ErrorDocument is in scope, the same internal - redirect machinery comes into play.

          +

        • If some handler signaled an error, and an + ErrorDocument is in scope, the same internal + redirect machinery comes into play.

          -

        • Finally, a handler occasionally needs to investigate `what +
        • 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.

          + order to figure out what icon to use.

          - Such handlers can construct a sub-request, using the - functions sub_req_lookup_file and - sub_req_lookup_uri; this constructs a new - request_rec structure and processes it as you + Such handlers can construct a sub-request, using the + functions sub_req_lookup_file and + sub_req_lookup_uri; this constructs 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).

          + as the original request).

          (Server-side includes work by building sub-requests and then actually invoking the response handler for them, via the - function run_sub_request). -

        + function run_sub_request). +
      -

      Handling requests, declining, and returning error codes

      +

      Handling requests, declining, and returning error codes

      As discussed above, each handler, when invoked to handle a particular -request_rec, has to return an int to +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 +
          +
        • OK --- the request was handled successfully. This may or may not terminate the phase. -
        • DECLINED --- no erroneous condition exists, but the module +
        • DECLINED --- no erroneous condition exists, but the module declines to handle the phase; the server tries to find another. -
        • an HTTP error code, which aborts handling of the request. -
        +
      • an HTTP error code, which aborts handling of the request. +
      -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.

      +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.

      -

      Special considerations for response handlers

      +

      Special considerations for response handlers

      Handlers for most phases do their work by simply setting a few fields -in the request_rec structure (or, in the case of access +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.

      +response handlers have to actually send a request back to the client.

      They should begin by sending an HTTP response header, using the -function send_http_header. (You don't have to do +function 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 +the request is marked header_only, that's all they should do; they should return after that, without attempting any further -output.

      +output.

      Otherwise, they should produce a request body which responds to the -client as appropriate. The primitives for this are rputc -and rprintf, for internally generated output, and -send_fd, to copy the contents of some FILE * -straight to the client.

      +client as appropriate. The primitives for this are rputc +and rprintf, for internally generated output, and +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 +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 --- set_last_modified checks -against the If-modified-since value supplied by the +GETs can be handled, if it's desirable to do so in a +particular response handler --- 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 -set_content_length, but it returns an error code for -symmetry.

      +set_content_length, but it returns an error code for +symmetry.

      -

      +
       int default_handler (request_rec *r)
 {
     int errstatus;
@@ -449,96 +449,96 @@ int default_handler (request_rec *r)
     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 -internal_redirect, which is how the internal redirection +internal_redirect, which is how the internal redirection machinery discussed above is invoked. A response handler which has -internally redirected should always return OK.

      +internally redirected should always return OK.

      -(Invoking internal_redirect from handlers which are -not response handlers will lead to serious confusion). +(Invoking internal_redirect from handlers which are +not response handlers will lead to serious confusion). -

      Special considerations for authentication handlers

      +

      Special considerations for authentication handlers

      Stuff that should be discussed here in detail: -
        -
      • Authentication-phase handlers not invoked unless auth is +
          +
        • Authentication-phase handlers not invoked unless auth is configured for the directory. -
        • Common auth configuration stored in the core per-dir - configuration; it has accessors auth_type, - auth_name, and requires. -
        • Common routines, to handle the protocol end of things, at least - for HTTP basic authentication (get_basic_auth_pw, - which sets the connection->user structure field - automatically, and note_basic_auth_failure, which - arranges for the proper WWW-Authenticate: header +
        • Common auth configuration stored in the core per-dir + configuration; it has accessors auth_type, + auth_name, and requires. +
        • Common routines, to handle the protocol end of things, at least + for HTTP basic authentication (get_basic_auth_pw, + which sets the connection->user structure field + automatically, and note_basic_auth_failure, which + arranges for the proper WWW-Authenticate: header to be sent back). -
        +
      -

      Special considerations for logging handlers

      +

      Special considerations for logging handlers

      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 +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). -

      Resource allocation and resource pools

      +

      Resource allocation and resource pools

      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.

      +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.

      +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 +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.

      +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 +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.

      +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 pfopen, which also +function pfopen, which also arranges for the underlying file descriptor to be closed before any -child processes, such as for CGI scripts, are execed), or +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, palloc is generally faster than -malloc.

      +allocation, 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 @@ -547,15 +547,15 @@ machinery.

      Allocation of memory in pools

      Memory is allocated to pools by calling the function -palloc, which takes two arguments, one being a pointer to +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 +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 +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;
@@ -563,20 +563,20 @@ int my_handler(request_rec *r)
 
     foo = (foo *)palloc (r->pool, sizeof(my_structure));
 }
-
      
+
      -Note that there is no pfree --- -palloced memory is freed only when the associated -resource pool is cleared. This means that palloc does not -have to do as much accounting as malloc(); all it does in +Note that there is no pfree --- +palloced memory is freed only when the associated +resource pool is cleared. This means that 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.

      +range check.

      -(It also raises the possibility that heavy use of palloc +(It also raises the possibility that heavy use of 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 +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 @@ -586,107 +586,107 @@ thousands of files).

      Allocating initialized memory

      There are functions which allocate initialized memory, and are -frequently useful. The function pcalloc has the same -interface as palloc, but clears out the memory it -allocates before it returns it. The function pstrdup -takes a resource pool and a char * as arguments, and +frequently useful. The function pcalloc has the same +interface as palloc, but clears out the memory it +allocates before it returns it. The function 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 pstrcat is a +returning a pointer to the copy. Finally 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 +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: -
      +
            pstrcat (r->pool, "foo", "/", "bar", NULL);
-
      
+
      returns a pointer to 8 bytes worth of memory, initialized to -"foo/bar". +"foo/bar". -

      Tracking open files, etc.

      +

      Tracking open files, etc.

      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 pfopen, which +routine which is typically used for this is pfopen, which takes a resource pool and two strings as arguments; the strings are -the same as the typical arguments to fopen, e.g., +the same as the typical arguments to fopen, e.g., -
      +
            ...
      FILE *f = pfopen (r->pool, r->filename, "r");
 
      if (f == NULL) { ... } else { ... }
-
      
+
      -There is also a popenf routine, which parallels the -lower-level open system call. Both of these routines +There is also a 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.

      +is cleared.

      -Unlike the case for memory, there are functions to close -files allocated with pfopen, and popenf, -namely pfclose and pclosef. (This is +Unlike the case for memory, there are functions to close +files allocated with pfopen, and popenf, +namely pfclose and 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 pfopen and -popenf, since to do otherwise could cause fatal errors on +functions to close files allocated with pfopen and +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.

      +FILE* is closed more than once.

      -(Using the close functions is not mandatory, since the +(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).

      Other sorts of resources --- cleanup functions

      More text goes here. Describe the the cleanup primitives in terms of -which the file stuff is implemented; also, spawn_process. +which the file stuff is implemented; also, spawn_process.

      Fine control --- creating and dealing with sub-pools, with a note on sub-requests

      -On rare occasions, too-free use of palloc() and the +On rare occasions, too-free use of 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 +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 +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 +very large directories. Unnecessary use of the primitives discussed here can hair up your code quite a bit, with very little -gain).

      +gain).

      -The primitive for creating a sub-pool is make_sub_pool, +The primitive for creating a sub-pool is 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 -clear_pool and destroy_pool, respectively. -(The difference is that clear_pool frees resources -associated with the pool, while destroy_pool also +clear_pool and destroy_pool, respectively. +(The difference is that clear_pool frees resources +associated with the pool, while 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).

      +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 sub_req_lookup_... functions) -is destroy_sub_request, which frees the resource pool. +have allocated (using the sub_req_lookup_... functions) +is destroy_sub_request, 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).

      +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 -destroy... functions). +destroy... functions). -

      Configuration, commands and the like

      +

      Configuration, commands and the like

      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 @@ -696,7 +696,7 @@ 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.

      +modules.

      However, just giving the modules command tables is not enough to divorce them completely from the server core. The server has to @@ -705,77 +705,77 @@ 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 +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 +Aliases and Redirects which come into play before the request is tied to a particular place in the underlying -file system.

      +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 +.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 +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 />).

      +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 +.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.

      +per-transaction resource pool.

      -

      Per-directory configuration structures

      +

      Per-directory configuration structures

      -Let's look out how all of this plays out in mod_mime.c, +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 +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 +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 +<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.

      +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 +(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).

      +pool if necessary).

      For the MIME module, the per-dir config creation function just -pallocs the structure above, and a creates a couple of -tables to fill it. That looks like this: +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 =
@@ -786,15 +786,15 @@ void *create_mime_dir_config (pool *p, char *dummy)
 
     return new;
 }
-
      
+
      -Now, suppose we've just read in a .htaccess file. We +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 +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.

      +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: @@ -803,7 +803,7 @@ 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;
@@ -818,63 +818,63 @@ void *merge_mime_dir_configs (pool *p, void *parent_dirv, void *subdirv)
 
     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 +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.

      +corresponding structure slot in the module itself NULL.

      -

      Command handling

      +

      Command handling

      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. +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 +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;
     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. +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.

      +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 +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).

      +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" },
@@ -882,54 +882,54 @@ command_rec mime_cmds[] = {
     "an encoding (e.g., gzip), followed by a file extension" },
 { NULL }
 };
-
      
+
      The entries in these tables are: -
        -
      • The name of the command -
      • The function which handles it -
      • a (void *) pointer, which is passed in the - cmd_parms structure to the command handler --- +
          +
        • The name of the command +
        • The function which handles it +
        • a (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. -
        • A bit mask indicating where the command may appear. There are - mask bits corresponding to each AllowOverride - option, and an additional mask bit, RSRC_CONF, +
        • A bit mask indicating where the command may appear. There are + mask bits corresponding to each 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 + config files, but not in any .htaccess file. -
        • A flag indicating how many arguments the command handler wants +
        • A flag indicating how many arguments the command handler wants pre-parsed, and how they should be passed in. - 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 + 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 + 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 + 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. -
        • Finally, we have a string which describes the arguments that +
        • Finally, we have a string which describes the arguments that should be present. If the arguments in the actual config file are not as required, this string will be used to help give a more specific error message. (You can safely leave this - NULL). -
        + 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 get_module_config function. +request_rec's per-directory configuration vector by using +the get_module_config function. -
      +
       int find_ct(request_rec *r)
 {
     int i;
@@ -965,9 +965,9 @@ int find_ct(request_rec *r)
     return OK;
 }
 
-
      
+
      -

      Side notes --- per-server configuration, virtual servers, etc.

      +

      Side notes --- per-server configuration, virtual servers, etc.

      The basic ideas behind per-server module configuration are basically the same as those for per-directory configuration; there is a creation @@ -976,17 +976,17 @@ 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).

      +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 +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;
@@ -999,6 +999,6 @@ char *add_redirect(cmd_parms *cmd, void *dummy, char *f, char *url)
     new->fake = f; new->real = url;
     return NULL;
 }
-
      
+
      - + diff --git a/docs/manual/misc/FAQ.html b/docs/manual/misc/FAQ.html index 95bd6c1966..f5284247a3 100644 --- a/docs/manual/misc/FAQ.html +++ b/docs/manual/misc/FAQ.html @@ -15,7 +15,7 @@

      Apache Server Frequently Asked Questions

      - $Revision: 1.103 $ ($Date: 1998/01/26 07:09:13 $) + $Revision: 1.104 $ ($Date: 1998/01/26 16:53:48 $)

      The latest version of this FAQ is always available from the main @@ -1957,7 +1957,7 @@

      Hmmm... there are a lot of reasons. First, mod_rewrite itself is a powerful - module which can help you in really all aspects of URL rewriting, so + module which can help you in really all aspects of URL rewriting, so it can be no trivial module per definition. To accomplish its hard job it uses software leverage and makes use of a powerful regular expression library by Henry Spencer which is an integral part of Apache since its @@ -1967,7 +1967,7 @@

      On the other hand mod_rewrite has to work inside the Apache API environment and needs to do some tricks to fit there. For instance the Apache API as of - 1.x really was not designed for URL rewriting at the .htaccess + 1.x really was not designed for URL rewriting at the .htaccess level of processing. Or the problem of multiple rewrites in sequence, which is also not handled by the API per design. To provide this features mod_rewrite has to do some special (but API compliant!) handling which leads diff --git a/docs/manual/misc/client_block_api.html b/docs/manual/misc/client_block_api.html index ea7896b46a..4f65341af6 100644 --- a/docs/manual/misc/client_block_api.html +++ b/docs/manual/misc/client_block_api.html @@ -13,73 +13,73 @@ ALINK="#FF0000" > -

      Reading Client Input in Apache 1.2

      +

      Reading Client Input in Apache 1.2

      -
      +
      -

      Apache 1.1 and earlier let modules handle POST and PUT requests by +

      Apache 1.1 and earlier let modules handle POST and PUT requests by themselves. The module would, on its own, determine whether the request had an entity, how many bytes it was, and then called a -function (read_client_block) to get the data. +function (read_client_block) to get the data. -

      However, HTTP/1.1 requires several things of POST and PUT request +

      However, HTTP/1.1 requires several things of POST and PUT request handlers that did not fit into this module, and all existing modules have to be rewritten. The API calls for handling this have been further abstracted, so that future HTTP protocol changes can be -accomplished while remaining backwards-compatible.

      +accomplished while remaining backwards-compatible.

      -
      +

      The New API Functions

      -
      +
          int setup_client_block (request_rec *, int read_policy);
    int should_client_block (request_rec *);
    long get_client_block (request_rec *, char *buffer, int buffer_size);
-
      
+
      -
        -
      1. Call setup_client_block() near the beginning of the request +
          +
        1. Call setup_client_block() near the beginning of the request handler. This will set up all the necessary properties, and will return either OK, or an error code. If the latter, the module should return that error code. The second parameter selects the policy to apply if the request message indicates a body, and how a chunked transfer-coding should be interpreted. Choose one of -
          +
               REQUEST_NO_BODY          Send 413 error if message has any body
     REQUEST_CHUNKED_ERROR    Send 411 error if body without Content-Length
     REQUEST_CHUNKED_DECHUNK  If chunked, remove the chunks for me.
     REQUEST_CHUNKED_PASS     Pass the chunks to me without removal.
-
          
+
          In order to use the last two options, the caller MUST provide a buffer large enough to hold a chunk-size line, including any extensions. -
        2. When you are ready to possibly accept input, call - should_client_block(). +
        3. When you are ready to possibly accept input, call + should_client_block(). This will tell the module whether or not to read input. If it is 0, the module should assume that the input is of a non-entity type (e.g. a GET request). A nonzero response indicates that the module should proceed (to step 3). This step also sends a 100 Continue response to HTTP/1.1 clients, so should not be called until the module - is *definitely* ready to read content. (otherwise, the point of the + is *definitely* ready to read content. (otherwise, the point of the 100 response is defeated). Never call this function more than once. -
        4. Finally, call get_client_block in a loop. Pass it a +
        5. Finally, call get_client_block in a loop. Pass it a buffer and its size. It will put data into the buffer (not necessarily the full buffer, in the case of chunked inputs), and return the length of the input block. When it is done reading, it will return 0 if EOF, or -1 if there was an error. -
        +
      -

      As an example, please look at the code in -mod_cgi.c. This is properly written to the new API -guidelines.

      +

      As an example, please look at the code in +mod_cgi.c. This is properly written to the new API +guidelines.

      diff --git a/docs/manual/misc/compat_notes.html b/docs/manual/misc/compat_notes.html index 64abbbe18b..213fc302f4 100644 --- a/docs/manual/misc/compat_notes.html +++ b/docs/manual/misc/compat_notes.html @@ -21,8 +21,8 @@ a couple gotcha's to watch out for. These are mostly due to the fact that the parser for config and access control files was rewritten from scratch, so certain liberties the earlier servers took may not be available here. These are all easily fixable. If you know of other -non-fatal problems that belong here, let us know. +non-fatal problems that belong here, let us know.

      Please also check the known bugs page, and the known client @@ -34,13 +34,13 @@ problems page.

    3. The basic mod_auth AuthGroupFile-specified group file format allows commas between user names - Apache does not.
      - - added 12/1/96 + - added 12/1/96

    4. If you follow the NCSA guidelines for setting up access restrictions based on client domain, you may well have added entries for, AuthType, AuthName, AuthUserFile or AuthGroupFile. - None of these are needed (or appropriate) for restricting access + None of these are needed (or appropriate) for restricting access based on client domain.

      When Apache sees AuthType it (reasonably) assumes you @@ -63,7 +63,7 @@ problems page.

      -

    5. exec cgi="" produces reasonable malformed header +
    6. exec cgi="" produces reasonable malformed header responses when used to invoke non-CGI scripts.
      The NCSA code ignores the missing header. (bad idea)
      Solution: write CGI to the CGI spec or use exec cmd="" instead. @@ -83,8 +83,8 @@ problems page.

    7. Icons for FancyIndexing broken - well, no, they're not broken, we've just upgraded the icons from flat .xbm files to pretty and much smaller .gif files, courtesy of -Kevin Hughes at -EIT. +Kevin Hughes at +EIT. If you are using the same srm.conf from an old distribution, make sure you add the new page.

      valid group name (i.e., "nogroup") not the numeric group ID. The distribution httpd.conf, and earlier ones, had the default Group be "#-1", which - was causing silent exits at startup.

      + was causing silent exits at startup.

      -

    8. .asis files: Apache 0.6.5 did not require a Status header; +
    9. .asis files: Apache 0.6.5 did not require a Status header; it added one automatically if the .asis file contained a Location header. -0.8.14 requires a Status header.

      +0.8.14 requires a Status header.

    10. Apache versions before 1.2b1 will ignore the last line of configuration @@ -123,16 +123,16 @@ it added one automatically if the .asis file contained a Location header.
    11. Apache's <VirtualHost> treats all addresses as "optional" (i.e. the server should continue booting if it can't resolve the address). Whereas in NCSA the default is to fail booting unless - an added optional keyword is included. + an added optional keyword is included.
    12. Apache does not implement OnDeny use - ErrorDocument + ErrorDocument instead.
    13. Apache (as of 1.3) always performs the equivalent of - HostnameLookups minimal. minimal is not an - option to - HostnameLookups. + HostnameLookups minimal. minimal is not an + option to + HostnameLookups.
    14. To embed spaces in directive arguments NCSA used a backslash before the space. Apache treats backslashes as normal characters. To diff --git a/docs/manual/misc/descriptors.html b/docs/manual/misc/descriptors.html index db028bf907..5841e10e1e 100644 --- a/docs/manual/misc/descriptors.html +++ b/docs/manual/misc/descriptors.html @@ -15,11 +15,11 @@

      Descriptors and Apache

      -

      A descriptor, also commonly called a file handle is +

      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 stdin, -stdout, and stderr which are descriptors 0, +by an integer, and you may be familiar with 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 @@ -28,7 +28,7 @@ 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). -

      The operating system enforces a limit on the number of descriptors +

      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 @@ -44,49 +44,49 @@ 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: +

      To summarize: -

      +
         #open files  <=  soft limit  <=  hard limit  <=  kernel limit
-
      
+
      -

      You control the hard and soft limits using the limit (csh) -or ulimit (sh) directives. See the respective man pages +

      You control the hard and soft limits using the 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 +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. -

      Unfortunately, it's not always this simple. As mentioned above, +

      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): -

      +
      -
      BSDI 2.0 -
      Under BSDI 2.0 you can build Apache to support more descriptors - by adding -DFD_SETSIZE=nnn to - EXTRA_CFLAGS (where nnn is the number of descriptors +
      BSDI 2.0 +
      Under BSDI 2.0 you can build Apache to support more descriptors + by adding -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+ -
      Similar to the BSDI 2.0 case, you should define - FD_SETSIZE and rebuild. But the extra +
      FreeBSD 2.2, BSDI 2.1+ +
      Similar to the BSDI 2.0 case, you should define + FD_SETSIZE and rebuild. But the extra Listen limitation doesn't exist. -

      +

      -

      Linux -
      By default Linux has a kernel maximum of 256 open descriptors +
      Linux +
      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. + 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 @@ -95,34 +95,34 @@ situation somewhat. Here is a partial list of systems and workarounds 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 through 2.5.1 -
      Solaris has a kernel hard limit of 1024 (may be lower in earlier +
      Solaris through 2.5.1 +
      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 -DHIGH_SLACK_LINE=256 added to - EXTRA_CFLAGS. You will be limited to approximately + build Apache with -DHIGH_SLACK_LINE=256 added to + EXTRA_CFLAGS. You will be limited to approximately 240 error logs if you do this. -

      +

      -

      AIX -
      AIX version 3.2?? appears to have a hard limit of 128 descriptors. +
      AIX +
      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. -

      +

      -

      Others -
      If you have details on another operating system, please submit - it through our Bug - Report Page. -

      +

      Others +
      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 +

      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 @@ -131,23 +131,23 @@ 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 +

      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, +

      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 LOW_SLACK_LINE and there's a tiny -bit of documentation in the header file httpd.h. - -

      Finally, if you suspect that all this slack stuff is causing you -problems, you can disable it. Add -DNO_SLACK to -EXTRA_CFLAGS and rebuild. But please report it to -our Bug -Report Page so that +time parameter is LOW_SLACK_LINE and there's a tiny +bit of documentation in the header file httpd.h. + +

      Finally, if you suspect that all this slack stuff is causing you +problems, you can disable it. Add -DNO_SLACK to +EXTRA_CFLAGS and rebuild. But please report it to +our Bug +Report Page so that we can investigate. diff --git a/docs/manual/misc/fin_wait_2.html b/docs/manual/misc/fin_wait_2.html index 0027263f8e..135b8b06e0 100644 --- a/docs/manual/misc/fin_wait_2.html +++ b/docs/manual/misc/fin_wait_2.html @@ -21,7 +21,7 @@

    15. What is the FIN_WAIT_2 state?

      Starting with the Apache 1.2 betas, people are reporting many more connections in the FIN_WAIT_2 state (as reported by -netstat) than they saw using older versions. When the +netstat) than they saw using older versions. When the server closes a TCP connection, it sends a packet with the FIN bit sent 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 diff --git a/docs/manual/misc/howto.html b/docs/manual/misc/howto.html index a7d6b38c3c..0fa77d96be 100644 --- a/docs/manual/misc/howto.html +++ b/docs/manual/misc/howto.html @@ -18,49 +18,49 @@

      Apache HOWTO documentation

      How to: - +

      How to redirect an entire server or directory to a single URL

      There are two chief ways to redirect all requests for an entire server to a single location: one which requires the use of -mod_rewrite, and another which uses a CGI script. +mod_rewrite, and another which uses a CGI script.

      First: if all you need to do is migrate a server from one name to -another, simply use the Redirect directive, as supplied -by mod_alias: +another, simply use the Redirect directive, as supplied +by mod_alias: -

      +
         Redirect / http://www.apache.org/
-
      
+
      -

      Since Redirect will forward along the complete path, +

      Since Redirect will forward along the complete path, however, it may not be appropriate - for example, when the directory structure has changed after the move, and you simply want to direct people to the home page. -

      The best option is to use the standard Apache module mod_rewrite. +

      The best option is to use the standard Apache module mod_rewrite. If that module is compiled in, the following lines: -

      RewriteEngine On
+
      RewriteEngine On
 RewriteRule /.* http://www.apache.org/ [R]
-
      
+
      This will send an HTTP 302 Redirect back to the client, and no matter what they gave in the original URL, they'll be sent to "http://www.apache.org". The second option is to set up a ScriptAlias pointing to -a cgi script which outputs a 301 or 302 status and the location +a cgi script which outputs a 301 or 302 status and the location of the other server.

      -

      By using a cgi-script you can intercept various requests and -treat them specially, e.g. you might want to intercept POST +

      By using a cgi-script you can intercept various requests and +treat them specially, e.g. you might want to intercept POST requests, so that the client isn't redirected to a script on the other server which expects POST information (a redirect will lose the POST information.) You might also want to use a CGI script if you don't @@ -68,17 +68,17 @@ want to compile mod_rewrite into your server.

      Here's how to redirect all requests to a script... In the server configuration file, -

      ScriptAlias / /usr/local/httpd/cgi-bin/redirect_script
      +
      ScriptAlias / /usr/local/httpd/cgi-bin/redirect_script
      and here's a simple perl script to redirect requests: -
      +
       #!/usr/local/bin/perl
 
 print "Status: 302 Moved Temporarily\r
 Location: http://www.some.where.else.com/\r\n\r\n";
 
-
      
+

      @@ -100,14 +100,14 @@ characters.

      The correct procedure is to move the logfile, then signal Apache to tell it to reopen the logfiles.

      -

      Apache is signaled using the SIGHUP (-1) signal. e.g. -

      +

      Apache is signaled using the SIGHUP (-1) signal. e.g. +

      mv access_log access_log.old
      kill -1 `cat httpd.pid` -
      +

      -

      Note: httpd.pid is a file containing the process id +

      Note: httpd.pid is a file containing the process id of the Apache httpd daemon, Apache saves this in the same directory as the log files.

      @@ -118,16 +118,16 @@ nightly or weekly basis.

      How to stop or restrict robots

      Ever wondered why so many clients are interested in a file called -robots.txt which you don't have, and never did have?

      +robots.txt which you don't have, and never did have?

      -

      These clients are called robots (also known as crawlers, +

      These clients are called robots (also known as crawlers, spiders and other cute name) - special automated clients which wander around the web looking for interesting resources.

      -

      Most robots are used to generate some kind of web index which -is then used by a search engine to help locate information.

      +

      Most robots are used to generate some kind of web index which +is then used by a search engine to help locate information.

      -

      robots.txt provides a means to request that robots limit their +

      robots.txt provides a means to request that robots limit their activities at the site, or more often than not, to leave the site alone.

      When the first robots were developed, they had a bad reputation for diff --git a/docs/manual/misc/index.html b/docs/manual/misc/index.html index b8a5608b32..b9eb945cc3 100644 --- a/docs/manual/misc/index.html +++ b/docs/manual/misc/index.html @@ -13,7 +13,7 @@ ALINK="#FF0000" > -

      Apache Miscellaneous Documentation

      +

      Apache Miscellaneous Documentation

      Below is a list of additional documentation pages that apply to the diff --git a/docs/manual/misc/known_client_problems.html b/docs/manual/misc/known_client_problems.html index fddb1c25f8..59de0de7bb 100644 --- a/docs/manual/misc/known_client_problems.html +++ b/docs/manual/misc/known_client_problems.html @@ -15,119 +15,119 @@

      Known Problems in Clients

      -

      Over time the Apache Group has discovered or been notified of problems +

      Over time the Apache Group has discovered or been notified of problems with various clients which we have had to work around. 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, and MSIE will refer to Microsoft's Internet Explorer +

      For brevity, Navigator will refer to Netscape's Navigator +product, 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 +

      For reference, +RFC1945 defines HTTP/1.0, and -RFC2068 +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. +

      Various of these workarounds are triggered by environment variables. The admin typically controls which are set, and for which clients, by using -mod_browser. Unless otherwise +mod_browser. Unless otherwise noted all of these workarounds exist in versions 1.2 and later. -

      Trailing CRLF on POSTs

      +

      Trailing CRLF on POSTs

       -

      This is a legacy issue. The CERN webserver required 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. +

      This is a legacy issue. The CERN webserver required 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

      +

      Broken keepalive

       -

      Various clients have had broken implementations of keepalive +

      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: -

      +
      BrowserMatch Mozilla/2 nokeepalive -
      +
      Note that this matches some earlier versions of MSIE, which began the -practice of calling themselves Mozilla in their user-agent +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 +

      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 nokeepalive code +responses. Unfortunately Apache's 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: -

      +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

       +

      Incorrect interpretation of HTTP/1.1 in response

       -

      To quote from section 3.1 of RFC1945: -

      -HTTP uses a "." numbering scheme to indicate versions +

      To quote from section 3.1 of RFC1945: +

      +HTTP uses a "." 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. -
      +
      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. +

      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 force-response-1.0 +anticipation of similar problems, the 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. -

      The pre-1.1 Java Development Kit (JDK) that is used in many clients +

      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: -

      -BrowserMatch Java1.0 force-response-1.0
      +
      +BrowserMatch Java1.0 force-response-1.0
      BrowserMatch JDK/1.0 force-response-1.0 -
      +
      -

      RealPlayer 4.0 from Progressive Networks also exhibits this problem. +

      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 User-Agent as version 4.0. The +4.01 uses the same 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

       +

      Requests use HTTP/1.1 but responses must be in HTTP/1.0

       -

      MSIE 4.0b2 has this problem. Its Java VM makes requests in HTTP/1.1 +

      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 +does not understand chunked responses). The workaround is to fool Apache into believing the request came in HTTP/1.0 format. -

      +
      BrowserMatch "MSIE 4\.0b2;" downgrade-1.0 force-response-1.0 -
      +
      This workaround is available in 1.2.2, and in a -patch - against 1.2.1. +patch + against 1.2.1. -

      Boundary problems with header parsing

       +

      Boundary problems with header parsing

       -

      All versions of Navigator from 2.0 through 4.0b2 (and possibly later) +

      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 @@ -135,18 +135,18 @@ on all responses. The workaround is to detect when this condition would occur in a response and add extra padding to the header to push the trailing CRLF past offset 258 of the response. -

      Multipart responses and Quoted Boundary Strings

      +

      Multipart responses and Quoted Boundary Strings

       -

      On multipart responses some clients will not accept quotes (") +

      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. -

      Byterange requests

      +

      Byterange requests

       -

      A byterange request is used when the client wishes to retrieve a +

      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 @@ -155,66 +155,66 @@ 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 -Request-Range, and a response type -multipart/x-byteranges. The HTTP/1.1 standard includes +

      A subsequent draft of this standard defines a header +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. - -

      Navigator (versions 2 and 3) sends both 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. - -

      The Adobe Acrobat Reader plugin makes extensive use of byteranges and -prior to version 3.01 supports only the multipart/x-byterange +Range and type multipart/byteranges. + +

      Navigator (versions 2 and 3) sends both 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. + +

      The Adobe Acrobat Reader plugin makes extensive use of byteranges and +prior to version 3.01 supports only the 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 +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. -

      Netscape Communicator appears to not issue the non-standard -Request-Range header. When an Acrobat plugin prior to +

      Netscape Communicator appears to not issue the non-standard +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 unmergeable

      +

      Set-Cookie header is unmergeable

       -

      The HTTP specifications say that it is legal to merge headers with +

      The HTTP specifications say that it is legal to merge headers with duplicate names into one (separated by semicolon). Some browsers that support Cookies don't like merged headers and prefer that each -Set-Cookie header is sent separately. When parsing the +Set-Cookie header is sent separately. When parsing the headers returned by a CGI, Apache will explicitly avoid merging any -Set-Cookie headers. +Set-Cookie headers. -

      Expires headers and GIF89A animations

      +

      Expires headers and GIF89A animations

       -

      Navigator versions 2 through 4 will erroneously re-request +

      Navigator versions 2 through 4 will erroneously re-request GIF89A animations on each loop of the animation if the first -response included an Expires header. This happens +response included an Expires 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. +is no workaround supplied with Apache, however there are hacks for 1.2 +and for 1.3. -

      POST without Content-Length

      +

      POST without Content-Length

       -

      In certain situations Navigator 3.01 through 3.03 appear to incorrectly +

      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. +information. There's also - -some information about the actual problem. + +some information about the actual problem. diff --git a/docs/manual/misc/perf-tuning.html b/docs/manual/misc/perf-tuning.html index f75fbf926b..33aab731a6 100644 --- a/docs/manual/misc/perf-tuning.html +++ b/docs/manual/misc/perf-tuning.html @@ -1,15 +1,15 @@ - - -Apache Performance Notes - + + +Apache Performance Notes + -

      Apache Performance Notes

      +

      Apache Performance Notes

      -

      Author: Dean Gaudet +

      Author: Dean Gaudet

      Introduction

      -

      Apache is a general webserver, which is designed to be correct first, and +

      Apache is a general webserver, which is designed to be correct first, and fast second. Even so, it's performance is quite satisfactory. Most sites have less than 10Mbits of outgoing bandwidth, which Apache can fill using only a low end Pentium-based webserver. In practice sites @@ -18,7 +18,7 @@ due to other constraints (such as CGI or database transaction overhead). For these reasons the development focus has been mostly on correctness and configurability. -

      Unfortunately many folks overlook these facts and cite raw performance +

      Unfortunately many folks overlook these facts and cite raw performance numbers as if they are some indication of the quality of a web server product. There is a bare minimum performance that is acceptable, beyond that extra speed only caters to a much smaller segment of the market. @@ -26,32 +26,32 @@ But in order to avoid this hurdle to the acceptance of Apache in some markets, effort was put into Apache 1.3 to bring performance up to a point where the difference with other high-end webservers is minimal. -

      Finally there are the folks who just plain want to see how fast something +

      Finally there are the folks who just plain want to see how fast something can go. The author falls into this category. The rest of this document is dedicated to these folks who want to squeeze every last bit of performance out of Apache's current model, and want to understand why it does some things which slow it down. -

      Note that this is tailored towards Apache 1.3 on Unix. Some of it applies +

      Note that this is tailored towards Apache 1.3 on Unix. Some of it applies to Apache on NT. Apache on NT has not been tuned for performance yet, in fact it probably performs very poorly because NT performance requires a different programming model.

      Hardware and Operating System Issues

      -

      The single biggest hardware issue affecting webserver performance +

      The single biggest hardware issue affecting webserver performance is RAM. A webserver should never ever have to swap, 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 MaxClients +the load. You can, and should, control the MaxClients setting so that your server does not spawn so many children it starts swapping. -

      Beyond that the rest is mundane: get a fast enough CPU, a fast enough +

      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 +

      Operating system choice is largely a matter of local concerns. But a general guideline is to always apply the latest vendor TCP/IP patches. HTTP serving completely breaks many of the assumptions built into Unix kernels up through 1994 and even 1995. Good choices include @@ -60,56 +60,56 @@ recent FreeBSD, and Linux.

      Run-Time Configuration Issues

      HostnameLookups

      -

      Prior to Apache 1.3, HostnameLookups defaulted to On. +

      Prior to Apache 1.3, 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. -However (1.3 or later), if you use any allow from domain or -deny from domain directives then you will pay for a +However (1.3 or later), if you use any allow from domain or +deny from domain directives then you will pay for a double reverse DNS lookup (a reverse, followed by a forward to make sure that the reverse is not being spoofed). So for the highest performance avoid using these directives (it's fine to use IP addresses rather than domain names). -

      Note that it's possible to scope the directives, such as within -a <Location /server-status> section. In this +

      Note that it's possible to scope the directives, such as within +a <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>
-
      
+
      But even still, if you just need DNS names in some CGIs you could consider doing the -gethostbyname call in the specific CGIs that need it. +gethostbyname call in the specific CGIs that need it.

      FollowSymLinks and SymLinksIfOwnerMatch

      -

      Wherever in your URL-space you do not have an -Options FollowSymLinks, or you do have an -Options SymLinksIfOwnerMatch Apache will have to +

      Wherever in your URL-space you do not have an +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>
-
      
+
      -and a request is made for the URI /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, +and a request is made for the URI /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
@@ -117,72 +117,72 @@ DocumentRoot /www/htdocs
 <Directory /www/htdocs>
     Options -FollowSymLinks +SymLinksIfOwnerMatch
 </Directory>
-
      
+
      -This at least avoids the extra checks for the DocumentRoot +This at least avoids the extra checks for the DocumentRoot path. Note that you'll need to add similar sections if you have any -Alias or RewriteRule paths outside of your +Alias or RewriteRule paths outside of your document root. For highest performance, and no symlink protection, -set FollowSymLinks everywhere, and never set -SymLinksIfOwnerMatch. +set FollowSymLinks everywhere, and never set +SymLinksIfOwnerMatch.

      AllowOverride

      -

      Wherever in your URL-space you allow overrides (typically -.htaccess files) Apache will attempt to open -.htaccess for each filename component. For example, +

      Wherever in your URL-space you allow overrides (typically +.htaccess files) Apache will attempt to open +.htaccess for each filename component. For example, -

      +
       DocumentRoot /www/htdocs
 <Directory />
     AllowOverride all
 </Directory>
-
      
+
      -and a request is made for the URI /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. +and a request is made for the URI /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

      -

      If at all possible, avoid content-negotiation if you're really +

      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: -

      +
       DirectoryIndex index
-
      
+
      Use a complete list of options: -
      +
       DirectoryIndex index.cgi index.pl index.shtml index.html
-
      
+
      where you list the most common choice first.

      Process Creation

      -

      Prior to Apache 1.3 the MinSpareServers, -MaxSpareServers, and StartServers settings +

      Prior to Apache 1.3 the 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 +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 +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. -

      The one-per-second rule was implemented in an effort to avoid +

      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 @@ -191,61 +191,61 @@ 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 -MinSpareServers setting. +MinSpareServers setting. -

      This appears to be responsive enough that it's -almost unnecessary to twiddle the MinSpareServers, -MaxSpareServers and StartServers knobs. When +

      This appears to be responsive enough that it's +almost unnecessary to twiddle the 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 +to the ErrorLog. If you see a lot of these errors then +consider tuning these settings. Use the mod_status output as a guide. -

      Related to process creation is process death induced by the -MaxRequestsPerChild setting. By default this is 30, which +

      Related to process creation is process death induced by the +MaxRequestsPerChild setting. By default this is 30, which is probably far too low unless your server is using a module such as -mod_perl which causes children to have bloated memory +mod_perl which causes children to have bloated memory images. If your server is serving mostly static pages then consider raising this value to something like 10000. The code is robust enough that this shouldn't be a problem. -

      When keep-alives are in use, children will be kept busy +

      When keep-alives are in use, children will be kept busy doing nothing waiting for more requests on the already open -connection. The default KeepAliveTimeout of +connection. The default 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. + +most of the benefits are lost.

      Compile-Time Configuration Issues

      mod_status and Rule STATUS=yes

      -

      If you include mod_status -and you also set Rule STATUS=yes when building +

      If you include mod_status +and you also set Rule STATUS=yes when building Apache, then on every request Apache will perform two calls to -gettimeofday(2) (or times(2) depending +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 Rule -STATUS=no. +time(2). This is all done so that the status report +contains timing indications. For highest performance, set Rule +STATUS=no.

      accept Serialization - multiple sockets

      -

      This discusses a shortcoming in the Unix socket API. +

      This discusses a shortcoming in the Unix socket API. Suppose your -web server uses multiple Listen statements to listen on +web server uses multiple 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 none or -at least one connection waiting on it. Apache's model includes +socket to see if a connection is ready Apache uses select(2). +select(2) indicates that a socket has none 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;
@@ -267,43 +267,43 @@ pedagogical purposes):
 	}
 	process the new_connection;
     }
-
      
+
      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 select when they are in between +children will block at 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 +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 +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. +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 +PR#467. There are at least two solutions. -

      One solution is to make the sockets non-blocking. In this case the -accept won't block the children, and they will be allowed +

      One solution is to make the sockets non-blocking. In this case the +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 +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 +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. -

      Another solution, the one used by Apache, is to serialize entry into +

      Another solution, the one used by Apache, is to serialize entry into the inner loop. The loop looks like this (differences highlighted): -

      +
           for (;;) {
-	accept_mutex_on ();
+	accept_mutex_on ();
 	for (;;) {
 	    fd_set accept_fds;
 
@@ -322,64 +322,64 @@ the inner loop.  The loop looks like this (differences highlighted):
 	    }
 	    if (new_connection != -1) break;
 	}
-	accept_mutex_off ();
+	accept_mutex_off ();
 	process the new_connection;
     }
-
      
+
      - -The functions accept_mutex_on and accept_mutex_off + +The functions 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/main/conf.h (1.3 or later). Some architectures +mutexes. The choice is defined in src/conf.h (pre-1.3) or +src/main/conf.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. +to use multiple Listen directives. -
      -
      USE_FLOCK_SERIALIZED_ACCEPT -
      This method uses the flock(2) system call to lock a -lock file (located by the LockFile directive). +
      +
      USE_FLOCK_SERIALIZED_ACCEPT +
      This method uses the flock(2) system call to lock a +lock file (located by the LockFile directive). -
      USE_FCNTL_SERIALIZED_ACCEPT -
      This method uses the fcntl(2) system call to lock a -lock file (located by the LockFile directive). +
      USE_FCNTL_SERIALIZED_ACCEPT +
      This method uses the fcntl(2) system call to lock a +lock file (located by the LockFile directive). -
      USE_SYSVSEM_SERIALIZED_ACCEPT -
      (1.3 or later) This method uses SysV-style semaphores to implement the +
      USE_SYSVSEM_SERIALIZED_ACCEPT +
      (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 ipcs(8) man page). The other is that the semaphore +(see the ipcs(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). -
      USE_USLOCK_SERIALIZED_ACCEPT -
      (1.3 or later) This method is only available on IRIX, and uses -usconfig(2) to create a mutex. While this method avoids +
      USE_USLOCK_SERIALIZED_ACCEPT +
      (1.3 or later) This method is only available on IRIX, and uses +usconfig(2) to create a mutex. While this method avoids the hassles of SysV-style semaphores, it is not the default for IRIX. This is because on single processor IRIX boxes (5.3 or 6.2) the uslock code is two orders of magnitude slower than the SysV-semaphore code. On multi-processor IRIX boxes the uslock code is an order of magnitude faster than the SysV-semaphore code. Kind of a messed up situation. So if you're using a multiprocessor IRIX box then you should rebuild your -webserver with -DUSE_USLOCK_SERIALIZED_ACCEPT on the -EXTRA_CFLAGS. +webserver with -DUSE_USLOCK_SERIALIZED_ACCEPT on the +EXTRA_CFLAGS. -
      USE_PTHREAD_SERIALIZED_ACCEPT -
      (1.3 or later) This method uses POSIX mutexes and should work on +
      USE_PTHREAD_SERIALIZED_ACCEPT +
      (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). This is the default for Solaris 2.5 or later. -
      +
      -

      If your system has another method of serialization which isn't in the +

      If your system has another method of serialization which isn't in the above list then it may be worthwhile adding code for it (and submitting a patch back to Apache). -

      Another solution that has been considered but never implemented is +

      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 @@ -387,26 +387,26 @@ 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 Listen +

      Ideally you should run servers without multiple Listen statements if you want the highest performance. But read on.

      accept Serialization - single socket

      -

      The above is fine and dandy for multiple socket servers, but what +

      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 -accept(2) until a connection arrives, and no starvation +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 +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. -

      For this reason we have found that many architectures behave more +

      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 @@ -415,20 +415,20 @@ 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 SINGLE_LISTEN_UNSERIALIZED_ACCEPT +serialization you can define SINGLE_LISTEN_UNSERIALIZED_ACCEPT and then single-socket servers will not serialize at all.

      Lingering Close

      -

      As discussed in -draft-ietf-http-connection-00.txt section 8, -in order for an HTTP server to reliably implement the protocol +

      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 +

      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 FIN_WAIT_2 state has a timeout, but it doesn't prohibit it. On systems without the timeout, @@ -438,17 +438,17 @@ 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. -

      There are two ways of accomplishing this. One is the -socket option SO_LINGER. But as fate would have it, +

      There are two ways of accomplishing this. One is the +socket option 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. -

      For the most part, Apache implements this in a function called -lingering_close (in http_main.c). The +

      For the most part, Apache implements this in a function called +lingering_close (in http_main.c). The function looks roughly like this: -

      +
           void lingering_close (int s)
     {
 	char junk_buffer[2048];
@@ -470,48 +470,48 @@ function looks roughly like this:
 
 	close (s);
     }
-
      
+
      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 NO_LINGCLOSE, but +disable this feature you can define NO_LINGCLOSE, but this is not recommended at all. In particular, as HTTP/1.1 pipelined -persistent connections come into use lingering_close +persistent connections come into use lingering_close is an absolute necessity (and - -pipelined connections are faster, so you + +pipelined connections are faster, so you want to support them).

      Scoreboard File

      -

      Apache's parent and children communicate with each other through +

      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 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 +(and less featured). Peruse the 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 +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 +

      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

      +

      DYNAMIC_MODULE_LIMIT

      -

      If you have no intention of using dynamically loaded modules +

      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 --DDYNAMIC_MODULE_LIMIT=0 when building your server. +-DDYNAMIC_MODULE_LIMIT=0 when building your server. This will save RAM that's allocated only for supporting dynamically loaded modules. @@ -520,21 +520,21 @@ loaded modules. Here is a system call trace of Apache 1.3 running on Linux. The run-time configuration file is essentially the default plus: -

      +
       <Directory />
     AllowOverride none
     Options FollowSymLinks
 </Directory>
-
      
+
      The file being requested is a static 6K file of no particular content. Traces of non-static requests or requests with content negotiation look wildly different (and quite ugly in some cases). First the entire trace, then we'll examine details. (This was generated by -the strace program, other similar programs include -truss, ktrace, and par.) +the strace program, other similar programs include +truss, ktrace, and par.) -
      +
       accept(15, {sin_family=AF_INET, sin_port=htons(22283), sin_addr=inet_addr("127.0.0.1")}, [16]) = 3
 flock(18, LOCK_UN)                      = 0
 sigaction(SIGUSR1, {SIG_IGN}, {0x8059954, [], SA_INTERRUPT}) = 0
@@ -560,31 +560,31 @@ close(3)                                = 0
 sigaction(SIGUSR1, {0x8059954, [], SA_INTERRUPT}, {SIG_IGN}) = 0
 munmap(0x400ee000, 6144)                = 0
 flock(18, LOCK_EX)                      = 0
-
      
+
      -

      Notice the accept serialization: +

      Notice the accept serialization: -

      +
       flock(18, LOCK_UN)                      = 0
 ...
 flock(18, LOCK_EX)                      = 0
-
      
+
      These two calls can be removed by defining -SINGLE_LISTEN_UNSERIALIZED_ACCEPT as described earlier. +SINGLE_LISTEN_UNSERIALIZED_ACCEPT as described earlier. -

      Notice the SIGUSR1 manipulation: +

      Notice the SIGUSR1 manipulation: -

      +
       sigaction(SIGUSR1, {SIG_IGN}, {0x8059954, [], SA_INTERRUPT}) = 0
 ...
 sigaction(SIGUSR1, {SIG_IGN}, {SIG_IGN}) = 0
 ...
 sigaction(SIGUSR1, {0x8059954, [], SA_INTERRUPT}, {SIG_IGN}) = 0
-
      
+
      This is caused by the implementation of graceful restarts. When the -parent receives a SIGUSR1 it sends a SIGUSR1 +parent receives a SIGUSR1 it sends a SIGUSR1 to all of its children (and it also increments a "generation counter" in shared memory). Any children that are idle (between connections) will immediately die @@ -593,7 +593,7 @@ connections, but are in between requests will die off immediately. But any children that have a connection and are still waiting for the first request will not die off immediately. -

      To see why this is necessary, consider how a browser reacts to a closed +

      To see why this is necessary, consider how a browser reacts to a closed connection. If the connection was a keep-alive connection and the request being serviced was not the first request then the browser will quietly reissue the request on a new connection. It has to do this because the @@ -605,40 +605,40 @@ dialogue (or a broken image icon). This is done on the assumption that the server is broken in some way (or maybe too overloaded to respond at all). So Apache tries to avoid ever deliberately closing the connection before it has sent a single response. This is the cause of those -SIGUSR1 manipulations. +SIGUSR1 manipulations. -

      Note that it is theoretically possible to eliminate all three of +

      Note that it is theoretically possible to eliminate all three of these calls. But in rough tests the gain proved to be almost unnoticeable. -

      In order to implement virtual hosts, Apache needs to know the +

      In order to implement virtual hosts, Apache needs to know the local socket address used to accept the connection: -

      +
       getsockname(3, {sin_family=AF_INET, sin_port=htons(8080), sin_addr=inet_addr("127.0.0.1")}, [16]) = 0
-
      
+
      It is possible to eliminate this call in many situations (such as when -there are no virtual hosts, or when Listen directives are +there are no virtual hosts, or when Listen directives are used which do not have wildcard addresses). But no effort has yet been made to do these optimizations. -

      Apache turns off the Nagle algorithm: +

      Apache turns off the Nagle algorithm: -

      +
       setsockopt(3, IPPROTO_TCP1, [1], 4)     = 0
-
      
+
      because of problems described in -a -paper by John Heidemann. +a +paper by John Heidemann. -

      Notice the two time calls: +

      Notice the two time calls: -

      +
       time(NULL)                              = 873959960
 ...
 time(NULL)                              = 873959960
-
      
+
      One of these occurs at the beginning of the request, and the other occurs as a result of writing the log. At least one of these is required to @@ -647,115 +647,115 @@ Common Log Format dictates that the log record include a timestamp of the end of the request. A custom logging module could eliminate one of the calls. -

      As described earlier, Rule STATUS=yes causes two -gettimeofday calls and a call to times: +

      As described earlier, Rule STATUS=yes causes two +gettimeofday calls and a call to times: -

      +
       gettimeofday({873959960, 404935}, NULL) = 0
 ...
 gettimeofday({873959960, 417742}, NULL) = 0
 times({tms_utime=5, tms_stime=0, tms_cutime=0, tms_cstime=0}) = 446747
-
      
+
      -These can be removed by either removing mod_status or -setting Rule STATUS=no. +These can be removed by either removing mod_status or +setting Rule STATUS=no. -

      It might seem odd to call stat: +

      It might seem odd to call stat: -

      +
       stat("/home/dgaudet/ap/apachen/htdocs/6k", {st_mode=S_IFREG|0644, st_size=6144, ...}) = 0
-
      
+
      This is part of the algorithm which calculates the -PATH_INFO for use by CGIs. In fact if the request had been -for the URI /cgi-bin/printenv/foobar then there would be -two calls to stat. The first for -/home/dgaudet/ap/apachen/cgi-bin/printenv/foobar +PATH_INFO for use by CGIs. In fact if the request had been +for the URI /cgi-bin/printenv/foobar then there would be +two calls to stat. The first for +/home/dgaudet/ap/apachen/cgi-bin/printenv/foobar which does not exist, and the second for -/home/dgaudet/ap/apachen/cgi-bin/printenv, which does exist. -Regardless, at least one stat call is necessary when +/home/dgaudet/ap/apachen/cgi-bin/printenv, which does exist. +Regardless, at least one stat call is necessary when serving static files because the file size and modification times are -used to generate HTTP headers (such as Content-Length, -Last-Modified) and implement protocol features (such -as If-Modified-Since). A somewhat more clever server -could avoid the stat when serving non-static files, +used to generate HTTP headers (such as Content-Length, +Last-Modified) and implement protocol features (such +as If-Modified-Since). A somewhat more clever server +could avoid the stat when serving non-static files, however doing so in Apache is very difficult given the modular structure. -

      All static files are served using mmap: +

      All static files are served using mmap: -

      +
       mmap(0, 6144, PROT_READ, MAP_PRIVATE, 4, 0) = 0x400ee000
 ...
 munmap(0x400ee000, 6144)                = 0
-
      
+
      -On some architectures it's slower to mmap small -files than it is to simply read them. The define -MMAP_THRESHOLD can be set to the minimum -size required before using mmap. By default +On some architectures it's slower to mmap small +files than it is to simply read them. The define +MMAP_THRESHOLD can be set to the minimum +size required before using mmap. By default it's set to 0 (except on SunOS4 where experimentation has -shown 8192 to be a better value). Using a tool such as lmbench you +shown 8192 to be a better value). Using a tool such as lmbench you can determine the optimal setting for your environment. -

      You may also wish to experiment with MMAP_SEGMENT_SIZE +

      You may also wish to experiment with MMAP_SEGMENT_SIZE (default 32768) which determines the maximum number of bytes that will be written at a time from mmap()d files. Apache only resets the -client's Timeout in between write()s. So setting this +client's Timeout in between write()s. So setting this large may lock out low bandwidth clients unless you also increase the -Timeout. +Timeout. -

      It may even be the case that mmap isn't -used on your architecture, if so then defining USE_MMAP_FILES -and HAVE_MMAP might work (if it works then report back to us). +

      It may even be the case that mmap isn't +used on your architecture, if so then defining USE_MMAP_FILES +and HAVE_MMAP might work (if it works then report back to us). -

      Apache does its best to avoid copying bytes around in memory. The -first write of any request typically is turned into a writev +

      Apache does its best to avoid copying bytes around in memory. The +first write of any request typically is turned into a writev which combines both the headers and the first hunk of data: -

      +
       writev(3, [{"HTTP/1.1 200 OK\r\nDate: Thu, 11"..., 245}, {"\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0"..., 6144}], 2) = 6389
-
      
+
      When doing HTTP/1.1 chunked encoding Apache will generate up to four -element writevs. The goal is to push the byte copying +element writevs. The goal is to push the byte copying into the kernel, where it typically has to happen anyhow (to assemble network packets). On testing, various Unixes (BSDI 2.x, Solaris 2.5, Linux 2.0.31+) properly combine the elements into network packets. Pre-2.0.31 Linux will not combine, and will create a packet for -each element, so upgrading is a good idea. Defining NO_WRITEV +each element, so upgrading is a good idea. Defining NO_WRITEV will disable this combining, but result in very poor chunked encoding performance. -

      The log write: +

      The log write: -

      +
       write(17, "127.0.0.1 - - [10/Sep/1997:23:39"..., 71) = 71
-
      
+
      -can be deferred by defining BUFFERED_LOGS. In this case -up to PIPE_BUF bytes (a POSIX defined constant) of log entries +can be deferred by defining BUFFERED_LOGS. In this case +up to PIPE_BUF bytes (a POSIX defined constant) of log entries are buffered before writing. At no time does it split a log entry -across a PIPE_BUF boundary because those writes may not +across a PIPE_BUF boundary because those writes may not be atomic. (i.e. entries from multiple children could become mixed together). The code does it best to flush this buffer when a child dies. -

      The lingering close code causes four system calls: +

      The lingering close code causes four system calls: -

      +
       shutdown(3, 1 /* send */)               = 0
 oldselect(4, [3], NULL, [3], {2, 0})    = 1 (in [3], left {2, 0})
 read(3, "", 2048)                       = 0
 close(3)                                = 0
-
      
+
      which were described earlier. -

      Let's apply some of these optimizations: --DSINGLE_LISTEN_UNSERIALIZED_ACCEPT -DBUFFERED_LOGS and -Rule STATUS=no. Here's the final trace: +

      Let's apply some of these optimizations: +-DSINGLE_LISTEN_UNSERIALIZED_ACCEPT -DBUFFERED_LOGS and +Rule STATUS=no. Here's the final trace: -

      +
       accept(15, {sin_family=AF_INET, sin_port=htons(22286), sin_addr=inet_addr("127.0.0.1")}, [16]) = 3
 sigaction(SIGUSR1, {SIG_IGN}, {0x8058c98, [], SA_INTERRUPT}) = 0
 getsockname(3, {sin_family=AF_INET, sin_port=htons(8080), sin_addr=inet_addr("127.0.0.1")}, [16]) = 0
@@ -775,15 +775,15 @@ read(3, "", 2048)                       = 0
 close(3)                                = 0
 sigaction(SIGUSR1, {0x8058c98, [], SA_INTERRUPT}, {SIG_IGN}) = 0
 munmap(0x400e3000, 6144)                = 0
-
      
+
      That's 19 system calls, of which 4 remain relatively easy to remove, but don't seem worth the effort.

      Appendix: The Pre-Forking Model

      -

      Apache (on Unix) is a pre-forking model server. The -parent process is responsible only for forking child +

      Apache (on Unix) is a pre-forking model server. The +parent process is responsible only for forking child processes, it does not serve any requests or service any network sockets. The child processes actually process connections, they serve multiple connections (one at a time) before dying. @@ -791,7 +791,7 @@ The parent spawns new or kills off old children in response to changes in the load on the server (it does so by monitoring a scoreboard which the children keep up to date). -

      This model for servers offers a robustness that other models do +

      This model for servers offers a robustness that other models do not. In particular, the parent code is very simple, and with a high degree of confidence the parent will continue to do its job without error. The children are complex, and when you add in third party @@ -800,22 +800,22 @@ corruption. Even should such a thing happen, it only affects one connection and the server continues serving requests. The parent quickly replaces the dead child. -

      Pre-forking is also very portable across dialects of Unix. +

      Pre-forking is also very portable across dialects of Unix. Historically this has been an important goal for Apache, and it continues to remain so. -

      The pre-forking model comes under criticism for various +

      The pre-forking model comes under criticism for various performance aspects. Of particular concern are the overhead of forking a process, the overhead of context switches between processes, and the memory overhead of having multiple processes. Furthermore it does not offer as many opportunities for data-caching -between requests (such as a pool of mmapped files). +between requests (such as a pool of mmapped files). Various other models exist and extensive analysis can be found in the - papers -of the JAWS project. In practice all of these costs vary drastically + papers +of the JAWS project. In practice all of these costs vary drastically depending on the operating system. -

      Apache's core code is already multithread aware, and Apache version +

      Apache's core code is already multithread aware, and Apache version 1.3 is multithreaded on NT. There have been at least two other experimental implementations of threaded Apache (one using the 1.3 code base on DCE, and one using a custom user-level threads package and the 1.0 code base, @@ -824,5 +824,5 @@ of Apache will include abstractions of the server model so that we can continue to support the pre-forking model, and also support various threaded models. - - + + diff --git a/docs/manual/misc/security_tips.html b/docs/manual/misc/security_tips.html index 715ccb90d7..d454122ebc 100644 --- a/docs/manual/misc/security_tips.html +++ b/docs/manual/misc/security_tips.html @@ -15,51 +15,51 @@

      Security Tips for Server Configuration

      -
      +

      Some hints and tips on security issues in setting up a web server. Some of the suggestions will be general, others specific to Apache.

      - -

      Permissions on ServerRoot Directories

       + +

      Permissions on ServerRoot Directories

      In typical operation, Apache is started by the root -user, and it switches to the user defined by the User directive to serve hits. +user, and it switches to the user defined by the 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 +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
-
      
+
      It is assumed that /, /usr, and /usr/local are only modifiable by root. When you install the 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
-
      
+
      -

      You can create an htdocs subdirectory which is modifiable by other +

      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 +

      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 httpd binary so that the next time you start it, it will execute some arbitrary code. If the logs @@ -73,16 +73,16 @@ may be able to overwrite the log itself with bogus data.

      Server Side Includes

      Server side includes (SSI) can be configured so that users can execute arbitrary programs on the server. That thought alone should send a shiver -down the spine of any sys-admin.

      +down the spine of any sys-admin.

      One solution is to disable that part of SSI. To do that you use the IncludesNOEXEC option to the Options -directive.

      +directive.

      Non Script Aliased CGI

      -

      Allowing users to execute CGI scripts in any directory should only +

      Allowing users to execute CGI scripts in any directory should only be considered if;

      1. You trust your users not to write scripts which will deliberately or @@ -90,23 +90,23 @@ accidentally expose your system to an attack.
      2. You consider security at your site to be so feeble in other areas, as to make one more potential hole irrelevant.
      3. You have no users, and nobody ever visits your server. -

      +

    Script Alias'ed CGI

    -

    Limiting CGI to special directories gives the admin control over +

    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 +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.

    +Most sites choose this option over the non script aliased CGI approach.

    CGI in general

    Always remember that you must trust the writers of the CGI script/programs or your ability to spot potential security holes in CGI, whether they were -deliberate or accidental.

    +deliberate or accidental.

    All the CGI scripts will run as the same user, so they have potential to conflict (accidentally or deliberately) with other scripts e.g. @@ -123,21 +123,21 @@ the Apache server code. Another popular way of doing this is with

    Stopping users overriding system wide settings...

    To run a really tight ship, you'll want to stop users from setting up .htaccess files which can override security features -you've configured. Here's one way to do it...

    +you've configured. Here's one way to do it...

    In the server configuration file, put -

    -<Directory />
    -AllowOverride None
    -Options None
    -allow from all
    -</Directory>
    -
    +
    +<Directory />
    +AllowOverride None
    +Options None
    +allow from all
    +</Directory>
    +
    Then setup for specific directories

    This stops all overrides, Includes and accesses in all directories apart -from those named.

    +from those named.

    Protect server files by default @@ -220,7 +220,7 @@ by filling out a problem report, or by sending mail to apache-bugs@mail.apache.org -

    +

    diff --git a/docs/manual/mod/core.html b/docs/manual/mod/core.html index e2b7232ad5..1c4d650726 100644 --- a/docs/manual/mod/core.html +++ b/docs/manual/mod/core.html @@ -14,144 +14,144 @@ > -

    Apache Core Features

    +

    Apache Core Features

    These configuration parameters control the core Apache features, and are always available.

    Directives

    - -
    + +

    AccessConfig directive

    -Syntax: AccessConfig filename
    -Default: AccessConfig conf/access.conf
    -Context: server config, virtual host
    -Status: core

    +Syntax: AccessConfig filename
    +Default: AccessConfig conf/access.conf
    +Context: server config, virtual host
    +Status: core

    The server will read this file for more directives after reading the -ResourceConfig file. Filename is +ResourceConfig file. Filename is relative to the ServerRoot. This feature can be disabled using: -

    AccessConfig /dev/null
    +
    AccessConfig /dev/null
    Historically, this file only contained <Directory> sections; in fact it can now -contain any server directive allowed in the server config context. -

    +contain any server directive allowed in the server config context. +

    AccessFileName directive

    -Syntax: AccessFileName filename filename ...
    -Default: AccessFileName .htaccess
    -Context: server config, virtual host
    -Status: core
    -Compatibility: AccessFileName can accept more than one filename only in Apache 1.3 and later

    +Syntax: AccessFileName filename filename ...
    +Default: AccessFileName .htaccess
    +Context: server config, virtual host
    +Status: core
    +Compatibility: AccessFileName can accept more than one filename only in Apache 1.3 and later

    When returning a document to the client the server looks for the first existing access control file from this list of names in every directory of the path to the document, if access control files are enabled for that directory. For example: -

    AccessFileName .acl
    +
    AccessFileName .acl
    before returning the document /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>

    +
    +<Directory />
    +AllowOverride None
    +</Directory>

    AddModule directive

    -Syntax: AddModule module module ...
    -Context: server config
    -Status: core
    -Compatibility: AddModule is only available in Apache 1.2 and later

    +Syntax: AddModule module module ...
    +Context: server config
    +Status: core
    +Compatibility: AddModule is only available in Apache 1.2 and later

    The server can have modules compiled in which are not actively in use. This directive can be used to enable the use of those modules. The server comes with a pre-loaded list of active modules; this list can be cleared with the ClearModuleList -directive.

    +directive.

    AllowOverride directive

    -Syntax: AllowOverride override override ...
    -Default: AllowOverride All
    -Context: directory
    -Status: core

    +Syntax: AllowOverride override override ...
    +Default: AllowOverride All
    +Context: directory
    +Status: core

    When the server finds an .htaccess file (as specified by AccessFileName) it needs to know which -directives declared in that file can override earlier access information.

    +directives declared in that file can override earlier access information.

    -Override can be set to None, in which case the server -will not read the file, All in which case the server will +Override can be set to None, in which case the server +will not read the file, All in which case the server will allow all the directives, or one or more of the following: -

    -
    AuthConfig -
    +
    +
    AuthConfig +
    Allow use of the authorization directives (AuthDBMGroupFile, @@ -160,8 +160,8 @@ Allow use of the authorization directives AuthName, AuthType, AuthUserFile, require, etc.). -
    FileInfo -
    +
    FileInfo +
    Allow use of the directives controlling document types (AddEncoding, @@ -170,8 +170,8 @@ Allow use of the directives controlling document types DefaultType, ErrorDocument, LanguagePriority, etc.). -
    Indexes -
    +
    Indexes +
    Allow use of the directives controlling directory indexing (AddDescription, @@ -185,24 +185,24 @@ Allow use of the directives controlling directory indexing IndexIgnore, IndexOptions, ReadmeName, etc.). -
    Limit -
    +
    Limit +
    Allow use of the directives controlling host access (allow, deny and order). -
    Options -
    +
    Options +
    Allow use of the directives controlling specific directory features (Options and XBitHack). -

    +

    AuthName directive

    -Syntax: AuthName auth-domain
    -Context: directory, .htaccess
    -Override: AuthConfig
    -Status: core

    +Syntax: AuthName auth-domain
    +Context: directory, .htaccess
    +Override: AuthConfig
    +Status: core

    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 @@ -210,81 +210,81 @@ password to send. It must be accompanied by AuthType and require directives, and directives such as AuthUserFile and -AuthGroupFile to work.

    +AuthGroupFile to work.

    AuthType directive

    -Syntax: AuthType type
    -Context: directory, .htaccess
    -Override: AuthConfig
    -Status: core

    +Syntax: AuthType type
    +Context: directory, .htaccess
    +Override: AuthConfig
    +Status: core

    This directive selects the type of user authentication for a directory. -Only Basic is currently implemented. +Only Basic is currently implemented. It must be accompanied by AuthName and require directives, and directives such as AuthUserFile and -AuthGroupFile to work.

    +AuthGroupFile to work.

    BindAddress directive

    -Syntax: BindAddress saddr
    -Default: BindAddress *
    -Context: server config
    -Status: core

    +Syntax: BindAddress saddr
    +Default: BindAddress *
    +Context: server config
    +Status: core

    A Unix® http server can either listen for connections to every IP address of the server machine, or just one IP address of the server -machine. Saddr can be +machine. Saddr can be -

    -
  3. * -
  4. An IP address -
  5. A fully-qualified Internet domain name -
    6.  + +
  6. * +
  7. An IP address +
  8. A fully-qualified Internet domain name +
    9.  If the value is *, then the server will listen for connections on every IP address, otherwise it will only listen on the IP address -specified.

    +specified.

    -Only one BindAddress directive can be used. For more +Only one BindAddress directive can be used. For more control over which address and ports Apache listens to, use the -Listen directive instead of -BindAddress.

    +Listen directive instead of +BindAddress.

    -BindAddress can be used as an alternative method for +BindAddress can be used as an alternative method for supporting virtual hosts using -multiple independent servers, instead of using <VirtualHost> sections. +multiple independent servers, instead of using <VirtualHost> sections. -

    See Also: -DNS Issues
    -See Also: -Setting which addresses and ports Apache uses

    +

    See Also: +DNS Issues
    +See Also: +Setting which addresses and ports Apache uses

    -
    +

    ClearModuleList directive

    -Syntax: ClearModuleList
    -Context: server config
    -Status: core
    -Compatibility: ClearModuleList is only available in Apache 1.2 and later

    +Syntax: ClearModuleList
    +Context: server config
    +Status: core
    +Compatibility: ClearModuleList is only available in Apache 1.2 and later

    The server comes with a built-in list of active modules. This directive clears the list. It is assumed that the list will then be -re-populated using the AddModule directive.

    +re-populated using the AddModule directive.

    ContentDigest directive

    -Syntax: ContentDigest on|off
    -Default: ContentDigest off
    -Context: server config, virtual host, directory, .htaccess
    -Override: AuthConfig
    -Status: experimental

    -Compatibility: ContentDigest is only available in Apache 1.1 and later

    - -This directive enables the generation of Content-MD5 headers +Syntax: ContentDigest on|off
    +Default: ContentDigest off
    +Context: server config, virtual host, directory, .htaccess
    +Override: AuthConfig
    +Status: experimental

    +Compatibility: ContentDigest is only available in Apache 1.1 and later

    + +This directive enables the generation of Content-MD5 headers as defined in RFC1864 respectively RFC2068.

    MD5 is an algorithm for computing a "message digest" (sometimes called @@ -292,108 +292,108 @@ MD5 is an algorithm for computing a "message digest" (sometimes called that any alterations in the data will be reflected in alterations in the message digest.

    -The Content-MD5 header provides an end-to-end message +The 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: AuLb7Dp1rqtRtxz2m9kRpA==

    Note that this can cause performance problems on your server since the message digest is computed on every request (the values are not cached).

    -Content-MD5 is only sent for documents served by the +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. -

    +

    CoreDumpDirectory directive

    -Syntax: CoreDumpDirectory directory
    -Default: the same location as ServerRoot
    -Context: server config
    -Status: core

    +Syntax: CoreDumpDirectory directory
    +Default: the same location as ServerRoot
    +Context: server config
    +Status: core

    This controls the directory to which Apache attempts to switch before dumping core. The default is in the ServerRoot 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.

    +it in a different location.

    DefaultType directive

    -Syntax: DefaultType mime-type
    -Default: DefaultType text/html
    -Context: server config, virtual host, directory, .htaccess
    -Override: FileInfo
    -Status: core

    +Syntax: DefaultType mime-type
    +Default: DefaultType text/html
    +Context: server config, virtual host, directory, .htaccess
    +Override: FileInfo
    +Status: core

    There will be times when the server is asked to provide a document -whose type cannot be determined by its MIME types mappings.

    +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 DefaultType. For example: -

    DefaultType image/gif
    +
    DefaultType image/gif
    would be appropriate for a directory which contained many gif images -with filenames missing the .gif extension.

    +with filenames missing the .gif extension.

    <Directory> directive

    -Syntax: <Directory directory> ... </Directory>
    -Context: server config, virtual host
    -Status: Core.

    +Syntax: <Directory directory> ... </Directory>
    +Context: server config, virtual host
    +Status: Core.

    <Directory> and </Directory> are used to enclose a group of directives which will apply only to the named directory and sub-directories of that directory. Any directive which is allowed in a directory -context may be used. Directory is either the full path to a directory, +context may be used. Directory is either the full path to a directory, or a wild-card string. In a wild-card string, `?' matches any single character, and `*' matches any sequences of characters. As of Apache 1.3, you may also use `[]' character ranges like in the shell. Also as of Apache 1.3 none of the wildcards match a `/' character, which more closely mimics the behaviour of Unix shells. Example: -

    +
        <Directory /usr/local/httpd/htdocs>
    Options Indexes FollowSymLinks
    </Directory>
-
    
+
    -

    Apache 1.2 and above: +

    Apache 1.2 and above: Extended regular expressions can also be used, with the addition of the -~ character. For example:

    +~ character. For example:

    -
    +
        <Directory ~ "^/www/.*/[0-9]{3}">
-
    
+
    would match directories in /www/ that consisted of three numbers. -

    If multiple (non-regular expression) directory sections match the +

    If multiple (non-regular expression) directory sections match the directory (or 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>
    -for access to the document /home/web/dir/doc.html the +
    +<Directory />
    +AllowOverride None
    +</Directory>

    +<Directory /home/*>
    +AllowOverride FileInfo
    +</Directory>
    +for access to the document /home/web/dir/doc.html the steps are: - -
  9. Apply directive AllowOverride None (disabling -.htaccess files). -
  10. Apply directive AllowOverride FileInfo (for directory -/home/web). -
  11. Apply any FileInfo directives in /home/web/.htaccess -
    12.  + +
  12. Apply directive AllowOverride None (disabling +.htaccess files). +
  13. Apply directive AllowOverride FileInfo (for directory +/home/web). +
  14. Apply any FileInfo directives in /home/web/.htaccess +
    15.

    Regular expression directory sections are handled slightly differently @@ -404,22 +404,22 @@ possible occurs. In Apache 1.3 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 -

    -<Directory ~ abc$>
    -... directives here ...
    -</Directory>
    -
    +
    +<Directory ~ abc$>
    +... directives here ...
    +</Directory>
    +
    Suppose that the filename being accessed is -/home/abc/public_html/abc/index.html. The server -considers each of /, /home, /home/abc, -/home/abc/public_html, and /home/abc/public_html/abc +/home/abc/public_html/abc/index.html. The server +considers each of /, /home, /home/abc, +/home/abc/public_html, and /home/abc/public_html/abc in that order. In Apache 1.2, when -/home/abc is considered, the regular expression will match +/home/abc is considered, the regular expression will match and be applied. In Apache 1.3 the regular expression isn't considered at all at that point in the tree. It won't be considered until after -all normal <Directory>s and .htaccess files have +all normal <Directory>s and .htaccess files have been applied. Then the regular expression will -match on /home/abc/public_html/abc and be applied. +match on /home/abc/public_html/abc and be applied.

    @@ -449,72 +449,72 @@ page for more details. The directory sections typically occur in the access.conf file, but they may appear in any configuration file. <Directory> directives cannot nest, and cannot appear in a <Limit> section. -

    +

    -See also: How Directory, -Location and Files sections work for an explanation of how these +See also: How Directory, +Location and Files sections work for an explanation of how these different sections are combined when a request is received -

    +

    <DirectoryMatch>

    -Syntax: <DirectoryMatch regex> ... </DirectoryMatch>
    -Context: server config, virtual host
    -Status: Core.
    -Compatibility: Available in Apache 1.3 and later +Syntax: <DirectoryMatch regex> ... </DirectoryMatch>
    +Context: server config, virtual host
    +Status: Core.
    +Compatibility: Available in Apache 1.3 and later -

    <DirectoryMatch> and </DirectoryMatch> are used to enclose a group of +

    <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:

    +of that directory, the same as <Directory>. However, it takes as an +argument a regular expression. For example:

    -
    +
        <DirectoryMatch "^/www/.*/[0-9]{3}">
-
    
+
    -

    would match directories in /www/ that consisted of three numbers.

    +

    would match directories in /www/ that consisted of three numbers.

    -

    See Also: -<Directory> for a description of how +

    See Also: +<Directory> for a description of how regular expressions are mixed in with normal <Directory>s. -
    -See also: How Directory, -Location and Files sections work for an explanation of how these +
    +See also: How Directory, +Location and Files sections work for an explanation of how these different sections are combined when a request is received -

    +

    DocumentRoot directive

    -Syntax: DocumentRoot directory-filename
    -Default: DocumentRoot -/usr/local/apache/htdocs
    -Context: server config, virtual host
    -Status: core

    +Syntax: DocumentRoot directory-filename
    +Default: DocumentRoot +/usr/local/apache/htdocs
    +Context: server config, virtual host
    +Status: core

    This directive sets the directory from which 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
    -then an access to http://www.my.host.com/index.html refers -to /usr/web/index.html. +
    DocumentRoot /usr/web
    +then an access to http://www.my.host.com/index.html refers +to /usr/web/index.html.

    There appears to be a bug in mod_dir which causes problems when the DocumentRoot has a trailing slash (i.e. "DocumentRoot /usr/web/") so please avoid that. -

    +

    ErrorDocument directive

    -Syntax: ErrorDocument error-code document
    -Context: server config, virtual host, directory, .htaccess
    -Status: core
    -Override: FileInfo
    -Compatibility: The directory and .htaccess contexts -are only available in Apache 1.1 and later.

    +Syntax: ErrorDocument error-code document
    +Context: server config, virtual host, directory, .htaccess
    +Status: core
    +Override: FileInfo
    +Compatibility: The directory and .htaccess contexts +are only available in Apache 1.1 and later.

    In the event of a problem or error, Apache can be configured to do one of four things, @@ -530,19 +530,19 @@ one of four things, using the ErrorDocument directive, which is followed by the HTTP response code and a message or URL. -

    Messages in this context begin with a single quote -("), which does not form part of the message itself. +

    Messages in this context begin with a single quote +("), which does not form part of the message itself. Apache will sometimes offer additional information regarding the problem/error.

    URLs can begin with a slash (/) for local URLs, or be a full URL which the client can resolve. Examples: -

    -ErrorDocument 500 http://foo.example.com/cgi-bin/tester
    -ErrorDocument 404 /cgi-bin/bad_urls.pl
    -ErrorDocument 401 /subscription_info.html
    +
    +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 -
    +

    Note that when you specify an ErrorDocument that points to a remote URL (ie. anything with a method such as "http" in @@ -554,654 +554,654 @@ directive then it must refer to a local document. This results from the nature of the HTTP basic authentication scheme.

    See Also: documentation of customizable -responses.

    +responses.

    ErrorLog directive

    -Syntax: ErrorLog filename
    -Default: ErrorLog logs/error_log
    -Context: server config, virtual host
    -Status: core

    +Syntax: ErrorLog filename
    +Default: ErrorLog logs/error_log
    +Context: server config, virtual host
    +Status: core

    The error log directive sets the name of the file to which the server will log any errors it encounters. If the filename does not begin with a slash (/) then it is assumed to be relative to the ServerRoot. Example: -

    ErrorLog /dev/null
    -This effectively turns off error logging.

    +

    ErrorLog /dev/null
    +This effectively turns off error logging.

    SECURITY: 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. -

    +

    <Files> directive

    -Syntax: <Files filename> -... </Files>
    -Context: server config, virtual host, .htaccess
    -Status: core
    -Compatibility: only available in Apache -1.2 and above.

    - -

    The <Files> directive provides for access control by -filename. It is comparable to the <Directory> directive and -<Location> directives. It +Syntax: <Files filename> +... </Files>
    +Context: server config, virtual host, .htaccess
    +Status: core
    +Compatibility: only available in Apache +1.2 and above.

    + +

    The <Files> directive provides for access control by +filename. It is comparable to the <Directory> directive and +<Location> directives. It should be matched with a </Files> directive. Directives that apply to the filename given should be listed -within. <Files> sections are processed in the +within. <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.

    +<Directory> sections and .htaccess files are +read, but before <Location> sections.

    -

    The filename argument should include a filename, or a +

    The filename argument should include a filename, or a wild-card string, where `?' 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:

    +the ~ character. For example:

    -
    +
        <Files ~ "\.(gif|jpe?g|png)$">
-
    
+
    would match most common Internet graphics formats. In Apache 1.3 and -later, <FilesMatch> is preferred, +later, <FilesMatch> is preferred, however. -

    Note that unlike <Directory> and <Location> sections, -<Files> sections can be used inside .htaccess +

    Note that unlike <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. When used in an .htaccess file, if the -filename does not begin with a / character, +filename does not begin with a / character, the directory being applied will be prefixed automatically. -

    +

    -See also: How Directory, -Location and Files sections work for an explanation of how these +See also: How Directory, +Location and Files sections work for an explanation of how these different sections are combined when a request is received -

    +

    <FilesMatch>

    -Syntax: <FilesMatch regex> -... </Files>
    -Context: server config, virtual host, .htaccess
    -Status: core
    -Compatibility: only available in Apache -1.3 and above.

    - -

    The <FilesMatch> directive provides for access control by -filename, just as the <Files> directive -does. However, it accepts a regular expression. For example:

    - -
    +Syntax: <FilesMatch regex>
+... </Files>
    
+Context: server config, virtual host, .htaccess
    
+Status: core
    
+Compatibility: only available in Apache
+1.3 and above.
    
+
+
    The <FilesMatch> directive provides for access control by
+filename, just as the <Files> directive
+does. However, it accepts a regular expression. For example:
    
+
+
        <FilesMatch "\.(gif|jpe?g|png)$">
-
    
+
    -

    would match most common Internet graphics formats.

    +

    would match most common Internet graphics formats.

    -See also: How Directory, -Location and Files sections work for an explanation of how these +See also: How Directory, +Location and Files sections work for an explanation of how these different sections are combined when a request is received -
    +

    Group directive

    -Syntax: Group unix-group
    -Default: Group #-1
    -Context: server config, virtual host
    -Status: core

    +Syntax: Group unix-group
    +Default: Group #-1
    +Context: server config, virtual host
    +Status: core

    The Group directive sets the group under which the server will answer requests. In order to use this directive, the stand-alone server must be run initially -as root. Unix-group is one of: -

    -
    A group name -
    Refers to the given group by name. -
    # followed by a group number. -
    Refers to a group by its number. -
    +as root. Unix-group is one of: +
    +
    A group name +
    Refers to the given group by name. +
    # followed by a group number. +
    Refers to a group by its number. +
    It is recommended that you set up a new group specifically for running the -server. Some admins use user nobody, but this is not always -possible or desirable.

    +server. Some admins use user nobody, but this is not always +possible or desirable.

    Note: 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.

    +original user.

    Special note: Use of this directive in <VirtualHost> requires a properly configured suEXEC wrapper. When used inside a <VirtualHost> in this manner, only the group that CGIs are run as is affected. Non-CGI requests are still processed -as the group specified in the main Group directive.

    +as the group specified in the main Group directive.

    SECURITY: See User for a discussion of the security -considerations.

    +considerations.

    HostNameLookups directive

    -Syntax: HostNameLookups on | off | double
    -Default: HostNameLookups off
    -Context: server config, virtual host, directory, .htaccess
    -Status: core
    -Compatibility: double available only in Apache -1.3 and above.
    -Compatibility: Default was on prior to Apache -1.3.

    +Syntax: HostNameLookups on | off | double
    +Default: HostNameLookups off
    +Context: server config, virtual host, directory, .htaccess
    +Status: core
    +Compatibility: double available only in Apache +1.3 and above.
    +Compatibility: Default was on prior to Apache +1.3.

    This directive enables DNS lookups so that host names can be logged (and -passed to CGIs/SSIs in REMOTE_HOST). -The value double refers to doing double-reverse DNS. +passed to CGIs/SSIs in REMOTE_HOST). +The value double refers to doing double-reverse DNS. 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.)

    +this is called PARANOID.)

    -Regardless of the setting, when mod_access +Regardless of the setting, when 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 +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.

    +result in REMOTE_HOST.

    -The default for this directive was previously on in -versions of Apache prior to 1.3. It was changed to off +The default for this directive was previously on in +versions of Apache prior to 1.3. It was changed to 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, -provided in the /support directory, can be used to look up host names -from logged IP addresses offline.

    +Heavily loaded sites should leave this directive off, since DNS +lookups can take considerable amounts of time. The utility logresolve, +provided in the /support directory, can be used to look up host names +from logged IP addresses offline.

    IdentityCheck directive

    -Syntax: IdentityCheck boolean
    -Default: IdentityCheck off
    -Context: server config, virtual host, directory, .htaccess
    -Status: core

    +Syntax: IdentityCheck boolean
    +Default: IdentityCheck off
    +Context: server config, virtual host, directory, .htaccess
    +Status: core

    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. Boolean is either -on or off.

    +This information is logged in the access log. Boolean is either +on or off.

    The information should not be trusted in any way except for rudimentary usage -tracking.

    +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. -

    +

    <IfModule> directive

    -Syntax: <IfModule [!]module-name> ... -</IfModule>
    -Default: None
    -Context: all
    -Status: Core
    -Compatibility: IfModule is only available in 1.2 and +Syntax: <IfModule [!]module-name> ... +</IfModule>
    +Default: None
    +Context: all
    +Status: Core
    +Compatibility: IfModule is only available in 1.2 and later.

    -

    +

    -The <IfModule test>...</IfModule> +The <IfModule test>...</IfModule> section is used to mark directives that are conditional. The directives within an IfModule section are only -processed if the test is true. If test +processed if the test is true. If test is false, everything between the start and end markers -is ignored.

    +is ignored.

    -The test in the <IfModule> section directive +The test in the <IfModule> section directive can be one of two forms: -

      -
    • module name -
    • !module name -
    +
      +
    • module name +
    • !module name +
    -

    In the former case, the directives between the start and end markers -are only processed if the module named module name is compiled +

    In the former case, the directives between the start and end markers +are only processed if the module named module name is compiled in to Apache. The second format reverses the test, and only processes -the directives if module name is not compiled in. +the directives if module name is not compiled in. -

    The module name argument is a module name as given as the file +

    The module name argument is a module name as given as the file name of the module, at the time it was compiled. For example, -mod_rewrite.c. +mod_rewrite.c. -

    <IfModule> sections are nest-able, which can be used to implement +

    <IfModule> sections are nest-able, which can be used to implement simple multiple-module tests. -

    +

    -

    Include directive

    -Syntax: (Apache 1.2) Include filename
    -Context: server config
    -Status: Core
    -Compatibility: Include is only available in Apache 1.3 and later. +

    Include directive

    +Syntax: (Apache 1.2) Include filename
    +Context: server config
    +Status: Core
    +Compatibility: Include is only available in Apache 1.3 and later.

    This directive allows inclusion of other configuration files from within the server configuration files. -

    +

    -

    KeepAlive directive

    -Syntax: (Apache 1.1) KeepAlive max-requests
    -Default: (Apache 1.1) KeepAlive 5
    -Syntax: (Apache 1.2) KeepAlive on/off
    -Default: (Apache 1.2) KeepAlive On
    -Context: server config
    -Status: Core
    -Compatibility: KeepAlive is only available in Apache -1.1 and later.

    +

    KeepAlive directive

    +Syntax: (Apache 1.1) KeepAlive max-requests
    +Default: (Apache 1.1) KeepAlive 5
    +Syntax: (Apache 1.2) KeepAlive on/off
    +Default: (Apache 1.2) KeepAlive On
    +Context: server config
    +Status: Core
    +Compatibility: KeepAlive is only available in Apache +1.1 and later.

    This directive enables -Keep-Alive +Keep-Alive support. -

    Apache 1.1: Set max-requests +

    Apache 1.1: Set max-requests to the maximum number of requests you want Apache to entertain per request. A limit is imposed to prevent a client from hogging your -server resources. Set this to 0 to disable support. +server resources. Set this to 0 to disable support. -

    Apache 1.2 and later: Set to "On" to enable -persistent connections, "Off" to disable. See also the MaxKeepAliveRequests directive.

    +

    Apache 1.2 and later: Set to "On" to enable +persistent connections, "Off" to disable. See also the MaxKeepAliveRequests directive.

    -

    KeepAliveTimeout directive

    -Syntax: KeepAliveTimeout seconds
    -Default: KeepAliveTimeout 15
    -Context: server config
    -Status: Core
    -Compatibility: KeepAliveTimeout is only available in Apache -1.1 and later.

    +

    KeepAliveTimeout directive

    +Syntax: KeepAliveTimeout seconds
    +Default: KeepAliveTimeout 15
    +Context: server config
    +Status: Core
    +Compatibility: KeepAliveTimeout is only available in Apache +1.1 and later.

    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 Timeout directive +value specified by the Timeout directive applies. -

    +

    <Limit> directive

    -Syntax: - <Limit method method ... > ... </Limit>
    -Context: any
    -Status: core

    +Syntax: + <Limit method method ... > ... </Limit>
    +Context: any
    +Status: core

    <Limit> and </Limit> are used to enclose a group of access control directives which will then apply only to the specified -access methods, where method is any valid HTTP method. +access methods, where method is any valid HTTP method. Any directive except another <Limit> or <Directory> may be used; the majority will be unaffected by the <Limit>. Example: -

    -<Limit GET POST>
    -require valid-user
    -</Limit>
    +
    +<Limit GET POST>
    +require valid-user
    +</Limit>
    If an access control directive appears outside a <Limit> directive, then it applies to all access methods. The method names listed can be one or more of: GET, POST, PUT, DELETE, CONNECT or OPTIONS. If GET is used it will also restrict HEAD requests. If you wish to limit all methods, do not include any -<Limit> directive at all.

    +<Limit> directive at all.

    Listen directive

    -Syntax: -Listen [IP address:]port number
    -Context: server config
    -Status: core
    -Compatibility: Listen is only available in Apache -1.1 and later.

    - -

    The Listen directive instructs Apache to listen to more than one IP +Syntax: +Listen [IP address:]port number
    +Context: server config
    +Status: core
    +Compatibility: Listen is only available in Apache +1.1 and later.

    + +

    The Listen directive instructs Apache to listen to more than one IP address or port; by default it responds to requests on all IP -interfaces, but only on the port given by the Port directive.

    +interfaces, but only on the port given by the Port directive.

    -Listen can be used instead of BindAddress and Port. It tells +Listen can be used instead of BindAddress and Port. It tells the server to accept incoming requests on the specified port or address-and-port combination. If the first format is used, with a port number only, the server listens to the given port on all interfaces, -instead of the port given by the Port directive. If an IP +instead of the port given by the Port directive. If an IP address is given as well as a port, the server will listen on the -given port and interface.

    +given port and interface.

    -Note that you may still require a Port directive so +Note that you may still require a Port directive so that URLs that Apache generates that point to your server still -work.

    +work.

    Multiple 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. -

    +

    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
-
    
+
    -

    See Also: -DNS Issues
    -See Also: -Setting which addresses and ports Apache uses
    -See Also: -Known Bugs

    -
    +

    See Also: +DNS Issues
    +See Also: +Setting which addresses and ports Apache uses
    +See Also: +Known Bugs

    +

    ListenBacklog directive

    -Syntax: ListenBacklog backlog
    -Default: ListenBacklog 511
    -Context: server config
    -Status: Core
    -Compatibility: ListenBacklog is only available in Apache -versions after 1.2.0.

    +Syntax: ListenBacklog backlog
    +Default: ListenBacklog 511
    +Context: server config
    +Status: Core
    +Compatibility: ListenBacklog is only available in Apache +versions after 1.2.0.

    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 listen(2) system call.

    +the backlog parameter to the listen(2) system call.

    -

    <Location> directive

    +

    <Location> directive

    -Syntax: <Location URL> -... </Location>
    -Context: server config, virtual host
    -Status: core
    -Compatibility: Location is only available in Apache -1.1 and later.

    +Syntax: <Location URL> +... </Location>
    +Context: server config, virtual host
    +Status: core
    +Compatibility: Location is only available in Apache +1.1 and later.

    -

    The <Location> directive provides for access control by -URL. It is comparable to the <Directory> directive, and +

    The <Location> directive provides for access control by +URL. It is comparable to the <Directory> directive, and should be matched with a </Location> directive. Directives that apply to the URL given should be listed -within. <Location> sections are processed in the +within. <Location> sections are processed in the order they appear in the configuration file, after the -<Directory> sections and .htaccess files are -read.

    +<Directory> sections and .htaccess files are +read.

    -

    Note that, due to the way HTTP functions, URL prefix -should, save for proxy requests, be of the form /path/, -and should not include the http://servername. It doesn't +

    Note that, due to the way HTTP functions, URL prefix +should, save for proxy requests, be of the form /path/, +and should not include the http://servername. It doesn't necessarily have to protect a directory (it can be an individual file, or a number of files), and can include wild-cards. In a wild-card string, `?' matches any single character, and `*' matches any sequences of characters. -

    Apache 1.2 and above: +

    Apache 1.2 and above: Extended regular expressions can also be used, with the addition of the -~ character. For example:

    +~ character. For example:

    -
    +
        <Location ~ "/(extra|special)/data">
-
    
+
    -

    would match URLs that contained the substring "/extra/data" or -"/special/data". However, in Apache 1.3 and above, use of <LocationMatch> is preferred.

    +

    would match URLs that contained the substring "/extra/data" or +"/special/data". However, in Apache 1.3 and above, use of <LocationMatch> is preferred.

    -

    The Location functionality is especially useful when -combined with the SetHandler directive. For example, to enable status requests, but allow them only +

    The 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>
-
    
+
    -

    -See also: How Directory, -Location and Files sections work for an explanation of how these +

    +See also: How Directory, +Location and Files sections work for an explanation of how these different sections are combined when a request is received -

    +
    -

    <LocationMatch>

    +

    <LocationMatch>

    -Syntax: <LocationMatch regex> -... </LocationMatch>
    -Context: server config, virtual host
    -Status: core
    -Compatibility: Location is only available in Apache -1.3 and later.

    +Syntax: <LocationMatch regex> +... </LocationMatch>
    +Context: server config, virtual host
    +Status: core
    +Compatibility: Location is only available in Apache +1.3 and later.

    -

    The <LocationMatch> directive provides for access control by -URL, in an identical manner to <Location>. However, it takes a regular -expression as an argument instead of a simple string. For example:

    +

    The <LocationMatch> directive provides for access control 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">
-
    
+
    -

    would match URLs that contained the substring "/extra/data" or -"/special/data".

    +

    would match URLs that contained the substring "/extra/data" or +"/special/data".

    -See also: How Directory, -Location and Files sections work for an explanation of how these +See also: How Directory, +Location and Files sections work for an explanation of how these different sections are combined when a request is received -
    +

    LockFile directive

    -Syntax: LockFile filename
    -Default: LockFile logs/accept.lock
    -Context: server config
    -Status: core

    +Syntax: LockFile filename
    +Default: LockFile logs/accept.lock
    +Context: server config
    +Status: core

    The LockFile directive sets the path to the lockfile used when Apache is compiled with either USE_FCNTL_SERIALIZED_ACCEPT or USE_FLOCK_SERIALIZED_ACCEPT. 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.

    +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: It is best to avoid putting this file in a world writable directory such as /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.

    +server will try to create.

    MaxClients directive

    -Syntax: MaxClients number
    -Default: MaxClients 256
    -Context: server config
    -Status: core

    +Syntax: MaxClients number
    +Default: MaxClients 256
    +Context: server config
    +Status: core

    The MaxClients directive sets the limit on the number of simultaneous requests that can be supported; not more than this number of child server -processes will be created.

    +processes will be created.

    MaxKeepAliveRequests directive

    -Syntax: MaxKeepAliveRequests number
    -Default: MaxKeepAliveRequests 100
    -Context: server config
    -Status: core
    -Compatibility: Only available in Apache +Syntax: MaxKeepAliveRequests number
    +Default: MaxKeepAliveRequests 100
    +Context: server config
    +Status: core
    +Compatibility: Only available in Apache 1.2 and later. -

    The MaxKeepAliveRequests directive limits the number of requests -allowed per connection when KeepAlive is -on. If it is set to "0", unlimited requests will be +

    The 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.

    +maximum server performance.

    MaxRequestsPerChild directive

    -Syntax: MaxRequestsPerChild number
    -Default: MaxRequestsPerChild 0
    -Context: server config
    -Status: core

    +Syntax: MaxRequestsPerChild number
    +Default: MaxRequestsPerChild 0
    +Context: server config
    +Status: core

    The MaxRequestsPerChild 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.

    +the process will never expire.

    Setting MaxRequestsPerChild to a non-zero limit has two beneficial effects: -

      -
    • it limits the amount of memory that process can consume by (accidental) +
        +
      • it limits the amount of memory that process can consume by (accidental) memory leakage; -
      • by giving processes a finite lifetime, it helps reduce the +
      • by giving processes a finite lifetime, it helps reduce the number of processes when the server load reduces. -

      +

    MaxSpareServers directive

    -Syntax: MaxSpareServers number
    -Default: MaxSpareServers 10
    -Context: server config
    -Status: core

    +Syntax: MaxSpareServers number
    +Default: MaxSpareServers 10
    +Context: server config
    +Status: core

    -The MaxSpareServers directive sets the desired maximum number of idle +The MaxSpareServers directive sets the desired maximum number of idle child server processes. An idle process is one which is not handling a request. If there are more than MaxSpareServers idle, then the parent -process will kill off the excess processes.

    +process will kill off the excess processes.

    Tuning of this parameter should only be necessary on very busy sites. -Setting this parameter to a large number is almost always a bad idea.

    +Setting this parameter to a large number is almost always a bad idea.

    See also MinSpareServers and -StartServers.

    +StartServers.

    MinSpareServers directive

    -Syntax: MinSpareServers number
    -Default: MinSpareServers 5
    -Context: server config
    -Status: core

    +Syntax: MinSpareServers number
    +Default: MinSpareServers 5
    +Context: server config
    +Status: core

    -The MinSpareServers directive sets the desired minimum number of idle +The MinSpareServers directive sets the desired minimum number of idle child server processes. An idle process is one which is not handling a request. If there are fewer than MinSpareServers idle, then the parent -process creates new children at a maximum rate of 1 per second.

    +process creates new children at a maximum rate of 1 per second.

    Tuning of this parameter should only be necessary on very busy sites. -Setting this parameter to a large number is almost always a bad idea.

    +Setting this parameter to a large number is almost always a bad idea.

    See also MaxSpareServers and -StartServers.

    +StartServers.

    NameVirtualHost directive

    -Syntax: NameVirtualHost addr[:port]
    -Context: server config
    -Status: core

    -Compatibility: NameVirtualHost is only available in Apache 1.3 and later

    +Syntax: NameVirtualHost addr[:port]
    +Context: server config
    +Status: core

    +Compatibility: NameVirtualHost is only available in Apache 1.3 and later

    The NameVirtualHost directive is a required directive if you want to configure -name-based virtual hosts.

    +name-based virtual hosts.

    -Although addr can be hostname it is recommended that you always use +Although addr can be hostname it is recommended that you always use an IP address, e.g. -

    NameVirtualHost 111.22.33.44
    +
    NameVirtualHost 111.22.33.44
    With the NameVirtualHost directive the address to which your name-based virtual host names resolve. If you have multiple name-based hosts on multiple addresses, -repeat the directive for each address.

    +repeat the directive for each address.

    Optionally you can specify a port number on which the name-based virtual hosts should be used, e.g. -

    NameVirtualHost 111.22.33.44:8080
    +
    NameVirtualHost 111.22.33.44:8080
    -See also: -Apache Virtual Host documentation +See also: +Apache Virtual Host documentation

    Options directive

    -Syntax: Options [+|-]option [+|-]option ...
    -Context: server config, virtual host, directory, .htaccess
    -Override: Options
    -Status: core

    +Syntax: Options [+|-]option [+|-]option ...
    +Context: server config, virtual host, directory, .htaccess
    +Override: Options
    +Status: core

    The Options directive controls which server features are available in a particular directory. -

    -option can be set to None, in which case none of +

    +option can be set to None, in which case none of the extra features are enabled, or one or more of the following: -

    -
    All -
    All options except for MultiViews. -
    ExecCGI -
    +
    +
    All +
    All options except for MultiViews. +
    ExecCGI +
    Execution of CGI scripts is permitted. -
    FollowSymLinks -
    +
    FollowSymLinks +
    The server will follow symbolic links in this directory. -Note: even though the server follows the symlink it does not -change the pathname used to match against <Directory> +Note: even though the server follows the symlink it does not +change the pathname used to match against <Directory> sections. -
    Includes -
    +
    Includes +
    Server-side includes are permitted. -
    IncludesNOEXEC -
    +
    IncludesNOEXEC +
    Server-side includes are permitted, but the #exec command and #include of CGI scripts are disabled. -
    Indexes -
    +
    Indexes +
    If a URL which maps to a directory is requested, and the there is no DirectoryIndex (e.g. index.html) in that directory, then the server will return a formatted listing of the directory. -
    MultiViews -
    +
    MultiViews +
    Content negotiated MultiViews are allowed. -
    SymLinksIfOwnerMatch -
    +
    SymLinksIfOwnerMatch +
    The server will only follow symbolic links for which the target file or directory is owned by the same user id as the link. -
    +
    -Normally, if multiple Options could apply to a directory, +Normally, if multiple Options could apply to a directory, then the most specific one is taken complete; the options are not -merged. However if all the options on the Options +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 @@ -1209,258 +1209,258 @@ the options currently in force.

    For example, without any + and - symbols: -

    -<Directory /web/docs>
    -Options Indexes FollowSymLinks
    -</Directory>
    -<Directory /web/docs/spec>
    -Options Includes
    +
    +<Directory /web/docs>
    +Options Indexes FollowSymLinks
    +</Directory>
    +<Directory /web/docs/spec>
    +Options Includes
    </Directory> -
    -then only 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
    +
    +then only 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> -
    -then the options FollowSymLinks and Includes +
    +then the options FollowSymLinks and Includes are set for the /web/docs/spec directory. -
    +

    PidFile directive

    -Syntax: PidFile filename
    -Default: PidFile logs/httpd.pid
    -Context: server config
    -Status: core

    +Syntax: PidFile filename
    +Default: PidFile logs/httpd.pid
    +Context: server config
    +Status: core

    The PidFile directive sets the file to which the server records the process id of the daemon. If the filename does not begin with a slash (/) then it is assumed to be relative to the ServerRoot. -The PidFile is only used in standalone mode.

    +The PidFile is only used in standalone mode.

    It is often useful to be able to send the server a signal, so that it closes and then reopens its 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.

    +signal to the process id listed in the PidFile.

    The PidFile is subject to the same warnings about log file placement and -security. +security. -

    +

    Port directive

    -Syntax: Port number
    -Default: Port 80
    -Context: server config
    -Status: core

    +Syntax: Port number
    +Default: Port 80
    +Context: server config
    +Status: core

    -Number is a number from 0 to 65535; some port numbers (especially below -1024) are reserved for particular protocols. See /etc/services +Number is a number from 0 to 65535; some port numbers (especially below +1024) are reserved for particular protocols. See /etc/services for a list of some defined ports; the standard port for the http protocol -is 80.

    +is 80.

    The Port directive has two behaviors, the first of which is necessary for NCSA backwards compatibility (and which is confusing in the context of -Apache).

    +Apache).

    -

      -
    • -In the absence of any Listen or -BindAddress directives specifying a port number, +
        +
      • +In the absence of any Listen or +BindAddress directives specifying a port number, a Port directive given in the "main server" -(i.e. outside any <VirtualHost> section) +(i.e. outside any <VirtualHost> section) sets the network port on which the server listens. If there are any Listen or BindAddress directives specifying -:number then Port has no effect on what address the server +:number then Port has no effect on what address the server listens at. -
      • The Port directive -sets the SERVER_PORT environment variable (for -CGI and SSI), +
      • The Port directive +sets the SERVER_PORT environment variable (for +CGI and SSI), and is used when the server must generate a URL that refers to itself (for example when creating an external redirect to itself). -
      +
    In no event does a Port setting affect -what ports a VirtualHost responds on, the -VirtualHost directive itself is used for that.

    +what ports a VirtualHost responds on, the +VirtualHost directive itself is used for that.

    The primary behaviour of Port should be considered to be similar to that of -the ServerName directive. The ServerName -and Port together specify what you consider to be the canonical -address of the server.

    +the ServerName directive. The ServerName +and Port together specify what you consider to be the canonical +address of the server.

    Port 80 is one of Unix's special ports. All ports numbered below 1024 are reserved for system use, i.e. regular (non-root) users cannot make use of them; instead they can only use higher port numbers. To use port 80, you must start the server from the root account. After binding to the port and before accepting requests, Apache will change -to a low privileged user as set by the User directive.

    +to a low privileged user as set by the User directive.

    If you cannot use port 80, choose any other unused port. Non-root users -will have to choose a port number higher than 1023, such as 8000.

    +will have to choose a port number higher than 1023, such as 8000.

    SECURITY: if you do start the server as root, be sure not to set User to root. If you run the server as root whilst handling connections, your site may be open to a major security -attack.

    +attack.

    require directive

    -Syntax: require entity-name entity entity...
    -Context: directory, .htaccess
    -Override: AuthConfig
    -Status: core

    +Syntax: require entity-name entity entity...
    +Context: directory, .htaccess
    +Override: AuthConfig
    +Status: core

    This directive selects which authenticated users can access a directory. The allowed syntaxes are: -

      -
    • require user userid userid ...

      -Only the named users can access the directory.

      -

    • require group group-name group-name ...

      -Only users in the named groups can access the directory.

      -

    • require valid-user

      +

        +
      • require user userid userid ...

        +Only the named users can access the directory.

        +

      • require group group-name group-name ...

        +Only users in the named groups can access the directory.

        +

      • require valid-user

        All valid users can access the directory. -

      -

      -If require appears in a <Limit> +

    +

    +If require appears in a <Limit> section, then it restricts access to the named methods, otherwise it restricts access for all methods. Example: -

    -AuthType Basic
    -AuthName somedomain
    -AuthUserFile /web/users
    -AuthGroupFile /web/groups
    -<Limit GET POST>
    -require group admin
    +
    +AuthType Basic
    +AuthName somedomain
    +AuthUserFile /web/users
    +AuthGroupFile /web/groups
    +<Limit GET POST>
    +require group admin
    </Limit> -
    +
    Require 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.

    +groups) in order to work correctly.

    ResourceConfig directive

    -Syntax: ResourceConfig filename
    -Default: ResourceConfig conf/srm.conf
    -Context: server config, virtual host
    -Status: core

    +Syntax: ResourceConfig filename
    +Default: ResourceConfig conf/srm.conf
    +Context: server config, virtual host
    +Status: core

    The server will read this file for more directives after reading the -httpd.conf file. Filename is relative to the +httpd.conf file. Filename is relative to the ServerRoot. This feature can be disabled using: -

    ResourceConfig /dev/null
    +
    ResourceConfig /dev/null
    Historically, this file contained most directives except for server configuration directives and <Directory> sections; in fact it can now contain any server directive allowed in the -server config context.

    +server config context.

    -See also AccessConfig.

    +See also AccessConfig.

    RLimitCPU directive

    -Syntax: RLimitCPU # or 'max' [# or 'max']
    -Default: Unset; uses operating system defaults
    -Context: server config, virtual host
    -Status: core
    -Compatibility: RLimitCPU is only available in Apache 1.2 and later

    +Syntax: RLimitCPU # or 'max' [# or 'max']
    +Default: Unset; uses operating system defaults
    +Context: server config, virtual host
    +Status: core
    +Compatibility: RLimitCPU is only available in Apache 1.2 and later

    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 max to indicate to the server that the limit should +can be a number, or 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.

    +startup phase.

    -CPU resource limits are expressed in seconds per process.

    +CPU resource limits are expressed in seconds per process.

    -See also RLimitMEM or RLimitNPROC.

    +See also RLimitMEM or RLimitNPROC.

    RLimitMEM directive

    -Syntax: RLimitMEM # or 'max' [# or 'max']
    -Default: Unset; uses operating system defaults
    -Context: server config, virtual host
    -Status: core
    -Compatibility: RLimitMEM is only available in Apache 1.2 and later

    +Syntax: RLimitMEM # or 'max' [# or 'max']
    +Default: Unset; uses operating system defaults
    +Context: server config, virtual host
    +Status: core
    +Compatibility: RLimitMEM is only available in Apache 1.2 and later

    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 max to indicate to the server that the limit should +can be a number, or 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.

    +startup phase.

    -Memory resource limits are expressed in bytes per process.

    +Memory resource limits are expressed in bytes per process.

    -See also RLimitCPU or RLimitNPROC.

    +See also RLimitCPU or RLimitNPROC.

    RLimitNPROC directive

    -Syntax: RLimitNPROC # or 'max' [# or 'max']
    -Default: Unset; uses operating system defaults
    -Context: server config, virtual host
    -Status: core
    -Compatibility: RLimitNPROC is only available in Apache 1.2 and later

    +Syntax: RLimitNPROC # or 'max' [# or 'max']
    +Default: Unset; uses operating system defaults
    +Context: server config, virtual host
    +Status: core
    +Compatibility: RLimitNPROC is only available in Apache 1.2 and later

    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 max to indicate to the server that the limit should +can be a number, or 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.

    +startup phase.

    -Process limits control the number of processes per user.

    +Process limits control the number of processes per user.

    -Note: If CGI processes are not running under userids other than the +Note: If CGI processes are not running under userids other than the web server userid, this directive will limit the number of processes that the server itself can create. Evidence of this situation will be indicated by -cannot fork messages in the error_log.

    +cannot fork messages in the error_log.

    See also RLimitMEM or RLimitCPU. -

    +

    Satisfy directive

    -Syntax: Satisfy 'any' or 'all'
    -Default: Satisfy all
    -Context: directory, .htaccess
    -Status: core
    -Compatibility: Satisfy is only available in Apache 1.2 and later

    +Syntax: Satisfy 'any' or 'all'
    +Default: Satisfy all
    +Context: directory, .htaccess
    +Status: core
    +Compatibility: Satisfy is only available in Apache 1.2 and later

    Access policy if both allow and require used. The parameter can be -either 'all' or 'any'. This directive is only useful +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 +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 +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. -

    +

    ScoreBoardFile directive

    -Syntax: ScoreBoardFile filename
    -Default: ScoreBoardFile logs/apache_status
    -Context: server config
    -Status: core

    +Syntax: ScoreBoardFile filename
    +Default: ScoreBoardFile logs/apache_status
    +Context: server config
    +Status: core

    The ScoreBoardFile directive is required on some architectures to place a file that the server will use to communicate between its children and @@ -1468,143 +1468,143 @@ the parent. The easiest way to find out if your architecture requires a scoreboard file is to run Apache and see if it creates the file named by the directive. If your architecture requires it then you must ensure that this file is not used at the same time by more than one invocation -of Apache.

    +of Apache.

    If you have to use a 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.

    +security.

    -Apache 1.2 and above:

    +Apache 1.2 and above:

    Linux 1.x users might be able to add --DHAVE_SHMGET -DUSE_SHMGET_SCOREBOARD to -the EXTRA_CFLAGS in your Configuration. This +-DHAVE_SHMGET -DUSE_SHMGET_SCOREBOARD to +the EXTRA_CFLAGS in your Configuration. This might work with some 1.x installations, but won't work with all of -them. (Prior to 1.3b4, HAVE_SHMGET would have sufficed.)

    +them. (Prior to 1.3b4, HAVE_SHMGET would have sufficed.)

    SVR4 users should consider adding --DHAVE_SHMGET -DUSE_SHMGET_SCOREBOARD to the -EXTRA_CFLAGS in your Configuration. This +-DHAVE_SHMGET -DUSE_SHMGET_SCOREBOARD to the +EXTRA_CFLAGS in your Configuration. This is believed to work, but we were unable to test it in time for 1.2 -release. (Prior to 1.3b4, HAVE_SHMGET would have sufficed.)

    +release. (Prior to 1.3b4, HAVE_SHMGET would have sufficed.)

    -See Also: -Stopping and Restarting Apache

    +See Also: +Stopping and Restarting Apache

    -

    +

    SendBufferSize directive

    -Syntax: SendBufferSize bytes
    -Context: server config
    -Status: core

    +Syntax: SendBufferSize bytes
    +Context: server config
    +Status: core

    The server will set the TCP 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) -

    +

    ServerAdmin directive

    -Syntax: ServerAdmin email-address
    -Context: server config, virtual host
    -Status: core

    +Syntax: ServerAdmin email-address
    +Context: server config, virtual host
    +Status: core

    The ServerAdmin sets the e-mail address that the server includes in any -error messages it returns to the client.

    +error messages it returns to the client.

    It may be worth setting up a dedicated address for this, e.g. -

    ServerAdmin www-admin@foo.bar.com
    -as users do not always mention that they are talking about the server!

    +
    ServerAdmin www-admin@foo.bar.com
    +as users do not always mention that they are talking about the server!

    ServerAlias directive

    -Syntax: ServerAlias host1 host2 ...
    -Context: virtual host
    -Status: core
    -Compatibility: ServerAlias is only available in Apache -1.1 and later.

    +Syntax: ServerAlias host1 host2 ...
    +Context: virtual host
    +Status: core
    +Compatibility: ServerAlias is only available in Apache +1.1 and later.

    The ServerAlias directive sets the alternate names for a host, for use with -name-based virtual hosts. +name-based virtual hosts. -

    See also: -Apache Virtual Host documentation +

    See also: +Apache Virtual Host documentation -

    +

    ServerName directive

    -Syntax: ServerName fully-qualified domain name
    -Context: server config, virtual host
    -Status: core

    +Syntax: ServerName fully-qualified domain name
    +Context: server config, virtual host
    +Status: core

    The ServerName directive sets the hostname of the server; this is only used when creating redirection URLs. If it is not specified, then the server attempts to deduce it from its own IP address; however this may not work reliably, or may not return the preferred hostname. For example: -

    ServerName www.wibble.com
    +
    ServerName www.wibble.com
    would be used if the canonical (main) name of the actual machine -were monster.wibble.com.

    -

    See Also: -DNS Issues

    -
    +were monster.wibble.com.

    +

    See Also: +DNS Issues

    +

    ServerPath directive

    -Syntax: ServerPath pathname
    -Context: virtual host
    -Status: core
    -Compatibility: ServerPath is only available in Apache -1.1 and later.

    +Syntax: ServerPath pathname
    +Context: virtual host
    +Status: core
    +Compatibility: ServerPath is only available in Apache +1.1 and later.

    The ServerPath directive sets the legacy URL pathname for a host, for -use with name-based virtual hosts. +use with name-based virtual hosts. -

    See also: -Apache Virtual Host documentation +

    See also: +Apache Virtual Host documentation -

    +

    ServerRoot directive

    -Syntax: ServerRoot directory-filename
    -Default: ServerRoot /usr/local/apache
    -Context: server config
    -Status: core

    +Syntax: ServerRoot directory-filename
    +Default: ServerRoot /usr/local/apache
    +Context: server config
    +Status: core

    The ServerRoot directive sets the directory in which the server lives. -Typically it will contain the subdirectories conf/ and -logs/. Relative paths for other configuration files are taken -as relative to this directory.

    +Typically it will contain the subdirectories conf/ and +logs/. Relative paths for other configuration files are taken +as relative to this directory.

    -See also the -d option to httpd.

    -See also the security tips -for information on how to properly set permissions on the ServerRoot.

    +See also the -d option to httpd.

    +See also the security tips +for information on how to properly set permissions on the ServerRoot.

    -

    +

    ServerType directive

    -Syntax: ServerType type
    -Default: ServerType standalone
    -Context: server config
    -Status: core

    +Syntax: ServerType type
    +Default: ServerType standalone
    +Context: server config
    +Status: core

    The ServerType directive sets how the server is executed by the system. -Type is one of -

    -
    inetd -
    The server will be run from the system process inetd; the command to start -the server is added to /etc/inetd.conf -
    standalone -
    The server will run as a daemon process; the command to start the server -is added to the system startup scripts. (/etc/rc.local or -/etc/rc3.d/....) -
    +Type is one of +
    +
    inetd +
    The server will be run from the system process inetd; the command to start +the server is added to /etc/inetd.conf +
    standalone +
    The server will run as a daemon process; the command to start the server +is added to the system startup scripts. (/etc/rc.local or +/etc/rc3.d/....) +
    Inetd is the lesser used of the two options. For each http connection received, a new copy of the server is started from scratch; @@ -1612,56 +1612,56 @@ after the connection is complete, this program exits. There is a high price to pay per connection, but for security reasons, some admins prefer this option. Inetd mode is no longer recommended and does not always work properly. Avoid it if at all possible. -

    +

    Standalone is the most common setting for ServerType since it is far more efficient. The server is started once, and services all subsequent connections. If you intend running Apache to serve a busy site, -standalone will probably be your only option.

    +standalone will probably be your only option.

    StartServers directive

    -Syntax: StartServers number
    -Default: StartServers 5
    -Context: server config
    -Status: core

    +Syntax: StartServers number
    +Default: StartServers 5
    +Context: server config
    +Status: core

    The StartServers 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.

    +on the load, there is usually little reason to adjust this parameter.

    -

    When running with Microsoft Windows, this directive sets the total +

    When running with Microsoft Windows, this directive sets the total number of child processes running. Since the Windows version of Apache is multithreaded, one processes handles all the requests. The rest are held in reserve until the main processes dies. See also MinSpareServers and -MaxSpareServers.

    +MaxSpareServers.

    ThreadsPerChild

    -Syntax: ThreadsPerChild number
    -Default: ThreadsPerChild 50
    -Context: server config
    -Status: core (Windows)
    -Compatbility: Available only with Apache 1.3 and later +Syntax: ThreadsPerChild number
    +Default: ThreadsPerChild 50
    +Context: server config
    +Status: core (Windows)
    +Compatbility: Available only with Apache 1.3 and later with Windows -

    This directive tells the server how many threads it should use. This +

    This directive tells the server how many threads it should use. This is the maximum number of connections the server can handle at once; be sure and set this number high enough for your site if you get a lot of hits. -

    See also StartServers and MaxRequestsPerChild.

    +

    See also StartServers and MaxRequestsPerChild.

    -
    +

    TimeOut directive

    -Syntax: TimeOut number
    -Default: TimeOut 300
    -Context: server config
    -Status: core

    +Syntax: TimeOut number
    +Default: TimeOut 300
    +Context: server config
    +Status: core

    The TimeOut directive currently defines the amount of time Apache will wait for three things: @@ -1681,121 +1681,121 @@ 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. -

    +

    User directive

    -Syntax: User unix-userid
    -Default: User #-1
    -Context: server config, virtual host
    -Status: core

    +Syntax: User unix-userid
    +Default: User #-1
    +Context: server config, virtual host
    +Status: core

    The User directive sets the userid as which the server will answer requests. In order to use this directive, the standalone server must be run initially -as root. Unix-userid is one of: -

    -
    A username -
    Refers to the given user by name. -
    # followed by a user number. -
    Refers to a user by their number. -
    +as root. Unix-userid is one of: +
    +
    A username +
    Refers to the given user by name. +
    # followed by a user number. +
    Refers to a user by their number. +
    The user should have no privileges which result in it being able to access files which are not intended to be visible to the outside world, and similarly, the user should not be able to execute code which is not meant for httpd requests. It is recommended that you set up a new user and group specifically for running the server. Some admins use user -nobody, but this is not always possible or desirable.

    +nobody, but this is not always possible or desirable.

    Notes: 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.

    +for the parent process to remain running as root.

    Special note: Use of this directive in <VirtualHost> requires a properly configured suEXEC wrapper. When used inside a <VirtualHost> in this manner, only the user that CGIs are run as is affected. Non-CGI requests are still processed -with the user specified in the main User directive.

    +with the user specified in the main User directive.

    SECURITY: Don't set User (or Group) to -root unless you know exactly what you are doing, and what the -dangers are.

    +root unless you know exactly what you are doing, and what the +dangers are.

    <VirtualHost> directive

    -Syntax: <VirtualHost addr[:port] ...> ... -</VirtualHost>
    -Context: server config
    -Status: Core.
    -Compatibility: Non-IP address-based Virtual Hosting only -available in Apache 1.1 and later.
    -Compatibility: Multiple address support only available in -Apache 1.2 and later.

    +Syntax: <VirtualHost addr[:port] ...> ... +</VirtualHost>
    +Context: server config
    +Status: Core.
    +Compatibility: Non-IP address-based Virtual Hosting only +available in Apache 1.1 and later.
    +Compatibility: Multiple address support only available in +Apache 1.2 and later.

    <VirtualHost> and </VirtualHost> are used to enclose a group of directives which will apply only to a particular virtual host. Any directive which 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 -

    -
  15. The IP address of the virtual host -
  16. A fully qualified domain name for the IP address of the virtual host. -
    17.  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
    +section. Addr can be + +
  17. The IP address of the virtual host +
  18. A fully qualified domain name for the IP address of the virtual host. +
    19.  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> -
    +
    Each VirtualHost must correspond to a different IP address, different port number or a different host name for the server, in the latter 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 ifconfig alias +then this can be accomplished with the ifconfig alias command (if your OS supports it), or with kernel patches like VIF (for SunOS(TM) 4.1.x)).

    +HREF="../misc/vif-info.html">VIF (for SunOS(TM) 4.1.x)).

    -The special name _default_ can be specified in which case +The special name _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 match occurs.

    +any VirtualHost section, is used when no match occurs.

    -You can specify a :port to change the port that is matched. +You can specify a :port to change the port that is matched. If unspecified then it defaults to the same port as the most recent -Port statement of the main server. You -may also specify :* to match all ports on that address. -(This is recommended when used with _default_.)

    +Port 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 the +SECURITY: 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. -

    NOTE: The use of <VirtualHost> does -not affect what addresses Apache listens on. You may +

    NOTE: The use of <VirtualHost> does +not affect what addresses Apache listens on. You may need to ensure that Apache is listening on the correct addresses using -either BindAddress or Listen. - -

    See also: -Apache Virtual Host documentation
    -See also: -Warnings about DNS and Apache
    -See also: -Setting which addresses and ports Apache uses
    -See also: How Directory, -Location and Files sections work for an explanation of how these +either BindAddress or Listen. + +

    See also: +Apache Virtual Host documentation
    +See also: +Warnings about DNS and Apache
    +See also: +Setting which addresses and ports Apache uses
    +See also: How Directory, +Location and Files sections work for an explanation of how these different sections are combined when a request is received -

    +

    diff --git a/docs/manual/mod/directives.html b/docs/manual/mod/directives.html index 17055e28ed..b29213e697 100644 --- a/docs/manual/mod/directives.html +++ b/docs/manual/mod/directives.html @@ -23,179 +23,179 @@ listed here. They are described using a consistent format, and there is >a dictionary of the terms used in their descriptions available.

    - + diff --git a/docs/manual/mod/index.html b/docs/manual/mod/index.html index 426e7758f2..6ac99dba3a 100644 --- a/docs/manual/mod/index.html +++ b/docs/manual/mod/index.html @@ -13,7 +13,7 @@ ALINK="#FF0000" > -

    Apache modules

    +

    Apache modules

    Below is a list of all of the modules that come as part of the @@ -23,93 +23,93 @@ Apache distribution. See also the complete alphabetical list of >all Apache directives.

    -
    -
    Core -
    Core Apache features. -
    mod_access -
    Host based access control. -
    mod_actions Apache 1.1 and later. -
    Filetype/method-based script execution -
    mod_alias -
    Aliases and redirects. -
    mod_asis -
    The .asis file handler. -
    mod_auth -
    User authentication using text files. -
    mod_auth_anon -
    Anonymous user authentication, FTP-style. -
    mod_auth_db -
    User authentication using Berkeley DB files. -
    mod_auth_dbm -
    User authentication using DBM files. -
    mod_autoindex -
    Automatic directory listings. -
    mod_browser Apache 1.2.* only -
    Set environment variables based on User-Agent strings. Replaced by +
    +
    Core +
    Core Apache features. +
    mod_access +
    Host based access control. +
    mod_actions Apache 1.1 and later. +
    Filetype/method-based script execution +
    mod_alias +
    Aliases and redirects. +
    mod_asis +
    The .asis file handler. +
    mod_auth +
    User authentication using text files. +
    mod_auth_anon +
    Anonymous user authentication, FTP-style. +
    mod_auth_db +
    User authentication using Berkeley DB files. +
    mod_auth_dbm +
    User authentication using DBM files. +
    mod_autoindex +
    Automatic directory listings. +
    mod_browser Apache 1.2.* only +
    Set environment variables based on User-Agent strings. Replaced by mod_setenvif in Apache 1.3 and up -
    mod_cern_meta -
    Support for HTTP header metafiles. -
    mod_cgi -
    Invoking CGI scripts. -
    mod_cookies up to Apache 1.1.1 -
    Support for Netscape-like cookies. Replaced in Apache 1.2 by +
    mod_cern_meta +
    Support for HTTP header metafiles. +
    mod_cgi +
    Invoking CGI scripts. +
    mod_cookies up to Apache 1.1.1 +
    Support for Netscape-like cookies. Replaced in Apache 1.2 by mod_usertrack -
    mod_digest -
    MD5 authentication -
    mod_dir -
    Basic directory handling. -
    mod_dld -
    Start-time linking with the GNU libdld. -
    mod_dll -
    Start-time module linking with Win32 DLLs. -
    mod_env -
    Passing of environments to CGI scripts -
    mod_example Apache 1.2 and up -
    Demonstrates Apache API -
    mod_expires Apache 1.2 and up -
    Apply Expires: headers to resources -
    mod_headers Apache 1.2 and up -
    Add arbitrary HTTP headers to resources -
    mod_imap -
    The imagemap file handler. -
    mod_include -
    Server-parsed documents. -
    mod_info -
    Server configuration information -
    mod_isapi -
    Windows ISAPI Extension support -
    mod_log_agent -
    Logging of User Agents. -
    mod_log_common up to Apache 1.1.1 -
    Standard logging in the Common Logfile Format. Replaced by the +
    mod_digest +
    MD5 authentication +
    mod_dir +
    Basic directory handling. +
    mod_dld +
    Start-time linking with the GNU libdld. +
    mod_dll +
    Start-time module linking with Win32 DLLs. +
    mod_env +
    Passing of environments to CGI scripts +
    mod_example Apache 1.2 and up +
    Demonstrates Apache API +
    mod_expires Apache 1.2 and up +
    Apply Expires: headers to resources +
    mod_headers Apache 1.2 and up +
    Add arbitrary HTTP headers to resources +
    mod_imap +
    The imagemap file handler. +
    mod_include +
    Server-parsed documents. +
    mod_info +
    Server configuration information +
    mod_isapi +
    Windows ISAPI Extension support +
    mod_log_agent +
    Logging of User Agents. +
    mod_log_common up to Apache 1.1.1 +
    Standard logging in the Common Logfile Format. Replaced by the mod_log_config module in Apache 1.2 and up -
    mod_log_config -
    User-configurable logging replacement for mod_log_common. -
    mod_log_referer -
    Logging of document references. -
    mod_mime -
    Determining document types using file extensions. -
    mod_mime_magic -
    Determining document types using "magic numbers". -
    mod_negotiation -
    Content negotiation. -
    mod_proxy -
    Caching proxy abilities -
    mod_rewrite Apache 1.2 and up -
    Powerful URI-to-filename mapping using regular expressions -
    mod_setenvif Apache 1.3 and up -
    Set environment variables based on client information -
    mod_speling Apache 1.3 and up -
    Automatically correct minor typos in URLs -
    mod_status -
    Server status display -
    mod_userdir -
    User home directories. -
    mod_unique_id Apache 1.3 and up -
    Generate unique request identifier for every request -
    mod_usertrack Apache 1.2 and up -
    User tracking using Cookies (replacement for mod_cookies.c) -
    +
    mod_log_config +
    User-configurable logging replacement for mod_log_common. +
    mod_log_referer +
    Logging of document references. +
    mod_mime +
    Determining document types using file extensions. +
    mod_mime_magic +
    Determining document types using "magic numbers". +
    mod_negotiation +
    Content negotiation. +
    mod_proxy +
    Caching proxy abilities +
    mod_rewrite Apache 1.2 and up +
    Powerful URI-to-filename mapping using regular expressions +
    mod_setenvif Apache 1.3 and up +
    Set environment variables based on client information +
    mod_speling Apache 1.3 and up +
    Automatically correct minor typos in URLs +
    mod_status +
    Server status display +
    mod_userdir +
    User home directories. +
    mod_unique_id Apache 1.3 and up +
    Generate unique request identifier for every request +
    mod_usertrack Apache 1.2 and up +
    User tracking using Cookies (replacement for mod_cookies.c) +
    diff --git a/docs/manual/mod/mod_access.html b/docs/manual/mod/mod_access.html index 4e9bcf4606..50a1785827 100644 --- a/docs/manual/mod/mod_access.html +++ b/docs/manual/mod/mod_access.html @@ -14,76 +14,76 @@ > -

    Module mod_access

    +

    Module mod_access

    -This module is contained in the mod_access.c file, and +This module is contained in the mod_access.c file, and is compiled in by default. It provides access control based on client hostname or IP address.

    -
    +

    allow directive

    -Syntax: allow from host host ...
    -Context: directory, .htaccess
    -Override: Limit
    -Status: Base
    -Module: mod_access -

    +Syntax: allow from host host ...
    +Context: directory, .htaccess
    +Override: Limit
    +Status: Base
    +Module: mod_access +

    The allow directive affects which hosts can access a given directory. -Host is one of the following: -

    -
    -
    all -
    All hosts are allowed access -
    A (partial) domain-name -
    Hosts whose names match, or end in, this string are allowed access. -
    A full IP address -
    An IP address of a host allowed access -
    A partial IP address -
    The first 1 to 3 bytes of an IP address, for subnet restriction. -
    A network/netmask pair (Apache 1.3 and later) -
    A network a.b.c.d, and a netmask w.x.y.z. For more fine-grained subnet +Host is one of the following: +

    +
    +
    all +
    All hosts are allowed access +
    A (partial) domain-name +
    Hosts whose names match, or end in, this string are allowed access. +
    A full IP address +
    An IP address of a host allowed access +
    A partial IP address +
    The first 1 to 3 bytes of an IP address, for subnet restriction. +
    A network/netmask pair (Apache 1.3 and later) +
    A network a.b.c.d, and a netmask w.x.y.z. For more fine-grained subnet restriction. (i.e. 10.1.0.0/255.255.0.0) -
    A network/nnn CIDR specification (Apache 1.3 and later) -
    Similar to the previous case, except the netmask consists of nnn +
    A network/nnn CIDR specification (Apache 1.3 and later) +
    Similar to the previous case, except the netmask consists of nnn high-order 1 bits. (i.e. 10.1.0.0/16 is the same as 10.1.0.0/255.255.0.0) -
    +

    Example:

    -
    allow from .ncsa.uiuc.edu
    +
    allow from .ncsa.uiuc.edu

    All hosts in the specified domain are allowed access. -

    +

    -Note that this compares whole components; bar.edu -would not match foobar.edu. +Note that this compares whole components; bar.edu +would not match foobar.edu.

    See also deny, order, and -BrowserMatch. -

    +BrowserMatch. +

    -Syntax: allow from env=variablename
    -Context: directory, .htaccess
    -Override: Limit
    -Status: Base
    -Module: mod_access
    -Compatibility: Apache 1.2 and above -

    +Syntax: allow from env=variablename
    +Context: directory, .htaccess
    +Override: Limit
    +Status: Base
    +Module: mod_access
    +Compatibility: Apache 1.2 and above +

    The allow from env directive controls access to a directory by the existence (or non-existence) of an environment variable. @@ -91,74 +91,74 @@ existence (or non-existence) of an environment variable.

    Example:

    -
    +
     BrowserMatch ^KnockKnock/2.0 let_me_in
 <Directory /docroot>
     order deny,allow
     deny from all
     allow from env=let_me_in
 </Directory>
-
    
-In this case browsers with the user-agent string KnockKnock/2.0 will
+
    +In this case browsers with the user-agent string KnockKnock/2.0 will be allowed access, and all others will be denied.

    See also deny from env and order. -

    -
    +

    +

    deny directive

    -Syntax: deny from host host ...
    -Context: directory, .htaccess
    -Override: Limit
    -Status: Base
    -Module: mod_access -

    +Syntax: deny from host host ...
    +Context: directory, .htaccess
    +Override: Limit
    +Status: Base
    +Module: mod_access +

    The deny directive affects which hosts can access a given directory. -Host is one of the following: -

    -
    -
    all -
    all hosts are denied access -
    A (partial) domain-name -
    host whose name is, or ends in, this string are denied access. -
    A full IP address -
    An IP address of a host denied access -
    A partial IP address -
    The first 1 to 3 bytes of an IP address, for subnet restriction. -
    A network/netmask pair (Apache 1.3 and later) -
    A network a.b.c.d, and a netmask w.x.y.z. For more fine-grained subnet +Host is one of the following: +

    +
    +
    all +
    all hosts are denied access +
    A (partial) domain-name +
    host whose name is, or ends in, this string are denied access. +
    A full IP address +
    An IP address of a host denied access +
    A partial IP address +
    The first 1 to 3 bytes of an IP address, for subnet restriction. +
    A network/netmask pair (Apache 1.3 and later) +
    A network a.b.c.d, and a netmask w.x.y.z. For more fine-grained subnet restriction. (i.e. 10.1.0.0/255.255.0.0) -
    A network/nnn CIDR specification (Apache 1.3 and later) -
    Similar to the previous case, except the netmask consists of nnn +
    A network/nnn CIDR specification (Apache 1.3 and later) +
    Similar to the previous case, except the netmask consists of nnn high-order 1 bits. (i.e. 10.1.0.0/16 is the same as 10.1.0.0/255.255.0.0) -
    +

    Example:

    -
    deny from 16
    +
    deny from 16

    All hosts in the specified network are denied access. -

    +

    -Note that this compares whole components; bar.edu -would not match foobar.edu. -

    +Note that this compares whole components; bar.edu +would not match foobar.edu. +

    See also allow and order. -

    +

    -Syntax: deny from env=variablename
    -Context: directory, .htaccess
    -Override: Limit
    -Status: Base
    -Module: mod_access
    -Compatibility: Apache 1.2 and above -

    +Syntax: deny from env=variablename
    +Context: directory, .htaccess
    +Override: Limit
    +Status: Base
    +Module: mod_access
    +Compatibility: Apache 1.2 and above +

    The deny from env directive controls access to a directory by the existence (or non-existence) of an environment variable. @@ -166,61 +166,61 @@ existence (or non-existence) of an environment variable.

    Example:

    -
    +
     BrowserMatch ^BadRobot/0.9 go_away
 <Directory /docroot>
     order allow,deny
     allow from all
     deny from env=go_away
 </Directory>
-
    
-In this case browsers with the user-agent string BadRobot/0.9 will
+
    +In this case browsers with the user-agent string BadRobot/0.9 will be denied access, and all others will be allowed.

    See also allow from env and order. -

    -
    +

    +

    order directive

    -Syntax: order ordering
    -Default: order deny,allow
    -Context: directory, .htaccess
    -Override: Limit
    -Status: Base
    -Module: mod_access -

    +Syntax: order ordering
    +Default: order deny,allow
    +Context: directory, .htaccess
    +Override: Limit
    +Status: Base
    +Module: mod_access +

    The order directive controls the order in which allow and -deny directives are evaluated. Ordering is one +deny directives are evaluated. Ordering is one of

    -
    -
    deny,allow -
    the deny directives are evaluated before the allow directives. (The +
    +
    deny,allow +
    the deny directives are evaluated before the allow directives. (The initial state is OK.) -
    allow,deny -
    the allow directives are evaluated before the deny directives. (The +
    allow,deny +
    the allow directives are evaluated before the deny directives. (The initial state is FORBIDDEN.) -
    mutual-failure -
    Only those hosts which appear on the allow list and do not appear +
    mutual-failure +
    Only those hosts which appear on the allow list and do not appear on the deny list are granted access. (The initial state is irrelevant.) -
    +

    -Note that in all cases every allow and deny -statement is evaluated, there is no "short-circuiting". +Note that in all cases every allow and deny +statement is evaluated, there is no "short-circuiting".

    -

    +

    Example:

    -
    - order deny,allow
    - deny from all
    - allow from .ncsa.uiuc.edu
    -
    +
    + order deny,allow
    + deny from all
    + allow from .ncsa.uiuc.edu
    +

    Hosts in the ncsa.uiuc.edu domain are allowed access; all other hosts are denied access. diff --git a/docs/manual/mod/mod_actions.html b/docs/manual/mod/mod_actions.html index 07823cbc82..dd41533dad 100644 --- a/docs/manual/mod/mod_actions.html +++ b/docs/manual/mod/mod_actions.html @@ -13,9 +13,9 @@ ALINK="#FF0000" > -

    Module mod_actions

    +

    Module mod_actions

    -This module is contained in the mod_actions.c file, and +This module is contained in the mod_actions.c file, and is compiled in by default. It provides for executing CGI scripts based on media type or request method. It is not present in versions prior to Apache 1.1. @@ -27,64 +27,64 @@ is requested. This makes it much easier to execute scripts that process files.

    Directives

    - + -
    +

    Action directive

    -Syntax: Action mime-type cgi-script
    -Context: server config, virtual host, directory, .htaccess
    -Override: FileInfo
    -Status: Base
    -Module: mod_actions
    -Compatibility: Action is only available in Apache 1.1 +Syntax: Action mime-type cgi-script
    +Context: server config, virtual host, directory, .htaccess
    +Override: FileInfo
    +Status: Base
    +Module: mod_actions
    +Compatibility: Action is only available in Apache 1.1 and later -

    +

    -This directive adds an action, which will activate cgi-script when -a file of content type mime-type is requested. It sends the +This directive adds an action, which will activate cgi-script when +a file of content type mime-type is requested. It sends the URL and file path of the requested document using the standard CGI PATH_INFO and PATH_TRANSLATED environment variables.

    -
    +

    Script directive

    -Syntax: Script method cgi-script
    -Context: server config, virtual host, directory
    -Status: Base
    -Module: mod_actions
    -Compatibility: Script is only available in Apache 1.1 +Syntax: Script method cgi-script
    +Context: server config, virtual host, directory
    +Status: Base
    +Module: mod_actions
    +Compatibility: Script is only available in Apache 1.1 and later -

    +

    -

    -This directive adds an action, which will activate cgi-script when -a file is requested using the method of method, which can be -one of GET, POST, PUT or -DELETE. It sends the +

    +This directive adds an action, which will activate cgi-script when +a file is requested using the method of method, which can be +one of GET, POST, PUT or +DELETE. It sends the URL and file path of the requested document using the standard CGI PATH_INFO and PATH_TRANSLATED environment variables.

    -

    +

    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 GET will only be called if there are +with a method of GET will only be called if there are query arguments present (e.g. foo.html?hi). Otherwise, the request will proceed normally.

    -

    +

    Examples:

    -
    +
         Script GET /cgi-bin/search     #e.g. for <ISINDEX>-style searching
     Script PUT /~bob/put.cgi
-
    
+
    diff --git a/docs/manual/mod/mod_alias.html b/docs/manual/mod/mod_alias.html index 82b025fbaf..61e2b07ca0 100644 --- a/docs/manual/mod/mod_alias.html +++ b/docs/manual/mod/mod_alias.html @@ -14,243 +14,243 @@ > -

    Module mod_alias

    +

    Module mod_alias

    -This module is contained in the mod_alias.c file, and +This module is contained in the mod_alias.c file, and is compiled in by default. It provides for mapping different parts of the host filesystem in the the document tree, and for URL redirection.

    Directives

    -
    +

    Alias directive

    -Syntax: Alias url-path directory-filename
    -Context: server config, virtual host
    -Status: Base
    -Module: mod_alias +Syntax: Alias url-path directory-filename
    +Context: server config, virtual host
    +Status: Base
    +Module: mod_alias

    The 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-filename. +URLs with a (%-decoded) path beginning with url-path will be +mapped to local files beginning with directory-filename.

    Example:

    -
    Alias /image /ftp/pub/image
    +
    Alias /image /ftp/pub/image

    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 +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 Alias /icons/ /usr/local/apache/icons/ then -the url /icons will not be aliased. -

    +if you use Alias /icons/ /usr/local/apache/icons/ then +the url /icons will not be aliased. +

    See also ScriptAlias. -

    -
    +

    +

    AliasMatch

    -Syntax: AliasMatch regex directory-filename
    -Context: server config, virtual host
    -Status: Base
    -Module: mod_alias
    -Compatibility: Available in Apache 1.3 and later +Syntax: AliasMatch regex directory-filename
    +Context: server config, virtual host
    +Status: Base
    +Module: mod_alias
    +Compatibility: Available in Apache 1.3 and later

    -

    This directive is equivalent to Alias, but +

    This directive is equivalent to Alias, but makes use of standard regular expressions, instead of simple prefix matching. The supplied regular expression is matched against the URL, 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: -

    +to activate the /icons directory, one might use:
+
         AliasMatch ^/icons(.*) /usr/local/apache/icons$1
-
    
-
    
+
    +

    -
    +

    Redirect directive

    -Syntax: Redirect [ status ] url-path url
    -Context: server config, virtual host, directory, .htaccess
    -Status: Base
    -Module: mod_alias
    -Compatibility: The directory and .htaccess context's -are only available in versions 1.1 and later. The status +Syntax: Redirect [ status ] url-path url
    +Context: server config, virtual host, directory, .htaccess
    +Status: Base
    +Module: mod_alias
    +Compatibility: The directory and .htaccess context's +are only available in versions 1.1 and later. The status argument is only available in Apache 1.2 or later.

    The Redirect directive maps an old URL into a new one. The new URL is returned to the client which attempts to fetch it again with the new address. -Url-path a (%-decoded) path; any requests for documents beginning with +Url-path a (%-decoded) path; any requests for documents beginning with this path will be returned a redirect error to a new (%-encoded) url -beginning with url. +beginning with url.

    Example:

    -
    Redirect /service -http://foo2.bar.com/service
    +
    Redirect /service +http://foo2.bar.com/service

    If the client requests http://myserver/service/foo.txt, it will be told to access http://foo2.bar.com/service/foo.txt instead. -

    +

    Note: Redirect directives take precedence over Alias and ScriptAlias directives, irrespective of their ordering in the configuration file. Also, -Url-path must be an absolute path, not a relative path, even +Url-path must be an absolute path, not a relative path, even when used with .htaccess files or inside of <Directory> sections. -

    +

    -If no status argument is given, the redirect will be +If no status argument is given, the redirect will be "temporary" (HTTP status 302). This indicates to the client that the -resources is has moved temporarily. The status +resources is has moved temporarily. The status argument can be used to return other HTTP status codes:

    -

    -
    permanent -
    Returns a permanent redirect status (301) indicating that +
    +
    permanent +
    Returns a permanent redirect status (301) indicating that the resource has moved permanently. -
    temp -
    Returns a temporary redirect status (302). This is the +
    temp +
    Returns a temporary redirect status (302). This is the default. -
    seeother -
    Returns a "See Other" status (303) indicating that +
    seeother +
    Returns a "See Other" status (303) indicating that the resource has been replaced. -
    gone -
    Returns a "Gone" status (410) indicating that the resource -has been permanently removed. When this status is used the url +
    gone +
    Returns a "Gone" status (410) indicating that the resource +has been permanently removed. When this status is used the url argument should be omitted. -
    +

    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 +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 send_error_response in http_protocol.c). +the function send_error_response in http_protocol.c).

    RedirectMatch

    -Syntax: RedirectMatch [status regex url
    -Context: server config, virtual host
    -Status: Base
    -Module: mod_alias
    -Compatibility: Available in Apache 1.3 and later +Syntax: RedirectMatch [status regex url
    +Context: server config, virtual host
    +Status: Base
    +Module: mod_alias
    +Compatibility: Available in Apache 1.3 and later

    -

    This directive is equivalent to Redirect, but +

    This directive is equivalent to Redirect, but makes use of standard regular expressions, instead of simple prefix matching. The supplied regular expression is matched against the URL, 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
-
    
-
    
+
    +

    -
    +

    RedirectTemp directive

    -Syntax: RedirectTemp url-path url
    -Context: server config, virtual host, directory, .htaccess
    -Status: Base
    -Module: mod_alias
    -Compatibility: This directive is only available in 1.2 +Syntax: RedirectTemp url-path url
    +Context: server config, virtual host, directory, .htaccess
    +Status: Base
    +Module: mod_alias
    +Compatibility: This directive is only available in 1.2

    This directive makes the client know that the Redirect is only -temporary (status 302). Exactly equivalent to Redirect -temporary. +temporary (status 302). Exactly equivalent to Redirect +temporary.

    RedirectPermanent directive

    -Syntax: RedirectPermanent url-path url
    -Context: server config, virtual host, directory, .htaccess
    -Status: Base
    -Module: mod_alias
    -Compatibility: This directive is only available in 1.2 +Syntax: RedirectPermanent url-path url
    +Context: server config, virtual host, directory, .htaccess
    +Status: Base
    +Module: mod_alias
    +Compatibility: This directive is only available in 1.2

    This directive makes the client know that the Redirect is permanent -(status 301). Exactly equivalent to Redirect permanent. +(status 301). Exactly equivalent to Redirect permanent.

    -
    +

    ScriptAlias directive

    -Syntax: ScriptAlias url-path directory-filename
    -Context: server config, virtual host
    -Status: Base
    -Module: mod_alias +Syntax: ScriptAlias url-path directory-filename
    +Context: server config, virtual host
    +Status: Base
    +Module: mod_alias

    The ScriptAlias directive has the same behavior as the Alias directive, except that in addition it marks the target directory as containing CGI scripts. -URLs with a (%-decoded) path beginning with url-path will be -mapped to scripts beginning with directory-filename. +URLs with a (%-decoded) path beginning with url-path will be +mapped to scripts beginning with directory-filename.

    Example:

    -
    ScriptAlias /cgi-bin/ /web/cgi-bin/
    +
    ScriptAlias /cgi-bin/ /web/cgi-bin/

    A request for http://myserver/cgi-bin/foo would cause the server to run the script /web/cgi-bin/foo.

    -
    +

    ScriptAliasMatch

    -Syntax: ScriptAliasMatch regex directory-filename
    -Context: server config, virtual host
    -Status: Base
    -Module: mod_alias
    -Compatibility: Available in Apache 1.3 and later +Syntax: ScriptAliasMatch regex directory-filename
    +Context: server config, virtual host
    +Status: Base
    +Module: mod_alias
    +Compatibility: Available in Apache 1.3 and later

    -

    This directive is equivalent to ScriptAlias, but +

    This directive is equivalent to ScriptAlias, but makes use of standard regular expressions, instead of simple prefix matching. The supplied regular expression is matched against the URL, 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: -

    +to activate the standard /cgi-bin, one might use:
+
         ScriptAliasMatch ^/cgi-bin(.*) /usr/local/apache/cgi-bin$1
-
    
-
    
+
    +

    diff --git a/docs/manual/mod/mod_asis.html b/docs/manual/mod/mod_asis.html index b3a445d078..db224d5177 100644 --- a/docs/manual/mod/mod_asis.html +++ b/docs/manual/mod/mod_asis.html @@ -14,11 +14,11 @@ > -

    Module mod_asis

    +

    Module mod_asis

    -This module is contained in the mod_asis.c file, and -is compiled in by default. It provides for .asis files. Any -document with mime type httpd/send-as-is will be processed by +This module is contained in the mod_asis.c file, and +is compiled in by default. It provides for .asis files. Any +document with mime type httpd/send-as-is will be processed by this module. @@ -31,36 +31,36 @@ and other special HTTP responses, without requiring a cgi-script or an nph script.

    Usage

    In the server configuration file, define a new mime type called -httpd/send-as-is e.g. -
    AddType httpd/send-as-is asis
    -this defines the .asis file extension as being of the new -httpd/send-as-is mime type. The contents of any file with a -.asis extension will then be sent by Apache to the client with +httpd/send-as-is e.g. +
    AddType httpd/send-as-is asis
    +this defines the .asis file extension as being of the new +httpd/send-as-is mime type. The contents of any file with a +.asis extension will then be sent by Apache to the client with almost no changes. Clients will need HTTP headers to be attached, so do not forget them. A Status: header is also required; the data should be the -3-digit HTTP response code, followed by a textual message.

    +3-digit HTTP response code, followed by a textual message.

    -Here's an example of a file whose contents are sent as is so as to +Here's an example of a file whose contents are sent as is so as to tell the client that a file has redirected. -

    -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>
    +
    +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: the server always adds a 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. +The server does not add a Last-Modified header; it probably should.

    diff --git a/docs/manual/mod/mod_auth.html b/docs/manual/mod/mod_auth.html index c0286fe395..eb006f4837 100644 --- a/docs/manual/mod/mod_auth.html +++ b/docs/manual/mod/mod_auth.html @@ -14,136 +14,136 @@ > -

    Module mod_auth

    +

    Module mod_auth

    -This module is contained in the mod_auth.c file, and +This module is contained in the mod_auth.c file, and is compiled in by default. It provides for user authentication using textual files. - -
  19. AuthGroupFile -
  20. AuthUserFile -
  21. AuthAuthoritative -
    22.  -
    + +
  22. AuthGroupFile +
  23. AuthUserFile +
  24. AuthAuthoritative +
    25.  +

    AuthGroupFile

     -Syntax: AuthGroupFile filename
    -Context: directory, .htaccess
    -Override: AuthConfig
    -Status: Base
    -Module: mod_auth

    +Syntax: AuthGroupFile filename
    +Context: directory, .htaccess
    +Override: AuthConfig
    +Status: Base
    +Module: mod_auth

    The AuthGroupFile directive sets the name of a textual file containing the list -of user groups for user authentication. Filename is the path +of user groups for user authentication. Filename is the path to the group file. If it is not absolute (i.e., if it doesn't begin with a slash), it is treated as relative to the ServerRoot.

    Each line of the group file contains a groupname followed by a colon, followed by the member usernames separated by spaces. Example: -

    mygroup: bob joe anne
    -Note that searching large text files is very inefficient; +
    mygroup: bob joe anne
    +Note that searching large text files is very inefficient; AuthDBMGroupFile should -be used instead.

    +be used instead.

    Security: make sure that the AuthGroupFile 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 AuthGroupFile.

    +document tree of the web-server; do not put it in the directory that +it protects. Otherwise, clients will be able to download the AuthGroupFile.

    See also AuthName, AuthType and -AuthUserFile.

    +AuthUserFile.

    AuthUserFile

     -Syntax: AuthUserFile filename
    -Context: directory, .htaccess
    -Override: AuthConfig
    -Status: Base
    -Module: mod_auth

    +Syntax: AuthUserFile filename
    +Context: directory, .htaccess
    +Override: AuthConfig
    +Status: Base
    +Module: mod_auth

    The AuthUserFile directive sets the name of a textual file containing the list of users and passwords for user -authentication. Filename is the path to the user +authentication. Filename 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. -

    Each line of the user file file contains a username followed +

    Each line of the user file file contains a username followed by a colon, followed by the crypt() encrypted password. The behavior of multiple occurrences of the same user is undefined. -

    Note that +

    Note that searching large text files is very inefficient; AuthDBMUserFile should be used instead. -

    +

    Security: make sure that the AuthUserFile 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 AuthUserFile.

    +document tree of the web-server; do not put it in the directory that +it protects. Otherwise, clients will be able to download the AuthUserFile.

    See also AuthName, AuthType and -AuthGroupFile.

    -

    +AuthGroupFile.

    +

    AuthAuthoritative

     -Syntax: AuthAuthoritative < on(default) | off >
    -Context: directory, .htaccess
    -Override: AuthConfig
    -Status: Base
    -Module: mod_auth

    +Syntax: AuthAuthoritative < on(default) | off >
    +Context: directory, .htaccess
    +Override: AuthConfig
    +Status: Base
    +Module: mod_auth

    -Setting the AuthAuthoritative directive explicitly to 'off' +Setting the AuthAuthoritative directive explicitly to 'off' allows for both authentication and authorization to be passed on to -lower level modules (as defined in the Configuration and -modules.c files) if there is no userID or -rule matching the supplied userID. If there is a userID and/or +lower level modules (as defined in the Configuration and +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 Authorization Required reply. -

    +

    So if a userID appears in the database of more than one module; or if a valid 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. -

    +

    A common use for this is in conjunction with one of the database -modules; such as mod_auth_db.c, mod_auth_dbm.c, -mod_auth_msql.c, and mod_auth_anon.c. These modules +modules; such as mod_auth_db.c, mod_auth_dbm.c, +mod_auth_msql.c, and mod_auth_anon.c. 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. -

    +

    -Default: By default; control is not passed on; and an unknown +Default: By default; control is not passed on; and an unknown userID or rule will result in an Authorization Required reply. Not setting it thus keeps the system secure; and forces an NSCA compliant behaviour. -

    +

    Security: 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 AuthUserFile is stored outside the document tree of the -web-server; do not put it in the directory that it +web-server; do not put it in the directory that it protects. Otherwise, clients will be able to download the AuthUserFile. -

    +

    See also AuthName, AuthType and -AuthGroupFile.

    +AuthGroupFile.

    diff --git a/docs/manual/mod/mod_auth_anon.html b/docs/manual/mod/mod_auth_anon.html index 2ab6e88afa..82acd9812f 100644 --- a/docs/manual/mod/mod_auth_anon.html +++ b/docs/manual/mod/mod_auth_anon.html @@ -14,7 +14,7 @@

    Module mod_auth_anon

    -This module is contained in the mod_auth_anon.c file and +This module is contained in the mod_auth_anon.c file and is not compiled in by default. It is only available in Apache 1.1 and later. It allows "anonymous" user access to authenticated areas. @@ -23,114 +23,114 @@ later. It allows "anonymous" user access to authenticated areas. It 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. -

    - -Directives / -Example / -Compile time options / -RevisionHistory / -Person to blame / -Sourcecode -

    - -

    Directives

    - - -
    +

    + +Directives / +Example / +Compile time options / +RevisionHistory / +Person to blame / +Sourcecode +

    + +

    Directives

    + + +

    Anonymous directive

    -Syntax: Anonymous user user ...
    -Default: none
    -Context: directory, .htaccess
    -Override: AuthConfig
    -Status: Extension
    -Module: mod_auth_anon

    +Syntax: Anonymous user user ...
    +Default: none
    +Context: directory, .htaccess
    +Override: AuthConfig
    +Status: Extension
    +Module: mod_auth_anon

    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. -
    - I strongly suggest that the magic username 'anonymous' +

    + Please note that the comparison is case-IN-sensitive. +
    + I strongly suggest that the magic username 'anonymous' is always one of the allowed userIDs. -

    - Example:
    - +

    + Example:
    + Anonymous anonymous "Not Registered" 'I don\'t know' -

    +

    This would allow the user to enter without password verification by using the userId's 'anonymous', 'AnonyMous','Not Registered' and 'I Don't Know'.

    Anonymous_Authoritative directive

    -Syntax: Anonymous_Authoritative on | off
    -Default: Anonymous_Authoritative off
    -Context: directory, .htaccess
    -Override: AuthConfig
    -Status: Extension
    -Module: mod_auth_anon

    +Syntax: Anonymous_Authoritative on | off
    +Default: Anonymous_Authoritative off
    +Context: directory, .htaccess
    +Override: AuthConfig
    +Status: Extension
    +Module: mod_auth_anon

    When set 'on', there is no fall-through to other authorization methods. So if a userID does not match the values specified in the - Anonymous directive, access is denied. -

    + Anonymous directive, access is denied. +

    Be sure you know what you are doing when you decide to switch it on. And remember that it is the linking order of the modules (in the Configuration / Make file) which details the order in which the Authorization modules are queried. -

    +

    Anonymous_LogEmail directive

    -Syntax: Anonymous_LogEmail on | off
    -Default: Anonymous_LogEmail on
    -Context: directory, .htaccess
    -Override: AuthConfig
    -Status: Extension
    -Module: mod_auth_anon

    +Syntax: Anonymous_LogEmail on | off
    +Default: Anonymous_LogEmail on
    +Context: directory, .htaccess
    +Override: AuthConfig
    +Status: Extension
    +Module: mod_auth_anon

    When set 'on', the default, the 'password' entered (which hopefully contains a sensible email address) is logged in the httpd-log file. -

    +

    Anonymous_MustGiveEmail directive

    -Syntax: Anonymous_MustGiveEmail on | off
    -Default: Anonymous_MustGiveEmail on
    -Context: directory, .htaccess
    -Override: AuthConfig
    -Status: Extension
    -Module: mod_auth_anon

    +Syntax: Anonymous_MustGiveEmail on | off
    +Default: Anonymous_MustGiveEmail on
    +Context: directory, .htaccess
    +Override: AuthConfig
    +Status: Extension
    +Module: mod_auth_anon

    Specifies whether the user must specify an email address as the password. This prohibits blank passwords.

    Anonymous_NoUserID directive

    -Syntax: Anonymous_NoUserID on | off
    -Default: Anonymous_NoUserID off
    -Context: directory, .htaccess
    -Override: AuthConfig
    -Status: Extension
    -Module: mod_auth_anon

    +Syntax: Anonymous_NoUserID on | off
    +Default: Anonymous_NoUserID off
    +Context: directory, .htaccess
    +Override: AuthConfig
    +Status: Extension
    +Module: mod_auth_anon

    When set 'on', users can leave the userID (and perhaps the password field) empty. This @@ -138,114 +138,114 @@ allows users to share URLs. just hit return or click directly on the OK button; which seems a natural reaction. -

    +

    Anonymous_VerifyEmail directive

    -Syntax: Anonymous_VerifyEmail on | off
    -Default: Anonymous_VerifyEmail off
    -Context: directory, .htaccess
    -Override: AuthConfig
    -Status: Extension
    -Module: mod_auth_anon

    +Syntax: Anonymous_VerifyEmail on | off
    +Default: Anonymous_VerifyEmail off
    +Context: directory, .htaccess
    +Override: AuthConfig
    +Status: Extension
    +Module: mod_auth_anon

    When set 'on' the 'password' entered is checked for at least one '@' and a '.' to encourage users to enter - valid email addresses (see the above Auth_LogEmail). + valid email addresses (see the above Auth_LogEmail). -

    -

    Example

    +
    +

    Example

    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: -
      -
    • -It insists that the user enters a userId. (Anonymous_NoUserId) -
    • -It insists that the user enters a password. (Anonymous_MustGiveEmail) -
    • +
        +
      • +It insists that the user enters a userId. (Anonymous_NoUserId) +
      • +It insists that the user enters a password. (Anonymous_MustGiveEmail) +
      • The password entered must be a valid email address, ie. contain at least one '@' and a '.'. -(Anonymous_VerifyEmail) -
      • -The userID must be one of anonymous guest www test welcome -and comparison is not case sensitive. -
      • +(Anonymous_VerifyEmail) +
      • +The userID must be one of anonymous guest www test welcome +and comparison is not case sensitive. +
      • And the Email addresses entered in the passwd field are logged to the httpd-log file -(Anonymous_LogEmail) -
      -

      +(Anonymous_LogEmail) +

    +

    Excerpt of access.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
    +

    +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>
    -

    - - -
    -

    Compile Time Options

    +

    +# 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>
    +

    + + +
    +

    Compile Time Options

    Currently there are no Compile options. -
    -

    Revision History

    +
    +

    Revision History

    This version: 23 Nov 1995, 24 Feb 1996, 16 May 1996. -
    +
    -
    Version 0.4
    -
    First release -
    -
    Version 0.5
    -
    Added 'VerifyEmail' and 'LogEmail' options. Multiple +
    Version 0.4
    +
    First release +
    +
    Version 0.5
    +
    Added 'VerifyEmail' and 'LogEmail' options. Multiple 'anonymous' tokens allowed. more docs. Added Authoritative functionality. -
    -
    + +
    -
    -

    Contact/person to blame

    +
    +

    Contact/person to blame

    This module was written for the -European Wide Service Exchange by -<Dirk.vanGulik@jrc.it>. +European Wide Service Exchange by +<Dirk.vanGulik@jrc.it>. Feel free to contact me if you have any problems, ice-creams or bugs. This -documentation, courtesy of Nick Himba, -<himba@cs.utwente.nl>. -

    +documentation, courtesy of Nick Himba, +<himba@cs.utwente.nl>. +

    -

    -

    Sourcecode

    +
    +

    Sourcecode

    -The source code can be found at -http://www.apache.org. A snapshot of a development version -usually resides at -http://me-www.jrc.it/~dirkx/mod_auth_anon.c. Please make sure +The source code can be found at +http://www.apache.org. A snapshot of a development version +usually resides at +http://me-www.jrc.it/~dirkx/mod_auth_anon.c. Please make sure that you always quote the version you use when filing a bug report. -

    +

    - - + + diff --git a/docs/manual/mod/mod_auth_db.html b/docs/manual/mod/mod_auth_db.html index d97035bf0f..55173ea97a 100644 --- a/docs/manual/mod/mod_auth_db.html +++ b/docs/manual/mod/mod_auth_db.html @@ -13,92 +13,92 @@ ALINK="#FF0000" > -

    Module mod_auth_db

    +

    Module mod_auth_db

    -This module is contained in the mod_auth_db.c file, and +This module is contained in the mod_auth_db.c file, and is not compiled in by default. It provides for user authentication using Berkeley DB files. It is an alternative to DBM files for those systems which support DB and not DBM. It is only available in Apache 1.1 and later. - -
  25. AuthDBGroupFile -
  26. AuthDBUserFile -
  27. AuthDBAuthoritative -
    28.  -
    + +
  28. AuthDBGroupFile +
  29. AuthDBUserFile +
  30. AuthDBAuthoritative +
    31.  +

    AuthDBGroupFile

     -Syntax: AuthDBGroupFile filename
    -Context: directory, .htaccess
    -Override: AuthConfig
    -Status: Extension
    -Module: mod_auth_db

    +Syntax: AuthDBGroupFile filename
    +Context: directory, .htaccess
    +Override: AuthConfig
    +Status: Extension
    +Module: mod_auth_db

    The AuthDBGroupFile directive sets the name of a DB file containing the list -of user groups for user authentication. Filename is the absolute path -to the group file.

    +of user groups for user authentication. Filename is the absolute path +to the group file.

    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.

    +be no whitespace within the value, and it must never contain any colons.

    Security: make sure that the AuthDBGroupFile is stored outside the -document tree of the web-server; do not put it in the directory that +document tree of the web-server; do not put it in the directory that it protects. Otherwise, clients will be able to download the -AuthDBGroupFile unless otherwise protected.

    +AuthDBGroupFile unless otherwise protected.

    Combining Group and Password DB 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 DB file:

    +and password files to point to the same DB file:

    -

    -AuthDBGroupFile /www/userbase
    +
    +AuthDBGroupFile /www/userbase
    AuthDBUserFile /www/userbase -
    +
    -The key for the single DB record is the username. The value consists of

    +The key for the single DB record is the username. The value consists of

    -

    +
    Unix Crypt-ed Password : List of Groups [ : (ignored) ] -
    +
    The password section contains the Unix crypt() password as before. This is followed by a colon and the comma separated list of groups. Other data may optionally be left in the DB file after another colon; it is ignored by the -authentication module.

    +authentication module.

    See also AuthName, AuthType and -AuthDBUserFile.

    +AuthDBUserFile.

    AuthDBUserFile

     -Syntax: AuthDBUserFile filename
    -Context: directory, .htaccess
    -Override: AuthConfig
    -Status: Extension
    -Module: mod_auth_db

    +Syntax: AuthDBUserFile filename
    +Context: directory, .htaccess
    +Override: AuthConfig
    +Status: Extension
    +Module: mod_auth_db

    The AuthDBUserFile directive sets the name of a DB file containing the list -of users and passwords for user authentication. Filename is the -absolute path to the user file.

    +of users and passwords for user authentication. Filename is the +absolute path to the user file.

    The user file is keyed on the username. The value for a user is the crypt() encrypted password, optionally followed by a colon and arbitrary data. The colon and the data following it will be ignored -by the server.

    +by the server.

    Security: make sure that the AuthDBUserFile is stored outside the -document tree of the web-server; do not put it in the directory that +document tree of the web-server; do not put it in the directory that it protects. Otherwise, clients will be able to download the -AuthDBUserFile.

    +AuthDBUserFile.

    Important compatibility note: The implementation of "dbmopen" in the apache modules reads the string length of the hashed values from the @@ -106,53 +106,53 @@ DB 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 DB files interchangeably between applications this may be a -part of the problem.

    +part of the problem.

    See also AuthName, AuthType and -AuthDBGroupFile.

    -

    +AuthDBGroupFile.

    +

    AuthDBAuthoritative

     -Syntax: AuthDBAuthoritative < on(default) | off >
    -Context: directory, .htaccess
    -Override: AuthConfig
    -Status: Base
    -Module: mod_auth

    +Syntax: AuthDBAuthoritative < on(default) | off >
    +Context: directory, .htaccess
    +Override: AuthConfig
    +Status: Base
    +Module: mod_auth

    -Setting the AuthDBAuthoritative directive explicitly to 'off' +Setting the AuthDBAuthoritative directive explicitly to 'off' allows for both authentication and authorization to be passed on -to lower level modules (as defined in the Configuration -and modules.c file if there is no userID or -rule matching the supplied userID. If there is a userID +to lower level modules (as defined in the Configuration +and modules.c file 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 Authorization Required reply. -

    +

    So if a userID appears in the database of more than one module; or if a valid 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.

    +passed on; regardless of the AuthAuthoritative setting.

    A common use for this is in conjunction with one of the basic auth -modules; such as mod_auth.c. +modules; such as mod_auth.c. Whereas this DB 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.

    +a lower level with a well protected .htpasswd file.

    -Default: By default; control is not passed on; and an unknown +Default: By default; control is not passed on; and an unknown userID or rule will result in an Authorization Required reply. Not setting it thus keeps the system secure; and forces an NSCA compliant -behaviour.

    +behaviour.

    Security: 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 which might have more access interfaces. -

    +

    See also AuthName, AuthType and -AuthDBGroupFile.

    +AuthDBGroupFile.

    diff --git a/docs/manual/mod/mod_auth_dbm.html b/docs/manual/mod/mod_auth_dbm.html index a8fabb2b80..abc34a1ed4 100644 --- a/docs/manual/mod/mod_auth_dbm.html +++ b/docs/manual/mod/mod_auth_dbm.html @@ -14,91 +14,91 @@ > -

    Module mod_auth_dbm

    +

    Module mod_auth_dbm

    -This module is contained in the mod_auth_dbm.c file, and +This module is contained in the mod_auth_dbm.c file, and is not compiled in by default. It provides for user authentication using DBM files. - -
  31. AuthDBMGroupFile -
  32. AuthDBMUserFile -
  33. AuthDBMAuthoritative -
    34.  -
    + +
  34. AuthDBMGroupFile +
  35. AuthDBMUserFile +
  36. AuthDBMAuthoritative +
    37.  +

    AuthDbmGroupFile

     -Syntax: AuthDBMGroupFile filename
    -Context: directory, .htaccess
    -Override: AuthConfig
    -Status: Extension
    -Module: mod_auth_dbm

    +Syntax: AuthDBMGroupFile filename
    +Context: directory, .htaccess
    +Override: AuthConfig
    +Status: Extension
    +Module: mod_auth_dbm

    The AuthDBMGroupFile directive sets the name of a DBM file containing the list -of user groups for user authentication. Filename is the absolute path -to the group file.

    +of user groups for user authentication. Filename is the absolute path +to the group file.

    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.

    +be no whitespace within the value, and it must never contain any colons.

    Security: make sure that the AuthDBMGroupFile is stored outside the -document tree of the web-server; do not put it in the directory that +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 unless otherwise protected.

    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:

    +and password files to point to the same DBM:

    -

    -AuthDBMGroupFile /www/userbase
    +
    +AuthDBMGroupFile /www/userbase
    AuthDBMUserFile /www/userbase -
    +
    -The key for the single DBM is the username. The value consists of

    +The key for the single DBM is the username. The value consists of

    -

    +
    Unix Crypt-ed Password : List of Groups [ : (ignored) ] -
    +
    The password section contains the Unix crypt() 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.

    +password and group database.

    See also AuthName, AuthType and -AuthDBMUserFile.

    +AuthDBMUserFile.

    AuthDBMUserFile

     -Syntax: AuthDBMUserFile filename
    -Context: directory, .htaccess
    -Override: AuthConfig
    -Status: Extension
    -Module: mod_auth_dbm

    +Syntax: AuthDBMUserFile filename
    +Context: directory, .htaccess
    +Override: AuthConfig
    +Status: Extension
    +Module: mod_auth_dbm

    The AuthDBMUserFile directive sets the name of a DBM file containing the list -of users and passwords for user authentication. Filename is the -absolute path to the user file.

    +of users and passwords for user authentication. Filename is the +absolute path to the user file.

    The user file is keyed on the username. The value for a user is the crypt() encrypted password, optionally followed by a colon and arbitrary data. The colon and the data following it will be ignored -by the server.

    +by the server.

    Security: make sure that the AuthDBMUserFile is stored outside the -document tree of the web-server; do not put it in the directory that +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.

    +AuthDBMUserFile.

    Important compatibility note: The implementation of "dbmopen" in the apache modules reads the string length of the hashed values from the @@ -106,44 +106,44 @@ 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.

    +part of the problem.

    See also AuthName, AuthType and -AuthDBMGroupFile.

    +AuthDBMGroupFile.

    -

    +

    AuthDBMAuthoritative

     -Syntax: AuthDBMAuthoritative < on(default) | off >
    -Context: directory, .htaccess
    -Override: AuthConfig
    -Status: Base
    -Module: mod_auth

    +Syntax: AuthDBMAuthoritative < on(default) | off >
    +Context: directory, .htaccess
    +Override: AuthConfig
    +Status: Base
    +Module: mod_auth

    -Setting the AuthDBMAuthoritative directive explicitly to 'off' +Setting the AuthDBMAuthoritative directive explicitly to 'off' allows for both authentication and authorization to be passed on -to lower level modules (as defined in the Configuration -and modules.c file if there is no userID or -rule matching the supplied userID. If there is a userID +to lower level modules (as defined in the Configuration +and modules.c file 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 Authorization Required reply. -

    +

    So if a userID appears in the database of more than one module; or if a valid 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.

    +passed on; regardless of the AuthAuthoritative setting.

    A common use for this is in conjunction with one of the basic auth -modules; such as mod_auth.c. +modules; such as mod_auth.c. 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.

    +a lower level with a well protected .htpasswd file.

    -Default: By default; control is not passed on; and an unknown +Default: By default; control is not passed on; and an unknown userID or rule will result in an Authorization Required reply. Not setting it thus keeps the system secure; and forces an NSCA compliant -behaviour.

    +behaviour.

    Security: Do consider the implications of allowing a user to allow fall-through in his .htaccess file; and verify that this is really @@ -151,10 +151,10 @@ 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. -

    +

    See also AuthName, AuthType and -AuthDBMGroupFile.

    +AuthDBMGroupFile.

    diff --git a/docs/manual/mod/mod_autoindex.html b/docs/manual/mod/mod_autoindex.html index b71ad7fdfa..10c438158a 100644 --- a/docs/manual/mod/mod_autoindex.html +++ b/docs/manual/mod/mod_autoindex.html @@ -15,24 +15,24 @@

    Module mod_autoindex

    -This module is contained in the mod_autoindex.c file, and +This module is contained in the mod_autoindex.c file, and is compiled in by default. It provides for automatic directory indexing.

    Summary

    The index of a directory can come from one of two sources: -
      -
    • A file written by the user, typically called index.html. +
        +
      • A file written by the user, typically called index.html. The DirectoryIndex directive sets the name of this file. -This is controlled by mod_dir. -
      • Otherwise, a listing generated by the server. The other directives +This is controlled by mod_dir. +
      • Otherwise, a listing generated by the server. The other directives control the format of this listing. The 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. -
      +are controlled by mod_autoindex. +
    The two functions are separated so that you can completely remove (or replace) automatic index generation should you want to.

    @@ -61,241 +61,241 @@ order) even though they both are shown as "1K".

    Directives

    - -
  37. AddAlt -
  38. AddAltByEncoding -
  39. AddAltByType -
  40. AddDescription -
  41. AddIcon -
  42. AddIconByEncoding -
  43. AddIconByType -
  44. DefaultIcon -
  45. FancyIndexing -
  46. HeaderName -
  47. IndexIgnore -
  48. IndexOptions -
  49. ReadmeName -
    50.  -
    + +
  50. AddAlt +
  51. AddAltByEncoding +
  52. AddAltByType +
  53. AddDescription +
  54. AddIcon +
  55. AddIconByEncoding +
  56. AddIconByType +
  57. DefaultIcon +
  58. FancyIndexing +
  59. HeaderName +
  60. IndexIgnore +
  61. IndexOptions +
  62. ReadmeName +
    63.  +

    AddAlt

     -Syntax: AddAlt string file file...
    -Context: server config, virtual host, directory, .htaccess
    -Override: Indexes
    -Status: Base
    -Module: mod_autoindex

    +Syntax: AddAlt string file file...
    +Context: server config, virtual host, directory, .htaccess
    +Override: Indexes
    +Status: Base
    +Module: mod_autoindex

    This sets the alternate text to display for a file, instead of an icon, for -FancyIndexing. File is a file +FancyIndexing. File is a file extension, partial filename, wild-card expression or full filename for files -to describe. String is enclosed in double quotes -("). This alternate text is displayed if the client is +to describe. String is enclosed in double quotes +("). This alternate text is displayed if the client is image-incapable or has image loading disabled.

    AddAltByEncoding

     -Syntax: AddAltByEncoding string MIME-encoding - MIME-encoding...
    -Context: server config, virtual host, directory, .htaccess
    -Override: Indexes
    -Status: Base
    -Module: mod_autoindex

    +Syntax: AddAltByEncoding string MIME-encoding + MIME-encoding...
    +Context: server config, virtual host, directory, .htaccess
    +Override: Indexes
    +Status: Base
    +Module: mod_autoindex

    This sets the alternate text to display for a file, instead of an icon, for -FancyIndexing. MIME-encoding is a +FancyIndexing. MIME-encoding is a valid content-encoding, such as x-compress. -String is enclosed in double quotes -("). This alternate text is displayed if the client is +String is enclosed in double quotes +("). This alternate text is displayed if the client is image-incapable or has image loading disabled.

    AddAltByType

     -Syntax: AddAltByType string MIME-type MIME-type...
    -Context: server config, virtual host, directory, .htaccess
    -Override: Indexes
    -Status: Base
    -Module: mod_autoindex

    +Syntax: AddAltByType string MIME-type MIME-type...
    +Context: server config, virtual host, directory, .htaccess
    +Override: Indexes
    +Status: Base
    +Module: mod_autoindex

    This sets the alternate text to display for a file, instead of an icon, for -FancyIndexing. MIME-type is a +FancyIndexing. MIME-type is a valid content-type, such as text/html. -String is enclosed in double quotes -("). This alternate text is displayed if the client is +String is enclosed in double quotes +("). This alternate text is displayed if the client is image-incapable or has image loading disabled.

    AddDescription

     -Syntax: AddDescription string file file...
    -Context: server config, virtual host, directory, .htaccess
    -Override: Indexes
    -Status: Base
    -Module: mod_autoindex

    +Syntax: AddDescription string file file...
    +Context: server config, virtual host, directory, .htaccess
    +Override: Indexes
    +Status: Base
    +Module: mod_autoindex

    This sets the description to display for a file, for -FancyIndexing. File is a file +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 -

    +to describe. String is enclosed in double quotes +("). Example: +
    AddDescription "The planet Mars" /web/pics/mars.gif +

    AddIcon

     -Syntax: AddIcon icon name name ...
    -Context: server config, virtual host, directory, .htaccess
    -Override: Indexes
    -Status: Base
    -Module: mod_autoindex

    - -This sets the icon to display next to a file ending in name for -FancyIndexing. Icon is either a +Syntax: AddIcon icon name name ...
    +Context: server config, virtual host, directory, .htaccess
    +Override: Indexes
    +Status: Base
    +Module: mod_autoindex

    + +This sets the icon to display next to a file ending in name for +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.

    +(alttext,url) where alttext is the text tag given +for an icon for non-graphical browsers.

    -Name is either ^^DIRECTORY^^ for directories, ^^BLANKICON^^ for +Name is either ^^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 (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.

    +AddIcon, when possible.

    AddIconByEncoding

     -Syntax: AddIconByEncoding icon mime-encoding mime-encoding -...
    -Context: server config, virtual host, directory, .htaccess
    -Override: Indexes
    -Status: Base
    -Module: mod_autoindex

    +Syntax: AddIconByEncoding icon mime-encoding mime-encoding +...
    +Context: server config, virtual host, directory, .htaccess
    +Override: Indexes
    +Status: Base
    +Module: mod_autoindex

    This sets the icon to display next to files with -mime-encoding for 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.

    +mime-encoding for 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.

    -Mime-encoding is a wildcard expression matching required the +Mime-encoding is a wildcard expression matching required the content-encoding. Examples: -

    +
    AddIconByEncoding /icons/compress.xbm x-compress -

    +

    AddIconByType

     -Syntax: AddIconByType icon mime-type mime-type ...
    -Context: server config, virtual host, directory, .htaccess
    -Override: Indexes
    -Status: Base
    -Module: mod_autoindex

    - -This sets the icon to display next to files of type mime-type for -FancyIndexing. Icon is either a +Syntax: AddIconByType icon mime-type mime-type ...
    +Context: server config, virtual host, directory, .htaccess
    +Override: Indexes
    +Status: Base
    +Module: mod_autoindex

    + +This sets the icon to display next to files of type mime-type for +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.

    -Mime-type is a wildcard expression matching required the mime types. +(alttext,url) where alttext is the text tag given +for an icon for non-graphical browsers.

    +Mime-type is a wildcard expression matching required the mime types. Examples: -

    +
    AddIconByType (IMG,/icons/image.xbm) image/* -

    +

    DefaultIcon

     -Syntax: DefaultIcon url
    -Context: server config, virtual host, directory, .htaccess
    -Override: Indexes
    -Status: Base
    -Module: mod_autoindex

    +Syntax: DefaultIcon url
    +Context: server config, virtual host, directory, .htaccess
    +Override: Indexes
    +Status: Base
    +Module: mod_autoindex

    The DefaultIcon directive sets the icon to display for files when no specific icon is known, for FancyIndexing. -Url is a (%-escaped) relative URL to the icon. Examples: -

    +Url is a (%-escaped) relative URL to the icon. Examples: +
    DefaultIcon /icon/unknown.xbm -

    +

    FancyIndexing

     -Syntax: FancyIndexing boolean
    -Context: server config, virtual host, directory, .htaccess
    -Override: Indexes
    -Status: Base
    -Module: mod_autoindex -

    +Syntax: FancyIndexing boolean
    +Context: server config, virtual host, directory, .htaccess
    +Override: Indexes
    +Status: Base
    +Module: mod_autoindex +

    The FancyIndexing directive sets the FancyIndexing option for a directory. -Boolean can be on or off. The +Boolean can be on or off. The IndexOptions directive should be used in preference. -

    +

    Note that the FancyIndexing and IndexOptions directives will override each other. You should use IndexOptions FancyIndexing in preference to the standalone FancyIndexing directive.
    -
    +

    HeaderName

     -Syntax: HeaderName filename
    -Context: server config, virtual host, directory, .htaccess
    -Override: Indexes
    -Status: Base
    -Module: mod_autoindex

    +Syntax: HeaderName filename
    +Context: server config, virtual host, directory, .htaccess
    +Override: Indexes
    +Status: Base
    +Module: mod_autoindex

    The 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 +at the top of the index listing. Filename is the name of the file to include, and is taken to be relative to the directory being indexed. -The server first attempts to include filename.html -as an HTML document, otherwise it will include filename as plain +The server first attempts to include filename.html +as an HTML document, otherwise it will include filename as plain text. Example: -

    HeaderName HEADER
    -when indexing the directory /web, the server will first look for -the HTML file /web/HEADER.html and include it if found, otherwise -it will include the plain text file /web/HEADER, if it exists. +
    HeaderName HEADER
    +when indexing the directory /web, the server will first look for +the HTML file /web/HEADER.html and include it if found, otherwise +it will include the plain text file /web/HEADER, if it exists. -

    See also ReadmeName.

    +

    See also ReadmeName.

    IndexIgnore

     -Syntax: IndexIgnore file file ...
    -Context: server config, virtual host, directory, .htaccess
    -Override: Indexes
    -Status: Base
    -Module: mod_autoindex

    +Syntax: IndexIgnore file file ...
    +Context: server config, virtual host, directory, .htaccess
    +Override: Indexes
    +Status: Base
    +Module: mod_autoindex

    The IndexIgnore directive adds to the list of files to hide when listing -a directory. File is a file extension, partial filename, +a directory. File is a file extension, partial filename, wildcard expression or full filename for files to ignore. Multiple IndexIgnore directives add to the list, rather than the replacing the list -of ignored files. By default, the list contains `.'. Example: -

    +of ignored files. By default, the list contains `.'. Example: +
    IndexIgnore README .htaccess *~ -

    +

    IndexOptions

     -Syntax: IndexOptions option option ...
    -Context: server config, virtual host, directory, .htaccess
    -Override: Indexes
    -Status: Base
    -Module: mod_autoindex

    +Syntax: IndexOptions option option ...
    +Context: server config, virtual host, directory, .htaccess
    +Override: Indexes
    +Status: Base
    +Module: mod_autoindex

    The IndexOptions directive specifies the behavior of the directory indexing. -Option can be one of -

    -
    FancyIndexing -
    +Option can be one of +
    +
    FancyIndexing +
    This turns on fancy indexing of directories.
    Note that the FancyIndexing and @@ -303,8 +303,8 @@ This turns on fancy indexing of directories. should use IndexOptions FancyIndexing in preference to the standalone FancyIndexing directive.
    -
    IconHeight[=pixels] (Apache 1.3 and later) -
    +
    IconHeight[=pixels] (Apache 1.3 and later) +
    Presence of this option, when used with IconWidth, will cause the server to include HEIGHT and WIDTH attributes in the @@ -313,13 +313,13 @@ 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. -
    IconsAreLinks -
    +
    IconsAreLinks +
    This makes the icons part of the anchor for the filename, for fancy indexing. -
    IconWidth[=pixels] (Apache 1.3 and later) -
    +
    IconWidth[=pixels] (Apache 1.3 and later) +
    Presence of this option, when used with IconHeight, will cause the server to include HEIGHT and WIDTH attributes in the @@ -328,8 +328,8 @@ 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. -
    ScanHTMLTitles -
    +
    ScanHTMLTitles +
    This enables the extraction of the title from HTML documents for fancy indexing. If the file does not have a description given by AddDescription then httpd will read the @@ -342,12 +342,12 @@ directory listing into links for sorting. The default behaviour is for them to be links; selecting the column heading will sort the directory listing by the values in that column. Only available in Apache 1.3 and later. -
    SuppressDescription -
    +
    SuppressDescription +
    This will suppress the file description in fancy indexing listings. -
    SuppressHTMLPreamble -
    +
    SuppressHTMLPreamble +
    If the directory actually contains a file specified by the ). 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. -
    SuppressLastModified -
    +
    SuppressLastModified +
    This will suppress the display of the last modification date, in fancy indexing listings. -
    SuppressSize -
    +
    SuppressSize +
    This will suppress the file size in fancy indexing listings. -
    +
    This default is that no options are enabled. If multiple IndexOptions could apply to a directory, then the most specific one is taken complete; the options are not merged. For example: -
    -<Directory /web/docs>
    -IndexOptions FancyIndexing
    -</Directory>
    -<Directory /web/docs/spec>
    -IndexOptions ScanHTMLTitles
    +
    +<Directory /web/docs>
    +IndexOptions FancyIndexing
    +</Directory>
    +<Directory /web/docs/spec>
    +IndexOptions ScanHTMLTitles
    </Directory> -
    -then only ScanHTMLTitles will be set for the /web/docs/spec -directory.

    +
    +then only ScanHTMLTitles will be set for the /web/docs/spec +directory.

    ReadmeName

     -Syntax: ReadmeName filename
    -Context: server config, virtual host, directory, .htaccess
    -Override: Indexes
    -Status: Base
    -Module: mod_autoindex

    +Syntax: ReadmeName filename
    +Context: server config, virtual host, directory, .htaccess
    +Override: Indexes
    +Status: Base
    +Module: mod_autoindex

    The 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 the end of the index listing. Filename is the name of the file to include, and is taken to be relative to the directory being indexed. -The server first attempts to include filename.html -as an HTML document, otherwise it will include filename as plain +The server first attempts to include filename.html +as an HTML document, otherwise it will include filename as plain text. Example: -

    ReadmeName README
    -when indexing the directory /web, the server will first look for -the HTML file /web/README.html and include it if found, otherwise -it will include the plain text file /web/README, if it exists. +
    ReadmeName README
    +when indexing the directory /web, the server will first look for +the HTML file /web/README.html and include it if found, otherwise +it will include the plain text file /web/README, if it exists. -

    See also HeaderName.

    +

    See also HeaderName.

    diff --git a/docs/manual/mod/mod_cern_meta.html b/docs/manual/mod/mod_cern_meta.html index 127ca3ef2b..9e311e3345 100644 --- a/docs/manual/mod/mod_cern_meta.html +++ b/docs/manual/mod/mod_cern_meta.html @@ -13,9 +13,9 @@ ALINK="#FF0000" > -

    Apache module mod_cern_meta

    +

    Apache module mod_cern_meta

    -This module is contained in the mod_cern_meta.c file, and +This module is contained in the mod_cern_meta.c file, and is not compiled in by default. It provides for CERN httpd metafile semantics. It is only available in Apache 1.1 and later. @@ -30,64 +30,64 @@ 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. +

    More information on the +CERN metafile semantics is available.

    Directives

    - + -
    +

    MetaFiles

    -Syntax: MetaFiles on/off
    -Default: MetaFiles off
    -Context: per-directory config
    -Status: Base
    -Module: mod_cern_meta
    -Compatibility: MetaFiles is only available in Apache 1.3 -and later.

    +Syntax: MetaFiles on/off
    +Default: MetaFiles off
    +Context: per-directory config
    +Status: Base
    +Module: mod_cern_meta
    +Compatibility: MetaFiles is only available in Apache 1.3 +and later.

    Turns on/off Meta file processing on a per-directory basis. This option was introduced in Apache 1.3.

    MetaDir

    -Syntax: MetaDir directory name
    -Default: MetaDir .web
    -Context: (Apache prior to 1.3) server config
    -Context: (Apache 1.3) per-directory config
    -Status: Base
    -Module: mod_cern_meta
    -Compatibility: MetaDir is only available in Apache 1.1 -and later.

    +Syntax: MetaDir directory name
    +Default: MetaDir .web
    +Context: (Apache prior to 1.3) server config
    +Context: (Apache 1.3) per-directory config
    +Status: Base
    +Module: mod_cern_meta
    +Compatibility: MetaDir is only available in Apache 1.1 +and later.

    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 "." to look in the same directory as the +accessed. Set to "." to look in the same directory as the file.

    MetaSuffix

    -Syntax: MetaSuffix suffix
    -Default: MetaSuffix .meta
    -Context: (Apache prior to 1.3) server config
    -Context: (Apache 1.3) per-directory config
    -Status: Base
    -Module: mod_cern_meta
    -Compatibility: MetaSuffix is only available in Apache 1.1 -and later.

    +Syntax: MetaSuffix suffix
    +Default: MetaSuffix .meta
    +Context: (Apache prior to 1.3) server config
    +Context: (Apache 1.3) per-directory config
    +Status: Base
    +Module: mod_cern_meta
    +Compatibility: MetaSuffix is only available in Apache 1.1 +and later.

    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 -DOCUMENT_ROOT/somedir/index.html to look in -DOCUMENT_ROOT/somedir/.web/index.html.meta and will use +directives will cause a request to +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. -

    +

    diff --git a/docs/manual/mod/mod_cgi.html b/docs/manual/mod/mod_cgi.html index cb45cc853f..0447f881dd 100644 --- a/docs/manual/mod/mod_cgi.html +++ b/docs/manual/mod/mod_cgi.html @@ -1,8 +1,8 @@ - - -Apache module mod_cgi - + + +Apache module mod_cgi + -

    Module mod_cgi

    +

    Module mod_cgi

    -This module is contained in the mod_cgi.c file, and +This module is contained in the mod_cgi.c file, and is compiled in by default. It provides for execution of CGI scripts. -Any file with mime type application/x-httpd-cgi will be +Any file with mime type application/x-httpd-cgi will be processed by this module.

    Summary

    -Any file that has the mime type application/x-httpd-cgi -or handler cgi-script (Apache 1.1 or later) +Any file that has the mime type 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 ending in an extension defined by the AddType directive, or by being in -a ScriptAlias directory.

    +a ScriptAlias directory.

    When the server invokes a CGI script, it will add a variable called -DOCUMENT_ROOT to the environment. This variable will contain the +DOCUMENT_ROOT to the environment. This variable will contain the value of the DocumentRoot configuration variable. @@ -41,21 +41,21 @@ configuration variable. The server will set the CGI environment variables as described in the CGI specification, with the following provisions: -

    -
    REMOTE_HOST -
    This will only be set if the server has not been compiled with -MINIMAL_DNS. -
    REMOTE_IDENT -
    This will only be set if -IdentityCheck is set to on. -
    REMOTE_USER -
    This will only be set if the CGI script is subject to authentication. -
    +
    +
    REMOTE_HOST +
    This will only be set if the server has not been compiled with +MINIMAL_DNS. +
    REMOTE_IDENT +
    This will only be set if +IdentityCheck is set to on. +
    REMOTE_USER +
    This will only be set if the CGI script is subject to authentication. +

    -

    +
    -

    CGI Debugging

    +

    CGI Debugging

    Debugging CGI scripts has traditionally been difficult, mainly because it has @@ -66,7 +66,7 @@ which are failing to run properly. These directives, included in Apache 1.2 and later, provide more detailed logging of errors when they occur. -
    +

    CGI Logfile Format

    @@ -75,53 +75,53 @@ 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: -
    -  %% [time] request-line
-  %% HTTP-status CGI-script-filename
-
    +
    +  %% [time] request-line
+  %% HTTP-status CGI-script-filename
+
    If the error is that CGI script cannot be run, the log file will contain an extra two lines: -
    +
       %%error
-  error-message
-
    
+  error-message
+
    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: -
    +
       %request
-  All HTTP request headers received
-  POST or PUT entity (if any)
+  All HTTP request headers received
+  POST or PUT entity (if any)
   %response
-  All headers output by the CGI script
+  All headers output by the CGI script
   %stdout
-  CGI standard output
+  CGI standard output
   %stderr
-  CGI standard error
-
    
+  CGI standard error
+
    (The %stdout and %stderr parts may be missing if the script did not output anything on standard output or standard error). -
    +

    Directives

    -

    ScriptLog

    +

    ScriptLog

    -Syntax: ScriptLog filename
    -Default: none
    -Context: resource config
    -Status: mod_cgi -

    +Syntax: ScriptLog filename
    +Default: none
    +Context: resource config
    +Status: mod_cgi +

    -The ScriptLog directive sets the CGI script error logfile. +The ScriptLog 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 server root. @@ -135,34 +135,34 @@ 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.

    -

    Note that script logging is meant to be a debugging feature when +

    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.

    +it was designed.

    -

    ScriptLogLength

    +

    ScriptLogLength

    -Syntax: ScriptLogLength size
    -Default: 10385760
    -Context: resource config
    -Status: mod_cgi -

    +Syntax: ScriptLogLength size
    +Default: 10385760
    +Context: resource config
    +Status: mod_cgi +

    -ScriptLogLength can be used to limit the size of the CGI +ScriptLogLength 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. -

    ScriptLogBuffer

    +

    ScriptLogBuffer

    -Syntax: ScriptLogBuffer size
    -Default: 1024
    -Context: resource config
    -Status: mod_cgi -

    +Syntax: ScriptLogBuffer size
    +Default: 1024
    +Context: resource config
    +Status: mod_cgi +

    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 diff --git a/docs/manual/mod/mod_dir.html b/docs/manual/mod/mod_dir.html index 4d1c461d80..9fc99ab2d3 100644 --- a/docs/manual/mod/mod_dir.html +++ b/docs/manual/mod/mod_dir.html @@ -15,47 +15,47 @@

    Module mod_dir

    -This module is contained in the mod_dir.c file, and +This module is contained in the mod_dir.c file, and is compiled in by default. It provides for "trailing slash" redirects and serving directory index files.

    Summary

    The index of a directory can come from one of two sources: -
      -
    • A file written by the user, typically called index.html. +
        +
      • A file written by the user, typically called index.html. The DirectoryIndex directive sets the name of this file. -This is controlled by mod_dir. -
      • Otherwise, a listing generated by the server. This is provided by -mod_autoindex. -
      +This is controlled by mod_dir. +
    • Otherwise, a listing generated by the server. This is provided by +mod_autoindex. +
    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 +

    A "trailing slash" redirect is issued when the server receives a request for a URL http://servername/foo/dirname where dirname is a directory. Directories require a trailing -slash, so mod_dir issues a redirect to +slash, so mod_dir issues a redirect to http://servername/foo/dirname/.

    Directives

    - -
  63. DirectoryIndex -
    64.  -
    + +
  64. DirectoryIndex +
    65.  +

    DirectoryIndex

     -Syntax: DirectoryIndex local-url local-url ...
    -Default: DirectoryIndex index.html
    -Context: server config, virtual host, directory, .htaccess
    -Override: Indexes
    -Status: Base
    -Module: mod_dir

    +Syntax: DirectoryIndex local-url local-url ...
    +Default: DirectoryIndex index.html
    +Context: server config, virtual host, directory, .htaccess
    +Override: Indexes
    +Status: Base
    +Module: mod_dir

    The 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 a directory name. Local-url is the +at the end of the a 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 @@ -65,19 +65,19 @@ listing of the directory.

    Example: -

    +
    DirectoryIndex index.html -
    -then a request for http://myserver/docs/ would return -http://myserver/docs/index.html if it exists, or would list -the directory if it did not.

    +

    +then a request for http://myserver/docs/ would return +http://myserver/docs/index.html if it exists, or would list +the directory if it did not.

    Note that the documents do not need to be relative to the directory; -

    -DirectoryIndex index.html index.txt /cgi-bin/index.pl
    -would cause the CGI script /cgi-bin/index.pl to be executed -if neither index.html or index.txt existed in -a directory.

    +
    +DirectoryIndex index.html index.txt /cgi-bin/index.pl
    +would cause the CGI script /cgi-bin/index.pl to be executed +if neither index.html or index.txt existed in +a directory.

    diff --git a/docs/manual/mod/mod_env.html b/docs/manual/mod/mod_env.html index 7d6de71d8f..4283b138db 100644 --- a/docs/manual/mod/mod_env.html +++ b/docs/manual/mod/mod_env.html @@ -13,9 +13,9 @@ ALINK="#FF0000" > -

    Apache module mod_env

    +

    Apache module mod_env

    -This module is contained in the mod_env.c file, and +This module is contained in the mod_env.c file, and is not compiled in by default. It provides for passing environment variables to CGI/SSI scripts. Is is only available in Apache 1.1 and later. @@ -29,63 +29,63 @@ useful to web-admins who wish to migrate from CERN to Apache without rewriting all their scripts

    Directives

    - + -
    +

    PassEnv

    -Syntax: PassEnv variable variable ...
    -Context: server config, virtual host
    -Status: Base
    -Module: mod_env
    -Compatibility: PassEnv is only available in -Apache 1.1 and later.

    +Syntax: PassEnv variable variable ...
    +Context: server config, virtual host
    +Status: Base
    +Module: mod_env
    +Compatibility: PassEnv is only available in +Apache 1.1 and later.

    Specifies one or more environment variables to pass to CGI scripts from the server's own environment. Example: -

    +
         PassEnv LD_LIBRARY_PATH
-
    
+

    SetEnv

    -Syntax: SetEnv variable value
    -Context: server config, virtual host
    -Status: Base
    -Module: mod_env
    -Compatibility: SetEnv is only available in -Apache 1.1 and later.

    +Syntax: SetEnv variable value
    +Context: server config, virtual host
    +Status: Base
    +Module: mod_env
    +Compatibility: SetEnv is only available in +Apache 1.1 and later.

    Sets an environment variable, which is then passed on to CGI scripts. Example: -

    +
         SetEnv SPECIAL_PATH /foo/bin
-
    
+
    -
    +

    UnsetEnv

    -Syntax: UnsetEnv variable variable ...
    -Context: server config, virtual host
    -Status: Base
    -Module: mod_env
    -Compatibility: UnsetEnv is only available in -Apache 1.1 and later.

    +Syntax: UnsetEnv variable variable ...
    +Context: server config, virtual host
    +Status: Base
    +Module: mod_env
    +Compatibility: UnsetEnv is only available in +Apache 1.1 and later.

    Removes one or more environment variables from those passed on to CGI scripts. Example: -

    +
         UnsetEnv LD_LIBRARY_PATH
-
    
+
    -

    +

    diff --git a/docs/manual/mod/mod_example.html b/docs/manual/mod/mod_example.html index 26004e37c0..f582dd45d2 100644 --- a/docs/manual/mod/mod_example.html +++ b/docs/manual/mod/mod_example.html @@ -12,7 +12,7 @@ ALINK="#FF0000" > -

    Module mod_example

    +

    Module mod_example

    This module is contained in the modules/mod_example.c file, and is not compiled in by default. It illustrates many of diff --git a/docs/manual/mod/mod_expires.html b/docs/manual/mod/mod_expires.html index df2782469a..a6f1914fe2 100644 --- a/docs/manual/mod/mod_expires.html +++ b/docs/manual/mod/mod_expires.html @@ -59,11 +59,11 @@ Syntax: ExpiresActive boolean
    Context: server config, virtual host, directory, .htaccess -
    +
    Override: Indexes -
    +
    Status: Extension -
    +
    Module: mod_expires

    @@ -100,11 +100,11 @@ Syntax: ExpiresByType mime-type <code>seconds
    Context: server config, virtual host, directory, .htaccess -
    +
    Override: Indexes -
    +
    Status: Extension -
    +
    Module: mod_expires

    @@ -170,11 +170,11 @@ Syntax: ExpiresDefault <code>seconds
    Context: server config, virtual host, directory, .htaccess -
    +
    Override: Indexes -
    +
    Status: Extension -
    +
    Module: mod_expires

    diff --git a/docs/manual/mod/mod_headers.html b/docs/manual/mod/mod_headers.html index 12b8490cdf..e5745b2bbc 100644 --- a/docs/manual/mod/mod_headers.html +++ b/docs/manual/mod/mod_headers.html @@ -13,53 +13,53 @@ ALINK="#FF0000" > -

    Module mod_headers

    +

    Module mod_headers

    The optional headers module allows for the customization of HTTP response headers. Headers can be merged, replaced or removed. The directives described in this document are only available if Apache is -compiled with mod_headers.c. +compiled with mod_headers.c. -
    +

    Directive

    - + -
    +

    Header

    -Syntax: Header [ set | append | add ] header value
    -Syntax: Header unset header
    -Context: server config, virtual host, access.conf, .htaccess
    -Status: optional
    -Module: mod_header

    +Syntax: Header [ set | append | add ] header value
    +Syntax: Header unset header
    +Context: server config, virtual host, access.conf, .htaccess
    +Status: optional
    +Module: mod_header

    This directive can replace, merge or remove HTTP response headers. The action it performs is determined by the first argument. This can be one of the following values: -

      -
    • set
      +
        +
      • set
        The response header is set, replacing any previous header with this name -
      • append
        +
      • append
        The response header is appended to any existing header of the same name. When a new value is merged onto an existing header it is separated from the existing header with a comma. This is the HTTP standard way of giving a header multiple values. -
      • add
        +
      • add
        The response header is added to the existing set of headers, even if this header already exists. This can result in two (or more) headers having the same name. This can lead to unforeseen consequences, and in general "append" should be used instead. -
      • unset
        +
      • unset
        The response header of this name is removed, if it exists. If there are multiple headers of the same name, only the first one set will be removed. -
      +
    This argument is followed by a header name, which can include the final colon, but it is not required. Case is ignored. For @@ -73,25 +73,25 @@ The Header directive can occur almost anywhere within the server configuration. It is valid in the main server config and virtual host sections, inside <Directory>, <Location> and <Files> sections, and within .htaccess files. -

    +

    The Header directives are processed in the following order: -

      -
    1. main server -
    2. virtual host -
    3. <Directory> sections and .htaccess -
    4. <Location> -
    5. <Files> -
    +
      +
    1. main server +
    2. virtual host +
    3. <Directory> sections and .htaccess +
    4. <Location> +
    5. <Files> +
    Order is important. These two headers have a different effect if reversed: -
    +
     Header append Author "John P. Doe"
 Header unset Author
-
    
+
    This way round, the Author header is not set. If reversed, the Author header is set to "John P. Doe". -

    +

    The Header directives are processed just before the response is sent by its handler. These means that some headers that are added just diff --git a/docs/manual/mod/mod_imap.html b/docs/manual/mod/mod_imap.html index 08ca89a18c..eb647df241 100644 --- a/docs/manual/mod/mod_imap.html +++ b/docs/manual/mod/mod_imap.html @@ -1,8 +1,8 @@ - - -Apache module mod_imap - + + +Apache module mod_imap + -

    Module mod_imap

    +

    Module mod_imap

    -This module is contained in the mod_imap.c file, and is -compiled in by default. It provides for .map files, -replacing the functionality of the imagemap CGI +This module is contained in the mod_imap.c file, and is +compiled in by default. It provides for .map files, +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 +imap-file (using either AddHandler or SetHandler) will be processed by this module.

    Summary

    This module is in the default Apache distribution. The following directive will -activate files ending with .map as imagemap files: +activate files ending with .map as imagemap files: -
    AddHandler imap-file map
    +
    AddHandler imap-file map
    Note that the following is still supported: -
    AddType application/x-httpd-imap map
    +
    AddType application/x-httpd-imap map
    However, we are trying to phase out "magic MIME types" so we are deprecating this method. @@ -42,111 +42,111 @@ this method. The imagemap module adds some new features that were not possible with previously distributed imagemap programs.

    -

      +
      • URL references relative to the Referer: information.
      • Default <BASE> assignment through a new map directive -base. -
      • No need for imagemap.conf file. +base. +
      • No need for imagemap.conf file.
      • Point references.
      • Configurable generation of imagemap menus. -
      +

    Configuration Directives

    - + -

    +

    ImapMenu

    -Syntax: ImapMenu {none, formatted, semi-formatted, - unformatted}
    -Context: server config, virtual host, directory, .htaccess
    -Override: Indexes
    -Module: mod_imap.c
    -Compatibility: ImapMenu is only available in Apache -1.1 and later.

    +Syntax: ImapMenu {none, formatted, semi-formatted, + unformatted}
    +Context: server config, virtual host, directory, .htaccess
    +Override: Indexes
    +Module: mod_imap.c
    +Compatibility: ImapMenu is only available in Apache +1.1 and later.

    The ImapMenu directive determines the action taken if an imagemap file is called without valid coordinates. -

    -
    none -
    If ImapMenu is - none, no menu is generated, and the default +
    +
    none +
    If ImapMenu is + none, no menu is generated, and the default action is performed. -
    formatted -
    A formatted menu is the simplest menu. Comments +
    formatted +
    A formatted 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. -
    semiformatted -
    In the semiformatted menu, comments are printed +
    semiformatted +
    In the semiformatted 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 -
    Comments are printed, blank lines are ignored. Nothing is + the menu is the same as a formatted menu. +
    unformatted +
    Comments are printed, blank lines are ignored. Nothing is printed that does not appear in the imagemap file. All breaks and headers must be included as comments in the imagemap file. This gives you the most flexibility over the appearance of your menus, but requires you to treat your map files as HTML instead of plaintext. -
    +
    -

    +

    ImapDefault

    -Syntax: ImapDefault {error, nocontent, - map, referer, URL}
    -Context: server config, virtual host, directory, .htaccess
    -Override: Indexes
    -Module: mod_imap.c
    -Compatibility: ImapDefault is only available in Apache -1.1 and later.

    +Syntax: ImapDefault {error, nocontent, + map, referer, URL}
    +Context: server config, virtual host, directory, .htaccess
    +Override: Indexes
    +Module: mod_imap.c
    +Compatibility: ImapDefault is only available in Apache +1.1 and later.

    -The ImapDefault directive sets the default default used in -the imagemap files. It's value is overridden by a default +The ImapDefault directive sets the default default used in +the imagemap files. It's 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 +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. -

    +

    ImapBase

    -Syntax: ImapBase {map, referer, URL}
    -Context: server config, virtual host, directory, .htaccess
    -Override: Indexes
    -Module: mod_imap.c
    -Compatibility: ImapBase is only available in Apache -1.1 and later.

    - -The ImapBase directive sets the default base used in -the imagemap files. It's value is overridden by a base +Syntax: ImapBase {map, referer, URL}
    +Context: server config, virtual host, directory, .htaccess
    +Override: Indexes
    +Module: mod_imap.c
    +Compatibility: ImapBase is only available in Apache +1.1 and later.

    + +The ImapBase directive sets the default base used in +the imagemap files. It's value is overridden by a base directive within the imagemap file. If not present, the -base defaults to http://servername/. +base defaults to http://servername/. -

    -

    +

    +

    Imagemap File

    The lines in the imagemap files can have one of several formats: -
    -directive value [x,y ...]
    -directive value "Menu text" [x,y ...]
    -directive value x,y ... "Menu text"
    -
    -The directive is one of base, default, -poly, circle, rect, or -point. The value is an absolute or relative URL, or one +
    +directive value [x,y ...]
    +directive value "Menu text" [x,y ...]
    +directive value x,y ... "Menu text"
    +
    +The directive is one of 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 +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. @@ -154,128 +154,128 @@ beginning with '#' are comments. 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. -
    -
    base Directive -
    Has the effect of <BASE href="value">. The +
    +
    base Directive +
    Has the effect of <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 + 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 + 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 Directive -
    The action taken if the coordinates given do not fit any of the - poly, 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 +

    +

    default Directive +
    The action taken if the coordinates given do not fit any of the + poly, 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 Directive -
    Takes three to one-hundred points, and is obeyed if the user selected +

    +

    poly Directive +
    Takes three to one-hundred points, and is obeyed if the user selected coordinates fall within the polygon defined by these points. -

    -

    circle -
    Takes the center coordinates of a circle and a point on the circle. Is +

    +

    circle +
    Takes the center coordinates of a circle and a point on the circle. Is obeyed if the user selected point is with the circle. -

    -

    rect Directive -
    Takes the coordinates of two opposing corners of a rectangle. Obeyed +

    +

    rect Directive +
    Takes the coordinates of two opposing corners of a rectangle. Obeyed if the point selected is within this rectangle. -

    -

    point Directive -
    Takes a single point. The point directive closest to the user +

    +

    point Directive +
    Takes a single point. The point directive closest to the user selected point is obeyed if no other directives are satisfied. - Note that default will not be followed if a - point directive is present and valid coordinates are + Note that default will not be followed if a + point directive is present and valid coordinates are given. -
    +

    Values

    The values for each of the directives can any of the following: -
    -
    a URL -
    The URL can be relative or absolute URL. Relative URLs can +
    +
    a URL +
    The URL can be relative or absolute URL. Relative URLs can contain '..' syntax and will be resolved relative to the - base value.
    - base itself will not resolved according to the current - value. A statement base mailto: will work properly, though. -

    -

    map -
    Equivalent to the URL of the imagemap file itself. No + base value.
    + base itself will not resolved according to the current + value. A statement base mailto: will work properly, though. +

    +

    map +
    Equivalent to the URL of the imagemap file itself. No coordinates are sent with this, so a menu will be generated unless ImapMenu is set to 'none'. -

    -

    menu -
    Synonymous with map. -

    -

    referer -
    Equivalent to the URL of the referring document. - Defaults to http://servername/ if no Referer: +

    +

    menu +
    Synonymous with map. +

    +

    referer +
    Equivalent to the URL of the referring document. + Defaults to http://servername/ if no Referer: header was present. -

    -

    nocontent -
    Sends a status code of 204 No Content, +

    +

    nocontent +
    Sends a status code of 204 No Content, telling the client to keep the same page displayed. Valid for - all but base. -

    -

    error -
    Fails with a 500 Server Error. Valid for all but - base, but sort of silly for anything but - default. -
    + all but base. +

    +

    error +
    Fails with a 500 Server Error. Valid for all but + base, but sort of silly for anything but + default. +

    Coordinates

    -
    -
    0,0 200,200 -
    A coordinate consists of an x and a y value +
    +
    0,0 200,200 +
    A coordinate consists of an x and a y value separated by a comma. The coordinates are separated from each other by whitespace. To accommodate the way Lynx handles imagemaps, should a - user select the coordinate 0,0, it is as if + user select the coordinate 0,0, it is as if no coordinate had been selected. -
    +

    Quoted Text

    -
    -
    "Menu Text" -
    After the value or after the coordinates, the line optionally may +
    +
    "Menu Text" +
    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:
    - <a href="http://foo.com/">Menu text</a>
    + text for the link if a menu is generated:
    + <a HREF="http://foo.com/">Menu text</a>
    If no quoted text is present, the name of the link will be used - as the text:
    - <a href="http://foo.com/">http://foo.com</a>
    + as the text:
    + <a HREF="http://foo.com/">http://foo.com</a>
    It is impossible to escape double quotes within this text. -
    +
    -
    +

    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?"
    -
    +
    +#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

    -
    -<A HREF="/maps/imagemap1.map">
    -<IMG ISMAP SRC="/images/imagemap1.gif">
    +
    +<A HREF="/maps/imagemap1.map">
    +<IMG ISMAP SRC="/images/imagemap1.gif">
    </A> -

    +

    diff --git a/docs/manual/mod/mod_include.html b/docs/manual/mod/mod_include.html index 939d8c33be..81647ed873 100644 --- a/docs/manual/mod/mod_include.html +++ b/docs/manual/mod/mod_include.html @@ -15,7 +15,7 @@

    Module mod_include

    -This module is contained in the mod_include.c file, and +This module is contained in the mod_include.c file, and is compiled in by default. It provides for server-parsed html documents. Several directives beyond the original NCSA definition have been included in Apache 1.2 - these are flagged below with the phrase @@ -49,107 +49,107 @@ directive can be used to parse normal (text/html) files, based on file permissions.

    For backwards compatibility, documents with mime type -text/x-server-parsed-html or -text/x-server-parsed-html3 will also be parsed -(and the resulting output given the mime type text/html). +text/x-server-parsed-html or +text/x-server-parsed-html3 will also be parsed +(and the resulting output given the mime type text/html).

    Basic Elements

    The document is parsed as an HTML document, with special commands embedded as SGML comments. A command has the syntax: -
    -<!--#element attribute=value attribute=value ... - --> -
    +
    +<!--#element attribute=value attribute=value ... + --> +
    The value will often be enclosed in double quotes; 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. -

    -The allowed elements are:

    +

    +The allowed elements are:

    -

    +
    -
    config -
    +
    config +
    This command controls various aspects of the parsing. The valid attributes are: -
    -
    errmsg -
    The value is a message that is sent back to the client if an error occurs +
    +
    errmsg +
    The value is a message that is sent back to the client if an error occurs whilst parsing the document. -
    sizefmt -
    The value sets the format to be used which displaying the size of a file. -Valid values are bytes for a count in bytes, or -abbrev for a count in Kb or Mb as appropriate. -
    timefmt -
    The value is a string to be used by the strftime(3) library +
    sizefmt +
    The value sets the format to be used which displaying the size of a file. +Valid values are bytes for a count in bytes, or +abbrev for a count in Kb or Mb as appropriate. +
    timefmt +
    The value is a string to be used by the strftime(3) library routine when printing dates. -
    +
    -
    echo -
    +
    echo +
    This command prints one of the include variables, defined below. -If the variable is unset, it is printed as (none). -Any dates printed are subject to the currently configured timefmt. +If the variable is unset, it is printed as (none). +Any dates printed are subject to the currently configured timefmt. Attributes: -
    -
    var -
    The value is the name of the variable to print. -
    +
    +
    var +
    The value is the name of the variable to print. +
    -
    exec -
    +
    exec +
    The exec command executes a given shell command or CGI script. The IncludesNOEXEC Option disables this command completely. The valid attributes are: -
    -
    cgi -
    +
    +
    cgi +
    The value specifies a (%-encoded) URL relative path to the CGI script. If the path does not begin with a (/), 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 ScriptAlias -or the ExecCGI Option).

    +or the ExecCGI Option).

    The CGI script is given the 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.

    +standard CGI environment.

    If the script returns a Location: header instead of output, then this -will be translated into an HTML anchor.

    -The include virtual element should be used in preference to -exec cgi. -

    cmd -
    The server will execute the given string using /bin/sh. +will be translated into an HTML anchor.

    +The include virtual element should be used in preference to +exec cgi. +

    cmd +
    The server will execute the given string using /bin/sh. The include variables are available to the command. -
    +
    -
    fsize -
    +
    fsize +
    This command prints the size of the specified file, subject to the -sizefmt format specification. Attributes: -
    -
    file -
    The value is a path relative to the directory containing the current +sizefmt format specification. Attributes: +
    +
    file +
    The value is a path relative to the directory containing the current document being parsed. -
    virtual -
    The value is a (%-encoded) URL-path relative to the current document being +
    virtual +
    The value is a (%-encoded) URL-path relative to the current document being parsed. If it does not begin with a slash (/) then it is taken to be relative to the current document. -
    +
    -
    flastmod -
    +
    flastmod +
    This command prints the last modification date of the specified file, -subject to the timefmt format specification. The attributes are -the same as for the fsize command. +subject to the timefmt format specification. The attributes are +the same as for the fsize command. -
    include -
    +
    include +
    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 the @@ -159,68 +159,68 @@ to be executed, then it will not be included; this prevents the execution of CGI scripts. Otherwise CGI scripts are invoked as normal using the complete URL given in the command, including any query string. -

    +

    An attribute defines the location of the document; the inclusion is done for each attribute given to the include command. The valid attributes are: -

    -
    file -
    The value is a path relative to the directory containing the current -document being parsed. It cannot contain ../, nor can it be an -absolute path. The virtual attribute should always be used +
    +
    file +
    The value is a path relative to the directory containing the current +document being parsed. It cannot contain ../, nor can it be an +absolute path. The virtual attribute should always be used in preference to this one. -
    virtual -
    The value is a (%-encoded) URL relative to the current document being +
    virtual +
    The value is a (%-encoded) URL relative to the current document being parsed. 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. -
    printenv -
    This prints out a listing of all existing variables and their values. +
    printenv +
    This prints out a listing of all existing variables and their values. No attributes. -
    For example: <!--#printenv --> -
    Apache 1.2 and above. - -
    set -
    This sets the value of a variable. Attributes: -
    -
    var -
    The name of the variable to set. -
    value -
    The value to give a variable. -
    +
    For example: <!--#printenv --> +
    Apache 1.2 and above. + +
    set +
    This sets the value of a variable. Attributes: +
    +
    var +
    The name of the variable to set. +
    value +
    The value to give a variable. +
    For example: <!--#set var="category" value="help" --> -
    Apache 1.2 and above. +
    Apache 1.2 and above. -
    +

    Include Variables

    In addition to the variables in the standard CGI environment, these are -available for the echo command, for if and -elif, and to any program invoked by the document. - -
    -
    DATE_GMT -
    The current date in Greenwich Mean Time. -
    DATE_LOCAL -
    The current date in the local time zone. -
    DOCUMENT_NAME -
    The filename (excluding directories) of the document requested by the +available for the echo command, for if and +elif, and to any program invoked by the document. + +
    +
    DATE_GMT +
    The current date in Greenwich Mean Time. +
    DATE_LOCAL +
    The current date in the local time zone. +
    DOCUMENT_NAME +
    The filename (excluding directories) of the document requested by the user. -
    DOCUMENT_URI -
    The (%-decoded) URL path of the document requested by the user. Note that -in the case of nested include files, this is not then URL for the +
    DOCUMENT_URI +
    The (%-decoded) URL path of the document requested by the user. Note that +in the case of nested include files, this is not then URL for the current document. -
    LAST_MODIFIED -
    The last modification date of the document requested by the user. -
    -

    +

    LAST_MODIFIED +
    The last modification date of the document requested by the user. +
    +

    Variable Substitution

    Variable substitution is done within quoted strings in most cases @@ -350,44 +350,44 @@ elements are: 'string1 string2' results in string1 string2 -

    +

    Directives

    - -
    + +

    XBitHack

    -Syntax: XBitHack status
    -Default: XBitHack off
    -Context: server config, virtual host, directory, .htaccess
    -Override: Options
    -Status: Base
    -Module: mod_include

    +Syntax: XBitHack status
    +Default: XBitHack off
    +Context: server config, virtual host, directory, .htaccess
    +Override: Options
    +Status: Base
    +Module: mod_include

    The XBitHack directives controls the parsing of ordinary html documents. This directive only affects files associated with the MIME type text/html. -Status can have the following values: -

    -
    off -
    No special treatment of executable files. -
    on -
    Any file that has the user-execute bit set will be treated as a +Status can have the following values: +
    +
    off +
    No special treatment of executable files. +
    on +
    Any file that has the user-execute bit set will be treated as a server-parsed html document. -
    full -
    As for on but also test the group-execute bit. If it +
    full +
    As for on 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: you would not want to use this, for example, when you -#include a CGI that produces different output on each hit +

    Note: you would not want to use this, for example, when you +#include a CGI that produces different output on each hit (or potentially depends on the hit). -

    -

    +

    +

    diff --git a/docs/manual/mod/mod_info.html b/docs/manual/mod/mod_info.html index 984a68b12c..d6728e7d03 100644 --- a/docs/manual/mod/mod_info.html +++ b/docs/manual/mod/mod_info.html @@ -1,8 +1,8 @@ - - -Apache module mod_info - + + +Apache module mod_info + -

    Module mod_info

    +

    Module mod_info

    -This module is contained in the mod_info.c file. It +This module is contained in the mod_info.c file. It provides a comprehensive overview of the server configuration including all installed modules and directives in the configuration files. This module is not compiled into the @@ -34,7 +34,7 @@ AddModule modules/standard/mod_info.o

    -To configure it, add the following to your access.conf file. +To configure it, add the following to your access.conf file. 

     <Location /server-info>
@@ -50,9 +50,9 @@ clause inside the
 location
-directive to limit access to your server configuration information.
    
+directive to limit access to your server configuration information.
    
 Once configured, the server information is obtained by accessing
-http://your.host.dom/server-info
    
+http://your.host.dom/server-info
    
 
    
  
   Note that the configuration files are read by the module at run-time,
diff --git a/docs/manual/mod/mod_isapi.html b/docs/manual/mod/mod_isapi.html
index e3d87e8c71..a8e3233932 100644
--- a/docs/manual/mod/mod_isapi.html
+++ b/docs/manual/mod/mod_isapi.html
@@ -14,59 +14,59 @@
 >
 
 
-
    Module mod_isapi
    
+
    Module mod_isapi
    
 
-
    This module is contained in the mod_isapi.c file, and is
+
    This module is contained in the mod_isapi.c file, and is
    compiled in by default. It provides support for ISAPI Extensions when
    running under Microsoft Windows. Any document with a handler of
-   isapi-isa will be processed by this module.
+   isapi-isa will be processed by this module.
 
 
    Purpose
    
 
-
    This module implements the ISAPI
-   Extension API. It allows Internet Server Applications (i.e., ISAPI
+
    This module implements the ISAPI
+   Extension API. It allows Internet Server Applications (i.e., ISAPI
    Extensions) to be used with Apache for Windows.
 
 
    Usage
    
 
-
    In the server configuration file, add a handler called
-   isapi-isa, and map it to files with a .DLL
-   extension. In other words:
    
-
    +
    In the server configuration file, add a handler called
+   isapi-isa, and map it to files with a .DLL
+   extension. In other words:
    
+
         AddHandler isapi-isa dll
-
    
-
    Now simply place the ISA DLLs into your document root, and they will
-   be loaded when their URLs are accessed.
    
+
    
+
    Now simply place the ISA DLLs into your document root, and they will
+   be loaded when their URLs are accessed.
    
 
-
    ISAPI Extensions are governed by the same restrictions as CGI
-   scripts. That is, Options ExecCGI must be active in the
-   directory that contains the ISA.
    
+
    ISAPI Extensions are governed by the same restrictions as CGI
+   scripts. That is, Options ExecCGI must be active in the
+   directory that contains the ISA.
    
 
 
    Notes
    
 
-
    Apache's ISAPI implementation conforms to all of the ISAPI 2.0
+
    Apache's ISAPI implementation conforms to all of the ISAPI 2.0
    specification, except for the "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 async I/O, a message will be place in the error log,
    to help with debugging.
 
-
    Some servers, like Microsoft IIS, load the ISA into the server, and
+
    Some servers, like Microsoft IIS, load the ISA into the server, and
    keep it loaded until memory usage is too high, and it is
    unloaded. Apache currently loads and unloads the ISA for each
    request. This is inefficient, but Apache's request model makes this
    method the only method that currently works. A future release may use
    a more effective loading method.
 
-
    Apache 1.3a1 currently limits POST and PUT input to 48k per
+
    Apache 1.3a1 currently limits POST and PUT input to 48k per
    request. This is to work around a problem with the ISAPI implementation
    that could result in a denial of service attack. It is expected that
    support for larger uploads will be added soon.
 
-
    Also, remember that while Apache supports ISAPI Extensions, it does
+
    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.
    
+   date, but no support is planned at this time.
    
 
 
 
diff --git a/docs/manual/mod/mod_log_agent.html b/docs/manual/mod/mod_log_agent.html
index 9e8fa50855..2a43155c25 100644
--- a/docs/manual/mod/mod_log_agent.html
+++ b/docs/manual/mod/mod_log_agent.html
@@ -13,47 +13,47 @@
  ALINK="#FF0000"
 >
 
-
    Module mod_log_agent
    
+
    Module mod_log_agent
    
 
-This module is contained in the mod_log_agent.c file, and is not
+This module is contained in the mod_log_agent.c file, and is not
 compiled in by default. It provides for logging of the client user agents.
 
 
-
-
    
+
+
    
 
 
 
    AgentLog
    
 
-Syntax: AgentLog file-pipe
    
-Default: AgentLog logs/agent_log
    
-Context: server config, virtual host
    
-Status: Extension
    
-Module: mod_log_agent
    
+Syntax: AgentLog file-pipe
    
+Default: AgentLog logs/agent_log
    
+Context: server config, virtual host
    
+Status: Extension
    
+Module: mod_log_agent
    
 
 The AgentLog directive sets the name of the file to which the server will
-log the UserAgent header of incoming requests. File-pipe is one
+log the UserAgent header of incoming requests. File-pipe is one
 of
-
    A filename
-
    A filename relative to the ServerRoot.
-
     `|' followed by a command
-
    A program to receive the agent log information on its standard input.
+
    A filename
+
    A filename relative to the ServerRoot.
+
     `|' followed by a command
+
    A program to receive the agent log information on its standard input.
 Note the a new program will not be started for a VirtualHost if it inherits
 the AgentLog from the main server.
-
    
-Security: if a program is used, then it will be
+
    
+Security: if a program is used, then it will be
 run under the user who started httpd. This will be root if the server
-was started by root; be sure that the program is secure.
    
+was started by root; be sure that the program is secure.
    
 
-Security: See the Security: 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.
    
 
-This directive is provided for compatibility with NCSA 1.4.
    
+This directive is provided for compatibility with NCSA 1.4.
    
 
 
 
diff --git a/docs/manual/mod/mod_log_config.html b/docs/manual/mod/mod_log_config.html
index c0a9369096..489148989f 100644
--- a/docs/manual/mod/mod_log_config.html
+++ b/docs/manual/mod/mod_log_config.html
@@ -13,9 +13,9 @@
  ALINK="#FF0000"
 >
 
-
    Module mod_log_config
    
+
    Module mod_log_config
    
 
-This module is contained in the mod_log_config.c file,
+This module is contained in the mod_log_config.c file,
 and is compiled in by default in Apache 1.2. mod_log_config replaces
 mod_log_common in Apache 1.2. Prior to version 1.2, mod_log_config was
 an optional module. It provides for logging of the requests made to
@@ -23,84 +23,84 @@ the server, using the Common Log Format or a user-specified format.
 
 
    Summary
    
 
-Three directives are provided by this module: TransferLog
-to create a log file, LogFormat to set a custom format,
-and CustomLog to define a log file and format in one go.
-The TransferLog and CustomLog directives can
+Three directives are provided by this module: TransferLog
+to create a log file, LogFormat to set a custom format,
+and CustomLog to define a log file and format in one go.
+The TransferLog and CustomLog directives can
 be used multiple times in each server to cause each request to be
 logged to multiple files.
 
    
 
 
    Compatibility notes
    
 
-
      
-
    • This module is based on mod_log_config distributed with
+
        
+
      • This module is based on mod_log_config distributed with
 previous Apache releases, now updated to handle multiple logs.
 There is now no need to re-configure Apache to use configuration log
 formats.
 
-
      • The module also implements the CookieLog directive,
-used to log user-tracking information created by mod_usertrack. The use of
-CookieLog is deprecated, and a CustomLog
+
      • The module also implements the CookieLog directive,
+used to log user-tracking information created by mod_usertrack. The use of
+CookieLog is deprecated, and a CustomLog
 should be defined to log user-tracking information instead.
 
-
      
+
    
 
 
    Log File Formats
    
 
-Unless told otherwise with LogFormat the log files created by
-TransferLog will be in standard "Common Log Format"
+Unless told otherwise with LogFormat the log files created by
+TransferLog will be in standard "Common Log Format"
 (CLF). The contents of each line in a CLF file are explained
 below. Alternatively, the log file can be customized (and if multiple
 log files are used, each can have a different format). Custom formats
-are set with LogFormat and CustomLog.
+are set with LogFormat and CustomLog.
 
 
    Common Log Format
    
 
 The Common Log Format (CLF) file contains a separate line for each
 request. A line is composed of several tokens separated by spaces:
 
-
    
+
    
 host ident authuser date request status bytes
-
    
+
    
 If a token does not have a value then it is represented by a hyphen (-).
 The meanings and values of these tokens are as follows:
-
    
-
    host
-
    The fully-qualified domain name of the client, or its IP number if the
+
    
+
    host
+
    The fully-qualified domain name of the client, or its IP number if the
 name is not available.
-
    ident
-
    If IdentityCheck is enabled and the
+
    ident
+
    If IdentityCheck is enabled and the
 client machine runs identd, then this is the identity information reported
 by the client.
-
    authuser
-
    If the request was for an password protected document, then this is
+
    authuser
+
    If the request was for an password protected document, then this is
 the userid used in the request.
-
    date
-
    The date and time of the request, in the following format:
-
     date = [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
    
-
    request
-
    The request line from the client, enclosed in double quotes
-(").
-
    status
-
    The three digit status code returned to the client.
-
    bytes
-
    The number of bytes in the object returned to the client, not including
+
    date
+
    The date and time of the request, in the following format:
+
     date = [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
    
+
    request
+
    The request line from the client, enclosed in double quotes
+(").
+
    status
+
    The three digit status code returned to the client.
+
    bytes
+
    The number of bytes in the object returned to the client, not including
 any headers.
-
    
+
    
 
 
    Custom Log Formats
    
 
-The format argument to the LogFormat and
-CustomLog is a string. This string is logged to the log
+The format argument to the LogFormat and
+CustomLog is a string. This string is logged to the log
 file for each request. It can contain literal characters copied into
 the log files, and `%' directives which are replaced in the log file
 by the values as follows:
@@ -129,7 +129,7 @@ by the values as follows:
 %...v:          The name of the server (i.e. which virtual host?)
    -The `...' can be nothing at all (e.g. "%h %u %r %s %b"), or it can +The `...' can be nothing at all (e.g. "%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). Note that there is no escaping performed on the strings from %r, %...i and @@ -144,18 +144,18 @@ 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. +requests which did not return some sort of normal status.

    -Note that the common log format is defined by the string "%h %l -%u %t \"%r\" %s %b", which can be used as the basis for +Note that the common log format is defined by the string "%h %l +%u %t \"%r\" %s %b", which can be used as the basis for extending for format if desired (e.g. to add extra fields at the end). -NCSA's extended/combined log format would be "%h %l %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-agent}i\"". +NCSA's extended/combined log format would be "%h %l %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-agent}i\"".

    Using Multiple Log Files

    -The TransferLog and CustomLog directives can +The TransferLog and CustomLog directives can be given more than once to log requests to multiple log files. Each request will be logged to all the log files defined by either of these directives. @@ -163,13 +163,13 @@ directives.

    Use with Virtual Hosts

    If a <VirtualHost> section does not contain any -TransferLog or CustomLog directives, the +TransferLog or CustomLog directives, the logs defined for the main server will be used. If it does contain one or more of these directives, requests serviced by this virtual host will only be logged in the log files defined within its definition, not in any of the main server's log files. See the examples below. -

    +

    Security Considerations

    @@ -177,36 +177,36 @@ 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. -

    +

    Directives

    - +

    CookieLog

    -Syntax: CookieLog filename
    -Context: server config, virtual host
    -Module: mod_cookies
    -Compatibility: Only available in Apache 1.2 and above

    +Syntax: CookieLog filename
    +Context: server config, virtual host
    +Module: mod_cookies
    +Compatibility: Only available in Apache 1.2 and above

    The 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. -

    +only for compatibility with mod_cookies, and is deprecated. +

    CustomLog

    -Syntax: CustomLog file-pipe - format-or-nickname
    +Syntax: CustomLog file-pipe + format-or-nickname
    Context: server config, virtual host
    Status: Base
    Compatibility: Nickname only available in Apache 1.3 @@ -226,7 +226,7 @@ server root.

    The format argument specifies a format for each line of the log file. The options available for the format are exactly the same as for -the argument of the LogFormat directive. If the format +the argument of the LogFormat directive. If the format includes any spaces (which it will do in almost all cases) it should be enclosed in double quotes.

    @@ -241,16 +241,16 @@ directive.

    LogFormat

    -Syntax: LogFormat format [nickname] -
    -Default: LogFormat "%h %l %u %t \"%r\" -%s %b"
    -Context: server config, virtual host
    -Status: Base
    +Syntax: LogFormat format [nickname] +
    +Default: LogFormat "%h %l %u %t \"%r\" +%s %b"
    +Context: server config, virtual host
    +Status: Base
    Compatibility: Nickname only available in Apache 1.3 or later
    -Module: mod_log_config +Module: mod_log_config

    This sets the format of the default logfile named by the -- that is, it only defines the nickname, it doesn't actually apply the format and make it the default.

    -
    +

    TransferLog

    -Syntax: TransferLog file-pipe
    -Default: none
    -Context: server config, virtual host
    -Status: Base
    -Module: mod_log_config

    +Syntax: TransferLog file-pipe
    +Default: none
    +Context: server config, virtual host
    +Status: Base
    +Module: mod_log_config

    The TransferLog directive adds a log file in the format defined by the most recent @@ -291,18 +291,18 @@ most recent >LogFormat directive, or Common Log Format if no other default format has been specified. -File-pipe is one +File-pipe is one of -

    A filename -
    A filename relative to the ServerRoot. -
    `|' followed by a command -
    A program to receive the agent log information on its standard input. +
    A filename +
    A filename relative to the ServerRoot. +
    `|' followed by a command +
    A program to receive the agent log information on its standard input. Note the a new program will not be started for a VirtualHost if it inherits the TransferLog from the main server. -
    -Security: if a program is used, then it will be +
    +Security: if a program is used, then it will be run under the user who started httpd. This will be root if the server -was started by root; be sure that the program is secure.

    +was started by root; be sure that the program is secure.

    diff --git a/docs/manual/mod/mod_log_referer.html b/docs/manual/mod/mod_log_referer.html index 8a5146491a..d98228f4e9 100644 --- a/docs/manual/mod/mod_log_referer.html +++ b/docs/manual/mod/mod_log_referer.html @@ -13,74 +13,74 @@ ALINK="#FF0000" > -

    Module mod_log_referer

    +

    Module mod_log_referer

    -This module is contained in the mod_log_referer.c file, and is not +This module is contained in the mod_log_referer.c file, and is not compiled in by default. It provides for logging of the documents which reference documents on the server.

    Log file format

    The log file contains a separate line for each refer. Each line has the format -
    uri -> document
    -where uri is the (%-escaped) URI for the document that references -the one requested by the client, and document is the (%-decoded) +
    uri -> document
    +where uri is the (%-escaped) URI for the document that references +the one requested by the client, and document is the (%-decoded) local URL to the document being referred to.

    Directives

    - -
    + +

    RefererIgnore

    -Syntax: RefererIgnore string string ...
    -Context: server config, virtual host
    -Status: Extension
    -Module: mod_log_referer

    +Syntax: RefererIgnore string string ...
    +Context: server config, virtual host
    +Status: Extension
    +Module: mod_log_referer

    The RefererIgnore directive adds to the list of strings to ignore in Referer headers. If any of the strings in the list is contained in the Referer header, then no referrer information will be logged for the request. Example: -

    RefererIgnore www.ncsa.uiuc.edu
    +
    RefererIgnore www.ncsa.uiuc.edu
    This avoids logging references from www.ncsa.uiuc.edu. -

    +

    RefererLog

    -Syntax: RefererLog file-pipe
    -Default: RefererLog logs/referer_log
    -Context: server config, virtual host
    -Status: Extension
    -Module: mod_log_referer

    +Syntax: RefererLog file-pipe
    +Default: RefererLog logs/referer_log
    +Context: server config, virtual host
    +Status: Extension
    +Module: mod_log_referer

    The RefererLog directive sets the name of the file to which the server will -log the Referer header of incoming requests. File-pipe is one +log the Referer header of incoming requests. File-pipe is one of -

    A filename -
    A filename relative to the ServerRoot. -
    `|' followed by a command -
    A program to receive the referrer log information on its standard input. +
    A filename +
    A filename relative to the ServerRoot. +
    `|' followed by a command +
    A program to receive the referrer log information on its standard input. Note the a new program will not be started for a VirtualHost if it inherits the RefererLog from the main server. -
    -Security: if a program is used, then it will be +
    +Security: if a program is used, then it will be run under the user who started httpd. This will be root if the server -was started by root; be sure that the program is secure.

    +was started by root; be sure that the program is secure.

    -Security: See the Security: 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.

    -This directive is provided for compatibility with NCSA 1.4.

    +This directive is provided for compatibility with NCSA 1.4.

    diff --git a/docs/manual/mod/mod_mime.html b/docs/manual/mod/mod_mime.html index cc3fe664d2..e71bd844e3 100644 --- a/docs/manual/mod/mod_mime.html +++ b/docs/manual/mod/mod_mime.html @@ -13,9 +13,9 @@ ALINK="#FF0000" > -

    Module mod_mime

    +

    Module mod_mime

    -This module is contained in the mod_mime.c file, and is +This module is contained in the mod_mime.c file, and is compiled in by default. It provides for determining the types of files from the filename. @@ -55,190 +55,190 @@ extensions to the left of the unknown extension. So, for example, if the extensions fr and html are mapped to the appropriate language and type but extension xxx is not assigned to anything, then the file welcome.fr.xxx.html will be associated with content-type -text/html but no language. +text/html but no language.

    Note that changing the type or encoding of a file does not change the -value of the Last-Modified header. Thus, previously cached +value of the Last-Modified header. Thus, previously cached copies may still be used by a client or proxy, with the previous headers.

    Please note that changing a file's type or encoding does not change -the value of the Last-Modified header. Previously cached +the value of the Last-Modified header. Previously cached copies may still be used by a client or proxy.

    Directives

    - -
    + +

    AddEncoding

    -Syntax: AddEncoding mime-enc extension extension...
    -Context: server config, virtual host, directory, .htaccess
    -Override: FileInfo
    -Status: Base
    -Module: mod_mime

    +Syntax: AddEncoding mime-enc extension extension...
    +Context: server config, virtual host, directory, .htaccess
    +Override: FileInfo
    +Status: Base
    +Module: mod_mime

    The AddEncoding directive adds to the list of filename extensions which -filenames may end in for the specified encoding type. Mime-enc -is the mime encoding to use for documents ending in extension. +filenames may end in for the specified encoding type. Mime-enc +is the mime encoding to use for documents ending in extension. Example: -

    -AddEncoding x-gzip gz
    +
    +AddEncoding x-gzip gz
    AddEncoding x-compress Z -
    +
    This will cause files ending in .gz to be marked as encoded using the x-gzip -encoding, and .Z files to be marked as encoded with x-compress.

    - -

    AddHandler

    - -Syntax: AddHandler handler-name extension extension...
    -Context: server config, virtual host, directory, .htaccess
    -Status: Base
    -Module: mod_mime
    -Compatibility: AddHandler is only available in Apache -1.1 and later

    - -

    AddHandler maps the filename extensions extension to the -handler -handler-name. For example, to activate CGI scripts -with the file extension ".cgi", you might use: -

    +encoding, and .Z files to be marked as encoded with x-compress.
    
+
+
    AddHandler
    
+
+Syntax: AddHandler handler-name extension extension...
    
+Context: server config, virtual host, directory, .htaccess
    
+Status: Base
    
+Module: mod_mime
    
+Compatibility: AddHandler is only available in Apache
+1.1 and later
    
+
+
    AddHandler maps the filename extensions extension to the
+handler
+handler-name. For example, to activate CGI scripts
+with the file extension ".cgi", you might use:
+
         AddHandler cgi-script cgi
-
    
+
    -

    Once that has been put into your srm.conf or httpd.conf file, any -file ending with ".cgi" will be treated as a CGI -program.

    +

    Once that has been put into your srm.conf or httpd.conf file, any +file ending with ".cgi" will be treated as a CGI +program.

    AddLanguage

    -Syntax: AddLanguage mime-lang extension extension...
    -Context: server config, virtual host, directory, .htaccess
    -Override: FileInfo
    -Status: Base
    -Module: mod_mime

    +Syntax: AddLanguage mime-lang extension extension...
    +Context: server config, virtual host, directory, .htaccess
    +Override: FileInfo
    +Status: Base
    +Module: mod_mime

    The AddLanguage directive adds to the list of filename extensions which -filenames may end in for the specified content language. Mime-lang -is the mime language of files with names ending extension, +filenames may end in for the specified content language. Mime-lang +is the mime language of files with names ending extension, after any content encoding extensions have been removed. Example: -

    -AddEncoding x-compress Z
    -AddLanguage en .en
    -AddLanguage fr .fr
    -
    +
    +AddEncoding x-compress Z
    +AddLanguage en .en
    +AddLanguage fr .fr
    +
    -Then the document xxxx.en.Z will be treated as being a compressed +Then the document xxxx.en.Z will be treated as being a compressed English document. 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.

    +from several documents based on the client's language preference.

    AddType

    -Syntax: AddType mime-type extension extension...
    -Context: server config, virtual host, directory, .htaccess
    -Override: FileInfo
    -Status: Base
    -Module: mod_mime

    +Syntax: AddType mime-type extension extension...
    +Context: server config, virtual host, directory, .htaccess
    +Override: FileInfo
    +Status: Base
    +Module: mod_mime

    The AddType directive adds to the list of filename extensions which -filenames may end in for the specified content type. Mime-enc -is the mime type to use for documents ending in extension. +filenames may end in for the specified content type. Mime-enc +is the mime type to use for documents ending in extension. after content-encoding and language extensions have been removed. Example: -

    +
    AddType image/gif GIF -
    +
    It is recommended that new mime types be added using the AddType directive -rather than changing the TypesConfig file.

    +rather than changing the TypesConfig file.

    Note that, unlike the NCSA httpd, this directive cannot be used to set the -type of particular files.

    +type of particular files.

    -

    ForceType

    +

    ForceType

    -Syntax: ForceType media type
    -Context: directory, .htaccess
    -Status: Base
    -Module: mod_mime
    -Compatibility: ForceType is only available in Apache -1.1 and later.

    +Syntax: ForceType media type
    +Context: directory, .htaccess
    +Status: Base
    +Module: mod_mime
    +Compatibility: ForceType is only available in Apache +1.1 and later.

    -

    When placed into an .htaccess file or a -<Directory> or <Location> section, +

    When placed into an .htaccess file or a +<Directory> or <Location> section, this directive forces all matching files to be served -as the content type given by media type. For example, if you +as the content type given by media 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
-
    
-
    Note that this will override any filename extensions that might
-media type.
    
+
    +

    Note that this will override any filename extensions that might +media type.

    -

    SetHandler

    +

    SetHandler

    -Syntax: SetHandler handler-name
    -Context: directory, .htaccess
    -Status: Base
    -Module: mod_mime
    -Compatibility: SetHandler is only available in Apache -1.1 and later.

    +Syntax: SetHandler handler-name
    +Context: directory, .htaccess
    +Status: Base
    +Module: mod_mime
    +Compatibility: SetHandler is only available in Apache +1.1 and later.

    -

    When placed into an .htaccess file or a -<Directory> or <Location> section, +

    When placed into an .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 +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: -

    +.htaccess file in that directory:
+
         SetHandler imap-file
-
    
+
    -

    Another example: if you wanted to have the server display a status -report whenever a URL of http://servername/status was +

    Another example: if you wanted to have the server display a status +report whenever a URL of http://servername/status was called, you might put the following into access.conf: -

    +
         <Location /status>
     SetHandler server-status
     </Location>
-
    
+

    TypesConfig

    -Syntax: TypesConfig filename
    -Default: TypesConfig conf/mime.types
    -Context: server config
    -Status: Base
    -Module: mod_mime

    +Syntax: TypesConfig filename
    +Default: TypesConfig conf/mime.types
    +Context: server config
    +Status: Base
    +Module: mod_mime

    The TypesConfig directive sets the location of the mime types configuration -file. Filename is relative to the +file. Filename is relative to the ServerRoot. This file sets the default list of mappings from filename extensions to content types; changing this file is not recommended. Use the AddType directive instead. The file contains lines in the format of the arguments to an AddType command: -

    mime-type extension extension ...
    +
    mime-type extension extension ...
    The extensions are lower-cased. Blank lines, and lines beginning with a hash -character (`#') are ignored.

    +character (`#') are ignored.

    diff --git a/docs/manual/mod/mod_mime_magic.html b/docs/manual/mod/mod_mime_magic.html index 22205b05e1..af00aaa82a 100644 --- a/docs/manual/mod/mod_mime_magic.html +++ b/docs/manual/mod/mod_mime_magic.html @@ -15,85 +15,85 @@ [APACHE DOCUMENTATION] -

    Module mod_mime_magic

    +

    Module mod_mime_magic

    This module is contained in the mod_mime_magic.c file, and is an optional extension to the Apache HTTPD server. It can be used to determine the MIME type of a file by looking at a few bytes of its contents, the same way the Unix file(1) command works. To use mod_mime_magic you have to enable the following line in the - server build Configuration file: + server build Configuration file: - 
    +  
           AddModule modules/standard/mod_mime_magic.o
-  
    
+
    - This should be listed before mod_mime in the build - Configuration file so that it will be used after mod_mime. + This should be listed before mod_mime in the build + Configuration file so that it will be used after mod_mime. mod_mime_magic is intended as a "second line of defense" for cases mod_mime cannot resolve.

    Summary

    - This module is derived from a free version of the file(1) + This module is derived from a free version of the file(1) command for Unix, which uses "magic numbers" and other hints from a file's contents to figure out what the contents are. In the case of this module, it tries to figure out the MIME type of the file. -

    +

    This module active only if the magic file is specified by the - MimeMagicFile directive. -

    + MimeMagicFile directive. +

    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 "#". The remaining lines are parsed for the following columns: - - - + + + - - - - - + + + + - - - - - - - - - - -
    ColumnDescription
    ColumnDescription
    1byte number to begin checking from -
    - ">" indicates a dependency upon the previous non-">" line
    2type of data to match + 1byte number to begin checking from +
    + ">" indicates a dependency upon the previous non-">" line
    2type of data to match - - - - - - - - - - - -
    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
    -
    3contents of data to match
    4MIME type if matched
    5MIME encoding if matched (optional)
    + 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) + + -

    +

    For example, the following magic file lines would recognize some audio formats. -

    +
     # Sun/NeXT audio data
 0       string          .snd
 >12     belong          1               audio/basic
@@ -104,13 +104,13 @@
 >12     belong          6               audio/basic
 >12     belong          7               audio/basic
 >12     belong          23              audio/x-adpcm
-
    
+
    Or these would recognize the difference between "*.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
@@ -124,23 +124,23 @@
 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
-
    
+
    An optional MIME encoding can be included as a fifth column. For example, this can recognize gzipped files and set the encoding for them. -
    +
     # gzip (GNU zip, not to be confused with [Info-ZIP/PKWARE] zip archiver)
 0       string          \037\213        application/octet-stream        x-gzip
-
    
+

    Performance Issues

    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 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 @@ -152,14 +152,14 @@ ...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. -

    +

    When compiling an Apache server, this module should be at or near the top of the list of modules in the Configuration file. The modules are listed in increasing priority so that will mean this one is used only as a last resort, just like it was designed to.

    Directives

    -

    +

    • MimeMagicFile
      • @@ -170,7 +170,7 @@ MimeMagicFile

      - Syntax: MimeMagicFile magic-file-name + Syntax: MimeMagicFile magic-file-name
      Default: none
      @@ -179,24 +179,24 @@ Status: Extension
      Module: mod_mime_magic -

      +

      - The MimeMagicFile directive can be used to enable this module, - the default file is distributed at conf/magic. + The 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. -

      +

      -

      Notes

      +

      Notes

      The following notes apply to the mod_mime_magic module and are included here for compliance with contributors' copyright restrictions that require their acknowledgment. -
      +
       /*
  * mod_mime_magic: MIME type lookup via file magic numbers
  * Copyright (c) 1996-1997 Cisco Systems, Inc.
@@ -254,7 +254,7 @@
  * - Command-line flags have been removed since they will never be used here.
  *
  */
-
      
+
      diff --git a/docs/manual/mod/mod_negotiation.html b/docs/manual/mod/mod_negotiation.html index c69777f9c9..c1ba2b0b17 100644 --- a/docs/manual/mod/mod_negotiation.html +++ b/docs/manual/mod/mod_negotiation.html @@ -13,9 +13,9 @@ ALINK="#FF0000" > -

      Module mod_negotiation

      +

      Module mod_negotiation

      -This module is contained in the mod_negotiation.c file, +This module is contained in the mod_negotiation.c file, and is compiled in by default. It provides for content negotiation. @@ -24,13 +24,13 @@ 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 (a file with the handler type-map) +
          +
        • A type map (a file with the handler type-map) which explicitly lists the files containing the variants. -
        • A MultiViews search (enabled by the MultiViews +
        • A MultiViews search (enabled by the MultiViews Option, where the server does an implicit filename pattern match, and choose from amongst the results. -
        +

      Type maps

      A type map has the same format as RFC822 mail headers. It contains document @@ -44,70 +44,70 @@ between the header name and value, and between the tokens of value. The headers allowed are: -
      -
      Content-Encoding: -
      The encoding of the file. Currently only two encodings are recognized -by http; x-compress for compressed files, and x-gzip +
      +
      Content-Encoding: +
      The encoding of the file. Currently only two encodings are recognized +by http; x-compress for compressed files, and x-gzip for gzipped files. -
      Content-Language: -
      The language of the variant, as an Internet standard language code, such -as en. -
      Content-Length: -
      The length of the file, in bytes. If this header is not present, then +
      Content-Language: +
      The language of the variant, as an Internet standard language code, such +as en. +
      Content-Length: +
      The length of the file, in bytes. If this header is not present, then the actual length of the file is used. -
      Content-Type: -
      The MIME media type of the document, with optional parameters. +
      Content-Type: +
      The MIME media type of the document, with optional parameters. parameters are separated from the media type and from one another by semi-colons. Parameter syntax is name=value; allowed parameters are: -
      -
      level -
      the value is an integer, which specifies the version of the media type. -For text/html this defaults to 2, otherwise 0. -
      qs -
      the value is a floating-point number with value between 0. and 1. +
      +
      level +
      the value is an integer, which specifies the version of the media type. +For text/html this defaults to 2, otherwise 0. +
      qs +
      the value is a floating-point number with value between 0. and 1. It indications the 'quality' of this variant. -
      +
      Example: -
      Content-Type: image/jpeg; qs=0.8
      -
      URI: -
      The path to the file containing this variant, relative to the map file. -
      +
      Content-Type: image/jpeg; qs=0.8
      +
      URI: +
      The path to the file containing this variant, relative to the map file. +

      MultiViews

      A MultiViews search is enabled by the MultiViews Option. -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 +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.

      +requirements, and returns that document.

      Directives

      - -
      + +

      CacheNegotiatedDocs

      -Syntax: CacheNegotiatedDocs
      -Context: server config
      -Status: Base
      -Module: mod_negotiation
      -Compatibility: CacheNegotiatedDocs is only available -in Apache 1.1 and later.

      - -

      If set, this directive allows content-negotiated documents to be +Syntax: CacheNegotiatedDocs
      +Context: server config
      +Status: Base
      +Module: mod_negotiation
      +Compatibility: CacheNegotiatedDocs is only available +in Apache 1.1 and later.

      + +

      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 @@ -118,22 +118,22 @@ HTTP/1.1 requests.

      LanguagePriority

      -Syntax: LanguagePriority mime-lang mime-lang...
      -Context: server config, virtual host, directory, .htaccess
      -Override: FileInfo
      -Status: Base
      -Module: mod_negotiation

      +Syntax: LanguagePriority mime-lang mime-lang...
      +Context: server config, virtual host, directory, .htaccess
      +Override: FileInfo
      +Status: Base
      +Module: mod_negotiation

      The 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 +MultiViews request. The list of mime-lang are in order of decreasing preference. Example: -

      LanguagePriority en fr de
      +
      LanguagePriority en fr de
      -For a request for 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.

      +For a request for 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.

      diff --git a/docs/manual/mod/mod_proxy.html b/docs/manual/mod/mod_proxy.html index 43e7dff8e0..b571bb3a91 100644 --- a/docs/manual/mod/mod_proxy.html +++ b/docs/manual/mod/mod_proxy.html @@ -13,77 +13,77 @@ ALINK="#FF0000" > -

      Apache module mod_proxy

      +

      Apache module mod_proxy

      -This module is contained in the mod_proxy.c file for Apache 1.1.x, -or the modules/proxy subdirectory for Apache 1.2, and +This module is contained in the mod_proxy.c file for Apache 1.1.x, +or the modules/proxy subdirectory for Apache 1.2, and is not compiled in by default. It provides for an HTTP 1.0 caching proxy server. It is only available in Apache 1.1 and later. Common configuration -questions are addressed after the directive -descriptions. +questions are addressed after the directive +descriptions.

      Note:

      -

      This module was experimental in Apache 1.1.x. As of Apache 1.2, mod_proxy -stability is greatly improved.

      +

      This module was experimental in Apache 1.1.x. As of Apache 1.2, mod_proxy +stability is greatly improved.

      Summary

      This module implements a proxy/cache for Apache. It implements proxying capability for -FTP, -CONNECT (for SSL), -HTTP/0.9, and -HTTP/1.0. +FTP, +CONNECT (for SSL), +HTTP/0.9, and +HTTP/1.0. The module can be configured to connect to other proxy modules for these and other protocols.

      Directives

      - - -
      + + +

      ProxyRequests

       -Syntax: ProxyRequests on/off
      -Default: ProxyRequests Off
      -Context: server config, virtual host
      -Override: Not applicable
      -Status: Base
      -Module: mod_proxy
      -Compatibility: ProxyRequests is only available in -Apache 1.1 and later.

      +Syntax: ProxyRequests on/off
      +Default: ProxyRequests Off
      +Context: server config, virtual host
      +Override: Not applicable
      +Status: Base
      +Module: mod_proxy
      +Compatibility: ProxyRequests is only available in +Apache 1.1 and later.

      This allows or prevents Apache from functioning as a proxy -server. Setting ProxyRequests to 'off' does not disable use of the ProxyPass directive. +server. Setting ProxyRequests to 'off' does not disable use of the ProxyPass directive.

      ProxyRemote

       -Syntax: ProxyRemote <match> <remote-server>
      -Default: None
      -Context: server config, virtual host
      -Override: Not applicable
      -Status: Base
      -Module: mod_proxy
      -Compatibility: ProxyRemote is only available in -Apache 1.1 and later.

      +Syntax: ProxyRemote <match> <remote-server>
      +Default: None
      +Context: server config, virtual host
      +Override: Not applicable
      +Status: Base
      +Module: mod_proxy
      +Compatibility: ProxyRemote is only available in +Apache 1.1 and later.

      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 @@ -91,19 +91,19 @@ for which the remote server should be used, or '*' to indicate the server should be contacted for all requests. <remote-server> is a partial URL for the remote server. Syntax: -

      +
         <remote-server> = <protocol>://<hostname>[:port]
-
      
+
      <protocol> is the protocol that should be used to communicate with the remote server; only "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
-
      
+
      In the last example, the proxy will forward FTP requests, encapsulated as yet another HTTP proxy request, to another proxy which can handle @@ -112,14 +112,14 @@ them.

      ProxyPass

       -Syntax: ProxyPass <path> <url>
      -Default: None
      -Context: server config, virtual host
      -Override: Not applicable
      -Status: Base
      -Module: mod_proxy
      -Compatibility: ProxyPass is only available in -Apache 1.1 and later.

      +Syntax: ProxyPass <path> <url>
      +Default: None
      +Context: server config, virtual host
      +Override: Not applicable
      +Status: Base
      +Module: mod_proxy
      +Compatibility: ProxyPass is only available in +Apache 1.1 and later.

      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, @@ -127,9 +127,9 @@ 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.

      Suppose the local server has address http://wibble.org/; then -

      +
          ProxyPass /mirror/foo http://foo.com
-
      
+
      will cause a local request for the <http://wibble.org/mirror/foo/bar> to be internally converted into a proxy request to @@ -138,52 +138,52 @@ internally converted into a proxy request to

      ProxyBlock

       -Syntax: ProxyBlock <word/host/domain list>
      -Default: None
      -Context: server config, virtual host
      -Override: Not applicable
      -Status: Base
      -Module: mod_proxy
      -Compatibility: ProxyBlock is only available in -Apache 1.2 and later.

      +Syntax: ProxyBlock <word/host/domain list>
      +Default: None
      +Context: server config, virtual host
      +Override: Not applicable
      +Status: Base
      +Module: mod_proxy
      +Compatibility: ProxyBlock is only available in +Apache 1.2 and later.

      The ProxyBlock directive specifies a list of words, hosts and/or domains, separated by spaces. HTTP, HTTPS, and FTP document requests to matched words, -hosts or domains are blocked by the proxy server. The proxy module +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. Example: -

      +
         ProxyBlock joes_garage.com some_host.co.uk rocky.wotsamattau.edu
-
      
+
      -'rocky.wotsamattau.edu' would also be matched if referenced by IP address.

      +'rocky.wotsamattau.edu' would also be matched if referenced by IP address.

      -Note that 'wotsamattau' would also be sufficient to match 'wotsamattau.edu'.

      +Note that 'wotsamattau' would also be sufficient to match 'wotsamattau.edu'.

      Note also that -

      +
       ProxyBlock *
-
      
+
      blocks connections to all sites.

      NoProxy

       -Syntax: NoProxy { <Domain> - | <SubNet> - | <IpAddr> - | <Hostname> - }
      -Default: None
      -Context: server config, virtual host
      -Override: Not applicable
      -Status: Base
      -Module: mod_proxy
      -Compatibility: NoProxy is only available in -Apache 1.3 and later.

      +Syntax: NoProxy { <Domain> + | <SubNet> + | <IpAddr> + | <Hostname> + }
      +Default: None
      +Context: server config, virtual host
      +Override: Not applicable
      +Status: Base
      +Module: mod_proxy
      +Compatibility: NoProxy is only available in +Apache 1.3 and later.

      This directive is only useful for Apache proxy servers within intranets. The NoProxy directive specifies a list of subnets, IP addresses, hosts @@ -193,10 +193,10 @@ the configured ProxyRemote proxy server(s).

      Example: -

      +
         ProxyRemote  *  http://firewall.mycompany.com:81
   NoProxy         .mycompany.com 192.168.112.0/21 
-
      
+
      The arguments to the NoProxy directive are one of the following type list:
      @@ -254,8 +254,8 @@ The arguments to the NoProxy directive are one of the following type list: Example: 192.168.123.7
      Note: An IPAddr does not need to be resolved by the DNS system, so it can result in more effective apache performance. -

      See Also: - DNS Issues

      +

      See Also: + DNS Issues

      @@ -281,47 +281,47 @@ The arguments to the NoProxy directive are one of the following type list: of the DNS tree, therefore two hosts WWW.MyDomain.com and www.mydomain.com. (note the trailing period) are considered equal.
      -

      See Also: -DNS Issues

      +

      See Also: +DNS Issues

      ProxyDomain

       -Syntax: ProxyDomain <Domain>
      -Default: None
      -Context: server config, virtual host
      -Override: Not applicable
      -Status: Base
      -Module: mod_proxy
      -Compatibility: ProxyDomain is only available in -Apache 1.3 and later.

      +Syntax: ProxyDomain <Domain>
      +Default: None
      +Context: server config, virtual host
      +Override: Not applicable
      +Status: Base
      +Module: mod_proxy
      +Compatibility: ProxyDomain is only available in +Apache 1.3 and later.

      This directive is only useful for Apache proxy servers within intranets. The 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. +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
-
      
+

      CacheRoot

       -Syntax: CacheRoot <directory>
      -Default: None
      -Context: server config, virtual host
      -Override: Not applicable
      -Status: Base
      -Module: mod_proxy
      -Compatibility: CacheRoot is only available in -Apache 1.1 and later.

      +Syntax: CacheRoot <directory>
      +Default: None
      +Context: server config, virtual host
      +Override: Not applicable
      +Status: Base
      +Module: mod_proxy
      +Compatibility: CacheRoot is only available in +Apache 1.1 and later.

      Sets the name of the directory to contain cache files; this must be writable @@ -330,14 +330,14 @@ by the httpd server.

      CacheSize

       -Syntax: CacheSize <size>
      -Default: CacheSize 5
      -Context: server config, virtual host
      -Override: Not applicable
      -Status: Base
      -Module: mod_proxy
      -Compatibility: CacheSize is only available in -Apache 1.1 and later.

      +Syntax: CacheSize <size>
      +Default: CacheSize 5
      +Context: server config, virtual host
      +Override: Not applicable
      +Status: Base
      +Module: mod_proxy
      +Compatibility: CacheSize is only available in +Apache 1.1 and later.

      Sets the desired space usage of the cache, in KB (1024-byte units). Although usage may grow above this setting, the garbage collection will delete files @@ -346,14 +346,14 @@ until the usage is at or below this setting.

      CacheGcInterval

       -Syntax: CacheGcInterval <time>
      -Default: None
      -Context: server config, virtual host
      -Override: Not applicable
      -Status: Base
      -Module: mod_proxy
      -Compatibility: CacheGcinterval is only available in -Apache 1.1 and later.

      +Syntax: CacheGcInterval <time>
      +Default: None
      +Context: server config, virtual host
      +Override: Not applicable
      +Status: Base
      +Module: mod_proxy
      +Compatibility: CacheGcinterval is only available in +Apache 1.1 and later.

      Check the cache every <time> hours, and delete files if the space usage is greater than that set by CacheSize. @@ -361,14 +361,14 @@ usage is greater than that set by CacheSize.

      CacheMaxExpire

       -Syntax: CacheMaxExpire <time>
      -Default: CacheMaxExpire 24
      -Context: server config, virtual host
      -Override: Not applicable
      -Status: Base
      -Module: mod_proxy
      -Compatibility: CacheMaxExpire is only available in -Apache 1.1 and later.

      +Syntax: CacheMaxExpire <time>
      +Default: CacheMaxExpire 24
      +Context: server config, virtual host
      +Override: Not applicable
      +Status: Base
      +Module: mod_proxy
      +Compatibility: CacheMaxExpire is only available in +Apache 1.1 and later.

      Cachable HTTP documents will be retained for at most <time> hours without checking the origin server. Thus documents can be at most <time> @@ -378,37 +378,37 @@ was supplied with the document.

      CacheLastModifiedFactor

       -Syntax: CacheLastModifiedFactor <factor>
      -Default: CacheLastModifiedFactor 0.1
      -Context: server config, virtual host
      -Override: Not applicable
      -Status: Base
      -Module: mod_proxy
      -Compatibility: CacheLastModifiedFactor is only available in -Apache 1.1 and later.

      +Syntax: CacheLastModifiedFactor <factor>
      +Default: CacheLastModifiedFactor 0.1
      +Context: server config, virtual host
      +Override: Not applicable
      +Status: Base
      +Module: mod_proxy
      +Compatibility: CacheLastModifiedFactor is only available in +Apache 1.1 and later.

      If the origin HTTP server did not supply an expiry date for the document, then estimate one using the formula -

      +
         expiry-period = time-since-last-modification * <factor>
-
      
+
      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 expiry-period would be longer than that set by CacheMaxExpire, +

      If the expiry-period would be longer than that set by CacheMaxExpire, then the latter takes precedence.

      CacheDirLevels

       -Syntax: CacheDirLevels <levels>
      -Default: CacheDirLevels 3
      -Context: server config, virtual host
      -Override: Not applicable
      -Status: Base
      -Module: mod_proxy
      -Compatibility: CacheDirLevels is only available in -Apache 1.1 and later.

      +Syntax: CacheDirLevels <levels>
      +Default: CacheDirLevels 3
      +Context: server config, virtual host
      +Override: Not applicable
      +Status: Base
      +Module: mod_proxy
      +Compatibility: CacheDirLevels is only available in +Apache 1.1 and later.

      CacheDirLevels sets the number of levels of subdirectories in the cache. Cached data will be saved this many directory levels below CacheRoot. @@ -416,89 +416,89 @@ Cached data will be saved this many directory levels below CacheRoot.

      CacheDirLength

       -Syntax: CacheDirLength <length>
      -Default: CacheDirLength 1
      -Context: server config, virtual host
      -Override: Not applicable
      -Status: Base
      -Module: mod_proxy
      -Compatibility: CacheDirLength is only available in -Apache 1.1 and later.

      +Syntax: CacheDirLength <length>
      +Default: CacheDirLength 1
      +Context: server config, virtual host
      +Override: Not applicable
      +Status: Base
      +Module: mod_proxy
      +Compatibility: CacheDirLength is only available in +Apache 1.1 and later.

      CacheDirLength sets the number of characters in proxy cache subdirectory names.

      CacheDefaultExpire

       -Syntax: CacheDefaultExpire <time>
      -Default: CacheDefaultExpire 1
      -Context: server config, virtual host
      -Override: Not applicable
      -Status: Base
      -Module: mod_proxy
      -Compatibility: CacheDefaultExpire is only available in -Apache 1.1 and later.

      +Syntax: CacheDefaultExpire <time>
      +Default: CacheDefaultExpire 1
      +Context: server config, virtual host
      +Override: Not applicable
      +Status: Base
      +Module: mod_proxy
      +Compatibility: CacheDefaultExpire is only available in +Apache 1.1 and later.

      If the document is fetched via a protocol that does not support expiry times, then use <time> hours as the expiry time. -CacheMaxExpire does not +CacheMaxExpire does not override this setting.

      NoCache

       -Syntax: NoCache <word/host/domain list>
      -Default: None
      -Context: server config, virtual host
      -Override: Not applicable
      -Status: Base
      -Module: mod_proxy
      -Compatibility: NoCache is only available in -Apache 1.1 and later.

      +Syntax: NoCache <word/host/domain list>
      +Default: None
      +Context: server config, virtual host
      +Override: Not applicable
      +Status: Base
      +Module: mod_proxy
      +Compatibility: NoCache is only available in +Apache 1.1 and later.

      The NoCache directive specifies a list of words, hosts and/or domains, separated by spaces. HTTP and non-passworded FTP documents from matched words, hosts or -domains are not cached by the proxy server. The proxy module will +domains are not cached 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. Example: -

      +
         NoCache joes_garage.com some_host.co.uk bullwinkle.wotsamattau.edu
-
      
+
      'bullwinkle.wotsamattau.edu' would also be matched if referenced by IP -address.

      +address.

      -Note that 'wotsamattau' would also be sufficient to match 'wotsamattau.edu'.

      +Note that 'wotsamattau' would also be sufficient to match 'wotsamattau.edu'.

      Note also that -

      +
       NoCache *
-
      
+
      -disables caching completely.

      +disables caching completely.

      -

      +
      -

      Common configuration topics

       +

      Common configuration topics

       - + -

      Controlling access to your proxy

      +

      Controlling access to your proxy

      You can control who can access your proxy via the normal <Directory> -control block using the following example:

      +control block using the following example:

      -

      +
       <Directory proxy:*>
 <Limit GET PUT POST DELETE CONNECT OPTIONS>
 order deny,allow
@@ -506,68 +506,68 @@ deny from [machines you'd like *not* to allow by IP address or name]
 allow from [machines you'd like to allow by IP address or name]
 </Limit>
 </Directory>
-
      
+

      A <Files> block will also work, and is the only method known to work -for all possible URLs in Apache versions earlier than 1.2b10.

      +for all possible URLs in Apache versions earlier than 1.2b10.

      -

      Using Netscape hostname shortcuts

      +

      Using Netscape hostname shortcuts

      There is an optional patch to the proxy module to allow Netscape-like hostname shortcuts to be used. It's available - -here.

      + +here.

      -

      Why doesn't file type xxx download via FTP?

      +

      Why doesn't file type xxx download via FTP?

      You probably don't have that particular file type defined as application/octet-stream in your proxy's mime.types configuration -file. A useful line can be

      +file. A useful line can be

      -

      +
       application/octet-stream        bin dms lha lzh exe class tgz taz
-
      
+
      -

      How can I force an FTP ASCII download of File xxx?

      +

      How can I force an FTP ASCII download of File xxx?

      In the rare situation where you must download a specific file using the FTP 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.

      +suffixing the request with ;type=a to force an ASCII transfer.

      -

      Why does Apache start more slowly when using the - proxy module?

      +

      Why does Apache start more slowly when using the + proxy module?

      -If you're using the ProxyBlock or NoCache +If you're using the ProxyBlock or NoCache directives, 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.

      +depending on the speed with which the hostname lookups occur.

      -

      Can I use the Apache proxy module with my SOCKS proxy?

      +

      Can I use the Apache proxy module with my SOCKS proxy?

      -Yes. Just build Apache with the rule SOCKS4=yes in your +Yes. Just build Apache with the rule SOCKS4=yes in your Configuration file, and follow the instructions there. SOCKS5 -capability can be added in a similar way (there's no SOCKS5 -rule yet), so use the EXTRA_LDFLAGS definition, or build Apache +capability can be added in a similar way (there's no SOCKS5 +rule yet), so use the EXTRA_LDFLAGS definition, or build Apache normally and run it with the runsocks wrapper provided with SOCKS5, -if your OS supports dynamically linked libraries.

      +if your OS supports dynamically linked libraries.

      Some users have reported problems when using SOCKS version 4.2 on Solaris. -The problem was solved by upgrading to SOCKS 4.3.

      +The problem was solved by upgrading to SOCKS 4.3.

      Remember that you'll also have to grant access to your Apache proxy machine by permitting connections on the appropriate ports in your SOCKS daemon's -configuration.

      +configuration.

      -

      What other functions are useful for an intranet proxy server?

      +

      What other functions are useful for an intranet proxy server?

      -

      An Apache proxy server situated in an intranet needs to forward external +

      An Apache proxy server situated in an intranet needs to forward external requests through the company's firewall. 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.

      +which hosts belong to the intranet and should be accessed directly.

      -

      Users within an intranet tend to omit the local domain name from their +

      Users within an intranet tend to omit the local domain name from their WWW requests, thus requesting "http://somehost/" instead of "http://somehost.my.dom.ain/". Some commercial proxy servers let them get away with this and simply serve the request, implying a configured @@ -575,7 +575,7 @@ 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.

      +since the user's bookmark files will then contain fully qualified hosts.

      diff --git a/docs/manual/mod/mod_rewrite.html b/docs/manual/mod/mod_rewrite.html index 366bf7afa4..be9cb2215e 100644 --- a/docs/manual/mod/mod_rewrite.html +++ b/docs/manual/mod/mod_rewrite.html @@ -2,10 +2,10 @@ - - -Apache module mod_rewrite - + + +Apache module mod_rewrite + -

      Module mod_rewrite

      +

      Module mod_rewrite

      -This module is contained in the mod_rewrite.c file, with Apache +This module is contained in the mod_rewrite.c file, with Apache 1.2 and later. It provides a rule-based rewriting engine to rewrite requested -URLs on the fly. mod_rewrite is not compiled into the server by -default. To use mod_rewrite you have to enable the following line +URLs on the fly. mod_rewrite is not compiled into the server by +default. To use mod_rewrite you have to enable the following line in the server build Configuration file: -
      +
           AddModule  modules/standard/mod_rewrite.o
-
      
+

      Summary

      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 additional rule conditions (which can operate on a lot of variables, including HTTP headers) for granular matching and external database lookups (either via plain text tables, DBM hash files or external processes) for advanced URL substitution. -

      +

      It operates on the full URLs (including the PATH_INFO part) both in per-server context (httpd.conf) and per-dir context (.htaccess) and even can generate QUERY_STRING parts on result. The rewritten result can lead to internal sub-processing, external request redirection or to internal proxy throughput. -

      +

      This module was originally written in April 1996 and gifted exclusively to the The Apache Group in July 1997 by -

      -

      - Ralf S. Engelschall
      - rse@engelschall.com
      - www.engelschall.com -
      +

      +

      + Ralf S. Engelschall
      + rse@engelschall.com
      + www.engelschall.com +
      -

      +

      Directives

      - + -
      +
      -
      - -

      Configuration Directives

      -       -
      +
      + +

      Configuration Directives

      +       +
      -

      RewriteEngine

       -Syntax: RewriteEngine {on,off}
      -Default: RewriteEngine off
      -Context: server config, virtual host, per-directory config
      -

      +

      RewriteEngine

      +Syntax: RewriteEngine {on,off}
      +Default: RewriteEngine off
      +Context: server config, virtual host, per-directory config
      +

      -The 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 +The 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. -

      +

      Use this directive to disable the module instead of commenting out -all RewriteRule directives! +all RewriteRule directives! -

      +

      Note that, by default, rewrite configurations are not inherited. -This means that you need to have a RewriteEngine on +This means that you need to have a RewriteEngine on directive for each virtual host you wish to use it in, unless RewriteOptions inherit is enabled. -

      +

      -

      +

      -

      RewriteOptions

      -Syntax: RewriteOptions Option ...
      -Default: -None-
      -Context: server config, virtual host, per-directory config
      -

      +

      RewriteOptions

      +Syntax: RewriteOptions Option ...
      +Default: -None-
      +Context: server config, virtual host, per-directory config
      +

      -The RewriteOptions directive sets some special options for the -current per-server or per-directory configuration. The Option +The RewriteOptions directive sets some special options for the +current per-server or per-directory configuration. The Option strings can be one of the following: -

        -
      • 'inherit'
        +
          +
        • 'inherit'
          This forces the current configuration to inherit the configuration of the parent. In per-virtual-server context this means that the maps, conditions and rules of the main server gets inherited. In per-directory context this means that conditions and rules of the parent directory's - .htaccess configuration gets inherited. -
        + .htaccess configuration gets inherited. +
      -

      +

      -

      +

      -

      RewriteLog

      -Syntax: RewriteLog Filename
      -Default: -None-
      -Context: server config, virtual host
      -

      +

      RewriteLog

      +Syntax: RewriteLog Filename
      +Default: -None-
      +Context: server config, virtual host
      +

      -The RewriteLog directive sets the name of the file to which the +The 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 +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 +to set Filename +to /dev/null, because although the rewriting engine does not create output to a logfile it still creates the logfile -output internally. This will slow down the server with no advantage to the -administrator! +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! -
      +RewriteLog directive or use RewriteLogLevel 0! + + -

      +

      - -
      -SECURITY: See the Apache Security -Tips document for details on why your security could be compromised if the +
      +SECURITY: See the Apache 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. -
      + + -

      -Example: -

      -
      +
      
+Example:
+
      
+
       RewriteLog "/usr/local/var/apache/logs/rewrite.log"
-
      
-
      
+
      +
      -

      +

      -

      +

      -

      RewriteLogLevel

      -Syntax: RewriteLogLevel Level
      -Default: RewriteLogLevel 0
      -Context: server config, virtual host
      -

      +

      RewriteLogLevel

      +Syntax: RewriteLogLevel Level
      +Default: RewriteLogLevel 0
      +Context: server config, virtual host
      +

      -The RewriteLogLevel directive set the verbosity level of the rewriting +The RewriteLogLevel directive set 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. -

      -To disable the logging of rewriting actions simply set Level to 0. +

      +To disable the logging of rewriting actions simply set Level to 0. This disables all rewrite action logs. -

      +

      - -
      -Notice: Using a high value for Level will slow down your Apache +
      +Notice: Using a high value for Level will slow down your Apache server dramatically! Use the rewriting logfile only for debugging or at least -at Level not greater than 2! -
      +at Level not greater than 2! + + -

      -Example: -

      -
      +
      
+Example:
+
      
+
       RewriteLogLevel 3
-
      
-
      
+
      +
      -

      +

      -

      +

      -

      RewriteMap

      -Syntax: RewriteMap Mapname {txt,dbm,prg}:Filename
      -Default: not used per default
      -Context: server config, virtual host
      -

      +

      RewriteMap

      +Syntax: RewriteMap Mapname {txt,dbm,prg}:Filename
      +Default: not used per default
      +Context: server config, virtual host
      +

      -The RewriteMap directive defines an external Rewriting Map +The RewriteMap directive defines an external Rewriting Map which can be used inside rule substitution strings by the mapping-functions to insert/substitute fields through a key lookup. -

      +

      -The Mapname is the name of the map and will +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 -

      -${ Mapname : LookupKey -| DefaultValue } -
      +
      +${ Mapname : LookupKey +| DefaultValue } +
      -When such a directive occurs the map Mapname -is consulted and the key LookupKey is looked-up. If the key is -found, the map-function directive is substituted by SubstValue. If -the key is not found then it is substituted by DefaultValue. +When such a directive occurs the map Mapname +is consulted and the key LookupKey is looked-up. If the key is +found, the map-function directive is substituted by SubstValue. If +the key is not found then it is substituted by DefaultValue. -

      -The Filename must be a valid Unix filepath, containing one +

      +The Filename must be a valid Unix filepath, containing one of the following formats: -

        -
      1. Plain Text Format -

        +

          +
        1. Plain Text Format +

          This is a ASCII file which contains either blank lines, comment lines (starting with a '#' character) or -

          - MatchingKey SubstValue -
          +
          + MatchingKey SubstValue +
          pairs - one per line. You can create such files either manually, using your favorite editor, or by using the programs - mapcollect and mapmerge from the support - directory of the mod_rewrite distribution. -

          - To declare such a map prefix, Filename with a txt: + mapcollect and mapmerge from the support + directory of the mod_rewrite distribution. +

          + To declare such a map prefix, Filename with a txt: string as in the following example: -

          +

          - -
          +
           #
 #   map.real-to-user -- maps realnames to usernames
 #
 
 Ralf.S.Engelschall    rse   # Bastard Operator From Hell
 Dr.Fred.Klabuster     fred  # Mr. DAU
-
          + + -

          +

          - -
          +
           RewriteMap real-to-host txt:/path/to/file/map.real-to-user
-
          + + -

          -

        2. DBM Hashfile Format -

          +

          +

        3. DBM Hashfile Format +

          This is a binary NDBM format file containing the - same contents as the Plain Text Format files. You can create - such a file with any NDBM tool or with the dbmmanage program - from the support directory of the Apache distribution. -

          - To declare such a map prefix Filename with a dbm: + same contents as the Plain Text Format files. You can create + such a file with any NDBM tool or with the dbmmanage program + from the support directory of the Apache distribution. +

          + To declare such a map prefix Filename with a dbm: string. -

          -

        4. Program Format -

          +

          +

        5. Program Format +

          This is a Unix executable, not a lookup file. To create it you can use the language of your choice, but the result has to be a run-able Unix binary (i.e. either object-code or a script with the - magic cookie trick '#!/path/to/interpreter' as the first line). -

          + magic cookie trick '#!/path/to/interpreter' as the first line). +

          This program gets started once at startup of the Apache servers and then - communicates with the rewriting engine over its stdin and - stdout file-handles. For each map-function lookup it will + communicates with the rewriting engine over its 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 + 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>) {
@@ -321,86 +321,86 @@ while (<STDIN>) {
     # or lookups should occur...
     print $_;
 }
-
          -

          - But be very careful:
          -

            -
          1. ``Keep the program simple, stupid'' (KISS), because + + +

            + But be very careful:
            +

              +
            1. ``Keep the program simple, stupid'' (KISS), because if this program hangs it will lead to a hang of the Apache server when the rule occurs. -
            2. Avoid one common mistake: never do buffered I/O on stdout! - This will cause a deadloop! Hence the ``$|=1'' in the above +
            3. Avoid one common mistake: never do buffered I/O on stdout! + This will cause a deadloop! Hence the ``$|=1'' in the above example... -
            -

            - To declare such a map prefix Filename with a prg: +

          +

          + To declare such a map prefix Filename with a prg: string. -

        +
      -The 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 +The 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. -

      +

      - -
      +
      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 +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 +for every request. This is no problem, because the external lookup only happens once! -
      + + -

      +

      -

      +

      -

      RewriteBase

      -Syntax: RewriteBase BaseURL
      -Default: default is the physical directory path
      -Context: per-directory config
      -

      +

      RewriteBase

      +Syntax: RewriteBase BaseURL
      +Default: default is the physical directory path
      +Context: per-directory config
      +

      -The 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). There it will act +The 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). There it will act locally, i.e. the local directory prefix is stripped at this stage of processing and your rewriting rules act only on the remainder. At the end it is automatically added. -

      +

      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. But at most websites URLs are -NOT directly related to physical filename paths, so this assumption -will be usually be wrong! There you have to use the RewriteBase +prefix is the corresponding filepath itself. But at most websites URLs are +NOT directly related to physical filename paths, so this assumption +will be usually be wrong! There you have to use the RewriteBase directive to specify the correct URL-prefix. -

      +

      - -
      -So, if your webserver's URLs are not directly -related to physical file paths, you have to use RewriteBase in every -.htaccess files where you want to use RewriteRule +
      +So, if your webserver's URLs are not directly +related to physical file paths, you have to use RewriteBase in every +.htaccess files where you want to use RewriteRule directives. -
      + + -

      -Example: +

      +Example: -

      +
      Assume the following per-directory config file: -

      +

      - -
      +
       #
 #  /abc/def/.htaccess -- per-dir config file for directory /abc/def
 #  Remember: /abc/def is the physical path of /xyz, i.e. the server
@@ -415,23 +415,23 @@ RewriteBase   /xyz
 
 #  now the rewriting rules
 RewriteRule   ^oldstuff\.html$  newstuff.html
-
      + + -

      -In the above example, a request to /xyz/oldstuff.html gets correctly -rewritten to the physical file /abc/def/newstuff.html. +

      +In the above example, a request to /xyz/oldstuff.html gets correctly +rewritten to the physical file /abc/def/newstuff.html. -

      +

      - -
      +
      -For the Apache hackers:
      +For the Apache hackers:
      The following list gives detailed information about the internal processing steps: -

      -

      +
      
+
       Request:
   /xyz/oldstuff.html
 
@@ -443,7 +443,7 @@ Internal Processing:
 
 Result:
   /abc/def/newstuff.html
-
      
+
      This seems very complicated but is the correct Apache internal processing, because the per-directory rewriting comes too late in the process. So, @@ -452,293 +452,293 @@ kernel! BUT: While this seems like a serious overhead, it really isn't, because this re-injection happens fully internal to the Apache server and the same procedure is used by many other operations inside Apache. So, you can be sure the design and implementation is correct. -       -
      + + + -

      +
      -

      +

      -

      +

      -

      RewriteCond

      -Syntax: RewriteCond TestString CondPattern
      -Default: -None-
      -Context: server config, virtual host, per-directory config
      -

      +

      RewriteCond

      +Syntax: RewriteCond TestString CondPattern
      +Default: -None-
      +Context: server config, virtual host, per-directory config
      +

      -The RewriteCond directive defines a rule condition. Precede a -RewriteRule directive with one or more RewriteCond +The RewriteCond directive defines a rule condition. Precede a +RewriteRule directive with one or more RewriteCond directives. The following rewriting rule is only used if its pattern matches the current -state of the URI AND if these additional conditions apply, too. +state of the URI AND if these additional conditions apply, too. -

      -TestString is a string which can contains the following +

      +TestString is a string which can contains the following expanded constructs in addition to plain text: -

        -
      • RewriteRule backreferences: These are backreferences of the form +
          +
        • RewriteRule backreferences: These are backreferences of the form -
          -$N -
          +
          +$N +
          (1 <= N <= 9) which provide access to the grouped parts (parenthesis!) of the -pattern from the corresponding RewriteRule directive (the one -following the current bunch of RewriteCond directives). +pattern from the corresponding RewriteRule directive (the one +following the current bunch of RewriteCond directives). -

          -

        • RewriteCond backreferences: These are backreferences of the form +

          +

        • RewriteCond backreferences: These are backreferences of the form -
          -%N -
          +
          +%N +
          (1 <= N <= 9) which provide access to the grouped parts (parenthesis!) of the -pattern from the last matched RewriteCond directive in the current +pattern from the last matched RewriteCond directive in the current bunch of conditions. -

          -

        • Server-Variables: These are variables +

          +

        • Server-Variables: These are variables of the form -
          -%{ NAME_OF_VARIABLE } -
          +
          +%{ NAME_OF_VARIABLE } +
          -where NAME_OF_VARIABLE can be a string +where NAME_OF_VARIABLE can be a string of the following list: -

          +

          - + +HTTP_USER_AGENT
          +HTTP_REFERER
          +HTTP_COOKIE
          +HTTP_FORWARDED
          +HTTP_HOST
          +HTTP_PROXY_CONNECTION
          +HTTP_ACCEPT
          + + - - - +REMOTE_ADDR
          +REMOTE_HOST
          +REMOTE_USER
          +REMOTE_IDENT
          +REQUEST_METHOD
          +SCRIPT_FILENAME
          +PATH_INFO
          +QUERY_STRING
          +AUTH_TYPE
          + + + + + +DOCUMENT_ROOT
          +SERVER_ADMIN
          +SERVER_NAME
          +SERVER_PORT
          +SERVER_PROTOCOL
          +SERVER_SOFTWARE
          +SERVER_VERSION
          + + +TIME_YEAR
          +TIME_MON
          +TIME_DAY
          +TIME_HOUR
          +TIME_MIN
          +TIME_SEC
          +TIME_WDAY
          +TIME
          + + - -
          -HTTP headers:

          +HTTP headers:

          -HTTP_USER_AGENT
          -HTTP_REFERER
          -HTTP_COOKIE
          -HTTP_FORWARDED
          -HTTP_HOST
          -HTTP_PROXY_CONNECTION
          -HTTP_ACCEPT
          -           -

          		 -connection & request:

          +connection & request:

          -REMOTE_ADDR
          -REMOTE_HOST
          -REMOTE_USER
          -REMOTE_IDENT
          -REQUEST_METHOD
          -SCRIPT_FILENAME
          -PATH_INFO
          -QUERY_STRING
          -AUTH_TYPE
          -           -

          -server internals:

          +server internals:

          -DOCUMENT_ROOT
          -SERVER_ADMIN
          -SERVER_NAME
          -SERVER_PORT
          -SERVER_PROTOCOL
          -SERVER_SOFTWARE
          -SERVER_VERSION
          -           -

          		 -system stuff:

          +system stuff:

          -TIME_YEAR
          -TIME_MON
          -TIME_DAY
          -TIME_HOUR
          -TIME_MIN
          -TIME_SEC
          -TIME_WDAY
          -TIME
          -           -

          		 -specials:

          +specials:

          -API_VERSION
          -THE_REQUEST
          -REQUEST_URI
          -REQUEST_FILENAME
          -IS_SUBREQ
          -           -

          - -

          +API_VERSION
          +THE_REQUEST
          +REQUEST_URI
          +REQUEST_FILENAME
          +IS_SUBREQ
          + + + + + +

          - -
          +
          These variables all correspond to the similar named HTTP MIME-headers, C -variables of the Apache server or struct tm fields of the Unix +variables of the Apache server or struct tm fields of the Unix system. -
          + + -

        +
      -

      +

      Special Notes: -

        -
      1. The variables SCRIPT_FILENAME and REQUEST_FILENAME contain the same -value, i.e. the value of the filename field of the internal -request_rec structure of the Apache server. The first name is just the +
          +
        1. The variables SCRIPT_FILENAME and REQUEST_FILENAME contain the same +value, i.e. the value of the filename field of the internal +request_rec structure of the Apache server. The first name is just the commonly known CGI variable name while the second is the consistent -counterpart to REQUEST_URI (which contains the value of the uri -field of request_rec). +counterpart to REQUEST_URI (which contains the value of the uri +field of request_rec). -

          -

        2. There is the special format: %{ENV:variable} where -variable can be any environment variable. This is looked-up via -internal Apache structures and (if not found there) via getenv() from +

          +

        3. There is the special format: %{ENV:variable} where +variable can be any environment variable. This is looked-up via +internal Apache structures and (if not found there) via getenv() from the Apache server process. -

          -

        4. There is the special format: %{HTTP:header} where -header can be any HTTP MIME-header name. This is looked-up -from the HTTP request. Example: %{HTTP:Proxy-Connection} -is the value of the HTTP header ``Proxy-Connection:''. - -

          -

        5. There is the special format: %{LA-U:url} -for look-aheads like -U. This performs a internal sub-request to -look-ahead for the final value of url. - -

          -

        6. There is the special format: %{LA-F:file} -for look-aheads like -F. This performs a internal sub-request to -look-ahead for the final value of file. -
        - -

        -CondPattern is the condition pattern, i.e. a regular expression -which gets applied to the current instance of the TestString, i.e. -TestString gets evaluated and then matched against -CondPattern. - -

        -Remember: CondPattern is a standard -Extended Regular Expression with some additions: - -

          -
        1. You can precede the pattern string with a '!' character -(exclamation mark) to specify a non-matching pattern. - -

          -

        2. -There are some special variants of CondPatterns. Instead of real +

          +

        3. There is the special format: %{HTTP:header} where +header can be any HTTP MIME-header name. This is looked-up +from the HTTP request. Example: %{HTTP:Proxy-Connection} +is the value of the HTTP header ``Proxy-Connection:''. + +

          +

        4. There is the special format: %{LA-U:url} +for look-aheads like -U. This performs a internal sub-request to +look-ahead for the final value of url. + +

          +

        5. There is the special format: %{LA-F:file} +for look-aheads like -F. This performs a internal sub-request to +look-ahead for the final value of file. +
        + +

        +CondPattern is the condition pattern, i.e. a regular expression +which gets applied to the current instance of the TestString, i.e. +TestString gets evaluated and then matched against +CondPattern. + +

        +Remember: CondPattern is a standard +Extended Regular Expression with some additions: + +

          +
        1. You can precede the pattern string with a '!' character +(exclamation mark) to specify a non-matching pattern. + +

          +

        2. +There are some special variants of CondPatterns. Instead of real regular expression strings you can also use one of the following: -

          -

            -
          • '<CondPattern' (is lexicographically lower)
            -Treats the CondPattern as a plain string and compares it -lexicographically to TestString and results in a true expression if -TestString is lexicographically lower then CondPattern. -

            -

          • '>CondPattern' (is lexicographically greater)
            -Treats the CondPattern as a plain string and compares it -lexicographically to TestString and results in a true expression if -TestString is lexicographically greater then CondPattern. -

            -

          • '=CondPattern' (is lexicographically equal)
            -Treats the CondPattern as a plain string and compares it -lexicographically to TestString and results in a true expression if -TestString is lexicographically equal to CondPattern, i.e the +

            +

              +
            • '<CondPattern' (is lexicographically lower)
              +Treats the CondPattern as a plain string and compares it +lexicographically to TestString and results in a true expression if +TestString is lexicographically lower then CondPattern. +

              +

            • '>CondPattern' (is lexicographically greater)
              +Treats the CondPattern as a plain string and compares it +lexicographically to TestString and results in a true expression if +TestString is lexicographically greater then CondPattern. +

              +

            • '=CondPattern' (is lexicographically equal)
              +Treats the CondPattern as a plain string and compares it +lexicographically to TestString and results in a true expression if +TestString is lexicographically equal to CondPattern, i.e the two strings are exactly equal (character by character). -If CondPattern is just "" (two quotation marks) this -compares TestString against the empty string. -

              -

            • '-d' (is directory)
              -Treats the TestString as a pathname and +If CondPattern is just "" (two quotation marks) this +compares TestString against the empty string. +

              +

            • '-d' (is directory)
              +Treats the TestString as a pathname and tests if it exists and is a directory. -

              -

            • '-f' (is regular file)
              -Treats the TestString as a pathname and +

              +

            • '-f' (is regular file)
              +Treats the TestString as a pathname and tests if it exists and is a regular file. -

              -

            • '-s' (is regular file with size)
              -Treats the TestString as a pathname and +

              +

            • '-s' (is regular file with size)
              +Treats the TestString as a pathname and tests if it exists and is a regular file with size greater then zero. -

              -

            • '-l' (is symbolic link)
              -Treats the TestString as a pathname and +

              +

            • '-l' (is symbolic link)
              +Treats the TestString as a pathname and tests if it exists and is a symbolic link. -

              -

            • '-F' (is existing file via subrequest)
              -Checks if TestString is a valid file and accessible via all the +

              +

            • '-F' (is existing file via subrequest)
              +Checks if TestString is a valid file and accessible via all the server's currently-configured access controls for that path. This uses an internal subrequest to determine the check, so use it with care because it decreases your servers performance! -

              -

            • '-U' (is existing URL via subrequest)
              -Checks if TestString is a valid URL and accessible via all the server's +

              +

            • '-U' (is existing URL via subrequest)
              +Checks if TestString is a valid URL and accessible via all the server's currently-configured access controls for that path. This uses an internal subrequest to determine the check, so use it with care because it decreases your servers performance! -
            -

            +

          +

          Notice: All of these tests can also be prefixed by a not ('!') character to negate their meaning. -

        +
      -

      -Additionally you can set special flags for CondPattern by appending +

      +Additionally you can set special flags for CondPattern by appending -

      -[flags] -
      +
      +[flags] +
      -as the third argument to the RewriteCond directive. Flags +as the third argument to the RewriteCond directive. Flags is a comma-separated list of the following flags: -
        -
      • 'nocase|NC' (no case)
        +
          +
        • 'nocase|NC' (no case)
          This makes the condition test case-insensitive, i.e. there is no difference between 'A-Z' and 'a-z' both in the expanded - TestString and the CondPattern. -

          -

        • 'ornext|OR' (or next condition)
          + TestString and the CondPattern. +

          +

        • 'ornext|OR' (or next condition)
          Use this to combine rule conditions with a local OR instead of the implicit AND. Typical example: -

          -

          +    
          
+
           RewriteCond %{REMOTE_HOST}  ^host1.*  [OR]
 RewriteCond %{REMOTE_HOST}  ^host2.*  [OR]
 RewriteCond %{REMOTE_HOST}  ^host3.*
 RewriteRule ...some special stuff for any of these hosts...
-
          
+
          Without this flag you had to write down the cond/rule three times. -
        +
      -

      -Example: -

      +

      +Example: +

      -To rewrite the Homepage of a site according to the ``User-Agent:'' +To rewrite the Homepage of a site according to the ``User-Agent:'' header of the request, you can use the following: -
      +
       RewriteCond  %{HTTP_USER_AGENT}  ^Mozilla.*
 RewriteRule  ^/$                 /homepage.max.html  [L]
 
@@ -746,355 +746,355 @@ RewriteCond  %{HTTP_USER_AGENT}  ^Lynx.*
 RewriteRule  ^/$                 /homepage.min.html  [L]
 
 RewriteRule  ^/$                 /homepage.std.html  [L]
-
      
+
      Interpretation: If you use Netscape Navigator as your browser (which identifies itself as 'Mozilla'), then you get the max homepage, which includes Frames, etc. If you use the Lynx browser (which is Terminal-based), then you get the min homepage, which contains no images, no tables, etc. If you use any other browser you get the standard homepage. -
      +
      -

      +

      -

      +

      -

      RewriteRule

      -Syntax: RewriteRule Pattern Substitution
      -Default: -None-
      -Context: server config, virtual host, per-directory config
      +

      RewriteRule

       +Syntax: RewriteRule Pattern Substitution
      +Default: -None-
      +Context: server config, virtual host, per-directory config
      -

      -The RewriteRule directive is the real rewriting workhorse. The +

      +The RewriteRule directive is the real rewriting workhorse. The directive can occur more than once. Each directive then defines one single -rewriting rule. The definition order of these rules is -important, because this order is used when applying the rules at +rewriting rule. The definition order of these rules is +important, because this order is used when applying the rules at run-time. -

      -Pattern can be (for Apache 1.1.x a System -V8 and for Apache 1.2.x a POSIX) regular expression +

      +Pattern can be (for Apache 1.1.x a System +V8 and for Apache 1.2.x a POSIX) regular expression which gets applied to the current URL. Here ``current'' means the value of the URL when this rule gets applied. This may not be the original requested URL, because there could be any number of rules before which already matched and made alterations to it. -

      +

      Some hints about the syntax of regular expressions: -

      +

      - + - -
      -
      -^           Start of line
-$           End of line
-.           Any single character
-[chars]     One of chars
-[^chars]    None of chars
-
-?           0 or 1 of the preceding char
-*           0 or N of the preceding char
-+           1 or N of the preceding char
-
-\char       escape that specific char
-            (e.g. for specifying the chars ".[]()" etc.)
-
-(string)    Grouping of chars (the Nth group can be used on the RHS with $N)
-
      -
      - -

      -Additionally the NOT character ('!') is a possible pattern -prefix. This gives you the ability to negate a pattern; to say, for instance: ``if -the current URL does NOT match to this pattern''. This can be used +

      +^           Start of line
+$           End of line
+.           Any single character
+[chars]     One of chars
+[^chars]    None of chars
+
+?           0 or 1 of the preceding char
+*           0 or N of the preceding char
++           1 or N of the preceding char
+
+\char       escape that specific char
+            (e.g. for specifying the chars ".[]()" etc.)
+
+(string)    Grouping of chars (the Nth group can be used on the RHS with $N)
+
      + + + + +

      +Additionally the NOT character ('!') is a possible pattern +prefix. This gives you the ability to negate a pattern; to say, for instance: ``if +the current URL does NOT match to this pattern''. This can be used for special cases where it is better to match the negative pattern or as a last default rule. -

      +

      - -
      -Notice! When using the NOT character to negate a pattern you cannot +
      +Notice! When using the NOT character to negate a pattern you cannot have grouped wildcard parts in the pattern. This is impossible because when the pattern does NOT match, there are no contents for the groups. In -consequence, if negated patterns are used, you cannot use $N in the +consequence, if negated patterns are used, you cannot use $N in the substitution string! -
      + + -

      -Substitution of a rewriting rule is the string +

      +Substitution of a rewriting rule is the string which is substituted for (or replaces) the original URL for which -Pattern matched. Beside plain text you can use - -

        -
      1. back-references $N to the RewriteRule pattern -
      2. back-references %N to the last matched RewriteCond pattern -
      3. server-variables as in rule condition test-strings (%{VARNAME}) -
      4. mapping-function calls (${mapname:key|default}) -
      - -Back-references are $N (N=1..9) identifiers 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 +Pattern matched. Beside plain text you can use + +
        +
      1. back-references $N to the RewriteRule pattern +
      2. back-references %N to the last matched RewriteCond pattern +
      3. server-variables as in rule condition test-strings (%{VARNAME}) +
      4. mapping-function calls (${mapname:key|default}) +
      + +Back-references are $N (N=1..9) identifiers 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 of the above list. -

      +

      As already mentioned above, all the rewriting rules are applied to the -Substitution (in the order of definition in the config file). The -URL is completely replaced by the Substitution and the +Substitution (in the order of definition in the config file). The +URL is completely replaced by the Substitution and the rewriting process goes on until there are no more rules (unless explicitly -terminated by a L flag - see below). +terminated by a L flag - see below). -

      -There is a special substitution string named '-' which means: -NO substitution! Sounds silly? No, it is useful to provide rewriting -rules which only match some URLs but do no substitution, e.g. in -conjunction with the C (chain) flag to be able to have more than one +

      +There is a special substitution string named '-' which means: +NO substitution! Sounds silly? No, it is useful to provide rewriting +rules which only match some URLs but do no substitution, e.g. in +conjunction with the C (chain) flag to be able to have more than one pattern to be applied before a substitution occurs. -

      +

      One more note: You can even create URLs in the substitution string containing a query string part. Just use a question mark inside the substitution string to indicate that the following stuff should be re-injected into the QUERY_STRING. When you want to erase an existing query string, end the substitution string with just the question mark. -

      +

      - -
      -Notice: There is a special feature. When you prefix a substitution -field with http://thishost[:thisport] then -mod_rewrite automatically strips it out. This auto-reduction on +
      +Notice: There is a special feature. When you prefix a substitution +field with http://thishost[:thisport] then +mod_rewrite automatically strips it out. This auto-reduction on implicit external redirect URLs is a useful and important feature when used in combination with a mapping-function which generates the hostname part. Have a look at the first example in the example section below to understand this. -

      -Remember: An unconditional external redirect to your own server will -not work with the prefix http://thishost because of this feature. -To achieve such a self-redirect, you have to use the R-flag (see +

      +Remember: An unconditional external redirect to your own server will +not work with the prefix http://thishost because of this feature. +To achieve such a self-redirect, you have to use the R-flag (see below). -

      + + -

      -Additionally you can set special flags for Substitution by appending +

      +Additionally you can set special flags for Substitution by appending -

      -[flags] -
      +
      +[flags] +
      -as the third argument to the RewriteRule directive. Flags is a +as the third argument to the RewriteRule directive. Flags is a comma-separated list of the following flags: -
        -
      • '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 +
          +
        • '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) is used. If you want to use other response codes in the range 300-400 just specify them as a number or use - one of the following symbolic names: temp (default), permanent, - seeother. + one of the following symbolic names: temp (default), permanent, + seeother. Use it for rules which should canonicalize the URL and gives it back to the client, e.g. translate - ``/~'' into ``/u/'' or always append a slash to - /u/user, etc.
          -

          - Notice: When you use this flag, make sure that the + ``/~'' into ``/u/'' or always append a slash to + /u/user, etc.
          +

          + Notice: When you use this flag, make sure that the substitution field is a valid URL! If not, you are redirecting to an invalid location! And remember that this flag itself only prefixes the - URL with http://thishost[:thisport]/, but rewriting goes on. + URL with http://thishost[:thisport]/, but rewriting goes on. Usually you also want to stop and do the redirection immediately. To stop the rewriting you also have to provide the 'L' flag. -

          -

        • 'forbidden|F' (force URL to be forbidden)
          +

          +

        • 'forbidden|F' (force URL to be forbidden)
          This forces the current URL to be forbidden, i.e. 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)
          +

          +

        • 'gone|G' (force URL to be gone)
          This forces the current URL to be gone, i.e. it immediately sends back a HTTP response of 410 (GONE). Use this flag to mark no longer existing pages as gone. -

          -

        • 'proxy|P' (force proxy)
          +

          +

        • 'proxy|P' (force proxy)
          This flag forces the substitution part to be internally forced as a proxy request and immediately (i.e. rewriting rule processing stops here) put through the proxy module. You have to make sure that the substitution - string is a valid URI (e.g. typically http://) which can + string is a valid URI (e.g. typically http://) which can be handled by the Apache proxy module. If not you get an error from the proxy module. Use this flag to achieve a more powerful implementation - of the mod_proxy directive ProxyPass, to map + of the mod_proxy directive ProxyPass, to map some remote stuff into the namespace of the local server. -

          - Notice: You really have to put ProxyRequests On into your +

          + Notice: You really have to put ProxyRequests On into your server configuration to prevent proxy requests from leading to core-dumps inside the Apache kernel. If you have not compiled in the proxy module, then there is no core-dump problem, because mod_rewrite checks for - existence of the proxy module and if lost forbids proxy URLs. -

          -

        • 'last|L' (last rule)
          + existence of the proxy module and if lost forbids proxy URLs.           +

          +

        • 'last|L' (last rule)
          Stop the rewriting process here and don't apply any more rewriting rules. This corresponds to the Perl - last command or the break command from the C + last command or the break command from the C language. Use this flag to prevent the currently rewritten URL from being rewritten further by following rules which may be wrong. For - example, use it to rewrite the root-path URL ('/') to a real - one, e.g. '/e/www/'. -

          -

        • 'next|N' (next round)
          + 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). Here the URL to match is again not the original URL but the URL from the last rewriting rule. This corresponds to the Perl - next command or the continue command from the C + next command or the continue command from the C language. Use this flag to restart the rewriting process, i.e. to - immediately go to the top of the loop.
          - But be careful not to create a deadloop! -

          -

        • 'chain|C' (chained with next rule)
          + immediately go to the top of the loop.
          + But be careful not to create a deadloop! +

          +

        • 'chain|C' (chained with next rule)
          This flag chains the current rule with the next rule (which itself can also be chained with its following rule, etc.). This has the following effect: if a rule matches, then processing continues as usual, i.e. the - flag has no effect. If the rule does not match, then all following + flag has no effect. If the rule does not match, then all following chained rules are skipped. For instance, use it to remove the - ``.www'' part inside a per-directory rule set when you let an - external redirect happen (where the ``.www'' part should not to + ``.www'' part inside a per-directory rule set when you let an + external redirect happen (where the ``.www'' part should not to occur!). -

          -

        • 'type|T=mime-type' (force MIME type)
          - Force the MIME-type of the target file to be mime-type. For - instance, this can be used to simulate the old mod_alias - directive ScriptAlias which internally forces all files inside +

          +

        • 'type|T=mime-type' (force MIME type)
          + Force the MIME-type of the target file to be mime-type. For + instance, this can be used to simulate the old mod_alias + directive ScriptAlias which internally forces all files inside the mapped directory to have a MIME type of - ``application/x-httpd-cgi''. -

          -

        • 'nosubreq|NS' (used only if no internal sub-request)
          + ``application/x-httpd-cgi''. +

          +

        • 'nosubreq|NS' (used only if no internal sub-request)
          This flag forces the rewriting engine to skip a rewriting 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). + 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 even sometimes causes a failure to - if the complete set of rules are applied. Use this flag to exclude some rules.
          -

          + if the complete set of rules are applied. Use this flag to exclude some rules.
          +

          Use the following rule for your decision: whenever you prefix some URLs with CGI-scripts to force them to be processed by the CGI-script, the chance is high that you will run into problems (or even overhead) on sub-requests. In these cases, use this flag. -

          -

        • 'qsappend|QSA' (query string - append)
          +

          +

        • 'qsappend|QSA' (query string + append)
          This flag forces the rewriting engine to append a query string part in the substitution string to the existing one instead of replacing it. Use this when you want to add more data to the query string via a rewrite rule. -

          -

        • 'passthrough|PT' (pass through to next handler)
          - This flag forces the rewriting 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 be able - to post-process the output of RewriteRule directives by - Alias, ScriptAlias, Redirect, etc. directives +

          +

        • 'passthrough|PT' (pass through to next handler)
          + This flag forces the rewriting 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 be able + to post-process the output of RewriteRule directives by + Alias, ScriptAlias, Redirect, etc. directives from other URI-to-filename translators. A trivial example to show the semantics: - If you want to rewrite /abc to /def via the rewriting - engine of mod_rewrite and then /def to /ghi - with mod_alias: - 
          +    If you want to rewrite /abc to /def via the rewriting
+    engine of mod_rewrite and then /def to /ghi
+    with mod_alias:
+    
               RewriteRule ^/abc(.*)  /def$1 [PT]
     Alias       /def       /ghi
-    
          
-    If you omit the PT flag then mod_rewrite
-    will do its job fine, i.e. it rewrites uri=/abc/... to
-    filename=/def/... as a full API-compliant URI-to-filename
-    translator should do. Then mod_alias comes and tries to do a
+
          + If you omit the PT flag then mod_rewrite + will do its job fine, i.e. it rewrites uri=/abc/... to + filename=/def/... as a full API-compliant URI-to-filename + translator should do. Then mod_alias comes and tries to do a URI-to-filename transition which will not work. -

          - Notice: You have to use this flag if you want to intermix directives - of different modules which contain URL-to-filename translators. The - typical example is the use of mod_alias and - mod_rewrite.. -

          +

          + Notice: You have to use this flag if you want to intermix directives + of different modules which contain URL-to-filename translators. The + typical example is the use of mod_alias and + mod_rewrite.. +

          - -
          +
          - For the Apache hackers:
          + For the Apache hackers:
          If the current Apache API had a filename-to-filename hook additionally to the URI-to-filename hook then we wouldn't need this flag! But without such a hook this flag is the only solution. The Apache Group has discussed this problem and will add such hooks into Apache version 2.0. -           -
          -

          -

        • 'skip|S=num' (skip next rule(s))
          - This flag forces the rewriting engine to skip the next num rules + + + +

          +

        • 'skip|S=num' (skip next rule(s))
          + This flag forces the rewriting engine to skip the next num rules in sequence when the current rule matches. Use this to make pseudo if-then-else constructs: The last rule of the then-clause becomes - a skip=N where N is the number of rules in the else-clause. - (This is not the same as the 'chain|C' flag!) -

          -

        • 'env|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 + a skip=N where N is the number of rules in the else-clause. + (This is not the same as the 'chain|C' flag!) +

          +

        • 'env|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 be later dereferenced at a lot of situations, but the usual location will be from - within XSSI (via <!--#echo var="VAR"-->) or CGI (e.g. - $ENV{'VAR'}). But additionally you can also dereference it in a - following RewriteCond pattern via %{ENV:VAR}. Use this to strip + within XSSI (via <!--#echo var="VAR"-->) or CGI (e.g. + $ENV{'VAR'}). But additionally you can also dereference it in a + following RewriteCond pattern via %{ENV:VAR}. Use this to strip but remember information from URLs. -
        +
      -

      +

      - -
      -Remember: Never forget that Pattern gets applied to a complete URL -in per-server configuration files. But in per-directory configuration +
      +Remember: Never forget that Pattern gets applied to a complete URL +in per-server configuration files. But in per-directory configuration files, the per-directory prefix (which always is the same for a specific -directory!) gets automatically removed for the pattern matching and -automatically added after the substitution has been done. This feature is +directory!) gets automatically removed for the pattern matching and +automatically added after the substitution has been done. This feature is essential for many sorts of rewriting, because without this prefix stripping you have to match the parent directory which is not always possible. -

      +

      There is one exception: If a substitution string starts with -``http://'' then the directory prefix will be not added and a -external redirect or proxy throughput (if flag P is used!) is forced! -

      +``http://'' then the directory prefix will be not added and a +external redirect or proxy throughput (if flag P is used!) is forced! + + -

      +

      - -
      +
      Notice! To enable the rewriting engine for per-directory configuration files -you need to set ``RewriteEngine On'' in these files and -``Option FollowSymLinks'' enabled. If your administrator has -disabled override of FollowSymLinks for a user's directory, then +you need to set ``RewriteEngine On'' in these files and +``Option FollowSymLinks'' 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. -
      + + -

      +

      Here are all possible substitution combinations and their meanings: -

      -Inside per-server configuration (httpd.conf)
      -for request ``GET /somepath/pathinfo'':
      +

      +Inside per-server configuration (httpd.conf)
      +for request ``GET /somepath/pathinfo'':
      -

      +

      - - + - -
      -
      -Given Rule                                      Resulting Substitution
+
      +
      +Given Rule                                      Resulting Substitution
 ----------------------------------------------  ----------------------------------
 ^/somepath(.*) otherpath$1                      not supported, because invalid!
 
@@ -1125,23 +1125,23 @@ for request ``GET /somepath/pathinfo'':
      
 
 ^/somepath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo
                                                 via internal proxy
-
      -
      - -

      -Inside per-directory configuration for /somepath
      -(i.e. file .htaccess in dir /physical/path/to/somepath containing -RewriteBase /somepath)
      for -request ``GET /somepath/localpath/pathinfo'':
      - -

      + + + + + +

      +Inside per-directory configuration for /somepath
      +(i.e. file .htaccess in dir /physical/path/to/somepath containing +RewriteBase /somepath)
      for +request ``GET /somepath/localpath/pathinfo'':
      + +

      - - + - -
      -
      -Given Rule                                      Resulting Substitution
+
      +
      +Given Rule                                      Resulting Substitution
 ----------------------------------------------  ----------------------------------
 ^localpath(.*) otherpath$1                      /somepath/otherpath/pathinfo
 
@@ -1173,80 +1173,80 @@ request ``GET /somepath/localpath/pathinfo'':
      
 
 ^localpath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo
                                                 via internal proxy
-
      -
      + + + + -

      -Example: -

      -

      +

      +Example: +

      +

      We want to rewrite URLs of the form -
      -/ Language -/~ Realname -/.../ File -
      +
      +/ Language +/~ Realname +/.../ File +
      into -
      -/u/ Username -/.../ File -. Language -
      -

      +

      +/u/ Username +/.../ File +. Language +
      +

      We take the rewrite mapfile from above and save it under -/anywhere/map.real-to-user. Then we only have to add the +/anywhere/map.real-to-user. Then we only have to add the following lines to the Apache server configuration file: -

      -
      +
      
+
       RewriteLog   /anywhere/rewrite.log
 RewriteMap   real-to-user               txt:/anywhere/map.real-to-host
 RewriteRule  ^/([^/]+)/~([^/]+)/(.*)$   /u/${real-to-user:$2|nobody}/$3.$1
-
      
-
      
-
      + +
      +
      -
      +
      -
      - -

      Additional Features

      -       -
      +
      + +

      Additional Features

      +       +
      - +

      Environment Variables

      -       + This module keeps track of two additional (non-standard) CGI/SSI environment -variables named 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. - -

      -Notice: These variables hold the URI/URL as they were initially -requested, i.e. in a state before any rewriting. This is +variables named 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. + +

      +Notice: These variables hold the URI/URL as they were initially +requested, i.e. in a state before any rewriting. This is important because the rewriting process is primarily used to rewrite logical URLs to physical pathnames. -

      -Example: +

      +Example: -

      -
      +
      
+
       SCRIPT_NAME=/v/sw/free/lib/apache/global/u/rse/.www/index.html
 SCRIPT_FILENAME=/u/rse/.www/index.html
 SCRIPT_URL=/u/rse/
 SCRIPT_URI=http://en2.en.sdm.de/u/rse/
-
      
-
      
+
      +
      diff --git a/docs/manual/mod/mod_speling.html b/docs/manual/mod/mod_speling.html index 3ece21704c..b2ed9e5ec5 100644 --- a/docs/manual/mod/mod_speling.html +++ b/docs/manual/mod/mod_speling.html @@ -14,11 +14,11 @@

      Module mod_speling

      - This module is contained in the mod_speling.c file, - and is not compiled in by default. + This module is contained in the mod_speling.c file, + and is not compiled in by default. It attempts to correct misspellings of URLs that users might have entered, by ignoring capitalization - and by allowing up to one misspelling.
      + and by allowing up to one misspelling.
      This catches the majority of misspelled requests. An automatic "spelling corrected" redirection is returned if only one matching document was found, and a list of matches is returned if more than @@ -26,7 +26,7 @@

      Summary

      -

      +

      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, @@ -36,38 +36,38 @@ 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, -

        -
      • no matching document was found, Apache will proceed as usual +
          +
        • no matching document was found, Apache will proceed as usual and return a "document not found" error. -
        • only one document is found that "almost" matches the request, +
        • only one document is found that "almost" matches the request, then it is returned in the form of a redirection response. -
        • more than one document with a close match was found, then +
        • more than one document with a close match was found, then the list of the matches is returned to the client, and the client can select the correct candidate. -
        -

        +
      +

      Directives

      - -
    • CheckSpelling -
      • + +
    • CheckSpelling +

      • CheckSpelling

       - Syntax: CheckSpelling on/off
      - Default: CheckSpelling Off
      - Context: server config, virtual host
      - Status: Base
      - Module: mod_speling
      - Compatibility: CheckSpelling was available as a separately + Syntax: CheckSpelling on/off
      + Default: CheckSpelling Off
      + Context: server config, virtual host
      + Status: Base
      + 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.

      + available as a separate module-->.

      This directive enables or disables the spelling module. When enabled, keep in mind that @@ -78,7 +78,7 @@

    • the document trees should not contain sensitive files which could be matched inadvertently, by a spelling "correction".
    • the module is unable to correct misspelled user names - (as in http://my.host/~apahce/), just file names or + (as in http://my.host/~apahce/), just file names or directory names.
    diff --git a/docs/manual/mod/mod_status.html b/docs/manual/mod/mod_status.html index 65c2dc389d..f6335a6926 100644 --- a/docs/manual/mod/mod_status.html +++ b/docs/manual/mod/mod_status.html @@ -1,7 +1,7 @@ - -Apache module mod_status - + +Apache module mod_status + -

    Module mod_status

    +

    Module mod_status

    -The Status Module is only available in Apache 1.1 and later.

    +The Status Module is only available in Apache 1.1 and later.

    Function

    @@ -23,23 +23,23 @@ 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 number of children serving requests -
    • The number of idle children -
    • The status of each child, the number of requests that child has +
        +
      • The number of children serving requests +
      • The number of idle children +
      • The status of each child, the number of requests that child has performed and the total number of bytes served by the child (*) -
      • A total number of accesses and byte count served (*) -
      • The time the server was started/restarted and the +
      • A total number of accesses and byte count served (*) +
      • The time the server was started/restarted and the time it has been running for -
      • Averages giving the number of requests per second, +
      • Averages giving the number of requests per second, the number of bytes served per second and the average number of bytes per request (*) -
      • The current percentage CPU used by each child and in total by +
      • The current percentage CPU used by each child and in total by Apache (*) -
      • The current hosts and requests being processed (*) -
      +
    • The current hosts and requests being processed (*) +
    A compile-time option must be used to display the details marked "(*)" as the instrumentation required for obtaining these statistics does not @@ -48,8 +48,8 @@ exist within standard Apache.

    Enabling Status Support

    To enable status reports only for browsers from the foo.com -domain add this code to your access.conf configuration file -
    +domain add this code to your access.conf configuration file
+
         <Location /server-status>
     SetHandler server-status
 
@@ -57,11 +57,11 @@ domain add this code to your access.conf configuration file
     deny from all
     allow from .foo.com
     </Location>
-
    
-
    
+
    +

    You can now access server statistics by using a Web browser to access the -page http://your.server.name/server-status -

    +page http://your.server.name/server-status +

    Note that mod_status will only work when you are running Apache in standalone mode and not inetd mode. @@ -69,29 +69,29 @@ Note that mod_status will only work when you are running Apache in

    Automatic Updates

    You can get the status page to update itself automatically if you have a browser that supports "refresh". Access the page -http://your.server.name/server-status?refresh=N to refresh the page +http://your.server.name/server-status?refresh=N to refresh the page every N seconds.

    Machine Readable Status File

    A machine-readable version of the status file is available by accessing the -page 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. +page 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.

    Full Instrumentation

    To obtain full statistics you must compile Apache with a special directive. On some machines there may be a small performance loss if you do this. Try full statistics and see if you notice any -difference. If you do please contact -mark@ukweb.com and tell me your configuration. +difference. If you do please contact +mark@ukweb.com and tell me your configuration. -

    +

    Do this by adding the following to the AUX_CFLAGS line in the "Configuration" file and then recompiling as usual. -

    +
             AUX_CFLAGS= (something) -DSTATUS
-
    
+
    diff --git a/docs/manual/mod/mod_unique_id.html b/docs/manual/mod/mod_unique_id.html index ff71fce934..919c9e8146 100644 --- a/docs/manual/mod/mod_unique_id.html +++ b/docs/manual/mod/mod_unique_id.html @@ -13,19 +13,19 @@ ALINK="#FF0000" > -

    Module mod_unique_id

    +

    Module mod_unique_id

    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 -UNIQUE_ID is set to the identifier for each request. +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

    -

    +

    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 @@ -33,7 +33,7 @@ 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 @@ -41,42 +41,42 @@ 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.) -

      -
    • The machines' times are synchronized via NTP or other network time +
        +
      • The machines' times are synchronized via NTP or other network time protocol. -
      • The machines' hostnames all differ, such that the module can do a +
      • The machines' hostnames all differ, such that the module can do a hostname lookup on the hostname and receive a different IP address for each machine in the cluster. -
      +
    -

    +

    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 +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 @@ -85,7 +85,7 @@ 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 @@ -94,7 +94,7 @@ 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). @@ -106,7 +106,7 @@ 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? Well 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 @@ -121,7 +121,7 @@ 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 @@ -130,33 +130,33 @@ 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 UNIQUE_ID environment variable is constructed by +

    +The 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@-] +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, +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 +Applications should treat the entire encoded UNIQUE_ID as an +opaque token, which can be compared against other UNIQUE_IDs for equality only. -

    +

    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 UNIQUE_IDs. The new encodings should also keep the time +of 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 +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. -

    +

    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 @@ -169,11 +169,11 @@ 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). -

    +

    Directives

    -mod_unique_id has no directives. +mod_unique_id has no directives. diff --git a/docs/manual/mod/mod_userdir.html b/docs/manual/mod/mod_userdir.html index 50ae172b13..2d79f11940 100644 --- a/docs/manual/mod/mod_userdir.html +++ b/docs/manual/mod/mod_userdir.html @@ -13,33 +13,33 @@ ALINK="#FF0000" > -

    Module mod_userdir

    +

    Module mod_userdir

    -This module is contained in the mod_userdir.c file, and +This module is contained in the mod_userdir.c file, and is compiled in by default. It provides for user-specific directories. - -
    + +

    UserDir

    -Syntax: UserDir directory/filename
    -Default: UserDir public_html
    -Context: server config, virtual host
    -Status: Base
    -Module: mod_userdir
    -Compatibility: All forms except the UserDir -public_html form are only available in Apache 1.1 or above. Use +Syntax: UserDir directory/filename
    +Default: UserDir public_html
    +Context: server config, virtual host
    +Status: Base
    +Module: mod_userdir
    +Compatibility: All forms except the UserDir +public_html form are only available in Apache 1.1 or above. Use of the enabled keyword, or disabled with a -list of usernames, is only available in Apache 1.3 and above.

    +list of usernames, is only available in Apache 1.3 and above.

    The 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: +Directory/filename is one of the following:

    • The name of a directory or a pattern such as those shown below. @@ -64,18 +64,18 @@ If neither the 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: -
      +http://www.foo.com/~bob/one/two.html will be translated to:
+
       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
-
      
+
      The following directives will send redirects to the client: -
      +
       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
-
      
+

      diff --git a/docs/manual/mod/mod_usertrack.html b/docs/manual/mod/mod_usertrack.html index 3bc03d3c22..af88b17c43 100644 --- a/docs/manual/mod/mod_usertrack.html +++ b/docs/manual/mod/mod_usertrack.html @@ -13,7 +13,7 @@ ALINK="#FF0000" > -

      Module mod_usertrack

      +

      Module mod_usertrack

      Previous releases of Apache have included a module which generates a 'clickstream' log of user activity on a site using cookies. This was @@ -22,60 +22,60 @@ module has been renamed the "user tracking" module, mod_usertrack. This module has been simplified and new directives added. -
      +

      Logging

      Previously, the cookies module (now the user tracking module) did its -own logging, using the CookieLog directive. In this release, +own logging, using the 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 +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"
-
      
+
      For backward compatibility the configurable log module implements the -old CookieLog directive, but this should be upgraded to the -above CustomLog directive. +old CookieLog directive, but this should be upgraded to the +above CustomLog directive.

      Directives

      - + -
      +
      -

      CookieExpires

      -Syntax: CookieExpires expiry-period
      -Context: server config, virtual host
      -Status: optional
      -Module: mod_usertrack

      +

      CookieExpires

      +Syntax: CookieExpires expiry-period
      +Context: server config, virtual host
      +Status: optional
      +Module: mod_usertrack

      When used, this directive sets an expiry time on the cookie generated -by the usertrack module. The expiry-period can be given either +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, 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.

      +

      If this directive is not used, cookies last only for the current +browser session.

      -

      CookieTracking

      -Syntax: CookieTracking on | off
      -Context: server config, virtual host, directory, -.htaccess
      -Override: FileInfo
      -Status: optional
      -Module: mod_usertrack

      +

      CookieTracking

      +Syntax: CookieTracking on | off
      +Context: server config, virtual host, directory, +.htaccess
      +Override: FileInfo
      +Status: optional
      +Module: mod_usertrack

      When the user track module is compiled in, and "CookieTracking on" is set, Apache will start sending a user-tracking cookie for all new diff --git a/docs/manual/platform/perf-bsd44.html b/docs/manual/platform/perf-bsd44.html index 01ea158da6..96536c266e 100644 --- a/docs/manual/platform/perf-bsd44.html +++ b/docs/manual/platform/perf-bsd44.html @@ -1,8 +1,8 @@ - - -Running a High-Performance Web Server for BSD - + + +Running a High-Performance Web Server for BSD +

      Running a High-Performance Web Server for BSD

      -Like other OS's, the listen queue is often the first limit hit. The +Like other OS's, the listen queue is often the first limit hit. The following are comments from "Aaron Gifford <agifford@InfoWest.COM>" on how to fix this on BSDI 1.x, 2.x, and FreeBSD 2.0 (and earlier): -

      +

      Edit the following two files: -

      /usr/include/sys/socket.h
      - /usr/src/sys/sys/socket.h
      +
      /usr/include/sys/socket.h
      + /usr/src/sys/sys/socket.h
      In each file, look for the following: -
      +
           /*
      * Maximum queue length specifiable by listen.
      */
     #define SOMAXCONN       5
-
      
+
      Just change the "5" to whatever appears to work. I bumped the two machines I was having problems with up to 32 and haven't noticed the problem since. -

      +

      After the edit, recompile the kernel and recompile the Apache server then reboot. @@ -48,27 +48,27 @@ then reboot. FreeBSD 2.1 seems to be perfectly happy, with SOMAXCONN set to 32 already. -

      +

      -Addendum for very heavily loaded BSD servers
      +Addendum for very heavily loaded BSD servers
       from Chuck Murcko <chuck@telebase.com> -

      +

      If you're running a really busy BSD Apache server, the following are useful -things to do if the system is acting sluggish:

      +things to do if the system is acting sluggish:

      -

        +
          -
        • Run vmstat to check memory usage, page/swap rates, etc. +
        • Run vmstat to check memory usage, page/swap rates, etc. -
        • Run netstat -m to check mbuf usage +
        • Run netstat -m to check mbuf usage -
        • Run fstat to check file descriptor usage +
        • Run fstat to check file descriptor usage -
        +
      These utilities give you an idea what you'll need to tune in your kernel, and whether it'll help to buy more RAM. @@ -78,36 +78,36 @@ FreeBSD and other 4.4-lite derivatives) from a system getting heavy usage. The tools mentioned above were used, and the system memory was increased to 48 MB before these tuneups. Other system parameters remained unchanged. -

      +

      -

      +
       maxusers        256
-
      
+
      -Maxusers drives a lot of other kernel parameters: +Maxusers drives a lot of other kernel parameters: -
        +
          -
        • Maximum # of processes +
        • Maximum # of processes -
        • Maximum # of processes per user +
        • Maximum # of processes per user -
        • System wide open files limit +
        • System wide open files limit -
        • Per-process open files limit +
        • Per-process open files limit -
        • Maximum # of mbuf clusters +
        • Maximum # of mbuf clusters -
        • Proc/pgrp hash table size +
        • Proc/pgrp hash table size -
        +
      The actual formulae for these derived parameters are in -/usr/src/sys/conf/param.c. +/usr/src/sys/conf/param.c. These calculated parameters can also be overridden (in part) by specifying your own values in the kernel configuration file: -
      +
       # Network options. NMBCLUSTERS defines the number of mbuf clusters and
 # defaults to 256. This machine is a server that handles lots of traffic,
 # so we crank that value.
@@ -119,13 +119,13 @@ options         NMBCLUSTERS=4096        # mbuf clusters at 4096
 #
 options         CHILD_MAX=512           # maximum number of child processes
 options         OPEN_MAX=512            # maximum fds (breaks RPC svcs)
-
      
+
      SOMAXCONN is not derived from maxusers, so you'll always need to increase that yourself. We used a value guaranteed to be larger than Apache's default for the listen() of 128, currently. -

      +

      In many cases, NMBCLUSTERS must be set much larger than would appear necessary at first glance. The reason for this is that if the browser @@ -137,10 +137,10 @@ this state doesn't time out on the server, and the browser never sent a final FIN. For more details see the FIN_WAIT_2 page. -

      +

      Some more info on mbuf clusters (from sys/mbuf.h): -

      +
       /*
  * Mbufs are of a single size, MSIZE (machine/machparam.h), which
  * includes overhead.  An mbuf may add a single "mbuf cluster" of size
@@ -148,9 +148,9 @@ Some more info on mbuf clusters (from sys/mbuf.h):
  * and is used instead of the internal data area; this is done when
  * at least MINCLSIZE of data must be stored.
  */
-
      
+
      -

      +

      CHILD_MAX and OPEN_MAX are set to allow up to 512 child processes (different than the maximum value for processes per user ID) and file descriptors. @@ -160,19 +160,19 @@ files). If you've got a lot of other activity besides httpd on the same machine, you'll have to set NPROC higher still. In this example, the NPROC value derived from maxusers proved sufficient for our load. -

      +

      -Caveats +Caveats -

      +

      Be aware that your system may not boot with a kernel that is configured -to use more resources than you have available system RAM. ALWAYS +to use more resources than you have available system RAM. ALWAYS have a known bootable kernel available when tuning your system this way, and use the system tools beforehand to learn if you need to buy more memory before tuning. -

      +

      RPC services will fail when the value of OPEN_MAX is larger than 256. This is a function of the original implementations of the RPC library, @@ -180,21 +180,21 @@ which used a byte value for holding file descriptors. BSDI has partially addressed this limit in its 2.1 release, but a real fix may well await the redesign of RPC itself. -

      +

      Finally, there's the hard limit of child processes configured in Apache. -

      +

      For versions of Apache later than 1.0.5 you'll need to change the -definition for HARD_SERVER_LIMIT in httpd.h and recompile +definition for HARD_SERVER_LIMIT in httpd.h and recompile if you need to run more than the default 150 instances of httpd. -

      +

      From conf/httpd.conf-dist: -

      +
       # Limit on total number of servers running, i.e., limit on the number
 # of clients who can simultaneously connect --- if this limit is ever
 # reached, clients will be LOCKED OUT, so it should NOT BE SET TOO LOW.
@@ -202,35 +202,35 @@ From conf/httpd.conf-dist:
 # Unix with it as it spirals down...
 
 MaxClients 150
-
      
+
      Know what you're doing if you bump this value up, and make sure you've done your system monitoring, RAM expansion, and kernel tuning beforehand. Then you're ready to service some serious hits! -

      +

      -Thanks to Tony Sanders and Chris Torek at BSDI for their +Thanks to Tony Sanders and Chris Torek at BSDI for their helpful suggestions and information.

      "M. Teterin" <mi@ALDAN.ziplink.net> writes:

      -

      It really does help if your kernel and frequently used utilities +
      It really does help if your kernel and frequently used utilities are fully optimized. Rebuilding the FreeBSD kernel on an AMD-133 (486-class CPU) web-server with
      - -m486 -fexpensive-optimizations -fomit-frame-pointer -O2
      + -m486 -fexpensive-optimizations -fomit-frame-pointer -O2
      helped reduce the number of "unable" errors, because the CPU was -often maxed out.
      +often maxed out.

      More welcome!

      -If you have tips to contribute, send mail to brian@organic.com +If you have tips to contribute, send mail to brian@organic.com - + diff --git a/docs/manual/platform/perf-dec.html b/docs/manual/platform/perf-dec.html index 8b5b940264..67eed58ff1 100644 --- a/docs/manual/platform/perf-dec.html +++ b/docs/manual/platform/perf-dec.html @@ -32,10 +32,10 @@ Date: Fri, 28 Jun 96 16:07:56 MDT
      mechanism.
    • Patch ID OSF350-146 has been superseded by -
      +
      Patch ID OSF350-195 for V3.2C
      Patch ID OSF360-350195 for V3.2D -
      +
      Patch IDs for V3.2E and V3.2F should be available soon. There is no known reason why the Patch ID OSF360-350195 won't work on these releases, but such use is not officially diff --git a/docs/manual/platform/perf-hp.html b/docs/manual/platform/perf-hp.html index 23ab1c250a..606b08151c 100644 --- a/docs/manual/platform/perf-hp.html +++ b/docs/manual/platform/perf-hp.html @@ -1,8 +1,8 @@ - - -Running a High-Performance Web Server on HPUX - + + +Running a High-Performance Web Server on HPUX + . If folks are running Apache on a PA-8000 based system, they should consider "chatr'ing" the Apache executable to have a large page size. -This would be "chatr +pi L ." The GID of the running executable +This would be "chatr +pi L ." The GID of the running executable must have MLOCK privileges. Setprivgrp(1m) should be consulted for assigning MLOCK. The change can be validated by running Glance and examining the memory regions of the server(s) to make sure that they @@ -120,5 +120,5 @@ http://www.cup.hp.com/netperf/NetperfPage.html Index Home - + diff --git a/docs/manual/platform/perf.html b/docs/manual/platform/perf.html index f0af157c06..b0188b50d1 100644 --- a/docs/manual/platform/perf.html +++ b/docs/manual/platform/perf.html @@ -1,8 +1,8 @@ - - -Hints on Running a High-Performance Web Server - + + +Hints on Running a High-Performance Web Server + If you are running Apache on A/UX, a page that gives some helpful -performance hints (concerning the listen() queue and using +performance hints (concerning the listen() queue and using virtual hosts) can be found here @@ -78,9 +78,9 @@ where the whole server will appear to freeze for a couple of minutes at a time, and then come back to life. This has been traced to a listen() queue overload - certain Linux implementations have a low value set for the incoming connection queue which can cause problems. -Please see our Using Apache on -Linux page for more info on how to fix this. +Please see our Using Apache on +Linux page for more info on how to fix this.

      @@ -100,9 +100,9 @@ Other links:
        -
      • +
      • World Wide Web Server Performance, -<http://www.sun.com/sun-on-net/performance.html> +<http://www.sun.com/sun-on-net/performance.html>
      • Solaris 2.x - tuning your TCP/IP stack contains some good technical information about tuning various Solaris TCP/IP parameters. @@ -122,9 +122,9 @@ http://www.islandnet.com/~mark/somaxconn.html.

        More welcome!

        -If you have tips to contribute, send mail to brian@organic.com +If you have tips to contribute, send mail to brian@organic.com - + diff --git a/docs/manual/platform/unixware.html b/docs/manual/platform/unixware.html index eb8adbe2fe..458104a9d0 100644 --- a/docs/manual/platform/unixware.html +++ b/docs/manual/platform/unixware.html @@ -23,16 +23,16 @@ bind errors, and accept errors, to name a few.

        UnixWare 1.x

        Make sure that USE_FCNTL_SERIALIZE_ACCEPT is defined (if not -defined by Apache autoconfiguration). If using the UnixWare cc +defined by Apache autoconfiguration). If using the UnixWare cc compiler, and you still see accept() errors, don't use compiler optimization, -or get gcc. +or get gcc.

        UnixWare 2.0.x

        -SCO patch tf2163 is required +SCO patch tf2163 is required in order for Apache to work correctly on UnixWare 2.0.x. See -http://www.sco.com -for UnixWare patch information.

        +http://www.sco.com +for UnixWare patch information.

        In addition, make sure that USE_FCNTL_SERIALIZE_ACCEPT is defined (if not defined by Apache autoconfiguration). To reduce instances of connections @@ -41,20 +41,20 @@ only).

        UnixWare 2.1.x

        -SCO patch ptf3123 is required +SCO patch ptf3123 is required in order for Apache to work correctly on UnixWare 2.1.x. See -http://www.sco.com -for UnixWare patch information.

        +http://www.sco.com +for UnixWare patch information.

        -NOTE: Unixware 2.1.2 and later already have patch ptf3123 included

        +NOTE: Unixware 2.1.2 and later already have patch ptf3123 included

        In addition, make sure that USE_FCNTL_SERIALIZE_ACCEPT is defined (if not defined by Apache autoconfiguration). To reduce instances of connections in FIN_WAIT_2 state, you may also want to define NO_LINGCLOSE (Apache 1.2 -only).

        +only).

        Thanks to Joe Doupnik <JRD@cc.usu.edu> and Rich Vaughn -<rvaughn@aad.com> for additional info for UnixWare builds.

        +<rvaughn@aad.com> for additional info for UnixWare builds.

        diff --git a/docs/manual/platform/windows.html b/docs/manual/platform/windows.html index 1f1758d92d..19a06c0cd5 100644 --- a/docs/manual/platform/windows.html +++ b/docs/manual/platform/windows.html @@ -16,215 +16,215 @@

        Using Apache With Microsoft Windows

        -

        This document explains how to compile, install, configure and run +

        This document explains how to compile, install, configure and run Apache 1.3b3 (or later) under Microsoft Windows. Please note that at this time, Windows support is entirely experimental, and is recommended only for experienced users. The Apache Group does not guarantee that this software will work as documented, or even at all. If you find any bugs, or wish to contribute in other ways, please - use our bug reporting - page.

        + use our bug reporting + page.

        -

        Warning: Apache on NT has not yet been optimized for performance. +

        Warning: Apache on NT has not yet been optimized for performance. Apache still performs best, and is most reliable on Unix platforms. Over time we will improve NT performance. Folks doing comparative reviews of webserver performance are asked to compare against Apache -on a Unix platform such as Solaris, FreeBSD, or Linux.

        +on a Unix platform such as Solaris, FreeBSD, or Linux.

        -
        +
        - + -
        +
        -

        Requirements

        +

        Requirements

        -

        Apache 1.3b3 requires the following:

        +

        Apache 1.3b3 requires the following:

        -
          -
        • Microsoft Windows NT 4.0*, or Windows 95. -
        • An Intel-based PC-compatible capable of running above OS (exact +
            +
          • Microsoft Windows NT 4.0*, or Windows 95. +
          • An Intel-based PC-compatible capable of running above OS (exact requirements unknown) with a connection to a TCP/IP network. -
          • Microsoft Visual C++ 5.0 or later. -
          +
        • Microsoft Visual C++ 5.0 or later. +
        -

        * Apache may run with Windows NT 3.5.1, but - has not been tested.

        +

        * Apache may run with Windows NT 3.5.1, but + has not been tested.

        -

        This documentation assumes good working knowledge of Microsoft +

        This documentation assumes good working knowledge of Microsoft Windows, Microsoft Visual C++, and the Apache web server (for - Unix).

        + Unix).

        -

        Downloading Apache for Windows

        +

        Downloading Apache for Windows

        -

        Information on the latest version of Apache can be found on the Apache +

        Information on the latest version of Apache can be found on the Apache web server at http://www.apache.org/. This will list the current release, any more recent alpha or beta-test release, -together with details of mirror web and anonymous ftp sites.

        +together with details of mirror web and anonymous ftp sites.

        -

        You can download Apache 1.3b3 in two different forms: an InstallShield-based - .exe file which contains the precompiled binary, and a - .tar.gz which contains the source code (and is also the +

        You can download Apache 1.3b3 in two different forms: an InstallShield-based + .exe file which contains the precompiled binary, and a + .tar.gz which contains the source code (and is also the regular Unix distribution). -

        Compiling Apache for Windows

        +

        Compiling Apache for Windows

        -

        Compiling Apache requires Microsoft Visual C++ 5.0 to be properly +

        Compiling Apache requires Microsoft Visual C++ 5.0 to be properly installed. It is easiest to compile with the command-line tools (nmake, etc...). Consult the VC++ manual to determine how to install - them.

        + them.

        -

        First, unpack the Apache distribution into an appropriate +

        First, unpack the Apache distribution into an appropriate directory. Open a command-line prompt, and change to the - src subdirectory of the Apache distribution.

        + src subdirectory of the Apache distribution.

        -

        The master Apache makefile instructions are contained in the - Makefile.nt file. To compile Apache, simply use one of +

        The master Apache makefile instructions are contained in the + Makefile.nt file. To compile Apache, simply use one of the following commands: -

          -
        • nmake /f Makefile.nt _apacher (release build) -
        • nmake /f Makefile.nt _apached (debug build) -
        +
          +
        • nmake /f Makefile.nt _apacher (release build) +
        • nmake /f Makefile.nt _apached (debug build) +
        -

        These will both compile Apache. The latter will include debugging +

        These will both compile Apache. The latter will include debugging information in the resulting files, making it easier to find bugs and - track down problems.

        + track down problems.

        -

        Apache can also be compiled using VC++'s Visual Studio development +

        Apache can also be compiled using VC++'s Visual Studio development environment. Although compiling Apache in this manner is not as simple, it makes it possible to easily modify the Apache source, or to compile - Apache if the command-line tools are not installed.

        + Apache if the command-line tools are not installed.

        -

        Project files (.DSP) are included for each of the +

        Project files (.DSP) are included for each of the portions of Apache. The three projects that are necessary for - Apache to run are Apache.dsp, - ApacheCore.dsp and - os/win32/ApacheOS.dsp. The regular expression library - in regex also need to be compiled using the supplied - makefile. The src/win32 subdirectory contains project - files for the optional modules (see below).

        + Apache to run are Apache.dsp, + ApacheCore.dsp and + os/win32/ApacheOS.dsp. The regular expression library + in regex also need to be compiled using the supplied + makefile. The src/win32 subdirectory contains project + files for the optional modules (see below).

        -

        Installing Apache for Windows

        +

        Installing Apache for Windows

        -

        Once Apache has been compiled, it needs to be installed in its server - root directory. The hard-coded default is the \Apache +

        Once Apache has been compiled, it needs to be installed in its server + root directory. The hard-coded default is the \Apache directory, on the current hard drive. Another directory may be used, - but the files will need to be installed manually.

        + but the files will need to be installed manually.

        -

        To install the files into the \Apache directory - automatically, use one the following nmake commands (see above):

        -
          -
        • nmake /f Makefile.nt installr (for release build) -
        • nmake /f Makefile.nt installd (for debug build) -
        +

        To install the files into the \Apache directory + automatically, use one the following nmake commands (see above):

        +
          +
        • nmake /f Makefile.nt installr (for release build) +
        • nmake /f Makefile.nt installd (for debug build) +
        -

        This will install the following:

        +

        This will install the following:

        -
          -
        • \Apache\Apache.exe - Apache executable -
        • \Apache\ApacheCore.dll - Main Apache shared library -
        • \Apache\modules\ApacheModule*.dll - Optional Apache +
            +
          • \Apache\Apache.exe - Apache executable +
          • \Apache\ApacheCore.dll - Main Apache shared library +
          • \Apache\modules\ApacheModule*.dll - Optional Apache modules (7 files) -
          • \Apache\conf - Empty configuration directory -
          • \Apache\logs - Empty logging directory -
          +
        • \Apache\conf - Empty configuration directory +
        • \Apache\logs - Empty logging directory +
        -

        If you do not have nmake, or wish to install in a different directory, - be sure to use a similar naming scheme.

        +

        If you do not have nmake, or wish to install in a different directory, + be sure to use a similar naming scheme.

        -

        Using Apache for Windows

        +

        Using Apache for Windows

        -

        The first step is to set up Apache's configuration files. Default - configuration files for Windows are located in the conf +

        The first step is to set up Apache's configuration files. Default + configuration files for Windows are located in the conf subdirectory in the Apache distribution, and are named - httpd.conf-dist-win, access.conf-dist-win - and srm.conf-dist-win. Move these into - \Apache\conf, and rename them httpd.conf, - access.conf and srm.conf, respectively.

        + httpd.conf-dist-win, access.conf-dist-win + and srm.conf-dist-win. Move these into + \Apache\conf, and rename them httpd.conf, + access.conf and srm.conf, respectively.

        -

        Configuring Apache is nearly identical to the Unix version of Apache, - so most of the standard Apache documentation is - applicable. A few things are, however, different, or new:

        +

        Configuring Apache is nearly identical to the Unix version of Apache, + so most of the standard Apache documentation is + applicable. A few things are, however, different, or new:

        -
          -

        • Because Apache for Windows is multithreaded, it does not use a +

            +

          • Because Apache for Windows is multithreaded, it does not use a separate process for each request, as Apache does with Unix. Therefore, the "process"-management directives are different: -

            StartServers - This +

            StartServers - This tells the server how many processes to use. Unlike Unix, there will never be more than this number, and only one will be used at a time (the others will be held in reserve in case the main processes crashes or otherwise dies). The recommended default is - StartServers 3. -

            MaxRequestsPerChild + StartServers 3. +

            MaxRequestsPerChild - Like the Unix directive, this controls how many requests a process will serve before exiting. However, unlike Unix, a process serves all the requests at once, not just one, so if this is set, it is recommended that a very high number is - used. The recommended default, MaxRequestsPerChild - 0, does not cause the process to ever exit. -

            ThreadsPerChild - + used. The recommended default, MaxRequestsPerChild + 0, does not cause the process to ever exit. +

            ThreadsPerChild - This directive is new, and tells the server how many threads it should use. This is the maximum number of connections the server can handle at once; be sure and set this number high enough for your site if you get a lot of hits. The recommended default is - ThreadsPerChild 50.

            -

          • The directives that accept filenames as arguments now must use + ThreadsPerChild 50.

            +

          • The directives that accept filenames as arguments now must use Windows filenames instead of Unix ones. However, because Apache uses Unix-style names internally, you must use forward slashes, not backslashes. Drive letters can be used; if omitted, the drive with - the Apache executable will be assumed.

            -

          • Apache for Windows contains the ability to load modules at runtime, + the Apache executable will be assumed.

            +

          • Apache for Windows contains the ability to load modules at runtime, without recompiling the server. If Apache is compiled normally, it will install a number of optional modules in the - \Apache\modules directory. To activate these, or other - modules, the new LoadModule + \Apache\modules directory. To activate these, or other + modules, the new LoadModule directive must be used. For example, to active the status module, use the following (in addition to the status-activating directives - in access.conf):

            -
            +      in access.conf):
            
+
                 LoadModule status_module modules/ApacheModuleStatus.dll
-
            
-      
            Information on creating module
-         DLLs is also available.
            
-  
          • Apache can also load ISAPI Extensions (i.e., Internet Server
+
            • +

            Information on creating module + DLLs is also available.

            +

          • Apache can also load ISAPI Extensions (i.e., Internet Server Applications), such as those used by Microsoft's IIS, and other - Windows servers. More information - is available. -

          - -

          Once Apache is configured correctly, it is nearly ready to be -run. However, we recommend you copy the icons and -htdocs subdirectories from the Apache distribution to -\Apache. The latter is especially important, as it contains + Windows servers. More information + is available. +

        + +

        Once Apache is configured correctly, it is nearly ready to be +run. However, we recommend you copy the icons and +htdocs subdirectories from the Apache distribution to +\Apache. The latter is especially important, as it contains the document root (what the server actually serves). -

        Apache can be executed in one of two ways, directly from the command +

        Apache can be executed in one of two ways, directly from the command line, or as a Windows NT service. To run it from the command line, use the following command: -

        -    C:\Apache> apache -s
-
        - -

        Apache will then execute, and will remain running until it is - exited. To use Apache as a Windows NT service, use the following:

        -
        -    C:\Apache> apache -i
-
        -

        Then open the Services control panel, and start the Apache service.

        - -

        If you installed Apache in a server root other than - \Apache, you must use the -f command-line - option to specify the httpd.conf file, or the -d option - to specify the server root.

        +
        +    C:\Apache> apache -s
+
        + +

        Apache will then execute, and will remain running until it is + exited. To use Apache as a Windows NT service, use the following:

        +
        +    C:\Apache> apache -i
+
        +

        Then open the Services control panel, and start the Apache service.

        + +

        If you installed Apache in a server root other than + \Apache, you must use the -f command-line + option to specify the httpd.conf file, or the -d option + to specify the server root.

        diff --git a/docs/manual/process-model.html b/docs/manual/process-model.html index 9e27192fef..74f7d4e6eb 100644 --- a/docs/manual/process-model.html +++ b/docs/manual/process-model.html @@ -63,6 +63,6 @@ Apache uses
- + diff --git a/docs/manual/sections.html b/docs/manual/sections.html index 6951e7cdbe..b5cce17df2 100644 --- a/docs/manual/sections.html +++ b/docs/manual/sections.html @@ -1,7 +1,7 @@ - -How Directory, Location and Files sections work - + +How Directory, Location and Files sections work + -

How Directory, Location and Files sections work

+

How Directory, Location and Files sections work

-The sections <Directory>, <Location> and <Files> can contain +The sections <Directory>, <Location> and <Files> can contain directives which only apply to specified directories, URLs or files respectively. Also htaccess files can be used inside a directory to apply directives to that directory. This document explains how these @@ -28,112 +28,112 @@ request URL.

Directives allowed in the sections

Everything that is syntactically allowed in -<Directory> is also allowed in -<Location> (except a sub-<Files> +<Directory> is also allowed in +<Location> (except a sub-<Files> section, but the code doesn't test for that, Lars has an open bug report on that). Semantically however some things, and the most notable is AllowOverrides, make no sense in -<Location>. The same for -<Files> -- syntactically everything is fine, but +<Location>. The same for +<Files> -- syntactically everything is fine, but semantically some things are different.

How the sections are merged

The order of merging is: -
    +
      -
    1. +
    2. - <Directory> (except regular expressions) and + <Directory> (except regular expressions) and .htaccess done simultaneously (with .htaccess overriding - <Directory>) + <Directory>) -
      3. + -
    3. - <DirectoryMatch>, and - <Directory> with regular expressions +
    4. + <DirectoryMatch>, and + <Directory> with regular expressions -
      5. + -
    5. <Files> and <FilesMatch> done simultaneously -
      6. +
    6. <Files> and <FilesMatch> done simultaneously +
      7. -
    7. <Location> and <LocationMatch> done simultaneously -
      8. +
    8. <Location> and <LocationMatch> done simultaneously +
      9. -
    +
-Apart from <Directory>, each group is processed in +Apart from <Directory>, each group is processed in the order that they appear in the configuration -files. <Directory> (group 1 above) is processed in +files. <Directory> (group 1 above) is processed in the order shortest directory component to longest. If multiple -<Directory> sections apply to the same directory +<Directory> sections apply to the same directory they they are processed in the configuration file order. The configuration files are read in the order httpd.conf, srm.conf and -access.conf. Configurations included via the Include +access.conf. Configurations included via the Include directive will be treated as if they where inside the including file -at the location of the Include directive. +at the location of the Include directive. -

+

-Sections inside <VirtualHost> sections are applied -after the corresponding sections outside the virtual host +Sections inside <VirtualHost> sections are applied +after the corresponding sections outside the virtual host definition. This allows virtual hosts to override the main server configuration. (Note: this only works correctly from 1.2.2 and 1.3a2 onwards. Before those releases sections inside virtual hosts were -applied before the main server). +applied before the main server).

Notes about using sections

The general guidelines are: -

+

-

    -
  • +
      +
    • If you are attempting to match objects at the filesystem level - then you must use <Directory> and/or - <Files>. -
      • + then you must use <Directory> and/or + <Files>. + -
    • +
    • If you are attempting to match objects at the URL level then you - must use <Location> -
      • -
    + must use <Location> +
    • +
But a notable exception is: -
    -
  • - proxy control is done via <Directory>. This is +
      +
    • + proxy control is done via <Directory>. This is a legacy mistake because the proxy existed prior to - <Location>. A future version of the config + <Location>. A future version of the config language should probably switch this to - <Location>. -
      • -
    + <Location>. +
    • +
Note also that modifying .htaccess parsing during Location doesn't do anything because .htaccess parsing has already occurred. -

+

Another note: -

+

-

    -
  • +
      +
    • There is actually a - <Location>/<LocationMatch> + <Location>/<LocationMatch> sequence performed just before the name translation phase (where - Aliases and DocumentRoots are used to + Aliases and DocumentRoots are used to map URLs to filenames). The results of this sequence are completely thrown away after the translation has completed. -
      • -
    +
    • +
- + diff --git a/docs/manual/sections.html.en b/docs/manual/sections.html.en index 6951e7cdbe..b5cce17df2 100644 --- a/docs/manual/sections.html.en +++ b/docs/manual/sections.html.en @@ -1,7 +1,7 @@ - -How Directory, Location and Files sections work - + +How Directory, Location and Files sections work + -

How Directory, Location and Files sections work

+

How Directory, Location and Files sections work

-The sections <Directory>, <Location> and <Files> can contain +The sections <Directory>, <Location> and <Files> can contain directives which only apply to specified directories, URLs or files respectively. Also htaccess files can be used inside a directory to apply directives to that directory. This document explains how these @@ -28,112 +28,112 @@ request URL.

Directives allowed in the sections

Everything that is syntactically allowed in -<Directory> is also allowed in -<Location> (except a sub-<Files> +<Directory> is also allowed in +<Location> (except a sub-<Files> section, but the code doesn't test for that, Lars has an open bug report on that). Semantically however some things, and the most notable is AllowOverrides, make no sense in -<Location>. The same for -<Files> -- syntactically everything is fine, but +<Location>. The same for +<Files> -- syntactically everything is fine, but semantically some things are different.

How the sections are merged

The order of merging is: -
    +
      -
    1. +
    2. - <Directory> (except regular expressions) and + <Directory> (except regular expressions) and .htaccess done simultaneously (with .htaccess overriding - <Directory>) + <Directory>) -
      3. + -
    3. - <DirectoryMatch>, and - <Directory> with regular expressions +
    4. + <DirectoryMatch>, and + <Directory> with regular expressions -
      5. + -
    5. <Files> and <FilesMatch> done simultaneously -
      6. +
    6. <Files> and <FilesMatch> done simultaneously +
      7. -
    7. <Location> and <LocationMatch> done simultaneously -
      8. +
    8. <Location> and <LocationMatch> done simultaneously +
      9. -
    +
-Apart from <Directory>, each group is processed in +Apart from <Directory>, each group is processed in the order that they appear in the configuration -files. <Directory> (group 1 above) is processed in +files. <Directory> (group 1 above) is processed in the order shortest directory component to longest. If multiple -<Directory> sections apply to the same directory +<Directory> sections apply to the same directory they they are processed in the configuration file order. The configuration files are read in the order httpd.conf, srm.conf and -access.conf. Configurations included via the Include +access.conf. Configurations included via the Include directive will be treated as if they where inside the including file -at the location of the Include directive. +at the location of the Include directive. -

+

-Sections inside <VirtualHost> sections are applied -after the corresponding sections outside the virtual host +Sections inside <VirtualHost> sections are applied +after the corresponding sections outside the virtual host definition. This allows virtual hosts to override the main server configuration. (Note: this only works correctly from 1.2.2 and 1.3a2 onwards. Before those releases sections inside virtual hosts were -applied before the main server). +applied before the main server).

Notes about using sections

The general guidelines are: -

+

-

    -
  • +
      +
    • If you are attempting to match objects at the filesystem level - then you must use <Directory> and/or - <Files>. -
      • + then you must use <Directory> and/or + <Files>. + -
    • +
    • If you are attempting to match objects at the URL level then you - must use <Location> -
      • -
    + must use <Location> +
    • +
But a notable exception is: -
    -
  • - proxy control is done via <Directory>. This is +
      +
    • + proxy control is done via <Directory>. This is a legacy mistake because the proxy existed prior to - <Location>. A future version of the config + <Location>. A future version of the config language should probably switch this to - <Location>. -
      • -
    + <Location>. +
    • +
Note also that modifying .htaccess parsing during Location doesn't do anything because .htaccess parsing has already occurred. -

+

Another note: -

+

-

    -
  • +
      +
    • There is actually a - <Location>/<LocationMatch> + <Location>/<LocationMatch> sequence performed just before the name translation phase (where - Aliases and DocumentRoots are used to + Aliases and DocumentRoots are used to map URLs to filenames). The results of this sequence are completely thrown away after the translation has completed. -
      • -
    +
    • +
- + diff --git a/docs/manual/stopping.html b/docs/manual/stopping.html index 673d81beb3..d5c2e0d154 100644 --- a/docs/manual/stopping.html +++ b/docs/manual/stopping.html @@ -13,34 +13,34 @@ ALINK="#FF0000" > -

Stopping and Restarting Apache

+

Stopping and Restarting Apache

-

You will notice many httpd executables running on your system, +

You will notice many httpd executables running on your system, but you should not send signals to any of them except the parent, whose -pid is in the PidFile. That is to +pid is in the PidFile. That is to say you shouldn't ever need to send signals to any process except the parent. There are three signals that you can send the parent: -TERM, HUP, and USR1, which will +TERM, HUP, and USR1, which will be described in a moment. -

To send a signal to the parent you should issue a command such as: -

+
To send a signal to the parent you should issue a command such as:
+
     kill -TERM `cat /usr/local/apache/logs/httpd.pid`
-

+
You can read about its progress by issuing: -
+
     tail -f /usr/local/apache/logs/error_log
-

+
Modify those examples to match your -ServerRoot and -PidFile settings. +ServerRoot and +PidFile settings.

TERM Signal: stop now

-

Sending the TERM signal to the parent causes it to +

Sending the TERM signal to the parent causes it to immediately attempt to kill off all of its children. It may take it several seconds to complete killing off its children. Then the parent itself exits. Any requests in progress are terminated, and no @@ -48,67 +48,67 @@ further requests are served.

HUP Signal: restart now

-

Sending the HUP signal to the parent causes it to kill off -its children like in TERM but the parent doesn't exit. It +

Sending the HUP signal to the parent causes it to kill off +its children like in TERM but the parent doesn't exit. It re-reads its configuration files, and re-opens any log files. Then it spawns a new set of children and continues serving hits. -

Users of the -status module +

Users of the +status module will notice that the server statistics are -set to zero when a HUP is sent. +set to zero when a HUP is sent. -

Note: If your configuration file has errors in it when you issue a +

Note: If your configuration file has errors in it when you issue a restart then your parent will not restart, it will exit with an error. See below for a method of avoiding this.

USR1 Signal: graceful restart

-

Note: prior to release 1.2b9 this code is quite unstable and +

Note: prior to release 1.2b9 this code is quite unstable and shouldn't be used at all. -

The USR1 signal causes the parent process to advise +

The USR1 signal causes the parent process to advise the children to exit after their current request (or to exit immediately if they're not serving anything). The parent re-reads its configuration files and re-opens its log files. As each child dies off the parent -replaces it with a child from the new generation of the +replaces it with a child from the new generation of the configuration, which begins serving new requests immediately. -

This code is designed to always respect the -MaxClients, -MinSpareServers, -and MaxSpareServers settings. -Furthermore, it respects StartServers +

This code is designed to always respect the +MaxClients, +MinSpareServers, +and MaxSpareServers settings. +Furthermore, it respects StartServers in the following manner: if after one second at least StartServers new children have not been created, then create enough to pick up the slack. This is to say that the code tries to maintain both the number of children appropriate for the current load on the server, and respect your wishes with the StartServers parameter. -

Users of the -status module +

Users of the +status module will notice that the server statistics -are not set to zero when a USR1 is sent. The code +are not set to zero when a USR1 is sent. The code was written to both minimize the time in which the server is unable to serve new requests (they will be queued up by the operating system, so they're not lost in any event) and to respect your tuning parameters. In order -to do this it has to keep the scoreboard used to keep track +to do this it has to keep the scoreboard used to keep track of all children across generations. -

The status module will also use a G to indicate those +

The status module will also use a G to indicate those children which are still serving requests started before the graceful restart was given. -

At present there is no way for a log rotation script using -USR1 to know for certain that all children writing the +

At present there is no way for a log rotation script using +USR1 to know for certain that all children writing the pre-restart log have finished. We suggest that you use a suitable delay -after sending the USR1 signal before you do anything with the +after sending the USR1 signal before you do anything with the old log. For example if most of your hits take less than 10 minutes to complete for users on low bandwidth links then you could wait 15 minutes before doing anything with the old log. -

Note: If your configuration file has errors in it when you issue a +

Note: If your configuration file has errors in it when you issue a restart then your parent will not restart, it will exit with an error. In the case of graceful restarts it will also leave children running when it exits. (These are @@ -124,7 +124,7 @@ error and the error should be fixed before issuing the graceful restart.

Appendix: signals and race conditions

-

Prior to Apache 1.2b9 there were several race conditions +

Prior to Apache 1.2b9 there were several race conditions involving the restart and die signals (a simple description of race condition is: a time-sensitive problem, as in if something happens at just the wrong time it won't behave as expected). For those architectures that @@ -132,11 +132,11 @@ have the "right" feature set we have eliminated as many as we can. But it should be noted that there still do exist race conditions on certain architectures. -

Architectures that use an on disk -ScoreBoardFile +

Architectures that use an on disk +ScoreBoardFile have the potential to corrupt their scoreboards. This can result in -the "bind: Address already in use" (after HUP) or -"long lost child came home!" (after USR1). The former is +the "bind: Address already in use" (after HUP) or +"long lost child came home!" (after USR1). The former is a fatal error, while the latter just causes the server to lose a scoreboard slot. So it might be advisable to use graceful restarts, with an occasional hard restart. These problems are very difficult to work @@ -144,13 +144,13 @@ around, but fortunately most architectures do not require a scoreboard file. See the ScoreBoardFile documentation for a method to determine if your architecture uses it. -

NEXT and MACHTEN (68k only) have small race +

NEXT and MACHTEN (68k only) have small race conditions which can cause a restart/die signal to be lost, but should not cause the server to do anything otherwise problematic. -

All architectures have a small race condition in each child involving +

All architectures have a small race condition in each child involving the second and subsequent requests on a persistent HTTP connection (KeepAlive). It may exit after reading the request line but before reading any of the request headers. There is a fix that was discovered diff --git a/docs/manual/stopping.html.en b/docs/manual/stopping.html.en index 673d81beb3..d5c2e0d154 100644 --- a/docs/manual/stopping.html.en +++ b/docs/manual/stopping.html.en @@ -13,34 +13,34 @@ ALINK="#FF0000" > -

Stopping and Restarting Apache

+

Stopping and Restarting Apache

-

You will notice many httpd executables running on your system, +

You will notice many httpd executables running on your system, but you should not send signals to any of them except the parent, whose -pid is in the PidFile. That is to +pid is in the PidFile. That is to say you shouldn't ever need to send signals to any process except the parent. There are three signals that you can send the parent: -TERM, HUP, and USR1, which will +TERM, HUP, and USR1, which will be described in a moment. -

To send a signal to the parent you should issue a command such as: -

+
To send a signal to the parent you should issue a command such as:
+
     kill -TERM `cat /usr/local/apache/logs/httpd.pid`
-

+
You can read about its progress by issuing: -
+
     tail -f /usr/local/apache/logs/error_log
-

+
Modify those examples to match your -ServerRoot and -PidFile settings. +ServerRoot and +PidFile settings.

TERM Signal: stop now

-

Sending the TERM signal to the parent causes it to +

Sending the TERM signal to the parent causes it to immediately attempt to kill off all of its children. It may take it several seconds to complete killing off its children. Then the parent itself exits. Any requests in progress are terminated, and no @@ -48,67 +48,67 @@ further requests are served.

HUP Signal: restart now

-

Sending the HUP signal to the parent causes it to kill off -its children like in TERM but the parent doesn't exit. It +

Sending the HUP signal to the parent causes it to kill off +its children like in TERM but the parent doesn't exit. It re-reads its configuration files, and re-opens any log files. Then it spawns a new set of children and continues serving hits. -

Users of the -status module +

Users of the +status module will notice that the server statistics are -set to zero when a HUP is sent. +set to zero when a HUP is sent. -

Note: If your configuration file has errors in it when you issue a +

Note: If your configuration file has errors in it when you issue a restart then your parent will not restart, it will exit with an error. See below for a method of avoiding this.

USR1 Signal: graceful restart

-

Note: prior to release 1.2b9 this code is quite unstable and +

Note: prior to release 1.2b9 this code is quite unstable and shouldn't be used at all. -

The USR1 signal causes the parent process to advise +

The USR1 signal causes the parent process to advise the children to exit after their current request (or to exit immediately if they're not serving anything). The parent re-reads its configuration files and re-opens its log files. As each child dies off the parent -replaces it with a child from the new generation of the +replaces it with a child from the new generation of the configuration, which begins serving new requests immediately. -

This code is designed to always respect the -MaxClients, -MinSpareServers, -and MaxSpareServers settings. -Furthermore, it respects StartServers +

This code is designed to always respect the +MaxClients, +MinSpareServers, +and MaxSpareServers settings. +Furthermore, it respects StartServers in the following manner: if after one second at least StartServers new children have not been created, then create enough to pick up the slack. This is to say that the code tries to maintain both the number of children appropriate for the current load on the server, and respect your wishes with the StartServers parameter. -

Users of the -status module +

Users of the +status module will notice that the server statistics -are not set to zero when a USR1 is sent. The code +are not set to zero when a USR1 is sent. The code was written to both minimize the time in which the server is unable to serve new requests (they will be queued up by the operating system, so they're not lost in any event) and to respect your tuning parameters. In order -to do this it has to keep the scoreboard used to keep track +to do this it has to keep the scoreboard used to keep track of all children across generations. -

The status module will also use a G to indicate those +

The status module will also use a G to indicate those children which are still serving requests started before the graceful restart was given. -

At present there is no way for a log rotation script using -USR1 to know for certain that all children writing the +

At present there is no way for a log rotation script using +USR1 to know for certain that all children writing the pre-restart log have finished. We suggest that you use a suitable delay -after sending the USR1 signal before you do anything with the +after sending the USR1 signal before you do anything with the old log. For example if most of your hits take less than 10 minutes to complete for users on low bandwidth links then you could wait 15 minutes before doing anything with the old log. -

Note: If your configuration file has errors in it when you issue a +

Note: If your configuration file has errors in it when you issue a restart then your parent will not restart, it will exit with an error. In the case of graceful restarts it will also leave children running when it exits. (These are @@ -124,7 +124,7 @@ error and the error should be fixed before issuing the graceful restart.

Appendix: signals and race conditions

-

Prior to Apache 1.2b9 there were several race conditions +

Prior to Apache 1.2b9 there were several race conditions involving the restart and die signals (a simple description of race condition is: a time-sensitive problem, as in if something happens at just the wrong time it won't behave as expected). For those architectures that @@ -132,11 +132,11 @@ have the "right" feature set we have eliminated as many as we can. But it should be noted that there still do exist race conditions on certain architectures. -

Architectures that use an on disk -ScoreBoardFile +

Architectures that use an on disk +ScoreBoardFile have the potential to corrupt their scoreboards. This can result in -the "bind: Address already in use" (after HUP) or -"long lost child came home!" (after USR1). The former is +the "bind: Address already in use" (after HUP) or +"long lost child came home!" (after USR1). The former is a fatal error, while the latter just causes the server to lose a scoreboard slot. So it might be advisable to use graceful restarts, with an occasional hard restart. These problems are very difficult to work @@ -144,13 +144,13 @@ around, but fortunately most architectures do not require a scoreboard file. See the ScoreBoardFile documentation for a method to determine if your architecture uses it. -

NEXT and MACHTEN (68k only) have small race +

NEXT and MACHTEN (68k only) have small race conditions which can cause a restart/die signal to be lost, but should not cause the server to do anything otherwise problematic. -

All architectures have a small race condition in each child involving +

All architectures have a small race condition in each child involving the second and subsequent requests on a persistent HTTP connection (KeepAlive). It may exit after reading the request line but before reading any of the request headers. There is a fix that was discovered diff --git a/docs/manual/suexec.html b/docs/manual/suexec.html index 90af9ad117..51df1dd5ff 100644 --- a/docs/manual/suexec.html +++ b/docs/manual/suexec.html @@ -268,11 +268,11 @@ suEXEC binary in its proper location, and configure Apache for use with suEXEC.

EDITING THE SUEXEC HEADER FILE
- From the top-level of the Apache source tree, type:   -cd support [ENTER] +cd support [ENTER]

-Edit the suexec.h file and change the following macros to +Edit the suexec.h file and change the following macros to match your local Apache installation.

@@ -347,7 +347,7 @@ match your local Apache installation. COMPILING THE SUEXEC WRAPPER
You now need to compile the suEXEC wrapper. At the shell command prompt, type:  cc suexec.c -o suexec [ENTER]. -This should create the suexec wrapper executable. +This should create the suexec wrapper executable.

@@ -373,7 +373,7 @@ info on this process.

COPYING THE SUEXEC BINARY TO ITS PROPER LOCATION
-Copy the suexec executable created in the +Copy the suexec executable created in the exercise above to the defined location for SUEXEC_BIN.

@@ -383,8 +383,8 @@ exercise above to the defined location for SUEXEC_BIN.

In order for the wrapper to set the user ID, it must me installed as owner -root and must have the setuserid execution bit -set for file modes. If you are not running a root +root and must have the setuserid execution bit +set for file modes. If you are not running a root user shell, do so now and execute the following commands.

@@ -420,16 +420,16 @@ your installation and try again.

One way to use suEXEC is through the -User and -Group directives in -VirtualHost +User and +Group directives in +VirtualHost definitions. By setting these directives to values different from the main server user ID, all requests for CGI resources will be executed as the User and Group defined for that <VirtualHost>. If only one or neither of these directives are specified for a <VirtualHost> then the main -server userid is assumed.

+server userid is assumed.

suEXEC can also be used to to execute CGI programs as the user to which the request is being directed. This is accomplished by @@ -437,7 +437,7 @@ using the ~ character prefixing the user ID for whom execution is desired. The only requirement needed for this feature to work is for CGI execution to be enabled for the user and that the script must meet the -scrutiny of the security checks above. +scrutiny of the security checks above.

BACK TO CONTENTS @@ -446,7 +446,7 @@ scrutiny of the security checks above.

Debugging suEXEC

The suEXEC wrapper will write log information to the location defined in -the suexec.h as indicated above. If you feel you have +the suexec.h as indicated above. If you feel you have configured and installed the wrapper properly, have a look at this log and the error_log for the server to see where you may have gone astray.

diff --git a/docs/manual/suexec.html.en b/docs/manual/suexec.html.en index 90af9ad117..51df1dd5ff 100644 --- a/docs/manual/suexec.html.en +++ b/docs/manual/suexec.html.en @@ -268,11 +268,11 @@ suEXEC binary in its proper location, and configure Apache for use with suEXEC.

EDITING THE SUEXEC HEADER FILE
- From the top-level of the Apache source tree, type:   -cd support [ENTER] +cd support [ENTER]

-Edit the suexec.h file and change the following macros to +Edit the suexec.h file and change the following macros to match your local Apache installation.

@@ -347,7 +347,7 @@ match your local Apache installation. COMPILING THE SUEXEC WRAPPER
You now need to compile the suEXEC wrapper. At the shell command prompt, type:  cc suexec.c -o suexec [ENTER]. -This should create the suexec wrapper executable. +This should create the suexec wrapper executable.

@@ -373,7 +373,7 @@ info on this process.

COPYING THE SUEXEC BINARY TO ITS PROPER LOCATION
-Copy the suexec executable created in the +Copy the suexec executable created in the exercise above to the defined location for SUEXEC_BIN.

@@ -383,8 +383,8 @@ exercise above to the defined location for SUEXEC_BIN.

In order for the wrapper to set the user ID, it must me installed as owner -root and must have the setuserid execution bit -set for file modes. If you are not running a root +root and must have the setuserid execution bit +set for file modes. If you are not running a root user shell, do so now and execute the following commands.

@@ -420,16 +420,16 @@ your installation and try again.

One way to use suEXEC is through the -User and -Group directives in -VirtualHost +User and +Group directives in +VirtualHost definitions. By setting these directives to values different from the main server user ID, all requests for CGI resources will be executed as the User and Group defined for that <VirtualHost>. If only one or neither of these directives are specified for a <VirtualHost> then the main -server userid is assumed.

+server userid is assumed.

suEXEC can also be used to to execute CGI programs as the user to which the request is being directed. This is accomplished by @@ -437,7 +437,7 @@ using the ~ character prefixing the user ID for whom execution is desired. The only requirement needed for this feature to work is for CGI execution to be enabled for the user and that the script must meet the -scrutiny of the security checks above. +scrutiny of the security checks above.

BACK TO CONTENTS @@ -446,7 +446,7 @@ scrutiny of the security checks above.

Debugging suEXEC

The suEXEC wrapper will write log information to the location defined in -the suexec.h as indicated above. If you feel you have +the suexec.h as indicated above. If you feel you have configured and installed the wrapper properly, have a look at this log and the error_log for the server to see where you may have gone astray.

diff --git a/docs/manual/vhosts/details.html b/docs/manual/vhosts/details.html index e64973edd7..e0792c3aba 100644 --- a/docs/manual/vhosts/details.html +++ b/docs/manual/vhosts/details.html @@ -1,7 +1,7 @@ - -An In-Depth Discussion of Virtual Host Matching - + +An In-Depth Discussion of Virtual Host Matching + -

An In-Depth Discussion of Virtual Host Matching

+

An In-Depth Discussion of Virtual Host Matching

-

The virtual host code was completely rewritten in Apache 1.3. +

The virtual host code was completely rewritten in Apache 1.3. This document attempts to explain exactly what Apache does when deciding what virtual host to serve a hit from. With the help of the new NameVirtualHost directive virtual host configuration should be a lot easier and safer than with versions prior to 1.3. -

If you just want to make it work without understanding -how, here are some examples. +

If you just want to make it work without understanding +how, here are some examples.

Config File Parsing

-

There is a main_server which consists of all +

There is a main_server which consists of all the definitions appearing outside of <VirtualHost> sections. There are virtual servers, called vhosts, which are defined by <VirtualHost> sections. -

The directives +

The directives Port, ServerName, ServerPath, @@ -42,25 +42,25 @@ can appear anywhere within the definition of a server. However, each appearance overrides the previous appearance (within that server). -

The default value of the Port field for main_server -is 80. The main_server has no default ServerPath, or -ServerAlias. The default ServerName is +

The default value of the Port field for main_server +is 80. The main_server has no default ServerPath, or +ServerAlias. The default ServerName is deduced from the servers IP address. -

The main_server Port directive has two functions due to legacy +

The main_server Port directive has two functions due to legacy compatibility with NCSA configuration files. One function is to determine the default network port Apache will bind to. This default is overridden by the existence of any -Listen directives. +Listen directives. The second function is to specify the port number which is used in absolute URIs during redirects. -

Unlike the main_server, vhost ports do not affect what +

Unlike the main_server, vhost ports do not affect what ports Apache listens for connections on. -

Each address appearing in the VirtualHost directive +

Each address appearing in the VirtualHost directive can have an optional port. If the port is unspecified it defaults to -the value of the main_server's most recent Port statement. +the value of the main_server's most recent Port statement. The special port * indicates a wildcard that matches any port. Collectively the entire set of addresses (including multiple A record @@ -70,22 +70,22 @@ results from DNS lookups) are called the vhost's address set. directive is used for a specific IP address the first vhost with that address is treated as an IP-based vhost. -

If name-based vhosts should be used a NameVirtualHost -directive must appear with the IP address set to be used for the +

If name-based vhosts should be used a NameVirtualHost +directive must appear with the IP address set to be used for the name-based vhosts. In other words, you must specify the IP address that holds the hostname aliases (CNAMEs) for your name-based vhosts via a -NameVirtualHost directive in your configuration file. +NameVirtualHost directive in your configuration file. -

Multiple NameVirtualHost directives can be used each -with a set of VirtualHost directives. +

Multiple NameVirtualHost directives can be used each +with a set of VirtualHost directives. -

The ordering of NameVirtualHost and -VirtualHost directives is not important which makes the +

The ordering of NameVirtualHost and +VirtualHost directives is not important which makes the following two examples identical (only the order of the -VirtualHost directives for one address set +VirtualHost directives for one address set is important, see below): -

+
                                 |
   NameVirtualHost 111.22.33.44  | <VirtualHost 111.22.33.44>
   <VirtualHost 111.22.33.44>    | # server A
@@ -107,58 +107,58 @@ is important, see below):
   ... 			        | NameVirtualHost 111.22.33.55
   </VirtualHost>	        |
                                 |
-

+
-

(To aid the readability of your configuration you should prefer the +

(To aid the readability of your configuration you should prefer the left variant.) -

After parsing the VirtualHost directive, the vhost server -is given a default Port equal to the port assigned to the -first name in its VirtualHost directive. +

After parsing the VirtualHost directive, the vhost server +is given a default Port equal to the port assigned to the +first name in its VirtualHost directive. -

The complete list of names in the VirtualHost directive -are treated just like a ServerAlias (but are not overridden by any -ServerAlias statement) if all names resolve to the same address set. -Note that subsequent Port statements for this vhost will not affect +

The complete list of names in the VirtualHost directive +are treated just like a ServerAlias (but are not overridden by any +ServerAlias statement) if all names resolve to the same address set. +Note that subsequent Port statements for this vhost will not affect the ports assigned in the address set. -

During initialization a list for each IP address +

During initialization a list for each IP address is generated an inserted into an hash table. If the IP address is -used in a NameVirtualHost directive the list contains +used in a NameVirtualHost directive the list contains all name-based vhosts for the given IP address. If there are no -vhosts defined for that address the NameVirtualHost directive +vhosts defined for that address the NameVirtualHost directive is ignored and an error is logged. For an IP-based vhost the list in the hash table is empty. -

Due to a fast hashing function the overhead of hashing an IP address +

Due to a fast hashing function the overhead of hashing an IP address during a request is minimal and almost not existent. Additionally the table is optimized for IP addresses which vary in the last octet. -

For every vhost various default values are set. In particular: - -

    -
  1. If a vhost has no - ServerAdmin, - ResourceConfig, - AccessConfig, - Timeout, - KeepAliveTimeout, - KeepAlive, - MaxKeepAliveRequests, +

    For every vhost various default values are set. In particular: + +

      +
    1. If a vhost has no + ServerAdmin, + ResourceConfig, + AccessConfig, + Timeout, + KeepAliveTimeout, + KeepAlive, + MaxKeepAliveRequests, or - SendBufferSize + SendBufferSize directive then the respective value is inherited from the main_server. (That is, inherited from whatever the final setting of that value is in the main_server.) -
    2. The "lookup defaults" that define the default directory +
    3. The "lookup defaults" that define the default directory permissions for a vhost are merged with those of the main_server. This includes any per-directory configuration information for any module. -
    4. The per-server configs for each module from the main_server are +
    5. The per-server configs for each module from the main_server are merged into the vhost server. -
    +
Essentially, the main_server is treated as "defaults" or a "base" on which to build each vhost. @@ -168,33 +168,33 @@ config of the main_server has been parsed when this final merging occurs. So even if a main_server definition appears after a vhost definition it might affect the vhost definition. -

If the main_server has no ServerName at this point, +

If the main_server has no ServerName at this point, then the hostname of the machine that httpd is running on is used instead. We will call the main_server address set those IP -addresses returned by a DNS lookup on the ServerName of +addresses returned by a DNS lookup on the ServerName of the main_server. -

For any undefined ServerName fields, a name-based vhost -defaults to the address given first in the VirtualHost +

For any undefined ServerName fields, a name-based vhost +defaults to the address given first in the VirtualHost statement defining the vhost.

Any vhost that includes the magic _default_ wildcard -is given the same ServerName as the main_server. +is given the same ServerName as the main_server.

Virtual Host Matching

-

The server determines which vhost to use for a request as follows: +

The server determines which vhost to use for a request as follows:

Hash table lookup

-

When the connection is first made by a client, the IP address to +

When the connection is first made by a client, the IP address to which the client connected is looked up in the internal IP hash table.

If the lookup fails (the IP address wasn't found) the request is -served from the _default_ vhost if there is such a vhost +served from the _default_ vhost if there is such a vhost for the port to which the client sent the request. If there is no -matching _default_ vhost the request is served from the +matching _default_ vhost the request is served from the main_server.

If the lookup succeeded (a corresponding list for the IP address was @@ -209,36 +209,36 @@ served from that vhost.

Name-based vhost

-

If the entry corresponds to a name-based vhost the name list contains +

If the entry corresponds to a name-based vhost the name list contains one or more vhost structures. This list contains the vhosts in the same -order as the VirtualHost directives appear in the config +order as the VirtualHost directives appear in the config file. -

The first vhost on this list (the first vhost that appears after the -corresponding NameVirtualHost directive in the config file) +

The first vhost on this list (the first vhost that appears after the +corresponding NameVirtualHost directive in the config file) has the highest priority and catches any request to an unknown -server name or a request without a Host: header. +server name or a request without a Host: header. -

If the client provided a Host: header the list is -searched for a matching vhost and the first hit on a ServerName -or ServerAlias is taken and the request is served from -that vhost. A Host: header can contain a port number, but +

If the client provided a Host: header the list is +searched for a matching vhost and the first hit on a ServerName +or ServerAlias is taken and the request is served from +that vhost. A Host: header can contain a port number, but Apache always matches against the real port to which the client sent the request. -

If the client submitted a HTTP/1.0 request without Host: +

If the client submitted a HTTP/1.0 request without Host: header we don't know to what server the client tried to connect and -any existing ServerPath is matched against the URI +any existing ServerPath is matched against the URI from the request. The first matching path on the list is used and the request is served from that vhost. -

If no matching vhost could be found the request is served from the +

If no matching vhost could be found the request is served from the first vhost with a matching port number that is on the list for the IP to which the client connected (as already mentioned before).

Persistent connections

-The IP lookup described above is only done once for a particular -TCP/IP session while the name lookup is done on every request +The IP lookup described above is only done once for a particular +TCP/IP session while the name lookup is done on every request during a KeepAlive/persistent connection. In other words a client may request pages from different name-based vhosts during a single persistent connection. @@ -246,9 +246,9 @@ persistent connection.

Absolute URI

-

If the URI from the request is an absolute URI, and its hostname and +

If the URI from the request is an absolute URI, and its hostname and port match the main server or one of the configured virtual hosts -and match the address and port to which the client sent the request, +and match the address and port to which the client sent the request, then the scheme/hostname/port prefix is stripped off and the remaining relative URI is served by the corresponding main server or virtual host. If it does not match, then the URI remains untouched and the request is @@ -257,110 +257,110 @@ taken to be a proxy request.

Observations

-
    +
      -
    • A name-based vhost can never interfere with an IP-base vhost and +
    • A name-based vhost can never interfere with an IP-base vhost and vice versa. IP-based vhosts can only be reached through an IP address of its own address set and never through any other address. The same applies to name-based vhosts, they can only be reached through an IP address of the corresponding address set which must - be defined with a NameVirtualHost directive. -

      + be defined with a NameVirtualHost directive. +

      -

    • ServerAlias and ServerPath checks are never +
    • ServerAlias and ServerPath checks are never performed for an IP-based vhost. -

      +

      -

    • The order of name-/IP-based, the _default_ - vhost and the NameVirtualHost directive within the config +
    • The order of name-/IP-based, the _default_ + vhost and the NameVirtualHost directive within the config file is not important. Only the ordering of name-based vhosts for a specific address set is significant. The one name-based vhosts that comes first in the configuration file has the highest priority for its corresponding address set. -

      +

      -

    • For security reasons the port number given in a Host: +
    • For security reasons the port number given in a Host: header is never used during the matching process. Apache always uses the real port to which the client sent the request. -

      +

      -

    • If a ServerPath directive exists which is a prefix of - another ServerPath directive that appears later in +
    • If a ServerPath directive exists which is a prefix of + another ServerPath directive that appears later in the configuration file, then the former will always be matched and the latter will never be matched. (That is assuming that no Host header was available to disambiguate the two.) -

      +

      -

    • If two IP-based vhosts have an address in common, the vhost appearing +
    • If two IP-based vhosts have an address in common, the vhost appearing first in the config file is always matched. Such a thing might happen inadvertently. The server will give a warning in the error logfile when it detects this. -

      +

      -

    • A _default_ vhost catches a request only if there is no - other vhost with a matching IP address and a matching port +
    • A _default_ vhost catches a request only if there is no + other vhost with a matching IP address and a matching port number for the request. The request is only caught if the port number to which the client sent the request matches the port number of your - _default_ vhost which is your standard Port + _default_ vhost which is your standard Port by default. A wildcard port can be specified (i.e. - _default_:*) to catch requests to any available port. -

      + _default_:*) to catch requests to any available port. +

      -

    • The main_server is only used to serve a request if the IP address +
    • The main_server is only used to serve a request if the IP address and port number to which the client connected is unspecified - and does not match any other vhost (including a _default_ + and does not match any other vhost (including a _default_ vhost). In other words the main_server only catches a request for an - unspecified address/port combination (unless there is a _default_ + unspecified address/port combination (unless there is a _default_ vhost which matches that port). -

      +

      -

    • A _default_ vhost or the main_server is never - matched for a request with an unknown or missing Host: header +
    • A _default_ vhost or the main_server is never + matched for a request with an unknown or missing Host: header if the client connected to an address (and port) which is used - for name-based vhosts, e.g. in a NameVirtualHost directive. -

      + for name-based vhosts, e.g. in a NameVirtualHost directive. +

      -

    • You should never specify DNS names in VirtualHost +
    • You should never specify DNS names in VirtualHost directives because it will force your server to rely on DNS to boot. Furthermore it poses a security threat if you do not control the DNS for all the domains listed. - There's more information + There's more information available on this and the next two topics. -

      +

      -

    • ServerName should always be set for each vhost. Otherwise +
    • ServerName should always be set for each vhost. Otherwise A DNS lookup is required for each vhost. -

      +

      -

    +

Tips

-

In addition to the tips on the DNS -Issues page, here are some further tips: +

In addition to the tips on the DNS +Issues page, here are some further tips: -

    +
      -
    • Place all main_server definitions before any VirtualHost +
    • Place all main_server definitions before any VirtualHost definitions. (This is to aid the readability of the configuration -- the post-config merging process makes it non-obvious that definitions mixed in around virtual hosts might affect all virtual hosts.) -

      +

      -

    • Group corresponding NameVirtualHost and - VirtualHost definitions in your configuration to ensure +
    • Group corresponding NameVirtualHost and + VirtualHost definitions in your configuration to ensure better readability. -

      +

      -

    • Avoid ServerPaths which are prefixes of other - ServerPaths. If you cannot avoid this then you have to +
    • Avoid ServerPaths which are prefixes of other + ServerPaths. If you cannot avoid this then you have to ensure that the longer (more specific) prefix vhost appears earlier in the configuration file than the shorter (less specific) prefix (i.e., "ServerPath /abc" should appear after "ServerPath /abc/def"). -

      +

      -

    +
diff --git a/docs/manual/vhosts/details_1_2.html b/docs/manual/vhosts/details_1_2.html index d2339bff81..b378f68591 100644 --- a/docs/manual/vhosts/details_1_2.html +++ b/docs/manual/vhosts/details_1_2.html @@ -1,7 +1,7 @@ - -An In-Depth Discussion of VirtualHost Matching - + +An In-Depth Discussion of VirtualHost Matching + -

An In-Depth Discussion of VirtualHost Matching

+

An In-Depth Discussion of VirtualHost Matching

-

This is a very rough document that was probably out of date the moment +

This is a very rough document that was probably out of date the moment it was written. It attempts to explain exactly what the code does when deciding what virtual host to serve a hit from. It's provided on the assumption that something is better than nothing. The server version under discussion is Apache 1.2. -

If you just want to "make it work" without understanding -how, there's a What Works section at the bottom. +

If you just want to "make it work" without understanding +how, there's a What Works section at the bottom.

Config File Parsing

-

There is a main_server which consists of all the definitions appearing +

There is a main_server which consists of all the definitions appearing outside of VirtualHost sections. There are virtual servers, called vhosts, which are defined by vhosts, which are defined by >VirtualHost sections. -

The directives +

The directives Port, @@ -51,47 +51,47 @@ can appear anywhere within the definition of a server. However, each appearance overrides the previous appearance (within that server). -

The default value of the Port field for main_server -is 80. The main_server has no default ServerName, -ServerPath, or ServerAlias. +

The default value of the Port field for main_server +is 80. The main_server has no default ServerName, +ServerPath, or ServerAlias. -

In the absence of any +

In the absence of any Listen directives, the (final if there -are multiple) Port directive in the main_server indicates +are multiple) Port directive in the main_server indicates which port httpd will listen on. -

The Port and ServerName directives for +

The Port and ServerName directives for any server main or virtual are used when generating URLs such as during redirects. -

Each address appearing in the VirtualHost directive +

Each address appearing in the VirtualHost directive can have an optional port. If the port is unspecified it defaults to -the value of the main_server's most recent Port statement. +the value of the main_server's most recent Port statement. The special port * indicates a wildcard that matches any port. Collectively the entire set of addresses (including multiple A record results from DNS lookups) are called the vhost's address set. -

The magic _default_ address has significance during +

The magic _default_ address has significance during the matching algorithm. It essentially matches any unspecified address. -

After parsing the VirtualHost directive, the vhost server -is given a default Port equal to the port assigned to the -first name in its VirtualHost directive. The complete -list of names in the VirtualHost directive are treated -just like a ServerAlias (but are not overridden by any -ServerAlias statement). Note that subsequent Port +

After parsing the VirtualHost directive, the vhost server +is given a default Port equal to the port assigned to the +first name in its VirtualHost directive. The complete +list of names in the VirtualHost directive are treated +just like a ServerAlias (but are not overridden by any +ServerAlias statement). Note that subsequent Port statements for this vhost will not affect the ports assigned in the address set. -

+

All vhosts are stored in a list which is in the reverse order that they appeared in the config file. For example, if the config file is: -

+
     <VirtualHost A>
     ...
     </VirtualHost>
@@ -103,53 +103,53 @@ they appeared in the config file.  For example, if the config file is:
     <VirtualHost C>
     ...
     </VirtualHost>
-

+
Then the list will be ordered: main_server, C, B, A. Keep this in mind. -

+

After parsing has completed, the list of servers is scanned, and various merges and default values are set. In particular: -

    -
  1. If a vhost has no +
      +
    1. If a vhost has no ServerAdmin, + >ServerAdmin, ResourceConfig, + >ResourceConfig, AccessConfig, + >AccessConfig, Timeout, + >Timeout, KeepAliveTimeout, + >KeepAliveTimeout, KeepAlive, + >KeepAlive, MaxKeepAliveRequests, + >MaxKeepAliveRequests, or SendBufferSize + >SendBufferSize directive then the respective value is inherited from the main_server. (That is, inherited from whatever the final setting of that value is in the main_server.) -
    2. The "lookup defaults" that define the default directory +
    3. The "lookup defaults" that define the default directory permissions for a vhost are merged with those of the main server. This includes any per-directory configuration information for any module. -
    4. The per-server configs for each module from the main_server are +
    5. The per-server configs for each module from the main_server are merged into the vhost server. -
    +
Essentially, the main_server is treated as "defaults" or a "base" on @@ -159,134 +159,134 @@ config of the main_server has been parsed when this final merging occurs. So even if a main_server definition appears after a vhost definition it might affect the vhost definition. -

If the main_server has no ServerName at this point, +

If the main_server has no ServerName at this point, then the hostname of the machine that httpd is running on is used instead. We will call the main_server address set those IP -addresses returned by a DNS lookup on the ServerName of +addresses returned by a DNS lookup on the ServerName of the main_server. -

Now a pass is made through the vhosts to fill in any missing -ServerName fields and to classify the vhost as either +

Now a pass is made through the vhosts to fill in any missing +ServerName fields and to classify the vhost as either an IP-based vhost or a name-based vhost. A vhost is considered a name-based vhost if any of its address set overlaps the main_server (the port associated with each address must match the -main_server's Port). Otherwise it is considered an IP-based +main_server's Port). Otherwise it is considered an IP-based vhost. -

For any undefined ServerName fields, a name-based vhost -defaults to the address given first in the VirtualHost +

For any undefined ServerName fields, a name-based vhost +defaults to the address given first in the VirtualHost statement defining the vhost. Any vhost that includes the magic -_default_ wildcard is given the same ServerName as +_default_ wildcard is given the same ServerName as the main_server. Otherwise the vhost (which is necessarily an IP-based -vhost) is given a ServerName based on the result of a reverse -DNS lookup on the first address given in the VirtualHost +vhost) is given a ServerName based on the result of a reverse +DNS lookup on the first address given in the VirtualHost statement. -

+

Vhost Matching

-

Apache 1.3 differs from what is documented -here, and documentation still has to be written. +

Apache 1.3 differs from what is documented +here, and documentation still has to be written. -

+

The server determines which vhost to use for a request as follows: -

find_virtual_server: When the connection is first made +

find_virtual_server: When the connection is first made by the client, the local IP address (the IP address to which the client connected) is looked up in the server list. A vhost is matched if it is an IP-based vhost, the IP address matches and the port matches (taking into account wildcards). -

If no vhosts are matched then the last occurrence, if it appears, +

If no vhosts are matched then the last occurrence, if it appears, of a _default_ address (which if you recall the ordering of the server list mentioned above means that this would be the first occurrence of _default_ in the config file) is matched. -

In any event, if nothing above has matched, then the main_server is +

In any event, if nothing above has matched, then the main_server is matched. -

The vhost resulting from the above search is stored with data +

The vhost resulting from the above search is stored with data about the connection. We'll call this the connection vhost. The connection vhost is constant over all requests in a particular TCP/IP session -- that is, over all requests in a KeepAlive/persistent session. -

For each request made on the connection the following sequence of +

For each request made on the connection the following sequence of events further determines the actual vhost that will be used to serve the request. -

check_fulluri: If the requestURI is an absoluteURI, that -is it includes http://hostname/, then an attempt is made to +

check_fulluri: If the requestURI is an absoluteURI, that +is it includes http://hostname/, then an attempt is made to determine if the hostname's address (and optional port) match that of the connection vhost. If it does then the hostname portion of the URI is saved as the request_hostname. If it does not match, then the URI remains untouched. Note: to achieve this address comparison, the hostname supplied goes through a DNS lookup unless it matches the -ServerName or the local IP address of the client's socket. +ServerName or the local IP address of the client's socket. -

parse_uri: If the URI begins with a protocol -(i.e., http:, ftp:) then the request is +

parse_uri: If the URI begins with a protocol +(i.e., http:, ftp:) then the request is considered a proxy request. Note that even though we may have stripped -an http://hostname/ in the previous step, this could still +an http://hostname/ in the previous step, this could still be a proxy request. -

read_request: If the request does not have a hostname -from the earlier step, then any Host: header sent by the +

read_request: If the request does not have a hostname +from the earlier step, then any Host: header sent by the client is used as the request hostname. -

check_hostalias: If the request now has a hostname, +

check_hostalias: If the request now has a hostname, then an attempt is made to match for this hostname. The first step of this match is to compare any port, if one was given in the request, -against the Port field of the connection vhost. If there's +against the Port field of the connection vhost. If there's a mismatch then the vhost used for the request is the connection vhost. (This is a bug, see observations.) -

+

If the port matches, then httpd scans the list of vhosts starting with the next server after the connection vhost. This scan does not stop if there are any matches, it goes through all possible vhosts, and in the end uses the last match it found. The comparisons performed are as follows: -

    -
  • Compare the request hostname:port with the vhost - ServerName and Port. +
      +
    • Compare the request hostname:port with the vhost + ServerName and Port. -
    • Compare the request hostname against any and all addresses given in - the VirtualHost directive for this vhost. +
    • Compare the request hostname against any and all addresses given in + the VirtualHost directive for this vhost. -
    • Compare the request hostname against the ServerAlias +
    • Compare the request hostname against the ServerAlias given for the vhost. -
    +
-

-check_serverpath: If the request has no hostname +

+check_serverpath: If the request has no hostname (back up a few paragraphs) then a scan similar to the one -in check_hostalias is performed to match any -ServerPath directives given in the vhosts. Note that the +in check_hostalias is performed to match any +ServerPath directives given in the vhosts. Note that the last match is used regardless (again consider the ordering of the virtual hosts).

Observations

-
    +
      -
    • It is difficult to define an IP-based vhost for the machine's +
    • It is difficult to define an IP-based vhost for the machine's "main IP address". You essentially have to create a bogus - ServerName for the main_server that does not match the + ServerName for the main_server that does not match the machine's IPs.

      -

    • During the scans in both check_hostalias and - check_serverpath no check is made that the vhost being +
    • During the scans in both check_hostalias and + check_serverpath no check is made that the vhost being scanned is actually a name-based vhost. This means, for example, that it's possible to match an IP-based vhost through another address. But because the scan starts in the vhost list at the first vhost that matched the local IP address of the connection, not all IP-based vhosts can be matched. -

      +

      Consider the config file above with three vhosts A, B, C. Suppose that B is a named-based vhost, and A and C are IP-based vhosts. If a request comes in on B or C's address containing a header @@ -294,102 +294,102 @@ the virtual hosts). it will be served from A's config. If a request comes in on A's address then it will always be served from A's config regardless of any Host: header. -

      +

      -
    • Unless you have a _default_ vhost, +
    • Unless you have a _default_ vhost, it doesn't matter if you mix name-based vhosts in amongst IP-based - vhosts. During the find_virtual_server phase above no + vhosts. During the find_virtual_server phase above no named-based vhost will be matched, so the main_server will remain the connection vhost. Then scans will cover all vhosts in the vhost list. -

      +

      If you do have a _default_ vhost, then you cannot place named-based vhosts after it in the config. This is because on any connection to the main server IPs the connection vhost will always be the _default_ vhost since none of the name-based are - considered during find_virtual_server. -

      + considered during find_virtual_server. +

      -
    • You should never specify DNS names in VirtualHost +
    • You should never specify DNS names in VirtualHost directives because it will force your server to rely on DNS to boot. Furthermore it poses a security threat if you do not control the DNS for all the domains listed. - There's more information - available on this and the next two topics. -

      + There's more information + available on this and the next two topics. +

      -

    • ServerName should always be set for each vhost. Otherwise +
    • ServerName should always be set for each vhost. Otherwise A DNS lookup is required for each vhost. -

      +

      -

    • A DNS lookup is always required for the main_server's - ServerName (or to generate that if it isn't specified +
    • A DNS lookup is always required for the main_server's + ServerName (or to generate that if it isn't specified in the config). -

      +

      -

    • If a ServerPath directive exists which is a prefix of - another ServerPath directive that appears later in +
    • If a ServerPath directive exists which is a prefix of + another ServerPath directive that appears later in the configuration file, then the former will always be matched and the latter will never be matched. (That is assuming that no Host header was available to disambiguate the two.) -

      +

      -

    • If a vhost that would otherwise be a name-vhost includes a - Port statement that doesn't match the main_server - Port then it will be considered an IP-based vhost. - Then find_virtual_server will match it (because +
    • If a vhost that would otherwise be a name-vhost includes a + Port statement that doesn't match the main_server + Port then it will be considered an IP-based vhost. + Then find_virtual_server will match it (because the ports associated with each address in the address set default to the port of the main_server) as the connection vhost. Then - check_hostalias will refuse to check any other name-based + check_hostalias will refuse to check any other name-based vhost because of the port mismatch. The result is that the vhost will steal all hits going to the main_server address. -

      +

      -

    • If two IP-based vhosts have an address in common, the vhost appearing +
    • If two IP-based vhosts have an address in common, the vhost appearing later in the file is always matched. Such a thing might happen inadvertently. If the config has name-based vhosts and for some reason - the main_server ServerName resolves to the wrong address + the main_server ServerName resolves to the wrong address then all the name-based vhosts will be parsed as ip-based vhosts. Then the last of them will steal all the hits.

      -

    • The last name-based vhost in the config is always matched for any hit +
    • The last name-based vhost in the config is always matched for any hit which doesn't match one of the other name-based vhosts. -
    +
-

What Works

+

What Works

-

In addition to the tips on the DNS -Issues page, here are some further tips: +

In addition to the tips on the DNS +Issues page, here are some further tips: -

    +
      -
    • Place all main_server definitions before any VirtualHost definitions. +
    • Place all main_server definitions before any VirtualHost definitions. (This is to aid the readability of the configuration -- the post-config merging process makes it non-obvious that definitions mixed in around virtualhosts might affect all virtualhosts.) -

      +

      -

    • Arrange your VirtualHosts such +
    • Arrange your VirtualHosts such that all name-based virtual hosts come first, followed by IP-based virtual hosts, followed by any _default_ virtual host -

      +

      -

    • Avoid ServerPaths which are prefixes of other -ServerPaths. If you cannot avoid this then you have to +
    • Avoid ServerPaths which are prefixes of other +ServerPaths. If you cannot avoid this then you have to ensure that the longer (more specific) prefix vhost appears earlier in the configuration file than the shorter (less specific) prefix (i.e., "ServerPath /abc" should appear after "ServerPath /abcdef"). -

      +

      -

    • Do not use port-based vhosts in the same server as +
    • Do not use port-based vhosts in the same server as name-based vhosts. A loose definition for port-based is a vhost which -is determined by the port on the server (i.e., one server with +is determined by the port on the server (i.e., one server with ports 8000, 8080, and 80 - all of which have different configurations). -

      +

      -

    +
diff --git a/docs/manual/vhosts/examples.html b/docs/manual/vhosts/examples.html index fbf159ecaf..46fdb58e5a 100644 --- a/docs/manual/vhosts/examples.html +++ b/docs/manual/vhosts/examples.html @@ -1,7 +1,7 @@ - -VirtualHost Examples - + +VirtualHost Examples + -

Virtual Host examples for common setups

+

Virtual Host examples for common setups

Base configuration

- +

Additional features

- +

IP-based vhosts only

-
    +
      -
    • Setup 1: - The server machine has two IP addresses (111.22.33.44 - and 111.22.33.55) - which resolve to the names server.domain.tld and - www.otherdomain.tld respectively. - The hostname www.domain.tld is an alias (CNAME) - for server.domain.tld and will represent the +
    • Setup 1: + The server machine has two IP addresses (111.22.33.44 + and 111.22.33.55) + which resolve to the names server.domain.tld and + www.otherdomain.tld respectively. + The hostname www.domain.tld is an alias (CNAME) + for server.domain.tld and will represent the main server. -

      - Server configuration: +

      + Server configuration: - 

      +    
           ...
     Port 80
     DocumentRoot /www/domain
@@ -61,20 +61,20 @@
     ServerName www.otherdomain.tld
     ...
     </VirtualHost>
-    
      
-    www.otherdomain.tld can only be reached through the
-    address 111.22.33.55, while www.domain.tld
-    can only be reached through 111.22.33.44
+
      + www.otherdomain.tld can only be reached through the + address 111.22.33.55, while www.domain.tld + can only be reached through 111.22.33.44 (which represents our main server). -
      -

      + +

      -

    • Setup 2: +
    • Setup 2: Same as setup 1, but we don't want to have a dedicated main server. -

      - Server configuration: +

      + Server configuration: - 

      +    
           ...
     Port 80
     ServerName server.domain.tld
@@ -90,28 +90,28 @@
     ServerName www.otherdomain.tld
     ...
     </VirtualHost>
-    
      
+
      The main server can never catch a request, because all IP addresses of our machine are in use for IP-based virtual hosts - (only localhost requests can hit the main server). -
      -

      + (only localhost requests can hit the main server). + +

      -

    • Setup 3: - The server machine has two IP addresses (111.22.33.44 - and 111.22.33.55) - which resolve to the names server.domain.tld and - www-cache.domain.tld respectively. - The hostname www.domain.tld is an alias (CNAME) - for server.domain.tld and will represent the +
    • Setup 3: + The server machine has two IP addresses (111.22.33.44 + and 111.22.33.55) + which resolve to the names server.domain.tld and + www-cache.domain.tld respectively. + The hostname www.domain.tld is an alias (CNAME) + for server.domain.tld and will represent the main server. - www-cache.domain.tld will become our proxy-cache + www-cache.domain.tld will become our proxy-cache listening on port 8080, while the web server itself uses the default port 80. -

      - Server configuration: +

      + Server configuration: - 

      +    
           ...
     Port 80
     Listen 111.22.33.44:80
@@ -133,28 +133,28 @@
       allow from 111.22.33
       </Directory>
     </VirtualHost>
-    
      
+
      The main server can never catch a request, because all IP addresses - (apart from localhost) of our machine are in use for IP-based + (apart from localhost) of our machine are in use for IP-based virtual hosts. The web server can only be reached on the first address through port 80 and the proxy only on the second address through port 8080. -
      -
    + +

Name-based vhosts only

-
    +
      -
    • Setup 1: - The server machine has one IP address (111.22.33.44) - which resolves to the name server.domain.tld. - There are two aliases (CNAMEs) www.domain.tld and - www.sub.domain.tld for the address 111.22.33.44. -

      - Server configuration: +

    • Setup 1: + The server machine has one IP address (111.22.33.44) + which resolves to the name server.domain.tld. + There are two aliases (CNAMEs) www.domain.tld and + www.sub.domain.tld for the address 111.22.33.44. +

      + Server configuration: - 

      +    
           ...
     Port 80
     ServerName server.domain.tld
@@ -172,33 +172,33 @@
     ServerName www.sub.domain.tld
     ...
     </VirtualHost> 
-    
      
-    Apart from localhost there are no unspecified
+
      + Apart from localhost there are no unspecified addresses/ports, therefore the main server only serves - localhost requests. Due to the fact - that www.domain.tld has the highest priority - it can be seen as the default or - primary server. -
      -

      + localhost requests. Due to the fact + that www.domain.tld has the highest priority + it can be seen as the default or + primary server. + +

      -

    • Setup 2: - The server machine has two IP addresses (111.22.33.44 - and 111.22.33.55) - which resolve to the names server1.domain.tld and - server2.domain.tld respectively. - The alias www.domain.tld should be used for the +
    • Setup 2: + The server machine has two IP addresses (111.22.33.44 + and 111.22.33.55) + which resolve to the names server1.domain.tld and + server2.domain.tld respectively. + The alias www.domain.tld should be used for the main server which should also catch any unspecified addresses. We want to use a virtual host for the alias - www.otherdomain.tld and one virtual host should + www.otherdomain.tld and one virtual host should catch any request to hostnames of the form - *.sub.domain.tld with www.sub.domain.tld - as its server name. The address 111.22.33.55 should be + *.sub.domain.tld with www.sub.domain.tld + as its server name. The address 111.22.33.55 should be used for the virtual hosts. -

      - Server configuration: +

      + Server configuration: - 

      +    
           ...
     Port 80
     ServerName www.domain.tld
@@ -218,13 +218,13 @@
     ServerAlias *.sub.domain.tld
     ...
     </VirtualHost> 
-    
      
-    Any request to an address other than 111.22.33.55
+
      + Any request to an address other than 111.22.33.55 will be served from the main server. A request to - 111.22.33.55 with an unknown or no Host: - header will be served from www.otherdomain.tld. -
      -
    + 111.22.33.55 with an unknown or no Host: + header will be served from www.otherdomain.tld. + +
@@ -232,18 +232,18 @@
    -
  • Setup: - The server machine has three IP addresses (111.22.33.44, - 111.22.33.55 and 111.22.33.66) - which resolve to the names server.domain.tld, - www.otherdomain1.tld and www.otherdomain2.tld +
  • Setup: + The server machine has three IP addresses (111.22.33.44, + 111.22.33.55 and 111.22.33.66) + which resolve to the names server.domain.tld, + www.otherdomain1.tld and www.otherdomain2.tld respectively. - The address 111.22.33.44 should we used for a couple + The address 111.22.33.44 should we used for a couple of name-based vhosts and the other addresses for IP-based vhosts. -

    - Server configuration: +

    + Server configuration: - 

    +    
         ...
     Port 80
     ServerName server.domain.tld
@@ -279,26 +279,26 @@
     ServerName www.otherdomain2.tld
     ...
     </VirtualHost>     
-    
    
+
    -
+

Port-based vhosts

-
    +
      -
    • Setup: - The server machine has one IP address (111.22.33.44) - which resolves to the name www.domain.tld. +
    • Setup: + The server machine has one IP address (111.22.33.44) + which resolves to the name www.domain.tld. If we don't have the option to get another address or alias for our server we can use port-based vhosts if we need a virtual host with a different configuration. -

      - Server configuration: +

      + Server configuration: - 

      +    
           ...
     Listen 80
     Listen 8080
@@ -309,56 +309,56 @@
     DocumentRoot /www/domain2
     ...
     </VirtualHost>
-    
      
-    A request to www.domain.tld on port 80 is served
+
      + A request to www.domain.tld on port 80 is served from the main server and a request to port 8080 is served from the virtual host. -
      -
    + +
-

Using _default_ vhosts

+

Using _default_ vhosts

-
    +
      -
    • Setup 1: - Catching every request to any unspecified IP address and port, +
    • Setup 1: + Catching every request to any unspecified IP address and port, i.e. an address/port combination that is not used for any other virtual host. -

      - Server configuration: +

      + Server configuration: - 

      +    
           ...
     <VirtualHost _default_:*>
     DocumentRoot /www/default
     ...
     </VirtualHost>
-    
      
+
      Using such a default vhost with a wildcard port effectively - prevents any request going to the main server.
      + prevents any request going to the main server.
      A default vhost never serves a request that was sent to an address/port that is used for name-based vhosts. If the request - contained an unknown or no Host: header it is + contained an unknown or no Host: header it is always served from the primary name-based vhost (the vhost for that address/port appearing first in the configuration - file).
      + file).
      You can use - AliasMatch + AliasMatch or - RewriteRule + RewriteRule to rewrite any request to a single information page (or script). -
      -

      + +

      -

    • Setup 2: +
    • Setup 2: Same as setup 1, but the server listens on several ports and - we want to use a second _default_ vhost for port 80. -

      - Server configuration: + we want to use a second _default_ vhost for port 80. +

      + Server configuration: - 

      +    
           ...
     <VirtualHost _default_:80>
     DocumentRoot /www/default80
@@ -369,52 +369,52 @@
     DocumentRoot /www/default
     ...
     </VirtualHost>    
-    
      
-    The default vhost for port 80 (which must appear before
+
      + The default vhost for port 80 (which must appear before any default vhost with a wildcard port) catches all requests that were sent to an unspecified IP address. The main server is never used to serve a request. -
      -

      + +

      -

    • Setup 3: +
    • Setup 3: We want to have a default vhost for port 80, but no other default vhosts. -

      - Server configuration: +

      + Server configuration: - 

      +    
           ...
     <VirtualHost _default_:80>
     DocumentRoot /www/default
     ...
     </VirtualHost>
-    
      
+
      A request to an unspecified address on port 80 is served from the default vhost any other request to an unspecified address and port is served from the main server. -
      + -
    +

Migrating a name-based vhost to an IP-based vhost

-
    +
      -
    • Setup: +
    • Setup: The name-based vhost with the hostname - www.otherdomain.tld (from our name-based + www.otherdomain.tld (from our name-based example, setup 2) should get its own IP address. To avoid problems with name servers or proxies who cached the old IP address for the name-based vhost we want to provide both variants - during a migration phase.
      + during a migration phase.
      The solution is easy, because we can simply add the new IP address - (111.22.33.66) to the VirtualHost directive. -

      - Server configuration: + (111.22.33.66) to the VirtualHost directive. +

      + Server configuration: - 

      +    
           ...
     Port 80
     ServerName www.domain.tld
@@ -434,31 +434,31 @@
     ServerAlias *.sub.domain.tld
     ...
     </VirtualHost>
-    
      
+
      The vhost can now be accessed through the new address (as an IP-based vhost) and through the old address (as a name-based vhost). -
      + -
    +
-

Using the ServerPath directive

+

Using the ServerPath directive

-
    +
      -
    • Setup: +
    • Setup: We have a server with two name-based vhosts. In order to match the correct - virtual host a client must send the correct Host: header. + virtual host a client must send the correct Host: header. Old HTTP/1.0 clients do not send such a header and Apache has no clue what vhost the client tried to reach (and serves the request from the primary vhost). To provide as much backward compatibility as possible we create a primary vhost which returns a single page containing links with an URL prefix to the name-based virtual hosts. -

      - Server configuration: +

      + Server configuration: - 

      +    
           ...
     NameVirtualHost 111.22.33.44
 
@@ -487,25 +487,25 @@
     RewriteRule ^(/sub2/.*) /www/subdomain$1 
     ...
     </VirtualHost>
-    
      
-    Due to the ServerPath
+
      + Due to the ServerPath directive a request to the - URL http://www.sub1.domain.tld/sub1/ is always - served from the sub1-vhost.
      - A request to the URL http://www.sub1.domain.tld/ + URL http://www.sub1.domain.tld/sub1/ is always + served from the sub1-vhost.
      + A request to the URL http://www.sub1.domain.tld/ is only served from the sub1-vhost if the client sent a correct - Host: header. - If no Host: header is sent the client gets the - information page from the primary host.
      + Host: header. + If no Host: header is sent the client gets the + information page from the primary host.
      Please note that there is one oddity: A request to - http://www.sub2.domain.tld/sub1/ is also served from - the sub1-vhost if the client sent no Host: header.
      - The RewriteRule directives are used to make sure that - a client which sent a correct Host: header can use + http://www.sub2.domain.tld/sub1/ is also served from + the sub1-vhost if the client sent no Host: header.
      + The RewriteRule directives are used to make sure that + a client which sent a correct Host: header can use both URL variants, i.e. with or without URL prefix. -
      + -
    +
diff --git a/docs/manual/vhosts/fd-limits.html b/docs/manual/vhosts/fd-limits.html index 77f4d8254d..ad8fc0c7cf 100644 --- a/docs/manual/vhosts/fd-limits.html +++ b/docs/manual/vhosts/fd-limits.html @@ -1,8 +1,8 @@ - - -Apache Server Virtual Host Support - + + +Apache Server Virtual Host Support + -

File Descriptor Limits

+

File Descriptor Limits

When using a large number of Virtual Hosts, Apache may run out of available -file descriptors (sometimes called file handles if each Virtual +file descriptors (sometimes called file handles if each Virtual Host specifies different log files. The total number of file descriptors used by Apache is one for each distinct error log file, one for every other log file directive, plus 10-20 for internal use. Unix operating systems limit the number of file descriptors that may be used by a process; the limit is typically 64, and may usually be increased up to a large hard-limit. -

+

Although Apache attempts to increase the limit as required, this may not work if: -

    -
  1. Your system does not provide the setrlimit() system call. -
  2. The setrlimit(RLIMIT_NOFILE) call does not function on your system +
      +
    1. Your system does not provide the setrlimit() system call. +
    2. The setrlimit(RLIMIT_NOFILE) call does not function on your system (such as Solaris 2.3) -
    3. The number of file descriptors required exceeds the hard limit. -
    4. Your system imposes other limits on file descriptors, such as a limit +
    5. The number of file descriptors required exceeds the hard limit. +
    6. Your system imposes other limits on file descriptors, such as a limit on stdio streams only using file descriptors below 256. (Solaris 2) -
    +
In the event of problems you can: -
    -
  • Reduce the number of log files; don't specify log files in the VirtualHost +
      +
    • Reduce the number of log files; don't specify log files in the VirtualHost sections, but only log to the main log files. -
    • If you system falls into 1 or 2 (above), then increase the file descriptor +
    • If you system falls into 1 or 2 (above), then increase the file descriptor limit before starting Apache, using a script like -
      -#!/bin/sh
      -ulimit -S -n 100
      -exec httpd
      -
    +
    +#!/bin/sh
    +ulimit -S -n 100
    +exec httpd
    +

Please see the Descriptors and Apache @@ -55,5 +55,5 @@ they can be solved on your operating system.

- + diff --git a/docs/manual/vhosts/fd-limits.html.en b/docs/manual/vhosts/fd-limits.html.en index 77f4d8254d..ad8fc0c7cf 100644 --- a/docs/manual/vhosts/fd-limits.html.en +++ b/docs/manual/vhosts/fd-limits.html.en @@ -1,8 +1,8 @@ - - -Apache Server Virtual Host Support - + + +Apache Server Virtual Host Support + -

File Descriptor Limits

+

File Descriptor Limits

When using a large number of Virtual Hosts, Apache may run out of available -file descriptors (sometimes called file handles if each Virtual +file descriptors (sometimes called file handles if each Virtual Host specifies different log files. The total number of file descriptors used by Apache is one for each distinct error log file, one for every other log file directive, plus 10-20 for internal use. Unix operating systems limit the number of file descriptors that may be used by a process; the limit is typically 64, and may usually be increased up to a large hard-limit. -

+

Although Apache attempts to increase the limit as required, this may not work if: -

    -
  1. Your system does not provide the setrlimit() system call. -
  2. The setrlimit(RLIMIT_NOFILE) call does not function on your system +
      +
    1. Your system does not provide the setrlimit() system call. +
    2. The setrlimit(RLIMIT_NOFILE) call does not function on your system (such as Solaris 2.3) -
    3. The number of file descriptors required exceeds the hard limit. -
    4. Your system imposes other limits on file descriptors, such as a limit +
    5. The number of file descriptors required exceeds the hard limit. +
    6. Your system imposes other limits on file descriptors, such as a limit on stdio streams only using file descriptors below 256. (Solaris 2) -
    +
In the event of problems you can: -
    -
  • Reduce the number of log files; don't specify log files in the VirtualHost +
      +
    • Reduce the number of log files; don't specify log files in the VirtualHost sections, but only log to the main log files. -
    • If you system falls into 1 or 2 (above), then increase the file descriptor +
    • If you system falls into 1 or 2 (above), then increase the file descriptor limit before starting Apache, using a script like -
      -#!/bin/sh
      -ulimit -S -n 100
      -exec httpd
      -
    +
    +#!/bin/sh
    +ulimit -S -n 100
    +exec httpd
    +

Please see the Descriptors and Apache @@ -55,5 +55,5 @@ they can be solved on your operating system.

- + diff --git a/docs/manual/vhosts/host.html b/docs/manual/vhosts/host.html index 8c37eaccae..437c66e50d 100644 --- a/docs/manual/vhosts/host.html +++ b/docs/manual/vhosts/host.html @@ -1,7 +1,7 @@ - -Apache non-IP Virtual Hosts - + +Apache non-IP Virtual Hosts + -

Apache non-IP Virtual Hosts

+

Apache non-IP Virtual Hosts

-See Also: -Virtual Host Support +See Also: +Virtual Host Support -
+

What is a Virtual Host

-

The "Virtual Host" refers to the practice of maintaining more than +

The "Virtual Host" refers to the practice of maintaining more than one server on one machine, as differentiated by their apparent hostname. For example, it is often desirable for companies sharing a web server to have their own domains, with web servers accessible as -www.company1.com and www.company2.com, -without requiring the user to know any extra path information.

+www.company1.com and www.company2.com, +without requiring the user to know any extra path information.

-

Apache was one of the first servers to support virtual hosts right -out of the box, but since the base HTTP (HyperText +

Apache was one of the first servers to support virtual hosts right +out of the box, but since the base HTTP (HyperText Transport Protocol) standard does not allow any method for the server to determine the hostname it is being addressed as, Apache's virtual host support has required a separate IP address for each server. Documentation on using this approach (which still works very -well) is available. +well) is available. -

While the approach described above works, with the available IP +

While the approach described above works, with the available IP address space growing smaller, and the number of domains increasing, it is not the most elegant solution, and is hard to implement on some -machines. The HTTP/1.1 protocol contains a method for the +machines. The HTTP/1.1 protocol contains a method for the server to identify what name it is being addressed as. Apache 1.1 and later support this approach as well as the traditional -IP-address-per-hostname method.

+IP-address-per-hostname method.

-

The benefits of using the new virtual host support is a practically +

The benefits of using the new virtual host support is a practically unlimited number of servers, ease of configuration and use, and requires no additional hardware or software. The main disadvantage is that the user's browser must support this part of the protocol. The latest versions of many browsers (including Netscape Navigator 2.0 and later) do, but many browsers, especially older ones, do not. This can -cause problems, although a possible solution is addressed below.

+cause problems, although a possible solution is addressed below.

Using non-IP Virtual Hosts

-

Using the new virtual hosts is quite easy, and superficially looks +

Using the new virtual hosts is quite easy, and superficially looks like the old method. You simply add to one of the Apache configuration -files (most likely httpd.conf or srm.conf) -code similar to the following:

-
+files (most likely httpd.conf or srm.conf)
+code similar to the following:

+
     <VirtualHost www.apache.org>
     ServerName www.apache.org
     DocumentRoot /usr/web/apache
     </VirtualHost>
-

+
-

Of course, any additional directives can (and should) be placed -into the <VirtualHost> section. To make this work, -all that is needed is to make sure that the www.apache.org +

Of course, any additional directives can (and should) be placed +into the <VirtualHost> section. To make this work, +all that is needed is to make sure that the www.apache.org DNS entry points to the same IP address as the main server. Optionally, you could simply use that IP address in the -<VirtualHost> entry.

+<VirtualHost> entry.

-

Additionally, many servers may wish to be accessible by more than +

Additionally, many servers may wish to be accessible by more than one name. For example, the Apache server might want to be accessible -as apache.org, or ftp.apache.org, assuming +as apache.org, or ftp.apache.org, assuming the IP addresses pointed to the same server. In fact, one might want it -so that all addresses at apache.org were picked up by the -server. This is possible with the ServerAlias +so that all addresses at apache.org were picked up by the +server. This is possible with the ServerAlias directive, placed inside the <VirtualHost> section. For -example:

+example:

-
+
     ServerAlias apache.org *.apache.org
-

+
-

Note that you can use * and ? as wild-card -characters.

+

Note that you can use * and ? as wild-card +characters.

-

You also might need ServerAlias if you are serving local users who +

You also might need ServerAlias if you are serving local users who do not always include the domain name. For example, if local users are familiar with typing "www" or "www.physics" then you will need to add -ServerAlias www www.physics. It isn't possible for the +ServerAlias www www.physics. It isn't possible for the server to know what domain the client uses for their name resolution -because the client doesn't provide that information in the request.

+because the client doesn't provide that information in the request.

Security Considerations

Apache allows all virtual hosts to be made accessible via the -Host: header through all IP interfaces, even those which +Host: header through all IP interfaces, even those which are configured to use different IP interfaces. For example, if the -configuration for www.foo.com contained a virtual host -section for www.bar.com, and www.bar.com was +configuration for www.foo.com contained a virtual host +section for www.bar.com, and www.bar.com was a separate IP interface, such that -non-Host:-header-supporting browsers can use it, as +non-Host:-header-supporting browsers can use it, as before with Apache 1.0. If a request is made to -www.foo.com and the request includes the header -Host: www.bar.com, a page from www.bar.com +www.foo.com and the request includes the header +Host: www.bar.com, a page from www.bar.com will be sent.

This is a security concern if you are controlling access to a particular server based on IP-layer controls, such as from within a -firewall or router. Let's say www.bar.com in the above +firewall or router. Let's say www.bar.com in the above example was instead an intra-net server called -private.foo.com, and the router used by foo.com only let -internal users access private.foo.com. Obviously, -Host: header functionality now allows someone who has -access to www.foo.com to get -private.foo.com, if they send a Host: -private.foo.com header. It is important to note that this +private.foo.com, and the router used by foo.com only let +internal users access private.foo.com. Obviously, +Host: header functionality now allows someone who has +access to www.foo.com to get +private.foo.com, if they send a Host: +private.foo.com header. It is important to note that this condition exists only if you only implement this policy at the IP layer - all security controls used by Apache (i.e., allow, deny from, etc.) are consistently @@ -128,44 +128,44 @@ respected.

Compatibility with Older Browsers

-

As mentioned earlier, a majority of browsers do not send the +

As mentioned earlier, a majority of browsers do not send the required data for the new virtual hosts to work properly. These browsers will always be sent to the main server's pages. There is a -workaround, albeit a slightly cumbersome one:

+workaround, albeit a slightly cumbersome one:

-

To continue the www.apache.org example (Note: Apache's +

To continue the www.apache.org example (Note: Apache's web server does not actually function in this manner), we might use the -new ServerPath directive in the www.apache.org virtual host, +new ServerPath directive in the www.apache.org virtual host, for example: -

+
     ServerPath /apache
-

-
What does this mean? It means that a request for any file beginning
-with "/apache" will be looked for in the Apache
+
+

What does this mean? It means that a request for any file beginning +with "/apache" will be looked for in the Apache docs. This means that the pages can be accessed as -http://www.apache.org/apache/ for all browsers, although +http://www.apache.org/apache/ for all browsers, although new browsers can also access it as -http://www.apache.org/.

+http://www.apache.org/.

-

In order to make this work, put a link on your main server's page -to http://www.apache.org/apache/ (Note: Do not use -http://www.apache.org/ - this would create an endless +

In order to make this work, put a link on your main server's page +to http://www.apache.org/apache/ (Note: Do not use +http://www.apache.org/ - this would create an endless loop). Then, in the virtual host's pages, be sure to use either purely -relative links (e.g. "file.html" or -"../icons/image.gif" or links containing the prefacing -/apache/ -(e.g. "http://www.apache.org/apache/file.html" or -"/apache/docs/1.1/index.html").

+relative links (e.g. "file.html" or +"../icons/image.gif" or links containing the prefacing +/apache/ +(e.g. "http://www.apache.org/apache/file.html" or +"/apache/docs/1.1/index.html").

-

This requires a bit of +

This requires a bit of discipline, but adherence to these guidelines will, for the most part, ensure that your pages will work with all browsers, new and old. When -a new browser contacts http://www.apache.org/, they will +a new browser contacts http://www.apache.org/, they will be directly taken to the Apache pages. Older browsers will be able to click on the link from the main server, go to -http://www.apache.org/apache/, and then access the -pages.

+http://www.apache.org/apache/, and then access the +pages.

diff --git a/docs/manual/vhosts/index.html b/docs/manual/vhosts/index.html index 0b1a22678e..d2df6e0824 100644 --- a/docs/manual/vhosts/index.html +++ b/docs/manual/vhosts/index.html @@ -13,16 +13,16 @@ ALINK="#FF0000" > -

Apache Virtual Host documentation

+

Apache Virtual Host documentation

-

The term Virtual Host refers to the practice of maintaining +

The term Virtual Host refers to the practice of maintaining more than one server on one machine, as differentiated by their apparent hostname. For example, it is often desirable for companies sharing a web server to have their own domains, with web servers accessible as -www.company1.com and www.company2.com, -without requiring the user to know any extra path information.

+www.company1.com and www.company2.com, +without requiring the user to know any extra path information.

-

Apache was one of the first servers to support IP-based +

Apache was one of the first servers to support IP-based virtual hosts right out of the box. Versions 1.1 and later of Apache support both, IP-based and name-based virtual hosts (vhosts). The latter variant of virtual hosts is sometimes also called host-based or diff --git a/docs/manual/vhosts/index.html.en b/docs/manual/vhosts/index.html.en index 0b1a22678e..d2df6e0824 100644 --- a/docs/manual/vhosts/index.html.en +++ b/docs/manual/vhosts/index.html.en @@ -13,16 +13,16 @@ ALINK="#FF0000" > -

Apache Virtual Host documentation

+

Apache Virtual Host documentation

-

The term Virtual Host refers to the practice of maintaining +

The term Virtual Host refers to the practice of maintaining more than one server on one machine, as differentiated by their apparent hostname. For example, it is often desirable for companies sharing a web server to have their own domains, with web servers accessible as -www.company1.com and www.company2.com, -without requiring the user to know any extra path information.

+www.company1.com and www.company2.com, +without requiring the user to know any extra path information.

-

Apache was one of the first servers to support IP-based +

Apache was one of the first servers to support IP-based virtual hosts right out of the box. Versions 1.1 and later of Apache support both, IP-based and name-based virtual hosts (vhosts). The latter variant of virtual hosts is sometimes also called host-based or diff --git a/docs/manual/vhosts/ip-based.html b/docs/manual/vhosts/ip-based.html index b31fb8da07..4e090890a5 100644 --- a/docs/manual/vhosts/ip-based.html +++ b/docs/manual/vhosts/ip-based.html @@ -1,8 +1,8 @@ - - -Apache IP-based Virtual Host Support - + + +Apache IP-based Virtual Host Support + -

Apache IP-based Virtual Host Support

+

Apache IP-based Virtual Host Support

-See also: -Name-based Virtual Hosts Support +See also: +Name-based Virtual Hosts Support

System requirements

-As the term IP-based indicates, the server must have a -different IP address for each IP-based virtual host. +As the term IP-based indicates, the server must have a +different IP address for each IP-based virtual host. This can be achieved by the machine having several physical network connections, or by use of virtual interfaces which are supported by most modern operating systems (see system documentation for details, these are @@ -33,18 +33,18 @@ is most commonly used to set them up). There are two ways of configuring apache to support multiple hosts. Either by running a separate httpd daemon for each hostname, or by running a single daemon which supports all the virtual hosts. -

+

Use multiple daemons when: -

    -
  • There are security partitioning issues, such as company1 does not want +
      +
    • There are security partitioning issues, such as company1 does not want anyone at company2 to be able to read their data except via the web. In this case you would need two daemons, each running with different User, Group, Listen, and ServerRoot settings. -
    • You can afford the memory and - file descriptor requirements of +
    • You can afford the memory and + file descriptor requirements of listening to every IP alias on the machine. It's only possible to Listen to the "wildcard" address, or to specific addresses. So if you have @@ -52,13 +52,13 @@ Use multiple daemons when: will need to listen to all specific addresses. (Although one httpd could listen to N-1 of the addresses, and another could listen to the remaining address.) -
    +
Use a single daemon when: -
    -
  • Sharing of the httpd configuration between virtual hosts is acceptable. -
  • The machine services a large number of requests, and so the performance +
      +
    • Sharing of the httpd configuration between virtual hosts is acceptable. +
    • The machine services a large number of requests, and so the performance loss in running separate daemons may be significant. -
    +

Setting up multiple daemons

Create a separate httpd installation for each virtual host. @@ -66,9 +66,9 @@ For each installation, use the Listen directive in the configuration file to select which IP address (or virtual host) that daemon services. e.g. -
+
     Listen www.smallco.com:80
-

+
It is recommended that you use an IP address instead of a hostname (see DNS caveats). @@ -85,7 +85,7 @@ The VirtualHost directive in the CustomLog configuration directives to different values for each virtual host. e.g. -
+
     <VirtualHost www.smallco.com>
     ServerAdmin webmaster@mail.smallco.com
     DocumentRoot /groups/smallco/www
@@ -101,14 +101,14 @@ e.g.
     ErrorLog /groups/baygroup/logs/error_log
     TransferLog /groups/baygroup/logs/access_log
     </VirtualHost>
-

+
It is recommended that you use an IP address instead of a hostname (see DNS caveats).

-Almost any configuration directive can be put +Almost any configuration directive can be put in the VirtualHost directive, with the exception of ServerType, StartServers, @@ -135,6 +135,6 @@ tips document for details.

- - + + diff --git a/docs/manual/vhosts/name-based.html b/docs/manual/vhosts/name-based.html index 8c77f4fb0b..567cab8b58 100644 --- a/docs/manual/vhosts/name-based.html +++ b/docs/manual/vhosts/name-based.html @@ -1,7 +1,7 @@ - -Apache name-based Virtual Hosts - + +Apache name-based Virtual Hosts + -

Apache name-based Virtual Host Support

+

Apache name-based Virtual Host Support

-See Also: -IP-based Virtual Host Support +See Also: +IP-based Virtual Host Support -
+

Name-based vs. IP-based virtual hosts

-

While the approach with IP-based virtual hosts works very well, +

While the approach with IP-based virtual hosts works very well, it is not the most elegant solution, because a dedicated IP address is needed for every virtual host and it is hard to implement on some -machines. The HTTP/1.1 protocol contains a method for the +machines. The HTTP/1.1 protocol contains a method for the server to identify what name it is being addressed as. Apache 1.1 and later support this approach as well as the traditional -IP-address-per-hostname method.

+IP-address-per-hostname method.

-

The benefits of using the new name-based virtual host support is a +

The benefits of using the new name-based virtual host support is a practically unlimited number of servers, ease of configuration and use, and requires no additional hardware or software. The main disadvantage is that the client must support this part of the protocol. The latest versions of most browsers do, but there are still old browsers in use who do not. This can cause problems, although a possible -solution is addressed below.

+solution is addressed below.

Using non-IP Virtual Hosts

-

Using the new virtual hosts is quite easy, and superficially looks +

Using the new virtual hosts is quite easy, and superficially looks like the old method. You simply add to one of the Apache configuration -files (most likely httpd.conf or srm.conf) -code similar to the following:

-
+files (most likely httpd.conf or srm.conf)
+code similar to the following:

+
     NameVirtualHost 111.22.33.44
 
     <VirtualHost 111.22.33.44>
     ServerName www.domain.tld
     DocumentRoot /web/domain
     </VirtualHost>
-

+
-

The notable difference between IP-based and name-based virtual host +

The notable difference between IP-based and name-based virtual host configuration is the -NameVirtualHost +NameVirtualHost directive which specifies an IP address that should be used as a target for name-based virtual hosts. -

Of course, any additional directives can (and should) be placed -into the <VirtualHost> section. To make this work, +

Of course, any additional directives can (and should) be placed +into the <VirtualHost> section. To make this work, all that is needed is to make sure that the name -www.domain.tld is an alias (CNAME) pointing to the IP address -111.22.33.44

+www.domain.tld is an alias (CNAME) pointing to the IP address +111.22.33.44

-

Additionally, many servers may wish to be accessible by more than +

Additionally, many servers may wish to be accessible by more than one name. For example, the example server might want to be accessible -as domain.tld, or www2.domain.tld, assuming +as domain.tld, or www2.domain.tld, assuming the IP addresses pointed to the same server. In fact, one might want it -so that all addresses at domain.tld were picked up by the +so that all addresses at domain.tld were picked up by the server. This is possible with the -ServerAlias +ServerAlias directive, placed inside the <VirtualHost> section. For -example:

+example:

-
+
     ServerAlias domain.tld *.domain.tld
-

+
-

Note that you can use * and ? as wild-card -characters.

+

Note that you can use * and ? as wild-card +characters.

-

You also might need ServerAlias if you are +

You also might need ServerAlias if you are serving local users who do not always include the domain name. For example, if local users are familiar with typing "www" or "www.foobar" then you will need to add -ServerAlias www www.foobar. It isn't possible for the +ServerAlias www www.foobar. It isn't possible for the server to know what domain the client uses for their name resolution -because the client doesn't provide that information in the request.

+because the client doesn't provide that information in the request.

Compatibility with Older Browsers

-

As mentioned earlier, there are still some clients in use who +

As mentioned earlier, there are still some clients in use who do not send the required data for the name-based virtual hosts to work properly. These clients will always be sent the pages from the -primary name-based virtual host (the first virtual host -appearing in the configuration file for a specific IP address).

+primary name-based virtual host (the first virtual host +appearing in the configuration file for a specific IP address).

-

There is a possible workaround with the -ServerPath -directive, albeit a slightly cumbersome one:

+

There is a possible workaround with the +ServerPath +directive, albeit a slightly cumbersome one:

-

Example configuration: +

Example configuration: -

+
     NameVirtualHost 111.22.33.44
 
     <VirtualHost 111.22.33.44>
@@ -111,30 +111,30 @@ directive, albeit a slightly cumbersome one:

     ServerPath /domain
     DocumentRoot /web/domain
     </VirtualHost>
-

+
-

What does this mean? It means that a request for any URI beginning -with "/domain" will be served from the virtual host -www.domain.tld This means that the pages can be accessed as -http://www.domain.tld/domain/ for all clients, although -clients sending a Host: header can also access it as -http://www.domain.tld/.

+

What does this mean? It means that a request for any URI beginning +with "/domain" will be served from the virtual host +www.domain.tld This means that the pages can be accessed as +http://www.domain.tld/domain/ for all clients, although +clients sending a Host: header can also access it as +http://www.domain.tld/.

-

In order to make this work, put a link on your primary virtual host's page -to http://www.domain.tld/domain/ +

In order to make this work, put a link on your primary virtual host's page +to http://www.domain.tld/domain/ Then, in the virtual host's pages, be sure to use either purely -relative links (e.g. "file.html" or -"../icons/image.gif" or links containing the prefacing -/domain/ -(e.g. "http://www.domain.tld/domain/misc/file.html" or -"/domain/misc/file.html").

+relative links (e.g. "file.html" or +"../icons/image.gif" or links containing the prefacing +/domain/ +(e.g. "http://www.domain.tld/domain/misc/file.html" or +"/domain/misc/file.html").

-

This requires a bit of +

This requires a bit of discipline, but adherence to these guidelines will, for the most part, -ensure that your pages will work with all browsers, new and old.

+ensure that your pages will work with all browsers, new and old.

-

See also: ServerPath configuration -example

+

See also: ServerPath configuration +example

diff --git a/docs/manual/vhosts/name-based.html.en b/docs/manual/vhosts/name-based.html.en index 8c77f4fb0b..567cab8b58 100644 --- a/docs/manual/vhosts/name-based.html.en +++ b/docs/manual/vhosts/name-based.html.en @@ -1,7 +1,7 @@ - -Apache name-based Virtual Hosts - + +Apache name-based Virtual Hosts + -

Apache name-based Virtual Host Support

+

Apache name-based Virtual Host Support

-See Also: -IP-based Virtual Host Support +See Also: +IP-based Virtual Host Support -
+

Name-based vs. IP-based virtual hosts

-

While the approach with IP-based virtual hosts works very well, +

While the approach with IP-based virtual hosts works very well, it is not the most elegant solution, because a dedicated IP address is needed for every virtual host and it is hard to implement on some -machines. The HTTP/1.1 protocol contains a method for the +machines. The HTTP/1.1 protocol contains a method for the server to identify what name it is being addressed as. Apache 1.1 and later support this approach as well as the traditional -IP-address-per-hostname method.

+IP-address-per-hostname method.

-

The benefits of using the new name-based virtual host support is a +

The benefits of using the new name-based virtual host support is a practically unlimited number of servers, ease of configuration and use, and requires no additional hardware or software. The main disadvantage is that the client must support this part of the protocol. The latest versions of most browsers do, but there are still old browsers in use who do not. This can cause problems, although a possible -solution is addressed below.

+solution is addressed below.

Using non-IP Virtual Hosts

-

Using the new virtual hosts is quite easy, and superficially looks +

Using the new virtual hosts is quite easy, and superficially looks like the old method. You simply add to one of the Apache configuration -files (most likely httpd.conf or srm.conf) -code similar to the following:

-
+files (most likely httpd.conf or srm.conf)
+code similar to the following:

+
     NameVirtualHost 111.22.33.44
 
     <VirtualHost 111.22.33.44>
     ServerName www.domain.tld
     DocumentRoot /web/domain
     </VirtualHost>
-

+
-

The notable difference between IP-based and name-based virtual host +

The notable difference between IP-based and name-based virtual host configuration is the -NameVirtualHost +NameVirtualHost directive which specifies an IP address that should be used as a target for name-based virtual hosts. -

Of course, any additional directives can (and should) be placed -into the <VirtualHost> section. To make this work, +

Of course, any additional directives can (and should) be placed +into the <VirtualHost> section. To make this work, all that is needed is to make sure that the name -www.domain.tld is an alias (CNAME) pointing to the IP address -111.22.33.44

+www.domain.tld is an alias (CNAME) pointing to the IP address +111.22.33.44

-

Additionally, many servers may wish to be accessible by more than +

Additionally, many servers may wish to be accessible by more than one name. For example, the example server might want to be accessible -as domain.tld, or www2.domain.tld, assuming +as domain.tld, or www2.domain.tld, assuming the IP addresses pointed to the same server. In fact, one might want it -so that all addresses at domain.tld were picked up by the +so that all addresses at domain.tld were picked up by the server. This is possible with the -ServerAlias +ServerAlias directive, placed inside the <VirtualHost> section. For -example:

+example:

-
+
     ServerAlias domain.tld *.domain.tld
-

+
-

Note that you can use * and ? as wild-card -characters.

+

Note that you can use * and ? as wild-card +characters.

-

You also might need ServerAlias if you are +

You also might need ServerAlias if you are serving local users who do not always include the domain name. For example, if local users are familiar with typing "www" or "www.foobar" then you will need to add -ServerAlias www www.foobar. It isn't possible for the +ServerAlias www www.foobar. It isn't possible for the server to know what domain the client uses for their name resolution -because the client doesn't provide that information in the request.

+because the client doesn't provide that information in the request.

Compatibility with Older Browsers

-

As mentioned earlier, there are still some clients in use who +

As mentioned earlier, there are still some clients in use who do not send the required data for the name-based virtual hosts to work properly. These clients will always be sent the pages from the -primary name-based virtual host (the first virtual host -appearing in the configuration file for a specific IP address).

+primary name-based virtual host (the first virtual host +appearing in the configuration file for a specific IP address).

-

There is a possible workaround with the -ServerPath -directive, albeit a slightly cumbersome one:

+

There is a possible workaround with the +ServerPath +directive, albeit a slightly cumbersome one:

-

Example configuration: +

Example configuration: -

+
     NameVirtualHost 111.22.33.44
 
     <VirtualHost 111.22.33.44>
@@ -111,30 +111,30 @@ directive, albeit a slightly cumbersome one:

     ServerPath /domain
     DocumentRoot /web/domain
     </VirtualHost>
-

+
-

What does this mean? It means that a request for any URI beginning -with "/domain" will be served from the virtual host -www.domain.tld This means that the pages can be accessed as -http://www.domain.tld/domain/ for all clients, although -clients sending a Host: header can also access it as -http://www.domain.tld/.

+

What does this mean? It means that a request for any URI beginning +with "/domain" will be served from the virtual host +www.domain.tld This means that the pages can be accessed as +http://www.domain.tld/domain/ for all clients, although +clients sending a Host: header can also access it as +http://www.domain.tld/.

-

In order to make this work, put a link on your primary virtual host's page -to http://www.domain.tld/domain/ +

In order to make this work, put a link on your primary virtual host's page +to http://www.domain.tld/domain/ Then, in the virtual host's pages, be sure to use either purely -relative links (e.g. "file.html" or -"../icons/image.gif" or links containing the prefacing -/domain/ -(e.g. "http://www.domain.tld/domain/misc/file.html" or -"/domain/misc/file.html").

+relative links (e.g. "file.html" or +"../icons/image.gif" or links containing the prefacing +/domain/ +(e.g. "http://www.domain.tld/domain/misc/file.html" or +"/domain/misc/file.html").

-

This requires a bit of +

This requires a bit of discipline, but adherence to these guidelines will, for the most part, -ensure that your pages will work with all browsers, new and old.

+ensure that your pages will work with all browsers, new and old.

-

See also: ServerPath configuration -example

+

See also: ServerPath configuration +example

diff --git a/docs/manual/vhosts/vhosts-in-depth.html b/docs/manual/vhosts/vhosts-in-depth.html index d2339bff81..b378f68591 100644 --- a/docs/manual/vhosts/vhosts-in-depth.html +++ b/docs/manual/vhosts/vhosts-in-depth.html @@ -1,7 +1,7 @@ - -An In-Depth Discussion of VirtualHost Matching - + +An In-Depth Discussion of VirtualHost Matching + -

An In-Depth Discussion of VirtualHost Matching

+

An In-Depth Discussion of VirtualHost Matching

-

This is a very rough document that was probably out of date the moment +

This is a very rough document that was probably out of date the moment it was written. It attempts to explain exactly what the code does when deciding what virtual host to serve a hit from. It's provided on the assumption that something is better than nothing. The server version under discussion is Apache 1.2. -

If you just want to "make it work" without understanding -how, there's a What Works section at the bottom. +

If you just want to "make it work" without understanding +how, there's a What Works section at the bottom.

Config File Parsing

-

There is a main_server which consists of all the definitions appearing +

There is a main_server which consists of all the definitions appearing outside of VirtualHost sections. There are virtual servers, called vhosts, which are defined by vhosts, which are defined by >VirtualHost sections. -

The directives +

The directives Port, @@ -51,47 +51,47 @@ can appear anywhere within the definition of a server. However, each appearance overrides the previous appearance (within that server). -

The default value of the Port field for main_server -is 80. The main_server has no default ServerName, -ServerPath, or ServerAlias. +

The default value of the Port field for main_server +is 80. The main_server has no default ServerName, +ServerPath, or ServerAlias. -

In the absence of any +

In the absence of any Listen directives, the (final if there -are multiple) Port directive in the main_server indicates +are multiple) Port directive in the main_server indicates which port httpd will listen on. -

The Port and ServerName directives for +

The Port and ServerName directives for any server main or virtual are used when generating URLs such as during redirects. -

Each address appearing in the VirtualHost directive +

Each address appearing in the VirtualHost directive can have an optional port. If the port is unspecified it defaults to -the value of the main_server's most recent Port statement. +the value of the main_server's most recent Port statement. The special port * indicates a wildcard that matches any port. Collectively the entire set of addresses (including multiple A record results from DNS lookups) are called the vhost's address set. -

The magic _default_ address has significance during +

The magic _default_ address has significance during the matching algorithm. It essentially matches any unspecified address. -

After parsing the VirtualHost directive, the vhost server -is given a default Port equal to the port assigned to the -first name in its VirtualHost directive. The complete -list of names in the VirtualHost directive are treated -just like a ServerAlias (but are not overridden by any -ServerAlias statement). Note that subsequent Port +

After parsing the VirtualHost directive, the vhost server +is given a default Port equal to the port assigned to the +first name in its VirtualHost directive. The complete +list of names in the VirtualHost directive are treated +just like a ServerAlias (but are not overridden by any +ServerAlias statement). Note that subsequent Port statements for this vhost will not affect the ports assigned in the address set. -

+

All vhosts are stored in a list which is in the reverse order that they appeared in the config file. For example, if the config file is: -

+
     <VirtualHost A>
     ...
     </VirtualHost>
@@ -103,53 +103,53 @@ they appeared in the config file.  For example, if the config file is:
     <VirtualHost C>
     ...
     </VirtualHost>
-

+
Then the list will be ordered: main_server, C, B, A. Keep this in mind. -

+

After parsing has completed, the list of servers is scanned, and various merges and default values are set. In particular: -

    -
  1. If a vhost has no +
      +
    1. If a vhost has no ServerAdmin, + >ServerAdmin, ResourceConfig, + >ResourceConfig, AccessConfig, + >AccessConfig, Timeout, + >Timeout, KeepAliveTimeout, + >KeepAliveTimeout, KeepAlive, + >KeepAlive, MaxKeepAliveRequests, + >MaxKeepAliveRequests, or SendBufferSize + >SendBufferSize directive then the respective value is inherited from the main_server. (That is, inherited from whatever the final setting of that value is in the main_server.) -
    2. The "lookup defaults" that define the default directory +
    3. The "lookup defaults" that define the default directory permissions for a vhost are merged with those of the main server. This includes any per-directory configuration information for any module. -
    4. The per-server configs for each module from the main_server are +
    5. The per-server configs for each module from the main_server are merged into the vhost server. -
    +
Essentially, the main_server is treated as "defaults" or a "base" on @@ -159,134 +159,134 @@ config of the main_server has been parsed when this final merging occurs. So even if a main_server definition appears after a vhost definition it might affect the vhost definition. -

If the main_server has no ServerName at this point, +

If the main_server has no ServerName at this point, then the hostname of the machine that httpd is running on is used instead. We will call the main_server address set those IP -addresses returned by a DNS lookup on the ServerName of +addresses returned by a DNS lookup on the ServerName of the main_server. -

Now a pass is made through the vhosts to fill in any missing -ServerName fields and to classify the vhost as either +

Now a pass is made through the vhosts to fill in any missing +ServerName fields and to classify the vhost as either an IP-based vhost or a name-based vhost. A vhost is considered a name-based vhost if any of its address set overlaps the main_server (the port associated with each address must match the -main_server's Port). Otherwise it is considered an IP-based +main_server's Port). Otherwise it is considered an IP-based vhost. -

For any undefined ServerName fields, a name-based vhost -defaults to the address given first in the VirtualHost +

For any undefined ServerName fields, a name-based vhost +defaults to the address given first in the VirtualHost statement defining the vhost. Any vhost that includes the magic -_default_ wildcard is given the same ServerName as +_default_ wildcard is given the same ServerName as the main_server. Otherwise the vhost (which is necessarily an IP-based -vhost) is given a ServerName based on the result of a reverse -DNS lookup on the first address given in the VirtualHost +vhost) is given a ServerName based on the result of a reverse +DNS lookup on the first address given in the VirtualHost statement. -

+

Vhost Matching

-

Apache 1.3 differs from what is documented -here, and documentation still has to be written. +

Apache 1.3 differs from what is documented +here, and documentation still has to be written. -

+

The server determines which vhost to use for a request as follows: -

find_virtual_server: When the connection is first made +

find_virtual_server: When the connection is first made by the client, the local IP address (the IP address to which the client connected) is looked up in the server list. A vhost is matched if it is an IP-based vhost, the IP address matches and the port matches (taking into account wildcards). -

If no vhosts are matched then the last occurrence, if it appears, +

If no vhosts are matched then the last occurrence, if it appears, of a _default_ address (which if you recall the ordering of the server list mentioned above means that this would be the first occurrence of _default_ in the config file) is matched. -

In any event, if nothing above has matched, then the main_server is +

In any event, if nothing above has matched, then the main_server is matched. -

The vhost resulting from the above search is stored with data +

The vhost resulting from the above search is stored with data about the connection. We'll call this the connection vhost. The connection vhost is constant over all requests in a particular TCP/IP session -- that is, over all requests in a KeepAlive/persistent session. -

For each request made on the connection the following sequence of +

For each request made on the connection the following sequence of events further determines the actual vhost that will be used to serve the request. -

check_fulluri: If the requestURI is an absoluteURI, that -is it includes http://hostname/, then an attempt is made to +

check_fulluri: If the requestURI is an absoluteURI, that +is it includes http://hostname/, then an attempt is made to determine if the hostname's address (and optional port) match that of the connection vhost. If it does then the hostname portion of the URI is saved as the request_hostname. If it does not match, then the URI remains untouched. Note: to achieve this address comparison, the hostname supplied goes through a DNS lookup unless it matches the -ServerName or the local IP address of the client's socket. +ServerName or the local IP address of the client's socket. -

parse_uri: If the URI begins with a protocol -(i.e., http:, ftp:) then the request is +

parse_uri: If the URI begins with a protocol +(i.e., http:, ftp:) then the request is considered a proxy request. Note that even though we may have stripped -an http://hostname/ in the previous step, this could still +an http://hostname/ in the previous step, this could still be a proxy request. -

read_request: If the request does not have a hostname -from the earlier step, then any Host: header sent by the +

read_request: If the request does not have a hostname +from the earlier step, then any Host: header sent by the client is used as the request hostname. -

check_hostalias: If the request now has a hostname, +

check_hostalias: If the request now has a hostname, then an attempt is made to match for this hostname. The first step of this match is to compare any port, if one was given in the request, -against the Port field of the connection vhost. If there's +against the Port field of the connection vhost. If there's a mismatch then the vhost used for the request is the connection vhost. (This is a bug, see observations.) -

+

If the port matches, then httpd scans the list of vhosts starting with the next server after the connection vhost. This scan does not stop if there are any matches, it goes through all possible vhosts, and in the end uses the last match it found. The comparisons performed are as follows: -

    -
  • Compare the request hostname:port with the vhost - ServerName and Port. +
      +
    • Compare the request hostname:port with the vhost + ServerName and Port. -
    • Compare the request hostname against any and all addresses given in - the VirtualHost directive for this vhost. +
    • Compare the request hostname against any and all addresses given in + the VirtualHost directive for this vhost. -
    • Compare the request hostname against the ServerAlias +
    • Compare the request hostname against the ServerAlias given for the vhost. -
    +
-

-check_serverpath: If the request has no hostname +

+check_serverpath: If the request has no hostname (back up a few paragraphs) then a scan similar to the one -in check_hostalias is performed to match any -ServerPath directives given in the vhosts. Note that the +in check_hostalias is performed to match any +ServerPath directives given in the vhosts. Note that the last match is used regardless (again consider the ordering of the virtual hosts).

Observations

-
    +
      -
    • It is difficult to define an IP-based vhost for the machine's +
    • It is difficult to define an IP-based vhost for the machine's "main IP address". You essentially have to create a bogus - ServerName for the main_server that does not match the + ServerName for the main_server that does not match the machine's IPs.

      -

    • During the scans in both check_hostalias and - check_serverpath no check is made that the vhost being +
    • During the scans in both check_hostalias and + check_serverpath no check is made that the vhost being scanned is actually a name-based vhost. This means, for example, that it's possible to match an IP-based vhost through another address. But because the scan starts in the vhost list at the first vhost that matched the local IP address of the connection, not all IP-based vhosts can be matched. -

      +

      Consider the config file above with three vhosts A, B, C. Suppose that B is a named-based vhost, and A and C are IP-based vhosts. If a request comes in on B or C's address containing a header @@ -294,102 +294,102 @@ the virtual hosts). it will be served from A's config. If a request comes in on A's address then it will always be served from A's config regardless of any Host: header. -

      +

      -
    • Unless you have a _default_ vhost, +
    • Unless you have a _default_ vhost, it doesn't matter if you mix name-based vhosts in amongst IP-based - vhosts. During the find_virtual_server phase above no + vhosts. During the find_virtual_server phase above no named-based vhost will be matched, so the main_server will remain the connection vhost. Then scans will cover all vhosts in the vhost list. -

      +

      If you do have a _default_ vhost, then you cannot place named-based vhosts after it in the config. This is because on any connection to the main server IPs the connection vhost will always be the _default_ vhost since none of the name-based are - considered during find_virtual_server. -

      + considered during find_virtual_server. +

      -
    • You should never specify DNS names in VirtualHost +
    • You should never specify DNS names in VirtualHost directives because it will force your server to rely on DNS to boot. Furthermore it poses a security threat if you do not control the DNS for all the domains listed. - There's more information - available on this and the next two topics. -

      + There's more information + available on this and the next two topics. +

      -

    • ServerName should always be set for each vhost. Otherwise +
    • ServerName should always be set for each vhost. Otherwise A DNS lookup is required for each vhost. -

      +

      -

    • A DNS lookup is always required for the main_server's - ServerName (or to generate that if it isn't specified +
    • A DNS lookup is always required for the main_server's + ServerName (or to generate that if it isn't specified in the config). -

      +

      -

    • If a ServerPath directive exists which is a prefix of - another ServerPath directive that appears later in +
    • If a ServerPath directive exists which is a prefix of + another ServerPath directive that appears later in the configuration file, then the former will always be matched and the latter will never be matched. (That is assuming that no Host header was available to disambiguate the two.) -

      +

      -

    • If a vhost that would otherwise be a name-vhost includes a - Port statement that doesn't match the main_server - Port then it will be considered an IP-based vhost. - Then find_virtual_server will match it (because +
    • If a vhost that would otherwise be a name-vhost includes a + Port statement that doesn't match the main_server + Port then it will be considered an IP-based vhost. + Then find_virtual_server will match it (because the ports associated with each address in the address set default to the port of the main_server) as the connection vhost. Then - check_hostalias will refuse to check any other name-based + check_hostalias will refuse to check any other name-based vhost because of the port mismatch. The result is that the vhost will steal all hits going to the main_server address. -

      +

      -

    • If two IP-based vhosts have an address in common, the vhost appearing +
    • If two IP-based vhosts have an address in common, the vhost appearing later in the file is always matched. Such a thing might happen inadvertently. If the config has name-based vhosts and for some reason - the main_server ServerName resolves to the wrong address + the main_server ServerName resolves to the wrong address then all the name-based vhosts will be parsed as ip-based vhosts. Then the last of them will steal all the hits.

      -

    • The last name-based vhost in the config is always matched for any hit +
    • The last name-based vhost in the config is always matched for any hit which doesn't match one of the other name-based vhosts. -
    +
-

What Works

+

What Works

-

In addition to the tips on the DNS -Issues page, here are some further tips: +

In addition to the tips on the DNS +Issues page, here are some further tips: -

    +
      -
    • Place all main_server definitions before any VirtualHost definitions. +
    • Place all main_server definitions before any VirtualHost definitions. (This is to aid the readability of the configuration -- the post-config merging process makes it non-obvious that definitions mixed in around virtualhosts might affect all virtualhosts.) -

      +

      -

    • Arrange your VirtualHosts such +
    • Arrange your VirtualHosts such that all name-based virtual hosts come first, followed by IP-based virtual hosts, followed by any _default_ virtual host -

      +

      -

    • Avoid ServerPaths which are prefixes of other -ServerPaths. If you cannot avoid this then you have to +
    • Avoid ServerPaths which are prefixes of other +ServerPaths. If you cannot avoid this then you have to ensure that the longer (more specific) prefix vhost appears earlier in the configuration file than the shorter (less specific) prefix (i.e., "ServerPath /abc" should appear after "ServerPath /abcdef"). -

      +

      -

    • Do not use port-based vhosts in the same server as +
    • Do not use port-based vhosts in the same server as name-based vhosts. A loose definition for port-based is a vhost which -is determined by the port on the server (i.e., one server with +is determined by the port on the server (i.e., one server with ports 8000, 8080, and 80 - all of which have different configurations). -

      +

      -

    +
diff --git a/docs/manual/vhosts/virtual-host.html b/docs/manual/vhosts/virtual-host.html index 79b6b3a920..69a06852e5 100644 --- a/docs/manual/vhosts/virtual-host.html +++ b/docs/manual/vhosts/virtual-host.html @@ -1,8 +1,8 @@ - - -Apache Server Virtual Host Support - + + +Apache Server Virtual Host Support + -

Virtual Host Support

+

Virtual Host Support

-See Also: -Non-IP based virtual hosts +See Also: +Non-IP based virtual hosts

What are virtual hosts?

This is the ability of a single machine to be a web server for multiple domains. For example, an Internet service provider might have a machine -called www.serve.com which provides Web space for several -organizations including, say, smallco and baygroup. +called www.serve.com which provides Web space for several +organizations including, say, smallco and baygroup. Ordinarily, these groups would be given parts of the Web tree on www.serve.com. So smallco's home page would have the URL -
+
http://www.serve.com/smallco/ -
+
and baygroup's home page would have the URL -
+
http://www.serve.com/baygroup/ -
-

+

+

For esthetic reasons, however, both organizations would rather their home pages appeared under their own names rather than that of the service provider's; but they do not want to set up their own Internet links and servers. -

+

Virtual hosts are the solution to this problem. smallco and baygroup would -have their own Internet name registrations, www.smallco.com and -www.baygroup.org respectively. These hostnames would both +have their own Internet name registrations, www.smallco.com and +www.baygroup.org respectively. These hostnames would both correspond to the service provider's machine (www.serve.com). Thus smallco's home page would now have the URL -

+
http://www.smallco.com/ -
+
and baygroup's home page would would have the URL -
+
http://www.baygroup.org/ -
+

System requirements

-Due to limitations in the HTTP/1.0 protocol, the web server must have a -different IP address for each virtual host. This can be achieved +Due to limitations in the HTTP/1.0 protocol, the web server must have a +different IP address for each virtual host. This can be achieved by the machine having several physical network connections, or by use -of a virtual interface on some operating systems. +of a virtual interface on some operating systems.

How to set up Apache

There are two ways of configuring apache to support multiple hosts. Either by running a separate httpd daemon for each hostname, or by running a single daemon which supports all the virtual hosts. -

+

Use multiple daemons when: -

    -
  • The different virtual hosts need very different httpd configurations, such +
      +
    • The different virtual hosts need very different httpd configurations, such as different values for: ServerType, User, Group, TypesConfig or ServerRoot. -
    • The machine does not process a very high request rate. -
    +
  • The machine does not process a very high request rate. +
Use a single daemon when: -
    -
  • Sharing of the httpd configuration between virtual hosts is acceptable. -
  • The machine services a large number of requests, and so the performance +
      +
    • Sharing of the httpd configuration between virtual hosts is acceptable. +
    • The machine services a large number of requests, and so the performance loss in running separate daemons may be significant. -
    +

Setting up multiple daemons

Create a separate httpd installation for each virtual host. @@ -85,7 +85,7 @@ For each installation, use the BindAddress directive in the configuration file to select which IP address (or virtual host) that daemon services. e.g. -
BindAddress www.smallco.com
+
BindAddress www.smallco.com
This hostname can also be given as an IP address.

Setting up a single daemon

@@ -99,29 +99,29 @@ The VirtualHost directive in the TransferLog configuration directives to different values for each virtual host. e.g. -
-<VirtualHost www.smallco.com>
-ServerAdmin webmaster@mail.smallco.com
-DocumentRoot /groups/smallco/www
-ServerName www.smallco.com
-ErrorLog /groups/smallco/logs/error_log
-TransferLog /groups/smallco/logs/access_log
-</VirtualHost>
-
-<VirtualHost www.baygroup.org>
-ServerAdmin webmaster@mail.baygroup.org
-DocumentRoot /groups/baygroup/www
-ServerName www.baygroup.org
-ErrorLog /groups/baygroup/logs/error_log
-TransferLog /groups/baygroup/logs/access_log
-</VirtualHost>
-
+
+<VirtualHost www.smallco.com>
+ServerAdmin webmaster@mail.smallco.com
+DocumentRoot /groups/smallco/www
+ServerName www.smallco.com
+ErrorLog /groups/smallco/logs/error_log
+TransferLog /groups/smallco/logs/access_log
+</VirtualHost>
+
+<VirtualHost www.baygroup.org>
+ServerAdmin webmaster@mail.baygroup.org
+DocumentRoot /groups/baygroup/www
+ServerName www.baygroup.org
+ErrorLog /groups/baygroup/logs/error_log
+TransferLog /groups/baygroup/logs/access_log
+</VirtualHost>
+
This VirtualHost hostnames can also be given as IP addresses.

-Almost ANY configuration directive can be put +Almost ANY configuration directive can be put in the VirtualHost directive, with the exception of ServerType, User, @@ -153,36 +153,36 @@ error log file, one for every other log file directive, plus 10-20 for internal use. Unix operating systems limit the number of file descriptors that may be used by a process; the limit is typically 64, and may usually be increased up to a large hard-limit. -

+

Although Apache attempts to increase the limit as required, this may not work if: -

    -
  1. Your system does not provide the setrlimit() system call. -
  2. The setrlimit(RLIMIT_NOFILE) call does not function on your system +
      +
    1. Your system does not provide the setrlimit() system call. +
    2. The setrlimit(RLIMIT_NOFILE) call does not function on your system (such as Solaris 2.3) -
    3. The number of file descriptors required exceeds the hard limit. -
    4. Your system imposes other limits on file descriptors, such as a limit +
    5. The number of file descriptors required exceeds the hard limit. +
    6. Your system imposes other limits on file descriptors, such as a limit on stdio streams only using file descriptors below 256. (Solaris 2) -
    +
In the event of problems you can: -
    -
  • Reduce the number of log files; don't specify log files in the VirtualHost +
      +
    • Reduce the number of log files; don't specify log files in the VirtualHost sections, but only log to the main log files. -
    • If you system falls into 1 or 2 (above), then increase the file descriptor +
    • If you system falls into 1 or 2 (above), then increase the file descriptor limit before starting Apache, using a script like -
      -#!/bin/sh
      -ulimit -S -n 100
      -exec httpd
      -
    +
    +#!/bin/sh
    +ulimit -S -n 100
    +exec httpd
    +
The have been reports that Apache may start running out of resources allocated for the root process. This will exhibit itself as errors in the error log like "unable to fork". There are two ways you can bump this up:
    -
  1. Have a csh script wrapper around httpd which sets the +
  2. Have a csh script wrapper around httpd which sets the "rlimit" to some large number, like 512.
  3. Edit http_main.c to add calls to setrlimit() from main(), along the lines of 
    @@ -200,5 +200,5 @@ for the root process. This will exhibit itself as errors in the error log like
 The latter will probably manifest itself in a later version of Apache.
 
 
-
+
 
-- 
2.50.1