diff options
| author | (no author) <(no author)@unknown> | 1999-03-21 02:03:04 +0000 |
|---|---|---|
| committer | (no author) <(no author)@unknown> | 1999-03-21 02:03:04 +0000 |
| commit | 511070cd54ee0fad3406971ffaf846ccaee7e1a6 (patch) | |
| tree | f44645e6a2c5dd3b514d146674e8d240e3460262 | |
| parent | 990a430cadaf94bd2479dcae7cbcfdfd02a444c4 (diff) | |
| download | httpd-511070cd54ee0fad3406971ffaf846ccaee7e1a6.tar.gz | |
This commit was manufactured by cvs2svn to create tag 'APACHE_1_3_5'.1.3.5
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/tags/1.3.5@82962 13f79535-47bb-0310-9956-ffa450edef68
24 files changed, 0 insertions, 6216 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 11dd0dbb4b..0000000000 --- a/docs/manual/content-negotiation.html.en +++ /dev/null @@ -1,589 +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. -Apache 1.3.4 also supports 'transparent' content negotiation, which is -an experimental negotiation protocol defined in RFC 2295 and RFC 2296. -It does not offer support for 'feature negotiation' as defined in -these RFCs. -<P> - -A <STRONG>resource</STRONG> is a conceptual entity identified by a URI -(RFC 2396). An HTTP server like Apache provides access to -<STRONG>representations</STRONG> of the resource(s) within its namespace, -with each representation in the form of a sequence of bytes with a -defined media type, character set, encoding, etc. Each resource may be -associated with zero, one, or more than one representation -at any given time. If multiple representations are available, -the resource is referred to as <STRONG>negotiable</STRONG> and each of its -representations is termed a <STRONG>variant</STRONG>. The ways in which the -variants for a negotiable resource vary are called the -<STRONG>dimensions</STRONG> of negotiation. - -<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 (<EM>i.e.</EM>, a <CODE>*.var</CODE> file) which - names the files containing the variants explicitly, or - <LI> 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 must have a handler set in the configuration that defines a -file suffix as <CODE>type-map</CODE>; this is best done with a - -<PRE> - AddHandler type-map var -</PRE> - -in the server configuration file. See the comments in the sample config -file for more details. <P> - -Type map files have an entry for each available variant; these entries -consist of contiguous HTTP-format header lines. Entries for -different variants are separated by blank lines. Blank lines are -illegal within an entry. It is conventional to begin a map file with -an entry for the combined entity as a whole (although this -is not required, and if present will be ignored). An example -map file is: - -<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 in the range 0.000 to 1.000. Note that any variant with -a qs value of 0.000 will never be chosen. Variants with no 'qs' -parameter value are given a qs factor of 1.0. The qs parameter indicates -the relative 'quality' of this variant compared to the other available -variants, independent of the client's capabilities. For example, a jpeg -file is usually of higher source quality than an ascii file if it is -attempting to represent a photograph. However, if the resource being -represented is an original ascii art, then an ascii representation would -have a higher source quality than a jpeg representation. A qs value -is therefore specific to a given variant depending on the nature of -the resource it represents. - -<P> -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 tag from RFC 1766 (<EM>e.g.</EM>, <CODE>en</CODE> for English, - <CODE>kr</CODE> for Korean, <EM>etc.</EM>). - <DT> <CODE>Content-Encoding:</CODE> - <DD> If the file is compressed, or otherwise encoded, rather than - containing the actual raw data, this says how that was done. - Apache only recognizes encodings that are defined by an - <A HREF="mod/mod_mime.html#addencoding">AddEncoding</A> directive. - This normally includes the encodings <CODE>x-compress</CODE> - for compress'd files, and <CODE>x-gzip</CODE> for gzip'd files. - The <CODE>x-</CODE> prefix is ignored for encoding comparisons. - <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. - <DT> <CODE>Description:</CODE> - <DD> A human-readable textual description of the variant. If Apache cannot - find any appropriate variant to return, it will return an error - response which lists all available variants instead. Such a variant - list will include the human-readable variant descriptions. -</DL> - -<H3>Multiviews</H3> - -<P> -<CODE>MultiViews</CODE> is a per-directory option, meaning it can be set with -an <CODE>Options</CODE> directive within a <CODE><Directory></CODE>, -<CODE><Location></CODE> or <CODE><Files></CODE> -section in <CODE>access.conf</CODE>, or (if <CODE>AllowOverride</CODE> -is properly set) in <CODE>.htaccess</CODE> files. Note that -<CODE>Options All</CODE> does not set <CODE>MultiViews</CODE>; you -have to ask for it by name. - -<P> -The effect of <CODE>MultiViews</CODE> is as follows: if the server -receives a request for <CODE>/some/dir/foo</CODE>, if -<CODE>/some/dir</CODE> has <CODE>MultiViews</CODE> enabled, and -<CODE>/some/dir/foo</CODE> does <EM>not</EM> exist, then the server reads the -directory looking for files named foo.*, and effectively fakes up a -type map which names all those files, assigning them the same media -types and content-encodings it would have if the client had asked for -one of them by name. It then chooses the best match to the client's -requirements. - -<P> -<CODE>MultiViews</CODE> may also apply to searches for the file named by the -<CODE>DirectoryIndex</CODE> directive, if the server is trying to -index a directory. If the configuration files specify - -<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 Methods</H2> - -After Apache has obtained a list of the variants for a given resource, -either from a type-map file or from the filenames in the directory, it -invokes one of two methods to decide on the 'best' variant to -return, if any. It is not necessary to know any of the details of how -negotiation actually takes place in order to use Apache's content -negotiation features. However the rest of this document explains the -methods used for those interested. -<P> - -There are two negotiation methods: - -<OL> - -<LI><STRONG>Server driven negotiation with the Apache -algorithm</STRONG> is used in the normal case. The Apache algorithm is -explained in more detail below. When this algorithm is used, Apache -can sometimes 'fiddle' the quality factor of a particular dimension to -achieve a better result. The ways Apache can fiddle quality factors is -explained in more detail below. - -<LI><STRONG>Transparent content negotiation</STRONG> is used when the -browser specifically requests this through the mechanism defined in RFC -2295. This negotiation method gives the browser full control over -deciding on the 'best' variant, the result is therefore dependent on -the specific algorithms used by the browser. As part of the -transparent negotiation process, the browser can ask Apache to run the -'remote variant selection algorithm' defined in RFC 2296. </UL> - - -<H3>Dimensions of Negotiation</H3> - -<TABLE> -<TR valign="top"> -<TH>Dimension -<TH>Notes -<TR valign="top"> -<TD>Media Type -<TD>Browser indicates preferences with the Accept header field. Each item -can have an associated quality factor. Variant description can also -have a quality factor (the "qs" parameter). -<TR valign="top"> -<TD>Language -<TD>Browser indicates preferences with the Accept-Language header field. -Each item can have a quality factor. Variants can be associated with none, one -or more than one language. -<TR valign="top"> -<TD>Encoding -<TD>Browser indicates preference with the Accept-Encoding header field. -Each item can have a quality factor. -<TR valign="top"> -<TD>Charset -<TD>Browser indicates preference with the Accept-Charset header field. -Each item can have a quality factor. -Variants can indicate a charset as a parameter of the media type. -</TABLE> - -<H3>Apache Negotiation Algorithm</H3> - -<P> -Apache can use the following algorithm to select the 'best' variant -(if any) to return to the browser. This algorithm is not -further configurable. It operates as follows: - -<OL> -<LI>First, for each dimension of the negotiation, check the appropriate -<EM>Accept*</EM> header field and assign a quality to each -variant. If the <EM>Accept*</EM> header for any dimension implies that this -variant is not acceptable, eliminate it. If no variants remain, go -to step 4. - -<LI>Select the 'best' variant by a process of elimination. Each of the -following tests is applied in order. Any variants not selected at each -test are eliminated. After each test, if only one variant remains, -select it as the best match and proceed to step 3. If more than one -variant remains, move on to the next test. - -<OL> -<LI>Multiply the quality factor from the Accept header with the - quality-of-source factor for this variant's media type, and select - the variants with the highest value. - -<LI>Select the variants with the highest language quality factor. - -<LI>Select the variants with the best language match, using either the - order of languages in the Accept-Language header (if present), or else - else the order of languages in the <CODE>LanguagePriority</CODE> - directive (if present). - -<LI>Select the variants with the highest 'level' media parameter - (used to give the version of text/html media types). - -<LI>Select variants with the best charset media parameters, - as given on the Accept-Charset header line. Charset ISO-8859-1 - is acceptable unless explicitly excluded. Variants with a - <CODE>text/*</CODE> media type but not explicitly associated - with a particular charset are assumed to be in ISO-8859-1. - -<LI>Select those variants which have associated - charset media parameters that are <EM>not</EM> ISO-8859-1. - If there are no such variants, select all variants instead. - -<LI>Select the variants with the best encoding. If there are - variants with an encoding that is acceptable to the user-agent, - select only these variants. Otherwise if there is a mix of encoded - and non-encoded variants, select only the unencoded variants. - If either all variants are encoded or all variants are not encoded, - select all variants. - -<LI>Select 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 when variants are read from - the directory, the one whose file name comes first when sorted using - ASCII code order. - -</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 none are acceptable - to the browser). Return a 406 status (meaning "No acceptable representation") - with a response body consisting of an HTML document listing the - available variants. Also set the HTTP Vary header to indicate the - dimensions of variance. - -</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 Apache negotiation -algorithm above. This is to get a better result from the algorithm for -browsers which do not send full or accurate information. Some of the -most popular browsers send Accept header information which would -otherwise result in the selection of the wrong variant in many -cases. If a browser sends full and correct information these fiddles -will not be applied. -<P> - -<H3>Media Types and Wildcards</H3> - -<P> -The Accept: request header indicates preferences for media types. It -can also include 'wildcard' media types, such as "image/*" or "*/*" -where the * matches any string. So a request including: -<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>Extensions to Transparent Content Negotiation</H2> - -Apache extends the transparent content negotiation protocol (RFC 2295) -as follows. A new <CODE> {encoding ..}</CODE> element is used in -variant lists to label variants which are available with a specific -content-encoding only. The implementation of the -RVSA/1.0 algorithm (RFC 2296) is extended to recognize encoded -variants in the list, and to use them as candidate variants whenever -their encodings are acceptable according to the Accept-Encoding -request header. The RVSA/1.0 implementation does not round computed -quality factors to 5 decimal places before choosing the best variant. - -<H2>Note on hyperlinks and naming conventions</H2> - -<P> -If you are using language negotiation you can choose between -different naming conventions, because files can have more than one -extension, and the order of the extensions is normally irrelevant -(see <A HREF="mod/mod_mime.html">mod_mime</A> documentation for details). -<P> -A typical file has a MIME-type extension (<EM>e.g.</EM>, <SAMP>html</SAMP>), -maybe an encoding extension (<EM>e.g.</EM>, <SAMP>gz</SAMP>), and of course a -language extension (<EM>e.g.</EM>, <SAMP>en</SAMP>) when we have different -language variants of this file. - -<P> -Examples: -<UL> -<LI>foo.en.html -<LI>foo.html.en -<LI>foo.en.html.gz -</UL> - -<P> -Here some more examples of filenames together with valid and invalid -hyperlinks: -</P> - -<TABLE BORDER=1 CELLPADDING=8 CELLSPACING=0> -<TR> - <TH>Filename</TH> - <TH>Valid hyperlink</TH> - <TH>Invalid hyperlink</TH> -</TR> -<TR> - <TD><EM>foo.html.en</EM></TD> - <TD>foo<BR> - foo.html</TD> - <TD>-</TD> -</TR> -<TR> - <TD><EM>foo.en.html</EM></TD> - <TD>foo</TD> - <TD>foo.html</TD> -</TR> -<TR> - <TD><EM>foo.html.en.gz</EM></TD> - <TD>foo<BR> - foo.html</TD> - <TD>foo.gz<BR> - foo.html.gz</TD> -</TR> -<TR> - <TD><EM>foo.en.html.gz</EM></TD> - <TD>foo</TD> - <TD>foo.html<BR> - foo.html.gz<BR> - foo.gz</TD> -</TR> -<TR> - <TD><EM>foo.gz.html.en</EM></TD> - <TD>foo<BR> - foo.gz<BR> - foo.gz.html</TD> - <TD>foo.html</TD> -</TR> -<TR> - <TD><EM>foo.html.gz.en</EM></TD> - <TD>foo<BR> - foo.html<BR> - foo.html.gz</TD> - <TD>foo.gz</TD> -</TR> -</TABLE> - -<P> -Looking at the table above you will notice that it is always possible to -use the name without any extensions in an hyperlink (<EM>e.g.</EM>, <SAMP>foo</SAMP>). -The advantage is that you can hide the actual type of a -document rsp. file and can change it later, <EM>e.g.</EM>, from <SAMP>html</SAMP> -to <SAMP>shtml</SAMP> or <SAMP>cgi</SAMP> without changing any -hyperlink references. - -<P> -If you want to continue to use a MIME-type in your hyperlinks (<EM>e.g.</EM> -<SAMP>foo.html</SAMP>) the language extension (including an encoding extension -if there is one) must be on the right hand side of the MIME-type extension -(<EM>e.g.</EM>, <SAMP>foo.html.en</SAMP>). - - -<H2>Note on Caching</H2> - -<P> -When a cache stores a representation, it associates it with the request URL. -The next time that URL is requested, the cache can use the stored -representation. But, if the resource is negotiable at the server, -this might result in only the first requested variant being cached and -subsequent cache hits might return the wrong response. To prevent this, -Apache normally marks all responses that are returned after content negotiation -as non-cacheable by HTTP/1.0 clients. Apache also supports the HTTP/1.1 -protocol features to allow caching of negotiated responses. <P> - -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 09604ea972..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, <EM>e.g.</EM> - - <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, <EM>i.e.</EM>, <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 bf0fb77d7a..0000000000 --- a/docs/manual/developer/API.html +++ /dev/null @@ -1,1153 +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, <EM>etc.</EM> 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> (<EM>i.e.</EM>, 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, <EM>etc.</EM>, 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, <EM>etc.</EM> */ - int method_number; /* M_GET, M_POST, <EM>etc.</EM> */ - - /* 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, <EM>etc.</EM> */ - 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 (<EM>i.e.</EM>, 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>, - <CODE>ap_sub_req_lookup_uri</CODE>, and - <CODE>ap_sub_req_method_uri</CODE>; these construct 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>ap_run_sub_req</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, <EM>etc.</EM>), 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, <EM>etc.</EM>, 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>, - ap_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. <EM>i.e.</EM>, 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_...</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 (<EM>e.g.</EM>, 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 (<EM>e.g.</EM>, 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 e23a6061cd..0000000000 --- a/docs/manual/dso.html.en +++ /dev/null @@ -1,388 +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 <EM>etc.</EM> In other words: The executable program has to -manually resolve every symbol it needs to be able to use it. The advantage of -such a mechanism is that optional program parts need not be loaded (and thus -do not spend memory) until they are needed by the program in question. When -required, these program parts can be loaded dynamically to extend the base -program's functionality. - -<P>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, <EM>etc.</EM> Starting -with version 1.3, Apache joined the crew, because Apache already uses a module -concept to extend its functionality and internally uses a dispatch-list-based -approach to link external modules into the Apache core functionality. So, -Apache is really predestined for using DSO to load its modules at run-time. - -<P>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 BSDI (4.0) -o Linux (Debian/1.3.1, RedHat/4.2) -o Solaris (2.4, 2.5.1, 2.6) -o SunOS (4.1.3) -o Digital UNIX (4.0) -o IRIX (6.2) -o HP/UX (10.20) -o UnixWare (2.01, 2.1.2) -o SCO (5.0.4) -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], <EM>etc.</EM>) 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, <EM>etc.</EM> -<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 chances to use other code is to either make - sure the Apache core itself already contains a reference to it, loading - the code yourself via <CODE>dlopen()</CODE> or enabling the - <CODE>SHARED_CHAIN</CODE> rule while building Apache when your platform - supports linking DSO files against DSO libraries. -<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 72f16fd170..0000000000 --- a/docs/manual/handler.html.en +++ /dev/null @@ -1,195 +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 (See also -<A HREF="mod/mod_mime.html#multipleext">Files with Multiple Extensions</A>) - -</P> - -<P>Handlers can either be built into the server or to a module, or -they can be added with the <A -HREF="mod/mod_actions.html#action">Action</A> directive. The built-in -handlers in the standard distribution are as follows:</P> - -<UL> -<LI><STRONG>default-handler</STRONG>: - Send the file using the <CODE>default_handler()</CODE>, which is the - handler used by default to handle static content. - (core) -<LI><STRONG>send-as-is</STRONG>: - Send file with HTTP headers as is. - (<A HREF="mod/mod_asis.html">mod_asis</A>) -<LI><STRONG>cgi-script</STRONG>: - 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 extension...</EM><BR> -<A - HREF="mod/directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> -<A - HREF="mod/directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="mod/directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Base<BR> -<A - HREF="mod/directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_mime<BR> -<A - HREF="mod/directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> AddHandler is only available in Apache -1.1 and later<P> - -<P>AddHandler maps the filename extensions <EM>extension</EM> to the -handler <EM>handler-name</EM>. This mapping is added to any already -in force, overriding any mappings that already exist for the same -<EM>extension</EM>. - -For example, to activate CGI scripts -with the file extension "<CODE>.cgi</CODE>", you might use: -<PRE> - AddHandler cgi-script cgi -</PRE> - -<P>Once that has been put into your srm.conf or httpd.conf file, any -file containing the "<CODE>.cgi</CODE>" extension will be treated as a -CGI program.</P> - -<P> - -<STRONG>See also</STRONG>: <A HREF="mod/mod_mime.html#multipleext">Files with -multiple extensions</A> - -<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<BR> -<A - HREF="mod/directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> SetHandler is only available in Apache -1.1 and later.<P> - -<P>When placed into an <CODE>.htaccess</CODE> file or a -<CODE><Directory></CODE> or <CODE><Location></CODE> -section, this directive forces all matching files to be parsed through -the handler given by <EM>handler-name</EM>. For example, if you had a -directory you wanted to be parsed entirely as imagemap rule files, -regardless of extension, you might put the following into an -<CODE>.htaccess</CODE> file in that directory: -<PRE> - 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> -<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 40cad3178b..0000000000 --- a/docs/manual/install.html.en +++ /dev/null @@ -1,270 +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> - -This document covers compilation and installation of Apache on Unix -systems only. For compiling and installation on Windows, see <A -HREF="windows.html">Using Apache with Microsoft Windows</A> and for -TPF see <A HREF="install-tpf.html">Installing the Apache 1.3 HTTP -Server on TPF</A>. - -<P> - -UnixWare users will want to consult <A HREF="unixware.html">build notes</A> -for various UnixWare versions before compiling. - -<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 (<EM>e.g.</EM>, to include - an additional library required by an optional module) you might need - to edit one or more of the following options in the - <CODE>Configuration</CODE> file: - <CODE>EXTRA_CFLAGS, LIBS, 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, <EM>etc.</EM> Next -edit the <CODE>srm.conf</CODE> file; this sets up the root of the -document tree, special functions like server-parsed HTML or internal -imagemap parsing, <EM>etc.</EM> Finally, edit the <CODE>access.conf</CODE> -file to at least set the base cases of access. - -<P> - -In addition to these three files, the server behavior can be configured -on a directory-by-directory basis by using <CODE>.htaccess</CODE> -files in directories accessed by the server. - -<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 6b0be6decb..0000000000 --- a/docs/manual/invoking.html.en +++ /dev/null @@ -1,210 +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> - -On Unix, the <CODE>httpd</CODE> program is usually run as a daemon -which executes continuously, handling requests. It is possible to -invoke Apache by the Internet daemon <CODE>inetd</CODE> each time a -connection to the HTTP service is made (use the <A -HREF="mod/core.html#servertype">ServerType</A> directive) but this is -not recommended. - -<P> - -On Windows, Apache is normally run as a service on Windows NT, or as a -console application on Windows 95. See also <A -HREF="windows.html#run">running Apache for Windows</A>. - -<H2>Command line options</H2> -The following options are recognized on the httpd command line: -<DL> -<DT><CODE>-d</CODE> <EM>serverroot</EM> -<DD>Set the initial value for the -<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> on Unix, <CODE>/apache</CODE> on -Windows and <CODE>/os2httpd</CODE> on OS/2. - -<DT><CODE>-D</CODE> <EM>name</EM> -<DD>Define a name for use in in -<A HREF="mod/core.html#ifdefine">IfDefine</A> directives. -This option can be used to optionally enable certain functionality in the -configuration file, or to use a common configuration for -several independent hosts, where host specific information is enclosed in -<IfDefine> sections. - -<DT><CODE>-f</CODE> <EM>config</EM> -<DD>Execute the commands in the file <EM>config</EM> on startup. If -<EM>config</EM> does not begin with a <CODE>/</CODE>, then it is taken to be a -path relative to the <A HREF="mod/core.html#serverroot">ServerRoot</A>. The -default is <CODE>conf/httpd.conf</CODE>. - -<DT><CODE>-C</CODE> <EM>"directive"</EM> -<DD>Process the given apache "directive" (just as if it had been part of a -configuration file) <STRONG>before</STRONG> actually reading the regular configuration files. - -<DT><CODE>-c</CODE> <EM>"directive"</EM> -<DD>Process the given apache "directive" <STRONG>after</STRONG> reading -all the regular configuration files. - -<DT><CODE>-X</CODE> -<DD>Run in single-process mode, for internal debugging purposes only; the -daemon does not detach from the terminal or fork any children. Do <EM>NOT</EM> -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 -build date, and a list of compile time settings which influence the -behavior and performance of the apache server (<EM>e.g.</EM>, -<SAMP>-DUSE_MMAP_FILES</SAMP>), -then exit. - -<DT><A NAME="help"><CODE>-L</CODE></A> -<DD> - -Give a list of directives together with expected arguments and places -where the directive is valid, then exit. (Apache 1.3.4 and -later. Earlier versions used -l instead). - - -<DT><CODE>-l</CODE></A> -<DD> - -Give a list of all modules compiled into the server, then exit. -(Apache 1.3.4 and later. Earlier versions used -h instead).<br> - -Give a list of directives together with expected arguments and places -where the directive is valid, then exit. (Apache 1.2 to 1.3.3. Later -versions use -L instead). - - - -<DT><CODE>-h</CODE> -<DD> - -Print a list of the httpd options, then exit. (Apache 1.3.4 and -later. Earlier versions used -? instead).<br> - -Give a list of all modules compiled into the server, then exit. (Up to -Apache 1.3.3. Later versions use -l instead).<br> - - -<DT><CODE>-S</CODE> -<DD>Show the settings as parsed from the config file (currently only -shows a breakdown of the vhost settings) but do not start the -server. (Up to Apache 1.3.3, this option also started the server). - -<DT><CODE>-t</CODE> -<DD>Test the configuration file syntax (<EM>i.e.</EM>, read all configuration files -and interpret them) but do not start the server. If the configuration contains -errors, display an error message and exit with a non-zero exit status, -otherwise display "Syntax OK" and terminate with a zero exit status. - -<DT><CODE>-k</CODE> <EM>option</EM> -<DD>Windows only: signal Apache to restart or shutdown. <EM>option</EM> -is one of "shutdown" or "restart". (Apache 1.3.3 and later). - -<DT><CODE>-?</CODE> -<DD>Print a list of the httpd options, and then exit (up to Apache -1.3.3. Later version use -h instead). - -</DL> - -<H2>Configuration files</H2> -The server will read three files for configuration directives. Any -directive may appear in any of these files. The the names of these -files are taken to be relative to the server root; this is set by the -<A HREF="mod/core.html#serverroot">ServerRoot</A> directive, the -<CODE>-d</CODE> command line flag, or (on Windows only) the registry -(see <A HREF="windows.html#run">Running Apache for Windows</A>). - -Conventionally, the files are: -<DL> -<DT><CODE>conf/httpd.conf</CODE> -<DD>Contains directives that control the operation of the server daemon. -The filename may be overridden with the <CODE>-f</CODE> command line flag. - -<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 startup, Apache saves the process id of the parent httpd process to -the file <CODE>logs/httpd.pid</CODE>. This filename can be changed -with the <A HREF="mod/core.html#pidfile">PidFile</A> directive. The -process-id is for use by the administrator in restarting and -terminating the daemon: on Unix, a HUP or USR1 signal causes the -daemon to re-read its configuration files and a TERM signal causes it -to die gracefully; on Windows, use the -k command line option instead. -For more information see the <A HREF="stopping.html">Stopping and -Restarting</A> page. - -<P> -If the process dies (or is killed) abnormally, then it will be necessary to -kill the children httpd processes. - -<H3>Error log</H3> - -The server will log error messages to a log file, by default -<CODE>logs/error_log</CODE> on Unix or <CODE>logs/error.log</CODE> on -Windows and OS/2. The filename can be set using the <A -HREF="mod/core.html#errorlog">ErrorLog</A> directive; different error -logs can be set for different <A -HREF="mod/core.html#virtualhost">virtual hosts</A>. - -<H3>Transfer log</H3> - -The server will typically log each request to a transfer file, by -default <CODE>logs/access_log</CODE> on Unix or -<CODE>logs/access.log</CODE> on Windows and OS/2. The filename can be -set using a <A -HREF="mod/mod_log_config.html#transferlog">TransferLog</A> directive -or additional log files created with the <A -HREF="mod/mod_log_config.html#customlog">CustomLog</A> directive; -different transfer logs can be set for different <A -HREF="mod/core.html#virtualhost">virtual hosts</A>. - -<!--#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 c5e978c2b9..0000000000 --- a/docs/manual/platform/perf-bsd44.html +++ /dev/null @@ -1,254 +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, <EM>etc.</EM> - -<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 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> - -<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> - -To increase the size of the <CODE>listen()</CODE> queue, you need to -adjust the value of SOMAXCONN. SOMAXCONN is not derived from maxusers, -so you'll always need to increase that yourself. We use a value guaranteed -to be larger than Apache's default for the listen() of 128, currently. -The actual value for SOMAXCONN is set in <CODE>sys/socket.h</CODE>. -The best way to adjust this parameter is run-time, rather than changing -it in this header file and thus hardcoding a value in the kernel and -elsewhere. To do this, edit <CODE>/etc/rc.local</CODE> and add the -following line: -<PRE> - /usr/sbin/sysctl -w kern.somaxconn=256 -</PRE> - -<P> - -We used <CODE>256</CODE> but you can tune it for your own setup. In -many cases, however, even the default value of <CODE>128</CODE> (for -later versions of FreeBSD) is OK. - -<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, <EM>i.e.</EM>, 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 61e6314a70..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 (<EM>e.g.</EM>, 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 ca902a09fe..0000000000 --- a/docs/manual/platform/perf-hp.html +++ /dev/null @@ -1,122 +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. - -Notice that it's critically important that you use "W" to write a 32 bit -quantity, not "w" to write a 16 bit value when patching the disc image because -the tcp_hash_size variable is a 32 bit quantity. - -<P> - -How to pick the value? Examine the output of -<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 73bd5b5b20..0000000000 --- a/docs/manual/platform/perf.html +++ /dev/null @@ -1,175 +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, <EM>etc.</EM> - -<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> - -There are no known problems with heavily loaded systems running Linux -kernels 2.0.32 or later. Earlier kernels have some problems, and an -upgrade to the latest 2.0.x is a good idea to eliminate various security -and denial of service attacks. - -<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/readme-tpf.html b/docs/manual/platform/readme-tpf.html deleted file mode 100644 index 2e9161b1aa..0000000000 --- a/docs/manual/platform/readme-tpf.html +++ /dev/null @@ -1,206 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> -<TITLE>The Apache TPF Port</TITLE> -</HEAD> -<BODY> -<A NAME="top"></A> -<H1 align="center">Overview of the Apache TPF Port</H1> -<HR> -<CENTER>[ <A HREF="#configuration_files">Configuration Files</A> - | <A HREF="#auto_generated_files">Auto Generated Files</A> - | <A HREF="#whats_available">What's Available</A> - | <A HREF="#porting_notes">Porting Notes</A> ] -</CENTER> -<HR> -<BR> - -<P> - This version of Apache includes changes allowing it to run on - IBM's EBCDIC-based - <A HREF="http://www.s390.ibm.com/products/tpf/tpfhp.html">TPF</A> - (Transaction Processing Facility) operating system. - Unless otherwise noted TPF version 4.1 PUT08 and APAR PJ25589 are required. - <BR><BR> - Refer to htdocs/manual/<A HREF="install-tpf.html">install-tpf.html</A> - for step-by-step installation instructions. - <BR><BR> - As this is the first cut at making Apache run on TPF, - performance tuning has not been done. - <BR><BR> - This port builds upon the <A HREF="ebcdic.html">EBCDIC changes</A> - previously made to Apache. - <BR> -</P> - -<A NAME="configuration_files"> </A> -<H2 align=center>Apache Configuration Files</H2> -<P> - The distributed configuration files (httpd.conf-dist and - mime.types, both located in the conf subdirectory) - work on TPF with only a couple of operating system specific changes - to httpd.conf:<BR> - <UL> - <LI>ServerType needs to be "inetd" since TPF does not yet support - "standalone" mode. - <LI>Performance considerations may dictate setting KeepAlive to "Off" - (the default is "On") or lowering the Timeout value from the default - 300 seconds (5 minutes) in order to reduce the number of active ECBs on your system. - </UL> -</P> - -<A NAME="whats_available"> </A> -<H2 align=center>What's Available in this Version</H2> - - (The Apache organization provides - <A HREF="http://www.apache.org/docs/">online documentation</A> - describing the various modules and components of the server.) - -<H3>Components/modules tested on TPF:</H3> - - <multicol COLS=3><UL> - <LI>alloc.c - <LI>ap_cpystrn.c - <LI>ap_fnmatch.c - <LI>ap_signal.c - <LI>ap_slack.c - <LI>ap_snprintf.c - <LI>buff.c - <LI>buildmark.c - <LI>ebcdic.c - <LI>http_config.c - <LI>http_core.c - <LI>http_log.c - <LI>http_main.c - <LI>http_protocol.c - <LI>http_request.c - <LI>http_vhost.c <A HREF="#note_2">*</A> - <LI>mod_access.c - <LI>mod_alias.c - <LI>mod_asis.c - <LI>mod_autoindex.c - <LI>mod_cern_meta.c - <LI>mod_dir.c - <LI>mod_example.c - <LI>mod_expires.c - <LI>mod_headers.c - <LI>mod_imap.c - <LI>mod_info.c - <LI>mod_log_agent.c - <LI>mod_log_config.c - <LI>mod_log_referer.c - <LI>mod_mime.c - <LI>mod_negotiation.c - <LI>mod_setenvif.c - <LI>mod_speling.c - <LI>mod_userdir.c - <LI>mod_usertrack.c - <LI>os.c - <LI>os-inline.c - <LI>regular expression parser - <LI>util.c - <LI>util_date.c - <LI>util_uri.c - </UL></MULTICOL> - Please keep in mind that some major pieces are not yet in place including - standalone mode, pipes, password/group files, CGI scripts, and MD5 support. - <BR> - <A NAME="note_2"> </A> - <BR> - * virtual hosting requires TPF version 4.1 PUT09 - -<H3>Components/modules not (yet?) supported on TPF:</H3> - - <multicol COLS=3><UL> - <LI>htpasswd.c - <LI>md5c.c - <LI>mod_actions.c - <LI>mod_auth.c - <LI>mod_auth_anon.c - <LI>mod_cgi.c - <LI>mod_digest.c - <LI>mod_env.c - <LI>mod_include.c - <LI>mod_mime_magic.c - <LI>mod_proxy.c - <LI>mod_rewrite.c - <LI>mod_status.c - <LI>mod_unique_id.c - <LI>proxy_cache.c - <LI>proxy_connect.c - <LI>proxy_ftp.c - <LI>proxy_http.c - <LI>proxy_util.c - <LI>rfc1413.c - <LI>util_md5.c - <LI>util_script.c - </UL></MULTICOL> - -<H3>Components/modules that don't apply or that probably won't ever be available on TPF:</H3> - - <multicol COLS=3><UL> - <LI>gen_test.char.c - <LI>gen_uri_delims.c - <LI>mod_auth_db.c - <LI>mod_auth_dbm.c - <LI>mod_auth_db.module - <LI>mod_mmap_static.c - <LI>mod_so.c - </UL></MULTICOL> - -<A NAME="porting_notes"> </A> -<H2 align=center>Porting Notes</H2> -<P> - <H3>Changes made due to differences between UNIX and - TPF's process models:</H3> - <UL> - <LI><STRONG>Signals</STRONG>: On TPF a signal that is sent to a process - remains unhandled until the process explicitly requests that signals - be handled using the <CODE>tpf_process_signals()</CODE> function. - Additionally, the default action for an alarm on TPF is to take - an OPR-7777 dump and exit. (On UNIX the default is the equivalent - of <CODE>exit()</CODE> with no dump taken.) - These differences necessitated a few modifications: - <BR><BR> - <UL> - <LI>bypass the use of <CODE>ap_block_alarms()</CODE> & - <CODE>ap_unblock_alarms()</CODE> - <LI>add <CODE>tpf_process_signals()</CODE> calls - <LI>add <CODE>select()</CODE> calls in buff.c to prevent blocking. - </UL> - <BR> - </UL> - - <H3>Find that function...</H3> - <P>Some simple functions & definitions needed to be added - on TPF, such as <CODE>FD_SET()</CODE>. - We've put these in src/os/tpf/os.h for now. - </P> - - <H3>EBCDIC changes:</H3> - <P>TPF-specific conversion tables between US-ASCII and - EBCDIC (character set IBM-1047 to be exact) were created - and put into ebcdic.c in the src/os/tpf directory. - </P> - - <H3>Miscellaneous, minor changes:</H3> - <P>Various minor changes (such as casting) were made due to - differences in how some functions are implemented on TPF. - </P> - - <H3>Temporary changes:</H3> - <P>Lastly, we needed to bypass sections of Apache processing - since this first cut for TPF doesn't include - Standalone mode, pipes, forking, et cetera. - </P> - -<HR> -<CENTER>[ <A HREF="#top">top</A> - | <A HREF="#configuration_files">Configuration Files</A> - | <A HREF="#auto_generated_files">Auto Generated Files</A> - | <A HREF="#whats_available">What's Available</A> - | <A HREF="#porting_notes">Porting Notes</A> ] -</CENTER> - -</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 67eee003a2..0000000000 --- a/docs/manual/platform/windows.html +++ /dev/null @@ -1,488 +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.3 under Microsoft Windows. Please note that at - this time, Windows support is entirely experimental, and is - recommended only for experienced users. The Apache Group does not - guarantee that this software will work as documented, or even at - 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="#signal">Signalling Apache when running</A> - <LI><A HREF="#comp">Compiling Apache for Windows</A> -</UL> - -<HR> - -<H2><A NAME="req">Requirements</A></H2> - -Apache 1.3 is designed to run on Windows NT 4.0. The binary installer -will only work in Intel processors. Apache may also run on Windows 95, -Windows 98 and Windows NT 3.5.1, but these have not been tested. In -all cases TCP/IP networking must be installed. - -<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. - -<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 releases, -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. (If there is -no <SAMP>.zip</SAMP> file, the source will be available in a -<SAMP>.tar.gz</SAMP> file but this will contain Unix line endings. You -will have to convert at least the <SAMP>.mak</SAMP> and -<SAMP>.dsp</SAMP> files to have DOS line endings before MSVC will -understand them). - -<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> - -During the installation, Apache will configure the files in the -<SAMP>conf</SAMP> directory for your chosen installation -directory. However if any of the files in this directory already exist -they will <STRONG>not</STRONG> be overwritten. Instead the new copy of -the corresponding file will be left with the extension -<SAMP>.default</SAMP>. So, for example, if -<SAMP>conf\httpd.conf</SAMP> already exists it will not be altered, -but the version which would have been installed will be left in -<SAMP>conf\httpd.conf.default</SAMP>. After the installation has -finished you should manually check to see what in new in the -<SAMP>.default</SAMP> file, and if necessary update your existing -configuration files. - -<P> - -Also, if you already have a file called <SAMP>htdocs\index.html</SAMP> -then it will not be overwritten (no <SAMP>index.html.default</SAMP> -file will be installed either). This should mean it a safe to install -Apache over an existing installation (but you will have to stop the -existing server running before doing the installation, then start the -new one after the installation is finished). - -<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 quickly the files should work as installed. - -<H2><A NAME="run">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 <A HREF="#cmdline">console window</A>. 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 (NT only)" 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 "Start Apache as -console app" option from the Start menu (in Apache 1.3.4 and earlier, -this option was called "Apache Server"). 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, either select -the "Shutdown Apache console app" icon option from the Start menu -(this is not available in Apache 1.3.4 or earlier), or see <A -HREF="#signal">Signalling Apache when Running</A> for how -to control Apache from the command line. - -<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 (<EM>i.e.</EM>, 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 a simple -interface 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. Apache will try one of the following, in this order. - -<UL> -<LI>A ServerRoot directive via a -C switch. -<LI>The -f switch on the command line. -<LI>The -d switch on the command line. -<LI>A registry entry, created if you did a binary install. -<LI>The server root compiled into the server. -</UL> - -<P> -The server root compiled into the server is usually "/apache". -invoking apache with the -v switch will display this value -labeled as HTTPD_ROOT. - -<P> -Your current working directory when Apache is started up has no -effect on Apache's behavior. - -<P> -When invoked from the start menu or the Service Manager, Apache is -usually passed no arguments, so using the registry entry is the preferred -technique. - -<P> -During a binary installation, a registry key will have -been installed, for example: -<PRE> - HKEY_LOCAL_MACHINE\Software\Apache Group\Apache\1.3.4\ServerRoot -</PRE> - -<P> -This key is compiled into the server and can enable you to test -new versions without affecting the current version. Of course -you must take care not to install the new version on top of the -old version in the file system. You cannot run two invocations -of Apache on Windows simultaneously. - -<P> -If you did not do a binary install then Apache will in some -scenarios complain that about the missing registry key. This -warning can be ignored if it otherwise was able to find it's -configuration files. - -<P> -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> - -Apache will execute, and will remain running until it is stopped by pressing -control-C. (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.) - -<P> - -You can install Apache as a Windows NT service as follows: - -<PRE> - apache -i -</PRE> - -and to remove the Apache service, use - -<PRE> - apache -u -</PRE> - - -<H2><A NAME="signal">Signalling Apache when running</A></H2> - -On Windows 95, Apache runs as a console application. You can tell a -running Apache to stop by opening another console window and running - -<PRE> - apache -k shutdown -</PRE> -<BLOCKQUOTE> - <STRONG>Note: This option is only available with Apache 1.3.3 and - later. For earlier versions, you need to use Control-C in the - Apache console window to shut down the server.</STRONG> -</BLOCKQUOTE> - -<P> -This should be used instead of pressing Control-C in the running -Apache console window, because it lets Apache end any current -transactions and cleanup gracefully. - -<P> - -You can also tell Apache to restart. This makes it re-read the -configuration files. Any transactions in progress are allowed to -complete without interruption. To restart Apache, run - -<PRE> - apache -k restart -</PRE> -<BLOCKQUOTE> - <STRONG>Note: This option is only available with Apache 1.3.3 and - later. For earlier versions, you need to use Control-C in the - Apache console window to shut down the server.</STRONG> -</BLOCKQUOTE> - -<P> -Note for people familiar with the Unix version of Apache: these -commands provide a Windows equivalent to <CODE>kill -TERM -<EM>pid</EM></CODE> and <CODE>kill -USR1 <EM>pid</EM></CODE>. The command -line option used, <CODE>-k</CODE>, was chosen as a reminder of the -"kill" command used on Unix. - -<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, <EM>etc.</EM>..). 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 on Windows NT, simply - use one of the following commands: -<UL> -<LI><CODE>nmake /f Makefile.nt _apacher</CODE> (release build) -<LI><CODE>nmake /f Makefile.nt _apached</CODE> (debug build) -</UL> - -<P><em>(1.3.4 and later)</em> To compile Apache on Windows 95, use one of -<UL> -<LI><CODE>nmake /f Makefile_win32.txt</CODE> (release build) -<LI><CODE>nmake /f Makefile_win32_debug.txt</CODE> (debug build) -</UL> - -<P>These will both compile Apache. The latter will include debugging - information in the resulting files, making it easier to find bugs and - track down problems.</P> - -<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. - Project files (<CODE>.DSP</CODE>) are included for each of the - portions of Apache. To build Apache from the these projects files - you will need to build the following projects <EM>in this order</EM>: - - <OL> - <LI><CODE>os\win32\ApacheOS.dsp</CODE> - <LI><CODE>regex\regex.dsp</CODE> - <LI><CODE>ap\ap.dsp</CODE> - <LI><CODE>main\gen_uri_delims.dsp</CODE> - <LI><CODE>main\gen_test_char.dsp</CODE> - <LI><CODE>ApacheCore.dsp</CODE> - <LI><CODE>Apache.dsp</CODE> - </OL> - - In addition, the <CODE>src\os\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> -or, for Windows 95 (1.3.4 and later), use one of: -<UL> -<LI><CODE>nmake /f Makefile_win32.txt install INSTDIR=<EM>dir</EM></CODE> - (for release build) -<LI><CODE>nmake /f Makefile_win32_debug.txt install INSTDIR=<EM>dir</EM></CODE> - (for debug build) -</UL> - -The dir argument to INSTDIR gives the installation directory; it 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> - -<P> -Before running the server you must fill out the conf directory. -Copy the *.conf-dist-win from the distribution conf directory -and rename *.conf. Edit the @@ServerRoot@@ entries to your -actual server root (for example "C:\apache"). Copy over -the conf/magic and conf/mime.types files as well. - -<!--#include virtual="footer.html" --> -</BODY> -</HTML> diff --git a/docs/manual/sections.html.en b/docs/manual/sections.html.en deleted file mode 100644 index 88f3329408..0000000000 --- a/docs/manual/sections.html.en +++ /dev/null @@ -1,170 +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). Semantically however some things, and the most -notable are <CODE>AllowOverride</CODE> and the two options -<CODE>FollowSymLinks</CODE> and <CODE>SymLinksIfOwnerMatch</CODE>, -make no sense in <CODE><Location></CODE>, -<CODE><LocationMatch></CODE> or <CODE><DirectoryMatch></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> - -<P> -Note about .htaccess parsing: -</P> -<UL> -<LI> - Modifying .htaccess parsing during Location doesn't do - anything because .htaccess parsing has already occurred. -</UL> - -<P> -<CODE><Location></CODE> and symbolic links: -</P> -<UL> -<LI> - It is not possible to use "<CODE>Options FollowSymLinks</CODE>" - or "<CODE>Options SymLinksIfOwnerMatch</CODE>" inside a - <CODE><Location></CODE>, <CODE><LocationMatch></CODE> - or <CODE><DirectoryMatch></CODE> section - (the options are simply ignored). - Using the options in question is only possible inside a - <CODE><Directory></CODE> section (or a <CODE>.htaccess</CODE> file). -</UL> - -<P> -<CODE><Files></CODE> and <CODE>Options</CODE>: -</P> -<UL> -<LI> - Apache won't check for it, but using an <CODE>Options</CODE> - directive inside a <CODE><Files></CODE> section has no effect. -</UL> - -<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 fe5889cfe6..0000000000 --- a/docs/manual/stopping.html.en +++ /dev/null @@ -1,178 +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>This document covers stopping and restarting Apache on Unix -only. Windows users should see <A HREF="windows.html#signal">Signalling -Apache when running</A>.</P> - -<P>You will notice many <CODE>httpd</CODE> executables running on your system, -but you should not send signals to any of them except the parent, whose -pid is in the <A HREF="mod/core.html#pidfile">PidFile</A>. That is to -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 3d8623df04..0000000000 --- a/docs/manual/suexec.html.en +++ /dev/null @@ -1,518 +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="#usage">Using 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="#jabberwock">"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. If you use Apache 1.2 or prefer to configure -Apache 1.3 with the "<CODE>src/Configure</CODE>" script you have to edit -the suEXEC header file and install the binary in its proper location -manually. This procedure is described in an -<A HREF="suexec_1_2.html">extra document</A>. -The following sections describe the configuration and installation -for Apache 1.3 with the AutoConf-style interface (APACI). -</P> - -<P ALIGN="LEFT"> -<STRONG>APACI's suEXEC configuration options</STRONG><BR> -<DL> -<DT><CODE>--enable-suexec</CODE> -<DD>This option enables the suEXEC feature which is never installed or - activated by default. At least one --suexec-xxxxx option has to be - provided together with the --enable-suexec option to let APACI - accept your request for using the suEXEC feature. -<DT><CODE>--suexec-caller=<EM>UID</EM></CODE> -<DD>The <A HREF="mod/core.html#user">username</A> under which - Apache normally runs. - This is the only user allowed to execute this program. -<DT><CODE>--suexec-docroot=<EM>DIR</EM></CODE> -<DD>Define as the DocumentRoot set for Apache. - This will be the only hierarchy (aside from UserDirs) - that can be used for suEXEC behavior. - The default directory is the --datadir value with - the suffix "/htdocs", <EM>e.g.</EM> if you configure with - "<CODE>--datadir=/home/apache</CODE>" the directory - "/home/apache/htdocs" is used as document root for - the suEXEC wrapper. -<DT><CODE>--suexec-logfile=<EM>FILE</EM></CODE> -<DD>This defines the filename to which all suEXEC transactions and - errors are logged (useful for auditing and debugging purposes). - By default the logfile is named "suexec_log" and located in your - standard logfile directory (--logfiledir). -<DT><CODE>--suexec-userdir=<EM>DIR</EM></CODE> -<DD>Define to be the subdirectory under users' - home directories where suEXEC access should - be allowed. All executables under this directory - will be executable by suEXEC as the user so - they should be "safe" programs. If you are - using a "simple" UserDir directive (ie. one - without a "*" in it) this should be set to - the same value. suEXEC will not work properly - in cases where the UserDir directive points to - a location that is not the same as the user's - home directory as referenced in the passwd file. - Default value is "public_html". - <BR> - If you have virtual hosts with a different - UserDir for each, you will need to define them to - all reside in one parent directory; then name that - parent directory here. <STRONG>If this is not defined - properly, "~userdir" cgi requests will not work!</STRONG> -<DT><CODE>--suexec-uidmin=<EM>UID</EM></CODE> -<DD>Define this as the lowest UID allowed to be a target user - for suEXEC. For most systems, 500 or 100 is common. - Default value is 100. -<DT><CODE>--suexec-gidmin=<EM>GID</EM></CODE> -<DD>Define this as the lowest GID allowed to be a target group - for suEXEC. For most systems, 100 is common and therefore - used as default value. -<DT><CODE>--suexec-safepath=<EM>PATH</EM></CODE> -<DD>Define a safe PATH environment to pass to CGI executables. - Default value is "/usr/local/bin:/usr/bin:/bin". -</DL> -</P> - -<P ALIGN="LEFT"> -<STRONG>Checking your suEXEC setup</STRONG><BR> -Before you compile and install the suEXEC wrapper you can check -the configuration with the --layout option. -<BR> -Example output: -<PRE> - suEXEC setup: - suexec binary: /usr/local/apache/sbin/suexec - document root: /usr/local/apache/share/htdocs - userdir suffix: public_html - logfile: /usr/local/apache/var/log/suexec_log - safe path: /usr/local/bin:/usr/bin:/bin - caller ID: www - minimum user ID: 100 - minimum group ID: 100 -</PRE> -</P> - -<P ALIGN="LEFT"> -<STRONG>Compiling and installing the suEXEC wrapper</STRONG><BR> -If you have enabled the suEXEC feature with the --enable-suexec option -the suexec binary (together with Apache itself) is automatically built -if you execute the command "make". -<BR> -After all components have been built you can execute the command -"make install" to install them. -The binary image "suexec" is installed in the directory defined by -the --sbindir option. Default location is "/usr/local/apache/sbin/suexec". -<BR> -Please note that you need <STRONG><EM>root privileges</EM></STRONG> for -the installation step. In order for the wrapper to set the user ID, it -must be installed as owner <CODE><EM>root</EM></CODE> and must have the -setuserid execution bit set for file modes. -</P> - -<P ALIGN="CENTER"> -<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> -</P> - -<H3><A NAME="enable">Enabling & Disabling suEXEC</A></H3> -<P ALIGN="LEFT"> -Upon startup of Apache, it looks for the file "suexec" in the "sbin" -directory (default is "/usr/local/apache/sbin/suexec"). -If Apache finds a properly configured suEXEC wrapper, it will print -the following message to the error log: -<PRE> - [notice] suEXEC mechanism enabled (wrapper: <EM>/path/to/suexec</EM>) -</PRE> -If you don't see this message at server startup, the server is most -likely not finding the wrapper program where it expects it, or the -executable is not installed <EM>setuid root</EM>. -<BR> -If you want to enable the suEXEC mechanism for the first time -and an Apache server is already running you must kill and restart Apache. -Restarting it with a simple HUP or USR1 signal will not be enough. -<BR> -If you want to disable suEXEC you should kill and restart Apache after -you have removed the "suexec" file. -</P> - -<P ALIGN="CENTER"> -<STRONG><A HREF="suexec.html">BACK TO CONTENTS</A></STRONG> -</P> - -<H3><A NAME="usage">Using suEXEC</A></H3> -<P ALIGN="LEFT"> -<STRONG>Virtual Hosts:</STRONG><BR> -One way to use the suEXEC wrapper is through the -<A HREF="mod/core.html#user">User</A> and -<A HREF="mod/core.html#group">Group</A> directives in -<A HREF="mod/core.html#virtualhost">VirtualHost</A> -definitions. By setting these directives to values different from the -main server user ID, all requests for CGI resources will be executed as -the <EM>User</EM> and <EM>Group</EM> defined for that -<CODE><VirtualHost></CODE>. If only one or -neither of these directives are specified for a -<CODE><VirtualHost></CODE> then the main -server userid is assumed. -<P> -<STRONG>User directories:</STRONG><BR> -The suEXEC wrapper can also be used to execute CGI programs as -the user to which the request is being directed. This is accomplished by -using the "<STRONG><CODE>~</CODE></STRONG>" character prefixing the user -ID for whom execution is desired. -The only requirement needed for this feature to work is for CGI -execution to be enabled for the user and that the script must meet the -scrutiny of the <A HREF="#model">security checks</A> above. - -<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 file defined -with the --suexec-logfile option as indicated above. If you feel you have -configured and installed the wrapper properly, have a look at this log -and the error_log for the server to see where you may have gone astray. -</P> - -<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 9a569028cf..0000000000 --- a/docs/manual/vhosts/index.html.en +++ /dev/null @@ -1,65 +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> -<LI><A HREF="mass.html">Dynamically Configured Mass Virtual Hosting with mod_rewrite</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 238cf5c721..0000000000 --- a/docs/manual/vhosts/name-based.html.en +++ /dev/null @@ -1,164 +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. The notable difference between IP-based and -name-based virtual host configuration is the -<A HREF="../mod/core.html#namevirtualhost"><CODE>NameVirtualHost</CODE></A> -directive which specifies an IP address that should be used as a -target for name-based virtual hosts.</P> - -<P>For example, suppose that both <SAMP>www.domain.tld</SAMP> and -<SAMP>www.otherdomain.tld</SAMP> point at the IP address -<SAMP>111.22.33.44</SAMP>. Then you simply add to one of the Apache -configuration files (most likely <CODE>httpd.conf</CODE> or -<CODE>srm.conf</CODE>) code similar to the following:</P> - - - -<PRE> - NameVirtualHost 111.22.33.44 - - <VirtualHost 111.22.33.44> - ServerName www.domain.tld - DocumentRoot /www/domain - </VirtualHost> - - <VirtualHost 111.22.33.44> - ServerName www.otherdomain.tld - DocumentRoot /www/otherdomain - </VirtualHost> -</PRE> - -<P>Of course, any additional directives can (and should) be placed -into the <CODE><VirtualHost></CODE> section. To make this work, -all that is needed is to make sure that the names -<SAMP>www.domain.tld</SAMP> and <SAMP>www.otherdomain.tld</SAMP> -are pointing to the IP address <SAMP>111.22.33.44</SAMP></P> - -<P>Note: When you specify an IP address in a <CODE>NameVirtualHost</CODE> -directive then requests to that IP address will only ever be served -by matching <VirtualHost>s. The "main server" will -<STRONG>never</STRONG> be served from the specified IP address. -If you start to use virtual hosts you should stop to use the "main server" -as an independent server and rather use it as a place for -configuration directives that are common for all your virtual hosts. -In other words, you should add a <VirtualHost> section for -<EM>every</EM> server (hostname) you want to maintain on your server. - -<P>Additionally, many servers may wish to be accessible by more than -one name. For example, the example server might want to be accessible -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. -The <CODE>ServerAlias</CODE> directive is generally a way to have different -hostnames pointing to the same virtual host. -</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 -first virtual host listed for that IP address (the -<CITE>primary</CITE> name-based virtual host).</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 (<EM>e.g.</EM>, "<SAMP>file.html</SAMP>" or -"<SAMP>../icons/image.gif</SAMP>" or links containing the prefacing -<SAMP>/domain/</SAMP> -(<EM>e.g.</EM>, "<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> |
