diff options
| author | paul <paul@unknown> | 1996-11-18 20:51:08 +0100 |
|---|---|---|
| committer | paul <paul@unknown> | 1996-11-18 20:51:08 +0100 |
| commit | 2ada5933c85b2ca45770c2df27e2d292667f36c4 (patch) | |
| tree | 53c64bebbb2a1da979c0ac496b2db09ba38c495d | |
| parent | Added a test index.html file and an image to a default htdocs directory to (diff) | |
| download | apache2-2ada5933c85b2ca45770c2df27e2d292667f36c4.tar.xz apache2-2ada5933c85b2ca45770c2df27e2d292667f36c4.zip | |
New manual setup. This is the current docs for all versions of the
server merged into a single manual.
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@76987 13f79535-47bb-0310-9956-ffa450edef68
| -rw-r--r-- | docs/manual/LICENSE | 51 | ||||
| -rw-r--r-- | docs/manual/bind.html | 103 | ||||
| -rw-r--r-- | docs/manual/bind.html.en | 103 | ||||
| -rw-r--r-- | docs/manual/content-negotiation.html | 216 | ||||
| -rw-r--r-- | docs/manual/content-negotiation.html.en | 216 | ||||
| -rw-r--r-- | docs/manual/custom-error.html | 109 | ||||
| -rw-r--r-- | docs/manual/custom-error.html.en | 109 | ||||
| -rw-r--r-- | docs/manual/handler.html | 138 | ||||
| -rw-r--r-- | docs/manual/handler.html.en | 138 | ||||
| -rw-r--r-- | docs/manual/install.html | 109 | ||||
| -rw-r--r-- | docs/manual/install.html.en | 109 | ||||
| -rw-r--r-- | docs/manual/invoking.html | 108 | ||||
| -rw-r--r-- | docs/manual/invoking.html.en | 108 | ||||
| -rw-r--r-- | docs/manual/location.html | 58 | ||||
| -rw-r--r-- | docs/manual/process-model.html | 50 |
15 files changed, 1725 insertions, 0 deletions
diff --git a/docs/manual/LICENSE b/docs/manual/LICENSE new file mode 100644 index 0000000000..0d3053a52e --- /dev/null +++ b/docs/manual/LICENSE @@ -0,0 +1,51 @@ + +Apache httpd license + ==================== + + +This is the license for the Apache Server. It covers all the +files which come in this distribution, and should never be removed. + +The "Apache Group" has based this server, called "Apache", on +public domain code distributed under the name "NCSA httpd 1.3". + +NCSA httpd 1.3 was placed in the public domain by the National Center +for Supercomputing Applications at the University of Illinois +at Urbana-Champaign. + +As requested by NCSA we acknowledge, + + "Portions developed at the National Center for Supercomputing + Applications at the University of Illinois at Urbana-Champaign." + +Copyright on the sections of code added by the "Apache Group" belong +to the "Apache Group" and/or the original authors. The "Apache Group" and +authors hereby grant permission for their code, along with the +public domain NCSA code, to be distributed under the "Apache" name. + +Reuse of "Apache Group" code outside of the Apache distribution should +be acknowledged with the following quoted text, to be included with any new +work; + + "Portions developed by the "Apache Group", taken with permission + from the Apache Server http://www.hyperreal.com/apache/ " + + +Permission is hereby granted to anyone to redistribute Apache under +the "Apache" name. We do not grant permission for the resale of Apache, but +we do grant permission for vendors to bundle Apache free with other software, +or to charge a reasonable price for redistribution, provided it is made +clear that Apache is free. Permission is also granted for vendors to +sell support for for Apache. We explicitly forbid the redistribution of +Apache under any other name. + +The "Apache Group" makes no promises to support "Apache". Users and +sellers of Apache support, and users of "Apache Group" code, should be +aware that they use "Apache" or portions of the "Apache Group" code at +their own risk. While every effort has been made to ensure that "Apache" +is robust and safe to use, we will not accept responsibility for any +damage caused, or loss of data or income which results from its use. + + + +Apache httpd server (c) 1995 The Apache Group. diff --git a/docs/manual/bind.html b/docs/manual/bind.html new file mode 100644 index 0000000000..777f79650f --- /dev/null +++ b/docs/manual/bind.html @@ -0,0 +1,103 @@ +<html><head> +<title>Setting which addresses and ports Apache uses</title> +</head><body> + +<img src="../images/apache_sub.gif" alt=""> +<h1>Setting which addresses and ports Apache uses</h1> + +<hr> + +When Apache starts, it connects to some port and address on the +local machine and waits for incoming requests. By default, it +listens to all addresses on the machine, and to the port +as specified by the <tt>Port</tt> directive in the server configuration. +However, it can be told to listen to more the one port, or to listen +to only selected addresses, or a combination. This is often combined +with the Virtual Host feature which determines how Apache +responds to different IP addresses, hostnames and ports.<p> + +There are two directives used to restrict or specify which addresses +and ports Apache listens to. + +<ul> +<li><a href="#bindaddress">BindAddress</a> is used to restrict the server to listening to + a single address, and can be used to permit multiple Apache servers + on the same machine listening to different IP addresses. +<li><a href="#listen">Listen</a> can be used to make a single Apache server listen + to more than one address and/or port. +</ul> + +<h3><a name="bindaddress">BindAddress</a></h3> +<strong>Syntax:</strong> BindAddress <em>[ * | IP-address | hostname ]</em><br> +<strong>Default:</strong> <code>BindAddress *</code><br> +<strong>Context:</strong> server config<br> +<strong>Status:</strong> Core<p> + +Makes the server listen to just the specified address. If the argument +is *, the server listens to all addresses. The port listened to +is set with the <tt>Port</tt> directive. Only one BindAddress +should be used. + +<h3><a name="listen">Listen</a></h3> +<strong>Syntax:</strong> Listen <em>[ port | IP-address:port ]</em><br> +<strong>Default:</strong> <code>none</code><br> +<strong>Context:</strong> server config<br> +<strong>Status:</strong> Core<p> + +<tt>Listen</tt> can be used instead of <tt>BindAddress</tt> and +<tt>Port</tt>. It tells the server to accept incoming requests on the +specified port or address-and-port combination. If the first format is +used, with a port number only, the server listens to the given port on +all interfaces, instead of the port given by the <tt>Port</tt> +directive. If an IP address is given as well as a port, the server +will listen on the given port and interface. <p> Multiple Listen +directives may be used to specify a number of addresses and ports to +listen to. The server will respond to requests from any of the listed +addresses and ports.<p> + +For example, to make the server accept connections on both port +80 and port 8000, use: +<pre> + Listen 80 + Listen 8000 +</pre> + +To make the server accept connections on two specified +interfaces and port numbers, use +<pre> + Listen 192.170.2.1:80 + Listen 192.170.2.5:8000 +</pre> + +<h2>How this works with Virtual Hosts</h2> + +BindAddress and Listen do not implement Virtual Hosts. They tell the +main server what addresses and ports to listen to. If no +<VirtualHost> directives are used, the server will behave the +same for all accepted requests. However, <VirtualHost> can be +used to specify a different behavour for one or more of the addresses +and ports. To implement a VirtualHost, the server must first be told +to listen to the address and port to be used. Then a +<VirtualHost> section should be created for a specified address +and port to set the behaviour of this virtual host. Note that if the +<VirtualHost> is set for an address and port that the server is +not listening to, it cannot be accessed. + +<h2>See also</h2> + +See also the documentation on +<a href="virtual-host.html">Virtual Hosts</a>, +<a href="host.html">Non-IP virtual hosts</a>, +<a href="core.html#bindaddress">BindAddress directive</a>, +<a href="core.html#port">Port directive</a> +and +<a href="core.html#virtualhost"><VirtualHost> section</a>. +</ul> + +<hr> +<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> +<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> + +</BODY> +</HTML> + diff --git a/docs/manual/bind.html.en b/docs/manual/bind.html.en new file mode 100644 index 0000000000..777f79650f --- /dev/null +++ b/docs/manual/bind.html.en @@ -0,0 +1,103 @@ +<html><head> +<title>Setting which addresses and ports Apache uses</title> +</head><body> + +<img src="../images/apache_sub.gif" alt=""> +<h1>Setting which addresses and ports Apache uses</h1> + +<hr> + +When Apache starts, it connects to some port and address on the +local machine and waits for incoming requests. By default, it +listens to all addresses on the machine, and to the port +as specified by the <tt>Port</tt> directive in the server configuration. +However, it can be told to listen to more the one port, or to listen +to only selected addresses, or a combination. This is often combined +with the Virtual Host feature which determines how Apache +responds to different IP addresses, hostnames and ports.<p> + +There are two directives used to restrict or specify which addresses +and ports Apache listens to. + +<ul> +<li><a href="#bindaddress">BindAddress</a> is used to restrict the server to listening to + a single address, and can be used to permit multiple Apache servers + on the same machine listening to different IP addresses. +<li><a href="#listen">Listen</a> can be used to make a single Apache server listen + to more than one address and/or port. +</ul> + +<h3><a name="bindaddress">BindAddress</a></h3> +<strong>Syntax:</strong> BindAddress <em>[ * | IP-address | hostname ]</em><br> +<strong>Default:</strong> <code>BindAddress *</code><br> +<strong>Context:</strong> server config<br> +<strong>Status:</strong> Core<p> + +Makes the server listen to just the specified address. If the argument +is *, the server listens to all addresses. The port listened to +is set with the <tt>Port</tt> directive. Only one BindAddress +should be used. + +<h3><a name="listen">Listen</a></h3> +<strong>Syntax:</strong> Listen <em>[ port | IP-address:port ]</em><br> +<strong>Default:</strong> <code>none</code><br> +<strong>Context:</strong> server config<br> +<strong>Status:</strong> Core<p> + +<tt>Listen</tt> can be used instead of <tt>BindAddress</tt> and +<tt>Port</tt>. It tells the server to accept incoming requests on the +specified port or address-and-port combination. If the first format is +used, with a port number only, the server listens to the given port on +all interfaces, instead of the port given by the <tt>Port</tt> +directive. If an IP address is given as well as a port, the server +will listen on the given port and interface. <p> Multiple Listen +directives may be used to specify a number of addresses and ports to +listen to. The server will respond to requests from any of the listed +addresses and ports.<p> + +For example, to make the server accept connections on both port +80 and port 8000, use: +<pre> + Listen 80 + Listen 8000 +</pre> + +To make the server accept connections on two specified +interfaces and port numbers, use +<pre> + Listen 192.170.2.1:80 + Listen 192.170.2.5:8000 +</pre> + +<h2>How this works with Virtual Hosts</h2> + +BindAddress and Listen do not implement Virtual Hosts. They tell the +main server what addresses and ports to listen to. If no +<VirtualHost> directives are used, the server will behave the +same for all accepted requests. However, <VirtualHost> can be +used to specify a different behavour for one or more of the addresses +and ports. To implement a VirtualHost, the server must first be told +to listen to the address and port to be used. Then a +<VirtualHost> section should be created for a specified address +and port to set the behaviour of this virtual host. Note that if the +<VirtualHost> is set for an address and port that the server is +not listening to, it cannot be accessed. + +<h2>See also</h2> + +See also the documentation on +<a href="virtual-host.html">Virtual Hosts</a>, +<a href="host.html">Non-IP virtual hosts</a>, +<a href="core.html#bindaddress">BindAddress directive</a>, +<a href="core.html#port">Port directive</a> +and +<a href="core.html#virtualhost"><VirtualHost> section</a>. +</ul> + +<hr> +<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> +<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> + +</BODY> +</HTML> + diff --git a/docs/manual/content-negotiation.html b/docs/manual/content-negotiation.html new file mode 100644 index 0000000000..20825f3661 --- /dev/null +++ b/docs/manual/content-negotiation.html @@ -0,0 +1,216 @@ +<html> +<head> +<title>Apache server Content arbitration: MultiViews and *.var files</title> +</head> + +<body> +<IMG SRC="../images/apache_sub.gif" ALT=""> +<h3>Content Arbitration: MultiViews and *.var files</h3> + +The HTTP standard allows clients (i.e., browsers like Mosaic or +Netscape) to specify what data formats they are prepared to accept. +The intention is that when information is available in multiple +variants (e.g., in different data formats), servers can use this +information to decide which variant to send. This feature has been +supported in the CERN server for a while, and while it is not yet +supported in the NCSA server, it is likely to assume a new importance +in light of the emergence of HTML3 capable browsers. <p> + +The Apache module <A HREF="mod_negotiation.html">mod_negotiation</A> handles +content negotiation in two different ways; special treatment for the +pseudo-mime-type <code>application/x-type-map</code>, and the +MultiViews per-directory Option (which can be set in srm.conf, or in +.htaccess files, as usual). These features are alternate user +interfaces to what amounts to the same piece of code (in the new file +<code>http_mime_db.c</code>) which implements the content negotiation +portion of the HTTP protocol. <p> + +Each of these features allows one of several files to satisfy a +request, based on what the client says it's willing to accept; the +differences are in the way the files are identified: + +<ul> + <li> A type map (i.e., a <code>*.var</code> file) names the files + containing the variants explicitly + <li> In a MultiViews search, the server does an implicit filename + pattern match, and chooses from among the results. +</ul> + +Apache also supports a new pseudo-MIME type, +text/x-server-parsed-html3, which is treated as text/html;level=3 +for purposes of content negotiation, and as server-side-included HTML +elsewhere. + +<h3>Type maps (*.var files)</h3> + +A type map is a document which is typed by the server (using its +normal suffix-based mechanisms) as +<code>application/x-type-map</code>. Note that to use this feature, +you've got to have an <code>AddType</code> some place which defines a +file suffix as <code>application/x-type-map</code>; the easiest thing +may be to stick a +<pre> + + AddType application/x-type-map var + +</pre> +in <code>srm.conf</code>. See comments in the sample config files for +details. <p> + +Type map files have an entry for each available variant; these entries +consist of contiguous RFC822-format header lines. Entries for +different variants are separated by blank lines. Blank lines are +illegal within an entry. It is conventional to begin a map file with +an entry for the combined entity as a whole, e.g., +<pre> + + URI: foo; vary="type,language" + + URI: foo.en.html + Content-type: text/html; level=2 + Content-language: en + + URI: foo.fr.html + Content-type: text/html; level=2 + Content-language: fr + +</pre> +If the variants have different qualities, that may be indicated by the +"qs" parameter, as in this picture (available as jpeg, gif, or ASCII-art): +<pre> + + URI: foo; vary="type,language" + + 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> + +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 --- level may be specified, along with "qs". 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 language of the variant, specified as an internet standard + language code (e.g., <code>en</code> for English, + <code>kr</code> for Korean, etc.). + <dt> <code>Content-encoding:</code> + <dd> If the file is compressed, or otherwise encoded, rather than + containing the actual raw data, this says how that was done. + For compressed files (the only case where this generally comes + up), content encoding should be + <code>x-compress</code>, or <code>gzip</code>, as appropriate. + <dt> <code>Content-length:</code> + <dd> The size of the file. Clients can ask to receive a given media + type only if the variant isn't too big; specifying a content + length in the map allows the server to compare against these + thresholds without checking the actual file. +</dl> + +<h3>Multiviews</h3> + +This is a per-directory option, meaning it can be set with an +<code>Options</code> directive within a <code><Directory></code> +section in <code>access.conf</code>, or (if <code>AllowOverride</code> +is properly set) in <code>.htaccess</code> files. Note that +<code>Options All</code> does not set <code>MultiViews</code>; you +have to ask for it by name. (Fixing this is a one-line change to +<code>httpd.h</code>). + +<p> + +The effect of <code>MultiViews</code> is as follows: if the server +receives a request for <code>/some/dir/foo</code>, if +<code>/some/dir</code> has <code>MultiViews</code> enabled, and +<code>/some/dir/foo</code> does *not* exist, then the server reads the +directory looking for files named foo.*, and effectively fakes up a +type map which names all those files, assigning them the same media +types and content-encodings it would have if the client had asked for +one of them by name. It then chooses the best match to the client's +requirements, and forwards them along. + +<p> + +This applies to searches for the file named by the +<code>DirectoryIndex</code> directive, if the server is trying to +index a directory; if the configuration files specify +<pre> + + DirectoryIndex index + +</pre> then the server will arbitrate between <code>index.html</code> +and <code>index.html3</code> if both are present. If neither are +present, and <code>index.cgi</code> is there, the server will run it. + +<p> + +If one of the files found by the globbing is a CGI script, it's not +obvious what should happen. My code gives that case gets 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. This is the only jiggering of quality ratings done by the +MultiViews code; aside from that, all Qualities in the synthesized +type maps are 1.0. + +<p> + +<B>New as of 0.8:</B> Documents in multiple languages can also be resolved through the use +of the <code>AddLanguage</code> and <code>LanguagePriority</code> +directives: + +<pre> +AddLanguage en .en +AddLanguage fr .fr +AddLanguage de .de +AddLanguage da .da +AddLanguage el .el +AddLanguage it .it + +# LanguagePriority allows you to give precedence to some languages +# in case of a tie during content negotiation. +# Just list the languages in decreasing order of preference. + +LanguagePriority en fr de +</pre> + +Here, a request for "foo.html" matched against "foo.html.en" and +"foo.html.fr" would return an French document to a browser that +indicated a preference for French, or an English document otherwise. +In fact, a request for "foo" matched against "foo.html.en", +"foo.html.fr", "foo.ps.en", "foo.pdf.de", and "foo.txt.it" would do +just what you expect - treat those suffices as a database and compare +the request to it, returning the best match. The languages and data +types share the same suffix name space. + +<p> + +Note that this machinery only comes into play if the file which the +user attempted to retrieve does <em>not</em> exist by that name; if it +does, it is simply retrieved as usual. (So, someone who actually asks +for <code>foo.jpeg</code>, as opposed to <code>foo</code>, never gets +<code>foo.gif</code>). + +<P><HR><P> +<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> +<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> + +</body> </html> diff --git a/docs/manual/content-negotiation.html.en b/docs/manual/content-negotiation.html.en new file mode 100644 index 0000000000..20825f3661 --- /dev/null +++ b/docs/manual/content-negotiation.html.en @@ -0,0 +1,216 @@ +<html> +<head> +<title>Apache server Content arbitration: MultiViews and *.var files</title> +</head> + +<body> +<IMG SRC="../images/apache_sub.gif" ALT=""> +<h3>Content Arbitration: MultiViews and *.var files</h3> + +The HTTP standard allows clients (i.e., browsers like Mosaic or +Netscape) to specify what data formats they are prepared to accept. +The intention is that when information is available in multiple +variants (e.g., in different data formats), servers can use this +information to decide which variant to send. This feature has been +supported in the CERN server for a while, and while it is not yet +supported in the NCSA server, it is likely to assume a new importance +in light of the emergence of HTML3 capable browsers. <p> + +The Apache module <A HREF="mod_negotiation.html">mod_negotiation</A> handles +content negotiation in two different ways; special treatment for the +pseudo-mime-type <code>application/x-type-map</code>, and the +MultiViews per-directory Option (which can be set in srm.conf, or in +.htaccess files, as usual). These features are alternate user +interfaces to what amounts to the same piece of code (in the new file +<code>http_mime_db.c</code>) which implements the content negotiation +portion of the HTTP protocol. <p> + +Each of these features allows one of several files to satisfy a +request, based on what the client says it's willing to accept; the +differences are in the way the files are identified: + +<ul> + <li> A type map (i.e., a <code>*.var</code> file) names the files + containing the variants explicitly + <li> In a MultiViews search, the server does an implicit filename + pattern match, and chooses from among the results. +</ul> + +Apache also supports a new pseudo-MIME type, +text/x-server-parsed-html3, which is treated as text/html;level=3 +for purposes of content negotiation, and as server-side-included HTML +elsewhere. + +<h3>Type maps (*.var files)</h3> + +A type map is a document which is typed by the server (using its +normal suffix-based mechanisms) as +<code>application/x-type-map</code>. Note that to use this feature, +you've got to have an <code>AddType</code> some place which defines a +file suffix as <code>application/x-type-map</code>; the easiest thing +may be to stick a +<pre> + + AddType application/x-type-map var + +</pre> +in <code>srm.conf</code>. See comments in the sample config files for +details. <p> + +Type map files have an entry for each available variant; these entries +consist of contiguous RFC822-format header lines. Entries for +different variants are separated by blank lines. Blank lines are +illegal within an entry. It is conventional to begin a map file with +an entry for the combined entity as a whole, e.g., +<pre> + + URI: foo; vary="type,language" + + URI: foo.en.html + Content-type: text/html; level=2 + Content-language: en + + URI: foo.fr.html + Content-type: text/html; level=2 + Content-language: fr + +</pre> +If the variants have different qualities, that may be indicated by the +"qs" parameter, as in this picture (available as jpeg, gif, or ASCII-art): +<pre> + + URI: foo; vary="type,language" + + 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> + +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 --- level may be specified, along with "qs". 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 language of the variant, specified as an internet standard + language code (e.g., <code>en</code> for English, + <code>kr</code> for Korean, etc.). + <dt> <code>Content-encoding:</code> + <dd> If the file is compressed, or otherwise encoded, rather than + containing the actual raw data, this says how that was done. + For compressed files (the only case where this generally comes + up), content encoding should be + <code>x-compress</code>, or <code>gzip</code>, as appropriate. + <dt> <code>Content-length:</code> + <dd> The size of the file. Clients can ask to receive a given media + type only if the variant isn't too big; specifying a content + length in the map allows the server to compare against these + thresholds without checking the actual file. +</dl> + +<h3>Multiviews</h3> + +This is a per-directory option, meaning it can be set with an +<code>Options</code> directive within a <code><Directory></code> +section in <code>access.conf</code>, or (if <code>AllowOverride</code> +is properly set) in <code>.htaccess</code> files. Note that +<code>Options All</code> does not set <code>MultiViews</code>; you +have to ask for it by name. (Fixing this is a one-line change to +<code>httpd.h</code>). + +<p> + +The effect of <code>MultiViews</code> is as follows: if the server +receives a request for <code>/some/dir/foo</code>, if +<code>/some/dir</code> has <code>MultiViews</code> enabled, and +<code>/some/dir/foo</code> does *not* exist, then the server reads the +directory looking for files named foo.*, and effectively fakes up a +type map which names all those files, assigning them the same media +types and content-encodings it would have if the client had asked for +one of them by name. It then chooses the best match to the client's +requirements, and forwards them along. + +<p> + +This applies to searches for the file named by the +<code>DirectoryIndex</code> directive, if the server is trying to +index a directory; if the configuration files specify +<pre> + + DirectoryIndex index + +</pre> then the server will arbitrate between <code>index.html</code> +and <code>index.html3</code> if both are present. If neither are +present, and <code>index.cgi</code> is there, the server will run it. + +<p> + +If one of the files found by the globbing is a CGI script, it's not +obvious what should happen. My code gives that case gets 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. This is the only jiggering of quality ratings done by the +MultiViews code; aside from that, all Qualities in the synthesized +type maps are 1.0. + +<p> + +<B>New as of 0.8:</B> Documents in multiple languages can also be resolved through the use +of the <code>AddLanguage</code> and <code>LanguagePriority</code> +directives: + +<pre> +AddLanguage en .en +AddLanguage fr .fr +AddLanguage de .de +AddLanguage da .da +AddLanguage el .el +AddLanguage it .it + +# LanguagePriority allows you to give precedence to some languages +# in case of a tie during content negotiation. +# Just list the languages in decreasing order of preference. + +LanguagePriority en fr de +</pre> + +Here, a request for "foo.html" matched against "foo.html.en" and +"foo.html.fr" would return an French document to a browser that +indicated a preference for French, or an English document otherwise. +In fact, a request for "foo" matched against "foo.html.en", +"foo.html.fr", "foo.ps.en", "foo.pdf.de", and "foo.txt.it" would do +just what you expect - treat those suffices as a database and compare +the request to it, returning the best match. The languages and data +types share the same suffix name space. + +<p> + +Note that this machinery only comes into play if the file which the +user attempted to retrieve does <em>not</em> exist by that name; if it +does, it is simply retrieved as usual. (So, someone who actually asks +for <code>foo.jpeg</code>, as opposed to <code>foo</code>, never gets +<code>foo.gif</code>). + +<P><HR><P> +<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> +<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> + +</body> </html> diff --git a/docs/manual/custom-error.html b/docs/manual/custom-error.html new file mode 100644 index 0000000000..31c955a2c4 --- /dev/null +++ b/docs/manual/custom-error.html @@ -0,0 +1,109 @@ +<HTML> +<HEAD> +<TITLE>Ccustom error responses</TITLE> +</HEAD> + +<BODY> +<IMG SRC="../images/apache_sub.gif" ALT=""> +<H1>Custom error responses</H1> +<DL> +<DT>Purpose +<DD>Additional functionality. Allows webmasters to configure the response of +Apache to some error or problem.<BR> +<P>Customizable responses can be defined to be activated in the event of a +server detected error or problem.<BR> +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). +<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><BR> +<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.<BR>To achieve this, Apache will define new CGI-like environment +variables, e.g. +<blockquote><code> +REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/x-xbitmap, image/jpeg <br> +REDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX A.09.05 9000/712) <br> +REDIRECT_PATH=.:/bin:/usr/local/bin:/etc <br> +REDIRECT_QUERY_STRING= <br> +REDIRECT_REMOTE_ADDR=121.345.78.123 <br> +REDIRECT_REMOTE_HOST=ooh.ahhh.com <br> +REDIRECT_SERVER_NAME=crash.bang.edu <br> +REDIRECT_SERVER_PORT=80 <br> +REDIRECT_SERVER_SOFTWARE=Apache/0.8.15 <br> +REDIRECT_URL=/cgi-bin/buggy.pl <br> +</code></blockquote> + +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.<p> + +<DT>Configuration +<DD><em>file: </em>server configuration<BR> +<P>Here are some examples... +<blockquote><code> +ErrorDocument 500 /cgi-bin/crash-recover <br> +ErrorDocument 500 "Sorry, our script crashed because %s. 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> +The syntax is, <p> +<code><A HREF="core.html#errordocument">ErrorDocument</A></code> +<3-digit-code> action <p> + +where the action can be, +<OL> +<LI>Text to be displayed.<BR>Prefix the text with a quote ("). Whatever +follows the quote is displayed. If the error/problem produced any additional +information, it can be specified using <code>%s</code>. +<em>Note: the (") prefix isn't displayed.</em> +<LI>An external URL to redirect to. +<LI>A local URL to redirect to. +</OL> +<P><code>ErrorDocument</code> definitions are sensitive to a +<code>SIGHUP</code>, so you can change any of the definitions or add new ones +prior to sending a <code>SIGHUP</code> (kill -1) signal. +</DL> +<P><HR><P> + +<h2>Custom error responses and redirects</H2> +<DL> +<DT>Purpose +<DD>Apache's behaviour to redirected URLs has been modified so that additional +environment variables are available to a script/server-include.<p> + +<DT>Old behaviour +<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 behaviour +<DD>A new batch of environment variables will be initialized for use by a +script which has been redirected to.<BR> +Each new variable will have the prefix <code>REDIRECT_</code>.<BR> +REDIRECT_ environment variables are created from the CGI environment +variables which existed prior to the redirect, they are renamed with a +REDIRECT_ prefix, i.e. HTTP_USER_AGENT -> REDIRECT_HTTP_USER_AGENT.<BR> +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.<BR> +Logging: both the original URL and the URL being redirected to, will +now be logged correctly in the access log.<p> +</DL> +<P><HR> + +<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> +<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> +</BODY> +</HTML> diff --git a/docs/manual/custom-error.html.en b/docs/manual/custom-error.html.en new file mode 100644 index 0000000000..31c955a2c4 --- /dev/null +++ b/docs/manual/custom-error.html.en @@ -0,0 +1,109 @@ +<HTML> +<HEAD> +<TITLE>Ccustom error responses</TITLE> +</HEAD> + +<BODY> +<IMG SRC="../images/apache_sub.gif" ALT=""> +<H1>Custom error responses</H1> +<DL> +<DT>Purpose +<DD>Additional functionality. Allows webmasters to configure the response of +Apache to some error or problem.<BR> +<P>Customizable responses can be defined to be activated in the event of a +server detected error or problem.<BR> +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). +<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><BR> +<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.<BR>To achieve this, Apache will define new CGI-like environment +variables, e.g. +<blockquote><code> +REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/x-xbitmap, image/jpeg <br> +REDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX A.09.05 9000/712) <br> +REDIRECT_PATH=.:/bin:/usr/local/bin:/etc <br> +REDIRECT_QUERY_STRING= <br> +REDIRECT_REMOTE_ADDR=121.345.78.123 <br> +REDIRECT_REMOTE_HOST=ooh.ahhh.com <br> +REDIRECT_SERVER_NAME=crash.bang.edu <br> +REDIRECT_SERVER_PORT=80 <br> +REDIRECT_SERVER_SOFTWARE=Apache/0.8.15 <br> +REDIRECT_URL=/cgi-bin/buggy.pl <br> +</code></blockquote> + +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.<p> + +<DT>Configuration +<DD><em>file: </em>server configuration<BR> +<P>Here are some examples... +<blockquote><code> +ErrorDocument 500 /cgi-bin/crash-recover <br> +ErrorDocument 500 "Sorry, our script crashed because %s. 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> +The syntax is, <p> +<code><A HREF="core.html#errordocument">ErrorDocument</A></code> +<3-digit-code> action <p> + +where the action can be, +<OL> +<LI>Text to be displayed.<BR>Prefix the text with a quote ("). Whatever +follows the quote is displayed. If the error/problem produced any additional +information, it can be specified using <code>%s</code>. +<em>Note: the (") prefix isn't displayed.</em> +<LI>An external URL to redirect to. +<LI>A local URL to redirect to. +</OL> +<P><code>ErrorDocument</code> definitions are sensitive to a +<code>SIGHUP</code>, so you can change any of the definitions or add new ones +prior to sending a <code>SIGHUP</code> (kill -1) signal. +</DL> +<P><HR><P> + +<h2>Custom error responses and redirects</H2> +<DL> +<DT>Purpose +<DD>Apache's behaviour to redirected URLs has been modified so that additional +environment variables are available to a script/server-include.<p> + +<DT>Old behaviour +<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 behaviour +<DD>A new batch of environment variables will be initialized for use by a +script which has been redirected to.<BR> +Each new variable will have the prefix <code>REDIRECT_</code>.<BR> +REDIRECT_ environment variables are created from the CGI environment +variables which existed prior to the redirect, they are renamed with a +REDIRECT_ prefix, i.e. HTTP_USER_AGENT -> REDIRECT_HTTP_USER_AGENT.<BR> +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.<BR> +Logging: both the original URL and the URL being redirected to, will +now be logged correctly in the access log.<p> +</DL> +<P><HR> + +<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> +<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> +</BODY> +</HTML> diff --git a/docs/manual/handler.html b/docs/manual/handler.html new file mode 100644 index 0000000000..4472b3165d --- /dev/null +++ b/docs/manual/handler.html @@ -0,0 +1,138 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> +<HTML> +<HEAD> +<TITLE>Apache's Handler Use</TITLE> +</HEAD> + +<BODY> +<IMG SRC="../images/apache_sub.gif" ALT=""> +<h1>Apache's Handler Use</h1> + +<h2>What is a Handler</h2> + +<p>A "handler" is an internal Apache representation of the action to be +performed when a file is called. Generally, files have implicit +handlers, based on the file type. Normally, all files are simply +served by the server, but certain file typed are "handled" +seperately. For example, you may use a type of +"application/x-httpd-cgi" to invoke CGI scripts.</p> + +<p>Apache 1.1 adds the additional ability to use handlers +explicitly. Either based on filename extensions or on location, these +handlers are unrelated to file type. This is advantageous both because +it is a more elegant solution, but it also allows for both a type +<strong>and</strong> a handler to be associated with a file.</p> + +<p>Handlers can either be built into the server or to a module, or +they can be added with the <a +href="mod_actions.html#action">Action</a> directive. The built-in +handlers in the standard distribution are as follows:</p> + +<ul> +<li><strong>send-as-is</strong>: + Send file with HTTP headers as is. + (<a href="mod_asis.html">mod_asis</a>) +<li><strong>cgi-script</strong>: + Treat the file as a CGI script. + (<a href="mod_cgi.html">mod_cgi</a>) +<li><strong>imap-file</strong>: + Imagemap rule file. + (<a href="mod_imap.html">mod_imap</a>) +<li><strong>server-info</strong>: + Get the server's configuration information + (<a href="mod_info.html">mod_info</a>) +<li><strong>server-parsed</strong>: + Parse for server-side includes + (<a href="mod_include.html">mod_include</a>) +<li><strong>server-status</strong>: + Get the server's status report + (<a href="mod_status.html">mod_status</a>) +<li><strong>type-map</strong>: + Parse as a type map file for content negotation + (<a href="mod_negotiation.html">mod_negotiation</a>) +</ul> + +<p> + +<h2>Directives</h2> +<ul> +<li><A HREF="#addhandler">AddHandler</A> +<li><A HREF="#sethandler">SetHandler</A> +</ul> + +<hr> + +<h2><a name="addhandler">AddHandler</a></h2> + +<strong>Syntax:</strong> <AddHandler <em>handler-name extention</em>><br> +<strong>Context:</strong> server config, virtual host, directory, .htaccess<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_mime + +<p>AddHandler maps the filename extension <em>extension</em> to the +handler <em>handler-name</em>. For example, to activate CGI scripts +with the file extension "<code>.cgi</code>", you might use: +<pre> + AddHandler cgi-script cgi +</pre> + +<p>Once that has been put into your srm.conf or httpd.conf file, any +file ending with "<code>.cgi</code>" will be treated as a CGI +program.</p> + +<hr> + +<h2><a name="sethandler">SetHandler</a></h2> + +<strong>Syntax:</strong> <SetHandler <em>handler-name</em>><br> +<strong>Context:</strong> directory, .htaccess<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_mime + +<p>When placed into an <code>.htaccess</code> file or a +<code><Directory></code> or <code><Location</code> section, +this directive forces all matching files to be parsed through the +handler given by <em>handler-name</em>. For example, if you had a +directory you wanted to be parsed entirely as imagemap rule files, +regardless of extension, you might put the following into an +<code>.htaccess</code> file in that directory: +<pre> + SetHandler imap-file +</pre> +<p>Another example: if you wanted to have the server display a status +report whenever a URL of <code>http://servername/status</code> was +called, you might put the following into access.conf: +<pre> + <Location /status> + SetHandler server-status + </Location> +</pre> + +<p><hr> + +<h2>Programmer's Note</h2> + +<p>In order to implement the handler features, an addition has been +made to the <a href="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, albiet using +the handler name instead of a content type. While it is not +neccessary, the naming convention for handlers is to use a +dash-seperated word, with no slashes, so as to not invade the media +type namespace.</p> + +<hr> + +<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> +<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> + +</BODY> +</HTML> + diff --git a/docs/manual/handler.html.en b/docs/manual/handler.html.en new file mode 100644 index 0000000000..4472b3165d --- /dev/null +++ b/docs/manual/handler.html.en @@ -0,0 +1,138 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> +<HTML> +<HEAD> +<TITLE>Apache's Handler Use</TITLE> +</HEAD> + +<BODY> +<IMG SRC="../images/apache_sub.gif" ALT=""> +<h1>Apache's Handler Use</h1> + +<h2>What is a Handler</h2> + +<p>A "handler" is an internal Apache representation of the action to be +performed when a file is called. Generally, files have implicit +handlers, based on the file type. Normally, all files are simply +served by the server, but certain file typed are "handled" +seperately. For example, you may use a type of +"application/x-httpd-cgi" to invoke CGI scripts.</p> + +<p>Apache 1.1 adds the additional ability to use handlers +explicitly. Either based on filename extensions or on location, these +handlers are unrelated to file type. This is advantageous both because +it is a more elegant solution, but it also allows for both a type +<strong>and</strong> a handler to be associated with a file.</p> + +<p>Handlers can either be built into the server or to a module, or +they can be added with the <a +href="mod_actions.html#action">Action</a> directive. The built-in +handlers in the standard distribution are as follows:</p> + +<ul> +<li><strong>send-as-is</strong>: + Send file with HTTP headers as is. + (<a href="mod_asis.html">mod_asis</a>) +<li><strong>cgi-script</strong>: + Treat the file as a CGI script. + (<a href="mod_cgi.html">mod_cgi</a>) +<li><strong>imap-file</strong>: + Imagemap rule file. + (<a href="mod_imap.html">mod_imap</a>) +<li><strong>server-info</strong>: + Get the server's configuration information + (<a href="mod_info.html">mod_info</a>) +<li><strong>server-parsed</strong>: + Parse for server-side includes + (<a href="mod_include.html">mod_include</a>) +<li><strong>server-status</strong>: + Get the server's status report + (<a href="mod_status.html">mod_status</a>) +<li><strong>type-map</strong>: + Parse as a type map file for content negotation + (<a href="mod_negotiation.html">mod_negotiation</a>) +</ul> + +<p> + +<h2>Directives</h2> +<ul> +<li><A HREF="#addhandler">AddHandler</A> +<li><A HREF="#sethandler">SetHandler</A> +</ul> + +<hr> + +<h2><a name="addhandler">AddHandler</a></h2> + +<strong>Syntax:</strong> <AddHandler <em>handler-name extention</em>><br> +<strong>Context:</strong> server config, virtual host, directory, .htaccess<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_mime + +<p>AddHandler maps the filename extension <em>extension</em> to the +handler <em>handler-name</em>. For example, to activate CGI scripts +with the file extension "<code>.cgi</code>", you might use: +<pre> + AddHandler cgi-script cgi +</pre> + +<p>Once that has been put into your srm.conf or httpd.conf file, any +file ending with "<code>.cgi</code>" will be treated as a CGI +program.</p> + +<hr> + +<h2><a name="sethandler">SetHandler</a></h2> + +<strong>Syntax:</strong> <SetHandler <em>handler-name</em>><br> +<strong>Context:</strong> directory, .htaccess<br> +<strong>Status:</strong> Base<br> +<strong>Module:</strong> mod_mime + +<p>When placed into an <code>.htaccess</code> file or a +<code><Directory></code> or <code><Location</code> section, +this directive forces all matching files to be parsed through the +handler given by <em>handler-name</em>. For example, if you had a +directory you wanted to be parsed entirely as imagemap rule files, +regardless of extension, you might put the following into an +<code>.htaccess</code> file in that directory: +<pre> + SetHandler imap-file +</pre> +<p>Another example: if you wanted to have the server display a status +report whenever a URL of <code>http://servername/status</code> was +called, you might put the following into access.conf: +<pre> + <Location /status> + SetHandler server-status + </Location> +</pre> + +<p><hr> + +<h2>Programmer's Note</h2> + +<p>In order to implement the handler features, an addition has been +made to the <a href="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, albiet using +the handler name instead of a content type. While it is not +neccessary, the naming convention for handlers is to use a +dash-seperated word, with no slashes, so as to not invade the media +type namespace.</p> + +<hr> + +<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> +<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> + +</BODY> +</HTML> + diff --git a/docs/manual/install.html b/docs/manual/install.html new file mode 100644 index 0000000000..dd53b73a2e --- /dev/null +++ b/docs/manual/install.html @@ -0,0 +1,109 @@ +<!--%hypertext --> +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> +<HTML> +<HEAD> +<TITLE>Compiling and Installing Apache</TITLE> +</HEAD> + +<BODY> +<!--/%hypertext --> + +<h1>Compiling and Installing Apache</h1> +<h2>Downloading Apache</h2> +Information on the latest version of Apache can be found on the Apache +web server at http://www.apache.org/. This will list the current release, +any more recent beta-test release, together with details of mirror +web and anonymous ftp sites. + +<h2>Compiling Apache</h2> +This release of Apache supports the notion of `optional modules'. +However, the server has to know which modules are compiled into it, in +order for those modules to be effective; this requires generation of a +short bit of code (`<code>modules.c</code>') which simply has a list of them. +<p> +If you are satisfied with our standard module set, and expect to +continue to be satisfied with it, then you can just edit the stock +<code>Makefile</code> and compile as you have been doing previously. If you +would +like to select optional modules, however, you need to run the +configuration script. +<p> +To do this: +<ol> +<li>Edit the file `<code>Configuration</code>'. This contains the per-machine +config settings of the Makefile, and also an additional section at +the bottom which lists the modules which have been compiled in, and +also names the files containing them. You will need to: +<ol> +<li> Select a compiler and compilation options as appropriate to +your machine. +<li> Uncomment lines corresponding to those optional modules you wish +to include (among the Module lines at the bottom of the file) +or add new lines corresponding to custom modules you have written. +<p> +Note that DBM auth has to be explicitly configured in, if you want +it; just uncomment the corresponding line. +</ol> +<li> Run the `Configure' script: +<blockquote><code> +% Configure<br> +Using 'Configuration' as config file<br> +%</code></blockquote> + +This generates new versions of the Makefile and of modules.c. If +you want to maintain multiple configurations, you can say, e.g., +<blockquote><code> +% Configure -file Configuration.ai<br> +Using alternate config file Configuration.ai<br> +%</code></blockquote> + +<li>Type `make'. +<p> +The modules we place in the Apache distribution are the ones we have +tested and are used regularly by various members of the Apache +development group. Additional modules contributed by members or third +parties with specific needs or functions are available at +<A HREF="http://www.apache.org/dist/contrib/modules/"><URL:http://www.apache.org/dist/contrib/modules/></A>. There are instructions on that page for +linking these modules into the core Apache code. +</ol> + +<h2>Installing Apache</h2> +After compilation, you will have a binary called `httpd' in the +<code>src/</code> directory. A binary distribution of Apache will supply this +file. +<p> +The next step is to edit the configuration files for the server. In +the subdirectory called `conf' you should find distribution versions +of the three configuration files: <code>srm.conf-dist</code>, +<code>access.conf-dist</code> and <code>httpd.conf-dist</code>. Copy them to +<code>srm.conf</code>, <code>access.conf</code> and <code>httpd.conf</code> +respectively. +<p> +First edit <code>httpd.conf</code>. This sets up general attributes about the +server; the port number, the user it runs as, etc. Next edit the +<code>srm.conf</code> file; this sets up the root of the document tree, +special functions like server-parsed HTML or internal imagemap parsing, etc. +Finally, edit the <code>access.conf</code> file to at least set the base cases +of access. +<p> +Finally, make a call to httpd, with a -f to the full path to the +httpd.conf file. I.e., the common case: +<blockquote><code> + /usr/local/etc/apache/src/httpd -f /usr/local/etc/apache/conf/httpd.conf +</code></blockquote> +The server should be now running. +<p> +By default the <code>srm.conf</code> and <code>access.conf</code> files are +located by name; to specifically call them by other names, use the +<A HREF="core.html#accessconfig">AccessConfig</A> and +<A HREF="core.html#resourceconfig">ResourceConfig</A> directives in +<code>httpd.conf</code>. + +<!--%hypertext --> +<hr> +<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> +<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> + +</BODY> +</HTML> +<!--/%hypertext --> diff --git a/docs/manual/install.html.en b/docs/manual/install.html.en new file mode 100644 index 0000000000..dd53b73a2e --- /dev/null +++ b/docs/manual/install.html.en @@ -0,0 +1,109 @@ +<!--%hypertext --> +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> +<HTML> +<HEAD> +<TITLE>Compiling and Installing Apache</TITLE> +</HEAD> + +<BODY> +<!--/%hypertext --> + +<h1>Compiling and Installing Apache</h1> +<h2>Downloading Apache</h2> +Information on the latest version of Apache can be found on the Apache +web server at http://www.apache.org/. This will list the current release, +any more recent beta-test release, together with details of mirror +web and anonymous ftp sites. + +<h2>Compiling Apache</h2> +This release of Apache supports the notion of `optional modules'. +However, the server has to know which modules are compiled into it, in +order for those modules to be effective; this requires generation of a +short bit of code (`<code>modules.c</code>') which simply has a list of them. +<p> +If you are satisfied with our standard module set, and expect to +continue to be satisfied with it, then you can just edit the stock +<code>Makefile</code> and compile as you have been doing previously. If you +would +like to select optional modules, however, you need to run the +configuration script. +<p> +To do this: +<ol> +<li>Edit the file `<code>Configuration</code>'. This contains the per-machine +config settings of the Makefile, and also an additional section at +the bottom which lists the modules which have been compiled in, and +also names the files containing them. You will need to: +<ol> +<li> Select a compiler and compilation options as appropriate to +your machine. +<li> Uncomment lines corresponding to those optional modules you wish +to include (among the Module lines at the bottom of the file) +or add new lines corresponding to custom modules you have written. +<p> +Note that DBM auth has to be explicitly configured in, if you want +it; just uncomment the corresponding line. +</ol> +<li> Run the `Configure' script: +<blockquote><code> +% Configure<br> +Using 'Configuration' as config file<br> +%</code></blockquote> + +This generates new versions of the Makefile and of modules.c. If +you want to maintain multiple configurations, you can say, e.g., +<blockquote><code> +% Configure -file Configuration.ai<br> +Using alternate config file Configuration.ai<br> +%</code></blockquote> + +<li>Type `make'. +<p> +The modules we place in the Apache distribution are the ones we have +tested and are used regularly by various members of the Apache +development group. Additional modules contributed by members or third +parties with specific needs or functions are available at +<A HREF="http://www.apache.org/dist/contrib/modules/"><URL:http://www.apache.org/dist/contrib/modules/></A>. There are instructions on that page for +linking these modules into the core Apache code. +</ol> + +<h2>Installing Apache</h2> +After compilation, you will have a binary called `httpd' in the +<code>src/</code> directory. A binary distribution of Apache will supply this +file. +<p> +The next step is to edit the configuration files for the server. In +the subdirectory called `conf' you should find distribution versions +of the three configuration files: <code>srm.conf-dist</code>, +<code>access.conf-dist</code> and <code>httpd.conf-dist</code>. Copy them to +<code>srm.conf</code>, <code>access.conf</code> and <code>httpd.conf</code> +respectively. +<p> +First edit <code>httpd.conf</code>. This sets up general attributes about the +server; the port number, the user it runs as, etc. Next edit the +<code>srm.conf</code> file; this sets up the root of the document tree, +special functions like server-parsed HTML or internal imagemap parsing, etc. +Finally, edit the <code>access.conf</code> file to at least set the base cases +of access. +<p> +Finally, make a call to httpd, with a -f to the full path to the +httpd.conf file. I.e., the common case: +<blockquote><code> + /usr/local/etc/apache/src/httpd -f /usr/local/etc/apache/conf/httpd.conf +</code></blockquote> +The server should be now running. +<p> +By default the <code>srm.conf</code> and <code>access.conf</code> files are +located by name; to specifically call them by other names, use the +<A HREF="core.html#accessconfig">AccessConfig</A> and +<A HREF="core.html#resourceconfig">ResourceConfig</A> directives in +<code>httpd.conf</code>. + +<!--%hypertext --> +<hr> +<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> +<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> + +</BODY> +</HTML> +<!--/%hypertext --> diff --git a/docs/manual/invoking.html b/docs/manual/invoking.html new file mode 100644 index 0000000000..f00b68e459 --- /dev/null +++ b/docs/manual/invoking.html @@ -0,0 +1,108 @@ +<!--%hypertext --> +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> +<HTML> +<HEAD> +<TITLE>Starting Apache</TITLE> +</HEAD> + +<BODY> +<!--/%hypertext --> + +<h1>Starting Apache</h1> +<h2>Invoking Apache</h2> +The <code>httpd</code> program is either invoked by the Internet +daemon <code>inetd</code> each time a connection to the HTTP service is made, +or alternatively it may run as a daemon which executes continuously, handling +requests. Whatever method is chosen, the +<A HREF="core.html#servertype">ServerType</A> directive must be set +to tell the server how it is to run. + +<h2>Command line options</h2> +The following options are recognised on the httpd command line: +<dl> +<dt><code>-d</code> <em>serverroot</em> +<dd>Set the initial value for the +<A HREF="core.html#serverroot">ServerRoot</A> variable to +<em>serverroot</em>. This can be overridden by the ServerRoot command in the +configuration file. The default is <code>/usr/local/etc/httpd</code>. + +<dt><code>-f</code> <em>config</em> +<dd>Execute the commands in the file <em>config</em> on startup. If +<em>config</em> does not begin with a <code>/</code>, then it is taken to be a +path relative to the <A HREF="core.html#serverroot">ServerRoot</A>. The +default is <code>conf/httpd.conf</code>. + +<dt><code>-X</code> +<dd>Run in single-process mode, for internal debugging purposes only; the +daemon does not detach from the terminal or fork any children. Do <em>NOT</em> +use this mode to provide ordinary web service. + +<dt><code>-v</code> +<dd>Print the version of httpd, and then exit. + +<dt><code>-?</code> +<dd>Print a list of the httpd options, and then exit. +</dl> + +<h2>Configuration files</h2> +The server will read three files for configuration directives. Any directive +may appear in any of these files. The the names of these files are taken +to be relative to the server root; this is set by the +<A HREF="core.html#serverroot">ServerRoot</A> directive, or the +<code>-d</code> command line flag. + +Conventionally, the files are: +<dl> +<dt><code>conf/httpd.conf</code> +<dd>Contains directives that control the operation of the server daemon. +The filename may be overridden with the <code>-f</code> command line flag. + +<dt><code>conf/srm.conf</code> +<dd>Contains directives that control the specification of documents that +the server can provide to clients. The filename may be overridden with +the <A HREF="core.html#resourceconfig">ResourceConfig</A> directive. + +<dt><code>conf/acces.conf</code> +<dd>Contains directives that control access to documents. +The filename may be overridden with the +<A HREF="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_mime.html#typesconfig">TypesConfig</A> directive, +and is <code>conf/mime.types</code> by default. + +<h2>Log files</h2> +<h3>pid file</h3> +On daemon startup, it saves the process id of the parent httpd process to +the file <code>logs/httpd.pid</code>. This filename can be changed with the +<A HREF="core.html#pidfile">PidFile</A> directive. The process-id is for +use by the administrator in restarting and terminating the daemon; +A HUP signal causes the daemon to re-read its configuration files and +a TERM signal causes it to die gracefully. +<p> +If the process dies (or is killed) abnormally, then it will be necessary to +kill the children httpd processes. + +<h3>Error log</h3> +The server will log error messages to a log file, <code>logs/error_log</code> +by default. The filename can be set using the +<A HREF="core.html#errorlog">ErrorLog</A> directive; different error logs can +be set for different <A HREF="core.html#virtualhost">virtual hosts</A>. + +<h3>Transfer log</h3> +The server will typically log each request to a transfer file, +<code>logs/access_log</code> by default. The filename can be set using a +<A HREF="mod_log_common.html#transferlog">TransferLog</A> directive; different +transfer logs can be set for different <A HREF="core.html#virtualhost">virtual +hosts</A>. + +<!--%hypertext --> +<hr> +<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> +<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> + +</BODY> +</HTML> +<!--/%hypertext --> diff --git a/docs/manual/invoking.html.en b/docs/manual/invoking.html.en new file mode 100644 index 0000000000..f00b68e459 --- /dev/null +++ b/docs/manual/invoking.html.en @@ -0,0 +1,108 @@ +<!--%hypertext --> +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> +<HTML> +<HEAD> +<TITLE>Starting Apache</TITLE> +</HEAD> + +<BODY> +<!--/%hypertext --> + +<h1>Starting Apache</h1> +<h2>Invoking Apache</h2> +The <code>httpd</code> program is either invoked by the Internet +daemon <code>inetd</code> each time a connection to the HTTP service is made, +or alternatively it may run as a daemon which executes continuously, handling +requests. Whatever method is chosen, the +<A HREF="core.html#servertype">ServerType</A> directive must be set +to tell the server how it is to run. + +<h2>Command line options</h2> +The following options are recognised on the httpd command line: +<dl> +<dt><code>-d</code> <em>serverroot</em> +<dd>Set the initial value for the +<A HREF="core.html#serverroot">ServerRoot</A> variable to +<em>serverroot</em>. This can be overridden by the ServerRoot command in the +configuration file. The default is <code>/usr/local/etc/httpd</code>. + +<dt><code>-f</code> <em>config</em> +<dd>Execute the commands in the file <em>config</em> on startup. If +<em>config</em> does not begin with a <code>/</code>, then it is taken to be a +path relative to the <A HREF="core.html#serverroot">ServerRoot</A>. The +default is <code>conf/httpd.conf</code>. + +<dt><code>-X</code> +<dd>Run in single-process mode, for internal debugging purposes only; the +daemon does not detach from the terminal or fork any children. Do <em>NOT</em> +use this mode to provide ordinary web service. + +<dt><code>-v</code> +<dd>Print the version of httpd, and then exit. + +<dt><code>-?</code> +<dd>Print a list of the httpd options, and then exit. +</dl> + +<h2>Configuration files</h2> +The server will read three files for configuration directives. Any directive +may appear in any of these files. The the names of these files are taken +to be relative to the server root; this is set by the +<A HREF="core.html#serverroot">ServerRoot</A> directive, or the +<code>-d</code> command line flag. + +Conventionally, the files are: +<dl> +<dt><code>conf/httpd.conf</code> +<dd>Contains directives that control the operation of the server daemon. +The filename may be overridden with the <code>-f</code> command line flag. + +<dt><code>conf/srm.conf</code> +<dd>Contains directives that control the specification of documents that +the server can provide to clients. The filename may be overridden with +the <A HREF="core.html#resourceconfig">ResourceConfig</A> directive. + +<dt><code>conf/acces.conf</code> +<dd>Contains directives that control access to documents. +The filename may be overridden with the +<A HREF="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_mime.html#typesconfig">TypesConfig</A> directive, +and is <code>conf/mime.types</code> by default. + +<h2>Log files</h2> +<h3>pid file</h3> +On daemon startup, it saves the process id of the parent httpd process to +the file <code>logs/httpd.pid</code>. This filename can be changed with the +<A HREF="core.html#pidfile">PidFile</A> directive. The process-id is for +use by the administrator in restarting and terminating the daemon; +A HUP signal causes the daemon to re-read its configuration files and +a TERM signal causes it to die gracefully. +<p> +If the process dies (or is killed) abnormally, then it will be necessary to +kill the children httpd processes. + +<h3>Error log</h3> +The server will log error messages to a log file, <code>logs/error_log</code> +by default. The filename can be set using the +<A HREF="core.html#errorlog">ErrorLog</A> directive; different error logs can +be set for different <A HREF="core.html#virtualhost">virtual hosts</A>. + +<h3>Transfer log</h3> +The server will typically log each request to a transfer file, +<code>logs/access_log</code> by default. The filename can be set using a +<A HREF="mod_log_common.html#transferlog">TransferLog</A> directive; different +transfer logs can be set for different <A HREF="core.html#virtualhost">virtual +hosts</A>. + +<!--%hypertext --> +<hr> +<A HREF="../"><IMG SRC="../images/apache_home.gif" ALT="Home"></A> +<A HREF="./"><IMG SRC="../images/apache_index.gif" ALT="Index"></A> + +</BODY> +</HTML> +<!--/%hypertext --> diff --git a/docs/manual/location.html b/docs/manual/location.html new file mode 100644 index 0000000000..a1f4c9ea3f --- /dev/null +++ b/docs/manual/location.html @@ -0,0 +1,58 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN"> +<HTML> +<HEAD> +<TITLE>Access Control by URL</TITLE> +</HEAD> + +<BODY> +<IMG SRC="../../images/apache_sub.gif" ALT=""> +<H1>Access Control by URL</H1> + +<h2><a name="location">The <code><Location></code> Directive</a></h2> + +<strong>Syntax:</strong> <Location <em>URL prefix</em>><br> +<strong>Context:</strong> server config, virtual host<br> +<strong>Status:</strong> core<br> + +<p>The <Location> directive provides for access control by +URL. It is comprable to the <a +href="../core.html#directory"><Directory></a> directive, and +should be matched with a </Location> directive. Directives that +apply to the URL given should be listen +within. <code><Location></code> sections are processed in the +order they appear in the configuration file, after the +<Directory> sections and <code>.htaccess</code> files are +read.</p> + +<p>Note that, due to the way HTTP functions, <em>URL prefix</em> +should, save for proxy requests, be of the form <code>/path/</code>, +and should not include the <code>http://servername</code>. It doesn't +neccessarily have to protect a directory (it can be an individual +file, or a number of files), and can include wildcards. In a wildcard +string, `?' matches any single character, and `*' matches any +sequences of characters. + +<p>This functionality is especially useful when combined with the +<code><a href="../mod_mime.html#sethandler">SetHandler</a></code> +directive. For example, to enable status requests, but allow them only +from browsers at foo.com, you might use: + +<pre> + <Location /status> + SetHandler server-status + <Limit GET> + order deny,allow + deny from all + allow from .foo.com + </Limit> + </Location> +</pre> + +<p><hr> + +<A HREF="../../"><IMG SRC="../../images/apache_home.gif" ALT="Home"></A> +<A HREF="./"><IMG SRC="../../images/apache_index.gif" ALT="Index"></A> + +</BODY> +</HTML> + diff --git a/docs/manual/process-model.html b/docs/manual/process-model.html new file mode 100644 index 0000000000..f2c22f9ccc --- /dev/null +++ b/docs/manual/process-model.html @@ -0,0 +1,50 @@ +<HTML><HEAD> +<TITLE>Server Pool Management with MinSpareServers and MaxSpareServers</TITLE> +</HEAD><BODY> + +<IMG SRC="../images/apache_sub.gif" ALT=""> +<H3>Server Pool Management with MinSpareServers and MaxSpareServers</H3> + +<HR> +<P> +We found that many people were using values for "MaxServers" either +too high or too low, and were hanging themselves on it. The model we +adopted is still based on long-lived minimal-forking processes, but +instead of specifying one number of persistant processes, the +webmaster specifies a maximum and minimum number of processes to be +"spare" - every couple of seconds the parent checks the actual number +of spare servers and adjusts accordingly. This should keep the number +of servers concurrently running relatively low while still ensuring +minimal forking. + +<P> + +We renamed the current StartServers to MinSpareServers, created +separate StartServers parameter which means what it says, and renamed +MaxServers to MaxSpareServers (though the old name still works, for +NCSA 1.4 back-combatibility). The old names were generally regarded +as too confusing. + +<P> + +The defaults for each variable are: + +<PRE> +MinSpareServers 5 +MaxSpareServers 10 +StartServers 10 +</PRE> + +There is a compile-time limit of 150 absolute maximum number of +simultaneous children that will be allowed, which can be overruled by +"MaxClients", though we don't recommend changing that number unless + +<OL> +<LI>You know you have the server resources to handle more +<LI>You use the machine for other purposes and must limit the amount of memory +Apache uses +</OL> + +</body></html> + + |