diff options
| author | (no author) <(no author)@unknown> | 1997-04-28 20:16:48 +0000 |
|---|---|---|
| committer | (no author) <(no author)@unknown> | 1997-04-28 20:16:48 +0000 |
| commit | 91988af446ef2c42989d2fdd1f64885e4e2c1614 (patch) | |
| tree | 919ef6c1b6c49398ce4d3962f1e3e6fb7fb3ed2d | |
| parent | 9c9ce0ebcf943341f280e9535fccdb486ebfdcb3 (diff) | |
| download | httpd-91988af446ef2c42989d2fdd1f64885e4e2c1614.tar.gz | |
This commit was manufactured by cvs2svn to create tagAPACHE_1_2b10
'APACHE_1_2b10'.
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/tags/APACHE_1_2b10@78055 13f79535-47bb-0310-9956-ffa450edef68
| -rw-r--r-- | docs/docroot/apache_pb.gif | bin | 2326 -> 0 bytes | |||
| -rw-r--r-- | docs/manual/bind.html.en | 101 | ||||
| -rw-r--r-- | docs/manual/cgi_path.html.en | 84 | ||||
| -rw-r--r-- | docs/manual/content-negotiation.html.en | 419 | ||||
| -rw-r--r-- | docs/manual/custom-error.html.en | 145 | ||||
| -rw-r--r-- | docs/manual/developer/API.html | 996 | ||||
| -rw-r--r-- | docs/manual/handler.html.en | 134 | ||||
| -rw-r--r-- | docs/manual/install.html.en | 242 | ||||
| -rw-r--r-- | docs/manual/invoking.html.en | 117 | ||||
| -rw-r--r-- | docs/manual/platform/perf-bsd44.html | 228 | ||||
| -rw-r--r-- | docs/manual/platform/perf-dec.html | 271 | ||||
| -rw-r--r-- | docs/manual/platform/perf.html | 134 | ||||
| -rw-r--r-- | docs/manual/platform/unixware.html | 52 | ||||
| -rw-r--r-- | docs/manual/stopping.html.en | 140 | ||||
| -rw-r--r-- | docs/manual/suexec.html.en | 155 |
15 files changed, 0 insertions, 3218 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 9812613a02..0000000000 --- a/docs/manual/bind.html.en +++ /dev/null @@ -1,101 +0,0 @@ -<html><head> -<title>Setting which addresses and ports Apache uses</title> -</head><body> - -<!--#include virtual="header.html" --> -<h1>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 behavour 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>. -</ul> - -<!--#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 81bb314ead..0000000000 --- a/docs/manual/cgi_path.html.en +++ /dev/null @@ -1,84 +0,0 @@ -<html><head> -<title>PATH_INFO Changes in the CGI Environment</title> -</head><body> - -<!--#include virtual="header.html" --> -<h1>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 -counterintiutive, 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 -gauranteed that -"<code>http://$SERVER_NAME:$SERVER_PORT$SCRIPT_NAME$PATH_INFO</code>" -will always be an accessable URL that points to the current script, -something which was not neccessarily 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 neccessary 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 existance 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 45388ff294..0000000000 --- a/docs/manual/content-negotiation.html.en +++ /dev/null @@ -1,419 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Apache Content Negotiation</TITLE> -</HEAD> - -<BODY> -<!--#include virtual="header.html" --> -<h1>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 prefering 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 negotaion actually takes place in order to use Apache's -content negotation 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 achive a better result. The ways Apache can -fiddle quality factors is explained in more detail below. - -<h3>Dimensions of Negotation</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 preferneces 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 negotation (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 -behaviour. 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 cacheing 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.en b/docs/manual/custom-error.html.en deleted file mode 100644 index 09b4cf5261..0000000000 --- a/docs/manual/custom-error.html.en +++ /dev/null @@ -1,145 +0,0 @@ -<HTML> -<HEAD> -<TITLE>Custom error responses</TITLE> -</HEAD> - -<BODY> -<!--#include virtual="header.html" --> -<H1>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 a45d8694cb..0000000000 --- a/docs/manual/developer/API.html +++ /dev/null @@ -1,996 +0,0 @@ -<html><head> -<title>Apache API notes</title> -</head> -<body> -<!--#include virtual="header.html" --> -<h1>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 recognise <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>Tracking open files, etc.</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 c8ca434f13..0000000000 --- a/docs/manual/handler.html.en +++ /dev/null @@ -1,134 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Apache's Handler Use</TITLE> -</HEAD> - -<BODY> -<!--#include virtual="header.html" --> -<h1>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 71efcea03b..0000000000 --- a/docs/manual/install.html.en +++ /dev/null @@ -1,242 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Compiling and Installing Apache</TITLE> -</HEAD> - -<BODY> -<!--#include virtual="header.html" --> - -<H1>Compiling and Installing Apache 1.2</H1> - -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 initiallisation 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 7534bc055f..0000000000 --- a/docs/manual/invoking.html.en +++ /dev/null @@ -1,117 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Starting Apache</TITLE> -</HEAD> - -<BODY> -<!--#include virtual="header.html" --> -<h1>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/platform/perf-bsd44.html b/docs/manual/platform/perf-bsd44.html deleted file mode 100644 index ffcf4d845a..0000000000 --- a/docs/manual/platform/perf-bsd44.html +++ /dev/null @@ -1,228 +0,0 @@ -<html> -<head> -<title>Running a High-Performance Web Server for BSD</title> -</head> - -<body> -<A NAME="initial"> -<!--#include virtual="header.html" --> -</A> -<H2>Running a High-Performance Web Server for BSD</H2> - -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 ef75f81b06..0000000000 --- a/docs/manual/platform/perf-dec.html +++ /dev/null @@ -1,271 +0,0 @@ -<HEAD> -<TITLE>Performance Tuning Tips for Digital Unix</TITLE> -</HEAD> -<BODY> -<!--#include virtual="header.html" --> -<H1>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. -</UL> - -<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 4fc97a88eb..0000000000 --- a/docs/manual/platform/perf.html +++ /dev/null @@ -1,134 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<html> -<head> -<title>Hints on Running a High-Performance Web Server</title> -</head> - -<body> -<!--#include virtual="header.html" --> -<h2>Hints on Running a High-Performance Web Server</H2> - -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> - -<A NAME="AUX"> -<H3>A/UX (Apple's UNIX)</H3> -</A> - -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> - -<A NAME="BSD"> -<H3>BSD-based (BSDI, FreeBSD, etc)</H3> -</A> - -<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> - -<A NAME="DEC"> -<H3>Digital UNIX</H3> -</A> - -We have some <A HREF="perf-dec.html">newsgroup postings</A> on how to -tune Digital UNIX 3.2 and 4.0. - -<P><HR> - -<A NAME="HP"> -<H3>Hewlett-Packard</H3> -</A> - -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> - -<A NAME="Linux"> -<H3>Linux</H3> -</A> - -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> - -<A NAME="SGI"> -<H3>SGI</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> - -<A NAME="Solaris"> -<H3>Solaris 2.4</H3> -</A> - -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> - -<A NAME="SunOS"> -<H3>SunOS 4.x</H3> -</A> - -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 73240b5cee..0000000000 --- a/docs/manual/platform/unixware.html +++ /dev/null @@ -1,52 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Compiling Apache under UnixWare</TITLE> -</HEAD> - -<BODY> -<!--#include virtual="header.html" --> - -<H1>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). - -<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/stopping.html.en b/docs/manual/stopping.html.en deleted file mode 100644 index e333deb851..0000000000 --- a/docs/manual/stopping.html.en +++ /dev/null @@ -1,140 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> -<HTML> -<HEAD> -<TITLE>Stopping and Restarting Apache</TITLE> -</HEAD> - -<BODY> -<!--#include virtual="header.html" --> -<h1>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. - -<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. - -<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> 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.en b/docs/manual/suexec.html.en deleted file mode 100644 index 53ad269e6f..0000000000 --- a/docs/manual/suexec.html.en +++ /dev/null @@ -1,155 +0,0 @@ -<html><head> -<title>Apache SetUserID Support</title> -</head><body> - -<!--#include virtual="header.html" --> -<h1>Apache suEXEC Support</h1> - -<hr> - -<h3>What is suEXEC?</h3> -The <b>suEXEC</b> feature, introduced in Apache 1.2 provides the ability to -run <b>CGI</b> 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. <b>:-)</b> 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> - -<ul> -<h3>Configuring the suEXEC wrapper</h3> -From the top-level of the Apache source tree, type: <b><code>cd support [ENTER]</code></b><p> -Edit the <code>suexec.h</code> file and change the following macros to match your -local Apache installation.<p> -<i>From support/suexec.h</i> -<code> -<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> -</code> - -<h3>Compiling the suEXEC wrapper</h3> -At the shell command prompt, type: <b><code>cc suexec.c -o suexec [ENTER]</code></b>.<p> -This should create the <b><em>suexec</em></b> 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> -<i>From src/httpd.h</i> -<code> -<pre> -/* The path to the suEXEC wrapper */ -#ifndef SUEXEC_BIN -#define SUEXEC_BIN "/usr/local/etc/httpd/sbin/suexec" -#endif -</pre> -</code> -<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 <b><em>suexec</em></b> executable created in the exercise above to the defined -location for <b>SUEXEC_BIN</b>.<p> -In order for the wrapper to set the user id for execution requests it must me installed -as owner <b><em>root</em></b> and must have the setuserid execution bit set for file modes. -If you are not running a <b><em>root</em></b> user shell, do so now and execute the following -commands.<p> - -<b><code>chown root /usr/local/etc/httpd/sbin/suexec [ENTER]</code></b><p> -<b><code>chmod 4711 /usr/local/etc/httpd/sbin/suexec [ENTER]</code></b><p> - -<i>Change the path to the suEXEC wrapper to match your system installation.</i> -</ul> - -<hr> - -<a name="model"></a> -<h3>Security Model of suEXEC</h3> -The <b>suEXEC</b> 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 <b>must be a valid user on this system</b>. -<li>User executing the wrapper <b>must be the compiled in HTTPD_USER</b>. -<li>The command that the request wishes to execute <b>must not contain a /</b>. -<li>The command being executed <b>must reside under the compiled in DOC_ROOT</b>. -<li>The current working directory <b>must be a directory</b>. -<li>The current working directory <b>must not be writable by <em>group</em> or <em>other</em></b>. -<li>The command being executed <b>cannot be a symbolic link</b>. -<li>The command being executed <b>cannot be writable by <em>group</em> or <em>other</em></b>. -<li>The command being executed <b>cannot be a <em>setuid</em> or <em>setgid</em> program</b>. -<li>The target UID and GID <b>must be a valid user and group on this system</b>. -<li>The target UID and GID to execute as, <b>must match the UID and GID of the directory</b>. -<li>The target execution UID and GID <b>must not be the privledged ID 0</b>. -</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. <b>:-)</b> - -<hr> - -<h3>Using suEXEC</h3> -After properly installing the <b>suexec</b> wrapper executable, you must kill and restart -the Apache server. A simple <code><b>kill -1 `cat httpd.pid`</b></code> will not be enough. -Upon startup of the web-server, if Apache finds a properly configured <b>suexec</b> 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 <b><em>setuid root</em></b>. Check your installation and try again.<p> - -One way to use <b>suEXEC</b> is through the <a href="mod/core.html#user"><b>User</b></a> and <a href="mod/core.html#group"><b>Group</b></a> directives in <a href="mod/core.html#virtualhost"><b>VirtualHost</b></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 <b>User</b> and <b>Group</b> defined for that <b><VirtualHost></b>. If only one or -neither of these directives are specified for a <b><VirtualHost></b> then the main -server userid is assumed.<p> - -<b>suEXEC</b> 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 <b>~</b> 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> - |
