diff options
| author | Bob Beck <beck@cvs.openbsd.org> | 1999-03-01 01:07:30 +0000 |
|---|---|---|
| committer | Bob Beck <beck@cvs.openbsd.org> | 1999-03-01 01:07:30 +0000 |
| commit | 21d723c6847eebcff10c51f4ca9a9f2f90cdea59 (patch) | |
| tree | f9556634aa856b074e95cf0e9aeff4b39f785ae5 /usr.sbin/httpd/htdocs | |
| parent | 5376803c9e4a906a4befe58a0c30f3ed32f270bb (diff) | |
Apache 1.3.4 merge
Diffstat (limited to 'usr.sbin/httpd/htdocs')
28 files changed, 4368 insertions, 2471 deletions
diff --git a/usr.sbin/httpd/htdocs/manual/LICENSE b/usr.sbin/httpd/htdocs/manual/LICENSE index ec09d302feb..6ac6538b3ca 100644 --- a/usr.sbin/httpd/htdocs/manual/LICENSE +++ b/usr.sbin/httpd/htdocs/manual/LICENSE @@ -1,5 +1,5 @@ /* ==================================================================== - * Copyright (c) 1995-1997 The Apache Group. All rights reserved. + * Copyright (c) 1995-1999 The Apache Group. All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -20,9 +20,14 @@ * * 4. The names "Apache Server" and "Apache Group" must not be used to * endorse or promote products derived from this software without - * prior written permission. + * prior written permission. For written permission, please contact + * apache@apache.org. * - * 5. Redistributions of any form whatsoever must retain the following + * 5. Products derived from this software may not be called "Apache" + * nor may "Apache" appear in their names without prior written + * permission of the Apache Group. + * + * 6. Redistributions of any form whatsoever must retain the following * acknowledgment: * "This product includes software developed by the Apache Group * for use in the Apache HTTP server project (http://www.apache.org/)." diff --git a/usr.sbin/httpd/htdocs/manual/content-negotiation.html b/usr.sbin/httpd/htdocs/manual/content-negotiation.html index ad4eae9fa57..044e196f587 100644 --- a/usr.sbin/httpd/htdocs/manual/content-negotiation.html +++ b/usr.sbin/httpd/htdocs/manual/content-negotiation.html @@ -15,27 +15,29 @@ <DIV ALIGN="CENTER"> <IMG SRC="images/sub.gif" ALT="[APACHE DOCUMENTATION]"> <H3> - Apache HTTP Server Version 1.2 + Apache HTTP Server Version 1.3 </H3> </DIV> -<h1 ALIGN="CENTER">Content Negotiation</h1> +<H1 ALIGN="CENTER">Content Negotiation</H1> +<P> 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. <p> +browsers which send incomplete negotiation information. <P> -Content negotiation is provided by the -<a href="mod/mod_negotiation.html">mod_negotiation</a> module, +Content negotiation is provided by the +<A HREF="mod/mod_negotiation.html">mod_negotiation</A> module, which is compiled in by default. -<hr> +<HR> -<h2>About Content Negotiation</h2> +<H2>About Content Negotiation</H2> +<P> 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 @@ -48,13 +50,14 @@ information in French, if possible, else English will do. Browsers indicate their preferences by headers in the request. To request only French representations, the browser would send -<pre> +<PRE> Accept-Language: fr -</pre> +</PRE> +<P> Note that this preference will only be applied when there is a choice -of representations and they vary by language. -<p> +of representations and they vary by language. +<P> As an example of a more complex request, this browser has been configured to accept French and English, but prefer French, and to @@ -62,52 +65,54 @@ accept various media types, preferring HTML over plain text or other text types, and preferring GIF or JPEG over other media types, but also allowing any other media type as a last resort: -<pre> +<PRE> 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 -</pre> +</PRE> 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. -<p> +<P> -The terms used in content negotiation are: a <b>resource</b> is an +The terms used in content negotiation are: a <STRONG>resource</STRONG> is an item which can be requested of a server, which might be selected as the result of a content negotiation algorithm. If a resource is -available in several formats, these are called <b>representations</b> -or <b>variants</b>. The ways in which the variants for a particular -resource vary are called the <b>dimensions</b> of negotiation. +available in several formats, these are called <STRONG>representations</STRONG> +or <STRONG>variants</STRONG>. The ways in which the variants for a particular +resource vary are called the <STRONG>dimensions</STRONG> of negotiation. -<h2>Negotiation in Apache</h2> +<H2>Negotiation in Apache</H2> +<P> 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: +ways: -<ul> - <li> Using a type map (i.e., a <code>*.var</code> file) which +<UL> + <LI> Using a type map (<EM>i.e.</EM>, a <CODE>*.var</CODE> file) which names the files containing the variants explicitly - <li> Or using a 'MultiViews' search, where the server does an implicit + <LI> Or using a 'MultiViews' search, where the server does an implicit filename pattern match, and chooses from among the results. -</ul> +</UL> -<h3>Using a type-map file</h3> +<H3>Using a type-map file</H3> +<P> A type map is a document which is associated with the handler -named <code>type-map</code> (or, for backwards-compatibility with +named <CODE>type-map</CODE> (or, for backwards-compatibility with older Apache configurations, the mime type -<code>application/x-type-map</code>). Note that to use this feature, -you've got to have a <code>SetHandler</code> some place which defines a -file suffix as <code>type-map</code>; this is best done with a -<pre> +<CODE>application/x-type-map</CODE>). Note that to use this feature, +you've got to have a <CODE>SetHandler</CODE> some place which defines a +file suffix as <CODE>type-map</CODE>; this is best done with a +<PRE> AddHandler type-map var -</pre> -in <code>srm.conf</code>. See comments in the sample config files for -details. <p> +</PRE> +in <CODE>srm.conf</CODE>. See comments in the sample config files for +details. <P> Type map files have an entry for each available variant; these entries consist of contiguous RFC822-format header lines. Entries for @@ -116,7 +121,7 @@ illegal within an entry. It is conventional to begin a map file with an entry for the combined entity as a whole (although this is not required, and if present will be ignored). An example map file is: -<pre> +<PRE> URI: foo @@ -127,12 +132,12 @@ map file is: URI: foo.fr.de.html Content-type: text/html; charset=iso-8859-2 Content-language: fr, de -</pre> +</PRE> 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): -<pre> +<PRE> URI: foo URI: foo.jpeg @@ -144,82 +149,83 @@ as jpeg, gif, or ASCII-art): URI: foo.txt Content-type: text/plain; qs=0.01 -</pre> -<p> +</PRE> +<P> qs values can vary between 0.000 and 1.000. Note that any variant with a qs value of 0.000 will never be chosen. Variants with no 'qs' -parameter value are given a qs factor of 1.0. <p> +parameter value are given a qs factor of 1.0. <P> The full list of headers recognized is: -<dl> - <dt> <code>URI:</code> - <dd> uri of the file containing the variant (of the given media +<DL> + <DT> <CODE>URI:</CODE> + <DD> 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. - <dt> <code>Content-type:</code> - <dd> media type --- charset, level and "qs" parameters may be given. These + directly. + <DT> <CODE>Content-type:</CODE> + <DD> media type --- charset, level and "qs" parameters may be given. These are often referred to as MIME types; typical media types are - <code>image/gif</code>, <code>text/plain</code>, or - <code>text/html; level=3</code>. - <dt> <code>Content-language:</code> - <dd> The languages of the variant, specified as an Internet standard - language code (e.g., <code>en</code> for English, - <code>kr</code> for Korean, etc.). - <dt> <code>Content-encoding:</code> - <dd> If the file is compressed, or otherwise encoded, rather than + <CODE>image/gif</CODE>, <CODE>text/plain</CODE>, or + <CODE>text/html; level=3</CODE>. + <DT> <CODE>Content-language:</CODE> + <DD> The languages of the variant, specified as an Internet standard + language code (<EM>e.g.</EM>, <CODE>en</CODE> for English, + <CODE>kr</CODE> for Korean, <EM>etc.</EM>). + <DT> <CODE>Content-encoding:</CODE> + <DD> If the file is compressed, or otherwise encoded, rather than containing the actual raw data, this says how that was done. For compressed files (the only case where this generally comes up), content encoding should be - <code>x-compress</code>, or <code>x-gzip</code>, as appropriate. - <dt> <code>Content-length:</code> - <dd> The size of the file. Clients can ask to receive a given media + <CODE>x-compress</CODE>, or <CODE>x-gzip</CODE>, as appropriate. + <DT> <CODE>Content-length:</CODE> + <DD> The size of the file. Clients can ask to receive a given media type only if the variant isn't too big; specifying a content length in the map allows the server to compare against these thresholds without checking the actual file. -</dl> +</DL> -<h3>Multiviews</h3> +<H3>Multiviews</H3> +<P> This is a per-directory option, meaning it can be set with an -<code>Options</code> directive within a <code><Directory></code>, -<code><Location></code> or <code><Files></code> -section in <code>access.conf</code>, or (if <code>AllowOverride</code> -is properly set) in <code>.htaccess</code> files. Note that -<code>Options All</code> does not set <code>MultiViews</code>; you +<CODE>Options</CODE> directive within a <CODE><Directory></CODE>, +<CODE><Location></CODE> or <CODE><Files></CODE> +section in <CODE>access.conf</CODE>, or (if <CODE>AllowOverride</CODE> +is properly set) in <CODE>.htaccess</CODE> files. Note that +<CODE>Options All</CODE> does not set <CODE>MultiViews</CODE>; you have to ask for it by name. (Fixing this is a one-line change to -<code>http_core.h</code>). +<CODE>http_core.h</CODE>). -<p> +<P> -The effect of <code>MultiViews</code> is as follows: if the server -receives a request for <code>/some/dir/foo</code>, if -<code>/some/dir</code> has <code>MultiViews</code> enabled, and -<code>/some/dir/foo</code> does <em>not</em> exist, then the server reads the +The effect of <CODE>MultiViews</CODE> is as follows: if the server +receives a request for <CODE>/some/dir/foo</CODE>, if +<CODE>/some/dir</CODE> has <CODE>MultiViews</CODE> enabled, and +<CODE>/some/dir/foo</CODE> does <EM>not</EM> exist, then the server reads the directory looking for files named foo.*, and effectively fakes up a type map which names all those files, assigning them the same media types and content-encodings it would have if the client had asked for one of them by name. It then chooses the best match to the client's requirements, and forwards them along. -<p> +<P> This applies to searches for the file named by the -<code>DirectoryIndex</code> directive, if the server is trying to +<CODE>DirectoryIndex</CODE> directive, if the server is trying to index a directory; if the configuration files specify -<pre> +<PRE> DirectoryIndex index -</pre> then the server will arbitrate between <code>index.html</code> -and <code>index.html3</code> if both are present. If neither are -present, and <code>index.cgi</code> is there, the server will run it. +</PRE> then the server will arbitrate between <CODE>index.html</CODE> +and <CODE>index.html3</CODE> if both are present. If neither are +present, and <CODE>index.cgi</CODE> is there, the server will run it. -<p> +<P> 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 @@ -229,7 +235,7 @@ 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. -<h2>The Negotiation Algorithm</h2> +<H2>The Negotiation Algorithm</H2> 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 @@ -238,99 +244,105 @@ any. To do this it calculates a quality value for each variant in each of the dimensions of variance. It is not necessary to know any of the details of how negotiation actually takes place in order to use Apache's content negotiation features. However the rest of this document -explains in detail the algorithm used for those interested. <p> +explains in detail the algorithm used for those interested. <P> In some circumstances, Apache can '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. -<h3>Dimensions of Negotiation</h3> +<H3>Dimensions of Negotiation</H3> -<table> -<tr><th>Dimension -<th>Notes -<tr><td>Media Type -<td>Browser indicates preferences on Accept: header. Each item +<TABLE> +<TR><TH>Dimension +<TH>Notes +<TR><TD>Media Type +<TD>Browser indicates preferences on Accept: header. Each item can have an associated quality factor. Variant description can also have a quality factor. -<tr><td>Language -<td>Browser indicates preferences on Accept-Language: header. Each +<TR><TD>Language +<TD>Browser indicates preferences on Accept-Language: header. Each item can have a quality factor. Variants can be associated with none, one or more languages. -<tr><td>Encoding -<td>Browser indicates preference with Accept-Encoding: header. -<tr><td>Charset -<td>Browser indicates preference with Accept-Charset: header. Variants +<TR><TD>Encoding +<TD>Browser indicates preference with Accept-Encoding: header. +<TR><TD>Charset +<TD>Browser indicates preference with Accept-Charset: header. Variants can indicate a charset as a parameter of the media type. -</table> +</TABLE> -<h3>Apache Negotiation Algorithm</h3> +<H3>Apache Negotiation Algorithm</H3> +<P> Apache uses an algorithm to select the 'best' variant (if any) to return to the browser. This algorithm is not configurable. It operates like this: -<p> -<ol> -<li> +<OL> +<LI> Firstly, for each dimension of the negotiation, the appropriate Accept header is checked and a quality assigned to this each variant. If the Accept header for any dimension means that this variant is not acceptable, eliminate it. If no variants remain, go to step 4. -<li>Select the 'best' variant by a process of elimination. Each of +<LI>Select the 'best' variant by a process of elimination. Each of the following tests is applied in order. Any variants not selected at each stage are eliminated. After each test, if only one variant remains, it is selected as the best match. If more than one variant remains, move onto the next test. -<ol> -<li>Multiply the quality factor from the Accept header with the +<OL> +<LI>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 -<li>Select the variants with the highest language quality factor +<LI>Select the variants with the highest language quality factor -<li>Select the variants with the best language match, using either the - order of languages on the <code>LanguagePriority</code> directive (if present), +<LI>Select the variants with the best language match, using either the + order of languages on the <CODE>LanguagePriority</CODE> directive (if + present), else the order of languages on the Accept-Language header. -<li>Select the variants with the highest 'level' media parameter - (used to give the version of text/html media types). +<LI>Select the variants with the highest 'level' media parameter + (used to give the version of text/html media types). -<li>Select only unencoded variants, if there is a mix of encoded - and non-encoded variants. If either all variants are encoded - or all variants are not encoded, select all. +<LI>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. -<li>Select only variants with acceptable charset media parameters, +<LI>Select only variants with acceptable charset media parameters, as given on the Accept-Charset header line. Charset ISO-8859-1 is always acceptable. Variants not associated with a particular charset are assumed to be in ISO-8859-1. -<li>Select the variants with the smallest content length +<LI>Select the variants with the smallest content length -<li>Select the first variant of those remaining (this will be either the +<LI>Select the first variant of those remaining (this will be either the first listed in the type-map file, or the first read from the directory) and go to stage 3. -</ol> +</OL> -<li>The algorithm has now selected one 'best' variant, so return +<LI>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. -<li>To get here means no variant was selected (because non are acceptable +<LI>To get here means no variant was selected (because non are acceptable to the browser). Return a 406 status (meaning "No acceptable representation") with a response body consisting of an HTML document listing the available variants. Also set the HTTP Vary header to indicate the dimensions of variance. -</ol> -<h2><a name="better">Fiddling with Quality Values</a></h2> +</OL> + +<H2><A NAME="better">Fiddling with Quality Values</A></H2> +<P> Apache sometimes changes the quality values from what would be expected by a strict interpretation of the algorithm above. This is to get a better result from the algorithm for browsers which do not send @@ -339,24 +351,25 @@ Accept header information which would otherwise result in the selection of the wrong variant in many cases. If a browser sends full and correct information these fiddles will not be applied. -<p> +<P> -<h3>Media Types and Wildcards</h3> +<H3>Media Types and Wildcards</H3> +<P> 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: -<pre> +<PRE> Accept: image/*, */* -</pre> +</PRE> 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: -<pre> +<PRE> Accept: text/html, text/plain, image/gif, image/jpeg, */* -</pre> +</PRE> The intention of this is to indicate that the explicitly listed types are preferred, but if a different representation is @@ -365,72 +378,163 @@ 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: -<pre> +<PRE> Accept: text/html, text/plain, image/gif, image/jpeg, */*; q=0.01 -</pre> +</PRE> 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. -<p> +no variant matches an explicitly listed type. +<P> -If the Accept: header contains <i>no</i> q factors at all, Apache sets +If the Accept: header contains <EM>no</EM> 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 <i>not</i> applied, so requests from browsers +these special values are <EM>not</EM> applied, so requests from browsers which send the correct information to start with work as expected. -<h3>Variants with no Language</h3> +<H3>Variants with no Language</H3> +<P> 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.<p> +are given a very low language quality factor of 0.001.<P> 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. +other variants match the browser's language preferences. For example, consider the situation with three variants: -<ul> -<li>foo.en.html, language en -<li>foo.fr.html, language en -<li>foo.html, no language -</ul> +<UL> +<LI>foo.en.html, language en +<LI>foo.fr.html, language en +<LI>foo.html, no language +</UL> +<P> 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. -<h2>Note on Caching</h2> - +<H2>Note on hyperlinks and naming conventions</H2> + +<P> +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 <A HREF="mod/mod_mime.html">mod_mime</A> documentation for details). +<P> +A typical file has a MIME-type extension (<EM>e.g.</EM>, <SAMP>html</SAMP>), +maybe an encoding extension (<EM>e.g.</EM>, <SAMP>gz</SAMP>), and of course a +language extension (<EM>e.g.</EM>, <SAMP>en</SAMP>) when we have different +language variants of this file. + +<P> +Examples: +<UL> +<LI>foo.en.html +<LI>foo.html.en +<LI>foo.en.html.gz +</UL> + +<P> +Here some more examples of filenames together with valid and invalid +hyperlinks: +</P> + +<TABLE BORDER=1 CELLPADDING=8 CELLSPACING=0> +<TR> + <TH>Filename</TH> + <TH>Valid hyperlink</TH> + <TH>Invalid hyperlink</TH> +</TR> +<TR> + <TD><EM>foo.html.en</EM></TD> + <TD>foo<BR> + foo.html</TD> + <TD>-</TD> +</TR> +<TR> + <TD><EM>foo.en.html</EM></TD> + <TD>foo</TD> + <TD>foo.html</TD> +</TR> +<TR> + <TD><EM>foo.html.en.gz</EM></TD> + <TD>foo<BR> + foo.html</TD> + <TD>foo.gz<BR> + foo.html.gz</TD> +</TR> +<TR> + <TD><EM>foo.en.html.gz</EM></TD> + <TD>foo</TD> + <TD>foo.html<BR> + foo.html.gz<BR> + foo.gz</TD> +</TR> +<TR> + <TD><EM>foo.gz.html.en</EM></TD> + <TD>foo<BR> + foo.gz<BR> + foo.gz.html</TD> + <TD>foo.html</TD> +</TR> +<TR> + <TD><EM>foo.html.gz.en</EM></TD> + <TD>foo<BR> + foo.html<BR> + foo.html.gz</TD> + <TD>foo.gz</TD> +</TR> +</TABLE> + +<P> +Looking at the table above you will notice that it is always possible to +use the name without any extensions in an hyperlink (<EM>e.g.</EM>, <SAMP>foo</SAMP>). +The advantage is that you can hide the actual type of a +document rsp. file and can change it later, <EM>e.g.</EM>, from <SAMP>html</SAMP> +to <SAMP>shtml</SAMP> or <SAMP>cgi</SAMP> without changing any +hyperlink references. + +<P> +If you want to continue to use a MIME-type in your hyperlinks (<EM>e.g.</EM> +<SAMP>foo.html</SAMP>) the language extension (including an encoding extension +if there is one) must be on the right hand side of the MIME-type extension +(<EM>e.g.</EM>, <SAMP>foo.html.en</SAMP>). + + +<H2>Note on Caching</H2> + +<P> When a cache stores a document, it associates it with the request URL. The next time that URL is requested, the cache can use the stored document, provided it is still within date. But if the resource is subject to content negotiation at the server, this would result in only the first requested variant being cached, and subsequent cache -hits could return the wrong response. To prevent this, +hits could 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 +as non-cacheable by HTTP/1.0 clients. Apache also supports the HTTP/1.1 protocol features to allow caching of negotiated responses. <P> For requests which come from a HTTP/1.0 compliant client (either a -browser or a cache), the directive <tt>CacheNegotiatedDocs</tt> can be +browser or a cache), the directive <TT>CacheNegotiatedDocs</TT> 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. <HR> -<H3 ALIGN="CENTER"> - Apache HTTP Server Version 1.2 -</H3> + <H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 + </H3> <A HREF="./"><IMG SRC="images/index.gif" ALT="Index"></A> diff --git a/usr.sbin/httpd/htdocs/manual/dso.html b/usr.sbin/httpd/htdocs/manual/dso.html index da6d0f13978..4c48262512b 100644 --- a/usr.sbin/httpd/htdocs/manual/dso.html +++ b/usr.sbin/httpd/htdocs/manual/dso.html @@ -183,6 +183,7 @@ platforms are supported. The definitive current state (May 1998) is this: o FreeBSD (2.1.5, 2.2.5, 2.2.6) o OpenBSD (2.x) o NetBSD (1.3.1) +o BSDI (4.0) o Linux (Debian/1.3.1, RedHat/4.2) o Solaris (2.4, 2.5.1, 2.6) o SunOS (4.1.3) diff --git a/usr.sbin/httpd/htdocs/manual/handler.html b/usr.sbin/httpd/htdocs/manual/handler.html index 43a0047228c..597ea8cd9e4 100644 --- a/usr.sbin/httpd/htdocs/manual/handler.html +++ b/usr.sbin/httpd/htdocs/manual/handler.html @@ -15,136 +15,190 @@ <DIV ALIGN="CENTER"> <IMG SRC="images/sub.gif" ALT="[APACHE DOCUMENTATION]"> <H3> - Apache HTTP Server Version 1.2 + Apache HTTP Server Version 1.3 </H3> </DIV> -<h1 ALIGN="CENTER">Apache's Handler Use</h1> +<H1 ALIGN="CENTER">Apache's Handler Use</H1> -<h2>What is a Handler</h2> +<H2>What is a Handler</H2> -<p>A "handler" is an internal Apache representation of the action to be +<P>A "handler" is an internal Apache representation of the action to be performed when a file is called. Generally, files have implicit handlers, based on the file type. Normally, all files are simply served by the server, but certain file typed are "handled" separately. For example, you may use a type of -"application/x-httpd-cgi" to invoke CGI scripts.</p> +"application/x-httpd-cgi" to invoke CGI scripts.</P> -<p>Apache 1.1 adds the additional ability to use handlers +<P>Apache 1.1 adds the additional ability to use handlers explicitly. Either based on filename extensions or on location, these handlers are unrelated to file type. This is advantageous both because it is a more elegant solution, but it also allows for both a type -<strong>and</strong> a handler to be associated with a file.</p> - -<p>Handlers can either be built into the server or to a module, or -they can be added with the <a -href="mod/mod_actions.html#action">Action</a> directive. The built-in -handlers in the standard distribution are as follows:</p> - -<ul> -<li><strong>send-as-is</strong>: +<STRONG>and</STRONG> a handler to be associated with a file (See also +<A HREF="mod/mod_mime#multipleext">Files with Multiple Extensions</A>) + +</P> + +<P>Handlers can either be built into the server or to a module, or +they can be added with the <A +HREF="mod/mod_actions.html#action">Action</A> directive. The built-in +handlers in the standard distribution are as follows:</P> + +<UL> +<LI><STRONG>default-handler</STRONG>: + Send the file using the <CODE>default_handler()</CODE>, which is the + handler used by default to handle static content. + (core) +<LI><STRONG>send-as-is</STRONG>: Send file with HTTP headers as is. - (<a href="mod/mod_asis.html">mod_asis</a>) -<li><strong>cgi-script</strong>: + (<A HREF="mod/mod_asis.html">mod_asis</A>) +<LI><STRONG>cgi-script</STRONG>: Treat the file as a CGI script. - (<a href="mod/mod_cgi.html">mod_cgi</a>) -<li><strong>imap-file</strong>: + (<A HREF="mod/mod_cgi.html">mod_cgi</A>) +<LI><STRONG>imap-file</STRONG>: Imagemap rule file. - (<a href="mod/mod_imap.html">mod_imap</a>) -<li><strong>server-info</strong>: + (<A HREF="mod/mod_imap.html">mod_imap</A>) +<LI><STRONG>server-info</STRONG>: Get the server's configuration information - (<a href="mod/mod_info.html">mod_info</a>) -<li><strong>server-parsed</strong>: + (<A HREF="mod/mod_info.html">mod_info</A>) +<LI><STRONG>server-parsed</STRONG>: Parse for server-side includes - (<a href="mod/mod_include.html">mod_include</a>) -<li><strong>server-status</strong>: + (<A HREF="mod/mod_include.html">mod_include</A>) +<LI><STRONG>server-status</STRONG>: Get the server's status report - (<a href="mod/mod_status.html">mod_status</a>) -<li><strong>type-map</strong>: + (<A HREF="mod/mod_status.html">mod_status</A>) +<LI><STRONG>type-map</STRONG>: Parse as a type map file for content negotiation - (<a href="mod/mod_negotiation.html">mod_negotiation</a>) -</ul> - -<p> + (<A HREF="mod/mod_negotiation.html">mod_negotiation</A>) +</UL> -<h2>Directives</h2> -<ul> -<li><A HREF="#addhandler">AddHandler</A> -<li><A HREF="#sethandler">SetHandler</A> -</ul> +<P> -<hr> +<H2>Directives</H2> +<UL> +<LI><A HREF="#addhandler">AddHandler</A> +<LI><A HREF="#sethandler">SetHandler</A> +</UL> -<h2><a name="addhandler">AddHandler</a></h2> - -<strong>Syntax:</strong> <AddHandler <em>handler-name extension</em>><br> -<strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_mime +<HR> -<p>AddHandler maps the filename extension <em>extension</em> to the -handler <em>handler-name</em>. For example, to activate CGI scripts -with the file extension "<code>.cgi</code>", you might use: -<pre> +<H2><A NAME="addhandler">AddHandler</A></H2> + +<A + HREF="mod/directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> AddHandler <EM>handler-name extension extension...</EM><BR> +<A + HREF="mod/directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> +<A + HREF="mod/directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> FileInfo<BR> +<A + HREF="mod/directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="mod/directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_mime<BR> +<A + HREF="mod/directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> AddHandler is only available in Apache +1.1 and later<P> + +<P>AddHandler maps the filename extensions <EM>extension</EM> to the +handler <EM>handler-name</EM>. This mapping is added to any already +in force, overriding any mappings that already exist for the same +<EM>extension</EM>. + +For example, to activate CGI scripts +with the file extension "<CODE>.cgi</CODE>", you might use: +<PRE> AddHandler cgi-script cgi -</pre> +</PRE> -<p>Once that has been put into your srm.conf or httpd.conf file, any -file ending with "<code>.cgi</code>" will be treated as a CGI -program.</p> +<P>Once that has been put into your srm.conf or httpd.conf file, any +file containing the "<CODE>.cgi</CODE>" extension will be treated as a +CGI program.</P> -<hr> +<P> -<h2><a name="sethandler">SetHandler</a></h2> +<STRONG>See also</STRONG>: <A HREF="mod/mod_mime.html#multipleext">Files with +multiple extensions</A> -<strong>Syntax:</strong> <SetHandler <em>handler-name</em>><br> -<strong>Context:</strong> directory, .htaccess<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_mime +<HR> -<p>When placed into an <code>.htaccess</code> file or a -<code><Directory></code> or <code><Location></code> section, -this directive forces all matching files to be parsed through the -handler given by <em>handler-name</em>. For example, if you had a +<H2><A NAME="sethandler">SetHandler</A></H2> + +<A + HREF="mod/directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> SetHandler <EM>handler-name</EM><BR> +<A + HREF="mod/directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> directory, .htaccess<BR> +<A + HREF="mod/directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="mod/directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_mime<BR> +<A + HREF="mod/directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> SetHandler is only available in Apache +1.1 and later.<P> + +<P>When placed into an <CODE>.htaccess</CODE> file or a +<CODE><Directory></CODE> or <CODE><Location></CODE> +section, this directive forces all matching files to be parsed through +the handler given by <EM>handler-name</EM>. For example, if you had a directory you wanted to be parsed entirely as imagemap rule files, regardless of extension, you might put the following into an -<code>.htaccess</code> file in that directory: -<pre> +<CODE>.htaccess</CODE> file in that directory: +<PRE> SetHandler imap-file -</pre> -<p>Another example: if you wanted to have the server display a status -report whenever a URL of <code>http://servername/status</code> was +</PRE> + +<P>Another example: if you wanted to have the server display a status +report whenever a URL of <CODE>http://servername/status</CODE> was called, you might put the following into access.conf: -<pre> +<PRE> <Location /status> SetHandler server-status </Location> -</pre> - -<p><hr> +</PRE> +<HR> -<h2>Programmer's Note</h2> +<H2>Programmer's Note</H2> -<p>In order to implement the handler features, an addition has been -made to the <a href="misc/API.html">Apache API</a> that you may wish to +<P>In order to implement the handler features, an addition has been +made to the <A HREF="misc/API.html">Apache API</A> that you may wish to make use of. Specifically, a new record has been added to the -<code>request_rec</code> structure:</p> -<pre> +<CODE>request_rec</CODE> structure:</P> +<PRE> char *handler -</pre> -<p>If you wish to have your module engage a handler, you need only to -set <code>r->handler</code> to the name of the handler at any time -prior to the <code>invoke_handler</code> stage of the +</PRE> +<P>If you wish to have your module engage a handler, you need only to +set <CODE>r->handler</CODE> to the name of the handler at any time +prior to the <CODE>invoke_handler</CODE> 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.</p> +type name-space.</P> <HR> -<H3 ALIGN="CENTER"> - Apache HTTP Server Version 1.2 -</H3> + <H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 + </H3> <A HREF="./"><IMG SRC="images/index.gif" ALT="Index"></A> diff --git a/usr.sbin/httpd/htdocs/manual/index.html b/usr.sbin/httpd/htdocs/manual/index.html index dc967b83335..ff46a78f9a0 100644 --- a/usr.sbin/httpd/htdocs/manual/index.html +++ b/usr.sbin/httpd/htdocs/manual/index.html @@ -1,7 +1,7 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> <HTML> <HEAD> -<TITLE>Apache documentation</TITLE> +<TITLE>Apache 1.3 documentation</TITLE> </HEAD> <!-- Background white, links blue (unvisited), navy (visited), red (active) --> @@ -15,62 +15,58 @@ <DIV ALIGN="CENTER"> <IMG SRC="images/sub.gif" ALT="[APACHE DOCUMENTATION]"> <H3> - Apache HTTP Server Version 1.2 + Apache HTTP Server Version 1.3 </H3> </DIV> -<h1 ALIGN="CENTER">Apache User's Guide</h1> +<H1 ALIGN="CENTER">Apache 1.3 User's Guide</H1> -<hr> - -<h3><a name="new">Release Notes</a></h3> -<ul> -<li><a href="new_features_1_2.html">New features in Apache 1.2</a> -<li><a href="new_features_1_1.html">New features in Apache 1.1</a> -<li><a href="new_features_1_0.html">New features in Apache 1.0</a> -</ul> -<ul> -<li><a href="misc/known_bugs.html">Known Bugs</a> -<li><a href="misc/compat_notes.html">Compatibility Notes with NCSA httpd</a> -<li><a href="LICENSE">Apache License</A> -</ul> +<HR> -<H3><a name="ref">Apache Reference Manual</a></h3> +<H3><A NAME="new">Release Notes</A></H3> <UL> - <LI><A - HREF="http://www.apache.org/manual-index/docs" - ><STRONG>Search</STRONG></A> - the master manual pages for key words - </LI> +<LI><A HREF="new_features_1_3.html">New features in Apache 1.3</A> +<LI><A HREF="upgrading_to_1_3.html">Upgrading to Apache 1.3</A> +<LI><A HREF="LICENSE">Apache License</A> </UL> -<ul> -<li><A HREF="install.html">Compiling and Installing Apache</A> -<li><A HREF="invoking.html">Starting Apache</A> -<li><A HREF="stopping.html">Stopping or Restarting Apache</A> -<li><A HREF="mod/directives.html">Apache run-time configuration directives</A> -<li><A HREF="mod/">Apache modules</A> -<li><A HREF="handler.html">Apache's handler use</A> -<li><A HREF="env.html">Special purpose environment variables</A> -<LI><A HREF="misc/API.html">Highly generalized API to server functionality</A> + +<H3><A NAME="ref">Apache Reference Manual</A></H3> + +<UL> +<LI><A HREF="http://www.apache.org/manual-index.cgi/docs"> + <STRONG>Search</STRONG></A> for key words +<LI><A HREF="install.html">Compiling and Installing</A> +<LI><A HREF="invoking.html">Starting</A> +<LI><A HREF="stopping.html">Stopping or Restarting</A> +<LI><A HREF="mod/directives.html">Run-time configuration directives</A> +<LI><A HREF="mod/index.html">Modules</A> +<LI><A HREF="vhosts/index.html">Virtual Hosts</A> +<LI><A HREF="dso.html">Dynamic Shared Object (DSO) support</A> +<LI><A HREF="handler.html">Handlers</A> +<LI><A HREF="env.html">Special purpose environment variables</A> +<LI><A HREF="misc/API.html">The Apache API</A> <LI><A HREF="suexec.html">Using SetUserID Execution for CGI</A> -</ul> +</UL> -<h3><a name="oth">Other Notes</a></h3> -<ul> -<li><A HREF="misc/FAQ.html">Frequently Asked Questions list</a> -<li><A href="misc/howto.html">How do I? documentation</A> +<H3><A NAME="oth">Other Notes</A></H3> +<UL> +<LI><A HREF="misc/FAQ.html">Frequently Asked Questions</A> +<LI><A HREF="misc/perf-tuning.html">General Performance hints</A> for +getting the best performance out of Apache +<LI><A HREF="misc/perf.html">OS Specific Performance hints</A> to help +fine-tune specific platforms <LI><A HREF="misc/security_tips.html">Security tips</A> -<LI><A HREF="misc/perf.html">Performance hints</a> for heavily loaded web servers. +<LI><A HREF="misc/compat_notes.html">Compatibility Notes with NCSA httpd</A> +<LI><A HREF="misc/howto.html">How do I? documentation</A> <LI><A HREF="misc/fin_wait_2.html">Discussion of the FIN_WAIT_2 problem</A> -<LI><A - HREF="http://www.apache.org/info/jdk-102.html" - >Java's 1.0.2 virtual machine and HTTP/1.1</A> -</ul> +<LI><A HREF="misc/known_client_problems.html">Known problems with various + clients</A> +</UL> <HR> -<H3 ALIGN="CENTER"> - Apache HTTP Server Version 1.2 -</H3> + <H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 + </H3> <A HREF="./"><IMG SRC="images/index.gif" ALT="Index"></A> diff --git a/usr.sbin/httpd/htdocs/manual/install.html b/usr.sbin/httpd/htdocs/manual/install.html index 0bdc45c87df..73ab0d9a73f 100644 --- a/usr.sbin/httpd/htdocs/manual/install.html +++ b/usr.sbin/httpd/htdocs/manual/install.html @@ -15,15 +15,20 @@ <DIV ALIGN="CENTER"> <IMG SRC="images/sub.gif" ALT="[APACHE DOCUMENTATION]"> <H3> - Apache HTTP Server Version 1.2 + Apache HTTP Server Version 1.3 </H3> </DIV> -<H1 ALIGN="CENTER">Compiling and Installing Apache 1.2</H1> +<H1 ALIGN="CENTER">Compiling and Installing Apache 1.3</H1> -<P>If you wish to download and install an earlier version of Apache please -read <A HREF="install_1_1.html">Compiling and Installing Apache 1.1</A>.</P> +This document covers compilation and installation of Apache on Unix +systems only. For compiling and installation on Windows, see <A +HREF="windows.html">Using Apache with Microsoft Windows</A> and for +TPF see <A HREF="install-tpf.html">Installing the Apache 1.3 HTTP +Server on TPF</A>. + +<P> UnixWare users will want to consult <A HREF="unixware.html">build notes</A> for various UnixWare versions before compiling. @@ -34,7 +39,7 @@ Information on the latest version of Apache can be found on the Apache web server at <A HREF="http://www.apache.org/">http://www.apache.org/</A>. This will list the current release, any more recent beta-test release, together -with details of mirror web and anonymous ftp sites. +with details of mirror web and anonymous ftp sites. <P> @@ -42,10 +47,10 @@ If you downloaded a binary distribution, skip to <A HREF="#install">Installing Apache</A>. Otherwise read the next section for how to compile the server. -<h2>Compiling Apache</h2> +<H2>Compiling Apache</H2> Compiling Apache consists of three steps: Firstly select which Apache -<b>modules</b> you want to include into the server. Secondly create a +<STRONG>modules</STRONG> you want to include into the server. Secondly create a configuration for your operating system. Thirdly compile the executable. <P> @@ -57,7 +62,7 @@ directory of the Apache distribution. Change into this directory. <LI> Select modules to compile into Apache in the <CODE>Configuration</CODE> file. Uncomment lines corresponding to - those optional modules you wish to include (among the Module lines + those optional modules you wish to include (among the AddModule lines at the bottom of the file), or add new lines corresponding to additional modules you have downloaded or written. (See <A HREF="misc/API.html">API.html</A> for preliminary docs on how to @@ -74,11 +79,11 @@ directory of the Apache distribution. Change into this directory. <LI> Configure Apache for your operating system. Normally you can just type run the <CODE>Configure</CODE> script as given below. However - if this fails or you have any special requirements (e.g. to include + if this fails or you have any special requirements (<EM>e.g.</EM>, to include an additional library required by an optional module) you might need to edit one or more of the following options in the <CODE>Configuration</CODE> file: - <CODE>EXTRA_CFLAGS, LIBS, LFLAGS, INCLUDES</CODE>. + <CODE>EXTRA_CFLAGS, LIBS, LDFLAGS, INCLUDES</CODE>. <P> Run the <CODE>Configure</CODE> script: @@ -89,7 +94,12 @@ directory of the Apache distribution. Change into this directory. + configured for <whatever> platform + setting C compiler to <whatever> * + setting C compiler optimization-level to <whatever> * - % + + Adding selected modules + + doing sanity check on compiler and options + Creating Makefile in support + Creating Makefile in main + Creating Makefile in os/unix + Creating Makefile in modules/standard </PRE> </BLOCKQUOTE> @@ -114,12 +124,13 @@ directory of the Apache distribution. Change into this directory. The modules we place in the Apache distribution are the ones we have tested and are used regularly by various members of the Apache development group. Additional modules contributed by members or third -parties with specific needs or functions are available at <A -HREF="http://www.apache.org/dist/contrib/modules/"><URL:http://www.apache.org/dist/contrib/modules/></a>. +parties with specific needs or functions are available at +<<A HREF="http://www.apache.org/dist/contrib/modules/" + >http://www.apache.org/dist/contrib/modules/</A>>. There are instructions on that page for linking these modules into the core Apache code. -<h2><A NAME="install">Installing Apache</A></h2> +<H2><A NAME="install">Installing Apache</A></H2> You will have a binary file called <CODE>httpd</CODE> in the <CODE>src</CODE> directory. A binary distribution of Apache will @@ -129,10 +140,12 @@ The next step is to install the program and configure it. Apache is designed to be configured and run from the same set of directories where it is compiled. If you want to run it from somewhere else, make a directory and copy the <CODE>conf</CODE>, <CODE>logs</CODE> and -<CODE>icons</CODE> directories into it. <P> +<CODE>icons</CODE> directories into it. In either case you should +read the <A HREF="misc/security_tips.html#serverroot">security tips</A> +describing how to set the permissions on the server root directory.<P> The next step is to edit the configuration files for the server. This -consists of setting up various <B>directives</B> in up to three +consists of setting up various <STRONG>directives</STRONG> in up to three central configuration files. By default, these files are located in the <CODE>conf</CODE> directory and are called <CODE>srm.conf</CODE>, <CODE>access.conf</CODE> and <CODE>httpd.conf</CODE>. To help you get @@ -149,34 +162,42 @@ file usually does not need editing. <P> First edit <CODE>httpd.conf</CODE>. This sets up general attributes -about the server: the port number, the user it runs as, etc. Next +about the server: the port number, the user it runs as, <EM>etc.</EM> Next edit the <CODE>srm.conf</CODE> file; this sets up the root of the document tree, special functions like server-parsed HTML or internal -imagemap parsing, etc. Finally, edit the <CODE>access.conf</CODE> +imagemap parsing, <EM>etc.</EM> Finally, edit the <CODE>access.conf</CODE> file to at least set the base cases of access. <P> In addition to these three files, the server behavior can be configured on a directory-by-directory basis by using <CODE>.htaccess</CODE> -files in directories accessed by the server. +files in directories accessed by the server. + +<H3>Set your system time properly!</H3> + +Proper operation of a public web server requires accurate time +keeping, since elements of the HTTP protocol are expressed as the time +of day. So, it's time to investigate setting up NTP or some other +time synchronization system on your Unix box, or whatever the +equivalent on NT would be. <H3>Starting and Stopping the Server</H3> To start the server, simply run <CODE>httpd</CODE>. This will look for <CODE>httpd.conf</CODE> in the location compiled into the code (by -default <CODE>/usr/locale/etc/httpd/conf/httpd.conf</CODE>). If +default <CODE>/usr/local/apache/conf/httpd.conf</CODE>). If this file is somewhere else, you can give the real location with the -f argument. For example: <PRE> - /usr/local/etc/apache/src/httpd -f /usr/local/etc/apache/conf/httpd.conf + /usr/local/apache/httpd -f /usr/local/apache/conf/httpd.conf </PRE> If all goes well this will return to the command prompt almost immediately. This indicates that the server is now up and running. If anything goes wrong during the initialization of the server you will -see an error message on the screen. +see an error message on the screen. If the server started ok, you can now use your browser to connect to the server and read the documentation. If you are running @@ -190,10 +211,10 @@ port of 80, a suitable URL to enter into your browser is <P> Note that when the server starts it will create a number of -<i>child</i> processes to handle the requests. If you started Apache +<EM>child</EM> processes to handle the requests. If you started Apache as the root user, the parent process will continue to run as root while the children will change to the user as given in the httpd.conf -file. +file. <P> @@ -216,7 +237,7 @@ this will be located in the file <CODE>error_log</CODE> in the If you want your server to continue running after a system reboot, you should add a call to <CODE>httpd</CODE> to your system startup files (typically <CODE>rc.local</CODE> or a file in an -<CODE>rc.<I>N</I></CODE> directory). This will start Apache as root. +<CODE>rc.<EM>N</EM></CODE> directory). This will start Apache as root. Before doing this ensure that your server is properly configured for security and access restrictions. @@ -229,7 +250,7 @@ attempt to kill the child processes because they will be renewed by the parent. A typical command to stop the server is: <PRE> - kill -TERM `cat /usr/local/etc/apache/logs/httpd.pid` + kill -TERM `cat /usr/local/apache/logs/httpd.pid` </PRE> <P> @@ -251,9 +272,9 @@ the support programs, change into this directory and type </PRE> <HR> -<H3 ALIGN="CENTER"> - Apache HTTP Server Version 1.2 -</H3> + <H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 + </H3> <A HREF="./"><IMG SRC="images/index.gif" ALT="Index"></A> diff --git a/usr.sbin/httpd/htdocs/manual/invoking.html b/usr.sbin/httpd/htdocs/manual/invoking.html index b960916cfee..22f3dc07bad 100644 --- a/usr.sbin/httpd/htdocs/manual/invoking.html +++ b/usr.sbin/httpd/htdocs/manual/invoking.html @@ -15,120 +15,205 @@ <DIV ALIGN="CENTER"> <IMG SRC="images/sub.gif" ALT="[APACHE DOCUMENTATION]"> <H3> - Apache HTTP Server Version 1.2 + Apache HTTP Server Version 1.3 </H3> </DIV> -<h1 ALIGN="CENTER">Starting Apache</h1> +<H1 ALIGN="CENTER">Starting Apache</H1> -<h2>Invoking Apache</h2> -The <code>httpd</code> program is usually run as a daemon which executes -continuously, handling requests. It is possible to invoke Apache by -the Internet daemon <code>inetd</code> each time a connection to the HTTP -service is made (use the -<A HREF="mod/core.html#servertype">ServerType</A> directive) -but this is not recommended. +<H2>Invoking Apache</H2> -<h2>Command line options</h2> +On Unix, the <CODE>httpd</CODE> program is usually run as a daemon +which executes continuously, handling requests. It is possible to +invoke Apache by the Internet daemon <CODE>inetd</CODE> each time a +connection to the HTTP service is made (use the <A +HREF="mod/core.html#servertype">ServerType</A> directive) but this is +not recommended. + +<P> + +On Windows, Apache is normally run as a service on Windows NT, or as a +console application on Windows 95. See also <A +HREF="windows.html#run">running Apache for Windows</A>. + +<H2>Command line options</H2> The following options are recognized on the httpd command line: -<dl> -<dt><code>-d</code> <em>serverroot</em> -<dd>Set the initial value for the +<DL> +<DT><CODE>-d</CODE> <EM>serverroot</EM> +<DD>Set the initial value for the <A HREF="mod/core.html#serverroot">ServerRoot</A> variable to -<em>serverroot</em>. This can be overridden by the ServerRoot command in the -configuration file. The default is <code>/usr/local/etc/httpd</code>. - -<dt><code>-f</code> <em>config</em> -<dd>Execute the commands in the file <em>config</em> on startup. If -<em>config</em> does not begin with a <code>/</code>, then it is taken to be a +<EM>serverroot</EM>. This can be overridden by the ServerRoot command +in the configuration file. The default is +<CODE>/usr/local/apache</CODE> on Unix, <CODE>/apache</CODE> on +Windows and <CODE>/os2httpd</CODE> on OS/2. + +<DT><CODE>-D</CODE> <EM>name</EM> +<DD>Define a name for use in in +<A HREF="mod/core.html#ifdefine">IfDefine</A> directives. +This option can be used to optionally enable certain functionality in the +configuration file, or to use a common configuration for +several independent hosts, where host specific information is enclosed in +<IfDefine> sections. + +<DT><CODE>-f</CODE> <EM>config</EM> +<DD>Execute the commands in the file <EM>config</EM> on startup. If +<EM>config</EM> does not begin with a <CODE>/</CODE>, then it is taken to be a path relative to the <A HREF="mod/core.html#serverroot">ServerRoot</A>. The -default is <code>conf/httpd.conf</code>. +default is <CODE>conf/httpd.conf</CODE>. + +<DT><CODE>-C</CODE> <EM>"directive"</EM> +<DD>Process the given apache "directive" (just as if it had been part of a +configuration file) <STRONG>before</STRONG> actually reading the regular configuration files. + +<DT><CODE>-c</CODE> <EM>"directive"</EM> +<DD>Process the given apache "directive" <STRONG>after</STRONG> reading +all the regular configuration files. -<dt><code>-X</code> -<dd>Run in single-process mode, for internal debugging purposes only; the -daemon does not detach from the terminal or fork any children. Do <em>NOT</em> +<DT><CODE>-X</CODE> +<DD>Run in single-process mode, for internal debugging purposes only; the +daemon does not detach from the terminal or fork any children. Do <EM>NOT</EM> use this mode to provide ordinary web service. -<dt><code>-v</code> -<dd>Print the version of httpd, and then exit. +<DT><CODE>-v</CODE> +<DD>Print the version of httpd and its build date, and then exit. + +<DT><A NAME="version"><CODE>-V</CODE></A> +<DD>Print the base version of httpd, its +build date, and a list of compile time settings which influence the +behavior and performance of the apache server (<EM>e.g.</EM>, +<SAMP>-DUSE_MMAP_FILES</SAMP>), +then exit. + +<DT><A NAME="help"><CODE>-L</CODE></A> +<DD> + +Give a list of directives together with expected arguments and places +where the directive is valid, then exit. (Apache 1.3.4 and +later. Earlier versions used -l instead). + + +<DT><CODE>-l</CODE></A> +<DD> + +Give a list of all modules compiled into the server, then exit. +(Apache 1.3.4 and later. Earlier versions used -h instead).<br> -<dt><a name="help"><code>-h</code></a> -<dd>Give a list of directives together with expected arguments and -places where the directive is valid. (New in Apache 1.2) +Give a list of directives together with expected arguments and places +where the directive is valid, then exit. (Apache 1.2 to 1.3.3. Later +versions use -L instead). -<dt><code>-l</code> -<dd>Give a list of all modules compiled into the server. -<dt><code>-?</code> -<dd>Print a list of the httpd options, and then exit. -</dl> -<h2>Configuration files</h2> -The server will read three files for configuration directives. Any directive -may appear in any of these files. The the names of these files are taken -to be relative to the server root; this is set by the -<A HREF="mod/core.html#serverroot">ServerRoot</A> directive, or the -<code>-d</code> command line flag. +<DT><CODE>-h</CODE> +<DD> + +Print a list of the httpd options, then exit. (Apache 1.3.4 and +later. Earlier versions used -? instead).<br> + +Give a list of all modules compiled into the server, then exit. (Up to +Apache 1.3.3. Later versions use -l instead).<br> + + +<DT><CODE>-S</CODE> +<DD>Show the settings as parsed from the config file (currently only +shows a breakdown of the vhost settings) but do not start the +server. (Up to Apache 1.3.3, this option also started the server). + +<DT><CODE>-t</CODE> +<DD>Test the configuration file syntax (<EM>i.e.</EM>, read all configuration files +and interpret them) but do not start the server. If the configuration contains +errors, display an error message and exit with a non-zero exit status, +otherwise display "Syntax OK" and terminate with a zero exit status. + +<DT><CODE>-k</CODE> <EM>option</EM> +<DD>Windows only: signal Apache to restart or shutdown. <EM>option</EM> +is one of "shutdown" or "restart". (Apache 1.3.3 and later). + +<DT><CODE>-?</CODE> +<DD>Print a list of the httpd options, and then exit (up to Apache +1.3.3. Later version use -h instead). + +</DL> + +<H2>Configuration files</H2> +The server will read three files for configuration directives. Any +directive may appear in any of these files. The the names of these +files are taken to be relative to the server root; this is set by the +<A HREF="mod/core.html#serverroot">ServerRoot</A> directive, the +<CODE>-d</CODE> command line flag, or (on Windows only) the registry +(see <A HREF="windows.html#run">Running Apache for Windows</A>). Conventionally, the files are: -<dl> -<dt><code>conf/httpd.conf</code> -<dd>Contains directives that control the operation of the server daemon. -The filename may be overridden with the <code>-f</code> command line flag. +<DL> +<DT><CODE>conf/httpd.conf</CODE> +<DD>Contains directives that control the operation of the server daemon. +The filename may be overridden with the <CODE>-f</CODE> command line flag. -<dt><code>conf/srm.conf</code> -<dd>Contains directives that control the specification of documents that +<DT><CODE>conf/srm.conf</CODE> +<DD>Contains directives that control the specification of documents that the server can provide to clients. The filename may be overridden with the <A HREF="mod/core.html#resourceconfig">ResourceConfig</A> directive. -<dt><code>conf/access.conf</code> -<dd>Contains directives that control access to documents. +<DT><CODE>conf/access.conf</CODE> +<DD>Contains directives that control access to documents. The filename may be overridden with the <A HREF="mod/core.html#accessconfig">AccessConfig</A> directive. -</dl> +</DL> However, these conventions need not be adhered to. -<p> +<P> The server also reads a file containing mime document types; the filename -is set by the <A HREF="mod/mod_mime.html#typesconfig">TypesConfig</A> directive, -and is <code>conf/mime.types</code> by default. +is set by the <A HREF="mod/mod_mime.html#typesconfig">TypesConfig</A> +directive, +and is <CODE>conf/mime.types</CODE> by default. -<h2>Log files</h2> -<h3>security warning</h3> +<H2>Log files</H2> +<H3>security warning</H3> 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 <EM>NOT</EM> give people write access to the directory the logs are stored in without being aware of the consequences; see the <A HREF="misc/security_tips.html">security tips</A> document for details. -<h3>pid file</h3> -On daemon startup, it saves the process id of the parent httpd process to -the file <code>logs/httpd.pid</code>. This filename can be changed with the -<A HREF="mod/core.html#pidfile">PidFile</A> directive. The process-id is for -use by the administrator in restarting and terminating the daemon; -A HUP or USR1 signal causes the daemon to re-read its configuration files and -a TERM signal causes it to die gracefully. For more information -see the <a href="stopping.html">Stopping and Restarting</a> page. -<p> +<H3>pid file</H3> + +On startup, Apache saves the process id of the parent httpd process to +the file <CODE>logs/httpd.pid</CODE>. This filename can be changed +with the <A HREF="mod/core.html#pidfile">PidFile</A> directive. The +process-id is for use by the administrator in restarting and +terminating the daemon: on Unix, a HUP or USR1 signal causes the +daemon to re-read its configuration files and a TERM signal causes it +to die gracefully; on Windows, use the -k command line option instead. +For more information see the <A HREF="stopping.html">Stopping and +Restarting</A> page. + +<P> If the process dies (or is killed) abnormally, then it will be necessary to kill the children httpd processes. -<h3>Error log</h3> -The server will log error messages to a log file, <code>logs/error_log</code> -by default. The filename can be set using the -<A HREF="mod/core.html#errorlog">ErrorLog</A> directive; different error logs can -be set for different <A HREF="mod/core.html#virtualhost">virtual hosts</A>. +<H3>Error log</H3> -<h3>Transfer log</h3> -The server will typically log each request to a transfer file, -<code>logs/access_log</code> by default. The filename can be set using a -<A HREF="mod/mod_log_common.html#transferlog">TransferLog</A> directive; different -transfer logs can be set for different <A HREF="mod/core.html#virtualhost">virtual -hosts</A>. +The server will log error messages to a log file, by default +<CODE>logs/error_log</CODE> on Unix or <CODE>logs/error.log</CODE> on +OS/2. The filename can be set using the <A +HREF="mod/core.html#errorlog">ErrorLog</A> directive; different error +logs can be set for different <A +HREF="mod/core.html#virtualhost">virtual hosts</A>. + +<H3>Transfer log</H3> + +The server will typically log each request to a transfer file, by +default <CODE>logs/access_log</CODE> on Unix or +<CODE>logs/access.log</CODE> on OS/2. The filename can be set using a +<A HREF="mod/mod_log_config.html#transferlog">TransferLog</A> +directive or additional log files created with the <A +HREF="mod/mod_log_config.html#customlog">CustomLog</A> directive; +different transfer logs can be set for different <A +HREF="mod/core.html#virtualhost">virtual hosts</A>. <HR> -<H3 ALIGN="CENTER"> - Apache HTTP Server Version 1.2 -</H3> + <H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 + </H3> <A HREF="./"><IMG SRC="images/index.gif" ALT="Index"></A> diff --git a/usr.sbin/httpd/htdocs/manual/misc/FAQ.html b/usr.sbin/httpd/htdocs/manual/misc/FAQ.html index 767a5759eb0..d7d335f7810 100644 --- a/usr.sbin/httpd/htdocs/manual/misc/FAQ.html +++ b/usr.sbin/httpd/htdocs/manual/misc/FAQ.html @@ -20,7 +20,7 @@ <H1 ALIGN="CENTER">Apache Server Frequently Asked Questions</H1> <P> - $Revision: 1.2 $ ($Date: 1998/10/11 19:45:05 $) + $Revision: 1.3 $ ($Date: 1999/03/01 01:05:09 $) </P> <P> The latest version of this FAQ is always available from the main @@ -85,6 +85,8 @@ <!-- (A: you can't but "satisfy any; allow from all" can be close --> <!-- - '400 malformed request' on Win32 might mean stale proxy; see --> <!-- PR #2300. --> +<!-- - "expected </Directory> saw </Directory" due to buggy AIX --> +<!-- compiler. --> <UL> <LI><STRONG>Background</STRONG> <OL START=1> @@ -194,9 +196,6 @@ </LI> <LI><A HREF="#SSL-i">Why doesn't Apache include SSL?</A> </LI> - <LI><A HREF="#HPUX-core">Why do I get core dumps under HPUX using - HP's ANSI C compiler?</A> - </LI> <LI><A HREF="#midi">How do I get Apache to send a MIDI file so the browser can play it?</A> </LI> @@ -732,6 +731,12 @@ whatever language you <EM>are</EM> using (<EM>e.g.</EM>, for C, call <CODE>fflush()</CODE> after writing the headers). </P> + <P> + Another cause for the "premature end of script headers" + message are the RLimitCPU and RLimitMEM directives. You may + get the message if the CGI script was killed due to a + resource limit. + </P> <HR> </LI> @@ -1242,7 +1247,7 @@ The simple answer is that it was becoming too difficult to keep the version being included with Apache synchronized with the master copy at the - <A HREF="http://www.fastcgi.com/servers/apache/" + <A HREF="http://www.fastcgi.com/" >FastCGI web site</A>. When a new version of Apache was released, the version of the FastCGI module included with it would soon be out of date. </P> @@ -1436,18 +1441,6 @@ <HR> </LI> - <LI><A NAME="HPUX-core"> - <STRONG>Why do I get core dumps under HPUX using HP's ANSI - C compiler?</STRONG> - </A> - <P> - We have had numerous reports of Apache dumping core when compiled - with HP's ANSI C compiler using optimization. Disabling the compiler - optimization has fixed these problems. - </P> - <HR> - </LI> - <LI><A NAME="midi"> <STRONG>How do I get Apache to send a MIDI file so the browser can play it?</STRONG> @@ -1717,7 +1710,7 @@ <BR> AuthUserFile /usr/local/apache/conf/htpasswd.users <BR> - AuthName special directory + AuthName "special directory" <BR> require valid-user <BR> diff --git a/usr.sbin/httpd/htdocs/manual/misc/compat_notes.html b/usr.sbin/httpd/htdocs/manual/misc/compat_notes.html index b6594d354e6..3a6a1c40f8d 100644 --- a/usr.sbin/httpd/htdocs/manual/misc/compat_notes.html +++ b/usr.sbin/httpd/htdocs/manual/misc/compat_notes.html @@ -1,6 +1,8 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML><HEAD> -<TITLE>Apache HTTP Server: Compatibility Notes with NCSA's Server</TITLE> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" + "http://www.w3.org/TR/REC-html40/loose.dtd"> +<HTML> +<HEAD> +<TITLE>Apache HTTP Server: Notes about Compatibility with NCSA's Server</TITLE> </HEAD> <!-- Background white, links blue (unvisited), navy (visited), red (active) --> <BODY @@ -13,7 +15,7 @@ <DIV ALIGN="CENTER"> <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> <H3> - Apache HTTP Server Version 1.2 + Apache HTTP Server Version 1.3 </H3> </DIV> @@ -21,125 +23,114 @@ <HR> -While Apache 0.8.x and beyond are for the most part a drop-in -replacement for NCSA's httpd and earlier versions of Apache, there are -a couple gotcha's to watch out for. These are mostly due to the fact -that the parser for config and access control files was rewritten from -scratch, so certain liberties the earlier servers took may not be -available here. These are all easily fixable. If you know of other -non-fatal problems that belong here, <a -href="http://www.apache.org/bugdb.cgi">let us know.</a> - -<P>Please also check the <A HREF="known_bugs.html">known bugs</A> page. - +While Apache is for the most part a drop-in replacement for NCSA's +httpd, there are a couple gotcha's to watch out for. These are mostly +due to the fact that the parser for config and access control files +was rewritten from scratch, so certain liberties the earlier servers +took may not be available here. These are all easily fixable. If you +know of other non-fatal problems that belong here, <A +HREF="http://www.apache.org/bug_report.html">let us know.</A> +<P>Please also check the <A HREF="known_client_problems.html">known +client problems</A> page. <OL> +<LI>As of Apache 1.3.1, methods named in a + <A HREF="../mod/core.html#limit"><SAMP><Limit></SAMP></A> + section <EM>must</EM> be listed in upper-case. Lower- or mixed-case + method names will result in a configuration error. + <P> + </P> +</LI> <LI>The basic mod_auth <CODE>AuthGroupFile</CODE>-specified group file - format allows commas between user names - Apache does not.<BR> - <I>- added 12/1/96</I> - <p> - - <LI><P>If you follow the NCSA guidelines for setting up access restrictions - based on client domain, you may well have added entries for, - <CODE>AuthType, AuthName, AuthUserFile</CODE> or <CODE>AuthGroupFile</CODE>. - <B>None</B> of these are needed (or appropriate) for restricting access - based on client domain. - - <P>When Apache sees <CODE>AuthType</CODE> it (reasonably) assumes you - are using some authorization type based on username and password. - - <P>Please remove <CODE>AuthType</CODE>, it's unnecessary even for NCSA. - - <P> - - <LI><CODE>AuthUserFile</CODE> requires a full pathname. In earlier - versions of NCSA httpd and Apache, you could use a filename - relative to the .htaccess file. This could be a major security hole, - as it made it trivially easy to make a ".htpass" file in the a - directory easily accessible by the world. We recommend you store - your passwords outside your document tree. - - <P> - - <LI><CODE>OldScriptAlias</CODE> is no longer supported. - - <P> - - <LI><CODE>exec cgi=""</CODE> produces reasonable <B>malformed header</B> - responses when used to invoke non-CGI scripts.<BR> - The NCSA code ignores the missing header. (bad idea)<BR> - Solution: write CGI to the CGI spec or use <CODE>exec cmd=""</CODE> instead. - <P>We might add <CODE>virtual</CODE> support to <CODE>exec cmd</CODE> to - make up for this difference. - - <P> - - <LI><Limit> silliness - in the old Apache 0.6.5, a - directive of <Limit GET> would also restrict POST methods - Apache 0.8.8's new - core is correct in not presuming a limit on a GET is the same limit on a POST, - so if you are relying on that behavior you need to change your access configurations - to reflect that. - - <P> - - <LI>Icons for FancyIndexing broken - well, no, they're not broken, - we've just upgraded the - icons from flat .xbm files to pretty and much smaller .gif files, courtesy of -<a href="mailto:kevinh@eit.com">Kevin Hughes</a> at -<a href="http://www.eit.com/">EIT</a>. - If you are using the same srm.conf from an old distribution, make sure - you add the new - <A - HREF="../mod/mod_dir.html#addicon" - >AddIcon</A>, - <A - HREF="../mod/mod_dir.html#addiconbytype" - >AddIconByType</A>, - and - <A - HREF="../mod/mod_dir.html#defaulticon" - >DefaultIcon</A> - directives. - - <P> - - <LI>Under IRIX, the "Group" directive in httpd.conf needs to be a - valid group name - (<EM>i.e.</EM>, "nogroup") not the numeric group ID. The distribution - httpd.conf, and earlier ones, had the default Group be "#-1", which - was causing silent exits at startup.<p> - -<li><code>.asis</code> files: Apache 0.6.5 did not require a Status header; -it added one automatically if the .asis file contained a Location header. -0.8.14 requires a Status header. <p> - - <P> - <LI>Apache versions before 1.2b1 will ignore the last line of configuration - files if the last line does not have a trailing newline. This affects - configuration files (httpd.conf, access.conf and srm.conf), and - htpasswd and htgroup files. - </LI> - - <LI>Apache does not permit commas delimiting the methods in <Limit>. - - <LI>Apache's <CODE><VirtualHost></CODE> treats all addresses as - "optional" (i.e. the server should continue booting if it can't resolve - the address). Whereas in NCSA the default is to fail booting unless - an added <code>optional</code> keyword is included. - - <LI>Apache does not implement <CODE>OnDeny</CODE> use - <a href="../mod/core.html#errordocument"><code>ErrorDocument</code></a> - instead. + format allows commas between user names - Apache does not. + +<P> +<LI>If you follow the NCSA guidelines for setting up access + restrictions based on client domain, you may well have added + entries for, <CODE>AuthType, AuthName, AuthUserFile</CODE> or + <CODE>AuthGroupFile</CODE>. <STRONG>None</STRONG> of these are + needed (or appropriate) for restricting access based on client + domain. When Apache sees <CODE>AuthType</CODE> it (reasonably) + assumes you are using some authorization type based on username + and password. Please remove <CODE>AuthType</CODE>, it's + unnecessary even for NCSA. + +<P> +<LI><CODE>OldScriptAlias</CODE> is no longer supported. + +<P> +<LI><CODE>exec cgi=""</CODE> produces reasonable <STRONG>malformed + header</STRONG> responses when used to invoke non-CGI scripts.<BR> + The NCSA code ignores the missing header. (bad idea) + <BR>Solution: write CGI to the CGI spec and use + <CODE>include virtual</CODE>, or use <CODE>exec cmd=""</CODE> instead. + +<P> +<LI>Icons for FancyIndexing broken - well, no, they're not broken, + we've just upgraded the icons from flat .xbm files to pretty and + much smaller .gif files, courtesy of <A + HREF="mailto:kevinh@eit.com">Kevin Hughes</A> at <A + HREF="http://www.eit.com/">EIT</A>. If you are using the same + srm.conf from an old distribution, make sure you add the new <A + HREF="../mod/mod_autoindex.html#addicon">AddIcon</A>, <A + HREF="../mod/mod_autoindex.html#addiconbytype">AddIconByType</A>, + and <A + HREF="../mod/mod_autoindex.html#defaulticon">DefaultIcon</A> + directives. + +<P> +<LI>Apache versions before 1.2b1 will ignore the last line of configuration + files if the last line does not have a trailing newline. This affects + configuration files (httpd.conf, access.conf and srm.conf), and + htpasswd and htgroup files. + +<P> +<LI>Apache does not permit commas delimiting the methods in <Limit>. + +<P> +<LI>Apache's <CODE><VirtualHost></CODE> treats all addresses as + "optional" (<EM>i.e.</EM>, the server should continue booting if it can't + resolve the address). Whereas in NCSA the default is to fail + booting unless an added <CODE>optional</CODE> keyword is included. + +<P> +<LI>Apache does not implement <CODE>OnDeny</CODE> use + <A HREF="../mod/core.html#errordocument"><CODE>ErrorDocument</CODE></A> + instead. + +<P> +<LI>Apache (as of 1.3) always performs the equivalent of + <CODE>HostnameLookups minimal</CODE>. <CODE>minimal</CODE> is not an + option to <A HREF="../mod/core.html#hostnamelookups"><CODE> + HostnameLookups</CODE></A>. + +<P> +<LI>To embed spaces in directive arguments NCSA used a backslash + before the space. Apache treats backslashes as normal characters. To + embed spaces surround the argument with double-quotes instead. + +<P> +<LI>Apache does not implement the NCSA <CODE>referer</CODE> + directive. See <A HREF="http://bugs.apache.org/index/full/968"> + PR#968</A> for a few brief suggestions on alternative ways to + implement the same thing under Apache. + +<P> +<LI>Apache does not allow ServerRoot settings inside a VirtualHost + container. There is only one global ServerRoot in Apache; any desired + changes in paths for virtual hosts need to be made with the explicit + directives, eg. DocumentRoot, TransferLog, <EM>etc.</EM> </OL> More to come when we notice them.... <HR> + <H3 ALIGN="CENTER"> - Apache HTTP Server Version 1.2 + Apache HTTP Server Version 1.3 </H3> <A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> diff --git a/usr.sbin/httpd/htdocs/manual/misc/howto.html b/usr.sbin/httpd/htdocs/manual/misc/howto.html index c3ddf868066..62f1116656a 100644 --- a/usr.sbin/httpd/htdocs/manual/misc/howto.html +++ b/usr.sbin/httpd/htdocs/manual/misc/howto.html @@ -1,7 +1,8 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> <HTML> <HEAD> -<META NAME="description" CONTENT="Some 'how to' tips for the Apache httpd server"> +<META NAME="description" + CONTENT="Some 'how to' tips for the Apache httpd server"> <META NAME="keywords" CONTENT="apache,redirect,robots,rotate,logfiles"> <TITLE>Apache HOWTO documentation</TITLE> </HEAD> @@ -17,56 +18,64 @@ <DIV ALIGN="CENTER"> <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> <H3> - Apache HTTP Server Version 1.2 + Apache HTTP Server Version 1.3 </H3> </DIV> <H1 ALIGN="CENTER">Apache HOWTO documentation</H1> How to: -<ul> -<li><A HREF="#redirect">redirect an entire server or directory to a single URL</A> -<li><A HREF="#logreset">reset your log files</A> -<li><A HREF="#stoprob">stop/restrict robots</A> -</ul> +<UL> +<LI><A HREF="#redirect">redirect an entire server or directory to a single + URL</A> +<LI><A HREF="#logreset">reset your log files</A> +<LI><A HREF="#stoprob">stop/restrict robots</A> +<LI><A HREF="#proxyssl">proxy SSL requests <EM>through</EM> your non-SSL + server</A> +</UL> <HR> -<H2><A name="redirect">How to redirect an entire server or directory to a single URL</A></H2> +<H2><A NAME="redirect">How to redirect an entire server or directory to a +single URL</A></H2> <P>There are two chief ways to redirect all requests for an entire server to a single location: one which requires the use of -<code>mod_rewrite</code>, and another which uses a CGI script. +<CODE>mod_rewrite</CODE>, and another which uses a CGI script. <P>First: if all you need to do is migrate a server from one name to -another, simply use the <code>Redirect</code> directive, as supplied -by <code>mod_alias</code>: +another, simply use the <CODE>Redirect</CODE> directive, as supplied +by <CODE>mod_alias</CODE>: -<blockquote><pre> +<BLOCKQUOTE><PRE> Redirect / http://www.apache.org/ -</pre></blockquote> +</PRE></BLOCKQUOTE> -<P>Since <code>Redirect</code> will forward along the complete path, +<P>Since <CODE>Redirect</CODE> will forward along the complete path, however, it may not be appropriate - for example, when the directory structure has changed after the move, and you simply want to direct people to the home page. -<P>The best option is to use the standard Apache module <code>mod_rewrite</code>. -If that module is compiled in, the following lines: +<P>The best option is to use the standard Apache module +<CODE>mod_rewrite</CODE>. +If that module is compiled in, the following lines -<blockquote><pre>RewriteEngine On +<BLOCKQUOTE><PRE>RewriteEngine On RewriteRule /.* http://www.apache.org/ [R] -</pre></blockquote> +</PRE></BLOCKQUOTE> This will send an HTTP 302 Redirect back to the client, and no matter what they gave in the original URL, they'll be sent to "http://www.apache.org". -The second option is to set up a <CODE>ScriptAlias</Code> pointing to -a <B>cgi script</B> which outputs a 301 or 302 status and the location +The second option is to set up a <CODE>ScriptAlias</CODE> pointing to +a <STRONG>CGI script</STRONG> which outputs a 301 or 302 status and the +location of the other server.</P> -<P>By using a <B>cgi-script</B> you can intercept various requests and -treat them specially, e.g. you might want to intercept <B>POST</B> +<P>By using a <STRONG>CGI script</STRONG> you can intercept various requests +and +treat them specially, <EM>e.g.</EM>, you might want to intercept +<STRONG>POST</STRONG> requests, so that the client isn't redirected to a script on the other server which expects POST information (a redirect will lose the POST information.) You might also want to use a CGI script if you don't @@ -74,21 +83,22 @@ want to compile mod_rewrite into your server. <P>Here's how to redirect all requests to a script... In the server configuration file, -<blockquote><pre>ScriptAlias / /usr/local/httpd/cgi-bin/redirect_script</pre></blockquote> +<BLOCKQUOTE><PRE>ScriptAlias / /usr/local/httpd/cgi-bin/redirect_script</PRE> +</BLOCKQUOTE> and here's a simple perl script to redirect requests: -<blockquote><pre> +<BLOCKQUOTE><PRE> #!/usr/local/bin/perl print "Status: 302 Moved Temporarily\r Location: http://www.some.where.else.com/\r\n\r\n"; -</pre></blockquote></P> +</PRE></BLOCKQUOTE></P> <HR> -<H2><A name="logreset">How to reset your log files</A></H2> +<H2><A NAME="logreset">How to reset your log files</A></H2> <P>Sooner or later, you'll want to reset your log files (access_log and error_log) because they are too big, or full of old information you don't @@ -104,16 +114,19 @@ logfile moved. This results in a new logfile being created which is just as big as the old one, but it now contains thousands (or millions) of null characters.</P> -<P>The correct procedure is to move the logfile, then signal Apache to tell it to reopen the logfiles.</P> +<P>The correct procedure is to move the logfile, then signal Apache to tell +it to reopen the logfiles.</P> -<P>Apache is signaled using the <B>SIGHUP</B> (-1) signal. e.g. -<blockquote><code> +<P>Apache is signaled using the <STRONG>SIGHUP</STRONG> (-1) signal. +<EM>e.g.</EM> +<BLOCKQUOTE><CODE> mv access_log access_log.old<BR> kill -1 `cat httpd.pid` -</code></blockquote> +</CODE></BLOCKQUOTE> </P> -<P>Note: <code>httpd.pid</code> is a file containing the <B>p</B>rocess <B>id</B> +<P>Note: <CODE>httpd.pid</CODE> is a file containing the +<STRONG>p</STRONG>rocess <STRONG>id</STRONG> of the Apache httpd daemon, Apache saves this in the same directory as the log files.</P> @@ -121,22 +134,29 @@ files.</P> nightly or weekly basis.</P> <HR> -<H2><A name="stoprob">How to stop or restrict robots</A></H2> +<H2><A NAME="stoprob">How to stop or restrict robots</A></H2> <P>Ever wondered why so many clients are interested in a file called -<code>robots.txt</code> which you don't have, and never did have?</P> +<CODE>robots.txt</CODE> which you don't have, and never did have?</P> -<P>These clients are called <B>robots</B> (also known as crawlers, +<P>These clients are called <STRONG>robots</STRONG> (also known as crawlers, spiders and other cute name) - special automated clients which wander around the web looking for interesting resources.</P> -<P>Most robots are used to generate some kind of <em>web index</em> which -is then used by a <em>search engine</em> to help locate information.</P> +<P>Most robots are used to generate some kind of <EM>web index</EM> which +is then used by a <EM>search engine</EM> to help locate information.</P> -<P><code>robots.txt</code> provides a means to request that robots limit their +<P><CODE>robots.txt</CODE> provides a means to request that robots limit their activities at the site, or more often than not, to leave the site alone.</P> -<P>When the first robots were developed, they had a bad reputation for sending hundreds/thousands of requests to each site, often resulting in the site being overloaded. Things have improved dramatically since then, thanks to <A HREF="http://info.webcrawler.com/mak/projects/robots/guidelines.html"> Guidelines for Robot Writers</A>, but even so, some robots may <A HREF="http://www.zyzzyva.com/robots/alert/">exhibit unfriendly behavior</A> which the webmaster isn't willing to tolerate, and will want to stop.</P> +<P>When the first robots were developed, they had a bad reputation for +sending hundreds/thousands of requests to each site, often resulting +in the site being overloaded. Things have improved dramatically since +then, thanks to <A +HREF="http://info.webcrawler.com/mak/projects/robots/guidelines.html"> +Guidelines for Robot Writers</A>, but even so, some robots may exhibit +unfriendly behavior which the webmaster isn't willing to tolerate, and +will want to stop.</P> <P>Another reason some webmasters want to block access to robots, is to stop them indexing dynamic information. Many search engines will use the @@ -146,11 +166,53 @@ stale by the time people find it in a search engine.</P> <P>If you decide to exclude robots completely, or just limit the areas in which they can roam, create a <CODE>robots.txt</CODE> file; refer -to the <A HREF="http://info.webcrawler.com/mak/projects/robots/robots.html">robot information pages</A> provided by Martijn Koster for the syntax.</P> +to the <A HREF="http://info.webcrawler.com/mak/projects/robots/robots.html" +>robot information pages</A> provided by Martijn Koster for the syntax.</P> <HR> +<H2><A NAME="proxyssl">How to proxy SSL requests <EM>through</EM> + your non-SSL Apache server</A> + <BR> + <SMALL>(<EM>submitted by David Sedlock</EM>)</SMALL> +</H2> +<P> +SSL uses port 443 for requests for secure pages. If your browser just +sits there for a long time when you attempt to access a secure page +over your Apache proxy, then the proxy may not be configured to handle +SSL. You need to instruct Apache to listen on port 443 in addition to +any of the ports on which it is already listening: +</P> +<PRE> + Listen 80 + Listen 443 +</PRE> +<P> +Then set the security proxy in your browser to 443. That might be it! +</P> +<P> +If your proxy is sending requests to another proxy, then you may have +to set the directive ProxyRemote differently. Here are my settings: +</P> +<PRE> + ProxyRemote http://nicklas:80/ http://proxy.mayn.franken.de:8080 + ProxyRemote http://nicklas:443/ http://proxy.mayn.franken.de:443 +</PRE> +<P> +Requests on port 80 of my proxy <SAMP>nicklas</SAMP> are forwarded to +proxy<SAMP>.mayn.franken.de:8080</SAMP>, while requests on port 443 are +forwarded to <SAMP>proxy.mayn.franken.de:443</SAMP>. +If the remote proxy is not set up to +handle port 443, then the last directive can be left out. SSL requests +will only go over the first proxy. +</P> +<P> +Note that your Apache does NOT have to be set up to serve secure pages +with SSL. Proxying SSL is a different thing from using it. +</P> +<HR> + <H3 ALIGN="CENTER"> - Apache HTTP Server Version 1.2 + Apache HTTP Server Version 1.3 </H3> <A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> diff --git a/usr.sbin/httpd/htdocs/manual/misc/perf-hp.html b/usr.sbin/httpd/htdocs/manual/misc/perf-hp.html index 9db0a08c9ff..a65184609fb 100644 --- a/usr.sbin/httpd/htdocs/manual/misc/perf-hp.html +++ b/usr.sbin/httpd/htdocs/manual/misc/perf-hp.html @@ -50,6 +50,10 @@ default is 256 buckets and must be set to a power of two. This is accomplished with adb against the *disc* image of the kernel. The variable name is tcp_hash_size. +Notice that it's critically important that you use "W" to write a 32 bit +quantity, not "w" to write a 16 bit value when patching the disc image because +the tcp_hash_size variable is a 32 bit quantity. + <P> How to pick the value? Examine the output of diff --git a/usr.sbin/httpd/htdocs/manual/misc/perf-tuning.html b/usr.sbin/httpd/htdocs/manual/misc/perf-tuning.html index 9ab35a0340e..956a7febbc5 100644 --- a/usr.sbin/httpd/htdocs/manual/misc/perf-tuning.html +++ b/usr.sbin/httpd/htdocs/manual/misc/perf-tuning.html @@ -340,7 +340,7 @@ the inner loop. The loop looks like this (differences highlighted): implement a mutual exclusion semaphore. Only one child can have the mutex at any time. There are several choices for implementing these mutexes. The choice is defined in <CODE>src/conf.h</CODE> (pre-1.3) or -<CODE>src/main/conf.h</CODE> (1.3 or later). Some architectures +<CODE>src/include/ap_config.h</CODE> (1.3 or later). Some architectures do not have any locking choice made, on these architectures it is unsafe to use multiple <CODE>Listen</CODE> directives. @@ -432,7 +432,7 @@ and then single-socket servers will not serialize at all. <P>As discussed in <A - HREF="ftp://ds.internic.net/internet-drafts/draft-ietf-http-connection-00.txt" + HREF="http://www.ics.uci.edu/pub/ietf/http/draft-ietf-http-connection-00.txt" >draft-ietf-http-connection-00.txt</A> section 8, in order for an HTTP server to <STRONG>reliably</STRONG> implement the protocol it needs to shutdown each direction of the communication independently diff --git a/usr.sbin/httpd/htdocs/manual/mod/core.html b/usr.sbin/httpd/htdocs/manual/mod/core.html index f8734d1d9d7..f7a38be36bc 100644 --- a/usr.sbin/httpd/htdocs/manual/mod/core.html +++ b/usr.sbin/httpd/htdocs/manual/mod/core.html @@ -287,7 +287,8 @@ Allow use of the directives controlling specific directory features This directive sets the name of the authorization realm for a directory. This realm is given to the client so that the user knows which username and -password to send. +password to send. <SAMP>AuthName</SAMP> takes a single argument; +if the realm name contains spaces, it must be enclosed in quotation marks. It must be accompanied by <A HREF="#authtype">AuthType</A> and <A HREF="#require">require</A> directives, and directives such as <A HREF="mod_auth.html#authuserfile">AuthUserFile</A> and @@ -450,11 +451,11 @@ re-populated using the <A HREF="#addmodule">AddModule</A> directive.<P><HR> <A HREF="directive-dict.html#Override" REL="Help" -><STRONG>Override:</STRONG></A> AuthConfig<BR> +><STRONG>Override:</STRONG></A> Options<BR> <A HREF="directive-dict.html#Status" REL="Help" -><STRONG>Status:</STRONG></A> experimental<P> +><STRONG>Status:</STRONG></A> experimental<BR> <A HREF="directive-dict.html#Compatibility" REL="Help" @@ -818,7 +819,7 @@ responses.</A><P><HR> <A HREF="directive-dict.html#Syntax" REL="Help" -><STRONG>Syntax:</STRONG></A> ErrorLog ><EM>filename</EM>|<CODE>syslog[:facility]</CODE> +><STRONG>Syntax:</STRONG></A> ErrorLog <EM>filename</EM>|<CODE>syslog[:facility]</CODE> <BR> <A HREF="directive-dict.html#Default" @@ -2050,7 +2051,7 @@ See also <A HREF="#maxspareservers">MaxSpareServers</A> and <A HREF="directive-dict.html#Status" REL="Help" -><STRONG>Status:</STRONG></A> core<P> +><STRONG>Status:</STRONG></A> core<BR> <A HREF="directive-dict.html#Compatibility" REL="Help" @@ -3011,7 +3012,7 @@ a packet is sent. <STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess <BR> <A HREF="directive-dict.html#Override" REL="Help"> -<STRONG>Override:</STRONG></A> AuthConfig<BR> +<STRONG>Override:</STRONG></A> Options<BR> <A HREF="directive-dict.html#Compatibility" REL="Help"> <STRONG>Compatibility:</STRONG></A> UseCanonicalName is only available in Apache 1.3 and later<P> diff --git a/usr.sbin/httpd/htdocs/manual/mod/directives.html b/usr.sbin/httpd/htdocs/manual/mod/directives.html index e5d8fb839e1..57938e5b190 100644 --- a/usr.sbin/httpd/htdocs/manual/mod/directives.html +++ b/usr.sbin/httpd/htdocs/manual/mod/directives.html @@ -15,172 +15,216 @@ <DIV ALIGN="CENTER"> <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> <H3> - Apache HTTP Server Version 1.2 + Apache HTTP Server Version 1.3 </H3> </DIV> -<H1 ALIGN="CENTER">Apache directives</H1> - -<ul> -<li><A HREF="core.html#accessconfig">AccessConfig</A> -<li><A HREF="core.html#accessfilename">AccessFileName</A> -<li><A HREF="mod_actions.html#action">Action</A> -<li><A HREF="mod_dir.html#addalt">AddAlt</A> -<li><A HREF="mod_dir.html#addaltbyencoding">AddAltByEncoding</A> -<li><A HREF="mod_dir.html#addaltbytype">AddAltByType</A> -<li><A HREF="mod_dir.html#adddescription">AddDescription</A> -<li><A HREF="mod_mime.html#addencoding">AddEncoding</A> -<li><A HREF="mod_mime.html#addhandler">AddHandler</A> -<li><A HREF="mod_dir.html#addicon">AddIcon</A> -<li><A HREF="mod_dir.html#addiconbyencoding">AddIconByEncoding</A> -<li><A HREF="mod_dir.html#addiconbytype">AddIconByType</A> -<li><A HREF="mod_mime.html#addlanguage">AddLanguage</A> -<li><A HREF="core.html#addmodule">AddModule</A> -<li><A HREF="mod_mime.html#addtype">AddType</A> -<li><A HREF="mod_log_agent.html#agentlog">AgentLog</A> -<li><A HREF="mod_alias.html#alias">Alias</A> -<li><A HREF="mod_access.html#allow">allow</A> -<li><A HREF="core.html#allowoverride">AllowOverride</A> -<li><A HREF="mod_auth_anon.html#anonymous">Anonymous</A> -<li><A HREF="mod_auth_anon.html#Authoritative">Anonymous_Authoritative</A> -<li><A HREF="mod_auth_anon.html#LogEmail">Anonymous_LogEmail</A> -<li><A HREF="mod_auth_anon.html#MustGiveEmail">Anonymous_MustGiveEmail</A> -<li><A HREF="mod_auth_anon.html#NoUserID">Anonymous_NoUserID</A> -<li><A HREF="mod_auth_anon.html#VerifyEmail">Anonymous_VerifyEmail</A> -<li><A HREF="mod_auth.html#authauthoritative">AuthAuthoritative</A> -<li><A HREF="mod_auth_db.html#authdbauthoritative">AuthDBAuthoritative</A> -<li><A HREF="mod_auth_db.html#authdbgroupfile">AuthDBGroupFile</A> -<li><A HREF="mod_auth_dbm.html#authdbmauthoritative">AuthDBMAuthoritative</A> -<li><A HREF="mod_auth_dbm.html#authdbmgroupfile">AuthDBMGroupFile</A> -<li><A HREF="mod_auth_dbm.html#authdbmgroupfile">AuthDBMGroupFile</A> -<li><A HREF="mod_auth_db.html#authdbuserfile">AuthDBUserFile</A> -<li><A HREF="mod_auth_dbm.html#authdbmuserfile">AuthDBMUserFile</A> -<li><A HREF="mod_digest.html#authdigestfile">AuthDigestFile</A> -<li><A HREF="mod_auth.html#authgroupfile">AuthGroupFile</A> -<li><A HREF="core.html#authname">AuthName</A> -<li><A HREF="core.html#authtype">AuthType</A> -<li><A HREF="mod_auth.html#authuserfile">AuthUserFile</A> -<li><A HREF="core.html#bindaddress">BindAddress</A> -<li><A HREF="mod_browser.html#browsermatch">BrowserMatch</A> -<li><A HREF="mod_browser.html#browsermatchnocase">BrowserMatchNoCase</A> -<li><A HREF="mod_proxy.html#cachedefaultexpire">CacheDefaultExpire</A> -<li><A HREF="mod_proxy.html#cachedirlength">CacheDirLength</A> -<li><A HREF="mod_proxy.html#cachedirlevels">CacheDirLevels</A> -<li><A HREF="mod_proxy.html#cachegcinterval">CacheGcInterval</A> -<li><A HREF="mod_proxy.html#cachelastmodifiedfactor">CacheLastModifiedFactor</A> -<li><A HREF="mod_proxy.html#cachemaxexpire">CacheMaxExpire</A> -<li><A HREF="mod_negotiation.html#cachenegotiateddocs">CacheNegotiatedDocs</A> -<li><A HREF="mod_proxy.html#cacheroot">CacheRoot</A> -<li><A HREF="mod_proxy.html#cachesize">CacheSize</A> -<li><A HREF="core.html#clearmodulelist">ClearModuleList</A> -<li><A HREF="mod_usertrack.html#cookieexpires">CookieExpires</A> -<li><A HREF="mod_cookies.html#cookielog">CookieLog</A> (mod_cookies) -<li><A HREF="mod_log_config.html#cookielog">CookieLog</A> (mod_log_config) -<li><A HREF="mod_usertrack.html#cookietracking">CookieTracking</A> -<li><A HREF="mod_log_config.html#customlog">CustomLog</A> -<li><A HREF="mod_dir.html#defaulticon">DefaultIcon</A> -<li><A HREF="core.html#defaulttype">DefaultType</A> -<li><A HREF="mod_access.html#deny">deny</A> -<li><A HREF="core.html#directory"><Directory></A> -<li><A HREF="mod_dir.html#directoryindex">DirectoryIndex</A> -<li><A HREF="core.html#documentroot">DocumentRoot</A> -<li><A HREF="core.html#errordocument">ErrorDocument</A> -<li><A HREF="core.html#errorlog">ErrorLog</A> -<li><A HREF="mod_example.html#example">Example</A> -<li><A HREF="mod_expires.html#expiresactive">ExpiresActive</A> -<li><A HREF="mod_expires.html#expiresbytype">ExpiresByType</A> -<li><A HREF="mod_expires.html#expiresdefault">ExpiresDefault</A> -<li><A HREF="mod_dir.html#fancyindexing">FancyIndexing</A> -<li><A HREF="core.html#files"><Files></A> -<li><A HREF="mod_mime.html#forcetype">ForceType</A> -<li><A HREF="core.html#group">Group</A> -<li><A HREF="mod_headers.html#header">Header</A> -<li><A HREF="mod_dir.html#headername">HeaderName</A> -<li><A HREF="core.html#hostnamelookups">HostNameLookups</A> -<li><A HREF="core.html#identitycheck">IdentityCheck</A> -<li><A HREF="core.html#ifmodule"><IfModule></A> -<li><A HREF="mod_imap.html#imapbase">ImapBase</A> -<li><A HREF="mod_imap.html#imapdefault">ImapDefault</A> -<li><A HREF="mod_imap.html#imapmenu">ImapMenu</A> -<li><A HREF="mod_dir.html#indexignore">IndexIgnore</A> -<li><A HREF="mod_dir.html#indexoptions">IndexOptions</A> -<li><A HREF="core.html#keepalive">KeepAlive</A> -<li><A HREF="core.html#keepalivetimeout">KeepAliveTimeout</A> -<li><A HREF="mod_negotiation.html#languagepriority">LanguagePriority</A> -<li><A HREF="core.html#limit"><Limit></A> -<li><A HREF="core.html#listen">Listen</A> -<li><A HREF="mod_dld.html#loadfile">LoadFile</A> -<li><A HREF="mod_dld.html#loadmodule">LoadModule</A> -<li><A HREF="core.html#location"><Location></A> -<li><A HREF="core.html#lockfile">LockFile</A> -<li><A HREF="mod_log_config.html#logformat">LogFormat</A> -<li><A HREF="core.html#maxclients">MaxClients</A> -<li><A HREF="core.html#maxkeepaliverequests">MaxKeepAliveRequests</A> -<li><A HREF="core.html#maxrequestsperchild">MaxRequestsPerChild</A> -<li><A HREF="core.html#maxspareservers">MaxSpareServers</A> -<li><A HREF="mod_cern_meta.html#metadir">MetaDir</A> -<li><A HREF="mod_cern_meta.html#metasuffix">MetaSuffix</A> -<li><A HREF="core.html#minspareservers">MinSpareServers</A> -<li><A HREF="mod_proxy.html#nocache">NoCache</A> -<li><A HREF="core.html#options">Options</A> -<li><A HREF="mod_access.html#order">order</A> -<li><A HREF="mod_env.html#passenv">PassEnv</A> -<li><A HREF="core.html#pidfile">PidFile</A> -<li><A HREF="core.html#port">Port</A> -<li><A HREF="mod_proxy.html#proxyblock">ProxyBlock</A> -<li><A HREF="mod_proxy.html#proxypass">ProxyPass</A> -<li><A HREF="mod_proxy.html#proxyremote">ProxyRemote</A> -<li><A HREF="mod_proxy.html#proxyrequests">ProxyRequests</A> -<li><A HREF="mod_dir.html#readmename">ReadmeName</A> -<li><A HREF="mod_alias.html#redirect">Redirect</A> -<li><A HREF="mod_alias.html#redirectperm">RedirectPermanent</A> -<li><A HREF="mod_alias.html#redirecttemp">RedirectTemp</A> -<li><A HREF="mod_log_referer.html#refererignore">RefererIgnore</A> -<li><A HREF="mod_log_referer.html#refererlog">RefererLog</A> -<li><A HREF="core.html#require">require</A> -<li><A HREF="core.html#resourceconfig">ResourceConfig</A> -<li><A HREF="mod_rewrite.html#RewriteBase">RewriteBase</A> -<li><A HREF="mod_rewrite.html#RewriteCond">RewriteCond</A> -<li><A HREF="mod_rewrite.html#RewriteEngine">RewriteEngine</A> -<li><A HREF="mod_rewrite.html#RewriteLog">RewriteLog</A> -<li><A HREF="mod_rewrite.html#RewriteLogLevel">RewriteLogLevel</A> -<li><A HREF="mod_rewrite.html#RewriteMap">RewriteMap</A> -<li><A HREF="mod_rewrite.html#RewriteOptions">RewriteOptions</A> -<li><A HREF="mod_rewrite.html#RewriteRule">RewriteRule</A> -<li><A HREF="core.html#rlimitcpu">RLimitCPU</A> -<li><A HREF="core.html#rlimitmem">RLimitMEM</A> -<li><A HREF="core.html#rlimitnproc">RLimitNPROC</A> -<li><A HREF="core.html#satisfy">Satisfy</A> -<li><A HREF="core.html#scoreboardfile">ScoreBoardFile</A> -<li><A HREF="mod_actions.html#script">Script</A> -<li><A HREF="mod_alias.html#scriptalias">ScriptAlias</A> -<li><A HREF="mod_cgi.html#scriptlog">ScriptLog</A> -<li><A HREF="mod_cgi.html#scriptlogbuffer">ScriptLogBuffer</A> -<li><A HREF="mod_cgi.html#scriptloglength">ScriptLogLength</A> -<li><A HREF="core.html#sendbuffersize">SendBufferSize</A> -<li><A HREF="core.html#serveradmin">ServerAdmin</A> -<li><A HREF="core.html#serveralias">ServerAlias</A> -<li><A HREF="core.html#servername">ServerName</A> -<li><A HREF="core.html#serverpath">ServerPath</A> -<li><A HREF="core.html#serverroot">ServerRoot</A> -<li><A HREF="core.html#servertype">ServerType</A> -<li><A HREF="mod_env.html#setenv">SetEnv</A> -<li><A HREF="mod_mime.html#sethandler">SetHandler</A> -<li><A HREF="core.html#startservers">StartServers</A> -<li><A HREF="core.html#timeout">TimeOut</A> -<li><A HREF="mod_log_common.html#transferlog">TransferLog</A> (mod_log_common) -<li><A HREF="mod_log_config.html#transferlog">TransferLog</A> (mod_log_config) -<li><A HREF="mod_mime.html#typesconfig">TypesConfig</A> -<li><A HREF="mod_env.html#unsetenv">UnsetEnv</A> -<li><A HREF="core.html#user">User</A> -<li><A HREF="mod_userdir.html#userdir">UserDir</A> -<li><A HREF="core.html#virtualhost"><VirtualHost></A> -<li><A HREF="mod_include.html#xbithack">XBitHack</A> -</ul> +<H1 ALIGN="CENTER">Apache Directives</H1> +<P> +Each Apache directive available in the standard Apache distribution is +listed here. They are described using a consistent format, and there is +<A + HREF="directive-dict.html" + REL="Glossary" +>a dictionary</A> +of the terms used in their descriptions available. +</P> +<UL> +<LI><A HREF="core.html#accessconfig">AccessConfig</A> +<LI><A HREF="core.html#accessfilename">AccessFileName</A> +<LI><A HREF="mod_actions.html#action">Action</A> +<LI><A HREF="mod_autoindex.html#addalt">AddAlt</A> +<LI><A HREF="mod_autoindex.html#addaltbyencoding">AddAltByEncoding</A> +<LI><A HREF="mod_autoindex.html#addaltbytype">AddAltByType</A> +<LI><A HREF="mod_autoindex.html#adddescription">AddDescription</A> +<LI><A HREF="mod_mime.html#addencoding">AddEncoding</A> +<LI><A HREF="mod_mime.html#addhandler">AddHandler</A> +<LI><A HREF="mod_autoindex.html#addicon">AddIcon</A> +<LI><A HREF="mod_autoindex.html#addiconbyencoding">AddIconByEncoding</A> +<LI><A HREF="mod_autoindex.html#addiconbytype">AddIconByType</A> +<LI><A HREF="mod_mime.html#addlanguage">AddLanguage</A> +<LI><A HREF="core.html#addmodule">AddModule</A> +<LI><A HREF="mod_info.html#addmoduleinfo">AddModuleInfo</A> +<LI><A HREF="mod_mime.html#addtype">AddType</A> +<LI><A HREF="mod_log_agent.html#agentlog">AgentLog</A> +<LI><A HREF="mod_alias.html#alias">Alias</A> +<LI><A HREF="mod_alias.html#aliasmatch">AliasMatch</A> +<LI><A HREF="mod_access.html#allow">allow</A> +<LI><A HREF="core.html#allowoverride">AllowOverride</A> +<LI><A HREF="mod_auth_anon.html#anonymous">Anonymous</A> +<LI><A HREF="mod_auth_anon.html#Authoritative">Anonymous_Authoritative</A> +<LI><A HREF="mod_auth_anon.html#LogEmail">Anonymous_LogEmail</A> +<LI><A HREF="mod_auth_anon.html#MustGiveEmail">Anonymous_MustGiveEmail</A> +<LI><A HREF="mod_auth_anon.html#NoUserID">Anonymous_NoUserID</A> +<LI><A HREF="mod_auth_anon.html#VerifyEmail">Anonymous_VerifyEmail</A> +<LI><A HREF="mod_auth.html#authauthoritative">AuthAuthoritative</A> +<LI><A HREF="mod_auth_db.html#authdbauthoritative">AuthDBAuthoritative</A> +<LI><A HREF="mod_auth_db.html#authdbgroupfile">AuthDBGroupFile</A> +<LI><A HREF="mod_auth_dbm.html#authdbmauthoritative">AuthDBMAuthoritative</A> +<LI><A HREF="mod_auth_dbm.html#authdbmgroupfile">AuthDBMGroupFile</A> +<LI><A HREF="mod_auth_dbm.html#authdbmgroupfile">AuthDBMGroupFile</A> +<LI><A HREF="mod_auth_db.html#authdbuserfile">AuthDBUserFile</A> +<LI><A HREF="mod_auth_dbm.html#authdbmuserfile">AuthDBMUserFile</A> +<LI><A HREF="mod_digest.html#authdigestfile">AuthDigestFile</A> +<LI><A HREF="mod_auth.html#authgroupfile">AuthGroupFile</A> +<LI><A HREF="core.html#authname">AuthName</A> +<LI><A HREF="core.html#authtype">AuthType</A> +<LI><A HREF="mod_auth.html#authuserfile">AuthUserFile</A> +<LI><A HREF="core.html#bindaddress">BindAddress</A> +<LI><A HREF="mod_setenvif.html#BrowserMatch">BrowserMatch</A> +<LI><A HREF="mod_setenvif.html#BrowserMatchNoCase">BrowserMatchNoCase</A> +<LI><A HREF="core.html#bs2000account">BS2000Account</A> +<LI><A HREF="mod_proxy.html#cachedefaultexpire">CacheDefaultExpire</A> +<LI><A HREF="mod_proxy.html#cachedirlength">CacheDirLength</A> +<LI><A HREF="mod_proxy.html#cachedirlevels">CacheDirLevels</A> +<LI><A HREF="mod_proxy.html#cacheforcecompletion">CacheForceCompletion</A> +<LI><A HREF="mod_proxy.html#cachegcinterval">CacheGcInterval</A> +<LI><A HREF="mod_proxy.html#cachelastmodifiedfactor">CacheLastModifiedFactor</A> +<LI><A HREF="mod_proxy.html#cachemaxexpire">CacheMaxExpire</A> +<LI><A HREF="mod_negotiation.html#cachenegotiateddocs">CacheNegotiatedDocs</A> +<LI><A HREF="mod_proxy.html#cacheroot">CacheRoot</A> +<LI><A HREF="mod_proxy.html#cachesize">CacheSize</A> +<LI><A HREF="mod_speling.html#checkspelling">CheckSpelling</A> +<LI><A HREF="core.html#clearmodulelist">ClearModuleList</A> +<LI><A HREF="core.html#contentdigest">ContentDigest</A> +<LI><A HREF="mod_usertrack.html#cookieexpires">CookieExpires</A> +<LI><A HREF="mod_cookies.html#cookielog">CookieLog</A> (mod_cookies) +<LI><A HREF="mod_log_config.html#cookielog">CookieLog</A> (mod_log_config) +<LI><A HREF="mod_usertrack.html#cookietracking">CookieTracking</A> +<LI><A HREF="core.html#coredumpdirectory">CoreDumpDirectory</A> +<LI><A HREF="mod_log_config.html#customlog">CustomLog</A> +<LI><A HREF="mod_autoindex.html#defaulticon">DefaultIcon</A> +<LI><A HREF="mod_mime.html#defaultlanguage">DefaultLanguage</A> +<LI><A HREF="core.html#defaulttype">DefaultType</A> +<LI><A HREF="mod_access.html#deny">deny</A> +<LI><A HREF="core.html#directory"><Directory></A> +<LI><A HREF="core.html#directorymatch"><DirectoryMatch></A> +<LI><A HREF="mod_dir.html#directoryindex">DirectoryIndex</A> +<LI><A HREF="core.html#documentroot">DocumentRoot</A> +<LI><A HREF="core.html#errordocument">ErrorDocument</A> +<LI><A HREF="core.html#errorlog">ErrorLog</A> +<LI><A HREF="mod_example.html#example">Example</A> +<LI><A HREF="mod_expires.html#expiresactive">ExpiresActive</A> +<LI><A HREF="mod_expires.html#expiresbytype">ExpiresByType</A> +<LI><A HREF="mod_expires.html#expiresdefault">ExpiresDefault</A> +<LI><A HREF="mod_status.html#extendedstatus">ExtendedStatus</A> +<LI><A HREF="mod_autoindex.html#fancyindexing">FancyIndexing</A> +<LI><A HREF="core.html#files"><Files></A> +<LI><A HREF="core.html#filesmatch"><FilesMatch></A> +<LI><A HREF="mod_mime.html#forcetype">ForceType</A> +<LI><A HREF="core.html#group">Group</A> +<LI><A HREF="mod_headers.html#header">Header</A> +<LI><A HREF="mod_autoindex.html#headername">HeaderName</A> +<LI><A HREF="core.html#hostnamelookups">HostNameLookups</A> +<LI><A HREF="core.html#identitycheck">IdentityCheck</A> +<LI><A HREF="core.html#ifdefine"><IfDefine></A> +<LI><A HREF="core.html#ifmodule"><IfModule></A> +<LI><A HREF="mod_imap.html#imapbase">ImapBase</A> +<LI><A HREF="mod_imap.html#imapdefault">ImapDefault</A> +<LI><A HREF="mod_imap.html#imapmenu">ImapMenu</A> +<LI><A HREF="core.html#include">Include</A> +<LI><A HREF="mod_autoindex.html#indexignore">IndexIgnore</A> +<LI><A HREF="mod_autoindex.html#indexoptions">IndexOptions</A> +<LI><A HREF="core.html#keepalive">KeepAlive</A> +<LI><A HREF="core.html#keepalivetimeout">KeepAliveTimeout</A> +<LI><A HREF="mod_negotiation.html#languagepriority">LanguagePriority</A> +<LI><A HREF="core.html#limit"><Limit></A> +<LI><A HREF="core.html#limitrequestbody">LimitRequestBody</A> +<LI><A HREF="core.html#limitrequestfields">LimitRequestFields</A> +<LI><A HREF="core.html#limitrequestfieldsize">LimitRequestFieldsize</A> +<LI><A HREF="core.html#limitrequestline">LimitRequestLine</A> +<LI><A HREF="core.html#listen">Listen</A> +<LI><A HREF="core.html#listenbacklog">ListenBacklog</A> +<LI><A HREF="mod_so.html#loadfile">LoadFile</A> +<LI><A HREF="mod_so.html#loadmodule">LoadModule</A> +<LI><A HREF="core.html#location"><Location></A> +<LI><A HREF="core.html#locationmatch"><LocationMatch></A> +<LI><A HREF="core.html#lockfile">LockFile</A> +<LI><A HREF="mod_log_config.html#logformat">LogFormat</A> +<LI><A HREF="core.html#loglevel">LogLevel</A> +<LI><A HREF="core.html#maxclients">MaxClients</A> +<LI><A HREF="core.html#maxkeepaliverequests">MaxKeepAliveRequests</A> +<LI><A HREF="core.html#maxrequestsperchild">MaxRequestsPerChild</A> +<LI><A HREF="core.html#maxspareservers">MaxSpareServers</A> +<LI><A HREF="mod_cern_meta.html#metadir">MetaDir</A> +<LI><A HREF="mod_cern_meta.html#metafiles">MetaFiles</A> +<LI><A HREF="mod_cern_meta.html#metasuffix">MetaSuffix</A> +<LI><A HREF="mod_mime_magic.html#mimemagicfile">MimeMagicFile</A> +<LI><A HREF="core.html#minspareservers">MinSpareServers</A> +<LI><A HREF="mod_mmap_static.html#mmapfile">MMapFile</A> +<LI><A HREF="core.html#namevirtualhost">NameVirtualHost</A> +<LI><A HREF="mod_proxy.html#nocache">NoCache</A> +<LI><A HREF="core.html#options">Options</A> +<LI><A HREF="mod_access.html#order">order</A> +<LI><A HREF="mod_env.html#passenv">PassEnv</A> +<LI><A HREF="core.html#pidfile">PidFile</A> +<LI><A HREF="core.html#port">Port</A> +<LI><A HREF="mod_proxy.html#proxyblock">ProxyBlock</A> +<LI><A HREF="mod_proxy.html#proxypass">ProxyPass</A> +<LI><A HREF="mod_proxy.html#proxypassreverse">ProxyPassReverse</A> +<LI><A HREF="mod_proxy.html#proxyreceivebuffersize">ProxyReceiveBufferSize</A> +<LI><A HREF="mod_proxy.html#proxyremote">ProxyRemote</A> +<LI><A HREF="mod_proxy.html#proxyrequests">ProxyRequests</A> +<LI><A HREF="mod_proxy.html#proxyvia">ProxyVia</A> +<LI><A HREF="mod_autoindex.html#readmename">ReadmeName</A> +<LI><A HREF="mod_alias.html#redirect">Redirect</A> +<LI><A HREF="mod_alias.html#redirectmatch">RedirectMatch</A> +<LI><A HREF="mod_alias.html#redirectperm">RedirectPermanent</A> +<LI><A HREF="mod_alias.html#redirecttemp">RedirectTemp</A> +<LI><A HREF="mod_log_referer.html#refererignore">RefererIgnore</A> +<LI><A HREF="mod_log_referer.html#refererlog">RefererLog</A> +<LI><A HREF="core.html#require">require</A> +<LI><A HREF="core.html#resourceconfig">ResourceConfig</A> +<LI><A HREF="mod_rewrite.html#RewriteBase">RewriteBase</A> +<LI><A HREF="mod_rewrite.html#RewriteCond">RewriteCond</A> +<LI><A HREF="mod_rewrite.html#RewriteEngine">RewriteEngine</A> +<LI><A HREF="mod_rewrite.html#RewriteLock">RewriteLock</A> +<LI><A HREF="mod_rewrite.html#RewriteLog">RewriteLog</A> +<LI><A HREF="mod_rewrite.html#RewriteLogLevel">RewriteLogLevel</A> +<LI><A HREF="mod_rewrite.html#RewriteMap">RewriteMap</A> +<LI><A HREF="mod_rewrite.html#RewriteOptions">RewriteOptions</A> +<LI><A HREF="mod_rewrite.html#RewriteRule">RewriteRule</A> +<LI><A HREF="core.html#rlimitcpu">RLimitCPU</A> +<LI><A HREF="core.html#rlimitmem">RLimitMEM</A> +<LI><A HREF="core.html#rlimitnproc">RLimitNPROC</A> +<LI><A HREF="core.html#satisfy">Satisfy</A> +<LI><A HREF="core.html#scoreboardfile">ScoreBoardFile</A> +<LI><A HREF="mod_actions.html#script">Script</A> +<LI><A HREF="mod_alias.html#scriptalias">ScriptAlias</A> +<LI><A HREF="mod_alias.html#scriptaliasmatch">ScriptAliasMatch</A> +<LI><A HREF="mod_cgi.html#scriptlog">ScriptLog</A> +<LI><A HREF="mod_cgi.html#scriptlogbuffer">ScriptLogBuffer</A> +<LI><A HREF="mod_cgi.html#scriptloglength">ScriptLogLength</A> +<LI><A HREF="core.html#sendbuffersize">SendBufferSize</A> +<LI><A HREF="core.html#serveradmin">ServerAdmin</A> +<LI><A HREF="core.html#serveralias">ServerAlias</A> +<LI><A HREF="core.html#servername">ServerName</A> +<LI><A HREF="core.html#serverpath">ServerPath</A> +<LI><A HREF="core.html#serverroot">ServerRoot</A> +<LI><A HREF="core.html#serversignature">ServerSignature</A> +<LI><A HREF="core.html#servertokens">ServerTokens</A> +<LI><A HREF="core.html#servertype">ServerType</A> +<LI><A HREF="mod_env.html#setenv">SetEnv</A> +<LI><A HREF="mod_setenvif.html#setenvif">SetEnvIf</A> +<LI><A HREF="mod_setenvif.html#SetEnvIfNoCase">SetEnvIfNoCase</A> +<LI><A HREF="mod_mime.html#sethandler">SetHandler</A> +<LI><A HREF="core.html#startservers">StartServers</A> +<LI><A HREF="core.html#threadsperchild">ThreadsPerChild</A> +<LI><A HREF="core.html#timeout">TimeOut</A> +<LI><A HREF="mod_log_config.html#transferlog">TransferLog</A> +<LI><A HREF="mod_mime.html#typesconfig">TypesConfig</A> +<LI><A HREF="mod_env.html#unsetenv">UnsetEnv</A> +<LI><A HREF="core.html#usecanonicalname">UseCanonicalName</A> +<LI><A HREF="core.html#user">User</A> +<LI><A HREF="mod_userdir.html#userdir">UserDir</A> +<LI><A HREF="core.html#virtualhost"><VirtualHost></A> +<LI><A HREF="mod_include.html#xbithack">XBitHack</A> +</UL> <HR> + <H3 ALIGN="CENTER"> - Apache HTTP Server Version 1.2 + Apache HTTP Server Version 1.3 </H3> <A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_actions.html b/usr.sbin/httpd/htdocs/manual/mod/mod_actions.html index 686760abf26..816a186ed2a 100644 --- a/usr.sbin/httpd/htdocs/manual/mod/mod_actions.html +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_actions.html @@ -15,79 +15,122 @@ <DIV ALIGN="CENTER"> <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> <H3> - Apache HTTP Server Version 1.2 + Apache HTTP Server Version 1.3 </H3> </DIV> -<H1 ALIGN="CENTER">Module mod_actions</h1> - -This module is contained in the <code>mod_actions.c</code> file, and +<H1 ALIGN="CENTER">Module mod_actions</H1> +<P> +This module is contained in the <CODE>mod_actions.c</CODE> file, and is compiled in by default. It provides for executing CGI scripts based on media type or request method. It is not present in versions prior to Apache 1.1. - -<h2>Summary</h2> - +</P> +<H2>Summary</H2> +<P> This module lets you run CGI scripts whenever a file of a certain type is requested. This makes it much easier to execute scripts that process files. +</P> +<H2>Directives</H2> +<UL> +<LI><A HREF="#action">Action</A> +<LI><A HREF="#script">Script</A> +</UL> -<h2>Directives</h2> -<ul> -<li><A HREF="#action">Action</A> -<li><A HREF="#script">Script</A> -</ul> - -<hr> +<HR> -<A name="action"><h2>Action</h2></A> -<strong>Syntax:</strong> Action <em>mime-type cgi-script</em><br> -<strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<strong>Override:</strong> FileInfo<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_actions<br> -<strong>Compatibility:</strong> Action is only available in Apache 1.1 -and later<p> +<H2><A NAME="action">Action directive</A></H2> +<P> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> Action <EM>action-type cgi-script</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host, directory, + .htaccess<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> FileInfo<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_actions<BR> +<A + HREF="directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> Action is only available in Apache 1.1 +and later +</P> +<P> +This directive adds an action, which will activate <EM>cgi-script</EM> when +<EM>action-type</EM> is triggered by the request. The <EM>action-type</EM> can +be either a <A HREF="../handler.html">handler</A> or a MIME content type. It +sends the URL and file path of the requested document using the standard CGI +PATH_INFO and PATH_TRANSLATED environment variables. +</P> +<HR> -This directive adds an action, which will activate <em>cgi-script</em> when -a file of content type <em>mime-type</em> is requested. It sends the +<H2><A NAME="script">Script directive</A></H2> +<P> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> Script <EM>method cgi-script</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host, directory<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_actions<BR> +<A + HREF="directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> Script is only available in Apache 1.1 +and later +</P> + +<P> +This directive adds an action, which will activate <EM>cgi-script</EM> when +a file is requested using the method of <EM>method</EM>, which can be +one of <CODE>GET</CODE>, <CODE>POST</CODE>, <CODE>PUT</CODE> or +<CODE>DELETE</CODE>. It sends the URL and file path of the requested document using the standard CGI PATH_INFO and PATH_TRANSLATED environment variables. - -<hr> - -<A name="script"><h2>Script</h2></A> -<strong>Syntax:</strong> Script <em>method cgi-script</em><br> -<strong>Context:</strong> server config, virtual host, directory<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_actions<br> -<strong>Compatibility:</strong> Script is only available in Apache 1.1 -and later<p> - -<p>This directive adds an action, which will activate <em>cgi-script</em> when -a file is requested using the method of <em>method</em>, which can be -one of <code>GET</code>, <code>POST</code>, <code>PUT</code> or -<code>DELETE</code>. It sends the -URL and file path of the requested document using the standard -CGI PATH_INFO and PATH_TRANSLATED environment variables. - -<p>Note that the Script command defines default actions only. If a CGI +</P> +<P> +Note that the Script command defines default actions only. If a CGI script is called, or some other resource that is capable of handling -the requested method internally, it will do so. Also note that script -with a method of <code>GET</code> will only be called if there are -query arguments present (e.g. foo.html?hi). Otherwise, the request +the requested method internally, it will do so. Also note that Script +with a method of <CODE>GET</CODE> will only be called if there are +query arguments present (<EM>e.g.</EM>, foo.html?hi). Otherwise, the request will proceed normally. - -<p>Examples: -<pre> - Script GET /cgi-bin/search #e.g. for <ISINDEX>-style searching +</P> +<P> +Examples: +</P> +<PRE> + Script GET /cgi-bin/search #<EM>e.g.</EM> for <ISINDEX>-style searching Script PUT /~bob/put.cgi - -</pre> +</PRE> <HR> + <H3 ALIGN="CENTER"> - Apache HTTP Server Version 1.2 + Apache HTTP Server Version 1.3 </H3> <A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> @@ -95,4 +138,3 @@ will proceed normally. </BODY> </HTML> - diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_alias.html b/usr.sbin/httpd/htdocs/manual/mod/mod_alias.html index 247cdc35ade..affa6d3cc9f 100644 --- a/usr.sbin/httpd/htdocs/manual/mod/mod_alias.html +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_alias.html @@ -15,140 +15,400 @@ <DIV ALIGN="CENTER"> <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> <H3> - Apache HTTP Server Version 1.2 + Apache HTTP Server Version 1.3 </H3> </DIV> -<H1 ALIGN="CENTER">Module mod_alias</h1> - -This module is contained in the <code>mod_alias.c</code> file, and +<H1 ALIGN="CENTER">Module mod_alias</H1> +<P> +This module is contained in the <CODE>mod_alias.c</CODE> file, and is compiled in by default. It provides for mapping different parts of the host filesystem in the the document tree, and for URL redirection. +</P> - -<menu> -<li><A HREF="#alias">Alias</A> -<li><A HREF="#redirect">Redirect</A> -<li><A HREF="#redirecttemp">RedirectTemp</A> -<li><A HREF="#redirectperm">RedirectPermanent</A> -<li><A HREF="#scriptalias">ScriptAlias</A> -</menu> -<hr> +<H2>Directives</H2> +<UL> +<LI><A HREF="#alias">Alias</A> +<LI><A HREF="#aliasmatch">AliasMatch</A> +<LI><A HREF="#redirect">Redirect</A> +<LI><A HREF="#redirectmatch">RedirectMatch</A> +<LI><A HREF="#redirecttemp">RedirectTemp</A> +<LI><A HREF="#redirectperm">RedirectPermanent</A> +<LI><A HREF="#scriptalias">ScriptAlias</A> +<LI><A HREF="#scriptaliasmatch">ScriptAliasMatch</A> +</UL> +<HR> -<A name="alias"><h2>Alias</h2></A> +<H2><A NAME="alias">Alias directive</A></H2> +<P> <!--%plaintext <?INDEX {\tt Alias} directive> --> -<strong>Syntax:</strong> Alias <em>url-path directory-filename</em><br> -<Strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_alias<br> - +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> Alias <EM>url-path directory-filename</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_alias +</P> +<P> The Alias directive allows documents to be stored in the local filesystem other than under the <A HREF="core.html#documentroot">DocumentRoot</A>. -URLs with a (%-decoded) path beginning with <em>url-path</em> will be -mapped to local files beginning with <em>directory-filename</em>. +URLs with a (%-decoded) path beginning with <EM>url-path</EM> will be +mapped to local files beginning with <EM>directory-filename</EM>. +<P> Example: -<blockquote><code>Alias /image /ftp/pub/image</code></blockquote> +</P> +<BLOCKQUOTE><CODE>Alias /image /ftp/pub/image</CODE></BLOCKQUOTE> +<P> A request for http://myserver/image/foo.gif would cause the server to -return the file /ftp/pub/image/foo.gif.<p> - -Note that if you include a trailing / on the <em>url-path</em> then the +return the file /ftp/pub/image/foo.gif. +</P> +<P> +Note that if you include a trailing / on the <EM>url-path</EM> then the server will require a trailing / in order to expand the alias. That is, -if you use <code>Alias /icons/ /usr/local/etc/httpd/icons/</code> then -the url <code>/icons</code> will not be aliased.<p> +if you use <CODE>Alias /icons/ /usr/local/apache/icons/</CODE> then +the url <CODE>/icons</CODE> will not be aliased. +</P> +<P> +Note that you may need to specify additional +<A HREF="core.html#directory"><CODE><Directory></CODE></A> sections +which cover the <EM>destination</EM> of aliases. Aliasing occurs +before <CODE><Directory></CODE> sections are checked, so only +the destination of aliases are affected. (Note however +<A HREF="core.html#location"><CODE><Location></CODE></A> +sections are run through once before aliases are performed, so they +will apply.) +<P> +See also <A HREF="#scriptalias">ScriptAlias</A>. +</P> +<HR> -See also <A HREF="#scriptalias">ScriptAlias</A>.<p><hr> +<H2><A NAME="aliasmatch">AliasMatch</A></H2> +<P> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> AliasMatch <EM>regex directory-filename</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_alias<BR> +<A + HREF="directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> Available in Apache 1.3 and later +</P> -<A name="redirect"><h2>Redirect</h2></A> -<!--%plaintext <?INDEX {\tt Redirect} directive> --> -<strong>Syntax:</strong> Redirect [ <em>status</em> ] <em>url-path url</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_alias<br> -<strong>Compatibility:</strong> The directory and .htaccess context's -are only available in versions 1.1 and later. The <em>status</em> argument is only available in Apache 1.2 or later.<p> +<P>This directive is equivalent to <A HREF="#alias">Alias</A>, but +makes use of standard regular expressions, instead of simple prefix +matching. The supplied regular expression is matched against the URL, +and if it matches, the server will substitute any parenthesized +matches into the given string and use it as a filename. For example, +to activate the <CODE>/icons</CODE> directory, one might use: +<PRE> + AliasMatch ^/icons(.*) /usr/local/apache/icons$1 +</PRE> +</P> +<HR> + +<H2><A NAME="redirect">Redirect directive</A></H2> +<P> +<!--%plaintext <?INDEX {\tt Redirect} directive> --> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> Redirect [ <EM>status</EM> ] + <EM>url-path url</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host, directory, + .htaccess<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> FileInfo<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_alias<BR> +<A + HREF="directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> The directory and .htaccess context's +are only available in versions 1.1 and later. The <EM>status</EM> +argument is only available in Apache 1.2 or later. +</P> +<P> The Redirect directive maps an old URL into a new one. The new URL is returned to the client which attempts to fetch it again with the new address. -<em>Url-path</em> a (%-decoded) path; any requests for documents beginning with +<EM>Url-path</EM> a (%-decoded) path; any requests for documents beginning with this path will be returned a redirect error to a new (%-encoded) url -beginning with <em>url</em>. Example: -<blockquote><code>Redirect /service -http://foo2.bar.com/service</code></blockquote> +beginning with <EM>url</EM>. +</P> +<P> +Example: +</P> +<BLOCKQUOTE><CODE>Redirect /service +http://foo2.bar.com/service</CODE></BLOCKQUOTE> +<P> If the client requests http://myserver/service/foo.txt, it will be told to -access http://foo2.bar.com/service/foo.txt instead.<p> - -Note: Redirect directives take precedence over Alias and ScriptAlias +access http://foo2.bar.com/service/foo.txt instead. +</P> +<P> +<STRONG>Note:</STRONG> Redirect directives take precedence over Alias +and ScriptAlias directives, irrespective of their ordering in the configuration file. Also, -<em>Url-path</em> must be an absolute path, not a relative path, even when used with -.htaccess files or inside of <Directory> sections.<p> - -If no <em>status</em> argument is given, the redirect will be -"temporary" (HTTP status 302). This indicates to the client that the -resources is has moved temporarily. The <em>status</em> +<EM>Url-path</EM> must be an absolute path, not a relative path, even +when used with .htaccess files or inside of <Directory> sections. +</P> +<P> +If no <EM>status</EM> argument is given, the redirect will be +"temporary" (HTTP status 302). This indicates to the client that the +resources is has moved temporarily. The <EM>status</EM> argument can be used to return other HTTP status codes: -<dl> -<dt>permanent<dd>Returns a permanent redirect status (301) indicating that +<P> +<DL> +<DT>permanent +<DD>Returns a permanent redirect status (301) indicating that the resource has moved permanently. -<dt>temp<dd>Returns a temporary redirect status (302). This is the +<DT>temp +<DD>Returns a temporary redirect status (302). This is the default. -<dt>seeother<dd>Returns a "See Other" status (303) indicating that +<DT>seeother +<DD>Returns a "See Other" status (303) indicating that the resource has been replaced. -<dt>gone<dd>Returns a "Gone" status (410) indicating that the resource -has been permanently removed. When this status is used the <em>url</em> +<DT>gone +<DD>Returns a "Gone" status (410) indicating that the resource +has been permanently removed. When this status is used the <EM>url</EM> argument should be omitted. -</dl> - +</DL> +<P> Other status codes can be returned by giving the numeric status code -as the value of <em>status</em>. If the status is between 300 and 399, -the <em>url</em> argument must be present, otherwise it must be +as the value of <EM>status</EM>. If the status is between 300 and 399, +the <EM>url</EM> argument must be present, otherwise it must be omitted. Note that the status must be known to the Apache code (see -the function <code>send_error_response</code> in http_protocol.c). +the function <CODE>send_error_response</CODE> in http_protocol.c). +</P> +<HR> -<A name="redirecttemp"><h2>RedirectTemp</h2></A> -<!--%plaintext <?INDEX {\tt Redirect} directive> --> -<strong>Syntax:</strong> RedirectTemp <em>url-path url</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_alias<br> -<strong>Compatibility:</strong> This directive is only available in 1.2<P> +<H2><A NAME="redirectmatch">RedirectMatch</A></H2> +<P> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> + RedirectMatch [<EM>status</EM>] <EM>regex url</EM> +<BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> FileInfo<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_alias<BR> +<A + HREF="directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> Available in Apache 1.3 and later +</P> -This directive makes the client know that the Redirect is only -temporary. (Status 302). Exactly equivalent to <code>Redirect temporary </code><P> +<P>This directive is equivalent to <A HREF="#alias">Redirect</A>, but +makes use of standard regular expressions, instead of simple prefix +matching. The supplied regular expression is matched against the URL, +and if it matches, the server will substitute any parenthesized +matches into the given string and use it as a filename. For example, +to redirect all GIF files to like-named JPEG files on another server, +one might use: +<PRE> + RedirectMatch (.*)\.gif$ http://www.anotherserver.com$1.jpg +</PRE> +</P> + +<HR> -<A name="redirectperm"><h2>RedirectPermanent</h2></A> +<H2><A NAME="redirecttemp">RedirectTemp directive</A></H2> +<P> <!--%plaintext <?INDEX {\tt Redirect} directive> --> -<strong>Syntax:</strong> RedirectPermanent <em>url-path url</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_alias<br> -<strong>Compatibility:</strong> This directive is only available in 1.2<P> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> RedirectTemp <EM>url-path url</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host, directory, + .htaccess<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> FileInfo<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_alias<BR> +<A + HREF="directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> This directive is only available in 1.2 +</P> +<P> +This directive makes the client know that the Redirect is only +temporary (status 302). Exactly equivalent to <CODE>Redirect +temporary</CODE>. +</P> +<HR> -This directive makes the client know that the Redirect is permanent. -(Status 301). Exactly equivalent to <code>Redirect permanent</code><P> +<H2><A NAME="redirectperm">RedirectPermanent directive</A></H2> +<P> +<!--%plaintext <?INDEX {\tt Redirect} directive> --> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> RedirectPermanent <EM>url-path url</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host, directory, + .htaccess<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> FileInfo<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_alias<BR> +<A + HREF="directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> This directive is only available in 1.2 +</P> +<P> +This directive makes the client know that the Redirect is permanent +(status 301). Exactly equivalent to <CODE>Redirect permanent</CODE>. +</P> +<HR> -<hr> -<A name="scriptalias"><h2>ScriptAlias</h2></A> +<H2><A NAME="scriptalias">ScriptAlias directive</A></H2> +<P> <!--%plaintext <?INDEX {\tt ScriptAlias} directive> --> -<strong>Syntax:</strong> ScriptAlias <em>url-path directory-filename</em><br> -<Strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_alias<br> - +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> ScriptAlias <EM>url-path directory-filename</EM> +<BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_alias +</P> +<P> The ScriptAlias directive has the same behavior as the <A HREF="#alias">Alias</A> directive, except that in addition it marks the target directory as containing CGI scripts. -URLs with a (%-decoded) path beginning with <em>url-path</em> will be -mapped to scripts beginning with <em>directory-filename</em>. +URLs with a (%-decoded) path beginning with <EM>url-path</EM> will be +mapped to scripts beginning with <EM>directory-filename</EM>. +<P> Example: -<blockquote><code>ScriptAlias /cgi-bin/ /web/cgi-bin/</code></blockquote> +</P> +<BLOCKQUOTE><CODE>ScriptAlias /cgi-bin/ /web/cgi-bin/</CODE></BLOCKQUOTE> +<P> A request for http://myserver/cgi-bin/foo would cause the server to -run the script /web/cgi-bin/foo.<p> +run the script /web/cgi-bin/foo. +</P> <HR> + +<H2><A NAME="scriptaliasmatch">ScriptAliasMatch</A></H2> +<P> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> ScriptAliasMatch + <EM>regex directory-filename</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_alias<BR> +<A + HREF="directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> Available in Apache 1.3 and later +</P> + +<P>This directive is equivalent to <A HREF="#scriptalias">ScriptAlias</A>, but +makes use of standard regular expressions, instead of simple prefix +matching. The supplied regular expression is matched against the URL, +and if it matches, the server will substitute any parenthesized +matches into the given string and use it as a filename. For example, +to activate the standard <CODE>/cgi-bin</CODE>, one might use: +<PRE> + ScriptAliasMatch ^/cgi-bin(.*) /usr/local/apache/cgi-bin$1 +</PRE> +</P> + +<HR> + <H3 ALIGN="CENTER"> - Apache HTTP Server Version 1.2 + Apache HTTP Server Version 1.3 </H3> <A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> @@ -156,4 +416,3 @@ run the script /web/cgi-bin/foo.<p> </BODY> </HTML> - diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_autoindex.html b/usr.sbin/httpd/htdocs/manual/mod/mod_autoindex.html index f4091df25da..7fa844647b6 100644 --- a/usr.sbin/httpd/htdocs/manual/mod/mod_autoindex.html +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_autoindex.html @@ -80,6 +80,7 @@ order) even though they both are shown as "1K". <LI><A HREF="#headername">HeaderName</A> <LI><A HREF="#indexignore">IndexIgnore</A> <LI><A HREF="#indexoptions">IndexOptions</A> +<LI><A HREF="#indexorderdefault">IndexOrderDefault</A> <LI><A HREF="#readmename">ReadmeName</A> </MENU> <HR> @@ -213,7 +214,15 @@ extension, partial filename, wild-card expression or full filename for files to describe. <EM>String</EM> is enclosed in double quotes (<CODE>"</CODE>). Example: <BLOCKQUOTE><CODE>AddDescription "The planet Mars" /web/pics/mars.gif -</CODE></BLOCKQUOTE><P><HR> +</CODE></BLOCKQUOTE> +<P> +The description field is 23 bytes wide. 7 more bytes may be +added if the directory is covered by an +<CODE>IndexOptions SuppressSize</CODE>, and 19 bytes may be +added if <CODE>IndexOptions SuppressLastModified</CODE> is +in effect. The widest this column can be is therefore 49 bytes. +</P> +<HR> <H2><A NAME="addicon">AddIcon</A></H2> <!--%plaintext <?INDEX {\tt AddIcon} directive> --> @@ -578,6 +587,7 @@ listing by the values in that column. <!--%plaintext <?INDEX {\tt SuppressDescription} index option> --> This will suppress the file description in fancy indexing listings. <DT><A NAME="indexoptions:suppresshtmlpreamble">SuppressHTMLPreamble</A> + (<EM>Apache 1.3 and later</EM>) <DD> <!--%plaintext <?INDEX {\tt SuppressHTMLPreamble} index option> --> If the directory actually contains a file specified by the @@ -665,6 +675,66 @@ keywords without either '+' or '-' prefixes. </P> </DD> </DL> + +<HR> + +<H2><A NAME="indexorderdefault">IndexOrderDefault</A></H2> +<!--%plaintext <?INDEX {\tt IndexOrderDefault} directive> --> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> IndexOrderDefault + <EM>Ascending|Descending</EM> <EM>Name|Date|Size|Description</EM> +<BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host, directory, + .htaccess +<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> Indexes +<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base +<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_autoindex +<BR> +<A + HREF="directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> IndexOrderDefault is only available in +Apache 1.3.4 and later. + +<P> +The <SAMP>IndexOrderDefault</SAMP> directive is used in combination with +the <A HREF="#indexoptions:fancyindexing"><SAMP>FancyIndexing</SAMP></A> +index option. By default, fancyindexed directory listings are displayed in ascending order by filename; the <SAMP>IndexOrderDefault</SAMP> allows +you to change this initial display order. +</P> +<P> +<SAMP>IndexOrderDefault</SAMP> takes two arguments. The first must be either +<SAMP>Ascending</SAMP> or <SAMP>Descending</SAMP>, indicating the direction +of the sort. The second argument must be one of the keywords +<SAMP>Name</SAMP>, <SAMP>Date</SAMP>, <SAMP>Size</SAMP>, or +<SAMP>Description</SAMP>, and identifies the primary key. The secondary +key is <EM>always</EM> the ascending filename. +</P> +<P> +You can force a directory listing to only be displayed in a particular +order by combining this directive with the +<A HREF="#indexoptions:suppresscolumnsorting" +><SAMP>SuppressColumnSorting</SAMP></A> index option; this will prevent +the client from requesting the directory listing in a different order. +</P> + <HR> <H2><A NAME="readmename">ReadmeName</A></H2> diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_cgi.html b/usr.sbin/httpd/htdocs/manual/mod/mod_cgi.html index d1cfa745a5b..dd6e29277e5 100644 --- a/usr.sbin/httpd/htdocs/manual/mod/mod_cgi.html +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_cgi.html @@ -1,8 +1,8 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<html> -<head> -<title>Apache module mod_cgi</title> -</head> +<HTML> +<HEAD> +<TITLE>Apache module mod_cgi</TITLE> +</HEAD> <!-- Background white, links blue (unvisited), navy (visited), red (active) --> <BODY @@ -15,52 +15,58 @@ <DIV ALIGN="CENTER"> <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> <H3> - Apache HTTP Server Version 1.2 + Apache HTTP Server Version 1.3 </H3> </DIV> -<h1 ALIGN="CENTER">Module mod_cgi</h1> +<H1 ALIGN="CENTER">Module mod_cgi</H1> -This module is contained in the <code>mod_cgi.c</code> file, and +This module is contained in the <CODE>mod_cgi.c</CODE> file, and is compiled in by default. It provides for execution of CGI scripts. -Any file with mime type <code>application/x-httpd-cgi</code> will be +Any file with mime type <CODE>application/x-httpd-cgi</CODE> will be processed by this module. <!--%plaintext <?INDEX {\tt application/x-httpd-cgi} mime type> --> <!--%plaintext <?INDEX CGI scripts> --> -<h2>Summary</h2> -Any file that has the mime type <code>application/x-httpd-cgi</code> -or handler <code>cgi-script</code> (Apache 1.1 or later) +<H2>Summary</H2> +Any file that has the mime type <CODE>application/x-httpd-cgi</CODE> +or handler <CODE>cgi-script</CODE> (Apache 1.1 or later) will be treated as a CGI script, and run by the server, with its output being returned to the client. Files acquire this type either by -having a name ending in an extension defined by the +having a name containing an extension defined by the <A HREF="mod_mime.html#addtype">AddType</A> directive, or by being in -a <A HREF="mod_alias.html#scriptalias">ScriptAlias</A> directory. <p> +a <A HREF="mod_alias.html#scriptalias">ScriptAlias</A> directory. <P> When the server invokes a CGI script, it will add a variable called -<code>DOCUMENT_ROOT</code> to the environment. This variable will contain the +<CODE>DOCUMENT_ROOT</CODE> to the environment. This variable will contain the value of the <A HREF="core.html#documentroot">DocumentRoot</A> configuration variable. -<h2>CGI Environment variables</h2> -The server will set the CGI environment variables as described in the CGI -specification, with the following provisions: -<dl> -<dt>REMOTE_HOST -<dd>This will only be set if the server has not been compiled with -<code>MINIMAL_DNS</code>. -<dt>REMOTE_IDENT -<dd>This will only be set if -<A HREF="core.html#identitycheck">IdentityCheck</A> is set to <code>on</code>. -<dt>REMOTE_USER -<dd>This will only be set if the CGI script is subject to authentication. -</dl> +<H2>CGI Environment variables</H2> +The server will set the CGI environment variables as described in the +<A HREF="http://hoohoo.ncsa.uiuc.edu/cgi/">CGI specification</A>, with the +following provisions: +<DL> +<DT>REMOTE_HOST +<DD>This will only be set if <A HREF="core.html#hostnamelookups"><CODE>HostnameLookups</CODE></A> +is set to <CODE>on</CODE> (it is off by default), and if a reverse DNS +lookup of the accessing host's address indeed finds a host name. +<DT>REMOTE_IDENT +<DD>This will only be set if +<A HREF="core.html#identitycheck">IdentityCheck</A> is set to <CODE>on</CODE> +and the accessing host supports the ident protocol. Note that the contents +of this variable cannot be relied upon because it can easily be faked, and if +there is a proxy between the client and the server, it is usually +totally useless. +<DT>REMOTE_USER +<DD>This will only be set if the CGI script is subject to authentication. +</DL> <P> -<hr> +<HR> -<h2><a name="cgi_debug">CGI Debugging</a></h2> +<H2><A NAME="cgi_debug">CGI Debugging</A></H2> Debugging CGI scripts has traditionally been difficult, mainly because it has @@ -71,62 +77,74 @@ which are failing to run properly. These directives, included in Apache 1.2 and later, provide more detailed logging of errors when they occur. -<hr> +<HR> -<h2>CGI Logfile Format</h2> +<H2>CGI Logfile Format</H2> When configured, the CGI error log logs any CGI which does not execute properly. Each CGI script which fails to operate causes several lines of information to be logged. The first two lines are always of the format: -<pre> - %% [<i>time</i>] <i>request-line</i> - %% <i>HTTP-status</i> <i>CGI-script-filename</i> -</pre> +<PRE> + %% [<EM>time</EM>] <EM>request-line</EM> + %% <EM>HTTP-status</EM> <EM>CGI-script-filename</EM> +</PRE> If the error is that CGI script cannot be run, the log file will contain an extra two lines: -<pre> +<PRE> %%error - <i>error-message</i> -</pre> + <EM>error-message</EM> +</PRE> Alternatively, if the error is the result of the script returning incorrect header information (often due to a bug in the script), the following information is logged: -<pre> +<PRE> %request - <i>All HTTP request headers received</i> - <i>POST or PUT entity (if any)</i> + <EM>All HTTP request headers received</EM> + <EM>POST or PUT entity (if any)</EM> %response - <i>All headers output by the CGI script</i> + <EM>All headers output by the CGI script</EM> %stdout - <i>CGI standard output</i> + <EM>CGI standard output</EM> %stderr - <i>CGI standard error</i> -</pre> + <EM>CGI standard error</EM> +</PRE> (The %stdout and %stderr parts may be missing if the script did not output anything on standard output or standard error). -<hr> - -<h2>Directives</h2> - -<h3><a name="scriptlog">ScriptLog</a></h3> +<HR> -<b>Syntax:</b> ScriptLog <i>filename</i><br> -<b>Default:</b> none<br> -<b>Context:</b> resource config<br> -<b>Status:</b> mod_cgi -<p> +<H2>Directives</H2> + +<H3><A NAME="scriptlog">ScriptLog</A></H3> + +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> ScriptLog <EM>filename</EM><BR> +<A + HREF="directive-dict.html#Default" + REL="Help" +><STRONG>Default:</STRONG></A> none<BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> mod_cgi +<P> -The <tt>ScriptLog</tt> directive sets the CGI script error logfile. +The <TT>ScriptLog</TT> directive sets the CGI script error logfile. If no ScriptLog is given, no error log is created. If given, any CGI errors are logged into the filename given as argument. If this is a relative file or path it is taken relative to the server root. @@ -140,34 +158,58 @@ script log in your main logs directory, do <STRONG>NOT</STRONG> change the directory permissions to make it writable by the user the child processes run as.</P> -<p>Note that script logging is meant to be a debugging feature when +<P>Note that script logging is meant to be a debugging feature when writing CGI scripts, and is not meant to be activated continuously on running servers. It is not optimized for speed or efficiency, and may have security problems if used in a manner other than that for which -it was designed.</p> - -<h3><a name="scriptloglength">ScriptLogLength</a></h3> - -<b>Syntax:</b> ScriptLogLength <i>size</i><br> -<b>Default:</b> 10385760<br> -<b>Context:</b> resource config<br> -<b>Status:</b> mod_cgi -<p> +it was designed.</P> + +<H3><A NAME="scriptloglength">ScriptLogLength</A></H3> + +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> ScriptLogLength <EM>size</EM><BR> +<A + HREF="directive-dict.html#Default" + REL="Help" +><STRONG>Default:</STRONG></A> 10385760<BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> mod_cgi +<P> -<tt>ScriptLogLength</tt> can be used to limit the size of the CGI +<TT>ScriptLogLength</TT> can be used to limit the size of the CGI script logfile. Since the logfile logs a lot of information per CGI error (all request headers, all script output) it can grow to be a big file. To prevent problems due to unbounded growth, this directive can be used to set an maximum file-size for the CGI logfile. If the file exceeds this size, no more information will be written to it. -<h3><a name="scriptlogbuffer">ScriptLogBuffer</a></h3> - -<b>Syntax:</b> ScriptLogBuffer <i>size</i><br> -<b>Default:</b> 1024<br> -<b>Context:</b> resource config<br> -<b>Status:</b> mod_cgi -<p> +<H3><A NAME="scriptlogbuffer">ScriptLogBuffer</A></H3> + +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> ScriptLogBuffer <EM>size</EM><BR> +<A + HREF="directive-dict.html#Default" + REL="Help" +><STRONG>Default:</STRONG></A> 1024<BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> mod_cgi +<P> The size of any PUT or POST entity body that is logged to the file is limited, to prevent the log file growing too big too quickly if large @@ -175,8 +217,9 @@ bodies are being received. By default, up to 1024 bytes are logged, but this can be changed with this directive. <HR> + <H3 ALIGN="CENTER"> - Apache HTTP Server Version 1.2 + Apache HTTP Server Version 1.3 </H3> <A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_env.html b/usr.sbin/httpd/htdocs/manual/mod/mod_env.html index f3b602fdd72..0e1faea4d14 100644 --- a/usr.sbin/httpd/htdocs/manual/mod/mod_env.html +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_env.html @@ -15,86 +15,132 @@ <DIV ALIGN="CENTER"> <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> <H3> - Apache HTTP Server Version 1.2 + Apache HTTP Server Version 1.3 </H3> </DIV> -<H1 ALIGN="CENTER">Module mod_env</H1> +<H1 ALIGN="CENTER">Apache module mod_env</H1> -This module is contained in the <code>mod_env.c</code> file, and -is not compiled in by default. It provides for +This module is contained in the <CODE>mod_env.c</CODE> file, and +is compiled in by default. It provides for passing environment variables to CGI/SSI scripts. Is is only available in Apache 1.1 and later. -<h2>Summary</h2> +<H2>Summary</H2> This module allows Apache's CGI and SSI environment to inherit environment variables from the shell which invoked the httpd process. CERN web-servers are able to do this, so this module is especially useful to web-admins who wish to migrate from CERN to Apache without rewriting all their scripts - -<h2>Directives</h2> -<ul> -<li><A HREF="#passenv">PassEnv</A> -<li><A HREF="#setenv">SetEnv</A> -<li><A HREF="#unsetenv">UnsetEnv</A> -</ul> - -<hr> - -<h2><A name="passenv">PassEnv</A></h2> -<strong>Syntax:</strong> PassEnv <em>variable variable ...</em><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_env<br> -<strong>Compatibility:</strong> PassEnv is only available in -Apache 1.1 and later.<p> + +<H2>Directives</H2> +<UL> +<LI><A HREF="#passenv">PassEnv</A> +<LI><A HREF="#setenv">SetEnv</A> +<LI><A HREF="#unsetenv">UnsetEnv</A> +</UL> + +<HR> + +<H2><A NAME="passenv">PassEnv</A></H2> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> PassEnv <EM>variable variable ...</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_env<BR> +<A + HREF="directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> PassEnv is only available in +Apache 1.1 and later.<P> Specifies one or more environment variables to pass to CGI scripts from the server's own environment. Example: -<pre> +<PRE> PassEnv LD_LIBRARY_PATH -</pre> +</PRE> <HR> -<h2><A name="setenv">SetEnv</A></h2> -<strong>Syntax:</strong> SetEnv <em>variable value</em><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_env<br> -<strong>Compatibility:</strong> SetEnv is only available in -Apache 1.1 and later.<p> +<H2><A NAME="setenv">SetEnv</A></H2> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> SetEnv <EM>variable value</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_env<BR> +<A + HREF="directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> SetEnv is only available in +Apache 1.1 and later.<P> Sets an environment variable, which is then passed on to CGI scripts. Example: -<pre> +<PRE> SetEnv SPECIAL_PATH /foo/bin -</pre> +</PRE> -<hr> +<HR> -<h2><A name="unsetenv">UnsetEnv</A></h2> -<strong>Syntax:</strong> UnsetEnv <em>variable variable ...</em><br> -<strong>Context:</strong> server config, virtual host<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_env<br> -<strong>Compatibility:</strong> UnsetEnv is only available in -Apache 1.1 and later.<p> +<H2><A NAME="unsetenv">UnsetEnv</A></H2> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> UnsetEnv <EM>variable variable ...</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_env<BR> +<A + HREF="directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> UnsetEnv is only available in +Apache 1.1 and later.<P> Removes one or more environment variables from those passed on to CGI scripts. Example: -<pre> +<PRE> UnsetEnv LD_LIBRARY_PATH -</pre> +</PRE> -<p> +<P> <HR> + <H3 ALIGN="CENTER"> - Apache HTTP Server Version 1.2 + Apache HTTP Server Version 1.3 </H3> <A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_mime.html b/usr.sbin/httpd/htdocs/manual/mod/mod_mime.html index aaf392a3e4a..1c02c8c3212 100644 --- a/usr.sbin/httpd/htdocs/manual/mod/mod_mime.html +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_mime.html @@ -15,17 +15,17 @@ <DIV ALIGN="CENTER"> <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> <H3> - Apache HTTP Server Version 1.2 + Apache HTTP Server Version 1.3 </H3> </DIV> -<H1 ALIGN="CENTER">Module mod_mime</h1> +<H1 ALIGN="CENTER">Module mod_mime</H1> -This module is contained in the <code>mod_mime.c</code> file, and is +This module is contained in the <CODE>mod_mime.c</CODE> file, and is compiled in by default. It provides for determining the types of files from the filename. -<h2>Summary</h2> +<H2>Summary</H2> This module is used to determine various bits of "meta information" about documents. This information relates to the content of the @@ -40,18 +40,24 @@ HREF="#addhandler">AddHandler</A>, <A HREF="#addlanguage">AddLanguage</A> and <A HREF="#addtype">AddType</A> are all used to map file extensions onto the meta-information for that file. Respectively they set the content-encoding, handler, -content-language and mime-type (content-type) of documents. The +content-language and MIME-type (content-type) of documents. The directive <A HREF="#typesconfig">TypesConfig</A> is used to specify a -file which also maps extensions onto mime types. The directives <A +file which also maps extensions onto MIME types. The directives <A HREF="#forcetype">ForceType</A> and <A HREF="#sethandler">SetHandler</A> are used to associated all the files -in a given location (e.g. a particular directory) onto a particular -mime type or handler. +in a given location (<EM>e.g.</EM>, a particular directory) onto a particular +MIME type or handler. <P> +Note that changing the type or encoding of a file does not change the +value of the <CODE>Last-Modified</CODE> header. Thus, previously cached +copies may still be used by a client or proxy, with the previous headers. + +<H2><A NAME="multipleext">Files with Multiple Extensions</A></H2> + Files can have more than one extension, and the order of the -extensions is normally irrelevant. For example, if the file +extensions is <EM>normally</EM> irrelevant. For example, if the file <CODE>welcome.html.fr</CODE> maps onto content type text/html and language French then the file <CODE>welcome.fr.html</CODE> will map onto exactly the same information. The only exception to this is if an @@ -61,182 +67,464 @@ extensions to the left of the unknown extension. So, for example, if the extensions fr and html are mapped to the appropriate language and type but extension xxx is not assigned to anything, then the file <CODE>welcome.fr.xxx.html</CODE> will be associated with content-type -text/html but <i>no</i> language. +text/html but <EM>no</EM> language. + +<P> + +If more than one extension is given which maps onto the same type of +meta-information, then the one to the right will be used. For example, +if ".gif" maps to the MIME-type image/gif and ".html" maps to the +MIME-type text/html, then the file <CODE>welcome.gif.html</CODE> will +be associated with the MIME-type "text/html". <P> -<h2> Directives</h2> -<ul> -<li><A HREF="#addencoding">AddEncoding</A> -<li><A HREF="#addhandler">AddHandler</A> -<li><A HREF="#addlanguage">AddLanguage</A> -<li><A HREF="#addtype">AddType</A> -<li><A HREF="#forcetype">ForceType</A> -<li><A HREF="#sethandler">SetHandler</A> -<li><A HREF="#typesconfig">TypesConfig</A> -</ul> -<hr> +Care should be taken when a file with multiple extensions gets +associated with both a MIME-type and a handler. This will usually +result in the request being by the module associated with the +handler. For example, if the <CODE>.imap</CODE> extension is mapped to +the handler "imap-file" (from mod_imap) and the <CODE>.html</CODE> +extension is mapped to the MIME-type "text/html", then the file +<CODE>world.imap.html</CODE> will be associated with both the +"imap-file" handler and "text/html" MIME-type. When it is processed, +the "imap-file" handler will be used, and so it will be treated as a +mod_imap imagemap file. + +<H2>Directives</H2> +<UL> +<LI><A HREF="#addencoding">AddEncoding</A> +<LI><A HREF="#addhandler">AddHandler</A> +<LI><A HREF="#addlanguage">AddLanguage</A> +<LI><A HREF="#addtype">AddType</A> +<LI><A HREF="#defaultlanguage">DefaultLanguage</A> +<LI><A HREF="#forcetype">ForceType</A> +<LI><A HREF="#removehandler">RemoveHandler</A> +<LI><A HREF="#sethandler">SetHandler</A> +<LI><A HREF="#typesconfig">TypesConfig</A> +</UL> +<HR> -<h2><A name="addencoding">AddEncoding</A></h2> +<H2><A NAME="addencoding">AddEncoding</A></H2> <!--%plaintext <?INDEX {\tt AddEncoding} directive> --> -<strong>Syntax:</strong> AddEncoding <em>mime-enc extension extension...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> FileInfo<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_mime<p> - -The AddEncoding directive adds to the list of filename extensions which -filenames may end in for the specified encoding type. <em>Mime-enc</em> -is the mime encoding to use for documents ending in <em>extension</em>. +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> AddEncoding <EM>MIME-enc extension extension...</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> FileInfo<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_mime<P> + +The AddEncoding directive maps the given filename extensions to the +specified encoding type. <EM>MIME-enc</EM> is the MIME encoding to use +for documents containing the <EM>extension</EM>. This mapping is added +to any already in force, overriding any mappings that already exist +for the same <EM>extension</EM>. + Example: -<blockquote><code> -AddEncoding x-gzip gz<br> -AddEncoding x-compress Z -</code></blockquote> - -This will cause files ending in .gz to be marked as encoded using the x-gzip -encoding, and .Z files to be marked as encoded with x-compress.<p><hr> - -<h2><a name="addhandler">AddHandler</a></h2> - -<strong>Syntax:</strong> AddHandler <em>handler-name extension extension...</em><br> -<strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_mime<br> -<strong>Compatibility:</strong> AddHandler is only available in Apache -1.1 and later<p> - -<p>AddHandler maps the filename extensions <em>extension</em> to the -<a href="../handler.html">handler</a> -<em>handler-name</em>. For example, to activate CGI scripts -with the file extension "<code>.cgi</code>", you might use: -<pre> +<BLOCKQUOTE><CODE> AddEncoding x-gzip gz<BR> AddEncoding x-compress Z +</CODE></BLOCKQUOTE> + +This will cause filenames containing the .gz extension to be marked as +encoded using the x-gzip encoding, and filenames containing the .Z +extension to be marked as encoded with x-compress.<P> + +Old clients expect <CODE>x-gzip</CODE> and <CODE>x-compress</CODE>, +however the standard dictates that they're equivalent to <CODE>gzip</CODE> +and <CODE>compress</CODE> respectively. Apache does content encoding +comparisons by ignoring any leading <CODE>x-</CODE>. When responding +with an encoding Apache will use whatever form (<EM>i.e.</EM>, <CODE>x-foo</CODE> +or <CODE>foo</CODE>) the client requested. If the client didn't +specifically request a particular form Apache will use the form given by +the <CODE>AddEncoding</CODE> directive. To make this long story short, +you should always use <CODE>x-gzip</CODE> and <CODE>x-compress</CODE> +for these two specific encodings. More recent encodings, such as +<CODE>deflate</CODE> should be specified without the <CODE>x-</CODE>. + +<P> + +<STRONG>See also</STRONG>: <A HREF="#multipleext">Files with +multiple extensions</A> + +<P><HR> + +<H2><A NAME="addhandler">AddHandler</A></H2> + +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> AddHandler <EM>handler-name extension extension...</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> FileInfo<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_mime<BR> +<A + HREF="directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> AddHandler is only available in Apache +1.1 and later<P> + +<P>AddHandler maps the filename extensions <EM>extension</EM> to the +<A HREF="../handler.html">handler</A> <EM>handler-name</EM>. This +mapping is added to any already in force, overriding any mappings that +already exist for the same <EM>extension</EM>. + +For example, to activate CGI scripts +with the file extension "<CODE>.cgi</CODE>", you might use: +<PRE> AddHandler cgi-script cgi -</pre> +</PRE> + +<P>Once that has been put into your srm.conf or httpd.conf file, any +file containing the "<CODE>.cgi</CODE>" extension will be treated as a +CGI program.</P> + +<P> + +<STRONG>See also</STRONG>: <A HREF="#multipleext">Files with +multiple extensions</A> -<p>Once that has been put into your srm.conf or httpd.conf file, any -file ending with "<code>.cgi</code>" will be treated as a CGI -program.</p> <HR> -<h2><A name="addlanguage">AddLanguage</A></h2> +<H2><A NAME="addlanguage">AddLanguage</A></H2> <!--%plaintext <?INDEX {\tt AddLanguage} directive> --> -<strong>Syntax:</strong> AddLanguage <em>mime-lang extension extension...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> FileInfo<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_mime<p> - -The AddLanguage directive adds to the list of filename extensions which -filenames may end in for the specified content language. <em>Mime-lang</em> -is the mime language of files with names ending <em>extension</em>, -after any content encoding extensions have been removed. Example: -<blockquote><code> -AddEncoding x-compress Z<br> -AddLanguage en .en<br> -AddLanguage fr .fr<br> -</code></blockquote> - -Then the document <code>xxxx.en.Z</code> will be treated as being a compressed -English document. Although the content language is reported to the client, -the browser is unlikely to use this information. The AddLanguage directive -is more useful for content negotiation, where the server returns one -from several documents based on the client's language preference.<p><hr> - -<h2><A name="addtype">AddType</A></h2> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> AddLanguage <EM>MIME-lang extension extension...</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> FileInfo<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_mime<P> + +The AddLanguage directive maps the given filename extensions to the +specified content language. <EM>MIME-lang</EM> is the MIME language of +filenames containing <EM>extension</EM>. This mapping is added to any +already in force, overriding any mappings that already exist for the +same <EM>extension</EM>. + +Example: <BLOCKQUOTE><CODE> +AddEncoding x-compress Z<BR> AddLanguage en .en<BR> AddLanguage fr +.fr<BR> </CODE></BLOCKQUOTE> + +Then the document <CODE>xxxx.en.Z</CODE> will be treated as being a +compressed English document (as will the document +<CODE>xxxx.Z.en</CODE>). Although the content language is reported to +the client, the browser is unlikely to use this information. The +AddLanguage directive is more useful for <A +HREF="../content-negotiation.html">content negotiation</A>, where +the server returns one from several documents based on the client's +language preference.<P> + +<P> + +<STRONG>See also</STRONG>: <A HREF="#multipleext">Files with +multiple extensions</A> +<BR> +<STRONG>See also</STRONG>: <A +HREF="./mod_negotiation.html">mod_negotiation</A> + +<HR> + +<H2><A NAME="addtype">AddType</A></H2> <!--%plaintext <?INDEX {\tt AddType} directive> --> -<strong>Syntax:</strong> AddType <em>mime-type extension extension...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> FileInfo<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_mime<p> - -The AddType directive adds to the list of filename extensions which -filenames may end in for the specified content type. <em>Mime-enc</em> -is the mime type to use for documents ending in <em>extension</em>. -after content-encoding and language extensions have been removed. Example: -<blockquote><code> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> AddType <EM>MIME-type extension extension...</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> FileInfo<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_mime<P> + +The AddType directive maps the given filename extensions onto the +specified content type. <EM>MIME-enc</EM> is the MIME type to use for +filenames containing <EM>extension</EM>. This mapping is added to any +already in force, overriding any mappings that already exist for the +same <EM>extension</EM>. This directive can be used to add mappings +not listed in the MIME types file (see the <CODE><A +HREF="#typesconfig">TypesConfig</A></CODE> directive). + +Example: +<BLOCKQUOTE><CODE> AddType image/gif GIF -</code></blockquote> -It is recommended that new mime types be added using the AddType directive -rather than changing the <A HREF="#typesconfig">TypesConfig</A> file.<p> +</CODE></BLOCKQUOTE> +It is recommended that new MIME types be added using the AddType directive +rather than changing the <A HREF="#typesconfig">TypesConfig</A> file.<P> Note that, unlike the NCSA httpd, this directive cannot be used to set the -type of particular files.<p><hr> +type of particular files.<P> + +<P> + +<STRONG>See also</STRONG>: <A HREF="#multipleext">Files with +multiple extensions</A> -<h2><a name="forcetype">ForceType</a></h2> +<HR> + +<H2><A NAME="defaultlanguage">DefaultLanguage</A></H2> +<!--%plaintext <?INDEX {\tt DefaultLanguage} directive> --> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> DefaultLanguage <EM>MIME-lang</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> FileInfo<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_mime<P> + +The DefaultLanguage directive tells Apache that all files in the +directive's scope (<EM>e.g.</EM>, all files covered by the current +<CODE><Directory></CODE> container) that don't have an explicit +language extension (such as <SAMP>.fr</SAMP> or <SAMP>.de</SAMP> as +configured by <SAMP>AddLanguage</SAMP>) should be considered to be in +the specified <EM>MIME-lang</EM> language. This allows entire +directories to be marked as containing Dutch content, for instance, +without having to rename each file. Note that unlike using extensions +to specify languages, <SAMP>DefaultLanguage</SAMP> can only specify a +single language. -<strong>Syntax:</strong> ForceType <em>media type</em><br> -<strong>Context:</strong> directory, .htaccess<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_mime<br> -<strong>Compatibility:</strong> ForceType is only available in Apache -1.1 and later.<p> +<P> -<p>When placed into an <code>.htaccess</code> file or a -<code><Directory></code> or <code><Location></code> section, +If no <SAMP>DefaultLanguage</SAMP> directive is in force, and a file +does not have any language extensions as configured by +<SAMP>AddLanguage</SAMP>, then that file will be considered to have no +language attribute. + +<P> + +<STRONG>See also</STRONG>: <A +HREF="./mod_negotiation.html">mod_negotiation</A> +<BR> +<STRONG>See also</STRONG>: <A HREF="#multipleext">Files with +multiple extensions</A> + +<HR> + +<H2><A NAME="forcetype">ForceType</A></H2> + +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> ForceType <EM>media type</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> directory, .htaccess<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_mime<BR> +<A + HREF="directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> ForceType is only available in Apache +1.1 and later.<P> + +<P>When placed into an <CODE>.htaccess</CODE> file or a +<CODE><Directory></CODE> or <CODE><Location></CODE> section, this directive forces all matching files to be served -as the content type given by <em>media type</em>. For example, if you +as the content type given by <EM>media type</EM>. For example, if you had a directory full of GIF files, but did not want to label them all with ".gif", you might want to use: -<pre> +<PRE> ForceType image/gif -</pre> -<p>Note that this will override any filename extensions that might -media type.</p> - -<h2><a name="sethandler">SetHandler</a></h2> +</PRE> +<P>Note that this will override any filename extensions that might determine +the media type.</P><HR> + +<H2><A NAME="removehandler">RemoveHandler</A></H2> + +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> RemoveHandler <EM>extension extension...</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> directory, .htaccess<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_mime<BR> +<A + HREF="directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> RemoveHandler is only available in Apache +1.3.4 and later.<P> -<strong>Syntax:</strong> SetHandler <em>handler-name</em><br> -<strong>Context:</strong> directory, .htaccess<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_mime<br> -<strong>Compatibility:</strong> SetHandler is only available in Apache -1.1 and later.<p> +<P> +The <SAMP>RemoveHandler</SAMP> directive removes any +handler associations for files with the given extensions. +This allows <CODE>.htaccess</CODE> files in subdirectories to undo +any associations inherited from parent directories or the server +config files. An example of its use might be: +</P> +<DL> + <DT><CODE>/foo/.htaccess:</CODE></DT> + <DD><CODE>AddHandler server-parsed .html</CODE></DD> + <DT><CODE>/foo/bar/.htaccess:</CODE></DT> + <DD><CODE>RemoveHandler .html</CODE></DD> +</DL> +<P> +This has the effect of returning <SAMP>.html</SAMP> files in the +<SAMP>/foo/bar</SAMP> directory to being treated as normal +files, rather than as candidates for parsing (see the +<A HREF="mod_include.html"><SAMP>mod_include</SAMP></A> module). +</P> +<HR> -<p>When placed into an <code>.htaccess</code> file or a -<code><Directory></code> or <code><Location></code> section, +<H2><A NAME="sethandler">SetHandler</A></H2> + +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> SetHandler <EM>handler-name</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> directory, .htaccess<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_mime<BR> +<A + HREF="directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> SetHandler is only available in Apache +1.1 and later.<P> + +<P>When placed into an <CODE>.htaccess</CODE> file or a +<CODE><Directory></CODE> or <CODE><Location></CODE> section, this directive forces all matching files to be parsed through the -<a href="../handler.html">handler</a> -given by <em>handler-name</em>. For example, if you had a +<A HREF="../handler.html">handler</A> +given by <EM>handler-name</EM>. For example, if you had a directory you wanted to be parsed entirely as imagemap rule files, regardless of extension, you might put the following into an -<code>.htaccess</code> file in that directory: -<pre> +<CODE>.htaccess</CODE> file in that directory: +<PRE> SetHandler imap-file -</pre> +</PRE> -<p>Another example: if you wanted to have the server display a status -report whenever a URL of <code>http://servername/status</code> was +<P>Another example: if you wanted to have the server display a status +report whenever a URL of <CODE>http://servername/status</CODE> was called, you might put the following into access.conf: -<pre> +<PRE> <Location /status> SetHandler server-status </Location> -</pre> +</PRE> <HR> -<h2><A name="typesconfig">TypesConfig</A></h2> +<H2><A NAME="typesconfig">TypesConfig</A></H2> <!--%plaintext <?INDEX {\tt TypesConfig} directive> --> -<strong>Syntax:</strong> TypesConfig <em>filename</em><br> -<strong>Default:</strong> <code>TypesConfig conf/mime.types</code><br> -<Strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_mime<p> - -The TypesConfig directive sets the location of the mime types configuration -file. <em>Filename</em> is relative to the +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> TypesConfig <EM>filename</EM><BR> +<A + HREF="directive-dict.html#Default" + REL="Help" +><STRONG>Default:</STRONG></A> <CODE>TypesConfig conf/MIME.types</CODE><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_mime<P> + +The TypesConfig directive sets the location of the MIME types configuration +file. <EM>Filename</EM> is relative to the <A HREF="core.html#serverroot">ServerRoot</A>. This file sets the default list of mappings from filename extensions to content types; changing this file is not recommended. Use the <A HREF="#addtype">AddType</A> directive instead. The file contains lines in the format of the arguments to an AddType command: -<blockquote><em>mime-type extension extension ...</em></blockquote> +<BLOCKQUOTE><EM>MIME-type extension extension ...</EM></BLOCKQUOTE> The extensions are lower-cased. Blank lines, and lines beginning with a hash -character (`#') are ignored.<p> +character (`#') are ignored.<P> <HR> + <H3 ALIGN="CENTER"> - Apache HTTP Server Version 1.2 + Apache HTTP Server Version 1.3 </H3> <A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_negotiation.html b/usr.sbin/httpd/htdocs/manual/mod/mod_negotiation.html index 94cef4e5ac3..818d5e1fd68 100644 --- a/usr.sbin/httpd/htdocs/manual/mod/mod_negotiation.html +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_negotiation.html @@ -15,30 +15,30 @@ <DIV ALIGN="CENTER"> <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> <H3> - Apache HTTP Server Version 1.2 + Apache HTTP Server Version 1.3 </H3> </DIV> -<H1 ALIGN="CENTER">Module mod_negotiation</h1> +<H1 ALIGN="CENTER">Module mod_negotiation</H1> -This module is contained in the <code>mod_negotiation.c</code> file, +This module is contained in the <CODE>mod_negotiation.c</CODE> file, and is compiled in by default. It provides for <A -HREF="../content-negotiation.html">content negotiation</A>. +HREF="../content-negotiation.html">content negotiation</A>. -<h2>Summary</h2> +<H2>Summary</H2> Content negotiation, or more accurately content selection, is the selection of the document that best matches the clients capabilities, from one of several available documents. There are two implementations of this. -<ul> -<li> A type map (a file with the handler <code>type-map</code>) +<UL> +<LI> A type map (a file with the handler <CODE>type-map</CODE>) which explicitly lists the files containing the variants. -<li> A MultiViews search (enabled by the MultiViews +<LI> A MultiViews search (enabled by the MultiViews <A HREF="core.html#options">Option</A>, where the server does an implicit filename pattern match, and choose from amongst the results. -</ul> +</UL> -<h3>Type maps</h3> +<H3>Type maps</H3> A type map has the same format as RFC822 mail headers. It contains document descriptions separated by blank lines, with lines beginning with a hash character ('#') treated as comments. A document description consists of @@ -50,106 +50,144 @@ between the header name and value, and between the tokens of value. The headers allowed are: -<dl> -<dt>Content-Encoding: -<dd>The encoding of the file. Currently only two encodings are recognized -by http; <code>x-compress</code> for compressed files, and <code>x-gzip</code> +<DL> +<DT>Content-Encoding: +<DD>The encoding of the file. Currently only two encodings are recognized +by http; <CODE>x-compress</CODE> for compressed files, and <CODE>x-gzip</CODE> for gzipped files. -<dt>Content-Language: -<dd>The language of the variant, as an Internet standard language code, such -as <code>en</code>. -<dt>Content-Length: -<dd>The length of the file, in bytes. If this header is not present, then +<DT>Content-Language: +<DD>The language of the variant, as an Internet standard language code, such +as <CODE>en</CODE>. +<DT>Content-Length: +<DD>The length of the file, in bytes. If this header is not present, then the actual length of the file is used. -<dt>Content-Type: -<dd>The MIME media type of the document, with optional parameters. +<DT>Content-Type: +<DD>The MIME media type of the document, with optional parameters. parameters are separated from the media type and from one another by semi-colons. Parameter syntax is name=value; allowed parameters are: -<dl> -<dt>level -<dd>the value is an integer, which specifies the version of the media type. -For <code>text/html</code> this defaults to 2, otherwise 0. -<dt>qs -<dd>the value is a floating-point number with value between 0. and 1. +<DL> +<DT>level +<DD>the value is an integer, which specifies the version of the media type. +For <CODE>text/html</CODE> this defaults to 2, otherwise 0. +<DT>qs +<DD>the value is a floating-point number with value between 0. and 1. It indications the 'quality' of this variant. -</dl> +</DL> Example: -<blockquote><code>Content-Type: image/jpeg; qs=0.8</code></blockquote> -<dt>URI: -<dd>The path to the file containing this variant, relative to the map file. -</dl> +<BLOCKQUOTE><CODE>Content-Type: image/jpeg; qs=0.8</CODE></BLOCKQUOTE> +<DT>URI: +<DD>The path to the file containing this variant, relative to the map file. +</DL> -<h3>MultiViews</h3> +<H3>MultiViews</H3> A MultiViews search is enabled by the MultiViews <A HREF="core.html#options">Option</A>. -If the server receives a request for <code>/some/dir/foo</code> and -<code>/some/dir/foo</code> does <em>not</em> exist, then the server reads the -directory looking for all files named <code>foo.*</code>, and effectively +If the server receives a request for <CODE>/some/dir/foo</CODE> and +<CODE>/some/dir/foo</CODE> does <EM>not</EM> exist, then the server reads the +directory looking for all files named <CODE>foo.*</CODE>, and effectively fakes up a type map which names all those files, assigning them the same media types and content-encodings it would have if the client had asked for one of them by name. It then chooses the best match to the client's -requirements, and returns that document.<p> +requirements, and returns that document.<P> -<h2>Directives</h2> -<ul> -<li><A href="#cachenegotiateddocs">CacheNegotiatedDocs</a> -<li><A HREF="#languagepriority">LanguagePriority</A> -</ul> -<hr> - +<H2>Directives</H2> +<UL> +<LI><A HREF="#cachenegotiateddocs">CacheNegotiatedDocs</A> +<LI><A HREF="#languagepriority">LanguagePriority</A> +</UL> +<HR> -<h2><A name="cachenegotiateddocs">CacheNegotiatedDocs</A></h2> -<strong>Syntax:</strong> CacheNegotiatedDocs<br> -<Strong>Context:</strong> server config<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_negotiation<br> -<strong>Compatibility:</strong> CacheNegotiatedDocs is only available -in Apache 1.1 and later.<p> -<p>If set, this directive allows content-negotiated documents to be +<H2><A NAME="cachenegotiateddocs">CacheNegotiatedDocs</A></H2> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> CacheNegotiatedDocs<BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_negotiation<BR> +<A + HREF="directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> CacheNegotiatedDocs is only available +in Apache 1.1 and later.<P> + +<P>If set, this directive allows content-negotiated documents to be cached by proxy servers. This could mean that clients behind those proxys could retrieve versions of the documents that are not the best match for their abilities, but it will make caching more efficient. -<p> +<P> This directive only applies to requests which come from HTTP/1.0 browsers. HTTP/1.1 provides much better control over the caching of negotiated -documents, and this directive has no effect in responses to +documents, and this directive has no effect in responses to HTTP/1.1 requests. -<h2><A name="languagepriority">LanguagePriority</A></h2> +<H2><A NAME="languagepriority">LanguagePriority</A></H2> <!--%plaintext <?INDEX {\tt LanguagePriority} directive> --> -<strong>Syntax:</strong> LanguagePriority <em>mime-lang mime-lang...</em><br> -<Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<Strong>Override:</strong> FileInfo<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_negotiation<p> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> LanguagePriority <EM>MIME-lang MIME-lang...</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> FileInfo<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Base<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_negotiation<P> The LanguagePriority sets the precedence of language variants for the case where the client does not express a preference, when handling a -MultiViews request. The list of <em>mime-lang</em> are in order of decreasing +MultiViews request. The list of <EM>MIME-lang</EM> are in order of decreasing preference. Example: -<blockquote><code>LanguagePriority en fr de</code></blockquote> +<BLOCKQUOTE><CODE>LanguagePriority en fr de</CODE></BLOCKQUOTE> -For a request for <code>foo.html</code>, where <code>foo.html.fr</code> -and <code>foo.html.de</code> both existed, but the browser did not express -a language preference, then <code>foo.html.fr</code> would be returned.<p> +For a request for <CODE>foo.html</CODE>, where <CODE>foo.html.fr</CODE> +and <CODE>foo.html.de</CODE> both existed, but the browser did not express +a language preference, then <CODE>foo.html.fr</CODE> would be returned.<P> <P> Note that this directive only has an effect if a 'best' language -cannot be determined by other any other means. Correctly implemented -HTTP/1.1 requests will mean this directive has no effect. +cannot be determined by any other means. Correctly implemented +HTTP/1.1 requests will mean this directive has no effect. + +<P> + +<STRONG>See also</STRONG>: +<A HREF="./mod_mime.html#defaultlanguage">DefaultLanguage</A> and +<A HREF="./mod_mime.html#addlanguage">AddLanguage</A> + <HR> + <H3 ALIGN="CENTER"> - Apache HTTP Server Version 1.2 + Apache HTTP Server Version 1.3 </H3> <A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> diff --git a/usr.sbin/httpd/htdocs/manual/mod/mod_rewrite.html b/usr.sbin/httpd/htdocs/manual/mod/mod_rewrite.html index 44ed3239cf2..118ea068ccd 100644 --- a/usr.sbin/httpd/htdocs/manual/mod/mod_rewrite.html +++ b/usr.sbin/httpd/htdocs/manual/mod/mod_rewrite.html @@ -2,10 +2,10 @@ <!--%hypertext --> <!-- mod_rewrite.html --> <!-- Documentation for the mod_rewrite Apache module --> -<html> -<head> -<title>Apache module mod_rewrite</title> -</head> +<HTML> +<HEAD> +<TITLE>Apache module mod_rewrite</TITLE> +</HEAD> <!-- Background white, links blue (unvisited), navy (visited), red (active) --> <BODY @@ -15,305 +15,777 @@ VLINK="#000080" ALINK="#FF0000" > +<BLOCKQUOTE><!-- page indentation --> <DIV ALIGN="CENTER"> <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> <H3> - Apache HTTP Server Version 1.2 + Apache HTTP Server Version 1.3 </H3> </DIV> -<h1 ALIGN="CENTER">Module mod_rewrite</h1> - -This module is contained in the <code>mod_rewrite.c</code> file, with Apache -1.2 and later. It provides a rule-based rewriting engine to rewrite requested -URLs on the fly. <code>mod_rewrite</code> is not compiled into the server by -default. To use <code>mod_rewrite</code> you have to enable the following line -in the server build Configuration file: -<pre> - Module rewrite_module mod_rewrite.o -</pre> - -<h2>Summary</h2> - -This module uses a rule-based rewriting engine (based on a -regular-expression parser) to rewrite requested URLs on the fly. - -<p> -It supports an unlimited number of additional rule conditions (which can -operate on a lot of variables, including HTTP headers) for granular -matching and external database lookups (either via plain text -tables, DBM hash files or external processes) for advanced URL -substitution. - -<p> -It operates on the full URLs (including the PATH_INFO part) both in per-server -context (httpd.conf) and per-dir context (.htaccess) and even can generate -QUERY_STRING parts on result. The rewritten result can lead to internal -sub-processing, external request redirection or to internal proxy throughput. - -<p> -This module was originally written in April 1996 and -gifted exclusively to the The Apache Group in July 1997 by -<p> -<blockquote> - <i>Ralf S. Engelschall</i><br> - <a href="mailto:rse@engelschall.com"><tt>rse@engelschall.com</tt></a><br> - <a href="http://www.engelschall.com/"><tt>www.engelschall.com</tt></a> -</blockquote> - -<!--%hypertext --> -<HR> -<!--/%hypertext --> - -<p> -<h2>Directives</h2> - -<ul> - <li><a href="#RewriteEngine">RewriteEngine</a> - <li><a href="#RewriteOptions">RewriteOptions</a> - <li><a href="#RewriteLog">RewriteLog</a> - <li><a href="#RewriteLogLevel">RewriteLogLevel</a> - <li><a href="#RewriteMap">RewriteMap</a> - <li><a href="#RewriteBase">RewriteBase</a> - <li><a href="#RewriteCond">RewriteCond</a> - <li><a href="#RewriteRule">RewriteRule</a> -</ul> - -<!--%hypertext --> -<hr> -<!--/%hypertext --> - - -<center> -<a name="Configuration"> -<h1>Configuration Directives</h1> -</a> -</center> +<BR> +<H1 ALIGN="CENTER">Module mod_rewrite<BR>URL Rewriting Engine</H1> + +This module is contained in the <CODE>mod_rewrite.c</CODE> file, with Apache +1.2 and later. It provides a rule-based rewriting engine to rewrite requested +URLs on the fly. It is not compiled into the server by default. To use +<CODE>mod_rewrite</CODE> you have to enable the following line in the server +build <CODE>Configuration</CODE> file: +<PRE> + AddModule modules/standard/mod_rewrite.o +</PRE> + +<P> +<HR NOSHADE SIZE=1> + +<BR> +<H2>Summary</H2> + +<BLOCKQUOTE> +<BLOCKQUOTE> +<BLOCKQUOTE> +<EM>``The great thing about mod_rewrite is it gives you all the +configurability and flexibility of Sendmail. The downside to +mod_rewrite is that it gives you all the configurability and +flexibility of Sendmail.''</EM> +<DIV ALIGN=RIGHT> +-- Brian Behlendorf<BR> +Apache Group +</DIV> +</BLOCKQUOTE> +</BLOCKQUOTE> +</BLOCKQUOTE> + +<BLOCKQUOTE> +<BLOCKQUOTE> +<BLOCKQUOTE> +<EM>`` +Despite the tons of examples and docs, mod_rewrite +is voodoo. Damned cool voodoo, but still voodoo. +''</EM> +<DIV ALIGN=RIGHT> +-- Brian Moore<BR> +bem@news.cmc.net +</DIV> +</BLOCKQUOTE> +</BLOCKQUOTE> +</BLOCKQUOTE> + +Welcome to mod_rewrite, the Swiss Army Knife of URL manipulation! + +<P> +This module uses a rule-based rewriting engine (based on a regular-expression +parser) to rewrite requested URLs on the fly. It supports an unlimited number +of rules and an unlimited number of attached rule conditions for each rule to +provide a really flexible and powerful URL manipulation mechanism. The URL +manipulations can depend on various tests, for instance server variables, +environment variables, HTTP headers, time stamps and even external database +lookups in various formats can be used to achieve a really granular URL +matching. + +<P> +This module operates on the full URLs (including the path-info part) both in +per-server context (<CODE>httpd.conf</CODE>) and per-directory context +(<CODE>.htaccess</CODE>) and even can generate query-string parts on result. +The rewritten result can lead to internal sub-processing, external request +redirection or even to an internal proxy throughput. + +<P> +But all this functionality and flexibility has its drawback: complexity. So +don't expect to understand this module in it's whole in just one day. + +<P> +This module was invented and originally written in April 1996<BR> +and gifted exclusively to the The Apache Group in July 1997 by + +<P> +<BLOCKQUOTE> +<A HREF="http://www.engelschall.com/"><CODE>Ralf S. Engelschall</CODE></A><BR> +<A HREF="mailto:rse@engelschall.com"><CODE>rse@engelschall.com</CODE></A><BR> +<A HREF="http://www.engelschall.com/"><CODE>www.engelschall.com</CODE></A> +</BLOCKQUOTE> + +<P> +<HR NOSHADE SIZE=1> + +<H2>Table Of Contents</H2> + +<P> +<STRONG>Internal Processing</STRONG> +<UL> + <LI><A HREF="#InternalAPI">API Phases</A> + <LI><A HREF="#InternalRuleset">Ruleset Processing</A> + <LI><A HREF="#InternalBackRefs">Regex Back-Reference Availability</A> +</UL> +<P> +<STRONG>Configuration Directives</STRONG> +<UL> + <LI><A HREF="#RewriteEngine">RewriteEngine</A> + <LI><A HREF="#RewriteOptions">RewriteOptions</A> + <LI><A HREF="#RewriteLog">RewriteLog</A> + <LI><A HREF="#RewriteLogLevel">RewriteLogLevel</A> + <LI><A HREF="#RewriteLock">RewriteLock</A> + <LI><A HREF="#RewriteMap">RewriteMap</A> + <LI><A HREF="#RewriteBase">RewriteBase</A> + <LI><A HREF="#RewriteCond">RewriteCond</A> + <LI><A HREF="#RewriteRule">RewriteRule</A> +</UL> +<STRONG>Miscellaneous</STRONG> +<UL> + <LI><A HREF="#EnvVar">Environment Variables</A> + <LI><A HREF="#Solutions">Practical Solutions</A> +</UL> + +<P> +<HR NOSHADE SIZE=1> + +<CENTER> +<H1><A NAME="Internal">Internal Processing</A></H1> +</CENTER> + +<P> +<HR NOSHADE SIZE=1> + +<P> +The internal processing of this module is very complex but needs to be +explained once even to the average user to avoid common mistakes and to let +you exploit its full functionality. + +<H2><A NAME="InternalAPI">API Phases</A></H2> + +<P> +First you have to understand that when Apache processes a HTTP request it does +this in phases. A hook for each of these phases is provided by the Apache API. +Mod_rewrite uses two of these hooks: the URL-to-filename translation hook +which is used after the HTTP request was read and before any authorization +starts and the Fixup hook which is triggered after the authorization phases +and after the per-directory config files (<CODE>.htaccess</CODE>) where read, +but before the content handler is activated. + +<P> +So, after a request comes in and Apache has determined the corresponding +server (or virtual server) the rewriting engine start processing of all +mod_rewrite directives from the per-server configuration in the +URL-to-filename phase. A few steps later when the final data directories are +found, the per-directory configuration directives of mod_rewrite are triggered +in the Fixup phase. In both situations mod_rewrite either rewrites URLs to new +URLs or to filenames, although there is no obvious distinction between them. +This is a usage of the API which was not intended this way when the API +was designed, but as of Apache 1.x this is the only way mod_rewrite can +operate. To make this point more clear remember the following two points: + +<OL> +<LI>The API currently provides only a URL-to-filename hook. Although + mod_rewrite rewrites URLs to URLs, URLs to filenames and even + filenames to filenames. In Apache 2.0 the two missing hooks + will be added to make the processing more clear. But this + point has no drawbacks for the user, it is just a fact which + should be remembered: Apache does more in the URL-to-filename hook + then the API intends for it. +<P> +<LI>Unbelievably mod_rewrite provides URL manipulations in per-directory + context, <EM>i.e.</EM>, within <CODE>.htaccess</CODE> files, although + these are + reached a very long time after the URLs were translated to filenames (this + has to be this way, because <CODE>.htaccess</CODE> files stay in the + filesystem, so processing has already been reached this stage of + processing). In other words: According to the API phases at this time it + is too late for any URL manipulations. To overcome this chicken and egg + problem mod_rewrite uses a trick: When you manipulate a URL/filename in + per-directory context mod_rewrite first rewrites the filename back to its + corresponding URL (which it usually impossible, but see the + <CODE>RewriteBase</CODE> directive below for the trick to achieve this) + and then initiates a new internal sub-request with the new URL. This leads + to a new processing of the API phases from the beginning. + <P> + Again mod_rewrite tries hard to make this complicated step totally + transparent to the user, but you should remember here: While URL + manipulations in per-server context are really fast and efficient, + per-directory rewrites are slow and inefficient due to this chicken and + egg problem. But on the other hand this is the only way mod_rewrite can + provide (locally restricted) URL manipulations to the average user. +</OL> + +<P> +Don't forget these two points! + +<H2><A NAME="InternalRuleset">Ruleset Processing</A></H2> + +Now when mod_rewrite is triggered in these two API phases, it reads the +configured rulesets from its configuration structure (which itself was either +created on startup for per-server context or while the directory walk of the +Apache kernel for per-directory context). Then the URL rewriting engine is +started with the contained ruleset (one or more rules together with their +conditions). The operation of the URL rewriting engine itself is exactly the +same for both configuration contexts. Just the final result processing is +different. + +<P> +The order of rules in the ruleset is important because the rewriting engine +processes them in a special order. And this order is not very obvious. The +rule is this: The rewriting engine loops through the ruleset rule by rule +(<CODE>RewriteRule</CODE> directives!) and when a particular rule matched it +optionally loops through existing corresponding conditions +(<CODE>RewriteCond</CODE> directives). Because of historical reasons the +conditions are given first, the control flow is a little bit winded. See +Figure 1 for more details. + +<P> +<DIV ALIGN=CENTER> +<TABLE CELLSPACING=0 CELLPADDING=2 BORDER=0> +<TR> +<TD BGCOLOR="#CCCCCC"><IMG + SRC="../images/mod_rewrite_fig1.gif" + WIDTH="428" HEIGHT="385" + ALT="[Needs graphics capability to display]"></TD> +</TR> +<TR> +<TD ALIGN=CENTER> +<STRONG>Figure 1:</STRONG> The control flow through the rewriting ruleset +</TD> +</TR> +</TABLE> +</DIV> -<a name="RewriteEngine"><h3>RewriteEngine</h3></a> -<strong>Syntax:</strong> <code>RewriteEngine</code> {<code>on,off</code>}<br> -<strong>Default:</strong> <strong><code>RewriteEngine off</code></strong><br> -<strong>Context:</strong> server config, virtual host, per-directory config<br> -<p> +<P> +As you can see, first the URL is matched against the <EM>Pattern</EM> of each +rule. When it fails mod_rewrite immediately stops processing this rule and +continues with the next rule. If the <EM>Pattern</EM> matched, mod_rewrite +looks for corresponding rule conditions. If none are present, it just +substitutes the URL with a new value which is constructed from the string +<EM>Substitution</EM> and goes on with its rule-looping. But +if conditions exists, it starts an inner loop for processing them in order +they are listed. For conditions the logic is different: We don't match a +pattern against the current URL. Instead we first create a string +<EM>TestString</EM> by expanding variables, back-references, map lookups, +<EM>etc.</EM> and then we try to match <EM>CondPattern</EM> against it. If the +pattern doesn't match, the complete set of conditions and the corresponding +rule fails. If the pattern matches, then the next condition is processed +until no more condition is available. If all conditions matched processing is +continued with the substitution of the URL with <EM>Substitution</EM>. + +<H2><A NAME="InternalBackRefs">Regex Back-Reference Availability</A></H2> + +One important thing here has to be remembered: Whenever you +use parenthesis in <EM>Pattern</EM> or in one of the <EM>CondPattern</EM> +back-reference are internally created which can be used with the +strings <CODE>$N</CODE> and <CODE>%N</CODE> (see below). And these +are available for creating the strings <EM>Substitution</EM> and +<EM>TestCond</EM>. Figure 2 shows at which locations the back-references are +transfered to for expansion. + +<P> +<DIV ALIGN=CENTER> +<TABLE CELLSPACING=0 CELLPADDING=2 BORDER=0> +<TR> +<TD BGCOLOR="#CCCCCC"><IMG + SRC="../images/mod_rewrite_fig2.gif" + WIDTH="381" HEIGHT="179" + ALT="[Needs graphics capability to display]"></TD> +</TR> +<TR> +<TD ALIGN=CENTER> +<STRONG>Figure 2:</STRONG> The back-reference flow through a rule +</TD> +</TR> +</TABLE> +</DIV> -The <tt>RewriteEngine</tt> directive enables or disables the -runtime rewriting engine. If it is set to <code>off</code> this module does -no runtime processing at all. It does not even update the <tt>SCRIPT_URx</tt> +<P> +We know, this was a crash course of mod_rewrite's internal processing. But +you will benefit from this knowledge when reading the following documentation +of the available directives. + +<P> +<HR NOSHADE SIZE=1> + +<CENTER> +<H1><A NAME="Configuration">Configuration Directives</A></H1> +</CENTER> + +<P> +<HR NOSHADE SIZE=1> + +<H3><A NAME="RewriteEngine">RewriteEngine</A></H3> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> + <CODE>RewriteEngine</CODE> {<CODE>on,off</CODE>}<BR> +<A + HREF="directive-dict.html#Default" + REL="Help" +><STRONG>Default:</STRONG></A> + <STRONG><CODE>RewriteEngine off</CODE></STRONG><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> + server config, virtual host, directory, .htaccess<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> FileInfo<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Extension<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> +<A + HREF="directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> Apache 1.2<BR> + +<P> +The <CODE>RewriteEngine</CODE> directive enables or disables the runtime +rewriting engine. If it is set to <CODE>off</CODE> this module does no runtime +processing at all. It does not even update the <CODE>SCRIPT_URx</CODE> environment variables. -<p> +<P> Use this directive to disable the module instead of commenting out -all <tt>RewriteRule</tt> directives! - -<p> -<hr noshade size=1> -<p> - -<a name="RewriteOptions"><h3>RewriteOptions</h3></a> -<strong>Syntax:</strong> <code>RewriteOptions</code> <em>Option</em> ...<br> -<strong>Default:</strong> -<em>None</em>-<br> -<strong>Context:</strong> server config, virtual host, per-directory config<br> -<p> - -The <tt>RewriteOption</tt> directive sets some special options for the -current per-server or per-directory configuration. The <em>Option</em> +all <CODE>RewriteRule</CODE> directives! + +<P> +Note that, by default, rewrite configurations are not inherited. +This means that you need to have a <CODE>RewriteEngine on</CODE> +directive for each virtual host you wish to use it in. + +<P> +<HR NOSHADE SIZE=1> +<P> + +<H3><A NAME="RewriteOptions">RewriteOptions</A></H3> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> <CODE>RewriteOptions</CODE> <EM>Option</EM><BR> +<A + HREF="directive-dict.html#Default" + REL="Help" +><STRONG>Default:</STRONG></A> <EM>None</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host, directory, + .htaccess<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> FileInfo<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Extension<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> +<A + HREF="directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> Apache 1.2<BR> + +<P> +The <CODE>RewriteOptions</CODE> directive sets some special options for the +current per-server or per-directory configuration. The <EM>Option</EM> strings can be one of the following: -<ul> -<li>'<strong><code>inherit</code></strong>'<br> +<UL> +<LI>'<STRONG><CODE>inherit</CODE></STRONG>'<BR> This forces the current configuration to inherit the configuration of the parent. In per-virtual-server context this means that the maps, conditions and rules of the main server gets inherited. In per-directory context this means that conditions and rules of the parent directory's - <tt>.htaccess</tt> configuration gets inherited. -</ul> - -<p> -<hr noshade size=1> -<p> - -<a name="RewriteLog"><h3>RewriteLog</h3></a> -<strong>Syntax:</strong> <code>RewriteLog</code> <em>Filename</em><br> -<strong>Default:</strong> -<em>None</em>-<br> -<strong>Context:</strong> server config, virtual host<br> -<p> - -The <tt>RewriteLog</tt> directive sets the name of the file to which the + <CODE>.htaccess</CODE> configuration gets inherited. +</UL> + +<P> +<HR NOSHADE SIZE=1> +<P> + +<H3><A NAME="RewriteLog">RewriteLog</A></H3> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> <CODE>RewriteLog</CODE> <EM>Filename</EM><BR> +<A + HREF="directive-dict.html#Default" + REL="Help" +><STRONG>Default:</STRONG></A> <EM>None</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Extension<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> +<A + HREF="directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> Apache 1.2<BR> + +<P> +The <CODE>RewriteLog</CODE> directive sets the name of the file to which the server logs any rewriting actions it performs. If the name does not begin -with a slash ('<tt>/</tt>') then it is assumed to be relative to the -<em>Server Root</em>. The directive should occur only once per server +with a slash ('<CODE>/</CODE>') then it is assumed to be relative to the +<EM>Server Root</EM>. The directive should occur only once per server config. -<p> -<table width="70%" border=0 bgcolor="#f0f0f0" cellspacing=0 cellpadding=10> -<tr><td> -To disable the logging of rewriting actions it is not recommended -to set <em>Filename</em> -to <code>/dev/null</code>, because although the rewriting engine does +<P> +<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> +<TR><TD> +<STRONG>Notice</STRONG>: To disable the logging of rewriting actions it is +not recommended to set <EM>Filename</EM> +to <CODE>/dev/null</CODE>, because although the rewriting engine does not create output to a logfile it still creates the logfile -output internally. <b>This will slow down the server with no advantage to the -administrator!</b> +output internally. <STRONG>This will slow down the server with no advantage +to the administrator!</STRONG> To disable logging either remove or comment out the -<tt>RewriteLog</tt> directive or use <tt>RewriteLogLevel 0</tt>! -</td></tr> -</table> - -<p> -<table width="70%" border=0 bgcolor="#fff0f0" cellspacing=0 cellpadding=10> -<tr><td> -SECURITY: See the <a -href="../misc/security_tips.html">Apache Security -Tips</a> document for details on why your security could be compromised if the +<CODE>RewriteLog</CODE> directive or use <CODE>RewriteLogLevel 0</CODE>! +</TD></TR> +</TABLE> + +<P> +<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> +<TR><TD> +<STRONG>Security</STRONG>: See the <A +HREF="../misc/security_tips.html">Apache Security +Tips</A> document for details on why your security could be compromised if the directory where logfiles are stored is writable by anyone other than the user that starts the server. -</td></tr> -</table> +</TD></TR> +</TABLE> -<p> -<b>Example:</b> -<blockquote> -<pre> +<P> +<STRONG>Example:</STRONG> +<BLOCKQUOTE> +<PRE> RewriteLog "/usr/local/var/apache/logs/rewrite.log" -</pre> -</blockquote> - -<p> -<hr noshade size=1> -<p> - -<a name="RewriteLogLevel"><h3>RewriteLogLevel</h3></a> -<strong>Syntax:</strong> <code>RewriteLogLevel</code> <em>Level</em><br> -<strong>Default:</strong> <strong><code>RewriteLogLevel 0</code></strong><br> -<strong>Context:</strong> server config, virtual host<br> -<p> - -The <tt>RewriteLogLevel</tt> directive set the verbosity level of the rewriting +</PRE> +</BLOCKQUOTE> + +<P> +<HR NOSHADE SIZE=1> +<P> + +<H3><A NAME="RewriteLogLevel">RewriteLogLevel</A></H3> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> <CODE>RewriteLogLevel</CODE> <EM>Level</EM><BR> +<A + HREF="directive-dict.html#Default" + REL="Help" +><STRONG>Default:</STRONG></A> <STRONG><CODE>RewriteLogLevel 0</CODE></STRONG> +<BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Extension<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> +<A + HREF="directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> Apache 1.2<BR> + +<P> +The <CODE>RewriteLogLevel</CODE> directive set the verbosity level of the +rewriting logfile. The default level 0 means no logging, while 9 or more means that practically all actions are logged. -<p> -To disable the logging of rewriting actions simply set <em>Level</em> to 0. +<P> +To disable the logging of rewriting actions simply set <EM>Level</EM> to 0. This disables all rewrite action logs. -<p> -<table width="70%" border=0 bgcolor="#f0f0f0" cellspacing=0 cellpadding=10> -<tr><td> -<b>Notice:</b> Using a high value for <i>Level</i> will slow down your Apache +<P> +<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> +<TR><TD> +<STRONG>Notice:</STRONG> Using a high value for <EM>Level</EM> will slow down +your Apache server dramatically! Use the rewriting logfile only for debugging or at least -at <em>Level</em> not greater than 2! -</td></tr> -</table> +at <EM>Level</EM> not greater than 2! +</TD></TR> +</TABLE> -<p> -<b>Example:</b> -<blockquote> -<pre> +<P> +<STRONG>Example:</STRONG> +<BLOCKQUOTE> +<PRE> RewriteLogLevel 3 -</pre> -</blockquote> - -<p> -<hr noshade size=1> -<p> - -<a name="RewriteMap"><h3>RewriteMap</h3></a> -<strong>Syntax:</strong> <code>RewriteMap</code> <em>Mapname</em> <code>{txt,dbm,prg}:</code><em>Filename</em><br> -<strong>Default:</strong> not used per default<br> -<strong>Context:</strong> server config, virtual host<br> -<p> - -The <tt>RewriteMap</tt> directive defines an external <em>Rewriting Map</em> +</PRE> +</BLOCKQUOTE> + +<P> +<HR NOSHADE SIZE=1> +<P> + +<H3><A NAME="RewriteLock">RewriteLock</A></H3> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> <CODE>RewriteLock</CODE> <EM>Filename</EM><BR> +<A + HREF="directive-dict.html#Default" + REL="Help" +><STRONG>Default:</STRONG></A> <EM>None</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Extension<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> +<A + HREF="directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> Apache 1.3<BR> + +<P> +This directive sets the filename for a synchronization lockfile which +mod_rewrite needs to communicate with <SAMP>RewriteMap</SAMP> +<EM>programs</EM>. Set this lockfile to a local path (not on a NFS-mounted +device) when you want to use a rewriting map-program. It is not required for +SAMP using all other types of rewriting maps. + +<P> +<HR NOSHADE SIZE=1> +<P> + +<H3><A NAME="RewriteMap">RewriteMap</A></H3> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> <CODE>RewriteMap</CODE> <EM>MapName </EM> + <EM>MapType</EM><CODE>:</CODE><EM>MapSource</EM><BR> +<A + HREF="directive-dict.html#Default" + REL="Help" +><STRONG>Default:</STRONG></A> not used per default<BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Extension<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> +<A + HREF="directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> Apache 1.2 (partially), Apache 1.3<BR> + +<P> +The <CODE>RewriteMap</CODE> directive defines a <EM>Rewriting Map</EM> which can be used inside rule substitution strings by the mapping-functions -to insert/substitute fields through a key lookup. -<p> +to insert/substitute fields through a key lookup. The source of this +lookup can be of various types. +<P> -The <a name="mapfunc"><em>Mapname</em></a> is the name of the map and will +The <A NAME="mapfunc"><EM>MapName</EM></A> is the name of the map and will be used to specify a mapping-function for the substitution strings of a -rewriting rule via - -<blockquote><strong> -<code>${</code> <em>Mapname</em> <code>:</code> <em>LookupKey</em> -<code>|</code> <em>DefaultValue</em> <code>}</code> -</strong></blockquote> - -When such a directive occurs the map <em>Mapname</em> -is consulted and the key <em>LookupKey</em> is looked-up. If the key is -found, the map-function directive is substituted by <em>SubstValue</em>. If -the key is not found then it is substituted by <em>DefaultValue</em>. - -<p> -The <em>Filename</em> must be a valid Unix filepath, containing one -of the following formats: - -<ol> -<li><b>Plain Text Format</b> - <p> - This is a ASCII file which contains either blank lines, comment lines - (starting with a '#' character) or - - <blockquote><strong> - <em>MatchingKey</em> <em>SubstValue</em> - </strong></blockquote> - - pairs - one per line. You can create such files either manually, - using your favorite editor, or by using the programs - <tt>mapcollect</tt> and <tt>mapmerge</tt> from the <tt>support</tt> - directory of the <b>mod_rewrite</b> distribution. - <p> - To declare such a map prefix, <em>Filename</em> with a <code>txt:</code> - string as in the following example: - -<p> -<table border=0 cellspacing=1 cellpadding=5 bgcolor="#f0f0f0"> -<tr><td><pre> -# -# map.real-to-user -- maps realnames to usernames -# +rewriting rule via one of the following constructs: + +<BLOCKQUOTE><STRONG> +<CODE>${</CODE> <EM>MapName</EM> <CODE>:</CODE> <EM>LookupKey</EM> +<CODE>}</CODE><BR> +<CODE>${</CODE> <EM>MapName</EM> <CODE>:</CODE> <EM>LookupKey</EM> +<CODE>|</CODE> <EM>DefaultValue</EM> <CODE>}</CODE> +</STRONG></BLOCKQUOTE> + +When such a construct occurs the map <EM>MapName</EM> +is consulted and the key <EM>LookupKey</EM> is looked-up. If the key is +found, the map-function construct is substituted by <EM>SubstValue</EM>. If +the key is not found then it is substituted by <EM>DefaultValue</EM> or +the empty string if no <EM>DefaultValue</EM> was specified. + +<P> +The following combinations for <EM>MapType</EM> and <EM>MapSource</EM> +can be used: + +<UL> +<LI><STRONG>Standard Plain Text</STRONG><BR> + MapType: <CODE>txt</CODE>, MapSource: Unix filesystem path to valid regular + file + <P> + This is the standard rewriting map feature where the <EM>MapSource</EM> is + a plain ASCII file containing either blank lines, comment lines (starting + with a '#' character) or pairs like the following - one per line. + + <BLOCKQUOTE><STRONG> + <EM>MatchingKey</EM> <EM>SubstValue</EM> + </STRONG></BLOCKQUOTE> + + <P> + Example: +<P> +<TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> +<TR><TD><PRE> +## +## map.txt -- rewriting map +## Ralf.S.Engelschall rse # Bastard Operator From Hell -Dr.Fred.Klabuster fred # Mr. DAU -</pre></td></tr> -</table> - -<p> -<table border=0 cellspacing=1 cellpadding=5 bgcolor="#f0f0f0"> -<tr><td><pre> -RewriteMap real-to-host txt:/path/to/file/map.real-to-user -</pre></td></tr> -</table> - -<p> -<li><b>DBM Hashfile Format</b> - <p> - This is a binary NDBM format file containing the - same contents as the <em>Plain Text Format</em> files. You can create - such a file with any NDBM tool or with the <tt>dbmmanage</tt> program - from the <tt>support</tt> directory of the Apache distribution. - <p> - To declare such a map prefix <em>Filename</em> with a <code>dbm:</code> - string. -<p> -<li><b>Program Format</b> - <p> - This is a Unix executable, not a lookup file. To create it you can use +Mr.Joe.Average joe # Mr. Average +</PRE></TD></TR> +</TABLE> + +<P> +<TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> +<TR><TD><PRE> +RewriteMap real-to-user txt:/path/to/file/map.txt +</PRE></TD></TR> +</TABLE> + +<P> +<LI><STRONG>Randomized Plain Text</STRONG><BR> + MapType: <CODE>rnd</CODE>, MapSource: Unix filesystem path to valid regular + file + <P> + This is identical to the Standard Plain Text variant above but with a + special + post-processing feature: After looking up a value it is parsed according + to contained ``<CODE>|</CODE>'' characters which have the meaning of + ``or''. Or + in other words: they indicate a set of alternatives from which the actual + returned value is chosen randomly. Although this sounds crazy and useless, + it + was actually designed for load balancing in a reverse proxy situation where + the looked up values are server names. + Example: +<P> +<TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> +<TR><TD><PRE> +## +## map.txt -- rewriting map +## + +static www1|www2|www3|www4 +dynamic www5|www6 +</PRE></TD></TR> +</TABLE> + +<P> +<TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> +<TR><TD><PRE> +RewriteMap servers rnd:/path/to/file/map.txt +</PRE></TD></TR> +</TABLE> + +<P> +<LI><STRONG>Hash File</STRONG><BR> + MapType: <CODE>dbm</CODE>, MapSource: Unix filesystem path to valid + regular file + <P> + Here the source is a binary NDBM format file containing the same contents + as a <EM>Plain Text</EM> format file, but in a special representation + which is optimized for really fast lookups. You can create such a file with + any NDBM tool or with the following Perl script: + <P> + <TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> + <TR><TD><PRE> +#!/path/to/bin/perl +## +## txt2dbm -- convert txt map to dbm format +## + +($txtmap, $dbmmap) = @ARGV; +open(TXT, "<$txtmap"); +dbmopen(%DB, $dbmmap, 0644); +while (<TXT>) { + next if (m|^s*#.*| or m|^s*$|); + $DB{$1} = $2 if (m|^\s*(\S+)\s+(\S+)$|); +} +dbmclose(%DB); +close(TXT)</PRE></TD></TR> + </TABLE> + <P> + <TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> + <TR><TD><PRE>$ txt2dbm map.txt map.db </PRE></TD></TR> + </TABLE> +<P> +<LI><STRONG>Internal Function</STRONG><BR> + MapType: <CODE>int</CODE>, MapSource: Internal Apache function + <P> + Here the source is an internal Apache function. Currently you cannot + create your own, but the following functions already exists: + <UL> + <LI><STRONG>toupper</STRONG>:<BR> + Converts the looked up key to all upper case. + <LI><STRONG>tolower</STRONG>:<BR> + Converts the looked up key to all lower case. + <LI><STRONG>escape</STRONG>:<BR> + Translates special characters in the looked up key to hex-encodings. + <LI><STRONG>unescape</STRONG>:<BR> + Translates hex-encodings in the looked up key back to special characters. + </UL> +<P> +<LI><STRONG>External Rewriting Program</STRONG><BR> + MapType: <CODE>prg</CODE>, MapSource: Unix filesystem path to valid + regular file + <P> + Here the source is a Unix program, not a map file. To create it you can use the language of your choice, but the result has to be a run-able Unix - binary (i.e. either object-code or a script with the - magic cookie trick '<tt>#!/path/to/interpreter</tt>' as the first line). - <p> + executable (<EM>i.e.</EM>, either object-code or a script with the + magic cookie trick '<CODE>#!/path/to/interpreter</CODE>' as the first + line). + <P> This program gets started once at startup of the Apache servers and then - communicates with the rewriting engine over its <tt>stdin</tt> and - <tt>stdout</tt> file-handles. For each map-function lookup it will + communicates with the rewriting engine over its <CODE>stdin</CODE> and + <CODE>stdout</CODE> file-handles. For each map-function lookup it will receive the key to lookup as a newline-terminated string on - <tt>stdin</tt>. It then has to give back the looked-up value as a - newline-terminated string on <tt>stdout</tt> or the four-character string - ``<tt>NULL</tt>'' if it fails (i.e. there is no corresponding value + <CODE>stdin</CODE>. It then has to give back the looked-up value as a + newline-terminated string on <CODE>stdout</CODE> or the four-character + string ``<CODE>NULL</CODE>'' if it fails (<EM>i.e.</EM>, there is no + corresponding value for the given key). A trivial program which will implement a 1:1 map - (i.e. key == value) could be: - <p> -<table border=0 cellspacing=1 cellpadding=5 bgcolor="#f0f0f0"> -<tr><td><pre> + (<EM>i.e.</EM>, key == value) could be: + <P> +<TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> +<TR><TD><PRE> #!/usr/bin/perl $| = 1; while (<STDIN>) { @@ -321,90 +793,117 @@ while (<STDIN>) { # or lookups should occur... print $_; } -</pre></td></tr> -</table> - <p> - <b>But be very careful:</b><br> - <ol> - <li>``<i>Keep the program simple, stupid</i>'' (KISS), because +</PRE></TD></TR> +</TABLE> + <P> + But be very careful:<BR> + <OL> + <LI>``<EM>Keep the program simple, stupid</EM>'' (KISS), because if this program hangs it will lead to a hang of the Apache server when the rule occurs. - <li>Avoid one common mistake: never do buffered I/O on <tt>stdout</tt>! - This will cause a deadloop! Hence the ``<tt>$|=1</tt>'' in the above - example... - </ol> - <p> - To declare such a map prefix <em>Filename</em> with a <code>prg:</code> - string. -</ol> - -The <tt>RewriteMap</tt> directive can occur more than once. For each -mapping-function use one <tt>RewriteMap</tt> directive to declare its -rewriting mapfile. While you cannot <b>declare</b> a map in per-directory -context it is of course possible to <b>use</b> this map in per-directory -context. - -<p> -<table width="70%" border=0 bgcolor="#f0f0f0" cellspacing=0 cellpadding=10> -<tr><td> -For plain text and DBM format files the looked-up keys are cached in-core -until the <tt>mtime</tt> of the mapfile changes or the server does a + <LI>Avoid one common mistake: never do buffered I/O on <CODE>stdout</CODE>! + This will cause a deadloop! Hence the ``<CODE>$|=1</CODE>'' in the + above example... + <LI>Use the <SAMP>RewriteLock</SAMP> directive to define a lockfile + mod_rewrite can use to synchronize the communication to the program. + Per default no such synchronization takes place. + </OL> +</UL> + +The <CODE>RewriteMap</CODE> directive can occur more than once. For each +mapping-function use one <CODE>RewriteMap</CODE> directive to declare its +rewriting mapfile. While you cannot <STRONG>declare</STRONG> a map in +per-directory context it is of course possible to <STRONG>use</STRONG> +this map in per-directory context. + +<P> +<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> +<TR><TD> +<STRONG>Notice:</STRONG> For plain text and DBM format files the looked-up +keys are cached in-core +until the <CODE>mtime</CODE> of the mapfile changes or the server does a restart. This way you can have map-functions in rules which are used -for <b>every</b> request. This is no problem, because the external lookup -only happens once! -</td></tr> -</table> - - -<p> -<hr noshade size=1> -<p> - -<a name="RewriteBase"><h3>RewriteBase</h3></a> -<strong>Syntax:</strong> <code>RewriteBase</code> <em>BaseURL</em><br> -<strong>Default:</strong> <em>default is the physical directory path</em><br> -<strong>Context:</strong> per-directory config<br> -<p> - -The <tt>RewriteBase</tt> directive explicitly sets the base URL for -per-directory rewrites. As you will see below, <tt>RewriteRule</tt> can be -used in per-directory config files (<tt>.htaccess</tt>). There it will act -locally, i.e. the local directory prefix is stripped at this stage of +for <STRONG>every</STRONG> request. This is no problem, because the +external lookup only happens once! +</TD></TR> +</TABLE> + +<P> +<HR NOSHADE SIZE=1> +<P> + +<H3><A NAME="RewriteBase">RewriteBase</A></H3> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> <CODE>RewriteBase</CODE> <EM>BaseURL</EM><BR> +<A + HREF="directive-dict.html#Default" + REL="Help" +><STRONG>Default:</STRONG></A> <EM>default is the physical directory path</EM> +<BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> directory, .htaccess<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> <EM>FileInfo</EM><BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Extension<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> +<A + HREF="directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> Apache 1.2<BR> + +<P> +The <CODE>RewriteBase</CODE> directive explicitly sets the base URL for +per-directory rewrites. As you will see below, <CODE>RewriteRule</CODE> can be +used in per-directory config files (<CODE>.htaccess</CODE>). There it will act +locally, <EM>i.e.</EM>, the local directory prefix is stripped at this stage of processing and your rewriting rules act only on the remainder. At the end it is automatically added. -<p> -When a substitution occurs for a new URL, this module has to -re-inject the URL into the server processing. To be able to do this it needs -to know what the corresponding URL-prefix or URL-base is. By default this -prefix is the corresponding filepath itself. <b>But at most websites URLs are -<b>NOT</b> directly related to physical filename paths, so this assumption -will be usually be wrong!</b> There you have to use the <tt>RewriteBase</tt> -directive to specify the correct URL-prefix. - -<p> -<table width="70%" border=0 bgcolor="#fff0f0" cellspacing=0 cellpadding=10> -<tr><td> -So, if your webserver's URLs are <b>not</b> directly -related to physical file paths, you have to use <tt>RewriteBase</tt> in every -<tt>.htaccess</tt> files where you want to use <tt>RewriteRule</tt> +<P> +When a substitution occurs for a new URL, this module has to re-inject the URL +into the server processing. To be able to do this it needs to know what the +corresponding URL-prefix or URL-base is. By default this prefix is the +corresponding filepath itself. <STRONG>But at most websites URLs are +<STRONG>NOT</STRONG> directly related to physical filename paths, so this +assumption will be usually be wrong!</STRONG> There you have to use the +<CODE>RewriteBase</CODE> directive to specify the correct URL-prefix. + +<P> +<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> +<TR><TD> +<STRONG>Notice:</STRONG> If your webserver's URLs are <STRONG>not</STRONG> +directly related to physical file paths, you have to use +<CODE>RewriteBase</CODE> in every +<CODE>.htaccess</CODE> files where you want to use <CODE>RewriteRule</CODE> directives. -</td></tr> -</table> +</TD></TR> +</TABLE> -<p> -<b>Example:</b> +<P> +<STRONG>Example:</STRONG> -<blockquote> +<BLOCKQUOTE> Assume the following per-directory config file: -<p> -<table border=0 cellspacing=1 cellpadding=5 bgcolor="#f0f0f0"> -<tr><td><pre> +<P> +<TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> +<TR><TD><PRE> # # /abc/def/.htaccess -- per-dir config file for directory /abc/def -# Remember: /abc/def is the physical path of /xyz, i.e. the server -# has a 'Alias /xyz /abc/def' directive e.g. +# Remember: /abc/def is the physical path of /xyz, <EM>i.e.</EM>, the server +# has a 'Alias /xyz /abc/def' directive <EM>e.g.</EM> # RewriteEngine On @@ -415,35 +914,36 @@ RewriteBase /xyz # now the rewriting rules RewriteRule ^oldstuff\.html$ newstuff.html -</pre></td></tr> -</table> - -<p> -In the above example, a request to <tt>/xyz/oldstuff.html</tt> gets correctly -rewritten to the physical file <tt>/abc/def/newstuff.html</tt>. - -<p> -<table width="70%" border=0 bgcolor="#fff0f0" cellspacing=0 cellpadding=10> -<tr><td> -<font size=-1> -<b>For the Apache hackers:</b><br> +</PRE></TD></TR> +</TABLE> + +<P> +In the above example, a request to <CODE>/xyz/oldstuff.html</CODE> +gets correctly +rewritten to the physical file <CODE>/abc/def/newstuff.html</CODE>. + +<P> +<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> +<TR><TD> +<FONT SIZE=-1> +<STRONG>Notice - For the Apache hackers:</STRONG><BR> The following list gives detailed information about the internal processing steps: -<p> -<pre> +<P> +<PRE> Request: /xyz/oldstuff.html Internal Processing: - /xyz/oldstuff.html -> /abc/def/oldstuff.html (per-server Alias) - /abc/def/oldstuff.html -> /abc/def/newstuff.html (per-dir RewriteRule) - /abc/def/newstuff.html -> /xyz/newstuff.html (per-dir RewriteBase) - /xyz/newstuff.html -> /abc/def/newstuff.html (per-server Alias) + /xyz/oldstuff.html -> /abc/def/oldstuff.html (per-server Alias) + /abc/def/oldstuff.html -> /abc/def/newstuff.html (per-dir RewriteRule) + /abc/def/newstuff.html -> /xyz/newstuff.html (per-dir RewriteBase) + /xyz/newstuff.html -> /abc/def/newstuff.html (per-server Alias) Result: /abc/def/newstuff.html -</pre> +</PRE> This seems very complicated but is the correct Apache internal processing, because the per-directory rewriting comes too late in the process. So, @@ -452,263 +952,343 @@ kernel! BUT: While this seems like a serious overhead, it really isn't, because this re-injection happens fully internal to the Apache server and the same procedure is used by many other operations inside Apache. So, you can be sure the design and implementation is correct. -</font> -</td></tr> -</table> +</FONT> +</TD></TR> +</TABLE> + +</BLOCKQUOTE> + + +<P> +<HR NOSHADE SIZE=1> +<P> + +<H3><A NAME="RewriteCond">RewriteCond</A></H3> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> <CODE>RewriteCond</CODE> <EM>TestString</EM> + <EM>CondPattern</EM><BR> +<A + HREF="directive-dict.html#Default" + REL="Help" +><STRONG>Default:</STRONG></A> <EM>None</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host, directory, + .htaccess<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> <EM>FileInfo</EM><BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Extension<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> +<A + HREF="directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> Apache 1.2 (partially), Apache 1.3<BR> + +<P> +The <CODE>RewriteCond</CODE> directive defines a rule condition. Precede a +<CODE>RewriteRule</CODE> directive with one or more <CODE>RewriteCond</CODE> +directives. -</blockquote> +The following rewriting rule is only used if its pattern matches the current +state of the URI <STRONG>and</STRONG> if these additional conditions apply +too. +<P> +<EM>TestString</EM> is a string which can contains the following +expanded constructs in addition to plain text: -<p> -<hr noshade size=1> -<p> +<UL> +<LI><STRONG>RewriteRule backreferences</STRONG>: These are backreferences of + the form -<a name="RewriteCond"><h3>RewriteCond</h3></a> -<strong>Syntax:</strong> <code>RewriteCond</code> <em>TestString</em> <em>CondPattern</em><br> -<strong>Default:</strong> -<em>None</em>-<br> -<strong>Context:</strong> server config, virtual host, per-directory config<br> -<p> +<BLOCKQUOTE><STRONG> +<CODE>$N</CODE> +</STRONG></BLOCKQUOTE> -The <tt>RewriteCond</tt> directive defines a rule condition. Precede a -<tt>RewriteRule</tt> directive with one or more <tt>RewriteCond</tt> -directives. +(1 <= N <= 9) which provide access to the grouped parts (parenthesis!) +of the +pattern from the corresponding <CODE>RewriteRule</CODE> directive (the one +following the current bunch of <CODE>RewriteCond</CODE> directives). -The following rewriting rule is only used if its pattern matches the current -state of the URI <b>AND</b> if these additional conditions apply, too. +<P> +<LI><STRONG>RewriteCond backreferences</STRONG>: These are backreferences of +the form + +<BLOCKQUOTE><STRONG> +<CODE>%N</CODE> +</STRONG></BLOCKQUOTE> -<p> -<em>TestString</em> is a string which contains server-variables of the form +(1 <= N <= 9) which provide access to the grouped parts (parenthesis!) of +the pattern from the last matched <CODE>RewriteCond</CODE> directive in the +current bunch of conditions. -<blockquote><strong> -<tt>%{</tt> <em>NAME_OF_VARIABLE</em> <tt>}</tt> -</strong></blockquote> +<P> +<LI><STRONG>Server-Variables</STRONG>: These are variables + of the form -where <em>NAME_OF_VARIABLE</em> can be a string +<BLOCKQUOTE><STRONG> +<CODE>%{</CODE> <EM>NAME_OF_VARIABLE</EM> <CODE>}</CODE> +</STRONG></BLOCKQUOTE> + +where <EM>NAME_OF_VARIABLE</EM> can be a string of the following list: -<p> -<table bgcolor="#f0f0f0" cellspacing=0 cellpadding=5> -<tr> -<td valign=top> -<b>HTTP headers:</b><p> -<font size=-1> -HTTP_USER_AGENT<br> -HTTP_REFERER<br> -HTTP_COOKIE<br> -HTTP_FORWARDED<br> -HTTP_HOST<br> -HTTP_PROXY_CONNECTION<br> -HTTP_ACCEPT<br> -</font> -</td> - -<td valign=top> -<b>connection & request:</b><p> -<font size=-1> -REMOTE_ADDR<br> -REMOTE_HOST<br> -REMOTE_USER<br> -REMOTE_IDENT<br> -REQUEST_METHOD<br> -SCRIPT_FILENAME<br> -PATH_INFO<br> -QUERY_STRING<br> -AUTH_TYPE<br> -</font> -</td> - -</tr> -<tr> - -<td valign=top> -<b>server internals:</b><p> -<font size=-1> -DOCUMENT_ROOT<br> -SERVER_ADMIN<br> -SERVER_NAME<br> -SERVER_PORT<br> -SERVER_PROTOCOL<br> -SERVER_SOFTWARE<br> -SERVER_VERSION<br> -</font> -</td> - -<td valign=top> -<b>system stuff:</b><p> -<font size=-1> -TIME_YEAR<br> -TIME_MON<br> -TIME_DAY<br> -TIME_HOUR<br> -TIME_MIN<br> -TIME_SEC<br> -TIME_WDAY<br> -TIME<br> -</font> -</td> - -<td valign=top> -<b>specials:</b><p> -<font size=-1> -API_VERSION<br> -THE_REQUEST<br> -REQUEST_URI<br> -REQUEST_FILENAME<br> -IS_SUBREQ<br> -</font> -</td> -</tr> -</table> - - -<p> -<table width="70%" border=0 bgcolor="#f0f0f0" cellspacing=0 cellpadding=10> -<tr><td> -These variables all correspond to the similar named HTTP MIME-headers, C -variables of the Apache server or <tt>struct tm</tt> fields of the Unix -system. -</td></tr> -</table> - -<p> +<P> +<TABLE BGCOLOR="#F0F0F0" CELLSPACING=0 CELLPADDING=5> +<TR> +<TD VALIGN=TOP> +<STRONG>HTTP headers:</STRONG><P> +<FONT SIZE=-1> +HTTP_USER_AGENT<BR> +HTTP_REFERER<BR> +HTTP_COOKIE<BR> +HTTP_FORWARDED<BR> +HTTP_HOST<BR> +HTTP_PROXY_CONNECTION<BR> +HTTP_ACCEPT<BR> +</FONT> +</TD> + +<TD VALIGN=TOP> +<STRONG>connection & request:</STRONG><P> +<FONT SIZE=-1> +REMOTE_ADDR<BR> +REMOTE_HOST<BR> +REMOTE_USER<BR> +REMOTE_IDENT<BR> +REQUEST_METHOD<BR> +SCRIPT_FILENAME<BR> +PATH_INFO<BR> +QUERY_STRING<BR> +AUTH_TYPE<BR> +</FONT> +</TD> + +</TR> +<TR> + +<TD VALIGN=TOP> +<STRONG>server internals:</STRONG><P> +<FONT SIZE=-1> +DOCUMENT_ROOT<BR> +SERVER_ADMIN<BR> +SERVER_NAME<BR> +SERVER_PORT<BR> +SERVER_PROTOCOL<BR> +SERVER_SOFTWARE<BR> +</FONT> +</TD> + +<TD VALIGN=TOP> +<STRONG>system stuff:</STRONG><P> +<FONT SIZE=-1> +TIME_YEAR<BR> +TIME_MON<BR> +TIME_DAY<BR> +TIME_HOUR<BR> +TIME_MIN<BR> +TIME_SEC<BR> +TIME_WDAY<BR> +TIME<BR> +</FONT> +</TD> + +<TD VALIGN=TOP> +<STRONG>specials:</STRONG><P> +<FONT SIZE=-1> +API_VERSION<BR> +THE_REQUEST<BR> +REQUEST_URI<BR> +REQUEST_FILENAME<BR> +IS_SUBREQ<BR> +</FONT> +</TD> +</TR> +</TABLE> + +<P> +<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> +<TR><TD> +<STRONG>Notice:</STRONG> These variables all correspond to the similar named +HTTP MIME-headers, C variables of the Apache server or <CODE>struct tm</CODE> +fields of the Unix system. +</TD></TR> +</TABLE> + +</UL> + +<P> Special Notes: -<ol> -<li>The variables SCRIPT_FILENAME and REQUEST_FILENAME contain the same -value, i.e. the value of the <tt>filename</tt> field of the internal -<tt>request_rec</tt> structure of the Apache server. The first name is just the + +<OL> +<LI>The variables SCRIPT_FILENAME and REQUEST_FILENAME contain the same +value, <EM>i.e.</EM>, the value of the <CODE>filename</CODE> field of +the internal +<CODE>request_rec</CODE> structure of the Apache server. The first name is +just the commonly known CGI variable name while the second is the consistent -counterpart to REQUEST_URI (which contains the value of the <tt>uri</tt> -field of <tt>request_rec</tt>). - -<p> -<li>There is the special format: <tt>%{ENV:variable}</tt> where -<i>variable</i> can be any environment variable. This is looked-up via -internal Apache structures and (if not found there) via <tt>getenv()</tt> from -the Apache server process. - -<p> -<li>There is the special format: <tt>%{HTTP:header}</tt> where -<i>header</i> can be any HTTP MIME-header name. This is looked-up -from the HTTP request. Example: <tt>%{HTTP:Proxy-Connection}</tt> -is the value of the HTTP header ``<tt>Proxy-Connection:</tt>''. - -<p> -<li>There is the special format: <tt>%{LA-U:url}</tt> -for look-aheads like <tt>-U</tt>. This performs a internal sub-request to -look-ahead for the final value of <i>url</i>. - -<p> -<li>There is the special format: <tt>%{LA-F:file}</tt> -for look-aheads like <tt>-F</tt>. This performs a internal sub-request to -look-ahead for the final value of <i>file</i>. -</ol> - -<p> -<em>CondPattern</em> is the condition pattern, i.e. a regular expression -which gets applied to the current instance of the <em>TestString</em>, i.e. -<em>TestString</em> gets evaluated and then matched against -<em>CondPattern</em>. - -<p> -<b>Remember:</b> <em>CondPattern</em> is a standard -<em>Extended Regular Expression</em> with some additions: - -<ol> -<li>You can precede the pattern string with a '<tt>!</tt>' character -(exclamation mark) to specify a <b>non</b>-matching pattern. - -<p> -<li> -There are some special variants of <em>CondPatterns</em>. Instead of real +counterpart to REQUEST_URI (which contains the value of the <CODE>uri</CODE> +field of <CODE>request_rec</CODE>). + +<P> +<LI>There is the special format: <CODE>%{ENV:variable}</CODE> where +<EM>variable</EM> can be any environment variable. This is looked-up via +internal Apache structures and (if not found there) via <CODE>getenv()</CODE> +from the Apache server process. + +<P> +<LI>There is the special format: <CODE>%{HTTP:header}</CODE> where +<EM>header</EM> can be any HTTP MIME-header name. This is looked-up +from the HTTP request. Example: <CODE>%{HTTP:Proxy-Connection}</CODE> +is the value of the HTTP header ``<CODE>Proxy-Connection:</CODE>''. + +<P> +<LI>There is the special format <CODE>%{LA-U:variable}</CODE> for look-aheads +which perform an internal (URL-based) sub-request to determine the final value +of <EM>variable</EM>. Use this when you want to use a variable for rewriting +which actually is set later in an API phase and thus is not available at the +current stage. For instance when you want to rewrite according to the +<CODE>REMOTE_USER</CODE> variable from within the per-server context +(<CODE>httpd.conf</CODE> file) you have to use <CODE>%{LA-U:REMOTE_USER}</CODE> +because this variable is set by the authorization phases which come +<EM>after</EM> the URL translation phase where mod_rewrite operates. On the +other hand, because mod_rewrite implements its per-directory context +(<CODE>.htaccess</CODE> file) via the Fixup phase of the API and because the +authorization phases come <EM>before</EM> this phase, you just can use +<CODE>%{REMOTE_USER}</CODE> there. + +<P> +<LI>There is the special format: <CODE>%{LA-F:variable}</CODE> which perform an +internal (filename-based) sub-request to determine the final value of +<EM>variable</EM>. This is the most of the time the same as LA-U above. +</OL> + +<P> +<EM>CondPattern</EM> is the condition pattern, <EM>i.e.</EM>, a regular +expression +which gets applied to the current instance of the <EM>TestString</EM>, +<EM>i.e.</EM>, <EM>TestString</EM> gets evaluated and then matched against +<EM>CondPattern</EM>. + +<P> +<STRONG>Remember:</STRONG> <EM>CondPattern</EM> is a standard +<EM>Extended Regular Expression</EM> with some additions: + +<OL> +<LI>You can precede the pattern string with a '<CODE>!</CODE>' character +(exclamation mark) to specify a <STRONG>non</STRONG>-matching pattern. + +<P> +<LI> +There are some special variants of <EM>CondPatterns</EM>. Instead of real regular expression strings you can also use one of the following: -<p> -<ul> -<li>'<b><CondPattern</b>' (is lexicographically lower)<br> -Treats the <i>CondPattern</i> as a plain string and compares it -lexicographically to <i>TestString</i> and results in a true expression if -<i>TestString</i> is lexicographically lower then <i>CondPattern</i>. -<p> -<li>'<b>>CondPattern</b>' (is lexicographically greater)<br> -Treats the <i>CondPattern</i> as a plain string and compares it -lexicographically to <i>TestString</i> and results in a true expression if -<i>TestString</i> is lexicographically greater then <i>CondPattern</i>. -<p> -<li>'<b>=CondPattern</b>' (is lexicographically equal)<br> -Treats the <i>CondPattern</i> as a plain string and compares it -lexicographically to <i>TestString</i> and results in a true expression if -<i>TestString</i> is lexicographically equal to <i>CondPattern</i>, i.e the +<P> +<UL> +<LI>'<STRONG><CondPattern</STRONG>' (is lexicographically lower)<BR> +Treats the <EM>CondPattern</EM> as a plain string and compares it +lexicographically to <EM>TestString</EM> and results in a true expression if +<EM>TestString</EM> is lexicographically lower than <EM>CondPattern</EM>. +<P> +<LI>'<STRONG>>CondPattern</STRONG>' (is lexicographically greater)<BR> +Treats the <EM>CondPattern</EM> as a plain string and compares it +lexicographically to <EM>TestString</EM> and results in a true expression if +<EM>TestString</EM> is lexicographically greater than <EM>CondPattern</EM>. +<P> +<LI>'<STRONG>=CondPattern</STRONG>' (is lexicographically equal)<BR> +Treats the <EM>CondPattern</EM> as a plain string and compares it +lexicographically to <EM>TestString</EM> and results in a true expression if +<EM>TestString</EM> is lexicographically equal to <EM>CondPattern</EM>, i.e the two strings are exactly equal (character by character). -<p> -<li>'<b>-d</b>' (is <b>d</b>irectory)<br> -Treats the <i>TestString</i> as a pathname and +If <EM>CondPattern</EM> is just <SAMP>""</SAMP> (two quotation marks) this +compares <EM>TestString</EM> against the empty string. +<P> +<LI>'<STRONG>-d</STRONG>' (is <STRONG>d</STRONG>irectory)<BR> +Treats the <EM>TestString</EM> as a pathname and tests if it exists and is a directory. -<p> -<li>'<b>-f</b>' (is regular <b>f</b>ile)<br> -Treats the <i>TestString</i> as a pathname and +<P> +<LI>'<STRONG>-f</STRONG>' (is regular <STRONG>f</STRONG>ile)<BR> +Treats the <EM>TestString</EM> as a pathname and tests if it exists and is a regular file. -<p> -<li>'<b>-s</b>' (is regular file with <b>s</b>ize)<br> -Treats the <i>TestString</i> as a pathname and -tests if it exists and is a regular file with size greater then zero. -<p> -<li>'<b>-l</b>' (is symbolic <b>l</b>ink)<br> -Treats the <i>TestString</i> as a pathname and +<P> +<LI>'<STRONG>-s</STRONG>' (is regular file with <STRONG>s</STRONG>ize)<BR> +Treats the <EM>TestString</EM> as a pathname and +tests if it exists and is a regular file with size greater than zero. +<P> +<LI>'<STRONG>-l</STRONG>' (is symbolic <STRONG>l</STRONG>ink)<BR> +Treats the <EM>TestString</EM> as a pathname and tests if it exists and is a symbolic link. -<p> -<li>'<b>-F</b>' (is existing file via subrequest)<br> -Checks if <i>TestString</i> is a valid file and accessible via all the +<P> +<LI>'<STRONG>-F</STRONG>' (is existing file via subrequest)<BR> +Checks if <EM>TestString</EM> is a valid file and accessible via all the server's currently-configured access controls for that path. This uses an internal subrequest to determine the check, so use it with care because it decreases your servers performance! -<p> -<li>'<b>-U</b>' (is existing URL via subrequest)<br> -Checks if <i>TestString</i> is a valid URL and accessible via all the server's +<P> +<LI>'<STRONG>-U</STRONG>' (is existing URL via subrequest)<BR> +Checks if <EM>TestString</EM> is a valid URL and accessible via all the +server's currently-configured access controls for that path. This uses an internal subrequest to determine the check, so use it with care because it decreases -your servers performance! -</ul> -<p> -Notice: All of these tests can also be prefixed by a not ('!') character +your server's performance! +</UL> +<P> +<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> +<TR><TD> +<STRONG>Notice:</STRONG> +All of these tests can also be prefixed by a not ('!') character to negate their meaning. -</ol> +</TD></TR> +</TABLE> +</OL> -<p> -Additionally you can set special flags for <em>CondPattern</em> by appending +<P> +Additionally you can set special flags for <EM>CondPattern</EM> by appending -<blockquote><strong> -<code>[</code><em>flags</em><code>]</code> -</strong></blockquote> +<BLOCKQUOTE><STRONG> +<CODE>[</CODE><EM>flags</EM><CODE>]</CODE> +</STRONG></BLOCKQUOTE> -as the third argument to the <tt>RewriteCond</tt> directive. <em>Flags</em> +as the third argument to the <CODE>RewriteCond</CODE> directive. <EM>Flags</EM> is a comma-separated list of the following flags: -<ul> -<li>'<strong><code>nocase|NC</code></strong>' (<b>n</b>o <b>c</b>ase)<br> - This makes the condition test case-insensitive, i.e. there is +<UL> +<LI>'<STRONG><CODE>nocase|NC</CODE></STRONG>' (<STRONG>n</STRONG>o <STRONG>c</STRONG>ase)<BR> + This makes the condition test case-insensitive, <EM>i.e.</EM>, there is no difference between 'A-Z' and 'a-z' both in the expanded - <em>TestString</em> and the <em>CondPattern</em>. -<p> -<li>'<strong><code>ornext|OR</code></strong>' (<b>or</b> next condition)<br> + <EM>TestString</EM> and the <EM>CondPattern</EM>. +<P> +<LI>'<STRONG><CODE>ornext|OR</CODE></STRONG>' (<STRONG>or</STRONG> next condition)<BR> Use this to combine rule conditions with a local OR instead of the implicit AND. Typical example: - <p> -<blockquote><pre> + <P> +<BLOCKQUOTE><PRE> RewriteCond %{REMOTE_HOST} ^host1.* [OR] RewriteCond %{REMOTE_HOST} ^host2.* [OR] RewriteCond %{REMOTE_HOST} ^host3.* RewriteRule ...some special stuff for any of these hosts... -</pre></blockquote> +</PRE></BLOCKQUOTE> Without this flag you had to write down the cond/rule three times. -</ul> +</UL> -<p> -<b>Example:</b> -<blockquote> +<P> +<STRONG>Example:</STRONG> +<BLOCKQUOTE> -To rewrite the Homepage of a site according to the ``<tt>User-Agent:</tt>'' +To rewrite the Homepage of a site according to the ``<CODE>User-Agent:</CODE>'' header of the request, you can use the following: -<blockquote><pre> +<BLOCKQUOTE><PRE> RewriteCond %{HTTP_USER_AGENT} ^Mozilla.* RewriteRule ^/$ /homepage.max.html [L] @@ -716,354 +1296,417 @@ RewriteCond %{HTTP_USER_AGENT} ^Lynx.* RewriteRule ^/$ /homepage.min.html [L] RewriteRule ^/$ /homepage.std.html [L] -</pre></blockquote> +</PRE></BLOCKQUOTE> Interpretation: If you use Netscape Navigator as your browser (which identifies itself as 'Mozilla'), then you get the max homepage, which includes -Frames, etc. If you use the Lynx browser (which is Terminal-based), then you -get the min homepage, which contains no images, no tables, etc. If you +Frames, <EM>etc.</EM> If you use the Lynx browser (which is Terminal-based), then you +get the min homepage, which contains no images, no tables, <EM>etc.</EM> If you use any other browser you get the standard homepage. -</blockquote> - -<p> -<hr noshade size=1> -<p> - -<a name="RewriteRule"><h3>RewriteRule</h3></a> -<strong>Syntax:</strong> <code>RewriteRule</code> <em>Pattern</em> <em>Substitution</em><br> -<strong>Default:</strong> -<em>None</em>-<br> -<strong>Context:</strong> server config, virtual host, per-directory config<br> - -<p> -The <tt>RewriteRule</tt> directive is the real rewriting workhorse. The +</BLOCKQUOTE> + +<P> +<HR NOSHADE SIZE=1> +<P> + +<H3><A NAME="RewriteRule">RewriteRule</A></H3> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> <CODE>RewriteRule</CODE> <EM>Pattern</EM> <EM>Substitution</EM><BR> +<A + HREF="directive-dict.html#Default" + REL="Help" +><STRONG>Default:</STRONG></A> <EM>None</EM><BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> +<A + HREF="directive-dict.html#Override" + REL="Help" +><STRONG>Override:</STRONG></A> <EM>FileInfo</EM><BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Extension<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> +<A + HREF="directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> Apache 1.2 (partially), Apache 1.3<BR> + +<P> +The <CODE>RewriteRule</CODE> directive is the real rewriting workhorse. The directive can occur more than once. Each directive then defines one single -rewriting rule. The <b>definition order</b> of these rules is -<b>important</b>, because this order is used when applying the rules at +rewriting rule. The <STRONG>definition order</STRONG> of these rules is +<STRONG>important</STRONG>, because this order is used when applying the rules at run-time. -<p> -<a name="patterns"><em>Pattern</em></a> can be (for Apache 1.1.x a System -V8 and for Apache 1.2.x a POSIX) <a name="regexp">regular expression</a> +<P> +<A NAME="patterns"><EM>Pattern</EM></A> can be (for Apache 1.1.x a System +V8 and for Apache 1.2.x a POSIX) <A NAME="regexp">regular expression</A> which gets applied to the current URL. Here ``current'' means the value of the URL when this rule gets applied. This may not be the original requested URL, because there could be any number of rules before which already matched and made alterations to it. -<p> +<P> Some hints about the syntax of regular expressions: -<p> -<table bgcolor="#f0f0f0" cellspacing=0 cellpadding=5> -<tr> -<td valign=top> -<pre> -<strong><code>^</code></strong> Start of line -<strong><code>$</code></strong> End of line -<strong><code>.</code></strong> Any single character -<strong><code>[</code></strong>chars<strong><code>]</code></strong> One of chars -<strong><code>[^</code></strong>chars<strong><code>]</code></strong> None of chars - -<strong><code>?</code></strong> 0 or 1 of the preceding char -<strong><code>*</code></strong> 0 or N of the preceding char -<strong><code>+</code></strong> 1 or N of the preceding char - -<strong><code>\</code></strong>char escape that specific char - (e.g. for specifying the chars "<code>.[]()</code>" etc.) - -<strong><code>(</code></strong>string<strong><code>)</code></strong> Grouping of chars (the <b>N</b>th group can be used on the RHS with <code>$</code><b>N</b>) -</pre> -</td> -</tr> -</table> - -<p> -Additionally the NOT character ('<tt>!</tt>') is a possible pattern -prefix. This gives you the ability to negate a pattern; to say, for instance: ``<i>if -the current URL does <b>NOT</b> match to this pattern</i>''. This can be used -for special cases where it is better to match the negative pattern or as a -last default rule. - -<p> -<table width="70%" border=0 bgcolor="#fff0f0" cellspacing=0 cellpadding=10> -<tr><td> -<b>Notice!</b> When using the NOT character to negate a pattern you cannot +<P> +<TABLE BGCOLOR="#F0F0F0" CELLSPACING=0 CELLPADDING=5> +<TR> +<TD VALIGN=TOP> +<PRE> +<STRONG>Text:</STRONG> + <STRONG><CODE>.</CODE></STRONG> Any single character + <STRONG><CODE>[</CODE></STRONG>chars<STRONG><CODE>]</CODE></STRONG> Character class: One of chars + <STRONG><CODE>[^</CODE></STRONG>chars<STRONG><CODE>]</CODE></STRONG> Character class: None of chars + text1<STRONG><CODE>|</CODE></STRONG>text2 Alternative: text1 or text2 + +<STRONG>Quantifiers:</STRONG> + <STRONG><CODE>?</CODE></STRONG> 0 or 1 of the preceding text + <STRONG><CODE>*</CODE></STRONG> 0 or N of the preceding text (N > 1) + <STRONG><CODE>+</CODE></STRONG> 1 or N of the preceding text (N > 1) + +<STRONG>Grouping:</STRONG> + <STRONG><CODE>(</CODE></STRONG>text<STRONG><CODE>)</CODE></STRONG> Grouping of text + (either to set the borders of an alternative or + for making backreferences where the <STRONG>N</STRONG>th group can + be used on the RHS of a RewriteRule with <CODE>$</CODE><STRONG>N</STRONG>) + +<STRONG>Anchors:</STRONG> + <STRONG><CODE>^</CODE></STRONG> Start of line anchor + <STRONG><CODE>$</CODE></STRONG> End of line anchor + +<STRONG>Escaping:</STRONG> + <STRONG><CODE>\</CODE></STRONG>char escape that particular char + (for instance to specify the chars "<CODE>.[]()</CODE>" <EM>etc.</EM>) +</PRE> +</TD> +</TR> +</TABLE> + +<P> +For more information about regular expressions either have a look at your +local regex(3) manpage or its <CODE>src/regex/regex.3</CODE> copy in the +Apache 1.3 distribution. When you are interested in more detailed and deeper +information about regular expressions and its variants (POSIX regex, Perl +regex, <EM>etc.</EM>) have a look at the following dedicated book on this topic: + +<BLOCKQUOTE> +<EM>Mastering Regular Expressions</EM><BR> +Jeffrey E.F. Friedl<BR> +Nutshell Handbook Series<BR> +O'Reilly & Associates, Inc. 1997<BR> +ISBN 1-56592-257-3<BR> +</BLOCKQUOTE> + +<P> +Additionally in mod_rewrite the NOT character ('<CODE>!</CODE>') is a possible +pattern prefix. This gives you the ability to negate a pattern; to say, for +instance: ``<EM>if the current URL does <STRONG>NOT</STRONG> match to this +pattern</EM>''. This can be used for special cases where it is better to match +the negative pattern or as a last default rule. + +<P> +<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> +<TR><TD> +<STRONG>Notice:</STRONG> When using the NOT character to negate a pattern you cannot have grouped wildcard parts in the pattern. This is impossible because when the pattern does NOT match, there are no contents for the groups. In -consequence, if negated patterns are used, you cannot use <tt>$N</tt> in the +consequence, if negated patterns are used, you cannot use <CODE>$N</CODE> in the substitution string! -</td></tr> -</table> +</TD></TR> +</TABLE> -<p> -<a name="rhs"><em>Substitution</em></a> of a rewriting rule is the string +<P> +<A NAME="rhs"><EM>Substitution</EM></A> of a rewriting rule is the string which is substituted for (or replaces) the original URL for which -<em>Pattern</em> matched. Beside plain text you can use - -<ol> -<li>pattern-group back-references (<code>$N</code>) -<li>server-variables as in rule condition test-strings (<code>%{VARNAME}</code>) -<li><a href="#mapfunc">mapping-function</a> calls (<code>${mapname:key|default}</code>) -</ol> - -Back-references are <code>$</code><b>N</b> (<b>N</b>=1..9) identifiers which -will be replaced by the contents of the <b>N</b>th group of the matched -<em>Pattern</em>. The server-variables are the same as for the -<em>TestString</em> of a <tt>RewriteCond</tt> directive. The -mapping-functions come from the <tt>RewriteMap</tt> directive and are +<EM>Pattern</EM> matched. Beside plain text you can use + +<OL> +<LI>back-references <CODE>$N</CODE> to the RewriteRule pattern +<LI>back-references <CODE>%N</CODE> to the last matched RewriteCond pattern +<LI>server-variables as in rule condition test-strings (<CODE>%{VARNAME}</CODE>) +<LI><A HREF="#mapfunc">mapping-function</A> calls (<CODE>${mapname:key|default}</CODE>) +</OL> + +Back-references are <CODE>$</CODE><STRONG>N</STRONG> (<STRONG>N</STRONG>=1..9) identifiers which +will be replaced by the contents of the <STRONG>N</STRONG>th group of the matched +<EM>Pattern</EM>. The server-variables are the same as for the +<EM>TestString</EM> of a <CODE>RewriteCond</CODE> directive. The +mapping-functions come from the <CODE>RewriteMap</CODE> directive and are explained there. These three types of variables are expanded in the order of the above list. -<p> +<P> As already mentioned above, all the rewriting rules are applied to the -<em>Substitution</em> (in the order of definition in the config file). The -URL is <b>completely replaced</b> by the <em>Substitution</em> and the +<EM>Substitution</EM> (in the order of definition in the config file). The +URL is <STRONG>completely replaced</STRONG> by the <EM>Substitution</EM> and the rewriting process goes on until there are no more rules (unless explicitly -terminated by a <code><b>L</b></code> flag - see below). +terminated by a <CODE><STRONG>L</STRONG></CODE> flag - see below). -<p> -There is a special substitution string named '<tt>-</tt>' which means: -<b>NO substitution</b>! Sounds silly? No, it is useful to provide rewriting -rules which <b>only</b> match some URLs but do no substitution, e.g. in -conjunction with the <b>C</b> (chain) flag to be able to have more than one +<P> +There is a special substitution string named '<CODE>-</CODE>' which means: +<STRONG>NO substitution</STRONG>! Sounds silly? No, it is useful to provide rewriting +rules which <STRONG>only</STRONG> match some URLs but do no substitution, <EM>e.g.</EM>, in +conjunction with the <STRONG>C</STRONG> (chain) flag to be able to have more than one pattern to be applied before a substitution occurs. -<p> +<P> One more note: You can even create URLs in the substitution string containing a query string part. Just use a question mark inside the substitution string to indicate that the following stuff should be re-injected into the QUERY_STRING. When you want to erase an existing query string, end the substitution string with just the question mark. -<p> -<table width="70%" border=0 bgcolor="#fff0f0" cellspacing=0 cellpadding=10> -<tr><td> -<b>Notice</b>: There is a special feature. When you prefix a substitution -field with <tt>http://</tt><em>thishost</em>[<em>:thisport</em>] then -<b>mod_rewrite</b> automatically strips it out. This auto-reduction on +<P> +<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> +<TR><TD> +<STRONG>Notice</STRONG>: There is a special feature. When you prefix a substitution +field with <CODE>http://</CODE><EM>thishost</EM>[<EM>:thisport</EM>] then +<STRONG>mod_rewrite</STRONG> automatically strips it out. This auto-reduction on implicit external redirect URLs is a useful and important feature when used in combination with a mapping-function which generates the hostname part. Have a look at the first example in the example section below to understand this. -<p> -<b>Remember:</b> An unconditional external redirect to your own server will -not work with the prefix <tt>http://thishost</tt> because of this feature. -To achieve such a self-redirect, you have to use the <b>R</b>-flag (see +</TD></TR> +</TABLE> + +<P> +<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> +<TR><TD> +<STRONG>Remember:</STRONG> An unconditional external redirect to your own server will +not work with the prefix <CODE>http://thishost</CODE> because of this feature. +To achieve such a self-redirect, you have to use the <STRONG>R</STRONG>-flag (see below). -</td></tr> -</table> +</TD></TR> +</TABLE> -<p> -Additionally you can set special flags for <em>Substitution</em> by appending +<P> +Additionally you can set special flags for <EM>Substitution</EM> by appending -<blockquote><strong> -<code>[</code><em>flags</em><code>]</code> -</strong></blockquote> +<BLOCKQUOTE><STRONG> +<CODE>[</CODE><EM>flags</EM><CODE>]</CODE> +</STRONG></BLOCKQUOTE> -as the third argument to the <tt>RewriteRule</tt> directive. <em>Flags</em> is a +as the third argument to the <CODE>RewriteRule</CODE> directive. <EM>Flags</EM> is a comma-separated list of the following flags: -<ul> -<li>'<strong><code>redirect|R</code>[=<i>code</i>]</strong>' (force <a name="redirect"><b>r</b>edirect</a>)<br> - Prefix <em>Substitution</em> - with <code>http://thishost[:thisport]/</code> (which makes the new URL a URI) to - force a external redirection. If no <i>code</i> is given a HTTP response +<UL> +<LI>'<STRONG><CODE>redirect|R</CODE> [=<EM>code</EM>]</STRONG>' (force <A NAME="redirect"><STRONG>r</STRONG>edirect</A>)<BR> + Prefix <EM>Substitution</EM> + with <CODE>http://thishost[:thisport]/</CODE> (which makes the new URL a URI) to + force a external redirection. If no <EM>code</EM> is given a HTTP response of 302 (MOVED TEMPORARILY) is used. If you want to use other response codes in the range 300-400 just specify them as a number or use - one of the following symbolic names: <tt>temp</tt> (default), <tt>permanent</tt>, - <tt>seeother</tt>. + one of the following symbolic names: <CODE>temp</CODE> (default), <CODE>permanent</CODE>, + <CODE>seeother</CODE>. Use it for rules which should - canonicalize the URL and gives it back to the client, e.g. translate - ``<code>/~</code>'' into ``<code>/u/</code>'' or always append a slash to - <code>/u/</code><em>user</em>, etc.<br> - <p> - <b>Notice:</b> When you use this flag, make sure that the + canonicalize the URL and gives it back to the client, <EM>e.g.</EM>, translate + ``<CODE>/~</CODE>'' into ``<CODE>/u/</CODE>'' or always append a slash to + <CODE>/u/</CODE><EM>user</EM>, etc.<BR> + <P> + <STRONG>Notice:</STRONG> When you use this flag, make sure that the substitution field is a valid URL! If not, you are redirecting to an invalid location! And remember that this flag itself only prefixes the - URL with <code>http://thishost[:thisport]/</code>, but rewriting goes on. + URL with <CODE>http://thishost[:thisport]/</CODE>, but rewriting goes on. Usually you also want to stop and do the redirection immediately. To stop the rewriting you also have to provide the 'L' flag. -<p> -<li>'<strong><code>forbidden|F</code></strong>' (force URL to be <b>f</b>orbidden)<br> - This forces the current URL to be forbidden, i.e. it immediately sends +<P> +<LI>'<STRONG><CODE>forbidden|F</CODE></STRONG>' (force URL to be <STRONG>f</STRONG>orbidden)<BR> + This forces the current URL to be forbidden, <EM>i.e.</EM>, it immediately sends back a HTTP response of 403 (FORBIDDEN). Use this flag in conjunction with appropriate RewriteConds to conditionally block some URLs. -<p> -<li>'<strong><code>gone|G</code></strong>' (force URL to be <b>g</b>one)<br> - This forces the current URL to be gone, i.e. it immediately sends back a +<P> +<LI>'<STRONG><CODE>gone|G</CODE></STRONG>' (force URL to be <STRONG>g</STRONG>one)<BR> + This forces the current URL to be gone, <EM>i.e.</EM>, it immediately sends back a HTTP response of 410 (GONE). Use this flag to mark no longer existing pages as gone. -<p> -<li>'<strong><code>proxy|P</code></strong>' (force <b>p</b>roxy)<br> +<P> +<LI>'<STRONG><CODE>proxy|P</CODE></STRONG>' (force <STRONG>p</STRONG>roxy)<BR> This flag forces the substitution part to be internally forced as a proxy - request and immediately (i.e. rewriting rule processing stops here) put - through the proxy module. You have to make sure that the substitution - string is a valid URI (e.g. typically <tt>http://</tt>) which can - be handled by the Apache proxy module. If not you get an error from - the proxy module. Use this flag to achieve a more powerful implementation - of the <tt>mod_proxy</tt> directive <tt>ProxyPass</tt>, to map - some remote stuff into the namespace of the local server. - <p> - Notice: <b>You really have to put <tt>ProxyRequests On</tt> into your - server configuration to prevent proxy requests from leading to core-dumps - inside the Apache kernel. If you have not compiled in the proxy module, - then there is no core-dump problem, because mod_rewrite checks for - existence of the proxy module and if lost forbids proxy URLs. </b> -<p> -<li>'<strong><code>last|L</code></strong>' (<b>l</b>ast rule)<br> + request and immediately (<EM>i.e.</EM>, rewriting rule processing stops here) put + through the <A HREF="mod_proxy.html">proxy module</A>. You have to make + sure that the substitution string is a valid URI (<EM>e.g.</EM>, typically starting + with <CODE>http://</CODE><EM>hostname</EM>) which can be handled by the + Apache proxy module. If not you get an error from the proxy module. Use + this flag to achieve a more powerful implementation of the <A + HREF="mod_proxy.html#proxypass">ProxyPass</A> directive, to map some + remote stuff into the namespace of the local server. + <P> + Notice: To use this functionality make sure you have the proxy module + compiled into your Apache server program. If you don't know please check + whether <CODE>mod_proxy.c</CODE> is part of the ``<CODE>httpd -l</CODE>'' + output. If yes, this functionality is available to mod_rewrite. If not, + then you first have to rebuild the ``<CODE>httpd</CODE>'' program with + mod_proxy enabled. +<P> +<LI>'<STRONG><CODE>last|L</CODE></STRONG>' (<STRONG>l</STRONG>ast rule)<BR> Stop the rewriting process here and don't apply any more rewriting rules. This corresponds to the Perl - <code>last</code> command or the <code>break</code> command from the C + <CODE>last</CODE> command or the <CODE>break</CODE> command from the C language. Use this flag to prevent the currently rewritten URL from being rewritten further by following rules which may be wrong. For - example, use it to rewrite the root-path URL ('<code>/</code>') to a real - one, e.g. '<code>/e/www/</code>'. -<p> -<li>'<strong><code>next|N</code></strong>' (<b>n</b>ext round)<br> + example, use it to rewrite the root-path URL ('<CODE>/</CODE>') to a real + one, <EM>e.g.</EM>, '<CODE>/e/www/</CODE>'. +<P> +<LI>'<STRONG><CODE>next|N</CODE></STRONG>' (<STRONG>n</STRONG>ext round)<BR> Re-run the rewriting process (starting again with the first rewriting rule). Here the URL to match is again not the original URL but the URL from the last rewriting rule. This corresponds to the Perl - <code>next</code> command or the <code>continue</code> command from the C - language. Use this flag to restart the rewriting process, i.e. to - immediately go to the top of the loop. <br> - <b>But be careful not to create a deadloop!</b> -<p> -<li>'<strong><code>chain|C</code></strong>' (<b>c</b>hained with next rule)<br> + <CODE>next</CODE> command or the <CODE>continue</CODE> command from the C + language. Use this flag to restart the rewriting process, <EM>i.e.</EM>, to + immediately go to the top of the loop. <BR> + <STRONG>But be careful not to create a deadloop!</STRONG> +<P> +<LI>'<STRONG><CODE>chain|C</CODE></STRONG>' (<STRONG>c</STRONG>hained with next rule)<BR> This flag chains the current rule with the next rule (which itself can - also be chained with its following rule, etc.). This has the following - effect: if a rule matches, then processing continues as usual, i.e. the - flag has no effect. If the rule does <b>not</b> match, then all following + also be chained with its following rule, <EM>etc.</EM>). This has the following + effect: if a rule matches, then processing continues as usual, <EM>i.e.</EM>, the + flag has no effect. If the rule does <STRONG>not</STRONG> match, then all following chained rules are skipped. For instance, use it to remove the - ``<tt>.www</tt>'' part inside a per-directory rule set when you let an - external redirect happen (where the ``<tt>.www</tt>'' part should not to + ``<CODE>.www</CODE>'' part inside a per-directory rule set when you let an + external redirect happen (where the ``<CODE>.www</CODE>'' part should not to occur!). -<p> -<li>'<strong><code>type|T</code></strong>=<em>mime-type</em>' (force MIME <b>t</b>ype)<br> - Force the MIME-type of the target file to be <em>mime-type</em>. For - instance, this can be used to simulate the old <tt>mod_alias</tt> - directive <tt>ScriptAlias</tt> which internally forces all files inside +<P> +<LI>'<STRONG><CODE>type|T</CODE></STRONG>=<EM>MIME-type</EM>' (force MIME <STRONG>t</STRONG>ype)<BR> + Force the MIME-type of the target file to be <EM>MIME-type</EM>. For + instance, this can be used to simulate the <CODE>mod_alias</CODE> + directive <CODE>ScriptAlias</CODE> which internally forces all files inside the mapped directory to have a MIME type of - ``<tt>application/x-httpd-cgi</tt>''. -<p> -<li>'<strong><code>nosubreq|NS</code></strong>' (used only if <b>n</b>o internal <b>s</b>ub-request)<br> + ``<CODE>application/x-httpd-cgi</CODE>''. +<P> +<LI>'<STRONG><CODE>nosubreq|NS</CODE></STRONG>' (used only if <STRONG>n</STRONG>o internal <STRONG>s</STRONG>ub-request)<BR> This flag forces the rewriting engine to skip a rewriting rule if the current request is an internal sub-request. For instance, sub-requests - occur internally in Apache when <tt>mod_include</tt> tries to find out - information about possible directory default files (<tt>index.xxx</tt>). + occur internally in Apache when <CODE>mod_include</CODE> tries to find out + information about possible directory default files (<CODE>index.xxx</CODE>). On sub-requests it is not always useful and even sometimes causes a failure to - if the complete set of rules are applied. Use this flag to exclude some rules.<br> - <p> + if the complete set of rules are applied. Use this flag to exclude some rules.<BR> + <P> Use the following rule for your decision: whenever you prefix some URLs with CGI-scripts to force them to be processed by the CGI-script, the chance is high that you will run into problems (or even overhead) on sub-requests. In these cases, use this flag. -<p> -<li>'<strong><code>qsappend|QSA</code></strong>' (<b>q</b>uery <b>s</b>tring - <b>a</b>ppend)<br> +<P> +<LI>'<STRONG><CODE>nocase|NC</CODE></STRONG>' (<STRONG>n</STRONG>o <STRONG>c</STRONG>ase)<BR> + This makes the <EM>Pattern</EM> case-insensitive, <EM>i.e.</EM>, there is + no difference between 'A-Z' and 'a-z' when <EM>Pattern</EM> is matched + against the current URL. +<P> +<LI>'<STRONG><CODE>qsappend|QSA</CODE></STRONG>' (<STRONG>q</STRONG>uery <STRONG>s</STRONG>tring + <STRONG>a</STRONG>ppend)<BR> This flag forces the rewriting engine to append a query string part in the substitution string to the existing one instead of replacing it. Use this when you want to add more data to the query string via a rewrite rule. -<p> -<li>'<strong><code>passthrough|PT</code></strong>' (<b>p</b>ass <b>t</b>hrough to next handler)<br> - This flag forces the rewriting engine to set the <code>uri</code> field - of the internal <code>request_rec</code> structure to the value - of the <code>filename</code> field. This flag is just a hack to be able - to post-process the output of <tt>RewriteRule</tt> directives by - <tt>Alias</tt>, <tt>ScriptAlias</tt>, <tt>Redirect</tt>, etc. directives +<P> +<LI>'<STRONG><CODE>passthrough|PT</CODE></STRONG>' (<STRONG>p</STRONG>ass <STRONG>t</STRONG>hrough to next handler)<BR> + This flag forces the rewriting engine to set the <CODE>uri</CODE> field + of the internal <CODE>request_rec</CODE> structure to the value + of the <CODE>filename</CODE> field. This flag is just a hack to be able + to post-process the output of <CODE>RewriteRule</CODE> directives by + <CODE>Alias</CODE>, <CODE>ScriptAlias</CODE>, <CODE>Redirect</CODE>, <EM>etc.</EM> directives from other URI-to-filename translators. A trivial example to show the semantics: - If you want to rewrite <tt>/abc</tt> to <tt>/def</tt> via the rewriting - engine of <tt>mod_rewrite</tt> and then <tt>/def</tt> to <tt>/ghi</tt> - with <tt>mod_alias</tt>: - <pre> + If you want to rewrite <CODE>/abc</CODE> to <CODE>/def</CODE> via the rewriting + engine of <CODE>mod_rewrite</CODE> and then <CODE>/def</CODE> to <CODE>/ghi</CODE> + with <CODE>mod_alias</CODE>: + <PRE> RewriteRule ^/abc(.*) /def$1 [PT] Alias /def /ghi - </pre> - If you omit the <tt>PT</tt> flag then <tt>mod_rewrite</tt> - will do its job fine, i.e. it rewrites <tt>uri=/abc/...</tt> to - <tt>filename=/def/...</tt> as a full API-compliant URI-to-filename - translator should do. Then <tt>mod_alias</tt> comes and tries to do a + </PRE> + If you omit the <CODE>PT</CODE> flag then <CODE>mod_rewrite</CODE> + will do its job fine, <EM>i.e.</EM>, it rewrites <CODE>uri=/abc/...</CODE> to + <CODE>filename=/def/...</CODE> as a full API-compliant URI-to-filename + translator should do. Then <CODE>mod_alias</CODE> comes and tries to do a URI-to-filename transition which will not work. - <p> - Notice: <b>You have to use this flag if you want to intermix directives - of different modules which contain URL-to-filename translators</b>. The - typical example is the use of <tt>mod_alias</tt> and - <tt>mod_rewrite</tt>.. -<p> -<table width="70%" border=0 bgcolor="#fff0f0" cellspacing=0 cellpadding=10> -<tr><td> + <P> + Notice: <STRONG>You have to use this flag if you want to intermix directives + of different modules which contain URL-to-filename translators</STRONG>. The + typical example is the use of <CODE>mod_alias</CODE> and + <CODE>mod_rewrite</CODE>.. +<P> +<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> +<TR><TD> <font size=-1> - <b>For the Apache hackers:</b><br> + <STRONG>Notice - For the Apache hackers:</STRONG><BR> If the current Apache API had a filename-to-filename hook additionally to the URI-to-filename hook then we wouldn't need this flag! But without such a hook this flag is the only solution. The Apache Group has discussed this problem and will add such hooks into Apache version 2.0. -</font> -</td></tr> -</table> -<p> -<li>'<strong><code>skip|S</code></strong>=<em>num</em>' (<b>s</b>kip next rule(s))<br> - This flag forces the rewriting engine to skip the next <em>num</em> rules +</FONT> +</TD></TR> +</TABLE> +<P> +<LI>'<STRONG><CODE>skip|S</CODE></STRONG>=<EM>num</EM>' (<STRONG>s</STRONG>kip next rule(s))<BR> + This flag forces the rewriting engine to skip the next <EM>num</EM> rules in sequence when the current rule matches. Use this to make pseudo if-then-else constructs: The last rule of the then-clause becomes - a <tt>skip=N</tt> where N is the number of rules in the else-clause. - (This is <b>not</b> the same as the 'chain|C' flag!) -<p> -<li>'<strong><code>env|E=</code></strong><i>VAR</i>:<i>VAL</i>' (set <b>e</b>nvironment variable)<br> - This forces an environment variable named <i>VAR</i> to be set to the value - <i>VAL</i>, where <i>VAL</i> can contain regexp backreferences <tt>$N</tt> - which will be expanded. You can use this flag more than once to set more - than one variable. The variables can be later dereferenced at a lot of - situations, but the usual location will be from within XSSI (via - <tt><!--#echo var="VAR"--></tt>) or CGI (e.g. <tt>$ENV{'VAR'}</tt>). - But additionally you can also dereference it in a following RewriteCond - pattern via <tt>%{ENV:VAR}</tt>. Use this to strip but remember - information from URLs. -</ul> - -<p> -<table width="70%" border=0 bgcolor="#fff0f0" cellspacing=0 cellpadding=10> -<tr><td> -Remember: Never forget that <em>Pattern</em> gets applied to a complete URL -in per-server configuration files. <b>But in per-directory configuration + a <CODE>skip=N</CODE> where N is the number of rules in the else-clause. + (This is <STRONG>not</STRONG> the same as the 'chain|C' flag!) +<P> +<LI>'<STRONG><CODE>env|E=</CODE></STRONG><EM>VAR</EM>:<EM>VAL</EM>' (set <STRONG>e</STRONG>nvironment variable)<BR> + This forces an environment variable named <EM>VAR</EM> to be set to the + value <EM>VAL</EM>, where <EM>VAL</EM> can contain regexp backreferences + <CODE>$N</CODE> and <CODE>%N</CODE> which will be expanded. You can use this flag + more than once to set more than one variable. The variables can be later + dereferenced at a lot of situations, but the usual location will be from + within XSSI (via <CODE><!--#echo var="VAR"--></CODE>) or CGI (<EM>e.g.</EM> + <CODE>$ENV{'VAR'}</CODE>). But additionally you can also dereference it in a + following RewriteCond pattern via <CODE>%{ENV:VAR}</CODE>. Use this to strip + but remember information from URLs. +</UL> + +<P> +<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> +<TR><TD> +<STRONG>Notice:</STRONG> Never forget that <EM>Pattern</EM> gets applied to a complete URL +in per-server configuration files. <STRONG>But in per-directory configuration files, the per-directory prefix (which always is the same for a specific -directory!) gets automatically <em>removed</em> for the pattern matching and -automatically <em>added</em> after the substitution has been done.</b> This feature is +directory!) gets automatically <EM>removed</EM> for the pattern matching and +automatically <EM>added</EM> after the substitution has been done.</STRONG> This feature is essential for many sorts of rewriting, because without this prefix stripping you have to match the parent directory which is not always possible. -<p> +<P> There is one exception: If a substitution string starts with -``<tt>http://</tt>'' then the directory prefix will be <b>not</b> added and a -external redirect or proxy throughput (if flag <b>P</b> is used!) is forced! -</td></tr> -</table> - -<p> -<table width="70%" border=0 bgcolor="#fff0f0" cellspacing=0 cellpadding=10> -<tr><td> -Notice! To enable the rewriting engine for per-directory configuration files -you need to set ``<tt>RewriteEngine On</tt>'' in these files <b>and</b> -``<tt>Option FollowSymLinks</tt>'' enabled. If your administrator has -disabled override of <tt>FollowSymLinks</tt> for a user's directory, then +``<CODE>http://</CODE>'' then the directory prefix will be <STRONG>not</STRONG> added and a +external redirect or proxy throughput (if flag <STRONG>P</STRONG> is used!) is forced! +</TD></TR> +</TABLE> + +<P> +<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> +<TR><TD> +<STRONG>Notice:</STRONG> To enable the rewriting engine for per-directory configuration files +you need to set ``<CODE>RewriteEngine On</CODE>'' in these files <STRONG>and</STRONG> +``<CODE>Option FollowSymLinks</CODE>'' enabled. If your administrator has +disabled override of <CODE>FollowSymLinks</CODE> for a user's directory, then you cannot use the rewriting engine. This restriction is needed for security reasons. -</td></tr> -</table> +</TD></TR> +</TABLE> -<p> +<P> Here are all possible substitution combinations and their meanings: -<p> -<b>Inside per-server configuration (<tt>httpd.conf</tt>)<br> -for request ``<tt>GET /somepath/pathinfo</tt>'':</b><br> +<P> +<STRONG>Inside per-server configuration (<CODE>httpd.conf</CODE>)<BR> +for request ``<CODE>GET /somepath/pathinfo</CODE>'':</STRONG><BR> -<p> -<table bgcolor="#f0f0f0" cellspacing=0 cellpadding=5> -<tr> -<td> -<pre> -<b>Given Rule</b> <b>Resulting Substitution</b> +<P> +<TABLE BGCOLOR="#F0F0F0" CELLSPACING=0 CELLPADDING=5> +<TR> +<TD> +<PRE> +<STRONG>Given Rule</STRONG> <STRONG>Resulting Substitution</STRONG> ---------------------------------------------- ---------------------------------- ^/somepath(.*) otherpath$1 not supported, because invalid! @@ -1094,23 +1737,23 @@ for request ``<tt>GET /somepath/pathinfo</tt>'':</b><br> ^/somepath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo via internal proxy -</pre> -</td> -</tr> -</table> - -<p> -<b>Inside per-directory configuration for <tt>/somepath</tt><br> -(i.e. file <tt>.htaccess</tt> in dir <tt>/physical/path/to/somepath</tt> containing -<tt>RewriteBase /somepath</tt>)<br> for -request ``<tt>GET /somepath/localpath/pathinfo</tt>'':</b><br> - -<p> -<table bgcolor="#f0f0f0" cellspacing=0 cellpadding=5> -<tr> -<td> -<pre> -<b>Given Rule</b> <b>Resulting Substitution</b> +</PRE> +</TD> +</TR> +</TABLE> + +<P> +<STRONG>Inside per-directory configuration for <CODE>/somepath</CODE><BR> +(<EM>i.e.</EM>, file <CODE>.htaccess</CODE> in dir <CODE>/physical/path/to/somepath</CODE> containing +<CODE>RewriteBase /somepath</CODE>)<BR> for +request ``<CODE>GET /somepath/localpath/pathinfo</CODE>'':</STRONG><BR> + +<P> +<TABLE BGCOLOR="#F0F0F0" CELLSPACING=0 CELLPADDING=5> +<TR> +<TD> +<PRE> +<STRONG>Given Rule</STRONG> <STRONG>Resulting Substitution</STRONG> ---------------------------------------------- ---------------------------------- ^localpath(.*) otherpath$1 /somepath/otherpath/pathinfo @@ -1142,90 +1785,103 @@ request ``<tt>GET /somepath/localpath/pathinfo</tt>'':</b><br> ^localpath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo via internal proxy -</pre> -</td> -</tr> -</table> - - -<p> -<b>Example:</b> -<p> -<blockquote> +</PRE> +</TD> +</TR> +</TABLE> + +<P> +<STRONG>Example:</STRONG> +<P> +<BLOCKQUOTE> We want to rewrite URLs of the form -<blockquote> -<code>/</code> <em>Language</em> -<code>/~</code> <em>Realname</em> -<code>/.../</code> <em>File</em> -</blockquote> +<BLOCKQUOTE> +<CODE>/</CODE> <EM>Language</EM> +<CODE>/~</CODE> <EM>Realname</EM> +<CODE>/.../</CODE> <EM>File</EM> +</BLOCKQUOTE> into -<blockquote> -<code>/u/</code> <em>Username</em> -<code>/.../</code> <em>File</em> -<code>.</code> <em>Language</em> -</blockquote> -<p> +<BLOCKQUOTE> +<CODE>/u/</CODE> <EM>Username</EM> +<CODE>/.../</CODE> <EM>File</EM> +<CODE>.</CODE> <EM>Language</EM> +</BLOCKQUOTE> +<P> We take the rewrite mapfile from above and save it under -<code>/anywhere/map.real-to-user</code>. Then we only have to add the +<CODE>/path/to/file/map.txt</CODE>. Then we only have to add the following lines to the Apache server configuration file: -<blockquote> -<pre> -RewriteLog /anywhere/rewrite.log -RewriteMap real-to-user txt:/anywhere/map.real-to-host +<BLOCKQUOTE> +<PRE> +RewriteLog /path/to/file/rewrite.log +RewriteMap real-to-user txt:/path/to/file/map.txt RewriteRule ^/([^/]+)/~([^/]+)/(.*)$ /u/${real-to-user:$2|nobody}/$3.$1 -</pre> -</blockquote> -</blockquote> +</PRE> +</BLOCKQUOTE> +</BLOCKQUOTE> -<!--%hypertext --> -<hr> -<!--/%hypertext --> +<P> +<HR NOSHADE SIZE=1> -<center> -<a name="Additional"> -<h1>Additional Features</h1> -</a> -</center> +<CENTER> +<H1><A NAME="Miscelleneous">Miscellaneous</A></H1> +</CENTER> -<a name="EnvVar"> -<h2>Environment Variables</h2> -</a> +<P> +<HR NOSHADE SIZE=1> + +<H2><A NAME="EnvVar">Environment Variables</A></H2> This module keeps track of two additional (non-standard) CGI/SSI environment -variables named <tt>SCRIPT_URL</tt> and <tt>SCRIPT_URI</tt>. These contain -the <em>logical</em> Web-view to the current resource, while the standard CGI/SSI -variables <tt>SCRIPT_NAME</tt> and <tt>SCRIPT_FILENAME</tt> contain the -<em>physical</em> System-view. - -<p> -Notice: These variables hold the URI/URL <em>as they were initially -requested</em>, i.e. in a state <em>before</em> any rewriting. This is +variables named <CODE>SCRIPT_URL</CODE> and <CODE>SCRIPT_URI</CODE>. These contain +the <EM>logical</EM> Web-view to the current resource, while the standard CGI/SSI +variables <CODE>SCRIPT_NAME</CODE> and <CODE>SCRIPT_FILENAME</CODE> contain the +<EM>physical</EM> System-view. + +<P> +Notice: These variables hold the URI/URL <EM>as they were initially +requested</EM>, <EM>i.e.</EM>, in a state <EM>before</EM> any rewriting. This is important because the rewriting process is primarily used to rewrite logical URLs to physical pathnames. -<p> -<b>Example:</b> +<P> +<STRONG>Example:</STRONG> -<blockquote> -<pre> -SCRIPT_NAME=/v/sw/free/lib/apache/global/u/rse/.www/index.html +<BLOCKQUOTE> +<PRE> +SCRIPT_NAME=/sw/lib/w3s/tree/global/u/rse/.www/index.html SCRIPT_FILENAME=/u/rse/.www/index.html SCRIPT_URL=/u/rse/ -SCRIPT_URI=http://en2.en.sdm.de/u/rse/ -</pre> -</blockquote> +SCRIPT_URI=http://en1.engelschall.com/u/rse/ +</PRE> +</BLOCKQUOTE> + +<P> +<HR NOSHADE SIZE=1> +<H2><A NAME="Solutions">Practical Solutions</A></H2> + +There is a comprehensive collection of practical solutions for URL-based +problems available by the author of mod_rewrite. Here you will find real-life +rulesets and additional information. + +<BLOCKQUOTE> +<STRONG>Apache URL Rewriting Guide</STRONG><BR> +<STRONG><A HREF="http://www.engelschall.com/pw/apache/rewriteguide/" + >http://www.engelschall.com/pw/apache/rewriteguide/</A></STRONG> +</BLOCKQUOTE> <HR> + <H3 ALIGN="CENTER"> - Apache HTTP Server Version 1.2 + Apache HTTP Server Version 1.3 </H3> <A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> <A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> +</BLOCKQUOTE><!-- page indentation --> </BODY> </HTML> <!--/%hypertext --> diff --git a/usr.sbin/httpd/htdocs/manual/new_features_1_3.html b/usr.sbin/httpd/htdocs/manual/new_features_1_3.html index 0963caa9d90..2b3c0d6a135 100644 --- a/usr.sbin/httpd/htdocs/manual/new_features_1_3.html +++ b/usr.sbin/httpd/htdocs/manual/new_features_1_3.html @@ -131,6 +131,24 @@ documentation</A> for more information. <H2><A NAME="config">Configuration Enhancements</A></H2> <DL> +<DT><STRONG>Unified Server Configuration Files</STRONG></DT> +<DD><EM>(Apache 1.3.4)</EM> The contents of the three + server configuration files (<SAMP>httpd.conf</SAMP>, + <SAMP>srm.conf</SAMP>, and <SAMP>access.conf</SAMP>) have + been merged into a single <SAMP>httpd.conf</SAMP> file. + The <SAMP>srm.conf</SAMP> and <SAMP>access.conf</SAMP> files + are now empty except for comments directing the Webmaster + to look in <SAMP>httpd.conf</SAMP>. In addition, the + merged <SAMP>httpd.conf</SAMP> file has been restructured + to allow directives to appear in a hopefully more + intuitive and meaningful order. +</DD> +<DT><STRONG>Continuation Lines in config files</STRONG></DT> +<DD>Directive lines in the server configuration files may now be + split onto multiple lines by using the canonical Unix continuation + mechanism, namely a '\' as the last non-blank character on the + line to indicate that the next line should be concatenated. +</DD> <DT><STRONG>Apache Autoconf-style Interface (APACI)</STRONG> <DD>Until Apache 1.3 there was no real out-of-the-box batch-capable build and installation procedure for the complete Apache @@ -141,7 +159,10 @@ documentation</A> for more information. <CODE>src/Configure</CODE> stuff in batch and additionally installs the package with a GNU-conforming directory layout. Any options from the old configuration scheme are available plus a lot - of new options for flexibly customizing Apache. + of new options for flexibly customizing Apache.<BR> + <STRONG>Note:</STRONG> The default installation layout has changed + for Apache 1.3.4. See the files <CODE>README.configure</CODE> and + <CODE>INSTALL</CODE> for more information. <DT><STRONG>APache eXtenSion (APXS) support tool</STRONG> <DD>Now that Apache provides full support for loading modules under @@ -193,6 +214,13 @@ documentation</A> for more information. <H3><A NAME="mod">Module Enhancements</A></H3> <DL> +<DT><A HREF="mod/mod_negotiation.html"><STRONG>Improved mod_negotiation + </STRONG></A><BR> +<DD>The optional content negotiation (MultiViews) module has been completely + overhauled for Apache 1.3.4, incorporating the latest HTTP/1.1 + revisions and the experimental Transparent Content Negotion features + of RFC 2295 and RFC 2296. + <DT><A HREF="mod/mod_speling.html"><STRONG>NEW - Spelling correction module</STRONG></A><BR> <DD>This optional module corrects frequently occurring spelling and diff --git a/usr.sbin/httpd/htdocs/manual/stopping.html b/usr.sbin/httpd/htdocs/manual/stopping.html index 1db5e588609..e5200a31da9 100644 --- a/usr.sbin/httpd/htdocs/manual/stopping.html +++ b/usr.sbin/httpd/htdocs/manual/stopping.html @@ -15,106 +15,118 @@ <DIV ALIGN="CENTER"> <IMG SRC="images/sub.gif" ALT="[APACHE DOCUMENTATION]"> <H3> - Apache HTTP Server Version 1.2 + Apache HTTP Server Version 1.3 </H3> </DIV> -<h1 ALIGN="CENTER">Stopping and Restarting Apache</h1> +<H1 ALIGN="CENTER">Stopping and Restarting Apache</H1> -<p>You will notice many <code>httpd</code> executables running on your system, +<P>This document covers stopping and restarting Apache on Unix +only. Windows users should see <A HREF="windows.html#signal">Signalling +Apache when running</A>.</P> + +<P>You will notice many <CODE>httpd</CODE> executables running on your system, but you should not send signals to any of them except the parent, whose -pid is in the <a href="mod/core.html#pidfile">PidFile</a>. That is to +pid is in the <A HREF="mod/core.html#pidfile">PidFile</A>. 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: -<code>TERM</code>, <code>HUP</code>, and <code>USR1</code>, which will +<CODE>TERM</CODE>, <CODE>HUP</CODE>, and <CODE>USR1</CODE>, which will be described in a moment. -<p>To send a signal to the parent you should issue a command such as: -<blockquote><pre> - kill -TERM `cat /usr/local/etc/httpd/logs/httpd.pid` -</pre></blockquote> +<P>To send a signal to the parent you should issue a command such as: +<BLOCKQUOTE><PRE> + kill -TERM `cat /usr/local/apache/logs/httpd.pid` +</PRE></BLOCKQUOTE> You can read about its progress by issuing: -<blockquote><pre> - tail -f /usr/local/etc/httpd/logs/error_log -</pre></blockquote> +<BLOCKQUOTE><PRE> + tail -f /usr/local/apache/logs/error_log +</PRE></BLOCKQUOTE> Modify those examples to match your -<a href="mod/core.html#serverroot">ServerRoot</a> and -<a href="mod/core.html#pidfile">PidFile</a> settings. +<A HREF="mod/core.html#serverroot">ServerRoot</A> and +<A HREF="mod/core.html#pidfile">PidFile</A> settings. + +<P>As of Apache 1.3 we provide a script <CODE>src/support/apachectl</CODE> +which can be used to start, stop, and restart Apache. It may need a +little customization for your system, see the comments at the top of +the script. -<h3>TERM Signal: stop now</h3> +<H3>TERM Signal: stop now</H3> -<p>Sending the <code>TERM</code> signal to the parent causes it to +<P>Sending the <CODE>TERM</CODE> 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. -<h3>HUP Signal: restart now</h3> +<H3>HUP Signal: restart now</H3> -<p>Sending the <code>HUP</code> signal to the parent causes it to kill off -its children like in <code>TERM</code> but the parent doesn't exit. It +<P>Sending the <CODE>HUP</CODE> signal to the parent causes it to kill off +its children like in <CODE>TERM</CODE> 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. -<p>Users of the -<a href="mod/mod_status.html">status module</a> +<P>Users of the +<A HREF="mod/mod_status.html">status module</A> will notice that the server statistics are -set to zero when a <code>HUP</code> is sent. +set to zero when a <CODE>HUP</CODE> is sent. -<p><b>Note:</b> If your configuration file has errors in it when you issue a +<P><STRONG>Note:</STRONG> 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. -<h3>USR1 Signal: graceful restart</h3> +<H3>USR1 Signal: graceful restart</H3> -<p><b>Note:</b> prior to release 1.2b9 this code is quite unstable and -shouldn't be used at all. +<P><STRONG>Note:</STRONG> prior to release 1.2b9 this code is quite unstable +and shouldn't be used at all. -<p>The <code>USR1</code> signal causes the parent process to <i>advise</i> +<P>The <CODE>USR1</CODE> signal causes the parent process to <EM>advise</EM> 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 <i>generation</i> of the +replaces it with a child from the new <EM>generation</EM> of the configuration, which begins serving new requests immediately. -<p>This code is designed to always respect the -<a href="mod/core.html#maxclients">MaxClients</a>, -<a href="mod/core.html#minspareservers">MinSpareServers</a>, -and <a href="mod/core.html#maxspareservers">MaxSpareServers</a> settings. -Furthermore, it respects <a href="mod/core.html#startservers">StartServers</a> +<P>This code is designed to always respect the +<A HREF="mod/core.html#maxclients">MaxClients</A>, +<A HREF="mod/core.html#minspareservers">MinSpareServers</A>, +and <A HREF="mod/core.html#maxspareservers">MaxSpareServers</A> settings. +Furthermore, it respects <A HREF="mod/core.html#startservers">StartServers</A> 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. -<p>Users of the -<a href="mod/mod_status.html">status module</a> +<P>Users of the +<A HREF="mod/mod_status.html">status module</A> will notice that the server statistics -are <b>not</b> set to zero when a <code>USR1</code> is sent. The code +are <STRONG>not</STRONG> set to zero when a <CODE>USR1</CODE> 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 <i>scoreboard</i> used to keep track +to do this it has to keep the <EM>scoreboard</EM> used to keep track of all children across generations. -<p>The status module will also use a <code>G</code> to indicate those +<P>The status module will also use a <CODE>G</CODE> to indicate those children which are still serving requests started before the graceful restart was given. -<p>At present there is no way for a log rotation script using -<code>USR1</code> to know for certain that all children writing the +<P>At present there is no way for a log rotation script using +<CODE>USR1</CODE> 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 <code>USR1</code> signal before you do anything with the +after sending the <CODE>USR1</CODE> 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. -<p><b>Note:</b> If your configuration file has errors in it when you issue a +<P><STRONG>Note:</STRONG> 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 @@ -128,9 +140,9 @@ 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. -<h3>Appendix: signals and race conditions</h3> +<H3>Appendix: signals and race conditions</H3> -<p>Prior to Apache 1.2b9 there were several <i>race conditions</i> +<P>Prior to Apache 1.2b9 there were several <EM>race conditions</EM> 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 @@ -138,11 +150,11 @@ have the "right" feature set we have eliminated as many as we can. But it should be noted that there still do exist race conditions on certain architectures. -<p>Architectures that use an on disk -<a href="mod/core.html#scoreboardfile">ScoreBoardFile</a> +<P>Architectures that use an on disk +<A HREF="mod/core.html#scoreboardfile">ScoreBoardFile</A> have the potential to corrupt their scoreboards. This can result in -the "bind: Address already in use" (after <code>HUP</code>) or -"long lost child came home!" (after <code>USR1</code>). The former is +the "bind: Address already in use" (after <CODE>HUP</CODE>) or +"long lost child came home!" (after <CODE>USR1</CODE>). 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 @@ -150,13 +162,13 @@ around, but fortunately most architectures do not require a scoreboard file. See the ScoreBoardFile documentation for a method to determine if your architecture uses it. -<p><code>NEXT</code> and <code>MACHTEN</code> (68k only) have small race +<P><CODE>NEXT</CODE> and <CODE>MACHTEN</CODE> (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. <!-- they don't have sigaction, or we're not using it -djg --> -<p>All architectures have a small race condition in each child involving +<P>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 @@ -168,9 +180,9 @@ clients successfully browsed the site without getting broken images or empty documents. <HR> -<H3 ALIGN="CENTER"> - Apache HTTP Server Version 1.2 -</H3> + <H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 + </H3> <A HREF="./"><IMG SRC="images/index.gif" ALT="Index"></A> diff --git a/usr.sbin/httpd/htdocs/manual/suexec.html b/usr.sbin/httpd/htdocs/manual/suexec.html index fb77589b83b..7be9878127e 100644 --- a/usr.sbin/httpd/htdocs/manual/suexec.html +++ b/usr.sbin/httpd/htdocs/manual/suexec.html @@ -14,7 +14,7 @@ <DIV ALIGN="CENTER"> <IMG SRC="images/sub.gif" ALT="[APACHE DOCUMENTATION]"> <H3> - Apache HTTP Server Version 1.2 + Apache HTTP Server Version 1.3 </H3> </DIV> @@ -23,15 +23,16 @@ <P ALIGN="LEFT"> <OL> - <LH><BIG><STRONG>CONTENTS</STRONG></BIG></LH> + <LI><BIG><STRONG>CONTENTS</STRONG></BIG></LI> <LI><A HREF="#what">What is suEXEC?</A></LI> <LI><A HREF="#before">Before we begin.</A></LI> <LI><A HREF="#model">suEXEC Security Model.</A></LI> <LI><A HREF="#install">Configuring & Installing suEXEC</A></LI> <LI><A HREF="#enable">Enabling & Disabling suEXEC</A></LI> + <LI><A HREF="#usage">Using suEXEC</A></LI> <LI><A HREF="#debug">Debugging suEXEC</A></LI> <LI><A HREF="#jabberwock">Beware the Jabberwock: Warnings & - Examples</A></LI> + Examples</A></LI> </OL> </P> @@ -49,9 +50,9 @@ 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 +with managing setuid root programs and the security issues they present, we highly recommend that you not consider using suEXEC. -</P> +</P> <P ALIGN="CENTER"> <STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> @@ -71,7 +72,7 @@ capable of supporting suEXEC, may differ in their configuration. </P> <P ALIGN="LEFT"> -Second, it is assumed you are familiar with some basic concepts of your +Second, it is assumed you are familiar with some basic concepts of your computer's security and its administration. This involves an understanding of <STRONG>setuid/setgid</STRONG> operations and the various effects they may have on your system and its level of security. @@ -80,21 +81,25 @@ may have on your system and its level of security. <P ALIGN="LEFT"> Third, it is assumed that you are using an <STRONG>unmodified</STRONG> 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 -<STRONG>highly</STRONG> recommended you not alter the suEXEC code unless you +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 +<STRONG>highly</STRONG> 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. </P> <P ALIGN="LEFT"> -Fourth, and last, it has been the decision of the Apache Group to +Fourth, and last, it has been the decision of the Apache Group to <STRONG>NOT</STRONG> make suEXEC part of the default installation of Apache. -To this end, suEXEC configuration is a manual process requiring of the -administrator careful attention to details. It is through this process -that the Apache Group hopes to limit suEXEC installation only to those -who are determined to use it. +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. </P> <P ALIGN="LEFT"> @@ -118,7 +123,7 @@ are taken to ensure your system's security. 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 +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. </P> @@ -126,124 +131,150 @@ 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: - <OL> - <LI><STRONG>Was the wrapper called with the proper number of arguments?</STRONG> - <BLOCKQUOTE> - 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. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the user executing this wrapper a valid user of this system?</STRONG> - <BLOCKQUOTE> - This is to ensure that the user executing the wrapper is truly a user of the system. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is this valid user allowed to run the wrapper?</STRONG> - <BLOCKQUOTE> - Is this user the user allowed to run this wrapper? Only one user (the Apache - user) is allowed to execute this program. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Does the target program have an unsafe hierarchical reference?</STRONG> - <BLOCKQUOTE> - Does the target program contain a leading '/' or have a '..' backreference? These - are not allowed; the target program must reside within the Apache webspace. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target user name valid?</STRONG> - <BLOCKQUOTE> - Does the target user exist? - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target group name valid?</STRONG> - <BLOCKQUOTE> - Does the target group exist? - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target user <EM>NOT</EM> superuser?</STRONG> - <BLOCKQUOTE> - Presently, suEXEC does not allow 'root' to execute CGI/SSI programs. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target userid <EM>ABOVE</EM> the minimum ID number?</STRONG> - <BLOCKQUOTE> - 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. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target group <EM>NOT</EM> the superuser group?</STRONG> - <BLOCKQUOTE> - Presently, suEXEC does not allow the 'root' group to execute CGI/SSI programs. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target groupid <EM>ABOVE</EM> the minimum ID number?</STRONG> - <BLOCKQUOTE> - 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. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Can the wrapper successfully become the target user and group?</STRONG> - <BLOCKQUOTE> - 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. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Does the directory in which the program resides exist?</STRONG> - <BLOCKQUOTE> - If it doesn't exist, it can't very well contain files. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the directory within the Apache webspace?</STRONG> - <BLOCKQUOTE> - 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? - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the directory <EM>NOT</EM> writable by anyone else?</STRONG> - <BLOCKQUOTE> - We don't want to open up the directory to others; only the owner user may be able - to alter this directories contents. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Does the target program exist?</STRONG> - <BLOCKQUOTE> - If it doesn't exists, it can't very well be executed. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target program <EM>NOT</EM> writable by anyone else?</STRONG> - <BLOCKQUOTE> - We don't want to give anyone other than the owner the ability to change the program. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target program <EM>NOT</EM> setuid or setgid?</STRONG> - <BLOCKQUOTE> - We do not want to execute programs that will then change our UID/GID again. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target user/group the same as the program's user/group?</STRONG> - <BLOCKQUOTE> - Is the user the owner of the file? - </BLOCKQUOTE> - </LI> - <LI><STRONG>Can we successfully clean the process environment to ensure safe operations?</STRONG> - <BLOCKQUOTE> - 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). - </BLOCKQUOTE> - </LI> - <LI><STRONG>Can we successfully become the target program and execute?</STRONG> - <BLOCKQUOTE> - Here is where suEXEC ends and the target program begins. - </BLOCKQUOTE> - </LI> - </OL> +<OL> + <LI><STRONG>Was the wrapper called with the proper number of + arguments?</STRONG> + <BLOCKQUOTE> + 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. + </BLOCKQUOTE> + </LI> + <LI><STRONG>Is the user executing this wrapper a valid user of this + system?</STRONG> + <BLOCKQUOTE> + This is to ensure that the user executing the wrapper is truly a user of the + system. + </BLOCKQUOTE> + </LI> + <LI><STRONG>Is this valid user allowed to run the wrapper?</STRONG> + <BLOCKQUOTE> + Is this user the user allowed to run this wrapper? Only one user (the + Apache user) is allowed to execute this program. + </BLOCKQUOTE> + </LI> + <LI><STRONG>Does the target program have an unsafe hierarchical + reference?</STRONG> + <BLOCKQUOTE> + Does the target program contain a leading '/' or have a '..' backreference? + These are not allowed; the target program must reside within the Apache + webspace. + </BLOCKQUOTE> + </LI> + <LI><STRONG>Is the target user name valid?</STRONG> + <BLOCKQUOTE> + Does the target user exist? + </BLOCKQUOTE> + </LI> + <LI><STRONG>Is the target group name valid?</STRONG> + <BLOCKQUOTE> + Does the target group exist? + </BLOCKQUOTE> + </LI> + <LI><STRONG>Is the target user <EM>NOT</EM> superuser?</STRONG> + <BLOCKQUOTE> + Presently, suEXEC does not allow 'root' to execute CGI/SSI programs. + </BLOCKQUOTE> + </LI> + <LI><STRONG>Is the target userid <EM>ABOVE</EM> the minimum ID + number?</STRONG> + <BLOCKQUOTE> + 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. + </BLOCKQUOTE> + </LI> + <LI><STRONG>Is the target group <EM>NOT</EM> the superuser group?</STRONG> + <BLOCKQUOTE> + Presently, suEXEC does not allow the 'root' group to execute CGI/SSI + programs. + </BLOCKQUOTE> + </LI> + <LI><STRONG>Is the target groupid <EM>ABOVE</EM> the minimum ID + number?</STRONG> + <BLOCKQUOTE> + 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. + </BLOCKQUOTE> + </LI> + <LI><STRONG>Can the wrapper successfully become the target user and + group?</STRONG> + <BLOCKQUOTE> + 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. + </BLOCKQUOTE> + </LI> + <LI><STRONG>Does the directory in which the program resides exist?</STRONG> + <BLOCKQUOTE> + If it doesn't exist, it can't very well contain files. + </BLOCKQUOTE> + </LI> + <LI><STRONG>Is the directory within the Apache webspace?</STRONG> + <BLOCKQUOTE> + 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? + </BLOCKQUOTE> + </LI> + <LI><STRONG>Is the directory <EM>NOT</EM> writable by anyone else?</STRONG> + <BLOCKQUOTE> + We don't want to open up the directory to others; only the owner user + may be able + to alter this directories contents. + </BLOCKQUOTE> + </LI> + <LI><STRONG>Does the target program exist?</STRONG> + <BLOCKQUOTE> + If it doesn't exists, it can't very well be executed. + </BLOCKQUOTE> + </LI> + <LI><STRONG>Is the target program <EM>NOT</EM> writable by anyone + else?</STRONG> + <BLOCKQUOTE> + We don't want to give anyone other than the owner the ability to + change the program. + </BLOCKQUOTE> + </LI> + <LI><STRONG>Is the target program <EM>NOT</EM> setuid or setgid?</STRONG> + <BLOCKQUOTE> + We do not want to execute programs that will then change our UID/GID again. + </BLOCKQUOTE> + </LI> + <LI><STRONG>Is the target user/group the same as the program's + user/group?</STRONG> + <BLOCKQUOTE> + Is the user the owner of the file? + </BLOCKQUOTE> + </LI> + <LI><STRONG>Can we successfully clean the process environment to + ensure safe operations?</STRONG> + <BLOCKQUOTE> + 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). + </BLOCKQUOTE> + </LI> + <LI><STRONG>Can we successfully become the target program and + execute?</STRONG> + <BLOCKQUOTE> + Here is where suEXEC ends and the target program begins. + </BLOCKQUOTE> + </LI> +</OL> </P> <P ALIGN="LEFT"> @@ -255,8 +286,9 @@ in mind. <P ALIGN="LEFT"> 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 <A HREF="#beware">"Beware the Jabberwock"</A> +in regards to server configuration, as well as what security risks can be +avoided with a proper suEXEC setup, see the +<A HREF="#jabberwock">"Beware the Jabberwock"</A> section of this document. </P> @@ -266,184 +298,162 @@ section of this document. <H3><A NAME="install">Configuring & Installing suEXEC</A></H3> <P ALIGN="LEFT"> -Here's where we begin the fun. The configuration and installation of suEXEC is -a four step process: edit the suEXEC header file, compile suEXEC, place the -suEXEC binary in its proper location, and configure Apache for use with suEXEC. -</P> - -<P ALIGN="LEFT"> -<STRONG>EDITING THE SUEXEC HEADER FILE</STRONG><BR> -- From the top-level of the Apache source tree, type: -<STRONG><code>cd support [ENTER]</code></STRONG> -</P> - -<P ALIGN="LEFT"> -Edit the <code>suexec.h</code> file and change the following macros to -match your local Apache installation. -</P> - -<P ALIGN="LEFT"> -<EM>From support/suexec.h</EM> +Here's where we begin the fun. If you use Apache 1.2 or prefer to configure +Apache 1.3 with the "<CODE>src/Configure</CODE>" script you have to edit +the suEXEC header file and install the binary in its proper location +manually. This procedure is described in an +<A HREF="suexec_1_2.html">extra document</A>. +The following sections describe the configuration and installation +for Apache 1.3 with the AutoConf-style interface (APACI). +</P> + +<P ALIGN="LEFT"> +<STRONG>APACI's suEXEC configuration options</STRONG><BR> +<DL> +<DT><CODE>--enable-suexec</CODE> +<DD>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. +<DT><CODE>--suexec-caller=<EM>UID</EM></CODE> +<DD>The <A HREF="mod/core.html#user">username</A> under which + Apache normally runs. + This is the only user allowed to execute this program. +<DT><CODE>--suexec-docroot=<EM>DIR</EM></CODE> +<DD>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", <EM>e.g.</EM> if you configure with + "<CODE>--datadir=/home/apache</CODE>" the directory + "/home/apache/htdocs" is used as document root for + the suEXEC wrapper. +<DT><CODE>--suexec-logfile=<EM>FILE</EM></CODE> +<DD>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). +<DT><CODE>--suexec-userdir=<EM>DIR</EM></CODE> +<DD>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". + <BR> + 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. <STRONG>If this is not defined + properly, "~userdir" cgi requests will not work!</STRONG> +<DT><CODE>--suexec-uidmin=<EM>UID</EM></CODE> +<DD>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. +<DT><CODE>--suexec-gidmin=<EM>GID</EM></CODE> +<DD>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. +<DT><CODE>--suexec-safepath=<EM>PATH</EM></CODE> +<DD>Define a safe PATH environment to pass to CGI executables. + Default value is "/usr/local/bin:/usr/bin:/bin". +</DL> +</P> + +<P ALIGN="LEFT"> +<STRONG>Checking your suEXEC setup</STRONG><BR> +Before you compile and install the suEXEC wrapper you can check +the configuration with the --layout option. +<BR> +Example output: <PRE> - /* - * HTTPD_USER -- Define as the username under which Apache normally - * runs. This is the only user allowed to execute - * this program. - */ - #define HTTPD_USER "www" - - /* - * UID_MIN -- Define this as the lowest UID allowed to be a target user - * for suEXEC. For most systems, 500 or 100 is common. - */ - #define UID_MIN 100 - - /* - * GID_MIN -- Define this as the lowest GID allowed to be a target group - * for suEXEC. For most systems, 100 is common. - */ - #define GID_MIN 100 - - /* - * USERDIR_SUFFIX -- 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. - * - * If you have VirtualHosts 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! - * See the suEXEC documentation for more detailed - * information. - */ - #define USERDIR_SUFFIX "public_html" - - /* - * LOG_EXEC -- Define this as a filename if you want all suEXEC - * transactions and errors logged for auditing and - * debugging purposes. - */ - #define LOG_EXEC "/usr/local/etc/httpd/logs/cgi.log" /* Need me? */ - - /* - * DOC_ROOT -- Define as the DocumentRoot set for Apache. This - * will be the only hierarchy (aside from UserDirs) - * that can be used for suEXEC behavior. - */ - #define DOC_ROOT "/usr/local/etc/httpd/htdocs" - - /* - * SAFE_PATH -- Define a safe PATH environment to pass to CGI executables. - * - */ - #define SAFE_PATH "/usr/local/bin:/usr/bin:/bin" + suEXEC setup: + suexec binary: /usr/local/apache/sbin/suexec + document root: /usr/local/apache/share/htdocs + userdir suffix: public_html + logfile: /usr/local/apache/var/log/suexec_log + safe path: /usr/local/bin:/usr/bin:/bin + caller ID: www + minimum user ID: 100 + minimum group ID: 100 </PRE> </P> <P ALIGN="LEFT"> -<STRONG>COMPILING THE SUEXEC WRAPPER</STRONG><BR> -You now need to compile the suEXEC wrapper. At the shell command prompt, -type: <STRONG><CODE>cc suexec.c -o suexec [ENTER]</CODE></STRONG>. -This should create the <STRONG><em>suexec</em></STRONG> wrapper executable. +<STRONG>Compiling and installing the suEXEC wrapper</STRONG><BR> +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". +<BR> +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". +<BR> +Please note that you need <STRONG><EM>root privileges</EM></STRONG> for +the installation step. In order for the wrapper to set the user ID, it +must be installed as owner <CODE><EM>root</EM></CODE> and must have the +setuserid execution bit set for file modes. </P> -<P ALIGN="LEFT"> -<STRONG>COMPILING APACHE FOR USE WITH SUEXEC</STRONG><BR> -By default, Apache is compiled to look for the suEXEC wrapper in the following -location. +<P ALIGN="CENTER"> +<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> </P> +<H3><A NAME="enable">Enabling & Disabling suEXEC</A></H3> <P ALIGN="LEFT"> -<EM>From src/httpd.h</EM> +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: <PRE> - /* The path to the suEXEC wrapper */ - #define SUEXEC_BIN "/usr/local/etc/httpd/sbin/suexec" + [notice] suEXEC mechanism enabled (wrapper: <EM>/path/to/suexec</EM>) </PRE> -</P> - -<P ALIGN="LEFT"> -If your installation requires location of the wrapper program in a different -directory, edit src/httpd.h and recompile your Apache server. -See <A HREF="install.html">Compiling and Installing Apache</A> for more -info on this process. -</P> - -<P ALIGN="LEFT"> -<STRONG>COPYING THE SUEXEC BINARY TO ITS PROPER LOCATION</STRONG><BR> -Copy the <STRONG><em>suexec</em></STRONG> executable created in the -exercise above to the defined location for <STRONG>SUEXEC_BIN</STRONG>. -</P> - -<P ALIGN="LEFT"> -<STRONG><CODE>cp suexec /usr/local/etc/httpd/sbin/suexec [ENTER]</CODE></STRONG> -</P> - -<P ALIGN="LEFT"> -In order for the wrapper to set the user ID, it must me installed as owner -<STRONG><em>root</em></STRONG> and must have the setuserid execution bit -set for file modes. If you are not running a <STRONG><em>root</em></STRONG> -user shell, do so now and execute the following commands. -</P> - -<P ALIGN="LEFT"> -<STRONG><CODE>chown root /usr/local/etc/httpd/sbin/suexec [ENTER]</CODE></STRONG><BR> -<STRONG><CODE>chmod 4711 /usr/local/etc/httpd/sbin/suexec [ENTER]</CODE></STRONG> +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 <EM>setuid root</EM>. +<BR> +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. +<BR> +If you want to disable suEXEC you should kill and restart Apache after +you have removed the "suexec" file. </P> <P ALIGN="CENTER"> <STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> </P> -<H3><A NAME="enable">Enabling & Disabling suEXEC</A></H3> +<H3><A NAME="usage">Using suEXEC</A></H3> <P ALIGN="LEFT"> -After properly installing the <STRONG>suexec</STRONG> wrapper -executable, you must kill and restart the Apache server. A simple -<STRONG><CODE>kill -1 `cat httpd.pid`</CODE></STRONG> will not be enough. -Upon startup of the web-server, if Apache finds a properly configured -<STRONG>suexec</STRONG> wrapper, it will print the following message to -the console: -</P> - -<P ALIGN="LEFT"> -<CODE>Configuring Apache for use with suexec wrapper.</CODE> -</P> - -<P ALIGN="LEFT"> -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 <STRONG><EM>setuid root</EM></STRONG>. Check -your installation and try again. -</P> - -<P ALIGN="LEFT"> -One way to use <STRONG>suEXEC</STRONG> is through the -<a href="mod/core.html#user"><STRONG>User</STRONG></a> and -<a href="mod/core.html#group"><STRONG>Group</STRONG></a> directives in -<a href="mod/core.html#virtualhost"><STRONG>VirtualHost</STRONG></a> +<STRONG>Virtual Hosts:</STRONG><BR> +One way to use the suEXEC wrapper is through the +<A HREF="mod/core.html#user">User</A> and +<A HREF="mod/core.html#group">Group</A> directives in +<A HREF="mod/core.html#virtualhost">VirtualHost</A> definitions. By setting these directives to values different from the main server user ID, all requests for CGI resources will be executed as -the <STRONG>User</STRONG> and <STRONG>Group</STRONG> defined for that -<STRONG><VirtualHost></STRONG>. If only one or +the <EM>User</EM> and <EM>Group</EM> defined for that +<CODE><VirtualHost></CODE>. If only one or neither of these directives are specified for a -<STRONG><VirtualHost></STRONG> then the main -server userid is assumed.<p> - -<STRONG>suEXEC</STRONG> can also be used to to execute CGI programs as +<CODE><VirtualHost></CODE> then the main +server userid is assumed. +<P> +<STRONG>User directories:</STRONG><BR> +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 <STRONG>~</STRONG> character prefixing the user ID for whom -execution is desired. +using the "<STRONG><CODE>~</CODE></STRONG>" 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 <a href="#model">security checks</a> above. +scrutiny of the <A HREF="#model">security checks</A> above. <P ALIGN="CENTER"> <STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> @@ -451,9 +461,9 @@ scrutiny of the <a href="#model">security checks</a> above. <H3><A NAME="debug">Debugging suEXEC</A></H3> <P ALIGN="LEFT"> -The suEXEC wrapper will write log information to the location defined in -the <code>suexec.h</code> as indicated above. If you feel you have -configured and installed the wrapper properly, have a look at this log +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. </P> @@ -461,7 +471,9 @@ and the error_log for the server to see where you may have gone astray. <STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> </P> -<H3><A NAME="jabberwock">Beware the Jabberwock: Warnings & Examples</A></H3> +<H3> +<A NAME="jabberwock">Beware the Jabberwock: Warnings & Examples</A> +</H3> <P ALIGN="LEFT"> <STRONG>NOTE!</STRONG> This section may not be complete. For the latest revision of this section of the documentation, see the Apache Group's @@ -474,7 +486,7 @@ 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. <UL> - <LH><STRONG>suEXEC Points Of Interest</STRONG></LH> + <LI><STRONG>suEXEC Points Of Interest</STRONG></LI> <LI>Hierarchy limitations <BLOCKQUOTE> For security and efficiency reasons, all suexec requests must @@ -508,9 +520,9 @@ limitations on server setup. Please review these before submitting any </P> <HR> -<H3 ALIGN="CENTER"> - Apache HTTP Server Version 1.2 -</H3> + <H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 + </H3> <A HREF="./"><IMG SRC="images/index.gif" ALT="Index"></A> diff --git a/usr.sbin/httpd/htdocs/manual/upgrading_to_1_3.html b/usr.sbin/httpd/htdocs/manual/upgrading_to_1_3.html index 0db2c7c666d..e4d9d081704 100644 --- a/usr.sbin/httpd/htdocs/manual/upgrading_to_1_3.html +++ b/usr.sbin/httpd/htdocs/manual/upgrading_to_1_3.html @@ -78,6 +78,21 @@ document, or in the <CODE>src/CHANGES</CODE> file. <H3>Run-Time Configuration Changes</H3> <UL> + <LI>There have been numerous changes to the default config files. + Ensure that you compare your existing configuration files with the + new ones to ensure there aren't any undesired differences. In + particular: + <UL> + <LI>As of Apache 1.3.0, the current config files apply different + <A HREF="mod/core.html#options">Options</A> and + <A HREF="mod/core.html#allowoverride">AllowOverride</A> settings to + various directories than were used in 1.2. + </LI> + <LI>As of the release following Apache 1.3.3, the three + config file templates have been merged into <SAMP>httpd.conf-dist</SAMP> + and the order of the directives changed. + </LI> + </UL> <LI>As of 1.3.2, <A HREF="mod/mod_expires.html"><CODE>mod_expires</CODE></A> will add Expires headers to content that does not come from a file on disk, unless you are using a modification time based setting. @@ -116,7 +131,7 @@ document, or in the <CODE>src/CHANGES</CODE> file. "<SAMP><Limit Get post></SAMP>" in your configuration files, you need to correct them to use uppercase names. <P> - Unrecognised method names in the server configuration files will + Unrecognized method names in the server configuration files will result in the server logging an error message and failing to start. In <SAMP>.htaccess</SAMP> files, unknown methods will cause the server to log an error to its error log and return an 'Internal @@ -186,7 +201,7 @@ document, or in the <CODE>src/CHANGES</CODE> file. <LI><Files> sections previously could take a full pathname, and were matched against the full pathnames. This had some - inconsistancies, and was removed. To emulate this older behaviour + inconsistencies, and was removed. To emulate this older behaviour use a <Files> section nested inside a <Directory> section. diff --git a/usr.sbin/httpd/htdocs/manual/vhosts/name-based.html b/usr.sbin/httpd/htdocs/manual/vhosts/name-based.html index 339f54949e0..d9a9ce93e8e 100644 --- a/usr.sbin/httpd/htdocs/manual/vhosts/name-based.html +++ b/usr.sbin/httpd/htdocs/manual/vhosts/name-based.html @@ -46,34 +46,49 @@ solution is addressed below.</P> <H2>Using non-IP Virtual Hosts</H2> <P>Using the new virtual hosts is quite easy, and superficially looks -like the old method. You simply add to one of the Apache configuration -files (most likely <CODE>httpd.conf</CODE> or <CODE>srm.conf</CODE>) -code similar to the following:</P> +like the old method. The notable difference between IP-based and +name-based virtual host configuration is the +<A HREF="../mod/core.html#namevirtualhost"><CODE>NameVirtualHost</CODE></A> +directive which specifies an IP address that should be used as a +target for name-based virtual hosts.</P> + +<P>For example, suppose that both <SAMP>www.domain.tld</SAMP> and +<SAMP>www.otherdomain.tld</SAMP> point at the IP address +<SAMP>111.22.33.44</SAMP>. Then you simply add to one of the Apache +configuration files (most likely <CODE>httpd.conf</CODE> or +<CODE>srm.conf</CODE>) code similar to the following:</P> + + + <PRE> NameVirtualHost 111.22.33.44 <VirtualHost 111.22.33.44> ServerName www.domain.tld - DocumentRoot /web/domain + DocumentRoot /www/domain </VirtualHost> -</PRE> -<P>The notable difference between IP-based and name-based virtual host -configuration is the -<A HREF="../mod/core.html#namevirtualhost"><CODE>NameVirtualHost</CODE></A> -directive which specifies an IP address that should be used as a target for -name-based virtual hosts. + <VirtualHost 111.22.33.44> + ServerName www.otherdomain.tld + DocumentRoot /www/otherdomain + </VirtualHost> +</PRE> <P>Of course, any additional directives can (and should) be placed into the <CODE><VirtualHost></CODE> section. To make this work, -all that is needed is to make sure that the name -<SAMP>www.domain.tld</SAMP> points to the IP address -<SAMP>111.22.33.44</SAMP></P> +all that is needed is to make sure that the names +<SAMP>www.domain.tld</SAMP> and <SAMP>www.otherdomain.tld</SAMP> +are pointing to the IP address <SAMP>111.22.33.44</SAMP></P> <P>Note: When you specify an IP address in a <CODE>NameVirtualHost</CODE> directive then requests to that IP address will only ever be served -by matching <VirtualHost>s. The "main server" will <STRONG>never</STRONG> -be served from the specified IP address. +by matching <VirtualHost>s. The "main server" will +<STRONG>never</STRONG> be served from the specified IP address. +If you start to use virtual hosts you should stop to use the "main server" +as an independent server and rather use it as a place for +configuration directives that are common for all your virtual hosts. +In other words, you should add a <VirtualHost> section for +<EM>every</EM> server (hostname) you want to maintain on your server. <P>Additionally, many servers may wish to be accessible by more than one name. For example, the example server might want to be accessible diff --git a/usr.sbin/httpd/htdocs/manual/windows.html b/usr.sbin/httpd/htdocs/manual/windows.html index 8ddc4aad3e4..f23f1227d94 100644 --- a/usr.sbin/httpd/htdocs/manual/windows.html +++ b/usr.sbin/httpd/htdocs/manual/windows.html @@ -23,7 +23,7 @@ <H1 ALIGN="CENTER">Using Apache With Microsoft Windows</H1> <P>This document explains how to install, configure and run - Apache 1.3b6 and later under Microsoft Windows. Please note that at + Apache 1.3 under Microsoft Windows. Please note that at this time, Windows support is entirely experimental, and is recommended only for experienced users. The Apache Group does not guarantee that this software will work as documented, or even at @@ -138,19 +138,6 @@ new one after the installation is finished). <P> -<BLOCKQUOTE> -<STRONG>Important note for 1.3b6 installs</STRONG>: the above only -applies for 1.3b7 and later. In 1.3b6 the installer would overwrite -any existing <SAMP>httpd.conf</SAMP>, <SAMP>access.conf</SAMP>, -<SAMP>srm.conf</SAMP> or <SAMP>mime.types</SAMP> files in the -<SAMP>conf</SAMP>, and will also overwrite your -<SAMP>index.html</SAMP> file in the <SAMP>htdocs</SAMP> directory. You -should copy these files or directories before installing Apache 1.3b6 -or install into a new directory. -</BLOCKQUOTE> - -<P> - After installing Apache, you should edit the configuration files in the <SAMP>conf</SAMP> directory as required. These files will be configured during the install ready for Apache to be run from the @@ -190,8 +177,8 @@ with To run Apache from a console window, select the "Apache Server" option from the Start menu. This will open a console window and start Apache running inside it. The window will remain active until you stop -Apache. To stop Apache running, see <A HREF="#signal>Signalling Apache -when Running</SAMP>. +Apache. To stop Apache running, see <A HREF="#signal"><SAMP>Signalling Apache +when Running</SAMP></A>. <P> @@ -275,8 +262,8 @@ The main differences in Apache for Windows are: <H2><A NAME="cmdline">Running Apache for Windows from the Command Line</A></H2> -The Start menu icons and the NT Service manager can provide an simple -interafce for administering Apache. But in some cases it is easier to +The Start menu icons and the NT Service manager can provide a simple +interface for administering Apache. But in some cases it is easier to work from the command line. <P> @@ -301,27 +288,27 @@ Your current working directory when Apache is started up has no effect on Apache's behavior. <P> -Under windows, when invoked from the start menu or the Service Manager Apache is -usually passed no arguments. So using the registry entry is the perfered +When invoked from the start menu or the Service Manager, Apache is +usually passed no arguments, so using the registry entry is the preferred technique. <P> During a binary installation, a registry key will have been installed, for example: <PRE> - HKEY_LOCAL_MACHINE\Software\Apache Group\Apache\1.3.1\ServerRoot + HKEY_LOCAL_MACHINE\Software\Apache Group\Apache\1.3.4\ServerRoot </PRE> <P> This key is compiled into the server and can enable you to test new versions without affecting the current version. Of course you must take care not to install the new version on top of the -old version in the file system. You can not run two invocations +old version in the file system. You cannot run two invocations of Apache on Windows simultaneously. <P> If you did not do a binary install then Apache will in some -senarios complain that about the missing registry key. This +scenarios complain that about the missing registry key. This warning can be ignored if it otherwise was able to find it's configuration files. @@ -350,7 +337,7 @@ prevents Apache waiting to see if Apache is running as a service.) <P> -To install Apache as a Windows NT service as follows: +You can install Apache as a Windows NT service as follows: <PRE> apache -i @@ -365,13 +352,19 @@ and to remove the Apache service, use <H2><A NAME="signal">Signalling Apache when running</A></H2> -On Windows 95 Apache runs as a console application. You can tell a +On Windows 95, Apache runs as a console application. You can tell a running Apache to stop by opening another console window and running <PRE> apache -k shutdown </PRE> +<BLOCKQUOTE> + <STRONG>Note: This option is only available with Apache 1.3.3 and + later. For earlier versions, you need to use Control-C in the + Apache console window to shut down the server.</STRONG> +</BLOCKQUOTE> +<P> This should be used instead of pressing Control-C in the running Apache console window, because it lets Apache end any current transactions and cleanup gracefully. @@ -385,10 +378,16 @@ complete without interruption. To restart Apache, run <PRE> apache -k restart </PRE> +<BLOCKQUOTE> + <STRONG>Note: This option is only available with Apache 1.3.3 and + later. For earlier versions, you need to use Control-C in the + Apache console window to shut down the server.</STRONG> +</BLOCKQUOTE> +<P> Note for people familiar with the Unix version of Apache: these commands provide a Windows equivalent to <CODE>kill -TERM -<i>pid</i></CODE> and <CODE>kill -USR1 <i>pid</i></CODE>. The command +<EM>pid</EM></CODE> and <CODE>kill -USR1 <EM>pid</EM></CODE>. The command line option used, <CODE>-k</CODE>, was chosen as a reminder of the "kill" command used on Unix. @@ -404,13 +403,19 @@ line option used, <CODE>-k</CODE>, was chosen as a reminder of the <CODE>src</CODE> subdirectory of the Apache distribution.</P> <P>The master Apache makefile instructions are contained in the - <CODE>Makefile.nt</CODE> file. To compile Apache, simply use one of - the following commands: + <CODE>Makefile.nt</CODE> file. To compile Apache on Windows NT, simply + use one of the following commands: <UL> <LI><CODE>nmake /f Makefile.nt _apacher</CODE> (release build) <LI><CODE>nmake /f Makefile.nt _apached</CODE> (debug build) </UL> +<P><em>(1.3.4 and later)</em> To compile Apache on Windows 95, use one of +<UL> +<LI><CODE>nmake /f Makefile_win32.txt</CODE> (release build) +<LI><CODE>nmake /f Makefile_win32_debug.txt</CODE> (debug build) +</UL> + <P>These will both compile Apache. The latter will include debugging information in the resulting files, making it easier to find bugs and track down problems.</P> @@ -448,8 +453,15 @@ line option used, <CODE>-k</CODE>, was chosen as a reminder of the <LI><CODE>nmake /f Makefile.nt installd INSTDIR=<EM>dir</EM></CODE> (for debug build) </UL> +or, for Windows 95 (1.3.4 and later), use one of: +<UL> +<LI><CODE>nmake /f Makefile_win32.txt install INSTDIR=<EM>dir</EM></CODE> + (for release build) +<LI><CODE>nmake /f Makefile_win32_debug.txt install INSTDIR=<EM>dir</EM></CODE> + (for debug build) +</UL> -The dir argument to INSTDIR gives the installation directory. The can +The dir argument to INSTDIR gives the installation directory; it can be omitted if Apache is to be installed into <SAMP>\Apache</SAMP>. <P>This will install the following:</P> |