diff options
Diffstat (limited to 'docs/manual')
| -rw-r--r-- | docs/manual/content-negotiation.html.en | 622 | ||||
| -rw-r--r-- | docs/manual/developer/modules.html.en | 258 | ||||
| -rw-r--r-- | docs/manual/dso.html.en | 344 | ||||
| -rw-r--r-- | docs/manual/logs.html.en | 666 | ||||
| -rw-r--r-- | docs/manual/mod/directive-dict.html.en | 327 | ||||
| -rw-r--r-- | docs/manual/mod/module-dict.html.en | 123 | ||||
| -rw-r--r-- | docs/manual/sitemap.html.en | 201 | ||||
| -rw-r--r-- | docs/manual/stopping.html.en | 209 | ||||
| -rwxr-xr-x | docs/manual/urlmapping.html.en | 333 |
9 files changed, 0 insertions, 3083 deletions
diff --git a/docs/manual/content-negotiation.html.en b/docs/manual/content-negotiation.html.en deleted file mode 100644 index 0f4e03ce31..0000000000 --- a/docs/manual/content-negotiation.html.en +++ /dev/null @@ -1,622 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> - -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta name="generator" content="HTML Tidy, see www.w3.org" /> - - <title>Apache Content Negotiation</title> - </head> - <!-- Background white, links blue (unvisited), navy (visited), red (active) --> - - <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" - vlink="#000080" alink="#FF0000"> - <!--#include virtual="header.html" --> - - <h1 align="CENTER">Content Negotiation</h1> - - <p>Apache's supports content negotiation as described in - the HTTP/1.1 specification. It can choose the best - representation of a resource based on the browser-supplied - preferences for media type, languages, character set and - encoding. It also implements a couple of features to give - more intelligent handling of requests from browsers that send - incomplete negotiation information.</p> - - <p>Content negotiation is provided by the <a - href="mod/mod_negotiation.html">mod_negotiation</a> module, - which is compiled in by default.</p> - <hr /> - - <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 appropriate choice is to give the - user an index page, and let them select. However it is often - possible for the server to choose automatically. This works - because browsers can send as part of each request information - about what representations they prefer. For example, a browser - could indicate that it would like to see information in French, - if possible, else English will do. Browsers indicate their - preferences by headers in the request. To request only French - representations, the browser would send</p> -<pre> - Accept-Language: fr -</pre> - - <p>Note that this preference will only be applied when there is - a choice of representations and they vary by language.</p> - - <p>As an example of a more complex request, this browser has - been configured to accept French and English, but prefer - French, and to accept various media types, preferring HTML over - plain text or other text types, and preferring GIF or JPEG over - other media types, but also allowing any other media type as a - last resort:</p> -<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> - Apache supports 'server driven' content negotiation, as - defined in the HTTP/1.1 specification. It fully supports the - Accept, Accept-Language, Accept-Charset and Accept-Encoding - request headers. Apache also supports 'transparent' - content negotiation, which is an experimental negotiation - protocol defined in RFC 2295 and RFC 2296. It does not offer - support for 'feature negotiation' as defined in these RFCs. - - <p>A <strong>resource</strong> is a conceptual entity - identified by a URI (RFC 2396). An HTTP server like Apache - provides access to <strong>representations</strong> of the - resource(s) within its namespace, with each representation in - the form of a sequence of bytes with a defined media type, - character set, encoding, etc. Each resource may be associated - with zero, one, or more than one representation at any given - time. If multiple representations are available, the resource - is referred to as <strong>negotiable</strong> and each of its - representations is termed a <strong>variant</strong>. The ways - in which the variants for a negotiable resource vary are called - the <strong>dimensions</strong> of negotiation.</p> - - <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:</p> - - <ul> - <li>Using a type map (<em>i.e.</em>, a <code>*.var</code> - file) which names the files containing the variants - explicitly, or</li> - - <li>Using a 'MultiViews' search, where the server does an - implicit filename pattern match and chooses from among the - results.</li> - </ul> - - <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 older Apache configurations, the - mime type <code>application/x-type-map</code>). Note that to - use this feature, you must have a handler set in the - configuration that defines a file suffix as - <code>type-map</code>; this is best done with a</p> -<pre> - AddHandler type-map .var -</pre> - in the server configuration file. - - <p>Type map files should have the same name as the resource - which they are describing, and have an entry for each available - variant; these entries consist of contiguous HTTP-format header - lines. Entries for different variants are separated by blank - lines. Blank lines are illegal within an entry. It is - conventional to begin a map file with an entry for the combined - entity as a whole (although this is not required, and if - present will be ignored). An example map file is shown below. - This file would be named <code>foo.var</code>, as it describes - a resource named <code>foo</code>.</p> -<pre> - URI: foo - - URI: foo.en.html - Content-type: text/html - Content-language: en - - URI: foo.fr.de.html - Content-type: text/html;charset=iso-8859-2 - Content-language: fr, de -</pre> - Note also that a typemap file will take precedence over the - filename's extension, even when Multiviews is on. If the - variants have different source qualities, that may be indicated - by the "qs" parameter to the media type, as in this picture - (available as jpeg, gif, or ASCII-art): -<pre> - URI: foo - - URI: foo.jpeg - Content-type: image/jpeg; qs=0.8 - - URI: foo.gif - Content-type: image/gif; qs=0.5 - - URI: foo.txt - Content-type: text/plain; qs=0.01 -</pre> - - <p>qs values can vary in the range 0.000 to 1.000. Note that - any variant with a qs value of 0.000 will never be chosen. - Variants with no 'qs' parameter value are given a qs factor of - 1.0. The qs parameter indicates the relative 'quality' of this - variant compared to the other available variants, independent - of the client's capabilities. For example, a jpeg file is - usually of higher source quality than an ascii file if it is - attempting to represent a photograph. However, if the resource - being represented is an original ascii art, then an ascii - representation would have a higher source quality than a jpeg - representation. A qs value is therefore specific to a given - variant depending on the nature of the resource it - represents.</p> - - <p>The full list of headers recognized is available in the <a - href="mod/mod_negotiation.html#typemaps">mod_negotation</a> - documentation.</p> - - - <h3>Multiviews</h3> - - <p><code>MultiViews</code> 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 have to ask for it by name.</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 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.</p> - - <p><code>MultiViews</code> may also apply to searches for the - file named by the <code>DirectoryIndex</code> directive, if the - server is trying to index a directory. If the configuration - files specify</p> -<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. - - <p>If one of the files found when reading the directory does not - have an extension recognized by <code>mod_mime</code> to designate - its Charset, Content-Type, Language, or Encoding, then the result - depends on the setting of the <a - href="mod/mod_mime.html#multiviewsmatch">MultiViewsMatch</a> - directive. This directive determines whether handlers, filters, - and other extension types can participate in MultiViews - negotiation.</p> - - <h2>The Negotiation Methods</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 invokes one of two methods to decide on the - 'best' variant to return, if any. It is not necessary to know - any of the details of how negotiation actually takes place in - order to use Apache's content negotiation features. However the - rest of this document explains the methods used for those - interested. - - <p>There are two negotiation methods:</p> - - <ol> - <li><strong>Server driven negotiation with the Apache - algorithm</strong> is used in the normal case. The Apache - algorithm is explained in more detail below. When this - algorithm is used, Apache can sometimes 'fiddle' the quality - factor of a particular dimension to achieve a better result. - The ways Apache can fiddle quality factors is explained in - more detail below.</li> - - <li><strong>Transparent content negotiation</strong> is used - when the browser specifically requests this through the - mechanism defined in RFC 2295. This negotiation method gives - the browser full control over deciding on the 'best' variant, - the result is therefore dependent on the specific algorithms - used by the browser. As part of the transparent negotiation - process, the browser can ask Apache to run the 'remote - variant selection algorithm' defined in RFC 2296.</li> - </ol> - - <h3>Dimensions of Negotiation</h3> - - <table> - <tr valign="top"> - <th>Dimension</th> - - <th>Notes</th> - </tr> - - <tr valign="top"> - <td>Media Type</td> - - <td>Browser indicates preferences with the Accept header - field. Each item can have an associated quality factor. - Variant description can also have a quality factor (the - "qs" parameter).</td> - </tr> - - <tr valign="top"> - <td>Language</td> - - <td>Browser indicates preferences with the Accept-Language - header field. Each item can have a quality factor. Variants - can be associated with none, one or more than one - language.</td> - </tr> - - <tr valign="top"> - <td>Encoding</td> - - <td>Browser indicates preference with the Accept-Encoding - header field. Each item can have a quality factor.</td> - </tr> - - <tr valign="top"> - <td>Charset</td> - - <td>Browser indicates preference with the Accept-Charset - header field. Each item can have a quality factor. Variants - can indicate a charset as a parameter of the media - type.</td> - </tr> - </table> - - <h3>Apache Negotiation Algorithm</h3> - - <p>Apache can use the following algorithm to select the 'best' - variant (if any) to return to the browser. This algorithm is - not further configurable. It operates as follows:</p> - - <ol> - <li>First, for each dimension of the negotiation, check the - appropriate <em>Accept*</em> header field and assign a - quality to each variant. If the <em>Accept*</em> header for - any dimension implies that this variant is not acceptable, - eliminate it. If no variants remain, go to step 4.</li> - - <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 test are eliminated. After each test, - if only one variant remains, select it as the best match - and proceed to step 3. If more than one variant remains, - move on to the next test. - - <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> - - <li>Select the variants with the highest language quality - factor.</li> - - <li>Select the variants with the best language match, - using either the order of languages in the - Accept-Language header (if present), or else the order of - languages in the <code>LanguagePriority</code> directive - (if present).</li> - - <li>Select the variants with the highest 'level' media - parameter (used to give the version of text/html media - types).</li> - - <li>Select variants with the best charset media - parameters, as given on the Accept-Charset header line. - Charset ISO-8859-1 is acceptable unless explicitly - excluded. Variants with a <code>text/*</code> media type - but not explicitly associated with a particular charset - are assumed to be in ISO-8859-1.</li> - - <li>Select those variants which have associated charset - media parameters that are <em>not</em> ISO-8859-1. If - there are no such variants, select all variants - instead.</li> - - <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> - - <li>Select the variants with the smallest content - length.</li> - - <li>Select the first variant of those remaining. This - will be either the first listed in the type-map file, or - when variants are read from the directory, the one whose - file name comes first when sorted using ASCII code - order.</li> - </ol> - </li> - - <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> - - <li>To get here means no variant was selected (because none - are acceptable to the browser). Return a 406 status (meaning - "No acceptable representation") with a response body - consisting of an HTML document listing the available - variants. Also set the HTTP Vary header to indicate the - dimensions of variance.</li> - </ol> - - <h2><a id="better" 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 Apache - negotiation algorithm above. This is to get a better result - from the algorithm for browsers which do not send full or - accurate information. Some of the most popular browsers send - Accept header information which would otherwise result in the - selection of the wrong variant in many cases. If a browser - sends full and correct information these fiddles will not be - applied.</p> - - <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:</p> -<pre> - Accept: image/*, */* -</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> - Accept: text/html, text/plain, image/gif, image/jpeg, */* -</pre> - The intention of this is to indicate that the explicitly listed - types are preferred, but if a different representation is - available, that is ok too. However under the basic algorithm, - as given above, the */* wildcard has exactly equal preference - to all the other types, so they are not being preferred. The - browser should really have sent a request with a lower quality - (preference) value for *.*, such as: -<pre> - Accept: text/html, text/plain, image/gif, image/jpeg, */*; q=0.01 -</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>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 - <em>not</em> applied, so requests from browsers which send the - correct information to start with work as expected.</p> - - <h3>Language Negotiation Exceptions</h3> - - <p>New in Apache 2.0, some exceptions have been added to the - negotiation algorithm to allow graceful fallback when language - negotiation fails to find a match.</p> - - <p>When a client requests a page on your server, but the server - cannot find a single page that matches the Accept-language sent by - the browser, the server will return either a "No Acceptable - Variant" or "Multiple Choices" response to the client. To avoid - these error messages, it is possible to configure Apache to ignore - the Accept-language in these cases and provide a document that - does not explictly match the client's request. The <a - href="mod/mod_negotiation.html#forcelanguagepriority">ForceLanguagePriority</a> - directive can be used to override one or both of these error - messages and subsitute the servers judgement in the form of the <a - href="mod/mod_negotiation.html#languagepriority">LanguagePriority</a> - directive.</p> - - <p>The server will also attempt to match language-subsets when no - other match can be found. For example, if a client requests - documents with the language <code>en-GB</code> for British - English, the server is not normally allowed by the HTTP/1.1 - standard to match that against a document that is marked as simply - <code>en</code>. (Note that it is almost surely a configuration - error to include <code>en-GB</code> and not <code>en</code> in the - Accept-Language header, since it is very unlikely that a reader - understands British English, but doesn't understand English in - general. Unfortunately, many current clients have default - configurations that resemble this.) However, if no other language - match is possible and the server is about to return a "No - Acceptable Variants" error or fallback to the - <code>LanguagePriority</code>, the server will ignore the subset - specification and match <code>en-GB</code> against <code>en</code> - documents. Implicitly, Apache will add the parent language to - the client's acceptable language list with a very low quality - value. But note that if the client requests "en-GB; qs=0.9, fr; - qs=0.8", and the server has documents designated "en" and "fr", - then the "fr" document will be returned. This is necessary to - maintain compliance with the HTTP/1.1 specification and to work - effectively with properly configured clients.</p> - - - <h2>Extensions to Transparent Content Negotiation</h2> - Apache extends the transparent content negotiation protocol - (RFC 2295) as follows. A new <code>{encoding ..}</code> element - is used in variant lists to label variants which are available - with a specific content-encoding only. The implementation of - the RVSA/1.0 algorithm (RFC 2296) is extended to recognize - encoded variants in the list, and to use them as candidate - variants whenever their encodings are acceptable according to - the Accept-Encoding request header. The RVSA/1.0 implementation - does not round computed quality factors to 5 decimal places - before choosing the best variant. - - <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 the <a - href="mod/mod_mime.html#multipleext">mod_mime</a> documentation - for details).</p> - - <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> - - <p>Examples:</p> - - <ul> - <li>foo.en.html</li> - - <li>foo.html.en</li> - - <li>foo.en.html.gz</li> - </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> - - <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>).</p> - - <h2>Note on Caching</h2> - - <p>When a cache stores a representation, it associates it with - the request URL. The next time that URL is requested, the cache - can use the stored representation. But, if the resource is - negotiable at the server, this might result in only the first - requested variant being cached and subsequent cache hits might - return the wrong response. To prevent this, Apache normally - marks all responses that are returned after content negotiation - as non-cacheable by HTTP/1.0 clients. Apache also supports the - HTTP/1.1 protocol features to allow caching of negotiated - responses.</p> - - <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 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. - - <h2>More Information</h2> - - <p>For more information about content negotiation, see Alan - J. Flavell's <a - href="http://ppewww.ph.gla.ac.uk/~flavell/www/lang-neg.html">Language - Negotiation Notes</a>. But note that this document may not be - updated to include changes in Apache 2.0.</p> - - <!--#include virtual="footer.html" --> - </body> -</html> - diff --git a/docs/manual/developer/modules.html.en b/docs/manual/developer/modules.html.en deleted file mode 100644 index ebf7c33da2..0000000000 --- a/docs/manual/developer/modules.html.en +++ /dev/null @@ -1,258 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> - -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta name="generator" content="HTML Tidy, see www.w3.org" /> - - <title>Converting Modules from Apache 1.3 to Apache 2.0</title> - </head> - <!-- Background white, links blue (unvisited), navy (visited), red (active) --> - - <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" - vlink="#000080" alink="#FF0000"> - <!--#include virtual="header.html" --> - - <h1 align="CENTER">From Apache 1.3 to Apache 2.0<br /> - Modules</h1> - - <p>This is a first attempt at writing the lessons I learned - when trying to convert the mod_mmap_static module to Apache - 2.0. It's by no means definitive and probably won't even be - correct in some ways, but it's a start.</p> - <hr /> - - <h2>The easier changes...</h2> - - <h3>Cleanup Routines</h3> - - <p>These now need to be of type apr_status_t and return a value - of that type. Normally the return value will be APR_SUCCESS - unless there is some need to signal an error in the cleanup. Be - aware that even though you signal an error not all code yet - checks and acts upon the error.</p> - - <h3>Initialisation Routines</h3> - - <p>These should now be renamed to better signify where they sit - in the overall process. So the name gets a small change from - mmap_init to mmap_post_config. The arguments passed have - undergone a radical change and now look like</p> - - <ul style="list-style:none"> - <li>apr_pool_t *p,</li> - - <li>apr_pool_t *plog,</li> - - <li>apr_pool_t *ptemp,</li> - - <li>server_rec *s</li> - </ul> - - <h3>Data Types</h3> - - <p>A lot of the data types have been moved into the APR. This - means that some have had a name change, such as the one shown - above. The following is a brief list of some of the changes - that you are likely to have to make.</p> - - <ul style="list-style:none"> - <li>pool becomes apr_pool_t</li> - - <li>table becomes apr_table_t</li> - </ul> - <hr /> - - <h2>The <em>messier</em> changes...</h2> - - <h3>Register Hooks</h3> - - <p>The new architecture uses a series of hooks to provide for - calling your functions. These you'll need to add to your module - by way of a new function, static void register_hooks(void). The - function is really reasonably straightforward once you - understand what needs to be done. Each function that needs - calling at some stage in the processing of a request needs to - be registered, handlers do not. There are a number of phases - where functions can be added, and for each you can specify with - a high degree of control the relative order that the function - will be called in.</p> - - <p>This is the code that was added to mod_mmap_static:</p> -<pre> -static void register_hooks(void) -{ - static const char * const aszPre[]={ "http_core.c",NULL }; - ap_hook_post_config(mmap_post_config,NULL,NULL,HOOK_MIDDLE); - ap_hook_translate_name(mmap_static_xlat,aszPre,NULL,HOOK_LAST); -}; -</pre> - - <p>This registers 2 functions that need to be called, one in - the post_config stage (virtually every module will need this - one) and one for the translate_name phase. note that while - there are different function names the format of each is - identical. So what is the format?</p> - - <p><strong>ap_hook_[phase_name](function_name, predecessors, - successors, position);</strong></p> - - <p>There are 3 hook positions defined...</p> - - <ul style="list-style:none"> - <li>HOOK_FIRST</li> - - <li>HOOK_MIDDLE</li> - - <li>HOOK_LAST</li> - </ul> - - <p>To define the position you use the position and then modify - it with the predecessors and successors. each of the modifiers - can be a list of functions that should be called, either before - the function is run (predecessors) or after the function has - run (successors).</p> - - <p>In the mod_mmap_static case I didn't care about the - post_config stage, but the mmap_static_xlat MUST be called - after the core module had done it's name translation, hence the - use of the aszPre to define a modifier to the position - HOOK_LAST.</p> - - <h3>Module Definition</h3> - - <p>There are now a lot fewer stages to worry about when - creating your module definition. The old defintion looked - like</p> -<pre> -module MODULE_VAR_EXPORT [module_name]_module = -{ - STANDARD_MODULE_STUFF, - /* initializer */ - /* dir config creater */ - /* dir merger --- default is to override */ - /* server config */ - /* merge server config */ - /* command handlers */ - /* handlers */ - /* filename translation */ - /* check_user_id */ - /* check auth */ - /* check access */ - /* type_checker */ - /* fixups */ - /* logger */ - /* header parser */ - /* child_init */ - /* child_exit */ - /* post read-request */ -}; -</pre> - - <p>The new structure is a great deal simpler...</p> -<pre> -module MODULE_VAR_EXPORT [module_name]_module = -{ - STANDARD20_MODULE_STUFF, - /* create per-directory config structures */ - /* merge per-directory config structures */ - /* create per-server config structures */ - /* merge per-server config structures */ - /* command handlers */ - /* handlers */ - /* register hooks */ - }; -</pre> - - <p>Some of these read directly across, some don't. I'll try to - summarise what should be done below.</p> - - <p>The stages that read directly across :</p> - - <ul style="list-style:none"> - <li>/* dir config creater */ ==> /* create per-directory - config structures */</li> - - <li>/* server config */ ==> /* create per-server config - structures */</li> - - <li>/* dir merger */ ==> /* merge per-directory config - structures */</li> - - <li>/* merge server config */ ==> /* merge per-server - config structures */</li> - - <li>/* command table */ ==> /* command apr_table_t */</li> - - <li>/* handlers */ ==> /* handlers */</li> - </ul> - - <p>The remainder of the old functions should be registered as - hooks. There are the following hook stages defined so - far...</p> - - <ul style="list-style:none"> - <li>ap_hook_post_config <em>(this is where the old _init - routines get registered)</em></li> - - <li>ap_hook_http_method <em>(retrieve the http method from a - request. (legacy))</em></li> - - <li>ap_hook_open_logs <em>(open any specified logs)</em></li> - - <li>ap_hook_auth_checker <em>(check if the resource requires - authorization)</em></li> - - <li>ap_hook_access_checker <em>(check for module-specific - restrictions)</em></li> - - <li>ap_hook_check_user_id <em>(check the user-id and - password)</em></li> - - <li>ap_hook_default_port <em>(retrieve the default port for - the server)</em></li> - - <li>ap_hook_pre_connection <em>(do any setup required just - before processing, but after accepting)</em></li> - - <li>ap_hook_process_connection <em>(run the correct - protocol)</em></li> - - <li>ap_hook_child_init <em>(call as soon as the child is - started)</em></li> - - <li>ap_hook_create_request <em>(??)</em></li> - - <li>ap_hook_fixups <em>(last chance to modify things before - generating content)</em></li> - - <li>ap_hook_handler <em>(generate the content)</em></li> - - <li>ap_hook_header_parser <em>(let's modules look at the - headers, not used by most modules, because they use - post_read_request for this.)</em></li> - - <li>ap_hook_insert_filter <em>(to insert filters into the - filter chain)</em></li> - - <li>ap_hook_log_transaction <em>(log information about the - request)</em></li> - - <li>ap_hook_optional_fn_retrieve <em>(retrieve any functions - registered as optional)</em></li> - - <li>ap_hook_post_read_request <em>(called after reading the - request, before any other phase)</em></li> - - <li>ap_hook_quick_handler <em>(??)</em></li> - - <li>ap_hook_translate_name <em>(translate the URI into a - filename)</em></li> - - <li>ap_hook_type_checker <em>(determine and/or set the doc - type)</em> <!--#include virtual="footer.html" --> - </li> - </ul> - </body> -</html> - diff --git a/docs/manual/dso.html.en b/docs/manual/dso.html.en deleted file mode 100644 index 41d965d671..0000000000 --- a/docs/manual/dso.html.en +++ /dev/null @@ -1,344 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> - -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta name="generator" content="HTML Tidy, see www.w3.org" /> - - <title>Dynamic Shared Object (DSO) support</title> - </head> - <!-- Background white, links blue (unvisited), navy (visited), red (active) --> - - <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" - vlink="#000080" alink="#FF0000"> - <!--#include virtual="header.html" --> - - <h1 align="center">Dynamic Shared Object (DSO) Support</h1> - - <p>The Apache HTTP Server is a modular program where the - administrator can choose the functionality to include in the - server by selecting a set of modules. The modules can be - statically compiled into the <code>httpd</code> binary when the - server is built. Alternatively, modules can be compiled as - Dynamic Shared Objects (DSOs) that exist separately from the - main <code>httpd</code> binary file. DSO modules may be - compiled at the time the server is built, or they may be - compiled and added at a later time using the Apache Extension - Tool (<a href="programs/apxs.html">apxs</a>).</p> - - <p>This document describes how to use DSO modules as well as - the theory behind their use.</p> - - <ul> - <li><a href="#implementation">Implementation</a></li> - - <li><a href="#usage">Usage Summary</a></li> - - <li><a href="#background">Background</a></li> - - <li><a href="#advantages">Advantages and - Disadvantages</a></li> - </ul> - <hr /> - - <table border="1"> - <tr> - <td valign="top"><strong>Related Modules</strong><br /> - <br /> - <a href="mod/mod_so.html">mod_so</a><br /> - </td> - - <td valign="top"><strong>Related Directives</strong><br /> - <br /> - <a href="mod/mod_so.html#loadmodule">LoadModule</a><br /> - </td> - </tr> - </table> - - <h2><a id="implementation" - name="implementation">Implementation</a></h2> - - <p>The DSO support for loading individual Apache modules is - based on a module named <a - href="mod/mod_so.html"><code>mod_so.c</code></a> which must be - statically compiled into the Apache core. It is the only module - besides <code>core.c</code> which cannot be put into a DSO - itself. Practically all other distributed Apache modules - can then be placed into a DSO by individually enabling the DSO - build for them via <code>configure</code>'s - <code>--enable-<i>module</i>=shared</code> option as disucussed - in the <a href="install.html">install documentation</a>. After - a module is compiled into a DSO named <code>mod_foo.so</code> - you can use <a href="mod/mod_so.html"><code>mod_so</code></a>'s - <a - href="mod/mod_so.html#loadmodule"><code>LoadModule</code></a> - command in your <code>httpd.conf</code> file to load this - module at server startup or restart.</p> - - <p>To simplify this creation of DSO files for Apache modules - (especially for third-party modules) a new support program - named <a href="programs/apxs.html">apxs</a> (<em>APache - eXtenSion</em>) is available. It can be used to build DSO based - modules <em>outside of</em> the Apache source tree. The idea is - simple: When installing Apache the <code>configure</code>'s - <code>make install</code> procedure installs the Apache C - header files and puts the platform-dependent compiler and - linker flags for building DSO files into the <code>apxs</code> - program. This way the user can use <code>apxs</code> to compile - his Apache module sources without the Apache distribution - source tree and without having to fiddle with the - platform-dependent compiler and linker flags for DSO - support.</p> - - <h2><a id="usage" name="usage">Usage Summary</a></h2> - - <p>To give you an overview of the DSO features of Apache 2.0, - here is a short and concise summary:</p> - - <ol> - <li> - Build and install a <em>distributed</em> Apache module, say - <code>mod_foo.c</code>, into its own DSO - <code>mod_foo.so</code>: - - <table bgcolor="#f0f0f0" cellpadding="10"> - <tr> - <td> -<pre> -$ ./configure --prefix=/path/to/install - --enable-foo=shared -$ make install -</pre> - </td> - </tr> - </table> - </li> - - <li> - Build and install a <em>third-party</em> Apache module, say - <code>mod_foo.c</code>, into its own DSO - <code>mod_foo.so</code>: - - <table bgcolor="#f0f0f0" cellpadding="10"> - <tr> - <td> -<pre> -$ ./configure --add-module=module_type:/path/to/3rdparty/mod_foo.c - --enable-foo=shared -$ make install -</pre> - </td> - </tr> - </table> - </li> - - <li> - Configure Apache for <em>later installation</em> of shared - modules: - - <table bgcolor="#f0f0f0" cellpadding="10"> - <tr> - <td> -<pre> -$ ./configure --enable-so -$ make install -</pre> - </td> - </tr> - </table> - </li> - - <li> - Build and install a <em>third-party</em> Apache module, say - <code>mod_foo.c</code>, into its own DSO - <code>mod_foo.so</code> <em>outside of</em> the Apache - source tree using <a href="programs/apxs.html">apxs</a>: - - <table bgcolor="#f0f0f0" cellpadding="10"> - <tr> - <td> -<pre> -$ cd /path/to/3rdparty -$ apxs -c mod_foo.c -$ apxs -i -a -n foo mod_foo.so -</pre> - </td> - </tr> - </table> - </li> - </ol> - - <p>In all cases, once the shared module is compiled, you must - use a <a - href="mod/mod_so.html#loadmodule"><code>LoadModule</code></a> - directive in <code>httpd.conf</code> to tell Apache to activate - the module.</p> - - <h2><a id="background" name="background">Background</a></h2> - - <p>On modern Unix derivatives there exists a nifty mechanism - usually called dynamic linking/loading of <em>Dynamic Shared - Objects</em> (DSO) which provides a way to build a piece of - program code in a special format for loading it at run-time - into the address space of an executable program.</p> - - <p>This loading can usually be done in two ways: Automatically - by a system program called <code>ld.so</code> when an - executable program is started or manually from within the - executing program via a programmatic system interface to the - Unix loader through the system calls - <code>dlopen()/dlsym()</code>.</p> - - <p>In the first way the DSO's are usually called <em>shared - libraries</em> or <em>DSO libraries</em> and named - <code>libfoo.so</code> or <code>libfoo.so.1.2</code>. They - reside in a system directory (usually <code>/usr/lib</code>) - and the link to the executable program is established at - build-time by specifying <code>-lfoo</code> to the linker - command. This hard-codes library references into the executable - program file so that at start-time the Unix loader is able to - locate <code>libfoo.so</code> in <code>/usr/lib</code>, in - paths hard-coded via linker-options like <code>-R</code> or in - paths configured via the environment variable - <code>LD_LIBRARY_PATH</code>. It then resolves any (yet - unresolved) symbols in the executable program which are - available in the DSO.</p> - - <p>Symbols in the executable program are usually not referenced - by the DSO (because it's a reusable library of general code) - and hence no further resolving has to be done. The executable - program has no need to do anything on its own to use the - symbols from the DSO because the complete resolving is done by - the Unix loader. (In fact, the code to invoke - <code>ld.so</code> is part of the run-time startup code which - is linked into every executable program which has been bound - non-static). The advantage of dynamic loading of common library - code is obvious: the library code needs to be stored only once, - in a system library like <code>libc.so</code>, saving disk - space for every program.</p> - - <p>In the second way the DSO's are usually called <em>shared - objects</em> or <em>DSO files</em> and can be named with an - arbitrary extension (although the canonical name is - <code>foo.so</code>). These files usually stay inside a - program-specific directory and there is no automatically - established link to the executable program where they are used. - Instead the executable program manually loads the DSO at - run-time into its address space via <code>dlopen()</code>. At - this time no resolving of symbols from the DSO for the - executable program is done. But instead the Unix loader - automatically resolves any (yet unresolved) symbols in the DSO - from the set of symbols exported by the executable program and - its already loaded DSO libraries (especially all symbols from - the ubiquitous <code>libc.so</code>). This way the DSO gets - knowledge of the executable program's symbol set as if it had - been statically linked with it in the first place.</p> - - <p>Finally, to take advantage of the DSO's API the executable - program has to resolve particular symbols from the DSO via - <code>dlsym()</code> for later use inside dispatch tables - <em>etc.</em> In other words: The executable program has to - manually resolve every symbol it needs to be able to use it. - The advantage of such a mechanism is that optional program - parts need not be loaded (and thus do not spend memory) until - they are needed by the program in question. When required, - these program parts can be loaded dynamically to extend the - base program's functionality.</p> - - <p>Although this DSO mechanism sounds straightforward there is - at least one difficult step here: The resolving of symbols from - the executable program for the DSO when using a DSO to extend a - program (the second way). Why? Because "reverse resolving" DSO - symbols from the executable program's symbol set is against the - library design (where the library has no knowledge about the - programs it is used by) and is neither available under all - platforms nor standardized. In practice the executable - program's global symbols are often not re-exported and thus not - available for use in a DSO. Finding a way to force the linker - to export all global symbols is the main problem one has to - solve when using DSO for extending a program at run-time.</p> - - <p>The shared library approach is the typical one, because it - is what the DSO mechanism was designed for, hence it is used - for nearly all types of libraries the operating system - provides. On the other hand using shared objects for extending - a program is not used by a lot of programs.</p> - - <p>As of 1998 there are only a few software packages available - which use the DSO mechanism to actually extend their - functionality at run-time: Perl 5 (via its XS mechanism and the - DynaLoader module), Netscape Server, <em>etc.</em> Starting - with version 1.3, Apache joined the crew, because Apache - already uses a module concept to extend its functionality and - internally uses a dispatch-list-based approach to link external - modules into the Apache core functionality. So, Apache is - really predestined for using DSO to load its modules at - run-time.</p> - - <h2><a id="advantages" name="advantages">Advantages and - Disadvantages</a></h2> - - <p>The above DSO based features have the following - advantages:</p> - - <ul> - <li>The server package is more flexible at run-time because - the actual server process can be assembled at run-time via <a - href="mod/mod_so.html#loadmodule"><code>LoadModule</code></a> - <code>httpd.conf</code> configuration commands instead of - <code>configure</code> options at build-time. For instance - this way one is able to run different server instances - (standard & SSL version, minimalistic & powered up - version [mod_perl, PHP3], <em>etc.</em>) with only one Apache - installation.</li> - - <li>The server package can be easily extended with - third-party modules even after installation. This is at least - a great benefit for vendor package maintainers who can create - a Apache core package and additional packages containing - extensions like PHP3, mod_perl, mod_fastcgi, - <em>etc.</em></li> - - <li>Easier Apache module prototyping because with the - DSO/<code>apxs</code> pair you can both work outside the - Apache source tree and only need an <code>apxs -i</code> - command followed by an <code>apachectl restart</code> to - bring a new version of your currently developed module into - the running Apache server.</li> - </ul> - - <p>DSO has the following disadvantages:</p> - - <ul> - <li>The DSO mechanism cannot be used on every platform - because not all operating systems support dynamic loading of - code into the address space of a program.</li> - - <li>The server is approximately 20% slower at startup time - because of the symbol resolving overhead the Unix loader now - has to do.</li> - - <li>The server is approximately 5% slower at execution time - under some platforms because position independent code (PIC) - sometimes needs complicated assembler tricks for relative - addressing which are not necessarily as fast as absolute - addressing.</li> - - <li>Because DSO modules cannot be linked against other - DSO-based libraries (<code>ld -lfoo</code>) on all platforms - (for instance a.out-based platforms usually don't provide - this functionality while ELF-based platforms do) you cannot - use the DSO mechanism for all types of modules. Or in other - words, modules compiled as DSO files are restricted to only - use symbols from the Apache core, from the C library - (<code>libc</code>) and all other dynamic or static libraries - used by the Apache core, or from static library archives - (<code>libfoo.a</code>) containing position independent code. - The only chances to use other code is to either make sure the - Apache core itself already contains a reference to it or - loading the code yourself via <code>dlopen()</code>.</li> - </ul> - <!--#include virtual="footer.html" --> - </body> -</html> - diff --git a/docs/manual/logs.html.en b/docs/manual/logs.html.en deleted file mode 100644 index 49ccee903a..0000000000 --- a/docs/manual/logs.html.en +++ /dev/null @@ -1,666 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> - -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta name="generator" content="HTML Tidy, see www.w3.org" /> - - <title>Log Files - Apache HTTP Server</title> - </head> - <!-- Background white, links blue (unvisited), navy (visited), red (active) --> - - <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" - vlink="#000080" alink="#FF0000"> - <!--#include virtual="header.html" --> - - <h1 align="center">Log Files</h1> - - <p>In order to effectively manage a web server, it is necessary - to get feedback about the activity and performance of the - server as well as any problems that may be occuring. The Apache - HTTP Server provides very comprehensive and flexible logging - capabilities. This document describes how to configure its - logging capabilities, and how to understand what the logs - contain.</p> - - <ul> - <li><a href="#security">Security Warning</a></li> - - <li><a href="#errorlog">Error Log</a></li> - - <li> - <a href="#accesslog">Access Log</a> - - <ul> - <li><a href="#common">Common Log Format</a></li> - - <li><a href="#combined">Combined Log Format</a></li> - - <li><a href="#multiple">Multiple Access Logs</a></li> - - <li><a href="#conditional">Conditional Logging</a></li> - </ul> - </li> - - <li><a href="#rotation">Log Rotation</a></li> - - <li><a href="#piped">Piped Logs</a></li> - - <li><a href="#virtualhosts">Virtual Hosts</a></li> - - <li> - <a href="#other">Other Log Files</a> - - <ul> - <li><a href="#pidfile">PID File</a></li> - - <li><a href="#scriptlog">Script Log</a></li> - - <li><a href="#rewritelog">Rewrite Log</a></li> - </ul> - </li> - </ul> - <hr /> - - <h2><a id="security" name="security">Security Warning</a></h2> - - <p>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.</p> - - <p>In addition, log files may contain information supplied - directly by the client, without escaping. Therefore, it is - possible for malicious clients to insert control-characters in - the log files, so care must be taken in dealing with raw - logs.</p> - <hr /> - - <h2><a id="errorlog" name="errorlog">Error Log</a></h2> - - <table border="1"> - <tr> - <td valign="top"><strong>Related Directives</strong><br /> - <br /> - <a href="mod/core.html#errorlog">ErrorLog</a><br /> - <a href="mod/core.html#loglevel">LogLevel</a> </td> - </tr> - </table> - - <p>The server error log, whose name and location is set by the - <a href="mod/core.html#errorlog">ErrorLog</a> directive, is the - most important log file. This is the place where Apache httpd - will send diagnostic information and record any errors that it - encounters in processing requests. It is the first place to - look when a problem occurs with starting the server or with the - operation of the server, since it will often contain details of - what went wrong and how to fix it.</p> - - <p>The error log is usually written to a file (typically - <code>error_log</code> on unix systems and - <code>error.log</code> on Windows and OS/2). On unix systems it - is also possible to have the server send errors to - <code>syslog</code> or <a href="#piped">pipe them to a - program</a>.</p> - - <p>The format of the error log is relatively free-form and - descriptive. But there is certain information that is contained - in most error log entries. For example, here is a typical - message.</p> - - <blockquote> - <code>[Wed Oct 11 14:32:52 2000] [error] [client 127.0.0.1] - client denied by server configuration: - /export/home/live/ap/htdocs/test</code> - </blockquote> - - <p>The first item in the log entry is the date and time of the - message. The second entry lists the severity of the error being - reported. The <a href="mod/core.html#loglevel">LogLevel</a> - directive is used to control the types of errors that are sent - to the error log by restricting the severity level. The third - entry gives the IP address of the client that generated the - error. Beyond that is the message itself, which in this case - indicates that the server has been configured to deny the - client access. The server reports the file-system path (as - opposed to the web path) of the requested document.</p> - - <p>A very wide variety of different messages can appear in the - error log. Most look similar to the example above. The error - log will also contain debugging output from CGI scripts. Any - information written to <code>stderr</code> by a CGI script will - be copied directly to the error log.</p> - - <p>It is not possible to customize the error log by adding or - removing information. However, error log entries dealing with - particular requests have corresponding entries in the <a - href="#accesslog">access log</a>. For example, the above example - entry corresponds to an access log entry with status code 403. - Since it is possible to customize the access log, you can - obtain more information about error conditions using that log - file.</p> - - <p>During testing, it is often useful to continuously monitor - the error log for any problems. On unix systems, you can - accomplish this using:</p> - - <blockquote> - <code>tail -f error_log</code> - </blockquote> - <hr /> - - <h2><a id="accesslog" name="accesslog">Access Log</a></h2> - - <table border="1"> - <tr> - <td valign="top"><strong>Related Modules</strong><br /> - <br /> - <a href="mod/mod_log_config.html">mod_log_config</a><br /> - </td> - - <td valign="top"><strong>Related Directives</strong><br /> - <br /> - <a - href="mod/mod_log_config.html#customlog">CustomLog</a><br /> - <a - href="mod/mod_log_config.html#logformat">LogFormat</a><br /> - <a href="mod/mod_setenvif.html#setenvif">SetEnvIf</a> - </td> - </tr> - </table> - - <p>The server access log records all requests processed by the - server. The location and content of the access log are - controlled by the <a - href="mod/mod_log_config.html#customlog">CustomLog</a> - directive. The <a - href="mod/mod_log_config.html#logformat">LogFormat</a> - directive can be used to simplify the selection of the contents - of the logs. This section describes how to configure the server - to record information in the access log.</p> - - <p>Of course, storing the information in the access log is only - the start of log management. The next step is to analyze this - information to produce useful statistics. Log analysis in - general is beyond the scope of this document, and not really - part of the job of the web server itself. For more information - about this topic, and for applications which perform log - analysis, check the <a - href="http://dmoz.org/Computers/Software/Internet/Site_Management/Log_analysis/"> - Open Directory</a> or <a - href="http://dir.yahoo.com/Computers_and_Internet/Software/Internet/World_Wide_Web/Servers/Log_Analysis_Tools/"> - Yahoo</a>.</p> - - <p>Various versions of Apache httpd have used other modules and - directives to control access logging, including - mod_log_referer, mod_log_agent, and the - <code>TransferLog</code> directive. The <code>CustomLog</code> - directive now subsumes the functionality of all the older - directives.</p> - - <p>The format of the access log is highly configurable. The - format is specified using a <a - href="mod/mod_log_config.html#format">format string</a> that - looks much like a C-style printf(1) format string. Some - examples are presented in the next sections. For a complete - list of the possible contents of the format string, see the <a - href="mod/mod_log_config.html">mod_log_config - documentation</a>.</p> - - <h3><a id="common" name="common">Common Log Format</a></h3> - - <p>A typical configuration for the access log might look as - follows.</p> - - <blockquote> - <code>LogFormat "%h %l %u %t \"%r\" %>s %b" common<br /> - CustomLog logs/access_log common</code> - </blockquote> - - <p>This defines the <em>nickname</em> <code>common</code> and - associates it with a particular log format string. The format - string consists of percent directives, each of which tell the - server to log a particular piece of information. Literal - characters may also be placed in the format string and will be - copied directly into the log output. The quote character - (<code>"</code>) must be escaped by placing a back-slash before - it to prevent it from being interpreted as the end of the - format string. The format string may also contain the special - control characters "<code>\n</code>" for new-line and - "<code>\t</code>" for tab.</p> - - <p>The <code>CustomLog</code> directive sets up a new log file - using the defined <em>nickname</em>. The filename for the - access log is relative to the <a - href="mod/core.html#serverroot">ServerRoot</a> unless it begins - with a slash.</p> - - <p>The above configuration will write log entries in a format - known as the Common Log Format (CLF). This standard format can - be produced by many different web servers and read by many log - analysis programs. The log file entries produced in CLF will - look something like this:</p> - - <blockquote> - <code>127.0.0.1 - frank [10/Oct/2000:13:55:36 -0700] "GET - /apache_pb.gif HTTP/1.0" 200 2326</code> - </blockquote> - - <p>Each part of this log entry is described below.</p> - - <dl> - <dt><code>127.0.0.1</code> (<code>%h</code>)</dt> - - <dd>This is the IP address of the client (remote host) which - made the request to the server. If <a - href="mod/core.html#hostnamelookups">HostnameLookups</a> is - set to <code>On</code>, then the server will try to determine - the hostname and log it in place of the IP address. However, - this configuration is not recommended since it can - significantly slow the server. Instead, it is best to use a - log post-processor such as <a - href="programs/logresolve.html">logresolve</a> to determine - the hostnames. The IP address reported here is not - necessarily the address of the machine at which the user is - sitting. If a proxy server exists between the user and the - server, this address will be the address of the proxy, rather - than the originating machine.</dd> - - <dt><code>-</code> (<code>%l</code>)</dt> - - <dd>The "hyphen" in the output indicates that the requested - piece of information is not available. In this case, the - information that is not available is the RFC 1413 identity of - the client determined by <code>identd</code> on the clients - machine. This information is highly unreliable and should - almost never be used except on tightly controlled internal - networks. Apache httpd will not even attempt to determine - this information unless <a - href="mod/core.html#identitycheck">IdentityCheck</a> is set - to <code>On</code>.</dd> - - <dt><code>frank</code> (<code>%u</code>)</dt> - - <dd>This is the userid of the person requesting the document - as determined by HTTP authentication. The same value is - typically provided to CGI scripts in the - <code>REMOTE_USER</code> environment variable. If the status - code for the request (see below) is 401, then this value - should not be trusted because the user is not yet - authenticated. If the document is not password protected, - this entry will be "<code>-</code>" just like the previous - one.</dd> - - <dt><code>[10/Oct/2000:13:55:36 -0700]</code> - (<code>%t</code>)</dt> - - <dd> - The time that the server finished processing the request. - The format is: - - <blockquote> - <code>[day/month/year:hour:minute:second zone]<br /> - day = 2*digit<br /> - month = 3*letter<br /> - year = 4*digit<br /> - hour = 2*digit<br /> - minute = 2*digit<br /> - second = 2*digit<br /> - zone = (`+' | `-') 4*digit</code> - </blockquote> - It is possible to have the time displayed in another format - by specifying <code>%{format}t</code> in the log format - string, where <code>format</code> is as in - <code>strftime(3)</code> from the C standard library. - </dd> - - <dt><code>"GET /apache_pb.gif HTTP/1.0"</code> - (<code>\"%r\"</code>)</dt> - - <dd>The request line from the client is given in double - quotes. The request line contains a great deal of useful - information. First, the method used by the client is - <code>GET</code>. Second, the client requested the resource - <code>/apache_pb.gif</code>, and third, the client used the - protocol <code>HTTP/1.0</code>. It is also possible to log - one or more parts of the request line independently. For - example, the format string "<code>%m %U%q %H</code>" will log - the method, path, query-string, and protocol, resulting in - exactly the same output as "<code>%r</code>".</dd> - - <dt><code>200</code> (<code>%>s</code>)</dt> - - <dd>This is the status code that the server sends back to the - client. This information is very valuable, because it reveals - whether the request resulted in a successful response (codes - beginning in 2), a redirection (codes beginning in 3), an - error caused by the client (codes beginning in 4), or an - error in the server (codes beginning in 5). The full list of - possible status codes can be found in the <a - href="http://www.w3.org/Protocols/rfc2616/rfc2616.txt">HTTP - specification</a> (RFC2616 section 10).</dd> - - <dt><code>2326</code> (<code>%b</code>)</dt> - - <dd>The last entry indicates the size of the object returned - to the client, not including the response headers. If no - content was returned to the client, this value will be - "<code>-</code>". To log "<code>0</code>" for no content, use - <code>%B</code> instead.</dd> - </dl> - - <h4><a id="combined" name="combined">Combined Log - Format</a></h4> - - <p>Another commonly used format string is called the Combined - Log Format. It can be used as follows.</p> - - <blockquote> - <code>LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" - \"%{User-agent}i\"" combined<br /> - CustomLog log/acces_log combined</code> - </blockquote> - - <p>This format is exactly the same as the Common Log Format, - with the addition of two more fields. Each of the additional - fields uses the percent-directive - <code>%{<em>header</em>}i</code>, where <em>header</em> can be - any HTTP request header. The access log under this format will - look like:</p> - - <blockquote> - <code>127.0.0.1 - frank [10/Oct/2000:13:55:36 -0700] "GET - /apache_pb.gif HTTP/1.0" 200 2326 - "http://www.example.com/start.html" "Mozilla/4.08 [en] - (Win98; I ;Nav)"</code> - </blockquote> - - <p>The additional fields are:</p> - - <dl> - <dt><code>"http://www.example.com/start.html"</code> - (<code>\"%{Referer}i\"</code>)</dt> - - <dd>The "Referer" (sic) HTTP request header. This gives the - site that the client reports having been referred from. (This - should be the page that links to or includes - <code>/apache_pb.gif</code>).</dd> - - <dt><code>"Mozilla/4.08 [en] (Win98; I ;Nav)"</code> - (<code>\"%{User-agent}i\"</code>)</dt> - - <dd>The User-Agent HTTP request header. This is the - identifying information that the client browser reports about - itself.</dd> - </dl> - - <h3><a id="multiple" name="multiple">Multiple Access - Logs</a></h3> - - <p>Multiple access logs can be created simply by specifying - multiple <code>CustomLog</code> directives in the configuration - file. For example, the following directives will create three - access logs. The first contains the basic CLF information, - while the second and third contain referer and browser - information. The last two <code>CustomLog</code> lines show how - to mimic the effects of the <code>ReferLog</code> and - <code>AgentLog</code> directives.</p> - - <blockquote> - <code>LogFormat "%h %l %u %t \"%r\" %>s %b" common<br /> - CustomLog logs/access_log common<br /> - CustomLog logs/referer_log "%{Referer}i -> %U"<br /> - CustomLog logs/agent_log "%{User-agent}i"</code> - </blockquote> - - <p>This example also shows that it is not necessary to define a - nickname with the <code>LogFormat</code> directive. Instead, - the log format can be specified directly in the - <code>CustomLog</code> directive.</p> - - <h3><a id="conditional" name="conditional">Conditional - Logging</a></h3> - - <p>There are times when it is convenient to exclude certain - entries from the access logs based on characteristics of the - client request. This is easily accomplished with the help of <a - href="env.html">environment variables</a>. First, an - environment variable must be set to indicate that the request - meets certain conditions. This is usually accomplished with <a - href="mod/mod_setenvif.html#setenvif">SetEnvIf</a>. Then the - <code>env=</code> clause of the <code>CustomLog</code> - directive is used to include or exclude requests where the - environment variable is set. Some examples:</p> - - <blockquote> - <code># Mark requests from the loop-back interface<br /> - SetEnvIf Remote_Addr "127\.0\.0\.1" dontlog<br /> - # Mark requests for the robots.txt file<br /> - SetEnvIf Request_URI "^/robots\.txt$" dontlog<br /> - # Log what remains<br /> - CustomLog logs/access_log common env=!dontlog</code> - </blockquote> - - <p>As another example, consider logging requests from - english-speakers to one log file, and non-english speakers to a - different log file.</p> - - <blockquote> - <code>SetEnvIf Accept-Language "en" english<br /> - CustomLog logs/english_log common env=english<br /> - CustomLog logs/non_english_log common env=!english</code> - </blockquote> - - <p>Although we have just shown that conditional logging is very - powerful and flexibly, it is not the only way to control the - contents of the logs. Log files are more useful when they - contain a complete record of server activity. It is often - easier to simply post-process the log files to remove requests - that you do not want to consider.</p> - <hr /> - - <h2><a id="rotation" name="rotation">Log Rotation</a></h2> - - <p>On even a moderately busy server, the quantity of - information stored in the log files is very large. The access - log file typically grows 1 MB or more per 10,000 requests. It - will consequently be necessary to periodically rotate the log - files by moving or deleting the existing logs. This cannot be - done while the server is running, because Apache will continue - writing to the old log file as long as it holds the file open. - Instead, the server must be <a - href="stopping.html">restarted</a> after the log files are - moved or deleted so that it will open new log files.</p> - - <p>By using a <em>graceful</em> restart, the server can be - instructed to open new log files without losing any existing or - pending connections from clients. However, in order to - accomplish this, the server must continue to write to the old - log files while it finishes serving old requests. It is - therefore necessary to wait for some time after the restart - before doing any processing on the log files. A typical - scenario that simply rotates the logs and compresses the old - logs to save space is:</p> - - <blockquote> - <code>mv access_log access_log.old<br /> - mv error_log error_log.old<br /> - apachectl graceful<br /> - sleep 600<br /> - gzip access_log.old error_log.old</code> - </blockquote> - - <p>Another way to perform log rotation is using <a - href="#piped">piped logs</a> as discussed in the next - section.</p> - <hr /> - - <h2><a id="piped" name="piped">Piped Logs</a></h2> - - <p>Apache httpd is capable of writing error and access log - files through a pipe to another process, rather than directly - to a file. This capability dramatically increases the - flexibility of logging, without adding code to the main server. - In order to write logs to a pipe, simply replace the filename - with the pipe character "<code>|</code>", followed by the name - of the executable which should accept log entries on its - standard input. Apache will start the piped-log process when - the server starts, and will restart it if it crashes while the - server is running. (This last feature is why we can refer to - this technique as "reliable piped logging".)</p> - - <p>Piped log processes are spawned by the parent Apache httpd - process, and inherit the userid of that process. This means - that piped log programs usually run as root. It is therefore - very important to keep the programs simple and secure.</p> - - <p>Some simple examples using piped logs:</p> - - <blockquote> - <code># compressed logs<br /> - CustomLog "|/usr/bin/gzip -c >> - /var/log/access_log.gz" common<br /> - # almost-real-time name resolution<br /> - CustomLog "|/usr/local/apache/bin/logresolve >> - /var/log/access_log" common</code> - </blockquote> - - <p>Notice that quotes are used to enclose the entire command - that will be called for the pipe. Although these examples are - for the access log, the same technique can be used for the - error log.</p> - - <p>One important use of piped logs is to allow log rotation - without having to restart the server. The Apache HTTP Server - includes a simple program called <a - href="programs/rotatelogs.html">rotatelogs</a> for this - purpose. For example, to rotate the logs every 24 hours, you - can use:</p> - - <blockquote> - <code>CustomLog "|/usr/local/apache/bin/rotatelogs - /var/log/access_log 86400" common</code> - </blockquote> - - <p>A similar, but much more flexible log rotation program - called <a href="http://www.cronolog.org/">cronolog</a> - is available at an external site.</p> - - <p>As with conditional logging, piped logs are a very powerful - tool, but they should not be used where a simpler solution like - off-line post-processing is available.</p> - <hr /> - - <h2><a id="virtualhosts" name="virtualhosts">Virtual - Hosts</a></h2> - - <p>When running a server with many <a href="vhosts/">virtual - hosts</a>, there are several options for dealing with log - files. First, it is possible to use logs exactly as in a - single-host server. Simply by placing the logging directives - outside the <code><VirtualHost></code> sections in the - main server context, it is possible to log all requests in the - same access log and error log. This technique does not allow - for easy collection of statistics on individual virtual - hosts.</p> - - <p>If <code>CustomLog</code> or <code>ErrorLog</code> - directives are placed inside a <code><VirtualHost></code> - section, all requests or errors for that virtual host will be - logged only to the specified file. Any virtual host which does - not have logging directives will still have its requests sent - to the main server logs. This technique is very useful for a - small number of virtual hosts, but if the number of hosts is - very large, it can be complicated to manage. In addition, it - can often create problems with <a - href="vhosts/fd-limits.html">insufficient file - descriptors</a>.</p> - - <p>For the access log, there is a very good compromise. By - adding information on the virtual host to the log format - string, it is possible to log all hosts to the same log, and - later split the log into individual files. For example, - consider the following directives.</p> - - <blockquote> - <code>LogFormat "%v %l %u %t \"%r\" %>s %b" - comonvhost<br /> - CustomLog logs/access_log comonvhost</code> - </blockquote> - - <p>The <code>%v</code> is used to log the name of the virtual - host that is serving the request. Then a program like <a - href="programs/other.html">split-logfile</a> can be used to - post-process the access log in order to split it into one file - per virtual host.</p> - - <p>Unfortunately, no similar technique is available for the - error log, so you must choose between mixing all virtual hosts - in the same error log and using one error log per virtual - host.</p> - <hr /> - - <h2><a id="other" name="other">Other Log Files</a></h2> - - <table border="1"> - <tr> - <td valign="top"><strong>Related Modules</strong><br /> - <br /> - <a href="mod/mod_cgi.html">mod_cgi</a><br /> - <a href="mod/mod_rewrite.html">mod_rewrite</a> </td> - - <td valign="top"><strong>Related Directives</strong><br /> - <br /> - <a href="mod/core.html#pidfile">PidFile</a><br /> - <a - href="mod/mod_rewrite.html#RewriteLog">RewriteLog</a><br /> - <a - href="mod/mod_rewrite.html#RewriteLogLevel">RewriteLogLevel</a><br /> - <a href="mod/mod_cgi.html#scriptlog">ScriptLog</a><br /> - <a - href="mod/mod_cgi.html#scriptloglength">ScriptLogLength</a><br /> - <a - href="mod/mod_cgi.html#scriptlogbuffer">ScriptLogBuffer</a> - </td> - </tr> - </table> - - <h3><a id="pidfile" name="pidfile">PID File</a></h3> - - <p>On startup, Apache httpd 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 by sending signals to the parent - process; on Windows, use the -k command line option instead. - For more information see the <a href="stopping.html">Stopping - and Restarting</a> page.</p> - - <h3><a id="scriptlog" name="scriptlog">Script Log</a></h3> - - <p>In order to aid in debugging, the <a - href="mod/mod_cgi.html#scriptlog">ScriptLog</a> directive - allows you to record the input to and output from CGI scripts. - This should only be used in testing - not for live servers. - More information is available in the <a - href="mod/mod_cgi.html">mod_cgi documentation</a>.</p> - - <h3><a id="rewritelog" name="rewritelog">Rewrite Log</a></h3> - - <p>When using the powerful and complex features of <a - href="mod/mod_rewrite.html">mod_rewrite</a>, it is almost - always necessary to use the <a - href="mod/mod_rewrite.html#RewriteLog">RewriteLog</a> to help - in debugging. This log file produces a detailed analysis of how - the rewriting engine transforms requests. The level of detail - is controlled by the <a - href="mod/mod_rewrite.html#RewriteLogLevel">RewriteLogLevel</a> - directive.</p> - <!--#include virtual="footer.html" --> - </body> -</html> - diff --git a/docs/manual/mod/directive-dict.html.en b/docs/manual/mod/directive-dict.html.en deleted file mode 100644 index deedf08aca..0000000000 --- a/docs/manual/mod/directive-dict.html.en +++ /dev/null @@ -1,327 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> - -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta name="generator" content="HTML Tidy, see www.w3.org" /> - - <title>Definitions of terms used to describe Apache - directives</title> - </head> - <!-- Background white, links blue (unvisited), navy (visited), red (active) --> - - <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" - vlink="#000080" alink="#FF0000"> - <!--#include virtual="header.html" --> - - <h1 align="CENTER">Terms Used to Describe Apache - Directives</h1> - - <p>Each Apache configuration directive is described using a - common format that looks like this:</p> - - <dl> - <dd><a href="#Syntax" rel="Help"><strong>Syntax:</strong></a> - <em>directive-name</em> <em>some args</em><br /> - <a href="#Default" rel="Help"><strong>Default:</strong></a> - <samp><em>directive-name default-value</em></samp><br /> - <a href="#Context" rel="Help"><strong>Context:</strong></a> - <em>context-list</em><br /> - <a href="#Override" - rel="Help"><strong>Override:</strong></a> - <em>override</em><br /> - <a href="#Status" rel="Help"><strong>Status:</strong></a> - <em>status</em><br /> - <a href="#Module" rel="Help"><strong>Module:</strong></a> - <em>module-name</em><br /> - <a href="#Compatibility" - rel="Help"><strong>Compatibility:</strong></a> - <em>compatibility notes</em><br /> - <a href="#Deprecated" - rel="Help"><strong>Deprecated:</strong></a> <em>see - other</em></dd> - </dl> - - <p>Each of the directive's attributes, complete with possible - values where possible, are described in this document.</p> - - <h2>Directive Terms</h2> - - <ul> - <li><a href="#Syntax">Syntax</a></li> - - <li><a href="#Default">Default</a></li> - - <li><a href="#Context">Context</a></li> - - <li><a href="#Override">Override</a></li> - - <li><a href="#Status">Status</a></li> - - <li><a href="#Module">Module</a></li> - - <li><a href="#Compatibility">Compatibility</a></li> - - <li><a href="#Deprecated">Deprecated</a></li> - </ul> - <hr /> - - <h2><a id="Syntax" name="Syntax">Syntax</a></h2> - - <p>This indicates the format of the directive as it would - appear in a configuration file. This syntax is extremely - directive-specific, and is described in detail in the - directive's definition. Generally, the directive name is - followed by a series of one or more space-separated arguments. - If an argument contains a space, the argument must be enclosed - in double quotes. Optional arguments are enclosed in square - brackets. Where an argument can take on more than one possible - value, the possible values are separated by vertical bars "|". - Literal text is presented in the default font, while - argument-types for which substitution is necessary are - <em>emphasized</em>. Directives which can take a variable - number of arguments will end in "..." indicating that the last - argument is repeated.</p> - - <p>Directives use a great number of different argument types. A - few common ones are defined below.</p> - - <dl> - <dt><em>URL</em></dt> - - <dd>A complete Uniform Resource Locator including a scheme, - hostname, and optional pathname as in - <code>http://www.example.com/path/to/file.html</code></dd> - - <dt><em>URL-path</em></dt> - - <dd>The part of a <em>url</em> which follows the scheme and - hostname as in <code>/path/to/file.html</code>. The - <em>url-path</em> represents a web-view of a resource, as - opposed to a file-system view.</dd> - - <dt><em>file-path</em></dt> - - <dd>The path to a file in the local file-system beginning - with the root directory as in - <code>/usr/local/apache/htdocs/path/to/file.html</code>. - Unless otherwise specified, a <em>file-path</em> which does - not begin with a slash will be treated as relative to the <a - href="core.html#serverroot">ServerRoot</a>.</dd> - - <dt><em>directory-path</em></dt> - - <dd>The path to a directory in the local file-system - beginning with the root directory as in - <code>/usr/local/apache/htdocs/path/to/</code>.</dd> - - <dt><em>filename</em></dt> - - <dd>The name of a file with no accompanying path information - as in <code>file.html</code>.</dd> - - <dt><em>regex</em></dt> - - <dd>A regular expression, which is a way of describing a - pattern to match in text. The directive definition will - specify what the <em>regex</em> is matching against.</dd> - - <dt><em>extension</em></dt> - - <dd>In general, this is the part of the <em>filename</em> - which follows the last dot. However, Apache recognizes - multiple filename extensions, so if a <em>filename</em> - contains more than one dot, each dot-separated part of the - filename following the first dot is an <em>extension</em>. - For example, the <em>filename</em> <code>file.html.en</code> - contains two extensions: <code>.html</code> and - <code>.en</code>. For Apache directives, you may specify - <em>extension</em>s with or without the leading dot. In - addition, <em>extension</em>s are not case sensitive.</dd> - - <dt><em>MIME-type</em></dt> - - <dd>A method of describing the format of a file which - consists of a major format type and a minor format type, - separated by a slash as in <code>text/html</code>.</dd> - - <dt><em>env-variable</em></dt> - - <dd>The name of an <a href="../env.html">environment - variable</a> defined in the Apache configuration process. - Note this is not necessarily the same as an operating system - environment variable. See the <a - href="../env.html">environment variable documentation</a> for - more details.</dd> - </dl> - <hr /> - - <h2><a id="Default" name="Default">Default</a></h2> - - <p>If the directive has a default value (<em>i.e.</em>, if you - omit it from your configuration entirely, the Apache Web server - will behave as though you set it to a particular value), it is - described here. If there is no default value, this section - should say "<em>None</em>". Note that the default listed here - is not necessarily the same as the value the directive takes in - the default httpd.conf distributed with the server.</p> - <hr /> - - <h2><a id="Context" name="Context">Context</a></h2> - - <p>This indicates where in the server's configuration files the - directive is legal. It's a comma-separated list of one or more - of the following values:</p> - - <dl> - <dt><strong>server config</strong></dt> - - <dd>This means that the directive may be used in the server - configuration files (<em>e.g.</em>, <samp>httpd.conf</samp>, - <samp>srm.conf</samp>, and <samp>access.conf</samp>), but - <strong>not</strong> within any - <samp><VirtualHost></samp> or <Directory> - containers. It is not allowed in <samp>.htaccess</samp> files - at all.</dd> - - <dt><strong>virtual host</strong></dt> - - <dd>This context means that the directive may appear inside - <samp><VirtualHost></samp> containers in the server - configuration files.</dd> - - <dt><strong>directory</strong></dt> - - <dd>A directive marked as being valid in this context may be - used inside <samp><Directory></samp>, - <samp><Location></samp>, and <samp><Files></samp> - containers in the server configuration files, subject to the - restrictions outlined in <a href="../sections.html">How - Directory, Location and Files sections work</a>.</dd> - - <dt><strong>.htaccess</strong></dt> - - <dd>If a directive is valid in this context, it means that it - can appear inside <em>per</em>-directory - <samp>.htaccess</samp> files. It may not be processed, though - depending upon the <a href="#Override" - rel="Help">overrides</a> currently active.</dd> - </dl> - - <p>The directive is <em>only</em> allowed within the designated - context; if you try to use it elsewhere, you'll get a - configuration error that will either prevent the server from - handling requests in that context correctly, or will keep the - server from operating at all -- <em>i.e.</em>, the server won't - even start.</p> - - <p>The valid locations for the directive are actually the - result of a Boolean OR of all of the listed contexts. In other - words, a directive that is marked as being valid in - "<samp>server config, .htaccess</samp>" can be used in the - <samp>httpd.conf</samp> file and in <samp>.htaccess</samp> - files, but not within any <Directory> or - <VirtualHost> containers.</p> - <hr /> - - <h2><a id="Override" name="Override">Override</a></h2> - - <p>This directive attribute indicates which configuration - override must be active in order for the directive to be - processed when it appears in a <samp>.htaccess</samp> file. If - the directive's <a href="#Context" rel="Help">context</a> - doesn't permit it to appear in <samp>.htaccess</samp> files, - this attribute should say "<em>Not applicable</em>".</p> - - <p>Overrides are activated by the <a - href="core.html#allowoverride" - rel="Help"><samp>AllowOverride</samp></a> directive, and apply - to a particular scope (such as a directory) and all - descendants, unless further modified by other - <samp>AllowOverride</samp> directives at lower levels. The - documentation for that directive also lists the possible - override names available.</p> - <hr /> - - <h2><a id="Status" name="Status">Status</a></h2> - - <p>This indicates how tightly bound into the Apache Web server - the directive is; in other words, you may need to recompile the - server with an enhanced set of modules in order to gain access - to the directive and its functionality. Possible values for - this attribute are:</p> - - <dl> - <dt><strong>Core</strong></dt> - - <dd>If a directive is listed as having "Core" status, that - means it is part of the innermost portions of the Apache Web - server, and is always available.</dd> - - <dt><strong>MPM</strong></dt> - - <dd>A directive labeled as having "MPM" status is provided by - a <a href="../mpm.html">Multi-Processing Module</a>. This - type of directive will be available if and only if you are - using one of the MPMs listed on the <a - href="#Module">Module</a> line of the directive - definition.</dd> - - <dt><strong>Base</strong></dt> - - <dd>A directive labeled as having "Base" status is supported - by one of the standard Apache modules which is compiled into - the server by default, and is therefore normally available - unless you've taken steps to remove the module from your - configuration.</dd> - - <dt><strong>Extension</strong></dt> - - <dd>A directive with "Extension" status is provided by one of - the modules included with the Apache server kit, but the - module isn't normally compiled into the server. To enable the - directive and its functionality, you will need to change the - server build configuration files and re-compile Apache.</dd> - - <dt><strong>Experimental</strong></dt> - - <dd>"Experimental" status indicates that the directive is - available as part of the Apache kit, but you're on your own - if you try to use it. The directive is being documented for - completeness, and is not necessarily supported. The module - which provides the directive may or may not be compiled in by - default; check the top of the page which describes the - directive and its module to see if it remarks on the - availability.</dd> - </dl> - <hr /> - - <h2><a id="Module" name="Module">Module</a></h2> - - <p>This quite simply lists the name of the source module which - defines the directive.</p> - <hr /> - - <h2><a id="Compatibility" - name="Compatibility">Compatibility</a></h2> - - <p>If the directive wasn't part of the original Apache version - 1 distribution, the version in which it was introduced should - be listed here. If the directive has the same name as one from - the NCSA HTTPd server, any inconsistencies in behavior between - the two should also be mentioned. Otherwise, this attribute - should say "<em>No compatibility issues.</em>"</p> - <hr /> - - <h2><a id="Deprecated" name="Deprecated">Deprecated</a></h2> - - <p>If this directive is eliminated since the Apache version 1 - distribution, the directive or option that replaces the - behavior should be cited here. In general, directives, - features, and options are only deprecated to minimize debugging - of conflicting features, or if the feature can only continue to - be supported in an alternate manner.</p> - <!--#include virtual="footer.html" --> - </body> -</html> - diff --git a/docs/manual/mod/module-dict.html.en b/docs/manual/mod/module-dict.html.en deleted file mode 100644 index 5e7cadb821..0000000000 --- a/docs/manual/mod/module-dict.html.en +++ /dev/null @@ -1,123 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> - -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta name="generator" content="HTML Tidy, see www.w3.org" /> - - <title>Definitions of terms used to describe Apache - modules</title> - </head> - <!-- Background white, links blue (unvisited), navy (visited), red (active) --> - - <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" - vlink="#000080" alink="#FF0000"> - <!--#include virtual="header.html" --> - - <h1 align="CENTER">Terms Used to Describe Apache Modules</h1> - - <p>Each Apache module is described using a common format that - looks like this:</p> - - <dl> - <dd><a href="#Status" rel="Help"><strong>Status:</strong></a> - <em>status</em><br /> - <a href="#SourceFile" rel="Help"><strong>Source - File:</strong></a> <em>source-file</em><br /> - <a href="#ModuleIdentifier" rel="Help"><strong>Module - Identifier:</strong></a> <em>module-identifier</em><br /> - <a href="#Compatibility" - rel="Help"><strong>Compatibility:</strong></a> - <em>compatibility notes</em></dd> - </dl> - - <p>Each of the attributes, complete with values where possible, - are described in this document.</p> - - <h2>Module Terms</h2> - - <ul> - <li><a href="#Status">Status</a></li> - - <li><a href="#SourceFile">Source File</a></li> - - <li><a href="#ModuleIdentifier">Module Identifier</a></li> - - <li><a href="#Compatibility">Compatibility</a></li> - </ul> - <hr /> - - <h2><a id="Status" name="Status">Status</a></h2> - - <p>This indicates how tightly bound into the Apache Web server - the module is; in other words, you may need to recompile the - server in order to gain access to the module and its - functionality. Possible values for this attribute are:</p> - - <dl> - <dt><strong>MPM</strong></dt> - - <dd>A module with status "MPM" is a <a - href="../mpm.html">Multi-Processing Module</a>. Unlike the - other types of modules, Apache must have one and only one MPM - in use at any time. This type of module is responsible for - basic request handling and dispatching.</dd> - - <dt><strong>Base</strong></dt> - - <dd>A module labeled as having "Base" status is compiled and - loaded into the server by default, and is therefore normally - available unless you have taken steps to remove the module - from your configuration.</dd> - - <dt><strong>Extension</strong></dt> - - <dd>A module with "Extension" status is not normally compiled - and loaded into the server. To enable the module and its - functionality, you may need to change the server build - configuration files and re-compile Apache.</dd> - - <dt><strong>Experimental</strong></dt> - - <dd>"Experimental" status indicates that the module is - available as part of the Apache kit, but you are on your own - if you try to use it. The module is being documented for - completeness, and is not necessarily supported.</dd> - - <dt><strong>External</strong></dt> - - <dd>Modules which are not included with the base Apache - distribution ("third-party modules") may use the "External" - status. We are not responsible for, nor do we support such - modules.</dd> - </dl> - <hr /> - - <h2><a id="SourceFile" name="SourceFile">Source File</a></h2> - - <p>This quite simply lists the name of the source file which - contains the code for the module. This is also the name used by - the <a - href="core.html#ifmodule"><code><IfModule></code></a> - directive.</p> - <hr /> - - <h2><a id="ModuleIdentifier" name="ModuleIdentifier">Module - Identifier</a></h2> - - <p>This is a string which identifies the module for use in the - <a href="mod_so.html#loadmodule">LoadModule</a> directive when - dynamically loading modules. In particular, it is the name of - the external variable of type module in the source file.</p> - <hr /> - - <h2><a id="Compatibility" - name="Compatibility">Compatibility</a></h2> - - <p>If the module was not part of the original Apache version 2 - distribution, the version in which it was introduced should be - listed here.</p> - <!--#include virtual="footer.html" --> - </body> -</html> - diff --git a/docs/manual/sitemap.html.en b/docs/manual/sitemap.html.en deleted file mode 100644 index d1f27cb89f..0000000000 --- a/docs/manual/sitemap.html.en +++ /dev/null @@ -1,201 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> - -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <title>Site Map - Apache HTTP Server 2.0</title> - </head> - <!-- Background white, links blue (unvisited), navy (visited), red (active) --> - - <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" - vlink="#000080" alink="#FF0000"> - <!--#include virtual="header.html" --> - - <h1 align="center">Site Map</h1> - -<ul> -<li><a href="index.html">Apache HTTP Server Version 2.0 Documentation</a> - -<ul> -<li>Release Notes -<ul> -<li><a href="upgrading.html">Upgrading to 2.0 from 1.3</a></li> -<li><a href="new_features_2_0.html">New features with Apache 2.0</a></li> -</ul></li> - -<li>Using the Apache HTTP Server -<ul> -<li><a href="install.html">Compiling and Installing Apache</a></li> -<li><a href="invoking.html">Starting Apache</a></li> -<li><a href="stopping.html">Stopping and Restarting the Server</a></li> -<li><a href="configuring.html">Configuration Files</a></li> -<li><a href="sections.html">How Directory, Location and Files sections work</a></li> -<li><a href="server-wide.html">Server-Wide Configuration</a></li> -<li><a href="logs.html">Log Files</a></li> -<li><a href="urlmapping.html">Mapping URLs to Filesystem Locations</a></li> -<li><a href="misc/security_tips.html">Security Tips</a></li> -<li><a href="dso.html">Dynamic Shared Object (DSO) support</a></li> -<li><a href="content-negotiation.html">Content Negotiation</a></li> -<li><a href="custom-error.html">Custom error responses</a></li> -<li><a href="bind.html">Setting which addresses and ports Apache uses</a></li> -<li><a href="mpm.html">Multi-Processing Modules (MPMs)</a></li> -<li><a href="env.html">Environment Variables in Apache</a></li> -<li><a href="handler.html">Apache's Handler Use</a></li> -<li><a href="filter.html">Filters</a></li> -<li><a href="suexec.html">suEXEC Support</a></li> -<li><a href="misc/perf-tuning.html">Performance Hintes</a></li> -<li><a href="misc/rewriteguide.html">URL Rewriting Guide</a></li> -</ul></li> - -<li><a href="vhosts/">Apache Virtual Host documentation</a> -<ul> -<li><a href="vhosts/name-based.html">Name-based Virtual Hosts</a></li> -<li><a href="vhosts/ip-based.html">IP-based Virtual Host Support</a></li> -<li><a href="vhosts/mass.html">Dynamically configured mass virtual hosting</a></li> -<li><a href="vhosts/examples.html">VirtualHost Examples</a></li> -<li><a href="vhosts/details.html">An In-Depth Discussion of Virtual Host Matching</a></li> -<li><a href="vhosts/fd-limits.html">File descriptor limitations</a></li> -<li><a href="dns-caveats.html">Issues Regarding DNS and Apache</a></li> -</ul></li> - -<li><a href="faq/">Apache Server Frequently Asked Questions</a> -<ul> -<li><a href="faq/support.html">Support</a></li> -</ul></li> - -<li><a href="ssl/">Apache SSL/TLS Encryption</a> -<ul> -<li><a href="ssl/ssl_intro.html">SSL/TLS Encryption: An Introduction</a></li> -<li><a href="ssl/ssl_compat.html">SSL/TLS Encryption: Compatibility</a></li> -<li><a href="ssl/ssl_howto.html">SSL/TLS Encryption: How-To</a></li> -<li><a href="ssl/ssl_faq.html">SSL/TLS Encryption: FAQ</a></li> -<li><a href="ssl/ssl_glossary.html">SSL/TLS Encryption: Glossary</a></li> -</ul></li> - - -<li>Guides, Tutorials, and HowTos -<ul> -<li><a href="howto/auth.html">Authentication</a></li> -<li><a href="howto/cgi.html">Apache Tutorial: Dynamic Content with CGI</a></li> -<li><a href="howto/ssi.html">Apache Tutorial: Introduction to Server -Side Includes</a></li> -<li><a href="misc/tutorials.html">Apache Tutorials</a></li> -</ul></li> - - -<li>Platform-specific Notes -<ul> -<li><a href="platform/windows.html">Using Apache with Microsoft -Windows</a></li> -<li><a href="platform/win_compiling.html">Compiling Apache for -Microsoft Windows</a></li> -<li><a href="platform/win_service.html">Running Apache for Windows as -a Service</a></li> -<li><a href="platform/netware.html">Using Apache with Novell NetWare</a></li> -<li><a href="platform/perf-hp.html">Running a High-Performance Web -Server on HPUX</a></li> -<li><a href="ebcdic.html">The Apache EBCDIC Port</a></li> -</ul></li> - -<li><a href="programs/">Apache HTTP Server and Supporting Programs</a> -<ul> -<li><a href="programs/httpd.html">Manual Page: httpd</a></li> -<li><a href="programs/ab.html">Manual Page: ab</a></li> -<li><a href="programs/apachectl.html">Manual Page: apachectl</a></li> -<li><a href="programs/apxs.html">Manual Page: apxs</a></li> -<li><a href="programs/dbmmanage.html">Manual Page: dbmmanage</a></li> -<li><a href="programs/htdigest.html">Manual Page: htdigest</a></li> -<li><a href="programs/htpasswd.html">Manual Page: htpasswd</a></li> -<li><a href="programs/logresolve.html">Manual Page: logresolve</a></li> -<li><a href="programs/rotatelogs.html">Manual Page: rotatelogs</a></li> -<li><a href="programs/suexec.html">Manual Page: suexec</a></li> -<li><a href="programs/other.html">Other Programs</a></li> -</ul></li> - -<li><a href="misc/">Apache Miscellaneous Documentation</a> -<ul> -<li><a href="misc/custom_errordocs.html">International Customized Server Error Messages</a></li> -<li><a href="misc/fin_wait_2.html">Connections in FIN_WAIT_2 and Apache</a></li> -<li><a href="misc/known_client_problems.html">Known Client Problems</a></li> -<li><a href="misc/descriptors.html">Descriptors and Apache</a></li> -<li><a href="cgi_path.html">PATH_INFO Changes in the CGI Environment</a></li> -</ul></li> - -<li><a href="mod/">Apache modules</a> -<ul> -<li><a href="mod/directives.html">Apache directives</a></li> -<li><a href="mod/module-dict.html">Definitions of terms used to describe Apache modules</a></li> -<li><a href="mod/directive-dict.html">Definitions of terms used to describe Apache directives</a></li> -<li><a href="mod/core.html">Apache Core Features</a></li> -<li><a href="mod/mpm_common.html">Apache MPM Common Directives</a></li> -<li><a href="mod/mpm_netware.html">Apache MPM netware</a></li> -<li><a href="mod/mpm_winnt.html">Apache MPM winnt</a></li> -<li><a href="mod/perchild.html">Apache MPM perchild</a></li> -<li><a href="mod/prefork.html">Apache MPM prefork</a></li> -<li><a href="mod/worker.html">Apache MPM worker</a></li> -<li><a href="mod/mod_access.html">Apache module mod_access</a></li> -<li><a href="mod/mod_actions.html">Apache module mod_actions</a></li> -<li><a href="mod/mod_alias.html">Apache module mod_alias</a></li> -<li><a href="mod/mod_asis.html">Apache module mod_asis</a></li> -<li><a href="mod/mod_auth.html">Apache module mod_auth</a></li> -<li><a href="mod/mod_auth_anon.html">Apache module mod_auth_anon.c</a></li> -<li><a href="mod/mod_auth_dbm.html">Apache module mod_auth_dbm</a></li> -<li><a href="mod/mod_auth_digest.html">Apache module mod_auth_digest</a></li> -<li><a href="mod/mod_auth_ldap.html">Apache module mod_ldap</a></li> -<li><a href="mod/mod_autoindex.html">Apache module mod_autoindex</a></li> -<li><a href="mod/mod_cache.html">Apache module mod_cache</a></li> -<li><a href="mod/mod_cern_meta.html">Apache module mod_cern_meta</a></li> -<li><a href="mod/mod_cgi.html">Apache module mod_cgi</a></li> -<li><a href="mod/mod_cgid.html">Apache module mod_cgi</a></li> -<li><a href="mod/mod_charset_lite.html">Apache module mod_charset_lite</a></li> -<li><a href="mod/mod_dav.html">Apache module mod_dav</a></li> -<li><a href="mod/mod_deflate.html">Apache module mod_deflate</a></li> -<li><a href="mod/mod_dir.html">Apache module mod_dir</a></li> -<li><a href="mod/mod_env.html">Apache module mod_env</a></li> -<li><a href="mod/mod_example.html">Apache module mod_example</a></li> -<li><a href="mod/mod_expires.html">Apache module mod_expires</a></li> -<li><a href="mod/mod_ext_filter.html">Apache module mod_ext_filter</a></li> -<li><a href="mod/mod_file_cache.html">Apache module mod_file_cache</a></li> -<li><a href="mod/mod_headers.html">Apache module mod_headers</a></li> -<li><a href="mod/mod_imap.html">Apache module mod_imap</a></li> -<li><a href="mod/mod_include.html">Apache module mod_include</a></li> -<li><a href="mod/mod_info.html">Apache module mod_info</a></li> -<li><a href="mod/mod_isapi.html">Apache module mod_isapi</a></li> -<li><a href="mod/mod_ldap.html">Apache module mod_ldap</a></li> -<li><a href="mod/mod_log_config.html">Apache module mod_log_config</a></li> -<li><a href="mod/mod_mime.html">Apache module mod_mime</a></li> -<li><a href="mod/mod_mime_magic.html">Apache module mod_mime_magic</a></li> -<li><a href="mod/mod_negotiation.html">Apache module mod_negotiation</a></li> -<li><a href="mod/mod_proxy.html">Apache module mod_proxy</a></li> -<li><a href="mod/mod_rewrite.html">Apache module mod_rewrite</a></li> -<li><a href="mod/mod_setenvif.html">Apache module mod_setenvif</a></li> -<li><a href="mod/mod_so.html">Apache module mod_so</a></li> -<li><a href="mod/mod_speling.html">Apache module mod_speling</a></li> -<li><a href="mod/mod_ssl.html">Apache module mod_ssl</a></li> -<li><a href="mod/mod_status.html">Apache module mod_status</a></li> -<li><a href="mod/mod_suexec.html">Apache module mod_suexec</a></li> -<li><a href="mod/mod_unique_id.html">Apache module mod_unique_id</a></li> -<li><a href="mod/mod_userdir.html">Apache module mod_userdir</a></li> -<li><a href="mod/mod_usertrack.html">Apache module mod_usertrack</a></li> -<li><a href="mod/mod_vhost_alias.html">Apache module mod_vhost_alias</a></li> -</ul></li> - -<li><a href="developer/">Developer Documentation</a> -<ul> -<li><a href="developer/API.html">Apache API notes</a></li> -<li><a href="developer/debugging.html">Debugging Memory Allocation in APR</a></li> -<li><a href="developer/documenting.html">Documenting Apache 2.0</a></li> -<li><a href="developer/hooks.html">Apache 2.0 Hook Functions</a></li> -<li><a href="developer/layeredio.html">Apache 2.0 Layered I/O</a></li> -<li><a href="developer/modules.html">Converting Modules from Apache 1.3 to Apache 2.0</a></li> -<li><a href="developer/request.html">Request Processing in Apache 2.0</a></li> -<li><a href="developer/filters.html">How Filters Work in Apache 2.0</a></li> -</ul></li> - -</ul></li> - -</ul> - - <!--#include virtual="footer.html" --> - </body> -</html> diff --git a/docs/manual/stopping.html.en b/docs/manual/stopping.html.en deleted file mode 100644 index 8e2c2b12c6..0000000000 --- a/docs/manual/stopping.html.en +++ /dev/null @@ -1,209 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> - -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta name="generator" content="HTML Tidy, see www.w3.org" /> - - <title>Stopping and Restarting the Server</title> - </head> - <!-- Background white, links blue (unvisited), navy (visited), red (active) --> - - <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" - vlink="#000080" alink="#FF0000"> - <!--#include virtual="header.html" --> - - <h1 align="CENTER">Stopping and Restarting the Server</h1> - - <p>This document covers stopping and restarting Apache on - Unix-like systems. Windows users should see <a - href="platform/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/mpm_common.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 be described in a moment.</p> - - <p>To send a signal to the parent you should issue a command - such as:</p> - - <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/apache/logs/error_log -</pre> - </blockquote> - Modify those examples to match your <a - href="mod/core.html#serverroot">ServerRoot</a> and <a - href="mod/mpm_common.html#pidfile">PidFile</a> settings. - - <p>A shell script called <a - href="programs/apachectl.html">apachectl</a> is provided which - automates the processing of signalling Apache. For details - about this script, see the documentation on <a - href="invoking.html">starting Apache</a>.</p> - - <h3>Stop Now</h3> - - <p><strong>Signal:</strong> TERM<br /> - <code>apachectl stop</code></p> - - <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.</p> - - <h3>Graceful Restart</h3> - - <p><strong>Signal:</strong> USR1<br /> - <code>apachectl graceful</code></p> - - <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 <em>generation</em> of - the configuration, which begins serving new requests - immediately.</p> - <i>On certain platforms that do not allow USR1 to be used for a - graceful restart, an alternative signal may be used (such as - WINCH). apachectl graceful will send the right signal for your - platform.</i> - - <p>This code is designed to always respect the <a - href="mod/mpm_common.html#maxclients">MaxClients</a>, <a - href="mod/prefork.html#minspareservers">MinSpareServers</a>, - and <a - href="mod/prefork.html#maxspareservers">MaxSpareServers</a> - settings. Furthermore, it respects <a - href="mod/mpm_common.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> - - <p>Users of the <a href="mod/mod_status.html">status module</a> - will notice that the server statistics 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 - <em>scoreboard</em> used to keep track of all children across - generations.</p> - - <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> - - <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 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> - - <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 the children which are "gracefully exiting" by - handling their last request.) This will cause problems if you - attempt to restart the server -- it will not be able to bind to - its listening ports. Before doing a restart, you can check the - syntax of the configuration files with the <code>-t</code> - command line argument (see <a - href="programs/httpd.html">httpd</a>). This still will not - guarantee that the server will restart correctly. To check the - semantics of the configuration files as well as the syntax, you - can try starting httpd as a non-root user. If there are no - errors it will attempt to open its sockets and logs and fail - because it's not root (or because the currently running httpd - already has those ports bound). If it fails for any other - reason then it's probably a config file error and the error - should be fixed before issuing the graceful restart.</p> - - <h3>Restart Now</h3> - - <p><strong>Signal:</strong> HUP<br /> - <code>apachectl restart</code></p> - - <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> - - <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.</p> - - <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.</p> - - <h3>Appendix: signals and race conditions</h3> - - <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 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> - - <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 a fatal error, while the latter just causes the - server to lose a scoreboard slot. So it might be advisable to - use graceful restarts, with an occasional hard restart. These - problems are very difficult to work around, but fortunately - most architectures do not require a scoreboard file. See the <a - href="mod/core.html#scoreboardfile">ScoreBoardFile</a> - documentation for a architecture uses it.</p> - - <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> - - <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 too late to make 1.2. In - theory this isn't an issue because the KeepAlive client has to - expect these events because of network latencies and server - timeouts. In practice it doesn't seem to affect anything either - -- in a test case the server was restarted twenty times per - second and clients successfully browsed the site without - getting broken images or empty documents. - <!--#include virtual="footer.html" --> - </p> - </body> -</html> - diff --git a/docs/manual/urlmapping.html.en b/docs/manual/urlmapping.html.en deleted file mode 100755 index a127bb1c16..0000000000 --- a/docs/manual/urlmapping.html.en +++ /dev/null @@ -1,333 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> - -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <title>Mapping URLs to Filesystem Locations - Apache HTTP - Server</title> - </head> - <!-- Background white, links blue (unvisited), navy (visited), red (active) --> - - <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" - vlink="#000080" alink="#FF0000"> - <!--#include virtual="header.html" --> - - <h1 align="center">Mapping URLs to Filesystem Locations</h1> - - <p>This document explains how Apache uses the URL of a request - to determine the filesystem location from which to serve a - file.</p> - - <ul> - <li><a href="#documentroot">DocumentRoot</a></li> - - <li><a href="#outside">Files Outside the - DocumentRoot</a></li> - - <li><a href="#user">User Directories</a></li> - - <li><a href="#redirect">URL Redirection</a></li> - - <li><a href="#proxy">Reverse Proxy</a></li> - - <li><a href="#rewrite">Rewrite Engine</a></li> - - <li><a href="#notfound">File Not Found</a></li> - </ul> - <hr /> - - <table border="1"> - <tr> - <td valign="top"><strong>Related Modules</strong><br /> - <br /> - <a href="mod/mod_alias.html">mod_alias</a><br /> - <a href="mod/mod_proxy.html">mod_proxy</a><br /> - <a href="mod/mod_rewrite.html">mod_rewrite</a><br /> - <a href="mod/mod_userdir.html">mod_userdir</a><br /> - <a href="mod/mod_speling.html">mod_speling</a><br /> - <a - href="mod/mod_vhost_alias.html">mod_vhost_alias</a><br /> - </td> - - <td valign="top"><strong>Related Directives</strong><br /> - <br /> - <a href="mod/mod_alias.html#alias">Alias</a><br /> - <a - href="mod/mod_alias.html#aliasmatch">AliasMatch</a><br /> - <a - href="mod/mod_speling.html#checkspelling">CheckSpelling</a><br /> - <a - href="mod/core.html#documentroot">DocumentRoot</a><br /> - <a - href="mod/core.html#errordocument">ErrorDocument</a><br /> - <a href="mod/core.html#options">Options</a><br /> - <a href="mod/mod_proxy.html#proxypass">ProxyPass</a><br /> - <a href="mod/mod_proxy.html#proxypassreverse">ProxyPassReverse</a><br /> - <a href="mod/mod_alias.html#redirect">Redirect</a><br /> - <a - href="mod/mod_alias.html#redirectmatch">RedirectMatch</a><br /> - <a - href="mod/mod_rewrite.html#RewriteCond">RewriteCond</a><br /> - <a - href="mod/mod_rewrite.html#RewriteRule">RewriteRule</a><br /> - <a - href="mod/mod_alias.html#scriptalias">ScriptAlias</a><br /> - <a - href="mod/mod_alias.html#scriptaliasmatch">ScriptAliasMatch</a><br /> - <a href="mod/mod_userdir.html#userdir">UserDir</a><br /> - </td> - </tr> - </table> - - <h2><a id="documentroot" - name="documentroot">DocumentRoot</a></h2> - - <p>In deciding what file to serve for a given request, Apache's - default behavior is to take the URL-Path for the request (the - part of the URL following the hostname and port) and add it to - the end of the <a - href="mod/core.html#documentroot">DocumentRoot</a> specified in - your configuration files. Therefore, the files and directories - underneath the <code>DocumentRoot</code> make up the basic - document tree which will be visible from the web.</p> - - <p>Apache is also capable of <a href="vhosts/">Virtual - Hosting</a>, where the server receives requests for more than - one host. In this case, a different <code>DocumentRoot</code> - can be specified for each virtual host, or alternatively, the - directives provided by the module <a - href="mod/mod_vhost_alias.html">mod_vhost_alias</a> can be used - to dynamically determine the appropriate place from which to - serve content based on the requested IP address or - hostname.</p> - - <h2><a id="outside" name="outside">Files Outside the - DocumentRoot</a></h2> - - <p>There are frequently circumstances where it is necessary to - allow web access to parts of the filesystem that are not - strictly underneath the <a - href="mod/core.html#documentroot">DocumentRoot</a>. Apache - offers several different ways to accomplish this. On Unix - systems, symbolic links can bring other parts of the filesystem - under the <code>DocumentRoot</code>. For security reasons, - Apache will follow symbolic links only if the <a - href="mod/core.html#options">Options</a> setting for the - relevant directory includes <code>FollowSymLinks</code> or - <code>SymLinksIfOwnerMatch</code>.</p> - - <p>Alternatively, the <a - href="mod/mod_alias.html#alias">Alias</a> directive will map - any part of the filesystem into the web space. For example, - with</p> - - <blockquote> - <code>Alias /docs /var/web/</code> - </blockquote> - - <p>the URL - <code>http://www.example.com/docs/dir/file.html</code> will be - served from <code>/var/web/dir/file.html</code>. The <a - href="mod/mod_alias.html#scriptalias">ScriptAlias</a> directive - works the same way, with the additional effect that all content - located at the target path is treated as CGI scripts.</p> - - <p>For situations where you require additional flexibility, you - can use the <a - href="mod/mod_alias.html#aliasmatch">AliasMatch</a> and <a - href="mod/mod_alias.html#scriptaliasmatch">ScriptAliasMatch</a> - directives to do powerful regular-expression based matching and - substitution. For example,</p> - - <blockquote> - <code>ScriptAliasMatch ^/~([a-zA-Z0-9]*)/cgi-bin/(.*) - /home/$1/cgi-bin/$2</code> - </blockquote> - - <p>will map a request to - <code>http://example.com/~user/cgi-bin/script.cgi</code> to the - path <code>/home/user/cgi-bin/script.cgi</code> and will treat - the resulting file as a CGI script.</p> - - <h2><a id="user" name="user">User Directories</a></h2> - - <p>Traditionally on Unix systems, the home directory of a - particular <em>user</em> can be referred to as - <code>~user/</code>. The module <a - href="mod/mod_userdir.html">mod_userdir</a> extends this idea - to the web by allowing files under each user's home directory - to be accessed using URLs such as the following.</p> - - <blockquote> - <code>http://www.example.com/~user/file.html</code> - </blockquote> - - <p>For security reasons, it is inappropriate to give direct - access to a user's home directory from the web. Therefore, the - <a href="mod/mod_userdir.html#userdir">UserDir</a> directive - specifies a directory underneath the user's home directory - where web files are located. Using the default setting of - <code>Userdir public_html</code>, the above URL maps to a file - at a directory like - <code>/home/user/public_html/file.html</code> where - <code>/home/user/</code> is the user's home directory as - specified in <code>/etc/passwd</code>.</p> - - <p>There are also several other forms of the - <code>Userdir</code> directive which you can use on systems - where <code>/etc/passwd</code> does not contain the location of - the home directory.</p> - - <p>Some people find the "~" symbol (which is often encoded on - the web as <code>%7e</code>) to be awkward and prefer to use an - alternate string to represent user directories. This - functionality is not supported by mod_userdir. However, if - users' home directories are structured in a regular way, then - it is possible to use the <a - href="mod/mod_alias.html#aliasmatch">AliasMatch</a> directive - to achieve the desired effect. For example, to make - <code>http://www.example.com/upages/user/file.html</code> map - to <code>/home/user/public_html/file.html</code>, use the - following <code>AliasMatch</code> directive:</p> - - <blockquote> - <code>AliasMatch ^/upages/([a-zA-Z0-9]*)/?(.*) - /home/$1/public_html/$2</code> - </blockquote> - - <h2><a id="redirect" name="redirect">URL Redirection</a></h2> - - <p>The configuration directives discussed in the above sections - tell Apache to get content from a specific place in the - filesystem and return it to the client. Sometimes, it is - desirable instead to inform the client that the requested - content is located at a different URL, and instruct the client - to make a new request with the new URL. This is called - <em>redirection</em> and is implemented by the <a - href="mod/mod_alias.html#redirect">Redirect</a> directive. For - example, if the contents of the directory <code>/foo/</code> - under the <code>DocumentRoot</code> are moved to the new - directory <code>/bar/</code>, you can instruct clients to - request the content at the new location as follows:</p> - - <blockquote> - <code>Redirect permanent /foo/ - http://www.example.com/bar/</code> - </blockquote> - - <p>This will redirect any URL-Path starting in - <code>/foo/</code> to the same URL path on the - <code>www.example.com</code> server with <code>/bar/</code> - substituted for <code>/foo/</code>. You can redirect clients to - any server, not only the origin server.</p> - - <p>Apache also provides a <a - href="mod/mod_alias.html#redirectmatch">RedirectMatch</a> - directive for more complicated rewriting problems. For example, - to redirect requests for the site home page to a different - site, but leave all other requests alone, use the following - configuration:</p> - - <blockquote> - <code>RedirectMatch permanent ^/$ - http://www.example.com/startpage.html</code> - </blockquote> - - <p>Alternatively, to temporarily redirect all pages on a site - to one particular page, use the following:</p> - - <blockquote> - <code>RedirectMatch temp .* - http://www.example.com/startpage.html</code> - </blockquote> - - -<h2><a id="proxy" name="proxy">Reverse Proxy</a></h2> - -<p>Apache also allows you to bring remote documents into the URL space -of the local server. This technique is called <em>reverse -proxying</em> because the web server acts like a proxy server by -fetching the documents from a remote server and returning them to the -client. It is different from normal proxying because, to the client, -it appears the documents originate at the reverse proxy server.</p> - -<p>In the following example, when clients request documents under the -<code>/foo/</code> directory, the server fetches those documents from -the <code>/bar/</code> directory on <code>internal.example.com</code> -and returns them to the client as if they were from the local -server.</p> - -<blockquote> -ProxyPass /foo/ http://internal.example.com/bar/<br /> -ProxyPassReverse /foo/ http://internal.example.com/bar/ -</blockquote> - -<p>The <a href="mod/mod_proxy.html#proxypass">ProxyPass</a> configures -the server to fetch the appropriate documents, while the <a -href="mod/mod_proxy.html#proxypassreverse">ProxyPassReverse</a> -directive rewrites redirects originating at -<code>internal.examle.com</code> so that they target the appropriate -directory on the local server. It is important to note, however, that -links inside the documents will not be rewritten. So any absolute -links on <code>internal.example.com</code> will result in the client -breaking out of the proxy server and requesting directly from -<code>internal.example.com</code>.</p> - - - <h2><a id="rewrite" name="rewrite">Rewriting Engine</a></h2> - - <p>When even more powerful substitution is required, the rewriting - engine provided by <a href="mod/mod_rewrite.html">mod_rewrite</a> - can be useful. The directives provided by this module use - characteristics of the request such as browser type or source IP - address in deciding from where to serve content. In addition, - mod_rewrite can use external database files or programs to - determine how to handle a request. The rewriting engine is capable - of performing all three types of mappings discussed above: - internal redirects (aliases), external redirects, and proxying. - Many practical examples employing mod_rewrite are discussed in the - <a href="misc/rewriteguide.html">URL Rewriting Guide</a>.</p> - - <h2><a id="notfound" name="notfound">File Not Found</a></h2> - - <p>Inevitably, URLs will be requested for which no matching - file can be found in the filesystem. This can happen for - several reasons. In some cases, it can be a result of moving - documents from one location to another. In this case, it is - best to use <a href="#redirect">URL redirection</a> to inform - clients of the new location of the resource. In this way, you - can assure that old bookmarks and links will continue to work, - even though the resource is at a new location.</p> - - <p>Another common cause of "File Not Found" errors is - accidental mistyping of URLs, either directly in the browser, - or in HTML links. Apache provides the module <a - href="mod/mod_speling.html">mod_speling</a> (sic) to help with - this problem. When this module is activated, it will intercept - "File Not Found" errors and look for a resource with a similar - filename. If one such file is found, mod_speling will send an - HTTP redirect to the client informing it of the correct - location. If several "close" files are found, a list of - available alternatives will be presented to the client.</p> - - <p>An especially useful feature of mod_speling, is that it will - compare filenames without respect to case. This can help - systems where users are unaware of the case-sensitive nature of - URLs and the unix filesystem. But using mod_speling for - anything more than the occasional URL correction can place - additional load on the server, since each "incorrect" request - is followed by a URL redirection and a new request from the - client.</p> - - <p>If all attempts to locate the content fail, Apache returns - an error page with HTTP status code 404 (file not found). The - appearance of this page is controlled with the <a - href="mod/core.html#errordocument">ErrorDocument</a> directive - and can be customized in a flexible manner as discussed in the - <a href="custom-error.html">Custom error responses</a> and <a - href="misc/custom_errordocs.html">International Server Error - Responses</a> documents.</p> - <!--#include virtual="footer.html" --> - </body> -</html> - |