From: Rich Bowen Date: Sat, 22 Sep 2001 18:53:20 +0000 (+0000) Subject: Ran w3c tidy on these as 'tidy -mi -asxml' to get xhtml. Please verify, X-Git-Tag: 2.0.26~199 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=1bf05b9838e25403ff49e68c7ce8e26af90b6bd5;p=thirdparty%2Fapache%2Fhttpd.git Ran w3c tidy on these as 'tidy -mi -asxml' to get xhtml. Please verify, in particular, the non-english files, to make sure I did not screw anything up. They look fine to me. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@91112 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/bind.html b/docs/manual/bind.html index 208c6c54a21..993887531b2 100644 --- a/docs/manual/bind.html +++ b/docs/manual/bind.html @@ -1,78 +1,79 @@ - - -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. -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.

+ Setting which addresses and ports Apache uses + + -

The Listen directive tells the server to accept -incoming requests only on the specified port or address-and-port -combinations. If only a port number is specified in the -Listen directive, the server listens to the given port on -all interfaces, 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 -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: -

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

+ +

The Listen directive tells the server to accept + incoming requests only on the specified port or + address-and-port combinations. If only a port number is + specified in the Listen directive, the server + listens to the given port on all interfaces, 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 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 -

+ 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

- -

Listen does not implement Virtual Hosts. It only tells the -main server what addresses and ports to listen to. If no -<VirtualHost> directives are used, the server will behave the -same for all accepted requests. However, <VirtualHost> can be -used to specify a different behavior for one or more of the addresses -and ports. To implement a VirtualHost, the server must first be told -to listen to the address and port to be used. Then a -<VirtualHost> section should be created for a specified address -and port to set the behavior of this virtual host. Note that if the -<VirtualHost> is set for an address and port that the server is -not listening to, it cannot be accessed. +

How this works with Virtual Hosts

-See also the documentation on -Listen directive, -Virtual Hosts, -Port directive, -DNS Issues -and -<VirtualHost> section. +

Listen does not implement Virtual Hosts. It only tells the + main server what addresses and ports to listen to. If no + <VirtualHost> directives are used, the server will behave + the same for all accepted requests. However, + <VirtualHost> can be used to specify a different behavior + for one or more of the addresses and ports. To implement a + VirtualHost, the server must first be told to listen to the + address and port to be used. Then a <VirtualHost> section + should be created for a specified address and port to set the + behavior of this virtual host. Note that if the + <VirtualHost> is set for an address and port that the + server is not listening to, it cannot be accessed.

- - - +

Setting which addresses and ports Apache uses

+ + + -

+ Setting which addresses and ports Apache uses + + -

+ + -

For example, to make the server accept connections on both port -80 and port 8000, use: -

Setting which addresses and ports Apache + uses

+ +

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 -

+ 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

- -

How this works with Virtual Hosts

-See also the documentation on -Listen directive, -Virtual Hosts, -Port directive, -DNS Issues -and -<VirtualHost> section. +

- - - +

PATH_INFO Changes in the CGI Environment

- -

Overview

- -

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

The Problem

- -

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

+ + + + + + + PATH_INFO Changes in the CGI Environment + + + + + + +

PATH_INFO Changes in the CGI + Environment

+ +

Overview

+ +

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

+ +

The Problem

+ +

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" -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 -incorrect. In certain cases, this could even cause the server to -crash.

- -

The Solution

- -

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 -in no server behavior problems. It also permits the script to be -guaranteed that -"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 -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. - -

Compatibility with Previous Servers

- -

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.

- -

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'};
-

+ +

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 incorrect. In + certain cases, this could even cause the server to crash.

+ +

The Solution

+ +

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 in no + server behavior problems. It also permits the script to be + guaranteed that + "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.

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

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.

+ +

Compatibility with Previous + Servers

+ +

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.

+ +

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.

+ + + diff --git a/docs/manual/cgi_path.html.en b/docs/manual/cgi_path.html.en index 2b7bd963b15..4ed74ade20a 100644 --- a/docs/manual/cgi_path.html.en +++ b/docs/manual/cgi_path.html.en @@ -1,93 +1,98 @@ - - -PATH_INFO Changes in the CGI Environment - - - - - -

PATH_INFO Changes in the CGI Environment

- -

Overview

- -

The Problem

- -

+ + + + + + + PATH_INFO Changes in the CGI Environment + + + + + + +

PATH_INFO Changes in the CGI + Environment

+ +

Overview

+ +

The Problem

+ +

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

- -

The Solution

- -

Compatibility with Previous Servers

- -

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

+ +

The Solution

+ +

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

+ +

Compatibility with Previous + Servers

+ +

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

+ + + diff --git a/docs/manual/configuring.html.en b/docs/manual/configuring.html.en index 23a1604d4bf..f0b3e2e47fc 100644 --- a/docs/manual/configuring.html.en +++ b/docs/manual/configuring.html.en @@ -1,205 +1,244 @@ - - - -Configuration Files - - - - - -

Configuration Files

- -

Main Configuration Files
Syntax of the Configuration Files
Modules
Scope of Directives
.htaccess Files

- -

Main Configuration Files

- - - -

-Related Modules

-mod_mime
-

-Related Directives

-<IfDefine>
-Include
-TypesConfig
-

- -

Apache is configured by placing directives in plain text configuration files. The main -configuration file is usually called httpd.conf. The -location of this file is set at compile-time, but may be overridden -with the -f command line flag. In addition, other -configuration files may be added using the Include directive. Any -directive may be placed in any of these configuration files. Changes -to the main configuration files are only recognized by Apache when it -is started or restarted.

- -

New with Apache 1.3.13 is a feature where if any configuration -file is actually a directory, Apache will enter that directory -and parse any files (and subdirectories) found there as configuration -files. One possible use for this would be to add VirtualHosts -by creating small configuration files for each host, and placing -them in such a configuration directory. Thus, you can add or -remove VirtualHosts without editing any files at all, simply -adding or deleting them. This makes automating such processes -much easier. - -

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

- -

Syntax of the Configuration Files

- -

Apache configuration files contain one directive per line. The -back-slash "\" may be used as the last character on a line to indicate -that the directive continues onto the next line. There must be no -other characters or white space between the back-slash and the end of -the line. - -

Directives in the configuration files are case-insensitive, but -arguments to directives are often case sensitive. Lines which begin -with the hash character "#" are considered comments, and are ignored. -Comments may not be included on a line after a -configuration directive. Blank lines and white space occurring before -a directive are ignored, so you may indent directives for clarity. - -

You can check your configuration files for syntax errors without -starting the server by using apachectl configtest -or the -t command line option. - -

- -

Modules

- - -

-Related Modules

-mod_so
-

-Related Directives

-AddModule
-ClearModuleList
-<IfModule>
-LoadModule
-

- -

Apache is a modular server. This implies that only the most basic -functionality is included in the core server. Extended features are -available through modules which -can be loaded into Apache. By default, a base set of modules is -included in the server at compile-time. If the server is compiled to -use dynamically loaded modules, then modules -can be compiled separately and added at any time using the LoadModule directive. -Otherwise, Apache must be recompiled to add or remove modules. -Configuration directives may be included conditional on a presence of -a particular module by enclosing them in an <IfModule> block. - -

To see which modules are currently compiled into the server, -you can use the -l command line option. - -

- -

Scope of Directives

- -

-Related Directives

-<Directory>
-<DirectoryMatch>
-<Files>
-<FilesMatch>
-<Location>
-<LocationMatch>
-<VirtualHost>
-

- -

Directives placed in the main configuration files apply to the entire -server. If you wish to change the configuration for only a part of -the server, you can scope your directives by placing them in -<Directory>, -<DirectoryMatch>, -<Files>, -<FilesMatch>, -<Location>, - and -<LocationMatch> - -sections. These sections limit the application of the directives -which they enclose to particular filesystem locations or URLs. They -can also be nested, allowing for very fine grained configuration. - -

Apache has the capability to serve many different websites -simultaneously. This is called Virtual Hosting. -Directives can also be scoped by placing them inside -<VirtualHost> -sections, so that they will only apply to requests for a particular -website. - -

Although most directives can be placed in any of these sections, -some directives do not make sense in some contexts. For example, -directives controlling process creation can only be placed in the main -server context. To find which directives can be placed in which -sections, check the Context of the directive. -For further information, we provide details on How Directory, Location and Files sections -work. - -

- -

.htaccess Files

- -

-Related Directives

-AccessFileName
-AllowOverride
-

- -

Apache allows for decentralized management of configuration via -special files placed inside the web tree. The special files are -usually called .htaccess, but any name can be specified -in the AccessFileName directive. Directives placed in -.htaccess files apply to the directory where you place -the file, and all sub-directories. The .htaccess files -follow the same syntax as the main configuration files. Since -.htaccess files are read on every request, changes made -in these files take immediate effect. - -

To find which directives can be placed in .htaccess -files, check the Context -of the directive. The server administrator further controls what -directives may be placed in .htaccess files by -configuring the AllowOverride -directive in the main configuration files. - -

For more information on .htaccess files, see Ken -Coar's tutorial on Using -.htaccess Files with Apache.

- - - - + + + + + + + Configuration Files + + + + + + +

Configuration Files

+ +

Main Configuration Files
Syntax of the Configuration + Files
Modules
Scope of Directives
.htaccess Files

+ +

Main Configuration Files

+ + + + + + + +

Related Modules
+
+ mod_mime
+

Related Directives
+
+ <IfDefine>
+ Include
+ TypesConfig
+

+ +

Apache is configured by placing directives in plain text + configuration files. The main configuration file is usually + called httpd.conf. The location of this file is + set at compile-time, but may be overridden with the + -f command line flag. In addition, other + configuration files may be added using the Include directive. Any + directive may be placed in any of these configuration files. + Changes to the main configuration files are only recognized by + Apache when it is started or restarted.

+ +

New with Apache 1.3.13 is a feature where if any + configuration file is actually a directory, Apache will enter + that directory and parse any files (and subdirectories) found + there as configuration files. One possible use for this would + be to add VirtualHosts by creating small configuration files + for each host, and placing them in such a configuration + directory. Thus, you can add or remove VirtualHosts without + editing any files at all, simply adding or deleting them. This + makes automating such processes much easier.

+ +

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

+ +

Syntax of the Configuration + Files

+ +

Apache configuration files contain one directive per line. + The back-slash "\" may be used as the last character on a line + to indicate that the directive continues onto the next line. + There must be no other characters or white space between the + back-slash and the end of the line.

+ +

Directives in the configuration files are case-insensitive, + but arguments to directives are often case sensitive. Lines + which begin with the hash character "#" are considered + comments, and are ignored. Comments may not be + included on a line after a configuration directive. Blank lines + and white space occurring before a directive are ignored, so + you may indent directives for clarity.

+ +

You can check your configuration files for syntax errors + without starting the server by using apachectl + configtest or the -t command line + option.

+ +

Modules

+ + + + + + + +

Related Modules
+
+ mod_so
+

Related Directives
+
+ AddModule
+ ClearModuleList
+ <IfModule>
+ LoadModule
+

+ +

Apache is a modular server. This implies that only the most + basic functionality is included in the core server. Extended + features are available through modules which can be loaded + into Apache. By default, a base set of modules is + included in the server at compile-time. If the server is + compiled to use dynamically loaded + modules, then modules can be compiled separately and added at + any time using the LoadModule directive. + Otherwise, Apache must be recompiled to add or remove modules. + Configuration directives may be included conditional on a + presence of a particular module by enclosing them in an <IfModule> block.

+ +

To see which modules are currently compiled into the server, + you can use the -l command line option.

+ +

Scope of Directives

+ + + + + +

Related Directives
+
+ <Directory>
+ <DirectoryMatch>
+ <Files>
+ <FilesMatch>
+ <Location>
+ <LocationMatch>
+ <VirtualHost>
+

+ +

Directives placed in the main configuration files apply to + the entire server. If you wish to change the configuration for + only a part of the server, you can scope your directives by + placing them in <Directory>, <DirectoryMatch>, + <Files>, <FilesMatch>, <Location>, and + <LocationMatch> + sections. These sections limit the application of the + directives which they enclose to particular filesystem + locations or URLs. They can also be nested, allowing for very + fine grained configuration.

+ +

Apache has the capability to serve many different websites + simultaneously. This is called Virtual + Hosting. Directives can also be scoped by placing them + inside <VirtualHost> + sections, so that they will only apply to requests for a + particular website.

+ +

Although most directives can be placed in any of these + sections, some directives do not make sense in some contexts. + For example, directives controlling process creation can only + be placed in the main server context. To find which directives + can be placed in which sections, check the Context of the + directive. For further information, we provide details on How Directory, Location and Files sections + work.

+ +

.htaccess Files

+ + + + + +

Related Directives
+
+ AccessFileName
+ AllowOverride
+

+ +

Apache allows for decentralized management of configuration + via special files placed inside the web tree. The special files + are usually called .htaccess, but any name can be + specified in the AccessFileName + directive. Directives placed in .htaccess files + apply to the directory where you place the file, and all + sub-directories. The .htaccess files follow the + same syntax as the main configuration files. Since + .htaccess files are read on every request, changes + made in these files take immediate effect.

+ +

To find which directives can be placed in + .htaccess files, check the Context of the + directive. The server administrator further controls what + directives may be placed in .htaccess files by + configuring the AllowOverride + directive in the main configuration files.

+ +

For more information on .htaccess files, see + Ken Coar's tutorial on + Using .htaccess Files with Apache.

+ + + + diff --git a/docs/manual/configuring.html.ja.jis b/docs/manual/configuring.html.ja.jis index c1b41e52518..1e01e21b9a7 100644 --- a/docs/manual/configuring.html.ja.jis +++ b/docs/manual/configuring.html.ja.jis @@ -1,247 +1,30 @@ - - - -$B@_Dj%U%!%$%k(B - - + - - - -

$B%U%!%$%k$N@_Dj(B

+ + + -

$B%a%$%s$N@_Dj%U%!%$%k(B
$B@_Dj%U%!%$%k$N9=J8(B
$B%b%8%e!<%k(B
$B%G%#%l%/%F%#%V$NE,MQHO0O(B
.htaccess $B%U%!%$%k(B
$B%m%0%U%!%$%k(B

+ $B@_Dj%U%!%$%k(B + + + -

+ + -

$B%a%$%s$N@_Dj%U%!%$%k(B

$B%U%!%$%k$N@_Dj(B

- +

$B%a%$%s$N@_Dj%U%!%$%k(B

-$B4XO"%b%8%e!<%k(B

-mod_mime
-

-$B4XO"%G%#%l%/%F%#%V(B

-<IfDefine>
-Include
-TypesConfig
-

$B@_Dj%U%!%$%k$N9=J8(B

Apache $B$O(B $B%G%#%l%/%F%#%V(B $B$r(B -$B@_Dj%U%!%$%k$KJ?J8$G=q$/$3$H$K$h$j@_Dj$7$^$9!#%a%$%s$N(B -$B@_Dj%U%!%$%k$OIaDL$O(B httpd.conf $B$H$$$&L>A0$G$9!#(B -$B$3$N%U%!%$%k$N0LCV$O%3%s%Q%$%k;~$K@_Dj$5$l$^$9$,!"%3%^%s%I%i%$%s$N(B --f $B%U%i%0$K$h$j>e=q$-$G$-$^$9!#$=$N>e!"B>$N@_Dj%U%!%$%k$,(B -Include $B%G%#%l%/%F%#%V(B -$B$K$h$C$FDI2C$5$l$F$$$k$+$b$7$l$^$;$s!#$I$N%G%#%l%/%F%#%V$b(B -$B$3$l$i$N@_Dj%U%!%$%k$N$I$l$K$G$bF~$l$i$l$^$9!#(BApache $B$O5/F0;~$+(B -$B:F5/F0;~$N$_%a%$%s@_Dj%U%!%$%k$NJQ99$rG'<1$7$^$9!#(B

- -

Apache 1.3.13 $B$N?7$7$$5!G=$H$7$F!"@_Dj%U%!%$%k$,$l$N%[%9%H$KBP$7$F>.$5$J@_Dj(B -$B%U%!%$%k$r:n$j!"@_Dj%G%#%l%/%H%j$KCV$/$H$$$&$b$N$,5s$2$i$l$^$9!#(B -$B$3$&$9$k$H!"C1$K%U%!%$%k$NDI2C!":o=|$r$9$k$3$H$K$h$jA4$/%U%!%$%k$r(B -$BJT=8$9$k$3$H$J$/%P!<%A%c%k%[%9%H$NDI2C!":o=|$,$G$-$^$9!#$3$l$O<+F02=$r(B -$B$:$C$H4JC1$K$7$^$9!#(B

- -

-$B%5!<%P$O(B mime $B%I%-%e%a%s%H%?%$%W$r4^$s$G$$$k%U%!%$%k$bFI$_9~$_$^$9!#(B -$B%U%!%$%kL>$O(B TypesConfig $B$G@_Dj$5$l!"%G%U%)%k%H$G(B mime.types -$B$K$J$C$F$$$^$9!#(B

- -

$B@_Dj%U%!%$%k$N9=J8(B

- -

Apache $B@_Dj%U%!%$%k$O(B1$B9T$K(B1$B$D$N%G%#%l%/%F%#%V$+$i$J$j$^$9!#(B -$B%P%C%/%9%i%C%7%e(B "\" $B$O%G%#%l%/%F%#%V$,$NJ8;z$d6uGr$,$"$C$F$O$$$1$^$;$s!#(B

- -

$B@_Dj%U%!%$%k$N%G%#%l%/%F%#%V$OBgJ8;z>.J8;z$r6hJL$7$^$;$s$,!"(B -$B0z?t$K$O$7$P$7$P6hJL$9$k$b$N$,$"$j$^$9!#%O%C%7%eJ8;z(B "#" $B$G;O$^$k9T$O(B -$B%3%a%s%H$H8+$J$5$l$FL5;k$5$l$^$9!#@_Dj%G%#%l%/%F%#%V$N8e$N9T$G$O(B -$B%3%a%s%H$,4^$^$l$F$$$F$O(B$B$$$1$^$;$s(B$B!#%G%#%l%/%F%#%V$N(B -$BA0$N6u9T$H6uGr$OL5;k$5$l$^$9$N$G!"$o$+$j$d$9$/$9$k$?$a$K%G%#%l%/%F%#%V$r(B -$B%$%s%G%s%H$9$k$3$H$,$G$-$^$9!#(B

- -

$B@_Dj%U%!%$%k$N9=J8%(%i!<$O(B -apachectl configtest $B$+%3%^%s%I%i%$%s%*%W%7%g%s(B --t $B$r;H$C$FD4$Y$i$l$^$9!#(B

- -

$B%b%8%e!<%k(B

- - -

-$B4XO"%b%8%e!<%k(B

-mod_so
-

-$B4XO"%G%#%l%/%F%#%V(B

-AddModule
-ClearModuleList
-<IfModule>
-LoadModule
-

- -

Apache $B$O%b%8%e!<%k2=$5$l$?%5!<%P$G$9!#%3%"%5!<%P$K$O(B -$B0lHV4pK\E*$J5!G=$@$1$,4^$^$l$F$$$^$9!#3HD%5!G=$O(B Apache $B$K(B -$B%m!<%I$5$l$k(B$B%b%8%e!<%k(B$B$H$7$F(B -$BMxMQ2DG=$G$9!#%G%U%)%k%H$G$O%3%s%Q%$%k;~$K%b%8%e!<%k$N(B$B4pK\(B$B%;%C%H$,(B -$B%5!<%P$K4^$^$l$^$9!#%5!<%P$,(B$BF0E*%m!<%I(B$B%b%8%e!<%k$r(B -$B;H$&$h$&$K%3%s%Q%$%k$5$l$F$$$k>l9g$O!"%b%8%e!<%k$rJL$K%3%s%Q%$%k$7$F!"(B -$B$$$D$G$b(B LoadModule -$B%G%#%l%/%F%#%V$r;H$C$FDI2C$G$-$^$9!#$=$&$G$J$$>l9g$O!"%b%8%e!<%k$N(B -$BDI2C$d:o=|$r$9$k$?$a$K$O(B Apache $B$r:F%3%s%Q%$%k$9$kI,MW$,$"$j$^$9!#(B -$B@_Dj%G%#%l%/%F%#%V$O(B <IfModule> $B%V%m%C%/$K(B -$BF~$l$k$3$H$GFCDj$N%b%8%e!<%k$,B8:_$9$k$H$-$@$1(B -$B@_Dj%U%!%$%k$K4^$^$l$k$h$&$K$9$k$3$H$,$G$-$^$9!#(B

- -

$B%3%^%s%I%i%$%s%*%W%7%g%s(B -l $B$r;H$C$F(B -$B8=;~E@$G$I$N%b%8%e!<%k$,%5!<%P$K%3%s%Q%$%k$5$l$F$$$k$+$r(B -$BCN$k$3$H$,$G$-$^$9!#(B - -

- -

$B%G%#%l%/%F%#%V$NE,MQHO0O(B

- -

-$B4XO"%G%#%l%/%F%#%V(B

-<Directory>
-<DirectoryMatch>
-<Files>
-<FilesMatch>
-<Location>
-<LocationMatch>
-<VirtualHost>
-

- -

$B%a%$%s@_Dj%U%!%$%k$K$"$k%G%#%l%/%F%#%V$O%5!<%PA4BN$KE,MQ$5$l$^$9!#(B -$B%5!<%P$N0lItJ,$N@_Dj$@$1$rJQ99$7$?$$>l9g$O(B -<Directory>, -<DirectoryMatch>, -<Files>, -<FilesMatch>, -<Location>, -<LocationMatch> - -$B%;%/%7%g%s$NCf$KCV$/$3$H$GE,MQHO0O$r7h$a$i$l$^$9!#$3$l$i$N%;%/%7%g%s$O(B -$B$=$NCf$K$"$k%G%#%l%/%F%#%V$NE,MQHO0O$rFCDj$N%U%!%$%k%7%9%F%`$N0LCV$d(B -URL $B$K8BDj$7$^$9!#Hs>o$K:YN3EY$N@_Dj$r2DG=$K$9$k$?$a$K!"%;%/%7%g%s$r(B -$BF~$l;R$K$9$k$3$H$b$G$-$^$9!#(B

- -

Apache $B$OF1;~$KB?$/$N0c$&%&%'%V%5%$%H$r07$&G=NO$,$"$j$^$9!#(B -$B$3$l$O(B $B%P!<%A%c%k%[%9%H(B $B$H8F$P$l$F$$$^$9!#(B -$BFCDj$N%&%'%V%5%$%H$K$N$_E,MQ$5$l$k$h$&$K$9$k$?$a$K!"%G%#%l%/%F%#%V$O(B -<VirtualHost> -$B%;%/%7%g%s$NCf$KCV$/$3$H$G$bE,MQHO0O$rJQ$($k$3$H$,$G$-$^$9!#(B

- -

$B$[$H$s$I$N%G%#%l%/%F%#%V$O$I$N%;%/%7%g%s$K$G$b=q$1$^$9$,!"(B -$BCf$K$O%3%s%F%-%9%H$K$h$C$F$O0UL#$r$J$5$J$$$b$N$b$"$j$^$9!#Nc$($P!"(B -$B%W%m%;%9$N:n@.$r@)8f$7$F$$$k%G%#%l%/%F%#%V$O%a%$%s%5!<%P$N%3%s%F%-%9%H$K(B -$B$N$_=q$/$3$H$,$G$-$^$9!#$I$N%G%#%l%/%F%#%V$r$I$N%;%/%7%g%s$K=q$/$3$H$,(B -$B$G$-$k$+$rCN$k$?$a$K$O%G%#%l%/%F%#%V$N(B -$B%3%s%F%-%9%H(B$B$rD4$Y$F$/$@$5$$!#(B -$B>\$7$$>pJs$O!"(BDirectory, Location, Files $B%;%/%7%g%s$NF0:nK!(B -$B$K$"$j$^$9!#(B

- -

.htaccess $B%U%!%$%k(B

- -

-$B4XO"%G%#%l%/%F%#%V(B

-AccessFileName
-AllowOverride
-

- -

Apache $B$G$O%&%'%V%D%j!<$NCf$KCV$+$l$?FCJL$J%U%!%$%k$r;H$C$F(B -$BHsCf1{=88"E*$J@_Dj4IM}$r$G$-$^$9!#$=$NFCJL$J%U%!%$%k$OIaDL$O(B -.htaccess $B$H$$$&L>A0$G!"(B -AccessFileName $B%G%#%l%/%F%#%V$G$I$s$JL>A0$G$b;XDj$G$-$^$9!#(B -.htaccess $B%U%!%$%k$K=q$+$l$?%G%#%l%/%F%#%V$O%U%!%$%k$r(B -$BCV$$$?%G%#%l%/%H%j$H$=$NA4$F$N%5%V%G%#%l%/%H%j$KE,MQ$5$l$^$9!#(B -.htaccess $B%U%!%$%k$O$9$Y$F$N%j%/%(%9%H$G(B -$BFI$_9~$^$l$k$?$a!"JQ99$O$9$0$KH?1G$5$l$^$9!#(B - -

$B$I$N%G%#%l%/%F%#%V$,(B .htaccess $B%U%!%$%k$K=q$1$k$+$r(B -$BD4$Y$k$K$O!"%G%#%l%/%F%#%V$N(B -$B%3%s%F%-%9%H(B $B$rD4$Y$F$/$@$5$$!#(B -$B%5!<%P4IM}AllowOverride -$B$r@_Dj$9$k$3$H$G$I$N%G%#%l%/%F%#%V$r(B .htaccess $B%U%!%$%k$K(B -$B=q$1$k$h$&$K$9$k$+$r@)8f$9$k$3$H$,$G$-$^$9!#(B

- -

$B%m%0%U%!%$%k(B

- -

$B%;%-%e%j%F%#$K4X$9$k7Y9p(B

-Apache $B$,%m%0%U%!%$%k$r=q$$$F$$$k%G%#%l%/%H%j$K=q$-9~$a$k?M$OC/$G$b(B -$B$[$\3N$B$7$J$$(B$B$G$/$@$5$$!#>\:Y$O(B -$B%;%-%e%j%F%#>pJs(B$B$r;2>H$7$F$/$@$5$$!#(B

- -

pid $B%U%!%$%k(B

- -

$B5/F0;~$K(B Apache $B$O?F(B httpd $B%W%m%;%9$N%W%m%;%9(B ID $B$r(B -logs/httpd.pid $B%U%!%$%k$KJ]B8$7$^$9!#$3$N%U%!%$%kL>$O(B -PidFile -$B%G%#%l%/%F%#%V$GJQ99$9$k$3$H$,$G$-$^$9!#%W%m%;%9(B ID $B$O4IM}\$7$$>pJs$O(B$B5/F0$H=*N;(B$B$r;2>H$7$F$/$@$5$$!#(B

- -

-$B%W%m%;%9$,0[>o=*N;$9$k(B ($B$b$7$/$O(B kill $B$5$l$k(B) $B$H!";R(B httpd $B%W%m%;%9$r(B -kill $B$9$kI,MW$,$"$j$^$9!#(B

- -

$B%(%i!<%m%0(B

- -

$B%5!<%P$O%(%i!<%a%C%;!<%8$r%m%0%U%!%$%k$K5-O?$7$^$9!#%G%U%)%k%H$O!"(BUnix -$B$G$O(B logs/error_log $B$G(B Windows $B$H(B OS/2 $B$G$O(B -logs/error.log $B$G$9!#%U%!%$%kL>$O(B ErrorLog $B%G%#%l%/%F%#%V$G@_Dj$G$-$^$9!#(B -$B0c$&(B$B%P!<%A%c%k%[%9%H(B -$B$K0c$&%(%i!<%m%0$r@_Dj$9$k$3$H$,$G$-$^$9!#(B

- -

$BE>Aw%m%0(B

- -

$B%5!<%P$OIaDL$=$l$>$l$N%j%/%(%9%H$rE>Aw%U%!%$%k$K%m%0$rlogs/access_log $B$G(B Windows $B$H(B -OS/2 $B$G$O(B logs/access.log $B$G$9!#%U%!%$%kL>$O(B -CustomLog -$B%G%#%l%/%F%#%V$r$G@_Dj$G$-$^$9!#0c$&(B$B%P!<%A%c%k%[%9%H(B$B$K(B -$B0c$&E>Aw%m%0$r@_Dj$9$k$3$H$,$G$-$^$9!#(B

- - - - +

$B%b%8%e!

+ + + diff --git a/docs/manual/content-negotiation.html b/docs/manual/content-negotiation.html index a813fcf8c94..b5af8bf892f 100644 --- a/docs/manual/content-negotiation.html +++ b/docs/manual/content-negotiation.html @@ -1,132 +1,127 @@ - - - -Apache 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.

- -Content negotiation is provided by the -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 -appropriate choice is to give the user an index page, and let them -select. However it is often possible for the server to choose -automatically. This works because browsers can send as part of each -request information about what representations they prefer. For -example, a browser could indicate that it would like to see -information in French, if possible, else English will do. Browsers -indicate their preferences by headers in the request. To request only -French representations, the browser would send - -

+
+
+
+  
+    
+
+    Apache 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.
+
+    Content negotiation is provided by the 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 appropriate choice is to give the
+    user an index page, and let them select. However it is often
+    possible for the server to choose automatically. This works
+    because browsers can send as part of each request information
+    about what representations they prefer. For example, a browser
+    could indicate that it would like to see information in French,
+    if possible, else English will do. Browsers indicate their
+    preferences by headers in the request. To request only French
+    representations, the browser would send
+   Accept-Language: fr
-
-
-
-Note that this preference will only be applied when there is a choice
-of representations and they vary by language.
-

-
-As an example of a more complex request, this browser has been
-configured to accept French and English, but prefer French, and to
-accept various media types, preferring HTML over plain text or other
-text types, and preferring GIF or JPEG over other media types, but also
-allowing any other media type as a last resort:
-
-
+
+
+    Note that this preference will only be applied when there is
+    a choice of representations and they vary by language.
+
+    As an example of a more complex request, this browser has
+    been configured to accept French and English, but prefer
+    French, and to accept various media types, preferring HTML over
+    plain text or other text types, and preferring GIF or JPEG over
+    other media types, but also allowing any other media type as a
+    last resort:
+   Accept-Language: fr; q=1.0, en; q=0.5
   Accept: text/html; q=1.0, text/*; q=0.8, image/gif; q=0.6,
         image/jpeg; q=0.6, image/*; q=0.5, */*; q=0.1
-
-
-Apache 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.
-Apache 1.3.4 also supports 'transparent' content negotiation, which is
-an experimental negotiation protocol defined in RFC 2295 and RFC 2296.
-It does not offer support for 'feature negotiation' as defined in
-these RFCs.  
-
-
-A resource is a conceptual entity identified by a URI
-(RFC 2396).  An HTTP server like Apache provides access to
-representations of the resource(s) within its namespace,
-with each representation in the form of a sequence of bytes with a
-defined media type, character set, encoding, etc.  Each resource may be
-associated with zero, one, or more than one representation
-at any given time.  If multiple representations are available,
-the resource is referred to as negotiable and each of its
-representations is termed a variant. The ways in which the
-variants for a negotiable resource vary are called the
-dimensions of negotiation.
-
-
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 (i.e., a *.var file) which
-       names the files containing the variants explicitly, or
-  
 Using a 'MultiViews' search, where the server does an implicit
-       filename pattern match and chooses from among the results.
-
-
-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
-older Apache configurations, the mime type
-application/x-type-map).  Note that to use this feature,
-you must have a handler set in the configuration that defines a
-file suffix as type-map; this is best done with a
-
-
+
+    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. Apache 1.3.4 also supports 'transparent'
+    content negotiation, which is an experimental negotiation
+    protocol defined in RFC 2295 and RFC 2296. It does not offer
+    support for 'feature negotiation' as defined in these RFCs. 
+
+    A resource is a conceptual entity
+    identified by a URI (RFC 2396). An HTTP server like Apache
+    provides access to representations of the
+    resource(s) within its namespace, with each representation in
+    the form of a sequence of bytes with a defined media type,
+    character set, encoding, etc. Each resource may be associated
+    with zero, one, or more than one representation at any given
+    time. If multiple representations are available, the resource
+    is referred to as negotiable and each of its
+    representations is termed a variant. The ways
+    in which the variants for a negotiable resource vary are called
+    the dimensions of negotiation.
+
+    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 (i.e., a *.var
+      file) which names the files containing the variants
+      explicitly, or
+
+      Using a 'MultiViews' search, where the server does an
+      implicit filename pattern match and chooses from among the
+      results.
+    
+
+    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 older Apache configurations, the
+    mime type application/x-type-map). Note that to
+    use this feature, you must have a handler set in the
+    configuration that defines a file suffix as
+    type-map; this is best done with a
+   AddHandler type-map .var
-
-
-in the server configuration file.
-
-Type map files should have the same name as the resource which they are
-describing, and have an entry for each available variant; these entries
-consist of contiguous HTTP-format header lines.  Entries for
-different variants are separated by blank lines.  Blank lines are
-illegal within an entry.  It is conventional to begin a map file with
-an entry for the combined entity as a whole (although this
-is not required, and if present will be ignored). An example
-map file is shown below. This file would be named foo.html,
-as it describes a resource named foo.
-
-
+
+    in the server configuration file. 
+
+    Type map files should have the same name as the resource
+    which they are describing, and have an entry for each available
+    variant; these entries consist of contiguous HTTP-format header
+    lines. Entries for different variants are separated by blank
+    lines. Blank lines are illegal within an entry. It is
+    conventional to begin a map file with an entry for the combined
+    entity as a whole (although this is not required, and if
+    present will be ignored). An example map file is shown below.
+    This file would be named foo.html, as it describes
+    a resource named foo.
+   URI: foo
 
   URI: foo.en.html
@@ -136,16 +131,13 @@ as it describes a resource named foo.
   URI: foo.fr.de.html
   Content-type: text/html;charset=iso-8859-2
   Content-language: fr, de
-
-
-Note also that a typemap file will take precedence over the filename's
-extension, even when Multiviews is on.
-
-If the variants have different source qualities, that may be indicated
-by the "qs" parameter to the media type, as in this picture (available
-as jpeg, gif, or ASCII-art):
-
-+
+    Note also that a typemap file will take precedence over the
+    filename's extension, even when Multiviews is on. If the
+    variants have different source qualities, that may be indicated
+    by the "qs" parameter to the media type, as in this picture
+    (available as jpeg, gif, or ASCII-art): 
+   URI: foo
 
   URI: foo.jpeg
@@ -156,445 +148,504 @@ as jpeg, gif, or ASCII-art):
 
   URI: foo.txt
   Content-type: text/plain; qs=0.01
-
-
-
-qs values can vary in the range 0.000 to 1.000. Note that any variant with
-a qs value of 0.000 will never be chosen. Variants with no 'qs'
-parameter value are given a qs factor of 1.0. The qs parameter indicates
-the relative 'quality' of this variant compared to the other available
-variants, independent of the client's capabilities.  For example, a jpeg
-file is usually of higher source quality than an ascii file if it is
-attempting to represent a photograph.  However, if the resource being
-represented is an original ascii art, then an ascii representation would
-have a higher source quality than a jpeg representation.  A qs value
-is therefore specific to a given variant depending on the nature of
-the resource it represents.
-
-

-The full list of headers recognized is:
-
-

-   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
-       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 tag from RFC 1766 (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.
-       Apache only recognizes encodings that are defined by an
-       AddEncoding directive.
-       This normally includes the encodings x-compress
-       for compress'd files, and x-gzip for gzip'd files.
-       The x- prefix is ignored for encoding comparisons.
-  
 Content-Length:
-  
 The size of the file in bytes.  Specifying content
-       lengths in the type-map allows the server to compare file sizes
-       without checking the actual files.
-  
 Description:
-  
 A human-readable textual description of the variant.  If Apache cannot
-       find any appropriate variant to return, it will return an error 
-       response which lists all available variants instead.  Such a variant
-       list will include the human-readable variant descriptions.
-
-
-Using a type map file is preferred over MultiViews because
-it requires less CPU time, and less file access, to parse a file
-explicitly listing the various resource variants, than to have to look
-at every matching file, and parse its file extensions.
-
-Multiviews
-
-
-MultiViews 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
-have to ask for it by name.
-
-

-The effect of MultiViews is as follows: if the server
-receives a request for /some/dir/foo, if
-/some/dir has MultiViews enabled, and
-/some/dir/foo does not exist, then the server reads the
-directory looking for files named foo.*, and effectively fakes up a
-type map which names all those files, assigning them the same media
-types and content-encodings it would have if the client had asked for
-one of them by name.  It then chooses the best match to the client's
-requirements.
-
-

-MultiViews may also apply to searches for the file named by the
-DirectoryIndex directive, if the server is trying to
-index a directory. If the configuration files specify
-
-
+
+
+    qs values can vary in the range 0.000 to 1.000. Note that
+    any variant with a qs value of 0.000 will never be chosen.
+    Variants with no 'qs' parameter value are given a qs factor of
+    1.0. The qs parameter indicates the relative 'quality' of this
+    variant compared to the other available variants, independent
+    of the client's capabilities. For example, a jpeg file is
+    usually of higher source quality than an ascii file if it is
+    attempting to represent a photograph. However, if the resource
+    being represented is an original ascii art, then an ascii
+    representation would have a higher source quality than a jpeg
+    representation. A qs value is therefore specific to a given
+    variant depending on the nature of the resource it
+    represents.
+
+    The full list of headers recognized is:
+
+    
+      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 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 tag from RFC 1766 (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. Apache only recognizes encodings that are defined by an
+      AddEncoding
+      directive. This normally includes the encodings
+      x-compress for compress'd files, and
+      x-gzip for gzip'd files. The x-
+      prefix is ignored for encoding comparisons.
+
+      Content-Length:
+
+      The size of the file in bytes. Specifying content lengths
+      in the type-map allows the server to compare file sizes
+      without checking the actual files.
+
+      Description:
+
+      A human-readable textual description of the variant. If
+      Apache cannot find any appropriate variant to return, it will
+      return an error response which lists all available variants
+      instead. Such a variant list will include the human-readable
+      variant descriptions.
+    
+    Using a type map file is preferred over MultiViews
+    because it requires less CPU time, and less file access, to
+    parse a file explicitly listing the various resource variants,
+    than to have to look at every matching file, and parse its file
+    extensions. 
+
+    Multiviews
+
+    MultiViews 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 have to ask for it by name.
+
+    The effect of MultiViews is as follows: if the
+    server receives a request for /some/dir/foo, if
+    /some/dir has MultiViews enabled, and
+    /some/dir/foo does not exist, then the
+    server reads the directory looking for files named foo.*, and
+    effectively fakes up a type map which names all those files,
+    assigning them the same media types and content-encodings it
+    would have if the client had asked for one of them by name. It
+    then chooses the best match to the client's requirements.
+
+    MultiViews may also apply to searches for the
+    file named by the DirectoryIndex directive, if the
+    server is trying to index a directory. If the configuration
+    files specify
+   DirectoryIndex index
-
-
-then the server will arbitrate between index.html
-and index.html3 if both are present.  If neither are
-present, and index.cgi is there, the server will run it.
-
-
-If one of the files found when reading the directive is a CGI script,
-it's not obvious what should happen.  The code gives that case
-special treatment --- if the request was a POST, or a GET with
-QUERY_ARGS or PATH_INFO, the script is given an extremely high quality
-rating, and generally invoked; otherwise it is given an extremely low
-quality rating, which generally causes one of the other views (if any)
-to be retrieved.
-
-
The Negotiation Methods
-
-After Apache has obtained a list of the variants for a given resource,
-either from a type-map file or from the filenames in the directory, it
-invokes one of two methods to decide on the 'best' variant to
-return, if any.  It is not necessary to know any of the details of how
-negotiation actually takes place in order to use Apache's content
-negotiation features. However the rest of this document explains the
-methods used for those interested.
-
-
-There are two negotiation methods:
-
-
 
-
-Server driven negotiation with the Apache
-algorithm is used in the normal case.  The Apache algorithm is
-explained in more detail below.  When this algorithm is used, Apache
-can sometimes 'fiddle' the quality factor of a particular dimension to
-achieve a better result. The ways Apache can fiddle quality factors is
-explained in more detail below.
-
-
Transparent content negotiation is used when the
-browser specifically requests this through the mechanism defined in RFC
-2295.  This negotiation method gives the browser full control over
-deciding on the 'best' variant, the result is therefore dependent on
-the specific algorithms used by the browser.  As part of the
-transparent negotiation process, the browser can ask Apache to run the
-'remote variant selection algorithm' defined in RFC 2296.
-
-
-
-
-Dimensions of Negotiation
-
-
-
-
-
-
-
-Dimension
- Notes
-
Media Type
- Browser indicates preferences with the Accept header field. Each item
-can have an associated quality factor. Variant description can also
-have a quality factor (the "qs" parameter).
-
Language
- Browser indicates preferences with the Accept-Language header field.
-Each item can have a quality factor. Variants can be associated with none, one
-or more than one language.
-
Encoding
- Browser indicates preference with the Accept-Encoding header field.
-Each item can have a quality factor.
-
Charset
- Browser indicates preference with the Accept-Charset header field.
-Each item can have a quality factor.
-Variants can indicate a charset as a parameter of the media type.
-
-
-Apache Negotiation Algorithm
-
-
-Apache can use the following algorithm to select the 'best' variant
-(if any) to return to the browser.  This algorithm is not
-further configurable. It operates as follows:
-
-

-First, for each dimension of the negotiation, check the appropriate
-Accept* header field and assign a quality to each
-variant. If the Accept* header for any dimension implies that this
-variant is not acceptable, eliminate it. If no variants remain, go
-to step 4.
-
-
Select the 'best' variant by a process of elimination. Each of the
-following tests is applied in order. Any variants not selected at each
-test are eliminated. After each test, if only one variant remains,
-select it as the best match and proceed to step 3. If more than one
-variant remains, move on to the next test.
-
-
-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.
-
-
Select the variants with the highest language quality factor.
-
-
Select the variants with the best language match, using either the
-  order of languages in the Accept-Language header (if present), or else 
-  the order of languages in the LanguagePriority 
-  directive (if present).
-
-
Select the variants with the highest 'level' media parameter
-  (used to give the version of text/html media types).
-
-
Select variants with the best charset media parameters,
-  as given on the Accept-Charset header line. Charset ISO-8859-1
-  is acceptable unless explicitly excluded. Variants with a
-  text/* media type but not explicitly associated
-  with a particular charset are assumed to be in ISO-8859-1.
-
-
Select those variants which have associated
-    charset media parameters that are not ISO-8859-1.
-    If there are no such variants, select all variants instead.
-
-
Select the variants with the best encoding. If there are
-  variants with an encoding that is acceptable to the user-agent,
-  select only these variants. Otherwise if there is a mix of encoded
-  and non-encoded variants, select only the unencoded variants.
-  If either all variants are encoded or all variants are not encoded, 
-  select all variants.
-
-
Select the variants with the smallest content length.
-
-
Select the first variant of those remaining. This will be either the
-  first listed in the type-map file, or when variants are read from
-  the directory, the one whose file name comes first when sorted using
-  ASCII code order.
-
-
-
-
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.
-
-
To get here means no variant was selected (because none 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
-
- 
-Apache sometimes changes the quality values from what would be
-expected by a strict interpretation of the Apache negotiation
-algorithm above. This is to get a better result from the algorithm for
-browsers which do not send full or accurate information. Some of the
-most popular browsers send Accept header information which would
-otherwise result in the selection of the wrong variant in many
-cases. If a browser sends full and correct information these fiddles
-will not be applied.
-

-
-
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:
-
+
+    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 special treatment --- if the request was a POST, or a
+    GET with QUERY_ARGS or PATH_INFO, the script is given an
+    extremely high quality rating, and generally invoked; otherwise
+    it is given an extremely low quality rating, which generally
+    causes one of the other views (if any) to be retrieved.
+
+    The Negotiation Methods
+    After Apache has obtained a list of the variants for a given
+    resource, either from a type-map file or from the filenames in
+    the directory, it invokes one of two methods to decide on the
+    'best' variant to return, if any. It is not necessary to know
+    any of the details of how negotiation actually takes place in
+    order to use Apache's content negotiation features. However the
+    rest of this document explains the methods used for those
+    interested. 
+
+    There are two negotiation methods:
+
+    
+      Server driven negotiation with the Apache
+      algorithm is used in the normal case. The Apache
+      algorithm is explained in more detail below. When this
+      algorithm is used, Apache can sometimes 'fiddle' the quality
+      factor of a particular dimension to achieve a better result.
+      The ways Apache can fiddle quality factors is explained in
+      more detail below.
+
+      Transparent content negotiation is used
+      when the browser specifically requests this through the
+      mechanism defined in RFC 2295. This negotiation method gives
+      the browser full control over deciding on the 'best' variant,
+      the result is therefore dependent on the specific algorithms
+      used by the browser. As part of the transparent negotiation
+      process, the browser can ask Apache to run the 'remote
+      variant selection algorithm' defined in RFC 2296.
+    
+
+    Dimensions of Negotiation
+
+    
+      
+        
+
+        
+      
+
+      
+        
+
+        
+      
+
+      
+        
+
+        
+      
+
+      
+        
+
+        
+      
+
+      
+        
+
+        
+      
+    Dimension Notes
Media Type Browser indicates preferences with the Accept header
+        field. Each item can have an associated quality factor.
+        Variant description can also have a quality factor (the
+        "qs" parameter).
Language Browser indicates preferences with the Accept-Language
+        header field. Each item can have a quality factor. Variants
+        can be associated with none, one or more than one
+        language.
Encoding Browser indicates preference with the Accept-Encoding
+        header field. Each item can have a quality factor.
Charset Browser indicates preference with the Accept-Charset
+        header field. Each item can have a quality factor. Variants
+        can indicate a charset as a parameter of the media
+        type.
+
+    Apache Negotiation Algorithm
+
+    Apache can use the following algorithm to select the 'best'
+    variant (if any) to return to the browser. This algorithm is
+    not further configurable. It operates as follows:
+
+    
+      First, for each dimension of the negotiation, check the
+      appropriate Accept* header field and assign a
+      quality to each variant. If the Accept* header for
+      any dimension implies that this variant is not acceptable,
+      eliminate it. If no variants remain, go to step 4.
+
+      
+        Select the 'best' variant by a process of elimination. Each
+        of the following tests is applied in order. Any variants
+        not selected at each test are eliminated. After each test,
+        if only one variant remains, select it as the best match
+        and proceed to step 3. If more than one variant remains,
+        move on to the next test. 
+
+        
+          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.
+
+          Select the variants with the highest language quality
+          factor.
+
+          Select the variants with the best language match,
+          using either the order of languages in the
+          Accept-Language header (if present), or else the order of
+          languages in the LanguagePriority directive
+          (if present).
+
+          Select the variants with the highest 'level' media
+          parameter (used to give the version of text/html media
+          types).
+
+          Select variants with the best charset media
+          parameters, as given on the Accept-Charset header line.
+          Charset ISO-8859-1 is acceptable unless explicitly
+          excluded. Variants with a text/* media type
+          but not explicitly associated with a particular charset
+          are assumed to be in ISO-8859-1.
+
+          Select those variants which have associated charset
+          media parameters that are not ISO-8859-1. If
+          there are no such variants, select all variants
+          instead.
+
+          Select the variants with the best encoding. If there
+          are variants with an encoding that is acceptable to the
+          user-agent, select only these variants. Otherwise if
+          there is a mix of encoded and non-encoded variants,
+          select only the unencoded variants. If either all
+          variants are encoded or all variants are not encoded,
+          select all variants.
+
+          Select the variants with the smallest content
+          length.
+
+          Select the first variant of those remaining. This
+          will be either the first listed in the type-map file, or
+          when variants are read from the directory, the one whose
+          file name comes first when sorted using ASCII code
+          order.
+        
+      
+
+      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.
+
+      To get here means no variant was selected (because none
+      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
+
+    Apache sometimes changes the quality values from what would
+    be expected by a strict interpretation of the Apache
+    negotiation algorithm above. This is to get a better result
+    from the algorithm for browsers which do not send full or
+    accurate information. Some of the most popular browsers send
+    Accept header information which would otherwise result in the
+    selection of the wrong variant in many cases. If a browser
+    sends full and correct information these fiddles will not be
+    applied.
+
+    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:
-+
+    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
-available, that is ok too. However under the basic algorithm, as given
-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:
-+
+    The intention of this is to indicate that the explicitly listed
+    types are preferred, but if a different representation is
+    available, that is ok too. However under the basic algorithm,
+    as given 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
-the q value of "*/*", if present, to 0.01 to emulate the desired
-behavior. It also sets the q value of wildcards of the format
-"type/*" to 0.02 (so these are preferred over matches against
-"*/*". If any media type on the Accept: header contains a q factor,
-these special values are not applied, so requests from browsers
-which send the 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.

-
-The reason for setting this language quality factor for
-variant with no language to a very low value is to allow
-for a default variant which can be supplied if none of the
-other variants match the browser's language preferences.
-
-For example, consider the situation with three variants:
-
-

-foo.en.html, language en
-
foo.fr.html, language en
-
foo.html, no language
-
-
-
-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
-or foo.fr.html will be returned. If the browser does not list
-either en or fr as acceptable, foo.html will be returned instead.
-
-
Extensions to Transparent Content Negotiation
-
-Apache extends the transparent content negotiation protocol (RFC 2295)
-as follows.  A new  {encoding ..} element is used in
-variant lists to label variants which are available with a specific
-content-encoding only. The implementation of the
-RVSA/1.0 algorithm (RFC 2296) is extended to recognize encoded
-variants in the list, and to use them as candidate variants whenever
-their encodings are acceptable according to the Accept-Encoding
-request header.  The RVSA/1.0 implementation does not round computed
-quality factors to 5 decimal places before choosing the best variant.
-
-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 the mod_mime
-documentation for details).
-

-A typical file has a MIME-type extension (e.g., html),
-maybe an encoding extension (e.g., gz), and of course a
-language extension (e.g., en) when we have different
-language variants of this file.
-
-

-Examples:
-

-foo.en.html
-
foo.html.en
-
foo.en.html.gz
-
-
-
-Here some more examples of filenames together with valid and invalid
-hyperlinks:
-
-
-
-
- 
- 
- 
-
-
- 
- 
- 
-
-
- 
- 
- 
-
-
- 
- 
- 
-
-
- 
- 
- 
-
-
- 
- 
- 
-
-
- 
- 
- 
-
-Filename Valid hyperlink Invalid hyperlink
foo.html.en foo

-     foo.html -
foo.en.html foo foo.html
foo.html.en.gz foo

-     foo.html foo.gz

-     foo.html.gz
foo.en.html.gz foo foo.html

-     foo.html.gz

-     foo.gz
foo.gz.html.en foo

-     foo.gz

-     foo.gz.html foo.html
foo.html.gz.en foo

-     foo.html

-     foo.html.gz foo.gz
-
-
-Looking at the table above you will notice that it is always possible to
-use the name without any extensions  in 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
-hyperlink references.
-
-

-If you want to continue to use a MIME-type in your hyperlinks (e.g.
-foo.html) the language extension (including an encoding extension
-if there is one) must be on the right hand side of the MIME-type extension
-(e.g., foo.html.en).
-
-
-
Note on Caching
-
-
-When a cache stores a representation, it associates it with the request URL.
-The next time that URL is requested, the cache can use the stored
-representation. But, if the resource is negotiable at the server,
-this might result in only the first requested variant being cached and
-subsequent cache hits might return the wrong response. To prevent this,
-Apache normally marks all responses that are returned after content negotiation
-as non-cacheable by HTTP/1.0 clients. Apache also supports the HTTP/1.1
-protocol features to allow caching of negotiated responses. 

-
-For requests which come from a HTTP/1.0 compliant client (either a
-browser or a cache), the directive CacheNegotiatedDocs can be
-used to allow caching of responses which were subject to negotiation.
-This directive can be given in the server config or virtual host, and
-takes no arguments. It has no effect on requests from HTTP/1.1 clients.
-
-
-
-
+

Dimension -	Notes -
Media Type -	Browser indicates preferences with the Accept header field. Each item -can have an associated quality factor. Variant description can also -have a quality factor (the "qs" parameter). -
Language -	Browser indicates preferences with the Accept-Language header field. -Each item can have a quality factor. Variants can be associated with none, one -or more than one language. -
Encoding -	Browser indicates preference with the Accept-Encoding header field. -Each item can have a quality factor. -
Charset -	Browser indicates preference with the Accept-Charset header field. -Each item can have a quality factor. -Variants can indicate a charset as a parameter of the media type. -

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

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

+ The explicit types have no quality factor, so they default to a + preference of 1.0 (the highest). The wildcard */* is given a + low preference of 0.01, so other types will only be returned if + no variant matches an explicitly listed type. + +

If the Accept: header contains no q factors at all, + Apache sets the q value of "*/*", if present, to 0.01 to + emulate the desired behavior. It also sets the q value of + wildcards of the format "type/*" to 0.02 (so these are + preferred over matches against "*/*". If any media type on the + Accept: header contains a q factor, these special values are + not applied, so requests from browsers which send the + 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.

+ +

The reason for setting this language quality factor for + variant with no language to a very low value is to allow for a + default variant which can be supplied if none of the other + variants match the browser's language preferences. For example, + consider the situation with three variants:

+ +

foo.en.html, language en
foo.fr.html, language en
foo.html, no language

+ +

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 or foo.fr.html will be returned. If the browser + does not list either en or fr as acceptable, foo.html will be + returned instead.

+ +

Extensions to Transparent Content Negotiation

+ Apache extends the transparent content negotiation protocol + (RFC 2295) as follows. A new {encoding ..} element + is used in variant lists to label variants which are available + with a specific content-encoding only. The implementation of + the RVSA/1.0 algorithm (RFC 2296) is extended to recognize + encoded variants in the list, and to use them as candidate + variants whenever their encodings are acceptable according to + the Accept-Encoding request header. The RVSA/1.0 implementation + does not round computed quality factors to 5 decimal places + before choosing the best variant. + +

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 the mod_mime documentation + for details).

+ +

A typical file has a MIME-type extension (e.g., + html), maybe an encoding extension (e.g., + gz), and of course a language extension + (e.g., en) when we have different + language variants of this file.

+ +

Examples:

+ +

foo.en.html
foo.html.en
foo.en.html.gz

+ +

Here some more examples of filenames together with valid and + invalid hyperlinks:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Filename	Valid hyperlink	Invalid hyperlink
foo.html.en	foo + foo.html	-
foo.en.html	foo	foo.html
foo.html.en.gz	foo + foo.html	foo.gz + foo.html.gz
foo.en.html.gz	foo	foo.html + foo.html.gz + foo.gz
foo.gz.html.en	foo + foo.gz + foo.gz.html	foo.html
foo.html.gz.en	foo + foo.html + foo.html.gz	foo.gz

+ +

Looking at the table above you will notice that it is always + possible to use the name without any extensions in 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 + hyperlink references.

+ +

If you want to continue to use a MIME-type in your + hyperlinks (e.g. foo.html) the language + extension (including an encoding extension if there is one) + must be on the right hand side of the MIME-type extension + (e.g., foo.html.en).

+ +

Note on Caching

+ +

When a cache stores a representation, it associates it with + the request URL. The next time that URL is requested, the cache + can use the stored representation. But, if the resource is + negotiable at the server, this might result in only the first + requested variant being cached and subsequent cache hits might + return the wrong response. To prevent this, Apache normally + marks all responses that are returned after content negotiation + as non-cacheable by HTTP/1.0 clients. Apache also supports the + HTTP/1.1 protocol features to allow caching of negotiated + responses.

+ +

For requests which come from a HTTP/1.0 compliant client + (either a browser or a cache), the directive + CacheNegotiatedDocs can be used to allow caching of + responses which were subject to negotiation. This directive can + be given in the server config or virtual host, and takes no + arguments. It has no effect on requests from HTTP/1.1 clients. + +

+ + + diff --git a/docs/manual/content-negotiation.html.en b/docs/manual/content-negotiation.html.en index a813fcf8c94..b5af8bf892f 100644 --- a/docs/manual/content-negotiation.html.en +++ b/docs/manual/content-negotiation.html.en @@ -1,132 +1,127 @@ - - - -Apache Content Negotiation - - - - - -

Content Negotiation

- -

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

- -

About Content Negotiation

- -

+
+
+
+  
+    
+
+    Apache 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.
+
+    Content negotiation is provided by the 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 appropriate choice is to give the
+    user an index page, and let them select. However it is often
+    possible for the server to choose automatically. This works
+    because browsers can send as part of each request information
+    about what representations they prefer. For example, a browser
+    could indicate that it would like to see information in French,
+    if possible, else English will do. Browsers indicate their
+    preferences by headers in the request. To request only French
+    representations, the browser would send
+   Accept-Language: fr
-
-
-
-Note that this preference will only be applied when there is a choice
-of representations and they vary by language.
-

-
-As an example of a more complex request, this browser has been
-configured to accept French and English, but prefer French, and to
-accept various media types, preferring HTML over plain text or other
-text types, and preferring GIF or JPEG over other media types, but also
-allowing any other media type as a last resort:
-
-
+
+
+    Note that this preference will only be applied when there is
+    a choice of representations and they vary by language.
+
+    As an example of a more complex request, this browser has
+    been configured to accept French and English, but prefer
+    French, and to accept various media types, preferring HTML over
+    plain text or other text types, and preferring GIF or JPEG over
+    other media types, but also allowing any other media type as a
+    last resort:
+   Accept-Language: fr; q=1.0, en; q=0.5
   Accept: text/html; q=1.0, text/*; q=0.8, image/gif; q=0.6,
         image/jpeg; q=0.6, image/*; q=0.5, */*; q=0.1
-
-
-Apache 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.
-Apache 1.3.4 also supports 'transparent' content negotiation, which is
-an experimental negotiation protocol defined in RFC 2295 and RFC 2296.
-It does not offer support for 'feature negotiation' as defined in
-these RFCs.  
-
-
-A resource is a conceptual entity identified by a URI
-(RFC 2396).  An HTTP server like Apache provides access to
-representations of the resource(s) within its namespace,
-with each representation in the form of a sequence of bytes with a
-defined media type, character set, encoding, etc.  Each resource may be
-associated with zero, one, or more than one representation
-at any given time.  If multiple representations are available,
-the resource is referred to as negotiable and each of its
-representations is termed a variant. The ways in which the
-variants for a negotiable resource vary are called the
-dimensions of negotiation.
-
-
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 (i.e., a *.var file) which
-       names the files containing the variants explicitly, or
-  
 Using a 'MultiViews' search, where the server does an implicit
-       filename pattern match and chooses from among the results.
-
-
-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
-older Apache configurations, the mime type
-application/x-type-map).  Note that to use this feature,
-you must have a handler set in the configuration that defines a
-file suffix as type-map; this is best done with a
-
-
+
+    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. Apache 1.3.4 also supports 'transparent'
+    content negotiation, which is an experimental negotiation
+    protocol defined in RFC 2295 and RFC 2296. It does not offer
+    support for 'feature negotiation' as defined in these RFCs. 
+
+    A resource is a conceptual entity
+    identified by a URI (RFC 2396). An HTTP server like Apache
+    provides access to representations of the
+    resource(s) within its namespace, with each representation in
+    the form of a sequence of bytes with a defined media type,
+    character set, encoding, etc. Each resource may be associated
+    with zero, one, or more than one representation at any given
+    time. If multiple representations are available, the resource
+    is referred to as negotiable and each of its
+    representations is termed a variant. The ways
+    in which the variants for a negotiable resource vary are called
+    the dimensions of negotiation.
+
+    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 (i.e., a *.var
+      file) which names the files containing the variants
+      explicitly, or
+
+      Using a 'MultiViews' search, where the server does an
+      implicit filename pattern match and chooses from among the
+      results.
+    
+
+    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 older Apache configurations, the
+    mime type application/x-type-map). Note that to
+    use this feature, you must have a handler set in the
+    configuration that defines a file suffix as
+    type-map; this is best done with a
+   AddHandler type-map .var
-
-
-in the server configuration file.
-
-Type map files should have the same name as the resource which they are
-describing, and have an entry for each available variant; these entries
-consist of contiguous HTTP-format header lines.  Entries for
-different variants are separated by blank lines.  Blank lines are
-illegal within an entry.  It is conventional to begin a map file with
-an entry for the combined entity as a whole (although this
-is not required, and if present will be ignored). An example
-map file is shown below. This file would be named foo.html,
-as it describes a resource named foo.
-
-
+
+    in the server configuration file. 
+
+    Type map files should have the same name as the resource
+    which they are describing, and have an entry for each available
+    variant; these entries consist of contiguous HTTP-format header
+    lines. Entries for different variants are separated by blank
+    lines. Blank lines are illegal within an entry. It is
+    conventional to begin a map file with an entry for the combined
+    entity as a whole (although this is not required, and if
+    present will be ignored). An example map file is shown below.
+    This file would be named foo.html, as it describes
+    a resource named foo.
+   URI: foo
 
   URI: foo.en.html
@@ -136,16 +131,13 @@ as it describes a resource named foo.
   URI: foo.fr.de.html
   Content-type: text/html;charset=iso-8859-2
   Content-language: fr, de
-
-
-Note also that a typemap file will take precedence over the filename's
-extension, even when Multiviews is on.
-
-If the variants have different source qualities, that may be indicated
-by the "qs" parameter to the media type, as in this picture (available
-as jpeg, gif, or ASCII-art):
-
-+
+    Note also that a typemap file will take precedence over the
+    filename's extension, even when Multiviews is on. If the
+    variants have different source qualities, that may be indicated
+    by the "qs" parameter to the media type, as in this picture
+    (available as jpeg, gif, or ASCII-art): 
+   URI: foo
 
   URI: foo.jpeg
@@ -156,445 +148,504 @@ as jpeg, gif, or ASCII-art):
 
   URI: foo.txt
   Content-type: text/plain; qs=0.01
-
-
-
-qs values can vary in the range 0.000 to 1.000. Note that any variant with
-a qs value of 0.000 will never be chosen. Variants with no 'qs'
-parameter value are given a qs factor of 1.0. The qs parameter indicates
-the relative 'quality' of this variant compared to the other available
-variants, independent of the client's capabilities.  For example, a jpeg
-file is usually of higher source quality than an ascii file if it is
-attempting to represent a photograph.  However, if the resource being
-represented is an original ascii art, then an ascii representation would
-have a higher source quality than a jpeg representation.  A qs value
-is therefore specific to a given variant depending on the nature of
-the resource it represents.
-
-

-The full list of headers recognized is:
-
-

-   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
-       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 tag from RFC 1766 (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.
-       Apache only recognizes encodings that are defined by an
-       AddEncoding directive.
-       This normally includes the encodings x-compress
-       for compress'd files, and x-gzip for gzip'd files.
-       The x- prefix is ignored for encoding comparisons.
-  
 Content-Length:
-  
 The size of the file in bytes.  Specifying content
-       lengths in the type-map allows the server to compare file sizes
-       without checking the actual files.
-  
 Description:
-  
 A human-readable textual description of the variant.  If Apache cannot
-       find any appropriate variant to return, it will return an error 
-       response which lists all available variants instead.  Such a variant
-       list will include the human-readable variant descriptions.
-
-
-Using a type map file is preferred over MultiViews because
-it requires less CPU time, and less file access, to parse a file
-explicitly listing the various resource variants, than to have to look
-at every matching file, and parse its file extensions.
-
-Multiviews
-
-
-MultiViews 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
-have to ask for it by name.
-
-

-The effect of MultiViews is as follows: if the server
-receives a request for /some/dir/foo, if
-/some/dir has MultiViews enabled, and
-/some/dir/foo does not exist, then the server reads the
-directory looking for files named foo.*, and effectively fakes up a
-type map which names all those files, assigning them the same media
-types and content-encodings it would have if the client had asked for
-one of them by name.  It then chooses the best match to the client's
-requirements.
-
-

-MultiViews may also apply to searches for the file named by the
-DirectoryIndex directive, if the server is trying to
-index a directory. If the configuration files specify
-
-
+
+
+    qs values can vary in the range 0.000 to 1.000. Note that
+    any variant with a qs value of 0.000 will never be chosen.
+    Variants with no 'qs' parameter value are given a qs factor of
+    1.0. The qs parameter indicates the relative 'quality' of this
+    variant compared to the other available variants, independent
+    of the client's capabilities. For example, a jpeg file is
+    usually of higher source quality than an ascii file if it is
+    attempting to represent a photograph. However, if the resource
+    being represented is an original ascii art, then an ascii
+    representation would have a higher source quality than a jpeg
+    representation. A qs value is therefore specific to a given
+    variant depending on the nature of the resource it
+    represents.
+
+    The full list of headers recognized is:
+
+    
+      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 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 tag from RFC 1766 (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. Apache only recognizes encodings that are defined by an
+      AddEncoding
+      directive. This normally includes the encodings
+      x-compress for compress'd files, and
+      x-gzip for gzip'd files. The x-
+      prefix is ignored for encoding comparisons.
+
+      Content-Length:
+
+      The size of the file in bytes. Specifying content lengths
+      in the type-map allows the server to compare file sizes
+      without checking the actual files.
+
+      Description:
+
+      A human-readable textual description of the variant. If
+      Apache cannot find any appropriate variant to return, it will
+      return an error response which lists all available variants
+      instead. Such a variant list will include the human-readable
+      variant descriptions.
+    
+    Using a type map file is preferred over MultiViews
+    because it requires less CPU time, and less file access, to
+    parse a file explicitly listing the various resource variants,
+    than to have to look at every matching file, and parse its file
+    extensions. 
+
+    Multiviews
+
+    MultiViews 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 have to ask for it by name.
+
+    The effect of MultiViews is as follows: if the
+    server receives a request for /some/dir/foo, if
+    /some/dir has MultiViews enabled, and
+    /some/dir/foo does not exist, then the
+    server reads the directory looking for files named foo.*, and
+    effectively fakes up a type map which names all those files,
+    assigning them the same media types and content-encodings it
+    would have if the client had asked for one of them by name. It
+    then chooses the best match to the client's requirements.
+
+    MultiViews may also apply to searches for the
+    file named by the DirectoryIndex directive, if the
+    server is trying to index a directory. If the configuration
+    files specify
+   DirectoryIndex index
-
-
-then the server will arbitrate between index.html
-and index.html3 if both are present.  If neither are
-present, and index.cgi is there, the server will run it.
-
-
-If one of the files found when reading the directive is a CGI script,
-it's not obvious what should happen.  The code gives that case
-special treatment --- if the request was a POST, or a GET with
-QUERY_ARGS or PATH_INFO, the script is given an extremely high quality
-rating, and generally invoked; otherwise it is given an extremely low
-quality rating, which generally causes one of the other views (if any)
-to be retrieved.
-
-
The Negotiation Methods
-
-After Apache has obtained a list of the variants for a given resource,
-either from a type-map file or from the filenames in the directory, it
-invokes one of two methods to decide on the 'best' variant to
-return, if any.  It is not necessary to know any of the details of how
-negotiation actually takes place in order to use Apache's content
-negotiation features. However the rest of this document explains the
-methods used for those interested.
-
-
-There are two negotiation methods:
-
-
 
-
-Server driven negotiation with the Apache
-algorithm is used in the normal case.  The Apache algorithm is
-explained in more detail below.  When this algorithm is used, Apache
-can sometimes 'fiddle' the quality factor of a particular dimension to
-achieve a better result. The ways Apache can fiddle quality factors is
-explained in more detail below.
-
-
Transparent content negotiation is used when the
-browser specifically requests this through the mechanism defined in RFC
-2295.  This negotiation method gives the browser full control over
-deciding on the 'best' variant, the result is therefore dependent on
-the specific algorithms used by the browser.  As part of the
-transparent negotiation process, the browser can ask Apache to run the
-'remote variant selection algorithm' defined in RFC 2296.
-
-
-
-
-Dimensions of Negotiation
-
-
-
-
-
-
-
-Dimension
- Notes
-
Media Type
- Browser indicates preferences with the Accept header field. Each item
-can have an associated quality factor. Variant description can also
-have a quality factor (the "qs" parameter).
-
Language
- Browser indicates preferences with the Accept-Language header field.
-Each item can have a quality factor. Variants can be associated with none, one
-or more than one language.
-
Encoding
- Browser indicates preference with the Accept-Encoding header field.
-Each item can have a quality factor.
-
Charset
- Browser indicates preference with the Accept-Charset header field.
-Each item can have a quality factor.
-Variants can indicate a charset as a parameter of the media type.
-
-
-Apache Negotiation Algorithm
-
-
-Apache can use the following algorithm to select the 'best' variant
-(if any) to return to the browser.  This algorithm is not
-further configurable. It operates as follows:
-
-

-First, for each dimension of the negotiation, check the appropriate
-Accept* header field and assign a quality to each
-variant. If the Accept* header for any dimension implies that this
-variant is not acceptable, eliminate it. If no variants remain, go
-to step 4.
-
-
Select the 'best' variant by a process of elimination. Each of the
-following tests is applied in order. Any variants not selected at each
-test are eliminated. After each test, if only one variant remains,
-select it as the best match and proceed to step 3. If more than one
-variant remains, move on to the next test.
-
-
-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.
-
-
Select the variants with the highest language quality factor.
-
-
Select the variants with the best language match, using either the
-  order of languages in the Accept-Language header (if present), or else 
-  the order of languages in the LanguagePriority 
-  directive (if present).
-
-
Select the variants with the highest 'level' media parameter
-  (used to give the version of text/html media types).
-
-
Select variants with the best charset media parameters,
-  as given on the Accept-Charset header line. Charset ISO-8859-1
-  is acceptable unless explicitly excluded. Variants with a
-  text/* media type but not explicitly associated
-  with a particular charset are assumed to be in ISO-8859-1.
-
-
Select those variants which have associated
-    charset media parameters that are not ISO-8859-1.
-    If there are no such variants, select all variants instead.
-
-
Select the variants with the best encoding. If there are
-  variants with an encoding that is acceptable to the user-agent,
-  select only these variants. Otherwise if there is a mix of encoded
-  and non-encoded variants, select only the unencoded variants.
-  If either all variants are encoded or all variants are not encoded, 
-  select all variants.
-
-
Select the variants with the smallest content length.
-
-
Select the first variant of those remaining. This will be either the
-  first listed in the type-map file, or when variants are read from
-  the directory, the one whose file name comes first when sorted using
-  ASCII code order.
-
-
-
-
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.
-
-
To get here means no variant was selected (because none 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
-
- 
-Apache sometimes changes the quality values from what would be
-expected by a strict interpretation of the Apache negotiation
-algorithm above. This is to get a better result from the algorithm for
-browsers which do not send full or accurate information. Some of the
-most popular browsers send Accept header information which would
-otherwise result in the selection of the wrong variant in many
-cases. If a browser sends full and correct information these fiddles
-will not be applied.
-

-
-
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:
-
+
+    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 special treatment --- if the request was a POST, or a
+    GET with QUERY_ARGS or PATH_INFO, the script is given an
+    extremely high quality rating, and generally invoked; otherwise
+    it is given an extremely low quality rating, which generally
+    causes one of the other views (if any) to be retrieved.
+
+    The Negotiation Methods
+    After Apache has obtained a list of the variants for a given
+    resource, either from a type-map file or from the filenames in
+    the directory, it invokes one of two methods to decide on the
+    'best' variant to return, if any. It is not necessary to know
+    any of the details of how negotiation actually takes place in
+    order to use Apache's content negotiation features. However the
+    rest of this document explains the methods used for those
+    interested. 
+
+    There are two negotiation methods:
+
+    
+      Server driven negotiation with the Apache
+      algorithm is used in the normal case. The Apache
+      algorithm is explained in more detail below. When this
+      algorithm is used, Apache can sometimes 'fiddle' the quality
+      factor of a particular dimension to achieve a better result.
+      The ways Apache can fiddle quality factors is explained in
+      more detail below.
+
+      Transparent content negotiation is used
+      when the browser specifically requests this through the
+      mechanism defined in RFC 2295. This negotiation method gives
+      the browser full control over deciding on the 'best' variant,
+      the result is therefore dependent on the specific algorithms
+      used by the browser. As part of the transparent negotiation
+      process, the browser can ask Apache to run the 'remote
+      variant selection algorithm' defined in RFC 2296.
+    
+
+    Dimensions of Negotiation
+
+    
+      
+        
+
+        
+      
+
+      
+        
+
+        
+      
+
+      
+        
+
+        
+      
+
+      
+        
+
+        
+      
+
+      
+        
+
+        
+      
+    Dimension Notes
Media Type Browser indicates preferences with the Accept header
+        field. Each item can have an associated quality factor.
+        Variant description can also have a quality factor (the
+        "qs" parameter).
Language Browser indicates preferences with the Accept-Language
+        header field. Each item can have a quality factor. Variants
+        can be associated with none, one or more than one
+        language.
Encoding Browser indicates preference with the Accept-Encoding
+        header field. Each item can have a quality factor.
Charset Browser indicates preference with the Accept-Charset
+        header field. Each item can have a quality factor. Variants
+        can indicate a charset as a parameter of the media
+        type.
+
+    Apache Negotiation Algorithm
+
+    Apache can use the following algorithm to select the 'best'
+    variant (if any) to return to the browser. This algorithm is
+    not further configurable. It operates as follows:
+
+    
+      First, for each dimension of the negotiation, check the
+      appropriate Accept* header field and assign a
+      quality to each variant. If the Accept* header for
+      any dimension implies that this variant is not acceptable,
+      eliminate it. If no variants remain, go to step 4.
+
+      
+        Select the 'best' variant by a process of elimination. Each
+        of the following tests is applied in order. Any variants
+        not selected at each test are eliminated. After each test,
+        if only one variant remains, select it as the best match
+        and proceed to step 3. If more than one variant remains,
+        move on to the next test. 
+
+        
+          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.
+
+          Select the variants with the highest language quality
+          factor.
+
+          Select the variants with the best language match,
+          using either the order of languages in the
+          Accept-Language header (if present), or else the order of
+          languages in the LanguagePriority directive
+          (if present).
+
+          Select the variants with the highest 'level' media
+          parameter (used to give the version of text/html media
+          types).
+
+          Select variants with the best charset media
+          parameters, as given on the Accept-Charset header line.
+          Charset ISO-8859-1 is acceptable unless explicitly
+          excluded. Variants with a text/* media type
+          but not explicitly associated with a particular charset
+          are assumed to be in ISO-8859-1.
+
+          Select those variants which have associated charset
+          media parameters that are not ISO-8859-1. If
+          there are no such variants, select all variants
+          instead.
+
+          Select the variants with the best encoding. If there
+          are variants with an encoding that is acceptable to the
+          user-agent, select only these variants. Otherwise if
+          there is a mix of encoded and non-encoded variants,
+          select only the unencoded variants. If either all
+          variants are encoded or all variants are not encoded,
+          select all variants.
+
+          Select the variants with the smallest content
+          length.
+
+          Select the first variant of those remaining. This
+          will be either the first listed in the type-map file, or
+          when variants are read from the directory, the one whose
+          file name comes first when sorted using ASCII code
+          order.
+        
+      
+
+      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.
+
+      To get here means no variant was selected (because none
+      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
+
+    Apache sometimes changes the quality values from what would
+    be expected by a strict interpretation of the Apache
+    negotiation algorithm above. This is to get a better result
+    from the algorithm for browsers which do not send full or
+    accurate information. Some of the most popular browsers send
+    Accept header information which would otherwise result in the
+    selection of the wrong variant in many cases. If a browser
+    sends full and correct information these fiddles will not be
+    applied.
+
+    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:
-+
+    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
-available, that is ok too. However under the basic algorithm, as given
-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:
-+
+    The intention of this is to indicate that the explicitly listed
+    types are preferred, but if a different representation is
+    available, that is ok too. However under the basic algorithm,
+    as given 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
-the q value of "*/*", if present, to 0.01 to emulate the desired
-behavior. It also sets the q value of wildcards of the format
-"type/*" to 0.02 (so these are preferred over matches against
-"*/*". If any media type on the Accept: header contains a q factor,
-these special values are not applied, so requests from browsers
-which send the 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.

-
-The reason for setting this language quality factor for
-variant with no language to a very low value is to allow
-for a default variant which can be supplied if none of the
-other variants match the browser's language preferences.
-
-For example, consider the situation with three variants:
-
-

-foo.en.html, language en
-
foo.fr.html, language en
-
foo.html, no language
-
-
-
-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
-or foo.fr.html will be returned. If the browser does not list
-either en or fr as acceptable, foo.html will be returned instead.
-
-
Extensions to Transparent Content Negotiation
-
-Apache extends the transparent content negotiation protocol (RFC 2295)
-as follows.  A new  {encoding ..} element is used in
-variant lists to label variants which are available with a specific
-content-encoding only. The implementation of the
-RVSA/1.0 algorithm (RFC 2296) is extended to recognize encoded
-variants in the list, and to use them as candidate variants whenever
-their encodings are acceptable according to the Accept-Encoding
-request header.  The RVSA/1.0 implementation does not round computed
-quality factors to 5 decimal places before choosing the best variant.
-
-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 the mod_mime
-documentation for details).
-

-A typical file has a MIME-type extension (e.g., html),
-maybe an encoding extension (e.g., gz), and of course a
-language extension (e.g., en) when we have different
-language variants of this file.
-
-

-Examples:
-

-foo.en.html
-
foo.html.en
-
foo.en.html.gz
-
-
-
-Here some more examples of filenames together with valid and invalid
-hyperlinks:
-
-
-
-
- 
- 
- 
-
-
- 
- 
- 
-
-
- 
- 
- 
-
-
- 
- 
- 
-
-
- 
- 
- 
-
-
- 
- 
- 
-
-
- 
- 
- 
-
-Filename Valid hyperlink Invalid hyperlink
foo.html.en foo

-     foo.html -
foo.en.html foo foo.html
foo.html.en.gz foo

-     foo.html foo.gz

-     foo.html.gz
foo.en.html.gz foo foo.html

-     foo.html.gz

-     foo.gz
foo.gz.html.en foo

-     foo.gz

-     foo.gz.html foo.html
foo.html.gz.en foo

-     foo.html

-     foo.html.gz foo.gz
-
-
-Looking at the table above you will notice that it is always possible to
-use the name without any extensions  in 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
-hyperlink references.
-
-

-If you want to continue to use a MIME-type in your hyperlinks (e.g.
-foo.html) the language extension (including an encoding extension
-if there is one) must be on the right hand side of the MIME-type extension
-(e.g., foo.html.en).
-
-
-
Note on Caching
-
-
-When a cache stores a representation, it associates it with the request URL.
-The next time that URL is requested, the cache can use the stored
-representation. But, if the resource is negotiable at the server,
-this might result in only the first requested variant being cached and
-subsequent cache hits might return the wrong response. To prevent this,
-Apache normally marks all responses that are returned after content negotiation
-as non-cacheable by HTTP/1.0 clients. Apache also supports the HTTP/1.1
-protocol features to allow caching of negotiated responses. 

-
-For requests which come from a HTTP/1.0 compliant client (either a
-browser or a cache), the directive CacheNegotiatedDocs can be
-used to allow caching of responses which were subject to negotiation.
-This directive can be given in the server config or virtual host, and
-takes no arguments. It has no effect on requests from HTTP/1.1 clients.
-
-
-
-
+

Dimension -	Notes -
Media Type -	Browser indicates preferences with the Accept header field. Each item -can have an associated quality factor. Variant description can also -have a quality factor (the "qs" parameter). -
Language -	Browser indicates preferences with the Accept-Language header field. -Each item can have a quality factor. Variants can be associated with none, one -or more than one language. -
Encoding -	Browser indicates preference with the Accept-Encoding header field. -Each item can have a quality factor. -
Charset -	Browser indicates preference with the Accept-Charset header field. -Each item can have a quality factor. -Variants can indicate a charset as a parameter of the media type. -

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

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

+ +

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.

+ +

foo.en.html, language en
foo.fr.html, language en
foo.html, no language

+ +

Extensions to Transparent Content Negotiation

Note on hyperlinks and naming conventions

+ +

Examples:

+ +

foo.en.html
foo.html.en
foo.en.html.gz

+ +

Here some more examples of filenames together with valid and + invalid hyperlinks:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Filename	Valid hyperlink	Invalid hyperlink
foo.html.en	foo + foo.html	-
foo.en.html	foo	foo.html
foo.html.en.gz	foo + foo.html	foo.gz + foo.html.gz
foo.en.html.gz	foo	foo.html + foo.html.gz + foo.gz
foo.gz.html.en	foo + foo.gz + foo.gz.html	foo.html
foo.html.gz.en	foo + foo.html + foo.html.gz	foo.gz

+ +

Note on Caching

+ +

+ + + diff --git a/docs/manual/custom-error.html b/docs/manual/custom-error.html index 09604ea972b..3cbb5704364 100644 --- a/docs/manual/custom-error.html +++ b/docs/manual/custom-error.html @@ -1,177 +1,182 @@ - - - -Custom error responses - - - - - -

Custom error responses

- -

Purpose - -

Additional functionality. Allows webmasters to configure the response of - Apache to some error or problem. - -

Customizable responses can be defined to be activated in the - event of a server detected error or problem. + + + + + + + Custom error responses + + + + + + +

Custom error responses

+ +

Purpose

+ Additional functionality. Allows webmasters to configure + the response of Apache to some error or problem. + +

Customizable responses can be defined to be activated in + the event of a server detected error or problem.

+ +

e.g. if a script crashes and produces a "500 Server + Error" response, then this response can be replaced with + either some friendlier text or by a redirection to another + URL (local or external).

Old behavior

NCSA httpd 1.3 would return some boring old error/problem + message which would often be meaningless to the user, and + would provide no means of logging the symptoms which caused + it.
+

New behavior

e.g. if a script crashes and produces a "500 Server Error" - response, then this response can be replaced with either some - friendlier text or by a redirection to another URL (local or - external). -

+ The server can be asked to; -

Old behavior +
+
Display some other text, instead of the NCSA hard + coded messages, or
-
NCSA httpd 1.3 would return some boring old error/problem message - which would often be meaningless to the user, and would provide no - means of logging the symptoms which caused it.
- -
- -
New behavior - -
The server can be asked to; -
-
Display some other text, instead of the NCSA hard coded messages, or -
redirect to a local URL, or -
redirect to an external URL. -
- -
Redirecting to another URL can be useful, but only if some information - can be passed which can then be used to explain and/or log the - error/problem - more clearly. - -
To achieve this, Apache will define new CGI-like environment - variables, 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 - 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 - scheme name - like http:, even if it refers to the same host as the - server).
- -
Configuration - -
Use of "ErrorDocument" is enabled for .htaccess files when the - "FileInfo" override is - allowed. - -
Here are some examples... - -
-ErrorDocument 500 /cgi-bin/crash-recover -ErrorDocument 500 "Sorry, our script crashed. Oh dear -ErrorDocument 500 http://xxx/ -ErrorDocument 404 /Lame_excuses/not_found.html -ErrorDocument 401 /Subscription/how_to_subscribe.html -
- -
The syntax is, - -
ErrorDocument -<3-digit-code> action - -
where the action can be, - -
-
Text to be displayed. Prefix the text with a quote ("). Whatever - follows the quote is displayed. Note: the (") prefix isn't - displayed. - -
An external URL to redirect to. - -
A local URL to redirect to. - -
-

- -

Custom error responses and redirects

- -

Purpose - -: Apache's behavior to redirected URLs has been modified so that additional - 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 -variables are created from the CGI environment variables which existed -prior to the redirect, they are renamed with a REDIRECT_ -prefix, i.e., HTTP_USER_AGENT becomes -REDIRECT_HTTP_USER_AGENT. In addition to these new -variables, Apache will define REDIRECT_URL and -REDIRECT_STATUS to help the script trace its origin. -Both the original URL and the URL being redirected to can be logged in -the access log. - -

-If the ErrorDocument specifies a local redirect to a CGI script, the script -should include a "Status:" header field in its output -in order to ensure the propagation all the way back to the client -of the error condition that caused it to be invoked. For instance, a Perl -ErrorDocument script might include the following: -

redirect to a local URL, or

+ +

redirect to an external URL.

+ + +

Redirecting to another URL can be useful, but only if + some information can be passed which can then be used to + explain and/or log the error/problem more clearly.

+ +

To achieve this, Apache will define new CGI-like + environment variables, 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 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 scheme name like + http:, even if it refers to the same host as + the server).

Configuration

+ Use of "ErrorDocument" is enabled for .htaccess files when + the "FileInfo" + override is allowed. + +

Here are some examples...

+ +

+ ErrorDocument 500 /cgi-bin/crash-recover + ErrorDocument 500 "Sorry, our script crashed. Oh + dear + ErrorDocument 500 http://xxx/ + ErrorDocument 404 /Lame_excuses/not_found.html + ErrorDocument 401 + /Subscription/how_to_subscribe.html +

+ +

The syntax is,

+ +

ErrorDocument + <3-digit-code> action

+ +

where the action can be,

+ +

Text to be displayed. Prefix the text with a quote + ("). Whatever follows the quote is displayed. Note: + the (") prefix isn't displayed.
An external URL to redirect to.
A local URL to redirect to.

+ +

Custom error responses and redirects

+ +

Purpose: Apache's behavior to redirected URLs has been modified so + that additional 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 variables are created from + the CGI environment variables which existed prior to the + redirect, they are renamed with a REDIRECT_ + prefix, i.e., HTTP_USER_AGENT becomes + REDIRECT_HTTP_USER_AGENT. In addition to these + new variables, Apache will define REDIRECT_URL + and REDIRECT_STATUS to help the script trace its + origin. Both the original URL and the URL being redirected to + can be logged in the access log.

+ +

If the ErrorDocument specifies a local redirect to a CGI + script, the script should include a "Status:" + header field in its output in order to ensure the propagation + all the way back to the client of the error condition that + caused it to be invoked. For instance, a Perl ErrorDocument + script might include the following:

       :
     print  "Content-type: text/html\n";
     printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"};
       :
-

-If the script is dedicated to handling a particular error condition, such as -404 Not Found, it can use the specific code and -error text instead. -

- - - - + + +

If the script is dedicated to handling a particular error + condition, such as 404 Not Found, it can + use the specific code and error text instead.

+ + + + diff --git a/docs/manual/custom-error.html.en b/docs/manual/custom-error.html.en index 09604ea972b..3cbb5704364 100644 --- a/docs/manual/custom-error.html.en +++ b/docs/manual/custom-error.html.en @@ -1,177 +1,182 @@ - - - -Custom error responses - - - - - -

Custom error responses

- -

Purpose - -

Additional functionality. Allows webmasters to configure the response of - Apache to some error or problem. - -

Customizable responses can be defined to be activated in the - event of a server detected error or problem. + + + + + + + Custom error responses + + + + + + +

Custom error responses

+ +

Purpose

+ Additional functionality. Allows webmasters to configure + the response of Apache to some error or problem. + +

Customizable responses can be defined to be activated in + the event of a server detected error or problem.

+ +

e.g. if a script crashes and produces a "500 Server + Error" response, then this response can be replaced with + either some friendlier text or by a redirection to another + URL (local or external).

Old behavior

NCSA httpd 1.3 would return some boring old error/problem + message which would often be meaningless to the user, and + would provide no means of logging the symptoms which caused + it.
+

New behavior

+ The server can be asked to; -

- -

Custom error responses and redirects

- -

Purpose - -: Apache's behavior to redirected URLs has been modified so that additional - 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 -variables are created from the CGI environment variables which existed -prior to the redirect, they are renamed with a REDIRECT_ -prefix, i.e., HTTP_USER_AGENT becomes -REDIRECT_HTTP_USER_AGENT. In addition to these new -variables, Apache will define REDIRECT_URL and -REDIRECT_STATUS to help the script trace its origin. -Both the original URL and the URL being redirected to can be logged in -the access log. - -

redirect to a local URL, or

+ +

redirect to an external URL.

+ + +

Redirecting to another URL can be useful, but only if + some information can be passed which can then be used to + explain and/or log the error/problem more clearly.

+ +

To achieve this, Apache will define new CGI-like + environment variables, 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.

+ +

Configuration

+ Use of "ErrorDocument" is enabled for .htaccess files when + the "FileInfo" + override is allowed. + +

Here are some examples...

+ +

+ ErrorDocument 500 /cgi-bin/crash-recover + ErrorDocument 500 "Sorry, our script crashed. Oh + dear + ErrorDocument 500 http://xxx/ + ErrorDocument 404 /Lame_excuses/not_found.html + ErrorDocument 401 + /Subscription/how_to_subscribe.html +

+ +

The syntax is,

+ +

ErrorDocument + <3-digit-code> action

+ +

where the action can be,

+ +

Text to be displayed. Prefix the text with a quote + ("). Whatever follows the quote is displayed. Note: + the (") prefix isn't displayed.
An external URL to redirect to.
A local URL to redirect to.

+ +

Custom error responses and redirects

+ +

Purpose: Apache's behavior to redirected URLs has been modified so + that additional 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 variables are created from + the CGI environment variables which existed prior to the + redirect, they are renamed with a REDIRECT_ + prefix, i.e., HTTP_USER_AGENT becomes + REDIRECT_HTTP_USER_AGENT. In addition to these + new variables, Apache will define REDIRECT_URL + and REDIRECT_STATUS to help the script trace its + origin. Both the original URL and the URL being redirected to + can be logged in the access log.

+ +

       :
     print  "Content-type: text/html\n";
     printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"};
       :
-

-If the script is dedicated to handling a particular error condition, such as -404 Not Found, it can use the specific code and -error text instead. -

- - - - + + +

If the script is dedicated to handling a particular error + condition, such as 404 Not Found, it can + use the specific code and error text instead.

+ + + + diff --git a/docs/manual/dns-caveats.html b/docs/manual/dns-caveats.html index a20127abfec..a68c8c5a7e3 100644 --- a/docs/manual/dns-caveats.html +++ b/docs/manual/dns-caveats.html @@ -1,188 +1,217 @@ - - -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. -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 -from other users). - -

A Simple Example

- -Consider this configuration snippet: - -

+ + + + + + + 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. 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 from other users).

+ +

A Simple Example

+ 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 -to have two pieces of information about each virtual host: the -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 -some reason DNS is not available at the time your server is parsing its -config file, then this virtual host will not be configured. It -won't be able to respond to any hits to this virtual host (prior to -Apache version 1.2 the server would not even boot). - -

Suppose that www.abc.dom has address 10.0.0.1. Then -consider this configuration snippet: - -

+
+

+ +

In order for Apache to function properly it absolutely needs + to have two pieces of information about each virtual host: the + ServerName + and at least one IP address that the server 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 some + reason DNS is not available at the time your server is parsing + its config file, then this virtual host will not be + configured. It won't be able to respond to any hits to + this virtual host (prior to Apache version 1.2 the server would + not even boot).

+ +

Suppose that www.abc.dom has address 10.0.0.1. + Then consider this configuration snippet:

+ +

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

- -

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

+
+

+ +

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 be + totally disabled, but if it is IP-based then it will mostly + work. However if Apache should ever have to generate a full URL + for the server which includes the server name then it will fail + to generate a valid URL.

+ +

Here is a snippet that avoids both of these problems.

+ +

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

- -

Denial of Service

- -

There are (at least) two forms that denial of service can come in. -If you are running a version of Apache prior to version 1.2 then your -server will not even boot if one of the two DNS lookups mentioned above -fails for any of your virtual hosts. In some cases this DNS lookup may -not even be under your control. For example, if abc.dom -is one of your customers and they control their own DNS then they -can force your (pre-1.2) server to fail while booting simply by deleting the -www.abc.dom record. - -

Another form is far more insidious. Consider this configuration -snippet: - -

+
+

+ +

Denial of Service

+ +

There are (at least) two forms that denial of service can + come in. If you are running a version of Apache prior to + version 1.2 then your server will not even boot if one of the + two DNS lookups mentioned above fails for any of your virtual + hosts. In some cases this DNS lookup may not even be under your + control. For example, if abc.dom is one of your + customers and they control their own DNS then they can force + your (pre-1.2) server to fail while booting simply by deleting + the www.abc.dom record.

+ +

Another form is far more insidious. Consider this + configuration snippet:

+ +

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

     <VirtualHost www.def.dom>
     ServerAdmin webguy@def.dom
     DocumentRoot /www/def
     </VirtualHost>
-

- -

Suppose that you've assigned 10.0.0.1 to www.abc.dom and -10.0.0.2 to www.def.dom. Furthermore, suppose that -def.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. - -

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

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 host that httpd is running on. To get this address it uses either -the global ServerName (if present) or calls the C function -gethostname (which should return the same as typing -"hostname" at the command prompt). Then it performs a DNS lookup on -this address. At present there is no way to avoid this lookup. - -

If you fear that this lookup might fail because your DNS server is down -then you can insert the hostname in /etc/hosts (where you -probably already have it so that the machine can boot properly). Then -ensure that your machine is configured to use /etc/hosts -in the event that DNS fails. Depending on what OS you are using this -might be accomplished by editing /etc/resolv.conf, or maybe -/etc/nsswitch.conf. - -

If your server doesn't have to perform DNS for any other reason -then you might be able to get away with running Apache with the -HOSTRESORDER environment variable set to "local". This all -depends on what OS and resolver libraries you are using. It also affects -CGIs unless you use mod_env -to control the environment. It's best to consult the man pages or FAQs -for your OS. - -

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 - has no pages to serve -

- -

Appendix: Future Directions

- -

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

A possible work around to the theft of service attack described above -would be to perform a reverse DNS lookup on the ip address returned by -the forward lookup and compare the two names. In the event of a mismatch -the virtualhost would be disabled. This would require reverse DNS to be -configured properly (which is something that most admins are familiar with -because of the common use of "double-reverse" DNS lookups by FTP servers -and TCP wrappers). - -

In any event it doesn't seem possible to reliably boot a virtual-hosted -web server when DNS has failed unless IP addresses are used. Partial -solutions such as disabling portions of the configuration might be worse -than not booting at all depending on what the webserver is supposed -to accomplish. - -

As HTTP/1.1 is deployed and browsers and proxies start issuing the -Host header it will become possible to avoid the use of -IP-based virtual hosts entirely. In this 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 -critical webservers. - - - - +

+ +

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.

+ +

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.

+ +

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 host that httpd is running on. To get + this address it uses either the global ServerName + (if present) or calls the C function gethostname + (which should return the same as typing "hostname" at the + command prompt). Then it performs a DNS lookup on this address. + At present there is no way to avoid this lookup.

+ +

If you fear that this lookup might fail because your DNS + server is down then you can insert the hostname in + /etc/hosts (where you probably already have it so + that the machine can boot properly). Then ensure that your + machine is configured to use /etc/hosts in the + event that DNS fails. Depending on what OS you are using this + might be accomplished by editing /etc/resolv.conf, + or maybe /etc/nsswitch.conf.

+ +

If your server doesn't have to perform DNS for any other + reason then you might be able to get away with running Apache + with the HOSTRESORDER environment variable set to + "local". This all depends on what OS and resolver libraries you + are using. It also affects CGIs unless you use mod_env to control the + environment. It's best to consult the man pages or FAQs for + your OS.

+ +

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 has no pages to serve

+ +

Appendix: Future Directions

+ +

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.

+ +

A possible work around to the theft of service attack + described above would be to perform a reverse DNS lookup on the + ip address returned by the forward lookup and compare the two + names. In the event of a mismatch the virtualhost would be + disabled. This would require reverse DNS to be configured + properly (which is something that most admins are familiar with + because of the common use of "double-reverse" DNS lookups by + FTP servers and TCP wrappers).

+ +

In any event it doesn't seem possible to reliably boot a + virtual-hosted web server when DNS has failed unless IP + addresses are used. Partial solutions such as disabling + portions of the configuration might be worse than not booting + at all depending on what the webserver is supposed to + accomplish.

+ +

As HTTP/1.1 is deployed and browsers and proxies start + issuing the Host header it will become possible to + avoid the use of IP-based virtual hosts entirely. In this 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 critical + webservers. +

+ + diff --git a/docs/manual/dso.html b/docs/manual/dso.html index 2ed4fbbaeae..38d28ba2a81 100644 --- a/docs/manual/dso.html +++ b/docs/manual/dso.html @@ -1,280 +1,344 @@ - - -Dynamic Shared Object (DSO) support - - - - - - -

-Dynamic Shared Object (DSO) Support -

- -

The Apache HTTP Server is a modular program where the administrator -can choose the functionality to include in the server by selecting a -set of modules. The modules can be statically compiled into the -httpd binary when the server is built. Alternatively, -modules can be compiled as Dynamic Shared Objects (DSOs) that exist -separately from the main httpd binary file. DSO modules -may be compiled at the time the server is built, or they may be -compiled and added at a later time using the Apache Extension Tool (apxs).

- -

This document describes how to use DSO modules as well as the theory -behind their use.

- -

Implementation
Usage Summary
Background
Advantages and Disadvantages

- -

- - -

-Related Modules

- -mod_so
- -

-Related Directives

- -LoadModule
- -

- -

Implementation

- -

The DSO support for loading individual Apache modules is based on a -module named mod_so.c which -must be statically compiled into the Apache core. It is the only -module besides core.c which cannot be put into a DSO -itself. Practically all other distributed Apache modules then can -then be placed into a DSO by individually enabling the DSO build for -them via configure's ---enable-module=shared option as disucussed in the -install documentation. After a module is -compiled into a DSO named mod_foo.so you can use mod_so's LoadModule command -in your httpd.conf file to load this module at server -startup or restart. - -

To simplify this creation of DSO files for Apache modules -(especially for third-party modules) a new support program named apxs (APache eXtenSion) is -available. It can be used to build DSO based modules outside -of the Apache source tree. The idea is simple: When installing -Apache the configure's make install -procedure installs the Apache C header files and puts the -platform-dependent compiler and linker flags for building DSO files -into the apxs program. This way the user can use -apxs to compile his Apache module sources without the -Apache distribution source tree and without having to fiddle with the -platform-dependent compiler and linker flags for DSO support. - -

Usage Summary

- -

To give you an overview of the DSO features of Apache 2.0, here is a short -and concise summary: - -

Build and install a distributed Apache module, say -mod_foo.c, into its own DSO mod_foo.so: - - + +

+ + + + + + + Dynamic Shared Object (DSO) support + + + + + + +

Dynamic Shared Object (DSO) Support

+ +

The Apache HTTP Server is a modular program where the + administrator can choose the functionality to include in the + server by selecting a set of modules. The modules can be + statically compiled into the httpd binary when the + server is built. Alternatively, modules can be compiled as + Dynamic Shared Objects (DSOs) that exist separately from the + main httpd binary file. DSO modules may be + compiled at the time the server is built, or they may be + compiled and added at a later time using the Apache Extension + Tool (apxs).

+ +

This document describes how to use DSO modules as well as + the theory behind their use.

+ +

Implementation
Usage Summary
Background
Advantages and + Disadvantages

+ + + + + + + +

Related Modules
+
+ mod_so
+

Related Directives
+
+ LoadModule
+

+ +

Implementation

+ +

The DSO support for loading individual Apache modules is + based on a module named mod_so.c which must be + statically compiled into the Apache core. It is the only module + besides core.c which cannot be put into a DSO + itself. Practically all other distributed Apache modules then + can then be placed into a DSO by individually enabling the DSO + build for them via configure's + --enable-module=shared option as disucussed + in the install documentation. After + a module is compiled into a DSO named mod_foo.so + you can use mod_so's + LoadModule + command in your httpd.conf file to load this + module at server startup or restart.

+ +

To simplify this creation of DSO files for Apache modules + (especially for third-party modules) a new support program + named apxs (APache + eXtenSion) is available. It can be used to build DSO based + modules outside of the Apache source tree. The idea is + simple: When installing Apache the configure's + make install procedure installs the Apache C + header files and puts the platform-dependent compiler and + linker flags for building DSO files into the apxs + program. This way the user can use apxs to compile + his Apache module sources without the Apache distribution + source tree and without having to fiddle with the + platform-dependent compiler and linker flags for DSO + support.

+ +

Usage Summary

+ +

To give you an overview of the DSO features of Apache 2.0, + here is a short and concise summary:

+ +

+ Build and install a distributed Apache module, say + mod_foo.c, into its own DSO + mod_foo.so: + + + +
+
$ ./configure --prefix=/path/to/install --enable-foo=shared $ make install -
-
- -
Build and install a third-party Apache module, say -mod_foo.c, into its own DSO mod_foo.so: - - + +
-
+
+
+
+ Build and install a third-party Apache module, say + mod_foo.c, into its own DSO + mod_foo.so: + + + +
+
$ ./configure --add-module=module_type:/path/to/3rdparty/mod_foo.c --enable-foo=shared $ make install -
-
- -
Configure Apache for later installation of shared modules: - + +
-
+
+
+
+ Configure Apache for later installation of shared + modules: + + + +
+
$ ./configure --enable-so $ make install -
-
- -
Build and install a third-party Apache module, say -mod_foo.c, into its own DSO mod_foo.so outside -of the Apache source tree using apxs: - + +
-
+
+
+
+ Build and install a third-party Apache module, say + mod_foo.c, into its own DSO + mod_foo.so outside of the Apache + source tree using apxs: + + + +
+
$ cd /path/to/3rdparty $ apxs -c mod_foo.c $ apxs -i -a -n foo mod_foo.so -
-
- -

- -

In all cases, once the shared module is compiled, you must use a LoadModule directive -in httpd.conf to tell Apache to activate the module. - - - -

Background

- -

On modern Unix derivatives there exists a nifty mechanism usually called -dynamic linking/loading of Dynamic Shared Objects (DSO) which -provides a way to build a piece of program code in a special format for -loading it at run-time into the address space of an executable program. - -

This loading can usually be done in two ways: Automatically by a system -program called ld.so when an executable program is started or -manually from within the executing program via a programmatic system interface -to the Unix loader through the system calls dlopen()/dlsym(). - -

In the first way the DSO's are usually called shared libraries or -DSO libraries and named libfoo.so or -libfoo.so.1.2. They reside in a system directory (usually -/usr/lib) and the link to the executable program is established -at build-time by specifying -lfoo to the linker command. This -hard-codes library references into the executable program file so that at -start-time the Unix loader is able to locate libfoo.so in -/usr/lib, in paths hard-coded via linker-options like --R or in paths configured via the environment variable -LD_LIBRARY_PATH. It then resolves any (yet unresolved) symbols in -the executable program which are available in the DSO. - -

Symbols in the executable program are usually not referenced by the DSO -(because it's a reusable library of general code) and hence no further -resolving has to be done. The executable program has no need to do anything on -its own to use the symbols from the DSO because the complete resolving is done -by the Unix loader. (In fact, the code to invoke ld.so is part of -the run-time startup code which is linked into every executable program which -has been bound non-static). The advantage of dynamic loading of common library -code is obvious: the library code needs to be stored only once, in a system -library like libc.so, saving disk space for every program. - -

In the second way the DSO's are usually called shared objects or -DSO files and can be named with an arbitrary extension (although the -canonical name is foo.so). These files usually stay inside a -program-specific directory and there is no automatically established link to -the executable program where they are used. Instead the executable program -manually loads the DSO at run-time into its address space via -dlopen(). At this time no resolving of symbols from the DSO for -the executable program is done. But instead the Unix loader automatically -resolves any (yet unresolved) symbols in the DSO from the set of symbols -exported by the executable program and its already loaded DSO libraries -(especially all symbols from the ubiquitous libc.so). This way -the DSO gets knowledge of the executable program's symbol set as if it had -been statically linked with it in the first place. - -

Finally, to take advantage of the DSO's API the executable program has to -resolve particular symbols from the DSO via dlsym() for later use -inside dispatch tables etc. In other words: The executable program has to -manually resolve every symbol it needs to be able to use it. The advantage of -such a mechanism is that optional program parts need not be loaded (and thus -do not spend memory) until they are needed by the program in question. When -required, these program parts can be loaded dynamically to extend the base -program's functionality. - -

Although this DSO mechanism sounds straightforward there is at least one -difficult step here: The resolving of symbols from the executable program for -the DSO when using a DSO to extend a program (the second way). Why? Because -"reverse resolving" DSO symbols from the executable program's symbol set is -against the library design (where the library has no knowledge about the -programs it is used by) and is neither available under all platforms nor -standardized. In practice the executable program's global symbols are often -not re-exported and thus not available for use in a DSO. Finding a way to -force the linker to export all global symbols is the main problem one has to -solve when using DSO for extending a program at run-time. - -

The shared library approach is the typical one, because it is what the DSO -mechanism was designed for, hence it is used for nearly all types of libraries -the operating system provides. On the other hand using shared objects for -extending a program is not used by a lot of programs. - -

As of 1998 there are only a few software packages available which use the -DSO mechanism to actually extend their functionality at run-time: Perl 5 (via -its XS mechanism and the DynaLoader module), Netscape Server, etc. Starting -with version 1.3, Apache joined the crew, because Apache already uses a module -concept to extend its functionality and internally uses a dispatch-list-based -approach to link external modules into the Apache core functionality. So, -Apache is really predestined for using DSO to load its modules at run-time. - - -

Advantages and Disadvantages

- -

The above DSO based features have the following advantages: - -

The server package is more flexible at run-time because the actual server - process can be assembled at run-time via LoadModule - httpd.conf configuration commands instead of - configure options at build-time. - For instance this way one is able to run different server instances - (standard & SSL version, minimalistic & powered up version - [mod_perl, PHP3], etc.) with only one Apache installation. -
-
The server package can be easily extended with third-party modules even - after installation. This is at least a great benefit for vendor package - maintainers who can create a Apache core package and additional packages - containing extensions like PHP3, mod_perl, mod_fastcgi, etc. -
-
Easier Apache module prototyping because with the DSO/apxs - pair you can both work outside the Apache source tree and only need an - apxs -i command followed by an apachectl - restart to bring a new version of your currently developed module - into the running Apache server. -

- -

DSO has the following disadvantages: - -

The DSO mechanism cannot be used on every platform because not all - operating systems support dynamic loading of code into the address space - of a program. -
-
The server is approximately 20% slower at startup time because of the - symbol resolving overhead the Unix loader now has to do. -
-
The server is approximately 5% slower at execution time under some - platforms because position independent code (PIC) sometimes needs - complicated assembler tricks for relative addressing which are not - necessarily as fast as absolute addressing. -
-
Because DSO modules cannot be linked against other DSO-based libraries - (ld -lfoo) on all platforms (for instance a.out-based - platforms usually don't provide this functionality while ELF-based - platforms do) you cannot use the DSO mechanism for all types of modules. - Or in other words, modules compiled as DSO files are restricted to only - use symbols from the Apache core, from the C library (libc) - and all other dynamic or static libraries used by the Apache core, or - from static library archives (libfoo.a) containing position - independent code. The only chances to use other code is to either make - sure the Apache core itself already contains a reference to it or loading - the code yourself via dlopen(). -
-

- - - - +

+ +

In all cases, once the shared module is compiled, you must + use a LoadModule + directive in httpd.conf to tell Apache to activate + the module.

+ +

Background

+ +

On modern Unix derivatives there exists a nifty mechanism + usually called dynamic linking/loading of Dynamic Shared + Objects (DSO) which provides a way to build a piece of + program code in a special format for loading it at run-time + into the address space of an executable program.

+ +

This loading can usually be done in two ways: Automatically + by a system program called ld.so when an + executable program is started or manually from within the + executing program via a programmatic system interface to the + Unix loader through the system calls + dlopen()/dlsym().

+ +

In the first way the DSO's are usually called shared + libraries or DSO libraries and named + libfoo.so or libfoo.so.1.2. They + reside in a system directory (usually /usr/lib) + and the link to the executable program is established at + build-time by specifying -lfoo to the linker + command. This hard-codes library references into the executable + program file so that at start-time the Unix loader is able to + locate libfoo.so in /usr/lib, in + paths hard-coded via linker-options like -R or in + paths configured via the environment variable + LD_LIBRARY_PATH. It then resolves any (yet + unresolved) symbols in the executable program which are + available in the DSO.

+ +

Symbols in the executable program are usually not referenced + by the DSO (because it's a reusable library of general code) + and hence no further resolving has to be done. The executable + program has no need to do anything on its own to use the + symbols from the DSO because the complete resolving is done by + the Unix loader. (In fact, the code to invoke + ld.so is part of the run-time startup code which + is linked into every executable program which has been bound + non-static). The advantage of dynamic loading of common library + code is obvious: the library code needs to be stored only once, + in a system library like libc.so, saving disk + space for every program.

+ +

In the second way the DSO's are usually called shared + objects or DSO files and can be named with an + arbitrary extension (although the canonical name is + foo.so). These files usually stay inside a + program-specific directory and there is no automatically + established link to the executable program where they are used. + Instead the executable program manually loads the DSO at + run-time into its address space via dlopen(). At + this time no resolving of symbols from the DSO for the + executable program is done. But instead the Unix loader + automatically resolves any (yet unresolved) symbols in the DSO + from the set of symbols exported by the executable program and + its already loaded DSO libraries (especially all symbols from + the ubiquitous libc.so). This way the DSO gets + knowledge of the executable program's symbol set as if it had + been statically linked with it in the first place.

+ +

Finally, to take advantage of the DSO's API the executable + program has to resolve particular symbols from the DSO via + dlsym() for later use inside dispatch tables + etc. In other words: The executable program has to + manually resolve every symbol it needs to be able to use it. + The advantage of such a mechanism is that optional program + parts need not be loaded (and thus do not spend memory) until + they are needed by the program in question. When required, + these program parts can be loaded dynamically to extend the + base program's functionality.

+ +

Although this DSO mechanism sounds straightforward there is + at least one difficult step here: The resolving of symbols from + the executable program for the DSO when using a DSO to extend a + program (the second way). Why? Because "reverse resolving" DSO + symbols from the executable program's symbol set is against the + library design (where the library has no knowledge about the + programs it is used by) and is neither available under all + platforms nor standardized. In practice the executable + program's global symbols are often not re-exported and thus not + available for use in a DSO. Finding a way to force the linker + to export all global symbols is the main problem one has to + solve when using DSO for extending a program at run-time.

+ +

The shared library approach is the typical one, because it + is what the DSO mechanism was designed for, hence it is used + for nearly all types of libraries the operating system + provides. On the other hand using shared objects for extending + a program is not used by a lot of programs.

+ +

As of 1998 there are only a few software packages available + which use the DSO mechanism to actually extend their + functionality at run-time: Perl 5 (via its XS mechanism and the + DynaLoader module), Netscape Server, etc. Starting + with version 1.3, Apache joined the crew, because Apache + already uses a module concept to extend its functionality and + internally uses a dispatch-list-based approach to link external + modules into the Apache core functionality. So, Apache is + really predestined for using DSO to load its modules at + run-time.

+ +

Advantages and + Disadvantages

+ +

The above DSO based features have the following + advantages:

+ +

The server package is more flexible at run-time because + the actual server process can be assembled at run-time via LoadModule + httpd.conf configuration commands instead of + configure options at build-time. For instance + this way one is able to run different server instances + (standard & SSL version, minimalistic & powered up + version [mod_perl, PHP3], etc.) with only one Apache + installation.
The server package can be easily extended with + third-party modules even after installation. This is at least + a great benefit for vendor package maintainers who can create + a Apache core package and additional packages containing + extensions like PHP3, mod_perl, mod_fastcgi, + etc.
Easier Apache module prototyping because with the + DSO/apxs pair you can both work outside the + Apache source tree and only need an apxs -i + command followed by an apachectl restart to + bring a new version of your currently developed module into + the running Apache server.

+ +

DSO has the following disadvantages:

+ +

The DSO mechanism cannot be used on every platform + because not all operating systems support dynamic loading of + code into the address space of a program.
The server is approximately 20% slower at startup time + because of the symbol resolving overhead the Unix loader now + has to do.
The server is approximately 5% slower at execution time + under some platforms because position independent code (PIC) + sometimes needs complicated assembler tricks for relative + addressing which are not necessarily as fast as absolute + addressing.
Because DSO modules cannot be linked against other + DSO-based libraries (ld -lfoo) on all platforms + (for instance a.out-based platforms usually don't provide + this functionality while ELF-based platforms do) you cannot + use the DSO mechanism for all types of modules. Or in other + words, modules compiled as DSO files are restricted to only + use symbols from the Apache core, from the C library + (libc) and all other dynamic or static libraries + used by the Apache core, or from static library archives + (libfoo.a) containing position independent code. + The only chances to use other code is to either make sure the + Apache core itself already contains a reference to it or + loading the code yourself via dlopen().

+ + + + diff --git a/docs/manual/dso.html.en b/docs/manual/dso.html.en index 2ed4fbbaeae..38d28ba2a81 100644 --- a/docs/manual/dso.html.en +++ b/docs/manual/dso.html.en @@ -1,280 +1,344 @@ - - -Dynamic Shared Object (DSO) support - - - - - - -

-Dynamic Shared Object (DSO) Support -

- -

This document describes how to use DSO modules as well as the theory -behind their use.

- -

Implementation
Usage Summary
Background
Advantages and Disadvantages

- -

- - -

-Related Modules

- -mod_so
- -

-Related Directives

- -LoadModule
- -

- -

Implementation

- -

Usage Summary

- -

To give you an overview of the DSO features of Apache 2.0, here is a short -and concise summary: - -

Build and install a distributed Apache module, say -mod_foo.c, into its own DSO mod_foo.so: - - + +

+ + + + + + + Dynamic Shared Object (DSO) support + + + + + + +

Dynamic Shared Object (DSO) Support

+ +

This document describes how to use DSO modules as well as + the theory behind their use.

+ +

Implementation
Usage Summary
Background
Advantages and + Disadvantages

+ + + + + + + +

Related Modules
+
+ mod_so
+

Related Directives
+
+ LoadModule
+

+ +

Implementation

+ +

Usage Summary

+ +

To give you an overview of the DSO features of Apache 2.0, + here is a short and concise summary:

+ +

+ Build and install a distributed Apache module, say + mod_foo.c, into its own DSO + mod_foo.so: + + + +
+
$ ./configure --prefix=/path/to/install --enable-foo=shared $ make install -
-
- -
Build and install a third-party Apache module, say -mod_foo.c, into its own DSO mod_foo.so: - - + +
-
+
+
+
+ Build and install a third-party Apache module, say + mod_foo.c, into its own DSO + mod_foo.so: + + + +
+
$ ./configure --add-module=module_type:/path/to/3rdparty/mod_foo.c --enable-foo=shared $ make install -
-
- -
Configure Apache for later installation of shared modules: - + +
-
+
+
+
+ Configure Apache for later installation of shared + modules: + + + +
+
$ ./configure --enable-so $ make install -
-
- -
Build and install a third-party Apache module, say -mod_foo.c, into its own DSO mod_foo.so outside -of the Apache source tree using apxs: - + +
-
+
+
+
+ Build and install a third-party Apache module, say + mod_foo.c, into its own DSO + mod_foo.so outside of the Apache + source tree using apxs: + + + +
+
$ cd /path/to/3rdparty $ apxs -c mod_foo.c $ apxs -i -a -n foo mod_foo.so -
-
- -

- -

In all cases, once the shared module is compiled, you must use a LoadModule directive -in httpd.conf to tell Apache to activate the module. - - - -

Background

- -

Advantages and Disadvantages

- -

The above DSO based features have the following advantages: - -

The server package is more flexible at run-time because the actual server - process can be assembled at run-time via LoadModule - httpd.conf configuration commands instead of - configure options at build-time. - For instance this way one is able to run different server instances - (standard & SSL version, minimalistic & powered up version - [mod_perl, PHP3], etc.) with only one Apache installation. -
-
The server package can be easily extended with third-party modules even - after installation. This is at least a great benefit for vendor package - maintainers who can create a Apache core package and additional packages - containing extensions like PHP3, mod_perl, mod_fastcgi, etc. -
-
Easier Apache module prototyping because with the DSO/apxs - pair you can both work outside the Apache source tree and only need an - apxs -i command followed by an apachectl - restart to bring a new version of your currently developed module - into the running Apache server. -

- -

DSO has the following disadvantages: - -

The DSO mechanism cannot be used on every platform because not all - operating systems support dynamic loading of code into the address space - of a program. -
-
The server is approximately 20% slower at startup time because of the - symbol resolving overhead the Unix loader now has to do. -
-
The server is approximately 5% slower at execution time under some - platforms because position independent code (PIC) sometimes needs - complicated assembler tricks for relative addressing which are not - necessarily as fast as absolute addressing. -
-
Because DSO modules cannot be linked against other DSO-based libraries - (ld -lfoo) on all platforms (for instance a.out-based - platforms usually don't provide this functionality while ELF-based - platforms do) you cannot use the DSO mechanism for all types of modules. - Or in other words, modules compiled as DSO files are restricted to only - use symbols from the Apache core, from the C library (libc) - and all other dynamic or static libraries used by the Apache core, or - from static library archives (libfoo.a) containing position - independent code. The only chances to use other code is to either make - sure the Apache core itself already contains a reference to it or loading - the code yourself via dlopen(). -
-

- - - - +

+ +

In all cases, once the shared module is compiled, you must + use a LoadModule + directive in httpd.conf to tell Apache to activate + the module.

+ +

Background

+ +

Advantages and + Disadvantages

+ +

The above DSO based features have the following + advantages:

+ +

The server package is more flexible at run-time because + the actual server process can be assembled at run-time via LoadModule + httpd.conf configuration commands instead of + configure options at build-time. For instance + this way one is able to run different server instances + (standard & SSL version, minimalistic & powered up + version [mod_perl, PHP3], etc.) with only one Apache + installation.
The server package can be easily extended with + third-party modules even after installation. This is at least + a great benefit for vendor package maintainers who can create + a Apache core package and additional packages containing + extensions like PHP3, mod_perl, mod_fastcgi, + etc.
Easier Apache module prototyping because with the + DSO/apxs pair you can both work outside the + Apache source tree and only need an apxs -i + command followed by an apachectl restart to + bring a new version of your currently developed module into + the running Apache server.

+ +

DSO has the following disadvantages:

+ +

The DSO mechanism cannot be used on every platform + because not all operating systems support dynamic loading of + code into the address space of a program.
The server is approximately 20% slower at startup time + because of the symbol resolving overhead the Unix loader now + has to do.
The server is approximately 5% slower at execution time + under some platforms because position independent code (PIC) + sometimes needs complicated assembler tricks for relative + addressing which are not necessarily as fast as absolute + addressing.
Because DSO modules cannot be linked against other + DSO-based libraries (ld -lfoo) on all platforms + (for instance a.out-based platforms usually don't provide + this functionality while ELF-based platforms do) you cannot + use the DSO mechanism for all types of modules. Or in other + words, modules compiled as DSO files are restricted to only + use symbols from the Apache core, from the C library + (libc) and all other dynamic or static libraries + used by the Apache core, or from static library archives + (libfoo.a) containing position independent code. + The only chances to use other code is to either make sure the + Apache core itself already contains a reference to it or + loading the code yourself via dlopen().

+ + + + diff --git a/docs/manual/ebcdic.html b/docs/manual/ebcdic.html index 8b9ce3cb4ee..0f5571e591c 100644 --- a/docs/manual/ebcdic.html +++ b/docs/manual/ebcdic.html @@ -1,505 +1,656 @@ - - - -The Apache EBCDIC Port - - - - - - -

Warning: -This document has not been updated to take into account changes -made in the 2.0 version of the Apache HTTP Server. Some of the -information may still be relevant, but please use it -with care. -

- -

Overview of the Apache EBCDIC Port

- -

- Version 1.3 of the Apache HTTP Server is the first version which - includes a port to a (non-ASCII) mainframe machine which uses - the EBCDIC character set as its native codeset.
- (It is the SIEMENS family of mainframes running the - BS2000/OSD - operating system. This mainframe OS nowadays features a - SVR4-derived POSIX subsystem). -

- -

- The port was started initially to -

prove the feasibility of porting - the Apache HTTP server - to this platform -
find a "worthy and capable" successor for the venerable - CERN-3.0 daemon - (which was ported a couple of years ago), and to -
prove that Apache's preforking process model can on this platform - easily outperform the accept-fork-serve model used by CERN by a - factor of 5 or more. -

- -

- This document serves as a rationale to describe some of the design - decisions of the port to this machine. -

- -

Design Goals

- One objective of the EBCDIC port was to maintain enough backwards - compatibility with the (EBCDIC) CERN server to make the transition to - the new server attractive and easy. This required the addition of - a configurable method to define whether a HTML document was stored - in ASCII (the only format accepted by the old server) or in EBCDIC - (the native document format in the POSIX subsystem, and therefore - the only realistic format in which the other POSIX tools like grep - or sed could operate on the documents). The current solution to - this is a "pseudo-MIME-format" which is intercepted and - interpreted by the Apache server (see below). Future versions - might solve the problem by defining an "ebcdic-handler" for all - documents which must be converted. -

- -

Technical Solution

- Since all Apache input and output is based upon the BUFF data type - and its methods, the easiest solution was to add the conversion to - the BUFF handling routines. The conversion must be settable at any - time, so a BUFF flag was added which defines whether a BUFF object - has currently enabled conversion or not. This flag is modified at - several points in the HTTP protocol: -

set before a request is received (because the - request and the request header lines are always in ASCII - format) - -
set/unset when the request body is - received - depending on the content type of the request body - (because the request body may contain ASCII text or a binary file) - -
set before a reply header is sent (because the - response header lines are always in ASCII format) - -
set/unset when the response body is - sent - depending on the content type of the response body - (because the response body may contain text or a binary file) -

- -

Porting Notes

- The relevant changes in the source are #ifdef'ed into two - categories: -
-
#ifdef CHARSET_EBCDIC -
Code which is needed for any EBCDIC based machine. This - includes character translations, differences in - contiguity of the two character sets, flags which - indicate which part of the HTTP protocol has to be - converted and which part doesn't etc. -
#ifdef _OSD_POSIX -
Code which is needed for the SIEMENS BS2000/OSD - mainframe platform only. This deals with include file - differences and socket implementation topics which are - only required on the BS2000/OSD platform. -
-

- The possibility to translate between ASCII and EBCDIC at the - socket level (on BS2000 POSIX, there is a socket option which - supports this) was intentionally not chosen, because - the byte stream at the HTTP protocol level consists of a - mixture of protocol related strings and non-protocol related - raw file data. HTTP protocol strings are always encoded in - ASCII (the GET request, any Header: lines, the chunking - information etc.) whereas the file transfer parts (i.e., GIF - images, CGI output etc.) should usually be just "passed through" - by the server. This separation between "protocol string" and - "raw data" is reflected in the server code by functions like - bgets() or rvputs() for strings, and functions like bwrite() - for binary data. A global translation of everything would - therefore be inadequate.
- (In the case of text files of course, provisions must be made so - that EBCDIC documents are always served in ASCII) -

- This port therefore features a built-in protocol level conversion - for the server-internal strings (which the compiler translated to - EBCDIC strings) and thus for all server-generated documents. - The hard coded ASCII escapes \012 and \015 which are - ubiquitous in the server code are an exception: they are - already the binary encoding of the ASCII \n and \r and must - not be converted to ASCII a second time. This exception is - only relevant for server-generated strings; and external - EBCDIC documents are not expected to contain ASCII newline characters. -

- By examining the call hierarchy for the BUFF management - routines, I added an "ebcdic/ascii conversion layer" which - would be crossed on every puts/write/get/gets, and a - conversion flag which allowed enabling/disabling the - conversions on-the-fly. Usually, a document crosses this - layer twice from its origin source (a file or CGI output) to - its destination (the requesting client): file -> - Apache, and Apache -> client.
- The server can now read the header - lines of a CGI-script output in EBCDIC format, and then find - out that the remainder of the script's output is in ASCII - (like in the case of the output of a WWW Counter program: the - document body contains a GIF image). All header processing is - done in the native EBCDIC format; the server then determines, - based on the type of document being served, whether the - document body (except for the chunking information, of - course) is in ASCII already or must be converted from EBCDIC. -

- For Text documents (MIME types text/plain, text/html etc.), - an implicit translation to ASCII can be used, or (if the - users prefer to store some documents in raw ASCII form for - faster serving, or because the files reside on a NFS-mounted - directory tree) can be served without conversion. -
- Example:

- to serve files with the suffix .ahtml as a raw ASCII text/html - document without implicit conversion (and suffix .ascii - as ASCII text/plain), use the directives:

+ + + + + + + The Apache EBCDIC Port + + + + + + +

+ Warning: This document has not been updated + to take into account changes made in the 2.0 version of the + Apache HTTP Server. Some of the information may still be + relevant, but please use it with care. +

+ +

Overview of the Apache EBCDIC Port

+ +

Version 1.3 of the Apache HTTP Server is the first version + which includes a port to a (non-ASCII) mainframe machine which + uses the EBCDIC character set as its native codeset.
+ (It is the SIEMENS family of mainframes running the BS2000/OSD + operating system. This mainframe OS nowadays features a + SVR4-derived POSIX subsystem).

+ +

The port was started initially to

+ +

prove the feasibility of porting the Apache HTTP server to + this platform
find a "worthy and capable" successor for the venerable + CERN-3.0 daemon + (which was ported a couple of years ago), and to
prove that Apache's preforking process model can on this + platform easily outperform the accept-fork-serve model used + by CERN by a factor of 5 or more.

+
+
+ + +

This document serves as a rationale to describe some of the + design decisions of the port to this machine.

+ +

Design Goals

+ +

One objective of the EBCDIC port was to maintain enough + backwards compatibility with the (EBCDIC) CERN server to make + the transition to the new server attractive and easy. This + required the addition of a configurable method to define + whether a HTML document was stored in ASCII (the only format + accepted by the old server) or in EBCDIC (the native document + format in the POSIX subsystem, and therefore the only realistic + format in which the other POSIX tools like grep or sed could + operate on the documents). The current solution to this is a + "pseudo-MIME-format" which is intercepted and interpreted by + the Apache server (see below). Future versions might solve the + problem by defining an "ebcdic-handler" for all documents which + must be converted.

+ +

Technical Solution

+ +

Since all Apache input and output is based upon the BUFF + data type and its methods, the easiest solution was to add the + conversion to the BUFF handling routines. The conversion must + be settable at any time, so a BUFF flag was added which defines + whether a BUFF object has currently enabled conversion or not. + This flag is modified at several points in the HTTP + protocol:

+ +

set before a request is received + (because the request and the request header lines are always + in ASCII format)
set/unset when the request body is + received - depending on the content type of the request body + (because the request body may contain ASCII text or a binary + file)
set before a reply header is sent + (because the response header lines are always in ASCII + format)
set/unset when the response body is sent + - depending on the content type of the response body (because + the response body may contain text or a binary file)

+
+
+ + +

Porting Notes

+ +

+ The relevant changes in the source are #ifdef'ed into two + categories: + +
+
#ifdef + CHARSET_EBCDIC
+ +
Code which is needed for any EBCDIC based machine. + This includes character translations, differences in + contiguity of the two character sets, flags which + indicate which part of the HTTP protocol has to be + converted and which part doesn't etc.
+ +
#ifdef _OSD_POSIX
+ +
Code which is needed for the SIEMENS BS2000/OSD + mainframe platform only. This deals with include file + differences and socket implementation topics which are + only required on the BS2000/OSD platform.
+
+
+
The possibility to translate between ASCII and EBCDIC at + the socket level (on BS2000 POSIX, there is a socket option + which supports this) was intentionally not chosen, + because the byte stream at the HTTP protocol level consists + of a mixture of protocol related strings and non-protocol + related raw file data. HTTP protocol strings are always + encoded in ASCII (the GET request, any Header: lines, the + chunking information etc.) whereas the file transfer + parts (i.e., GIF images, CGI output etc.) + should usually be just "passed through" by the server. This + separation between "protocol string" and "raw data" is + reflected in the server code by functions like bgets() or + rvputs() for strings, and functions like bwrite() for binary + data. A global translation of everything would therefore be + inadequate.
+ (In the case of text files of course, provisions must be + made so that EBCDIC documents are always served in + ASCII)
+
This port therefore features a built-in protocol level + conversion for the server-internal strings (which the + compiler translated to EBCDIC strings) and thus for all + server-generated documents. The hard coded ASCII escapes \012 + and \015 which are ubiquitous in the server code are an + exception: they are already the binary encoding of the ASCII + \n and \r and must not be converted to ASCII a second time. + This exception is only relevant for server-generated strings; + and external EBCDIC documents are not expected to + contain ASCII newline characters.
+
By examining the call hierarchy for the BUFF management + routines, I added an "ebcdic/ascii conversion layer" which + would be crossed on every puts/write/get/gets, and a + conversion flag which allowed enabling/disabling the + conversions on-the-fly. Usually, a document crosses this + layer twice from its origin source (a file or CGI output) to + its destination (the requesting client): file -> + Apache, and Apache -> client.
+ The server can now read the header lines of a CGI-script + output in EBCDIC format, and then find out that the remainder + of the script's output is in ASCII (like in the case of the + output of a WWW Counter program: the document body contains a + GIF image). All header processing is done in the native + EBCDIC format; the server then determines, based on the type + of document being served, whether the document body (except + for the chunking information, of course) is in ASCII already + or must be converted from EBCDIC.
+
+ For Text documents (MIME types text/plain, text/html + etc.), an implicit translation to ASCII can be + used, or (if the users prefer to store some documents in + raw ASCII form for faster serving, or because the files + reside on a NFS-mounted directory tree) can be served + without conversion.
+ Example: + +
+ to serve files with the suffix .ahtml as a raw ASCII + text/html document without implicit conversion (and + suffix .ascii as ASCII text/plain), use the directives: +
```
       AddType  text/x-ascii-html  .ahtml
       AddType  text/x-ascii-plain .ascii
-      
```
- Similarly, any text/foo MIME type can be served as "raw ASCII" by - configuring a MIME type "text/x-ascii-foo" for it using AddType. -

- Non-text documents are always served "binary" without conversion. - This seems to be the most sensible choice for, .e.g., GIF/ZIP/AU - file types. This of course requires the user to copy them to the - mainframe host using the "rcp -b" binary switch. -

- Server parsed files are always assumed to be in native (i.e., - EBCDIC) format as used on the machine, and are converted after - processing. -

- For CGI output, the CGI script determines whether a conversion is - needed or not: by setting the appropriate Content-Type, text files - can be converted, or GIF output can be passed through unmodified. - An example for the latter case is the wwwcount program which we ported - as well. -

- -

Document Storage Notes

Binary Files

- All files with a Content-Type: which does not - start with text/ are regarded as binary files - by the server and are not subject to any conversion. - Examples for binary files are GIF images, gzip-compressed - files and the like. -

- When exchanging binary files between the mainframe host and a - Unix machine or Windows PC, be sure to use the ftp "binary" - (TYPE I) command, or use the - rcp -b command from the mainframe host - (the -b switch is not supported in unix rcp's). -

- -

Text Documents

- The default assumption of the server is that Text Files - (i.e., all files whose Content-Type: starts with - text/) are stored in the native character - set of the host, EBCDIC. -

- -

Server Side Included Documents

- SSI documents must currently be stored in EBCDIC only. No - provision is made to convert it from ASCII before processing. -

- -

Apache Modules' Status

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Module -	Status -	Notes -
http_core -	+ -	-
mod_access -	+ -	-
mod_actions -	+ -	-
mod_alias -	+ -	-
mod_asis -	+ -	-
mod_auth -	+ -	-
mod_auth_anon -	+ -	-
mod_auth_db -	? -	with own libdb.a -
mod_auth_dbm -	? -	with own libdb.a -
mod_autoindex -	+ -	-
mod_cern_meta -	? -	-
mod_cgi -	+ -	-
mod_digest -	+ -	-
mod_dir -	+ -	-
mod_so -	- -	no shared libs -
mod_env -	+ -	-
mod_example -	- -	(test bed only) -
mod_expires -	+ -	-
mod_headers -	+ -	-
mod_imap -	+ -	-
mod_include -	+ -	-
mod_info -	+ -	-
mod_log_agent -	+ -	-
mod_log_config -	+ -	-
mod_log_referer -	+ -	-
mod_mime -	+ -	-
mod_mime_magic -	? -	not ported yet -
mod_negotiation -	+ -	-
mod_proxy -	+ -	-
mod_rewrite -	+ -	untested -
mod_setenvif -	+ -	-
mod_speling -	+ -	-
mod_status -	+ -	-
mod_unique_id -	+ -	-
mod_userdir -	+ -	-
mod_usertrack -	? -	untested -

- -

Third Party Modules' Status

- - - - - - - - - - - - - - - - -

Module -	Status -	Notes -
mod_jserv -	- -	JAVA still being ported. -
mod_php3 -	+ -	mod_php3 runs fine, with LDAP and GD and FreeType libraries -
mod_put -	? -	untested -
mod_session -	- -	untested -

- - - - + +

+ Similarly, any text/foo MIME type can be served as "raw + ASCII" by configuring a MIME type "text/x-ascii-foo" for it + using AddType. +

+
Non-text documents are always served "binary" without + conversion. This seems to be the most sensible choice for, + .e.g., GIF/ZIP/AU file types. This of course + requires the user to copy them to the mainframe host using + the "rcp -b" binary switch.
+
Server parsed files are always assumed to be in native + (i.e., EBCDIC) format as used on the machine, and + are converted after processing.
+
For CGI output, the CGI script determines whether a + conversion is needed or not: by setting the appropriate + Content-Type, text files can be converted, or GIF output can + be passed through unmodified. An example for the latter case + is the wwwcount program which we ported as well.
+

+
+
+ + +

Document Storage Notes

+ +

Binary Files

+ +

All files with a Content-Type: which does not + start with text/ are regarded as binary + files by the server and are not subject to any conversion. + Examples for binary files are GIF images, gzip-compressed files + and the like.

+ +

When exchanging binary files between the mainframe host and + a Unix machine or Windows PC, be sure to use the ftp "binary" + (TYPE I) command, or use the + rcp -b command from the mainframe host (the + -b switch is not supported in unix rcp's).

+ +

Text Documents

+ +

The default assumption of the server is that Text Files + (i.e., all files whose Content-Type: + starts with text/) are stored in the native + character set of the host, EBCDIC.

+ +

Server Side Included Documents

+ +

SSI documents must currently be stored in EBCDIC only. No + provision is made to convert it from ASCII before + processing.

+ +

Apache Modules' Status

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Module	Status	Notes
http_core	+	+
mod_access	+	+
mod_actions	+	+
mod_alias	+	+
mod_asis	+	+
mod_auth	+	+
mod_auth_anon	+	+
mod_auth_db	?	with own libdb.a
mod_auth_dbm	?	with own libdb.a
mod_autoindex	+	+
mod_cern_meta	?	+
mod_cgi	+	+
mod_digest	+	+
mod_dir	+	+
mod_so	-	no shared libs
mod_env	+	+
mod_example	-	(test bed only)
mod_expires	+	+
mod_headers	+	+
mod_imap	+	+
mod_include	+	+
mod_info	+	+
mod_log_agent	+	+
mod_log_config	+	+
mod_log_referer	+	+
mod_mime	+	+
mod_mime_magic	?	not ported yet
mod_negotiation	+	+
mod_proxy	+	+
mod_rewrite	+	untested
mod_setenvif	+	+
mod_speling	+	+
mod_status	+	+
mod_unique_id	+	+
mod_userdir	+	+
mod_usertrack	?	untested

+ +

Third Party Modules' Status

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Module	Status	Notes
mod_jserv	-	JAVA still being ported.
mod_php3 +	+	mod_php3 runs fine, with LDAP and GD and FreeType + libraries
+ mod_put	?	untested
mod_session +	-	untested

+ + + + diff --git a/docs/manual/env.html b/docs/manual/env.html index 6e755593856..8224f9768b6 100644 --- a/docs/manual/env.html +++ b/docs/manual/env.html @@ -1,268 +1,283 @@ - - - -Environment Variables in Apache - - - - - -

Environment Variables in Apache

- -

The Apache HTTP Server provides a mechanism for storing information -in named variables that are called environment variables. -This information can be used to control various operations such as -logging or access control. The variables are also used as a mechanism -to communicate with external programs such as CGI scripts. This -document discusses different ways to manipulate and use these -variables.

- -

Although these variables are referred to as environment -variables, they are not the same as the environment variables -controlled by the underlying operating system. Instead, these -variables are stored and manipulated in an internal Apache structure. -They only become actual operating system environment variables when -they are provided to CGI scripts and Server Side Include scripts. If -you wish to manipulate the operating system environment under which -the server itself runs, you must use the standard environment -manipulation mechanisms provided by your operating system shell.

- -

Setting Environment Variables
Using Environment Variables
Special Purpose Environment Variables
Examples

- -

Setting Environment Variables

- - -

-Related Modules

- -mod_env
-mod_rewrite
-mod_setenvif
-mod_unique_id
- -

-Related Directives

- -BrowserMatch
-BrowserMatchNoCase
-PassEnv
-RewriteRule
-SetEnv
-SetEnvIf
-SetEnvIfNoCase
-UnsetEnv
-

- -

Basic Environment Manipulation

- -

The most basic way to set an environment variable in Apache is -using the unconditional SetEnv directive. Variables -may also be passed from the environment of the shell which started -the server using the PassEnv directive.

- -

Conditional Per-Request Settings

- -

For additional flexibility, the directives provided by mod_setenvif -allow environment variables to be set on a per-request basis, -conditional on characteristics of particular requests. For example, a -variable could be set only when a specific browser (User-Agent) is -making a request, or only when a specific Referer [sic] header is -found. Even more flexibility is available through the mod_rewrite's -RewriteRule which uses the [E=...] option to -set environment variables.

- -

Unique Identifiers

- -

Finally, mod_unique_id sets the environment variable -UNIQUE_ID for each request to a value which is guaranteed -to be unique across "all" requests under very specific conditions.

- -

Standard CGI Variables

- -

In addition to all environment variables set within the Apache -configuration and passed from the shell, CGI scripts and SSI pages are -provided with a set of environment variables containing -meta-information about the request as required by the -CGI specification.

- -

Some Caveats

- -

It is not possible to override or change the standard CGI -variables using the environment manipulation directives.
When suexec is used to launch CGI -scripts, the environment will be cleaned down to a set of -safe variables before CGI scripts are launched. The list of -safe variables is defined at compile-time in -suexec.c.
For portability reasons, the names of environment variables -may contain only letters, numbers, and the underscore character. -In addition, the first character may not be a number. Characters -which do not match this restriction will be replaced by an -underscore when passed to CGI scripts and SSI pages.

- - -

- -

Using Environment Variables

- -

-Related Modules

- -mod_access
-mod_cgi
-mod_headers
-mod_include
-mod_log_config
-mod_rewrite
- -

-Related Directives

- -Allow
-CustomLog
-Deny
-Header
-LogFormat
-RewriteCond
-RewriteRule
- -

- -

CGI Scripts

- -

One of the primary uses of environment variables is to communicate -information to CGI scripts. As discussed above, the environment -passed to CGI scripts includes standard meta-information about the request -in addition to any variables set within the Apache configuration. -For more details, see the CGI tutorial. -

- -

SSI Pages

- -

Server-parsed (SSI) documents processed by mod_include's -INCLUDES filter can print environment variables -using the echo element, and can use environment variables -in flow control elements to makes parts of a page conditional on -characteristics of a request. Apache also provides SSI pages with the -standard CGI environment variables as discussed above. For more -details, see the SSI tutorial. -

- -

Access Control

- -

Access to the server can be controlled based on the value of -environment variables using the allow from env= and -deny from env= directives. In combination with -SetEnvIf, this allows for flexible control of access to -the server based on characteristics of the client. For example, you -can use these directives to deny access to a particular browser -(User-Agent). -

- -

Conditional Logging

- -

Environment variables can be logged in the access log using the -LogFormat option %e. In addition, the -decision on whether or not to log requests can be made based on the -status of environment variables using the conditional form of the -CustomLog directive. In combination with -SetEnvIf this allows for flexible control of which -requests are logged. For example, you can choose not to log requests -for filenames ending in gif, or you can choose to only -log requests from clients which are outside your subnet. -

- -

Conditional Response Headers

- -

The Header directive can use the presence or absence -of an environment variable to determine whether or not a certain -HTTP header will be placed in the response to the client. -This allows, for example, a certain response header to be sent -only if a corresponding header is received in the request from -the client.

- -

URL Rewriting

- -

The %{ENV:...} form of TestString in the -RewriteCond allows mod_rewrite's rewrite engine to make -decisions conditional on environment variables. Note that the -variables accessible in mod_rewrite without the ENV: -prefix are not actually environment variables. Rather, they -are variables special to mod_rewrite which cannot be accessed from -other modules.

- -

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 -are invoked by defining environment variables, typically with -BrowserMatch, though -SetEnv and -PassEnv could also be used, for -example. -

- -

downgrade-1.0

-This forces the request to be treated as a HTTP/1.0 request even if it -was in a later dialect. -

- -

force-no-vary

-This causes any Vary fields to be removed from the response -header before it is sent back to the client. Some clients don't -interpret this field correctly (see the -known client problems -page); setting this variable can work around this problem. Setting -this variable also implies force-response-1.0. -

- -

force-response-1.0

-This forces an HTTP/1.0 response when set. It was originally implemented as a -result of a problem with AOL's proxies. Some clients may not behave correctly -when given an HTTP/1.1 response, and this can be used to interoperate with -them. -

- -

nokeepalive

-This disables KeepAlive when set. -

- - -

- -

Examples

- -

Changing protocol behavior with misbehaving clients

- -

We recommend that the following lines be included in httpd.conf -to deal with known client problems.

- + + + + + + + Environment Variables in Apache + + + + + + +

Environment Variables in Apache

+ +

The Apache HTTP Server provides a mechanism for storing + information in named variables that are called environment + variables. This information can be used to control various + operations such as logging or access control. The variables are + also used as a mechanism to communicate with external programs + such as CGI scripts. This document discusses different ways to + manipulate and use these variables.

+ +

Although these variables are referred to as environment + variables, they are not the same as the environment + variables controlled by the underlying operating system. + Instead, these variables are stored and manipulated in an + internal Apache structure. They only become actual operating + system environment variables when they are provided to CGI + scripts and Server Side Include scripts. If you wish to + manipulate the operating system environment under which the + server itself runs, you must use the standard environment + manipulation mechanisms provided by your operating system + shell.

+ +

Setting Environment Variables
Using Environment Variables
Special Purpose Environment + Variables
Examples

+ +

Setting Environment + Variables

+ + + + + + + +

Related Modules
+
+ mod_env
+ mod_rewrite
+ mod_setenvif
+ mod_unique_id
+

Related Directives
+
+ BrowserMatch
+ BrowserMatchNoCase
+ PassEnv
+ RewriteRule
+ SetEnv
+ SetEnvIf
+ SetEnvIfNoCase
+ UnsetEnv
+

+ +

Basic Environment Manipulation

+ +

The most basic way to set an environment variable in Apache + is using the unconditional SetEnv directive. + Variables may also be passed from the environment of the shell + which started the server using the PassEnv + directive.

+ +

Conditional Per-Request Settings

+ +

For additional flexibility, the directives provided by + mod_setenvif allow environment variables to be set on a + per-request basis, conditional on characteristics of particular + requests. For example, a variable could be set only when a + specific browser (User-Agent) is making a request, or only when + a specific Referer [sic] header is found. Even more flexibility + is available through the mod_rewrite's RewriteRule + which uses the [E=...] option to set environment + variables.

+ +

Unique Identifiers

+ +

Finally, mod_unique_id sets the environment variable + UNIQUE_ID for each request to a value which is + guaranteed to be unique across "all" requests under very + specific conditions.

+ +

Standard CGI Variables

+ +

In addition to all environment variables set within the + Apache configuration and passed from the shell, CGI scripts and + SSI pages are provided with a set of environment variables + containing meta-information about the request as required by + the CGI + specification.

+ +

Some Caveats

+ +

It is not possible to override or change the standard CGI + variables using the environment manipulation directives.
When suexec is used to launch + CGI scripts, the environment will be cleaned down to a set of + safe variables before CGI scripts are launched. The + list of safe variables is defined at compile-time in + suexec.c.
For portability reasons, the names of environment + variables may contain only letters, numbers, and the + underscore character. In addition, the first character may + not be a number. Characters which do not match this + restriction will be replaced by an underscore when passed to + CGI scripts and SSI pages.

+ +

Using Environment + Variables

+ + + + + + + +

Related Modules
+
+ mod_access
+ mod_cgi
+ mod_headers
+ mod_include
+ mod_log_config
+ mod_rewrite
+

Related Directives
+
+ Allow
+ CustomLog
+ Deny
+ Header
+ LogFormat
+ RewriteCond
+ RewriteRule
+

+ +

CGI Scripts

+ +

One of the primary uses of environment variables is to + communicate information to CGI scripts. As discussed above, the + environment passed to CGI scripts includes standard + meta-information about the request in addition to any variables + set within the Apache configuration. For more details, see the + CGI tutorial.

+ +

SSI Pages

+ +

Server-parsed (SSI) documents processed by mod_include's + INCLUDES filter can print environment variables + using the echo element, and can use environment + variables in flow control elements to makes parts of a page + conditional on characteristics of a request. Apache also + provides SSI pages with the standard CGI environment variables + as discussed above. For more details, see the SSI tutorial.

+ +

Access Control

+ +

Access to the server can be controlled based on the value of + environment variables using the allow from env= + and deny from env= directives. In combination with + SetEnvIf, this allows for flexible control of + access to the server based on characteristics of the client. + For example, you can use these directives to deny access to a + particular browser (User-Agent).

+ +

Conditional Logging

+ +

Environment variables can be logged in the access log using + the LogFormat option %e. In addition, + the decision on whether or not to log requests can be made + based on the status of environment variables using the + conditional form of the CustomLog directive. In + combination with SetEnvIf this allows for flexible + control of which requests are logged. For example, you can + choose not to log requests for filenames ending in + gif, or you can choose to only log requests from + clients which are outside your subnet.

+ +

Conditional Response Headers

+ +

The Header directive can use the presence or + absence of an environment variable to determine whether or not + a certain HTTP header will be placed in the response to the + client. This allows, for example, a certain response header to + be sent only if a corresponding header is received in the + request from the client.

+ +

URL Rewriting

+ +

The %{ENV:...} form of TestString in + the RewriteCond allows mod_rewrite's rewrite + engine to make decisions conditional on environment variables. + Note that the variables accessible in mod_rewrite without the + ENV: prefix are not actually environment + variables. Rather, they are variables special to mod_rewrite + which cannot be accessed from other modules.

+ +

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 are invoked by defining environment variables, + typically with BrowserMatch, + though SetEnv and PassEnv could also be used, + for example.

+ +

downgrade-1.0

+ +

This forces the request to be treated as a HTTP/1.0 request + even if it was in a later dialect.

+ +

force-no-vary

+ +

This causes any Vary fields to be removed from + the response header before it is sent back to the client. Some + clients don't interpret this field correctly (see the known client + problems page); setting this variable can work around this + problem. Setting this variable also implies + force-response-1.0.

+ +

force-response-1.0

+ +

This forces an HTTP/1.0 response when set. It was originally + implemented as a result of a problem with AOL's proxies. Some + clients may not behave correctly when given an HTTP/1.1 + response, and this can be used to interoperate with them.

+ +

nokeepalive

+ +

This disables KeepAlive when set.

+ +

Examples

+ +

Changing protocol behavior with misbehaving clients

+ +

We recommend that the following lines be included in + httpd.conf to deal with known client problems.

 #
 # The following directives modify normal HTTP response behavior.
@@ -285,13 +300,12 @@ BrowserMatch "Java/1\.0" force-response-1.0
 BrowserMatch "JDK/1\.0" force-response-1.0

Do not log requests for images in the access log

- -

This example keeps requests for images from appearing -in the access log. It can be easily modified to prevent logging -of particular directories, or to prevent logging of requests -coming from particular hosts.

Do not log requests for images in the access log

This example keeps requests for images from appearing in the + access log. It can be easily modified to prevent logging of + particular directories, or to prevent logging of requests + coming from particular hosts.

     SetEnvIf Request_URI \.gif image-request
     SetEnvIf Request_URI \.jpg image-request
@@ -299,14 +313,13 @@ coming from particular hosts.
     CustomLog logs/access_log env=!image-request

Prevent "Image Theft"

- -

This example shows how to keep people not on your server from using -images on your server as inline-images on their pages. This is not -a recommended configuration, but it can work in limited -circumstances. We assume that all your images are in a directory -called /web/images.

Prevent "Image Theft"

This example shows how to keep people not on your server + from using images on your server as inline-images on their + pages. This is not a recommended configuration, but it can work + in limited circumstances. We assume that all your images are in + a directory called /web/images.

     SetEnvIf Referer "^http://www.example.com/" local_referal
     # Allow browsers that do not send Referer info
@@ -318,11 +331,11 @@ called /web/images.
     </Directory>

For more information about this technique, see the ApacheToday -tutorial "Keeping -Your Images from Adorning Other Sites".

For more information about this technique, see the + ApacheToday tutorial " + Keeping Your Images from Adorning Other Sites".

+ + + - - - diff --git a/docs/manual/env.html.en b/docs/manual/env.html.en index 6e755593856..8224f9768b6 100644 --- a/docs/manual/env.html.en +++ b/docs/manual/env.html.en @@ -1,268 +1,283 @@ - - - -Environment Variables in Apache - - - - - -

Environment Variables in Apache

- -

Setting Environment Variables
Using Environment Variables
Special Purpose Environment Variables
Examples

- -

Setting Environment Variables

- - -

-Related Modules

- -mod_env
-mod_rewrite
-mod_setenvif
-mod_unique_id
- -

-Related Directives

- -BrowserMatch
-BrowserMatchNoCase
-PassEnv
-RewriteRule
-SetEnv
-SetEnvIf
-SetEnvIfNoCase
-UnsetEnv
-

- -

Basic Environment Manipulation

- -

Conditional Per-Request Settings

- -

Unique Identifiers

- -

Finally, mod_unique_id sets the environment variable -UNIQUE_ID for each request to a value which is guaranteed -to be unique across "all" requests under very specific conditions.

- -

Standard CGI Variables

- -

Some Caveats

- -

It is not possible to override or change the standard CGI -variables using the environment manipulation directives.
When suexec is used to launch CGI -scripts, the environment will be cleaned down to a set of -safe variables before CGI scripts are launched. The list of -safe variables is defined at compile-time in -suexec.c.
For portability reasons, the names of environment variables -may contain only letters, numbers, and the underscore character. -In addition, the first character may not be a number. Characters -which do not match this restriction will be replaced by an -underscore when passed to CGI scripts and SSI pages.

- - -

- -

Using Environment Variables

- -

-Related Modules

- -mod_access
-mod_cgi
-mod_headers
-mod_include
-mod_log_config
-mod_rewrite
- -

-Related Directives

- -Allow
-CustomLog
-Deny
-Header
-LogFormat
-RewriteCond
-RewriteRule
- -

- -

CGI Scripts

- -

SSI Pages

- -

Access Control

- -

Conditional Logging

- -

Conditional Response Headers

- -

URL Rewriting

- -

Special Purpose Environment Variables

- -

downgrade-1.0

-This forces the request to be treated as a HTTP/1.0 request even if it -was in a later dialect. -

- -

force-no-vary

- -

force-response-1.0

- -

nokeepalive

-This disables KeepAlive when set. -

- - -

- -

Examples

- -

Changing protocol behavior with misbehaving clients

- -

We recommend that the following lines be included in httpd.conf -to deal with known client problems.

- + + + + + + + Environment Variables in Apache + + + + + + +

Environment Variables in Apache

+ +

Setting Environment Variables
Using Environment Variables
Special Purpose Environment + Variables
Examples

+ +

Setting Environment + Variables

+ + + + + + + +

Related Modules
+
+ mod_env
+ mod_rewrite
+ mod_setenvif
+ mod_unique_id
+

Related Directives
+
+ BrowserMatch
+ BrowserMatchNoCase
+ PassEnv
+ RewriteRule
+ SetEnv
+ SetEnvIf
+ SetEnvIfNoCase
+ UnsetEnv
+

+ +

Basic Environment Manipulation

+ +

Conditional Per-Request Settings

+ +

Unique Identifiers

+ +

Finally, mod_unique_id sets the environment variable + UNIQUE_ID for each request to a value which is + guaranteed to be unique across "all" requests under very + specific conditions.

+ +

Standard CGI Variables

+ +

Some Caveats

+ +

It is not possible to override or change the standard CGI + variables using the environment manipulation directives.
When suexec is used to launch + CGI scripts, the environment will be cleaned down to a set of + safe variables before CGI scripts are launched. The + list of safe variables is defined at compile-time in + suexec.c.
For portability reasons, the names of environment + variables may contain only letters, numbers, and the + underscore character. In addition, the first character may + not be a number. Characters which do not match this + restriction will be replaced by an underscore when passed to + CGI scripts and SSI pages.

+ +

Using Environment + Variables

+ + + + + + + +

Related Modules
+
+ mod_access
+ mod_cgi
+ mod_headers
+ mod_include
+ mod_log_config
+ mod_rewrite
+

Related Directives
+
+ Allow
+ CustomLog
+ Deny
+ Header
+ LogFormat
+ RewriteCond
+ RewriteRule
+

+ +

CGI Scripts

+ +

SSI Pages

+ +

Access Control

+ +

Conditional Logging

+ +

Conditional Response Headers

+ +

URL Rewriting

+ +

Special Purpose Environment + Variables

+ +

downgrade-1.0

+ +

This forces the request to be treated as a HTTP/1.0 request + even if it was in a later dialect.

+ +

force-no-vary

+ +

force-response-1.0

+ +

nokeepalive

+ +

This disables KeepAlive when set.

+ +

Examples

+ +

Changing protocol behavior with misbehaving clients

+ +

We recommend that the following lines be included in + httpd.conf to deal with known client problems.

 #
 # The following directives modify normal HTTP response behavior.
@@ -285,13 +300,12 @@ BrowserMatch "Java/1\.0" force-response-1.0
 BrowserMatch "JDK/1\.0" force-response-1.0

Do not log requests for images in the access log

- -

Do not log requests for images in the access log

     SetEnvIf Request_URI \.gif image-request
     SetEnvIf Request_URI \.jpg image-request
@@ -299,14 +313,13 @@ coming from particular hosts.
     CustomLog logs/access_log env=!image-request

Prevent "Image Theft"

- -

Prevent "Image Theft"

     SetEnvIf Referer "^http://www.example.com/" local_referal
     # Allow browsers that do not send Referer info
@@ -318,11 +331,11 @@ called /web/images.
     </Directory>

For more information about this technique, see the ApacheToday -tutorial "Keeping -Your Images from Adorning Other Sites".

For more information about this technique, see the + ApacheToday tutorial " + Keeping Your Images from Adorning Other Sites".

+ + + - - - diff --git a/docs/manual/filter.html b/docs/manual/filter.html index 49c59371968..9d176661c9e 100644 --- a/docs/manual/filter.html +++ b/docs/manual/filter.html @@ -1,60 +1,68 @@ - - - -Filters - Apache HTTPD - - - - - -

Filters

- - - - -

-Related Modules

- -mod_ext_filter
-mod_include
-

-Related Directives

- -AddInputFilter
-AddOutputFilter
-ExtFilterDefine
-ExtFilterOptions
-SetInputFilter
-SetOutputFilter
-

- -

A filter is a process which is applied to data that is -sent or received by the server. Data sent by clients to the server -is processed by input filters while data sent by the -server to the client is processed by output filters. -Multiple filters can be applied to the data, and the order -of the filters can be explicitly specified.

- -

Filters are used internally by Apache to perform functions such as -chunking and byte-range request handling. In addition, modules can -provide filters which are selectable using run-time configuration -directives. The set of filters which apply to data can be manipulated -with the SetInputFilter and SetOutputFilter -directives.

- -

The only configurable filter currently included with the Apache -distribution is the INCLUDES filter which is provided by -mod_include to process output for -Server Side Includes. There is also an experimental module called mod_ext_filter which allows for -external programs to be defined as filters.

- - - - + + + + + + + Filters - Apache HTTPD + + + + + + +

Filters

+ + + + + + + +

Related Modules
+
+ mod_ext_filter
+ mod_include
+

Related Directives
+
+ AddInputFilter
+ AddOutputFilter
+ ExtFilterDefine
+ ExtFilterOptions
+ SetInputFilter
+ SetOutputFilter
+

+ +

A filter is a process which is applied to data that + is sent or received by the server. Data sent by clients to the + server is processed by input filters while data sent + by the server to the client is processed by output + filters. Multiple filters can be applied to the data, and + the order of the filters can be explicitly specified.

+ +

Filters are used internally by Apache to perform functions + such as chunking and byte-range request handling. In addition, + modules can provide filters which are selectable using run-time + configuration directives. The set of filters which apply to + data can be manipulated with the SetInputFilter + and SetOutputFilter directives.

+ +

The only configurable filter currently included with the + Apache distribution is the INCLUDES filter which + is provided by mod_include + to process output for Server Side Includes. There is also an + experimental module called mod_ext_filter which allows + for external programs to be defined as filters.

+ + + + diff --git a/docs/manual/filter.html.en b/docs/manual/filter.html.en index 49c59371968..9d176661c9e 100644 --- a/docs/manual/filter.html.en +++ b/docs/manual/filter.html.en @@ -1,60 +1,68 @@ - - - -Filters - Apache HTTPD - - - - - -

Filters

- - - - -

-Related Modules

- -mod_ext_filter
-mod_include
-

-Related Directives

- -AddInputFilter
-AddOutputFilter
-ExtFilterDefine
-ExtFilterOptions
-SetInputFilter
-SetOutputFilter
-

- -

- - - - + + + + + + + Filters - Apache HTTPD + + + + + + +

Filters

+ + + + + + + +

Related Modules
+
+ mod_ext_filter
+ mod_include
+

Related Directives
+
+ AddInputFilter
+ AddOutputFilter
+ ExtFilterDefine
+ ExtFilterOptions
+ SetInputFilter
+ SetOutputFilter
+

+ +

+ + + + diff --git a/docs/manual/footer.html b/docs/manual/footer.html index 477d58ff601..0cd30f1d74d 100644 --- a/docs/manual/footer.html +++ b/docs/manual/footer.html @@ -1,6 +1,18 @@ -

- Apache HTTP Server Version 2.0 -

+ + + + + + + + + + +

+ +

Apache HTTP Server Version 2.0

+ + -

diff --git a/docs/manual/handler.html.en b/docs/manual/handler.html.en index c9c24275144..e2430733af7 100644 --- a/docs/manual/handler.html.en +++ b/docs/manual/handler.html.en @@ -1,152 +1,160 @@ - - - -Apache's Handler Use - - - - - -

Apache's Handler Use

- -

What is a Handler
Examples
Programmer's Note

- -

What is a Handler

- - - - -

-Related Modules

- -mod_actions
-mod_asis
-mod_cgi
-mod_imap
-mod_info
-mod_mime
-mod_negotiation
-mod_status
-

-Related Directives

- -Action
-AddHandler
-RemoveHandler
-SetHandler
-

- - -

A "handler" is an internal Apache representation of the action to be -performed when a file is called. Generally, files have implicit -handlers, based on the file type. Normally, all files are simply -served by the server, but certain file types are "handled" -separately.

- -

Apache 1.1 adds the ability to use handlers explicitly. Based on -either filename extensions or on location, handlers can be specified -without relation to file type. This is advantageous both because it is -a more elegant solution, and because it also allows for both a type -and a handler to be associated with a file. (See also -Files with Multiple -Extensions.)

- -

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

- -

default-handler: - Send the file using the default_handler(), which is the - handler used by default to handle static content. - (core) -
send-as-is: - Send file with HTTP headers as is. - (mod_asis) -
cgi-script: - Treat the file as a CGI script. - (mod_cgi) -
imap-file: - Parse as an imagemap rule file. - (mod_imap) -
server-info: - Get the server's configuration information. - (mod_info) -
server-status: - Get the server's status report. - (mod_status) -
type-map: - Parse as a type map file for content negotiation. - (mod_negotiation) -

- -

Examples

- -

Modifying static content using a CGI script

- -

The following directives will cause requests for files with the -html extension to trigger the launch of the -footer.pl CGI script.

- + + + + + + + Apache's Handler Use + + + + + + +

Apache's Handler Use

+ +

What is a Handler
Examples
Programmer's Note

+ +

What is a + Handler

+ + + + + + + +

Related Modules
+
+ mod_actions
+ mod_asis
+ mod_cgi
+ mod_imap
+ mod_info
+ mod_mime
+ mod_negotiation
+ mod_status
+

Related Directives
+
+ Action
+ AddHandler
+ RemoveHandler
+ SetHandler
+

+ +

A "handler" is an internal Apache representation of the + action to be performed when a file is called. Generally, files + have implicit handlers, based on the file type. Normally, all + files are simply served by the server, but certain file types + are "handled" separately.

+ +

Apache 1.1 adds the ability to use handlers explicitly. + Based on either filename extensions or on location, handlers + can be specified without relation to file type. This is + advantageous both because it is a more elegant solution, and + because it also allows for both a type and a + handler to be associated with a file. (See also Files with Multiple + Extensions.)

+ +

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

+ +

default-handler: Send the file using the + default_handler(), which is the handler used by + default to handle static content. (core)
send-as-is: Send file with HTTP headers + as is. (mod_asis)
cgi-script: Treat the file as a CGI + script. (mod_cgi)
imap-file: Parse as an imagemap rule + file. (mod_imap)
server-info: Get the server's + configuration information. (mod_info)
server-status: Get the server's status + report. (mod_status)
type-map: Parse as a type map file for + content negotiation. (mod_negotiation)

+ +

Examples

+ +

Modifying static content using a CGI script

+ +

The following directives will cause requests for files with + the html extension to trigger the launch of the + footer.pl CGI script.

      Action add-footer /cgi-bin/footer.pl
      AddHandler add-footer .html

Then the CGI script is responsible for sending the originally -requested document (pointed to by the PATH_TRANSLATED -environment variable) and making whatever modifications or additions -are desired.

- -

Files with HTTP headers

Then the CGI script is responsible for sending the + originally requested document (pointed to by the + PATH_TRANSLATED environment variable) and making + whatever modifications or additions are desired.

The following directives will enable the send-as-is -handler, which is used for files which contain their own HTTP headers. -All files in the /web/htdocs/asis/ directory will be -processed by the send-as-is handler, regardless of their -filename extensions.

Files with HTTP headers

The following directives will enable the + send-as-is handler, which is used for files which + contain their own HTTP headers. All files in the + /web/htdocs/asis/ directory will be processed by + the send-as-is handler, regardless of their + filename extensions.

     <Directory /web/htdocs/asis>
     SetHandler send-as-is
     </Directory>

- -

Programmer's Note

Programmer's + Note

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:

In order to implement the handler features, an addition has + been made to the Apache API that + you may wish to make use of. Specifically, a new record has + been added to the request_rec structure:

     char *handler
-

If you wish to have your module engage a handler, you need only to -set r->handler to the name of the handler at any time -prior to the invoke_handler stage of the -request. Handlers are implemented as they were before, albeit using -the handler name instead of a content type. While it is not -necessary, the naming convention for handlers is to use a -dash-separated word, with no slashes, so as to not invade the media -type name-space.

- - - - +

+ +

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.

+ + + diff --git a/docs/manual/handler.html.ja.jis b/docs/manual/handler.html.ja.jis index 917aabdccd1..d00827fc740 100644 --- a/docs/manual/handler.html.ja.jis +++ b/docs/manual/handler.html.ja.jis @@ -1,146 +1,39 @@ - - - -Apache $B$N%O%s%I%i$N;HMQ(B - - + - - - -

Apache $B$N%O%s%I%i$N;HMQ(B

+ + + -

$B%O%s%I%i$H$O(B
$BNc(B
$B%W%m%0%i%^8~$1$N%a%b(B

+ Apache $B$N%O%s%I%i$N;HMQ(B + + + -

$B%O%s%I%i$H$O(B

+ + - - - -

-$B4XO"%b%8%e!<%k(B

+

Apache $B$N%O%s%I%i$N;HMQ(B

-mod_actions
-mod_asis
-mod_cgi
-mod_imap
-mod_info
-mod_mime
-mod_negotiation
-mod_status
-

-$B4XO"%G%#%l%/%F%#%V(B

+

$B%O%s%I%i$H$O(B

$B%W%m%0%i%^8~$1$N%a%b(B

+ +

$B!V%O%s%I%i!W$H$O!"%U%!%$%k$,8F$P$l$?$H$-$Ko!"%U%!%$%k$O%U%!%$%k7?$K4p$E$$$?0EL[$N(B -$B%O%s%I%i$,$"$j$^$9!#IaDL$O$9$Y$F$N%U%!%$%k$OC1$K%5!<%P$K07$o$l$^$9$,!"(B -$B%U%!%$%k%?%$%W$NCf$K$OJL$K!V%O%s%I%k!W(B ($BLuCm(B: $B07$&(B) $B$5$l$k$b$N$b$"$j$^$9!#(B

$B%O%s%I%i$H$O(B

Apache 1.1 $B$G$O!"%O%s%I%i$rL@<(E*$K;HMQ$9$k5!G=$,DI2C$5$l$^$7$?!#(B -$B%U%!%$%k$N3HD%;R$dCV$$$F$$$k>l=j$K4p$E$$$F!"%U%!%$%k7?$H4X78$J$/%O%s%I%i$r(B -$B;XDj$9$k$3$H$,$G$-$^$9!#$3$l$O$h$jM%2m$J2r7hK!$H$$$&E@$H!"%U%!%$%k$K(B -$B%?%$%W(B$B$H(B$B%O%s%I%i$NN>J}$r4XO"IU$1$k$3$H$,$G$-$k$H$$$&(B -$BE@$GM%$l$F$$$^$9!#(B ($BJ#?t$N3HD%;R$N$"$k%U%!%$%k(B -$B$b;2>H$7$F$/$@$5$$(B)$B!#(B

- -

$B%O%s%I%i$O%5!<%P$KAH$_9~$s$@$j!"%b%8%e!<%k$H$7$F4^$a$?$j!"(B -Action $B%G%#%l%/%F%#%V$H$7$F(B -$BDI2C$7$?$j$9$k$3$H$,$G$-$^$9!#0J2<$OI8=`G[I[$KAH$_9~$^$l$F$$$k%O%s%I%i$G$9!#(B

- -

default-handler: - default_handelr() $B$r;H$C$F%U%!%$%k$rAw$j$^$9!#(B - $B@EE*$J%3%s%F%s%D$r07$&$H$-$K%G%U%)%k%H$G;HMQ$5$l$k%O%s%I%i$G$9!#(B - (core) -
send-as-is: - HTTP $B%X%C%@$N$"$k%U%!%$%k$r$=$N$^$^Aw$j$^$9!#(B - (mod_asis) -
cgi-script: - $B%U%!%$%k$r(B CGI $B%9%/%j%W%H$H$7$F07$$$^$9!#(B - (mod_cgi) -
imap-file: - $B%$%a!<%8%^%C%W$N%k!<%k%U%!%$%k$H$7$F2r@O$7$^$9!#(B - (mod_imap) -
server-info: - $B%5!<%P$N@_Dj>pJs$rmod_info) -
server-status: - $B%5!<%P$N>uBVJs9p$rmod_status) -
type-map: - $B%3%s%F%s%H%M%4%7%(!<%7%g%s$N$?$a$N%?%$%W%^%C%W$H$7$F2r@O$7$^$9!#(B - (mod_negotiation) -

- -

$BNc(B

- -

CGI $B%9%/%j%W%H$rMQ$$$F@EE*$J%3%s%F%s%D$rJQ99$9$k(B

- -

$B0J2<$N%G%#%l%/%F%#%V$K$h$C$F!"3HD%;R$,(B html $B$G$"$k%U%!%$%k$O(B -footer.pl CGI $B%9%/%j%W%H$r5/F0$9$k$h$&$K$J$j$^$9!#(B

- -

-     Action add-footer /cgi-bin/footer.pl
-     AddHandler add-footer .html
-

- -

CGI $B%9%/%j%W%H$OK>$^$7$$=$@5$dDI2C$r9T$J$C$F!"85!9MW5a$5$l$?J8=q(B -($B4D6-JQ?t(B PATH_TRANSLATED $B$G;X$5$l$F$$$^$9(B) $B$rAw$k@UG$$,$"$j$^$9!#(B

- -

HTTP $B%X%C%@$N$"$k%U%!%$%k(B

- -

$B0J2<$N%G%#%l%/%F%#%V$O(B send-as-is $B%O%s%I%i$r;HMQ$9$k(B -$B$h$&$K;X<($7$^$9!#$3$N%O%s%I%i$O<+J,<+?H$N(B HTTP $B%X%C%@$r;}$C$F$$$k%U%!%$%k$K(B -$B;HMQ$5$l$^$9!#$3$3$G$O!"3HD%;R$K4X$o$i$:!"(B/web/htdocs/asis -$B%G%#%l%/%H%j$K$"$kA4$F$N%U%!%$%k$O(B send-as-is $B%O%s%I%i$K$h$C$F(B -$B07$o$l$^$9!#(B

- -

-    <Directory /web/htdocs/asis>
-    SetHandler send-as-is
-    </Directory>
-

- -

$B%W%m%0%i%^8~$1$N%a%b(B

- -

$B%O%s%I%i$N5!G=$rApache API $B$KDI2C$5$l$^$7$?!#(B -$B>\$7$/8@$&$H!"(Brequest_rec $B9=B$BN$K?7$7$$%l%3!<%I$,(B -$BDI2C$5$l$?$H$$$&$3$H$G$9!#(B

-    char *handler
-

$B$b$7%b%8%e!<%k$,%O%s%I%i$K4X$o$j$?$$>l9g!"$d$i$J$1$l$P$J$i$J$$$3$H$O!"(B -$B%j%/%(%9%H$,(B invoke_handler $B%9%F!<%8$KC#$9$k0JA0$K(B -r->handler $B$r@_Dj$9$k$3$H$@$1$G$9!#(B -$B%O%s%I%i$O%3%s%F%s%H%?%$%W$NBe$o$j$K%O%s%I%iL>$r;H$&$h$&$K$J$C$F$$$k$3$H0J30$O!"(B -$B0JA0$HF1$8$h$&$KA06u4V$r?/$5$J$$$h$&$K!"%O%s%I%i$NL>A0$K$O%9%i%C%7%e(B -$B$r4^$^$J$$!"%@%C%7%e(B ($BLuCm(B: "-") $B$GJ,N%$5$l$?L>A0$rIU$1$k=,47$K$J$C$F$$$^$9!#(B

- - - + + + + +

$B4XO"%b%8%e!

+ + diff --git a/docs/manual/header.html b/docs/manual/header.html index 564a398ae73..6e617988d4e 100644 --- a/docs/manual/header.html +++ b/docs/manual/header.html @@ -1,6 +1,19 @@ -

- Apache HTTP Server Version 2.0 -

+ + + + + + + + + + +

+ +

Apache HTTP Server Version 2.0

+ + + diff --git a/docs/manual/index.html.en b/docs/manual/index.html.en index 8813d1bf9c2..dae581ed5e1 100644 --- a/docs/manual/index.html.en +++ b/docs/manual/index.html.en @@ -1,182 +1,296 @@ - - -Apache HTTP Server Version 2.0 Documentation - - -

- - - - - - - - - - - - -

- - - - - - -

- FAQ -

- Directives -

- Modules -

- Search -

Apache HTTP Server Version 2.0

- -

- - -

- -

- - - - - - - - - -

- - -

- Release Notes -

-New Features in Version 2.0 -

-Upgrading to Version 2.0 -

-Apache License -

- -

- -
-Reference Manual -
-Compiling and Installing -
-Starting -
-Stopping or Restarting -
-Run-time Configuration Directives -
-Modules: By Type or - Alphabetical -
-Multi-Processing Modules (MPMs) -
-Server and Supporting Programs -
-Dynamic Shared Object (DSO) Support -
- -

- -
-Platform Specific Notes -
-Microsoft Windows -
- -

- -

-Using the Apache HTTP Server -

-Configuration Files -

-Server-Wide Configuration -

-Log Files -

-Mapping URLs to the Filesystem -

-Virtual Hosts -

-Server Side Includes -

-Dynamic Content with CGI -

-Handlers -

-Filters -

-Content negotiation -

-Environment Variables -

-Using SetUserID Execution for CGI -

-General Performance hints -

-Security tips -

-URL Rewriting Guide -

- -

- -
-Other Topics -
-Frequently Asked Questions -
-Tutorials -
-Documentation for Developers -
-Other Notes -
-

- -

Maintained by the Apache HTTP Server -Documentation Project.

- - - + + + + + + + Apache HTTP Server Version 2.0 Documentation + + + +

+ + + + + + + + + + + + + + + + +

+ + + + + + + + + + +

FAQ

Directives +

Modules

Search +

Apache HTTP Server Version 2.0

+ +

+ + + + +

+ +

+ + + + + + + + + + +

+ + + + + + + + + + + + + + + + +

+ Release Notes

New Features in + Version 2.0

Upgrading to Version + 2.0

Apache License

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+ Reference Manual

Compiling and + Installing

Starting

Stopping or + Restarting

Run-time + Configuration Directives

Modules: By + Type or Alphabetical

Multi-Processing Modules + (MPMs)

Server and Supporting + Programs

Dynamic Shared Object (DSO) + Support

+ + + + + + + + + +

+ Platform Specific Notes

Microsoft + Windows

+ + + + +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Using + the Apache HTTP Server

Configuration + Files

Server-Wide + Configuration

Log Files

Mapping URLs to the + Filesystem

Virtual Hosts

Server Side + Includes

Dynamic Content with + CGI

Handlers

Filters

Content + negotiation

Environment Variables +

Using SetUserID Execution + for CGI

General + Performance hints

Security + tips

URL Rewriting + Guide

+ + + + + + + + + + + + + + + + + + + + + +

Other + Topics

Frequently Asked Questions +

Tutorials +

Documentation for + Developers

Other Notes

+ +

Maintained by the Apache HTTP Server + Documentation Project.

+ + + diff --git a/docs/manual/index.html.fr b/docs/manual/index.html.fr index e61c2658408..73f0f72942b 100644 --- a/docs/manual/index.html.fr +++ b/docs/manual/index.html.fr @@ -1,163 +1,267 @@ - - - - -Documentation du serveur HTTP Apache version 2.0 - - - -

- - - - - - - - - - - - -

- - - - - - -

- FAQ -

- Directives -

- Modules -

- Rechercher -

Serveur HTTP Apache version 2.0

- -

- - -

- -

- - - - - - - -

- - -

- Notes sur cette version -

-Nouvelles fonctionnalités de la version 2.0 -

-Migrer vers la version 2.0 -

-Licence Apache -

- -

- -
-Manuel de référence -
-Compilation et installation -
-Démarrage -
-Arrêt et redémarrage -
-Directives de configuration de l'exécution -
-Modules par type ou - par ordre alphabétique -
-Modules Multi-Traitements (MPMs) -
-Support des Objets partagés dynamiques (DSO) -
- -

- -
-Notes liées aux plates-formes -
-Microsoft Windows -
-Autres notes pour plates-formes spécifiques -
- -

- -

-Utilisation du serveur HTTP Apache -

-Fichiers de configuration -

-Configuration globale du serveur -

-Hôtes virtuels -

-Handlers -

-Négotiation de contenu -

-Variables d'environnement -

-Utilisation du SetUserID pour les CGI -

-Aides sur les performances générales -

-Trucs sur la sécurité -

-Guide de réécriture d'URLs -

- -

- -
-Autres sujets -
-Foires aux questions -
-Tutoriels -
-Documentation pour les développeurs -
-Autres notes -
-

- -

- - - + + + + + + + + Documentation du serveur HTTP Apache version 2.0 + + + +

+ + + + + + + + + + + + + + + + +

+ + + + + + + + + + +

FAQ

Directives +

Modules

Rechercher +

Serveur HTTP Apache version 2.0

+ +

+ + + + +

+ +

+ + + + + + + + + +

+ + + + + + + + + + + + + + + + +

Notes + sur cette version

Nouvelles + fonctionnalités de la version 2.0

Migrer vers la version + 2.0

Licence Apache

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Manuel + de référence

Compilation et + installation

Démarrage +

Arrêt et + redémarrage

Directives de + configuration de l'exécution

Modules par + type ou par ordre + alphabétique

Modules Multi-Traitements + (MPMs)

Support des Objets + partagés dynamiques (DSO)

+ + + + + + + + + + + + + +

Notes + liées aux plates-formes

Microsoft + Windows

Autres notes pour + plates-formes spécifiques

+ + + + +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+ Utilisation du serveur HTTP Apache +

Fichiers de + configuration

Configuration + globale du serveur

Hôtes virtuels +

Handlers

Négotiation + de contenu

Variables + d'environnement

Utilisation du SetUserID + pour les CGI

Aides sur les + performances générales

Trucs sur la + sécurité

Guide de + réécriture d'URLs

+ + + + + + + + + + + + + + + + + + + + + +

Autres + sujets

Foires aux questions

Tutoriels +

Documentation pour les + développeurs

Autres notes

+ + diff --git a/docs/manual/index.html.ja.jis b/docs/manual/index.html.ja.jis index ea7afa2a928..a7cabf40b85 100644 --- a/docs/manual/index.html.ja.jis +++ b/docs/manual/index.html.ja.jis @@ -1,179 +1,11 @@ - - -Apache HTTP $B%5!<%P(B $B%P!<%8%g%s(B 2.0 $B%I%-%e%a%s%H(B - - -

- - - - - - - - - - - - -

- - - - - - -

- FAQ -

- $B%G%#%l%/%F%#%V(B -

- $B%b%8%e!<%k(B -

- $B8!:w(B -

Apache HTTP Server Version 2.0

+ -

+ + + - -

- -

- - - - - - - - - -

- - -

- $B%j%j!<%9%N!<%H(B -

-Apache 2.0 $B$N?75!G=(B -

-Apache 2.0 $B$X$N%"%C%W%0%l!<%I(B -

-Apache $B$N%i%$%;%s%9(B -

- -

- -
-$B%j%U%!%l%s%9%^%K%e%"%k(B -
-$B%3%s%Q%$%k$H%$%s%9%H!<%k(B -
-$B5/F0(B -
-$B=*N;$^$?$O:F5/F0(B -
-$B -
-$B%b%8%e!<%k(B: $B $B$H(B - $B%"%k%U%!%Y%C%H=g(B -
-Multi-Processing Modules (MPM) -
-$B%5!<%P$H%5%]!<%H%W%m%0%i%`(B -
-Dynamic Shared Object (DSO) $B$N%5%]!<%H(B -
- -

- -
-$B%W%i%C%H%U%)!<%`8GM-$N>pJs(B -
-Microsoft Windows -
-$BB>$N%W%i%C%H%U%)!<%`FCM-$N>pJs(B -
- -

- -

-Apache HTTP $B%5!<%P$r;H$&(B -

-$B@_Dj%U%!%$%k(B -

-$B%5!<%PA4BN$N@_Dj(B -

-URL $B$r%U%!%$%k%7%9%F%`$K%^%C%W$9$k(B -

-$B%P!<%A%c%k%[%9%H(B -

-$B%O%s%I%i(B -

-$B%U%#%k%?(B -

-$B%3%s%F%s%H%M%4%7%(!<%7%g%s(B -

-$B4D6-JQ?t(B -

-CGI $B$G(B SetUserID $B -

-$B0lHLE*$J@-G=$K4X$9$k%R%s%H(B -

-$B%;%-%e%j%F%#>pJs(B -

-URL Rewriting $B$N%,%$%I(B -

- -

- -
-$B$=$NB>(B -
-FAQ -
-$B%A%e!<%H%j%"%k(B -
-$B3+H/ -
-$B$=$NB>(B -
-

- -

Apache HTTP Server -Documentation Project $B$K$h$j%a%s%F%J%s%9$5$l$F$$$^$9!#(B

- - - + Apache HTTP $B%5! + diff --git a/docs/manual/install.html b/docs/manual/install.html index 8d8f4178af9..b9103318d1f 100644 --- a/docs/manual/install.html +++ b/docs/manual/install.html @@ -1,532 +1,634 @@ - - - -Compiling and Installing Apache - - - - - - -

Compiling and Installing

- - -

This document covers compilation and installation of Apache on Unix -and Unix-like systems only. For compiling and installation on Windows, -see Using Apache with Microsoft -Windows. For other platforms, see the platform documentation.

- -

Apache 2.0's configuration and installation environment has changed -completely from Apache 1.3. Apache 1.3 used a custom set of scripts -to achieve easy installation. Apache 2.0 now uses libtool and -autoconf to create an environment that looks like many other Open -Source projects.

- -

Overview for the impatient
Requirements
Download
Extract
Configuring the source tree -
- Environment Variables
- autoconf Output Options
- Pathnames
- Modules
- Suexec
Build
Install
Customize
Test

- -

Overview for the impatient

- - - - - - - - - - - - - - - - - - - - - - - -

Download	`$ lynx http://www.apache.org/dist/httpd/httpd-2_0_NN.tar.gz -`
Extract	`$ gzip -d httpd-2_0_NN.tar.gz -$ tar xvf httpd-2_0_NN.tar -`
Configure	`$ ./configure --prefix=PREFIX -`
Compile	`$ make -`
Install	`$ make install -`
Customize	`$ vi PREFIX/conf/httpd.conf -`
Test	`$ PREFIX/bin/apachectl start -`

- -

NN must be replaced with the current minor version number, -and PREFIX must be replaced with the filesystem path under -which the server should be installed. If PREFIX is not -specified, it defaults to /usr/local/apache2.

- -

Each section of the compilation and installation process is -described in more detail below, beginning with the requirements -for compiling and installing Apache HTTPD.

- -

Requirements

- -

The following requirements exist for building Apache:

- -

Disk Space

Make sure you have at least 50 MB of temporary -free disk space available. After installation Apache occupies -approximately 10 MB of disk space. The actual disk space requirements -will vary considerably based on your chosen configuration options and -any third-party modules.
ANSI-C Compiler and Build System

Make sure you have an -ANSI-C compiler installed. The GNU C compiler -(GCC) from the Free Software -Foundation (FSF) is recommended (version 2.7.2 is fine). If you -don't have GCC then at least make sure your vendor's compiler is ANSI -compliant. In addition, your PATH must contain basic -build tools such as make.
Accurate time keeping

Elements of the HTTP protocol are -expressed as the time of day. So, it's time to investigate setting -some time synchronization facility on your system. Usually the ntpdate -or xntpd programs are used for this purpose which are based on the -Network Time Protocol (NTP). See the Usenet newsgroup comp.protocols.time.ntp and -the NTP homepage for more -details about NTP software and public time servers.
Perl 5 [OPTIONAL]

For -some of the support scripts like apxs -or dbmmanage (which are written -in Perl) the Perl 5 interpreter is required (versions 5.003 and 5.004 -are fine). If no such interpreter is found by the `configure' script -there is no harm. Of course, you still can build and install Apache -2.0. Only those support scripts cannot be used. If you have multiple -Perl interpreters installed (perhaps a Perl 4 from the vendor and a -Perl 5 from your own), then it is recommended to use the --with-perl -option (see below) to make sure the correct one is selected by -./configure.

- -

Download

- -

Apache can be downloaded from the Apache Software Foundation -download site or from a nearby mirror.

- -

Version numbers that end in alpha indicate early -pre-test versions which may or may not work. Version numbers ending -in beta indicate more reliable releases that still -require further testing or bug fixing. If you wish to download the -best available production release of the Apache HTTP Server, you -should choose the latest version with neither alpha nor -beta in its filename.

- -

After downloading, especially if a mirror site is used, it is -important to verify that you have a complete and unmodified version of -the Apache HTTP Server. This can be accomplished by testing the -downloaded tarball against the PGP signature. This, in turn, is a two -step procedure. First, you must obtain the KEYS file -from the Apache distribution -site. (To assure that the KEYS file itself has not -been modified, it may be a good idea to use a file from a previous -distribution of Apache or import the keys from a public key server.) -The keys are imported into your personal key ring using -one of the following commands (depending on your pgp version):

-$ pgp < KEYS -

-or -

-$ gpg --import KEYS -

- -

The next step is to test the tarball against the PGP signature, -which should always be obtained from the main Apache website. The -signature file has a filename identical to the source tarball with the -addition of .asc. Then you can check the distribution -with one of the following commands (again, depending on your pgp -version):

-$ pgp httpd-2_0_NN.tar.gz.asc -

-or -

-$ gpg --verify httpd-2_0_NN.tar.gz.asc -

You should receive a message like

-Good signature from user "Martin Kraemer <martin@apache.org>". -

Depending on the trust relationships contained -in your key ring, you may also receive a message saying that -the relationship between the key and the signer of the key -cannot be verified. This is not a problem if you trust the -authenticity of the KEYS file.

- -

Extract

- -

Extracting the source from the Apache HTTPD tarball is a simple -matter of uncompressing, and then untarring:

- -

-$ gzip -d httpd-2_0_NN.tar.gz -$ tar xvf httpd-2_0_NN.tar -

- -

This will create a new directory under the current directory -containing the source code for the distribution. You should -cd into that directory before proceeding with -compiling the server.

- -

Configuring the source tree

- -

The next step is to configure the Apache source tree for your -particular platform and personal requirements. This is done using the -script configure included in the root directory of the -distribution. (Developers downloading the CVS version of the Apache -source tree will need to have autoconf and -libtool installed and will need to run -buildconf before proceeding with the next steps. This is -not necessary for official releases.)

- -

To configure the source tree using all the default options, simply -type ./configure. To change the default options, -configure accepts a variety of variables and command line -options. Environment variables are generally placed before the -./configure command, while other options are placed -after. The most important option here is the location prefix where -Apache is to be installed later, because Apache has to be configured -for this location to work correctly. But there are a lot of other -options available for your pleasure.

- -

For a short impression of what possibilities you have, here is a -typical example which compiles Apache for the installation tree -/sw/pkg/apache with a particular compiler and flags plus the two -additional modules mod_rewrite and mod_speling for later loading -through the DSO mechanism:

- -

- $ CC="pgcc" CFLAGS="-O2" \ - ./configure --prefix=/sw/pkg/apache \ - --enable-rewrite=shared \ - --enable-speling=shared -

- -

When configure is run it will take several minutes to test for -the availability of features on your system and build Makefiles -which will later be used to compile the server.

- -

The easiest way to find all of the configuration flags for Apache -is to run ./configure --help. What follows is a brief description -of most of the arguments and environment variables.

- -

Environment Variables

- -

The autoconf build process uses several environment variables to -configure the build environment. In general, these variables change -the method used to build Apache, but not the eventual features of the -server. These variables can be placed in the environment before -invoking configure, but it is usually easier to specify -them on the configure command line as demonstrated -in the example above.

- -

CC=...: The name of the C compiler command.
CPPFLAGS=...: Miscellaneous C preprocessor -and compiler options.
CFLAGS=...: Debugging and optimization options for the C compiler.
LDFLAGS=...: Miscellaneous options to be passed to the linker.
LIBS=...: Library location information ("-L" and "-l" options) -to pass to the linker.
INCLUDES=...: Header file search directories ("-Idir").
TARGET=... [Default: apache]: Name of the executable which will be built.
NOTEST_CPPFLAGS=...
NOTEST_CFLAGS=...
NOTEST_LDFLAGS=...
NOTEST_LIBS=...: These variables share the same function as their non-NOTEST namesakes. -However, the variables are applied to the build process only after -autoconf has performed its feature testing. This allows the inclusion of -flags which will cause problems during feature testing, but must be used -for the final compilation.
SHLIB_PATH=...: Options which specify shared library paths for the compiler and -linker.

- -

autoconf Output Options

- -

--help: Prints the usage message including all available options, but -does not actually configure anything.
--quiet: Prevents the printing of the usual "checking..." messages.
--verbose: Prints much more information during the configuration process, -including the names of all the files examined.

- -

Pathnames

- -

There are currently two ways to configure the pathnames under -which Apache will install its files. First, you can specify -a directory and have Apache install itself under that directory -in its default locations.

- -

--prefix=PREFIX [Default: -/usr/local/apache2]: Specifies the directory under which the Apache files will be -installed.

- -

It is possible to specify that architecture-dependent files should -be placed under a different directory.

- -

--exec-prefix=EPREFIX [Default: -PREFIX]: Specifies the directory under which architecture-dependent files -will be placed.

- -

The second, and more flexible way to configure the install path -locations for Apache is using the config.layout file. -Using this method, it is possible to separately specify the location -for each type of file within the Apache installation. The -config.layout file contains several example -configurations, and you can also create your own custom configuration -following the examples. The different layouts in this file are -grouped into <Layout FOO>...</Layout> -sections and referred to by name as in FOO.

- -

--enable-layout=LAYOUT: Use the named layout in the config.layout file -to specify the installation paths.

- -

Presently it is not possible to mix the ---enable-layout and --prefix options. Nor -is it possible to individually specify detailed pathnames on the -configure command line. If you want just a basic -install, you can simply use the --prefix option on its -own. If you want to customize your install, you should edit the -config.layout file and use the ---enable-layout option.

- -

Modules

- -

Apache is a modular server. Only the most basic functionality is -included in the core server. Extended features are available in -various modules. During the configuration process, you must select -which modules to compile for use with your server. You can view a list of modules included in the -documentation. Those modules with a status -of "Base" are included by default and must be specifically disabled if -you do not want them. Modules with any other status must be -specifically enabled if you wish to use them.

- -

There are two ways for a module to be compiled and used with -Apache. Modules may be statically compiled, which means that -they are permanently included in the Apache binary. Alternatively, if -your operating system supports Dynamic Shared Objects (DSOs) and -autoconf can detect that support, then modules may be dynamically -compiled. DSO modules are stored separately from the Apache -binary, and may be included or excluded from the server using the -run-time configuration directives provided by mod_so. The mod_so is automatically -included in the server if any dynamic modules are included in the -compilation. If you would like to make your server capable of loading -DSOs without actually compiling any dynamic modules, you can -explicitly --enable-so.

- -

--enable-MODULE[=shared]: Compile -and include the module MODULE. The identifier -MODULE is the Module Identifier from the module documentation without the -"_module" string. To compile the module as a DSO, add the -option =shared.
--disable-MODULE: Remove the module MODULE which would otherwise be -compiled and included.
--enable-modules=MODULE-LIST: Compile and -include the modules listed in the space-separated -MODULE-LIST.
--enable-mods-shared=MODULE-LIST: Compile -and include the modules in the space-separated MODULE-LIST as -dynamically loadable (DSO) modules.

- -

The MODULE-LIST in the --enable-modules and ---enable-mods-shared options is usually a space-separated list -of module identifiers. For example, to enable mod_dav and mod_info, you -can either use

-./configure --enable-dav --enable-info -

or, equivalently,

-./configure --enable-modules="dav info" -

In addition, the special keywords all -or most can be used to add all or most of the modules -in one step. You can then remove any modules that you do not want -with the --disable-MODULE option. For example, -to include all modules as DSOs with the exception of mod_info, you can use

-./configure --enable-mods-shared=all --disable-info -

- -

In addition to the standard set of modules, Apache 2.0 also -includes a choice of Multi-Processing Modules -(MPMs). One, and only one MPM must be included in the compilation -process. The default MPMs for each platform are listed on the MPM documentation page, but can be overridden -on the configure command line. - -

--with-mpm=NAME: Choose the mpm NAME. - -

- -

Suexec

- -

Apache includes a support program called suexec which can be used to isolate user CGI -programs. However, if suexec is improperly configured, it can cause -serious security problems. Therefore, you should carefully read and -consider the suexec documentation before -implementing this feature.

- - -

Build

- -

Now you can build the various parts which form the Apache package -by simply running the command:

- -

- $ make -

- -

Please be patient here, since a base configuration takes -approximately 3 minutes to compile under a Pentium III/Linux 2.2 -system, but this will vary widely depending on your hardware and the -number of modules which you have enabled.

- - -

Install

+ + + + + + + Compiling and Installing Apache + + + + + + +

Compiling and Installing

+ +

This document covers compilation and installation of Apache + on Unix and Unix-like systems only. For compiling and + installation on Windows, see Using Apache with Microsoft + Windows. For other platforms, see the platform documentation.

+ +

Apache 2.0's configuration and installation environment has + changed completely from Apache 1.3. Apache 1.3 used a custom + set of scripts to achieve easy installation. Apache 2.0 now + uses libtool and autoconf to create an environment that looks + like many other Open Source projects.

+ +

Overview for the impatient
Requirements
Download
Extract
+ Configuring the source tree + +
- Environment Variables
- autoconf Output Options
- Pathnames
- Modules
- Suexec
+
Build
Install
Customize
Test

+ +

Overview for the + impatient

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Download	`$ lynx + http://www.apache.org/dist/httpd/httpd-2_0_NN.tar.gz` +
Extract	`$ gzip -d httpd-2_0_NN.tar.gz + $ tar xvf httpd-2_0_NN.tar`
Configure	`$ ./configure --prefix=PREFIX` +
Compile	`$ make`
Install	`$ make install`
Customize	`$ vi PREFIX/conf/httpd.conf`
Test	`$ PREFIX/bin/apachectl start` +

+ +

NN must be replaced with the current minor version + number, and PREFIX must be replaced with the + filesystem path under which the server should be installed. If + PREFIX is not specified, it defaults to + /usr/local/apache2.

+ +

Each section of the compilation and installation process is + described in more detail below, beginning with the requirements + for compiling and installing Apache HTTPD.

+ +

Requirements

+ +

The following requirements exist for building Apache:

+ +

Disk Space
+
+ Make sure you have at least 50 MB of temporary free disk + space available. After installation Apache occupies + approximately 10 MB of disk space. The actual disk space + requirements will vary considerably based on your chosen + configuration options and any third-party modules.
+
+
ANSI-C Compiler and Build System
+
+ Make sure you have an ANSI-C compiler installed. The GNU C + compiler (GCC) from the Free Software Foundation (FSF) + is recommended (version 2.7.2 is fine). If you don't have GCC + then at least make sure your vendor's compiler is ANSI + compliant. In addition, your PATH must contain + basic build tools such as make.
+
+
Accurate time keeping
+
+ Elements of the HTTP protocol are expressed as the time of + day. So, it's time to investigate setting some time + synchronization facility on your system. Usually the ntpdate + or xntpd programs are used for this purpose which are based + on the Network Time Protocol (NTP). See the Usenet newsgroup + comp.protocols.time.ntp + and the NTP + homepage for more details about NTP software and public + time servers.
+
+
Perl 5 + [OPTIONAL]
+
+ For some of the support scripts like apxs or dbmmanage (which are + written in Perl) the Perl 5 interpreter is required (versions + 5.003 and 5.004 are fine). If no such interpreter is found by + the `configure' script there is no harm. Of course, you still + can build and install Apache 2.0. Only those support scripts + cannot be used. If you have multiple Perl interpreters + installed (perhaps a Perl 4 from the vendor and a Perl 5 from + your own), then it is recommended to use the --with-perl + option (see below) to make sure the correct one is selected + by ./configure.
+
+

+ +

Download

+ +

Apache can be downloaded from the Apache Software + Foundation download site or from a nearby + mirror.

+ +

Version numbers that end in alpha indicate + early pre-test versions which may or may not work. Version + numbers ending in beta indicate more reliable + releases that still require further testing or bug fixing. If + you wish to download the best available production release of + the Apache HTTP Server, you should choose the latest version + with neither alpha nor beta in its + filename.

+ +

After downloading, especially if a mirror site is used, it + is important to verify that you have a complete and unmodified + version of the Apache HTTP Server. This can be accomplished by + testing the downloaded tarball against the PGP signature. This, + in turn, is a two step procedure. First, you must obtain the + KEYS file from the Apache distribution + site. (To assure that the KEYS file itself has + not been modified, it may be a good idea to use a file from a + previous distribution of Apache or import the keys from a + public key server.) The keys are imported into your personal + key ring using one of the following commands (depending on your + pgp version):

+ +

+ $ pgp < KEYS +

+ or + +

+ $ gpg --import KEYS +

+ +

The next step is to test the tarball against the PGP + signature, which should always be obtained from the main Apache + website. The signature file has a filename identical to the + source tarball with the addition of .asc. Then you + can check the distribution with one of the following commands + (again, depending on your pgp version):

+ +

+ $ pgp httpd-2_0_NN.tar.gz.asc +

+ or + +

+ $ gpg --verify httpd-2_0_NN.tar.gz.asc +

+ You should receive a message like
+
-

Now its time to install the package under the configured -installation PREFIX (see --prefix option above) -by running:

$ make install -

- -

If you are upgrading, the installation will not overwrite -your configuration files or documents.

- - -

Customize

- -

Next, you can customize your Apache HTTP server by editing the configuration files under -PREFIX/conf/.

- -

-$ vi PREFIX/conf/httpd.conf -

- -

Have a look at the Apache manual under docs/manual/ or http://httpd.apache.org/docs/ -for a complete reference of available configuration directives.

- -

Test

- -

Now you can start your Apache HTTP -server by immediately running:

- -

- $ PREFIX/bin/apachectl start -

- -

and then you should be able to request your first document via URL -http://localhost/. The web page you see is located under the DocumentRoot which will usually -be PREFIX/htdocs/. Then stop the server again by running:

- -

$ PREFIX/bin/apachectl stop -

- - - - - + +

+ Good signature from user "Martin Kraemer + <martin@apache.org>". +

+ +

Depending on the trust relationships contained in your key + ring, you may also receive a message saying that the + relationship between the key and the signer of the key cannot + be verified. This is not a problem if you trust the + authenticity of the KEYS file.

+ +

Extract

+ +

Extracting the source from the Apache HTTPD tarball is a + simple matter of uncompressing, and then untarring:

+ +

+ $ gzip -d httpd-2_0_NN.tar.gz + $ tar xvf httpd-2_0_NN.tar +

+ +

This will create a new directory under the current directory + containing the source code for the distribution. You should + cd into that directory before proceeding with + compiling the server.

+ +

Configuring the source + tree

+ +

The next step is to configure the Apache source tree for + your particular platform and personal requirements. This is + done using the script configure included in the + root directory of the distribution. (Developers downloading the + CVS version of the Apache source tree will need to have + autoconf and libtool installed and + will need to run buildconf before proceeding with + the next steps. This is not necessary for official + releases.)

+ +

To configure the source tree using all the default options, + simply type ./configure. To change the default + options, configure accepts a variety of variables + and command line options. Environment variables are generally + placed before the ./configure command, while other + options are placed after. The most important option here is the + location prefix where Apache is to be installed later, because + Apache has to be configured for this location to work + correctly. But there are a lot of other options available for + your pleasure.

+ +

For a short impression of what possibilities you have, here + is a typical example which compiles Apache for the installation + tree /sw/pkg/apache with a particular compiler and flags plus + the two additional modules mod_rewrite and mod_speling for + later loading through the DSO mechanism:

+ +

+ $ CC="pgcc" CFLAGS="-O2" \ + ./configure --prefix=/sw/pkg/apache \ + --enable-rewrite=shared \ + --enable-speling=shared +

+ +

When configure is run it will take several minutes to test + for the availability of features on your system and build + Makefiles which will later be used to compile the server.

+ +

The easiest way to find all of the configuration flags for + Apache is to run ./configure --help. What follows is a brief + description of most of the arguments and environment + variables.

+ +

Environment + Variables

+ +

The autoconf build process uses several environment + variables to configure the build environment. In general, these + variables change the method used to build Apache, but not the + eventual features of the server. These variables can be placed + in the environment before invoking configure, but + it is usually easier to specify them on the + configure command line as demonstrated in the + example above.

+ +

CC=...: The name of the C compiler command.
CPPFLAGS=...: Miscellaneous C preprocessor and compiler options.
CFLAGS=...: Debugging and optimization options for the C + compiler.
LDFLAGS=...: Miscellaneous options to be passed to the linker.
LIBS=...: Library location information ("-L" and "-l" options) to + pass to the linker.
INCLUDES=...: Header file search directories ("-Idir").
TARGET=... [Default: apache]: Name of the executable which will be built.
NOTEST_CPPFLAGS=...
NOTEST_CFLAGS=...
NOTEST_LDFLAGS=...
NOTEST_LIBS=...: These variables share the same function as their + non-NOTEST namesakes. However, the variables are applied to + the build process only after autoconf has performed its + feature testing. This allows the inclusion of flags which + will cause problems during feature testing, but must be used + for the final compilation.
SHLIB_PATH=...: Options which specify shared library paths for the + compiler and linker.

+ +

autoconf Output + Options

+ +

--help: Prints the usage message including all available options, + but does not actually configure anything.
--quiet: Prevents the printing of the usual "checking..." + messages.
--verbose: Prints much more information during the configuration + process, including the names of all the files examined.

+ +

Pathnames

+ +

There are currently two ways to configure the pathnames + under which Apache will install its files. First, you can + specify a directory and have Apache install itself under that + directory in its default locations.

+ +

--prefix=PREFIX [Default: + /usr/local/apache2]: Specifies the directory under which the Apache files will + be installed.

+ +

It is possible to specify that architecture-dependent files + should be placed under a different directory.

+ +

--exec-prefix=EPREFIX [Default: + PREFIX]: Specifies the directory under which + architecture-dependent files will be placed.

+ +

The second, and more flexible way to configure the install + path locations for Apache is using the + config.layout file. Using this method, it is + possible to separately specify the location for each type of + file within the Apache installation. The + config.layout file contains several example + configurations, and you can also create your own custom + configuration following the examples. The different layouts in + this file are grouped into <Layout + FOO>...</Layout> sections and referred to by + name as in FOO.

+ +

--enable-layout=LAYOUT: Use the named layout in the config.layout + file to specify the installation paths.

+ +

Presently it is not possible to mix the + --enable-layout and --prefix options. + Nor is it possible to individually specify detailed pathnames + on the configure command line. If you want just a + basic install, you can simply use the --prefix + option on its own. If you want to customize your install, you + should edit the config.layout file and use the + --enable-layout option.

+ +

Modules

+ +

Apache is a modular server. Only the most basic + functionality is included in the core server. Extended features + are available in various modules. During the configuration + process, you must select which modules to compile for use with + your server. You can view a list of modules included in + the documentation. Those modules with a status of "Base" are + included by default and must be specifically disabled if you do + not want them. Modules with any other status must be + specifically enabled if you wish to use them.

+ +

There are two ways for a module to be compiled and used with + Apache. Modules may be statically compiled, which + means that they are permanently included in the Apache binary. + Alternatively, if your operating system supports Dynamic Shared + Objects (DSOs) and autoconf can detect that support, then + modules may be dynamically compiled. DSO modules are + stored separately from the Apache binary, and may be included + or excluded from the server using the run-time configuration + directives provided by mod_so. + The mod_so is automatically included in the server if any + dynamic modules are included in the compilation. If you would + like to make your server capable of loading DSOs without + actually compiling any dynamic modules, you can explicitly + --enable-so.

+ +

--enable-MODULE[=shared]: Compile and include the module MODULE. The + identifier MODULE is the Module + Identifier from the module documentation without the + "_module" string. To compile the module as a DSO, add the + option =shared.
--disable-MODULE: Remove the module MODULE which would otherwise + be compiled and included.
--enable-modules=MODULE-LIST: Compile and include the modules listed in the + space-separated MODULE-LIST.
+ --enable-mods-shared=MODULE-LIST: Compile and include the modules in the space-separated + MODULE-LIST as dynamically loadable (DSO) + modules.

+ +

The MODULE-LIST in the + --enable-modules and + --enable-mods-shared options is usually a + space-separated list of module identifiers. For example, to + enable mod_dav and mod_info, you can either use

+ +

+ ./configure --enable-dav --enable-info +

+ +

or, equivalently,

+ +

+ ./configure --enable-modules="dav info" +

+ +

In addition, the special keywords all or + most can be used to add all or most of the modules + in one step. You can then remove any modules that you do not + want with the --disable-MODULE option. + For example, to include all modules as DSOs with the exception + of mod_info, you can use

+ +

+ ./configure --enable-mods-shared=all + --disable-info +

+ +

In addition to the standard set of modules, Apache 2.0 also + includes a choice of Multi-Processing + Modules (MPMs). One, and only one MPM must be included in + the compilation process. The default MPMs for each platform are + listed on the MPM documentation page, + but can be overridden on the configure command + line.

+ +

--with-mpm=NAME: Choose the mpm NAME.

+ +

Suexec

+ +

Apache includes a support program called suexec which can be used to isolate user + CGI programs. However, if suexec is improperly configured, it + can cause serious security problems. Therefore, you should + carefully read and consider the suexec + documentation before implementing this feature.

+ +

Build

+ +

Now you can build the various parts which form the Apache + package by simply running the command:

+ +

+ $ make +

+ +

Please be patient here, since a base configuration takes + approximately 3 minutes to compile under a Pentium III/Linux + 2.2 system, but this will vary widely depending on your + hardware and the number of modules which you have enabled.

+ +

Install

+ +

Now its time to install the package under the configured + installation PREFIX (see --prefix option + above) by running:

+ +

+ $ make install +

+ +

If you are upgrading, the installation will not overwrite + your configuration files or documents.

+ +

Customize

+ +

Next, you can customize your Apache HTTP server by editing + the configuration files under + PREFIX/conf/.

+ +

+ $ vi PREFIX/conf/httpd.conf +

+ +

Have a look at the Apache manual under docs/manual/ or http://httpd.apache.org/docs/ + for a complete reference of available configuration directives.

+ +

Test

+ +

Now you can start your Apache + HTTP server by immediately running:

+ +

+ $ PREFIX/bin/apachectl start +

+ +

and then you should be able to request your first document + via URL http://localhost/. The web page you see is located + under the DocumentRoot + which will usually be PREFIX/htdocs/. + Then stop the server again by + running:

+ +

+ $ PREFIX/bin/apachectl stop +

+ + + + diff --git a/docs/manual/install.html.en b/docs/manual/install.html.en index 8d8f4178af9..b9103318d1f 100644 --- a/docs/manual/install.html.en +++ b/docs/manual/install.html.en @@ -1,532 +1,634 @@ - - - -Compiling and Installing Apache - - - - - - -

Compiling and Installing

- - -

- -

Overview for the impatient
Requirements
Download
Extract
Configuring the source tree -
- Environment Variables
- autoconf Output Options
- Pathnames
- Modules
- Suexec
Build
Install
Customize
Test

- -

Overview for the impatient

- - - - - - - - - - - - - - - - - - - - - - - -

Download	`$ lynx http://www.apache.org/dist/httpd/httpd-2_0_NN.tar.gz -`
Extract	`$ gzip -d httpd-2_0_NN.tar.gz -$ tar xvf httpd-2_0_NN.tar -`
Configure	`$ ./configure --prefix=PREFIX -`
Compile	`$ make -`
Install	`$ make install -`
Customize	`$ vi PREFIX/conf/httpd.conf -`
Test	`$ PREFIX/bin/apachectl start -`

- -

Each section of the compilation and installation process is -described in more detail below, beginning with the requirements -for compiling and installing Apache HTTPD.

- -

Requirements

- -

The following requirements exist for building Apache:

- -

Disk Space

Make sure you have at least 50 MB of temporary -free disk space available. After installation Apache occupies -approximately 10 MB of disk space. The actual disk space requirements -will vary considerably based on your chosen configuration options and -any third-party modules.
ANSI-C Compiler and Build System

Make sure you have an -ANSI-C compiler installed. The GNU C compiler -(GCC) from the Free Software -Foundation (FSF) is recommended (version 2.7.2 is fine). If you -don't have GCC then at least make sure your vendor's compiler is ANSI -compliant. In addition, your PATH must contain basic -build tools such as make.
Accurate time keeping

Elements of the HTTP protocol are -expressed as the time of day. So, it's time to investigate setting -some time synchronization facility on your system. Usually the ntpdate -or xntpd programs are used for this purpose which are based on the -Network Time Protocol (NTP). See the Usenet newsgroup comp.protocols.time.ntp and -the NTP homepage for more -details about NTP software and public time servers.
Perl 5 [OPTIONAL]

For -some of the support scripts like apxs -or dbmmanage (which are written -in Perl) the Perl 5 interpreter is required (versions 5.003 and 5.004 -are fine). If no such interpreter is found by the `configure' script -there is no harm. Of course, you still can build and install Apache -2.0. Only those support scripts cannot be used. If you have multiple -Perl interpreters installed (perhaps a Perl 4 from the vendor and a -Perl 5 from your own), then it is recommended to use the --with-perl -option (see below) to make sure the correct one is selected by -./configure.

- -

Download

- -

Apache can be downloaded from the Apache Software Foundation -download site or from a nearby mirror.

- -

-$ pgp < KEYS -

-or -

-$ gpg --import KEYS -

- -

-$ pgp httpd-2_0_NN.tar.gz.asc -

-or -

-$ gpg --verify httpd-2_0_NN.tar.gz.asc -

You should receive a message like

-Good signature from user "Martin Kraemer <martin@apache.org>". -

- -

Extract

- -

Extracting the source from the Apache HTTPD tarball is a simple -matter of uncompressing, and then untarring:

- -

-$ gzip -d httpd-2_0_NN.tar.gz -$ tar xvf httpd-2_0_NN.tar -

- -

This will create a new directory under the current directory -containing the source code for the distribution. You should -cd into that directory before proceeding with -compiling the server.

- -

Configuring the source tree

- -

- $ CC="pgcc" CFLAGS="-O2" \ - ./configure --prefix=/sw/pkg/apache \ - --enable-rewrite=shared \ - --enable-speling=shared -

- -

When configure is run it will take several minutes to test for -the availability of features on your system and build Makefiles -which will later be used to compile the server.

- -

The easiest way to find all of the configuration flags for Apache -is to run ./configure --help. What follows is a brief description -of most of the arguments and environment variables.

- -

Environment Variables

- -

CC=...: The name of the C compiler command.
CPPFLAGS=...: Miscellaneous C preprocessor -and compiler options.
CFLAGS=...: Debugging and optimization options for the C compiler.
LDFLAGS=...: Miscellaneous options to be passed to the linker.
LIBS=...: Library location information ("-L" and "-l" options) -to pass to the linker.
INCLUDES=...: Header file search directories ("-Idir").
TARGET=... [Default: apache]: Name of the executable which will be built.
NOTEST_CPPFLAGS=...
NOTEST_CFLAGS=...
NOTEST_LDFLAGS=...
NOTEST_LIBS=...: These variables share the same function as their non-NOTEST namesakes. -However, the variables are applied to the build process only after -autoconf has performed its feature testing. This allows the inclusion of -flags which will cause problems during feature testing, but must be used -for the final compilation.
SHLIB_PATH=...: Options which specify shared library paths for the compiler and -linker.

- -

autoconf Output Options

- -

--help: Prints the usage message including all available options, but -does not actually configure anything.
--quiet: Prevents the printing of the usual "checking..." messages.
--verbose: Prints much more information during the configuration process, -including the names of all the files examined.

- -

Pathnames

- -

--prefix=PREFIX [Default: -/usr/local/apache2]: Specifies the directory under which the Apache files will be -installed.

- -

It is possible to specify that architecture-dependent files should -be placed under a different directory.

- -

--exec-prefix=EPREFIX [Default: -PREFIX]: Specifies the directory under which architecture-dependent files -will be placed.

- -

--enable-layout=LAYOUT: Use the named layout in the config.layout file -to specify the installation paths.

- -

Modules

- -

--enable-MODULE[=shared]: Compile -and include the module MODULE. The identifier -MODULE is the Module Identifier from the module documentation without the -"_module" string. To compile the module as a DSO, add the -option =shared.
--disable-MODULE: Remove the module MODULE which would otherwise be -compiled and included.
--enable-modules=MODULE-LIST: Compile and -include the modules listed in the space-separated -MODULE-LIST.
--enable-mods-shared=MODULE-LIST: Compile -and include the modules in the space-separated MODULE-LIST as -dynamically loadable (DSO) modules.

- -

-./configure --enable-dav --enable-info -

or, equivalently,

-./configure --enable-modules="dav info" -

-./configure --enable-mods-shared=all --disable-info -

- -

--with-mpm=NAME: Choose the mpm NAME. - -

- -

Suexec

- -

- - -

Build

- -

Now you can build the various parts which form the Apache package -by simply running the command:

- -

- $ make -

- -

- - -

Install

+ + + + + + + Compiling and Installing Apache + + + + + + +

Compiling and Installing

+ +

Overview for the impatient
Requirements
Download
Extract
+ Configuring the source tree + +
- Environment Variables
- autoconf Output Options
- Pathnames
- Modules
- Suexec
+
Build
Install
Customize
Test

+ +

Overview for the + impatient

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Download	`$ lynx + http://www.apache.org/dist/httpd/httpd-2_0_NN.tar.gz` +
Extract	`$ gzip -d httpd-2_0_NN.tar.gz + $ tar xvf httpd-2_0_NN.tar`
Configure	`$ ./configure --prefix=PREFIX` +
Compile	`$ make`
Install	`$ make install`
Customize	`$ vi PREFIX/conf/httpd.conf`
Test	`$ PREFIX/bin/apachectl start` +

+ +

Each section of the compilation and installation process is + described in more detail below, beginning with the requirements + for compiling and installing Apache HTTPD.

+ +

Requirements

+ +

The following requirements exist for building Apache:

+ +

Disk Space
+
+ Make sure you have at least 50 MB of temporary free disk + space available. After installation Apache occupies + approximately 10 MB of disk space. The actual disk space + requirements will vary considerably based on your chosen + configuration options and any third-party modules.
+
+
ANSI-C Compiler and Build System
+
+ Make sure you have an ANSI-C compiler installed. The GNU C + compiler (GCC) from the Free Software Foundation (FSF) + is recommended (version 2.7.2 is fine). If you don't have GCC + then at least make sure your vendor's compiler is ANSI + compliant. In addition, your PATH must contain + basic build tools such as make.
+
+
Accurate time keeping
+
+ Elements of the HTTP protocol are expressed as the time of + day. So, it's time to investigate setting some time + synchronization facility on your system. Usually the ntpdate + or xntpd programs are used for this purpose which are based + on the Network Time Protocol (NTP). See the Usenet newsgroup + comp.protocols.time.ntp + and the NTP + homepage for more details about NTP software and public + time servers.
+
+
Perl 5 + [OPTIONAL]
+
+ For some of the support scripts like apxs or dbmmanage (which are + written in Perl) the Perl 5 interpreter is required (versions + 5.003 and 5.004 are fine). If no such interpreter is found by + the `configure' script there is no harm. Of course, you still + can build and install Apache 2.0. Only those support scripts + cannot be used. If you have multiple Perl interpreters + installed (perhaps a Perl 4 from the vendor and a Perl 5 from + your own), then it is recommended to use the --with-perl + option (see below) to make sure the correct one is selected + by ./configure.
+
+

+ +

Download

+ +

Apache can be downloaded from the Apache Software + Foundation download site or from a nearby + mirror.

+ +

+ $ pgp < KEYS +

+ or + +

+ $ gpg --import KEYS +

+ +

+ $ pgp httpd-2_0_NN.tar.gz.asc +

+ or + +

+ $ gpg --verify httpd-2_0_NN.tar.gz.asc +

+ You should receive a message like
+
-

Now its time to install the package under the configured -installation PREFIX (see --prefix option above) -by running:

$ make install -

- -

If you are upgrading, the installation will not overwrite -your configuration files or documents.

- - -

Customize

- -

Next, you can customize your Apache HTTP server by editing the configuration files under -PREFIX/conf/.

- -

-$ vi PREFIX/conf/httpd.conf -

- -

Have a look at the Apache manual under docs/manual/ or http://httpd.apache.org/docs/ -for a complete reference of available configuration directives.

- -

Test

- -

Now you can start your Apache HTTP -server by immediately running:

- -

- $ PREFIX/bin/apachectl start -

- -

$ PREFIX/bin/apachectl stop -

- - - - - + +

+ Good signature from user "Martin Kraemer + <martin@apache.org>". +

+ +

Extract

+ +

Extracting the source from the Apache HTTPD tarball is a + simple matter of uncompressing, and then untarring:

+ +

+ $ gzip -d httpd-2_0_NN.tar.gz + $ tar xvf httpd-2_0_NN.tar +

+ +

This will create a new directory under the current directory + containing the source code for the distribution. You should + cd into that directory before proceeding with + compiling the server.

+ +

Configuring the source + tree

+ +

+ $ CC="pgcc" CFLAGS="-O2" \ + ./configure --prefix=/sw/pkg/apache \ + --enable-rewrite=shared \ + --enable-speling=shared +

+ +

When configure is run it will take several minutes to test + for the availability of features on your system and build + Makefiles which will later be used to compile the server.

+ +

The easiest way to find all of the configuration flags for + Apache is to run ./configure --help. What follows is a brief + description of most of the arguments and environment + variables.

+ +

Environment + Variables

+ +

CC=...: The name of the C compiler command.
CPPFLAGS=...: Miscellaneous C preprocessor and compiler options.
CFLAGS=...: Debugging and optimization options for the C + compiler.
LDFLAGS=...: Miscellaneous options to be passed to the linker.
LIBS=...: Library location information ("-L" and "-l" options) to + pass to the linker.
INCLUDES=...: Header file search directories ("-Idir").
TARGET=... [Default: apache]: Name of the executable which will be built.
NOTEST_CPPFLAGS=...
NOTEST_CFLAGS=...
NOTEST_LDFLAGS=...
NOTEST_LIBS=...: These variables share the same function as their + non-NOTEST namesakes. However, the variables are applied to + the build process only after autoconf has performed its + feature testing. This allows the inclusion of flags which + will cause problems during feature testing, but must be used + for the final compilation.
SHLIB_PATH=...: Options which specify shared library paths for the + compiler and linker.

+ +

autoconf Output + Options

+ +

--help: Prints the usage message including all available options, + but does not actually configure anything.
--quiet: Prevents the printing of the usual "checking..." + messages.
--verbose: Prints much more information during the configuration + process, including the names of all the files examined.

+ +

Pathnames

+ +

--prefix=PREFIX [Default: + /usr/local/apache2]: Specifies the directory under which the Apache files will + be installed.

+ +

It is possible to specify that architecture-dependent files + should be placed under a different directory.

+ +

--exec-prefix=EPREFIX [Default: + PREFIX]: Specifies the directory under which + architecture-dependent files will be placed.

+ +

--enable-layout=LAYOUT: Use the named layout in the config.layout + file to specify the installation paths.

+ +

Modules

+ +

--enable-MODULE[=shared]: Compile and include the module MODULE. The + identifier MODULE is the Module + Identifier from the module documentation without the + "_module" string. To compile the module as a DSO, add the + option =shared.
--disable-MODULE: Remove the module MODULE which would otherwise + be compiled and included.
--enable-modules=MODULE-LIST: Compile and include the modules listed in the + space-separated MODULE-LIST.
+ --enable-mods-shared=MODULE-LIST: Compile and include the modules in the space-separated + MODULE-LIST as dynamically loadable (DSO) + modules.

+ +

+ ./configure --enable-dav --enable-info +

+ +

or, equivalently,

+ +

+ ./configure --enable-modules="dav info" +

+ +

+ ./configure --enable-mods-shared=all + --disable-info +

+ +

--with-mpm=NAME: Choose the mpm NAME.

+ +

Suexec

+ +

Build

+ +

Now you can build the various parts which form the Apache + package by simply running the command:

+ +

+ $ make +

+ +

Install

+ +

Now its time to install the package under the configured + installation PREFIX (see --prefix option + above) by running:

+ +

+ $ make install +

+ +

If you are upgrading, the installation will not overwrite + your configuration files or documents.

+ +

Customize

+ +

Next, you can customize your Apache HTTP server by editing + the configuration files under + PREFIX/conf/.

+ +

+ $ vi PREFIX/conf/httpd.conf +

+ +

Have a look at the Apache manual under docs/manual/ or http://httpd.apache.org/docs/ + for a complete reference of available configuration directives.

+ +

Test

+ +

Now you can start your Apache + HTTP server by immediately running:

+ +

+ $ PREFIX/bin/apachectl start +

+ +

+ $ PREFIX/bin/apachectl stop +

+ + + + diff --git a/docs/manual/invoking.html b/docs/manual/invoking.html index c8c6e3ba4c7..1957e59ed76 100644 --- a/docs/manual/invoking.html +++ b/docs/manual/invoking.html @@ -1,118 +1,139 @@ - - - -Starting Apache - - - - - -

Starting Apache

- - -

Starting Apache on Windows
Starting Apache on Unix -
-

- -

Starting Apache On Windows

- -

On Windows, Apache is normally run as a service on Windows NT, or -as a console application on Windows 95. For details, see running Apache for Windows.

- -

Starting Apache on Unix

- -

On Unix, the httpd program is run -as a daemon which executes continuously in the background to handle -requests.

- -

If the Port specified in the -configuration file is the default of 80 (or any other port below -1024), then it is necessary to have root privileges in order to start -apache, so that it can bind to this privileged port. Once the server -has started and performed a few preliminary activities such as opening -its log files, it will launch several child processes which -do the work of listening for and answering requests from clients. The -main httpd process continues to run as the root user, but -the child processes run as a less privileged user. This is controlled -by the selected Multi-Processing Module.

- -

The first thing that httpd does when it is invoked is -to locate and read the configuration -file httpd.conf. The location of this file is set at -compile-time, but it is possible to specify its location at run time -using the -f command-line option as in

/usr/local/apache/bin/httpd -f -/usr/local/apache/conf/httpd.conf

- -

As an alternative to invoking the httpd binary -directly, a shell script called apachectl is provided which can be -used to control the daemon process with simple commands such as -apachectl start and apachectl stop.

- -

If all goes well during startup, the server will detach from the -terminal and the command prompt will return almost immediately. -This indicates that the server is up and running. You can then -use your browser to connect to the server and view the test -page in the DocumentRoot -directory and the local copy of the documentation linked from -that page.

- -

Errors During Start-up

- -

If Apache suffers a fatal problem during startup, it will write a -message describing the problem either to the console or to the ErrorLog before exiting. One of the -most common error messages is "Unable to bind to Port -...". This message is usually caused by either:

Trying to start the server on a privileged port when not -logged in as the root user; or
Trying to start the server when there is another instance -of Apache or some other web server already bound to the same Port.

For further trouble-shooting instructions, consult the Apache FAQ.

- -

Starting at Boot-Time

- -

If you want your server to continue running after a system reboot, -you should add a call to httpd or apachectl -to your system startup files (typically rc.local or a -file in an rc.N directory). This will start Apache as -root. Before doing this ensure that your server is properly configured -for security and access restrictions. The apachectl -script is designed so that it can often be linked directly as an init -script, but be sure to check the exact requirements of your system.

- -

Additional Information

- -

Additional information about the command-line options of httpd and apachectl as well as other support -programs included with the server is available on the Server and Supporting Programs page. There is -also documentation on all the modules included with -the Apache distribution and the directives that they provide.

- - - - - + + + + + + + Starting Apache + + + + + + +

Starting Apache

+ +

Starting Apache on Windows
+ Starting Apache on Unix + +
- Errors During Start-up
- Starting at Boot-Time
- Additional Information
+

+ +

Starting Apache On + Windows

+ +

On Windows, Apache is normally run as a service on Windows + NT, or as a console application on Windows 95. For details, see + running Apache for + Windows.

+ +

Starting Apache on Unix

+ +

On Unix, the httpd program + is run as a daemon which executes continuously in the + background to handle requests.

+ +

If the Port specified in + the configuration file is the default of 80 (or any other port + below 1024), then it is necessary to have root privileges in + order to start apache, so that it can bind to this privileged + port. Once the server has started and performed a few + preliminary activities such as opening its log files, it will + launch several child processes which do the work of + listening for and answering requests from clients. The main + httpd process continues to run as the root user, + but the child processes run as a less privileged user. This is + controlled by the selected Multi-Processing + Module.

+ +

The first thing that httpd does when it is + invoked is to locate and read the configuration file + httpd.conf. The location of this file is set at + compile-time, but it is possible to specify its location at run + time using the -f command-line option as in

+ +

+ /usr/local/apache/bin/httpd -f + /usr/local/apache/conf/httpd.conf +

+ +

As an alternative to invoking the httpd binary + directly, a shell script called apachectl is provided which + can be used to control the daemon process with simple commands + such as apachectl start and apachectl + stop.

+ +

If all goes well during startup, the server will detach from + the terminal and the command prompt will return almost + immediately. This indicates that the server is up and running. + You can then use your browser to connect to the server and view + the test page in the DocumentRoot directory + and the local copy of the documentation linked from that + page.

+ +

Errors During + Start-up

+ +

If Apache suffers a fatal problem during startup, it will + write a message describing the problem either to the console or + to the ErrorLog before + exiting. One of the most common error messages is "Unable + to bind to Port ...". This message is usually caused by + either:

+ +

Trying to start the server on a privileged port when not + logged in as the root user; or
Trying to start the server when there is another instance + of Apache or some other web server already bound to the same + Port.

+ +

For further trouble-shooting instructions, consult the + Apache FAQ.

+ +

Starting at Boot-Time

+ +

If you want your server to continue running after a system + reboot, you should add a call to httpd or + apachectl to your system startup files (typically + rc.local or a file in an rc.N + directory). This will start Apache as root. Before doing this + ensure that your server is properly configured for security and + access restrictions. The apachectl script is + designed so that it can often be linked directly as an init + script, but be sure to check the exact requirements of your + system.

+ +

Additional Information

+ +

Additional information about the command-line options of httpd and apachectl as well as other + support programs included with the server is available on the + Server and Supporting Programs page. + There is also documentation on all the modules included with the Apache distribution + and the directives that they + provide.

+ + + + diff --git a/docs/manual/invoking.html.en b/docs/manual/invoking.html.en index c8c6e3ba4c7..1957e59ed76 100644 --- a/docs/manual/invoking.html.en +++ b/docs/manual/invoking.html.en @@ -1,118 +1,139 @@ - - - -Starting Apache - - - - - -

Starting Apache

- - -

Starting Apache on Windows
Starting Apache on Unix -
-

- -

Starting Apache On Windows

- -

On Windows, Apache is normally run as a service on Windows NT, or -as a console application on Windows 95. For details, see running Apache for Windows.

- -

Starting Apache on Unix

- -

On Unix, the httpd program is run -as a daemon which executes continuously in the background to handle -requests.

- -

/usr/local/apache/bin/httpd -f -/usr/local/apache/conf/httpd.conf

- -

Errors During Start-up

- -

Trying to start the server on a privileged port when not -logged in as the root user; or
Trying to start the server when there is another instance -of Apache or some other web server already bound to the same Port.

For further trouble-shooting instructions, consult the Apache FAQ.

- -

Starting at Boot-Time

- -

Additional Information

- -

- - - - - + + + + + + + Starting Apache + + + + + + +

Starting Apache

+ +

Starting Apache on Windows
+ Starting Apache on Unix + +
- Errors During Start-up
- Starting at Boot-Time
- Additional Information
+

+ +

Starting Apache On + Windows

+ +

On Windows, Apache is normally run as a service on Windows + NT, or as a console application on Windows 95. For details, see + running Apache for + Windows.

+ +

Starting Apache on Unix

+ +

On Unix, the httpd program + is run as a daemon which executes continuously in the + background to handle requests.

+ +

+ /usr/local/apache/bin/httpd -f + /usr/local/apache/conf/httpd.conf +

+ +

Errors During + Start-up

+ +

Trying to start the server on a privileged port when not + logged in as the root user; or
Trying to start the server when there is another instance + of Apache or some other web server already bound to the same + Port.

+ +

For further trouble-shooting instructions, consult the + Apache FAQ.

+ +

Starting at Boot-Time

+ +

Additional Information

+ +

+ + + + diff --git a/docs/manual/logs.html b/docs/manual/logs.html index f83f474bf28..a45a96ef16d 100644 --- a/docs/manual/logs.html +++ b/docs/manual/logs.html @@ -1,582 +1,667 @@ - - - -Log Files - Apache HTTP Server - - - - - -

Log Files

- -

In order to effectively manage a web server, it is necessary to get -feedback about the activity and performance of the server as well as -any problems that may be occuring. The Apache HTTP Server provides -very comprehensive and flexible logging capabilities. This document -describes how to configure its logging capabilities, and how to -understand what the logs contain.

- -

Security Warning
Error Log
Access Log -
Log Rotation
Piped Logs
VirtualHosts -
Other Log Files -
- PID File
- Script Log
- Rewrite Log

- -

Security Warning

- -

Anyone who can write to the directory where Apache is writing a -log file can almost certainly gain access to the uid that the server is -started as, which is normally root. Do NOT give people write -access to the directory the logs are stored in without being aware of -the consequences; see the security tips -document for details.

- -

In addition, log files may contain information supplied directly -by the client, without escaping. Therefore, it is possible for -malicious clients to insert control-characters in the log files, so -care must be taken in dealing with raw logs.

- -

Error Log

- - -

-Related Directives

- -ErrorLog
-LogLevel -

- -

The server error log, whose name and location is set by the ErrorLog directive, is the most -important log file. This is the place where Apache httpd will send -diagnostic information and record any errors that it encounters in -processing requests. It is the first place to look when a problem -occurs with starting the server or with the operation of the server, -since it will often contain details of what went wrong and how to fix -it.

- -

The error log is usually written to a file (typically -error_log on unix systems and error.log on -Windows and OS/2). On unix systems it is also possible to have the -server send errors to syslog or pipe -them to a program.

- -

The format of the error log is relatively free-form and -descriptive. But there is certain information that is contained -in most error log entries. For example, here is a typical message.

- -

-[Wed Oct 11 14:32:52 2000] [error] [client 127.0.0.1] client denied by server configuration: /export/home/live/ap/htdocs/test -

- -

The first item in the log entry is the date and time of the -message. The second entry lists the severity of the error being -reported. The LogLevel directive -is used to control the types of errors that are sent to the error log -by restricting the severity level. The third entry gives the IP -address of the client that generated the error. Beyond that is the -message itself, which in this case indicates that the server has been -configured to deny the client access. The server reports the -file-system path (as opposed to the web path) of the requested -document.

- -

A very wide variety of different messages can appear in the error -log. Most look similar to the example above. The error log will also -contain debugging output from CGI scripts. Any information written to -stderr by a CGI script will be copied directly to the -error log.

- -

It is not possible to customize the error log by adding or removing -information. However, error log entries dealing with particular -requests have corresponding entries in the access -log. For example, the above example entry corresponds to an -access log entry with status code 403. Since it is possible to -customize the access log, you can obtain more information about error -conditions using that log file.

- -

During testing, it is often useful to continuously monitor the -error log for any problems. On unix systems, you can accomplish this -using:

-tail -f error_log -

- -

Access Log

- -

-Related Modules

- -mod_log_config
- -

-Related Directives

- -CustomLog
-LogFormat
-SetEnvIf - -

- -

The server access log records all requests processed by the server. -The location and content of the access log are controlled -by the CustomLog -directive. The LogFormat directive can -be used to simplify the selection of the contents of the logs. -This section describes how to configure the server to record -information in the access log.

- -

Of course, storing the information in the access log is only the -start of log management. The next step is to analyze this information -to produce useful statistics. Log analysis in general is beyond the -scope of this document, and not really part of the job of the -web server itself. For more information about this topic, and for -applications which perform log analysis, check the Open Directory or Yahoo.

- -

Various versions of Apache httpd have used other modules and -directives to control access logging, including mod_log_referer, -mod_log_agent, and the TransferLog directive. The -CustomLog directive now subsumes the functionality of all -the older directives.

- -

The format of the access log is highly configurable. The format is -specified using a format -string that looks much like a C-style printf(1) format string. -Some examples are presented in the next sections. For a complete list -of the possible contents of the format string, see the mod_log_config documentation.

- -

Common Log Format

- -

A typical configuration for the access log might look -as follows.

- -

-LogFormat "%h %l %u %t \"%r\" %>s %b" common -CustomLog logs/access_log common -

- -

This defines the nickname common and -associates it with a particular log format string. The format string -consists of percent directives, each of which tell the server to log a -particular piece of information. Literal characters may also be -placed in the format string and will be copied directly into the log -output. The quote character (") must be escaped by -placing a back-slash before it to prevent it from being interpreted as -the end of the format string. The format string may also contain the -special control characters "\n" for new-line and -"\t" for tab.

- -

The CustomLog directive sets up a new log file using -the defined nickname. The filename for the access log is -relative to the ServerRoot -unless it begins with a slash.

- -

The above configuration will write log entries in a format known as -the Common Log Format (CLF). This standard format can be produced by -many different web servers and read by many log analysis programs. -The log file entries produced in CLF will look something like -this:

- -

-127.0.0.1 - frank [10/Oct/2000:13:55:36 -0700] "GET /apache_pb.gif HTTP/1.0" 200 2326 -

- -

Each part of this log entry is described below.

- -

127.0.0.1 (%h): This is the IP -address of the client (remote host) which made the request to the -server. If HostNameLookups is set to -On, then the server will try to determine the hostname -and log it in place of the IP address. However, this configuration is -not recommended since it can significantly slow the server. Instead, -it is best to use a log post-processor such as logresolve to determine the -hostnames. The IP address reported here is not necessarily the -address of the machine at which the user is sitting. If a proxy -server exists between the user and the server, this address will be -the address of the proxy, rather than the originating machine.
- (%l): The "hyphen" in the -output indicates that the requested piece of information is not -available. In this case, the information that is not available is the -RFC 1413 identity of the client determined by identd on -the clients machine. This information is highly unreliable and should -almost never be used except on tightly controlled internal networks. -Apache httpd will not even attempt to determine this information -unless IdentityCheck is set -to On.
frank (%u): This is the userid -of the person requesting the document as determined by HTTP -authentication. The same value is typically provided to CGI scripts -in the REMOTE_USER environment variable. If the status -code for the request (see below) is 401, then this value should not be -trusted because the user is not yet authenticated. If the document is -not password protected, this entry will be "-" just like -the previous one.
[10/Oct/2000:13:55:36 -0700] (%t): The time that the server finished processing the request. The -format is: -
[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
-It is possible to have the time displayed in another format -by specifying %{format}t in the log format string, where -format is as in strftime(3) from the C -standard library. -
"GET /apache_pb.gif HTTP/1.0" -(\"%r\"): The request line from the client is -given in double quotes. The request line contains a great deal of -useful information. First, the method used by the client is -GET. Second, the client requested the resource -/apache_pb.gif, and third, the client used the protocol -HTTP/1.0. It is also possible to log one or more -parts of the request line independently. For example, the format -string "%m %U%q %H" will log the method, path, -query-string, and protocol, resulting in exactly the same output as -"%r".
200 (%>s): This is the status -code that the server sends back to the client. This information is -very valuable, because it reveals whether the request resulted in a -successful response (codes beginning in 2), a redirection (codes -beginning in 3), an error caused by the client (codes beginning in 4), -or an error in the server (codes beginning in 5). -The full list of possible status codes can be -found in the HTTP specification (RFC2616 section 10).
2326 (%b) -: The last entry indicates the size of the object returned to -the client, not including the response headers. If no content -was returned to the client, this value will be "-". -To log "0" for no content, use %B -instead.

- -

Combined Log Format

- -

Another commonly used format string is called the -Combined Log Format. It can be used as follows.

- -

-LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\"" combined -CustomLog log/acces_log combined -

- -

This format is exactly the same as the Common Log Format, with the -addition of two more fields. Each of the additional fields uses the -percent-directive %{header}i, where -header can be any HTTP request header. The access log under -this format will look like:

- -

-127.0.0.1 - frank [10/Oct/2000:13:55:36 -0700] "GET /apache_pb.gif HTTP/1.0" 200 2326 "http://www.example.com/start.html" "Mozilla/4.08 [en] (Win98; I ;Nav)" -

- -

The additional fields are:

- -

"http://www.example.com/start.html" -(\"%{Referer}i\"): The "Referer" (sic) HTTP -request header. This gives the site that the client reports having -been referred from. (This should be the page that links to or includes -/apache_pb.gif). - -
"Mozilla/4.08 [en] (Win98; I ;Nav)" -(\"%{User-agent}i\"): The User-Agent HTTP request -header. This is the identifying information that the client browser -reports about itself.

- -

Multiple Access Logs

- -

Multiple access logs can be created simply by specifying multiple -CustomLog directives in the configuration file. For -example, the following directives will create three access logs. The -first contains the basic CLF information, while the second and third -contain referer and browser information. The last two -CustomLog lines show how to mimic the effects of the -ReferLog and AgentLog directives.

- -

-LogFormat "%h %l %u %t \"%r\" %>s %b" common -CustomLog logs/access_log common -CustomLog logs/referer_log "%{Referer}i -> %U" -CustomLog logs/agent_log "%{User-agent}i" -

- -

This example also shows that it is not necessary to define a -nickname with the LogFormat directive. Instead, the log -format can be specified directly in the CustomLog -directive.

- -

Conditional Logging

- -

There are times when it is convenient to exclude certain entries -from the access logs based on characteristics of the client request. -This is easily accomplished with the help of environment variables. First, an environment -variable must be set to indicate that the request meets certain -conditions. This is usually accomplished with SetEnvIf. Then the -env= clause of the CustomLog directive is -used to include or exclude requests where the environment variable is -set. Some examples:

- -

-# Mark requests from the loop-back interface -SetEnvIf Remote_Addr "127\.0\.0\.1" dontlog -# Mark requests for the robots.txt file -SetEnvIf Request_URI "^/robots\.txt$" dontlog -# Log what remains -CustomLog logs/access_log common env=!dontlog -

- -

As another example, consider logging requests from english-speakers -to one log file, and non-english speakers to a different log file.

- -

-SetEnvIf Accept-Language "en" english -CustomLog logs/english_log common env=english -CustomLog logs/non_english_log common env=!english -

- -

Although we have just shown that conditional logging is very -powerful and flexibly, it is not the only way to control the contents -of the logs. Log files are more useful when they contain a complete -record of server activity. It is often easier to simply post-process -the log files to remove requests that you do not want to consider.

- -

Log Rotation

- -

On even a moderately busy server, the quantity of information -stored in the log files is very large. The access log file typically -grows 1 MB or more per 10,000 requests. It will consequently be -necessary to periodically rotate the log files by moving or deleting -the existing logs. This cannot be done while the server is running, -because Apache will continue writing to the old log file as long as it -holds the file open. Instead, the server must be restarted after the log files are moved or -deleted so that it will open new log files.

- -

By using a graceful restart, the server can be instructed -to open new log files without losing any existing or pending -connections from clients. However, in order to accomplish this, the -server must continue to write to the old log files while it finishes -serving old requests. It is therefore necessary to wait for some time -after the restart before doing any processing on the log files. A -typical scenario that simply rotates the logs and compresses the old -logs to save space is:

- -

-mv access_log access_log.old -mv error_log error_log.old -apachectl graceful -sleep 600 -gzip access_log.old error_log.old -

- -

Another way to perform log rotation is using piped -logs as discussed in the next section.

- -

Piped Logs

- -

Apache httpd is capable of writing error and access log files -through a pipe to another process, rather than directly to a file. -This capability dramatically increases the flexibility of logging, -without adding code to the main server. In order to write logs to a -pipe, simply replace the filename with the pipe character -"|", followed by the name of the executable which should -accept log entries on its standard input. Apache will start the -piped-log process when the server starts, and will restart it if it -crashes while the server is running. (This last feature is why we can -refer to this technique as "reliable piped logging".)

- -

Piped log processes are spawned by the parent Apache httpd process, -and inherit the userid of that process. This means that piped log -programs usually run as root. It is therefore very important to keep -the programs simple and secure.

- -

Some simple examples using piped logs:

- -

-# compressed logs -CustomLog "|/usr/bin/gzip -c >> /var/log/access_log.gz" common -# almost-real-time name resolution -CustomLog "|/usr/local/apache/bin/logresolve >> /var/log/access_log" common -

- -

Notice that quotes are used to enclose the entire command -that will be called for the pipe. Although these examples are -for the access log, the same technique can be used for the -error log.

- -

One important use of piped logs is to allow log rotation without -having to restart the server. The Apache HTTP Server includes a -simple program called rotatelogs for this purpose. For -example, to rotate the logs every 24 hours, you can use:

- -

-CustomLog "|/usr/local/apache/bin/rotatelogs /var/log/access_log 86400" common -

- -

A similar, but much more flexible log rotation program -called cronolog -is available at an external site.

- -

As with conditional logging, piped logs are a very powerful tool, -but they should not be used where a simpler solution like -off-line post-processing is available.

- -

Virtual Hosts

- -

When running a server with many virtual -hosts, there are several options for dealing with log files. -First, it is possible to use logs exactly as in a single-host server. -Simply by placing the logging directives outside the -<VirtualHost> sections in the main server context, -it is possible to log all requests in the same access log and error -log. This technique does not allow for easy collection of statistics -on individual virtual hosts.

- -

If CustomLog or ErrorLog directives are -placed inside a <VirtualHost> section, all requests -or errors for that virtual host will be logged only to the specified -file. Any virtual host which does not have logging directives will -still have its requests sent to the main server logs. This technique -is very useful for a small number of virtual hosts, but if the number -of hosts is very large, it can be complicated to manage. In addition, -it can often create problems with insufficient file descriptors.

- -

For the access log, there is a very good compromise. By adding -information on the virtual host to the log format string, -it is possible to log all hosts to the same log, and later -split the log into individual files. For example, consider the -following directives.

- -

-LogFormat "%v %l %u %t \"%r\" %>s %b" comonvhost -CustomLog logs/access_log comonvhost -

- -

The %v is used to log the name of the virtual host -that is serving the request. Then a program like split-logfile can be used to -post-process the access log in order to split it into one file per -virtual host.

- -

Unfortunately, no similar technique is available for the error log, -so you must choose between mixing all virtual hosts in the same error -log and using one error log per virtual host.

- -

Other Log Files

- -

-Related Modules

- -mod_cgi
-mod_rewrite - -

-Related Directives

- -PidFile
-RewriteLog
-RewriteLogLevel
-ScriptLog
-ScriptLogLength
-ScriptLogBuffer - -

- -

PID File

- -

On startup, Apache httpd saves the process id of the parent httpd -process to 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 by sending signals -to the parent process; on Windows, use the -k command line -option instead. For more information see the Stopping and Restarting page. - -

Script Log

- -

In order to aid in debugging, the -ScriptLog -directive allows you to record the input to and output from -CGI scripts. This should only be used in testing - not for -live servers. More information is available in the -mod_cgi documentation. - -

Rewrite Log

- -

When using the powerful and complex features of mod_rewrite, it is almost always -necessary to use the RewriteLog to help in -debugging. This log file produces a detailed analysis of how the -rewriting engine transforms requests. The level of detail is -controlled by the RewriteLogLevel -directive.

- - - - + + + + + + + Log Files - Apache HTTP Server + + + + + + +

Log Files

+ +

In order to effectively manage a web server, it is necessary + to get feedback about the activity and performance of the + server as well as any problems that may be occuring. The Apache + HTTP Server provides very comprehensive and flexible logging + capabilities. This document describes how to configure its + logging capabilities, and how to understand what the logs + contain.

+ +

Security Warning
Error Log
+ Access Log + +
- Common Log Format
- Combined Log Format
- Multiple Access Logs
- Conditional Logging
+
Log Rotation
Piped Logs
VirtualHosts
+ Other Log Files + +
- PID File
- Script Log
- Rewrite Log
+

+ +

Security Warning

+ +

Anyone who can write to the directory where Apache is + writing a log file can almost certainly gain access to the uid + that the server is started as, which is normally root. Do + NOT give people write access to the directory the logs + are stored in without being aware of the consequences; see the + security tips document + for details.

+ +

In addition, log files may contain information supplied + directly by the client, without escaping. Therefore, it is + possible for malicious clients to insert control-characters in + the log files, so care must be taken in dealing with raw + logs.

+ +

Error Log

+ + + + + +

Related Directives
+
+ ErrorLog
+ LogLevel

+ +

The server error log, whose name and location is set by the + ErrorLog directive, is the + most important log file. This is the place where Apache httpd + will send diagnostic information and record any errors that it + encounters in processing requests. It is the first place to + look when a problem occurs with starting the server or with the + operation of the server, since it will often contain details of + what went wrong and how to fix it.

+ +

The error log is usually written to a file (typically + error_log on unix systems and + error.log on Windows and OS/2). On unix systems it + is also possible to have the server send errors to + syslog or pipe them to a + program.

+ +

The format of the error log is relatively free-form and + descriptive. But there is certain information that is contained + in most error log entries. For example, here is a typical + message.

+ +

+ [Wed Oct 11 14:32:52 2000] [error] [client 127.0.0.1] + client denied by server configuration: + /export/home/live/ap/htdocs/test +

+ +

The first item in the log entry is the date and time of the + message. The second entry lists the severity of the error being + reported. The LogLevel + directive is used to control the types of errors that are sent + to the error log by restricting the severity level. The third + entry gives the IP address of the client that generated the + error. Beyond that is the message itself, which in this case + indicates that the server has been configured to deny the + client access. The server reports the file-system path (as + opposed to the web path) of the requested document.

+ +

A very wide variety of different messages can appear in the + error log. Most look similar to the example above. The error + log will also contain debugging output from CGI scripts. Any + information written to stderr by a CGI script will + be copied directly to the error log.

+ +

It is not possible to customize the error log by adding or + removing information. However, error log entries dealing with + particular requests have corresponding entries in the access log. For example, the above example + entry corresponds to an access log entry with status code 403. + Since it is possible to customize the access log, you can + obtain more information about error conditions using that log + file.

+ +

During testing, it is often useful to continuously monitor + the error log for any problems. On unix systems, you can + accomplish this using:

+ +

+ tail -f error_log +

+ +

Access Log

+ + + + + + + +

Related Modules
+
+ mod_log_config
+

Related Directives
+
+ CustomLog
+ LogFormat
+ SetEnvIf +

+ +

The server access log records all requests processed by the + server. The location and content of the access log are + controlled by the CustomLog + directive. The LogFormat + directive can be used to simplify the selection of the contents + of the logs. This section describes how to configure the server + to record information in the access log.

+ +

Of course, storing the information in the access log is only + the start of log management. The next step is to analyze this + information to produce useful statistics. Log analysis in + general is beyond the scope of this document, and not really + part of the job of the web server itself. For more information + about this topic, and for applications which perform log + analysis, check the + Open Directory or + Yahoo.

+ +

Various versions of Apache httpd have used other modules and + directives to control access logging, including + mod_log_referer, mod_log_agent, and the + TransferLog directive. The CustomLog + directive now subsumes the functionality of all the older + directives.

+ +

The format of the access log is highly configurable. The + format is specified using a format string that + looks much like a C-style printf(1) format string. Some + examples are presented in the next sections. For a complete + list of the possible contents of the format string, see the mod_log_config + documentation.

+ +

Common Log Format

+ +

A typical configuration for the access log might look as + follows.

+ +

+ LogFormat "%h %l %u %t \"%r\" %>s %b" common + CustomLog logs/access_log common +

+ +

This defines the nickname common and + associates it with a particular log format string. The format + string consists of percent directives, each of which tell the + server to log a particular piece of information. Literal + characters may also be placed in the format string and will be + copied directly into the log output. The quote character + (") must be escaped by placing a back-slash before + it to prevent it from being interpreted as the end of the + format string. The format string may also contain the special + control characters "\n" for new-line and + "\t" for tab.

+ +

The CustomLog directive sets up a new log file + using the defined nickname. The filename for the + access log is relative to the ServerRoot unless it begins + with a slash.

+ +

The above configuration will write log entries in a format + known as the Common Log Format (CLF). This standard format can + be produced by many different web servers and read by many log + analysis programs. The log file entries produced in CLF will + look something like this:

+ +

+ 127.0.0.1 - frank [10/Oct/2000:13:55:36 -0700] "GET + /apache_pb.gif HTTP/1.0" 200 2326 +

+ +

Each part of this log entry is described below.

+ +

127.0.0.1 (%h): This is the IP address of the client (remote host) which + made the request to the server. If HostNameLookups is + set to On, then the server will try to determine + the hostname and log it in place of the IP address. However, + this configuration is not recommended since it can + significantly slow the server. Instead, it is best to use a + log post-processor such as logresolve to determine + the hostnames. The IP address reported here is not + necessarily the address of the machine at which the user is + sitting. If a proxy server exists between the user and the + server, this address will be the address of the proxy, rather + than the originating machine.
- (%l): The "hyphen" in the output indicates that the requested + piece of information is not available. In this case, the + information that is not available is the RFC 1413 identity of + the client determined by identd on the clients + machine. This information is highly unreliable and should + almost never be used except on tightly controlled internal + networks. Apache httpd will not even attempt to determine + this information unless IdentityCheck is set + to On.
frank (%u): This is the userid of the person requesting the document + as determined by HTTP authentication. The same value is + typically provided to CGI scripts in the + REMOTE_USER environment variable. If the status + code for the request (see below) is 401, then this value + should not be trusted because the user is not yet + authenticated. If the document is not password protected, + this entry will be "-" just like the previous + one.
[10/Oct/2000:13:55:36 -0700] + (%t): + The time that the server finished processing the request. + The format is: + +
+ [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 +
+ It is possible to have the time displayed in another format + by specifying %{format}t in the log format + string, where format is as in + strftime(3) from the C standard library. +
"GET /apache_pb.gif HTTP/1.0" + (\"%r\"): The request line from the client is given in double + quotes. The request line contains a great deal of useful + information. First, the method used by the client is + GET. Second, the client requested the resource + /apache_pb.gif, and third, the client used the + protocol HTTP/1.0. It is also possible to log + one or more parts of the request line independently. For + example, the format string "%m %U%q %H" will log + the method, path, query-string, and protocol, resulting in + exactly the same output as "%r".
200 (%>s): This is the status code that the server sends back to the + client. This information is very valuable, because it reveals + whether the request resulted in a successful response (codes + beginning in 2), a redirection (codes beginning in 3), an + error caused by the client (codes beginning in 4), or an + error in the server (codes beginning in 5). The full list of + possible status codes can be found in the HTTP + specification (RFC2616 section 10).
2326 (%b): The last entry indicates the size of the object returned + to the client, not including the response headers. If no + content was returned to the client, this value will be + "-". To log "0" for no content, use + %B instead.

+ +

Combined Log + Format

+ +

Another commonly used format string is called the Combined + Log Format. It can be used as follows.

+ +

+ LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" + \"%{User-agent}i\"" combined + CustomLog log/acces_log combined +

+ +

This format is exactly the same as the Common Log Format, + with the addition of two more fields. Each of the additional + fields uses the percent-directive + %{header}i, where header can be + any HTTP request header. The access log under this format will + look like:

+ +

+ 127.0.0.1 - frank [10/Oct/2000:13:55:36 -0700] "GET + /apache_pb.gif HTTP/1.0" 200 2326 + "http://www.example.com/start.html" "Mozilla/4.08 [en] + (Win98; I ;Nav)" +

+ +

The additional fields are:

+ +

"http://www.example.com/start.html" + (\"%{Referer}i\"): The "Referer" (sic) HTTP request header. This gives the + site that the client reports having been referred from. (This + should be the page that links to or includes + /apache_pb.gif).
"Mozilla/4.08 [en] (Win98; I ;Nav)" + (\"%{User-agent}i\"): The User-Agent HTTP request header. This is the + identifying information that the client browser reports about + itself.

+ +

Multiple Access + Logs

+ +

Multiple access logs can be created simply by specifying + multiple CustomLog directives in the configuration + file. For example, the following directives will create three + access logs. The first contains the basic CLF information, + while the second and third contain referer and browser + information. The last two CustomLog lines show how + to mimic the effects of the ReferLog and + AgentLog directives.

+ +

+ LogFormat "%h %l %u %t \"%r\" %>s %b" common + CustomLog logs/access_log common + CustomLog logs/referer_log "%{Referer}i -> %U" + CustomLog logs/agent_log "%{User-agent}i" +

+ +

This example also shows that it is not necessary to define a + nickname with the LogFormat directive. Instead, + the log format can be specified directly in the + CustomLog directive.

+ +

Conditional + Logging

+ +

There are times when it is convenient to exclude certain + entries from the access logs based on characteristics of the + client request. This is easily accomplished with the help of environment variables. First, an + environment variable must be set to indicate that the request + meets certain conditions. This is usually accomplished with SetEnvIf. Then the + env= clause of the CustomLog + directive is used to include or exclude requests where the + environment variable is set. Some examples:

+ +

+ # Mark requests from the loop-back interface + SetEnvIf Remote_Addr "127\.0\.0\.1" dontlog + # Mark requests for the robots.txt file + SetEnvIf Request_URI "^/robots\.txt$" dontlog + # Log what remains + CustomLog logs/access_log common env=!dontlog +

+ +

As another example, consider logging requests from + english-speakers to one log file, and non-english speakers to a + different log file.

+ +

+ SetEnvIf Accept-Language "en" english + CustomLog logs/english_log common env=english + CustomLog logs/non_english_log common env=!english +

+ +

Although we have just shown that conditional logging is very + powerful and flexibly, it is not the only way to control the + contents of the logs. Log files are more useful when they + contain a complete record of server activity. It is often + easier to simply post-process the log files to remove requests + that you do not want to consider.

+ +

Log Rotation

+ +

On even a moderately busy server, the quantity of + information stored in the log files is very large. The access + log file typically grows 1 MB or more per 10,000 requests. It + will consequently be necessary to periodically rotate the log + files by moving or deleting the existing logs. This cannot be + done while the server is running, because Apache will continue + writing to the old log file as long as it holds the file open. + Instead, the server must be restarted after the log files are + moved or deleted so that it will open new log files.

+ +

By using a graceful restart, the server can be + instructed to open new log files without losing any existing or + pending connections from clients. However, in order to + accomplish this, the server must continue to write to the old + log files while it finishes serving old requests. It is + therefore necessary to wait for some time after the restart + before doing any processing on the log files. A typical + scenario that simply rotates the logs and compresses the old + logs to save space is:

+ +

+ mv access_log access_log.old + mv error_log error_log.old + apachectl graceful + sleep 600 + gzip access_log.old error_log.old +

+ +

Another way to perform log rotation is using piped logs as discussed in the next + section.

+ +

Piped Logs

+ +

Apache httpd is capable of writing error and access log + files through a pipe to another process, rather than directly + to a file. This capability dramatically increases the + flexibility of logging, without adding code to the main server. + In order to write logs to a pipe, simply replace the filename + with the pipe character "|", followed by the name + of the executable which should accept log entries on its + standard input. Apache will start the piped-log process when + the server starts, and will restart it if it crashes while the + server is running. (This last feature is why we can refer to + this technique as "reliable piped logging".)

+ +

Piped log processes are spawned by the parent Apache httpd + process, and inherit the userid of that process. This means + that piped log programs usually run as root. It is therefore + very important to keep the programs simple and secure.

+ +

Some simple examples using piped logs:

+ +

+ # compressed logs + CustomLog "|/usr/bin/gzip -c >> + /var/log/access_log.gz" common + # almost-real-time name resolution + CustomLog "|/usr/local/apache/bin/logresolve >> + /var/log/access_log" common +

+ +

Notice that quotes are used to enclose the entire command + that will be called for the pipe. Although these examples are + for the access log, the same technique can be used for the + error log.

+ +

One important use of piped logs is to allow log rotation + without having to restart the server. The Apache HTTP Server + includes a simple program called rotatelogs for this + purpose. For example, to rotate the logs every 24 hours, you + can use:

+ +

+ CustomLog "|/usr/local/apache/bin/rotatelogs + /var/log/access_log 86400" common +

+ +

A similar, but much more flexible log rotation program + called cronolog + is available at an external site.

+ +

As with conditional logging, piped logs are a very powerful + tool, but they should not be used where a simpler solution like + off-line post-processing is available.

+ +

Virtual + Hosts

+ +

When running a server with many virtual + hosts, there are several options for dealing with log + files. First, it is possible to use logs exactly as in a + single-host server. Simply by placing the logging directives + outside the <VirtualHost> sections in the + main server context, it is possible to log all requests in the + same access log and error log. This technique does not allow + for easy collection of statistics on individual virtual + hosts.

+ +

If CustomLog or ErrorLog + directives are placed inside a <VirtualHost> + section, all requests or errors for that virtual host will be + logged only to the specified file. Any virtual host which does + not have logging directives will still have its requests sent + to the main server logs. This technique is very useful for a + small number of virtual hosts, but if the number of hosts is + very large, it can be complicated to manage. In addition, it + can often create problems with insufficient file + descriptors.

+ +

For the access log, there is a very good compromise. By + adding information on the virtual host to the log format + string, it is possible to log all hosts to the same log, and + later split the log into individual files. For example, + consider the following directives.

+ +

+ LogFormat "%v %l %u %t \"%r\" %>s %b" + comonvhost + CustomLog logs/access_log comonvhost +

+ +

The %v is used to log the name of the virtual + host that is serving the request. Then a program like split-logfile can be used to + post-process the access log in order to split it into one file + per virtual host.

+ +

Unfortunately, no similar technique is available for the + error log, so you must choose between mixing all virtual hosts + in the same error log and using one error log per virtual + host.

+ +

Other Log Files

+ + + + + + + +

Related Modules
+
+ mod_cgi
+ mod_rewrite

Related Directives
+
+ PidFile
+ RewriteLog
+ RewriteLogLevel
+ ScriptLog
+ ScriptLogLength
+ ScriptLogBuffer +

+ +

PID File

+ +

On startup, Apache httpd saves the process id of the parent + httpd process to 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 by sending signals to the parent + process; on Windows, use the -k command line option instead. + For more information see the Stopping + and Restarting page.

+ +

Script Log

+ +

In order to aid in debugging, the ScriptLog directive + allows you to record the input to and output from CGI scripts. + This should only be used in testing - not for live servers. + More information is available in the mod_cgi documentation.

+ +

Rewrite Log

+ +

When using the powerful and complex features of mod_rewrite, it is almost + always necessary to use the RewriteLog to help + in debugging. This log file produces a detailed analysis of how + the rewriting engine transforms requests. The level of detail + is controlled by the RewriteLogLevel + directive.

+ + + + diff --git a/docs/manual/logs.html.en b/docs/manual/logs.html.en index f83f474bf28..a45a96ef16d 100644 --- a/docs/manual/logs.html.en +++ b/docs/manual/logs.html.en @@ -1,582 +1,667 @@ - - - -Log Files - Apache HTTP Server - - - - - -

Log Files

- -

Security Warning
Error Log
Access Log -
Log Rotation
Piped Logs
VirtualHosts -
Other Log Files -
- PID File
- Script Log
- Rewrite Log

- -

Security Warning

- -

Error Log

- - -

-Related Directives

- -ErrorLog
-LogLevel -

- -

The format of the error log is relatively free-form and -descriptive. But there is certain information that is contained -in most error log entries. For example, here is a typical message.

- -

-[Wed Oct 11 14:32:52 2000] [error] [client 127.0.0.1] client denied by server configuration: /export/home/live/ap/htdocs/test -

- -

During testing, it is often useful to continuously monitor the -error log for any problems. On unix systems, you can accomplish this -using:

-tail -f error_log -

- -

Access Log

- -

-Related Modules

- -mod_log_config
- -

-Related Directives

- -CustomLog
-LogFormat
-SetEnvIf - -

- -

Common Log Format

- -

A typical configuration for the access log might look -as follows.

- -

-LogFormat "%h %l %u %t \"%r\" %>s %b" common -CustomLog logs/access_log common -

- -

The CustomLog directive sets up a new log file using -the defined nickname. The filename for the access log is -relative to the ServerRoot -unless it begins with a slash.

- -

-127.0.0.1 - frank [10/Oct/2000:13:55:36 -0700] "GET /apache_pb.gif HTTP/1.0" 200 2326 -

- -

Each part of this log entry is described below.

- -

127.0.0.1 (%h): This is the IP -address of the client (remote host) which made the request to the -server. If HostNameLookups is set to -On, then the server will try to determine the hostname -and log it in place of the IP address. However, this configuration is -not recommended since it can significantly slow the server. Instead, -it is best to use a log post-processor such as logresolve to determine the -hostnames. The IP address reported here is not necessarily the -address of the machine at which the user is sitting. If a proxy -server exists between the user and the server, this address will be -the address of the proxy, rather than the originating machine.
- (%l): The "hyphen" in the -output indicates that the requested piece of information is not -available. In this case, the information that is not available is the -RFC 1413 identity of the client determined by identd on -the clients machine. This information is highly unreliable and should -almost never be used except on tightly controlled internal networks. -Apache httpd will not even attempt to determine this information -unless IdentityCheck is set -to On.
frank (%u): This is the userid -of the person requesting the document as determined by HTTP -authentication. The same value is typically provided to CGI scripts -in the REMOTE_USER environment variable. If the status -code for the request (see below) is 401, then this value should not be -trusted because the user is not yet authenticated. If the document is -not password protected, this entry will be "-" just like -the previous one.
[10/Oct/2000:13:55:36 -0700] (%t): The time that the server finished processing the request. The -format is: -
[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
-It is possible to have the time displayed in another format -by specifying %{format}t in the log format string, where -format is as in strftime(3) from the C -standard library. -
"GET /apache_pb.gif HTTP/1.0" -(\"%r\"): The request line from the client is -given in double quotes. The request line contains a great deal of -useful information. First, the method used by the client is -GET. Second, the client requested the resource -/apache_pb.gif, and third, the client used the protocol -HTTP/1.0. It is also possible to log one or more -parts of the request line independently. For example, the format -string "%m %U%q %H" will log the method, path, -query-string, and protocol, resulting in exactly the same output as -"%r".
200 (%>s): This is the status -code that the server sends back to the client. This information is -very valuable, because it reveals whether the request resulted in a -successful response (codes beginning in 2), a redirection (codes -beginning in 3), an error caused by the client (codes beginning in 4), -or an error in the server (codes beginning in 5). -The full list of possible status codes can be -found in the HTTP specification (RFC2616 section 10).
2326 (%b) -: The last entry indicates the size of the object returned to -the client, not including the response headers. If no content -was returned to the client, this value will be "-". -To log "0" for no content, use %B -instead.

- -

Combined Log Format

- -

Another commonly used format string is called the -Combined Log Format. It can be used as follows.

- -

-LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\"" combined -CustomLog log/acces_log combined -

- -

-127.0.0.1 - frank [10/Oct/2000:13:55:36 -0700] "GET /apache_pb.gif HTTP/1.0" 200 2326 "http://www.example.com/start.html" "Mozilla/4.08 [en] (Win98; I ;Nav)" -

- -

The additional fields are:

- -

"http://www.example.com/start.html" -(\"%{Referer}i\"): The "Referer" (sic) HTTP -request header. This gives the site that the client reports having -been referred from. (This should be the page that links to or includes -/apache_pb.gif). - -
"Mozilla/4.08 [en] (Win98; I ;Nav)" -(\"%{User-agent}i\"): The User-Agent HTTP request -header. This is the identifying information that the client browser -reports about itself.

- -

Multiple Access Logs

- -

-LogFormat "%h %l %u %t \"%r\" %>s %b" common -CustomLog logs/access_log common -CustomLog logs/referer_log "%{Referer}i -> %U" -CustomLog logs/agent_log "%{User-agent}i" -

- -

This example also shows that it is not necessary to define a -nickname with the LogFormat directive. Instead, the log -format can be specified directly in the CustomLog -directive.

- -

Conditional Logging

- -

-# Mark requests from the loop-back interface -SetEnvIf Remote_Addr "127\.0\.0\.1" dontlog -# Mark requests for the robots.txt file -SetEnvIf Request_URI "^/robots\.txt$" dontlog -# Log what remains -CustomLog logs/access_log common env=!dontlog -

- -

As another example, consider logging requests from english-speakers -to one log file, and non-english speakers to a different log file.

- -

-SetEnvIf Accept-Language "en" english -CustomLog logs/english_log common env=english -CustomLog logs/non_english_log common env=!english -

- -

Log Rotation

- -

-mv access_log access_log.old -mv error_log error_log.old -apachectl graceful -sleep 600 -gzip access_log.old error_log.old -

- -

Another way to perform log rotation is using piped -logs as discussed in the next section.

- -

Piped Logs

- -

Some simple examples using piped logs:

- -

-# compressed logs -CustomLog "|/usr/bin/gzip -c >> /var/log/access_log.gz" common -# almost-real-time name resolution -CustomLog "|/usr/local/apache/bin/logresolve >> /var/log/access_log" common -

- -

Notice that quotes are used to enclose the entire command -that will be called for the pipe. Although these examples are -for the access log, the same technique can be used for the -error log.

- -

-CustomLog "|/usr/local/apache/bin/rotatelogs /var/log/access_log 86400" common -

- -

A similar, but much more flexible log rotation program -called cronolog -is available at an external site.

- -

As with conditional logging, piped logs are a very powerful tool, -but they should not be used where a simpler solution like -off-line post-processing is available.

- -

Virtual Hosts

- -

-LogFormat "%v %l %u %t \"%r\" %>s %b" comonvhost -CustomLog logs/access_log comonvhost -

- -

Unfortunately, no similar technique is available for the error log, -so you must choose between mixing all virtual hosts in the same error -log and using one error log per virtual host.

- -

Other Log Files

- -

-Related Modules

- -mod_cgi
-mod_rewrite - -

-Related Directives

- -PidFile
-RewriteLog
-RewriteLogLevel
-ScriptLog
-ScriptLogLength
-ScriptLogBuffer - -

- -

PID File

- -

Script Log

- -

Rewrite Log

- -

- - - - + + + + + + + Log Files - Apache HTTP Server + + + + + + +

Log Files

+ +

Security Warning
Error Log
+ Access Log + +
- Common Log Format
- Combined Log Format
- Multiple Access Logs
- Conditional Logging
+
Log Rotation
Piped Logs
VirtualHosts
+ Other Log Files + +
- PID File
- Script Log
- Rewrite Log
+

+ +

Security Warning

+ +

Error Log

+ + + + + +

Related Directives
+
+ ErrorLog
+ LogLevel

+ +

The format of the error log is relatively free-form and + descriptive. But there is certain information that is contained + in most error log entries. For example, here is a typical + message.

+ +

+ [Wed Oct 11 14:32:52 2000] [error] [client 127.0.0.1] + client denied by server configuration: + /export/home/live/ap/htdocs/test +

+ +

During testing, it is often useful to continuously monitor + the error log for any problems. On unix systems, you can + accomplish this using:

+ +

+ tail -f error_log +

+ +

Access Log

+ + + + + + + +

Related Modules
+
+ mod_log_config
+

Related Directives
+
+ CustomLog
+ LogFormat
+ SetEnvIf +

+ +

Common Log Format

+ +

A typical configuration for the access log might look as + follows.

+ +

+ LogFormat "%h %l %u %t \"%r\" %>s %b" common + CustomLog logs/access_log common +

+ +

The CustomLog directive sets up a new log file + using the defined nickname. The filename for the + access log is relative to the ServerRoot unless it begins + with a slash.

+ +

+ 127.0.0.1 - frank [10/Oct/2000:13:55:36 -0700] "GET + /apache_pb.gif HTTP/1.0" 200 2326 +

+ +

Each part of this log entry is described below.

+ +

127.0.0.1 (%h): This is the IP address of the client (remote host) which + made the request to the server. If HostNameLookups is + set to On, then the server will try to determine + the hostname and log it in place of the IP address. However, + this configuration is not recommended since it can + significantly slow the server. Instead, it is best to use a + log post-processor such as logresolve to determine + the hostnames. The IP address reported here is not + necessarily the address of the machine at which the user is + sitting. If a proxy server exists between the user and the + server, this address will be the address of the proxy, rather + than the originating machine.
- (%l): The "hyphen" in the output indicates that the requested + piece of information is not available. In this case, the + information that is not available is the RFC 1413 identity of + the client determined by identd on the clients + machine. This information is highly unreliable and should + almost never be used except on tightly controlled internal + networks. Apache httpd will not even attempt to determine + this information unless IdentityCheck is set + to On.
frank (%u): This is the userid of the person requesting the document + as determined by HTTP authentication. The same value is + typically provided to CGI scripts in the + REMOTE_USER environment variable. If the status + code for the request (see below) is 401, then this value + should not be trusted because the user is not yet + authenticated. If the document is not password protected, + this entry will be "-" just like the previous + one.
[10/Oct/2000:13:55:36 -0700] + (%t): + The time that the server finished processing the request. + The format is: + +
+ [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 +
+ It is possible to have the time displayed in another format + by specifying %{format}t in the log format + string, where format is as in + strftime(3) from the C standard library. +
"GET /apache_pb.gif HTTP/1.0" + (\"%r\"): The request line from the client is given in double + quotes. The request line contains a great deal of useful + information. First, the method used by the client is + GET. Second, the client requested the resource + /apache_pb.gif, and third, the client used the + protocol HTTP/1.0. It is also possible to log + one or more parts of the request line independently. For + example, the format string "%m %U%q %H" will log + the method, path, query-string, and protocol, resulting in + exactly the same output as "%r".
200 (%>s): This is the status code that the server sends back to the + client. This information is very valuable, because it reveals + whether the request resulted in a successful response (codes + beginning in 2), a redirection (codes beginning in 3), an + error caused by the client (codes beginning in 4), or an + error in the server (codes beginning in 5). The full list of + possible status codes can be found in the HTTP + specification (RFC2616 section 10).
2326 (%b): The last entry indicates the size of the object returned + to the client, not including the response headers. If no + content was returned to the client, this value will be + "-". To log "0" for no content, use + %B instead.

+ +

Combined Log + Format

+ +

Another commonly used format string is called the Combined + Log Format. It can be used as follows.

+ +

+ LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" + \"%{User-agent}i\"" combined + CustomLog log/acces_log combined +

+ +

+ 127.0.0.1 - frank [10/Oct/2000:13:55:36 -0700] "GET + /apache_pb.gif HTTP/1.0" 200 2326 + "http://www.example.com/start.html" "Mozilla/4.08 [en] + (Win98; I ;Nav)" +

+ +

The additional fields are:

+ +

"http://www.example.com/start.html" + (\"%{Referer}i\"): The "Referer" (sic) HTTP request header. This gives the + site that the client reports having been referred from. (This + should be the page that links to or includes + /apache_pb.gif).
"Mozilla/4.08 [en] (Win98; I ;Nav)" + (\"%{User-agent}i\"): The User-Agent HTTP request header. This is the + identifying information that the client browser reports about + itself.

+ +

Multiple Access + Logs

+ +

+ LogFormat "%h %l %u %t \"%r\" %>s %b" common + CustomLog logs/access_log common + CustomLog logs/referer_log "%{Referer}i -> %U" + CustomLog logs/agent_log "%{User-agent}i" +

+ +

This example also shows that it is not necessary to define a + nickname with the LogFormat directive. Instead, + the log format can be specified directly in the + CustomLog directive.

+ +

Conditional + Logging

+ +

+ # Mark requests from the loop-back interface + SetEnvIf Remote_Addr "127\.0\.0\.1" dontlog + # Mark requests for the robots.txt file + SetEnvIf Request_URI "^/robots\.txt$" dontlog + # Log what remains + CustomLog logs/access_log common env=!dontlog +

+ +

As another example, consider logging requests from + english-speakers to one log file, and non-english speakers to a + different log file.

+ +

+ SetEnvIf Accept-Language "en" english + CustomLog logs/english_log common env=english + CustomLog logs/non_english_log common env=!english +

+ +

Log Rotation

+ +

+ mv access_log access_log.old + mv error_log error_log.old + apachectl graceful + sleep 600 + gzip access_log.old error_log.old +

+ +

Another way to perform log rotation is using piped logs as discussed in the next + section.

+ +

Piped Logs

+ +

Some simple examples using piped logs:

+ +

+ # compressed logs + CustomLog "|/usr/bin/gzip -c >> + /var/log/access_log.gz" common + # almost-real-time name resolution + CustomLog "|/usr/local/apache/bin/logresolve >> + /var/log/access_log" common +

+ +

Notice that quotes are used to enclose the entire command + that will be called for the pipe. Although these examples are + for the access log, the same technique can be used for the + error log.

+ +

+ CustomLog "|/usr/local/apache/bin/rotatelogs + /var/log/access_log 86400" common +

+ +

A similar, but much more flexible log rotation program + called cronolog + is available at an external site.

+ +

As with conditional logging, piped logs are a very powerful + tool, but they should not be used where a simpler solution like + off-line post-processing is available.

+ +

Virtual + Hosts

+ +

+ LogFormat "%v %l %u %t \"%r\" %>s %b" + comonvhost + CustomLog logs/access_log comonvhost +

+ +

Unfortunately, no similar technique is available for the + error log, so you must choose between mixing all virtual hosts + in the same error log and using one error log per virtual + host.

+ +

Other Log Files

+ + + + + + + +

Related Modules
+
+ mod_cgi
+ mod_rewrite

Related Directives
+
+ PidFile
+ RewriteLog
+ RewriteLogLevel
+ ScriptLog
+ ScriptLogLength
+ ScriptLogBuffer +

+ +

PID File

+ +

Script Log

+ +

Rewrite Log

+ +

+ + + + diff --git a/docs/manual/mpm.html b/docs/manual/mpm.html index 9c63844e921..31aa5546955 100644 --- a/docs/manual/mpm.html +++ b/docs/manual/mpm.html @@ -1,90 +1,95 @@ - - - -Apache Multi-Processing Modules (MPMs) - - - - - - - -

Apache Multi-Processing Modules

- -

The Apache HTTP Server is designed to be a powerful and flexible -web server that can work on a very wide variety of platforms in a -range of different environments. Different platforms and different -environments often require different features, or may have different -ways of implementing the same feature most efficiently. Apache has -always accommodated a wide variety of environments through its modular -design. This design allows the webmaster to choose which features -will be included in the server by selecting which modules to load -either at compile-time or at run-time.

- -

Apache 2.0 extends this modular design to the most basic functions -of a web server. The server ships with a selection of -Multi-Processing Modules (MPMs) which are responsible for binding to -network ports on the machine, accepting requests, and dispatching -children to handle the requests.

- -

Extending the modular design to this level of the server -allows two important benefits: -

Apache can more cleanly and efficiently support a wide variety of -operating systems. In particular, the Windows version of Apache is -now much more efficient, since mpm_winnt can use native networking -features in place of the POSIX layer used in Apache 1.3. This benefit -also extends to other operating systems that implement specialized -MPMs.
The server can be better customized for the needs of the -particular site. For example, sites that need a great deal of -scalability can choose to use a threaded MPM like threaded, while sites requiring -stability or compatibility with older software can use a preforking MPM. In addition, special -features like serving different hosts under different userids -(perchild) can be provided.

- -

At the user level, MPMs appear much like other Apache modules. -The main difference is that one and only one MPM must be loaded -into the server at any time. The list of available MPMs -appears on the module index page.

- -

Choosing an MPM

- -

MPMs must be chosen during configuration, and compiled into the server. -Compilers are capable of optimizing a lot of functions if threads are used, -but only if they know that threads are being used. Because some MPMs use -threads on Unix and others don't, Apache will always perform better if the -MPM is chosen at configuration time and built into Apache.

- -

To actually choose the desired MPM, use the argument --with-mpm= -NAME with the ./configure script. NAME is the name of -the desired MPM.

- -

Once the server has been compiled, it is possible to determine which -MPM was chosen by using ./httpd -l. This command will list -every module that is compiled into the server, including the MPM.

- -

MPM Defaults

- -

BeOS: mpmt_beos
OS/2: mpmt_os2
Unix: prefork
Windows: winnt

- - - - + + + + + + + Apache Multi-Processing Modules (MPMs) + + + + + + +

Apache Multi-Processing Modules

+ +

The Apache HTTP Server is designed to be a powerful and + flexible web server that can work on a very wide variety of + platforms in a range of different environments. Different + platforms and different environments often require different + features, or may have different ways of implementing the same + feature most efficiently. Apache has always accommodated a wide + variety of environments through its modular design. This design + allows the webmaster to choose which features will be included + in the server by selecting which modules to load either at + compile-time or at run-time.

+ +

Apache 2.0 extends this modular design to the most basic + functions of a web server. The server ships with a selection of + Multi-Processing Modules (MPMs) which are responsible for + binding to network ports on the machine, accepting requests, + and dispatching children to handle the requests.

+ +

Extending the modular design to this level of the server + allows two important benefits:

+ +

Apache can more cleanly and efficiently support a wide + variety of operating systems. In particular, the Windows + version of Apache is now much more efficient, since mpm_winnt can use native + networking features in place of the POSIX layer used in + Apache 1.3. This benefit also extends to other operating + systems that implement specialized MPMs.
The server can be better customized for the needs of the + particular site. For example, sites that need a great deal of + scalability can choose to use a threaded MPM like threaded, while sites requiring + stability or compatibility with older software can use a preforking MPM. In addition, + special features like serving different hosts under different + userids (perchild) can be + provided.

+ +

At the user level, MPMs appear much like other Apache + modules. The main difference is that one and only one MPM must + be loaded into the server at any time. The list of available + MPMs appears on the module index page.

+ +

Choosing an MPM

+ +

MPMs must be chosen during configuration, and compiled into + the server. Compilers are capable of optimizing a lot of + functions if threads are used, but only if they know that + threads are being used. Because some MPMs use threads on Unix + and others don't, Apache will always perform better if the MPM + is chosen at configuration time and built into Apache.

+ +

To actually choose the desired MPM, use the argument + --with-mpm= NAME with the ./configure script. + NAME is the name of the desired MPM.

+ +

Once the server has been compiled, it is possible to + determine which MPM was chosen by using ./httpd + -l. This command will list every module that is compiled + into the server, including the MPM.

+ +

MPM Defaults

+ +

BeOS: mpmt_beos
OS/2: mpmt_os2
Unix: prefork
Windows: winnt

+ + diff --git a/docs/manual/mpm.html.en b/docs/manual/mpm.html.en index 9c63844e921..31aa5546955 100644 --- a/docs/manual/mpm.html.en +++ b/docs/manual/mpm.html.en @@ -1,90 +1,95 @@ - - - -Apache Multi-Processing Modules (MPMs) - - - - - - - -

Apache Multi-Processing Modules

- -

Extending the modular design to this level of the server -allows two important benefits: -

Apache can more cleanly and efficiently support a wide variety of -operating systems. In particular, the Windows version of Apache is -now much more efficient, since mpm_winnt can use native networking -features in place of the POSIX layer used in Apache 1.3. This benefit -also extends to other operating systems that implement specialized -MPMs.
The server can be better customized for the needs of the -particular site. For example, sites that need a great deal of -scalability can choose to use a threaded MPM like threaded, while sites requiring -stability or compatibility with older software can use a preforking MPM. In addition, special -features like serving different hosts under different userids -(perchild) can be provided.

- -

Choosing an MPM

- -

To actually choose the desired MPM, use the argument --with-mpm= -NAME with the ./configure script. NAME is the name of -the desired MPM.

- -

Once the server has been compiled, it is possible to determine which -MPM was chosen by using ./httpd -l. This command will list -every module that is compiled into the server, including the MPM.

- -

MPM Defaults

- -

BeOS: mpmt_beos
OS/2: mpmt_os2
Unix: prefork
Windows: winnt

- - - - + + + + + + + Apache Multi-Processing Modules (MPMs) + + + + + + +

Apache Multi-Processing Modules

+ +

Extending the modular design to this level of the server + allows two important benefits:

+ +

Apache can more cleanly and efficiently support a wide + variety of operating systems. In particular, the Windows + version of Apache is now much more efficient, since mpm_winnt can use native + networking features in place of the POSIX layer used in + Apache 1.3. This benefit also extends to other operating + systems that implement specialized MPMs.
The server can be better customized for the needs of the + particular site. For example, sites that need a great deal of + scalability can choose to use a threaded MPM like threaded, while sites requiring + stability or compatibility with older software can use a preforking MPM. In addition, + special features like serving different hosts under different + userids (perchild) can be + provided.

+ +

Choosing an MPM

+ +

To actually choose the desired MPM, use the argument + --with-mpm= NAME with the ./configure script. + NAME is the name of the desired MPM.

+ +

MPM Defaults

+ +

BeOS: mpmt_beos
OS/2: mpmt_os2
Unix: prefork
Windows: winnt

+ + diff --git a/docs/manual/new_features_2_0.html.en b/docs/manual/new_features_2_0.html.en index 8bb0dc4944f..8e519f8dd2d 100644 --- a/docs/manual/new_features_2_0.html.en +++ b/docs/manual/new_features_2_0.html.en @@ -1,99 +1,121 @@ - - -New features with Apache 2.0 - - - - - -

Overview of New Features in Apache 2.0

- -

Enhancements: Core | Module - -

- -

Core Enhancements:

- -

Unix Threading -: On Unix systems with POSIX threads support, Apache can now run in a - hybrid multiprocess, multithreaded mode. This should improve - scalability. - -
New Build System -: The build system has been rewritten from scratch to be based on - autoconf and libtool. This makes Apache's configuration system more - similar to that of other packages. - -
Multiprotocol Support -: Apache now has some of the infrastructure in place to support serving - multiple protocols. mod_echo has been written as an example. - -
Better support for non-Unix platforms: Apache - 2.0 is faster and more stable on non-Unix platforms such as BeOS, - OS/2, and Windows. With the introduction of platform-specific multi-processing modules (MPMs) and the Apache - Portable Runtime (APR), these platforms are now implemented in their - native API, avoiding the often buggy and poorly performing - POSIX-emulation layers. - -
New Apache API -: The API for modules has changed significantly for 2.0. Many of the - module-ordering problems from 1.3 should be gone. 2.0 does much of - this automatically, and module ordering is now done per-hook to - allow more flexibility. Also, new calls have been added that provide - additional module capabilities without patching the core Apache server. - -
IPv6 Support: On systems where IPv6 is supported by the underlying Apache - Portable Runtime library, Apache gets IPv6 listening sockets by - default. Additionally, the Listen, NameVirtualHost, and - <VirtualHost> directives support IPv6 numeric address - strings (e.g., "Listen [fe80::1]:8080").
Filtering: Apache modules may now be written as filters which act on the - stream of content as it is delivered to or from the server. This - allows, for example, the output of CGI scripts to be parsed for - Server Side Include directive by mod_include.

- -

Module Enhancements:

- -

mod_auth_db -: Now supports Berkely DB 3.0 - -
mod_auth_digest -: Includes additional support for session caching across processes -using shared memory. - -
mod_charset_lite: New module in Apache 2.0. -This experimental module allows for character set translation -or recoding. - -
mod_dav -: New module in Apache 2.0. This module implements the -HTTP Distributed Authoring and Versioning (DAV) specification for -posting and maintaining web content. - -
mod_file_cache -: New module in Apache 2.0. This module includes the functionality -of mod_mmap_static in Apache 1.3, plus adds further caching abilities. - -
mod_headers -: This module is much more flexible in Apache 2.0. It can now -modify request headers used by mod_proxy, and it can conditionally set -response headers. - -

- - - - + + + + + + + New features with Apache 2.0 + + + + + + +

Overview of New Features in Apache 2.0

+ +

Enhancements: Core | Module

+ +

Core Enhancements:

+ +

Unix Threading: On Unix systems with POSIX threads support, Apache can + now run in a hybrid multiprocess, multithreaded mode. This + should improve scalability.
New Build System: The build system has been rewritten from scratch to be + based on autoconf and libtool. This makes Apache's + configuration system more similar to that of other + packages.
Multiprotocol Support: Apache now has some of the infrastructure in place to + support serving multiple protocols. mod_echo has been written + as an example.
Better support for non-Unix + platforms: Apache 2.0 is faster and more stable on non-Unix + platforms such as BeOS, OS/2, and Windows. With the + introduction of platform-specific multi-processing modules (MPMs) and the + Apache Portable Runtime (APR), these platforms are now + implemented in their native API, avoiding the often buggy and + poorly performing POSIX-emulation layers.
New Apache API: The API for modules has changed significantly for 2.0. + Many of the module-ordering problems from 1.3 should be gone. + 2.0 does much of this automatically, and module ordering is + now done per-hook to allow more flexibility. Also, new calls + have been added that provide additional module capabilities + without patching the core Apache server.
IPv6 Support: On systems where IPv6 is supported by the underlying + Apache Portable Runtime library, Apache gets IPv6 listening + sockets by default. Additionally, the Listen, + NameVirtualHost, and <VirtualHost> directives support + IPv6 numeric address strings (e.g., "Listen + [fe80::1]:8080").
Filtering: Apache modules may now be written as filters which act on + the stream of content as it is delivered to or from the + server. This allows, for example, the output of CGI scripts + to be parsed for Server Side Include directive by + mod_include.

+ +

Module Enhancements:

+ +

mod_auth_db: Now supports Berkely DB 3.0
mod_auth_digest: Includes additional support for session caching across + processes using shared memory.
mod_charset_lite: New module in Apache 2.0. This experimental module allows + for character set translation or recoding.
mod_dav: New module in Apache 2.0. This module implements the HTTP + Distributed Authoring and Versioning (DAV) specification for + posting and maintaining web content.
mod_file_cache: New module in Apache 2.0. This module includes the + functionality of mod_mmap_static in Apache 1.3, plus adds + further caching abilities.
mod_headers: This module is much more flexible in Apache 2.0. It can + now modify request headers used by mod_proxy, and it can + conditionally set response headers.

+ + + diff --git a/docs/manual/new_features_2_0.html.fr b/docs/manual/new_features_2_0.html.fr index a0c550472da..624b3adda86 100644 --- a/docs/manual/new_features_2_0.html.fr +++ b/docs/manual/new_features_2_0.html.fr @@ -1,89 +1,115 @@ - - - -Nouvelles fonctionnalités d'Apache 2.0 - - - - - -

Aperçu des nouvelles fonctionnalités -d'Apache 2.0

- -

Améliorations : Noyau -| Module - -

- -

Améliorations du noyau :

- -

Threads sur Unix -: Sur les systèmes Unix, Apache peut s'exécuter selon -un modèle hybride multi-processus et multi-threads, -en employant les threads selon la norme POSIX. Ceci devrait améliorer -les performances. - -
Nouveau système de construction -: Le système de construction a été entièrement -réécrit et repose sur autoconf et libtool. Cela rend le -système de configuration plus semblable aux autres paquetages. - -
Support multiprotocole -: Apache possède maintenant une infrastructure afin de servir de multiples -protocoles. mod_echo a été écrit comme exemple de ces -nouvelles fonctions. - -
Meilleur support des plates-formes autres qu'Unix -: Apache 2.0 est plus rapide et plus stable sur les plates-formes non Unix -telles que BeOS, OS/2, et Windows. Avec l'introduction des -modules multi traitements (MPMs) spécifiques aux -plates-formes et l'exécuteur portable Apache (APR), le code pour ces -plates-formes est réalisé en employant leurs API natives, -permettant ainsi d'éviter les couches d'émulation POSIX -souvent boguées et peu performantes. - -
Nouvelle API Apache -: L'API pour les modules de la version 2.0 a changé de manière -importante. Beaucoup de problèmes d'ordonnancement des modules existants -dans la version 1.3 devraient disparaître. La version 2.0 gère ceci de -manière automatique, et l'ordonnancement des modules s'effectue selon -une fonction d'accrochage afin de permettre une plus grande flexibilité. - -

- -

Améliorations concernant les modules :

- -

mod_auth_db -: Il accepte maintenant les bases Berkeley DB 3.0. - -
mod_auth_digest -: Il inclut une nouvelle gestion des sessions en utilisant un cache commun -aux processus grâce à une mémoire partagée. - -
mod_charset_lite: Nouveau module dans Apache 2.0. -Ce module expérimental permet la traduction des pages de caractères -ou leur recodage. - -
mod_dav -: Nouveau module dans Apache 2.0. Ce module met en oeuvre la spécification -"HTTP Distributed Authoring and Versioning (DAV)" permettant de distribuer et -maintenir le contenu d'un site web. - -
mod_file_cache -: Nouveau module dans Apache 2.0. Ce module inclut les fonctionnalités -du module mod_mmap_static existant dans la version d'Apache 1.3, en ajoutant -davantage de possibilités de cache. - -

- - - - + + + + + + + Nouvelles fonctionnalités d'Apache 2.0 + + + + + + +

Aperçu des nouvelles + fonctionnalités d'Apache 2.0

+ +

Améliorations : Noyau | Module

+ +

Améliorations du noyau + :

+ +

Threads sur Unix: Sur les systèmes Unix, Apache peut + s'exécuter selon un modèle hybride + multi-processus et multi-threads, en employant les threads + selon la norme POSIX. Ceci devrait améliorer les + performances.
Nouveau système de + construction: Le système de construction a été + entièrement réécrit et repose sur + autoconf et libtool. Cela rend le système de + configuration plus semblable aux autres paquetages.
Support multiprotocole: Apache possède maintenant une infrastructure afin + de servir de multiples protocoles. mod_echo a + été écrit comme exemple de ces nouvelles + fonctions.
Meilleur support des plates-formes autres + qu'Unix: Apache 2.0 est plus rapide et plus stable sur les + plates-formes non Unix telles que BeOS, OS/2, et Windows. + Avec l'introduction des modules multi + traitements (MPMs) spécifiques aux plates-formes + et l'exécuteur portable Apache (APR), le code pour ces + plates-formes est réalisé en employant leurs + API natives, permettant ainsi d'éviter les couches + d'émulation POSIX souvent boguées et peu + performantes.
Nouvelle API Apache: L'API pour les modules de la version 2.0 a changé + de manière importante. Beaucoup de problèmes + d'ordonnancement des modules existants dans la version 1.3 + devraient disparaître. La version 2.0 gère ceci + de manière automatique, et l'ordonnancement des + modules s'effectue selon une fonction d'accrochage afin de + permettre une plus grande flexibilité.

+ +

Améliorations + concernant les modules :

+ +

mod_auth_db: Il accepte maintenant les bases Berkeley DB 3.0.
mod_auth_digest: Il inclut une nouvelle gestion des sessions en utilisant + un cache commun aux processus grâce à une + mémoire partagée.
mod_charset_lite: Nouveau module dans Apache 2.0. Ce module + expérimental permet la traduction des pages de + caractères ou leur recodage.
mod_dav: Nouveau module dans Apache 2.0. Ce module met en oeuvre + la spécification "HTTP Distributed Authoring and + Versioning (DAV)" permettant de distribuer et maintenir le + contenu d'un site web.
mod_file_cache: Nouveau module dans Apache 2.0. Ce module inclut les + fonctionnalités du module mod_mmap_static existant + dans la version d'Apache 1.3, en ajoutant davantage de + possibilités de cache.

+ + + diff --git a/docs/manual/sections.html b/docs/manual/sections.html index 7d91191a6c2..9782a63a7ba 100644 --- a/docs/manual/sections.html +++ b/docs/manual/sections.html @@ -1,163 +1,152 @@ - - -How Directory, Location and Files sections work - - - - - - -

How Directory, Location and Files sections work

- -

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 -different sections differ and how they relate to each other when -Apache decides which directives apply for a particular directory or -request URL.

- -

Directives allowed in the sections

- -

Everything that is syntactically allowed in -<Directory> is also allowed in -<Location> (except a sub-<Files> -section). Semantically, however some things, most -notably AllowOverride and the two options -FollowSymLinks and SymLinksIfOwnerMatch, -make no sense in <Location>, -<LocationMatch> or <DirectoryMatch>. -The same for <Files> -- syntactically everything -is fine, but semantically some things are different.

- -

How the sections are merged

- -

The order of merging is:

- -

- - <Directory> (except regular expressions) and - .htaccess done simultaneously (with .htaccess, if allowed, overriding - <Directory>) - -
- <DirectoryMatch>, and - <Directory> with regular expressions - -
<Files> and <FilesMatch> done - simultaneously -
<Location> and <LocationMatch> done - simultaneously -

- -

Apart from <Directory>, each group is processed in -the order that they appear in the configuration -files. <Directory> (group 1 above) is processed in -the order shortest directory component to longest. If multiple -<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 -directive will be treated as if they were inside the including file -at the location of the Include directive.

- -

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.

- -

Later sections override earlier ones.

- -

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>. -
- If you are attempting to match objects at the URL level then you - must use <Location> -

- -

But a notable exception 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 - language should probably switch this to - <Location>. -

- -

Note about .htaccess parsing:

- -

- Modifying .htaccess parsing during Location doesn't do - anything because .htaccess parsing has already occurred. -

- -

<Location> and symbolic links:

- -

- It is not possible to use "Options FollowSymLinks" - or "Options SymLinksIfOwnerMatch" inside a - <Location>, <LocationMatch> - or <DirectoryMatch> section - (the options are simply ignored). - Using the options in question is only possible inside a - <Directory> section (or a .htaccess file). -

- -

<Files> and Options:

- -

- Apache won't check for it, but using an Options - directive inside a <Files> section has no effect. -

- -

Another note:

- -

- There is actually a - <Location>/<LocationMatch> - sequence performed just before the name translation phase (where - Aliases and DocumentRoots are used to - map URLs to filenames). The results of this sequence are - completely thrown away after the translation has completed. -

- - - - + + + + + + + How Directory, Location and Files sections work + + + + + + +

How Directory, Location and Files sections + work

+ +

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 different sections differ and how + they relate to each other when Apache decides which directives + apply for a particular directory or request URL.

+ +

Directives allowed in the sections

+ +

Everything that is syntactically allowed in + <Directory> is also allowed in + <Location> (except a + sub-<Files> section). Semantically, however + some things, most notably AllowOverride and the + two options FollowSymLinks and + SymLinksIfOwnerMatch, make no sense in + <Location>, + <LocationMatch> or + <DirectoryMatch>. The same for + <Files> -- syntactically everything is fine, + but semantically some things are different.

+ +

How the sections are merged

+ +

The order of merging is:

+ +

<Directory> (except regular + expressions) and .htaccess done simultaneously (with + .htaccess, if allowed, overriding + <Directory>)
<DirectoryMatch>, and + <Directory> with regular expressions
<Files> and + <FilesMatch> done simultaneously
<Location> and + <LocationMatch> done simultaneously

+ +

Apart from <Directory>, each group is + processed in the order that they appear in the configuration + files. <Directory> (group 1 above) is + processed in the order shortest directory component to longest. + If multiple <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 directive will be treated as if + they were inside the including file at the location of the + Include directive.

+ +

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.

+ +

Later sections override earlier ones.

+ +

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>.
If you are attempting to match objects at the URL level + then you must use <Location>

+ +

But a notable exception 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 + language should probably switch this to + <Location>.

+ +

Note about .htaccess parsing:

+ +

Modifying .htaccess parsing during Location doesn't do + anything because .htaccess parsing has already occurred.

+ +

<Location> and symbolic links:

+ +

It is not possible to use "Options + FollowSymLinks" or "Options + SymLinksIfOwnerMatch" inside a + <Location>, + <LocationMatch> or + <DirectoryMatch> section (the options are + simply ignored). Using the options in question is only + possible inside a <Directory> section (or + a .htaccess file).

+ +

<Files> and Options:

+ +

Apache won't check for it, but using an + Options directive inside a + <Files> section has no effect.

+ +

Another note:

+ +

There is actually a + <Location>/<LocationMatch> + sequence performed just before the name translation phase + (where 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 7d91191a6c2..9782a63a7ba 100644 --- a/docs/manual/sections.html.en +++ b/docs/manual/sections.html.en @@ -1,163 +1,152 @@ - - -How Directory, Location and Files sections work - - - - - - -

How Directory, Location and Files sections work

- -

Directives allowed in the sections

- -

How the sections are merged

- -

The order of merging is:

- -

- - <Directory> (except regular expressions) and - .htaccess done simultaneously (with .htaccess, if allowed, overriding - <Directory>) - -
- <DirectoryMatch>, and - <Directory> with regular expressions - -
<Files> and <FilesMatch> done - simultaneously -
<Location> and <LocationMatch> done - simultaneously -

- -

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.

- -

Later sections override earlier ones.

- -

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>. -
- If you are attempting to match objects at the URL level then you - must use <Location> -

- -

But a notable exception 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 - language should probably switch this to - <Location>. -

- -

Note about .htaccess parsing:

- -

- Modifying .htaccess parsing during Location doesn't do - anything because .htaccess parsing has already occurred. -

- -

<Location> and symbolic links:

- -

- It is not possible to use "Options FollowSymLinks" - or "Options SymLinksIfOwnerMatch" inside a - <Location>, <LocationMatch> - or <DirectoryMatch> section - (the options are simply ignored). - Using the options in question is only possible inside a - <Directory> section (or a .htaccess file). -

- -

<Files> and Options:

- -

- Apache won't check for it, but using an Options - directive inside a <Files> section has no effect. -

- -

Another note:

- -

- There is actually a - <Location>/<LocationMatch> - sequence performed just before the name translation phase (where - Aliases and DocumentRoots are used to - map URLs to filenames). The results of this sequence are - completely thrown away after the translation has completed. -

- - - - + + + + + + + How Directory, Location and Files sections work + + + + + + +

How Directory, Location and Files sections + work

+ +

Directives allowed in the sections

+ +

How the sections are merged

+ +

The order of merging is:

+ +

<Directory> (except regular + expressions) and .htaccess done simultaneously (with + .htaccess, if allowed, overriding + <Directory>)
<DirectoryMatch>, and + <Directory> with regular expressions
<Files> and + <FilesMatch> done simultaneously
<Location> and + <LocationMatch> done simultaneously

+ +

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.

+ +

Later sections override earlier ones.

+ +

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>.
If you are attempting to match objects at the URL level + then you must use <Location>

+ +

But a notable exception 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 + language should probably switch this to + <Location>.

+ +

Note about .htaccess parsing:

+ +

Modifying .htaccess parsing during Location doesn't do + anything because .htaccess parsing has already occurred.

+ +

<Location> and symbolic links:

+ +

It is not possible to use "Options + FollowSymLinks" or "Options + SymLinksIfOwnerMatch" inside a + <Location>, + <LocationMatch> or + <DirectoryMatch> section (the options are + simply ignored). Using the options in question is only + possible inside a <Directory> section (or + a .htaccess file).

+ +

<Files> and Options:

+ +

Apache won't check for it, but using an + Options directive inside a + <Files> section has no effect.

+ +

Another note:

+ +

There is actually a + <Location>/<LocationMatch> + sequence performed just before the name translation phase + (where 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/server-wide.html.en b/docs/manual/server-wide.html.en index bf8fa72a3ff..f2c932bef89 100644 --- a/docs/manual/server-wide.html.en +++ b/docs/manual/server-wide.html.en @@ -1,113 +1,134 @@ - - - -Server-Wide Configuration - - - - - -

Server-Wide Configuration

- -

This document explains some of the directives provided by the -core server which are used to configure -the basic operations of the server.

- -

Server Identification
File Locations
Limiting Resource Usage

- -

Server Identification

- - -

-Related Directives

- -ServerName
-ServerAdmin
-ServerSignature
-ServerTokens
-UseCanonicalName
-

- -

The ServerAdmin and ServerTokens -directives control what information about the server will be presented -in server-generated documents such as error messages. -The ServerTokens directive sets the value of the -Server HTTP response header field.

- -

The ServerName and UseCanonicalName -directives are used by the server to determine how to construct -self-referential URLs. For example, when a client requests a -directory, but does not include the trailing slash in the directory -name, Apache must redirect the client to the full name including the -trailing slash so that the client will correctly resolve relative -references in the document.

- -

File Locations

- - -

-Related Directives

- -CoreDumpDirectory
-DocumentRoot
-ErrorLog
-Lockfile
-PidFile
-ScoreBoardFile
-ServerRoot
-

- -

These directives control the locations of the various files that -Apache needs for proper operation. When the pathname used does not -begin with a slash "/", the files are located relative to the -ServerRoot. Be careful about locating files in paths -which are writable by non-root users. See the security tips documentation for -more details.

- -

Limiting Resource Usage

- -

-Related Directives

- -LimitRequestBody
-LimitRequestFields
-LimitRequestFieldsize
-LimitRequestLine
-RLimitCPU
-RLimitMEM
-RLimitNPROC
-ThreadStackSize
-

- -

The LimitRequest* directives are used to place limits -on the amount of resources Apache will use in reading requests -from clients. By limiting these values, some kinds of denial -of service attacks can be mitigated.

- -

The RLimit* directives are used to limit the amount -of resources which can be used by processes forked off from -the Apache children. In particular, this will control -resources used by CGI scripts and SSI exec commands.

- -

The ThreadStackSize directive is used only -on Netware to control the stack size.

- - - - + + + + + + + Server-Wide Configuration + + + + + + +

Server-Wide Configuration

+ +

This document explains some of the directives provided by + the core server which are used to + configure the basic operations of the server.

+ +

Server Identification
File Locations
Limiting Resource Usage

+ +

Server + Identification

+ + + + + +

Related Directives
+
+ ServerName
+ ServerAdmin
+ ServerSignature
+ ServerTokens
+ UseCanonicalName
+

+ +

The ServerAdmin and ServerTokens + directives control what information about the server will be + presented in server-generated documents such as error messages. + The ServerTokens directive sets the value of the + Server HTTP response header field.

+ +

The ServerName and + UseCanonicalName directives are used by the server + to determine how to construct self-referential URLs. For + example, when a client requests a directory, but does not + include the trailing slash in the directory name, Apache must + redirect the client to the full name including the trailing + slash so that the client will correctly resolve relative + references in the document.

+ +

File Locations

+ + + + + +

Related Directives
+
+ CoreDumpDirectory
+ DocumentRoot
+ ErrorLog
+ Lockfile
+ PidFile
+ ScoreBoardFile
+ ServerRoot
+

+ +

These directives control the locations of the various files + that Apache needs for proper operation. When the pathname used + does not begin with a slash "/", the files are located relative + to the ServerRoot. Be careful about locating files + in paths which are writable by non-root users. See the security tips documentation + for more details.

+ +

Limiting Resource + Usage

+ + + + + +

Related Directives
+
+ LimitRequestBody
+ LimitRequestFields
+ LimitRequestFieldsize
+ LimitRequestLine
+ RLimitCPU
+ RLimitMEM
+ RLimitNPROC
+ ThreadStackSize
+

+ +

The LimitRequest* directives are used to place + limits on the amount of resources Apache will use in reading + requests from clients. By limiting these values, some kinds of + denial of service attacks can be mitigated.

+ +

The RLimit* directives are used to limit the + amount of resources which can be used by processes forked off + from the Apache children. In particular, this will control + resources used by CGI scripts and SSI exec commands.

+ +

The ThreadStackSize directive is used only on + Netware to control the stack size.

+ + + + diff --git a/docs/manual/server-wide.html.ja.jis b/docs/manual/server-wide.html.ja.jis index 1ed7d254abc..06a2424c031 100644 --- a/docs/manual/server-wide.html.ja.jis +++ b/docs/manual/server-wide.html.ja.jis @@ -1,113 +1,20 @@ - - - -Server-Wide Configuration - - + - - - -

$B%5!<%PA4BN$N@_Dj(B

+ + + -

$B$3$N%I%-%e%a%s%H$G$O(B$B%3%"(B$B%5!<%P$N(B -$B%G%#%l%/%F%#%V$NCf$G!"4pK\F0:n$r@_Dj$9$k$?$a$N$b$N$r@bL@$7$^$9!#(B

+ Server-Wide Configuration + + + -

$B%5!<%P(B ID
$B%U%!%$%k$N0LCV(B
$B%j%=!<%9$N@)8B(B

+ + -

- -

$B%5!<%P(B ID

- - -

-$B4XO"%G%#%l%/%F%#%V(B

- -ServerName
-ServerAdmin
-ServerSignature
-ServerTokens
-UseCanonicalName
-

- -

ServerAdmin $B%G%#%l%/%F%#%V$H(B ServerTokens -$B%G%#%l%/%F%#%V$O!"%(%i!<%a%C%;!<%8$J$I$N%5!<%P$,:n$k%I%-%e%a%s%H$K!"(B -$B$I$N$h$&$J%5!<%P$N>pJs$rI=<($9$k$+$r@)8f$7$^$9!#(BServerTokens -$B%G%#%l%/%F%#%V$O!"(BServer HTTP $B%l%9%]%s%9%X%C%@%U%#!<%k%I$NCM$r(B -$B@_Dj$7$^$9!#(B

- -

ServerName $B%G%#%l%/%F%#%V$H(B UseCanonicalName -$B%G%#%l%/%F%#%V$O!"%5!<%P$,<+J,<+?H$r;2>H$9$k(B URL $B$r:n$k$H$-$K(B -$B;H$o$l$^$9!#$?$H$($P!"%/%i%$%"%s%H$,%G%#%l%/%H%j$rMW5a$7$F!"(B -$B$=$N%G%#%l%/%H%jL>$N:G8e$K%9%i%C%7%e$,IU$$$F$$$J$$$h$&$J>l9g$K$O!"(B -$B%I%-%e%a%s%H$NAjBPE*$J;2>H$r@5$7$/2r7h$G$-$k$h$&$K$9$k$?$a$K!"(B -Apache $B$O:G8e$N%9%i%C%7%e$r4^$s$@40A4$J%Q%9$K%/%i%$%"%s%H$r(B -$B%j%@%$%l%/%H$5$;$kI,MW$,$"$j$^$9!#(B

- -

$B%U%!%$%k$N0LCV(B

- - -

-$B4XO"%G%#%l%/%F%#%V(B

- -CoreDumpDirectory
-DocumentRoot
-ErrorLog
-Lockfile
-PidFile
-ScoreBoardFile
-ServerRoot
-

- -

$B$3$l$i$N%G%#%l%/%F%#%V$O(B Apache $B$,E,@Z$JF0:n$r$9$k$?$a$KI,MW$J(B -$B3FServerRoot $B$+$i$NAjBP%Q%9$H$7$F(B -$BC5$5$l$^$9!#(Broot $B0J30$N%f!<%6$,=q$-9~$_2DG=$J%Q%9$K%U%!%$%k$r(B -$BCV$/>l9g$OCm0U$,I,MW$G$9!#>\:Y$O(B$B!V%;%-%e%j%F%#>pJs!W(B$B$r(B -$B;2>H$7$F$/$@$5$$!#(B

- -

$B%j%=!<%9$N@)8B(B

- -

-$B4XO"%G%#%l%/%F%#%V(B

- -LimitRequestBody
-LimitRequestFields
-LimitRequestFieldsize
-LimitRequestLine
-RLimitCPU
-RLimitMEM
-RLimitNPROC
-ThreadStackSize
-

- -

LimitRequest* $B%G%#%l%/%F%#%V$O(B Apache $B$,(B -$B%/%i%$%"%s%H$+$i$N%j%/%(%9%HFI$_9~$_$G;H$&%j%=!<%9$r@)8B$9$k$?$a$K(B -$B;H$o$l$^$9!#$3$l$i$NCM$r@)8B$9$k$3$H$G!"$$$/$D$+$N%5!<%S%95qH]967b$O(B -$B1F6A$rOB$i$2$k$3$H$,$G$-$^$9!#(B

- -

RLimit* $B%G%#%l%/%F%#%V$O!"(BApache $B$N;R%W%m%;%9$+$i(B -fork $B$5$l$?%W%m%;%9$,;HMQ$9$k%j%=!<%9$r@)8B$9$k$?$a$K(B -$B;H$o$l$^$9!#FC$K!"$3$l$O(B CGI $B%9%/%j%W%H$H(B SSI exec $B%3%^%s%I$G(B -$B;H$o$l$k%j%=!<%9$r@)8f$7$^$9!#(B

- -

ThreadStackSize $B$O(B Netware $B$G$N$_!"%9%?%C%/$NBg$-$5$r(B -$B@)8f$9$k$?$a$K;H$o$l$^$9!#(B

- - - +

$B%5!

+ + diff --git a/docs/manual/stopping.html b/docs/manual/stopping.html index 8830c6cdbc0..89c1a58a3e3 100644 --- a/docs/manual/stopping.html +++ b/docs/manual/stopping.html @@ -1,197 +1,209 @@ - - - -Stopping and Restarting the Server - - - - - -

Stopping and Restarting the Server

- -

This document covers stopping and restarting Apache on Unix-like -systems. Windows users should see Signalling Apache when -running.

- -

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 -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 -be described in a moment. - -

To send a signal to the parent you should issue a command such as: -

+ + + + + + + Stopping and Restarting the Server + + + + + + +

Stopping and Restarting the Server

+ +

This document covers stopping and restarting Apache on + Unix-like systems. Windows users should see Signalling Apache when + running.

+ +

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 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 be described in a moment.

+ +

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: -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.
-
-A shell script called apachectl is provided which
-automates the processing of signalling Apache.  For details about this
-script, see the documentation on starting
-Apache.
-
-Stop Now
-
-Signal: TERM

-apachectl stop
-
-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
-further requests are served.
-
-
Graceful Restart
-
-Signal: USR1

-apachectl graceful
-
-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
-configuration, which begins serving new requests immediately.
-
-On certain platforms that do not allow USR1 to be used for a graceful
-restart, an alternative signal may be used (such as WINCH).  apachectl
-graceful will send the right signal for your platform.
-
-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
-will notice that the server statistics
-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
-of all children across generations.
-
-
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
-pre-restart log have finished.  We suggest that you use a suitable delay
-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 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 the children which
-are "gracefully exiting" by handling their last request.)  This will
-cause problems if you attempt to restart the server -- it will not be
-able to bind to its listening ports.  Before doing a restart, you can
-check the syntax of the configuration files with the -t
-command line argument (see httpd). This still will not guarantee
-that the server will restart correctly. To check the semantics of the
-configuration files as well as the syntax, you can try starting httpd
-as a non-root user.  If there are no errors it will attempt to open
-its sockets and logs and fail because it's not root (or because the
-currently running httpd already has those ports bound).  If it fails
-for any other reason then it's probably a config file error and the
-error should be fixed before issuing the graceful restart.
-
-
-
Restart Now
-
-Signal: HUP

-apachectl restart
-
-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
-will notice that the server statistics are
-set to zero when a HUP is sent.
-
-
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.
-
-
-
Appendix: signals and 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
-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
-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
-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
-around, but fortunately most architectures do not require a scoreboard file.
-See the ScoreBoardFile documentation for a
-architecture uses it.
-
-
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
-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
-too late to make 1.2.  In theory this isn't an issue because the KeepAlive
-client has to expect these events because of network latencies and
-server timeouts.  In practice it doesn't seem to affect anything either
--- in a test case the server was restarted twenty times per second and
-clients successfully browsed the site without getting broken images or
-empty documents.
-
-
-
-
+

+ Modify those examples to match your ServerRoot and PidFile settings. + +

A shell script called apachectl is provided which + automates the processing of signalling Apache. For details + about this script, see the documentation on starting Apache.

+ +

Stop Now

+ +

Signal: TERM
+ apachectl stop

+ +

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 further requests are served.

+ +

Graceful Restart

+ +

Signal: USR1
+ apachectl graceful

+ +

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 configuration, which begins serving new requests + immediately.

+ On certain platforms that do not allow USR1 to be used for a + graceful restart, an alternative signal may be used (such as + WINCH). apachectl graceful will send the right signal for your + platform. + +

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 + will notice that the server statistics 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 of all children across + generations.

+ +

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 pre-restart log have finished. We suggest that you use a + suitable delay 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 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 the children which are "gracefully exiting" by + handling their last request.) This will cause problems if you + attempt to restart the server -- it will not be able to bind to + its listening ports. Before doing a restart, you can check the + syntax of the configuration files with the -t + command line argument (see httpd). This still will not + guarantee that the server will restart correctly. To check the + semantics of the configuration files as well as the syntax, you + can try starting httpd as a non-root user. If there are no + errors it will attempt to open its sockets and logs and fail + because it's not root (or because the currently running httpd + already has those ports bound). If it fails for any other + reason then it's probably a config file error and the error + should be fixed before issuing the graceful restart.

+ +

Restart Now

+ +

Signal: HUP
+ apachectl restart

+ +

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 + will notice that the server statistics are set to zero when a + HUP is sent.

+ +

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.

+ +

Appendix: signals and 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 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 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 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 around, but fortunately + most architectures do not require a scoreboard file. See the ScoreBoardFile + documentation for a architecture uses it.

+ +

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 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 too late to make 1.2. In + theory this isn't an issue because the KeepAlive client has to + expect these events because of network latencies and server + timeouts. In practice it doesn't seem to affect anything either + -- in a test case the server was restarted twenty times per + second and clients successfully browsed the site without + getting broken images or empty documents. + +

+ + + diff --git a/docs/manual/stopping.html.en b/docs/manual/stopping.html.en index 8830c6cdbc0..89c1a58a3e3 100644 --- a/docs/manual/stopping.html.en +++ b/docs/manual/stopping.html.en @@ -1,197 +1,209 @@ - - - -Stopping and Restarting the Server - - - - - -

Stopping and Restarting the Server

- -

This document covers stopping and restarting Apache on Unix-like -systems. Windows users should see Signalling Apache when -running.

- -

To send a signal to the parent you should issue a command such as: -

+ + + + + + + Stopping and Restarting the Server + + + + + + +

Stopping and Restarting the Server

+ +

This document covers stopping and restarting Apache on + Unix-like systems. Windows users should see Signalling Apache when + running.

+ +

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: -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.
-
-A shell script called apachectl is provided which
-automates the processing of signalling Apache.  For details about this
-script, see the documentation on starting
-Apache.
-
-Stop Now
-
-Signal: TERM

-apachectl stop
-
-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
-further requests are served.
-
-
Graceful Restart
-
-Signal: USR1

-apachectl graceful
-
-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
-configuration, which begins serving new requests immediately.
-
-On certain platforms that do not allow USR1 to be used for a graceful
-restart, an alternative signal may be used (such as WINCH).  apachectl
-graceful will send the right signal for your platform.
-
-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
-will notice that the server statistics
-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
-of all children across generations.
-
-
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
-pre-restart log have finished.  We suggest that you use a suitable delay
-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 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 the children which
-are "gracefully exiting" by handling their last request.)  This will
-cause problems if you attempt to restart the server -- it will not be
-able to bind to its listening ports.  Before doing a restart, you can
-check the syntax of the configuration files with the -t
-command line argument (see httpd). This still will not guarantee
-that the server will restart correctly. To check the semantics of the
-configuration files as well as the syntax, you can try starting httpd
-as a non-root user.  If there are no errors it will attempt to open
-its sockets and logs and fail because it's not root (or because the
-currently running httpd already has those ports bound).  If it fails
-for any other reason then it's probably a config file error and the
-error should be fixed before issuing the graceful restart.
-
-
-
Restart Now
-
-Signal: HUP

-apachectl restart
-
-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
-will notice that the server statistics are
-set to zero when a HUP is sent.
-
-
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.
-
-
-
Appendix: signals and 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
-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
-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
-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
-around, but fortunately most architectures do not require a scoreboard file.
-See the ScoreBoardFile documentation for a
-architecture uses it.
-
-
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
-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
-too late to make 1.2.  In theory this isn't an issue because the KeepAlive
-client has to expect these events because of network latencies and
-server timeouts.  In practice it doesn't seem to affect anything either
--- in a test case the server was restarted twenty times per second and
-clients successfully browsed the site without getting broken images or
-empty documents.
-
-
-
-
+

+ Modify those examples to match your ServerRoot and PidFile settings. + +

A shell script called apachectl is provided which + automates the processing of signalling Apache. For details + about this script, see the documentation on starting Apache.

+ +

Stop Now

+ +

Signal: TERM
+ apachectl stop

+ +

Graceful Restart

+ +

Signal: USR1
+ apachectl graceful

+ +

The status module will also use a G to indicate + those children which are still serving requests started before + the graceful restart was given.

+ +

Restart Now

+ +

Signal: HUP
+ apachectl restart

+ +

Users of the status module + will notice that the server statistics are set to zero when a + HUP is sent.

+ +

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.

+ +

Appendix: signals and race conditions

+ +

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

+ +

+ + + diff --git a/docs/manual/suexec.html b/docs/manual/suexec.html index 8988cd42b8f..c4da9defb71 100644 --- a/docs/manual/suexec.html +++ b/docs/manual/suexec.html @@ -1,370 +1,463 @@ - - - -Apache suEXEC Support - - - - - -

Apache suEXEC Support

- -

CONTENTS
What is suEXEC?
Before we begin.
suEXEC Security Model.
Configuring & Installing suEXEC
Enabling & Disabling suEXEC
Using suEXEC
Debugging suEXEC
Beware the Jabberwock: Warnings & - Examples

- -

What is suEXEC?

-The suEXEC feature -- introduced in Apache 1.2 -- provides -Apache users the ability to run CGI and SSI -programs under user IDs different from the user ID of the calling web-server. -Normally, when a CGI or SSI program executes, it runs as the same user who is -running the web server. -

- -

-Used properly, this feature can reduce considerably the security risks involved -with allowing users to develop and run private CGI or SSI programs. However, -if suEXEC is improperly configured, it can cause any number of problems and -possibly create new holes in your computer's security. If you aren't familiar -with managing setuid root programs and the security issues they present, we -highly recommend that you not consider using suEXEC. -

- -

-BACK TO CONTENTS -

- -

Before we begin.

-Before jumping head-first into this document, you should be aware of the -assumptions made on the part of the Apache Group and this document. -

- -

-First, it is assumed that you are using a UNIX derivate operating system that -is capable of setuid and setgid operations. -All command examples are given in this regard. Other platforms, if they are -capable of supporting suEXEC, may differ in their configuration. -

- -

-Second, it is assumed you are familiar with some basic concepts of your -computer's security and its administration. This involves an understanding -of setuid/setgid operations and the various effects they -may have on your system and its level of security. -

- -

-Third, it is assumed that you are using an unmodified -version of suEXEC code. All code for suEXEC has been carefully scrutinized and -tested by the developers as well as numerous beta testers. Every precaution -has been taken to ensure a simple yet solidly safe base of code. Altering this -code can cause unexpected problems and new security risks. It is -highly recommended you not alter the suEXEC code unless you -are well versed in the particulars of security programming and are willing to -share your work with the Apache Group for consideration. -

- -

-Fourth, and last, it has been the decision of the Apache Group to -NOT make suEXEC part of the default installation of Apache. -To this end, suEXEC configuration requires of the administrator careful -attention to details. After due consideration has been given to the various -settings for suEXEC, the administrator may install suEXEC through normal -installation methods. The values for these settings need to be carefully -determined and specified by the administrator to properly maintain system -security during the use of suEXEC functionality. It is through this detailed -process that the Apache Group hopes to limit suEXEC installation only to those -who are careful and determined enough to use it. -

- -

-Still with us? Yes? Good. Let's move on! -

- -

-BACK TO CONTENTS -

- -

suEXEC Security Model

-Before we begin configuring and installing suEXEC, we will first discuss -the security model you are about to implement. By doing so, you may -better understand what exactly is going on inside suEXEC and what precautions -are taken to ensure your system's security. -

- -

-suEXEC is based on a setuid "wrapper" program that is -called by the main Apache web server. This wrapper is called when an HTTP -request is made for a CGI or SSI program that the administrator has designated -to run as a userid other than that of the main server. When such a request -is made, Apache provides the suEXEC wrapper with the program's name and the -user and group IDs under which the program is to execute. -

- -

-The wrapper then employs the following process to determine success or -failure -- if any one of these conditions fail, the program logs the failure -and exits with an error, otherwise it will continue: -

Was the wrapper called with the proper number of - arguments? -
- The wrapper will only execute if it is given the proper number of arguments. - The proper argument format is known to the Apache web server. If the - wrapper - is not receiving the proper number of arguments, it is either being hacked, - or - there is something wrong with the suEXEC portion of your Apache binary. -
-
Is the user executing this wrapper a valid user of this - system? -
- This is to ensure that the user executing the wrapper is truly a user of the - system. -
-
Is this valid user allowed to run the wrapper? -
- Is this user the user allowed to run this wrapper? Only one user (the - Apache user) is allowed to execute this program. -
-
Does the target program have an unsafe hierarchical - reference? -
- Does the target program contain a leading '/' or have a '..' backreference? - These are not allowed; the target program must reside within the Apache - webspace. -
-
Is the target user name valid? -
- Does the target user exist? -
-
Is the target group name valid? -
- Does the target group exist? -
-
Is the target user NOT superuser? -
- Presently, suEXEC does not allow 'root' to execute CGI/SSI programs. -
-
Is the target userid ABOVE the minimum ID - number? -
- The minimum user ID number is specified during configuration. This allows - you - to set the lowest possible userid that will be allowed to execute CGI/SSI - programs. This is useful to block out "system" accounts. -
-
Is the target group NOT the superuser group? -
- Presently, suEXEC does not allow the 'root' group to execute CGI/SSI - programs. -
-
Is the target groupid ABOVE the minimum ID - number? -
- The minimum group ID number is specified during configuration. This allows - you - to set the lowest possible groupid that will be allowed to execute CGI/SSI - programs. This is useful to block out "system" groups. -
-
Can the wrapper successfully become the target user and - group? -
- Here is where the program becomes the target user and group via setuid and - setgid - calls. The group access list is also initialized with all of the groups - of which - the user is a member. -
-
Does the directory in which the program resides exist? -
- If it doesn't exist, it can't very well contain files. -
-
Is the directory within the Apache webspace? -
- If the request is for a regular portion of the server, is the requested - directory - within the server's document root? If the request is for a UserDir, is - the requested - directory within the user's document root? -
-
Is the directory NOT writable by anyone else? -
- We don't want to open up the directory to others; only the owner user - may be able - to alter this directories contents. -
-
Does the target program exist? -
- If it doesn't exists, it can't very well be executed. -
-
Is the target program NOT writable by anyone - else? -
- We don't want to give anyone other than the owner the ability to - change the program. -
-
Is the target program NOT setuid or setgid? -
- We do not want to execute programs that will then change our UID/GID again. -
-
Is the target user/group the same as the program's - user/group? -
- Is the user the owner of the file? -
-
Can we successfully clean the process environment to - ensure safe operations? -
- suEXEC cleans the process' environment by establishing a safe - execution PATH (defined - during configuration), as well as only passing through those - variables whose names - are listed in the safe environment list (also created during - configuration). -
-
Can we successfully become the target program and - execute? -
- Here is where suEXEC ends and the target program begins. -
-

- -

-This is the standard operation of the the suEXEC wrapper's security model. -It is somewhat stringent and can impose new limitations and guidelines for -CGI/SSI design, but it was developed carefully step-by-step with security -in mind. -

- -

-For more information as to how this security model can limit your possibilities -in regards to server configuration, as well as what security risks can be -avoided with a proper suEXEC setup, see the -"Beware the Jabberwock" -section of this document. -

- -

-BACK TO CONTENTS -

- -

Configuring & Installing suEXEC

-Here's where we begin the fun. If you use Apache 1.2 or prefer to configure -Apache 1.3 with the "src/Configure" script you have to edit -the suEXEC header file and install the binary in its proper location -manually. The following sections describe the configuration and installation -for Apache 1.3 with the AutoConf-style interface (APACI). -

- -

-APACI's suEXEC configuration options
-

--enable-suexec -: This option enables the suEXEC feature which is never installed or - activated by default. At least one --suexec-xxxxx option has to be - provided together with the --enable-suexec option to let APACI - accept your request for using the suEXEC feature. -
--suexec-caller=UID -: The username under which - Apache normally runs. - This is the only user allowed to execute this program. -
--suexec-docroot=DIR -: Define as the DocumentRoot set for Apache. - This will be the only hierarchy (aside from UserDirs) - that can be used for suEXEC behavior. - The default directory is the --datadir value with - the suffix "/htdocs", e.g. if you configure with - "--datadir=/home/apache" the directory - "/home/apache/htdocs" is used as document root for - the suEXEC wrapper. -
--suexec-logfile=FILE -: This defines the filename to which all suEXEC transactions and - errors are logged (useful for auditing and debugging purposes). - By default the logfile is named "suexec_log" and located in your - standard logfile directory (--logfiledir). -
--suexec-userdir=DIR -: Define to be the subdirectory under users' - home directories where suEXEC access should - be allowed. All executables under this directory - will be executable by suEXEC as the user so - they should be "safe" programs. If you are - using a "simple" UserDir directive (ie. one - without a "*" in it) this should be set to - the same value. suEXEC will not work properly - in cases where the UserDir directive points to - a location that is not the same as the user's - home directory as referenced in the passwd file. - Default value is "public_html". -
- If you have virtual hosts with a different - UserDir for each, you will need to define them to - all reside in one parent directory; then name that - parent directory here. If this is not defined - properly, "~userdir" cgi requests will not work! -
--suexec-uidmin=UID -: Define this as the lowest UID allowed to be a target user - for suEXEC. For most systems, 500 or 100 is common. - Default value is 100. -
--suexec-gidmin=GID -: Define this as the lowest GID allowed to be a target group - for suEXEC. For most systems, 100 is common and therefore - used as default value. -
--suexec-safepath=PATH -: Define a safe PATH environment to pass to CGI executables. - Default value is "/usr/local/bin:/usr/bin:/bin". -

- -

-Checking your suEXEC setup
-Before you compile and install the suEXEC wrapper you can check -the configuration with the --layout option. -
-Example output: -

+
+
+
+  
+    
+
+    Apache suEXEC Support
+  
+  
+
+  
+    
+
+    Apache suEXEC Support
+
+    
+      CONTENTS
+
+      What is suEXEC?
+
+      Before we begin.
+
+      suEXEC Security Model.
+
+      Configuring & Installing
+      suEXEC
+
+      Enabling & Disabling
+      suEXEC
+
+      Using suEXEC
+
+      Debugging suEXEC
+
+      Beware the Jabberwock: Warnings
+      & Examples
+    
+    

+     

+     
+
+    What is suEXEC?
+
+    The suEXEC feature --
+    introduced in Apache 1.2 -- provides Apache users the ability
+    to run CGI and SSI programs
+    under user IDs different from the user ID of the calling
+    web-server. Normally, when a CGI or SSI program executes, it
+    runs as the same user who is running the web server.
+
+    Used properly, this feature can reduce
+    considerably the security risks involved with allowing users to
+    develop and run private CGI or SSI programs. However, if suEXEC
+    is improperly configured, it can cause any number of problems
+    and possibly create new holes in your computer's security. If
+    you aren't familiar with managing setuid root programs and the
+    security issues they present, we highly recommend that you not
+    consider using suEXEC.
+
+    BACK TO
+    CONTENTS
+
+    Before we begin.
+
+    Before jumping head-first into this document,
+    you should be aware of the assumptions made on the part of the
+    Apache Group and this document.
+
+    First, it is assumed that you are using a UNIX
+    derivate operating system that is capable of
+    setuid and setgid operations.
+    All command examples are given in this regard. Other platforms,
+    if they are capable of supporting suEXEC, may differ in their
+    configuration.
+
+    Second, it is assumed you are familiar with
+    some basic concepts of your computer's security and its
+    administration. This involves an understanding of
+    setuid/setgid operations and the various
+    effects they may have on your system and its level of
+    security.
+
+    Third, it is assumed that you are using an
+    unmodified version of suEXEC code. All code
+    for suEXEC has been carefully scrutinized and tested by the
+    developers as well as numerous beta testers. Every precaution
+    has been taken to ensure a simple yet solidly safe base of
+    code. Altering this code can cause unexpected problems and new
+    security risks. It is highly recommended you
+    not alter the suEXEC code unless you are well versed in the
+    particulars of security programming and are willing to share
+    your work with the Apache Group for consideration.
+
+    Fourth, and last, it has been the decision of
+    the Apache Group to NOT make suEXEC part of
+    the default installation of Apache. To this end, suEXEC
+    configuration requires of the administrator careful attention
+    to details. After due consideration has been given to the
+    various settings for suEXEC, the administrator may install
+    suEXEC through normal installation methods. The values for
+    these settings need to be carefully determined and specified by
+    the administrator to properly maintain system security during
+    the use of suEXEC functionality. It is through this detailed
+    process that the Apache Group hopes to limit suEXEC
+    installation only to those who are careful and determined
+    enough to use it.
+
+    Still with us? Yes? Good. Let's move on!
+
+    BACK TO
+    CONTENTS
+
+    suEXEC Security Model
+
+    Before we begin configuring and installing
+    suEXEC, we will first discuss the security model you are about
+    to implement. By doing so, you may better understand what
+    exactly is going on inside suEXEC and what precautions are
+    taken to ensure your system's security.
+
+    suEXEC is based on a setuid
+    "wrapper" program that is called by the main Apache web server.
+    This wrapper is called when an HTTP request is made for a CGI
+    or SSI program that the administrator has designated to run as
+    a userid other than that of the main server. When such a
+    request is made, Apache provides the suEXEC wrapper with the
+    program's name and the user and group IDs under which the
+    program is to execute.
+
+    The wrapper then employs the following process
+    to determine success or failure -- if any one of these
+    conditions fail, the program logs the failure and exits with an
+    error, otherwise it will continue:
+
+    
+      
+        Was the wrapper called with the proper number of
+        arguments? 
+
+        
+          The wrapper will only execute if it is given the proper
+          number of arguments. The proper argument format is known
+          to the Apache web server. If the wrapper is not receiving
+          the proper number of arguments, it is either being
+          hacked, or there is something wrong with the suEXEC
+          portion of your Apache binary.
+        
+      
+
+      
+        Is the user executing this wrapper a valid user of
+        this system? 
+
+        
+          This is to ensure that the user executing the wrapper is
+          truly a user of the system.
+        
+      
+
+      
+        Is this valid user allowed to run the
+        wrapper? 
+
+        
+          Is this user the user allowed to run this wrapper? Only
+          one user (the Apache user) is allowed to execute this
+          program.
+        
+      
+
+      
+        Does the target program have an unsafe hierarchical
+        reference? 
+
+        
+          Does the target program contain a leading '/' or have a
+          '..' backreference? These are not allowed; the target
+          program must reside within the Apache webspace.
+        
+      
+
+      
+        Is the target user name valid? 
+
+        
+          Does the target user exist?
+        
+      
+
+      
+        Is the target group name valid? 
+
+        
+          Does the target group exist?
+        
+      
+
+      
+        Is the target user NOT superuser?
+        
+
+        
+          Presently, suEXEC does not allow 'root' to execute
+          CGI/SSI programs.
+        
+      
+
+      
+        Is the target userid ABOVE the minimum ID
+        number? 
+
+        
+          The minimum user ID number is specified during
+          configuration. This allows you to set the lowest possible
+          userid that will be allowed to execute CGI/SSI programs.
+          This is useful to block out "system" accounts.
+        
+      
+
+      
+        Is the target group NOT the superuser
+        group? 
+
+        
+          Presently, suEXEC does not allow the 'root' group to
+          execute CGI/SSI programs.
+        
+      
+
+      
+        Is the target groupid ABOVE the minimum ID
+        number? 
+
+        
+          The minimum group ID number is specified during
+          configuration. This allows you to set the lowest possible
+          groupid that will be allowed to execute CGI/SSI programs.
+          This is useful to block out "system" groups.
+        
+      
+
+      
+        Can the wrapper successfully become the target user
+        and group? 
+
+        
+          Here is where the program becomes the target user and
+          group via setuid and setgid calls. The group access list
+          is also initialized with all of the groups of which the
+          user is a member.
+        
+      
+
+      
+        Does the directory in which the program resides
+        exist? 
+
+        
+          If it doesn't exist, it can't very well contain files.
+        
+      
+
+      
+        Is the directory within the Apache
+        webspace? 
+
+        
+          If the request is for a regular portion of the server, is
+          the requested directory within the server's document
+          root? If the request is for a UserDir, is the requested
+          directory within the user's document root?
+        
+      
+
+      
+        Is the directory NOT writable by anyone
+        else? 
+
+        
+          We don't want to open up the directory to others; only
+          the owner user may be able to alter this directories
+          contents.
+        
+      
+
+      
+        Does the target program exist? 
+
+        
+          If it doesn't exists, it can't very well be executed.
+        
+      
+
+      
+        Is the target program NOT writable by
+        anyone else? 
+
+        
+          We don't want to give anyone other than the owner the
+          ability to change the program.
+        
+      
+
+      
+        Is the target program NOT setuid or
+        setgid? 
+
+        
+          We do not want to execute programs that will then change
+          our UID/GID again.
+        
+      
+
+      
+        Is the target user/group the same as the program's
+        user/group? 
+
+        
+          Is the user the owner of the file?
+        
+      
+
+      
+        Can we successfully clean the process environment
+        to ensure safe operations? 
+
+        
+          suEXEC cleans the process' environment by establishing a
+          safe execution PATH (defined during configuration), as
+          well as only passing through those variables whose names
+          are listed in the safe environment list (also created
+          during configuration).
+        
+      
+
+      
+        Can we successfully become the target program and
+        execute? 
+
+        
+          Here is where suEXEC ends and the target program begins.
+        
+      
+    
+    

+     

+     
+
+    This is the standard operation of the the
+    suEXEC wrapper's security model. It is somewhat stringent and
+    can impose new limitations and guidelines for CGI/SSI design,
+    but it was developed carefully step-by-step with security in
+    mind.
+
+    For more information as to how this security
+    model can limit your possibilities in regards to server
+    configuration, as well as what security risks can be avoided
+    with a proper suEXEC setup, see the "Beware the Jabberwock" section of this
+    document.
+
+    BACK TO
+    CONTENTS
+
+    Configuring & Installing
+    suEXEC
+
+    Here's where we begin the fun. If you use
+    Apache 1.2 or prefer to configure Apache 1.3 with the
+    "src/Configure" script you have to edit the suEXEC
+    header file and install the binary in its proper location
+    manually. The following sections describe the configuration and
+    installation for Apache 1.3 with the AutoConf-style interface
+    (APACI).
+
+    APACI's suEXEC configuration
+    options

+    
+
+    
+      --enable-suexec
+
+      This option enables the suEXEC feature which is never
+      installed or activated by default. At least one
+      --suexec-xxxxx option has to be provided together with the
+      --enable-suexec option to let APACI accept your request for
+      using the suEXEC feature.
+
+      --suexec-caller=UID
+
+      The username under which
+      Apache normally runs. This is the only user allowed to
+      execute this program.
+
+      --suexec-docroot=DIR
+
+      Define as the DocumentRoot set for Apache. This will be
+      the only hierarchy (aside from UserDirs) that can be used for
+      suEXEC behavior. The default directory is the --datadir value
+      with the suffix "/htdocs", e.g. if you configure
+      with "--datadir=/home/apache" the directory
+      "/home/apache/htdocs" is used as document root for the suEXEC
+      wrapper.
+
+      --suexec-logfile=FILE
+
+      This defines the filename to which all suEXEC
+      transactions and errors are logged (useful for auditing and
+      debugging purposes). By default the logfile is named
+      "suexec_log" and located in your standard logfile directory
+      (--logfiledir).
+
+      --suexec-userdir=DIR
+
+      Define to be the subdirectory under users' home
+      directories where suEXEC access should be allowed. All
+      executables under this directory will be executable by suEXEC
+      as the user so they should be "safe" programs. If you are
+      using a "simple" UserDir directive (ie. one without a "*" in
+      it) this should be set to the same value. suEXEC will not
+      work properly in cases where the UserDir directive points to
+      a location that is not the same as the user's home directory
+      as referenced in the passwd file. Default value is
+      "public_html".

+       If you have virtual hosts with a different UserDir for each,
+      you will need to define them to all reside in one parent
+      directory; then name that parent directory here. If
+      this is not defined properly, "~userdir" cgi requests will
+      not work!
+
+      --suexec-uidmin=UID
+
+      Define this as the lowest UID allowed to be a target user
+      for suEXEC. For most systems, 500 or 100 is common. Default
+      value is 100.
+
+      --suexec-gidmin=GID
+
+      Define this as the lowest GID allowed to be a target
+      group for suEXEC. For most systems, 100 is common and
+      therefore used as default value.
+
+      --suexec-safepath=PATH
+
+      Define a safe PATH environment to pass to CGI
+      executables. Default value is
+      "/usr/local/bin:/usr/bin:/bin".
+    
+    

+     

+     
+
+    Checking your suEXEC
+    setup

+     Before you compile and install the suEXEC wrapper you can
+    check the configuration with the --layout option.

+     Example output:
+     suEXEC setup:
             suexec binary: /usr/local/apache/sbin/suexec
             document root: /usr/local/apache/share/htdocs
@@ -374,143 +467,154 @@ Example output:
                 caller ID: www
           minimum user ID: 100
          minimum group ID: 100
-
-
-
-
-Compiling and installing the suEXEC wrapper

-If you have enabled the suEXEC feature with the --enable-suexec option
-the suexec binary (together with Apache itself) is automatically built
-if you execute the command "make".
-

-After all components have been built you can execute the command
-"make install" to install them.
-The binary image "suexec" is installed in the directory defined by
-the --sbindir option. Default location is "/usr/local/apache/sbin/suexec".
-

-Please note that you need root privileges for
-the installation step. In order for the wrapper to set the user ID, it
-must be installed as owner root and must have the
-setuserid execution bit set for file modes.
-
-
-
-BACK TO CONTENTS
-
-
-Enabling & Disabling suEXEC
-
-Upon startup of Apache, it looks for the file "suexec" in the "sbin"
-directory (default is "/usr/local/apache/sbin/suexec").
-If Apache finds a properly configured suEXEC wrapper, it will print
-the following message to the error log:
-
-    [notice] suEXEC mechanism enabled (wrapper: /path/to/suexec)
-
-If you don't see this message at server startup, the server is most
-likely not finding the wrapper program where it expects it, or the
-executable is not installed setuid root.
-

-If you want to enable the suEXEC mechanism for the first time
-and an Apache server is already running you must kill and restart Apache.
-Restarting it with a simple HUP or USR1 signal will not be enough.
-

-If you want to disable suEXEC you should kill and restart Apache after
-you have removed the "suexec" file.
-
-
-
-BACK TO CONTENTS
-
-
-Using suEXEC
-
-Virtual Hosts:

-One way to use the suEXEC wrapper is through the
-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.
-

-User directories:

-The suEXEC wrapper can also be used to execute CGI programs as
-the user to which the request is being directed. This is accomplished by
-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.
-
-

-BACK TO CONTENTS
-
-
-Debugging suEXEC
-
-The suEXEC wrapper will write log information to the file defined
-with the --suexec-logfile option 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.
-
-
-
-BACK TO CONTENTS
-
-
-
-Beware the Jabberwock: Warnings & Examples
-
-
-NOTE!  This section may not be complete.  For the latest
-revision of this section of the documentation, see the Apache Group's
-Online Documentation
-version.
-
-
-
-There are a few points of interest regarding the wrapper that can cause
-limitations on server setup.  Please review these before submitting any
-"bugs" regarding suEXEC.
-

-        suEXEC Points Of Interest
-        Hierarchy limitations
-        
-        For security and efficiency reasons, all suexec requests must
-        remain within either a top-level document root for virtual
-        host requests, or one top-level personal document root for
-        userdir requests.  For example, if you have four VirtualHosts
-        configured, you would need to structure all of your VHosts'
-        document roots off of one main Apache document hierarchy to
-        take advantage of suEXEC for VirtualHosts. (Example forthcoming.)
-        
-        
-        suEXEC's PATH environment variable
-        
-        This can be a dangerous thing to change.  Make certain every
-        path you include in this define is a trusted
-        directory.  You don't want to open people up to having someone
-        from across the world running a trojan horse on them.
-        
-        
-        Altering the suEXEC code
-        
-        Again, this can cause Big Trouble if you try
-        this without knowing what you are doing.  Stay away from it
-        if at all possible.
-        
-        
-
-
-
-BACK TO CONTENTS
-
-
-
-
-
+

+
+
+ + +

Compiling and installing the suEXEC + wrapper
+ If you have enabled the suEXEC feature with the + --enable-suexec option the suexec binary (together with Apache + itself) is automatically built if you execute the command + "make".
+ After all components have been built you can execute the + command "make install" to install them. The binary image + "suexec" is installed in the directory defined by the --sbindir + option. Default location is + "/usr/local/apache/sbin/suexec".
+ Please note that you need root + privileges for the installation step. In order + for the wrapper to set the user ID, it must be installed as + owner root and must have the setuserid + execution bit set for file modes.

+ +

BACK TO + CONTENTS

+ +

Enabling & Disabling + suEXEC

+ +

Upon startup of Apache, it looks for the file + "suexec" in the "sbin" directory (default is + "/usr/local/apache/sbin/suexec"). If Apache finds a properly + configured suEXEC wrapper, it will print the following message + to the error log:

+    [notice] suEXEC mechanism enabled (wrapper: /path/to/suexec)
+

+ If you don't see this message at server startup, the server is + most likely not finding the wrapper program where it expects + it, or the executable is not installed setuid root. +
+ If you want to enable the suEXEC mechanism for the first time + and an Apache server is already running you must kill and + restart Apache. Restarting it with a simple HUP or USR1 signal + will not be enough.
+ If you want to disable suEXEC you should kill and restart + Apache after you have removed the "suexec" file.
+
+ + +

BACK TO + CONTENTS

+ +

Using suEXEC

+ +

Virtual Hosts:
+ One way to use the suEXEC wrapper is through the 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.

+ +

User directories:
+ The suEXEC wrapper can also be used to execute CGI programs as + the user to which the request is being directed. This is + accomplished by 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.

+ +

BACK TO + CONTENTS

+ +

Debugging suEXEC

+ +

The suEXEC wrapper will write log information + to the file defined with the --suexec-logfile option 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.

+ +

BACK TO + CONTENTS

+ +

Beware the Jabberwock: + Warnings & Examples

+ +

NOTE! This section may not be + complete. For the latest revision of this section of the + documentation, see the Apache Group's Online + Documentation version.

+ +

There are a few points of interest regarding + the wrapper that can cause limitations on server setup. Please + review these before submitting any "bugs" regarding suEXEC.

+ +

suEXEC Points Of Interest
+ Hierarchy limitations + +
+ For security and efficiency reasons, all suexec requests + must remain within either a top-level document root for + virtual host requests, or one top-level personal document + root for userdir requests. For example, if you have four + VirtualHosts configured, you would need to structure all + of your VHosts' document roots off of one main Apache + document hierarchy to take advantage of suEXEC for + VirtualHosts. (Example forthcoming.) +
+
+ suEXEC's PATH environment variable + +
+ This can be a dangerous thing to change. Make certain + every path you include in this define is a + trusted directory. You don't want to + open people up to having someone from across the world + running a trojan horse on them. +
+
+ Altering the suEXEC code + +
+ Again, this can cause Big Trouble if you + try this without knowing what you are doing. Stay away + from it if at all possible. +
+

+ +

BACK TO + CONTENTS

+ + + + diff --git a/docs/manual/suexec.html.en b/docs/manual/suexec.html.en index 8988cd42b8f..c4da9defb71 100644 --- a/docs/manual/suexec.html.en +++ b/docs/manual/suexec.html.en @@ -1,370 +1,463 @@ - - - -Apache suEXEC Support - - - - - -

Apache suEXEC Support

- -

CONTENTS
What is suEXEC?
Before we begin.
suEXEC Security Model.
Configuring & Installing suEXEC
Enabling & Disabling suEXEC
Using suEXEC
Debugging suEXEC
Beware the Jabberwock: Warnings & - Examples

- -

What is suEXEC?

- -

-BACK TO CONTENTS -

- -

Before we begin.

-Before jumping head-first into this document, you should be aware of the -assumptions made on the part of the Apache Group and this document. -

- -

-Still with us? Yes? Good. Let's move on! -

- -

-BACK TO CONTENTS -

- -

suEXEC Security Model

- -

Was the wrapper called with the proper number of - arguments? -
- The wrapper will only execute if it is given the proper number of arguments. - The proper argument format is known to the Apache web server. If the - wrapper - is not receiving the proper number of arguments, it is either being hacked, - or - there is something wrong with the suEXEC portion of your Apache binary. -
-
Is the user executing this wrapper a valid user of this - system? -
- This is to ensure that the user executing the wrapper is truly a user of the - system. -
-
Is this valid user allowed to run the wrapper? -
- Is this user the user allowed to run this wrapper? Only one user (the - Apache user) is allowed to execute this program. -
-
Does the target program have an unsafe hierarchical - reference? -
- Does the target program contain a leading '/' or have a '..' backreference? - These are not allowed; the target program must reside within the Apache - webspace. -
-
Is the target user name valid? -
- Does the target user exist? -
-
Is the target group name valid? -
- Does the target group exist? -
-
Is the target user NOT superuser? -
- Presently, suEXEC does not allow 'root' to execute CGI/SSI programs. -
-
Is the target userid ABOVE the minimum ID - number? -
- The minimum user ID number is specified during configuration. This allows - you - to set the lowest possible userid that will be allowed to execute CGI/SSI - programs. This is useful to block out "system" accounts. -
-
Is the target group NOT the superuser group? -
- Presently, suEXEC does not allow the 'root' group to execute CGI/SSI - programs. -
-
Is the target groupid ABOVE the minimum ID - number? -
- The minimum group ID number is specified during configuration. This allows - you - to set the lowest possible groupid that will be allowed to execute CGI/SSI - programs. This is useful to block out "system" groups. -
-
Can the wrapper successfully become the target user and - group? -
- Here is where the program becomes the target user and group via setuid and - setgid - calls. The group access list is also initialized with all of the groups - of which - the user is a member. -
-
Does the directory in which the program resides exist? -
- If it doesn't exist, it can't very well contain files. -
-
Is the directory within the Apache webspace? -
- If the request is for a regular portion of the server, is the requested - directory - within the server's document root? If the request is for a UserDir, is - the requested - directory within the user's document root? -
-
Is the directory NOT writable by anyone else? -
- We don't want to open up the directory to others; only the owner user - may be able - to alter this directories contents. -
-
Does the target program exist? -
- If it doesn't exists, it can't very well be executed. -
-
Is the target program NOT writable by anyone - else? -
- We don't want to give anyone other than the owner the ability to - change the program. -
-
Is the target program NOT setuid or setgid? -
- We do not want to execute programs that will then change our UID/GID again. -
-
Is the target user/group the same as the program's - user/group? -
- Is the user the owner of the file? -
-
Can we successfully clean the process environment to - ensure safe operations? -
- suEXEC cleans the process' environment by establishing a safe - execution PATH (defined - during configuration), as well as only passing through those - variables whose names - are listed in the safe environment list (also created during - configuration). -
-
Can we successfully become the target program and - execute? -
- Here is where suEXEC ends and the target program begins. -
-

- -

-BACK TO CONTENTS -

- -

Configuring & Installing suEXEC

- -

-APACI's suEXEC configuration options
-

--enable-suexec -: This option enables the suEXEC feature which is never installed or - activated by default. At least one --suexec-xxxxx option has to be - provided together with the --enable-suexec option to let APACI - accept your request for using the suEXEC feature. -
--suexec-caller=UID -: The username under which - Apache normally runs. - This is the only user allowed to execute this program. -
--suexec-docroot=DIR -: Define as the DocumentRoot set for Apache. - This will be the only hierarchy (aside from UserDirs) - that can be used for suEXEC behavior. - The default directory is the --datadir value with - the suffix "/htdocs", e.g. if you configure with - "--datadir=/home/apache" the directory - "/home/apache/htdocs" is used as document root for - the suEXEC wrapper. -
--suexec-logfile=FILE -: This defines the filename to which all suEXEC transactions and - errors are logged (useful for auditing and debugging purposes). - By default the logfile is named "suexec_log" and located in your - standard logfile directory (--logfiledir). -
--suexec-userdir=DIR -: Define to be the subdirectory under users' - home directories where suEXEC access should - be allowed. All executables under this directory - will be executable by suEXEC as the user so - they should be "safe" programs. If you are - using a "simple" UserDir directive (ie. one - without a "*" in it) this should be set to - the same value. suEXEC will not work properly - in cases where the UserDir directive points to - a location that is not the same as the user's - home directory as referenced in the passwd file. - Default value is "public_html". -
- If you have virtual hosts with a different - UserDir for each, you will need to define them to - all reside in one parent directory; then name that - parent directory here. If this is not defined - properly, "~userdir" cgi requests will not work! -
--suexec-uidmin=UID -: Define this as the lowest UID allowed to be a target user - for suEXEC. For most systems, 500 or 100 is common. - Default value is 100. -
--suexec-gidmin=GID -: Define this as the lowest GID allowed to be a target group - for suEXEC. For most systems, 100 is common and therefore - used as default value. -
--suexec-safepath=PATH -: Define a safe PATH environment to pass to CGI executables. - Default value is "/usr/local/bin:/usr/bin:/bin". -

- -

-Checking your suEXEC setup
-Before you compile and install the suEXEC wrapper you can check -the configuration with the --layout option. -
-Example output: -

+
+
+
+  
+    
+
+    Apache suEXEC Support
+  
+  
+
+  
+    
+
+    Apache suEXEC Support
+
+    
+      CONTENTS
+
+      What is suEXEC?
+
+      Before we begin.
+
+      suEXEC Security Model.
+
+      Configuring & Installing
+      suEXEC
+
+      Enabling & Disabling
+      suEXEC
+
+      Using suEXEC
+
+      Debugging suEXEC
+
+      Beware the Jabberwock: Warnings
+      & Examples
+    
+    

+     

+     
+
+    What is suEXEC?
+
+    The suEXEC feature --
+    introduced in Apache 1.2 -- provides Apache users the ability
+    to run CGI and SSI programs
+    under user IDs different from the user ID of the calling
+    web-server. Normally, when a CGI or SSI program executes, it
+    runs as the same user who is running the web server.
+
+    Used properly, this feature can reduce
+    considerably the security risks involved with allowing users to
+    develop and run private CGI or SSI programs. However, if suEXEC
+    is improperly configured, it can cause any number of problems
+    and possibly create new holes in your computer's security. If
+    you aren't familiar with managing setuid root programs and the
+    security issues they present, we highly recommend that you not
+    consider using suEXEC.
+
+    BACK TO
+    CONTENTS
+
+    Before we begin.
+
+    Before jumping head-first into this document,
+    you should be aware of the assumptions made on the part of the
+    Apache Group and this document.
+
+    First, it is assumed that you are using a UNIX
+    derivate operating system that is capable of
+    setuid and setgid operations.
+    All command examples are given in this regard. Other platforms,
+    if they are capable of supporting suEXEC, may differ in their
+    configuration.
+
+    Second, it is assumed you are familiar with
+    some basic concepts of your computer's security and its
+    administration. This involves an understanding of
+    setuid/setgid operations and the various
+    effects they may have on your system and its level of
+    security.
+
+    Third, it is assumed that you are using an
+    unmodified version of suEXEC code. All code
+    for suEXEC has been carefully scrutinized and tested by the
+    developers as well as numerous beta testers. Every precaution
+    has been taken to ensure a simple yet solidly safe base of
+    code. Altering this code can cause unexpected problems and new
+    security risks. It is highly recommended you
+    not alter the suEXEC code unless you are well versed in the
+    particulars of security programming and are willing to share
+    your work with the Apache Group for consideration.
+
+    Fourth, and last, it has been the decision of
+    the Apache Group to NOT make suEXEC part of
+    the default installation of Apache. To this end, suEXEC
+    configuration requires of the administrator careful attention
+    to details. After due consideration has been given to the
+    various settings for suEXEC, the administrator may install
+    suEXEC through normal installation methods. The values for
+    these settings need to be carefully determined and specified by
+    the administrator to properly maintain system security during
+    the use of suEXEC functionality. It is through this detailed
+    process that the Apache Group hopes to limit suEXEC
+    installation only to those who are careful and determined
+    enough to use it.
+
+    Still with us? Yes? Good. Let's move on!
+
+    BACK TO
+    CONTENTS
+
+    suEXEC Security Model
+
+    Before we begin configuring and installing
+    suEXEC, we will first discuss the security model you are about
+    to implement. By doing so, you may better understand what
+    exactly is going on inside suEXEC and what precautions are
+    taken to ensure your system's security.
+
+    suEXEC is based on a setuid
+    "wrapper" program that is called by the main Apache web server.
+    This wrapper is called when an HTTP request is made for a CGI
+    or SSI program that the administrator has designated to run as
+    a userid other than that of the main server. When such a
+    request is made, Apache provides the suEXEC wrapper with the
+    program's name and the user and group IDs under which the
+    program is to execute.
+
+    The wrapper then employs the following process
+    to determine success or failure -- if any one of these
+    conditions fail, the program logs the failure and exits with an
+    error, otherwise it will continue:
+
+    
+      
+        Was the wrapper called with the proper number of
+        arguments? 
+
+        
+          The wrapper will only execute if it is given the proper
+          number of arguments. The proper argument format is known
+          to the Apache web server. If the wrapper is not receiving
+          the proper number of arguments, it is either being
+          hacked, or there is something wrong with the suEXEC
+          portion of your Apache binary.
+        
+      
+
+      
+        Is the user executing this wrapper a valid user of
+        this system? 
+
+        
+          This is to ensure that the user executing the wrapper is
+          truly a user of the system.
+        
+      
+
+      
+        Is this valid user allowed to run the
+        wrapper? 
+
+        
+          Is this user the user allowed to run this wrapper? Only
+          one user (the Apache user) is allowed to execute this
+          program.
+        
+      
+
+      
+        Does the target program have an unsafe hierarchical
+        reference? 
+
+        
+          Does the target program contain a leading '/' or have a
+          '..' backreference? These are not allowed; the target
+          program must reside within the Apache webspace.
+        
+      
+
+      
+        Is the target user name valid? 
+
+        
+          Does the target user exist?
+        
+      
+
+      
+        Is the target group name valid? 
+
+        
+          Does the target group exist?
+        
+      
+
+      
+        Is the target user NOT superuser?
+        
+
+        
+          Presently, suEXEC does not allow 'root' to execute
+          CGI/SSI programs.
+        
+      
+
+      
+        Is the target userid ABOVE the minimum ID
+        number? 
+
+        
+          The minimum user ID number is specified during
+          configuration. This allows you to set the lowest possible
+          userid that will be allowed to execute CGI/SSI programs.
+          This is useful to block out "system" accounts.
+        
+      
+
+      
+        Is the target group NOT the superuser
+        group? 
+
+        
+          Presently, suEXEC does not allow the 'root' group to
+          execute CGI/SSI programs.
+        
+      
+
+      
+        Is the target groupid ABOVE the minimum ID
+        number? 
+
+        
+          The minimum group ID number is specified during
+          configuration. This allows you to set the lowest possible
+          groupid that will be allowed to execute CGI/SSI programs.
+          This is useful to block out "system" groups.
+        
+      
+
+      
+        Can the wrapper successfully become the target user
+        and group? 
+
+        
+          Here is where the program becomes the target user and
+          group via setuid and setgid calls. The group access list
+          is also initialized with all of the groups of which the
+          user is a member.
+        
+      
+
+      
+        Does the directory in which the program resides
+        exist? 
+
+        
+          If it doesn't exist, it can't very well contain files.
+        
+      
+
+      
+        Is the directory within the Apache
+        webspace? 
+
+        
+          If the request is for a regular portion of the server, is
+          the requested directory within the server's document
+          root? If the request is for a UserDir, is the requested
+          directory within the user's document root?
+        
+      
+
+      
+        Is the directory NOT writable by anyone
+        else? 
+
+        
+          We don't want to open up the directory to others; only
+          the owner user may be able to alter this directories
+          contents.
+        
+      
+
+      
+        Does the target program exist? 
+
+        
+          If it doesn't exists, it can't very well be executed.
+        
+      
+
+      
+        Is the target program NOT writable by
+        anyone else? 
+
+        
+          We don't want to give anyone other than the owner the
+          ability to change the program.
+        
+      
+
+      
+        Is the target program NOT setuid or
+        setgid? 
+
+        
+          We do not want to execute programs that will then change
+          our UID/GID again.
+        
+      
+
+      
+        Is the target user/group the same as the program's
+        user/group? 
+
+        
+          Is the user the owner of the file?
+        
+      
+
+      
+        Can we successfully clean the process environment
+        to ensure safe operations? 
+
+        
+          suEXEC cleans the process' environment by establishing a
+          safe execution PATH (defined during configuration), as
+          well as only passing through those variables whose names
+          are listed in the safe environment list (also created
+          during configuration).
+        
+      
+
+      
+        Can we successfully become the target program and
+        execute? 
+
+        
+          Here is where suEXEC ends and the target program begins.
+        
+      
+    
+    

+     

+     
+
+    This is the standard operation of the the
+    suEXEC wrapper's security model. It is somewhat stringent and
+    can impose new limitations and guidelines for CGI/SSI design,
+    but it was developed carefully step-by-step with security in
+    mind.
+
+    For more information as to how this security
+    model can limit your possibilities in regards to server
+    configuration, as well as what security risks can be avoided
+    with a proper suEXEC setup, see the "Beware the Jabberwock" section of this
+    document.
+
+    BACK TO
+    CONTENTS
+
+    Configuring & Installing
+    suEXEC
+
+    Here's where we begin the fun. If you use
+    Apache 1.2 or prefer to configure Apache 1.3 with the
+    "src/Configure" script you have to edit the suEXEC
+    header file and install the binary in its proper location
+    manually. The following sections describe the configuration and
+    installation for Apache 1.3 with the AutoConf-style interface
+    (APACI).
+
+    APACI's suEXEC configuration
+    options

+    
+
+    
+      --enable-suexec
+
+      This option enables the suEXEC feature which is never
+      installed or activated by default. At least one
+      --suexec-xxxxx option has to be provided together with the
+      --enable-suexec option to let APACI accept your request for
+      using the suEXEC feature.
+
+      --suexec-caller=UID
+
+      The username under which
+      Apache normally runs. This is the only user allowed to
+      execute this program.
+
+      --suexec-docroot=DIR
+
+      Define as the DocumentRoot set for Apache. This will be
+      the only hierarchy (aside from UserDirs) that can be used for
+      suEXEC behavior. The default directory is the --datadir value
+      with the suffix "/htdocs", e.g. if you configure
+      with "--datadir=/home/apache" the directory
+      "/home/apache/htdocs" is used as document root for the suEXEC
+      wrapper.
+
+      --suexec-logfile=FILE
+
+      This defines the filename to which all suEXEC
+      transactions and errors are logged (useful for auditing and
+      debugging purposes). By default the logfile is named
+      "suexec_log" and located in your standard logfile directory
+      (--logfiledir).
+
+      --suexec-userdir=DIR
+
+      Define to be the subdirectory under users' home
+      directories where suEXEC access should be allowed. All
+      executables under this directory will be executable by suEXEC
+      as the user so they should be "safe" programs. If you are
+      using a "simple" UserDir directive (ie. one without a "*" in
+      it) this should be set to the same value. suEXEC will not
+      work properly in cases where the UserDir directive points to
+      a location that is not the same as the user's home directory
+      as referenced in the passwd file. Default value is
+      "public_html".

+       If you have virtual hosts with a different UserDir for each,
+      you will need to define them to all reside in one parent
+      directory; then name that parent directory here. If
+      this is not defined properly, "~userdir" cgi requests will
+      not work!
+
+      --suexec-uidmin=UID
+
+      Define this as the lowest UID allowed to be a target user
+      for suEXEC. For most systems, 500 or 100 is common. Default
+      value is 100.
+
+      --suexec-gidmin=GID
+
+      Define this as the lowest GID allowed to be a target
+      group for suEXEC. For most systems, 100 is common and
+      therefore used as default value.
+
+      --suexec-safepath=PATH
+
+      Define a safe PATH environment to pass to CGI
+      executables. Default value is
+      "/usr/local/bin:/usr/bin:/bin".
+    
+    

+     

+     
+
+    Checking your suEXEC
+    setup

+     Before you compile and install the suEXEC wrapper you can
+    check the configuration with the --layout option.

+     Example output:
+     suEXEC setup:
             suexec binary: /usr/local/apache/sbin/suexec
             document root: /usr/local/apache/share/htdocs
@@ -374,143 +467,154 @@ Example output:
                 caller ID: www
           minimum user ID: 100
          minimum group ID: 100
-
-
-
-
-Compiling and installing the suEXEC wrapper

-If you have enabled the suEXEC feature with the --enable-suexec option
-the suexec binary (together with Apache itself) is automatically built
-if you execute the command "make".
-

-After all components have been built you can execute the command
-"make install" to install them.
-The binary image "suexec" is installed in the directory defined by
-the --sbindir option. Default location is "/usr/local/apache/sbin/suexec".
-

-Please note that you need root privileges for
-the installation step. In order for the wrapper to set the user ID, it
-must be installed as owner root and must have the
-setuserid execution bit set for file modes.
-
-
-
-BACK TO CONTENTS
-
-
-Enabling & Disabling suEXEC
-
-Upon startup of Apache, it looks for the file "suexec" in the "sbin"
-directory (default is "/usr/local/apache/sbin/suexec").
-If Apache finds a properly configured suEXEC wrapper, it will print
-the following message to the error log:
-
-    [notice] suEXEC mechanism enabled (wrapper: /path/to/suexec)
-
-If you don't see this message at server startup, the server is most
-likely not finding the wrapper program where it expects it, or the
-executable is not installed setuid root.
-

-If you want to enable the suEXEC mechanism for the first time
-and an Apache server is already running you must kill and restart Apache.
-Restarting it with a simple HUP or USR1 signal will not be enough.
-

-If you want to disable suEXEC you should kill and restart Apache after
-you have removed the "suexec" file.
-
-
-
-BACK TO CONTENTS
-
-
-Using suEXEC
-
-Virtual Hosts:

-One way to use the suEXEC wrapper is through the
-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.
-

-User directories:

-The suEXEC wrapper can also be used to execute CGI programs as
-the user to which the request is being directed. This is accomplished by
-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.
-
-

-BACK TO CONTENTS
-
-
-Debugging suEXEC
-
-The suEXEC wrapper will write log information to the file defined
-with the --suexec-logfile option 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.
-
-
-
-BACK TO CONTENTS
-
-
-
-Beware the Jabberwock: Warnings & Examples
-
-
-NOTE!  This section may not be complete.  For the latest
-revision of this section of the documentation, see the Apache Group's
-Online Documentation
-version.
-
-
-
-There are a few points of interest regarding the wrapper that can cause
-limitations on server setup.  Please review these before submitting any
-"bugs" regarding suEXEC.
-

-        suEXEC Points Of Interest
-        Hierarchy limitations
-        
-        For security and efficiency reasons, all suexec requests must
-        remain within either a top-level document root for virtual
-        host requests, or one top-level personal document root for
-        userdir requests.  For example, if you have four VirtualHosts
-        configured, you would need to structure all of your VHosts'
-        document roots off of one main Apache document hierarchy to
-        take advantage of suEXEC for VirtualHosts. (Example forthcoming.)
-        
-        
-        suEXEC's PATH environment variable
-        
-        This can be a dangerous thing to change.  Make certain every
-        path you include in this define is a trusted
-        directory.  You don't want to open people up to having someone
-        from across the world running a trojan horse on them.
-        
-        
-        Altering the suEXEC code
-        
-        Again, this can cause Big Trouble if you try
-        this without knowing what you are doing.  Stay away from it
-        if at all possible.
-        
-        
-
-
-
-BACK TO CONTENTS
-
-
-
-
-
+

+
+
+ + +

+ +

BACK TO + CONTENTS

+ +

Enabling & Disabling + suEXEC

+ +

+    [notice] suEXEC mechanism enabled (wrapper: /path/to/suexec)
+

BACK TO + CONTENTS

+ +

Using suEXEC

+ +

BACK TO + CONTENTS

+ +

Debugging suEXEC

+ +

BACK TO + CONTENTS

+ +

Beware the Jabberwock: + Warnings & Examples

+ +

NOTE! This section may not be + complete. For the latest revision of this section of the + documentation, see the Apache Group's Online + Documentation version.

+ +

There are a few points of interest regarding + the wrapper that can cause limitations on server setup. Please + review these before submitting any "bugs" regarding suEXEC.

+ +

suEXEC Points Of Interest
+ Hierarchy limitations + +
+ For security and efficiency reasons, all suexec requests + must remain within either a top-level document root for + virtual host requests, or one top-level personal document + root for userdir requests. For example, if you have four + VirtualHosts configured, you would need to structure all + of your VHosts' document roots off of one main Apache + document hierarchy to take advantage of suEXEC for + VirtualHosts. (Example forthcoming.) +
+
+ suEXEC's PATH environment variable + +
+ This can be a dangerous thing to change. Make certain + every path you include in this define is a + trusted directory. You don't want to + open people up to having someone from across the world + running a trojan horse on them. +
+
+ Altering the suEXEC code + +
+ Again, this can cause Big Trouble if you + try this without knowing what you are doing. Stay away + from it if at all possible. +
+

+ +

BACK TO + CONTENTS

+ + + + diff --git a/docs/manual/upgrading.html.en b/docs/manual/upgrading.html.en index dfd4370a8f5..730c635de7e 100644 --- a/docs/manual/upgrading.html.en +++ b/docs/manual/upgrading.html.en @@ -1,130 +1,146 @@ - - -Upgrading to 2.0 from 1.3 - - - - - -

Upgrading to 2.0 from 1.3

- -

In order to assist folks upgrading, we maintain a document -describing information critical to existing Apache users. These are -intended to be brief notes, and you should be able to find more -information in either the New -Features document, or in the src/CHANGES file. - -

Compile-Time Configuration Changes

- -

Apache now uses an autoconf and libtool -system for configuring the build processes. -Using this system is similar to, but not the same as, using the APACI -system in Apache 1.3.
In addition to the usual selection of modules which you can choose -to compile, Apache 2.0 has moved the main part of request processing -into Multi-Processing Modules (MPMs).

- -

Run-Time Configuration Changes

- -

Many directives that were in the core server in Apache 1.3 -are now in the MPMs. If you wish the behavior of the server -to be as similar as possible to the behavior of Apache 1.3, -you should select the prefork -MPM. Other MPMs will have different directives to control process -creation and request processing.
The CacheNegotiatedDocs directive now takes -the argument on or off. Existing -instances of CacheNegotiatedDocs should be replaced -with CacheNegotiatedDocs on.
The ErrorDocument directive no longer uses a quote at -the beginning of the argument to indicate a text message. Instead, -you should enclose the message in double quotes. For example, -existing instances of
ErrorDocument 403 "Some -Message
should be replaced with -
ErrorDocument 403 "Some -Message"
As long as the second argument is not a -valid URL or pathname, it will be treated as a text message.
The AccessConfig and ResourceConfig -directives no longer exist. Existing instances of these directives -can be replaced with the Include directive which -has equivalent functionality. If you were making use of the default -values of these directives without including them in the configuration -files, you may need to add Include conf/access.conf and -Include conf/srm.conf to your httpd.conf. In order to -assure that Apache reads the configuration files in the same order as -was implied by the older directives, the Include -directives should be placed at the end of httpd.conf, with the one for -srm.conf preceding the one for -access.conf.
The BindAddress directive no longer exists. -Equivalent functionality is provided with the more flexible Listen directive. - -
The ServerType directive no longer exists. -The method used to serve requests is now determined by the selection -of MPM. There is currently no MPM designed to be launched by -inetd.
The mod_log_agent and mod_log_referer modules which provided the -AgentLog, RefererLog and -RefererIgnore directives have been removed. Agent and -referer logs are still available using the CustomLog directive of -mod_log_config.
The AddModule and ClearModuleList -directives no longer exist. These directives where used to ensure -that modules could be enabled in the correct order. The new -Apache 2.0 API allows modules to explicitly specify their ordering, -eliminating the need for these directives.

- -

Misc Changes

- -

The httpd command line option -S -which was used for printing the virtual host configuration has -been replaced by -t -D DUMP_VHOSTS.
The module mod_auth_digest, which was experimental in Apache 1.3 -is now a standard module.
The mod_mmap_static module, which was experimental in Apache 1.3 -has been replaced with mod_file_cache.
The distribution has been completely reorganized so that it no -longer contains an independent src directory. Instead, -the sources are logically organized under the main distribution -directory, and installations of the compiled server should be -directed to a separate directory.

- -

Third Party Modules

- -

Extensive changes were made to the server API in Apache 2.0. -Existing modules designed for the Apache 1.3 API will not -work in Apache 2.0 without modification. Details are provided in -the developer documentation.

- - - - + + + + + + + Upgrading to 2.0 from 1.3 + + + + + + +

Upgrading to 2.0 from 1.3

+ +

In order to assist folks upgrading, we maintain a document + describing information critical to existing Apache users. These + are intended to be brief notes, and you should be able to find + more information in either the New Features document, or in + the src/CHANGES file.

+ +

Compile-Time Configuration Changes

+ +

Apache now uses an autoconf and + libtool system for configuring the build processes. + Using this system is similar to, but not the same as, using + the APACI system in Apache 1.3.
In addition to the usual selection of modules which you + can choose to compile, Apache 2.0 has moved the main part of + request processing into Multi-Processing + Modules (MPMs).

+ +

Run-Time Configuration Changes

+ +

Many directives that were in the core server in Apache + 1.3 are now in the MPMs. If you wish the behavior of the + server to be as similar as possible to the behavior of Apache + 1.3, you should select the prefork MPM. Other MPMs will have + different directives to control process creation and request + processing.
The CacheNegotiatedDocs directive now takes + the argument on or off. Existing + instances of CacheNegotiatedDocs should be + replaced with CacheNegotiatedDocs on.
+ The ErrorDocument directive no longer uses a + quote at the beginning of the argument to indicate a text + message. Instead, you should enclose the message in double + quotes. For example, existing instances of + +
+ ErrorDocument 403 "Some Message +
+ should be replaced with + +
+ ErrorDocument 403 "Some Message" +
+ As long as the second argument is not a valid URL or + pathname, it will be treated as a text message. +
The AccessConfig and + ResourceConfig directives no longer exist. + Existing instances of these directives can be replaced with + the Include + directive which has equivalent functionality. If you were + making use of the default values of these directives without + including them in the configuration files, you may need to + add Include conf/access.conf and Include + conf/srm.conf to your httpd.conf. In order to assure + that Apache reads the configuration files in the same order + as was implied by the older directives, the + Include directives should be placed at the end + of httpd.conf, with the one for srm.conf + preceding the one for access.conf.
The BindAddress directive no longer exists. + Equivalent functionality is provided with the more flexible + Listen + directive.
The ServerType directive no longer exists. + The method used to serve requests is now determined by the + selection of MPM. There is currently no MPM designed to be + launched by inetd.
The mod_log_agent and mod_log_referer modules which + provided the AgentLog, RefererLog + and RefererIgnore directives have been removed. + Agent and referer logs are still available using the CustomLog + directive of mod_log_config.
The AddModule and + ClearModuleList directives no longer exist. + These directives where used to ensure that modules could be + enabled in the correct order. The new Apache 2.0 API allows + modules to explicitly specify their ordering, eliminating the + need for these directives.

+ +

Misc Changes

+ +

The httpd command line option + -S which was used for printing the virtual host + configuration has been replaced by -t -D + DUMP_VHOSTS.
The module mod_auth_digest, which was experimental in + Apache 1.3 is now a standard module.
The mod_mmap_static module, which was experimental in + Apache 1.3 has been replaced with mod_file_cache.
The distribution has been completely reorganized so that + it no longer contains an independent src + directory. Instead, the sources are logically organized under + the main distribution directory, and installations of the + compiled server should be directed to a separate + directory.

+ +

Third Party Modules

+ +

Extensive changes were made to the server API in Apache 2.0. + Existing modules designed for the Apache 1.3 API will + not work in Apache 2.0 without modification. + Details are provided in the developer + documentation.

+ + + + diff --git a/docs/manual/upgrading.html.fr b/docs/manual/upgrading.html.fr index 65fba237e9f..fb403655cbf 100644 --- a/docs/manual/upgrading.html.fr +++ b/docs/manual/upgrading.html.fr @@ -1,123 +1,151 @@ - - - -Mise à jour de la version 1.3 à la version 2.0 - - - - - -

Mise à de la version 1.3 à la version 2.0

- -

Afin d'aider les personnes souhaitant se mettre à jour, nous -maintenons un document décrivant les informations critiques concernant -les utilisateurs d'Apache. Ces informations sont sous la forme de brèves -notes, et vous pouvez trouver plus d'informations dans le document - Nouvelles fonctionnalités - ou dans le fichier src/CHANGES. - -

Changement de la configuration à la compilation

- -

Apache utilise maintenant autoconf et libtool -afin de configurer la compilation. L'utilisation de ces outils est -similaire, mais pas tout à fait identique, au système APACI -de configuration existant dans la version 1.3 d'Apache. -
En plus de l'habituelle sélection de modules que vous pouvez choisir -de compiler, Apache 2.0 a déplacé la majeure partie du traitement -des requêtes dans les modules multi-traitements (MPMs).

- -

Changement de la configuration à l'exécution

- -

La directive CacheNegotiatedDocs prend maintenant un -paramètre qui est soit on soit off. Les configurations -existantes utilisant la directive CacheNegotiatedDocs doivent -la remplacer par CacheNegotiatedDocs on.
La directive ErrorDocument n'utilise plus de guillemets -ou d'apostrophes au début du paramètre indiquant le message. -Dorénavant, le message devra être entre guillemets. Par exemple, la -directive
ErrorDocument 403 "Some Message
-devra être remplacé par
ErrorDocument 403 "Some -Message"
Si le second argument n'est pas une URL ou un chemin -valide, il sera traité comme un message.
Les directives AccessConfig et ResourceConfig -n'existent plus. Ces directives peuvent être remplacées de manière -équivalente par la directive -Include. -Si vous utilisiez ces directives en utilisant les valeurs par défaut sans -les définir explicitement, vous devez -ajouter les lignes Include conf/access.conf et -Include conf/srm.conf dans votre fichier httpd.conf. -Afin de garantir qu'Apache lit les différents fichiers de configuration -dans le même ordre que celui pour les anciennes directives, Les directives -Include doivent être situées à la fin du fichier -httpd.conf, celle représentant srm.conf avant celle pour -access.conf.
La directive BindAddress n'existe plus. La même -fonctionnalité est fournie par la directive -Listen.
La directive ExtendedStatus n'existe plus. -Le suivi des statuts a été entièrement réécrit -afin de bénéficier du nouveau système MPM.
La directive ServerType n'existe plus. -La méthode utilisée pour servir les requêtes est -déterminée maintenant par la sélection d'un MPM. -Il n'existe pas actuellement de MPM conçu pour être lancé -par inetd.
Beaucoup de directives qui étaient situées dans le noyau -du serveur pour la version 1.3 se trouvent maintenant dans les MPMs.
Les modules mod_log_agent et mod_log_referer qui traitaient les directives -AgentLog, RefererLog et -RefererIgnore ont été supprimés. -Le traçage des agents et référants et toujours disponible -en utilisant la directive -CustomLog du module -mod_log_config.

- -

Changements divers

- -

L'option -S du programme httpd -qui servait à afficher la configuration des hôtes virtuels est -remplacé par -t -D DUMP_VHOSTS.
Le module mod_auth_digest, qui était expérimental dans la version 1.3, -est maintenant un module standard.
Le module mod_mmap_static, qui était expérimental dans la version 1.3 -a été remplacé par le module mod_file_cache.

- -

Modules tiers

- -

D'énormes changements ont été réalisés -sur l'API du serveur Apache 2.0. Les modules conçus à l'aide de -l'API Apache 1.3 ne fonctionneront pas sur Apache 2.0 sans -modifications. Plus de détails sont fournis dans la -documentation du développeur.

- - - - + + + + + + + + Mise à jour de la version 1.3 à la version + 2.0 + + + + + + +

Mise à de la version 1.3 à la + version 2.0

+ +

Afin d'aider les personnes souhaitant se mettre à + jour, nous maintenons un document décrivant les + informations critiques concernant les utilisateurs d'Apache. + Ces informations sont sous la forme de brèves notes, et + vous pouvez trouver plus d'informations dans le document Nouvelles + fonctionnalités ou dans le fichier + src/CHANGES.

+ +

Changement de la configuration à la compilation

+ +

Apache utilise maintenant autoconf et + libtool afin de configurer la compilation. + L'utilisation de ces outils est similaire, mais pas tout + à fait identique, au système APACI de + configuration existant dans la version 1.3 d'Apache.
En plus de l'habituelle sélection de modules que + vous pouvez choisir de compiler, Apache 2.0 a + déplacé la majeure partie du traitement des + requêtes dans les modules + multi-traitements (MPMs).

+ +

Changement de la configuration à + l'exécution

+ +

La directive CacheNegotiatedDocs prend + maintenant un paramètre qui est soit on + soit off. Les configurations existantes + utilisant la directive CacheNegotiatedDocs + doivent la remplacer par CacheNegotiatedDocs + on.
+ La directive ErrorDocument n'utilise plus de + guillemets ou d'apostrophes au début du + paramètre indiquant le message. Dorénavant, + le message devra être entre guillemets. Par exemple, + la directive + +
+ ErrorDocument 403 "Some Message +
+ devra être remplacé par + +
+ ErrorDocument 403 "Some Message" +
+ Si le second argument n'est pas une URL ou un chemin + valide, il sera traité comme un message. +
Les directives AccessConfig et + ResourceConfig n'existent plus. Ces directives + peuvent être remplacées de manière + équivalente par la directive Include. Si + vous utilisiez ces directives en utilisant les valeurs par + défaut sans les définir explicitement, vous + devez ajouter les lignes Include + conf/access.conf et Include conf/srm.conf + dans votre fichier httpd.conf. Afin de garantir qu'Apache lit + les différents fichiers de configuration dans le + même ordre que celui pour les anciennes directives, Les + directives Include doivent être + situées à la fin du fichier httpd.conf, celle + représentant srm.conf avant celle pour + access.conf.
La directive BindAddress n'existe plus. La + même fonctionnalité est fournie par la directive + Listen.
La directive ExtendedStatus n'existe plus. + Le suivi des statuts a été entièrement + réécrit afin de bénéficier du + nouveau système MPM.
La directive ServerType n'existe plus. La + méthode utilisée pour servir les requêtes + est déterminée maintenant par la + sélection d'un MPM. Il n'existe pas actuellement de + MPM conçu pour être lancé par inetd.
Beaucoup de directives qui étaient situées + dans le noyau du serveur pour la version 1.3 se trouvent + maintenant dans les MPMs.
Les modules mod_log_agent et mod_log_referer qui + traitaient les directives AgentLog, + RefererLog et RefererIgnore ont + été supprimés. Le traçage des + agents et référants et toujours disponible en + utilisant la directive CustomLog du + module mod_log_config.

+ +

Changements divers

+ +

L'option -S du programme httpd + qui servait à afficher la configuration des + hôtes virtuels est remplacé par -t -D + DUMP_VHOSTS.
Le module mod_auth_digest, qui était + expérimental dans la version 1.3, est maintenant un + module standard.
Le module mod_mmap_static, qui était + expérimental dans la version 1.3 a été + remplacé par le module mod_file_cache.

+ +

Modules tiers

+ +

D'énormes changements ont été + réalisés sur l'API du serveur Apache 2.0. Les + modules conçus à l'aide de l'API Apache 1.3 + ne fonctionneront pas sur Apache 2.0 sans + modifications. Plus de détails sont fournis dans la documentation du développeur.

+ + + + diff --git a/docs/manual/urlmapping.html b/docs/manual/urlmapping.html index 4f26c806293..627dcf053f9 100755 --- a/docs/manual/urlmapping.html +++ b/docs/manual/urlmapping.html @@ -1,247 +1,296 @@ - - - -Mapping URLs to Filesystem Locations - Apache HTTP Server - - - - - -

Mapping URLs to Filesystem Locations

- -

This document explains how Apache uses the URL of a request to -determine the filesystem location from which to serve a file.

- -

DocumentRoot
Files Outside the DocumentRoot
User Directories
URL Redirection
Rewrite Engine
File Not Found

- -

- - -

-Related Modules

- -mod_alias
-mod_rewrite
-mod_userdir
-mod_speling
-mod_vhost_alias
- -

-Related Directives

- -Alias
-AliasMatch
-CheckSpelling
-DocumentRoot
-ErrorDocument
-Options
-Redirect
-RedirectMatch
-RewriteCond
-RewriteRule
-ScriptAlias
-ScriptAliasMatch
-UserDir
- -

- -

DocumentRoot

- -

In deciding what file to serve for a given request, Apache's -default behavior is to take the URL-Path for the request (the part of -the URL following the hostname and port) and add it to the end of the -DocumentRoot specified in -your configuration files. Therefore, the files and directories -underneath the DocumentRoot make up the basic document -tree which will be visible from the web.

- -

Apache is also capable of Virtual Hosting, -where the server receives requests for more than one host. In this -case, a different DocumentRoot can be specified for each -virtual host, or alternatively, the directives provided by the module -mod_vhost_alias can be used to -dynamically determine the appropriate place from which to serve -content based on the requested IP address or hostname.

- -

Files Outside the DocumentRoot

- -

There are frequently circumstances where it is necessary to allow -web access to parts of the filesystem that are not strictly underneath -the DocumentRoot. Apache -offers several different ways to accomplish this. On Unix systems, -symbolic links can bring other parts of the filesystem under the -DocumentRoot. For security reasons, Apache will follow -symbolic links only if the Options -setting for the relevant directory includes -FollowSymLinks or SymLinksIfOwnerMatch.

- -

Alternatively, the Alias -directive will map any part of the filesystem into the web -space. For example, with

- -

Alias /docs /var/web/ -

- -

the URL http://www.example.com/docs/dir/file.html will -be served from /var/web/dir/file.html. The ScriptAlias directive works -the same way, with the additional effect that all content located at -the target path is treated as CGI scripts.

- -

For situations where you require additional flexibility, you can -use the AliasMatch and ScriptAliasMatch -directives to do powerful regular-expression based matching and -substitution. For example,

- -

ScriptAliasMatch ^/~([^/]*)/cgi-bin/(.*) -/home/$1/cgi-bin/$2

- -

will map a request to -http://example.com/~user/cgi-bin/script.cgi to the path -/home/user/cgi-bin/script.cgi and will treat the -resulting file as a CGI script.

- -

User Directories

- -

Traditionally on Unix systems, the home directory of a particular -user can be referred to as ~user/. The module -mod_userdir extends this idea to -the web by allowing files under each user's home directory to be -accessed using URLs such as the following.

- -

http://www.example.com/~user/file.html

- -

For security reasons, it is inappropriate to give direct -access to a user's home directory from the web. Therefore, the UserDir directive -specifies a directory underneath the user's home directory where web -files are located. Using the default setting of Userdir -public_html, the above URL maps to a file at a directory -like /home/user/public_html/file.html where -/home/user/ is the user's home directory as specified in -/etc/passwd.

- -

There are also several other forms of the Userdir -directive which you can use on systems where /etc/passwd -does not contain the location of the home directory.

- -

Some people find the "~" symbol (which is often encoded on the web -as %7e) to be awkward and prefer to use an alternate -string to represent user directories. This functionality is not -supported by mod_userdir. However, if users' home directories are -structured in a regular way, then it is possible to use the AliasMatch directive to -achieve the desired effect. For example, to make -http://www.example.com/upages/user/file.html map to -/home/user/public_html/file.html, use the following -AliasMatch directive:

- -

-AliasMatch ^/upages/([^/]*)/?(.*) /home/$1/public_html/$2 -

- -

URL Redirection

- -

The configuration directives discussed in the above sections tell -Apache to get content from a specific place in the filesystem and -return it to the client. Sometimes, it is desirable instead to inform -the client that the requested content is located at a different -URL, and instruct the client to make a new request with the new URL. -This is called redirection and is implemented by the -Redirect directive. For -example, if the contents of the directory /foo/ under the -DocumentRoot are moved to the new directory -/bar/, you can instruct clients to request the content at -the new location as follows:

- -

Redirect permanent -/foo/ http://www.example.com/bar/

- -

This will redirect any URL-Path starting in /foo/ to -the same URL path on the www.example.com server with -/bar/ substituted for /foo/. You can -redirect clients to any server, not only the origin server.

- -

Apache also provides a RedirectMatch directive -for more complicated rewriting problems. For example, to redirect -requests for the site home page to a different site, but leave all -other requests alone, use the following configuration:

- -

-RedirectMatch permanent ^/$ http://www.example.com/startpage.html -

- -

Alternatively, to temporarily redirect all pages on a site to one -particular page, use the following:

- -

-RedirectMatch temp .* http://www.example.com/startpage.html -

- -

Rewriting Engine

- -

When even more powerful substitution is required, the rewriting -engine provided by mod_rewrite can -be useful. The directives provided by this module use -characteristics of the request such as browser type or source IP -address in deciding from where to serve content. In addition, -mod_rewrite can use external database files or programs to determine -how to handle a request. Many practical examples employing -mod_rewrite are discussed in the URL -Rewriting Guide.

- -

File Not Found

- -

Inevitably, URLs will be requested for which no matching file can -be found in the filesystem. This can happen for several reasons. In -some cases, it can be a result of moving documents from one location -to another. In this case, it is best to use URL -redirection to inform clients of the new location of the resource. -In this way, you can assure that old bookmarks and links will continue -to work, even though the resource is at a new location.

- -

Another common cause of "File Not Found" errors is accidental -mistyping of URLs, either directly in the browser, or in HTML links. -Apache provides the module mod_speling -(sic) to help with this problem. When this module is activated, it -will intercept "File Not Found" errors and look for a resource with a -similar filename. If one such file is found, mod_speling will send an -HTTP redirect to the client informing it of the correct location. If -several "close" files are found, a list of available alternatives will -be presented to the client.

- -

An especially useful feature of mod_speling, is that it will -compare filenames without respect to case. This can help systems -where users are unaware of the case-sensitive nature of URLs and the -unix filesystem. But using mod_speling for anything more than the -occasional URL correction can place additional load on the server, -since each "incorrect" request is followed by a URL redirection and a -new request from the client.

- -

If all attempts to locate the content fail, Apache returns an error -page with HTTP status code 404 (file not found). The appearance of -this page is controlled with the ErrorDocument directive and can -be customized in a flexible manner as discussed in the Custom error responses and International Server Error -Responses documents.

- - - - + + + + + + + Mapping URLs to Filesystem Locations - Apache HTTP + Server + + + + + + +

Mapping URLs to Filesystem Locations

+ +

This document explains how Apache uses the URL of a request + to determine the filesystem location from which to serve a + file.

+ +

DocumentRoot
Files Outside the + DocumentRoot
User Directories
URL Redirection
Rewrite Engine
File Not Found

+ + + + + + + +

Related Modules
+
+ mod_alias
+ mod_rewrite
+ mod_userdir
+ mod_speling
+ mod_vhost_alias
+

Related Directives
+
+ Alias
+ AliasMatch
+ CheckSpelling
+ DocumentRoot
+ ErrorDocument
+ Options
+ Redirect
+ RedirectMatch
+ RewriteCond
+ RewriteRule
+ ScriptAlias
+ ScriptAliasMatch
+ UserDir
+

+ +

DocumentRoot

+ +

In deciding what file to serve for a given request, Apache's + default behavior is to take the URL-Path for the request (the + part of the URL following the hostname and port) and add it to + the end of the DocumentRoot specified in + your configuration files. Therefore, the files and directories + underneath the DocumentRoot make up the basic + document tree which will be visible from the web.

+ +

Apache is also capable of Virtual + Hosting, where the server receives requests for more than + one host. In this case, a different DocumentRoot + can be specified for each virtual host, or alternatively, the + directives provided by the module mod_vhost_alias can be used + to dynamically determine the appropriate place from which to + serve content based on the requested IP address or + hostname.

+ +

Files Outside the + DocumentRoot

+ +

There are frequently circumstances where it is necessary to + allow web access to parts of the filesystem that are not + strictly underneath the DocumentRoot. Apache + offers several different ways to accomplish this. On Unix + systems, symbolic links can bring other parts of the filesystem + under the DocumentRoot. For security reasons, + Apache will follow symbolic links only if the Options setting for the + relevant directory includes FollowSymLinks or + SymLinksIfOwnerMatch.

+ +

Alternatively, the Alias directive will map + any part of the filesystem into the web space. For example, + with

+ +

+ Alias /docs /var/web/ +

+ +

the URL + http://www.example.com/docs/dir/file.html will be + served from /var/web/dir/file.html. The ScriptAlias directive + works the same way, with the additional effect that all content + located at the target path is treated as CGI scripts.

+ +

For situations where you require additional flexibility, you + can use the AliasMatch and ScriptAliasMatch + directives to do powerful regular-expression based matching and + substitution. For example,

+ +

+ ScriptAliasMatch ^/~([^/]*)/cgi-bin/(.*) + /home/$1/cgi-bin/$2 +

+ +

will map a request to + http://example.com/~user/cgi-bin/script.cgi to the + path /home/user/cgi-bin/script.cgi and will treat + the resulting file as a CGI script.

+ +

User Directories

+ +

Traditionally on Unix systems, the home directory of a + particular user can be referred to as + ~user/. The module mod_userdir extends this idea + to the web by allowing files under each user's home directory + to be accessed using URLs such as the following.

+ +

+ http://www.example.com/~user/file.html +

+ +

For security reasons, it is inappropriate to give direct + access to a user's home directory from the web. Therefore, the + UserDir directive + specifies a directory underneath the user's home directory + where web files are located. Using the default setting of + Userdir public_html, the above URL maps to a file + at a directory like + /home/user/public_html/file.html where + /home/user/ is the user's home directory as + specified in /etc/passwd.

+ +

There are also several other forms of the + Userdir directive which you can use on systems + where /etc/passwd does not contain the location of + the home directory.

+ +

Some people find the "~" symbol (which is often encoded on + the web as %7e) to be awkward and prefer to use an + alternate string to represent user directories. This + functionality is not supported by mod_userdir. However, if + users' home directories are structured in a regular way, then + it is possible to use the AliasMatch directive + to achieve the desired effect. For example, to make + http://www.example.com/upages/user/file.html map + to /home/user/public_html/file.html, use the + following AliasMatch directive:

+ +

+ AliasMatch ^/upages/([^/]*)/?(.*) + /home/$1/public_html/$2 +

+ +

URL Redirection

+ +

The configuration directives discussed in the above sections + tell Apache to get content from a specific place in the + filesystem and return it to the client. Sometimes, it is + desirable instead to inform the client that the requested + content is located at a different URL, and instruct the client + to make a new request with the new URL. This is called + redirection and is implemented by the Redirect directive. For + example, if the contents of the directory /foo/ + under the DocumentRoot are moved to the new + directory /bar/, you can instruct clients to + request the content at the new location as follows:

+ +

+ Redirect permanent /foo/ + http://www.example.com/bar/ +

+ +

This will redirect any URL-Path starting in + /foo/ to the same URL path on the + www.example.com server with /bar/ + substituted for /foo/. You can redirect clients to + any server, not only the origin server.

+ +

Apache also provides a RedirectMatch + directive for more complicated rewriting problems. For example, + to redirect requests for the site home page to a different + site, but leave all other requests alone, use the following + configuration:

+ +

+ RedirectMatch permanent ^/$ + http://www.example.com/startpage.html +

+ +

Alternatively, to temporarily redirect all pages on a site + to one particular page, use the following:

+ +

+ RedirectMatch temp .* + http://www.example.com/startpage.html +

+ +

Rewriting Engine

+ +

When even more powerful substitution is required, the + rewriting engine provided by mod_rewrite can be useful. The + directives provided by this module use characteristics of the + request such as browser type or source IP address in deciding + from where to serve content. In addition, mod_rewrite can use + external database files or programs to determine how to handle + a request. Many practical examples employing mod_rewrite are + discussed in the URL Rewriting + Guide.

+ +

File Not Found

+ +

Inevitably, URLs will be requested for which no matching + file can be found in the filesystem. This can happen for + several reasons. In some cases, it can be a result of moving + documents from one location to another. In this case, it is + best to use URL redirection to inform + clients of the new location of the resource. In this way, you + can assure that old bookmarks and links will continue to work, + even though the resource is at a new location.

+ +

Another common cause of "File Not Found" errors is + accidental mistyping of URLs, either directly in the browser, + or in HTML links. Apache provides the module mod_speling (sic) to help with + this problem. When this module is activated, it will intercept + "File Not Found" errors and look for a resource with a similar + filename. If one such file is found, mod_speling will send an + HTTP redirect to the client informing it of the correct + location. If several "close" files are found, a list of + available alternatives will be presented to the client.

+ +

An especially useful feature of mod_speling, is that it will + compare filenames without respect to case. This can help + systems where users are unaware of the case-sensitive nature of + URLs and the unix filesystem. But using mod_speling for + anything more than the occasional URL correction can place + additional load on the server, since each "incorrect" request + is followed by a URL redirection and a new request from the + client.

+ +

If all attempts to locate the content fail, Apache returns + an error page with HTTP status code 404 (file not found). The + appearance of this page is controlled with the ErrorDocument directive + and can be customized in a flexible manner as discussed in the + Custom error responses and International Server Error + Responses documents.

+ + + + diff --git a/docs/manual/urlmapping.html.en b/docs/manual/urlmapping.html.en index 4f26c806293..627dcf053f9 100755 --- a/docs/manual/urlmapping.html.en +++ b/docs/manual/urlmapping.html.en @@ -1,247 +1,296 @@ - - - -Mapping URLs to Filesystem Locations - Apache HTTP Server - - - - - -

Mapping URLs to Filesystem Locations

- -

This document explains how Apache uses the URL of a request to -determine the filesystem location from which to serve a file.

- -

DocumentRoot
Files Outside the DocumentRoot
User Directories
URL Redirection
Rewrite Engine
File Not Found

- -

- - -

-Related Modules

- -mod_alias
-mod_rewrite
-mod_userdir
-mod_speling
-mod_vhost_alias
- -

-Related Directives

- -Alias
-AliasMatch
-CheckSpelling
-DocumentRoot
-ErrorDocument
-Options
-Redirect
-RedirectMatch
-RewriteCond
-RewriteRule
-ScriptAlias
-ScriptAliasMatch
-UserDir
- -

- -

DocumentRoot

- -

Files Outside the DocumentRoot

- -

Alternatively, the Alias -directive will map any part of the filesystem into the web -space. For example, with

- -

Alias /docs /var/web/ -

- -

For situations where you require additional flexibility, you can -use the AliasMatch and ScriptAliasMatch -directives to do powerful regular-expression based matching and -substitution. For example,

- -

ScriptAliasMatch ^/~([^/]*)/cgi-bin/(.*) -/home/$1/cgi-bin/$2

- -

will map a request to -http://example.com/~user/cgi-bin/script.cgi to the path -/home/user/cgi-bin/script.cgi and will treat the -resulting file as a CGI script.

- -

User Directories

- -

http://www.example.com/~user/file.html

- -

There are also several other forms of the Userdir -directive which you can use on systems where /etc/passwd -does not contain the location of the home directory.

- -

-AliasMatch ^/upages/([^/]*)/?(.*) /home/$1/public_html/$2 -

- -

URL Redirection

- -

Redirect permanent -/foo/ http://www.example.com/bar/

- -

-RedirectMatch permanent ^/$ http://www.example.com/startpage.html -

- -

Alternatively, to temporarily redirect all pages on a site to one -particular page, use the following:

- -

-RedirectMatch temp .* http://www.example.com/startpage.html -

- -

Rewriting Engine

- -

File Not Found

- -

- - - - + + + + + + + Mapping URLs to Filesystem Locations - Apache HTTP + Server + + + + + + +

Mapping URLs to Filesystem Locations

+ +

This document explains how Apache uses the URL of a request + to determine the filesystem location from which to serve a + file.

+ +

DocumentRoot
Files Outside the + DocumentRoot
User Directories
URL Redirection
Rewrite Engine
File Not Found

+ + + + + + + +

Related Modules
+
+ mod_alias
+ mod_rewrite
+ mod_userdir
+ mod_speling
+ mod_vhost_alias
+

+ +

DocumentRoot

+ +

Files Outside the + DocumentRoot

+ +

Alternatively, the Alias directive will map + any part of the filesystem into the web space. For example, + with

+ +

+ Alias /docs /var/web/ +

+ +

+ ScriptAliasMatch ^/~([^/]*)/cgi-bin/(.*) + /home/$1/cgi-bin/$2 +

+ +

will map a request to + http://example.com/~user/cgi-bin/script.cgi to the + path /home/user/cgi-bin/script.cgi and will treat + the resulting file as a CGI script.

+ +

User Directories

+ +

+ http://www.example.com/~user/file.html +

+ +

There are also several other forms of the + Userdir directive which you can use on systems + where /etc/passwd does not contain the location of + the home directory.

+ +

+ AliasMatch ^/upages/([^/]*)/?(.*) + /home/$1/public_html/$2 +

+ +

URL Redirection

+ +

+ Redirect permanent /foo/ + http://www.example.com/bar/ +

+ +

+ RedirectMatch permanent ^/$ + http://www.example.com/startpage.html +

+ +

Alternatively, to temporarily redirect all pages on a site + to one particular page, use the following:

+ +

+ RedirectMatch temp .* + http://www.example.com/startpage.html +

+ +

Rewriting Engine

+ +

File Not Found

+ +

+ + + +

Setting which addresses and ports Apache uses

Setting which addresses and ports Apache + uses

How this works with Virtual Hosts

See also

How this works with Virtual Hosts

See also

Setting which addresses and ports Apache uses

Setting which addresses and ports Apache + uses

How this works with Virtual Hosts

See also

How this works with Virtual Hosts

See also

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

Configuration Files

Configuration Files

$B%U%!%$%k$N@_Dj(B

$B%U%!%$%k$N@_Dj(B

$B%;%-%e%j%F%#$K4X$9$k7Y9p(B

pid $B%U%!%$%k(B

$B%(%i!<%m%0(B

$BE>Aw%m%0(B

Content Negotiation

About Content Negotiation

Content Negotiation

About Content Negotiation

Negotiation in Apache

Using a type-map file

Negotiation in Apache

Using a type-map file

Multiviews

Multiviews

The Negotiation Methods

Dimensions of Negotiation

Apache Negotiation Algorithm

Media Types and Wildcards

The Negotiation Methods

Dimensions of Negotiation

Apache Negotiation Algorithm

Media Types and Wildcards

Variants with no Language

Extensions to Transparent Content Negotiation

Note on hyperlinks and naming conventions

Note on Caching

Variants with no Language

Extensions to Transparent Content Negotiation

Note on hyperlinks and naming conventions

Note on Caching

Content Negotiation

About Content Negotiation

Content Negotiation

About Content Negotiation

Negotiation in Apache

Using a type-map file

Negotiation in Apache

Using a type-map file

Multiviews

Multiviews

The Negotiation Methods

Dimensions of Negotiation

Apache Negotiation Algorithm

Media Types and Wildcards

The Negotiation Methods

Dimensions of Negotiation

Apache Negotiation Algorithm

Media Types and Wildcards

Variants with no Language

Extensions to Transparent Content Negotiation

Note on hyperlinks and naming conventions

Note on Caching

Variants with no Language

Extensions to Transparent Content Negotiation

Note on hyperlinks and naming conventions

Note on Caching

Custom error responses

Custom error responses

Custom error responses and redirects

Custom error responses and redirects

$B%U%!%$%k$N@_Dj(B

$B%U%!%$%k$N@_Dj(B

$B%;%-%e%j%F%#$K4X$9$k7Y9p(B

pid $B%U%!%$%k(B

$B%(%i!<%m%0(B

$BE>Aw%m%0(B