diff options
author | (no author) <(no author)@unknown> | 1997-07-05 17:36:08 +0000 |
---|---|---|
committer | (no author) <(no author)@unknown> | 1997-07-05 17:36:08 +0000 |
commit | e9d660d6afa01a3bd8985bbcc87079d5d66d6e3b (patch) | |
tree | 6f288d1b6b0a5e1f5ac9461cebb7698846a47d4c | |
parent | 8a147876e28e6267146adb9f8af4920d3c22cd06 (diff) | |
download | httpd-e9d660d6afa01a3bd8985bbcc87079d5d66d6e3b.tar.gz |
This commit was manufactured by cvs2svn to create tag 'APACHE_1_2_1'.1.2.1
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/tags/1.2.1@78528 13f79535-47bb-0310-9956-ffa450edef68
34 files changed, 1294 insertions, 4038 deletions
diff --git a/docs/docroot/apache_pb.gif b/docs/docroot/apache_pb.gif Binary files differdeleted file mode 100644 index 3a1c139fc4..0000000000 --- a/docs/docroot/apache_pb.gif +++ /dev/null diff --git a/docs/manual/bind.html.en b/docs/manual/bind.html.en deleted file mode 100644 index 9253168138..0000000000 --- a/docs/manual/bind.html.en +++ /dev/null @@ -1,109 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<html><head> -<title>Setting which addresses and ports Apache uses</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">Setting which addresses and ports Apache uses</h1> - -<hr> - -When Apache starts, it connects to some port and address on the -local machine and waits for incoming requests. By default, it -listens to all addresses on the machine, and to the port -as specified by the <tt>Port</tt> directive in the server configuration. -However, it can be told to listen to more the one port, or to listen -to only selected addresses, or a combination. This is often combined -with the Virtual Host feature which determines how Apache -responds to different IP addresses, hostnames and ports.<p> - -There are two directives used to restrict or specify which addresses -and ports Apache listens to. - -<ul> -<li><a href="#bindaddress">BindAddress</a> is used to restrict the server to listening to - a single address, and can be used to permit multiple Apache servers - on the same machine listening to different IP addresses. -<li><a href="#listen">Listen</a> can be used to make a single Apache server listen - to more than one address and/or port. -</ul> - -<h3><a name="bindaddress">BindAddress</a></h3> -<strong>Syntax:</strong> BindAddress <em>[ * | IP-address | hostname ]</em><br> -<strong>Default:</strong> <code>BindAddress *</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Core<p> - -Makes the server listen to just the specified address. If the argument -is *, the server listens to all addresses. The port listened to -is set with the <tt>Port</tt> directive. Only one BindAddress -should be used. - -<h3><a name="listen">Listen</a></h3> -<strong>Syntax:</strong> Listen <em>[ port | IP-address:port ]</em><br> -<strong>Default:</strong> <code>none</code><br> -<strong>Context:</strong> server config<br> -<strong>Status:</strong> Core<p> - -<tt>Listen</tt> can be used instead of <tt>BindAddress</tt> and -<tt>Port</tt>. It tells the server to accept incoming requests on the -specified port or address-and-port combination. If the first format is -used, with a port number only, the server listens to the given port on -all interfaces, instead of the port given by the <tt>Port</tt> -directive. If an IP address is given as well as a port, the server -will listen on the given port and interface. <p> Multiple Listen -directives may be used to specify a number of addresses and ports to -listen to. The server will respond to requests from any of the listed -addresses and ports.<p> - -For example, to make the server accept connections on both port -80 and port 8000, use: -<pre> - Listen 80 - Listen 8000 -</pre> - -To make the server accept connections on two specified -interfaces and port numbers, use -<pre> - Listen 192.170.2.1:80 - Listen 192.170.2.5:8000 -</pre> - -<h2>How this works with Virtual Hosts</h2> - -BindAddress and Listen do not implement Virtual Hosts. They tell the -main server what addresses and ports to listen to. If no -<VirtualHost> directives are used, the server will behave the -same for all accepted requests. However, <VirtualHost> can be -used to specify a different behavior for one or more of the addresses -and ports. To implement a VirtualHost, the server must first be told -to listen to the address and port to be used. Then a -<VirtualHost> section should be created for a specified address -and port to set the behavior of this virtual host. Note that if the -<VirtualHost> is set for an address and port that the server is -not listening to, it cannot be accessed. - -<h2>See also</h2> - -See also the documentation on -<a href="virtual-host.html">Virtual Hosts</a>, -<a href="host.html">Non-IP virtual hosts</a>, -<a href="mod/core.html#bindaddress">BindAddress directive</a>, -<a href="mod/core.html#port">Port directive</a>, -<a href="dns-caveats.html">DNS Issues</a> -and -<a href="mod/core.html#virtualhost"><VirtualHost> section</a>. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/cgi_path.html.en b/docs/manual/cgi_path.html.en deleted file mode 100644 index 8ac3bc0dd1..0000000000 --- a/docs/manual/cgi_path.html.en +++ /dev/null @@ -1,93 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<html><head> -<title>PATH_INFO Changes in the CGI Environment</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">PATH_INFO Changes in the CGI Environment</h1> - -<hr> - -<h2><a name="over">Overview</a></h2> - -<p>As implemented in Apache 1.1.1 and earlier versions, the method -Apache used to create PATH_INFO in the CGI environment was -counterintuitive, and could result in crashes in certain cases. In -Apache 1.2 and beyond, this behavior has changed. Although this -results in some compatibility problems with certain legacy CGI -applications, the Apache 1.2 behavior is still compatible with the -CGI/1.1 specification, and CGI scripts can be easily modified (<a -href="#compat">see below</a>). - -<h2><a name="prob">The Problem</a></h2> - -<p>Apache 1.1.1 and earlier implemented the PATH_INFO and SCRIPT_NAME -environment variables by looking at the filename, not the URL. While -this resulted in the correct values in many cases, when the filesystem -path was overloaded to contain path information, it could result in -errant behavior. For example, if the following appeared in a config -file: -<pre> - Alias /cgi-ralph /usr/local/httpd/cgi-bin/user.cgi/ralph -</pre> -<p>In this case, <code>user.cgi</code> is the CGI script, the "/ralph" -is information to be passed onto the CGI. If this configuration was in -place, and a request came for "<code>/cgi-ralph/script/</code>", the -code would set PATH_INFO to "<code>/ralph/script</code>", and -SCRIPT_NAME to "<code>/cgi-</code>". Obviously, the latter is -incorrect. In certain cases, this could even cause the server to -crash.</p> - -<h2><a name="solution">The Solution</a></h2> - -<p>Apache 1.2 and later now determine SCRIPT_NAME and PATH_INFO by -looking directly at the URL, and determining how much of the URL is -client-modifiable, and setting PATH_INFO to it. To use the above -example, PATH_INFO would be set to "<code>/script</code>", and -SCRIPT_NAME to "<code>/cgi-ralph</code>". This makes sense and results -in no server behavior problems. It also permits the script to be -guaranteed that -"<code>http://$SERVER_NAME:$SERVER_PORT$SCRIPT_NAME$PATH_INFO</code>" -will always be an accessible URL that points to the current script, -something which was not necessarily true with previous versions of -Apache. - -<p>However, the "<code>/ralph</code>" -information from the <code>Alias</code> directive is lost. This is -unfortunate, but we feel that using the filesystem to pass along this -sort of information is not a recommended method, and a script making -use of it "deserves" not to work. Apache 1.2b3 and later, however, do -provide <a href="#compat">a workaround.</a> - -<h2><a name="compat">Compatibility with Previous Servers</a></h2> - -<p>It may be necessary for a script that was designed for earlier -versions of Apache or other servers to need the information that the -old PATH_INFO variable provided. For this purpose, Apache 1.2 (1.2b3 -and later) sets an additional variable, FILEPATH_INFO. This -environment variable contains the value that PATH_INFO would have had -with Apache 1.1.1.</p> - -<p>A script that wishes to work with both Apache 1.2 and earlier -versions can simply test for the existence of FILEPATH_INFO, and use -it if available. Otherwise, it can use PATH_INFO. For example, in -Perl, one might use: -<pre> - $path_info = $ENV{'FILEPATH_INFO'} || $ENV{'PATH_INFO'}; -</pre> - -<p>By doing this, a script can work with all servers supporting the -CGI/1.1 specification, including all versions of Apache.</p> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/content-negotiation.html.en b/docs/manual/content-negotiation.html.en deleted file mode 100644 index 2aa06eb32f..0000000000 --- a/docs/manual/content-negotiation.html.en +++ /dev/null @@ -1,426 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<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> - -Apache's support for content negotiation has been updated to meet the -HTTP/1.1 specification. It can choose the best representation of a -resource based on the browser-supplied preferences for media type, -languages, character set and encoding. It is also implements a -couple of features to give more intelligent handling of requests from -browsers which send incomplete negotiation information. <p> - -Content negotiation is provided by the -<a href="mod/mod_negotiation.html">mod_negotiation</a> module, -which is compiled in by default. - -<hr> - -<h2>About Content Negotiation</h2> - -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 - -<pre> - Accept-Language: fr -</pre> - -Note that this preference will only be applied when there is a choice -of representations and they vary by language. -<p> - -As an example of a more complex request, this browser has been -configured to accept French and English, but prefer French, and to -accept various media types, preferring HTML over plain text or other -text types, and preferring GIF or JPEG over other media types, but also -allowing any other media type as a last resort: - -<pre> - 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 1.2 supports 'server driven' content negotiation, as defined in -the HTTP/1.1 specification. It fully supports the Accept, -Accept-Language, Accept-Charset and Accept-Encoding request headers. -<p> - -The terms used in content negotiation are: a <b>resource</b> is an -item which can be requested of a server, which might be selected as -the result of a content negotiation algorithm. If a resource is -available in several formats, these are called <b>representations</b> -or <b>variants</b>. The ways in which the variants for a particular -resource vary are called the <b>dimensions</b> of negotiation. - -<h2>Negotiation in Apache</h2> - -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: - -<ul> - <li> Using a type map (i.e., a <code>*.var</code> file) which - names the files containing the variants explicitly - <li> Or using a 'MultiViews' search, where the server does an implicit - filename pattern match, and chooses from among the results. -</ul> - -<h3>Using a type-map file</h3> - -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've got to have a <code>SetHandler</code> some place which defines a -file suffix as <code>type-map</code>; this is best done with a -<pre> - - AddHandler type-map var - -</pre> -in <code>srm.conf</code>. See comments in the sample config files for -details. <p> - -Type map files have an entry for each available variant; these entries -consist of contiguous RFC822-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: -<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> - -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 between 0.000 and 1.000. Note that any variant with -a qs value of 0.000 will never be chosen. Variants with no 'qs' -parameter value are given a qs factor of 1.0. <p> - -The full list of headers recognized is: - -<dl> - <dt> <code>URI:</code> - <dd> uri of the file containing the variant (of the given media - type, encoded with the given content encoding). These are - interpreted as URLs relative to the map file; they must be on - the same server (!), and they must refer to files to which the - client would be granted access if they were to be requested - directly. - <dt> <code>Content-type:</code> - <dd> media type --- charset, level and "qs" parameters may be given. These - are often referred to as MIME types; typical media types are - <code>image/gif</code>, <code>text/plain</code>, or - <code>text/html; level=3</code>. - <dt> <code>Content-language:</code> - <dd> The languages of the variant, specified as an Internet standard - language code (e.g., <code>en</code> for English, - <code>kr</code> for Korean, etc.). - <dt> <code>Content-encoding:</code> - <dd> If the file is compressed, or otherwise encoded, rather than - containing the actual raw data, this says how that was done. - For compressed files (the only case where this generally comes - up), content encoding should be - <code>x-compress</code>, or <code>x-gzip</code>, as appropriate. - <dt> <code>Content-length:</code> - <dd> The size of the file. Clients can ask to receive a given media - type only if the variant isn't too big; specifying a content - length in the map allows the server to compare against these - thresholds without checking the actual file. -</dl> - -<h3>Multiviews</h3> - -This is a per-directory option, meaning it can be set with an -<code>Options</code> directive within a <code><Directory></code>, -<code><Location></code> or <code><Files></code> -section in <code>access.conf</code>, or (if <code>AllowOverride</code> -is properly set) in <code>.htaccess</code> files. Note that -<code>Options All</code> does not set <code>MultiViews</code>; you -have to ask for it by name. (Fixing this is a one-line change to -<code>http_core.h</code>). - -<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, and forwards them along. - -<p> - -This applies 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 -<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 directive is a CGI script, -it's not obvious what should happen. The code gives that case -special treatment --- if the request was a POST, or a GET with -QUERY_ARGS or PATH_INFO, the script is given an extremely high quality -rating, and generally invoked; otherwise it is given an extremely low -quality rating, which generally causes one of the other views (if any) -to be retrieved. - -<h2>The Negotiation Algorithm</h2> - -After Apache has obtained a list of the variants for a given resource, -either from a type-map file or from the filenames in the directory, it -applies a algorithm to decide on the 'best' variant to return, if -any. To do this it calculates a quality value for each variant in each -of the dimensions of variance. It is not necessary to know any of the -details of how negotiation actually takes place in order to use Apache's -content negotiation features. However the rest of this document -explains in detail the algorithm used for those interested. <p> - -In some circumstances, Apache can 'fiddle' the quality factor of a -particular dimension to achieve a better result. The ways Apache can -fiddle quality factors is explained in more detail below. - -<h3>Dimensions of Negotiation</h3> - -<table> -<tr><th>Dimension -<th>Notes -<tr><td>Media Type -<td>Browser indicates preferences on Accept: header. Each item -can have an associated quality factor. Variant description can also -have a quality factor. -<tr><td>Language -<td>Browser indicates preferences on Accept-Language: header. Each -item -can have a quality factor. Variants can be associated with none, one -or more languages. -<tr><td>Encoding -<td>Browser indicates preference with Accept-Encoding: header. -<tr><td>Charset -<td>Browser indicates preference with Accept-Charset: header. Variants -can indicate a charset as a parameter of the media type. -</table> - -<h3>Apache Negotiation Algorithm</h3> - -Apache uses an algorithm to select the 'best' variant (if any) to -return to the browser. This algorithm is not configurable. It operates -like this: -<p> - -<ol> -<li> -Firstly, for each dimension of the negotiation, the appropriate -Accept header is checked and a quality assigned to this each -variant. If the Accept header for any dimension means that this -variant is not acceptable, eliminate it. If no variants remain, go -to step 4. - -<li>Select the 'best' variant by a process of elimination. Each of -the following tests is applied in order. Any variants not selected at -each stage are eliminated. After each test, if only one variant -remains, it is selected as the best match. If more than one variant -remains, move onto the next test. - -<ol> -<li>Multiply the quality factor from the Accept header with the - quality-of-source factor for this variant's media type, and select - the variants with the highest value - -<li>Select the variants with the highest language quality factor - -<li>Select the variants with the best language match, using either the - order of languages on the <code>LanguagePriority</code> directive (if present), - else the order of languages on the Accept-Language header. - -<li>Select the variants with the highest 'level' media parameter - (used to give the version of text/html media types). - -<li>Select only unencoded variants, if there is a mix of encoded - and non-encoded variants. If either all variants are encoded - or all variants are not encoded, select all. - -<li>Select only variants with acceptable charset media parameters, - as given on the Accept-Charset header line. Charset ISO-8859-1 - is always acceptable. Variants not associated with a particular - charset are assumed to be in ISO-8859-1. - -<li>Select the variants with the smallest content length - -<li>Select the first variant of those remaining (this will be either the -first listed in the type-map file, or the first read from the directory) -and go to stage 3. - -</ol> - -<li>The algorithm has now selected one 'best' variant, so return - it as the response. The HTTP response header Vary is set to indicate the - dimensions of negotiation (browsers and caches can use this - information when caching the resource). End. - -<li>To get here means no variant was selected (because non are acceptable - to the browser). Return a 406 status (meaning "No acceptable representation") - with a response body consisting of an HTML document listing the - available variants. Also set the HTTP Vary header to indicate the - dimensions of variance. - -</ol> -<h2><a name="better">Fiddling with Quality Values</a></h2> - -Apache sometimes changes the quality values from what would be -expected by a strict interpretation of the algorithm above. This is to -get a better result from the algorithm for browsers which do not send -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> - -The Accept: request header indicates preferences for media types. It -can also include 'wildcard' media types, such as "image/*" or "*/*" -where the * matches any string. So a request including: -<pre> - 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 <i>no</i> q factors at all, Apache sets -the q value of "*/*", if present, to 0.01 to emulate the desired -behavior. It also sets the q value of wildcards of the format -"type/*" to 0.02 (so these are preferred over matches against -"*/*". If any media type on the Accept: header contains a q factor, -these special values are <i>not</i> applied, so requests from browsers -which send the correct information to start with work as expected. - -<h3>Variants with no Language</h3> - -If some of the variants for a particular resource have a language -attribute, and some do not, those variants with no language -are given a very low language quality factor of 0.001.<p> - -The reason for setting this language quality factor for -variant with no language to a very low value is to allow -for a default variant which can be supplied if none of the -other variants match the browser's language preferences. - -For example, consider the situation with three variants: - -<ul> -<li>foo.en.html, language en -<li>foo.fr.html, language en -<li>foo.html, no language -</ul> - -The meaning of a variant with no language is that it is -always acceptable to the browser. If the request Accept-Language -header includes either en or fr (or both) one of foo.en.html -or foo.fr.html will be returned. If the browser does not list -either en or fr as acceptable, foo.html will be returned instead. - -<h2>Note on Caching</h2> - -When a cache stores a document, it associates it with the request URL. -The next time that URL is requested, the cache can use the stored -document, provided it is still within date. But if the resource is -subject to content negotiation at the server, this would result in -only the first requested variant being cached, and subsequent cache -hits could return the wrong response. To prevent this, -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> - -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. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/custom-error.html b/docs/manual/custom-error.html index 3f04af058b..3165ec044e 100644 --- a/docs/manual/custom-error.html +++ b/docs/manual/custom-error.html @@ -29,9 +29,9 @@ response, then this response can be replaced with either some friendlier text or by a redirection to another URL (local or external). - + <P> - + <DT>Old behavior <DD>NCSA httpd 1.3 would return some boring old error/problem message diff --git a/docs/manual/custom-error.html.en b/docs/manual/custom-error.html.en deleted file mode 100644 index 3f04af058b..0000000000 --- a/docs/manual/custom-error.html.en +++ /dev/null @@ -1,153 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Custom error responses</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">Custom error responses</H1> - -<DL> - -<DT>Purpose - - <DD>Additional functionality. Allows webmasters to configure the response of - Apache to some error or problem. - - <P>Customizable responses can be defined to be activated in the - event of a server detected error or problem. - - <P>e.g. if a script crashes and produces a "500 Server Error" - response, then this response can be replaced with either some - friendlier text or by a redirection to another URL (local or - external). - - <P> - -<DT>Old behavior - - <DD>NCSA httpd 1.3 would return some boring old error/problem message - which would often be meaningless to the user, and would provide no - means of logging the symptoms which caused it.<BR> - - <P> - -<DT>New behavior - - <DD>The server can be asked to; - <OL> - <LI>Display some other text, instead of the NCSA hard coded messages, or - <LI>redirect to a local URL, or - <LI>redirect to an external URL. - </OL> - - <P>Redirecting to another URL can be useful, but only if some information - can be passed which can then be used to explain and/or log the error/problem - more clearly. - - <P>To achieve this, Apache will define new CGI-like environment - variables, e.g. - - <blockquote><code> -REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/x-xbitmap, image/jpeg <br> -REDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX A.09.05 9000/712) <br> -REDIRECT_PATH=.:/bin:/usr/local/bin:/etc <br> -REDIRECT_QUERY_STRING= <br> -REDIRECT_REMOTE_ADDR=121.345.78.123 <br> -REDIRECT_REMOTE_HOST=ooh.ahhh.com <br> -REDIRECT_SERVER_NAME=crash.bang.edu <br> -REDIRECT_SERVER_PORT=80 <br> -REDIRECT_SERVER_SOFTWARE=Apache/0.8.15 <br> -REDIRECT_URL=/cgi-bin/buggy.pl <br> - </code></blockquote> - - <P>note the <code>REDIRECT_</code> prefix. - - <P>At least <code>REDIRECT_URL</code> and <code>REDIRECT_QUERY_STRING</code> will - be passed to the new URL (assuming it's a cgi-script or a cgi-include). The - other variables will exist only if they existed prior to the error/problem. - <b>None</b> of these will be set if your ErrorDocument is an - <i>external</i> redirect (i.e. anything starting with a protocol name - like <code>http:</code>, even if it refers to the same host as the - server).<p> - -<DT>Configuration - - <DD> Use of "ErrorDocument" is enabled for .htaccess files when the - <A HREF="mod/core.html#allowoverride">"FileInfo" override</A> is allowed. - - <P>Here are some examples... - - <blockquote><code> -ErrorDocument 500 /cgi-bin/crash-recover <br> -ErrorDocument 500 "Sorry, our script crashed. Oh dear<br> -ErrorDocument 500 http://xxx/ <br> -ErrorDocument 404 /Lame_excuses/not_found.html <br> -ErrorDocument 401 /Subscription/how_to_subscribe.html - </code></blockquote> - - <P>The syntax is, - - <P><code><A HREF="mod/core.html#errordocument">ErrorDocument</A></code> -<3-digit-code> action - - <P>where the action can be, - - <OL> - <LI>Text to be displayed. Prefix the text with a quote ("). Whatever - follows the quote is displayed. <em>Note: the (") prefix isn't - displayed.</em> - - <LI>An external URL to redirect to. - - <LI>A local URL to redirect to. - - </OL> -</DL> - -<P><HR><P> - -<h2>Custom error responses and redirects</H2> - -<DL> - -<DT>Purpose - - <DD>Apache's behavior to redirected URLs has been modified so that additional - environment variables are available to a script/server-include.<p> - -<DT>Old behavior - - <DD>Standard CGI vars were made available to a script which has been - redirected to. No indication of where the redirection came from was provided. - - <p> - -<DT>New behavior - <DD> - -A new batch of environment variables will be initialized for use by a -script which has been redirected to. Each new variable will have the -prefix <code>REDIRECT_</code>. <code>REDIRECT_</code> environment -variables are created from the CGI environment variables which existed -prior to the redirect, they are renamed with a <code>REDIRECT_</code> -prefix, i.e. <code>HTTP_USER_AGENT</code> becomes -<code>REDIRECT_HTTP_USER_AGENT</code>. In addition to these new -variables, Apache will define <code>REDIRECT_URL</code> and -<code>REDIRECT_STATUS</code> to help the script trace its origin. -Both the original URL and the URL being redirected to can be logged in -the access log. - -</DL> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/developer/API.html b/docs/manual/developer/API.html deleted file mode 100644 index ad539e2abb..0000000000 --- a/docs/manual/developer/API.html +++ /dev/null @@ -1,1004 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<html><head> -<title>Apache API notes</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">Apache API notes</h1> - -These are some notes on the Apache API and the data structures you -have to deal with, etc. They are not yet nearly complete, but -hopefully, they will help you get your bearings. Keep in mind that -the API is still subject to change as we gain experience with it. -(See the TODO file for what <em>might</em> be coming). However, -it will be easy to adapt modules to any changes that are made. -(We have more modules to adapt than you do). -<p> - -A few notes on general pedagogical style here. In the interest of -conciseness, all structure declarations here are incomplete --- the -real ones have more slots that I'm not telling you about. For the -most part, these are reserved to one component of the server core or -another, and should be altered by modules with caution. However, in -some cases, they really are things I just haven't gotten around to -yet. Welcome to the bleeding edge.<p> - -Finally, here's an outline, to give you some bare idea of what's -coming up, and in what order: - -<ul> -<li> <a href="#basics">Basic concepts.</a> -<menu> - <li> <a href="#HMR">Handlers, Modules, and Requests</a> - <li> <a href="#moduletour">A brief tour of a module</a> -</menu> -<li> <a href="#handlers">How handlers work</a> -<menu> - <li> <a href="#req_tour">A brief tour of the <code>request_rec</code></a> - <li> <a href="#req_orig">Where request_rec structures come from</a> - <li> <a href="#req_return">Handling requests, declining, and returning error codes</a> - <li> <a href="#resp_handlers">Special considerations for response handlers</a> - <li> <a href="#auth_handlers">Special considerations for authentication handlers</a> - <li> <a href="#log_handlers">Special considerations for logging handlers</a> -</menu> -<li> <a href="#pools">Resource allocation and resource pools</a> -<li> <a href="#config">Configuration, commands and the like</a> -<menu> - <li> <a href="#per-dir">Per-directory configuration structures</a> - <li> <a href="#commands">Command handling</a> - <li> <a href="#servconf">Side notes --- per-server configuration, virtual servers, etc.</a> -</menu> -</ul> - -<h2><a name="basics">Basic concepts.</a></h2> - -We begin with an overview of the basic concepts behind the -API, and how they are manifested in the code. - -<h3><a name="HMR">Handlers, Modules, and Requests</a></h3> - -Apache breaks down request handling into a series of steps, more or -less the same way the Netscape server API does (although this API has -a few more stages than NetSite does, as hooks for stuff I thought -might be useful in the future). These are: - -<ul> - <li> URI -> Filename translation - <li> Auth ID checking [is the user who they say they are?] - <li> Auth access checking [is the user authorized <em>here</em>?] - <li> Access checking other than auth - <li> Determining MIME type of the object requested - <li> `Fixups' --- there aren't any of these yet, but the phase is - intended as a hook for possible extensions like - <code>SetEnv</code>, which don't really fit well elsewhere. - <li> Actually sending a response back to the client. - <li> Logging the request -</ul> - -These phases are handled by looking at each of a succession of -<em>modules</em>, looking to see if each of them has a handler for the -phase, and attempting invoking it if so. The handler can typically do -one of three things: - -<ul> - <li> <em>Handle</em> the request, and indicate that it has done so - by returning the magic constant <code>OK</code>. - <li> <em>Decline</em> to handle the request, by returning the magic - integer constant <code>DECLINED</code>. In this case, the - server behaves in all respects as if the handler simply hadn't - been there. - <li> Signal an error, by returning one of the HTTP error codes. - This terminates normal handling of the request, although an - ErrorDocument may be invoked to try to mop up, and it will be - logged in any case. -</ul> - -Most phases are terminated by the first module that handles them; -however, for logging, `fixups', and non-access authentication -checking, all handlers always run (barring an error). Also, the -response phase is unique in that modules may declare multiple handlers -for it, via a dispatch table keyed on the MIME type of the requested -object. Modules may declare a response-phase handler which can handle -<em>any</em> request, by giving it the key <code>*/*</code> (i.e., a -wildcard MIME type specification). However, wildcard handlers are -only invoked if the server has already tried and failed to find a more -specific response handler for the MIME type of the requested object -(either none existed, or they all declined).<p> - -The handlers themselves are functions of one argument (a -<code>request_rec</code> structure. vide infra), which returns an -integer, as above.<p> - -<h3><a name="moduletour">A brief tour of a module</a></h3> - -At this point, we need to explain the structure of a module. Our -candidate will be one of the messier ones, the CGI module --- this -handles both CGI scripts and the <code>ScriptAlias</code> config file -command. It's actually a great deal more complicated than most -modules, but if we're going to have only one example, it might as well -be the one with its fingers in every place.<p> - -Let's begin with handlers. In order to handle the CGI scripts, the -module declares a response handler for them. Because of -<code>ScriptAlias</code>, it also has handlers for the name -translation phase (to recognize <code>ScriptAlias</code>ed URIs), the -type-checking phase (any <code>ScriptAlias</code>ed request is typed -as a CGI script).<p> - -The module needs to maintain some per (virtual) -server information, namely, the <code>ScriptAlias</code>es in effect; -the module structure therefore contains pointers to a functions which -builds these structures, and to another which combines two of them (in -case the main server and a virtual server both have -<code>ScriptAlias</code>es declared).<p> - -Finally, this module contains code to handle the -<code>ScriptAlias</code> command itself. This particular module only -declares one command, but there could be more, so modules have -<em>command tables</em> which declare their commands, and describe -where they are permitted, and how they are to be invoked. <p> - -A final note on the declared types of the arguments of some of these -commands: a <code>pool</code> is a pointer to a <em>resource pool</em> -structure; these are used by the server to keep track of the memory -which has been allocated, files opened, etc., either to service a -particular request, or to handle the process of configuring itself. -That way, when the request is over (or, for the configuration pool, -when the server is restarting), the memory can be freed, and the files -closed, <i>en masse</i>, without anyone having to write explicit code to -track them all down and dispose of them. Also, a -<code>cmd_parms</code> structure contains various information about -the config file being read, and other status information, which is -sometimes of use to the function which processes a config-file command -(such as <code>ScriptAlias</code>). - -With no further ado, the module itself: - -<pre> -/* Declarations of handlers. */ - -int translate_scriptalias (request_rec *); -int type_scriptalias (request_rec *); -int cgi_handler (request_rec *); - -/* Subsidiary dispatch table for response-phase handlers, by MIME type */ - -handler_rec cgi_handlers[] = { -{ "application/x-httpd-cgi", cgi_handler }, -{ NULL } -}; - -/* Declarations of routines to manipulate the module's configuration - * info. Note that these are returned, and passed in, as void *'s; - * the server core keeps track of them, but it doesn't, and can't, - * know their internal structure. - */ - -void *make_cgi_server_config (pool *); -void *merge_cgi_server_config (pool *, void *, void *); - -/* Declarations of routines to handle config-file commands */ - -extern char *script_alias(cmd_parms *, void *per_dir_config, char *fake, - char *real); - -command_rec cgi_cmds[] = { -{ "ScriptAlias", script_alias, NULL, RSRC_CONF, TAKE2, - "a fakename and a realname"}, -{ NULL } -}; - -module cgi_module = { - STANDARD_MODULE_STUFF, - NULL, /* initializer */ - NULL, /* dir config creator */ - NULL, /* dir merger --- default is to override */ - make_cgi_server_config, /* server config */ - merge_cgi_server_config, /* merge server config */ - cgi_cmds, /* command table */ - cgi_handlers, /* handlers */ - translate_scriptalias, /* filename translation */ - NULL, /* check_user_id */ - NULL, /* check auth */ - NULL, /* check access */ - type_scriptalias, /* type_checker */ - NULL, /* fixups */ - NULL, /* logger */ - NULL /* header parser */ -}; -</pre> - -<h2><a name="handlers">How handlers work</a></h2> - -The sole argument to handlers is a <code>request_rec</code> structure. -This structure describes a particular request which has been made to -the server, on behalf of a client. In most cases, each connection to -the client generates only one <code>request_rec</code> structure.<p> - -<h3><a name="req_tour">A brief tour of the <code>request_rec</code></a></h3> - -The <code>request_rec</code> contains pointers to a resource pool -which will be cleared when the server is finished handling the -request; to structures containing per-server and per-connection -information, and most importantly, information on the request itself.<p> - -The most important such information is a small set of character -strings describing attributes of the object being requested, including -its URI, filename, content-type and content-encoding (these being filled -in by the translation and type-check handlers which handle the -request, respectively). <p> - -Other commonly used data items are tables giving the MIME headers on -the client's original request, MIME headers to be sent back with the -response (which modules can add to at will), and environment variables -for any subprocesses which are spawned off in the course of servicing -the request. These tables are manipulated using the -<code>table_get</code> and <code>table_set</code> routines. <p> -<BLOCKQUOTE> - Note that the <SAMP>Content-type</SAMP> header value <EM>cannot</EM> be - set by module content-handlers using the <SAMP>table_*()</SAMP> - routines. Rather, it is set by pointing the <SAMP>content_type</SAMP> - field in the <SAMP>request_rec</SAMP> structure to an appropriate - string. <EM>E.g.</EM>, - <PRE> - r->content_type = "text/html"; - </PRE> -</BLOCKQUOTE> -Finally, there are pointers to two data structures which, in turn, -point to per-module configuration structures. Specifically, these -hold pointers to the data structures which the module has built to -describe the way it has been configured to operate in a given -directory (via <code>.htaccess</code> files or -<code><Directory></code> sections), for private data it has -built in the course of servicing the request (so modules' handlers for -one phase can pass `notes' to their handlers for other phases). There -is another such configuration vector in the <code>server_rec</code> -data structure pointed to by the <code>request_rec</code>, which -contains per (virtual) server configuration data.<p> - -Here is an abridged declaration, giving the fields most commonly used:<p> - -<pre> -struct request_rec { - - pool *pool; - conn_rec *connection; - server_rec *server; - - /* What object is being requested */ - - char *uri; - char *filename; - char *path_info; - char *args; /* QUERY_ARGS, if any */ - struct stat finfo; /* Set by server core; - * st_mode set to zero if no such file */ - - char *content_type; - char *content_encoding; - - /* MIME header environments, in and out. Also, an array containing - * environment variables to be passed to subprocesses, so people can - * write modules to add to that environment. - * - * The difference between headers_out and err_headers_out is that - * the latter are printed even on error, and persist across internal - * redirects (so the headers printed for ErrorDocument handlers will - * have them). - */ - - table *headers_in; - table *headers_out; - table *err_headers_out; - table *subprocess_env; - - /* Info about the request itself... */ - - int header_only; /* HEAD request, as opposed to GET */ - char *protocol; /* Protocol, as given to us, or HTTP/0.9 */ - char *method; /* GET, HEAD, POST, etc. */ - int method_number; /* M_GET, M_POST, etc. */ - - /* Info for logging */ - - char *the_request; - int bytes_sent; - - /* A flag which modules can set, to indicate that the data being - * returned is volatile, and clients should be told not to cache it. - */ - - int no_cache; - - /* Various other config info which may change with .htaccess files - * These are config vectors, with one void* pointer for each module - * (the thing pointed to being the module's business). - */ - - void *per_dir_config; /* Options set in config files, etc. */ - void *request_config; /* Notes on *this* request */ - -}; - -</pre> - -<h3><a name="req_orig">Where request_rec structures come from</a></h3> - -Most <code>request_rec</code> structures are built by reading an HTTP -request from a client, and filling in the fields. However, there are -a few exceptions: - -<ul> - <li> If the request is to an imagemap, a type map (i.e., a - <code>*.var</code> file), or a CGI script which returned a - local `Location:', then the resource which the user requested - is going to be ultimately located by some URI other than what - the client originally supplied. In this case, the server does - an <em>internal redirect</em>, constructing a new - <code>request_rec</code> for the new URI, and processing it - almost exactly as if the client had requested the new URI - directly. <p> - - <li> If some handler signaled an error, and an - <code>ErrorDocument</code> is in scope, the same internal - redirect machinery comes into play.<p> - - <li> Finally, a handler occasionally needs to investigate `what - would happen if' some other request were run. For instance, - the directory indexing module needs to know what MIME type - would be assigned to a request for each directory entry, in - order to figure out what icon to use.<p> - - Such handlers can construct a <em>sub-request</em>, using the - functions <code>sub_req_lookup_file</code> and - <code>sub_req_lookup_uri</code>; this constructs a new - <code>request_rec</code> structure and processes it as you - would expect, up to but not including the point of actually - sending a response. (These functions skip over the access - checks if the sub-request is for a file in the same directory - as the original request).<p> - - (Server-side includes work by building sub-requests and then - actually invoking the response handler for them, via the - function <code>run_sub_request</code>). -</ul> - -<h3><a name="req_return">Handling requests, declining, and returning error codes</a></h3> - -As discussed above, each handler, when invoked to handle a particular -<code>request_rec</code>, has to return an <code>int</code> to -indicate what happened. That can either be - -<ul> - <li> OK --- the request was handled successfully. This may or may - not terminate the phase. - <li> DECLINED --- no erroneous condition exists, but the module - declines to handle the phase; the server tries to find another. - <li> an HTTP error code, which aborts handling of the request. -</ul> - -Note that if the error code returned is <code>REDIRECT</code>, then -the module should put a <code>Location</code> in the request's -<code>headers_out</code>, to indicate where the client should be -redirected <em>to</em>. <p> - -<h3><a name="resp_handlers">Special considerations for response handlers</a></h3> - -Handlers for most phases do their work by simply setting a few fields -in the <code>request_rec</code> structure (or, in the case of access -checkers, simply by returning the correct error code). However, -response handlers have to actually send a request back to the client. <p> - -They should begin by sending an HTTP response header, using the -function <code>send_http_header</code>. (You don't have to do -anything special to skip sending the header for HTTP/0.9 requests; the -function figures out on its own that it shouldn't do anything). If -the request is marked <code>header_only</code>, that's all they should -do; they should return after that, without attempting any further -output. <p> - -Otherwise, they should produce a request body which responds to the -client as appropriate. The primitives for this are <code>rputc</code> -and <code>rprintf</code>, for internally generated output, and -<code>send_fd</code>, to copy the contents of some <code>FILE *</code> -straight to the client. <p> - -At this point, you should more or less understand the following piece -of code, which is the handler which handles <code>GET</code> requests -which have no more specific handler; it also shows how conditional -<code>GET</code>s can be handled, if it's desirable to do so in a -particular response handler --- <code>set_last_modified</code> checks -against the <code>If-modified-since</code> value supplied by the -client, if any, and returns an appropriate code (which will, if -nonzero, be USE_LOCAL_COPY). No similar considerations apply for -<code>set_content_length</code>, but it returns an error code for -symmetry.<p> - -<pre> -int default_handler (request_rec *r) -{ - int errstatus; - FILE *f; - - if (r->method_number != M_GET) return DECLINED; - if (r->finfo.st_mode == 0) return NOT_FOUND; - - if ((errstatus = set_content_length (r, r->finfo.st_size)) - || (errstatus = set_last_modified (r, r->finfo.st_mtime))) - return errstatus; - - f = fopen (r->filename, "r"); - - if (f == NULL) { - log_reason("file permissions deny server access", - r->filename, r); - return FORBIDDEN; - } - - register_timeout ("send", r); - send_http_header (r); - - if (!r->header_only) send_fd (f, r); - pfclose (r->pool, f); - return OK; -} -</pre> - -Finally, if all of this is too much of a challenge, there are a few -ways out of it. First off, as shown above, a response handler which -has not yet produced any output can simply return an error code, in -which case the server will automatically produce an error response. -Secondly, it can punt to some other handler by invoking -<code>internal_redirect</code>, which is how the internal redirection -machinery discussed above is invoked. A response handler which has -internally redirected should always return <code>OK</code>. <p> - -(Invoking <code>internal_redirect</code> from handlers which are -<em>not</em> response handlers will lead to serious confusion). - -<h3><a name="auth_handlers">Special considerations for authentication handlers</a></h3> - -Stuff that should be discussed here in detail: - -<ul> - <li> Authentication-phase handlers not invoked unless auth is - configured for the directory. - <li> Common auth configuration stored in the core per-dir - configuration; it has accessors <code>auth_type</code>, - <code>auth_name</code>, and <code>requires</code>. - <li> Common routines, to handle the protocol end of things, at least - for HTTP basic authentication (<code>get_basic_auth_pw</code>, - which sets the <code>connection->user</code> structure field - automatically, and <code>note_basic_auth_failure</code>, which - arranges for the proper <code>WWW-Authenticate:</code> header - to be sent back). -</ul> - -<h3><a name="log_handlers">Special considerations for logging handlers</a></h3> - -When a request has internally redirected, there is the question of -what to log. Apache handles this by bundling the entire chain of -redirects into a list of <code>request_rec</code> structures which are -threaded through the <code>r->prev</code> and <code>r->next</code> -pointers. The <code>request_rec</code> which is passed to the logging -handlers in such cases is the one which was originally built for the -initial request from the client; note that the bytes_sent field will -only be correct in the last request in the chain (the one for which a -response was actually sent). - -<h2><a name="pools">Resource allocation and resource pools</a></h2> - -One of the problems of writing and designing a server-pool server is -that of preventing leakage, that is, allocating resources (memory, -open files, etc.), without subsequently releasing them. The resource -pool machinery is designed to make it easy to prevent this from -happening, by allowing resource to be allocated in such a way that -they are <em>automatically</em> released when the server is done with -them. <p> - -The way this works is as follows: the memory which is allocated, file -opened, etc., to deal with a particular request are tied to a -<em>resource pool</em> which is allocated for the request. The pool -is a data structure which itself tracks the resources in question. <p> - -When the request has been processed, the pool is <em>cleared</em>. At -that point, all the memory associated with it is released for reuse, -all files associated with it are closed, and any other clean-up -functions which are associated with the pool are run. When this is -over, we can be confident that all the resource tied to the pool have -been released, and that none of them have leaked. <p> - -Server restarts, and allocation of memory and resources for per-server -configuration, are handled in a similar way. There is a -<em>configuration pool</em>, which keeps track of resources which were -allocated while reading the server configuration files, and handling -the commands therein (for instance, the memory that was allocated for -per-server module configuration, log files and other files that were -opened, and so forth). When the server restarts, and has to reread -the configuration files, the configuration pool is cleared, and so the -memory and file descriptors which were taken up by reading them the -last time are made available for reuse. <p> - -It should be noted that use of the pool machinery isn't generally -obligatory, except for situations like logging handlers, where you -really need to register cleanups to make sure that the log file gets -closed when the server restarts (this is most easily done by using the -function <code><a href="#pool-files">pfopen</a></code>, which also -arranges for the underlying file descriptor to be closed before any -child processes, such as for CGI scripts, are <code>exec</code>ed), or -in case you are using the timeout machinery (which isn't yet even -documented here). However, there are two benefits to using it: -resources allocated to a pool never leak (even if you allocate a -scratch string, and just forget about it); also, for memory -allocation, <code>palloc</code> is generally faster than -<code>malloc</code>.<p> - -We begin here by describing how memory is allocated to pools, and then -discuss how other resources are tracked by the resource pool -machinery. - -<h3>Allocation of memory in pools</h3> - -Memory is allocated to pools by calling the function -<code>palloc</code>, which takes two arguments, one being a pointer to -a resource pool structure, and the other being the amount of memory to -allocate (in <code>char</code>s). Within handlers for handling -requests, the most common way of getting a resource pool structure is -by looking at the <code>pool</code> slot of the relevant -<code>request_rec</code>; hence the repeated appearance of the -following idiom in module code: - -<pre> -int my_handler(request_rec *r) -{ - struct my_structure *foo; - ... - - foo = (foo *)palloc (r->pool, sizeof(my_structure)); -} -</pre> - -Note that <em>there is no <code>pfree</code></em> --- -<code>palloc</code>ed memory is freed only when the associated -resource pool is cleared. This means that <code>palloc</code> does not -have to do as much accounting as <code>malloc()</code>; all it does in -the typical case is to round up the size, bump a pointer, and do a -range check.<p> - -(It also raises the possibility that heavy use of <code>palloc</code> -could cause a server process to grow excessively large. There are -two ways to deal with this, which are dealt with below; briefly, you -can use <code>malloc</code>, and try to be sure that all of the memory -gets explicitly <code>free</code>d, or you can allocate a sub-pool of -the main pool, allocate your memory in the sub-pool, and clear it out -periodically. The latter technique is discussed in the section on -sub-pools below, and is used in the directory-indexing code, in order -to avoid excessive storage allocation when listing directories with -thousands of files). - -<h3>Allocating initialized memory</h3> - -There are functions which allocate initialized memory, and are -frequently useful. The function <code>pcalloc</code> has the same -interface as <code>palloc</code>, but clears out the memory it -allocates before it returns it. The function <code>pstrdup</code> -takes a resource pool and a <code>char *</code> as arguments, and -allocates memory for a copy of the string the pointer points to, -returning a pointer to the copy. Finally <code>pstrcat</code> is a -varargs-style function, which takes a pointer to a resource pool, and -at least two <code>char *</code> arguments, the last of which must be -<code>NULL</code>. It allocates enough memory to fit copies of each -of the strings, as a unit; for instance: - -<pre> - pstrcat (r->pool, "foo", "/", "bar", NULL); -</pre> - -returns a pointer to 8 bytes worth of memory, initialized to -<code>"foo/bar"</code>. - -<h3><a name="pool-files">Tracking open files, etc.</a></h3> - -As indicated above, resource pools are also used to track other sorts -of resources besides memory. The most common are open files. The -routine which is typically used for this is <code>pfopen</code>, which -takes a resource pool and two strings as arguments; the strings are -the same as the typical arguments to <code>fopen</code>, e.g., - -<pre> - ... - FILE *f = pfopen (r->pool, r->filename, "r"); - - if (f == NULL) { ... } else { ... } -</pre> - -There is also a <code>popenf</code> routine, which parallels the -lower-level <code>open</code> system call. Both of these routines -arrange for the file to be closed when the resource pool in question -is cleared. <p> - -Unlike the case for memory, there <em>are</em> functions to close -files allocated with <code>pfopen</code>, and <code>popenf</code>, -namely <code>pfclose</code> and <code>pclosef</code>. (This is -because, on many systems, the number of files which a single process -can have open is quite limited). It is important to use these -functions to close files allocated with <code>pfopen</code> and -<code>popenf</code>, since to do otherwise could cause fatal errors on -systems such as Linux, which react badly if the same -<code>FILE*</code> is closed more than once. <p> - -(Using the <code>close</code> functions is not mandatory, since the -file will eventually be closed regardless, but you should consider it -in cases where your module is opening, or could open, a lot of files). - -<h3>Other sorts of resources --- cleanup functions</h3> - -More text goes here. Describe the the cleanup primitives in terms of -which the file stuff is implemented; also, <code>spawn_process</code>. - -<h3>Fine control --- creating and dealing with sub-pools, with a note -on sub-requests</h3> - -On rare occasions, too-free use of <code>palloc()</code> and the -associated primitives may result in undesirably profligate resource -allocation. You can deal with such a case by creating a -<em>sub-pool</em>, allocating within the sub-pool rather than the main -pool, and clearing or destroying the sub-pool, which releases the -resources which were associated with it. (This really <em>is</em> a -rare situation; the only case in which it comes up in the standard -module set is in case of listing directories, and then only with -<em>very</em> large directories. Unnecessary use of the primitives -discussed here can hair up your code quite a bit, with very little -gain). <p> - -The primitive for creating a sub-pool is <code>make_sub_pool</code>, -which takes another pool (the parent pool) as an argument. When the -main pool is cleared, the sub-pool will be destroyed. The sub-pool -may also be cleared or destroyed at any time, by calling the functions -<code>clear_pool</code> and <code>destroy_pool</code>, respectively. -(The difference is that <code>clear_pool</code> frees resources -associated with the pool, while <code>destroy_pool</code> also -deallocates the pool itself. In the former case, you can allocate new -resources within the pool, and clear it again, and so forth; in the -latter case, it is simply gone). <p> - -One final note --- sub-requests have their own resource pools, which -are sub-pools of the resource pool for the main request. The polite -way to reclaim the resources associated with a sub request which you -have allocated (using the <code>sub_req_lookup_...</code> functions) -is <code>destroy_sub_request</code>, which frees the resource pool. -Before calling this function, be sure to copy anything that you care -about which might be allocated in the sub-request's resource pool into -someplace a little less volatile (for instance, the filename in its -<code>request_rec</code> structure). <p> - -(Again, under most circumstances, you shouldn't feel obliged to call -this function; only 2K of memory or so are allocated for a typical sub -request, and it will be freed anyway when the main request pool is -cleared. It is only when you are allocating many, many sub-requests -for a single main request that you should seriously consider the -<code>destroy...</code> functions). - -<h2><a name="config">Configuration, commands and the like</a></h2> - -One of the design goals for this server was to maintain external -compatibility with the NCSA 1.3 server --- that is, to read the same -configuration files, to process all the directives therein correctly, -and in general to be a drop-in replacement for NCSA. On the other -hand, another design goal was to move as much of the server's -functionality into modules which have as little as possible to do with -the monolithic server core. The only way to reconcile these goals is -to move the handling of most commands from the central server into the -modules. <p> - -However, just giving the modules command tables is not enough to -divorce them completely from the server core. The server has to -remember the commands in order to act on them later. That involves -maintaining data which is private to the modules, and which can be -either per-server, or per-directory. Most things are per-directory, -including in particular access control and authorization information, -but also information on how to determine file types from suffixes, -which can be modified by <code>AddType</code> and -<code>DefaultType</code> directives, and so forth. In general, the -governing philosophy is that anything which <em>can</em> be made -configurable by directory should be; per-server information is -generally used in the standard set of modules for information like -<code>Alias</code>es and <code>Redirect</code>s which come into play -before the request is tied to a particular place in the underlying -file system. <p> - -Another requirement for emulating the NCSA server is being able to -handle the per-directory configuration files, generally called -<code>.htaccess</code> files, though even in the NCSA server they can -contain directives which have nothing at all to do with access -control. Accordingly, after URI -> filename translation, but before -performing any other phase, the server walks down the directory -hierarchy of the underlying filesystem, following the translated -pathname, to read any <code>.htaccess</code> files which might be -present. The information which is read in then has to be -<em>merged</em> with the applicable information from the server's own -config files (either from the <code><Directory></code> sections -in <code>access.conf</code>, or from defaults in -<code>srm.conf</code>, which actually behaves for most purposes almost -exactly like <code><Directory /></code>).<p> - -Finally, after having served a request which involved reading -<code>.htaccess</code> files, we need to discard the storage allocated -for handling them. That is solved the same way it is solved wherever -else similar problems come up, by tying those structures to the -per-transaction resource pool. <p> - -<h3><a name="per-dir">Per-directory configuration structures</a></h3> - -Let's look out how all of this plays out in <code>mod_mime.c</code>, -which defines the file typing handler which emulates the NCSA server's -behavior of determining file types from suffixes. What we'll be -looking at, here, is the code which implements the -<code>AddType</code> and <code>AddEncoding</code> commands. These -commands can appear in <code>.htaccess</code> files, so they must be -handled in the module's private per-directory data, which in fact, -consists of two separate <code>table</code>s for MIME types and -encoding information, and is declared as follows: - -<pre> -typedef struct { - table *forced_types; /* Additional AddTyped stuff */ - table *encoding_types; /* Added with AddEncoding... */ -} mime_dir_config; -</pre> - -When the server is reading a configuration file, or -<code><Directory></code> section, which includes one of the MIME -module's commands, it needs to create a <code>mime_dir_config</code> -structure, so those commands have something to act on. It does this -by invoking the function it finds in the module's `create per-dir -config slot', with two arguments: the name of the directory to which -this configuration information applies (or <code>NULL</code> for -<code>srm.conf</code>), and a pointer to a resource pool in which the -allocation should happen. <p> - -(If we are reading a <code>.htaccess</code> file, that resource pool -is the per-request resource pool for the request; otherwise it is a -resource pool which is used for configuration data, and cleared on -restarts. Either way, it is important for the structure being created -to vanish when the pool is cleared, by registering a cleanup on the -pool if necessary). <p> - -For the MIME module, the per-dir config creation function just -<code>palloc</code>s the structure above, and a creates a couple of -<code>table</code>s to fill it. That looks like this: - -<pre> -void *create_mime_dir_config (pool *p, char *dummy) -{ - mime_dir_config *new = - (mime_dir_config *) palloc (p, sizeof(mime_dir_config)); - - new->forced_types = make_table (p, 4); - new->encoding_types = make_table (p, 4); - - return new; -} -</pre> - -Now, suppose we've just read in a <code>.htaccess</code> file. We -already have the per-directory configuration structure for the next -directory up in the hierarchy. If the <code>.htaccess</code> file we -just read in didn't have any <code>AddType</code> or -<code>AddEncoding</code> commands, its per-directory config structure -for the MIME module is still valid, and we can just use it. -Otherwise, we need to merge the two structures somehow. <p> - -To do that, the server invokes the module's per-directory config merge -function, if one is present. That function takes three arguments: -the two structures being merged, and a resource pool in which to -allocate the result. For the MIME module, all that needs to be done -is overlay the tables from the new per-directory config structure with -those from the parent: - -<pre> -void *merge_mime_dir_configs (pool *p, void *parent_dirv, void *subdirv) -{ - mime_dir_config *parent_dir = (mime_dir_config *)parent_dirv; - mime_dir_config *subdir = (mime_dir_config *)subdirv; - mime_dir_config *new = - (mime_dir_config *)palloc (p, sizeof(mime_dir_config)); - - new->forced_types = overlay_tables (p, subdir->forced_types, - parent_dir->forced_types); - new->encoding_types = overlay_tables (p, subdir->encoding_types, - parent_dir->encoding_types); - - return new; -} -</pre> - -As a note --- if there is no per-directory merge function present, the -server will just use the subdirectory's configuration info, and ignore -the parent's. For some modules, that works just fine (e.g., for the -includes module, whose per-directory configuration information -consists solely of the state of the <code>XBITHACK</code>), and for -those modules, you can just not declare one, and leave the -corresponding structure slot in the module itself <code>NULL</code>.<p> - -<h3><a name="commands">Command handling</a></h3> - -Now that we have these structures, we need to be able to figure out -how to fill them. That involves processing the actual -<code>AddType</code> and <code>AddEncoding</code> commands. To find -commands, the server looks in the module's <code>command table</code>. -That table contains information on how many arguments the commands -take, and in what formats, where it is permitted, and so forth. That -information is sufficient to allow the server to invoke most -command-handling functions with pre-parsed arguments. Without further -ado, let's look at the <code>AddType</code> command handler, which -looks like this (the <code>AddEncoding</code> command looks basically -the same, and won't be shown here): - -<pre> -char *add_type(cmd_parms *cmd, mime_dir_config *m, char *ct, char *ext) -{ - if (*ext == '.') ++ext; - table_set (m->forced_types, ext, ct); - return NULL; -} -</pre> - -This command handler is unusually simple. As you can see, it takes -four arguments, two of which are pre-parsed arguments, the third being -the per-directory configuration structure for the module in question, -and the fourth being a pointer to a <code>cmd_parms</code> structure. -That structure contains a bunch of arguments which are frequently of -use to some, but not all, commands, including a resource pool (from -which memory can be allocated, and to which cleanups should be tied), -and the (virtual) server being configured, from which the module's -per-server configuration data can be obtained if required.<p> - -Another way in which this particular command handler is unusually -simple is that there are no error conditions which it can encounter. -If there were, it could return an error message instead of -<code>NULL</code>; this causes an error to be printed out on the -server's <code>stderr</code>, followed by a quick exit, if it is in -the main config files; for a <code>.htaccess</code> file, the syntax -error is logged in the server error log (along with an indication of -where it came from), and the request is bounced with a server error -response (HTTP error status, code 500). <p> - -The MIME module's command table has entries for these commands, which -look like this: - -<pre> -command_rec mime_cmds[] = { -{ "AddType", add_type, NULL, OR_FILEINFO, TAKE2, - "a mime type followed by a file extension" }, -{ "AddEncoding", add_encoding, NULL, OR_FILEINFO, TAKE2, - "an encoding (e.g., gzip), followed by a file extension" }, -{ NULL } -}; -</pre> - -The entries in these tables are: - -<ul> - <li> The name of the command - <li> The function which handles it - <li> a <code>(void *)</code> pointer, which is passed in the - <code>cmd_parms</code> structure to the command handler --- - this is useful in case many similar commands are handled by the - same function. - <li> A bit mask indicating where the command may appear. There are - mask bits corresponding to each <code>AllowOverride</code> - option, and an additional mask bit, <code>RSRC_CONF</code>, - indicating that the command may appear in the server's own - config files, but <em>not</em> in any <code>.htaccess</code> - file. - <li> A flag indicating how many arguments the command handler wants - pre-parsed, and how they should be passed in. - <code>TAKE2</code> indicates two pre-parsed arguments. Other - options are <code>TAKE1</code>, which indicates one pre-parsed - argument, <code>FLAG</code>, which indicates that the argument - should be <code>On</code> or <code>Off</code>, and is passed in - as a boolean flag, <code>RAW_ARGS</code>, which causes the - server to give the command the raw, unparsed arguments - (everything but the command name itself). There is also - <code>ITERATE</code>, which means that the handler looks the - same as <code>TAKE1</code>, but that if multiple arguments are - present, it should be called multiple times, and finally - <code>ITERATE2</code>, which indicates that the command handler - looks like a <code>TAKE2</code>, but if more arguments are - present, then it should be called multiple times, holding the - first argument constant. - <li> Finally, we have a string which describes the arguments that - should be present. If the arguments in the actual config file - are not as required, this string will be used to help give a - more specific error message. (You can safely leave this - <code>NULL</code>). -</ul> - -Finally, having set this all up, we have to use it. This is -ultimately done in the module's handlers, specifically for its -file-typing handler, which looks more or less like this; note that the -per-directory configuration structure is extracted from the -<code>request_rec</code>'s per-directory configuration vector by using -the <code>get_module_config</code> function. - -<pre> -int find_ct(request_rec *r) -{ - int i; - char *fn = pstrdup (r->pool, r->filename); - mime_dir_config *conf = (mime_dir_config *) - get_module_config(r->per_dir_config, &mime_module); - char *type; - - if (S_ISDIR(r->finfo.st_mode)) { - r->content_type = DIR_MAGIC_TYPE; - return OK; - } - - if((i=rind(fn,'.')) < 0) return DECLINED; - ++i; - - if ((type = table_get (conf->encoding_types, &fn[i]))) - { - r->content_encoding = type; - - /* go back to previous extension to try to use it as a type */ - - fn[i-1] = '\0'; - if((i=rind(fn,'.')) < 0) return OK; - ++i; - } - - if ((type = table_get (conf->forced_types, &fn[i]))) - { - r->content_type = type; - } - - return OK; -} - -</pre> - -<h3><a name="servconf">Side notes --- per-server configuration, virtual servers, etc.</a></h3> - -The basic ideas behind per-server module configuration are basically -the same as those for per-directory configuration; there is a creation -function and a merge function, the latter being invoked where a -virtual server has partially overridden the base server configuration, -and a combined structure must be computed. (As with per-directory -configuration, the default if no merge function is specified, and a -module is configured in some virtual server, is that the base -configuration is simply ignored). <p> - -The only substantial difference is that when a command needs to -configure the per-server private module data, it needs to go to the -<code>cmd_parms</code> data to get at it. Here's an example, from the -alias module, which also indicates how a syntax error can be returned -(note that the per-directory configuration argument to the command -handler is declared as a dummy, since the module doesn't actually have -per-directory config data): - -<pre> -char *add_redirect(cmd_parms *cmd, void *dummy, char *f, char *url) -{ - server_rec *s = cmd->server; - alias_server_conf *conf = (alias_server_conf *) - get_module_config(s->module_config,&alias_module); - alias_entry *new = push_array (conf->redirects); - - if (!is_url (url)) return "Redirect to non-URL"; - - new->fake = f; new->real = url; - return NULL; -} -</pre> -<!--#include virtual="footer.html" --> -</body></html> diff --git a/docs/manual/handler.html.en b/docs/manual/handler.html.en deleted file mode 100644 index 8059216112..0000000000 --- a/docs/manual/handler.html.en +++ /dev/null @@ -1,141 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache's Handler Use</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">Apache's Handler Use</h1> - -<h2>What is a Handler</h2> - -<p>A "handler" is an internal Apache representation of the action to be -performed when a file is called. Generally, files have implicit -handlers, based on the file type. Normally, all files are simply -served by the server, but certain file typed are "handled" -separately. For example, you may use a type of -"application/x-httpd-cgi" to invoke CGI scripts.</p> - -<p>Apache 1.1 adds the additional ability to use handlers -explicitly. Either based on filename extensions or on location, these -handlers are unrelated to file type. This is advantageous both because -it is a more elegant solution, but it also allows for both a type -<strong>and</strong> a handler to be associated with a file.</p> - -<p>Handlers can either be built into the server or to a module, or -they can be added with the <a -href="mod/mod_actions.html#action">Action</a> directive. The built-in -handlers in the standard distribution are as follows:</p> - -<ul> -<li><strong>send-as-is</strong>: - Send file with HTTP headers as is. - (<a href="mod/mod_asis.html">mod_asis</a>) -<li><strong>cgi-script</strong>: - Treat the file as a CGI script. - (<a href="mod/mod_cgi.html">mod_cgi</a>) -<li><strong>imap-file</strong>: - Imagemap rule file. - (<a href="mod/mod_imap.html">mod_imap</a>) -<li><strong>server-info</strong>: - Get the server's configuration information - (<a href="mod/mod_info.html">mod_info</a>) -<li><strong>server-parsed</strong>: - Parse for server-side includes - (<a href="mod/mod_include.html">mod_include</a>) -<li><strong>server-status</strong>: - Get the server's status report - (<a href="mod/mod_status.html">mod_status</a>) -<li><strong>type-map</strong>: - Parse as a type map file for content negotiation - (<a href="mod/mod_negotiation.html">mod_negotiation</a>) -</ul> - -<p> - -<h2>Directives</h2> -<ul> -<li><A HREF="#addhandler">AddHandler</A> -<li><A HREF="#sethandler">SetHandler</A> -</ul> - -<hr> - -<h2><a name="addhandler">AddHandler</a></h2> - -<strong>Syntax:</strong> <AddHandler <em>handler-name extension</em>><br> -<strong>Context:</strong> server config, virtual host, directory, .htaccess<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_mime - -<p>AddHandler maps the filename extension <em>extension</em> to the -handler <em>handler-name</em>. For example, to activate CGI scripts -with the file extension "<code>.cgi</code>", you might use: -<pre> - AddHandler cgi-script cgi -</pre> - -<p>Once that has been put into your srm.conf or httpd.conf file, any -file ending with "<code>.cgi</code>" will be treated as a CGI -program.</p> - -<hr> - -<h2><a name="sethandler">SetHandler</a></h2> - -<strong>Syntax:</strong> <SetHandler <em>handler-name</em>><br> -<strong>Context:</strong> directory, .htaccess<br> -<strong>Status:</strong> Base<br> -<strong>Module:</strong> mod_mime - -<p>When placed into an <code>.htaccess</code> file or a -<code><Directory></code> or <code><Location></code> section, -this directive forces all matching files to be parsed through the -handler given by <em>handler-name</em>. For example, if you had a -directory you wanted to be parsed entirely as imagemap rule files, -regardless of extension, you might put the following into an -<code>.htaccess</code> file in that directory: -<pre> - SetHandler imap-file -</pre> -<p>Another example: if you wanted to have the server display a status -report whenever a URL of <code>http://servername/status</code> was -called, you might put the following into access.conf: -<pre> - <Location /status> - SetHandler server-status - </Location> -</pre> - -<p><hr> - -<h2>Programmer's Note</h2> - -<p>In order to implement the handler features, an addition has been -made to the <a href="misc/API.html">Apache API</a> that you may wish to -make use of. Specifically, a new record has been added to the -<code>request_rec</code> structure:</p> -<pre> - char *handler -</pre> -<p>If you wish to have your module engage a handler, you need only to -set <code>r->handler</code> to the name of the handler at any time -prior to the <code>invoke_handler</code> stage of the -request. Handlers are implemented as they were before, albeit using -the handler name instead of a content type. While it is not -necessary, the naming convention for handlers is to use a -dash-separated word, with no slashes, so as to not invade the media -type name-space.</p> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/install.html.en b/docs/manual/install.html.en deleted file mode 100644 index 52e84b0c54..0000000000 --- a/docs/manual/install.html.en +++ /dev/null @@ -1,249 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Compiling and Installing Apache</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">Compiling and Installing Apache 1.2</H1> - -<P>If you wish to download and install an earlier version of Apache please -read <A HREF="install_1_1.html">Compiling and Installing Apache 1.1</A>.</P> - -UnixWare users will want to consult <A HREF="unixware.html">build notes</A> -for various UnixWare versions before compiling. - -<H2>Downloading Apache</H2> - -Information on the latest version of Apache can be found on the Apache -web server at <A -HREF="http://www.apache.org/">http://www.apache.org/</A>. This will -list the current release, any more recent beta-test release, together -with details of mirror web and anonymous ftp sites. - -<P> - -If you downloaded a binary distribution, skip to <A -HREF="#install">Installing Apache</A>. Otherwise read the next section -for how to compile the server. - -<h2>Compiling Apache</h2> - -Compiling Apache consists of three steps: Firstly select which Apache -<b>modules</b> you want to include into the server. Secondly create a -configuration for your operating system. Thirdly compile the -executable. -<P> - -All configuration of Apache is performed in the <CODE>src</CODE> -directory of the Apache distribution. Change into this directory. - -<OL> - <LI> - Select modules to compile into Apache in the - <CODE>Configuration</CODE> file. Uncomment lines corresponding to - those optional modules you wish to include (among the Module lines - at the bottom of the file), or add new lines corresponding to - additional modules you have downloaded or written. (See <A - HREF="misc/API.html">API.html</A> for preliminary docs on how to - write Apache modules). Advanced users can comment out some of the - default modules if they are sure they will not need them (be careful - though, since many of the default modules are vital for the correct - operation and security of the server). - <P> - - You should also read the instructions in the <CODE>Configuration</CODE> - file to see if you need to set any of the <CODE>Rule</CODE> lines. - - - <LI> - Configure Apache for your operating system. Normally you can just - type run the <CODE>Configure</CODE> script as given below. However - if this fails or you have any special requirements (e.g. to include - an additional library required by an optional module) you might need - to edit one or more of the following options in the - <CODE>Configuration</CODE> file: - <CODE>EXTRA_CFLAGS, LIBS, LFLAGS, INCLUDES</CODE>. - <P> - - Run the <CODE>Configure</CODE> script: - <BLOCKQUOTE> - <PRE> - % Configure - Using 'Configuration' as config file - + configured for <whatever> platform - + setting C compiler to <whatever> * - + setting C compiler optimization-level to <whatever> * - % - </PRE> - </BLOCKQUOTE> - - (*: Depending on Configuration and your system, Configure - make not print these lines. That's OK).<P> - - This generates a Makefile for use in stage 3. It also creates a - Makefile in the support directory, for compilation of the optional - support programs. - <P> - - (If you want to maintain multiple configurations, you can give a - option to <CODE>Configure</CODE> to tell it to read an alternative - Configuration file, such as <CODE>Configure -file - Configuration.ai</CODE>). - <P> - - <LI> - Type <CODE>make</CODE>. -</OL> - -The modules we place in the Apache distribution are the ones we have -tested and are used regularly by various members of the Apache -development group. Additional modules contributed by members or third -parties with specific needs or functions are available at <A -HREF="http://www.apache.org/dist/contrib/modules/"><URL:http://www.apache.org/dist/contrib/modules/></a>. -There are instructions on that page for linking these modules into the -core Apache code. - -<h2><A NAME="install">Installing Apache</A></h2> - -You will have a binary file called <CODE>httpd</CODE> in the -<CODE>src</CODE> directory. A binary distribution of Apache will -supply this file. <P> - -The next step is to install the program and configure it. Apache is -designed to be configured and run from the same set of directories -where it is compiled. If you want to run it from somewhere else, make -a directory and copy the <CODE>conf</CODE>, <CODE>logs</CODE> and -<CODE>icons</CODE> directories into it. <P> - -The next step is to edit the configuration files for the server. This -consists of setting up various <B>directives</B> in up to three -central configuration files. By default, these files are located in -the <CODE>conf</CODE> directory and are called <CODE>srm.conf</CODE>, -<CODE>access.conf</CODE> and <CODE>httpd.conf</CODE>. To help you get -started there are same files in the <CODE>conf</CODE> directory of the -distribution, called <CODE>srm.conf-dist</CODE>, -<CODE>access.conf-dist</CODE> and <CODE>httpd.conf-dist</CODE>. Copy -or rename these files to the names without the <CODE>-dist</CODE>. -Then edit each of the files. Read the comments in each file carefully. -Failure to setup these files correctly could lead to your server not -working or being insecure. You should also have an additional file in -the <CODE>conf</CODE> directory called <CODE>mime.types</CODE>. This -file usually does not need editing. - -<P> - -First edit <CODE>httpd.conf</CODE>. This sets up general attributes -about the server: the port number, the user it runs as, etc. Next -edit the <CODE>srm.conf</CODE> file; this sets up the root of the -document tree, special functions like server-parsed HTML or internal -imagemap parsing, etc. Finally, edit the <CODE>access.conf</CODE> -file to at least set the base cases of access. - -<P> - -In addition to these three files, the server behavior can be configured -on a directory-by-directory basis by using <CODE>.htaccess</CODE> -files in directories accessed by the server. - -<H3>Starting and Stopping the Server</H3> - -To start the server, simply run <CODE>httpd</CODE>. This will look for -<CODE>httpd.conf</CODE> in the location compiled into the code (by -default <CODE>/usr/locale/etc/httpd/conf/httpd.conf</CODE>). If -this file is somewhere else, you can give the real -location with the -f argument. For example: - -<PRE> - /usr/local/etc/apache/src/httpd -f /usr/local/etc/apache/conf/httpd.conf -</PRE> - -If all goes well this will return to the command prompt almost -immediately. This indicates that the server is now up and running. If -anything goes wrong during the initialization of the server you will -see an error message on the screen. - -If the server started ok, you can now use your browser to -connect to the server and read the documentation. If you are running -the browser on the same machine as the server and using the default -port of 80, a suitable URL to enter into your browser is - -<PRE> - http://localhost/ -</PRE> - -<P> - -Note that when the server starts it will create a number of -<i>child</i> processes to handle the requests. If you started Apache -as the root user, the parent process will continue to run as root -while the children will change to the user as given in the httpd.conf -file. - -<P> - -If when you run <CODE>httpd</CODE> it complained about being unable to -"bind" to an address, then either some other process is already using -the port you have configured Apache to use, or you are running httpd -as a normal user but trying to use port below 1024 (such as the -default port 80). - -<P> - -If the server is not running, read the error message displayed -when you run httpd. You should also check the server -error_log for additional information (with the default configuration, -this will be located in the file <CODE>error_log</CODE> in the -<CODE>logs</CODE> directory). - -<P> - -If you want your server to continue running after a system reboot, you -should add a call to <CODE>httpd</CODE> to your system startup files -(typically <CODE>rc.local</CODE> or a file in an -<CODE>rc.<I>N</I></CODE> directory). This will start Apache as root. -Before doing this ensure that your server is properly configured -for security and access restrictions. - -<P> - -To stop Apache send the parent process a TERM signal. The PID of this -process is written to the file <CODE>httpd.pid</CODE> in the -<CODE>logs</CODE> directory (unless configured otherwise). Do not -attempt to kill the child processes because they will be renewed by -the parent. A typical command to stop the server is: - -<PRE> - kill -TERM `cat /usr/local/etc/apache/logs/httpd.pid` -</PRE> - -<P> - -For more information about Apache command line options, configuration -and log files, see <A HREF="invoking.html">Starting Apache</A>. For a -reference guide to all Apache directives supported by the distributed -modules, see the <A HREF="mod/directives.html">Apache directives</A>. - -<H2>Compiling Support Programs</H2> - -In addition to the main <CODE>httpd</CODE> server which is compiled -and configured as above, Apache includes a number of support programs. -These are not compiled by default. The support programs are in the -<CODE>support</CODE> directory of the distribution. To compile -the support programs, change into this directory and type -<PRE> - make -</PRE> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/invoking.html.en b/docs/manual/invoking.html.en deleted file mode 100644 index 62e6a41af9..0000000000 --- a/docs/manual/invoking.html.en +++ /dev/null @@ -1,124 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Starting Apache</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">Starting Apache</h1> - -<h2>Invoking Apache</h2> -The <code>httpd</code> program is usually run as a daemon which executes -continuously, handling requests. It is possible to invoke Apache by -the Internet daemon <code>inetd</code> each time a connection to the HTTP -service is made (use the -<A HREF="mod/core.html#servertype">ServerType</A> directive) -but this is not recommended. - -<h2>Command line options</h2> -The following options are recognized on the httpd command line: -<dl> -<dt><code>-d</code> <em>serverroot</em> -<dd>Set the initial value for the -<A HREF="mod/core.html#serverroot">ServerRoot</A> variable to -<em>serverroot</em>. This can be overridden by the ServerRoot command in the -configuration file. The default is <code>/usr/local/etc/httpd</code>. - -<dt><code>-f</code> <em>config</em> -<dd>Execute the commands in the file <em>config</em> on startup. If -<em>config</em> does not begin with a <code>/</code>, then it is taken to be a -path relative to the <A HREF="mod/core.html#serverroot">ServerRoot</A>. The -default is <code>conf/httpd.conf</code>. - -<dt><code>-X</code> -<dd>Run in single-process mode, for internal debugging purposes only; the -daemon does not detach from the terminal or fork any children. Do <em>NOT</em> -use this mode to provide ordinary web service. - -<dt><code>-v</code> -<dd>Print the version of httpd, and then exit. - -<dt><a name="help"><code>-h</code></a> -<dd>Give a list of directives together with expected arguments and -places where the directive is valid. (New in Apache 1.2) - -<dt><code>-l</code> -<dd>Give a list of all modules compiled into the server. - -<dt><code>-?</code> -<dd>Print a list of the httpd options, and then exit. -</dl> - -<h2>Configuration files</h2> -The server will read three files for configuration directives. Any directive -may appear in any of these files. The the names of these files are taken -to be relative to the server root; this is set by the -<A HREF="mod/core.html#serverroot">ServerRoot</A> directive, or the -<code>-d</code> command line flag. - -Conventionally, the files are: -<dl> -<dt><code>conf/httpd.conf</code> -<dd>Contains directives that control the operation of the server daemon. -The filename may be overridden with the <code>-f</code> command line flag. - -<dt><code>conf/srm.conf</code> -<dd>Contains directives that control the specification of documents that -the server can provide to clients. The filename may be overridden with -the <A HREF="mod/core.html#resourceconfig">ResourceConfig</A> directive. - -<dt><code>conf/access.conf</code> -<dd>Contains directives that control access to documents. -The filename may be overridden with the -<A HREF="mod/core.html#accessconfig">AccessConfig</A> directive. -</dl> -However, these conventions need not be adhered to. -<p> -The server also reads a file containing mime document types; the filename -is set by the <A HREF="mod/mod_mime.html#typesconfig">TypesConfig</A> directive, -and is <code>conf/mime.types</code> by default. - -<h2>Log files</h2> -<h3>security warning</h3> -Anyone who can write to the directory where Apache is writing a -log file can almost certainly gain access to the uid that the server is -started as, which is normally root. Do <EM>NOT</EM> give people write -access to the directory the logs are stored in without being aware of -the consequences; see the <A HREF="misc/security_tips.html">security tips</A> -document for details. -<h3>pid file</h3> -On daemon startup, it saves the process id of the parent httpd process to -the file <code>logs/httpd.pid</code>. This filename can be changed with the -<A HREF="mod/core.html#pidfile">PidFile</A> directive. The process-id is for -use by the administrator in restarting and terminating the daemon; -A HUP or USR1 signal causes the daemon to re-read its configuration files and -a TERM signal causes it to die gracefully. For more information -see the <a href="stopping.html">Stopping and Restarting</a> page. -<p> -If the process dies (or is killed) abnormally, then it will be necessary to -kill the children httpd processes. - -<h3>Error log</h3> -The server will log error messages to a log file, <code>logs/error_log</code> -by default. The filename can be set using the -<A HREF="mod/core.html#errorlog">ErrorLog</A> directive; different error logs can -be set for different <A HREF="mod/core.html#virtualhost">virtual hosts</A>. - -<h3>Transfer log</h3> -The server will typically log each request to a transfer file, -<code>logs/access_log</code> by default. The filename can be set using a -<A HREF="mod/mod_log_common.html#transferlog">TransferLog</A> directive; different -transfer logs can be set for different <A HREF="mod/core.html#virtualhost">virtual -hosts</A>. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/misc/FAQ.html b/docs/manual/misc/FAQ.html index 94d257d661..ef0c292be0 100644 --- a/docs/manual/misc/FAQ.html +++ b/docs/manual/misc/FAQ.html @@ -15,7 +15,7 @@ <!--#include virtual="header.html" --> <H1 ALIGN="CENTER">Apache Server Frequently Asked Questions</H1> <P> - $Revision: 1.63 $ ($Date: 1997/06/04 11:42:55 $) + $Revision: 1.63.2.8 $ ($Date: 1997/07/05 17:30:58 $) </P> <P> The latest version of this FAQ is always available from the main @@ -35,6 +35,11 @@ <!-- apache.org or apacheweek.com). --> <!-- - When adding items, make sure they're put in the right place --> <!-- - verify that the numbering matches up. --> +<!-- - *Don't* use <PRE></PRE> blocks - they don't appear --> +<!-- correctly in a reliable way when this is converted to text --> +<!-- with Lynx. Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL> --> +<!-- blocks inside a <P></P> instead. This is necessary to get --> +<!-- the horizontal and vertical indenting right. --> <!-- - Don't forget to include an HR tag after the last /P tag --> <!-- but before the /LI in an item. --> <P> @@ -51,8 +56,8 @@ <!-- - mod_auth & passwd lines "user:pw:.*" - ++1st colon onward is --> <!-- treated as pw, not just ++1st to --2nd. --> <!-- - SSL: --> -<!-- Can I use Apache-SSL for free in Canada? --> -<!-- Why can't I use Apache-SSL in the U.S.? --> +<!-- - Can I use Apache-SSL for free in Canada? --> +<!-- - Why can't I use Apache-SSL in the U.S.? --> <!-- - How can I found out how many visitors my site gets? --> <!-- - How do I add a counter? --> <!-- - How do I configure Apache as a proxy? --> @@ -61,17 +66,17 @@ <!-- HTTP/1.1 browsers? --> <!-- - Is there an Apache for W95/WNT? --> <!-- - Why does Apache die when a vhost can't be DNS-resolved? --> -<!-- - How do I setup an access restriction so that people from --> -<!-- this domain don't have to authenticate, and all others can --> -<!-- do so via a username and password? --> <!-- - Why do I get "send lost connection" messages in my error --> <!-- log? --> <!-- - specifically consider .pdf files which seem to cause this --> <!-- a lot when accessed via the plugin ... and also mention --> <!-- how range-requests can cause bytes served < file size --> -<!-- - Why does http://host/~user not work but http://host/~user/ --> -<!-- works properly? --> +<!-- - Why do directory indexes appear as garbage? (A: -lucb) --> <!-- - How do I add a footer to all pages offered by my server? --> +<!-- - Fix midi question; a bigger problem than midi vs. x-midi is --> +<!-- the simple fact that older versions of Apache (and new ones --> +<!-- that have been upgraded without upgrading the mime.types --> +<!-- file) don't have the type listed at all. --> <UL> <LI><STRONG>Background</STRONG> <OL START=1> @@ -126,6 +131,8 @@ <LI><A HREF="#fdlim">Why can't I run more than <<EM>n</EM>> virtual hosts?</A> </LI> + <LI><A HREF="#freebsd-setsize">Can I increase FD_SETSIZE on FreeBSD?</A> + </LI> <LI><A HREF="#limitGET">Why do I keep getting "access denied" for form POST requests?</A> </LI> @@ -155,11 +162,14 @@ <LI><A HREF="#nodelay">Why am I getting "<SAMP>httpd: could not set socket option TCP_NODELAY</SAMP>" in my error log?</A> </LI> + <LI><A HREF="#peerreset">Why am I getting "<SAMP>connection + reset by peer</SAMP>" in my error log?</A> + </LI> <LI><A HREF="#nph-scripts">How can I get my script's output without Apache buffering it?</A> </LI> <LI><A HREF="#linuxiovec">Why do I get complaints about redefinition - of `struct iovec' when compiling under Linux?</A> + of "<CODE>struct iovec</CODE>" when compiling under Linux?</A> </LI> <LI><A HREF="#wheres-the-dump">The errorlog says Apache dumped core, but where's the dump file?</A> @@ -181,6 +191,35 @@ <LI><A HREF="#addlog">How do I add browsers and referrers to my logs?</A> </LI> + <LI><A HREF="#bind8.1">Why do I get an error about an undefined + reference to "<SAMP>__inet_ntoa</SAMP>" or other + <SAMP>__inet_*</SAMP> symbols?</A> + </LI> + <LI><A HREF="#set-servername">Why does accessing directories only work + when I include the trailing "/" + (<EM>e.g.</EM>, <SAMP>http://foo.domain.com/~user/</SAMP>) but + not when I omit it + (<EM>e.g.</EM>, <SAMP>http://foo.domain.com/~user</SAMP>)?</A> + </LI> + <LI><A HREF="#user-authentication">How do I set up Apache to require + a username and password to access certain documents?</A> + </LI> + <LI><A HREF="#remote-auth-only">How do I set up Apache to allow access + to certain documents only if a site is either a local site + <EM>or</EM> the user supplies a password and username?</A> + </LI> + <LI><A HREF="#no-info-directives">Why doesn't mod_info list any + directives?</A> + <LI><A HREF="#linux-shmget">When I run it under Linux I get "shmget: + function not found", what should I do?</A> + </LI> + <LI><A HREF="#authauthoritative">Why does my authentification give + me a server error?</A> + <LI><A HREF="#auth-on-same-machine">Do I have to keep the (mSQL) + authentification information on the same machine?</A> + </LI> + <LI><A HREF="#msql-slow">Why is my mSQL authentification terribly slow?</A> + </LI> </OL> </LI> </UL> @@ -222,8 +261,8 @@ programmers that httpd didn't behave as they wanted it to behave. Apache is an entirely volunteer effort, completely funded by its members, not by commercial sales. - <HR> </P> + <HR> </LI> <LI><A NAME="relate"> <STRONG>How does The Apache Group's work relate to other @@ -383,7 +422,7 @@ the server error log. Sometimes this is enough for you to diagnose & fix the problem yourself (such as file permissions or the like). The default location of the error log is - <CODE>/usr/local/etc/httpd/logs/error_log</CODE>, but see the + <SAMP>/usr/local/etc/httpd/logs/error_log</SAMP>, but see the <A HREF="../mod/core.html#errorlog" ><SAMP>ErrorLog</SAMP></A> @@ -446,16 +485,12 @@ dump, please include a backtrace (if possible). As an example, </P> <P> - <CODE> - <DL> - <DD># cd <EM>ServerRoot</EM> - </DD> - <DD># dbx httpd core - </DD> - <DD>(dbx) where - </DD> - </DL> - </CODE> + <DL> + <DD><CODE># cd <EM>ServerRoot</EM><BR> + # dbx httpd core<BR> + (dbx) where</CODE> + </DD> + </DL> </P> <P> (Substitute the appropriate locations for your @@ -524,15 +559,19 @@ </DD> </DL> </P> + <P> The server will then recognize that all files in that location (and its logical descendants) that end in "<SAMP>.cgi</SAMP>" are script files, not documents. + </P> </LI> <LI>Make sure that the directory location is covered by an <A HREF="../mod/core.html#options" ><SAMP>Options</SAMP></A> declaration that includes the <SAMP>ExecCGI</SAMP> option. + <P> + </P> </LI> </OL> <HR> @@ -544,27 +583,48 @@ <P> It means just what it says: the server was expecting a complete set of HTTP headers (one or more followed by a blank line), and didn't get - them. The most common cause of this (aside from people not - outputting the required headers at all) a result of an interaction - with perl's output buffering. To make perl flush its buffers - after each output statement, insert the following statements before your - first <CODE>print</CODE> or <CODE>write</CODE> statement: + them. </P> <P> - <CODE> - <DL> - <DD>$cfh = select (STDOUT); - </DD> - <DD>$| = 1; - </DD> - <DD>select ($cfh); - </DD> - </DL> - </CODE> + The most common cause of this problem is the script dying before + sending the complete set of headers, or possibly any at all, to the + server. To see if this is the case, try running the script standalone + from an interactive session, rather than as a script under the server. + If you get error messages, this is almost certainly the cause of the + "premature end of script headers" message. + </P> + <P> + The second most common cause of this (aside from people not + outputting the required headers at all) is a result of an interaction + with Perl's output buffering. To make Perl flush its buffers + after each output statement, insert the following statements around + the <CODE>print</CODE> or <CODE>write</CODE> statements that send your + HTTP headers: + </P> + <P> + <DL> + <DD><CODE>{<BR> + local ($oldbar) = $|;<BR> + $cfh = select (STDOUT);<BR> + $| = 1;<BR> + #<BR> + # print your HTTP headers here<BR> + #<BR> + $| = $oldbar;<BR> + select ($cfh);<BR> + }</CODE> + </DD> + </DL> </P> <P> This is generally only necessary when you are calling external - programs from your script that send output to stdout. + programs from your script that send output to stdout, or if there will + be a long delay between the time the headers are sent and the actual + content starts being emitted. To maximise performance, you should + turn buffer-flushing back <EM>off</EM> (with <CODE>$| = 0</CODE> or the + equivalent) after the statements that send the headers, as displayed + above. + </P> <P> If your script isn't written in Perl, do the equivalent thing for whatever language you <EM>are</EM> using (<EM>e.g.</EM>, for C, call @@ -587,7 +647,13 @@ Processing a document at run-time is called <EM>parsing</EM> it; hence the term "parsed HTML" sometimes used for documents that contain SSI instructions. Parsing tends to be <EM>extremely</EM> - resource-consumptive, and is not enabled by default. + resource-consumptive, and is not enabled by default. It can also + interfere with the cachability of your documents, which can put a + further load on your server. (see the + <A + HREF="#ssi-part-ii" + >next question</A> + for more information about this.) </P> <P> To enable SSI processing, you need to @@ -695,7 +761,11 @@ <STRONG>Does or will Apache act as a Proxy server?</STRONG> </A> <P> - Apache version 1.1 and above comes with a proxy module. If compiled + Apache version 1.1 and above comes with a + <A + HREF="../mod/mod_proxy.html" + >proxy module</A>. + If compiled in, this will make Apache act as a caching-proxy server. </P> <HR> @@ -761,8 +831,9 @@ HREF="../mod/core.html#listen" ><SAMP>Listen</SAMP></A> directives. If there are no other servers running on the machine - and all of them are running on the same port, you normally don't - need any Listen directives at all. + on the same port then you normally don't + need any Listen directives at all. By default Apache listens to + all addresses on port 80. </LI> <LI>Reduce the number of log files. You can use <A @@ -780,7 +851,8 @@ <A HREF="perf.html" >performance hints</A> - page. + page. There is a specific note for + <a href="#freebsd-setsize">FreeBSD</a> below. </LI> <LI>"Don't do that" - try to run with fewer virtual hosts </LI> @@ -794,8 +866,32 @@ <P> Since this is an operating-system limitation, there's not much else available in the way of solutions. + <P> + As of 1.2.1 we have made attempts to work around various limitations + involving running with many descriptors. + <a href="descriptors.html">More information is available.</a> </P> <HR> + </LI> + + <LI><A NAME="freebsd-setsize"> + <STRONG>Can I increase <SAMP>FD_SETSIZE</SAMP> on FreeBSD?</STRONG> + </A> + <P> + On FreeBSD 2.2 and older <SAMP>FD_SETSIZE</SAMP>, which limits the + number of open + files on the system, is limited to 256. This can restrict the number of + virtual hosts you can use; especially if they all use different log + files. Increasing this limit (and recompiling Apache) is not enough, + as it is on some platforms (such as Solaris), as you also will have + to recompile <SAMP>libc</SAMP> with the changed setting. + </P> + <P> + On FreeBSD 3.0 the default is 1024, so the problem is lessened. + </P> + <HR> + </LI> + <LI><A NAME="limitGET"> <STRONG>Why do I keep getting "access denied" for form POST requests?</STRONG> @@ -807,17 +903,13 @@ would affect the location where the POST-handling script resides: </P> <P> - <CODE> - <DL> - <DD><Limit GET> - </DD> - <DD> : - </DD> - </DL> - </CODE> + <DL> + <DD><CODE><Limit GET><BR> :</CODE> + </DD> + </DL> </P> <P> - Change that to <SAMP><Limit GET POST></SAMP> and the problem + Change that to <CODE><Limit GET POST></CODE> and the problem will probably go away. </P> <HR> @@ -875,12 +967,14 @@ warranty, though, and you'll lose all accumulated UNIX guru points. </P> <HR> + </LI> <LI><A NAME="errordoc401"> <STRONG>Why doesn't my <CODE>ErrorDocument 401</CODE> work?</STRONG> </A> <P> - You need to use it with a URL in the form "/foo/bar" and not one - with a method and hostname such as "http://host/foo/bar". See the + You need to use it with a URL in the form + "<SAMP>/foo/bar</SAMP>" and not one with a method and + hostname such as "<SAMP>http://host/foo/bar</SAMP>". See the <A HREF="../mod/core.html#errordocument" ><SAMP>ErrorDocument</SAMP></A> @@ -986,7 +1080,7 @@ </P> <P> <DL> - <DD><CODE>BrowserMatch Java/1.0 force-response-1.0</CODE> + <DD><CODE>BrowserMatch Java1.0 force-response-1.0</CODE> </DD> </DL> </P> @@ -1014,7 +1108,7 @@ ><CITE>Publishing Pages with PUT</CITE></A>. </P> <HR> - </LI> + </LI> <LI><A NAME="fastcgi"> <STRONG>Why isn't FastCGI included with Apache any more?</STRONG> </A> @@ -1045,6 +1139,20 @@ </P> <HR> </LI> + <LI><A NAME="peerreset"> + <STRONG>Why am I getting "<SAMP>connection reset by + peer</SAMP>" in my error log?</STRONG> + </A> + <P> + This is a normal message and nothing about which to be alarmed. It simply + means that the client cancelled the connection before it had been + completely set up - such as by the end-user pressing the "Stop" + button. People's patience being what it is, sites with response-time + problems or slow network links may experiences this more than + high-capacity ones or those with large pipes to the network. + </P> + <HR> + </LI> <LI><A NAME="nph-scripts"> <STRONG>How can I get my script's output without Apache buffering it?</STRONG> @@ -1079,25 +1187,25 @@ <P> As an example how you might handle the former (in a Perl script): </P> - <CODE> - <DL> - <DD>if ($0 =~ m:/*nph-:) { - <BR> - - $HTTP_headers = - "HTTP/1.1 200 OK\015\012"; - <BR> - - $HTTP_headers .= - "Connection: close\015\012"; - <BR> - - printf ($HTTP_headers); - <BR> - }; - </DD> - </DL> - </CODE> + <P> + <DL> + <DD><CODE>if ($0 =~ m:^(.*/)*nph-[^/]*$:) { + <BR> + + $HTTP_headers = + "HTTP/1.1 200 OK\015\012"; + <BR> + + $HTTP_headers .= + "Connection: close\015\012"; + <BR> + + print $HTTP_headers; + <BR> + }</CODE> + </DD> + </DL> + </P> <P> and then follow with your normal non-<SAMP>nph</SAMP> headers. </P> @@ -1105,13 +1213,15 @@ </LI> <LI><A NAME="linuxiovec"> <STRONG>Why do I get complaints about redefinition - of `struct iovec' when compiling under Linux?</STRONG> + of "<CODE>struct iovec</CODE>" when + compiling under Linux?</STRONG> </A> <P> This is a conflict between your C library includes and your kernel includes. You need to make sure that the versions of both are matched properly. There are two workarounds, either one will solve the problem: </P> + <P> <UL> <LI>Remove the definition of <CODE>struct iovec</CODE> from your C library includes. It is located in <CODE>/usr/include/sys/uio.h</CODE>. @@ -1122,6 +1232,7 @@ This hurts performance and should only be used as a last resort. </LI> </UL> + </P> <HR> </LI> <LI><A NAME="wheres-the-dump"> @@ -1129,7 +1240,7 @@ file?</STRONG> </A> <P> - In Apache version 1.2 (beginning with 1.2b8), the error log message + In Apache version 1.2, the error log message about dumped core includes the directory where the dump file should be located. However, many Unixes do not allow a process that has called <CODE>setuid()</CODE> to dump core for security reasons; @@ -1183,10 +1294,12 @@ this by adding the <SAMP>-DMAXIMUM_DNS</SAMP> clause to the <SAMP>EXTRA_CFLAGS</SAMP> definition in your <SAMP>Configuration</SAMP> file. For example: + <P> <DL> <DD><CODE>EXTRA_CFLAGS=-DMAXIMUM_DNS</CODE> </DD> </DL> + </P> <P> This will cause Apache to be very paranoid about making sure a particular host address is <EM>really</EM> assigned to the name it @@ -1227,8 +1340,8 @@ ><CITE>Apache and Secure Transactions</CITE></A>. </P> <HR> - </LI> - <LI><A NAME="HPUX-core"> + </LI> + <LI><A NAME="HPUX-core"> <STRONG>Why do I get core dumps under HPUX using HP's ANSI C compiler?</STRONG> </A> @@ -1259,10 +1372,12 @@ <LI>Instruct Apache to send a different <SAMP>Content-type</SAMP> header for these files by adding the following line to your server's configuration files: + <P> <DL> <DD><CODE>AddType audio/x-midi .mid .midi .kar</CODE> </DD> </DL> + </P> <P> Note that this may break browsers that <EM>do</EM> recognize the <SAMP>audio/midi</SAMP> MIME type unless they're prepared to also @@ -1275,7 +1390,7 @@ <LI><A NAME="cantbuild"> <STRONG>Why won't Apache compile with my system's <SAMP>cc</SAMP>?</STRONG> - </A> + </A> <P> If the server won't compile on your system, it is probably due to one of the following causes: @@ -1368,29 +1483,280 @@ </P> <HR> </LI> - <LI><A NAME="jdk1.x"> - <STRONG>Why do Java applets and applications not work - with documents on my Apache server?</A></STRONG> + <LI><A NAME="bind8.1"> + <STRONG>Why do I get an error about an undefined reference to + "<SAMP>__inet_ntoa</SAMP>" or other + <SAMP>__inet_*</SAMP> symbols?</STRONG> </A> <P> - The Java Development Kit (JDK) libraries versions 1.0.2 and 1.1 do not - correctly interpret the "<SAMP>HTTP/1.1</SAMP>" response - header that Apache 1.2 sends. Instead, if they don't see an exact - match for "<SAMP>HTTP/1.0</SAMP>", they assume the headers - are part of the document content. + If you have installed <A HREF="http://www.isc.org/bind.html">BIND-8</A> + then this is normally due to a conflict between your include files + and your libraries. BIND-8 installs its include files and libraries + <CODE>/usr/local/include/</CODE> and <CODE>/usr/local/lib/</CODE>, while + the resolver that comes with your system is probably installed in + <CODE>/usr/include/</CODE> and <CODE>/usr/lib/</CODE>. If + your system uses the header files in <CODE>/usr/local/include/</CODE> + before those in <CODE>/usr/include/</CODE> but you do not use the new + resolver library, then the two versions will conflict. + </P> + <P> + To resolve this, you can either make sure you use the include files + and libraries that came with your system or make sure to use the + new include files and libraries. Adding <CODE>-lbind</CODE> to the + <CODE>EXTRA_LDFLAGS</CODE> line in your <SAMP>Configuration</SAMP> + file, then re-running <SAMP>Configure</SAMP>, should resolve the + problem. (Apache versions 1.2.* and earlier use + <CODE>EXTRA_LFLAGS</CODE> instead.) </P> <P> - This is a known problem, and it has been reported to Sun's JavaSoft - unit. In the meantime, Apache 1.2 servers can work around this by - adding the following lines to their configuration files: + <STRONG>Note:</STRONG>As of BIND 8.1.1, the bind libraries and files are + installed under <SAMP>/usr/local/bind</SAMP> by default, so you + should not run into this problem. Should you want to use the bind + resolvers you'll have to add the following to the respective lines: </P> + <P> <DL> - <DD>BrowserMatch Java1.0 force-response-1.0</CODE> + <DD><CODE>EXTRA_CFLAGS=-I/usr/local/bind/include + <BR> + EXTRA_LDFLAGS=-L/usr/local/bind/lib + <BR> + EXTRA_LIBS=-lbind</CODE> </DD> </DL> + </P> <HR> - <!-- Don't forget to add HR tags at the end of each list item.. --> </LI> + <LI><A NAME="set-servername"> + <STRONG>Why does accessing directories only work when I include + the trailing "/" + (<EM>e.g.</EM>, <SAMP>http://foo.domain.com/~user/</SAMP>) + but not when I omit it + (<EM>e.g.</EM>, <SAMP>http://foo.domain.com/~user</SAMP>)?</STRONG> + </A> + <P> + When you access a directory without a trailing "/", Apache needs + to send what is called a redirect to the client to tell it to + add the trailing slash. If it did not do so, relative URLs would + not work properly. When it sends the redirect, it needs to know + the name of the server so that it can include it in the redirect. + There are two ways for Apache to find this out; either it can guess, + or you can tell it. If your DNS is configured correctly, it can + normally guess without any problems. If it is not, however, then + you need to tell it. + </P> + <P> + Add a <A HREF="../mod/core.html#servername">ServerName</A> directive + to the config file to tell it what the domain name of the server is. + </P> + <HR> + </LI> + <LI><A NAME="user-authentication"> + <STRONG>How do I set up Apache to require a username and + password to access certain documents?</STRONG> + </A> + <P> + There are several ways to do this; some of the more popular + ones are to use the <A HREF="../mod/mod_auth.html">mod_auth</A>, + <A HREF="../mod/mod_auth_db.html">mod_auth_db</A>, or + <A HREF="../mod/mod_auth_dbm.html">mod_auth_dbm</A> modules. + </P> + <P> + For an explaination on how to implement these restrictions, see + <A + HREF="http://www.apacheweek.com/" + ><CITE>Apache Week</CITE></A>'s + articles on + <A + HREF="http://www.apacheweek.com/features/userauth" + ><CITE>Using User Authentication</CITE></A> + or + <A + HREF="http://www.apacheweek.com/features/dbmauth" + ><CITE>DBM User Authentication</CITE></A>. + </P> + <HR> + </LI> + <LI><A NAME="remote-auth-only"> + <STRONG>How do I set up Apache to allow access to certain + documents only if a site is either a local site <EM>or</EM> + the user supplies a password and username?</STRONG> + </A> + <P> + Use the <A HREF="../mod/core.html#satisfy">Satisfy</A> directive, + in particular the <CODE>Satisfy Any</CODE> directive, to require + that only one of the access restrictions be met. For example, + adding the following configuration to a <SAMP>.htaccess</SAMP> + or server configuration file would restrict access to people who + either are accessing the site from a host under domain.com or + who can supply a valid username and password: + </P> + <P> + <DL> + <DD><CODE>deny from all + <BR> + allow from .domain.com + <BR> + AuthType Basic + <BR> + AuthUserFile /usr/local/etc/httpd/conf/htpasswd.users + <BR> + AuthName special directory + <BR> + require valid-user + <BR> + satisfy any</CODE> + </DD> + </DL> + </P> + <P> + See the <A HREF="#user-authentication">user authentication</A> + question and the <A HREF="../mod/mod_access.html">mod_access</A> + module for details on how the above directives work. + </P> + <HR> + </LI> + <LI><A NAME="no-info-directives"> + <STRONG>Why doesn't mod_info list any directives?</STRONG> + </A> + <P> + The + <A + HREF="../mod/mod_info.html" + ><SAMP>mod_info</SAMP></A> + module allows you to use a Web browser to see how your server is + configured. Among the information it displays is the list modules and + their configuration directives. The "current" values for + the directives are not necessarily those of the running server; they + are extracted from the configuration files themselves at the time of + the request. If the files have been changed since the server was last + reloaded, the display will will not match the values actively in use. + If the files and the path to the files are not readable by the user as + which the server is running (see the + <A + HREF="../mod/core.html#user" + ><SAMP>User</SAMP></A> + directive), then <SAMP>mod_info</SAMP> cannot read them in order to + list their values. An entry <EM>will</EM> be made in the error log in + this event, however. + </P> + <HR> + </LI> + <LI><A NAME="linux-shmget"> + <STRONG>When I run it under Linux I get "shmget: + function not found", what should I do?</STRONG> + </A> + <P> + Your kernel has been built without SysV IPC support. You will have to + rebuild the kernel with that support enabled (it's under the + "General Setup" submenu). Documentation for + kernel building is beyond the scope of this FAQ; you should consult + the + <A HREF="http://www.linuxhq.com/HOWTO/Kernel-HOWTO.html" + >Kernel HOWTO</A>, + or the documentation provided with your distribution, or a + <A HREF="http://www.linuxhq.com/HOWTO/META-FAQ.html" + >Linux newsgroup/mailing list</A>. + As a last-resort workaround, you can + comment out the <CODE>#define HAVE_SHMGET</CODE> definition in the + <SAMP>LINUX</SAMP> section of + <SAMP>src/conf.h</SAMP> and rebuild the server. This will produce + a server which is slower and less reliable. + </P> + <HR> + </LI> + <LI><A NAME="authauthoritative"> + <STRONG>Why does my authentification give me a server error?</STRONG> + </A> + <P> + Under normal circumstances, the Apache access control modules will + pass unrecognized user IDs on to the next access control module in + line. Only if the user ID is recognized and the password is validated + (or not) will it give the usual success or "authentification + failed" messages. + </P> + <P> + However, if the last access module in line 'declines' the validation + request (because it has never heard of the user ID or because it is not + configured), the <SAMP>http_request</SAMP> handler will give one of + the following, confusing, errors: + </P> + <UL> + <LI><SAMP>check access</SAMP> + </LI> + <LI><SAMP>check user. No user file?</SAMP> + </LI> + <LI><SAMP>check access. No groups file?</SAMP> + </LI> + </UL> + <P> + This does <EM>not</EM> mean that you have to add an + '<SAMP>AuthUserFile /dev/null</SAMP>' line as some magazines suggest! + </P> + <P> + The solution is to ensure that at least the last module is authoritative + and <STRONG>CONFIGURED</STRONG>. By default, <SAMP>mod_auth</SAMP> is + authoritative and will give an OK/Denied, but only if it is configured + with the proper <SAMP>AuthUserFile</SAMP>. Likewise, if a valid group + is required. (Remember that the modules are processed in the reverse + order from that in which they appear in your compile-time + <SAMP>Configuration</SAMP> file.) + </P> + <P> + A typical situation for this error is when you are using the + <SAMP>mod_auth_dbm</SAMP>, <SAMP>mod_auth_msql</SAMP>, + <SAMP>mod_auth_mysql</SAMP>, <SAMP>mod_auth_anon</SAMP> or + <SAMP>mod_auth_cookie</SAMP> modules on their own. These are by + default <STRONG>not</STRONG> authoritative, and this will pass the + buck on to the (non-existent) next authentification module when the + user ID is not in their respective database. Just add the appropriate + '<SAMP><EM>XXX</EM>Authoritative yes</SAMP>' line to the configuration. + </P> + <P> + In general it is a good idea (though not terribly efficient) to have the + file-based <SAMP>mod_auth</SAMP> a module of last resort. This allows + you to access the web server with a few special passwords even if the + databases are down or corrupted. This does cost a + file open/seek/close for each request in a protected area. + </P> + <HR> + </LI> + <LI><A NAME="auth-on-same-machine"> + <STRONG>Do I have to keep the (mSQL) authentification information + on the same machine?</STRONG> + </A> + <P> + Some organizations feel very strongly about keeping the authentification + information on a different machine than the webserver. With the + <SAMP>mod_auth_msql</SAMP>, <SAMP>mod_auth_mysql</SAMP>, and other SQL + modules connecting to (R)DBMses this is quite possible. Just configure + an explicit host to contact. + </P> + <P> + Be aware that with mSQL and Oracle, opening and closing these database + connections is very expensive and time consuming. You might want to + look at the code in the <SAMP>auth_*</SAMP> modules and play with the + compile time flags to alleviate this somewhat, if your RDBMS licences + allow for it. + </P> + <HR> + </LI> + <LI><A NAME="msql-slow"> + <STRONG>Why is my mSQL authentification terribly slow?</STRONG> + </A> + <P> + You have probably configured the Host by specificing a FQHN, + and thus the libmsql will use a full blown tcp/ip socket to talk to + the database, rather than a fast internal device. The + <SAMP>libmsql</SAMP>, the mSQL FAQ, and the <SAMP>mod_auth_msql</SAMP> + documentation warn you about this. If you have to use different + hosts, check out the <SAMP>mod_auth_msql</SAMP> code for + some compile time flags which might - or might not - suit you. + </P> + <HR> + </LI> + + <!-- Don't forget to add HR tags at the end of each list item.. --> + </OL> <!--#include virtual="footer.html" --> </BODY> diff --git a/docs/manual/misc/compat_notes.html b/docs/manual/misc/compat_notes.html index 56e20bb080..23adf537c6 100644 --- a/docs/manual/misc/compat_notes.html +++ b/docs/manual/misc/compat_notes.html @@ -33,18 +33,7 @@ href="http://www.apache.org/bugdb.cgi">let us know.</a> <LI>The basic mod_auth <CODE>AuthGroupFile</CODE>-specified group file format allows commas between user names - Apache does not.<BR> <I>- added 12/1/96</I> - -<LI><CODE>AddType</CODE> only accepts one file extension per line, without -any dots (<code>.</code>) in the extension, and does not take full filenames. -If you need multiple extensions per type, use multiple lines, e.g. -<blockquote><code> -AddType application/foo foo<br> -AddType application/foo bar -</code></blockquote> -To map <code>.foo</code> and <code>.bar</code> to <code>application/foo</code> -<p> - - + <p> <LI><P>If you follow the NCSA guidelines for setting up access restrictions based on client domain, you may well have added entries for, @@ -111,6 +100,9 @@ it added one automatically if the .asis file contained a Location header. files if the last line does not have a trailing newline. This affects configuration files (httpd.conf, access.conf and srm.conf), and htpasswd and htgroup files. + </LI> + + <LI>Apache does not permit commas delimiting the methods in <Limit>. </OL> diff --git a/docs/manual/misc/descriptors.html b/docs/manual/misc/descriptors.html new file mode 100644 index 0000000000..e5c97f3d21 --- /dev/null +++ b/docs/manual/misc/descriptors.html @@ -0,0 +1,155 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Descriptors and Apache</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">Descriptors and Apache</H1> + +<p>A <i>descriptor</i>, also commonly called a <i>file handle</i> is +an object that a program uses to read or write an open file, or open +network socket, or a variety of other devices. It is represented +by an integer, and you may be familiar with <code>stdin</code>, +<code>stdout</code>, and <code>stderr</code> which are descriptors 0, +1, and 2 respectively. +Apache needs a descriptor for each log file, plus one for each +network socket that it listens on, plus a handful of others. Libraries +that Apache uses may also require descriptors. Normal programs don't +open up many descriptors at all, and so there are some latent problems +that you may experience should you start running Apache with many +descriptors (i.e. with many virtual hosts). + +<p>The operating system enforces a limit on the number of descriptors +that a program can have open at a time. There are typically three limits +involved here. One is a kernel limitation, depending on your operating +system you will either be able to tune the number of descriptors available +to higher numbers (this is frequently called <i>FD_SETSIZE</i>). Or you +may be stuck with a (relatively) low amount. The second limit is called +the <i>hard resource</i> limit, and it is sometimes set by root in an +obscure operating system file, but frequently is the same as the kernel +limit. The third limit is called the <i>soft +resource</i> limit. The soft limit is always less than or equal to +the hard limit. For example, the hard limit may be 1024, but the soft +limit only 64. Any user can raise their soft limit up to the hard limit. +Root can raise the hard limit up to the system maximum limit. The soft +limit is the actual limit that is used when enforcing the maximum number +of files a process can have open. + +<p>To summarize: + +<center><pre> + #open files <= soft limit <= hard limit <= kernel limit +</pre></center> + +<p>You control the hard and soft limits using the <code>limit</code> (csh) +or <code>ulimit</code> (sh) directives. See the respective man pages +for more information. For example you can probably use +<code>ulimit -n unlimited</code> to raise your soft limit up to the +hard limit. You should include this command in a shell script which +starts your webserver. + +<p>Unfortunately, it's not always this simple. As mentioned above, +you will probably run into some system limitations that will need to be +worked around somehow. Work was done in version 1.2.1 to improve the +situation somewhat. Here is a partial list of systems and workarounds +(assuming you are using 1.2.1 or later): + +<dl> + + <dt> <b>BSDI 2.0</b> + <dd> Under BSDI 2.0 you can build Apache to support more descriptors + by adding <code>-DFD_SETSIZE=nnn</code> to + <code>EXTRA_CFLAGS</code> (where nnn is the number of descriptors + you wish to support, keep it less than the hard limit). But it + will run into trouble if more than approximately 240 Listen + directives are used. This may be cured by rebuilding your kernel + with a higher FD_SETSIZE. + <p> + + <dt> <b>FreeBSD 2.2, BSDI 2.1+</b> + <dd> Similar to the BSDI 2.0 case, you should define + <code>FD_SETSIZE</code> and rebuild. But the extra + Listen limitation doesn't exist. + <p> + + <dt> <b>Linux</b> + <dd> By default Linux has a kernel maximum of 256 open descriptors + per process. There are several patches available for the + 2.0.x series which raise this to 1024 and beyond, and you + can find them in the "unofficial patches" section of <a + href="http://www.linuxhq.com/">the Linux Information HQ</a>. + None of these patches are perfect, and an entirely different + approach is likely to be taken during the 2.1.x development. + Applying these patches will raise the FD_SETSIZE used to compile + all programs, and unless you rebuild all your libraries you should + avoid running any other program with a soft descriptor limit above + 256. As of this writing the patches available for increasing + the number of descriptors do not take this into account. On a + dedicated webserver you probably won't run into trouble. + <p> + + <dt> <b>Solaris through 2.5.1</b> + <dd> Solaris has a kernel hard limit of 1024 (may be lower in earlier + versions). But it has a limitation that files using + the stdio library cannot have a descriptor above 255. + Apache uses the stdio library for the ErrorLog directive. + When you have more than approximately 110 virtual hosts + (with an error log and an access log each) you will need to + build Apache with <code>-DHIGH_SLACK_LINE=256</code> added to + <code>EXTRA_CFLAGS</code>. You will be limited to approximately + 240 error logs if you do this. + <p> + + <dt> <b>AIX version ??</b> + <dd> AIX appears to have a hard limit of 128 descriptors. End of + story. + <p> + + <dt> <b>Others</b> + <dd> If you have details on another operating system, please submit + it through our <a href="http://www.apache.org/bug_report.html">Bug + Report Page</a>. + <p> + +</dl> + +<p>In addition to the problems described above there are problems with +many libraries that Apache uses. The most common example is the bind +DNS resolver library that is used by pretty much every unix, which +fails if it ends up with a descriptor above 256. We suspect there +are other libraries that similar limitations. So the code as of 1.2.1 +takes a defensive stance and tries to save descriptors less than 16 +for use while processing each request. This is called the <i>low +slack line</i>. + +<p>Note that this shouldn't waste descriptors. If you really are pushing +the limits and Apache can't get a descriptor above 16 when it wants +it, it will settle for one below 16. + +<p>In extreme situations you may want to lower the low slack line, +but you shouldn't ever need to. For example, lowering it can +increase the limits 240 described above under Solaris and BSDI 2.0. +But you'll play a delicate balancing game with the descriptors needed +to serve a request. Should you want to play this game, the compile +time parameter is <code>LOW_SLACK_LINE</code> and there's a tiny +bit of documentation in the header file <code>httpd.h</code>. + +<p>Finally, if you suspect that all this slack stuff is causing you +problems, you can disable it. Add <code>-DNO_SLACK</code> to +<code>EXTRA_CFLAGS</code> and rebuild. But please report it to +our <a href="http://www.apache.org/bug_report.html">Bug +Report Page</a> so that +we can investigate. + +<!--#include virtual="footer.html" --> +</BODY> +</HTML> diff --git a/docs/manual/misc/fin_wait_2.html b/docs/manual/misc/fin_wait_2.html index 48e10874af..4b9d60ad3a 100644 --- a/docs/manual/misc/fin_wait_2.html +++ b/docs/manual/misc/fin_wait_2.html @@ -57,13 +57,13 @@ not send back a FIN and ACK to the server. This means that the connection stays in the FIN_WAIT_2 state until one of the following happens:<P> <UL> - <LI>The client opens a new connection to the same or a different - site, which causes it to fully close the older connection on + <LI>The client opens a new connection to the same or a different + site, which causes it to fully close the older connection on that socket. - <LI>The user exits the client, which on some (most?) clients - causes the OS to fully shutdown the connection. - <LI>The FIN_WAIT_2 times out, on servers that have a timeout - for this state. + <LI>The user exits the client, which on some (most?) clients + causes the OS to fully shutdown the connection. + <LI>The FIN_WAIT_2 times out, on servers that have a timeout + for this state. </UL><P> If you are lucky, this means that the buggy client will fully close the connection and release the resources on your server. However, there @@ -77,16 +77,16 @@ TCP implementation.</STRONG> <P> The clients on which this problem has been verified to exist:<P> <UL> - <LI>Mozilla/3.01 (X11; I; FreeBSD 2.1.5-RELEASE i386) - <LI>Mozilla/2.02 (X11; I; FreeBSD 2.1.5-RELEASE i386) - <LI>Mozilla/3.01Gold (X11; I; SunOS 5.5 sun4m) - <LI>MSIE 3.01 on the Macintosh - <LI>MSIE 3.01 on Windows 95 + <LI>Mozilla/3.01 (X11; I; FreeBSD 2.1.5-RELEASE i386) + <LI>Mozilla/2.02 (X11; I; FreeBSD 2.1.5-RELEASE i386) + <LI>Mozilla/3.01Gold (X11; I; SunOS 5.5 sun4m) + <LI>MSIE 3.01 on the Macintosh + <LI>MSIE 3.01 on Windows 95 </UL><P> This does not appear to be a problem on: <UL> - <LI>Mozilla/3.01 (Win95; I) + <LI>Mozilla/3.01 (Win95; I) </UL> <P> @@ -155,56 +155,56 @@ violation of the RFC, but it is widely recognized as being necessary. The following systems are known to have a timeout: <P> <UL> - <LI><A HREF="http://www.freebsd.org/">FreeBSD</A> versions starting at 2.0 or possibly earlier. - <LI><A HREF="http://www.netbsd.org/">NetBSD</A> version 1.2(?) - <LI><A HREF="http://www.openbsd.org/">OpenBSD</A> all versions(?) - <LI><A HREF="http://www.bsdi.com/">BSD/OS</A> 2.1, with the - <A HREF="ftp://ftp.bsdi.com/bsdi/patches/patches-2.1/K210-027"> - K210-027</A> patch installed. - <LI><A HREF="http://www.sun.com/">Solaris</A> as of around version - 2.2. The timeout can be tuned by using <CODE>ndd</CODE> to - modify <CODE>tcp_fin_wait_2_flush_interval</CODE>, but the - default should be appropriate for most servers and improper - tuning can have negative impacts. - <LI><A HREF="http://www.sco.com/">SCO TCP/IP Release 1.2.1</A> - can be modified to have a timeout by following - <A HREF="http://www.sco.com/cgi-bin/waisgate?WAISdocID=2242622956+0+0+0&WAISaction=retrieve"> SCO's instructions</A>. - <LI><A HREF="http://www.linux.org/">Linux</A> 2.0.x and - earlier(?) - <LI><A HREF="http://www.hp.com/">HP-UX</A> 10.x defaults to - terminating connections in the FIN_WAIT_2 state after the - normal keepalive timeouts. This does not - refer to the persistent connection or HTTP keepalive - timeouts, but the <CODE>SO_LINGER</CODE> socket option - which is enabled by Apache. This parameter can be adjusted - by using <CODE>nettune</CODE> to modify parameters such as - <CODE>tcp_keepstart</CODE> and <CODE>tcp_keepstop</CODE>. - In later revisions, there is an explicit timer for - connections in FIN_WAIT_2 that can be modified; contact HP - support for details. - <LI><A HREF="http://www.sgi.com/">SGI IRIX</A> can be patched to - support a timeout. For IRIX 5.3, 6.2, and 6.3, - use patches 1654, 1703 and 1778 respectively. If you - have trouble locating these patches, please contact your - SGI support channel for help. - <LI><A HREF="http://www.ncr.com/">NCR's MP RAS Unix</A> 2.xx and - 3.xx both have FIN_WAIT_2 timeouts. In 2.xx it is non-tunable - at 600 seconds, while in 3.xx it defaults to 600 seconds and - is calculated based on the tunable "max keep alive probes" - (default of 8) multiplied by the "keep alive interval" (default - 75 seconds). - <LI><A HREF="http://www.sequent.com">Squent's ptx/TCP/IP for - DYNIX/ptx</A> has had a FIN_WAIT_2 timeout since around - release 4.1 in mid-1994. + <LI><A HREF="http://www.freebsd.org/">FreeBSD</A> versions starting at 2.0 or possibly earlier. + <LI><A HREF="http://www.netbsd.org/">NetBSD</A> version 1.2(?) + <LI><A HREF="http://www.openbsd.org/">OpenBSD</A> all versions(?) + <LI><A HREF="http://www.bsdi.com/">BSD/OS</A> 2.1, with the + <A HREF="ftp://ftp.bsdi.com/bsdi/patches/patches-2.1/K210-027"> + K210-027</A> patch installed. + <LI><A HREF="http://www.sun.com/">Solaris</A> as of around version + 2.2. The timeout can be tuned by using <CODE>ndd</CODE> to + modify <CODE>tcp_fin_wait_2_flush_interval</CODE>, but the + default should be appropriate for most servers and improper + tuning can have negative impacts. + <LI><A HREF="http://www.sco.com/">SCO TCP/IP Release 1.2.1</A> + can be modified to have a timeout by following + <A HREF="http://www.sco.com/cgi-bin/waisgate?WAISdocID=2242622956+0+0+0&WAISaction=retrieve"> SCO's instructions</A>. + <LI><A HREF="http://www.linux.org/">Linux</A> 2.0.x and + earlier(?) + <LI><A HREF="http://www.hp.com/">HP-UX</A> 10.x defaults to + terminating connections in the FIN_WAIT_2 state after the + normal keepalive timeouts. This does not + refer to the persistent connection or HTTP keepalive + timeouts, but the <CODE>SO_LINGER</CODE> socket option + which is enabled by Apache. This parameter can be adjusted + by using <CODE>nettune</CODE> to modify parameters such as + <CODE>tcp_keepstart</CODE> and <CODE>tcp_keepstop</CODE>. + In later revisions, there is an explicit timer for + connections in FIN_WAIT_2 that can be modified; contact HP + support for details. + <LI><A HREF="http://www.sgi.com/">SGI IRIX</A> can be patched to + support a timeout. For IRIX 5.3, 6.2, and 6.3, + use patches 1654, 1703 and 1778 respectively. If you + have trouble locating these patches, please contact your + SGI support channel for help. + <LI><A HREF="http://www.ncr.com/">NCR's MP RAS Unix</A> 2.xx and + 3.xx both have FIN_WAIT_2 timeouts. In 2.xx it is non-tunable + at 600 seconds, while in 3.xx it defaults to 600 seconds and + is calculated based on the tunable "max keep alive probes" + (default of 8) multiplied by the "keep alive interval" (default + 75 seconds). + <LI><A HREF="http://www.sequent.com">Squent's ptx/TCP/IP for + DYNIX/ptx</A> has had a FIN_WAIT_2 timeout since around + release 4.1 in mid-1994. </UL> <P> The following systems are known to not have a timeout: <P> <UL> - <LI><A HREF="http://www.sun.com/">SunOS 4.x</A> does not and - almost certainly never will have one because it as at the - very end of its development cycle for Sun. If you have kernel - source should be easy to patch. + <LI><A HREF="http://www.sun.com/">SunOS 4.x</A> does not and + almost certainly never will have one because it as at the + very end of its development cycle for Sun. If you have kernel + source should be easy to patch. </UL> <P> There is a @@ -266,6 +266,12 @@ many systems, this can be done by adding the line mbuf clusters you want to your kernel config file and rebuilding your kernel.<P> </DL> + +<H3>Disable KeepAlive</H3> +<P>If you are unable to do any of the above then you should, as a last +resort, disable KeepAlive. Edit your httpd.conf and change "KeepAlive On" +to "KeepAlive Off". + <H2><LI>Feedback</H2> If you have any information to add to this page, please contact me at diff --git a/docs/manual/misc/index.html b/docs/manual/misc/index.html index 127b1f2f0d..2b44c66131 100644 --- a/docs/manual/misc/index.html +++ b/docs/manual/misc/index.html @@ -21,92 +21,92 @@ </P> <DL> <DT><A - HREF="API.html" + HREF="API.html" >API</A> </DT> <DD>Description of Apache's Application Programming Interface. </DD> <DT><A - HREF="FAQ.html" + HREF="FAQ.html" >FAQ</A> </DT> <DD>Frequently-Asked Questions concerning the Apache project and server </DD> <DT><A - HREF="client_block_api.html" + HREF="client_block_api.html" >Reading Client Input in Apache 1.2</A> </DT> <DD>Describes differences between Apache 1.1 and 1.2 in how modules read information from the client </DD> <DT><A - HREF="compat_notes.html" + HREF="compat_notes.html" >Compatibility with NCSA</A> </DT> <DD>Notes about Apache's compatibility with the NCSA server </DD> <DT><A - HREF="fin_wait_2.html" + HREF="fin_wait_2.html" ><SAMP>FIN_WAIT_2</SAMP></A> </DT> <DD>A description of the causes of Apache processes going into the <SAMP>FIN_WAIT_2</SAMP> state, and what you can do about it </DD> <DT><A - HREF="howto.html" + HREF="howto.html" >"How-To"</A> </DT> <DD>Instructions about how to accomplish some commonly-desired server functionality changes </DD> <DT><A - HREF="known_bugs.html" + HREF="known_bugs.html" >Known Bugs</A> </DT> <DD>Just what it says - a list of known bugs in each of the Apache releases </DD> <DT><A - HREF="nopgp.html" + HREF="nopgp.html" >No PGP</A> </DT> <DD>Why we took PEM and PGP support out of the base Apache distribution </DD> <DT><A - HREF="perf-bsd44.html" + HREF="perf-bsd44.html" >Performance Notes (BSD 4.4)</A> </DT> <DD>Some notes about ways to improve/optimize Apache performance on BSD 4.4 systems </DD> <DT><A - HREF="perf-dec.html" + HREF="perf-dec.html" >Performance Notes (Digital UNIX)</A> </DT> <DD>Extracts of USENET postings describing how to optimize Apache performance on Digital UNIX systems </DD> <DT><A - HREF="perf.html" + HREF="perf.html" >Performance Notes (General)</A> </DT> <DD>Some generic notes about how to improve Apache performance </DD> <DT><A - HREF="security_tips.html" + HREF="security_tips.html" >Security Tips</A> </DT> <DD>Some "do"s - and "don't"s - for keeping your Apache web site secure </DD> <DT><A - HREF="vif-info.html" + HREF="vif-info.html" >Virtual Hosts (IP-based)</A> </DT> <DD>Excerpts and notes about configuring and using Apache IP-based virtual hosts </DD> <DT><A - HREF="windoz_keepalive.html" + HREF="windoz_keepalive.html" >Windows Bug with Web Keepalive</A> </DT> <DD>A brief description of a known problem with Microsoft Windows and diff --git a/docs/manual/misc/security_tips.html b/docs/manual/misc/security_tips.html index cba41ada90..21b51771cb 100644 --- a/docs/manual/misc/security_tips.html +++ b/docs/manual/misc/security_tips.html @@ -170,7 +170,6 @@ Also be wary of playing games with the >UserDir</A> directive; setting it to something like <SAMP>"./"</SAMP> would have the same effect, for root, as the first example above. -</P> <HR> <P>Please send any other useful security tips to The Apache Group diff --git a/docs/manual/mod/core.html b/docs/manual/mod/core.html index fde6c351a2..186a315b57 100644 --- a/docs/manual/mod/core.html +++ b/docs/manual/mod/core.html @@ -44,6 +44,7 @@ always available. <li><A HREF="#limit"><Limit></A> <li><A HREF="#listen">Listen</A> <li><A HREF="#location"><Location></A> +<li><A HREF="#lockfile">LockFile</A> <li><A HREF="#maxclients">MaxClients</A> <li><A HREF="#maxkeepaliverequests">MaxKeepAliveRequests</a> <li><A HREF="#maxrequestsperchild">MaxRequestsPerChild</A> @@ -714,7 +715,7 @@ the <Location ~ "/(extra|special)/data"> </pre> -would match URLs that contained the substring "/extra/data" or +<p>would match URLs that contained the substring "/extra/data" or "/special/data".</p> <p>The <code>Location</code> functionality is especially useful when @@ -732,7 +733,23 @@ from browsers at foo.com, you might use: </pre> <hr> -<A name="maxclients"><h2>MaxClients directive</h2></A> +<A NAME="lockfile"><H2>LockFile</H2></A> +<strong>Syntax:</strong> LockFile <em>filename</em><BR> +<strong>Default:</strong> <code>LockFile logs/accept.lock</code><BR> +<strong>Context:</strong> server config<BR> +<strong>Status:</strong> core<P> + +The LockFile directive sets the path to the lockfile used when +Apache is compiled with either USE_FCNTL_SERIALIZED_ACCEPT or +USE_FLOCK_SERIALIZED_ACCEPT. This directive should normally be +left at its default value. The main reason for changing it is if +the <code>logs</code> directory is NFS mounted, since the lockfile +should be stored on a local disk if possible. The PID of the main +server process is automatically appended to the filename. + +<P><HR> + +<A name="maxclients"><h2>MaxClients</h2></A> <!--%plaintext <?INDEX {\tt MaxClients} directive> --> <strong>Syntax:</strong> MaxClients <em>number</em><br> <strong>Default:</strong> <code>MaxClients 256</code><br> @@ -836,6 +853,9 @@ Execution of CGI scripts is permitted. <dd> <!--%plaintext <?INDEX {\tt FollowSymLinks} option> --> The server will follow symbolic links in this directory. +<b>Note</b>: even though the server follows the symlink it does <i>not</i> +change the pathname used to match against <code><Directory></code> +sections. <dt>Includes <dd> <!--%plaintext <?INDEX {\tt Includes} option> --> @@ -1031,7 +1051,7 @@ sections; in fact it can now contain any server directive allowed in the See also <A HREF="#accessconfig">AccessConfig</A>.<p><hr> -<A name="rlimit"> +<A name="rlimit"> </A> <A name="rlimitcpu"><h2>RLimitCPU directive</h2></A> <!--%plaintext <?INDEX {\tt RLimitCPU} directive> --> <strong>Syntax:</strong> RLimitCPU <em># or 'max'</em> <em>[# or 'max']</em><br> @@ -1158,7 +1178,7 @@ release.<p> <A name="sendbuffersize"><h2>SendBufferSize directive</h2></A> <!--%plaintext <?INDEX {\tt SendBufferSize} directive> --> <strong>Syntax:</strong> SendBufferSize <em>bytes</em><br> -<strong>Context:</strong> server config, virtual host<br> +<strong>Context:</strong> server config<br> <strong>Status:</strong> core<p> The server will set the TCP buffer size to the number of bytes diff --git a/docs/manual/mod/directives.html b/docs/manual/mod/directives.html index 23599099c2..b2645a45a5 100644 --- a/docs/manual/mod/directives.html +++ b/docs/manual/mod/directives.html @@ -106,6 +106,7 @@ <li><A HREF="mod_dld.html#loadfile">LoadFile</A> <li><A HREF="mod_dld.html#loadmodule">LoadModule</A> <li><A HREF="core.html#location"><Location></A> +<li><A HREF="core.html#lockfile">LockFile</A> <li><A HREF="mod_log_config.html#logformat">LogFormat</A> <li><A HREF="core.html#maxclients">MaxClients</A> <li><A HREF="core.html#maxkeepaliverequests">MaxKeepAliveRequests</A> diff --git a/docs/manual/mod/mod_auth_anon.html b/docs/manual/mod/mod_auth_anon.html index c880c34ee1..c1b6933053 100644 --- a/docs/manual/mod/mod_auth_anon.html +++ b/docs/manual/mod/mod_auth_anon.html @@ -61,23 +61,23 @@ allows users to share URLs. <strong>Status:</strong> Extension<br> <strong>Module:</strong> mod_auth_anon<p> - A list of one or more 'magic' userIDs which are allowed access - without password verification. The userIDs are space separated. - It is possible to use the ' and " quotes to allow a space in - a userID as well as the \ escape character. - <p> - Please note that the comparison is <b>case-IN-sensitive</b>. - <br> - I strongly suggest that the magic username '<code>anonymous</code>' - is always one of the allowed userIDs. - <p> - Example:<br> - <code> - Anonymous: anonymous "Not Registered" 'I don\'t know' - </code><p> - This would allow the user to enter without password verification - by using the userId's 'anonymous', 'AnonyMous','Not Registered' and - 'I Don't Know'. + A list of one or more 'magic' userIDs which are allowed access + without password verification. The userIDs are space separated. + It is possible to use the ' and " quotes to allow a space in + a userID as well as the \ escape character. + <p> + Please note that the comparison is <b>case-IN-sensitive</b>. + <br> + I strongly suggest that the magic username '<code>anonymous</code>' + is always one of the allowed userIDs. + <p> + Example:<br> + <code> + Anonymous: anonymous "Not Registered" 'I don\'t know' + </code><p> + This would allow the user to enter without password verification + by using the userId's 'anonymous', 'AnonyMous','Not Registered' and + 'I Don't Know'. <HR> <A name="Authoritative"><h2>Anonymous_Authoritative</h2></A> @@ -91,12 +91,12 @@ allows users to share URLs. When set 'on', there is no fall-through to other authorization methods. So if a userID does not match the values specified in the - <code>Anonymous</code> directive, access is denied. - <p> - Be sure you know what you are doing when you decide to switch - it on. And remember that it is the linking order of the modules - (in the Configuration / Make file) which details the order - in which the Authorization modules are queried. + <code>Anonymous</code> directive, access is denied. + <p> + Be sure you know what you are doing when you decide to switch + it on. And remember that it is the linking order of the modules + (in the Configuration / Make file) which details the order + in which the Authorization modules are queried. <hr> <A name="LogEmail"><h2>Anonymous_LogEmail</h2></A> @@ -107,8 +107,8 @@ allows users to share URLs. <strong>Status:</strong> Extension<br> <strong>Module:</strong> mod_auth_anon<p> - When set 'on', the default, the 'password' entered (which hopefully - contains a sensible email address) is logged in the httpd-log file. + When set 'on', the default, the 'password' entered (which hopefully + contains a sensible email address) is logged in the httpd-log file. <hr> <A name="MustGiveEmail"><h2>Anonymous_MustGiveEmail</h2></a> @@ -120,8 +120,8 @@ allows users to share URLs. <strong>Status:</strong> Extension<br> <strong>Module:</strong> mod_auth_anon<p> - Specifies whether the user must specify an email - address as the password. This prohibits blank passwords. + Specifies whether the user must specify an email + address as the password. This prohibits blank passwords. <HR> <A name="NoUserID"><h2>Anonymous_NoUserID</h2></A> @@ -132,11 +132,11 @@ allows users to share URLs. <strong>Status:</strong> Extension<br> <strong>Module:</strong> mod_auth_anon<p> - When set 'on', users can leave - the userID (and perhaps the password field) empty. This - can be very convenient for MS-Explorer users who can - just hit return or click directly on the OK button; which - seems a natural reaction. + When set 'on', users can leave + the userID (and perhaps the password field) empty. This + can be very convenient for MS-Explorer users who can + just hit return or click directly on the OK button; which + seems a natural reaction. <hr> @@ -148,9 +148,9 @@ allows users to share URLs. <strong>Status:</strong> Extension<br> <strong>Module:</strong> mod_auth_anon<p> - When set 'on' the 'password' entered is - checked for at least one '@' and a '.' to encourage users to enter - valid email addresses (see the above <code>Auth_LogEmail</code>). + When set 'on' the 'password' entered is + checked for at least one '@' and a '.' to encourage users to enter + valid email addresses (see the above <code>Auth_LogEmail</code>). <hr><a name="Example"><h2>Example</h2></a> @@ -180,10 +180,10 @@ Excerpt of access.conf: <dl> <dt><code> Anonymous anonymous guest www test welcome<p> -Anonymous_MustGiveEmail on<br> +Anonymous_MustGiveEmail on<br> Anonymous_VerifyEmail on<br> -Anonymous_NoUserId off<br> -Anonymous_LogEmail on<br> +Anonymous_NoUserId off<br> +Anonymous_LogEmail on<br> <p> AuthName Use 'anonymous' & Email address for guest entry<br> AuthType basic<p> @@ -217,8 +217,8 @@ This version: 23 Nov 1995, 24 Feb 1996, 16 May 1996. </dd> <dt>Version 0.5<br></dt> <dd>Added 'VerifyEmail' and 'LogEmail' options. Multiple - 'anonymous' tokens allowed. more docs. Added Authoritative - functionality. + 'anonymous' tokens allowed. more docs. Added Authoritative + functionality. </dd> </dl> diff --git a/docs/manual/mod/mod_include.html b/docs/manual/mod/mod_include.html index 6f51130998..f1576471e6 100644 --- a/docs/manual/mod/mod_include.html +++ b/docs/manual/mod/mod_include.html @@ -309,15 +309,15 @@ elements are: Unix egrep command. <DT>( <I>test_condition</I> ) - <DD>true if <I>test_condition</I> is true + <DD>true if <I>test_condition</I> is true <DT>! <I>test_condition</I> - <DD>true if <I>test_condition</I> is false + <DD>true if <I>test_condition</I> is false <DT><I>test_condition1</I> && <I>test_condition2</I> - <DD>true if both <I>test_condition1</I> and - <I>test_condition2</I> are true + <DD>true if both <I>test_condition1</I> and + <I>test_condition2</I> are true <DT><I>test_condition1</I> || <I>test_condition2</I> - <DD>true if either <I>test_condition1</I> or - <I>test_condition2</I> is true + <DD>true if either <I>test_condition1</I> or + <I>test_condition2</I> is true </DL> <P> "<I>=</I>" and "<I>!=</I>" bind more tightly than "<I>&&</I>" and diff --git a/docs/manual/mod/mod_mime.html b/docs/manual/mod/mod_mime.html index fa150c88e0..fd3e6b09df 100644 --- a/docs/manual/mod/mod_mime.html +++ b/docs/manual/mod/mod_mime.html @@ -20,22 +20,44 @@ compiled in by default. It provides for determining the types of files from the filename. <h2>Summary</h2> -This module is used to determine the mime types of documents. Some mime -types indicate special processing to be performed by the server, otherwise -the type is returned to the client so that the browser can deal with -the document appropriately.<p> - -The filename of a document is treated as being composed of a basename followed -by some extensions, in the following order: -<blockquote><em>base.type.language.enc</em></blockquote> -The <em>type</em> extension sets the type of the document; types are defined -in the <A HREF="#typesconfig">TypesConfig</A> file and by the -<A HREF="#addtype">AddType</A> directive. The <em>language</em> extension -sets the language of the document, as defined by the -<A HREF="#addlanguage">AddLanguage</A> directive. Finally, the -<em>enc</em> directive sets the encoding of the document, as defined by -the <A HREF="#addencoding">AddEncoding</A> directive. +This module is used to determine various bits of "meta information" +about documents. This information relates to the content of the +document and is returned to the browser or used in content-negotiation +within the server. In addition, a "handler" can be set for a document, +which determines how the document will be processed within the server. + +<P> + +The directives <A HREF="#addencoding">AddEncoding</A>, <A +HREF="#addhandler">AddHandler</A>, <A +HREF="#addlanguage">AddLanguage</A> and <A HREF="#addtype">AddType</A> +are all used to map file extensions onto the meta-information for that +file. Respectively they set the content-encoding, handler, +content-language and mime-type (content-type) of documents. The +directive <A HREF="#typesconfig">TypesConfig</A> is used to specify a +file which also maps extensions onto mime types. The directives <A +HREF="#forcetype">ForceType</A> and <A +HREF="#sethandler">SetHandler</A> are used to associated all the files +in a given location (e.g. a particular directory) onto a particular +mime type or handler. + +<P> + +Files can have more than one extension, and the order of the +extensions is normally irrelevant. For example, if the file +<CODE>welcome.html.fr</CODE> maps onto content type text/html and +language French then the file <CODE>welcome.fr.html</CODE> will map +onto exactly the same information. The only exception to this is if an +extension is given which Apache does not know how to handle. In this +case it will "forget" about any information it obtained from +extensions to the left of the unknown extension. So, for example, if +the extensions fr and html are mapped to the appropriate language and +type but extension xxx is not assigned to anything, then the file +<CODE>welcome.fr.xxx.html</CODE> will be associated with content-type +text/html but <i>no</i> language. + +<P> <h2> Directives</h2> <ul> @@ -72,14 +94,14 @@ encoding, and .Z files to be marked as encoded with x-compress.<p><hr> <h2><a name="addhandler">AddHandler</a></h2> -<strong>Syntax:</strong> <AddHandler <em>handler-name extension</em>><br> +<strong>Syntax:</strong> AddHandler <em>handler-name extension extension...</em><br> <strong>Context:</strong> server config, virtual host, directory, .htaccess<br> <strong>Status:</strong> Base<br> <strong>Module:</strong> mod_mime<br> <strong>Compatibility:</strong> AddHandler is only available in Apache 1.1 and later<p> -<p>AddHandler maps the filename extension <em>extension</em> to the +<p>AddHandler maps the filename extensions <em>extension</em> to the <a href="../handler.html">handler</a> <em>handler-name</em>. For example, to activate CGI scripts with the file extension "<code>.cgi</code>", you might use: @@ -138,7 +160,7 @@ type of particular files.<p><hr> <h2><a name="forcetype">ForceType</a></h2> -<strong>Syntax:</strong> <ForceType <em>media type</em>><br> +<strong>Syntax:</strong> ForceType <em>media type</em><br> <strong>Context:</strong> directory, .htaccess<br> <strong>Status:</strong> Base<br> <strong>Module:</strong> mod_mime<br> @@ -159,7 +181,7 @@ media type.</p> <h2><a name="sethandler">SetHandler</a></h2> -<strong>Syntax:</strong> <SetHandler <em>handler-name</em>><br> +<strong>Syntax:</strong> SetHandler <em>handler-name</em><br> <strong>Context:</strong> directory, .htaccess<br> <strong>Status:</strong> Base<br> <strong>Module:</strong> mod_mime<br> diff --git a/docs/manual/mod/mod_proxy.html b/docs/manual/mod/mod_proxy.html index e0aef68846..30926d4da6 100644 --- a/docs/manual/mod/mod_proxy.html +++ b/docs/manual/mod/mod_proxy.html @@ -297,7 +297,7 @@ disables caching completely.<p> <li><a href="#shortname">Using Netscape hostname shortcuts</a> <li><a href="#mimetypes">Why doesn't file type <i>xxx</i> download via FTP?</a> <li><a href="#startup">Why does Apache start more slowly when using the - proxy module?</a> + proxy module?</a> <li><a href="#socks">Can I use the Apache proxy module with my SOCKS proxy?</a> </ul> @@ -337,7 +337,7 @@ application/octet-stream bin dms lha lzh exe class tgz taz </pre> <h2><a name="startup">Why does Apache start more slowly when using the - proxy module?</a></h2> + proxy module?</a></h2> If you're using the <code>ProxyBlock</code> or <code>NoCache</code> directives, hostnames' IP addresses are looked up and cached during diff --git a/docs/manual/mod/mod_rewrite.html b/docs/manual/mod/mod_rewrite.html index 03eaa5801f..4cb6c83b85 100644 --- a/docs/manual/mod/mod_rewrite.html +++ b/docs/manual/mod/mod_rewrite.html @@ -44,7 +44,6 @@ substitution. It operates on the full URLs (including the PATH_INFO part) both in per-server context (httpd.conf) and per-dir context (.htaccess) and even can generate QUERY_STRING parts on result. The rewritten result can lead to internal sub-processing, external request redirection or to internal proxy throughput. -</b> <p> The latest version can be found on<br> @@ -147,7 +146,7 @@ with a slash ('<tt>/</tt>') then it is assumed to be relative to the config. <p> -<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> +<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> <tr><td> To disable the logging of rewriting actions it is not recommended to set <em>Filename</em> @@ -161,7 +160,7 @@ To disable logging either remove or comment out the </table> <p> -<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> +<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> <tr><td> SECURITY: See the <a href="../misc/security_tips.html">Apache Security @@ -198,7 +197,7 @@ To disable the logging of rewriting actions simply set <em>Level</em> to 0. This disables all rewrite action logs. <p> -<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> +<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> <tr><td> <b>Notice:</b> Using a high value for <i>Level</i> will slow down your Apache server dramatically! Use the rewriting logfile only for debugging or at least @@ -289,7 +288,7 @@ RewriteMap real-to-host txt:/path/to/file/map.real-to-user <li><b>DBM Hashfile Format</b> <p> This is a binary NDBM format file containing the - same contents as the <em>Plain Text Format</b> files. You can create + same contents as the <em>Plain Text Format</em> files. You can create such a file with any NDBM tool or with the <tt>dbmmanage</tt> program from the <tt>support</tt> directory of the Apache distribution. <p> @@ -346,7 +345,7 @@ context it is of course possible to <b>use</b> this map in per-directory context. <p> -<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> +<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> <tr><td> For plain text and DBM format files the looked-up keys are cached in-core until the <tt>mtime</tt> of the mapfile changes or the server does a @@ -384,7 +383,7 @@ will be usually be wrong!</b> There you have to use the <tt>RewriteBase</tt> directive to specify the correct URL-prefix. <p> -<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> +<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> <tr><td> So, if your webserver's URLs are <b>not</b> directly related to physical file paths, you have to use <tt>RewriteBase</tt> in every @@ -424,7 +423,7 @@ In the above example, a request to <tt>/xyz/oldstuff.html</tt> gets correctly rewritten to the physical file <tt>/abc/def/newstuff.html</tt>. <p> -<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> +<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> <tr><td> <font size=-1> <b>For the Apache hackers:</b><br> @@ -437,10 +436,10 @@ Request: /xyz/oldstuff.html Internal Processing: - /xyz/oldstuff.html -> /abc/def/oldstuff.html (per-server Alias) - /abc/def/oldstuff.html -> /abc/def/newstuff.html (per-dir RewriteRule) - /abc/def/newstuff.html -> /xyz/newstuff.html (per-dir RewriteBase) - /xyz/newstuff.html -> /abc/def/newstuff.html (per-server Alias) + /xyz/oldstuff.html -> /abc/def/oldstuff.html (per-server Alias) + /abc/def/oldstuff.html -> /abc/def/newstuff.html (per-dir RewriteRule) + /abc/def/newstuff.html -> /xyz/newstuff.html (per-dir RewriteBase) + /xyz/newstuff.html -> /abc/def/newstuff.html (per-server Alias) Result: /abc/def/newstuff.html @@ -471,7 +470,7 @@ sure the design and implementation is correct. <p> The <tt>RewriteCond</tt> directive defines a rule condition. Precede a -<tt>RewriteRule</tt> directive with one or more <t>RewriteCond</tt> +<tt>RewriteRule</tt> directive with one or more <tt>RewriteCond</tt> directives. The following rewriting rule is only used if its pattern matches the current @@ -562,7 +561,7 @@ IS_SUBREQ<br> <p> -<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> +<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> <tr><td> These variables all correspond to the similar named HTTP MIME-headers, C variables of the Apache server or <tt>struct tm</tt> fields of the Unix @@ -770,7 +769,7 @@ for special cases where it is better to match the negative pattern or as a last default rule. <p> -<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> +<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> <tr><td> <b>Notice!</b> When using the NOT character to negate a pattern you cannot have grouped wildcard parts in the pattern. This is impossible because when @@ -814,7 +813,7 @@ conjunction with the <b>C</b> (chain) flag to be able to have more than one pattern to be applied before a substitution occurs. <p> -<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> +<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> <tr><td> <b>Notice</b>: There is a special feature. When you prefix a substitution field with <tt>http://</tt><em>thishost</em>[<em>:thisport</em>] then @@ -962,7 +961,7 @@ comma-separated list of the following flags: typical example is the use of <tt>mod_alias</tt> and <tt>mod_rewrite</tt>.. <p> -<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> +<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> <tr><td> <font size=-1> <b>For the Apache hackers:</b><br> @@ -988,14 +987,14 @@ comma-separated list of the following flags: which will be expanded. You can use this flag more than once to set more than one variable. The variables can be later dereferenced at a lot of situations, but the usual location will be from within XSSI (via - <tt><!--#echo var="VAR"--></tt>) or CGI (e.g. <tt>$ENV{'VAR'}</tt>). - But additionally you can also dereference it in a following RewriteCond - pattern via <tt>%{ENV:VAR}</tt>. Use this to strip but remember - information from URLs. + <tt><!--#echo var="VAR"--></tt>) or CGI (e.g. <tt>$ENV{'VAR'}</tt>). + But additionally you can also dereference it in a following RewriteCond + pattern via <tt>%{ENV:VAR}</tt>. Use this to strip but remember + information from URLs. </ul> <p> -<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> +<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> <tr><td> Remember: Never forget that <em>Pattern</em> gets applied to a complete URL in per-server configuration files. <b>But in per-directory configuration @@ -1012,7 +1011,7 @@ external redirect or proxy throughput (if flag <b>P</b> is used!) is forced! </table> <p> -<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> +<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10> <tr><td> Notice! To enable the rewriting engine for per-directory configuration files you need to set ``<tt>RewriteEngine On</tt>'' in these files <b>and</b> @@ -1120,10 +1119,6 @@ request ``<tt>GET /somepath/localpath/pathinfo</tt>'':</b><br> </table> -</td> -</tr> -</table> - <p> <b>Example:</b> <p> diff --git a/docs/manual/mod/mod_status.html b/docs/manual/mod/mod_status.html index f5a55fa397..f671ad7836 100644 --- a/docs/manual/mod/mod_status.html +++ b/docs/manual/mod/mod_status.html @@ -90,7 +90,7 @@ mark@ukweb.com</a> and tell me your configuration. Do this by adding the following to the AUX_CFLAGS line in the "Configuration" file and then recompiling as usual. <pre> - AUX_CFLAGS= (something) -DSTATUS + AUX_CFLAGS= (something) -DSTATUS </pre> <BLOCKQUOTE> diff --git a/docs/manual/mod/mod_userdir.html b/docs/manual/mod/mod_userdir.html index cca87f5020..790c752efa 100644 --- a/docs/manual/mod/mod_userdir.html +++ b/docs/manual/mod/mod_userdir.html @@ -42,15 +42,15 @@ to use when a request for a document for a user is received. patterns. If not disabled, then a request for <code>http://www.foo.com/~bob/one/two.html</code> will be translated to: <pre> -UserDir public_html -> ~bob/public_html/one/two.html -UserDir /usr/web -> /usr/web/bob/one/two.html -UserDir /home/*/www -> /home/bob/www/one/two.html +UserDir public_html -> ~bob/public_html/one/two.html +UserDir /usr/web -> /usr/web/bob/one/two.html +UserDir /home/*/www -> /home/bob/www/one/two.html </pre> The following directives will send redirects to the client: <pre> -UserDir http://www.foo.com/users -> http//www.foo.com/users/bob/one/two.html -UserDir http://www.foo.com/*/usr -> http://www.foo.com/bob/usr/one/two.html -UserDir http://www.foo.com/~*/ -> http://www.foo.com/~bob/one/two.html +UserDir http://www.foo.com/users -> http//www.foo.com/users/bob/one/two.html +UserDir http://www.foo.com/*/usr -> http://www.foo.com/bob/usr/one/two.html +UserDir http://www.foo.com/~*/ -> http://www.foo.com/~bob/one/two.html </pre> <P> diff --git a/docs/manual/platform/perf-bsd44.html b/docs/manual/platform/perf-bsd44.html deleted file mode 100644 index 0a1661b7ca..0000000000 --- a/docs/manual/platform/perf-bsd44.html +++ /dev/null @@ -1,236 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<html> -<head> -<title>Running a High-Performance Web Server for BSD</title> -</head> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<A NAME="initial"> -<!--#include virtual="header.html" --> -</A> -<H1 ALIGN="CENTER">Running a High-Performance Web Server for BSD</H1> - -Like other OS's, the listen queue is often the <b>first limit hit</b>. The -following are comments from "Aaron Gifford <agifford@InfoWest.COM>" -on how to fix this on BSDI 1.x, 2.x, and FreeBSD 2.0 (and earlier): - -<p> - -Edit the following two files: -<blockquote><code> /usr/include/sys/socket.h <br> - /usr/src/sys/sys/socket.h </code></blockquote> -In each file, look for the following: -<pre> - /* - * Maximum queue length specifiable by listen. - */ - #define SOMAXCONN 5 -</pre> - -Just change the "5" to whatever appears to work. I bumped the two -machines I was having problems with up to 32 and haven't noticed the -problem since. - -<p> - -After the edit, recompile the kernel and recompile the Apache server -then reboot. - -<P> - -FreeBSD 2.1 seems to be perfectly happy, with SOMAXCONN -set to 32 already. - -<p> - -<A NAME="detail"> -<b>Addendum for <i>very</i> heavily loaded BSD servers</b><br> -</A> -from Chuck Murcko <chuck@telebase.com> - -<p> - -If you're running a really busy BSD Apache server, the following are useful -things to do if the system is acting sluggish:<p> - -<ul> - -<li> Run vmstat to check memory usage, page/swap rates, etc. - -<li> Run netstat -m to check mbuf usage - -<li> Run fstat to check file descriptor usage - -</ul> - -These utilities give you an idea what you'll need to tune in your kernel, -and whether it'll help to buy more RAM. - -Here are some BSD kernel config parameters (actually BSDI, but pertinent to -FreeBSD and other 4.4-lite derivatives) from a system getting heavy usage. -The tools mentioned above were used, and the system memory was increased to -48 MB before these tuneups. Other system parameters remained unchanged. - -<p> - -<pre> -maxusers 256 -</pre> - -Maxusers drives a <i>lot</i> of other kernel parameters: - -<ul> - -<li> Maximum # of processes - -<li> Maximum # of processes per user - -<li> System wide open files limit - -<li> Per-process open files limit - -<li> Maximum # of mbuf clusters - -<li> Proc/pgrp hash table size - -</ul> - -The actual formulae for these derived parameters are in -<i>/usr/src/sys/conf/param.c</i>. -These calculated parameters can also be overridden (in part) by specifying -your own values in the kernel configuration file: - -<pre> -# Network options. NMBCLUSTERS defines the number of mbuf clusters and -# defaults to 256. This machine is a server that handles lots of traffic, -# so we crank that value. -options SOMAXCONN=256 # max pending connects -options NMBCLUSTERS=4096 # mbuf clusters at 4096 - -# -# Misc. options -# -options CHILD_MAX=512 # maximum number of child processes -options OPEN_MAX=512 # maximum fds (breaks RPC svcs) -</pre> - -SOMAXCONN is not derived from maxusers, so you'll always need to increase -that yourself. We used a value guaranteed to be larger than Apache's -default for the listen() of 128, currently. - -<p> - -In many cases, NMBCLUSTERS must be set much larger than would appear -necessary at first glance. The reason for this is that if the browser -disconnects in mid-transfer, the socket fd associated with that particular -connection ends up in the TIME_WAIT state for several minutes, during -which time its mbufs are not yet freed. Another reason is that, on server -timeouts, some connections end up in FIN_WAIT_2 state forever, because -this state doesn't time out on the server, and the browser never sent -a final FIN. For more details see the -<A HREF="fin_wait_2.html">FIN_WAIT_2</A> page. - -<p> - -Some more info on mbuf clusters (from sys/mbuf.h): -<pre> -/* - * Mbufs are of a single size, MSIZE (machine/machparam.h), which - * includes overhead. An mbuf may add a single "mbuf cluster" of size - * MCLBYTES (also in machine/machparam.h), which has no additional overhead - * and is used instead of the internal data area; this is done when - * at least MINCLSIZE of data must be stored. - */ -</pre> - -<p> - -CHILD_MAX and OPEN_MAX are set to allow up to 512 child processes (different -than the maximum value for processes per user ID) and file descriptors. -These values may change for your particular configuration (a higher OPEN_MAX -value if you've got modules or CGI scripts opening lots of connections or -files). If you've got a lot of other activity besides httpd on the same -machine, you'll have to set NPROC higher still. In this example, the NPROC -value derived from maxusers proved sufficient for our load. - -<p> - -<b>Caveats</b> - -<p> - -Be aware that your system may not boot with a kernel that is configured -to use more resources than you have available system RAM. <b>ALWAYS</b> -have a known bootable kernel available when tuning your system this way, -and use the system tools beforehand to learn if you need to buy more -memory before tuning. - -<p> - -RPC services will fail when the value of OPEN_MAX is larger than 256. -This is a function of the original implementations of the RPC library, -which used a byte value for holding file descriptors. BSDI has partially -addressed this limit in its 2.1 release, but a real fix may well await -the redesign of RPC itself. - -<p> - -Finally, there's the hard limit of child processes configured in Apache. - -<p> - -For versions of Apache later than 1.0.5 you'll need to change the -definition for <b>HARD_SERVER_LIMIT</b> in <i>httpd.h</i> and recompile -if you need to run more than the default 150 instances of httpd. - -<p> - -From conf/httpd.conf-dist: - -<pre> -# Limit on total number of servers running, i.e., limit on the number -# of clients who can simultaneously connect --- if this limit is ever -# reached, clients will be LOCKED OUT, so it should NOT BE SET TOO LOW. -# It is intended mainly as a brake to keep a runaway server from taking -# Unix with it as it spirals down... - -MaxClients 150 -</pre> - -Know what you're doing if you bump this value up, and make sure you've -done your system monitoring, RAM expansion, and kernel tuning beforehand. -Then you're ready to service some serious hits! - -<p> - -Thanks to <i>Tony Sanders</i> and <i>Chris Torek</i> at BSDI for their -helpful suggestions and information. - -<P> - -"M. Teterin" <mi@ALDAN.ziplink.net> writes:<P> -<blockquote>It really does help if your kernel and frequently used utilities -are fully optimized. Rebuilding the FreeBSD kernel on an AMD-133 -(486-class CPU) web-server with<BR> -<code> -m486 -fexpensive-optimizations -fomit-frame-ponter -O2</code><BR> -helped reduce the number of "unable" errors, because the CPU was -often maxed out.</blockquote> -<P> - -<HR> - -<H3>More welcome!</H3> - -If you have tips to contribute, send mail to <a -href="mailto:brian@organic.com">brian@organic.com</a> - -<!--#include virtual="footer.html" --> -</body></html> - diff --git a/docs/manual/platform/perf-dec.html b/docs/manual/platform/perf-dec.html deleted file mode 100644 index 7cc8bb1308..0000000000 --- a/docs/manual/platform/perf-dec.html +++ /dev/null @@ -1,279 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Performance Tuning Tips for Digital Unix</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">Performance Tuning Tips for Digital Unix</H1> - -Below is a set of newsgroup posts made by an engineer from DEC in -response to queries about how to modify DEC's Digital Unix OS for more -heavily loaded web sites. Copied with permission. - -<HR> - -<H2>Update</H2> -From: Jeffrey Mogul <mogul@pa.dec.com><BR> -Date: Fri, 28 Jun 96 16:07:56 MDT<BR> - -<OL> -<LI> The advice given in the README file regarding the - "tcbhashsize" variable is incorrect. The largest value - this should be set to is 1024. Setting it any higher - will have the perverse result of disabling the hashing - mechanism. - -<LI>Patch ID OSF350-146 has been superseded by -<blockquote> - Patch ID OSF350-195 for V3.2C<BR> - Patch ID OSF360-350195 for V3.2D -</blockquote> - Patch IDs for V3.2E and V3.2F should be available soon. - There is no known reason why the Patch ID OSF360-350195 - won't work on these releases, but such use is not officially - supported by Digital. This patch kit will not be needed for - V3.2G when it is released. -</OL> -<HR> - - -<PRE> -From mogul@pa.dec.com (Jeffrey Mogul) -Organization DEC Western Research -Date 30 May 1996 00:50:25 GMT -Newsgroups <A HREF="news:comp.unix.osf.osf1">comp.unix.osf.osf1</A> -Message-ID <A HREF="news:4oirch$bc8@usenet.pa.dec.com"><4oirch$bc8@usenet.pa.dec.com></A> -Subject Re: Web Site Performance -References 1 - - - -In article <skoogDs54BH.9pF@netcom.com> skoog@netcom.com (Jim Skoog) writes: ->Where are the performance bottlenecks for Alpha AXP running the ->Netscape Commerce Server 1.12 with high volume internet traffic? ->We are evaluating network performance for a variety of Alpha AXP ->runing DEC UNIX 3.2C, which run DEC's seal firewall and behind ->that Alpha 1000 and 2100 webservers. - -Our experience (running such Web servers as <A HREF="http://altavista.digital.com">altavista.digital.com</A> -and <A HREF="http://www.digital.com">www.digital.com</A>) is that there is one important kernel tuning -knob to adjust in order to get good performance on V3.2C. You -need to patch the kernel global variable "somaxconn" (use dbx -k -to do this) from its default value of 8 to something much larger. - -How much larger? Well, no larger than 32767 (decimal). And -probably no less than about 2048, if you have a really high volume -(millions of hits per day), like AltaVista does. - -This change allows the system to maintain more than 8 TCP -connections in the SYN_RCVD state for the HTTP server. (You -can use "netstat -An |grep SYN_RCVD" to see how many such -connections exist at any given instant). - -If you don't make this change, you might find that as the load gets -high, some connection attempts take a very long time. And if a lot -of your clients disconnect from the Internet during the process of -TCP connection establishment (this happens a lot with dialup -users), these "embryonic" connections might tie up your somaxconn -quota of SYN_RCVD-state connections. Until the kernel times out -these embryonic connections, no other connections will be accepted, -and it will appear as if the server has died. - -The default value for somaxconn in Digital UNIX V4.0 will be quite -a bit larger than it has been in previous versions (we inherited -this default from 4.3BSD). - -Digital UNIX V4.0 includes some other performance-related changes -that significantly improve its maximum HTTP connection rate. However, -we've been using V3.2C systems to front-end for altavista.digital.com -with no obvious performance bottlenecks at the millions-of-hits-per-day -level. - -We have some Webstone performance results available at - <A HREF="http://www.digital.com/info/alphaserver/news/webff.html">http://www.digital.com/info/alphaserver/news/webff.html</A> -I'm not sure if these were done using V4.0 or an earlier version -of Digital UNIX, although I suspect they were done using a test -version of V4.0. - --Jeff - -<HR> - ----------------------------------------------------------------------------- - -From mogul@pa.dec.com (Jeffrey Mogul) -Organization DEC Western Research -Date 31 May 1996 21:01:01 GMT -Newsgroups <A HREF="news:comp.unix.osf.osf1">comp.unix.osf.osf1</A> -Message-ID <A HREF="news:4onmmd$mmd@usenet.pa.dec.com"><4onmmd$mmd@usenet.pa.dec.com></A> -Subject Digital UNIX V3.2C Internet tuning patch info - ----------------------------------------------------------------------------- - -Something that probably few people are aware of is that Digital -has a patch kit available for Digital UNIX V3.2C that may improve -Internet performance, especially for busy web servers. - -This patch kit is one way to increase the value of somaxconn, -which I discussed in a message here a day or two ago. - -I've included in this message the revised README file for this -patch kit below. Note that the original README file in the patch -kit itself may be an earlier version; I'm told that the version -below is the right one. - -Sorry, this patch kit is NOT available for other versions of Digital -UNIX. Most (but not quite all) of these changes also made it into V4.0, -so the description of the various tuning parameters in this README -file might be useful to people running V4.0 systems. - -This patch kit does not appear to be available (yet?) from - <A HREF="http://www.service.digital.com/html/patch_service.html">http://www.service.digital.com/html/patch_service.html</A> -so I guess you'll have to call Digital's Customer Support to get it. - --Jeff - -DESCRIPTION: Digital UNIX Network tuning patch - - Patch ID: OSF350-146 - - SUPERSEDED PATCHES: OSF350-151, OSF350-158 - - This set of files improves the performance of the network - subsystem on a system being used as a web server. There are - additional tunable parameters included here, to be used - cautiously by an informed system administrator. - -TUNING - - To tune the web server, the number of simultaneous socket - connection requests are limited by: - - somaxconn Sets the maximum number of pending requests - allowed to wait on a listening socket. The - default value in Digital UNIX V3.2 is 8. - This patch kit increases the default to 1024, - which matches the value in Digital UNIX V4.0. - - sominconn Sets the minimum number of pending connections - allowed on a listening socket. When a user - process calls listen with a backlog less - than sominconn, the backlog will be set to - sominconn. sominconn overrides somaxconn. - The default value is 1. - - The effectiveness of tuning these parameters can be monitored by - the sobacklog variables available in the kernel: - - sobacklog_hiwat Tracks the maximum pending requests to any - socket. The initial value is 0. - - sobacklog_drops Tracks the number of drops exceeding the - socket set backlog limit. The initial - value is 0. - - somaxconn_drops Tracks the number of drops exceeding the - somaxconn limit. When sominconn is larger - than somaxconn, tracks the number of drops - exceeding sominconn. The initial value is 0. - - TCP timer parameters also affect performance. Tuning the following - require some knowledge of the characteristics of the network. - - tcp_msl Sets the tcp maximum segment lifetime. - This is the maximum lifetime in half - seconds that a packet can be in transit - on the network. This value, when doubled, - is the length of time a connection remains - in the TIME_WAIT state after a incoming - close request is processed. The unit is - specified in 1/2 seconds, the initial - value is 60. - - tcp_rexmit_interval_min - Sets the minimum TCP retransmit interval. - For some WAN networks the default value may - be too short, causing unnecessary duplicate - packets to be sent. The unit is specified - in 1/2 seconds, the initial value is 1. - - tcp_keepinit This is the amount of time a partially - established connection will sit on the listen - queue before timing out (e.g. if a client - sends a SYN but never answers our SYN/ACK). - Partially established connections tie up slots - on the listen queue. If the queue starts to - fill with connections in SYN_RCVD state, - tcp_keepinit can be decreased to make those - partial connects time out sooner. This should - be used with caution, since there might be - legitimate clients that are taking a while - to respond to SYN/ACK. The unit is specified - in 1/2 seconds, the default value is 150 - (ie. 75 seconds). - - The hashlist size for the TCP inpcb lookup table is regulated by: - - tcbhashsize The number of hash buckets used for the - TCP connection table used in the kernel. - The initial value is 32. For best results, - should be specified as a power of 2. For - busy Web servers, set this to 2048 or more. - - The hashlist size for the interface alias table is regulated by: - - inifaddr_hsize The number of hash buckets used for the - interface alias table used in the kernel. - The initial value is 32. For best results, - should be specified as a power of 2. - - ipport_userreserved The maximum number of concurrent non-reserved, - dynamically allocated ports. Default range - is 1025-5000. The maximum value is 65535. - This limits the numer of times you can - simultaneously telnet or ftp out to connect - to other systems. - - tcpnodelack Don't delay acknowledging TCP data; this - can sometimes improve performance of locally - run CAD packages. Default is value is 0, - the enabled value is 1. - - Digital UNIX version: - - V3.2C -Feature V3.2C patch V4.0 - ======= ===== ===== ==== -somaxconn X X X -sominconn - X X -sobacklog_hiwat - X - -sobacklog_drops - X - -somaxconn_drops - X - -tcpnodelack X X X -tcp_keepidle X X X -tcp_keepintvl X X X -tcp_keepcnt - X X -tcp_keepinit - X X -TCP keepalive per-socket - - X -tcp_msl - X - -tcp_rexmit_interval_min - X - -TCP inpcb hashing - X X -tcbhashsize - X X -interface alias hashing - X X -inifaddr_hsize - X X -ipport_userreserved - X - -sysconfig -q inet - - X -sysconfig -q socket - - X - -</PRE> -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/platform/perf.html b/docs/manual/platform/perf.html deleted file mode 100644 index 96c48ea199..0000000000 --- a/docs/manual/platform/perf.html +++ /dev/null @@ -1,146 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<html> -<head> -<title>Hints on Running a High-Performance Web 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">Hints on Running a High-Performance Web Server</H1> - -Running Apache on a heavily loaded web server, one often encounters -problems related to the machine and OS configuration. "Heavy" is -relative, of course - but if you are seeing more than a couple hits -per second on a sustained basis you should consult the pointers on -this page. In general the suggestions involve how to tune your kernel -for the heavier TCP load, hardware/software conflicts that arise, etc. - -<UL> -<LI><A HREF="#AUX">A/UX (Apple's UNIX)</A> -<LI><A HREF="#BSD">BSD-based (BSDI, FreeBSD, etc)</A> -<LI><A HREF="#DEC">Digital UNIX</A> -<LI><A HREF="#HP">Hewlett-Packard</A> -<LI><A HREF="#Linux">Linux</A> -<LI><A HREF="#SGI">SGI</A> -<LI><A HREF="#Solaris">Solaris</A> -<LI><A HREF="#SunOS">SunOS 4.x</A> -</UL> - -<HR> - -<H3><A NAME="AUX"> -A/UX (Apple's UNIX) -</A></H3> - -If you are running Apache on A/UX, a page that gives some helpful -performance hints (concerning the <I>listen()</I> queue and using -virtual hosts) -<A HREF="http://www.jaguNET.com/apache.html">can be found here</A> - -<P><HR> - -<H3><A NAME="BSD"> -BSD-based (BSDI, FreeBSD, etc) -</A></H3> - -<A HREF="perf-bsd44.html#initial">Quick</A> and -<A HREF="perf-bsd44.html#detail">detailed</A> -performance tuning hints for BSD-derived systems. - -<P><HR> - -<H3><A NAME="DEC"> -Digital UNIX -</A></H3> - -<UL> - <LI><A HREF="http://www.digital.com/info/internet/document/ias/tuning.html">DIGITAL - UNIX Tuning Parameters for Web Servers</A> - <LI>We have some <A HREF="perf-dec.html">newsgroup postings</A> on how to tune - Digital UNIX 3.2 and 4.0. -</UL> - -<P><HR> - -<H3><A NAME="HP"> -Hewlett-Packard -</A></H3> - -Some documentation on tuning HP machines can be found at <A -HREF="http://www.software.hp.com/internet/perf/tuning.html">http://www.software.hp.com/internet/perf/tuning.html</A>. - -<P><HR> - -<H3><A NAME="Linux"> -Linux -</A></H3> - -The most common problem on Linux shows up on heavily-loaded systems -where the whole server will appear to freeze for a couple of minutes -at a time, and then come back to life. This has been traced to a -listen() queue overload - certain Linux implementations have a low -value set for the incoming connection queue which can cause problems. -Please see our <a -href="http://www.qosina.com/~awm/apache/linux-tcp.html">Using Apache on -Linux</a> page for more info on how to fix this. - -<P><HR> - -<H3><A NAME="SGI"> -SGI -</A></H3> - -<UL> -<LI><A HREF="http://www.sgi.com/Products/WebFORCE/Resources/res_TuningGuide.html"> -WebFORCE Web Server Tuning Guidelines for IRIX 5.3, -<http://www.sgi.com/Products/WebFORCE/Resources/res_TuningGuide.html></A> -</UL> - -<P><HR> - -<H3><A NAME="Solaris"> -Solaris 2.4 -</A></H3> - -The Solaris 2.4 TCP implementation has a few inherent limitations that -only became apparent under heavy loads. This has been fixed to some -extent in 2.5 (and completely revamped in 2.6), but for now consult -the following URL for tips on how to expand the capabilities if you -are finding slowdowns and lags are hurting performance. - -<UL> - -<LI><A href="http://www.sun.com/sun-on-net/Sun.Internet.Solutions/performance/"> -World Wide Web Server Performance, -<http://www.sun.com/sun-on-net/Sun.Internet.Solutions/performance/></a> -<LI><A HREF="http://www.sun.com/solaris/products/siss/"> -Solaris Internet Server Supplement for 2.5.1</A> -</UL> - -<P><HR> - -<H3><A NAME="SunOS"> -SunOS 4.x -</A></H3> - -More information on tuning SOMAXCONN on SunOS can be found at -<A HREF="http://www.islandnet.com/~mark/somaxconn.html"> -http://www.islandnet.com/~mark/somaxconn.html</A>. - -<P><HR> - -<H3>More welcome!</H3> - -If you have tips to contribute, send mail to <a -href="mailto:brian@organic.com">brian@organic.com</a> - -<!--#include virtual="footer.html" --> -</body></html> - diff --git a/docs/manual/platform/unixware.html b/docs/manual/platform/unixware.html deleted file mode 100644 index eb8adbe2fe..0000000000 --- a/docs/manual/platform/unixware.html +++ /dev/null @@ -1,61 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Compiling Apache under UnixWare</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">Compiling Apache under UnixWare</H1> - -To compile a working copy of Apache under UnixWare, there are several other -steps you may need to take. These prevent such problems as zombie processes, -bind errors, and accept errors, to name a few. - -<H2>UnixWare 1.x</H2> - -Make sure that USE_FCNTL_SERIALIZE_ACCEPT is defined (if not -defined by Apache autoconfiguration). If using the UnixWare <i>cc</i> -compiler, and you still see accept() errors, don't use compiler optimization, -or get <i>gcc</i>. - -<H2>UnixWare 2.0.x</H2> - -SCO patch <a href="ftp://ftp.sco.com/UW20/tf2163.txt">tf2163</a> is required -in order for Apache to work correctly on UnixWare 2.0.x. See -<a href="http://www.sco.com">http://www.sco.com</a> -for UnixWare patch information.<p> - -In addition, make sure that USE_FCNTL_SERIALIZE_ACCEPT is defined (if not -defined by Apache autoconfiguration). To reduce instances of connections -in FIN_WAIT_2 state, you may also want to define NO_LINGCLOSE (Apache 1.2 -only). - -<H2>UnixWare 2.1.x</H2> - -SCO patch <a href="ftp://ftp.sco.com/UW21/ptf3123b.txt">ptf3123</a> is required -in order for Apache to work correctly on UnixWare 2.1.x. See -<a href="http://www.sco.com">http://www.sco.com</a> -for UnixWare patch information.<p> - -<b>NOTE:</b> Unixware 2.1.2 and later already have patch ptf3123 included<p> - -In addition, make sure that USE_FCNTL_SERIALIZE_ACCEPT is defined (if not -defined by Apache autoconfiguration). To reduce instances of connections -in FIN_WAIT_2 state, you may also want to define NO_LINGCLOSE (Apache 1.2 -only).<p> - -Thanks to Joe Doupnik <JRD@cc.usu.edu> and Rich Vaughn -<rvaughn@aad.com> for additional info for UnixWare builds.<p> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/process-model.html b/docs/manual/process-model.html index c130decffa..2c37337b70 100644 --- a/docs/manual/process-model.html +++ b/docs/manual/process-model.html @@ -39,9 +39,9 @@ as too confusing. The defaults for each variable are: <PRE> -MinSpareServers 5 -MaxSpareServers 10 -StartServers 5 +MinSpareServers 5 +MaxSpareServers 10 +StartServers 5 </PRE> There is an absolute maximum number of simultaneous children defined diff --git a/docs/manual/search/manual-index.cgi b/docs/manual/search/manual-index.cgi deleted file mode 100644 index 8d06e8a115..0000000000 --- a/docs/manual/search/manual-index.cgi +++ /dev/null @@ -1,239 +0,0 @@ -#!/usr/local/bin/perl5 -w -# ==================================================================== -# Copyright (c) 1995-1997 The Apache Group. All rights reserved. -# -# Redistribution and use in source and binary forms, with or without -# modification, are permitted provided that the following conditions -# are met: -# -# 1. Redistributions of source code must retain the above copyright -# notice, this list of conditions and the following disclaimer. -# -# 2. Redistributions in binary form must reproduce the above copyright -# notice, this list of conditions and the following disclaimer in -# the documentation and/or other materials provided with the -# distribution. -# -# 3. All advertising materials mentioning features or use of this -# software must display the following acknowledgment: -# "This product includes software developed by the Apache Group -# for use in the Apache HTTP server project (http://www.apache.org/)." -# -# 4. The names "Apache Server" and "Apache Group" must not be used to -# endorse or promote products derived from this software without -# prior written permission. -# -# 5. Redistributions of any form whatsoever must retain the following -# acknowledgment: -# "This product includes software developed by the Apache Group -# for use in the Apache HTTP server project (http://www.apache.org/)." -# -# THIS SOFTWARE IS PROVIDED BY THE APACHE GROUP ``AS IS'' AND ANY -# EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE GROUP OR -# ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT -# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, -# STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) -# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED -# OF THE POSSIBILITY OF SUCH DAMAGE. -# ==================================================================== -# -# manual-index.cgi script -# originally written by Ken Coar <Coar@DECUS.Org> in May 1997 -# -# This script either displays a form in order to find documents in which -# a word appears, or displays the results of such a search. It is -# called as a CGI script. -# -# [FILE]PATH_INFO is the prefix to add to to the files names found in -# the index (URL prefix, not filesystem prefix), and QUERY_STRING is the -# word to be found. -# -#*** -#*** -# You may need to tweak the following line to point to the correct -# location of the index file on your system (it's in the -# apache/htdocs/manual directory of the Apache distribution tree). -#*** -#*** -$INDEX = "/export/pub/apache/manual-index.dat"; - -#*** -#*** -# You shouldn't have to modify anything else. -#*** -#*** - -$HTML = ""; - -# -# If we have a FILEPATH_INFO or PATH_INFO, it's there to remap the -# documents to the manual root directory. If this script is already in -# that directory, this isn't needed. -# -$prefix = $ENV{'FILEPATH_INFO'} || $ENV{'PATH_INFO'}; -$prefix .= "/" if ($prefix && ($prefix !~ m:/$:)); - -# -# QUERY_STRING, if present, contains the word for which we are to -# search. We also use its [non]presence to determine wha we display. -# -$word = $ENV{'QUERY_STRING'}; - -# -# Make sure our HTTP header makes it to the server by causing Perl to do -# a fflush() after every write to STDOUT. -# -select (STDOUT); -$| = 1; -printf ("Content-type: text/html\n\n"); - -# -# Fine, now buffering can go back to normal. -# -$| = 0; - -# -# Set up the HTML page title -$title = "Apache Documentation Search"; -$title .= ": Results for \"$word\"" if ($word); - -# -# We'll re-use the HTML scalar several times; we use it with here -# documents for multi-line static HTML code. Lets' do the standard page -# header. -# -$HTML = <<EOHT; -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>$title - </TITLE> - </HEAD> - <BODY BGCOLOR="white" TEXT="black" LINK="blue" VLINK="navy" ALINK="red"> - <DIV ALIGN="CENTER"> - <IMG - SRC="${prefix}images/sub.gif" - ALT="" - > - </DIV> - <H1 ALIGN="CENTER"> - Apache Documentation Search - </H1> - <P> - This script performs a very simple search across the Apache - documentation for any single case-insensitive word. No combinations, - wildcards, regular expressions, word-stubbing, or other fancy options - are supported; this is just to help you find topics quickly. Only - those pages which include the <EM>exact</EM> word you type will be - listed. - </P> - <P> - Documents containing the search word are <EM>not</EM> listed in any - sort of priority order. - </P> - <ISINDEX PROMPT="Enter word to find and press ENTER: "> -EOHT - -printf ($HTML); - -# -# Now set up the next section, which is only displayed if we've been -# given a word to find. -# -$HTML = <<EOHT; - <HR> - <H2> - Results of Search for <SAMP>$word</SAMP> - </H2> -EOHT - -# -# We enblock the next section so problems can drop out to the common -# closure code. -# -QUERY: - { - if ($word) { - # - # Try and open the index file; complain bitterly if we can't. - # - if (! open (INDEX, "<$INDEX")) { - printf ("Can't find documentation index!"); - last QUERY; - } - # - # Got it; display the search-results header. - # - printf ($HTML); - # - # Read the entire index in and turn it into an hash for the - # lookup. - # - @index = <INDEX>; - close (INDEX); - chomp (@index); - foreach (@index) { - ($key, $files) = split (/:/, $_); - $Index{$key} = $files; - } - # - # The dictionary is all lowercase words. Smash our query value - # and try to find it. - # - $word = lc ($word); - if (! exists ($Index{$word})) { - printf (" <P>\n <EM>Sorry, no matches found.</EM>\n </P>\n"); - last QUERY; - } - # - # Found an entry, so turn the hash value (a comma-separated list - # of relative file names) into an array for display. - # Incidentally, tell the user how many there are. - # - @files = split (/,/, $Index{$word}); - printf (" <P>Total of %d match", scalar (@files)); - # - # Be smart about plurals. - # - if (scalar (@files) != 1) { - printf ("es") ; - } - printf (" found.\n </P>\n"); - # - # Right. Now display the files as they're listed. - # - printf (" <OL>\n"); - foreach (@files) { - printf (" <LI><A HREF=\"${prefix}$_\">"); - printf ("<SAMP>$_</SAMP></A>\n"); - printf (" </LI>\n"); - } - printf (" </OL>\n"); - # - # C'est tout! - # - } - } - -# -# Back to common code - the exit path. Display the page trailer. -# -$HTML = <<EOHT; - <A - HREF="/" - ><IMG - SRC="/images/apache_home.gif" - ALT="Home" - ></A> - <HR> - </BODY> -</HTML> -EOHT - -printf ($HTML); -exit (0); diff --git a/docs/manual/stopping.html.en b/docs/manual/stopping.html.en deleted file mode 100644 index 373590a311..0000000000 --- a/docs/manual/stopping.html.en +++ /dev/null @@ -1,166 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Stopping and Restarting Apache</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 Apache</h1> - -<p>You will notice many <code>httpd</code> executables running on your system, -but you should not send signals to any of them except the parent, whose -pid is in the <a href="mod/core.html#pidfile">PidFile</a>. That is to -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>To send a signal to the parent you should issue a command such as: -<blockquote><pre> - kill -TERM `cat /usr/local/etc/httpd/logs/httpd.pid` -</pre></blockquote> - -You can read about its progress by issuing: - -<blockquote><pre> - tail -f /usr/local/etc/httpd/logs/error_log -</pre></blockquote> - -Modify those examples to match your -<a href="mod/core.html#serverroot">ServerRoot</a> and -<a href="mod/core.html#pidfile">PidFile</a> settings. - -<h3>TERM Signal: stop now</h3> - -<p>Sending the <code>TERM</code> signal to the parent causes it to -immediately attempt to kill off all of its children. It may take it -several seconds to complete killing off its children. Then the -parent itself exits. Any requests in progress are terminated, and no -further requests are served. - -<h3>HUP Signal: restart now</h3> - -<p>Sending the <code>HUP</code> signal to the parent causes it to kill off -its children like in <code>TERM</code> but the parent doesn't exit. It -re-reads its configuration files, and re-opens any log files. -Then it spawns a new set of children and continues -serving hits. - -<p>Users of the -<a href="mod/mod_status.html">status module</a> -will notice that the server statistics are -set to zero when a <code>HUP</code> is sent. - -<p><b>Note:</b> If your configuration file has errors in it when you issue a -restart then your parent will not restart, it will exit with an error. -See below for a method of avoiding this. - -<h3>USR1 Signal: graceful restart</h3> - -<p><b>Note:</b> prior to release 1.2b9 this code is quite unstable and -shouldn't be used at all. - -<p>The <code>USR1</code> signal causes the parent process to <i>advise</i> -the children to exit after their current request (or to exit immediately -if they're not serving anything). The parent re-reads its configuration -files and re-opens its log files. As each child dies off the parent -replaces it with a child from the new <i>generation</i> of the -configuration, which begins serving new requests immediately. - -<p>This code is designed to always respect the -<a href="mod/core.html#maxclients">MaxClients</a>, -<a href="mod/core.html#minspareservers">MinSpareServers</a>, -and <a href="mod/core.html#maxspareservers">MaxSpareServers</a> settings. -Furthermore, it respects <a href="mod/core.html#startservers">StartServers</a> -in the following manner: if after one second at least StartServers new -children have not been created, then create enough to pick up the slack. -This is to say that the code tries to maintain both the number of children -appropriate for the current load on the server, and respect your wishes -with the StartServers parameter. - -<p>Users of the -<a href="mod/mod_status.html">status module</a> -will notice that the server statistics -are <b>not</b> set to zero when a <code>USR1</code> is sent. The code -was written to both minimize the time in which the server is unable to serve -new requests (they will be queued up by the operating system, so they're -not lost in any event) and to respect your tuning parameters. In order -to do this it has to keep the <i>scoreboard</i> used to keep track -of all children across generations. - -<p>The status module will also use a <code>G</code> to indicate those -children which are still serving requests started before the graceful -restart was given. - -<p>At present there is no way for a log rotation script using -<code>USR1</code> to know for certain that all children writing the -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><b>Note:</b> 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. At present the only work -around is to check the syntax of your files before doing a restart. The -easiest way is to just run 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. - -<h3>Appendix: signals and race conditions</h3> - -<p>Prior to Apache 1.2b9 there were several <i>race conditions</i> -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>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 ScoreBoardFile documentation for a method to determine if your -architecture uses it. - -<p><code>NEXT</code> and <code>MACHTEN</code> (68k only) have small race -conditions -which can cause a restart/die signal to be lost, but should not cause the -server to do anything otherwise problematic. -<!-- they don't have sigaction, or we're not using it -djg --> - -<p>All architectures have a small race condition in each child involving -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" --> -</BODY> -</HTML> diff --git a/docs/manual/suexec.html b/docs/manual/suexec.html index 2b32aa950d..0157cd0c1b 100644 --- a/docs/manual/suexec.html +++ b/docs/manual/suexec.html @@ -1,8 +1,8 @@ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<html><head> -<title>Apache SetUserID Support</title> -</head> - +<HTML> +<HEAD> +<TITLE>Apache suEXEC Support</TITLE> +</HEAD> <!-- Background white, links blue (unvisited), navy (visited), red (active) --> <BODY BGCOLOR="#FFFFFF" @@ -12,150 +12,413 @@ ALINK="#FF0000" > <!--#include virtual="header.html" --> -<h1 ALIGN="CENTER">Apache suEXEC Support</h1> - -<hr> - -<h3>What is suEXEC?</h3> -The <STRONG>suEXEC</STRONG> feature, introduced in Apache 1.2 provides -the ability to run <STRONG>CGI</STRONG> programs under user IDs -different from the user ID of the calling web-server. Used properly, -this feature can reduce considerably the insecurity of allowing users to -run CGI programs. At the same time, improperly configured, this facility -can crash your computer, burn your house down and steal all the money -from your retirement fund. <STRONG>:-)</STRONG> If you aren't familiar -with managing setuid root programs and the security issues they -present, we highly recommend that you not consider using this feature.<p> - -<hr> - -<h3>Enabling suEXEC Support</h3> -Having said all that, enabling this feature is purposefully difficult with -the intent that it will only be installed by users determined to use it and -is not part of the normal install/compile process.<p> - -<h3>Configuring the suEXEC wrapper</h3> -From the top-level of the Apache source tree, -type: <STRONG><code>cd support [ENTER]</code></STRONG><p> + +<H1 ALIGN="CENTER">Apache suEXEC Support</H1> + +<P ALIGN="LEFT"> +<OL> + <LH><BIG><STRONG>CONTENTS</STRONG></BIG></LH> + <LI><A HREF="#what">What is suEXEC?</A></LI> + <LI><A HREF="#before">Before we begin.</A></LI> + <LI><A HREF="#model">suEXEC Security Model.</A></LI> + <LI><A HREF="#install">Configuring & Installing suEXEC</A></LI> + <LI><A HREF="#enable">Enabling & Disabling suEXEC</A></LI> + <LI><A HREF="#debug">Debugging suEXEC</A></LI> + <LI><A HREF="#jabberwock">Beware the Jabberwock: Warnings & + Examples</A></LI> +</OL> +</P> + +<H3><A NAME="what">What is suEXEC?</A></H3> +<P ALIGN="LEFT"> +The <STRONG>suEXEC</STRONG> feature -- introduced in Apache 1.2 -- provides +Apache users the ability to run <STRONG>CGI</STRONG> and <STRONG>SSI</STRONG> +programs under user IDs different from the user ID of the calling web-server. +Normally, when a CGI or SSI program executes, it runs as the same user who is +running the web server. +</P> + +<P ALIGN="LEFT"> +Used properly, this feature can reduce considerably the security risks involved +with allowing users to develop and run private CGI or SSI programs. However, +if suEXEC is improperly configured, it can cause any number of problems and +possibly create new holes in your computer's security. If you aren't familiar +with managing setuid root programs and the security issues they present, we +highly recommend that you not consider using suEXEC. +</P> + +<P ALIGN="CENTER"> +<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> +</P> + +<H3><A NAME="before">Before we begin.</A></H3> +<P ALIGN="LEFT"> +Before jumping head-first into this document, you should be aware of the +assumptions made on the part of the Apache Group and this document. +</P> + +<P ALIGN="LEFT"> +First, it is assumed that you are using a UNIX derivate operating system that +is capable of <STRONG>setuid</STRONG> and <STRONG>setgid</STRONG> operations. +All command examples are given in this regard. Other platforms, if they are +capable of supporting suEXEC, may differ in their configuration. +</P> + +<P ALIGN="LEFT"> +Second, it is assumed you are familiar with some basic concepts of your +computer's security and its administration. This involves an understanding +of <STRONG>setuid/setgid</STRONG> operations and the various effects they +may have on your system and its level of security. +</P> + +<P ALIGN="LEFT"> +Third, it is assumed that you are using an <STRONG>unmodified</STRONG> +version of suEXEC code. All code for suEXEC has been carefully scrutinized and +tested by the developers as well as numerous beta testers. Every precaution has +been taken to ensure a simple yet solidly safe base of code. Altering this +code can cause unexpected problems and new security risks. It is +<STRONG>highly</STRONG> recommended you not alter the suEXEC code unless you +are well versed in the particulars of security programming and are willing to +share your work with the Apache Group for consideration. +</P> + +<P ALIGN="LEFT"> +Fourth, and last, it has been the decision of the Apache Group to +<STRONG>NOT</STRONG> make suEXEC part of the default installation of Apache. +To this end, suEXEC configuration is a manual process requiring of the +administrator careful attention to details. It is through this process +that the Apache Group hopes to limit suEXEC installation only to those +who are determined to use it. +</P> + +<P ALIGN="LEFT"> +Still with us? Yes? Good. Let's move on! +</P> + +<P ALIGN="CENTER"> +<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> +</P> + +<H3><A NAME="model">suEXEC Security Model</A></H3> +<P ALIGN="LEFT"> +Before we begin configuring and installing suEXEC, we will first discuss +the security model you are about to implement. By doing so, you may +better understand what exactly is going on inside suEXEC and what precautions +are taken to ensure your system's security. +</P> + +<P ALIGN="LEFT"> +<STRONG>suEXEC</STRONG> is based on a setuid "wrapper" program that is +called by the main Apache web server. This wrapper is called when an HTTP +request is made for a CGI or SSI program that the administrator has designated +to run as a userid other than that of the main server. When such a request +is made, Apache provides the suEXEC wrapper with the program's name and the +user and group IDs under which the program is to execute. +</P> + +<P ALIGN="LEFT"> +The wrapper then employs the following process to determine success or +failure -- if any one of these conditions fail, the program logs the failure +and exits with an error, otherwise it will continue: + <OL> + <LI><STRONG>Was the wrapper called with the proper number of arguments?</STRONG> + <BLOCKQUOTE> + The wrapper will only execute if it is given the proper number of arguments. + The proper argument format is known to the Apache web server. If the wrapper + is not receiving the proper number of arguments, it is either being hacked, or + there is something wrong with the suEXEC portion of your Apache binary. + </BLOCKQUOTE> + </LI> + <LI><STRONG>Is the user executing this wrapper a valid user of this system?</STRONG> + <BLOCKQUOTE> + This is to ensure that the user executing the wrapper is truly a user of the system. + </BLOCKQUOTE> + </LI> + <LI><STRONG>Is this valid user allowed to run the wrapper?</STRONG> + <BLOCKQUOTE> + Is this user the user allowed to run this wrapper? Only one user (the Apache + user) is allowed to execute this program. + </BLOCKQUOTE> + </LI> + <LI><STRONG>Does the target program have an unsafe hierarchical reference?</STRONG> + <BLOCKQUOTE> + Does the target program contain a leading '/' or have a '..' backreference? These + are not allowed; the target program must reside within the Apache webspace. + </BLOCKQUOTE> + </LI> + <LI><STRONG>Is the target user name valid?</STRONG> + <BLOCKQUOTE> + Does the target user exist? + </BLOCKQUOTE> + </LI> + <LI><STRONG>Is the target group name valid?</STRONG> + <BLOCKQUOTE> + Does the target group exist? + </BLOCKQUOTE> + </LI> + <LI><STRONG>Is the target user <EM>NOT</EM> superuser?</STRONG> + <BLOCKQUOTE> + Presently, suEXEC does not allow 'root' to execute CGI/SSI programs. + </BLOCKQUOTE> + </LI> + <LI><STRONG>Is the target userid <EM>ABOVE</EM> the minimum ID number?</STRONG> + <BLOCKQUOTE> + The minimum user ID number is specified during configuration. This allows you + to set the lowest possible userid that will be allowed to execute CGI/SSI programs. + This is useful to block out "system" accounts. + </BLOCKQUOTE> + </LI> + <LI><STRONG>Is the target group <EM>NOT</EM> the superuser group?</STRONG> + <BLOCKQUOTE> + Presently, suEXEC does not allow the 'root' group to execute CGI/SSI programs. + </BLOCKQUOTE> + </LI> + <LI><STRONG>Is the target groupid <EM>ABOVE</EM> the minimum ID number?</STRONG> + <BLOCKQUOTE> + The minimum group ID number is specified during configuration. This allows you + to set the lowest possible groupid that will be allowed to execute CGI/SSI programs. + This is useful to block out "system" groups. + </BLOCKQUOTE> + </LI> + <LI><STRONG>Can the wrapper successfully become the target user and group?</STRONG> + <BLOCKQUOTE> + Here is where the program becomes the target user and group via setuid and setgid + calls. The group access list is also initialized with all of the groups of which + the user is a member. + </BLOCKQUOTE> + </LI> + <LI><STRONG>Does the directory in which the program resides exist?</STRONG> + <BLOCKQUOTE> + If it doesn't exist, it can't very well contain files. + </BLOCKQUOTE> + </LI> + <LI><STRONG>Is the directory within the Apache webspace?</STRONG> + <BLOCKQUOTE> + If the request is for a regular portion of the server, is the requested directory + within the server's document root? If the request is for a UserDir, is the requested + directory within the user's document root? + </BLOCKQUOTE> + </LI> + <LI><STRONG>Is the directory <EM>NOT</EM> writable by anyone else?</STRONG> + <BLOCKQUOTE> + We don't want to open up the directory to others; only the owner user may be able + to alter this directories contents. + </BLOCKQUOTE> + </LI> + <LI><STRONG>Does the target program exist?</STRONG> + <BLOCKQUOTE> + If it doesn't exists, it can't very well be executed. + </BLOCKQUOTE> + </LI> + <LI><STRONG>Is the target program <EM>NOT</EM> writable by anyone else?</STRONG> + <BLOCKQUOTE> + We don't want to give anyone other than the owner the ability to change the program. + </BLOCKQUOTE> + </LI> + <LI><STRONG>Is the target program <EM>NOT</EM> setuid or setgid?</STRONG> + <BLOCKQUOTE> + We do not want to execute programs that will then change our UID/GID again. + </BLOCKQUOTE> + </LI> + <LI><STRONG>Is the target user/group the same as the program's user/group?</STRONG> + <BLOCKQUOTE> + Is the user the owner of the file? + </BLOCKQUOTE> + </LI> + <LI><STRONG>Can we successfully clean the process environment to ensure safe operations?</STRONG> + <BLOCKQUOTE> + suEXEC cleans the process' environment by establishing a safe execution PATH (defined + during configuration), as well as only passing through those variables whose names + are listed in the safe environment list (also created during configuration). + </BLOCKQUOTE> + </LI> + <LI><STRONG>Can we successfully become the target program and execute?</STRONG> + <BLOCKQUOTE> + Here is where suEXEC ends and the target program begins. + </BLOCKQUOTE> + </LI> + </OL> +</P> + +<P ALIGN="LEFT"> +This is the standard operation of the the suEXEC wrapper's security model. +It is somewhat stringent and can impose new limitations and guidelines for +CGI/SSI design, but it was developed carefully step-by-step with security +in mind. +</P> + +<P ALIGN="LEFT"> +For more information as to how this security model can limit your possibilities +in regards to server configuration, as well as what security risks can be avoided +with a proper suEXEC setup, see the <A HREF="#beware">"Beware the Jabberwock"</A> +section of this document. +</P> + +<P ALIGN="CENTER"> +<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> +</P> + +<H3><A NAME="install">Configuring & Installing suEXEC</A></H3> +<P ALIGN="LEFT"> +Here's where we begin the fun. The configuration and installation of suEXEC is +a four step process: edit the suEXEC header file, compile suEXEC, place the +suEXEC binary in its proper location, and configure Apache for use with suEXEC. +</P> + +<P ALIGN="LEFT"> +<STRONG>EDITING THE SUEXEC HEADER FILE</STRONG><BR> +- From the top-level of the Apache source tree, type: +<STRONG><code>cd support [ENTER]</code></STRONG> +</P> + +<P ALIGN="LEFT"> Edit the <code>suexec.h</code> file and change the following macros to -match your local Apache installation.<p> +match your local Apache installation. +</P> + +<P ALIGN="LEFT"> <EM>From support/suexec.h</EM> -<pre> -/* - * HTTPD_USER -- Define as the username under which Apache normally - * runs. This is the only user allowed to execute - * this program. - */ -#define HTTPD_USER "www" - -/* - * LOG_EXEC -- Define this as a filename if you want all suEXEC - * transactions and errors logged for auditing and - * debugging purposes. - */ -#define LOG_EXEC "/usr/local/etc/httpd/logs/cgi.log" - -/* - * DOC_ROOT -- Define as the DocumentRoot set for Apache. This - * will be the only hierarchy (aside from UserDirs) - * that can be used for suEXEC behavior. - */ -#define DOC_ROOT "/usr/local/etc/httpd/htdocs" - -/* - * SAFE_PATH -- Define a safe PATH environment to pass to CGI executables. - * - */ -#define SAFE_PATH "/usr/local/bin:/usr/bin:/bin" -</pre> - -<h3>Compiling the suEXEC wrapper</h3> -At the shell command prompt, type: <STRONG><code>cc suexec.c --o suexec [ENTER]</code></STRONG>.<p> +<PRE> + /* + * HTTPD_USER -- Define as the username under which Apache normally + * runs. This is the only user allowed to execute + * this program. + */ + #define HTTPD_USER "www" + + /* + * UID_MIN -- Define this as the lowest UID allowed to be a target user + * for suEXEC. For most systems, 500 or 100 is common. + */ + #define UID_MIN 100 + + /* + * GID_MIN -- Define this as the lowest GID allowed to be a target group + * for suEXEC. For most systems, 100 is common. + */ + #define GID_MIN 100 + + /* + * USERDIR_SUFFIX -- Define to be the subdirectory under users' + * home directories where suEXEC access should + * be allowed. All executables under this directory + * will be executable by suEXEC as the user so + * they should be "safe" programs. If you are + * using a "simple" UserDir directive (ie. one + * without a "*" in it) this should be set to + * the same value. suEXEC will not work properly + * in cases where the UserDir directive points to + * a location that is not the same as the user's + * home directory as referenced in the passwd file. + * + * If you have VirtualHosts with a different + * UserDir for each, you will need to define them to + * all reside in one parent directory; then name that + * parent directory here. IF THIS IS NOT DEFINED + * PROPERLY, ~USERDIR CGI REQUESTS WILL NOT WORK! + * See the suEXEC documentation for more detailed + * information. + */ + #define USERDIR_SUFFIX "public_html" + + /* + * LOG_EXEC -- Define this as a filename if you want all suEXEC + * transactions and errors logged for auditing and + * debugging purposes. + */ + #define LOG_EXEC "/usr/local/etc/httpd/logs/cgi.log" /* Need me? */ + + /* + * DOC_ROOT -- Define as the DocumentRoot set for Apache. This + * will be the only hierarchy (aside from UserDirs) + * that can be used for suEXEC behavior. + */ + #define DOC_ROOT "/usr/local/etc/httpd/htdocs" + + /* + * SAFE_PATH -- Define a safe PATH environment to pass to CGI executables. + * + */ + #define SAFE_PATH "/usr/local/bin:/usr/bin:/bin" +</PRE> +</P> + +<P ALIGN="LEFT"> +<STRONG>COMPILING THE SUEXEC WRAPPER</STRONG><BR> +You now need to compile the suEXEC wrapper. At the shell command prompt, +type: <STRONG><CODE>cc suexec.c -o suexec [ENTER]</CODE></STRONG>. This should create the <STRONG><em>suexec</em></STRONG> wrapper executable. +</P> -<h3>Compiling Apache for suEXEC support</h3> +<P ALIGN="LEFT"> +<STRONG>COMPILING APACHE FOR USE WITH SUEXEC</STRONG><BR> By default, Apache is compiled to look for the suEXEC wrapper in the following -location.<p> +location. +</P> + +<P ALIGN="LEFT"> <EM>From src/httpd.h</EM> -<pre> -/* The path to the suEXEC wrapper */ -#ifndef SUEXEC_BIN -#define SUEXEC_BIN "/usr/local/etc/httpd/sbin/suexec" -#endif -</pre> -<p> +<PRE> + /* The path to the suEXEC wrapper */ + #define SUEXEC_BIN "/usr/local/etc/httpd/sbin/suexec" +</PRE> +</P> + +<P ALIGN="LEFT"> If your installation requires location of the wrapper program in a different directory, edit src/httpd.h and recompile your Apache server. -See <a href="install.html">Compiling and Installing Apache</a> for more -info on this process.<p> +See <A HREF="install.html">Compiling and Installing Apache</A> for more +info on this process. +</P> -<h3>Installing the suEXEC wrapper</h3> +<P ALIGN="LEFT"> +<STRONG>COPYING THE SUEXEC BINARY TO ITS PROPER LOCATION</STRONG><BR> Copy the <STRONG><em>suexec</em></STRONG> executable created in the -exercise above to the defined location for <STRONG>SUEXEC_BIN</STRONG>.<p> -In order for the wrapper to set the user ID for execution requests it -must me installed as owner <STRONG><em>root</em></STRONG> and must have -the setuserid execution bit set for file modes. -If you are not running a <STRONG><em>root</em></STRONG> user shell, do -so now and execute the following commands.<p> - -<STRONG><code>chown root /usr/local/etc/httpd/sbin/suexec [ENTER]</code></STRONG><p> -<STRONG><code>chmod 4711 /usr/local/etc/httpd/sbin/suexec [ENTER]</code></STRONG><p> - -<EM>Change the path to the suEXEC wrapper to match your system -installation.</EM> - -<hr> - -<h3><a name="model">Security Model of suEXEC</a></h3> -The <STRONG>suEXEC</STRONG> wrapper supplied with Apache performs the -following security checks before it will execute any program passed to -it for execution. -<ol> -<li>User executing the wrapper <STRONG>must be a valid user on this - system</STRONG>. -<li>User executing the wrapper <STRONG>must be the compiled in - HTTPD_USER</STRONG>. -<li>The command that the request wishes to execute <STRONG>must not - contain a leading / or ../, or the string "/../" anywhere</STRONG>. -<li>The command being executed <STRONG>must reside under the compiled in - DOC_ROOT</STRONG>. -<li>The current working directory <STRONG>must be a directory</STRONG>. -<li>The current working directory <STRONG>must not be writable by - <em>group</em> or <em>other</em></STRONG>. -<li>The command being executed <STRONG>cannot be a symbolic link</STRONG>. -<li>The command being executed <STRONG>cannot be writable by - <em>group</em> or <em>other</em></STRONG>. -<li>The command being executed <STRONG>cannot be a <em>setuid</em> or - <em>setgid</em> program</STRONG>. -<li>The target UID and GID <STRONG>must be a valid user and group on - this system</STRONG>. -<li>The target UID and GID to execute as, <STRONG>must match the UID and - GID of the directory</STRONG>. -<li>The target execution UID and GID <STRONG>must not be the privileged - ID 0</STRONG>. -</ol> -If any of these issues are too restrictive, or do not seem restrictive -enough, you are welcome to install your own version of the wrapper. -We've given you the rope, now go have fun with it. <STRONG>:-)</STRONG> - -<hr> - -<h3>Using suEXEC</h3> +exercise above to the defined location for <STRONG>SUEXEC_BIN</STRONG>. +</P> + +<P ALIGN="LEFT"> +<STRONG><CODE>cp suexec /usr/local/etc/httpd/sbin/suexec [ENTER]</CODE></STRONG> +</P> + +<P ALIGN="LEFT"> +In order for the wrapper to set the user ID, it must me installed as owner +<STRONG><em>root</em></STRONG> and must have the setuserid execution bit +set for file modes. If you are not running a <STRONG><em>root</em></STRONG> +user shell, do so now and execute the following commands. +</P> + +<P ALIGN="LEFT"> +<STRONG><CODE>chown root /usr/local/etc/httpd/sbin/suexec [ENTER]</CODE></STRONG><BR> +<STRONG><CODE>chmod 4711 /usr/local/etc/httpd/sbin/suexec [ENTER]</CODE></STRONG> +</P> + +<P ALIGN="CENTER"> +<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> +</P> + +<H3><A NAME="enable">Enabling & Disabling suEXEC</A></H3> +<P ALIGN="LEFT"> After properly installing the <STRONG>suexec</STRONG> wrapper -executable, you must kill and restart the Apache server. A simple -<code><STRONG>kill -1 `cat httpd.pid`</STRONG></code> will not be enough. +executable, you must kill and restart the Apache server. A simple +<STRONG><CODE>kill -1 `cat httpd.pid`</CODE></STRONG> will not be enough. Upon startup of the web-server, if Apache finds a properly configured <STRONG>suexec</STRONG> wrapper, it will print the following message to -the console:<p> +the console: +</P> -<code>Configuring Apache for use with suexec wrapper.</code><p> +<P ALIGN="LEFT"> +<CODE>Configuring Apache for use with suexec wrapper.</CODE> +</P> +<P ALIGN="LEFT"> If you don't see this message at server startup, the server is most likely not finding the wrapper program where it expects it, or the -executable is not installed <STRONG><em>setuid root</em></STRONG>. Check -your installation and try again.<p> +executable is not installed <STRONG><EM>setuid root</EM></STRONG>. Check +your installation and try again. +</P> +<P ALIGN="LEFT"> One way to use <STRONG>suEXEC</STRONG> is through the <a href="mod/core.html#user"><STRONG>User</STRONG></a> and <a href="mod/core.html#group"><STRONG>Group</STRONG></a> directives in @@ -176,15 +439,68 @@ The only requirement needed for this feature to work is for CGI execution to be enabled for the user and that the script must meet the scrutiny of the <a href="#model">security checks</a> above. -<hr> +<P ALIGN="CENTER"> +<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> +</P> -<h3>Debugging suEXEC</h3> +<H3><A NAME="debug">Debugging suEXEC</A></H3> +<P ALIGN="LEFT"> The suEXEC wrapper will write log information to the location defined in the <code>suexec.h</code> as indicated above. If you feel you have -configured and installed the wrapper properly, -have a look at this log and the error_log for the server to see where -you may have gone astray. -<!--#include virtual="footer.html" --> +configured and installed the wrapper properly, have a look at this log +and the error_log for the server to see where you may have gone astray. +</P> +<P ALIGN="CENTER"> +<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> +</P> + +<H3><A NAME="jabberwock">Beware the Jabberwock: Warnings & Examples</A></H3> +<P ALIGN="LEFT"> +<STRONG>NOTE!</STRONG> This section may not be complete. For the latest +revision of this section of the documentation, see the Apache Group's +<A HREF="http://www.apache.org/docs/suexec.html">Online Documentation</A> +version. +</P> + +<P ALIGN="LEFT"> +There are a few points of interest regarding the wrapper that can cause +limitations on server setup. Please review these before submitting any +"bugs" regarding suEXEC. +<UL> + <LH><STRONG>suEXEC Points Of Interest</STRONG></LH> + <LI>Hierarchy limitations + <BLOCKQUOTE> + For security and efficiency reasons, all suexec requests must + remain within either a top-level document root for virtual + host requests, or one top-level personal document root for + userdir requests. For example, if you have four VirtualHosts + configured, you would need to structure all of your VHosts' + document roots off of one main Apache document hierarchy to + take advantage of suEXEC for VirtualHosts. (Example forthcoming.) + </BLOCKQUOTE> + </LI> + <LI>suEXEC's PATH environment variable + <BLOCKQUOTE> + This can be a dangerous thing to change. Make certain every + path you include in this define is a <STRONG>trusted</STRONG> + directory. You don't want to open people up to having someone + from across the world running a trojan horse on them. + </BLOCKQUOTE> + </LI> + <LI>Altering the suEXEC code + <BLOCKQUOTE> + Again, this can cause <STRONG>Big Trouble</STRONG> if you try + this without knowing what you are doing. Stay away from it + if at all possible. + </BLOCKQUOTE> + </LI> +</UL> + +<P ALIGN="CENTER"> +<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> +</P> + +<!--#include virtual="footer.html" --> </BODY> </HTML> diff --git a/docs/manual/suexec.html.en b/docs/manual/suexec.html.en deleted file mode 100644 index 2b32aa950d..0000000000 --- a/docs/manual/suexec.html.en +++ /dev/null @@ -1,190 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<html><head> -<title>Apache SetUserID 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">Apache suEXEC Support</h1> - -<hr> - -<h3>What is suEXEC?</h3> -The <STRONG>suEXEC</STRONG> feature, introduced in Apache 1.2 provides -the ability to run <STRONG>CGI</STRONG> programs under user IDs -different from the user ID of the calling web-server. Used properly, -this feature can reduce considerably the insecurity of allowing users to -run CGI programs. At the same time, improperly configured, this facility -can crash your computer, burn your house down and steal all the money -from your retirement fund. <STRONG>:-)</STRONG> If you aren't familiar -with managing setuid root programs and the security issues they -present, we highly recommend that you not consider using this feature.<p> - -<hr> - -<h3>Enabling suEXEC Support</h3> -Having said all that, enabling this feature is purposefully difficult with -the intent that it will only be installed by users determined to use it and -is not part of the normal install/compile process.<p> - -<h3>Configuring the suEXEC wrapper</h3> -From the top-level of the Apache source tree, -type: <STRONG><code>cd support [ENTER]</code></STRONG><p> -Edit the <code>suexec.h</code> file and change the following macros to -match your local Apache installation.<p> -<EM>From support/suexec.h</EM> -<pre> -/* - * HTTPD_USER -- Define as the username under which Apache normally - * runs. This is the only user allowed to execute - * this program. - */ -#define HTTPD_USER "www" - -/* - * LOG_EXEC -- Define this as a filename if you want all suEXEC - * transactions and errors logged for auditing and - * debugging purposes. - */ -#define LOG_EXEC "/usr/local/etc/httpd/logs/cgi.log" - -/* - * DOC_ROOT -- Define as the DocumentRoot set for Apache. This - * will be the only hierarchy (aside from UserDirs) - * that can be used for suEXEC behavior. - */ -#define DOC_ROOT "/usr/local/etc/httpd/htdocs" - -/* - * SAFE_PATH -- Define a safe PATH environment to pass to CGI executables. - * - */ -#define SAFE_PATH "/usr/local/bin:/usr/bin:/bin" -</pre> - -<h3>Compiling the suEXEC wrapper</h3> -At the shell command prompt, type: <STRONG><code>cc suexec.c --o suexec [ENTER]</code></STRONG>.<p> -This should create the <STRONG><em>suexec</em></STRONG> wrapper executable. - -<h3>Compiling Apache for suEXEC support</h3> -By default, Apache is compiled to look for the suEXEC wrapper in the following -location.<p> -<EM>From src/httpd.h</EM> -<pre> -/* The path to the suEXEC wrapper */ -#ifndef SUEXEC_BIN -#define SUEXEC_BIN "/usr/local/etc/httpd/sbin/suexec" -#endif -</pre> -<p> -If your installation requires location of the wrapper program in a different -directory, edit src/httpd.h and recompile your Apache server. -See <a href="install.html">Compiling and Installing Apache</a> for more -info on this process.<p> - -<h3>Installing the suEXEC wrapper</h3> -Copy the <STRONG><em>suexec</em></STRONG> executable created in the -exercise above to the defined location for <STRONG>SUEXEC_BIN</STRONG>.<p> -In order for the wrapper to set the user ID for execution requests it -must me installed as owner <STRONG><em>root</em></STRONG> and must have -the setuserid execution bit set for file modes. -If you are not running a <STRONG><em>root</em></STRONG> user shell, do -so now and execute the following commands.<p> - -<STRONG><code>chown root /usr/local/etc/httpd/sbin/suexec [ENTER]</code></STRONG><p> -<STRONG><code>chmod 4711 /usr/local/etc/httpd/sbin/suexec [ENTER]</code></STRONG><p> - -<EM>Change the path to the suEXEC wrapper to match your system -installation.</EM> - -<hr> - -<h3><a name="model">Security Model of suEXEC</a></h3> -The <STRONG>suEXEC</STRONG> wrapper supplied with Apache performs the -following security checks before it will execute any program passed to -it for execution. -<ol> -<li>User executing the wrapper <STRONG>must be a valid user on this - system</STRONG>. -<li>User executing the wrapper <STRONG>must be the compiled in - HTTPD_USER</STRONG>. -<li>The command that the request wishes to execute <STRONG>must not - contain a leading / or ../, or the string "/../" anywhere</STRONG>. -<li>The command being executed <STRONG>must reside under the compiled in - DOC_ROOT</STRONG>. -<li>The current working directory <STRONG>must be a directory</STRONG>. -<li>The current working directory <STRONG>must not be writable by - <em>group</em> or <em>other</em></STRONG>. -<li>The command being executed <STRONG>cannot be a symbolic link</STRONG>. -<li>The command being executed <STRONG>cannot be writable by - <em>group</em> or <em>other</em></STRONG>. -<li>The command being executed <STRONG>cannot be a <em>setuid</em> or - <em>setgid</em> program</STRONG>. -<li>The target UID and GID <STRONG>must be a valid user and group on - this system</STRONG>. -<li>The target UID and GID to execute as, <STRONG>must match the UID and - GID of the directory</STRONG>. -<li>The target execution UID and GID <STRONG>must not be the privileged - ID 0</STRONG>. -</ol> -If any of these issues are too restrictive, or do not seem restrictive -enough, you are welcome to install your own version of the wrapper. -We've given you the rope, now go have fun with it. <STRONG>:-)</STRONG> - -<hr> - -<h3>Using suEXEC</h3> -After properly installing the <STRONG>suexec</STRONG> wrapper -executable, you must kill and restart the Apache server. A simple -<code><STRONG>kill -1 `cat httpd.pid`</STRONG></code> will not be enough. -Upon startup of the web-server, if Apache finds a properly configured -<STRONG>suexec</STRONG> wrapper, it will print the following message to -the console:<p> - -<code>Configuring Apache for use with suexec wrapper.</code><p> - -If you don't see this message at server startup, the server is most -likely not finding the wrapper program where it expects it, or the -executable is not installed <STRONG><em>setuid root</em></STRONG>. Check -your installation and try again.<p> - -One way to use <STRONG>suEXEC</STRONG> is through the -<a href="mod/core.html#user"><STRONG>User</STRONG></a> and -<a href="mod/core.html#group"><STRONG>Group</STRONG></a> directives in -<a href="mod/core.html#virtualhost"><STRONG>VirtualHost</STRONG></a> -definitions. By setting these directives to values different from the -main server user ID, all requests for CGI resources will be executed as -the <STRONG>User</STRONG> and <STRONG>Group</STRONG> defined for that -<STRONG><VirtualHost></STRONG>. If only one or -neither of these directives are specified for a -<STRONG><VirtualHost></STRONG> then the main -server userid is assumed.<p> - -<STRONG>suEXEC</STRONG> can also be used to to execute CGI programs as -the user to which the request is being directed. This is accomplished by -using the <STRONG>~</STRONG> character prefixing the user ID for whom -execution is desired. -The only requirement needed for this feature to work is for CGI -execution to be enabled for the user and that the script must meet the -scrutiny of the <a href="#model">security checks</a> above. - -<hr> - -<h3>Debugging suEXEC</h3> -The suEXEC wrapper will write log information to the location defined in -the <code>suexec.h</code> as indicated above. If you feel you have -configured and installed the wrapper properly, -have a look at this log and the error_log for the server to see where -you may have gone astray. -<!--#include virtual="footer.html" --> - -</BODY> -</HTML> |