diff options
| author | (no author) <(no author)@unknown> | 1998-05-21 04:07:17 +0000 |
|---|---|---|
| committer | (no author) <(no author)@unknown> | 1998-05-21 04:07:17 +0000 |
| commit | e84a1d63a22a813c89a7e7d749f8bebde3e668b0 (patch) | |
| tree | 9150dfb1f7232b18708c10b92fb893d188a9ca84 | |
| parent | 65b7400981c6924879fdd62c3c5030ebc61d47cf (diff) | |
| download | httpd-e84a1d63a22a813c89a7e7d749f8bebde3e668b0.tar.gz | |
This commit was manufactured by cvs2svn to create tag 'APACHE_1_3b7'.APACHE_1_3b7
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/tags/APACHE_1_3b7@81337 13f79535-47bb-0310-9956-ffa450edef68
24 files changed, 0 insertions, 5914 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 75bacbb253..0000000000 --- a/docs/manual/bind.html.en +++ /dev/null @@ -1,135 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML><HEAD> -<TITLE>Setting which addresses and ports Apache uses</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Setting which addresses and ports Apache uses</H1> - -<HR> - -When Apache starts, it connects to some port and address on the -local machine and waits for incoming requests. By default, it -listens to all addresses on the machine, and to the port -as specified by the <TT>Port</TT> directive in the server configuration. -However, it can be told to listen to more the one port, or to listen -to only selected addresses, or a combination. This is often combined -with the Virtual Host feature which determines how Apache -responds to different IP addresses, hostnames and ports.<P> - -There are two directives used to restrict or specify which addresses -and ports Apache listens to. - -<UL> -<LI><A HREF="#bindaddress">BindAddress</A> is used to restrict the server to - listening to - a single address, and can be used to permit multiple Apache servers - on the same machine listening to different IP addresses. -<LI><A HREF="#listen">Listen</A> can be used to make a single Apache server - listen - to more than one address and/or port. -</UL> - -<H3><A NAME="bindaddress">BindAddress</A></H3> -<A - HREF="mod/directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> BindAddress <EM>[ * | IP-address - | hostname ]</EM><BR> -<A - HREF="mod/directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>BindAddress *</CODE><BR> -<A - HREF="mod/directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="mod/directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> 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> -<A - HREF="mod/directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> Listen <EM>[ port | IP-address:port ]</EM><BR> -<A - HREF="mod/directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>none</CODE><BR> -<A - HREF="mod/directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="mod/directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Core<P> - -<TT>Listen</TT> can be used instead of <TT>BindAddress</TT> and -<TT>Port</TT>. It tells the server to accept incoming requests on the -specified port or address-and-port combination. If the first format is -used, with a port number only, the server listens to the given port on -all interfaces, instead of the port given by the <TT>Port</TT> -directive. If an IP address is given as well as a port, the server -will listen on the given port and interface. <P> Multiple Listen -directives may be used to specify a number of addresses and ports to -listen to. The server will respond to requests from any of the listed -addresses and ports.<P> - -For example, to make the server accept connections on both port -80 and port 8000, use: -<PRE> - Listen 80 - Listen 8000 -</PRE> - -To make the server accept connections on two specified -interfaces and port numbers, use -<PRE> - Listen 192.170.2.1:80 - Listen 192.170.2.5:8000 -</PRE> - -<H2>How this works with Virtual Hosts</H2> - -BindAddress and Listen do not implement Virtual Hosts. They tell the -main server what addresses and ports to listen to. If no -<VirtualHost> directives are used, the server will behave the -same for all accepted requests. However, <VirtualHost> can be -used to specify a different behavior for one or more of the addresses -and ports. To implement a VirtualHost, the server must first be told -to listen to the address and port to be used. Then a -<VirtualHost> section should be created for a specified address -and port to set the behavior of this virtual host. Note that if the -<VirtualHost> is set for an address and port that the server is -not listening to, it cannot be accessed. - -<H2>See also</H2> - -See also the documentation on -<A HREF="vhosts/index.html">Virtual Hosts</A>, -<A HREF="mod/core.html#bindaddress">BindAddress directive</A>, -<A HREF="mod/core.html#port">Port directive</A>, -<A HREF="dns-caveats.html">DNS Issues</A> -and -<A HREF="mod/core.html#virtualhost"><VirtualHost> section</A>. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/cgi_path.html.en b/docs/manual/cgi_path.html.en deleted file mode 100644 index 2b7bd963b1..0000000000 --- a/docs/manual/cgi_path.html.en +++ /dev/null @@ -1,93 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML><HEAD> -<TITLE>PATH_INFO Changes in the CGI Environment</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">PATH_INFO Changes in the CGI Environment</H1> - -<HR> - -<H2><A NAME="over">Overview</A></H2> - -<P>As implemented in Apache 1.1.1 and earlier versions, the method -Apache used to create PATH_INFO in the CGI environment was -counterintuitive, and could result in crashes in certain cases. In -Apache 1.2 and beyond, this behavior has changed. Although this -results in some compatibility problems with certain legacy CGI -applications, the Apache 1.2 behavior is still compatible with the -CGI/1.1 specification, and CGI scripts can be easily modified (<A -HREF="#compat">see below</A>). - -<H2><A NAME="prob">The Problem</A></H2> - -<P>Apache 1.1.1 and earlier implemented the PATH_INFO and SCRIPT_NAME -environment variables by looking at the filename, not the URL. While -this resulted in the correct values in many cases, when the filesystem -path was overloaded to contain path information, it could result in -errant behavior. For example, if the following appeared in a config -file: -<PRE> - Alias /cgi-ralph /usr/local/httpd/cgi-bin/user.cgi/ralph -</PRE> -<P>In this case, <CODE>user.cgi</CODE> is the CGI script, the "/ralph" -is information to be passed onto the CGI. If this configuration was in -place, and a request came for "<CODE>/cgi-ralph/script/</CODE>", the -code would set PATH_INFO to "<CODE>/ralph/script</CODE>", and -SCRIPT_NAME to "<CODE>/cgi-</CODE>". Obviously, the latter is -incorrect. In certain cases, this could even cause the server to -crash.</P> - -<H2><A NAME="solution">The Solution</A></H2> - -<P>Apache 1.2 and later now determine SCRIPT_NAME and PATH_INFO by -looking directly at the URL, and determining how much of the URL is -client-modifiable, and setting PATH_INFO to it. To use the above -example, PATH_INFO would be set to "<CODE>/script</CODE>", and -SCRIPT_NAME to "<CODE>/cgi-ralph</CODE>". This makes sense and results -in no server behavior problems. It also permits the script to be -guaranteed that -"<CODE>http://$SERVER_NAME:$SERVER_PORT$SCRIPT_NAME$PATH_INFO</CODE>" -will always be an accessible URL that points to the current script, -something which was not necessarily true with previous versions of -Apache. - -<P>However, the "<CODE>/ralph</CODE>" -information from the <CODE>Alias</CODE> directive is lost. This is -unfortunate, but we feel that using the filesystem to pass along this -sort of information is not a recommended method, and a script making -use of it "deserves" not to work. Apache 1.2b3 and later, however, do -provide <A HREF="#compat">a workaround.</A> - -<H2><A NAME="compat">Compatibility with Previous Servers</A></H2> - -<P>It may be necessary for a script that was designed for earlier -versions of Apache or other servers to need the information that the -old PATH_INFO variable provided. For this purpose, Apache 1.2 (1.2b3 -and later) sets an additional variable, FILEPATH_INFO. This -environment variable contains the value that PATH_INFO would have had -with Apache 1.1.1.</P> - -<P>A script that wishes to work with both Apache 1.2 and earlier -versions can simply test for the existence of FILEPATH_INFO, and use -it if available. Otherwise, it can use PATH_INFO. For example, in -Perl, one might use: -<PRE> - $path_info = $ENV{'FILEPATH_INFO'} || $ENV{'PATH_INFO'}; -</PRE> - -<P>By doing this, a script can work with all servers supporting the -CGI/1.1 specification, including all versions of Apache.</P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> - diff --git a/docs/manual/content-negotiation.html.en b/docs/manual/content-negotiation.html.en deleted file mode 100644 index 3f9d60ecf2..0000000000 --- a/docs/manual/content-negotiation.html.en +++ /dev/null @@ -1,527 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache Content Negotiation</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Content Negotiation</H1> - -<P> -Apache's support for content negotiation has been updated to meet the -HTTP/1.1 specification. It can choose the best representation of a -resource based on the browser-supplied preferences for media type, -languages, character set and encoding. It is also implements a -couple of features to give more intelligent handling of requests from -browsers which send incomplete negotiation information. <P> - -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> - -<P> -A resource may be available in several different representations. For -example, it might be available in different languages or different -media types, or a combination. One way of selecting the most -appropriate choice is to give the user an index page, and let them -select. However it is often possible for the server to choose -automatically. This works because browsers can send as part of each -request information about what representations they prefer. For -example, a browser could indicate that it would like to see -information in French, if possible, else English will do. Browsers -indicate their preferences by headers in the request. To request only -French representations, the browser would send - -<PRE> - Accept-Language: fr -</PRE> - -<P> -Note that this preference will only be applied when there is a choice -of representations and they vary by language. -<P> - -As an example of a more complex request, this browser has been -configured to accept French and English, but prefer French, and to -accept various media types, preferring HTML over plain text or other -text types, and preferring GIF or JPEG over other media types, but also -allowing any other media type as a last resort: - -<PRE> - Accept-Language: fr; q=1.0, en; q=0.5 - Accept: text/html; q=1.0, text/*; q=0.8, image/gif; q=0.6, - image/jpeg; q=0.6, image/*; q=0.5, */*; q=0.1 -</PRE> - -Apache 1.2 supports 'server driven' content negotiation, as defined in -the HTTP/1.1 specification. It fully supports the Accept, -Accept-Language, Accept-Charset and Accept-Encoding request headers. -<P> - -The terms used in content negotiation are: a <STRONG>resource</STRONG> is an -item which can be requested of a server, which might be selected as -the result of a content negotiation algorithm. If a resource is -available in several formats, these are called <STRONG>representations</STRONG> -or <STRONG>variants</STRONG>. The ways in which the variants for a particular -resource vary are called the <STRONG>dimensions</STRONG> of negotiation. - -<H2>Negotiation in Apache</H2> - -<P> -In order to negotiate a resource, the server needs to be given -information about each of the variants. This is done in one of two -ways: - -<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> - -<P> -A type map is a document which is associated with the handler -named <CODE>type-map</CODE> (or, for backwards-compatibility with -older Apache configurations, the mime type -<CODE>application/x-type-map</CODE>). Note that to use this feature, -you'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> - -<P> -This is a per-directory option, meaning it can be set with an -<CODE>Options</CODE> directive within a <CODE><Directory></CODE>, -<CODE><Location></CODE> or <CODE><Files></CODE> -section in <CODE>access.conf</CODE>, or (if <CODE>AllowOverride</CODE> -is properly set) in <CODE>.htaccess</CODE> files. Note that -<CODE>Options All</CODE> does not set <CODE>MultiViews</CODE>; you -have to ask for it by name. (Fixing this is a one-line change to -<CODE>http_core.h</CODE>). - -<P> - -The effect of <CODE>MultiViews</CODE> is as follows: if the server -receives a request for <CODE>/some/dir/foo</CODE>, if -<CODE>/some/dir</CODE> has <CODE>MultiViews</CODE> enabled, and -<CODE>/some/dir/foo</CODE> does <EM>not</EM> exist, then the server reads the -directory looking for files named foo.*, and effectively fakes up a -type map which names all those files, assigning them the same media -types and content-encodings it would have if the client had asked for -one of them by name. It then chooses the best match to the client's -requirements, and forwards them along. - -<P> - -This applies to searches for the file named by the -<CODE>DirectoryIndex</CODE> directive, if the server is trying to -index a directory; if the configuration files specify -<PRE> - - DirectoryIndex index - -</PRE> then the server will arbitrate between <CODE>index.html</CODE> -and <CODE>index.html3</CODE> if both are present. If neither are -present, and <CODE>index.cgi</CODE> is there, the server will run it. - -<P> - -If one of the files found when reading the directive is a CGI script, -it's not obvious what should happen. The code gives that case -special treatment --- if the request was a POST, or a GET with -QUERY_ARGS or PATH_INFO, the script is given an extremely high quality -rating, and generally invoked; otherwise it is given an extremely low -quality rating, which generally causes one of the other views (if any) -to be retrieved. - -<H2>The Negotiation Algorithm</H2> - -After Apache has obtained a list of the variants for a given resource, -either from a type-map file or from the filenames in the directory, it -applies a algorithm to decide on the 'best' variant to return, if -any. To do this it calculates a quality value for each variant in each -of the dimensions of variance. It is not necessary to know any of the -details of how negotiation actually takes place in order to use Apache's -content negotiation features. However the rest of this document -explains in detail the algorithm used for those interested. <P> - -In some circumstances, Apache can 'fiddle' the quality factor of a -particular dimension to achieve a better result. The ways Apache can -fiddle quality factors is explained in more detail below. - -<H3>Dimensions of Negotiation</H3> - -<TABLE> -<TR><TH>Dimension -<TH>Notes -<TR><TD>Media Type -<TD>Browser indicates preferences on Accept: header. Each item -can have an associated quality factor. Variant description can also -have a quality factor. -<TR><TD>Language -<TD>Browser indicates preferences on Accept-Language: header. Each -item -can have a quality factor. Variants can be associated with none, one -or more languages. -<TR><TD>Encoding -<TD>Browser indicates preference with Accept-Encoding: header. -<TR><TD>Charset -<TD>Browser indicates preference with Accept-Charset: header. Variants -can indicate a charset as a parameter of the media type. -</TABLE> - -<H3>Apache Negotiation Algorithm</H3> - -<P> -Apache uses an algorithm to select the 'best' variant (if any) to -return to the browser. This algorithm is not configurable. It operates -like this: - -<OL> -<LI> -Firstly, for each dimension of the negotiation, the appropriate -Accept header is checked and a quality assigned to this each -variant. If the Accept header for any dimension means that this -variant is not acceptable, eliminate it. If no variants remain, go -to step 4. - -<LI>Select the 'best' variant by a process of elimination. Each of -the following tests is applied in order. Any variants not selected at -each stage are eliminated. After each test, if only one variant -remains, it is selected as the best match. If more than one variant -remains, move onto the next test. - -<OL> -<LI>Multiply the quality factor from the Accept header with the - quality-of-source factor for this variant's media type, and select - the variants with the highest value - -<LI>Select the variants with the highest language quality factor - -<LI>Select the variants with the best language match, using either the - order of languages on the <CODE>LanguagePriority</CODE> directive (if - present), - else the order of languages on the Accept-Language header. - -<LI>Select the variants with the highest 'level' media parameter - (used to give the version of text/html media types). - -<LI>Select only unencoded variants, if there is a mix of encoded - and non-encoded variants. If either all variants are encoded - or all variants are not encoded, select all. - -<LI>Select only variants with acceptable charset media parameters, - as given on the Accept-Charset header line. Charset ISO-8859-1 - is always acceptable. Variants not associated with a particular - charset are assumed to be in ISO-8859-1. - -<LI>Select the variants with the smallest content length - -<LI>Select the first variant of those remaining (this will be either the -first listed in the type-map file, or the first read from the directory) -and go to stage 3. - -</OL> - -<LI>The algorithm has now selected one 'best' variant, so return - it as the response. The HTTP response header Vary is set to indicate the - dimensions of negotiation (browsers and caches can use this - information when caching the resource). End. - -<LI>To get here means no variant was selected (because non are acceptable - to the browser). Return a 406 status (meaning "No acceptable representation") - with a response body consisting of an HTML document listing the - available variants. Also set the HTTP Vary header to indicate the - dimensions of variance. - -</OL> - -<H2><A NAME="better">Fiddling with Quality Values</A></H2> - -<P> -Apache sometimes changes the quality values from what would be -expected by a strict interpretation of the algorithm above. This is to -get a better result from the algorithm for browsers which do not send -full or accurate information. Some of the most popular browsers send -Accept header information which would otherwise result in the -selection of the wrong variant in many cases. If a browser -sends full and correct information these fiddles will not -be applied. -<P> - -<H3>Media Types and Wildcards</H3> - -<P> -The Accept: request header indicates preferences for media types. It -can also include 'wildcard' media types, such as "image/*" or "*/*" -where the * matches any string. So a request including: -<PRE> - Accept: image/*, */* -</PRE> - -would indicate that any type starting "image/" is acceptable, -as is any other type (so the first "image/*" is redundant). Some -browsers routinely send wildcards in addition to explicit types they -can handle. For example: -<PRE> - Accept: text/html, text/plain, image/gif, image/jpeg, */* -</PRE> - -The intention of this is to indicate that the explicitly -listed types are preferred, but if a different representation is -available, that is ok too. However under the basic algorithm, as given -above, the */* wildcard has exactly equal preference to all the other -types, so they are not being preferred. The browser should really have -sent a request with a lower quality (preference) value for *.*, such -as: -<PRE> - Accept: text/html, text/plain, image/gif, image/jpeg, */*; q=0.01 -</PRE> - -The explicit types have no quality factor, so they default to a -preference of 1.0 (the highest). The wildcard */* is given -a low preference of 0.01, so other types will only be returned if -no variant matches an explicitly listed type. -<P> - -If the Accept: header contains <EM>no</EM> q factors at all, Apache sets -the q value of "*/*", if present, to 0.01 to emulate the desired -behavior. It also sets the q value of wildcards of the format -"type/*" to 0.02 (so these are preferred over matches against -"*/*". If any media type on the Accept: header contains a q factor, -these special values are <EM>not</EM> applied, so requests from browsers -which send the correct information to start with work as expected. - -<H3>Variants with no Language</H3> - -<P> -If some of the variants for a particular resource have a language -attribute, and some do not, those variants with no language -are given a very low language quality factor of 0.001.<P> - -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> - -<P> -The meaning of a variant with no language is that it is -always acceptable to the browser. If the request Accept-Language -header includes either en or fr (or both) one of foo.en.html -or foo.fr.html will be returned. If the browser does not list -either en or fr as acceptable, foo.html will be returned instead. - -<H2>Note on hyperlinks and naming conventions</H2> - -<P> -If you are using language negotiation you can choose between -different naming conventions, because files can have more than one -extension, and the order of the extensions is normally irrelevant -(see <A HREF="mod/mod_mime.html">mod_mime</A> documentation for details). -<P> -A typical file has a mime-type extension (e.g. <SAMP>html</SAMP>), -maybe an encoding extension (e.g. <SAMP>gz</SAMP> and of course a -language extension (e.g. <SAMP>en</SAMP>) when we have different -language variants of this file. - -<P> -Examples: -<UL> -<LI>foo.en.html -<LI>foo.html.en -<LI>foo.en.html.gz -</UL> - -<P> -Here some more examples of filenames together with valid and invalid -hyperlinks: -</P> - -<TABLE BORDER=1 CELLPADDING=8 CELLSPACING=0> -<TR> - <TH>Filename</TH> - <TH>Valid hyperlink</TH> - <TH>Invalid hyperlink</TH> -</TR> -<TR> - <TD><EM>foo.html.en</EM></TD> - <TD>foo<BR> - foo.html</TD> - <TD>-</TD> -</TR> -<TR> - <TD><EM>foo.en.html</EM></TD> - <TD>foo</TD> - <TD>foo.html</TD> -</TR> -<TR> - <TD><EM>foo.html.en.gz</EM></TD> - <TD>foo<BR> - foo.html</TD> - <TD>foo.gz<BR> - foo.html.gz</TD> -</TR> -<TR> - <TD><EM>foo.en.html.gz</EM></TD> - <TD>foo</TD> - <TD>foo.html<BR> - foo.html.gz<BR> - foo.gz</TD> -</TR> -<TR> - <TD><EM>foo.gz.html.en</EM></TD> - <TD>foo<BR> - foo.gz<BR> - foo.gz.html</TD> - <TD>foo.html</TD> -</TR> -<TR> - <TD><EM>foo.html.gz.en</EM></TD> - <TD>foo<BR> - foo.html<BR> - foo.html.gz</TD> - <TD>foo.gz</TD> -</TR> -</TABLE> - -<P> -Looking at the table above you will notice that it is always possible to -use the name without any extensions in an hyperlink (e.g. <SAMP>foo</SAMP>). -The advantage is that you can hide the actual type of a -document rsp. file and can change it later, e.g. from <SAMP>html</SAMP> -to <SAMP>shtml</SAMP> or <SAMP>cgi</SAMP> without changing any -hyperlink references. - -<P> -If you want to continue to use a mime-type in your hyperlinks (e.g. -<SAMP>foo.html</SAMP>) the language extension (including an encoding extension -if there is one) must be on the right hand side of the mime-type extension -(e.g. <SAMP>foo.html.en</SAMP>). - - -<H2>Note on Caching</H2> - -<P> -When a cache stores a document, it associates it with the request URL. -The next time that URL is requested, the cache can use the stored -document, provided it is still within date. But if the resource is -subject to content negotiation at the server, this would result in -only the first requested variant being cached, and subsequent cache -hits could return the wrong response. To prevent this, -Apache normally marks all responses that are returned after content negotiation -as non-cacheable by HTTP/1.0 clients. Apache also supports the HTTP/1.1 -protocol features to allow caching of negotiated responses. <P> - -For requests which come from a HTTP/1.0 compliant client (either a -browser or a cache), the directive <TT>CacheNegotiatedDocs</TT> can be -used to allow caching of responses which were subject to negotiation. -This directive can be given in the server config or virtual host, and -takes no arguments. It has no effect on requests from HTTP/1.1 -clients. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/custom-error.html.en b/docs/manual/custom-error.html.en deleted file mode 100644 index c76f224e26..0000000000 --- a/docs/manual/custom-error.html.en +++ /dev/null @@ -1,177 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Custom error responses</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Custom error responses</H1> - -<DL> - -<DT>Purpose - - <DD>Additional functionality. Allows webmasters to configure the response of - Apache to some error or problem. - - <P>Customizable responses can be defined to be activated in the - event of a server detected error or problem. - - <P>e.g. if a script crashes and produces a "500 Server Error" - response, then this response can be replaced with either some - friendlier text or by a redirection to another URL (local or - external). - <P> - -<DT>Old behavior - - <DD>NCSA httpd 1.3 would return some boring old error/problem message - which would often be meaningless to the user, and would provide no - means of logging the symptoms which caused it.<BR> - - <P> - -<DT>New behavior - - <DD>The server can be asked to; - <OL> - <LI>Display some other text, instead of the NCSA hard coded messages, or - <LI>redirect to a local URL, or - <LI>redirect to an external URL. - </OL> - - <P>Redirecting to another URL can be useful, but only if some information - can be passed which can then be used to explain and/or log the - error/problem - more clearly. - - <P>To achieve this, Apache will define new CGI-like environment - variables, e.g. - - <BLOCKQUOTE><CODE> -REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/x-xbitmap, image/jpeg <BR> -REDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX A.09.05 9000/712) <BR> -REDIRECT_PATH=.:/bin:/usr/local/bin:/etc <BR> -REDIRECT_QUERY_STRING= <BR> -REDIRECT_REMOTE_ADDR=121.345.78.123 <BR> -REDIRECT_REMOTE_HOST=ooh.ahhh.com <BR> -REDIRECT_SERVER_NAME=crash.bang.edu <BR> -REDIRECT_SERVER_PORT=80 <BR> -REDIRECT_SERVER_SOFTWARE=Apache/0.8.15 <BR> -REDIRECT_URL=/cgi-bin/buggy.pl <BR> - </CODE></BLOCKQUOTE> - - <P>note the <CODE>REDIRECT_</CODE> prefix. - - <P>At least <CODE>REDIRECT_URL</CODE> and <CODE>REDIRECT_QUERY_STRING</CODE> - will - be passed to the new URL (assuming it's a cgi-script or a cgi-include). - The - other variables will exist only if they existed prior to the - error/problem. - <STRONG>None</STRONG> of these will be set if your ErrorDocument is an - <EM>external</EM> redirect (<EM>i.e.</EM>, anything starting with a - scheme 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> -<P> -If the ErrorDocument specifies a local redirect to a CGI script, the script -should include a "<SAMP>Status:</SAMP>" header field in its output -in order to ensure the propagation all the way back to the client -of the error condition that caused it to be invoked. For instance, a Perl -ErrorDocument script might include the following: -</P> -<PRE> - : - print "Content-type: text/html\n"; - printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"}; - : -</PRE> -<P> -If the script is dedicated to handling a particular error condition, such as -<SAMP>404 Not Found</SAMP>, it can use the specific code and -error text instead. -</P> - -<!--#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 1b59833024..0000000000 --- a/docs/manual/developer/API.html +++ /dev/null @@ -1,1151 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML><HEAD> -<TITLE>Apache API notes</TITLE> -</HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Apache API notes</H1> - -These are some notes on the Apache API and the data structures you -have to deal with, etc. They are not yet nearly complete, but -hopefully, they will help you get your bearings. Keep in mind that -the API is still subject to change as we gain experience with it. -(See the TODO file for what <EM>might</EM> be coming). However, -it will be easy to adapt modules to any changes that are made. -(We have more modules to adapt than you do). -<P> - -A few notes on general pedagogical style here. In the interest of -conciseness, all structure declarations here are incomplete --- the -real ones have more slots that I'm not telling you about. For the -most part, these are reserved to one component of the server core or -another, and should be altered by modules with caution. However, in -some cases, they really are things I just haven't gotten around to -yet. Welcome to the bleeding edge.<P> - -Finally, here's an outline, to give you some bare idea of what's -coming up, and in what order: - -<UL> -<LI> <A HREF="#basics">Basic concepts.</A> -<MENU> - <LI> <A HREF="#HMR">Handlers, Modules, and Requests</A> - <LI> <A HREF="#moduletour">A brief tour of a module</A> -</MENU> -<LI> <A HREF="#handlers">How handlers work</A> -<MENU> - <LI> <A HREF="#req_tour">A brief tour of the <CODE>request_rec</CODE></A> - <LI> <A HREF="#req_orig">Where request_rec structures come from</A> - <LI> <A HREF="#req_return">Handling requests, declining, and returning error - codes</A> - <LI> <A HREF="#resp_handlers">Special considerations for response handlers</A> - <LI> <A HREF="#auth_handlers">Special considerations for authentication - handlers</A> - <LI> <A HREF="#log_handlers">Special considerations for logging handlers</A> -</MENU> -<LI> <A HREF="#pools">Resource allocation and resource pools</A> -<LI> <A HREF="#config">Configuration, commands and the like</A> -<MENU> - <LI> <A HREF="#per-dir">Per-directory configuration structures</A> - <LI> <A HREF="#commands">Command handling</A> - <LI> <A HREF="#servconf">Side notes --- per-server configuration, - virtual servers, <EM>etc</EM>.</A> -</MENU> -</UL> - -<H2><A NAME="basics">Basic concepts.</A></H2> - -We begin with an overview of the basic concepts behind the -API, and how they are manifested in the code. - -<H3><A NAME="HMR">Handlers, Modules, and Requests</A></H3> - -Apache breaks down request handling into a series of steps, more or -less the same way the Netscape server API does (although this API has -a few more stages than NetSite does, as hooks for stuff I thought -might be useful in the future). These are: - -<UL> - <LI> URI -> Filename translation - <LI> Auth ID checking [is the user who they say they are?] - <LI> Auth access checking [is the user authorized <EM>here</EM>?] - <LI> Access checking other than auth - <LI> Determining MIME type of the object requested - <LI> `Fixups' --- there aren't any of these yet, but the phase is - intended as a hook for possible extensions like - <CODE>SetEnv</CODE>, which don't really fit well elsewhere. - <LI> Actually sending a response back to the client. - <LI> Logging the request -</UL> - -These phases are handled by looking at each of a succession of -<EM>modules</EM>, looking to see if each of them has a handler for the -phase, and attempting invoking it if so. The handler can typically do -one of three things: - -<UL> - <LI> <EM>Handle</EM> the request, and indicate that it has done so - by returning the magic constant <CODE>OK</CODE>. - <LI> <EM>Decline</EM> to handle the request, by returning the magic - integer constant <CODE>DECLINED</CODE>. In this case, the - server behaves in all respects as if the handler simply hadn't - been there. - <LI> Signal an error, by returning one of the HTTP error codes. - This terminates normal handling of the request, although an - ErrorDocument may be invoked to try to mop up, and it will be - logged in any case. -</UL> - -Most phases are terminated by the first module that handles them; -however, for logging, `fixups', and non-access authentication -checking, all handlers always run (barring an error). Also, the -response phase is unique in that modules may declare multiple handlers -for it, via a dispatch table keyed on the MIME type of the requested -object. Modules may declare a response-phase handler which can handle -<EM>any</EM> request, by giving it the key <CODE>*/*</CODE> (i.e., a -wildcard MIME type specification). However, wildcard handlers are -only invoked if the server has already tried and failed to find a more -specific response handler for the MIME type of the requested object -(either none existed, or they all declined).<P> - -The handlers themselves are functions of one argument (a -<CODE>request_rec</CODE> structure. vide infra), which returns an -integer, as above.<P> - -<H3><A NAME="moduletour">A brief tour of a module</A></H3> - -At this point, we need to explain the structure of a module. Our -candidate will be one of the messier ones, the CGI module --- this -handles both CGI scripts and the <CODE>ScriptAlias</CODE> config file -command. It's actually a great deal more complicated than most -modules, but if we're going to have only one example, it might as well -be the one with its fingers in every place.<P> - -Let's begin with handlers. In order to handle the CGI scripts, the -module declares a response handler for them. Because of -<CODE>ScriptAlias</CODE>, it also has handlers for the name -translation phase (to recognize <CODE>ScriptAlias</CODE>ed URIs), the -type-checking phase (any <CODE>ScriptAlias</CODE>ed request is typed -as a CGI script).<P> - -The module needs to maintain some per (virtual) -server information, namely, the <CODE>ScriptAlias</CODE>es in effect; -the module structure therefore contains pointers to a functions which -builds these structures, and to another which combines two of them (in -case the main server and a virtual server both have -<CODE>ScriptAlias</CODE>es declared).<P> - -Finally, this module contains code to handle the -<CODE>ScriptAlias</CODE> command itself. This particular module only -declares one command, but there could be more, so modules have -<EM>command tables</EM> which declare their commands, and describe -where they are permitted, and how they are to be invoked. <P> - -A final note on the declared types of the arguments of some of these -commands: a <CODE>pool</CODE> is a pointer to a <EM>resource pool</EM> -structure; these are used by the server to keep track of the memory -which has been allocated, files opened, etc., either to service a -particular request, or to handle the process of configuring itself. -That way, when the request is over (or, for the configuration pool, -when the server is restarting), the memory can be freed, and the files -closed, <EM>en masse</EM>, 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>ap_table_get</CODE> and <CODE>ap_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>ap_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>ap_sub_req_lookup_file</CODE> and - <CODE>ap_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>ap_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>ap_rputc</CODE> -and <CODE>ap_rprintf</CODE>, for internally generated output, and -<CODE>ap_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>ap_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>ap_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 = ap_set_content_length (r, r->finfo.st_size)) - || (errstatus = ap_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); - ap_send_http_header (r); - - if (!r->header_only) send_fd (f, r); - ap_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>ap_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>ap_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>ap_auth_type</CODE>, - <CODE>ap_auth_name</CODE>, and <CODE>ap_requires</CODE>. - <LI> Common routines, to handle the protocol end of things, at least - for HTTP basic authentication (<CODE>ap_get_basic_auth_pw</CODE>, - which sets the <CODE>connection->user</CODE> structure field - automatically, and <CODE>ap_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> -<P> -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> -<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> -<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> -<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> -<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">ap_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>ap_palloc</CODE> is generally faster than -<CODE>malloc</CODE>. -</P> -<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. -</P> -<H3>Allocation of memory in pools</H3> -<P> -Memory is allocated to pools by calling the function -<CODE>ap_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: -</P> -<PRE> -int my_handler(request_rec *r) -{ - struct my_structure *foo; - ... - - foo = (foo *)ap_palloc (r->pool, sizeof(my_structure)); -} -</PRE> -<P> -Note that <EM>there is no <CODE>ap_pfree</CODE></EM> --- -<CODE>ap_palloc</CODE>ed memory is freed only when the associated -resource pool is cleared. This means that <CODE>ap_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> -<P> -(It also raises the possibility that heavy use of <CODE>ap_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). -</P> -<H3>Allocating initialized memory</H3> -<P> -There are functions which allocate initialized memory, and are -frequently useful. The function <CODE>ap_pcalloc</CODE> has the same -interface as <CODE>ap_palloc</CODE>, but clears out the memory it -allocates before it returns it. The function <CODE>ap_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>ap_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: -</P> -<PRE> - ap_pstrcat (r->pool, "foo", "/", "bar", NULL); -</PRE> -<P> -returns a pointer to 8 bytes worth of memory, initialized to -<CODE>"foo/bar"</CODE>. -</P> -<H3><A NAME="pools-used">Commonly-used pools in the Apache Web server</A></H3> -<P> -A pool is really defined by its lifetime more than anything else. There -are some static pools in http_main which are passed to various -non-http_main functions as arguments at opportune times. Here they are: -</P> -<DL COMPACT> - <DT>permanent_pool - </DT> - <DD> - <UL> - <LI>never passed to anything else, this is the ancestor of all pools - </LI> - </UL> - </DD> - <DT>pconf - </DT> - <DD> - <UL> - <LI>subpool of permanent_pool - </LI> - <LI>created at the beginning of a config "cycle"; exists until the - server is terminated or restarts; passed to all config-time - routines, either via cmd->pool, or as the "pool *p" argument on - those which don't take pools - </LI> - <LI>passed to the module init() functions - </LI> - </UL> - </DD> - <DT>ptemp - </DT> - <DD> - <UL> - <LI>sorry I lie, this pool isn't called this currently in 1.3, I - renamed it this in my pthreads development. I'm referring to - the use of ptrans in the parent... contrast this with the later - definition of ptrans in the child. - </LI> - <LI>subpool of permanent_pool - </LI> - <LI>created at the beginning of a config "cycle"; exists until the - end of config parsing; passed to config-time routines <EM>via</EM> - cmd->temp_pool. Somewhat of a "bastard child" because it isn't - available everywhere. Used for temporary scratch space which - may be needed by some config routines but which is deleted at - the end of config. - </LI> - </UL> - </DD> - <DT>pchild - </DT> - <DD> - <UL> - <LI>subpool of permanent_pool - </LI> - <LI>created when a child is spawned (or a thread is created); lives - until that child (thread) is destroyed - </LI> - <LI>passed to the module child_init functions - </LI> - <LI>destruction happens right after the child_exit functions are - called... (which may explain why I think child_exit is redundant - and unneeded) - </LI> - </UL> - </DD> - <DT>ptrans - <DT> - <DD> - <UL> - <LI>should be a subpool of pchild, but currently is a subpool of - permanent_pool, see above - </LI> - <LI>cleared by the child before going into the accept() loop to receive - a connection - </LI> - <LI>used as connection->pool - </LI> - </UL> - </DD> - <DT>r->pool - </DT> - <DD> - <UL> - <LI>for the main request this is a subpool of connection->pool; for - subrequests it is a subpool of the parent request's pool. - </LI> - <LI>exists until the end of the request (<EM>i.e.</EM>, destroy_sub_req, or - in child_main after process_request has finished) - </LI> - <LI>note that r itself is allocated from r->pool; <EM>i.e.</EM>, - r->pool is - first created and then r is the first thing palloc()d from it - </LI> - </UL> - </DD> -</DL> -<P> -For almost everything folks do, r->pool is the pool to use. But you -can see how other lifetimes, such as pchild, are useful to some -modules... such as modules that need to open a database connection once -per child, and wish to clean it up when the child dies. -</P> -<P> -You can also see how some bugs have manifested themself, such as setting -connection->user to a value from r->pool -- in this case -connection exists -for the lifetime of ptrans, which is longer than r->pool (especially if -r->pool is a subrequest!). So the correct thing to do is to allocate -from connection->pool. -</P> -<P> -And there was another interesting bug in mod_include/mod_cgi. You'll see -in those that they do this test to decide if they should use r->pool -or r->main->pool. In this case the resource that they are registering -for cleanup is a child process. If it were registered in r->pool, -then the code would wait() for the child when the subrequest finishes. -With mod_include this could be any old #include, and the delay can be up -to 3 seconds... and happened quite frequently. Instead the subprocess -is registered in r->main->pool which causes it to be cleaned up when -the entire request is done -- <EM>i.e.</EM>, after the output has been sent to -the client and logging has happened. -</P> -<H3><A NAME="pool-files">Tracking open files, etc.</A></H3> -<P> -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>ap_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>, <EM>e.g.</EM>, -</P> -<PRE> - ... - FILE *f = ap_pfopen (r->pool, r->filename, "r"); - - if (f == NULL) { ... } else { ... } -</PRE> -<P> -There is also a <CODE>ap_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> -<P> -Unlike the case for memory, there <EM>are</EM> functions to close -files allocated with <CODE>ap_pfopen</CODE>, and <CODE>ap_popenf</CODE>, -namely <CODE>ap_pfclose</CODE> and <CODE>ap_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>ap_pfopen</CODE> and -<CODE>ap_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> -<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). -</P> -<H3>Other sorts of resources --- cleanup functions</H3> -<BLOCKQUOTE> -More text goes here. Describe the the cleanup primitives in terms of -which the file stuff is implemented; also, <CODE>spawn_process</CODE>. -</BLOCKQUOTE> -<P> -Pool cleanups live until clear_pool() is called: clear_pool(a) recursively -calls destroy_pool() on all subpools of a; then calls all the cleanups for a; -then releases all the memory for a. destroy_pool(a) calls clear_pool(a) -and then releases the pool structure itself. i.e. clear_pool(a) doesn't -delete a, it just frees up all the resources and you can start using it -again immediately. -</P> -<H3>Fine control --- creating and dealing with sub-pools, with a note -on sub-requests</H3> - -On rare occasions, too-free use of <CODE>ap_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>ap_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>ap_clear_pool</CODE> and <CODE>ap_destroy_pool</CODE>, respectively. -(The difference is that <CODE>ap_clear_pool</CODE> frees resources -associated with the pool, while <CODE>ap_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>ap_sub_req_lookup_...</CODE> functions) -is <CODE>ap_destroy_sub_req</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>ap_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>ap_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 *) ap_palloc (p, sizeof(mime_dir_config)); - - new->forced_types = ap_make_table (p, 4); - new->encoding_types = ap_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 *)ap_palloc (p, sizeof(mime_dir_config)); - - new->forced_types = ap_overlay_tables (p, subdir->forced_types, - parent_dir->forced_types); - new->encoding_types = ap_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; - ap_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>ap_get_module_config</CODE> function. - -<PRE> -int find_ct(request_rec *r) -{ - int i; - char *fn = ap_pstrdup (r->pool, r->filename); - mime_dir_config *conf = (mime_dir_config *) - ap_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=ap_rind(fn,'.')) < 0) return DECLINED; - ++i; - - if ((type = ap_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=ap_rind(fn,'.')) < 0) return OK; - ++i; - } - - if ((type = ap_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, <EM>etc</EM>.</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 *) - ap_get_module_config(s->module_config,&alias_module); - alias_entry *new = ap_push_array (conf->redirects); - - if (!ap_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/dso.html.en b/docs/manual/dso.html.en deleted file mode 100644 index 0d79f7ee67..0000000000 --- a/docs/manual/dso.html.en +++ /dev/null @@ -1,384 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML><HEAD> -<TITLE>Apache 1.3 Dynamic Shared Object (DSO) support</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<BLOCKQUOTE> -<!--#include virtual="header.html" --> - -<DIV ALIGN=CENTER> - -<H1> -Apache 1.3<BR> -Dynamic Shared Object (DSO)<BR> -Support -</H1> - -<ADDRESS>Originally written by<BR> -Ralf S. Engelschall <rse@apache.org>, April 1998</ADDRESS> - -</DIV> - -<H3>Background</H3> - -<P>On modern Unix derivatives there exists a nifty mechanism usually called -dynamic linking/loading of <EM>Dynamic Shared Objects</EM> (DSO) which -provides a way to build a piece of program code in a special format for -loading it at run-time into the address space of an executable program. - -<P>This loading can usually be done in two ways: Automatically by a system -program called <CODE>ld.so</CODE> when an executable program is started or -manually from within the executing program via a programmatic system interface -to the Unix loader through the system calls <CODE>dlopen()/dlsym()</CODE>. - -<P>In the first way the DSO's are usually called <EM>shared libraries</EM> or -<EM>DSO libraries</EM> and named <CODE>libfoo.so</CODE> or -<CODE>libfoo.so.1.2</CODE>. They reside in a system directory (usually -<CODE>/usr/lib</CODE>) and the link to the executable program is established -at build-time by specifying <CODE>-lfoo</CODE> to the linker command. This -hard-codes library references into the executable program file so that at -start-time the Unix loader is able to locate <CODE>libfoo.so</CODE> in -<CODE>/usr/lib</CODE>, in paths hard-coded via linker-options like -<CODE>-R</CODE> or in paths configured via the environment variable -<CODE>LD_LIBRARY_PATH</CODE>. It then resolves any (yet unresolved) symbols in -the executable program which are available in the DSO. - -<P>Symbols in the executable program are usually not referenced by the DSO -(because it's a reusable library of general code) and hence no further -resolving has to be done. The executable program has no need to do anything on -its own to use the symbols from the DSO because the complete resolving is done -by the Unix loader. (In fact, the code to invoke <CODE>ld.so</CODE> is part of -the run-time startup code which is linked into every executable program which -has been bound non-static). The advantage of dynamic loading of common library -code is obvious: the library code needs to be stored only once, in a system -library like <CODE>libc.so</CODE>, saving disk space for every program. - -<P>In the second way the DSO's are usually called <EM>shared objects</EM> or -<EM>DSO files</EM> and can be named with an arbitrary extension (although the -canonical name is <CODE>foo.so</CODE>). These files usually stay inside a -program-specific directory and there is no automatically established link to -the executable program where they are used. Instead the executable program -manually loads the DSO at run-time into its address space via -<CODE>dlopen()</CODE>. At this time no resolving of symbols from the DSO for -the executable program is done. But instead the Unix loader automatically -resolves any (yet unresolved) symbols in the DSO from the set of symbols -exported by the executable program and its already loaded DSO libraries -(especially all symbols from the ubiquitous <CODE>libc.so</CODE>). This way -the DSO gets knowledge of the executable program's symbol set as if it had -been statically linked with it in the first place. - -<P>Finally, to take advantage of the DSO's API the executable program has to -resolve particular symbols from the DSO via <CODE>dlsym()</CODE> for later use -inside dispatch tables etc. In other words: The executable program has to -manually resolve every symbol it needs to be able to use it. The advantage of -such a mechanism is that optional program parts need not be loaded (and thus -do not spend memory) until they are needed by the program in question. When -required, these program parts can be loaded dynamically to extend the base -program's functionality. - -<P>Although this DSO mechanism sounds straightforward there is at least one -difficult step here: The resolving of symbols from the executable program for -the DSO when using a DSO to extend a program (the second way). Why? Because -"reverse resolving" DSO symbols from the executable program's symbol set is -against the library design (where the library has no knowledge about the -programs it is used by) and is neither available under all platforms nor -standardized. In practice the executable program's global symbols are often -not re-exported and thus not available for use in a DSO. Finding a way to -force the linker to export all global symbols is the main problem one has to -solve when using DSO for extending a program at run-time. - -<H3>Practical Usage</H3> - -<P>The shared library approach is the typical one, because it is what the DSO -mechanism was designed for, hence it is used for nearly all types of libraries -the operating system provides. On the other hand using shared objects for -extending a program is not used by a lot of programs. - -<P>As of 1998 there are only a few software packages available which use the -DSO mechanism to actually extend their functionality at run-time: Perl 5 (via -its XS mechanism and the DynaLoader module), Netscape Server, etc. Starting -with version 1.3, Apache joined the crew, because Apache already uses a module -concept to extend its functionality and internally uses a dispatch-list-based -approach to link external modules into the Apache core functionality. So, -Apache is really predestined for using DSO to load its modules at run-time. - -<P>As of Apache 1.3, the configuration system supports two optional features -for taking advantage of the modular DSO approach: compilation of the Apache -core program into a DSO library for shared usage and compilation of the -Apache modules into DSO files for explicit loading at run-time. - -<H3>Implementation</H3> - -<P>The DSO support for loading individual Apache modules is based on a module -named <A HREF="mod/mod_so.html"><CODE>mod_so.c</CODE></A> which has to be -statically compiled into the Apache core. It is the only module besides -<CODE>http_core.c</CODE> which cannot be put into a DSO itself -(bootstrapping!). Practically all other distributed Apache modules then can -then be placed into a DSO by individually enabling the DSO build for them via -<CODE>configure</CODE>'s <CODE>--enable-shared</CODE> option (see top-level -<CODE>INSTALL</CODE> file) or by changing the <CODE>AddModule</CODE> command -in your <CODE>src/Configuration</CODE> into a <CODE>SharedModule</CODE> -command (see <CODE>src/INSTALL</CODE> file). After a module is compiled into -a DSO named <CODE>mod_foo.so</CODE> you can use <A -HREF="mod/mod_so.html"><CODE>mod_so</CODE></A>'s <A -HREF="mod/mod_so.html#loadmodule"><CODE>LoadModule</CODE></A> command in your -<CODE>httpd.conf</CODE> file to load this module at server startup or restart. - -<P>To simplify this creation of DSO files for Apache modules (especially for -third-party modules) a new support program named <CODE>apxs</CODE> (<EM>APache -eXtenSion</EM>) is available. It can be used to build DSO based modules -<EM>outside of</EM> the Apache source tree. The idea is simple: When -installing Apache the <CODE>configure</CODE>'s <CODE>make install</CODE> -procedure installs the Apache C header files and puts the platform-dependent -compiler and linker flags for building DSO files into the <CODE>apxs</CODE> -program. This way the user can use <CODE>apxs</CODE> to compile his Apache -module sources without the Apache distribution source tree and without having -to fiddle with the platform-dependent compiler and linker flags for DSO -support. - -<P>To place the complete Apache core program into a DSO library (only required -on some of the supported platforms to force the linker to export the apache -core symbols -- a prerequisite for the DSO modularization) the rule -<CODE>SHARED_CORE</CODE> has to be enabled via <CODE>configure</CODE>'s -<CODE>--enable-rule=SHARED_CORE</CODE> option (see top-level -<CODE>INSTALL</CODE> file) or by changing the <CODE>Rule</CODE> command in -your <CODE>Configuration</CODE> file to <CODE>Rule SHARED_CORE=yes</CODE> (see -<CODE>src/INSTALL</CODE> file). The Apache core code is then placed into a DSO -library named <CODE>libhttpd.so</CODE>. Because one cannot link a DSO against -static libraries on all platforms, an additional executable program named -<CODE>libhttpd.ep</CODE> is created which both binds this static code and -provides a stub for the <CODE>main()</CODE> function. Finally the -<CODE>httpd</CODE> executable program itself is replaced by a bootstrapping -code which automatically makes sure the Unix loader is able to load and start -<CODE>libhttpd.ep</CODE> by providing the <CODE>LD_LIBRARY_PATH</CODE> to -<CODE>libhttpd.so</CODE>. - -<H3>Supported Platforms</H3> - -<P>Apache's <CODE>src/Configure</CODE> script currently has only limited but -adequate built-in knowledge on how to compile DSO files, because as already -mentioned this is heavily platform-dependent. Nevertheless all major Unix -platforms are supported. The definitive current state (May 1998) is this: - -<P> -<UL> -<LI>Out-of-the-box supported platforms:<BR> -(actually tested versions in parenthesis) - -<PRE> -o FreeBSD (2.1.5, 2.2.5, 2.2.6) -o OpenBSD (2.x) -o NetBSD (1.3.1) -o Linux (Debian/1.3.1, RedHat/4.2) -o Solaris (2.4, 2.5.1, 2.6) -o SunOS (4.1.3) -o OSF1 (4.0) -o IRIX (6.2) -o HP/UX (10.20) -o UnixWare (2.01, 2.1.2) -o AIX (3.2, 4.1.5, 4.2, 4.3) -o ReliantUNIX/SINIX (5.43) -o SVR4 (-) -</PRE> - -<P> -<LI> Explicitly unsupported platforms: - -<PRE> -o Ultrix (no dlopen-style interface under this platform) -</PRE> - -</UL> - -<H3>Usage Summary</H3> - -<P>To give you an overview of the DSO features of Apache 1.3, here is a short -and concise summary: - -<OL> - -<LI>Placing the Apache core code (all the stuff which usually forms the -<CODE>httpd</CODE> binary) into a DSO <CODE>libhttpd.so</CODE>, an executable -program <CODE>libhttpd.ep</CODE> and a bootstrapping executable program -<CODE>httpd</CODE> (Notice: this is only required on some of the supported -platforms to force the linker to export the Apache core symbols, which in turn -is a prerequisite for the DSO modularization): - -<P> -<UL> -<LI>Build and install via <CODE>configure</CODE> (preferred): -<TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> -<PRE> -$ ./configure --prefix=/path/to/install - --enable-rule=SHARED_CORE ... -$ make install -</PRE> -</TD></TR></TABLE> - -<LI>Build and install manually: -<TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> -<PRE> -- Edit src/Configuration: - << Rule SHARED_CORE=default - >> Rule SHARED_CORE=yes - << EXTRA_CFLAGS= - >> EXTRA_CFLAGS= -DSHARED_CORE_DIR=\"/path/to/install/libexec\" -$ make -$ cp src/libhttpd.so* /path/to/install/libexec/ -$ cp src/libhttpd.ep /path/to/install/libexec/ -$ cp src/httpd /path/to/install/bin/ -</PRE> -</TD></TR></TABLE> -</UL> - -<LI>Build and install a <EM>distributed</EM> Apache module, say -<CODE>mod_foo.c</CODE>, into its own DSO <CODE>mod_foo.so</CODE>: - -<P> -<UL> -<LI>Build and install via <CODE>configure</CODE> (preferred): -<TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> -<PRE> -$ ./configure --prefix=/path/to/install - --enable-shared=foo -$ make install -</PRE> -</TD></TR></TABLE> - -<LI>Build and install manually: -<TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> -<PRE> -- Edit src/Configuration: - << AddModule modules/xxxx/mod_foo.o - >> SharedModule modules/xxxx/mod_foo.so -$ make -$ cp src/xxxx/mod_foo.so /path/to/install/libexec -- Edit /path/to/install/etc/httpd.conf - >> LoadModule foo_module /path/to/install/libexec/mod_foo.so -</PRE> -</TD></TR></TABLE> -</UL> - -<LI>Build and install a <EM>third-party</EM> Apache module, say -<CODE>mod_foo.c</CODE>, into its own DSO <CODE>mod_foo.so</CODE> - -<P> -<UL> -<LI>Build and install via <CODE>configure</CODE> (preferred): -<TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> -<PRE> -$ ./configure --add-module=/path/to/3rdparty/mod_foo.c - --enable-shared=foo -$ make install -</PRE> -</TD></TR></TABLE> - -<LI>Build and install manually: -<TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> -<PRE> -$ cp /path/to/3rdparty/mod_foo.c /path/to/apache-1.3/src/modules/extra/ -- Edit src/Configuration: - >> SharedModule modules/extra/mod_foo.so -$ make -$ cp src/xxxx/mod_foo.so /path/to/install/libexec -- Edit /path/to/install/etc/httpd.conf - >> LoadModule foo_module /path/to/install/libexec/mod_foo.so -</PRE> -</TD></TR></TABLE> -</UL> - -<P> -<LI>Build and install a <EM>third-party</EM> Apache module, say -<CODE>mod_foo.c</CODE>, into its own DSO <CODE>mod_foo.so</CODE> <EM>outside -of</EM> the Apache source tree: - -<P> -<UL> -<LI>Build and install via <CODE>apxs</CODE>: -<TABLE BGCOLOR="#f0f0f0" CELLPADDING=10><TR><TD> -<PRE> -$ cd /path/to/3rdparty -$ apxs -c mod_foo.c -$ apxs -i -a -n foo mod_foo.so -</PRE> -</TD></TR></TABLE> -</UL> - -</OL> - -<H3>Advantages & Disadvantages</H3> - -<P>The above DSO based features of Apache 1.3 have the following advantages: - -<UL> -<LI> The server package is more flexible at run-time because the actual server - process can be assembled at run-time via <A - HREF="mod/mod_so.html#loadmodule"><CODE>LoadModule</CODE></A> - <CODE>httpd.conf</CODE> configuration commands instead of - <CODE>Configuration</CODE> <CODE>AddModule</CODE> commands at build-time. - For instance this way one is able to run different server instances - (standard & SSL version, minimalistic & powered up version - [mod_perl, PHP3], etc.) with only one Apache installation. -<P> -<LI> The server package can be easily extended with third-party modules even - after installation. This is at least a great benefit for vendor package - maintainers who can create a Apache core package and additional packages - containing extensions like PHP3, mod_perl, mod_fastcgi, etc. -<P> -<LI> Easier Apache module prototyping because with the DSO/<CODE>apxs</CODE> - pair you can both work outside the Apache source tree and only need an - <CODE>apxs -i</CODE> command followed by an <CODE>apachectl - restart</CODE> to bring a new version of your currently developed module - into the running Apache server. -</UL> - -<P>DSO has the following disadvantages: - -<UL> -<LI> The DSO mechanism cannot be used on every platform because not all - operating systems support dynamic loading of code into the address space - of a program. -<P> -<LI> The server is approximately 20% slower at startup time because of the - symbol resolving overhead the Unix loader now has to do. -<P> -<LI> The server is approximately 5% slower at execution time under some - platforms because position independent code (PIC) sometimes needs - complicated assembler tricks for relative addressing which are not - necessarily as fast as absolute addressing. -<P> -<LI> Because DSO modules cannot be linked against other DSO-based libraries - (<CODE>ld -lfoo</CODE>) on all platforms (for instance a.out-based - platforms usually don't provide this functionality while ELF-based - platforms do) you cannot use the DSO mechanism for all types of modules. - Or in other words, modules compiled as DSO files are restricted to only - use symbols from the Apache core, from the C library (<CODE>libc</CODE>) - and all other dynamic or static libraries used by the Apache core, or - from static library archives (<CODE>libfoo.a</CODE>) containing position - independent code. The only chance to use other code is to either make - sure the Apache core itself already contains a reference to it or loading - the code yourself via <CODE>dlopen()</CODE>. -<P> -<LI> Under some platforms (many SVR4 systems) there is no way to force the - linker to export all global symbols for use in DSO's when linking the - Apache httpd executable program. But without the visibility of the Apache - core symbols no standard Apache module could be used as a DSO. The only - chance here is to use the <CODE>SHARED_CORE</CODE> feature because this - way the global symbols are forced to be exported. As a consequence the - Apache <CODE>src/Configure</CODE> script automatically enforces - <CODE>SHARED_CORE</CODE> on these platforms when DSO features are used in - the <CODE>Configuration</CODE> file or on the configure command line. -</UL> - -<!--#include virtual="footer.html" --> -</BLOCKQUOTE> -</BODY> -</HTML> diff --git a/docs/manual/handler.html.en b/docs/manual/handler.html.en deleted file mode 100644 index 84cd97c06b..0000000000 --- a/docs/manual/handler.html.en +++ /dev/null @@ -1,167 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache's Handler Use</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Apache's Handler Use</H1> - -<H2>What is a Handler</H2> - -<P>A "handler" is an internal Apache representation of the action to be -performed when a file is called. Generally, files have implicit -handlers, based on the file type. Normally, all files are simply -served by the server, but certain file typed are "handled" -separately. For example, you may use a type of -"application/x-httpd-cgi" to invoke CGI scripts.</P> - -<P>Apache 1.1 adds the additional ability to use handlers -explicitly. Either based on filename extensions or on location, these -handlers are unrelated to file type. This is advantageous both because -it is a more elegant solution, but it also allows for both a type -<STRONG>and</STRONG> a handler to be associated with a file.</P> - -<P>Handlers can either be built into the server or to a module, or -they can be added with the <A -HREF="mod/mod_actions.html#action">Action</A> directive. The built-in -handlers in the standard distribution are as follows:</P> - -<UL> -<LI><STRONG>send-as-is</STRONG>: - Send file with HTTP headers as is. - (<A HREF="mod/mod_asis.html">mod_asis</A>) -<LI><STRONG>cgi-script</STRONG>: - Treat the file as a CGI script. - (<A HREF="mod/mod_cgi.html">mod_cgi</A>) -<LI><STRONG>imap-file</STRONG>: - Imagemap rule file. - (<A HREF="mod/mod_imap.html">mod_imap</A>) -<LI><STRONG>server-info</STRONG>: - Get the server's configuration information - (<A HREF="mod/mod_info.html">mod_info</A>) -<LI><STRONG>server-parsed</STRONG>: - Parse for server-side includes - (<A HREF="mod/mod_include.html">mod_include</A>) -<LI><STRONG>server-status</STRONG>: - Get the server's status report - (<A HREF="mod/mod_status.html">mod_status</A>) -<LI><STRONG>type-map</STRONG>: - Parse as a type map file for content negotiation - (<A HREF="mod/mod_negotiation.html">mod_negotiation</A>) -</UL> - -<P> - -<H2>Directives</H2> -<UL> -<LI><A HREF="#addhandler">AddHandler</A> -<LI><A HREF="#sethandler">SetHandler</A> -</UL> - -<HR> - -<H2><A NAME="addhandler">AddHandler</A></H2> - -<A - HREF="mod/directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> <AddHandler <EM>handler-name - extension</EM>><BR> -<A - HREF="mod/directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="mod/directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="mod/directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> 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> - -<A - HREF="mod/directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> <SetHandler <EM>handler-name</EM>><BR> -<A - HREF="mod/directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="mod/directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="mod/directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_mime - -<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 ad532557e1..0000000000 --- a/docs/manual/install.html.en +++ /dev/null @@ -1,262 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Compiling and Installing Apache</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Compiling and Installing Apache 1.3</H1> - -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 -<STRONG>modules</STRONG> 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 AddModule lines - at the bottom of the file), or add new lines corresponding to - additional modules you have downloaded or written. (See <A - HREF="misc/API.html">API.html</A> for preliminary docs on how to - 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, LDFLAGS, 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> * - + Adding selected modules - + doing sanity check on compiler and options - Creating Makefile in support - Creating Makefile in main - Creating Makefile in os/unix - Creating Makefile in modules/standard - </PRE> - </BLOCKQUOTE> - - (*: 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/" - >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. In either case you should -read the <A HREF="misc/security_tips.html#serverroot">security tips</A> -describing how to set the permissions on the server root directory.<P> - -The next step is to edit the configuration files for the server. This -consists of setting up various <STRONG>directives</STRONG> in up to three -central configuration files. By default, these files are located in -the <CODE>conf</CODE> directory and are called <CODE>srm.conf</CODE>, -<CODE>access.conf</CODE> and <CODE>httpd.conf</CODE>. To help you get -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>Set your system time properly!</H3> - -Proper operation of a public web server requires accurate time -keeping, since elements of the HTTP protocol are expressed as the time -of day. So, it's time to investigate setting up NTP or some other -time synchronization system on your Unix box, or whatever the -equivalent on NT would be. - -<H3>Starting and Stopping the Server</H3> - -To start the server, simply run <CODE>httpd</CODE>. This will look for -<CODE>httpd.conf</CODE> in the location compiled into the code (by -default <CODE>/usr/local/apache/conf/httpd.conf</CODE>). If -this file is somewhere else, you can give the real -location with the -f argument. For example: - -<PRE> - /usr/local/apache/httpd -f /usr/local/apache/conf/httpd.conf -</PRE> - -If all goes well this will return to the command prompt almost -immediately. This indicates that the server is now up and running. If -anything goes wrong during the initialization of the server you will -see an error message on the screen. - -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 -<EM>child</EM> processes to handle the requests. If you started Apache -as the root user, the parent process will continue to run as root -while the children will change to the user as given in the httpd.conf -file. - -<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.<EM>N</EM></CODE> directory). This will start Apache as root. -Before doing this ensure that your server is properly configured -for security and access restrictions. - -<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/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 df0a4d0445..0000000000 --- a/docs/manual/invoking.html.en +++ /dev/null @@ -1,137 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Starting Apache</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Starting Apache</H1> - -<H2>Invoking Apache</H2> -The <CODE>httpd</CODE> program is usually run as a daemon which executes -continuously, handling requests. It is possible to invoke Apache by -the Internet daemon <CODE>inetd</CODE> each time a connection to the HTTP -service is made (use the -<A HREF="mod/core.html#servertype">ServerType</A> directive) -but this is not recommended. - -<H2>Command line options</H2> -The following options are recognized on the httpd command line: -<DL> -<DT><CODE>-d</CODE> <EM>serverroot</EM> -<DD>Set the initial value for the -<A HREF="mod/core.html#serverroot">ServerRoot</A> variable to -<EM>serverroot</EM>. This can be overridden by the ServerRoot command in the -configuration file. The default is <CODE>/usr/local/apache</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 its build date, and then exit. - -<DT><A NAME="version"><CODE>-V</CODE></A> -<DD>Print the base version of httpd, its sub-version if defined, its -build date, and a list of compile time settings which influence the -behavior and performance of the apache server (<EM>e.g.</EM>, -<SAMP>-DUSE_MMAP_FILES</SAMP>), -then exit. - -<DT><A NAME="help"><CODE>-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>-S</CODE> -<DD>Show the settings as parsed from the config file (currently only -shows a breakdown of the vhost settings). - -<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_config.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/mod/directive-dict.html.en b/docs/manual/mod/directive-dict.html.en deleted file mode 100644 index a4c13e55f5..0000000000 --- a/docs/manual/mod/directive-dict.html.en +++ /dev/null @@ -1,262 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>Definitions of terms used to describe Apache directives - </TITLE> - </HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> - <BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" - > -<!--#include virtual="header.html" --> - <H1 ALIGN="CENTER">Terms Used to Describe Apache Directives</H1> - - <P> - Each Apache configuration directive is described using a common format - that looks like this: - </P> - <DL> - <DD><A - HREF="#Syntax" - REL="Help" - ><STRONG>Syntax:</STRONG></A> <EM>directive-name</EM> <EM>some args</EM> - <BR> - <A - HREF="#Default" - REL="Help" - ><STRONG>Default:</STRONG></A> - <SAMP><EM>directive-name default-value</EM></SAMP> - <BR> - <A - HREF="#Context" - REL="Help" - ><STRONG>Context:</STRONG></A> <EM>context-list</EM> - <BR> - <A - HREF="#Override" - REL="Help" - ><STRONG>Override:</STRONG></A> <EM>override</EM> - <BR> - <A - HREF="#Status" - REL="Help" - ><STRONG>Status:</STRONG></A> <EM>status</EM> - <BR> - <A - HREF="#Module" - REL="Help" - ><STRONG>Module:</STRONG></A> <EM>module-name</EM> - <BR> - <A - HREF="#Compatibility" - REL="Help" - ><STRONG>Compatibility:</STRONG></A> <EM>compatibility notes</EM> - </DD> - </DL> - <P> - Each of the directive's attributes, complete with possible values - where possible, are described in this document. - </P> - - <H2>Directive Terms</H2> - <UL> - <LI><A HREF="#Syntax">Syntax</A> - </LI> - <LI><A HREF="#Default">Default</A> - </LI> - <LI><A HREF="#Context">Context</A> - </LI> - <LI><A HREF="#Override">Override</A> - </LI> - <LI><A HREF="#Status">Status</A> - </LI> - <LI><A HREF="#Module">Module</A> - </LI> - <LI><A HREF="#Compatibility">Compatibility</A> - </LI> - </UL> - - <HR> - <H2><A NAME="Syntax">Syntax</A></H2> - <P> - This indicates the format of the directive as it would appear in a - configuration file. This syntax is extremely directive-specific, so - refer to the text of the directive's description for details. - </P> - - <HR> - <H2><A NAME="Default">Default</A></H2> - <P> - If the directive has a default value (<EM>i.e.</EM>, if you omit it - from your configuration entirely, the Apache Web server will behave as - though you set it to a particular value), it is described here. If - there is no default value, this section should say - "<EM>None</EM>". - </P> - - <HR> - <H2><A NAME="Context">Context</A></H2> - <P> - This indicates where in the server's configuration files the directive - is legal. It's a comma-separated list of one or more of the following - values: - </P> - <DL> - <DT><STRONG>server config</STRONG> - </DT> - <DD>This means that the directive may be used in the server - configuration files (<EM>e.g.</EM>, <SAMP>httpd.conf</SAMP>, - <SAMP>srm.conf</SAMP>, and <SAMP>access.conf</SAMP>), but - <STRONG>not</STRONG> within any <SAMP><VirtualHost></SAMP> or - <Directory> containers. It is not allowed in - <SAMP>.htaccess</SAMP> files at all. - <P> - </P> - </DD> - <DT><STRONG>virtual host</STRONG> - </DT> - <DD>This context means that the directive may appear inside - <SAMP><VirtualHost></SAMP> containers in the server - configuration files. - <P> - </P> - </DD> - <DT><STRONG>directory</STRONG> - </DT> - <DD>A directive marked as being valid in this context may be used - inside <SAMP><Directory></SAMP> containers in the server - configuration files. - <P> - </P> - </DD> - <DT><STRONG>.htaccess</STRONG> - </DT> - <DD>If a directive is valid in this context, it means that it can - appear inside <EM>per</EM>-directory <SAMP>.htaccess</SAMP> files. - It may not be processed, though depending upon the - <A - HREF="#Override" - REL="Help" - >overrides</A> - currently active. - <P> - </P> - </DD> - </DL> - <P> - The directive is <EM>only</EM> allowed within the designated context; - if you try to use it elsewhere, you'll get a configuration error that - will either prevent the server from handling requests in that context - correctly, or will keep the server from operating at all -- - <EM>i.e.</EM>, the server won't even start. - </P> - <P> - The valid locations for the directive are actually the result of a - Boolean OR of all of the listed contexts. In other words, a directive - that is marked as being valid in "<SAMP>server config, - .htaccess</SAMP>" can be used in the <SAMP>httpd.conf</SAMP> file - and in <SAMP>.htaccess</SAMP> files, but not within any - <Directory> or <VirtualHost> containers. - </P> - - <HR> - <H2><A NAME="Override">Override</A></H2> - <P> - This directive attribute indicates which configuration override must - be active in order for the directive to be processed when it appears - in a <SAMP>.htaccess</SAMP> file. If the directive's - <A - HREF="#Context" - REL="Help" - >context</A> - doesn't permit it to appear in <SAMP>.htaccess</SAMP> files, this - attribute should say "<EM>Not applicable</EM>". - </P> - <P> - Overrides are activated by the - <A - HREF="core.html#allowoverride" - REL="Help" - ><SAMP>AllowOverride</SAMP></A> - directive, and apply to a particular scope (such as a directory) and - all descendants, unless further modified by other - <SAMP>AllowOverride</SAMP> directives at lower levels. The - documentation for that directive also lists the possible override - names available. - </P> - - <HR> - <H2><A NAME="Status">Status</A></H2> - <P> - This indicates how tightly bound into the Apache Web server the - directive is; in other words, you may need to recompile the server - with an enhanced set of modules in order to gain access to the - directive and its functionality. Possible values for this attribute - are: - </P> - <DL> - <DT><STRONG>Core</STRONG> - </DT> - <DD>If a directive is listed as having "Core" status, that - means it is part of the innermost portions of the Apache Web server, - and is always available. - <P> - </P> - </DD> - <DT><STRONG>Base</STRONG> - </DT> - <DD>A directive labeled as having "Base" status is - supported by one of the standard Apache modules which is compiled - into the server by default, and is therefore normally available - unless you've taken steps to remove the module from your configuration. - <P> - </P> - </DD> - <DT><STRONG>Extension</STRONG> - </DT> - <DD>A directive with "Extension" status is provided by one - of the modules included with the Apache server kit, but the module - isn't normally compiled into the server. To enable the directive - and its functionality, you will need to change the server build - configuration files and re-compile Apache. - <P> - </P> - </DD> - <DT><STRONG>Experimental</STRONG> - </DT> - <DD>"Experimental" status indicates that the directive is - available as part of the Apache kit, but you're on your own if you - try to use it. The directive is being documented for completeness, - and is not necessarily supported. The module which provides the - directive may or may not be compiled in by default; check the top of - the page which describes the directive and its module to see if it - remarks on the availability. - <P> - </P> - </DD> - </DL> - - <HR> - <H2><A NAME="Module">Module</A></H2> - <P> - This quite simply lists the name of the source module which defines - the directive. - </P> - - <HR> - <H2><A NAME="Compatibility">Compatibility</A></H2> - <P> - If the directive wasn't part of the original Apache version 1 - distribution, the version in which it was introduced should be listed - here. If the directive has the same name as one from the NCSA HTTPd - server, any inconsistencies in behaviour between the two should also - be mentioned. Otherwise, this attribute should say "<EM>No - compatibility issues.</EM>" - </P> -<!--#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 4d60f4b887..0000000000 --- a/docs/manual/platform/perf-bsd44.html +++ /dev/null @@ -1,238 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Running a High-Performance Web Server for BSD</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<A NAME="initial"> -<!--#include virtual="header.html" --> -</A> -<H1 ALIGN="CENTER">Running a High-Performance Web Server for BSD</H1> - -Like other OS's, the listen queue is often the <STRONG>first limit -hit</STRONG>. 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"> -<STRONG>Addendum for <EM>very</EM> heavily loaded BSD servers</STRONG><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 <EM>lot</EM> 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 -<EM>/usr/src/sys/conf/param.c</EM>. -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> - -<STRONG>Caveats</STRONG> - -<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. -<STRONG>ALWAYS</STRONG> -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 <STRONG>HARD_SERVER_LIMIT</STRONG> in <EM>httpd.h</EM> 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 <EM>Tony Sanders</EM> and <EM>Chris Torek</EM> 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-pointer -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:apache@apache.org">apache@apache.org</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 32245e0fbc..0000000000 --- a/docs/manual/platform/perf-dec.html +++ /dev/null @@ -1,283 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Performance Tuning Tips for Digital Unix</TITLE> -</HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Performance Tuning Tips for Digital Unix</H1> - -Below is a set of newsgroup posts made by an engineer from DEC in -response to queries about how to modify DEC's Digital Unix OS for more -heavily loaded web sites. Copied with permission. - -<HR> - -<H2>Update</H2> -From: Jeffrey Mogul <mogul@pa.dec.com><BR> -Date: Fri, 28 Jun 96 16:07:56 MDT<BR> - -<OL> -<LI> The advice given in the README file regarding the - "tcbhashsize" variable is incorrect. The largest value - this should be set to is 1024. Setting it any higher - will have the perverse result of disabling the hashing - mechanism. - -<LI>Patch ID OSF350-146 has been superseded by -<BLOCKQUOTE> - Patch ID OSF350-195 for V3.2C<BR> - Patch ID OSF360-350195 for V3.2D -</BLOCKQUOTE> - Patch IDs for V3.2E and V3.2F should be available soon. - There is no known reason why the Patch ID OSF360-350195 - won't work on these releases, but such use is not officially - supported by Digital. This patch kit will not be needed for - V3.2G when it is released. -</OL> -<HR> - - -<PRE> -From mogul@pa.dec.com (Jeffrey Mogul) -Organization DEC Western Research -Date 30 May 1996 00:50:25 GMT -Newsgroups <A HREF="news:comp.unix.osf.osf1">comp.unix.osf.osf1</A> -Message-ID <4oirch$bc8@usenet.pa.dec.com> -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 <4onmmd$mmd@usenet.pa.dec.com> -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-hp.html b/docs/manual/platform/perf-hp.html deleted file mode 100644 index 13ed152e6a..0000000000 --- a/docs/manual/platform/perf-hp.html +++ /dev/null @@ -1,118 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Running a High-Performance Web Server on HPUX</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<A NAME="initial"> </A> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Running a High-Performance Web Server for HPUX</H1> - -<PRE> -Date: Wed, 05 Nov 1997 16:59:34 -0800 -From: Rick Jones <<A HREF="mailto:raj@cup.hp.com">raj@cup.hp.com</A>> -Reply-To: raj@cup.hp.com -Organization: Network Performance -Subject: HP-UX tuning tips -</PRE> - -Here are some tuning tips for HP-UX to add to the tuning page. - -<P> - -For HP-UX 9.X: Upgrade to 10.20<BR> -For HP-UX 10.[00|01|10]: Upgrade to 10.20 - -<P> - -For HP-UX 10.20: - -<P> - -Install the latest cumulative ARPA Transport Patch. This will allow you -to configure the size of the TCP connection lookup hash table. The -default is 256 buckets and must be set to a power of two. This is -accomplished with adb against the *disc* image of the kernel. The -variable name is tcp_hash_size. - -<P> - -How to pick the value? Examine the output of -<A HREF="ftp://ftp.cup.hp.com/dist/networking/tools/connhist"> -ftp://ftp.cup.hp.com/dist/networking/tools/connhist</A> and see how many -total TCP connections exist on the system. You probably want that number -divided by the hash table size to be reasonably small, say less than 10. -Folks can look at HP's SPECweb96 disclosures for some common settings. -These can be found at <A HREF="http://www.specbench.org/"> -http://www.specbench.org/</A>. If an HP-UX system was -performing at 1000 SPECweb96 connections per second, the TIME_WAIT time -of 60 seconds would mean 60,000 TCP "connections" being tracked. - -<P> - -Folks can check their listen queue depths with -<A HREF="ftp://ftp.cup.hp.com/dist/networking/misc/listenq"> -ftp://ftp.cup.hp.com/dist/networking/misc/listenq</A>. - -<P> - -If folks are running Apache on a PA-8000 based system, they should -consider "chatr'ing" the Apache executable to have a large page size. -This would be "chatr +pi L <BINARY>." The GID of the running executable -must have MLOCK privileges. Setprivgrp(1m) should be consulted for -assigning MLOCK. The change can be validated by running Glance and -examining the memory regions of the server(s) to make sure that they -show a non-trivial fraction of the text segment being locked. - -<P> - -If folks are running Apache on MP systems, they might consider writing a -small program that uses mpctl() to bind processes to processors. A -simple pid % numcpu algorithm is probably sufficient. This might even go -into the source code. - -<P> - -If folks are concerned about the number of FIN_WAIT_2 connections, they -can use nettune to shrink the value of tcp_keepstart. However, they -should be careful there - certainly do not make it less than oh two to -four minutes. If tcp_hash_size has been set well, it is probably OK to -let the FIN_WAIT_2's take longer to timeout (perhaps even the default -two hours) - they will not on average have a big impact on performance. - -<P> - -There are other things that could go into the code base, but that might -be left for another email. Feel free to drop me a message if you or -others are interested. - -<P> - -sincerely, - -<P> - -rick jones<BR> -<A HREF="http://www.cup.hp.com/netperf/NetperfPage.html"> -http://www.cup.hp.com/netperf/NetperfPage.html</A> - -<HR> - -<H3 ALIGN="CENTER"> - Apache HTTP Server Version 1.3 -</H3> - -<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> -<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> - -</BODY></HTML> - diff --git a/docs/manual/platform/perf.html b/docs/manual/platform/perf.html deleted file mode 100644 index 238224728e..0000000000 --- a/docs/manual/platform/perf.html +++ /dev/null @@ -1,176 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Hints on Running a High-Performance Web Server</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Hints on Running a High-Performance Web Server</H1> - -Running Apache on a heavily loaded web server, one often encounters -problems related to the machine and OS configuration. "Heavy" is -relative, of course - but if you are seeing more than a couple hits -per second on a sustained basis you should consult the pointers on -this page. In general the suggestions involve how to tune your kernel -for the heavier TCP load, hardware/software conflicts that arise, etc. - -<UL> -<LI><A HREF="#AUX">A/UX (Apple's UNIX)</A> -<LI><A HREF="#BSD">BSD-based (BSDI, FreeBSD, etc)</A> -<LI><A HREF="#DEC">Digital UNIX</A> -<LI><A HREF="perf-hp.html">HPUX</A> -<LI><A HREF="#Linux">Linux</A> -<LI><A HREF="#Solaris">Solaris</A> -<LI><A HREF="#SunOS">SunOS 4.x</A> -<LI><A HREF="#SVR4">SVR4</A> -</UL> - -<HR> - -<H3><A NAME="AUX"> -A/UX (Apple's UNIX) -</A></H3> - -If you are running Apache on A/UX, a page that gives some helpful -performance hints (concerning the <EM>listen()</EM> queue and using -virtual hosts) -<A HREF="http://www.jaguNET.com/apache.html">can be found here</A> - -<P><HR> - -<H3><A NAME="BSD"> -BSD-based (BSDI, FreeBSD, etc) -</A></H3> - -<A HREF="perf-bsd44.html#initial">Quick</A> and -<A HREF="perf-bsd44.html#detail">detailed</A> -performance tuning hints for BSD-derived systems. - -<P><HR> - -<H3><A NAME="DEC"> -Digital UNIX -</A></H3> - -<UL> - <LI><A - HREF="http://www.digital.com/info/internet/document/ias/tuning.html" - >DIGITAL UNIX Tuning Parameters for Web Servers</A> - <LI>We have some <A HREF="perf-dec.html">newsgroup postings</A> on how - to tune Digital UNIX 3.2 and 4.0. -</UL> - -<P><HR> - -<H3><A NAME="Linux"> -Linux -</A></H3> - -The most common problem on Linux shows up on heavily-loaded systems -where the whole server will appear to freeze for a couple of minutes -at a time, and then come back to life. This has been traced to a -listen() queue overload - certain Linux implementations have a low -value set for the incoming connection queue which can cause problems. - -<P><HR> - -<H3><A NAME="Solaris"> -Solaris 2.4 -</A></H3> - -The Solaris 2.4 TCP implementation has a few inherent limitations that -only became apparent under heavy loads. This has been fixed to some -extent in 2.5 (and completely revamped in 2.6), but for now consult -the following URL for tips on how to expand the capabilities if you -are finding slowdowns and lags are hurting performance. - -<P> - -Other links: - -<UL> - -<LI><A HREF="http://www.sun.com/sun-on-net/performance.html"> -World Wide Web Server Performance, -<http://www.sun.com/sun-on-net/performance.html></A> -<LI><A HREF="http://www.rvs.uni-hannover.de/people/voeckler/tune/EN/tune.html"> -Solaris 2.x - tuning your TCP/IP stack</A> contains some good technical -information about tuning various Solaris TCP/IP parameters. -</UL> - -<P><HR> - -<H3><A NAME="SunOS"> -SunOS 4.x -</A></H3> - -More information on tuning SOMAXCONN on SunOS can be found at -<A HREF="http://www.islandnet.com/~mark/somaxconn.html"> -http://www.islandnet.com/~mark/somaxconn.html</A>. - -<P><HR> - -<H3><A NAME="SVR4"> -SVR4 -</A></H3> - -Some SVR4 versions waste three system calls on every -<SAMP>gettimeofday()</SAMP> call. Depending on the syntactic -form of the <SAMP>TZ</SAMP> environment variable, these -systems have several different algorithms to determine the -local time zone (presumably <EM>compatible</EM> with -something). The following example uses the central european -time zone to demonstrate this: -<DL> - <DT><STRONG>TZ=:MET</STRONG> - <DD>This form delegates the knowledge of the time zone - information to an external compiled zoneinfo file - (à la BSD).<BR> - <STRONG>Caveat:</STRONG> Each time the gettimeofday() - function is called, the external zone info is read in - again (at least on some SVR4 systems). That results in - three wasted system calls with every apache request - served.<PRE> - open("/usr/lib/locale/TZ/MET", O_RDONLY) = 3 - read(3, "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0"..., 7944) = 778 - close(3) = 0</PRE> - - <DT><STRONG>TZ=MET-1MDT,M3.5.0/02:00:00,M10.5.0/03:00:00</STRONG> - <DD>This syntax form (à la SYSV) contains all the - knowledge about time zone beginning and ending times in - its external representation. It has to be parsed each - time it is evaluated, resulting in a slight computing - overhead, but it requires no system call. Though the - table lookup à la BSD is the more sophisticated - technical solution, the bad SVR4 implementation makes - this the preferred syntax on systems which otherwise - access the external zone info file repeatedly. -</DL> -You should use the <SAMP>truss</SAMP> utility on a -single-process apache server (started with the <SAMP>-X</SAMP> -debugging switch) to determine whether your system can profit -from the second form of the <SAMP>TZ</SAMP> environment -variable. If it does, you could integrate the setting of the -preferred <SAMP>TZ</SAMP> syntax into the httpd startup -script, which is usually simply a copy of (or symbolic link -to) the <SAMP>apachectl</SAMP> utility script, or into the -system's <SAMP>/etc/TIMEZONE</SAMP> script. - -<P><HR> - -<H3>More welcome!</H3> - -If you have tips to contribute, send mail to <A -HREF="mailto:apache@apache.org">apache@apache.org</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 a77a3b5cd4..0000000000 --- a/docs/manual/platform/unixware.html +++ /dev/null @@ -1,62 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Compiling Apache under UnixWare</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Compiling Apache under UnixWare</H1> - -To compile a working copy of Apache under UnixWare, there are several other -steps you may need to take. These prevent such problems as zombie processes, -bind errors, and accept errors, to name a few. - -<H2>UnixWare 1.x</H2> - -Make sure that USE_FCNTL_SERIALIZE_ACCEPT is defined (if not -defined by Apache autoconfiguration). If using the UnixWare <EM>cc</EM> -compiler, and you still see accept() errors, don't use compiler optimization, -or get <EM>gcc</EM>. - -<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> - -<STRONG>NOTE:</STRONG> 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/platform/windows.html b/docs/manual/platform/windows.html deleted file mode 100644 index a1499d8ff3..0000000000 --- a/docs/manual/platform/windows.html +++ /dev/null @@ -1,372 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Using Apache with Microsoft Windows</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Using Apache With Microsoft Windows</H1> - -<P>This document explains how to install, configure and run - Apache 1.3b6 (or later) under Microsoft Windows. Please note that at - this time, Windows support is entirely experimental, and is - recommended only for experienced users. The Apache Group does not - guarantee that this software will work as documented, or even at - all. If you find any bugs, or wish to contribute in other ways, please - use our <A HREF="http://www.apache.org/bug_report.html">bug reporting - page.</A></P> - -<P><STRONG>Warning: Apache on NT has not yet been optimized for performance. -Apache still performs best, and is most reliable on Unix platforms. Over -time we will improve NT performance. Folks doing comparative reviews -of webserver performance are asked to compare against Apache -on a Unix platform such as Solaris, FreeBSD, or Linux.</STRONG></P> - -<P> - -Most of this document assumes that you are installing Windows from a -binary distribution. If you want to compile Apache yourself (possibly -to help with development, or to track down bugs), see the section on -<A HREF="#comp">Compiling Apache for Windows</A> below. - -<HR> - -<UL> - <LI><A HREF="#req">Requirements</A> - <LI><A HREF="#down">Downloading Apache for Windows</A> - <LI><A HREF="#inst">Installing Apache for Windows (binary install)</A> - <LI><A HREF="#run">Running Apache for Windows</A> - <LI><A HREF="#use">Using Apache for Windows</A> - <LI><A HREF="#cmdline">Running Apache for Windows from the Command Line</A> - <LI><A HREF="#comp">Compiling Apache for Windows</A> -</UL> - -<HR> - -<H2><A NAME="req">Requirements</A></H2> - -<P>Apache 1.3b6 requires the following:</P> - -<UL> - <LI>Microsoft Windows NT 4.0<A HREF="#351">*</A>, or Windows 95. - <LI>An Intel-based PC-compatible capable of running above OS (exact - requirements unknown) with a connection to a TCP/IP network. -</UL> - -<P><SMALL><A NAME="351">*</A> Apache may run with Windows NT 3.5.1, but - has not been tested.</SMALL></P> - -<P>If running on Windows 95, using the "Winsock2" upgrade is recommended - but may not be necessary. If running on NT 4.0, installing Service Pack 2 - is recommended.</P> - -<H2><A NAME="down">Downloading Apache for Windows</A></H2> - -<P>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 alpha or beta-test release, -together with details of mirror web and anonymous ftp sites.</P> - -<P> - -You should download the version of Apache for Windows with the -<CODE>.exe</CODE> extension. This is a single file containing Apache, -ready to install and run. There may also be a <CODE>.zip</CODE> file -containing the source code, to compile Apache yourself. - -<H2><A NAME="inst">Installing Apache for Windows</A></H2> - -Run the Apache <SAMP>.exe</SAMP> file you downloaded above. This will -ask for: - -<UL> - - <LI>the directory to install Apache into (the default is - <CODE>\Program Files\Apache Group\Apache</CODE> although you can - change this to any other directory) - - <LI>the start menu name (default is "Apache Web Server") - - <LI>the installation type. The "Typical" option installs - everything except the source code. The "Minimum" option does not - install the manuals or source code. Choose the "Custom" install if - you want to install the source code. - -</UL> - -<P> - -<STRONG>Important note for 1.3b6 installs</STRONG>: the installer for -1.3b6 will overwrite any existing <SAMP>httpd.conf</SAMP>, -<SAMP>access.conf</SAMP>, <SAMP>srm.conf</SAMP> or -<SAMP>mime.types</SAMP> files in the <SAMP>conf</SAMP>, and will also -overwrite your <SAMP>index.html</SAMP> file in the <SAMP>htdocs</SAMP> -directory. You should copy this files or directories before installing -Apache 1.3b6, or install into a new directory. - -<P> - -After installing Apache, you should edit the configuration files in -the <SAMP>conf</SAMP> directory as required. These files will be -configured during the install ready for Apache to be run from the -directory where it was installed, with the documents served from the -subdirectory <SAMP>htdocs</SAMP>. There are lots of other options -which should be set before you start really using Apache. However to -get started the files should work as installed. - -<H2><A NAME="inst">Running Apache for Windows</A></H2> - -There are two ways you can run Apache: - -<UL> - <LI>As a "service" (available on NT only). This is the best option if - you want Apache to automatically start when you machine boots, and to - keep Apache running when you log-off. - - <LI>From a console window. This is the only option available for - Windows 95 users. -</UL> - -To start Apache as a service, you first need to install it as a -service. Run the "Install Apache as Service" option from the Start -menu. Once this is done you can start Apache by opening the Services -window (in the Control Panel), selecting Apache, then clicking on -Start. Apache will now be running in the background. You can later -stop Apache by clicking on Stop. As an alternative to using the -Services window, you can start and stop Apache from the control line -with - -<PRE> - NET START APACHE - NET STOP APACHE -</PRE> - -To run Apache from a console window, select the "Apache Server" option -from the Start menu. This will open a console window and start Apache -running inside it. The window will remain active until you stop -Apache. To stop Apache running, press Control-C within the console -window. - -<P> - -After starting Apache running (either in a console window or as a -service) if will be listening to port 80 (unless you changed the -<SAMP>Port</SAMP>, <SAMP>Listen</SAMP> or <SAMP>BindAddress</SAMP> -directives in the configuration files). To connect to the server and -access the default page, launch a browser and enter this URL: - -<PRE> - http://localhost/ -</PRE> - -This should respond with a welcome page, and a link to the Apache -manual. If nothing happens or you get an error, look in the -<SAMP>error_log</SAMP> file in the <SAMP>logs</SAMP> directory. - -<P> - -Once your basic installation is working, you should configure it -properly by editing the files in the <SAMP>conf</SAMP> directory. - -<H2><A NAME="use">Configuring Apache for Windows</A></H2> - -Apache is configured by files in the <SAMP>conf</SAMP> -directory. These are the same as files used to configure the Unix -version, but there are a few different directives for Apache on -Windows. See the <A HREF="./">Apache documentation</A> for all the -available directives. - -<P> - -The main differences in Apache for Windows are: - -<UL> - <LI><P>Because Apache for Windows is multithreaded, it does not use a - separate process for each request, as Apache does with - Unix. Instead there are usually only two Apache processes running: - a parent process, and a child which handles the requests. Within - the child each request is handled by a separate thread. - <P> - - So the "process"-management directives are different: - <P><A - HREF="mod/core.html#maxrequestsperchild">MaxRequestsPerChild</A> - - Like the Unix directive, this controls how many requests a - process will serve before exiting. However, unlike Unix, a - process serves all the requests at once, not just one, so if - this is set, it is recommended that a very high number is - used. The recommended default, <CODE>MaxRequestsPerChild - 0</CODE>, does not cause the process to ever exit. - <P><A HREF="mod/core.html#threadsperchild">ThreadsPerChild</A> - - This directive is new, and tells the server how many threads it - should use. This is the maximum number of connections the server - can handle at once; be sure and set this number high enough for - your site if you get a lot of hits. The recommended default is - <CODE>ThreadsPerChild 50</CODE>.</P> - <LI><P>The directives that accept filenames as arguments now must use - Windows filenames instead of Unix ones. However, because Apache - uses Unix-style names internally, you must use forward slashes, not - backslashes. Drive letters can be used; if omitted, the drive with - the Apache executable will be assumed.</P> - <LI><P>Apache for Windows contains the ability to load modules at runtime, - without recompiling the server. If Apache is compiled normally, it - will install a number of optional modules in the - <CODE>\Apache\modules</CODE> directory. To activate these, or other - modules, the new <A HREF="mod/mod_so.html#loadmodule">LoadModule</A> - directive must be used. For example, to active the status module, - use the following (in addition to the status-activating directives - in <CODE>access.conf</CODE>):</P> -<PRE> - LoadModule status_module modules/ApacheModuleStatus.dll -</PRE> - <P>Information on <A HREF="mod/mod_so.html#creating">creating loadable - modules</A> is also available.</P> - <LI><P>Apache can also load ISAPI Extensions (i.e., Internet Server - Applications), such as those used by Microsoft's IIS, and other - Windows servers. <A HREF="mod/mod_isapi.html">More information - is available.</A> -</UL> - -<H2><A NAME="cmdline">Running Apache for Windows from the Command Line</A></H2> - -The Start menu icons and the NT Service manager can provide an simple -interafce for administering Apache. But in some cases it is easier to -work from the command line. - -<P> - -When working with Apache it is important to know how it will find the -configuration files. During installation, a registry key will have -been installed called: - -<PRE> - HKEY_LOCAL_MACHINE\Software\Apache Group\Apache\1.3 beta\ServerRoot -</PRE> - -The value of this key is the "ServerRoot" directory, containing the -<SAMP>conf</SAMP> directory. When Apache starts it will read the -<SAMP>httpd.conf</SAMP> file from this directory. If this file -contains a <SAMP>ServerRoot</SAMP> directive which is different from -the directory obtained from the registry key above, Apache will forget -the registry key and use the directory from the configuration file. -If you copy the Apache directory or configuration files to a new -location it is vital that you update the <SAMP>ServerRoot</SAMP> -directory in the <SAMP>httpd.conf</SAMP> file to the new location. - -<P> - -To run Apache from the command line as a console application, use the -following command: - -<PRE> - apache -s -</PRE> - -(The -s option is not required by Windows 95, but on Windows NT it -prevents Apache waiting to see if Apache is running as a -service). Apache will execute, and will remain running until it -is stopped by pressing control-C. - -<P> - -To install Apache as a Windows NT service, use the following: - -<PRE> - apache -i -</PRE> - -and to remove the Apache service, use - -<PRE> - apache -u -</PRE> - -If you want to run an installation of Apache in a directory other than -the one in the registry key as above, use the <CODE>-f</CODE> -command-line to specify the path to the <SAMP>httpd.conf</SAMP> file, -or the <CODE>-d</CODE> option to specify the server root -directory. These options can be used with any of the other flags as -listed above. Again note that once Apache has read the -<SAMP>httpd.conf</SAMP> file it will then start using the directory -given on the <SAMP>ServerRoot</SAMP> directive line instead of the -f -or -d command line argument. - -<H2><A NAME="comp">Compiling Apache for Windows</A></H2> - -<P>Compiling Apache requires Microsoft Visual C++ 5.0 to be properly - installed. It is easiest to compile with the command-line tools - (nmake, etc...). Consult the VC++ manual to determine how to install - them.</P> - -<P>First, unpack the Apache distribution into an appropriate - directory. Open a command-line prompt, and change to the - <CODE>src</CODE> subdirectory of the Apache distribution.</P> - -<P>The master Apache makefile instructions are contained in the - <CODE>Makefile.nt</CODE> file. To compile Apache, simply use one of - the following commands: -<UL> -<LI><CODE>nmake /f Makefile.nt _apacher</CODE> (release build) -<LI><CODE>nmake /f Makefile.nt _apached</CODE> (debug build) -</UL> - -<P>These will both compile Apache. The latter will include debugging - information in the resulting files, making it easier to find bugs and - track down problems.</P> - -<P>Apache can also be compiled using VC++'s Visual Studio development - environment. Although compiling Apache in this manner is not as simple, - it makes it possible to easily modify the Apache source, or to compile - Apache if the command-line tools are not installed.</P> - -<P>Project files (<CODE>.DSP</CODE>) are included for each of the - portions of Apache. The three projects that are necessary for - Apache to run are <CODE>Apache.dsp</CODE>, <CODE>ap/ap.dsp</CODE>, - <CODE>regex/regex.dsp</CODE>, <CODE>ApacheCore.dsp</CODE> and - <CODE>os/win32/ApacheOS.dsp</CODE>. The <CODE>src/win32</CODE> - subdirectory contains project files for the optional modules (see - below).</P> - -<P>Once Apache has been compiled, it needs to be installed in its server - root directory. The default is the <CODE>\Apache</CODE> - directory, on the current hard drive. </P> - -<P>To install the files into the <CODE>\Apache</CODE> directory - automatically, use one the following nmake commands (see above):</P> -<UL> -<LI><CODE>nmake /f Makefile.nt installr INSTDIR=<EM>dir</EM></CODE> - (for release build) -<LI><CODE>nmake /f Makefile.nt installd INSTDIR=<EM>dir</EM></CODE> - (for debug build) -</UL> - -The dir argument to INSTDIR gives the installation directory. The can -be omitted if Apache is to be installed into <SAMP>\Apache</SAMP>. - -<P>This will install the following:</P> - -<UL> - <LI><CODE><EM>dir</EM>\Apache.exe</CODE> - Apache executable - <LI><CODE><EM>dir</EM>\ApacheCore.dll</CODE> - Main Apache shared library - <LI><CODE><EM>dir</EM>\modules\ApacheModule*.dll</CODE> - Optional Apache - modules (7 files) - <LI><CODE><EM>dir</EM>\conf</CODE> - Empty configuration directory - <LI><CODE><EM>dir</EM>\logs</CODE> - Empty logging directory -</UL> - -<P>If you do not have nmake, or wish to install in a different directory, - be sure to use a similar naming scheme.</P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/search/manual-index.cgi b/docs/manual/search/manual-index.cgi deleted file mode 100644 index 92891dac7c..0000000000 --- a/docs/manual/search/manual-index.cgi +++ /dev/null @@ -1,246 +0,0 @@ -#!/usr/local/bin/perl5 -w -# ==================================================================== -# Copyright (c) 1995-1997 The Apache Group. All rights reserved. -# -# Redistribution and use in source and binary forms, with or without -# modification, are permitted provided that the following conditions -# are met: -# -# 1. Redistributions of source code must retain the above copyright -# notice, this list of conditions and the following disclaimer. -# -# 2. Redistributions in binary form must reproduce the above copyright -# notice, this list of conditions and the following disclaimer in -# the documentation and/or other materials provided with the -# distribution. -# -# 3. All advertising materials mentioning features or use of this -# software must display the following acknowledgment: -# "This product includes software developed by the Apache Group -# for use in the Apache HTTP server project (http://www.apache.org/)." -# -# 4. The names "Apache Server" and "Apache Group" must not be used to -# endorse or promote products derived from this software without -# prior written permission. -# -# 5. Redistributions of any form whatsoever must retain the following -# acknowledgment: -# "This product includes software developed by the Apache Group -# for use in the Apache HTTP server project (http://www.apache.org/)." -# -# THIS SOFTWARE IS PROVIDED BY THE APACHE GROUP ``AS IS'' AND ANY -# EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE GROUP OR -# ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT -# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, -# STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) -# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED -# OF THE POSSIBILITY OF SUCH DAMAGE. -# ==================================================================== -# -# manual-index.cgi script -# originally written by Ken Coar <Coar@DECUS.Org> in May 1997 -# -# This script either displays a form in order to find documents in which -# a word appears, or displays the results of such a search. It is -# called as a CGI script. -# -# [FILE]PATH_INFO is the prefix to add to to the files names found in -# the index (URL prefix, not filesystem prefix), and QUERY_STRING is the -# word to be found. -# -#*** -#*** -# You may need to tweak the following line to point to the correct -# location of the index file on your system (it's in the -# apache/htdocs/manual directory of the Apache distribution tree). -#*** -#*** -$INDEX = "/export/pub/apache/manual-index-data"; - -#*** -#*** -# You shouldn't have to modify anything else. -#*** -#*** - -$HTML = ""; - -# -# If we have a FILEPATH_INFO or PATH_INFO, it's there to remap the -# documents to the manual root directory. If this script is already in -# that directory, this isn't needed. -# -$prefix = $ENV{'FILEPATH_INFO'} || $ENV{'PATH_INFO'}; -$prefix .= "/" if ($prefix && ($prefix !~ m:/$:)); - -# -# QUERY_STRING, if present, contains the word for which we are to -# search. We also use its [non]presence to determine wha we display. -# -$word = $ENV{'QUERY_STRING'}; - -# -# Make sure our HTTP header makes it to the server by causing Perl to do -# a fflush() after every write to STDOUT. -# -select (STDOUT); -$| = 1; -printf ("Content-type: text/html\n\n"); - -# -# Fine, now buffering can go back to normal. -# -$| = 0; - -# -# Set up the HTML page title -$title = "Apache Documentation Search"; -$title .= ": Results for \"$word\"" if ($word); - -# -# We'll re-use the HTML scalar several times; we use it with here -# documents for multi-line static HTML code. Lets' do the standard page -# header. -# -$HTML = <<EOHT; -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> - <HEAD> - <TITLE>$title - </TITLE> - </HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> - <BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" - > - <DIV ALIGN="CENTER"> - <IMG - SRC="${prefix}images/sub.gif" - ALT="" - > - </DIV> - <H1 ALIGN="CENTER"> - Apache Documentation Search - </H1> - <P> - This script performs a very simple search across the Apache - documentation for any single case-insensitive word. No combinations, - wildcards, regular expressions, word-stubbing, or other fancy options - are supported; this is just to help you find topics quickly. Only - those pages which include the <EM>exact</EM> word you type will be - listed. - </P> - <P> - Documents containing the search word are <EM>not</EM> listed in any - sort of priority order. - </P> - <ISINDEX PROMPT="Enter word to find and press ENTER: "> -EOHT - -printf ($HTML); - -# -# Now set up the next section, which is only displayed if we've been -# given a word to find. -# -$HTML = <<EOHT; - <HR> - <H2> - Results of Search for <SAMP>$word</SAMP> - </H2> -EOHT - -# -# We enblock the next section so problems can drop out to the common -# closure code. -# -QUERY: - { - if ($word) { - # - # Try and open the index file; complain bitterly if we can't. - # - if (! open (INDEX, "<$INDEX")) { - printf ("Can't find documentation index!"); - last QUERY; - } - # - # Got it; display the search-results header. - # - printf ($HTML); - # - # Read the entire index in and turn it into an hash for the - # lookup. - # - @index = <INDEX>; - close (INDEX); - chomp (@index); - foreach (@index) { - ($key, $files) = split (/:/, $_); - $Index{$key} = $files; - } - # - # The dictionary is all lowercase words. Smash our query value - # and try to find it. - # - $word = lc ($word); - if (! exists ($Index{$word})) { - printf (" <P>\n <EM>Sorry, no matches found.</EM>\n </P>\n"); - last QUERY; - } - # - # Found an entry, so turn the hash value (a comma-separated list - # of relative file names) into an array for display. - # Incidentally, tell the user how many there are. - # - @files = split (/,/, $Index{$word}); - printf (" <P>Total of %d match", scalar (@files)); - # - # Be smart about plurals. - # - if (scalar (@files) != 1) { - printf ("es") ; - } - printf (" found.\n </P>\n"); - # - # Right. Now display the files as they're listed. - # - printf (" <OL>\n"); - foreach (@files) { - printf (" <LI><A HREF=\"${prefix}$_\">"); - printf ("<SAMP>$_</SAMP></A>\n"); - printf (" </LI>\n"); - } - printf (" </OL>\n"); - # - # C'est tout! - # - } - } - -# -# Back to common code - the exit path. Display the page trailer. -# -$HTML = <<EOHT; - <A - HREF="/" - ><IMG - SRC="/images/apache_home.gif" - ALT="Home" - ></A> - <HR> - </BODY> -</HTML> -EOHT - -printf ($HTML); -exit (0); diff --git a/docs/manual/sections.html.en b/docs/manual/sections.html.en deleted file mode 100644 index a8e4756d92..0000000000 --- a/docs/manual/sections.html.en +++ /dev/null @@ -1,141 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML><HEAD> -<TITLE>How Directory, Location and Files sections work</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">How Directory, Location and Files sections work</H1> - -The sections <A -HREF="mod/core.html#directory"><CODE><Directory></CODE></A>, <A -HREF="mod/core.html#location"><CODE><Location></CODE></A> and <A -HREF="mod/core.html#files"><CODE><Files></CODE></A> can contain -directives which only apply to specified directories, URLs or files -respectively. Also htaccess files can be used inside a directory to -apply directives to that directory. This document explains how these -different sections differ and how they relate to each other when -Apache decides which directives apply for a particular directory or -request URL. - -<H2>Directives allowed in the sections</H2> - -Everything that is syntactically allowed in -<CODE><Directory></CODE> is also allowed in -<CODE><Location></CODE> (except a sub-<CODE><Files></CODE> -section, but the code doesn't test for that, Lars has an open bug -report on that). Semantically however some things, and the most -notable is AllowOverride, make no sense in -<CODE><Location></CODE>. The same for -<CODE><Files></CODE> -- syntactically everything is fine, but -semantically some things are different. - -<H2>How the sections are merged</H2> - -The order of merging is: - -<OL> - -<LI> - - <CODE><Directory></CODE> (except regular expressions) and - .htaccess done simultaneously (with .htaccess overriding - <CODE><Directory></CODE>) - -</LI> - -<LI> - <CODE><DirectoryMatch></CODE>, and - <CODE><Directory></CODE> with regular expressions - -</LI> - - <LI><CODE><Files></CODE> and <CODE><FilesMatch></CODE> done - simultaneously - </LI> - - <LI><CODE><Location></CODE> and <CODE><LocationMatch></CODE> done - simultaneously - </LI> - -</OL> - -Apart from <CODE><Directory></CODE>, each group is processed in -the order that they appear in the configuration -files. <CODE><Directory></CODE> (group 1 above) is processed in -the order shortest directory component to longest. If multiple -<CODE><Directory></CODE> sections apply to the same directory -they they are processed in the configuration file order. The -configuration files are read in the order httpd.conf, srm.conf and -access.conf. Configurations included via the <CODE>Include</CODE> -directive will be treated as if they where inside the including file -at the location of the <CODE>Include</CODE> directive. - -<P> - -Sections inside <CODE><VirtualHost></CODE> sections are applied -<EM>after</EM> the corresponding sections outside the virtual host -definition. This allows virtual hosts to override the main server -configuration. (Note: this only works correctly from 1.2.2 and 1.3a2 -onwards. Before those releases sections inside virtual hosts were -applied <EM>before</EM> the main server). - -<H2>Notes about using sections</H2> - -The general guidelines are: - -<P> - -<UL> -<LI> - If you are attempting to match objects at the filesystem level - then you must use <CODE><Directory></CODE> and/or - <CODE><Files></CODE>. -</LI> - -<LI> - If you are attempting to match objects at the URL level then you - must use <CODE><Location></CODE> -</LI> -</UL> - -But a notable exception is: - -<UL> -<LI> - proxy control is done via <CODE><Directory></CODE>. This is - a legacy mistake because the proxy existed prior to - <CODE><Location></CODE>. A future version of the config - language should probably switch this to - <CODE><Location></CODE>. -</LI> -</UL> - -Note also that modifying .htaccess parsing during Location doesn't do -anything because .htaccess parsing has already occurred. - -<P> - -Another note: -<P> - -<UL> -<LI> - There is actually a - <CODE><Location></CODE>/<CODE><LocationMatch></CODE> - sequence performed just before the name translation phase (where - <CODE>Aliases</CODE> and <CODE>DocumentRoots</CODE> are used to - map URLs to filenames). The results of this sequence are - completely thrown away after the translation has completed. -</LI> -</UL> - -<!--#include virtual="footer.html" --> -</BODY></HTML> diff --git a/docs/manual/stopping.html.en b/docs/manual/stopping.html.en deleted file mode 100644 index 3d03d4df97..0000000000 --- a/docs/manual/stopping.html.en +++ /dev/null @@ -1,174 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Stopping and Restarting Apache</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Stopping and Restarting Apache</H1> - -<P>You will notice many <CODE>httpd</CODE> executables running on your system, -but you should not send signals to any of them except the parent, whose -pid is in the <A HREF="mod/core.html#pidfile">PidFile</A>. That is to -say you shouldn't ever need to send signals to any process except the -parent. There are three signals that you can send the parent: -<CODE>TERM</CODE>, <CODE>HUP</CODE>, and <CODE>USR1</CODE>, which will -be described in a moment. - -<P>To send a signal to the parent you should issue a command such as: -<BLOCKQUOTE><PRE> - kill -TERM `cat /usr/local/apache/logs/httpd.pid` -</PRE></BLOCKQUOTE> - -You can read about its progress by issuing: - -<BLOCKQUOTE><PRE> - tail -f /usr/local/apache/logs/error_log -</PRE></BLOCKQUOTE> - -Modify those examples to match your -<A HREF="mod/core.html#serverroot">ServerRoot</A> and -<A HREF="mod/core.html#pidfile">PidFile</A> settings. - -<P>As of Apache 1.3 we provide a script <CODE>src/support/apachectl</CODE> -which can be used to start, stop, and restart Apache. It may need a -little customization for your system, see the comments at the top of -the script. - -<H3>TERM Signal: stop now</H3> - -<P>Sending the <CODE>TERM</CODE> signal to the parent causes it to -immediately attempt to kill off all of its children. It may take it -several seconds to complete killing off its children. Then the -parent itself exits. Any requests in progress are terminated, and no -further requests are served. - -<H3>HUP Signal: restart now</H3> - -<P>Sending the <CODE>HUP</CODE> signal to the parent causes it to kill off -its children like in <CODE>TERM</CODE> but the parent doesn't exit. It -re-reads its configuration files, and re-opens any log files. -Then it spawns a new set of children and continues -serving hits. - -<P>Users of the -<A HREF="mod/mod_status.html">status module</A> -will notice that the server statistics are -set to zero when a <CODE>HUP</CODE> is sent. - -<P><STRONG>Note:</STRONG> If your configuration file has errors in it when -you issue a -restart then your parent will not restart, it will exit with an error. -See below for a method of avoiding this. - -<H3>USR1 Signal: graceful restart</H3> - -<P><STRONG>Note:</STRONG> prior to release 1.2b9 this code is quite unstable -and shouldn't be used at all. - -<P>The <CODE>USR1</CODE> signal causes the parent process to <EM>advise</EM> -the children to exit after their current request (or to exit immediately -if they're not serving anything). The parent re-reads its configuration -files and re-opens its log files. As each child dies off the parent -replaces it with a child from the new <EM>generation</EM> of the -configuration, which begins serving new requests immediately. - -<P>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 <STRONG>not</STRONG> set to zero when a <CODE>USR1</CODE> is sent. The -code -was written to both minimize the time in which the server is unable to serve -new requests (they will be queued up by the operating system, so they're -not lost in any event) and to respect your tuning parameters. In order -to do this it has to keep the <EM>scoreboard</EM> used to keep track -of all children across generations. - -<P>The status module will also use a <CODE>G</CODE> to indicate those -children which are still serving requests started before the graceful -restart was given. - -<P>At present there is no way for a log rotation script using -<CODE>USR1</CODE> to know for certain that all children writing the -pre-restart log have finished. We suggest that you use a suitable delay -after sending the <CODE>USR1</CODE> signal before you do anything with the -old log. For example if most of your hits take less than 10 minutes to -complete for users on low bandwidth links then you could wait 15 minutes -before doing anything with the old log. - -<P><STRONG>Note:</STRONG> If your configuration file has errors in it when -you issue a -restart then your parent will not restart, it will exit with an error. -In the case of graceful -restarts it will also leave children running when it exits. (These are -the children which are "gracefully exiting" by handling their last request.) -This will cause problems if you attempt to restart the server -- it will -not be able to bind to its listening ports. At present the only work -around is to check the syntax of your files before doing a restart. The -easiest way is to just run httpd as a non-root user. If there are no -errors it will attempt to open its sockets and logs and fail because it's -not root (or because the currently running httpd already has those ports -bound). If it fails for any other reason then it's probably a config file -error and the error should be fixed before issuing the graceful restart. - -<H3>Appendix: signals and race conditions</H3> - -<P>Prior to Apache 1.2b9 there were several <EM>race conditions</EM> -involving the restart and die signals (a simple description of race -condition is: a time-sensitive problem, as in if something happens at just -the wrong time it won't behave as expected). For those architectures that -have the "right" feature set we have eliminated as many as we can. -But it should be noted that there still do exist race conditions on -certain architectures. - -<P>Architectures that use an on disk -<A HREF="mod/core.html#scoreboardfile">ScoreBoardFile</A> -have the potential to corrupt their scoreboards. This can result in -the "bind: Address already in use" (after <CODE>HUP</CODE>) or -"long lost child came home!" (after <CODE>USR1</CODE>). The former is -a fatal error, while the latter just causes the server to lose a scoreboard -slot. So it might be advisable to use graceful restarts, with -an occasional hard restart. These problems are very difficult to work -around, but fortunately most architectures do not require a scoreboard file. -See the ScoreBoardFile documentation for a method to determine if your -architecture uses it. - -<P><CODE>NEXT</CODE> and <CODE>MACHTEN</CODE> (68k only) have small race -conditions -which can cause a restart/die signal to be lost, but should not cause the -server to do anything otherwise problematic. -<!-- they don't have sigaction, or we're not using it -djg --> - -<P>All architectures have a small race condition in each child involving -the second and subsequent requests on a persistent HTTP connection -(KeepAlive). It may exit after reading the request line but before -reading any of the request headers. There is a fix that was discovered -too late to make 1.2. In theory this isn't an issue because the KeepAlive -client has to expect these events because of network latencies and -server timeouts. In practice it doesn't seem to affect anything either --- in a test case the server was restarted twenty times per second and -clients successfully browsed the site without getting broken images or -empty documents. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/suexec.html.en b/docs/manual/suexec.html.en deleted file mode 100644 index d005739b63..0000000000 --- a/docs/manual/suexec.html.en +++ /dev/null @@ -1,540 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache suEXEC Support</TITLE> -</HEAD> -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> - -<H1 ALIGN="CENTER">Apache suEXEC Support</H1> - -<P ALIGN="LEFT"> -<OL> - <LI><BIG><STRONG>CONTENTS</STRONG></BIG></LI> - <LI><A HREF="#what">What is suEXEC?</A></LI> - <LI><A HREF="#before">Before we begin.</A></LI> - <LI><A HREF="#model">suEXEC Security Model.</A></LI> - <LI><A HREF="#install">Configuring & Installing suEXEC</A></LI> - <LI><A HREF="#enable">Enabling & Disabling suEXEC</A></LI> - <LI><A HREF="#debug">Debugging suEXEC</A></LI> - <LI><A HREF="#jabberwock">Beware the Jabberwock: Warnings & - Examples</A></LI> -</OL> -</P> - -<H3><A NAME="what">What is suEXEC?</A></H3> -<P ALIGN="LEFT"> -The <STRONG>suEXEC</STRONG> feature -- introduced in Apache 1.2 -- provides -Apache users the ability to run <STRONG>CGI</STRONG> and <STRONG>SSI</STRONG> -programs under user IDs different from the user ID of the calling web-server. -Normally, when a CGI or SSI program executes, it runs as the same user who is -running the web server. -</P> - -<P ALIGN="LEFT"> -Used properly, this feature can reduce considerably the security risks involved -with allowing users to develop and run private CGI or SSI programs. However, -if suEXEC is improperly configured, it can cause any number of problems and -possibly create new holes in your computer's security. If you aren't familiar -with managing setuid root programs and the security issues they present, we -highly recommend that you not consider using suEXEC. -</P> - -<P ALIGN="CENTER"> -<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> -</P> - -<H3><A NAME="before">Before we begin.</A></H3> -<P ALIGN="LEFT"> -Before jumping head-first into this document, you should be aware of the -assumptions made on the part of the Apache Group and this document. -</P> - -<P ALIGN="LEFT"> -First, it is assumed that you are using a UNIX derivate operating system that -is capable of <STRONG>setuid</STRONG> and <STRONG>setgid</STRONG> operations. -All command examples are given in this regard. Other platforms, if they are -capable of supporting suEXEC, may differ in their configuration. -</P> - -<P ALIGN="LEFT"> -Second, it is assumed you are familiar with some basic concepts of your -computer's security and its administration. This involves an understanding -of <STRONG>setuid/setgid</STRONG> operations and the various effects they -may have on your system and its level of security. -</P> - -<P ALIGN="LEFT"> -Third, it is assumed that you are using an <STRONG>unmodified</STRONG> -version of suEXEC code. All code for suEXEC has been carefully scrutinized and -tested by the developers as well as numerous beta testers. Every precaution -has been taken to ensure a simple yet solidly safe base of code. Altering this -code can cause unexpected problems and new security risks. It is -<STRONG>highly</STRONG> recommended you not alter the suEXEC code unless you -are well versed in the particulars of security programming and are willing to -share your work with the Apache Group for consideration. -</P> - -<P ALIGN="LEFT"> -Fourth, and last, it has been the decision of the Apache Group to -<STRONG>NOT</STRONG> make suEXEC part of the default installation of Apache. -To this end, suEXEC configuration requires of the administrator careful -attention to details. After due consideration has been given to the various -settings for suEXEC, the administrator may install suEXEC through normal -installation methods. The values for these settings need to be carefully -determined and specified by the administrator to properly maintain system -security during the use of suEXEC functionality. It is through this detailed -process that the Apache Group hopes to limit suEXEC installation only to those -who are careful and determined enough to use it. -</P> - -<P ALIGN="LEFT"> -Still with us? Yes? Good. Let's move on! -</P> - -<P ALIGN="CENTER"> -<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> -</P> - -<H3><A NAME="model">suEXEC Security Model</A></H3> -<P ALIGN="LEFT"> -Before we begin configuring and installing suEXEC, we will first discuss -the security model you are about to implement. By doing so, you may -better understand what exactly is going on inside suEXEC and what precautions -are taken to ensure your system's security. -</P> - -<P ALIGN="LEFT"> -<STRONG>suEXEC</STRONG> is based on a setuid "wrapper" program that is -called by the main Apache web server. This wrapper is called when an HTTP -request is made for a CGI or SSI program that the administrator has designated -to run as a userid other than that of the main server. When such a request -is made, Apache provides the suEXEC wrapper with the program's name and the -user and group IDs under which the program is to execute. -</P> - -<P ALIGN="LEFT"> -The wrapper then employs the following process to determine success or -failure -- if any one of these conditions fail, the program logs the failure -and exits with an error, otherwise it will continue: -<OL> - <LI><STRONG>Was the wrapper called with the proper number of - arguments?</STRONG> - <BLOCKQUOTE> - The wrapper will only execute if it is given the proper number of arguments. - The proper argument format is known to the Apache web server. If the - wrapper - is not receiving the proper number of arguments, it is either being hacked, - or - there is something wrong with the suEXEC portion of your Apache binary. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the user executing this wrapper a valid user of this - system?</STRONG> - <BLOCKQUOTE> - This is to ensure that the user executing the wrapper is truly a user of the - system. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is this valid user allowed to run the wrapper?</STRONG> - <BLOCKQUOTE> - Is this user the user allowed to run this wrapper? Only one user (the - Apache user) is allowed to execute this program. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Does the target program have an unsafe hierarchical - reference?</STRONG> - <BLOCKQUOTE> - Does the target program contain a leading '/' or have a '..' backreference? - These are not allowed; the target program must reside within the Apache - webspace. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target user name valid?</STRONG> - <BLOCKQUOTE> - Does the target user exist? - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target group name valid?</STRONG> - <BLOCKQUOTE> - Does the target group exist? - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target user <EM>NOT</EM> superuser?</STRONG> - <BLOCKQUOTE> - Presently, suEXEC does not allow 'root' to execute CGI/SSI programs. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target userid <EM>ABOVE</EM> the minimum ID - number?</STRONG> - <BLOCKQUOTE> - The minimum user ID number is specified during configuration. This allows - you - to set the lowest possible userid that will be allowed to execute CGI/SSI - programs. This is useful to block out "system" accounts. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target group <EM>NOT</EM> the superuser group?</STRONG> - <BLOCKQUOTE> - Presently, suEXEC does not allow the 'root' group to execute CGI/SSI - programs. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target groupid <EM>ABOVE</EM> the minimum ID - number?</STRONG> - <BLOCKQUOTE> - The minimum group ID number is specified during configuration. This allows - you - to set the lowest possible groupid that will be allowed to execute CGI/SSI - programs. This is useful to block out "system" groups. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Can the wrapper successfully become the target user and - group?</STRONG> - <BLOCKQUOTE> - Here is where the program becomes the target user and group via setuid and - setgid - calls. The group access list is also initialized with all of the groups - of which - the user is a member. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Does the directory in which the program resides exist?</STRONG> - <BLOCKQUOTE> - If it doesn't exist, it can't very well contain files. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the directory within the Apache webspace?</STRONG> - <BLOCKQUOTE> - If the request is for a regular portion of the server, is the requested - directory - within the server's document root? If the request is for a UserDir, is - the requested - directory within the user's document root? - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the directory <EM>NOT</EM> writable by anyone else?</STRONG> - <BLOCKQUOTE> - We don't want to open up the directory to others; only the owner user - may be able - to alter this directories contents. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Does the target program exist?</STRONG> - <BLOCKQUOTE> - If it doesn't exists, it can't very well be executed. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target program <EM>NOT</EM> writable by anyone - else?</STRONG> - <BLOCKQUOTE> - We don't want to give anyone other than the owner the ability to - change the program. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target program <EM>NOT</EM> setuid or setgid?</STRONG> - <BLOCKQUOTE> - We do not want to execute programs that will then change our UID/GID again. - </BLOCKQUOTE> - </LI> - <LI><STRONG>Is the target user/group the same as the program's - user/group?</STRONG> - <BLOCKQUOTE> - Is the user the owner of the file? - </BLOCKQUOTE> - </LI> - <LI><STRONG>Can we successfully clean the process environment to - ensure safe operations?</STRONG> - <BLOCKQUOTE> - suEXEC cleans the process' environment by establishing a safe - execution PATH (defined - during configuration), as well as only passing through those - variables whose names - are listed in the safe environment list (also created during - configuration). - </BLOCKQUOTE> - </LI> - <LI><STRONG>Can we successfully become the target program and - execute?</STRONG> - <BLOCKQUOTE> - Here is where suEXEC ends and the target program begins. - </BLOCKQUOTE> - </LI> -</OL> -</P> - -<P ALIGN="LEFT"> -This is the standard operation of the the suEXEC wrapper's security model. -It is somewhat stringent and can impose new limitations and guidelines for -CGI/SSI design, but it was developed carefully step-by-step with security -in mind. -</P> - -<P ALIGN="LEFT"> -For more information as to how this security model can limit your possibilities -in regards to server configuration, as well as what security risks can be -avoided with a proper suEXEC setup, see the -<A HREF="#beware">"Beware the Jabberwock"</A> -section of this document. -</P> - -<P ALIGN="CENTER"> -<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> -</P> - -<H3><A NAME="install">Configuring & Installing suEXEC</A></H3> -<P ALIGN="LEFT"> -Here's where we begin the fun. The configuration and installation of suEXEC is -a four step process: edit the suEXEC header file, compile suEXEC, place the -suEXEC binary in its proper location, and configure Apache for use with suEXEC. -</P> - -<P ALIGN="LEFT"> -<STRONG>EDITING THE SUEXEC HEADER FILE</STRONG><BR> -- From the top-level of the Apache source tree, type: -<STRONG><CODE>cd support [ENTER]</CODE></STRONG> -</P> - -<P ALIGN="LEFT"> -Edit the <CODE>suexec.h</CODE> file and change the following macros to -match your local Apache installation. -</P> - -<P ALIGN="LEFT"> -<EM>From support/suexec.h</EM> -<PRE> - /* - * HTTPD_USER -- Define as the username under which Apache normally - * runs. This is the only user allowed to execute - * this program. - */ - #define HTTPD_USER "www" - - /* - * UID_MIN -- Define this as the lowest UID allowed to be a target user - * for suEXEC. For most systems, 500 or 100 is common. - */ - #define UID_MIN 100 - - /* - * GID_MIN -- Define this as the lowest GID allowed to be a target group - * for suEXEC. For most systems, 100 is common. - */ - #define GID_MIN 100 - - /* - * USERDIR_SUFFIX -- Define to be the subdirectory under users' - * home directories where suEXEC access should - * be allowed. All executables under this directory - * will be executable by suEXEC as the user so - * they should be "safe" programs. If you are - * using a "simple" UserDir directive (ie. one - * without a "*" in it) this should be set to - * the same value. suEXEC will not work properly - * in cases where the UserDir directive points to - * a location that is not the same as the user's - * home directory as referenced in the passwd file. - * - * If you have VirtualHosts with a different - * UserDir for each, you will need to define them to - * all reside in one parent directory; then name that - * parent directory here. IF THIS IS NOT DEFINED - * PROPERLY, ~USERDIR CGI REQUESTS WILL NOT WORK! - * See the suEXEC documentation for more detailed - * information. - */ - #define USERDIR_SUFFIX "public_html" - - /* - * LOG_EXEC -- Define this as a filename if you want all suEXEC - * transactions and errors logged for auditing and - * debugging purposes. - */ - #define LOG_EXEC "/usr/local/apache/logs/cgi.log" /* Need me? */ - - /* - * DOC_ROOT -- Define as the DocumentRoot set for Apache. This - * will be the only hierarchy (aside from UserDirs) - * that can be used for suEXEC behavior. - */ - #define DOC_ROOT "/usr/local/apache/htdocs" - - /* - * SAFE_PATH -- Define a safe PATH environment to pass to CGI executables. - * - */ - #define SAFE_PATH "/usr/local/bin:/usr/bin:/bin" -</PRE> -</P> - -<P ALIGN="LEFT"> -<STRONG>COMPILING THE SUEXEC WRAPPER</STRONG><BR> -You now need to compile the suEXEC wrapper. At the shell command prompt, -type: <STRONG><CODE>cc suexec.c -o suexec [ENTER]</CODE></STRONG>. -This should create the <STRONG><EM>suexec</EM></STRONG> wrapper executable. -</P> - -<P ALIGN="LEFT"> -<STRONG>COMPILING APACHE FOR USE WITH SUEXEC</STRONG><BR> -By default, Apache is compiled to look for the suEXEC wrapper in the following -location. -</P> - -<P ALIGN="LEFT"> -<EM>From src/httpd.h</EM> -<PRE> - /* The path to the suEXEC wrapper */ - #define SUEXEC_BIN "/usr/local/apache/sbin/suexec" -</PRE> -</P> - -<P ALIGN="LEFT"> -If your installation requires location of the wrapper program in a different -directory, edit src/httpd.h and recompile your Apache server. -See <A HREF="install.html">Compiling and Installing Apache</A> for more -info on this process. -</P> - -<P ALIGN="LEFT"> -<STRONG>COPYING THE SUEXEC BINARY TO ITS PROPER LOCATION</STRONG><BR> -Copy the <STRONG><EM>suexec</EM></STRONG> executable created in the -exercise above to the defined location for <STRONG>SUEXEC_BIN</STRONG>. -</P> - -<P ALIGN="LEFT"> -<STRONG><CODE>cp suexec /usr/local/apache/sbin/suexec [ENTER]</CODE></STRONG> -</P> - -<P ALIGN="LEFT"> -In order for the wrapper to set the user ID, it must me installed as owner -<STRONG><EM>root</EM></STRONG> and must have the setuserid execution bit -set for file modes. If you are not running a <STRONG><EM>root</EM></STRONG> -user shell, do so now and execute the following commands. -</P> - -<P ALIGN="LEFT"> -<STRONG><CODE>chown root /usr/local/apache/sbin/suexec [ENTER]</CODE></STRONG> -<BR> -<STRONG><CODE>chmod 4711 /usr/local/apache/sbin/suexec [ENTER]</CODE></STRONG> -</P> - -<P ALIGN="CENTER"> -<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> -</P> - -<H3><A NAME="enable">Enabling & Disabling suEXEC</A></H3> -<P ALIGN="LEFT"> -After properly installing the <STRONG>suexec</STRONG> wrapper -executable, you must kill and restart the Apache server. A simple -<STRONG><CODE>kill -1 `cat httpd.pid`</CODE></STRONG> will not be enough. -Upon startup of the web-server, if Apache finds a properly configured -<STRONG>suexec</STRONG> wrapper, it will print the following message to -the console: -</P> - -<P ALIGN="LEFT"> -<CODE>Configuring Apache for use with suexec wrapper.</CODE> -</P> - -<P ALIGN="LEFT"> -If you don't see this message at server startup, the server is most -likely not finding the wrapper program where it expects it, or the -executable is not installed <STRONG><EM>setuid root</EM></STRONG>. Check -your installation and try again. -</P> - -<P ALIGN="LEFT"> -One way to use <STRONG>suEXEC</STRONG> is through the -<A HREF="mod/core.html#user"><STRONG>User</STRONG></A> and -<A HREF="mod/core.html#group"><STRONG>Group</STRONG></A> directives in -<A HREF="mod/core.html#virtualhost"><STRONG>VirtualHost</STRONG></A> -definitions. By setting these directives to values different from the -main server user ID, all requests for CGI resources will be executed as -the <STRONG>User</STRONG> and <STRONG>Group</STRONG> defined for that -<STRONG><VirtualHost></STRONG>. If only one or -neither of these directives are specified for a -<STRONG><VirtualHost></STRONG> then the main -server userid is assumed.<P> - -<STRONG>suEXEC</STRONG> can also be used to to execute CGI programs as -the user to which the request is being directed. This is accomplished by -using the <STRONG>~</STRONG> character prefixing the user ID for whom -execution is desired. -The only requirement needed for this feature to work is for CGI -execution to be enabled for the user and that the script must meet the -scrutiny of the <A HREF="#model">security checks</A> above. - -<P ALIGN="CENTER"> -<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> -</P> - -<H3><A NAME="debug">Debugging suEXEC</A></H3> -<P ALIGN="LEFT"> -The suEXEC wrapper will write log information to the location defined in -the <CODE>suexec.h</CODE> as indicated above. If you feel you have -configured and installed the wrapper properly, have a look at this log -and the error_log for the server to see where you may have gone astray. -</P> - -<P ALIGN="CENTER"> -<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> -</P> - -<H3> -<A NAME="jabberwock">Beware the Jabberwock: Warnings & Examples</A> -</H3> -<P ALIGN="LEFT"> -<STRONG>NOTE!</STRONG> This section may not be complete. For the latest -revision of this section of the documentation, see the Apache Group's -<A HREF="http://www.apache.org/docs/suexec.html">Online Documentation</A> -version. -</P> - -<P ALIGN="LEFT"> -There are a few points of interest regarding the wrapper that can cause -limitations on server setup. Please review these before submitting any -"bugs" regarding suEXEC. -<UL> - <LI><STRONG>suEXEC Points Of Interest</STRONG></LI> - <LI>Hierarchy limitations - <BLOCKQUOTE> - For security and efficiency reasons, all suexec requests must - remain within either a top-level document root for virtual - host requests, or one top-level personal document root for - userdir requests. For example, if you have four VirtualHosts - configured, you would need to structure all of your VHosts' - document roots off of one main Apache document hierarchy to - take advantage of suEXEC for VirtualHosts. (Example forthcoming.) - </BLOCKQUOTE> - </LI> - <LI>suEXEC's PATH environment variable - <BLOCKQUOTE> - This can be a dangerous thing to change. Make certain every - path you include in this define is a <STRONG>trusted</STRONG> - directory. You don't want to open people up to having someone - from across the world running a trojan horse on them. - </BLOCKQUOTE> - </LI> - <LI>Altering the suEXEC code - <BLOCKQUOTE> - Again, this can cause <STRONG>Big Trouble</STRONG> if you try - this without knowing what you are doing. Stay away from it - if at all possible. - </BLOCKQUOTE> - </LI> -</UL> - -<P ALIGN="CENTER"> -<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> -</P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/vhosts/fd-limits.html.en b/docs/manual/vhosts/fd-limits.html.en deleted file mode 100644 index 6b9d0f93c4..0000000000 --- a/docs/manual/vhosts/fd-limits.html.en +++ /dev/null @@ -1,59 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache Server Virtual Host Support</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">File Descriptor Limits</H1> - -<P> -When using a large number of Virtual Hosts, Apache may run out of available -file descriptors (sometimes called <CITE>file handles</CITE> if each Virtual -Host specifies different log files. -The total number of file descriptors used by Apache is one for each distinct -error log file, one for every other log file directive, plus 10-20 for -internal use. Unix operating systems limit the number of file descriptors that -may be used by a process; the limit is typically 64, and may usually be -increased up to a large hard-limit. -<P> -Although Apache attempts to increase the limit as required, this -may not work if: -<OL> -<LI>Your system does not provide the setrlimit() system call. -<LI>The setrlimit(RLIMIT_NOFILE) call does not function on your system - (such as Solaris 2.3) -<LI>The number of file descriptors required exceeds the hard limit. -<LI>Your system imposes other limits on file descriptors, such as a limit -on stdio streams only using file descriptors below 256. (Solaris 2) -</OL> - -In the event of problems you can: -<UL> -<LI>Reduce the number of log files; don't specify log files in the VirtualHost -sections, but only log to the main log files. -<LI>If you system falls into 1 or 2 (above), then increase the file descriptor -limit before starting Apache, using a script like -<BLOCKQUOTE><CODE> -#!/bin/sh <BR> -ulimit -S -n 100 <BR> -exec httpd</CODE></BLOCKQUOTE> -</UL> -<P> -Please see the -<A HREF="../misc/descriptors.html">Descriptors and Apache</A> -document containing further details about file descriptor problems and how -they can be solved on your operating system. -</P> - -<!--#include virtual="footer.html" --> -</BODY></HTML> - diff --git a/docs/manual/vhosts/index.html.en b/docs/manual/vhosts/index.html.en deleted file mode 100644 index b08ea16444..0000000000 --- a/docs/manual/vhosts/index.html.en +++ /dev/null @@ -1,64 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>Apache Virtual Host documentation</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Apache Virtual Host documentation</H1> - -<P>The term <CITE>Virtual Host</CITE> refers to the practice of maintaining -more than one server on one machine, as differentiated by their apparent -hostname. For example, it is often desirable for companies sharing a -web server to have their own domains, with web servers accessible as -<SAMP>www.company1.com</SAMP> and <SAMP>www.company2.com</SAMP>, -without requiring the user to know any extra path information.</P> - -<P>Apache was one of the first servers to support IP-based -virtual hosts right out of the box. Versions 1.1 and later of -Apache support both, IP-based and name-based virtual hosts (vhosts). -The latter variant of virtual hosts is sometimes also called host-based or -non-IP virtual hosts.</P> - -<P>Below is a list of documentation pages which explain all details -of virtual host support in Apache version 1.3 and later.</P> - -<HR> - -<H2>Virtual Host Support</H2> - -<UL> -<LI><A HREF="ip-based.html">IP-based Virtual Hosts</A> -<LI><A HREF="name-based.html">Name-based Virtual Hosts</A> -<LI><A HREF="examples.html">Virtual Host examples for common setups</A> -<LI><A HREF="details.html">In-Depth Discussion of Virtual Host Matching</A> -<LI><A HREF="fd-limits.html">File Descriptor Limits</A> -</UL> - -<H2>Configuration directives</H2> - -<UL> -<LI><A HREF="../mod/core.html#virtualhost"><VirtualHost></A> -<LI><A HREF="../mod/core.html#namevirtualhost">NameVirtualHost</A> -<LI><A HREF="../mod/core.html#servername">ServerName</A> -<LI><A HREF="../mod/core.html#serveralias">ServerAlias</A> -<LI><A HREF="../mod/core.html#serverpath">ServerPath</A> -</UL> - -<P>Folks trying to debug their virtual host configuration may find the -Apache <CODE>-S</CODE> command line switch useful. It will dump out a -description of how Apache parsed the configuration file. Careful -examination of the IP addresses and server names may help uncover -configuration mistakes. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/vhosts/name-based.html.en b/docs/manual/vhosts/name-based.html.en deleted file mode 100644 index 1a86a32f70..0000000000 --- a/docs/manual/vhosts/name-based.html.en +++ /dev/null @@ -1,146 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML><HEAD> -<TITLE>Apache name-based Virtual Hosts</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<!--#include virtual="header.html" --> -<H1 ALIGN="CENTER">Apache name-based Virtual Host Support</H1> - -<STRONG>See Also:</STRONG> -<A HREF="ip-based.html">IP-based Virtual Host Support</A> - -<HR> - -<H2>Name-based vs. IP-based virtual hosts</H2> - -<P>While the approach with IP-based virtual hosts works very well, -it is not the most elegant solution, because a dedicated IP address -is needed for every virtual host and it is hard to implement on some -machines. The <CODE>HTTP/1.1</CODE> protocol contains a method for the -server to identify what name it is being addressed as. Apache 1.1 and -later support this approach as well as the traditional -IP-address-per-hostname method.</P> - -<P>The benefits of using the new name-based virtual host support is a -practically unlimited number of servers, ease of configuration and use, and -requires no additional hardware or software. -The main disadvantage is that the client must support this part of the -protocol. The latest versions of most browsers do, but there are still -old browsers in use who do not. This can cause problems, although a possible -solution is addressed below.</P> - -<H2>Using non-IP Virtual Hosts</H2> - -<P>Using the new virtual hosts is quite easy, and superficially looks -like the old method. You simply add to one of the Apache configuration -files (most likely <CODE>httpd.conf</CODE> or <CODE>srm.conf</CODE>) -code similar to the following:</P> -<PRE> - NameVirtualHost 111.22.33.44 - - <VirtualHost 111.22.33.44> - ServerName www.domain.tld - DocumentRoot /web/domain - </VirtualHost> -</PRE> - -<P>The notable difference between IP-based and name-based virtual host -configuration is the -<A HREF="../mod/core.html#namevirtualhost"><CODE>NameVirtualHost</CODE></A> -directive which specifies an IP address that should be used as a target for -name-based virtual hosts. - -<P>Of course, any additional directives can (and should) be placed -into the <CODE><VirtualHost></CODE> section. To make this work, -all that is needed is to make sure that the name -<SAMP>www.domain.tld</SAMP> points to the IP address -<SAMP>111.22.33.44</SAMP></P> - -<P>Note: When you specify an IP address in a <CODE>NameVirtualHost</CODE> -directive then requests to that IP address will only ever be served -by matching <VirtualHost>s. The "main server" will <STRONG>never</STRONG> -be served from the specified IP address. - -<P>Additionally, many servers may wish to be accessible by more than -one name. For example, the example server might want to be accessible -as <CODE>domain.tld</CODE>, or <CODE>www2.domain.tld</CODE>, assuming -the IP addresses pointed to the same server. In fact, one might want it -so that all addresses at <CODE>domain.tld</CODE> were picked up by the -server. This is possible with the -<A HREF="../mod/core.html#serveralias"><CODE>ServerAlias</CODE></A> -directive, placed inside the <VirtualHost> section. For -example:</P> - -<PRE> - ServerAlias domain.tld *.domain.tld -</PRE> - -<P>Note that you can use <CODE>*</CODE> and <CODE>?</CODE> as wild-card -characters.</P> - -<P>You also might need <CODE>ServerAlias</CODE> if you are -serving local users who do not always include the domain name. -For example, if local users are -familiar with typing "www" or "www.foobar" then you will need to add -<CODE>ServerAlias www www.foobar</CODE>. It isn't possible for the -server to know what domain the client uses for their name resolution -because the client doesn't provide that information in the request.</P> - -<H2>Compatibility with Older Browsers</H2> - -<P>As mentioned earlier, there are still some clients in use who -do not send the required data for the name-based virtual hosts to work -properly. These clients will always be sent the pages from the -<CITE>primary</CITE> name-based virtual host (the first virtual host -appearing in the configuration file for a specific IP address).</P> - -<P>There is a possible workaround with the -<A HREF="../mod/core.html#serverpath"><CODE>ServerPath</CODE></A> -directive, albeit a slightly cumbersome one:</P> - -<P>Example configuration: - -<PRE> - NameVirtualHost 111.22.33.44 - - <VirtualHost 111.22.33.44> - ServerName www.domain.tld - ServerPath /domain - DocumentRoot /web/domain - </VirtualHost> -</PRE> - -<P>What does this mean? It means that a request for any URI beginning -with "<SAMP>/domain</SAMP>" will be served from the virtual host -<SAMP>www.domain.tld</SAMP> This means that the pages can be accessed as -<CODE>http://www.domain.tld/domain/</CODE> for all clients, although -clients sending a <SAMP>Host:</SAMP> header can also access it as -<CODE>http://www.domain.tld/</CODE>.</P> - -<P>In order to make this work, put a link on your primary virtual host's page -to <SAMP>http://www.domain.tld/domain/</SAMP> -Then, in the virtual host's pages, be sure to use either purely -relative links (e.g. "<SAMP>file.html</SAMP>" or -"<SAMP>../icons/image.gif</SAMP>" or links containing the prefacing -<SAMP>/domain/</SAMP> -(e.g. "<SAMP>http://www.domain.tld/domain/misc/file.html</SAMP>" or -"<SAMP>/domain/misc/file.html</SAMP>").</P> - -<P>This requires a bit of -discipline, but adherence to these guidelines will, for the most part, -ensure that your pages will work with all browsers, new and old.</P> - -<P>See also: <A HREF="examples.html#serverpath">ServerPath configuration -example</A></P> - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> |
