Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

This commit was manufactured by cvs2svn to create tag 'APACHE_1_2b2'.

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/tags/APACHE_1_2b2@77239 13f79535-47bb-0310-9956-ffa450edef68
  • Loading branch information...
commit 6f77262fb2b48f1d7d8395239457d3c43bfcef79 1 parent 5381f94
No Author authored
View
BIN  docs/docroot/apache_pb.gif
Deleted file not rendered
View
100 docs/manual/bind.html.en
@@ -1,100 +0,0 @@
-<html><head>
-<title>Setting which addresses and ports Apache uses</title>
-</head><body>
-
-<!--#include virtual="header.html" -->
-<h1>Setting which addresses and ports Apache uses</h1>
-
-<hr>
-
-When Apache starts, it connects to some port and address on the
-local machine and waits for incoming requests. By default, it
-listens to all addresses on the machine, and to the port
-as specified by the <tt>Port</tt> directive in the server configuration.
-However, it can be told to listen to more the one port, or to listen
-to only selected addresses, or a combination. This is often combined
-with the Virtual Host feature which determines how Apache
-responds to different IP addresses, hostnames and ports.<p>
-
-There are two directives used to restrict or specify which addresses
-and ports Apache listens to.
-
-<ul>
-<li><a href="#bindaddress">BindAddress</a> is used to restrict the server to listening to
- a single address, and can be used to permit multiple Apache servers
- on the same machine listening to different IP addresses.
-<li><a href="#listen">Listen</a> can be used to make a single Apache server listen
- to more than one address and/or port.
-</ul>
-
-<h3><a name="bindaddress">BindAddress</a></h3>
-<strong>Syntax:</strong> BindAddress <em>[ * | IP-address | hostname ]</em><br>
-<strong>Default:</strong> <code>BindAddress *</code><br>
-<strong>Context:</strong> server config<br>
-<strong>Status:</strong> Core<p>
-
-Makes the server listen to just the specified address. If the argument
-is *, the server listens to all addresses. The port listened to
-is set with the <tt>Port</tt> directive. Only one BindAddress
-should be used.
-
-<h3><a name="listen">Listen</a></h3>
-<strong>Syntax:</strong> Listen <em>[ port | IP-address:port ]</em><br>
-<strong>Default:</strong> <code>none</code><br>
-<strong>Context:</strong> server config<br>
-<strong>Status:</strong> Core<p>
-
-<tt>Listen</tt> can be used instead of <tt>BindAddress</tt> and
-<tt>Port</tt>. It tells the server to accept incoming requests on the
-specified port or address-and-port combination. If the first format is
-used, with a port number only, the server listens to the given port on
-all interfaces, instead of the port given by the <tt>Port</tt>
-directive. If an IP address is given as well as a port, the server
-will listen on the given port and interface. <p> Multiple Listen
-directives may be used to specify a number of addresses and ports to
-listen to. The server will respond to requests from any of the listed
-addresses and ports.<p>
-
-For example, to make the server accept connections on both port
-80 and port 8000, use:
-<pre>
- Listen 80
- Listen 8000
-</pre>
-
-To make the server accept connections on two specified
-interfaces and port numbers, use
-<pre>
- Listen 192.170.2.1:80
- Listen 192.170.2.5:8000
-</pre>
-
-<h2>How this works with Virtual Hosts</h2>
-
-BindAddress and Listen do not implement Virtual Hosts. They tell the
-main server what addresses and ports to listen to. If no
-&lt;VirtualHost&gt; directives are used, the server will behave the
-same for all accepted requests. However, &lt;VirtualHost&gt; 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
-&lt;VirtualHost&gt; section should be created for a specified address
-and port to set the behavior of this virtual host. Note that if the
-&lt;VirtualHost&gt; is set for an address and port that the server is
-not listening to, it cannot be accessed.
-
-<h2>See also</h2>
-
-See also the documentation on
-<a href="virtual-host.html">Virtual Hosts</a>,
-<a href="host.html">Non-IP virtual hosts</a>,
-<a href="mod/core.html#bindaddress">BindAddress directive</a>,
-<a href="mod/core.html#port">Port directive</a>
-and
-<a href="mod/core.html#virtualhost">&lt;VirtualHost&gt; section</a>.
-</ul>
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
-
View
213 docs/manual/content-negotiation.html.en
@@ -1,213 +0,0 @@
-<html>
-<head>
-<title>Apache server Content arbitration: MultiViews and *.var files</title>
-</head>
-
-<body>
-<!--#include virtual="header.html" -->
-<h1>Content Arbitration: MultiViews and *.var files</h1>
-
-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;&nbsp;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>&lt;Directory&gt;</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>).
-
-<!--#include virtual="footer.html" -->
-</body> </html>
View
108 docs/manual/custom-error.html.en
@@ -1,108 +0,0 @@
-<HTML>
-<HEAD>
-<TITLE>Custom error responses</TITLE>
-</HEAD>
-
-<BODY>
-<!--#include virtual="header.html" -->
-<H1>Custom error responses</H1>
-
-<DL>
-<DT>Purpose
-<DD>Additional functionality. Allows web-masters 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="mod/core.html#errordocument">ErrorDocument</A></code>
-&lt;3-digit-code&gt; action <p>
-
-where the action can be,
-<OL>
-<LI>Text to be displayed.<BR>Prefix the text with a quote (&quot;). 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 (&quot;) 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 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.<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 -&gt; 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>
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
View
987 docs/manual/developer/API.html
@@ -1,987 +0,0 @@
-<html><head>
-<title>Apache API notes</title>
-</head>
-<body>
-<!--#include virtual="header.html" -->
-<h1>Apache API notes</h1>
-
-These are some notes on the Apache API and the data structures you
-have to deal with, etc. They are not yet nearly complete, but
-hopefully, they will help you get your bearings. Keep in mind that
-the API is still subject to change as we gain experience with it.
-(See the TODO file for what <em>might</em> be coming). However,
-it will be easy to adapt modules to any changes that are made.
-(We have more modules to adapt than you do).
-<p>
-
-A few notes on general pedagogical style here. In the interest of
-conciseness, all structure declarations here are incomplete --- the
-real ones have more slots that I'm not telling you about. For the
-most part, these are reserved to one component of the server core or
-another, and should be altered by modules with caution. However, in
-some cases, they really are things I just haven't gotten around to
-yet. Welcome to the bleeding edge.<p>
-
-Finally, here's an outline, to give you some bare idea of what's
-coming up, and in what order:
-
-<ul>
-<li> <a href="#basics">Basic concepts.</a>
-<menu>
- <li> <a href="#HMR">Handlers, Modules, and Requests</a>
- <li> <a href="#moduletour">A brief tour of a module</a>
-</menu>
-<li> <a href="#handlers">How handlers work</a>
-<menu>
- <li> <a href="#req_tour">A brief tour of the <code>request_rec</code></a>
- <li> <a href="#req_orig">Where request_rec structures come from</a>
- <li> <a href="#req_return">Handling requests, declining, and returning error codes</a>
- <li> <a href="#resp_handlers">Special considerations for response handlers</a>
- <li> <a href="#auth_handlers">Special considerations for authentication handlers</a>
- <li> <a href="#log_handlers">Special considerations for logging handlers</a>
-</menu>
-<li> <a href="#pools">Resource allocation and resource pools</a>
-<li> <a href="#config">Configuration, commands and the like</a>
-<menu>
- <li> <a href="#per-dir">Per-directory configuration structures</a>
- <li> <a href="#commands">Command handling</a>
- <li> <a href="#servconf">Side notes --- per-server configuration, virtual servers, etc.</a>
-</menu>
-</ul>
-
-<h2><a name="basics">Basic concepts.</a></h2>
-
-We begin with an overview of the basic concepts behind the
-API, and how they are manifested in the code.
-
-<h3><a name="HMR">Handlers, Modules, and Requests</a></h3>
-
-Apache breaks down request handling into a series of steps, more or
-less the same way the Netscape server API does (although this API has
-a few more stages than NetSite does, as hooks for stuff I thought
-might be useful in the future). These are:
-
-<ul>
- <li> URI -&gt; Filename translation
- <li> Auth ID checking [is the user who they say they are?]
- <li> Auth access checking [is the user authorized <em>here</em>?]
- <li> Access checking other than auth
- <li> Determining MIME type of the object requested
- <li> `Fixups' --- there aren't any of these yet, but the phase is
- intended as a hook for possible extensions like
- <code>SetEnv</code>, which don't really fit well elsewhere.
- <li> Actually sending a response back to the client.
- <li> Logging the request
-</ul>
-
-These phases are handled by looking at each of a succession of
-<em>modules</em>, looking to see if each of them has a handler for the
-phase, and attempting invoking it if so. The handler can typically do
-one of three things:
-
-<ul>
- <li> <em>Handle</em> the request, and indicate that it has done so
- by returning the magic constant <code>OK</code>.
- <li> <em>Decline</em> to handle the request, by returning the magic
- integer constant <code>DECLINED</code>. In this case, the
- server behaves in all respects as if the handler simply hadn't
- been there.
- <li> Signal an error, by returning one of the HTTP error codes.
- This terminates normal handling of the request, although an
- ErrorDocument may be invoked to try to mop up, and it will be
- logged in any case.
-</ul>
-
-Most phases are terminated by the first module that handles them;
-however, for logging, `fixups', and non-access authentication
-checking, all handlers always run (barring an error). Also, the
-response phase is unique in that modules may declare multiple handlers
-for it, via a dispatch table keyed on the MIME type of the requested
-object. Modules may declare a response-phase handler which can handle
-<em>any</em> request, by giving it the key <code>*/*</code> (i.e., a
-wildcard MIME type specification). However, wildcard handlers are
-only invoked if the server has already tried and failed to find a more
-specific response handler for the MIME type of the requested object
-(either none existed, or they all declined).<p>
-
-The handlers themselves are functions of one argument (a
-<code>request_rec</code> structure. vide infra), which returns an
-integer, as above.<p>
-
-<h3><a name="moduletour">A brief tour of a module</a></h3>
-
-At this point, we need to explain the structure of a module. Our
-candidate will be one of the messier ones, the CGI module --- this
-handles both CGI scripts and the <code>ScriptAlias</code> config file
-command. It's actually a great deal more complicated than most
-modules, but if we're going to have only one example, it might as well
-be the one with its fingers in every place.<p>
-
-Let's begin with handlers. In order to handle the CGI scripts, the
-module declares a response handler for them. Because of
-<code>ScriptAlias</code>, it also has handlers for the name
-translation phase (to recognise <code>ScriptAlias</code>ed URIs), the
-type-checking phase (any <code>ScriptAlias</code>ed request is typed
-as a CGI script).<p>
-
-The module needs to maintain some per (virtual)
-server information, namely, the <code>ScriptAlias</code>es in effect;
-the module structure therefore contains pointers to a functions which
-builds these structures, and to another which combines two of them (in
-case the main server and a virtual server both have
-<code>ScriptAlias</code>es declared).<p>
-
-Finally, this module contains code to handle the
-<code>ScriptAlias</code> command itself. This particular module only
-declares one command, but there could be more, so modules have
-<em>command tables</em> which declare their commands, and describe
-where they are permitted, and how they are to be invoked. <p>
-
-A final note on the declared types of the arguments of some of these
-commands: a <code>pool</code> is a pointer to a <em>resource pool</em>
-structure; these are used by the server to keep track of the memory
-which has been allocated, files opened, etc., either to service a
-particular request, or to handle the process of configuring itself.
-That way, when the request is over (or, for the configuration pool,
-when the server is restarting), the memory can be freed, and the files
-closed, <i>en masse</i>, without anyone having to write explicit code to
-track them all down and dispose of them. Also, a
-<code>cmd_parms</code> structure contains various information about
-the config file being read, and other status information, which is
-sometimes of use to the function which processes a config-file command
-(such as <code>ScriptAlias</code>).
-
-With no further ado, the module itself:
-
-<pre>
-/* Declarations of handlers. */
-
-int translate_scriptalias (request_rec *);
-int type_scriptalias (request_rec *);
-int cgi_handler (request_rec *);
-
-/* Subsidiary dispatch table for response-phase handlers, by MIME type */
-
-handler_rec cgi_handlers[] = {
-{ "application/x-httpd-cgi", cgi_handler },
-{ NULL }
-};
-
-/* Declarations of routines to manipulate the module's configuration
- * info. Note that these are returned, and passed in, as void *'s;
- * the server core keeps track of them, but it doesn't, and can't,
- * know their internal structure.
- */
-
-void *make_cgi_server_config (pool *);
-void *merge_cgi_server_config (pool *, void *, void *);
-
-/* Declarations of routines to handle config-file commands */
-
-extern char *script_alias(cmd_parms *, void *per_dir_config, char *fake,
- char *real);
-
-command_rec cgi_cmds[] = {
-{ "ScriptAlias", script_alias, NULL, RSRC_CONF, TAKE2,
- "a fakename and a realname"},
-{ NULL }
-};
-
-module cgi_module = {
- STANDARD_MODULE_STUFF,
- NULL, /* initializer */
- NULL, /* dir config creator */
- NULL, /* dir merger --- default is to override */
- make_cgi_server_config, /* server config */
- merge_cgi_server_config, /* merge server config */
- cgi_cmds, /* command table */
- cgi_handlers, /* handlers */
- translate_scriptalias, /* filename translation */
- NULL, /* check_user_id */
- NULL, /* check auth */
- NULL, /* check access */
- type_scriptalias, /* type_checker */
- NULL, /* fixups */
- NULL /* logger */
-};
-</pre>
-
-<h2><a name="handlers">How handlers work</a></h2>
-
-The sole argument to handlers is a <code>request_rec</code> structure.
-This structure describes a particular request which has been made to
-the server, on behalf of a client. In most cases, each connection to
-the client generates only one <code>request_rec</code> structure.<p>
-
-<h3><a name="req_tour">A brief tour of the <code>request_rec</code></a></h3>
-
-The <code>request_rec</code> contains pointers to a resource pool
-which will be cleared when the server is finished handling the
-request; to structures containing per-server and per-connection
-information, and most importantly, information on the request itself.<p>
-
-The most important such information is a small set of character
-strings describing attributes of the object being requested, including
-its URI, filename, content-type and content-encoding (these being filled
-in by the translation and type-check handlers which handle the
-request, respectively). <p>
-
-Other commonly used data items are tables giving the MIME headers on
-the client's original request, MIME headers to be sent back with the
-response (which modules can add to at will), and environment variables
-for any subprocesses which are spawned off in the course of servicing
-the request. These tables are manipulated using the
-<code>table_get</code> and <code>table_set</code> routines. <p>
-
-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>&lt;Directory&gt;</code> sections), for private data it has
-built in the course of servicing the request (so modules' handlers for
-one phase can pass `notes' to their handlers for other phases). There
-is another such configuration vector in the <code>server_rec</code>
-data structure pointed to by the <code>request_rec</code>, which
-contains per (virtual) server configuration data.<p>
-
-Here is an abridged declaration, giving the fields most commonly used:<p>
-
-<pre>
-struct request_rec {
-
- pool *pool;
- conn_rec *connection;
- server_rec *server;
-
- /* What object is being requested */
-
- char *uri;
- char *filename;
- char *path_info;
- char *args; /* QUERY_ARGS, if any */
- struct stat finfo; /* Set by server core;
- * st_mode set to zero if no such file */
-
- char *content_type;
- char *content_encoding;
-
- /* MIME header environments, in and out. Also, an array containing
- * environment variables to be passed to subprocesses, so people can
- * write modules to add to that environment.
- *
- * The difference between headers_out and err_headers_out is that
- * the latter are printed even on error, and persist across internal
- * redirects (so the headers printed for ErrorDocument handlers will
- * have them).
- */
-
- table *headers_in;
- table *headers_out;
- table *err_headers_out;
- table *subprocess_env;
-
- /* Info about the request itself... */
-
- int header_only; /* HEAD request, as opposed to GET */
- char *protocol; /* Protocol, as given to us, or HTTP/0.9 */
- char *method; /* GET, HEAD, POST, etc. */
- int method_number; /* M_GET, M_POST, etc. */
-
- /* Info for logging */
-
- char *the_request;
- int bytes_sent;
-
- /* A flag which modules can set, to indicate that the data being
- * returned is volatile, and clients should be told not to cache it.
- */
-
- int no_cache;
-
- /* Various other config info which may change with .htaccess files
- * These are config vectors, with one void* pointer for each module
- * (the thing pointed to being the module's business).
- */
-
- void *per_dir_config; /* Options set in config files, etc. */
- void *request_config; /* Notes on *this* request */
-
-};
-
-</pre>
-
-<h3><a name="req_orig">Where request_rec structures come from</a></h3>
-
-Most <code>request_rec</code> structures are built by reading an HTTP
-request from a client, and filling in the fields. However, there are
-a few exceptions:
-
-<ul>
- <li> If the request is to an imagemap, a type map (i.e., a
- <code>*.var</code> file), or a CGI script which returned a
- local `Location:', then the resource which the user requested
- is going to be ultimately located by some URI other than what
- the client originally supplied. In this case, the server does
- an <em>internal redirect</em>, constructing a new
- <code>request_rec</code> for the new URI, and processing it
- almost exactly as if the client had requested the new URI
- directly. <p>
-
- <li> If some handler signaled an error, and an
- <code>ErrorDocument</code> is in scope, the same internal
- redirect machinery comes into play.<p>
-
- <li> Finally, a handler occasionally needs to investigate `what
- would happen if' some other request were run. For instance,
- the directory indexing module needs to know what MIME type
- would be assigned to a request for each directory entry, in
- order to figure out what icon to use.<p>
-
- Such handlers can construct a <em>sub-request</em>, using the
- functions <code>sub_req_lookup_file</code> and
- <code>sub_req_lookup_uri</code>; this constructs a new
- <code>request_rec</code> structure and processes it as you
- would expect, up to but not including the point of actually
- sending a response. (These functions skip over the access
- checks if the sub-request is for a file in the same directory
- as the original request).<p>
-
- (Server-side includes work by building sub-requests and then
- actually invoking the response handler for them, via the
- function <code>run_sub_request</code>).
-</ul>
-
-<h3><a name="req_return">Handling requests, declining, and returning error codes</a></h3>
-
-As discussed above, each handler, when invoked to handle a particular
-<code>request_rec</code>, has to return an <code>int</code> to
-indicate what happened. That can either be
-
-<ul>
- <li> OK --- the request was handled successfully. This may or may
- not terminate the phase.
- <li> DECLINED --- no erroneous condition exists, but the module
- declines to handle the phase; the server tries to find another.
- <li> an HTTP error code, which aborts handling of the request.
-</ul>
-
-Note that if the error code returned is <code>REDIRECT</code>, then
-the module should put a <code>Location</code> in the request's
-<code>headers_out</code>, to indicate where the client should be
-redirected <em>to</em>. <p>
-
-<h3><a name="resp_handlers">Special considerations for response handlers</a></h3>
-
-Handlers for most phases do their work by simply setting a few fields
-in the <code>request_rec</code> structure (or, in the case of access
-checkers, simply by returning the correct error code). However,
-response handlers have to actually send a request back to the client. <p>
-
-They should begin by sending an HTTP response header, using the
-function <code>send_http_header</code>. (You don't have to do
-anything special to skip sending the header for HTTP/0.9 requests; the
-function figures out on its own that it shouldn't do anything). If
-the request is marked <code>header_only</code>, that's all they should
-do; they should return after that, without attempting any further
-output. <p>
-
-Otherwise, they should produce a request body which responds to the
-client as appropriate. The primitives for this are <code>rputc</code>
-and <code>rprintf</code>, for internally generated output, and
-<code>send_fd</code>, to copy the contents of some <code>FILE *</code>
-straight to the client. <p>
-
-At this point, you should more or less understand the following piece
-of code, which is the handler which handles <code>GET</code> requests
-which have no more specific handler; it also shows how conditional
-<code>GET</code>s can be handled, if it's desirable to do so in a
-particular response handler --- <code>set_last_modified</code> checks
-against the <code>If-modified-since</code> value supplied by the
-client, if any, and returns an appropriate code (which will, if
-nonzero, be USE_LOCAL_COPY). No similar considerations apply for
-<code>set_content_length</code>, but it returns an error code for
-symmetry.<p>
-
-<pre>
-int default_handler (request_rec *r)
-{
- int errstatus;
- FILE *f;
-
- if (r-&gt;method_number != M_GET) return DECLINED;
- if (r-&gt;finfo.st_mode == 0) return NOT_FOUND;
-
- if ((errstatus = set_content_length (r, r-&gt;finfo.st_size))
- || (errstatus = set_last_modified (r, r-&gt;finfo.st_mtime)))
- return errstatus;
-
- f = fopen (r-&gt;filename, "r");
-
- if (f == NULL) {
- log_reason("file permissions deny server access",
- r-&gt;filename, r);
- return FORBIDDEN;
- }
-
- register_timeout ("send", r);
- send_http_header (r);
-
- if (!r-&gt;header_only) send_fd (f, r);
- pfclose (r-&gt;pool, f);
- return OK;
-}
-</pre>
-
-Finally, if all of this is too much of a challenge, there are a few
-ways out of it. First off, as shown above, a response handler which
-has not yet produced any output can simply return an error code, in
-which case the server will automatically produce an error response.
-Secondly, it can punt to some other handler by invoking
-<code>internal_redirect</code>, which is how the internal redirection
-machinery discussed above is invoked. A response handler which has
-internally redirected should always return <code>OK</code>. <p>
-
-(Invoking <code>internal_redirect</code> from handlers which are
-<em>not</em> response handlers will lead to serious confusion).
-
-<h3><a name="auth_handlers">Special considerations for authentication handlers</a></h3>
-
-Stuff that should be discussed here in detail:
-
-<ul>
- <li> Authentication-phase handlers not invoked unless auth is
- configured for the directory.
- <li> Common auth configuration stored in the core per-dir
- configuration; it has accessors <code>auth_type</code>,
- <code>auth_name</code>, and <code>requires</code>.
- <li> Common routines, to handle the protocol end of things, at least
- for HTTP basic authentication (<code>get_basic_auth_pw</code>,
- which sets the <code>connection-&gt;user</code> structure field
- automatically, and <code>note_basic_auth_failure</code>, which
- arranges for the proper <code>WWW-Authenticate:</code> header
- to be sent back).
-</ul>
-
-<h3><a name="log_handlers">Special considerations for logging handlers</a></h3>
-
-When a request has internally redirected, there is the question of
-what to log. Apache handles this by bundling the entire chain of
-redirects into a list of <code>request_rec</code> structures which are
-threaded through the <code>r-&gt;prev</code> and <code>r-&gt;next</code>
-pointers. The <code>request_rec</code> which is passed to the logging
-handlers in such cases is the one which was originally built for the
-initial request from the client; note that the bytes_sent field will
-only be correct in the last request in the chain (the one for which a
-response was actually sent).
-
-<h2><a name="pools">Resource allocation and resource pools</a></h2>
-
-One of the problems of writing and designing a server-pool server is
-that of preventing leakage, that is, allocating resources (memory,
-open files, etc.), without subsequently releasing them. The resource
-pool machinery is designed to make it easy to prevent this from
-happening, by allowing resource to be allocated in such a way that
-they are <em>automatically</em> released when the server is done with
-them. <p>
-
-The way this works is as follows: the memory which is allocated, file
-opened, etc., to deal with a particular request are tied to a
-<em>resource pool</em> which is allocated for the request. The pool
-is a data structure which itself tracks the resources in question. <p>
-
-When the request has been processed, the pool is <em>cleared</em>. At
-that point, all the memory associated with it is released for reuse,
-all files associated with it are closed, and any other clean-up
-functions which are associated with the pool are run. When this is
-over, we can be confident that all the resource tied to the pool have
-been released, and that none of them have leaked. <p>
-
-Server restarts, and allocation of memory and resources for per-server
-configuration, are handled in a similar way. There is a
-<em>configuration pool</em>, which keeps track of resources which were
-allocated while reading the server configuration files, and handling
-the commands therein (for instance, the memory that was allocated for
-per-server module configuration, log files and other files that were
-opened, and so forth). When the server restarts, and has to reread
-the configuration files, the configuration pool is cleared, and so the
-memory and file descriptors which were taken up by reading them the
-last time are made available for reuse. <p>
-
-It should be noted that use of the pool machinery isn't generally
-obligatory, except for situations like logging handlers, where you
-really need to register cleanups to make sure that the log file gets
-closed when the server restarts (this is most easily done by using the
-function <code><a href="#pool-files">pfopen</a></code>, which also
-arranges for the underlying file descriptor to be closed before any
-child processes, such as for CGI scripts, are <code>exec</code>ed), or
-in case you are using the timeout machinery (which isn't yet even
-documented here). However, there are two benefits to using it:
-resources allocated to a pool never leak (even if you allocate a
-scratch string, and just forget about it); also, for memory
-allocation, <code>palloc</code> is generally faster than
-<code>malloc</code>.<p>
-
-We begin here by describing how memory is allocated to pools, and then
-discuss how other resources are tracked by the resource pool
-machinery.
-
-<h3>Allocation of memory in pools</h3>
-
-Memory is allocated to pools by calling the function
-<code>palloc</code>, which takes two arguments, one being a pointer to
-a resource pool structure, and the other being the amount of memory to
-allocate (in <code>char</code>s). Within handlers for handling
-requests, the most common way of getting a resource pool structure is
-by looking at the <code>pool</code> slot of the relevant
-<code>request_rec</code>; hence the repeated appearance of the
-following idiom in module code:
-
-<pre>
-int my_handler(request_rec *r)
-{
- struct my_structure *foo;
- ...
-
- foo = (foo *)palloc (r->pool, sizeof(my_structure));
-}
-</pre>
-
-Note that <em>there is no <code>pfree</code></em> ---
-<code>palloc</code>ed memory is freed only when the associated
-resource pool is cleared. This means that <code>palloc</code> does not
-have to do as much accounting as <code>malloc()</code>; all it does in
-the typical case is to round up the size, bump a pointer, and do a
-range check.<p>
-
-(It also raises the possibility that heavy use of <code>palloc</code>
-could cause a server process to grow excessively large. There are
-two ways to deal with this, which are dealt with below; briefly, you
-can use <code>malloc</code>, and try to be sure that all of the memory
-gets explicitly <code>free</code>d, or you can allocate a sub-pool of
-the main pool, allocate your memory in the sub-pool, and clear it out
-periodically. The latter technique is discussed in the section on
-sub-pools below, and is used in the directory-indexing code, in order
-to avoid excessive storage allocation when listing directories with
-thousands of files).
-
-<h3>Allocating initialized memory</h3>
-
-There are functions which allocate initialized memory, and are
-frequently useful. The function <code>pcalloc</code> has the same
-interface as <code>palloc</code>, but clears out the memory it
-allocates before it returns it. The function <code>pstrdup</code>
-takes a resource pool and a <code>char *</code> as arguments, and
-allocates memory for a copy of the string the pointer points to,
-returning a pointer to the copy. Finally <code>pstrcat</code> is a
-varargs-style function, which takes a pointer to a resource pool, and
-at least two <code>char *</code> arguments, the last of which must be
-<code>NULL</code>. It allocates enough memory to fit copies of each
-of the strings, as a unit; for instance:
-
-<pre>
- pstrcat (r->pool, "foo", "/", "bar", NULL);
-</pre>
-
-returns a pointer to 8 bytes worth of memory, initialized to
-<code>"foo/bar"</code>.
-
-<h3>Tracking open files, etc.</h3>
-
-As indicated above, resource pools are also used to track other sorts
-of resources besides memory. The most common are open files. The
-routine which is typically used for this is <code>pfopen</code>, which
-takes a resource pool and two strings as arguments; the strings are
-the same as the typical arguments to <code>fopen</code>, e.g.,
-
-<pre>
- ...
- FILE *f = pfopen (r->pool, r->filename, "r");
-
- if (f == NULL) { ... } else { ... }
-</pre>
-
-There is also a <code>popenf</code> routine, which parallels the
-lower-level <code>open</code> system call. Both of these routines
-arrange for the file to be closed when the resource pool in question
-is cleared. <p>
-
-Unlike the case for memory, there <em>are</em> functions to close
-files allocated with <code>pfopen</code>, and <code>popenf</code>,
-namely <code>pfclose</code> and <code>pclosef</code>. (This is
-because, on many systems, the number of files which a single process
-can have open is quite limited). It is important to use these
-functions to close files allocated with <code>pfopen</code> and
-<code>popenf</code>, since to do otherwise could cause fatal errors on
-systems such as Linux, which react badly if the same
-<code>FILE*</code> is closed more than once. <p>
-
-(Using the <code>close</code> functions is not mandatory, since the
-file will eventually be closed regardless, but you should consider it
-in cases where your module is opening, or could open, a lot of files).
-
-<h3>Other sorts of resources --- cleanup functions</h3>
-
-More text goes here. Describe the the cleanup primitives in terms of
-which the file stuff is implemented; also, <code>spawn_process</code>.
-
-<h3>Fine control --- creating and dealing with sub-pools, with a note
-on sub-requests</h3>
-
-On rare occasions, too-free use of <code>palloc()</code> and the
-associated primitives may result in undesirably profligate resource
-allocation. You can deal with such a case by creating a
-<em>sub-pool</em>, allocating within the sub-pool rather than the main
-pool, and clearing or destroying the sub-pool, which releases the
-resources which were associated with it. (This really <em>is</em> a
-rare situation; the only case in which it comes up in the standard
-module set is in case of listing directories, and then only with
-<em>very</em> large directories. Unnecessary use of the primitives
-discussed here can hair up your code quite a bit, with very little
-gain). <p>
-
-The primitive for creating a sub-pool is <code>make_sub_pool</code>,
-which takes another pool (the parent pool) as an argument. When the
-main pool is cleared, the sub-pool will be destroyed. The sub-pool
-may also be cleared or destroyed at any time, by calling the functions
-<code>clear_pool</code> and <code>destroy_pool</code>, respectively.
-(The difference is that <code>clear_pool</code> frees resources
-associated with the pool, while <code>destroy_pool</code> also
-deallocates the pool itself. In the former case, you can allocate new
-resources within the pool, and clear it again, and so forth; in the
-latter case, it is simply gone). <p>
-
-One final note --- sub-requests have their own resource pools, which
-are sub-pools of the resource pool for the main request. The polite
-way to reclaim the resources associated with a sub request which you
-have allocated (using the <code>sub_req_lookup_...</code> functions)
-is <code>destroy_sub_request</code>, which frees the resource pool.
-Before calling this function, be sure to copy anything that you care
-about which might be allocated in the sub-request's resource pool into
-someplace a little less volatile (for instance, the filename in its
-<code>request_rec</code> structure). <p>
-
-(Again, under most circumstances, you shouldn't feel obliged to call
-this function; only 2K of memory or so are allocated for a typical sub
-request, and it will be freed anyway when the main request pool is
-cleared. It is only when you are allocating many, many sub-requests
-for a single main request that you should seriously consider the
-<code>destroy...</code> functions).
-
-<h2><a name="config">Configuration, commands and the like</a></h2>
-
-One of the design goals for this server was to maintain external
-compatibility with the NCSA 1.3 server --- that is, to read the same
-configuration files, to process all the directives therein correctly,
-and in general to be a drop-in replacement for NCSA. On the other
-hand, another design goal was to move as much of the server's
-functionality into modules which have as little as possible to do with
-the monolithic server core. The only way to reconcile these goals is
-to move the handling of most commands from the central server into the
-modules. <p>
-
-However, just giving the modules command tables is not enough to
-divorce them completely from the server core. The server has to
-remember the commands in order to act on them later. That involves
-maintaining data which is private to the modules, and which can be
-either per-server, or per-directory. Most things are per-directory,
-including in particular access control and authorization information,
-but also information on how to determine file types from suffixes,
-which can be modified by <code>AddType</code> and
-<code>DefaultType</code> directives, and so forth. In general, the
-governing philosophy is that anything which <em>can</em> be made
-configurable by directory should be; per-server information is
-generally used in the standard set of modules for information like
-<code>Alias</code>es and <code>Redirect</code>s which come into play
-before the request is tied to a particular place in the underlying
-file system. <p>
-
-Another requirement for emulating the NCSA server is being able to
-handle the per-directory configuration files, generally called
-<code>.htaccess</code> files, though even in the NCSA server they can
-contain directives which have nothing at all to do with access
-control. Accordingly, after URI -&gt; 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>&lt;Directory&gt;</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>&lt;Directory /&gt;</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>&lt;Directory&gt;</code> section, which includes one of the MIME
-module's commands, it needs to create a <code>mime_dir_config</code>
-structure, so those commands have something to act on. It does this
-by invoking the function it finds in the module's `create per-dir
-config slot', with two arguments: the name of the directory to which
-this configuration information applies (or <code>NULL</code> for
-<code>srm.conf</code>), and a pointer to a resource pool in which the
-allocation should happen. <p>
-
-(If we are reading a <code>.htaccess</code> file, that resource pool
-is the per-request resource pool for the request; otherwise it is a
-resource pool which is used for configuration data, and cleared on
-restarts. Either way, it is important for the structure being created
-to vanish when the pool is cleared, by registering a cleanup on the
-pool if necessary). <p>
-
-For the MIME module, the per-dir config creation function just
-<code>palloc</code>s the structure above, and a creates a couple of
-<code>table</code>s to fill it. That looks like this:
-
-<pre>
-void *create_mime_dir_config (pool *p, char *dummy)
-{
- mime_dir_config *new =
- (mime_dir_config *) palloc (p, sizeof(mime_dir_config));
-
- new-&gt;forced_types = make_table (p, 4);
- new-&gt;encoding_types = make_table (p, 4);
-
- return new;
-}
-</pre>
-
-Now, suppose we've just read in a <code>.htaccess</code> file. We
-already have the per-directory configuration structure for the next
-directory up in the hierarchy. If the <code>.htaccess</code> file we
-just read in didn't have any <code>AddType</code> or
-<code>AddEncoding</code> commands, its per-directory config structure
-for the MIME module is still valid, and we can just use it.
-Otherwise, we need to merge the two structures somehow. <p>
-
-To do that, the server invokes the module's per-directory config merge
-function, if one is present. That function takes three arguments:
-the two structures being merged, and a resource pool in which to
-allocate the result. For the MIME module, all that needs to be done
-is overlay the tables from the new per-directory config structure with
-those from the parent:
-
-<pre>
-void *merge_mime_dir_configs (pool *p, void *parent_dirv, void *subdirv)
-{
- mime_dir_config *parent_dir = (mime_dir_config *)parent_dirv;
- mime_dir_config *subdir = (mime_dir_config *)subdirv;
- mime_dir_config *new =
- (mime_dir_config *)palloc (p, sizeof(mime_dir_config));
-
- new-&gt;forced_types = overlay_tables (p, subdir-&gt;forced_types,
- parent_dir-&gt;forced_types);
- new-&gt;encoding_types = overlay_tables (p, subdir-&gt;encoding_types,
- parent_dir-&gt;encoding_types);
-
- return new;
-}
-</pre>
-
-As a note --- if there is no per-directory merge function present, the
-server will just use the subdirectory's configuration info, and ignore
-the parent's. For some modules, that works just fine (e.g., for the
-includes module, whose per-directory configuration information
-consists solely of the state of the <code>XBITHACK</code>), and for
-those modules, you can just not declare one, and leave the
-corresponding structure slot in the module itself <code>NULL</code>.<p>
-
-<h3><a name="commands">Command handling</a></h3>
-
-Now that we have these structures, we need to be able to figure out
-how to fill them. That involves processing the actual
-<code>AddType</code> and <code>AddEncoding</code> commands. To find
-commands, the server looks in the module's <code>command table</code>.
-That table contains information on how many arguments the commands
-take, and in what formats, where it is permitted, and so forth. That
-information is sufficient to allow the server to invoke most
-command-handling functions with pre-parsed arguments. Without further
-ado, let's look at the <code>AddType</code> command handler, which
-looks like this (the <code>AddEncoding</code> command looks basically
-the same, and won't be shown here):
-
-<pre>
-char *add_type(cmd_parms *cmd, mime_dir_config *m, char *ct, char *ext)
-{
- if (*ext == '.') ++ext;
- table_set (m-&gt;forced_types, ext, ct);
- return NULL;
-}
-</pre>
-
-This command handler is unusually simple. As you can see, it takes
-four arguments, two of which are pre-parsed arguments, the third being
-the per-directory configuration structure for the module in question,
-and the fourth being a pointer to a <code>cmd_parms</code> structure.
-That structure contains a bunch of arguments which are frequently of
-use to some, but not all, commands, including a resource pool (from
-which memory can be allocated, and to which cleanups should be tied),
-and the (virtual) server being configured, from which the module's
-per-server configuration data can be obtained if required.<p>
-
-Another way in which this particular command handler is unusually
-simple is that there are no error conditions which it can encounter.
-If there were, it could return an error message instead of
-<code>NULL</code>; this causes an error to be printed out on the
-server's <code>stderr</code>, followed by a quick exit, if it is in
-the main config files; for a <code>.htaccess</code> file, the syntax
-error is logged in the server error log (along with an indication of
-where it came from), and the request is bounced with a server error
-response (HTTP error status, code 500). <p>
-
-The MIME module's command table has entries for these commands, which
-look like this:
-
-<pre>
-command_rec mime_cmds[] = {
-{ "AddType", add_type, NULL, OR_FILEINFO, TAKE2,
- "a mime type followed by a file extension" },
-{ "AddEncoding", add_encoding, NULL, OR_FILEINFO, TAKE2,
- "an encoding (e.g., gzip), followed by a file extension" },
-{ NULL }
-};
-</pre>
-
-The entries in these tables are:
-
-<ul>
- <li> The name of the command
- <li> The function which handles it
- <li> a <code>(void *)</code> pointer, which is passed in the
- <code>cmd_parms</code> structure to the command handler ---
- this is useful in case many similar commands are handled by the
- same function.
- <li> A bit mask indicating where the command may appear. There are
- mask bits corresponding to each <code>AllowOverride</code>
- option, and an additional mask bit, <code>RSRC_CONF</code>,
- indicating that the command may appear in the server's own
- config files, but <em>not</em> in any <code>.htaccess</code>
- file.
- <li> A flag indicating how many arguments the command handler wants
- pre-parsed, and how they should be passed in.
- <code>TAKE2</code> indicates two pre-parsed arguments. Other
- options are <code>TAKE1</code>, which indicates one pre-parsed
- argument, <code>FLAG</code>, which indicates that the argument
- should be <code>On</code> or <code>Off</code>, and is passed in
- as a boolean flag, <code>RAW_ARGS</code>, which causes the
- server to give the command the raw, unparsed arguments
- (everything but the command name itself). There is also
- <code>ITERATE</code>, which means that the handler looks the
- same as <code>TAKE1</code>, but that if multiple arguments are
- present, it should be called multiple times, and finally
- <code>ITERATE2</code>, which indicates that the command handler
- looks like a <code>TAKE2</code>, but if more arguments are
- present, then it should be called multiple times, holding the
- first argument constant.
- <li> Finally, we have a string which describes the arguments that
- should be present. If the arguments in the actual config file
- are not as required, this string will be used to help give a
- more specific error message. (You can safely leave this
- <code>NULL</code>).
-</ul>
-
-Finally, having set this all up, we have to use it. This is
-ultimately done in the module's handlers, specifically for its
-file-typing handler, which looks more or less like this; note that the
-per-directory configuration structure is extracted from the
-<code>request_rec</code>'s per-directory configuration vector by using
-the <code>get_module_config</code> function.
-
-<pre>
-int find_ct(request_rec *r)
-{
- int i;
- char *fn = pstrdup (r->pool, r->filename);
- mime_dir_config *conf = (mime_dir_config *)
- get_module_config(r->per_dir_config, &amp;mime_module);
- char *type;
-
- if (S_ISDIR(r->finfo.st_mode)) {
- r->content_type = DIR_MAGIC_TYPE;
- return OK;
- }
-
- if((i=rind(fn,'.')) &lt; 0) return DECLINED;
- ++i;
-
- if ((type = table_get (conf->encoding_types, &amp;fn[i])))
- {
- r->content_encoding = type;
-
- /* go back to previous extension to try to use it as a type */
-
- fn[i-1] = '\0';
- if((i=rind(fn,'.')) &lt; 0) return OK;
- ++i;
- }
-
- if ((type = table_get (conf->forced_types, &amp;fn[i])))
- {
- r->content_type = type;
- }
-
- return OK;
-}
-
-</pre>
-
-<h3><a name="servconf">Side notes --- per-server configuration, virtual servers, etc.</a></h3>
-
-The basic ideas behind per-server module configuration are basically
-the same as those for per-directory configuration; there is a creation
-function and a merge function, the latter being invoked where a
-virtual server has partially overridden the base server configuration,
-and a combined structure must be computed. (As with per-directory
-configuration, the default if no merge function is specified, and a
-module is configured in some virtual server, is that the base
-configuration is simply ignored). <p>
-
-The only substantial difference is that when a command needs to
-configure the per-server private module data, it needs to go to the
-<code>cmd_parms</code> data to get at it. Here's an example, from the
-alias module, which also indicates how a syntax error can be returned
-(note that the per-directory configuration argument to the command
-handler is declared as a dummy, since the module doesn't actually have
-per-directory config data):
-
-<pre>
-char *add_redirect(cmd_parms *cmd, void *dummy, char *f, char *url)
-{
- server_rec *s = cmd->server;
- alias_server_conf *conf = (alias_server_conf *)
- get_module_config(s-&gt;module_config,&amp;alias_module);
- alias_entry *new = push_array (conf-&gt;redirects);
-
- if (!is_url (url)) return "Redirect to non-URL";
-
- new-&gt;fake = f; new-&gt;real = url;
- return NULL;
-}
-</pre>
-<!--#include virtual="footer.html" -->
-</body></html>
-
View
134 docs/manual/handler.html.en
@@ -1,134 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
-<HTML>
-<HEAD>
-<TITLE>Apache's Handler Use</TITLE>
-</HEAD>
-
-<BODY>
-<!--#include virtual="header.html" -->
-<h1>Apache's Handler Use</h1>
-
-<h2>What is a Handler</h2>
-
-<p>A "handler" is an internal Apache representation of the action to be
-performed when a file is called. Generally, files have implicit
-handlers, based on the file type. Normally, all files are simply
-served by the server, but certain file typed are "handled"
-separately. For example, you may use a type of
-"application/x-httpd-cgi" to invoke CGI scripts.</p>
-
-<p>Apache 1.1 adds the additional ability to use handlers
-explicitly. Either based on filename extensions or on location, these
-handlers are unrelated to file type. This is advantageous both because
-it is a more elegant solution, but it also allows for both a type
-<strong>and</strong> a handler to be associated with a file.</p>
-
-<p>Handlers can either be built into the server or to a module, or
-they can be added with the <a
-href="mod/mod_actions.html#action">Action</a> directive. The built-in
-handlers in the standard distribution are as follows:</p>
-
-<ul>
-<li><strong>send-as-is</strong>:
- Send file with HTTP headers as is.
- (<a href="mod/mod_asis.html">mod_asis</a>)
-<li><strong>cgi-script</strong>:
- Treat the file as a CGI script.
- (<a href="mod/mod_cgi.html">mod_cgi</a>)
-<li><strong>imap-file</strong>:
- Imagemap rule file.
- (<a href="mod/mod_imap.html">mod_imap</a>)
-<li><strong>server-info</strong>:
- Get the server's configuration information
- (<a href="mod/mod_info.html">mod_info</a>)
-<li><strong>server-parsed</strong>:
- Parse for server-side includes
- (<a href="mod/mod_include.html">mod_include</a>)
-<li><strong>server-status</strong>:
- Get the server's status report
- (<a href="mod/mod_status.html">mod_status</a>)
-<li><strong>type-map</strong>:
- Parse as a type map file for content negotiation
- (<a href="mod/mod_negotiation.html">mod_negotiation</a>)
-</ul>
-
-<p>
-
-<h2>Directives</h2>
-<ul>
-<li><A HREF="#addhandler">AddHandler</A>
-<li><A HREF="#sethandler">SetHandler</A>
-</ul>
-
-<hr>
-
-<h2><a name="addhandler">AddHandler</a></h2>
-
-<strong>Syntax:</strong> &lt;AddHandler <em>handler-name extension</em>&gt;<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> &lt;SetHandler <em>handler-name</em>&gt;<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>&lt;Directory&gt;</code> or <code>&lt;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>
- &lt;Location /status&gt;
- SetHandler server-status
- &lt;/Location&gt;
-</pre>
-
-<p><hr>
-
-<h2>Programmer's Note</h2>
-
-<p>In order to implement the handler features, an addition has been
-made to the <a href="misc/API.html">Apache API</a> that you may wish to
-make use of. Specifically, a new record has been added to the
-<code>request_rec</code> structure:</p>
-<pre>
- char *handler
-</pre>
-<p>If you wish to have your module engage a handler, you need only to
-set <code>r-&gt;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>
-
View
118 docs/manual/install.html.en
@@ -1,118 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
-<HTML>
-<HEAD>
-<TITLE>Compiling and Installing Apache</TITLE>
-</HEAD>
-
-<BODY>
-<!--#include virtual="header.html" -->
-<h1>Compiling and Installing Apache 1.2</h1>
-If you wish to download and install an earlier version of Apache please
-read <a href="install_1_1.html">Compiling and Installing Apache 1.1</a>.
-
-<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.
-
-<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>
-It is also necessary to choose the correct options for your platform.
-
-To do this:
-<ol>
-<li>
-Copy the file "<code>Configuration.tmpl</code>" to
-"<code>Configuration</code>" and then edit
-"<code>Configuration</code>". This contains the list and settings of various
-"Rules" and 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:
-<ul>
-<p><LI> Adjust the Rules and <code>EXTRA_CFLAGS|LIBS|LFLAGS|INCLUDES</code> if
- you feel so inclined.
-
-<p><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.
- (See <a href="misc/API.html">API.html</a> for preliminary docs on how to do that).
-</ul><p>
- Note that DBM auth has to be explicitly configured in, if you want
- it --- just uncomment the corresponding line.
-
-
-<p><li> Run the "<code>Configure</code>" script:
-<blockquote><pre>
- % Configure
- Using 'Configuration' as config file
- + configured for <whatever> platform
- + setting C compiler to <whatever> *
- + setting C compiler optimization-level to <whatever> *
- %
-</pre></blockquote>
- This generates new versions of the Makefile and of modules.c. (If
- you want to maintain multiple configurations, you can say, e.g.,
-<blockquote><pre>
- % Configure -file Configuration.ai
- Using alternate config file Configuration.ai
- + configured for <whatever> platform
- + setting C compiler to <whatever> *
- + setting C compiler optimization-level to <whatever> *
- %
-</pre></blockquote><p>
-*: Depending on Configuration and your system, Configure
- make not print these lines. That's OK
-
-<p><li> Type "<code>make</code>".
-<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="mod/core.html#accessconfig">AccessConfig</A> and
-<A HREF="mod/core.html#resourceconfig">ResourceConfig</A> directives in
-<code>httpd.conf</code>.
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
View
109 docs/manual/invoking.html.en
@@ -1,109 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
-<HTML>
-<HEAD>
-<TITLE>Starting Apache</TITLE>
-</HEAD>
-
-<BODY>
-<!--#include virtual="header.html" -->
-<h1>Starting Apache</h1>
-
-<h2>Invoking Apache</h2>
-The <code>httpd</code> program is usually run as a daemon which executes
-continuously, handling requests. It is possible to invoke Apache by
-the Internet daemon <code>inetd</code> each time a connection to the HTTP
-service is made (use the
-<A HREF="mod/core.html#servertype">ServerType</A> directive)
-but this is not recommended.
-
-<h2>Command line options</h2>
-The following options are recognized on the httpd command line:
-<dl>
-<dt><code>-d</code> <em>serverroot</em>
-<dd>Set the initial value for the
-<A HREF="mod/core.html#serverroot">ServerRoot</A> variable to
-<em>serverroot</em>. This can be overridden by the ServerRoot command in the
-configuration file. The default is <code>/usr/local/etc/httpd</code>.
-
-<dt><code>-f</code> <em>config</em>
-<dd>Execute the commands in the file <em>config</em> on startup. If
-<em>config</em> does not begin with a <code>/</code>, then it is taken to be a
-path relative to the <A HREF="mod/core.html#serverroot">ServerRoot</A>. The
-default is <code>conf/httpd.conf</code>.
-
-<dt><code>-X</code>
-<dd>Run in single-process mode, for internal debugging purposes only; the
-daemon does not detach from the terminal or fork any children. Do <em>NOT</em>
-use this mode to provide ordinary web service.
-
-<dt><code>-v</code>
-<dd>Print the version of httpd, and then exit.
-
-<dt><a name="help"><code>-h</code></a>
-<dd>Give a list of directives together with expected arguments and
-places where the directive is valid
-
-<dt><code>-l</code>
-<dd>Give a list of all modules compiled into the server
-
-<dt><code>-?</code>
-<dd>Print a list of the httpd options, and then exit.
-</dl>
-
-<h2>Configuration files</h2>
-The server will read three files for configuration directives. Any directive
-may appear in any of these files. The the names of these files are taken
-to be relative to the server root; this is set by the
-<A HREF="mod/core.html#serverroot">ServerRoot</A> directive, or the
-<code>-d</code> command line flag.
-
-Conventionally, the files are:
-<dl>
-<dt><code>conf/httpd.conf</code>
-<dd>Contains directives that control the operation of the server daemon.
-The filename may be overridden with the <code>-f</code> command line flag.
-
-<dt><code>conf/srm.conf</code>
-<dd>Contains directives that control the specification of documents that
-the server can provide to clients. The filename may be overridden with
-the <A HREF="mod/core.html#resourceconfig">ResourceConfig</A> directive.
-
-<dt><code>conf/access.conf</code>
-<dd>Contains directives that control access to documents.
-The filename may be overridden with the
-<A HREF="mod/core.html#accessconfig">AccessConfig</A> directive.
-</dl>
-However, these conventions need not be adhered to.
-<p>
-The server also reads a file containing mime document types; the filename
-is set by the <A HREF="mod_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="mod/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="mod/core.html#errorlog">ErrorLog</A> directive; different error logs can
-be set for different <A HREF="mod/core.html#virtualhost">virtual hosts</A>.
-
-<h3>Transfer log</h3>
-The server will typically log each request to a transfer file,
-<code>logs/access_log</code> by default. The filename can be set using a
-<A HREF="mod/mod_log_common.html#transferlog">TransferLog</A> directive; different
-transfer logs can be set for different <A HREF="mod/core.html#virtualhost">virtual
-hosts</A>.
-
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
View
213 docs/manual/platform/perf-bsd44.html
@@ -1,213 +0,0 @@
-<html>
-<head>
-<title>Running a High-Performance Web Server for BSD</title>
-</head>
-
-<body>
-<A NAME="initial">
-<!--#include virtual="header.html" -->
-</A>
-<H2>Running a High-Performance Web Server for BSD</H2>
-
-Like other OS's, the listen queue is often the <b>first limit hit</b>. The
-following are comments from "Aaron Gifford &lt;agifford@InfoWest.COM&gt;"
-on how to fix this on BSDI 1.x, 2.x, and FreeBSD 2.0 (and earlier):
-
-<p>
-
-Edit the following two files:
-<blockquote><code> /usr/include/sys/socket.h <br>
- /usr/src/sys/sys/socket.h </code></blockquote>
-In each file, look for the following:
-<pre>
- /*
- * Maximum queue length specifiable by listen.
- */
- #define SOMAXCONN 5
-</pre>
-
-Just change the "5" to whatever appears to work. I bumped the two
-machines I was having problems with up to 32 and haven't noticed the
-problem since.
-
-<p>
-
-After the edit, recompile the kernel and recompile the Apache server
-then reboot.
-
-<P>
-
-FreeBSD 2.1 seems to be perfectly happy, with SOMAXCONN
-set to 32 already.
-
-<p>
-
-<A NAME="detail">
-<b>Addendum for <i>very</i> heavily loaded BSD servers</b><br>
-</A>
-from Chuck Murcko &lt;chuck@telebase.com&gt;
-
-<p>
-
-If you're running a really busy BSD Apache server, the following are useful
-things to do if the system is acting sluggish:<p>
-
-<ul>
-
-<li> Run vmstat to check memory usage, page/swap rates, etc.
-
-<li> Run netstat -m to check mbuf usage
-
-<li> Run fstat to check file descriptor usage
-
-</ul>
-
-These utilities give you an idea what you'll need to tune in your kernel,
-and whether it'll help to buy more RAM.
-
-Here are some BSD kernel config parameters (actually BSDI, but pertinent to
-FreeBSD and other 4.4-lite derivatives) from a system getting heavy usage.
-The tools mentioned above were used, and the system memory was increased to
-48 MB before these tuneups. Other system parameters remained unchanged.
-
-<p>
-
-<pre>
-maxusers 256
-</pre>
-
-Maxusers drives a <i>lot</i> of other kernel parameters:
-
-<ul>
-
-<li> Maximum # of processes
-
-<li> Maximum # of processes per user
-
-<li> System wide open files limit
-
-<li> Per-process open files limit
-
-<li> Maximum # of mbuf clusters
-
-<li> Proc/pgrp hash table size
-
-</ul>
-
-The actual formulae for these derived parameters are in
-<i>/usr/src/sys/conf/param.c</i>.
-These calculated parameters can also be overridden (in part) by specifying
-your own values in the kernel configuration file:
-
-<pre>
-# Network options. NMBCLUSTERS defines the number of mbuf clusters and
-# defaults to 256. This machine is a server that handles lots of traffic,
-# so we crank that value.
-options SOMAXCONN=256 # max pending connects
-options NMBCLUSTERS=4096 # mbuf clusters at 4096
-
-#
-# Misc. options
-#
-options CHILD_MAX=512 # maximum number of child processes
-options OPEN_MAX=512 # maximum fds (breaks RPC svcs)
-</pre>
-
-SOMAXCONN is not derived from maxusers, so you'll always need to increase
-that yourself. We used a value guaranteed to be larger than Apache's
-default for the listen() of 128, currently.
-
-<p>
-
-In many cases, NMBCLUSTERS must be set much larger than would appear
-necessary at first glance. The reason for this is that if the browser
-disconnects in mid-transfer, the socket fd associated with that particular
-connection ends up in the TIME_WAIT state for several minutes, during
-which time its mbufs are not yet freed.
-
-<p>
-
-Some more info on mbuf clusters (from sys/mbuf.h):
-<pre>
-/*
- * Mbufs are of a single size, MSIZE (machine/machparam.h), which
- * includes overhead. An mbuf may add a single "mbuf cluster" of size
- * MCLBYTES (also in machine/machparam.h), which has no additional overhead
- * and is used instead of the internal data area; this is done when
- * at least MINCLSIZE of data must be stored.
- */
-</pre>
-
-<p>
-
-CHILD_MAX and OPEN_MAX are set to allow up to 512 child processes (different
-than the maximum value for processes per user ID) and file descriptors.
-These values may change for your particular configuration (a higher OPEN_MAX
-value if you've got modules or CGI scripts opening lots of connections or
-files). If you've got a lot of other activity besides httpd on the same
-machine, you'll have to set NPROC higher still. In this example, the NPROC
-value derived from maxusers proved sufficient for our load.
-
-<p>
-
-<b>Caveats</b>
-
-<p>
-
-Be aware that your system may not boot with a kernel that is configured
-to use more resources than you have available system RAM. <b>ALWAYS</b>
-have a known bootable kernel available when tuning your system this way,
-and use the system tools beforehand to learn if you need to buy more
-memory before tuning.
-
-<p>
-
-RPC services will fail when the value of OPEN_MAX is larger than 256.
-This is a function of the original implementations of the RPC library,
-which used a byte value for holding file descriptors. BSDI has partially
-addressed this limit in its 2.1 release, but a real fix may well await
-the redesign of RPC itself.
-
-<p>
-
-Finally, there's the hard limit of child processes configured in Apache.
-
-<p>
-
-For versions of Apache later than 1.0.5 you'll need to change the
-definition for <b>HARD_SERVER_LIMIT</b> in <i>httpd.h</i> and recompile
-if you need to run more than the default 150 instances of httpd.
-
-<p>
-
-From conf/httpd.conf-dist:
-
-<pre>
-# Limit on total number of servers running, i.e., limit on the number
-# of clients who can simultaneously connect --- if this limit is ever
-# reached, clients will be LOCKED OUT, so it should NOT BE SET TOO LOW.
-# It is intended mainly as a brake to keep a runaway server from taking
-# Unix with it as it spirals down...
-
-MaxClients 150
-</pre>
-
-Know what you're doing if you bump this value up, and make sure you've
-done your system monitoring, RAM expansion, and kernel tuning beforehand.
-Then you're ready to service some serious hits!
-
-<p>
-
-Thanks to <i>Tony Sanders</i> and <i>Chris Torek</i> at BSDI for their
-helpful suggestions and information.
-
-<P><HR>
-
-<H3>More welcome!</H3>
-
-If you have tips to contribute, send mail to <a
-href="mailto:brian@organic.com">brian@organic.com</a>
-
-<!--#include virtual="footer.html" -->
-</body></html>
-
View
271 docs/manual/platform/perf-dec.html
@@ -1,271 +0,0 @@
-<HEAD>
-<TITLE>Performance Tuning Tips for Digital Unix</TITLE>
-</HEAD>
-<BODY>
-<!--#include virtual="header.html" -->
-<H1>Performance Tuning Tips for Digital Unix</H1>
-
-Below is a set of newsgroup posts made by an engineer from DEC in
-response to queries about how to modify DEC's Digital Unix OS for more
-heavily loaded web sites. Copied with permission.
-
-<HR>
-
-<H2>Update</H2>
-From: Jeffrey Mogul <mogul@pa.dec.com><BR>
-Date: Fri, 28 Jun 96 16:07:56 MDT<BR>
-
-<OL>
-<LI> The advice given in the README file regarding the
- "tcbhashsize" variable is incorrect. The largest value
- this should be set to is 1024. Setting it any higher
- will have the perverse result of disabling the hashing
- mechanism.
-
-<LI>Patch ID OSF350-146 has been superseded by
-<blockquote>
- Patch ID OSF350-195 for V3.2C<BR>
- Patch ID OSF360-350195 for V3.2D
-</blockquote>
- Patch IDs for V3.2E and V3.2F should be available soon.
- There is no known reason why the Patch ID OSF360-350195
- won't work on these releases, but such use is not officially
- supported by Digital. This patch kit will not be needed for
- V3.2G when it is released.
-</UL>
-
-<HR>
-
-
-<PRE>
-From mogul@pa.dec.com (Jeffrey Mogul)
-Organization DEC Western Research
-Date 30 May 1996 00:50:25 GMT
-Newsgroups <A HREF="news:comp.unix.osf.osf1">comp.unix.osf.osf1</A>
-Message-ID <A HREF="news:4oirch$bc8@usenet.pa.dec.com">&lt;4oirch$bc8@usenet.pa.dec.com&gt;</A>
-Subject Re: Web Site Performance
-References 1
-
-
-
-In article &lt;skoogDs54BH.9pF@netcom.com&gt; skoog@netcom.com (Jim Skoog) writes:
-&gt;Where are the performance bottlenecks for Alpha AXP running the
-&gt;Netscape Commerce Server 1.12 with high volume internet traffic?
-&gt;We are evaluating network performance for a variety of Alpha AXP
-&gt;runing DEC UNIX 3.2C, which run DEC's seal firewall and behind
-&gt;that Alpha 1000 and 2100 webservers.
-
-Our experience (running such Web servers as <A HREF="http://altavista.digital.com">altavista.digital.com</A>
-and <A HREF="http://www.digital.com">www.digital.com</A>) is that there is one important kernel tuning
-knob to adjust in order to get good performance on V3.2C. You
-need to patch the kernel global variable "somaxconn" (use dbx -k
-to do this) from its default value of 8 to something much larger.
-
-How much larger? Well, no larger than 32767 (decimal). And
-probably no less than about 2048, if you have a really high volume
-(millions of hits per day), like AltaVista does.
-
-This change allows the system to maintain more than 8 TCP
-connections in the SYN_RCVD state for the HTTP server. (You
-can use "netstat -An |grep SYN_RCVD" to see how many such
-connections exist at any given instant).
-
-If you don't make this change, you might find that as the load gets
-high, some connection attempts take a very long time. And if a lot
-of your clients disconnect from the Internet during the process of
-TCP connection establishment (this happens a lot with dialup
-users), these "embryonic" connections might tie up your somaxconn
-quota of SYN_RCVD-state connections. Until the kernel times out
-these embryonic connections, no other connections will be accepted,
-and it will appear as if the server has died.
-
-The default value for somaxconn in Digital UNIX V4.0 will be quite
-a bit larger than it has been in previous versions (we inherited
-this default from 4.3BSD).
-
-Digital UNIX V4.0 includes some other performance-related changes
-that significantly improve its maximum HTTP connection rate. However,
-we've been using V3.2C systems to front-end for altavista.digital.com
-with no obvious performance bottlenecks at the millions-of-hits-per-day
-level.
-
-We have some Webstone performance results available at
- <A HREF="http://www.digital.com/info/alphaserver/news/webff.html">http://www.digital.com/info/alphaserver/news/webff.html</A>
-I'm not sure if these were done using V4.0 or an earlier version
-of Digital UNIX, although I suspect they were done using a test
-version of V4.0.
-
--Jeff
-
-<HR>
-
-----------------------------------------------------------------------------
-
-From mogul@pa.dec.com (Jeffrey Mogul)
-Organization DEC Western Research
-Date 31 May 1996 21:01:01 GMT
-Newsgroups <A HREF="news:comp.unix.osf.osf1">comp.unix.osf.osf1</A>
-Message-ID <A HREF="news:4onmmd$mmd@usenet.pa.dec.com">&lt;4onmmd$mmd@usenet.pa.dec.com&gt;</A>
-Subject Digital UNIX V3.2C Internet tuning patch info
-
-----------------------------------------------------------------------------
-
-Something that probably few people are aware of is that Digital
-has a patch kit available for Digital UNIX V3.2C that may improve
-Internet performance, especially for busy web servers.
-
-This patch kit is one way to increase the value of somaxconn,
-which I discussed in a message here a day or two ago.
-
-I've included in this message the revised README file for this
-patch kit below. Note that the original README file in the patch
-kit itself may be an earlier version; I'm told that the version
-below is the right one.
-
-Sorry, this patch kit is NOT available for other versions of Digital
-UNIX. Most (but not quite all) of these changes also made it into V4.0,
-so the description of the various tuning parameters in this README
-file might be useful to people running V4.0 systems.
-
-This patch kit does not appear to be available (yet?) from
- <A HREF="http://www.service.digital.com/html/patch_service.html">http://www.service.digital.com/html/patch_service.html</A>
-so I guess you'll have to call Digital's Customer Support to get it.
-
--Jeff
-
-DESCRIPTION: Digital UNIX Network tuning patch
-
- Patch ID: OSF350-146
-
- SUPERSEDED PATCHES: OSF350-151, OSF350-158
-
- This set of files improves the performance of the network
- subsystem on a system being used as a web server. There are
- additional tunable parameters included here, to be used
- cautiously by an informed system administrator.
-
-TUNING
-
- To tune the web server, the number of simultaneous socket
- connection requests are limited by:
-
- somaxconn Sets the maximum number of pending requests
- allowed to wait on a listening socket. The
- default value in Digital UNIX V3.2 is 8.
- This patch kit increases the default to 1024,
- which matches the value in Digital UNIX V4.0.
-
- sominconn Sets the minimum number of pending connections
- allowed on a listening socket. When a user
- process calls listen with a backlog less
- than sominconn, the backlog will be set to
- sominconn. sominconn overrides somaxconn.
- The default value is 1.
-
- The effectiveness of tuning these parameters can be monitored by
- the sobacklog variables available in the kernel:
-
- sobacklog_hiwat Tracks the maximum pending requests to any
- socket. The initial value is 0.
-
- sobacklog_drops Tracks the number of drops exceeding the
- socket set backlog limit. The initial
- value is 0.
-
- somaxconn_drops Tracks the number of drops exceeding the
- somaxconn limit. When sominconn is larger
- than somaxconn, tracks the number of drops
- exceeding sominconn. The initial value is 0.
-
- TCP timer parameters also affect performance. Tuning the following
- require some knowledge of the characteristics of the network.
-
- tcp_msl Sets the tcp maximum segment lifetime.
- This is the maximum lifetime in half
- seconds that a packet can be in transit
- on the network. This value, when doubled,
- is the length of time a connection remains
- in the TIME_WAIT state after a incoming
- close request is processed. The unit is
- specified in 1/2 seconds, the initial
- value is 60.
-
- tcp_rexmit_interval_min
- Sets the minimum TCP retransmit interval.
- For some WAN networks the default value may
- be too short, causing unnecessary duplicate
- packets to be sent. The unit is specified
- in 1/2 seconds, the initial value is 1.
-
- tcp_keepinit This is the amount of time a partially
- established connection will sit on the listen
- queue before timing out (e.g. if a client
- sends a SYN but never answers our SYN/ACK).
- Partially established connections tie up slots
- on the listen queue. If the queue starts to
- fill with connections in SYN_RCVD state,
- tcp_keepinit can be decreased to make those
- partial connects time out sooner. This should
- be used with caution, since there might be
- legitimate clients that are taking a while
- to respond to SYN/ACK. The unit is specified
- in 1/2 seconds, the default value is 150
- (ie. 75 seconds).
-
- The hashlist size for the TCP inpcb lookup table is regulated by:
-
- tcbhashsize The number of hash buckets used for the
- TCP connection table used in the kernel.
- The initial value is 32. For best results,
- should be specified as a power of 2. For
- busy Web servers, set this to 2048 or more.
-
- The hashlist size for the interface alias table is regulated by:
-
- inifaddr_hsize The number of hash buckets used for the
- interface alias table used in the kernel.
- The initial value is 32. For best results,
- should be specified as a power of 2.
-
- ipport_userreserved The maximum number of concurrent non-reserved,
- dynamically allocated ports. Default range
- is 1025-5000. The maximum value is 65535.
- This limits the numer of times you can
- simultaneously telnet or ftp out to connect
- to other systems.
-
- tcpnodelack Don't delay acknowledging TCP data; this
- can sometimes improve performance of locally
- run CAD packages. Default is value is 0,
- the enabled value is 1.
-
- Digital UNIX version:
-
- V3.2C
-Feature V3.2C patch V4.0
- ======= ===== ===== ====
-somaxconn X X X
-sominconn - X X
-sobacklog_hiwat - X -
-sobacklog_drops - X -
-somaxconn_drops - X -
-tcpnodelack X X X
-tcp_keepidle X X X
-tcp_keepintvl X X X
-tcp_keepcnt - X X
-tcp_keepinit - X X
-TCP keepalive per-socket - - X
-tcp_msl - X -
-tcp_rexmit_interval_min - X -
-TCP inpcb hashing - X X
-tcbhashsize - X X
-interface alias hashing - X X
-inifaddr_hsize - X X
-ipport_userreserved - X -
-sysconfig -q inet - - X
-sysconfig -q socket - - X
-
-</PRE>
-<!--#include virtual="footer.html" -->
-</BODY>
-</HTML>
View
132 docs/manual/platform/perf.html
@@ -1,132 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
-<html>
-<head>
-<title>Hints on Running a High-Performance Web Server</title>
-</head>
-
-<body>
-<!--#include virtual="header.html" -->
-<h2>Hints on Running a High-Performance Web Server</H2>
-
-Running Apache on a heavily loaded web server, one often encounters
-problems related to the machine and OS configuration. "Heavy" is
-relative, of course - but if you are seeing more than a couple hits
-per second on a sustained basis you should consult the pointers on
-this page. In general the suggestions involve how to tune your kernel
-for the heavier TCP load, hardware/software conflicts that arise, etc.
-
-<UL>
-<LI><A HREF="#AUX">A/UX (Apple's UNIX)</A>
-<LI><A HREF="#BSD">BSD-based (BSDI, FreeBSD, etc)</A>
-<LI><A HREF="#DEC">Digital UNIX</A>
-<LI><A HREF="#HP">Hewlett-Packard</A>
-<LI><A HREF="#Linux">Linux</A>
-<LI><A HREF="#SGI">SGI</A>
-<LI><A HREF="#Solaris">Solaris</A>
-<LI><A HREF="#SunOS">SunOS 4.x</A>
-</UL>
-
-<HR>
-
-<A NAME="AUX">
-<H3>A/UX (Apple's UNIX)</H3>
-</A>
-
-If you are running Apache on A/UX, a page that gives some helpful
-performance hints (concerning the <I>listen()</I> queue and using
-virtual hosts)
-<A HREF="http://www.jaguNET.com/apache.html">can be found here</A>
-
-<P><HR>
-
-<A NAME="BSD">
-<H3>BSD-based (BSDI, FreeBSD, etc)</H3>
-</A>
-
-<A HREF="perf-bsd44.html#initial">Quick</A> and
-<A HREF="perf-bsd44.html#detail">detailed</A>
-performance tuning hints for BSD-derived systems.
-
-<P><HR>
-
-<A NAME="DEC">
-<H3>Digital UNIX</H3>
-</A>
-
-We have some <A HREF="perf-dec.html">newsgroup postings</A> on how to
-tune Digital UNIX 3.2 and 4.0.
-
-<P><HR>
-
-<A NAME="HP">
-<H3>Hewlett-Packard</H3>
-</A>
-
-Some documentation on tuning HP machines can be found at <A
-HREF="http://www.software.hp.com/internet/perf/tuning.html">http://www.software.hp.com/internet/perf/tuning.html</A>.
-
-<P><HR>
-
-<A NAME="Linux">
-<H3>Linux</H3>
-</A>
-
-The most common problem on Linux shows up on heavily-loaded systems
-where the whole server will appear to freeze for a couple of minutes
-at a time, and then come back to life. This has been traced to a
-listen() queue overload - certain Linux implementations have a low
-value set for the incoming connection queue which can cause problems.
-Please see our <a
-href="http://www.qosina.com/~awm/apache/linux-tcp.html">Using Apache on
-Linux</a> page for more info on how to fix this.
-
-<P><HR>
-
-<A NAME="SGI">
-<H3>SGI</H3>
-
-<UL>
-<LI><A HREF="http://www.sgi.com/Products/WebFORCE/TuningGuide.html">
-WebFORCE Web Server Tuning Guidelines for IRIX 5.3,
-&lt;http://www.sgi.com/Products/WebFORCE/TuningGuide.html&gt;</A>
-</UL>
-
-<P><HR>
-
-<A NAME="Solaris">
-<H3>Solaris 2.4</H3>
-</A>
-
-The Solaris 2.4 TCP implementation has a few inherent limitations that
-only became apparent under heavy loads. This has been fixed to some
-extent in 2.5 (and completely revamped in 2.6), but for now consult
-the following URL for tips on how to expand the capabilities if you
-are finding slowdowns and lags are hurting performance.
-
-<UL>
-
-<LI><A href="http://www.sun.com/sun-on-net/Sun.Internet.Solutions/performance/">
-World Wide Web Server Performance,
-&lt;http://www.sun.com/sun-on-net/Sun.Internet.Solutions/performance/&gt;</a>
-</UL>
-
-<P><HR>
-
-<A NAME="SunOS">
-<H3>SunOS 4.x</H3>
-</A>
-
-More information on tuning SOMAXCONN on SunOS can be found at
-<A HREF="http://www.islandnet.com/~mark/somaxconn.html">
-http://www.islandnet.com/~mark/somaxconn.html</A>.
-
-<P><HR>
-
-<H3>More welcome!</H3>
-
-If you have tips to contribute, send mail to <a
-href="mailto:brian@organic.com">brian@organic.com</a>
-
-<!--#include virtual="footer.html" -->
-</body></html>
-
View
164 docs/manual/suexec.html.en
@@ -1,164 +0,0 @@
-<html><head>
-<title>Apache SetUserID Support</title>
-</head><body>
-
-<!--#include virtual="header.html" -->
-<h1>Apache suEXEC Support</h1>
-
-<hr>
-
-<h3>What is suEXEC?</h3>
-The <b>suEXEC</b> feature, introduced in Apache 1.2 provides the ability to
-run <b>CGI</b> programs under user ids different from the user id of the
-calling web-server. Used properly, this feature can reduce considerably the
-insecurity of allowing users to run CGI programs. At the same time, improperly
-configured, this facility can crash your computer, burn your house down and
-steal all the money from your retirement fund. <b>:-)</b> If you aren't
-familiar with managing setuid root programs and the security issues they
-present, we highly recommend that you not consider using this feature.<p>
-
-<hr>
-
-<h3>Enabling suEXEC Support</h3>
-Having said all that, enabling this feature is purposefully difficult with
-the intent that it will only be installed by users determined to use it and
-is not part of the normal install/compile process.<p>
-
-<ul>
-<h3>Configuring the suEXEC wrapper</h3>
-From the top-level of the Apache source tree, type:&nbsp;&nbsp;<b><code>cd support [ENTER]</code></b><p>
-Edit the <code>suexec.h</code> file and change the following macros to match your
-local Apache installation.<p>
-<i>From support/suexec.h</i>
-<code>
-<pre>
-/*
- * HTTPD_USER -- Define as the username under which Apache normally
- * runs. This is the only user allowed to execute
- * this program.
- */
-#define HTTPD_USER "www"
-
-/*
- * LOG_EXEC -- Define this as a filename if you want all suEXEC
- * transactions and errors logged for auditing and
- * debugging purposes.
- */
-#define LOG_EXEC "/usr/local/etc/httpd/logs/cgi.log"
-
-/*
- * DOC_ROOT -- Define as the DocumentRoot set for Apache. This
- * will be the only hierarchy (aside from UserDirs)
- * that can be used for suEXEC behavior.
- */
-#define DOC_ROOT "/usr/local/etc/httpd/htdocs"
-
-/*
- * NNAME -- Define this as the name for the nobody account
- * on your operating system. Most systems will just
- * need the default 'nobody'.
- */
-#define NNAME "nobody"
-
-/* NGID -- Define this as the *number* for the nogroup group
- * on your operating system. Most systems will have
- * a -1 or -2. Others might have something above
- * 65000.
- */
-#define NGID -1
-</pre>
-</code>
-
-<h3>Compiling the suEXEC wrapper</h3>
-At the shell command prompt, type:&nbsp;&nbsp;<b><code>cc suexec.c -o suexec [ENTER]</code></b>.<p>
-This should create the <b><em>suexec</em></b> wrapper executable.
-
-<h3>Compiling Apache for suEXEC support</h3>
-By default, Apache is compiled to look for the suEXEC wrapper in the following
-location.<p>
-<i>From src/httpd.h</i>
-<code>
-<pre>
-/* The path to the suEXEC wrapper */
-#ifndef SUEXEC_BIN
-#define SUEXEC_BIN "/usr/local/etc/httpd/sbin/suexec"
-#endif
-</pre>
-</code>
-<p>
-If your installation requires location of the wrapper program in a different
-directory, edit src/httpd.h and recompile your Apache server. See <a href="install.html">Compiling and Installing Apache</a> for more info on this process.<p>
-
-<h3>Installing the suEXEC wrapper</h3>
-Copy the <b><em>suexec</em></b> executable created in the exercise above to the defined
-location for <b>SUEXEC_BIN</b>.<p>
-In order for the wrapper to set the user id for execution requests it must me installed
-as owner <b><em>root</em></b> and must have the setuserid execution bit set for file modes.
-If you are not running a <b><em>root</em></b> user shell, do so now and execute the following
-commands.<p>
-
-<b><code>chown root /usr/local/etc/httpd/sbin/suexec [ENTER]</code></b><p>
-<b><code>chmod 4711 /usr/local/etc/httpd/sbin/suexec [ENTER]</code></b><p>
-
-<i>Change the path to the suEXEC wrapper to match your system installation.</i>
-</ul>
-
-<hr>
-
-<a name="model"></a>
-<h3>Security Model of suEXEC</h3>
-The <b>suEXEC</b> wrapper supplied with Apache performs the following security
-checks before it will execute any program passed to it for execution.
-<ol>
-<li>User executing the wrapper <b>must be a valid user on this system</b>.
-<li>User executing the wrapper <b>must be the compiled in HTTPD_USER</b>.
-<li>The command that the request wishes to execute <b>must not contain a /</b>.
-<li>The command being executed <b>must reside under the compiled in DOC_ROOT</b>.
-<li>The current working directory <b>must be a directory</b>.
-<li>The current working directory <b>must not be writable by <em>group</em> or <em>other</em></b>.
-<li>The command being executed <b>cannot be a symbolic link</b>.
-<li>The command being executed <b>cannot be writable by <em>group</em> or <em>other</em></b>.
-<li>The command being executed <b>cannot be a <em>setuid</em> or <em>setgid</em> program</b>.
-<li>The target UID and GID <b>must be a valid user and group on this system</b>.
-<li>The target UID and GID to execute as, <b>must match the UID and GID of the directory</b>.
-<li>The target execution UID and GID <b>must not be the privledged ID 0</b>.
-<li>Group access list is set to NOGROUP and the command is executed.
-</ol>
-If any of these issues are too restrictive, or do not seem restrictive enough, you are
-welcome to install your own version of the wrapper. We've given you the rope, now go
-have fun with it. <b>:-)</b>
-
-<hr>
-
-<h3>Using suEXEC</h3>
-After properly installing the <b>suexec</b> wrapper executable, you must kill and restart
-the Apache server. A simple <code><b>kill -1 `cat httpd.pid`</b></code> will not be enough.
-Upon startup of the web-server, if Apache finds a properly configured <b>suexec</b> wrapper,
-it will print the following message to the console.<p>
-
-<code>Configuring Apache for use with suexec wrapper.</code><p>
-
-If you don't see this message at server startup, the server is most likely not finding the
-wrapper program where it expects it, or the executable is not installed <b><em>setuid root</em></b>. Check your installation and try again.<p>
-
-One way to use <b>suEXEC</b> is through the <a href="mod/core.html#user"><b>User</b></a> and <a href="mod/core.html#group"><b>Group</b></a> directives in <a href="mod/core.html#virtualhost"><b>VirtualHost</b></a> definitions. By setting these directives to values
-different from the main server user id, all requests for CGI resources will be executed as
-the <b>User</b> and <b>Group</b> defined for that <b>&lt;VirtualHost&gt;</b>. If only one or
-neither of these directives are specified for a <b>&lt;VirtualHost&gt;</b> then the main
-server userid is assumed.<p>
-
-<b>suEXEC</b> can also be used to to execute CGI programs as the user to which the request
-is being directed. This is accomplished by using the <b>~</b> character prefixing the
-user id for whom execution is desired. The only requirement needed for this feature to work
-is for CGI execution to be enabled for the user and that the script must meet the scrutiny of the <a href="#model">security checks</a> above.
-
-<hr>
-
-<h3>Debugging suEXEC</h3>
-The suEXEC wrapper will write log information to the location defined in the <code>suexec.h</code> as indicated above. If you feel you have configured and installed the wrapper properly,
-have a look at this log and the error_log for the server to see where you may have gone astray.
-<!--#include virtual="footer.html" -->
-
-</BODY>
-</HTML>
-
Please sign in to comment.
Something went wrong with that request. Please try again.