diff options
| author | Bob Beck <beck@cvs.openbsd.org> | 1998-03-25 07:08:54 +0000 |
|---|---|---|
| committer | Bob Beck <beck@cvs.openbsd.org> | 1998-03-25 07:08:54 +0000 |
| commit | 3f4ed824e7361dfbc5dae85d166deba9ba40590c (patch) | |
| tree | 5bd32792ece705c7a120022780079c337f60e041 /usr.sbin/httpd/htdocs/manual/misc | |
| parent | c62e56f3daf49ddbe42e2f80b0bde4b6a322fca0 (diff) | |
Initial import from apache 1.2.6
Diffstat (limited to 'usr.sbin/httpd/htdocs/manual/misc')
19 files changed, 6209 insertions, 0 deletions
diff --git a/usr.sbin/httpd/htdocs/manual/misc/API.html b/usr.sbin/httpd/htdocs/manual/misc/API.html new file mode 100644 index 00000000000..1ad15723ed3 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/misc/API.html @@ -0,0 +1,1017 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<html><head> +<title>Apache API notes</title> +</head> +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<h1 ALIGN="CENTER">Apache API notes</h1> + +These are some notes on the Apache API and the data structures you +have to deal with, etc. They are not yet nearly complete, but +hopefully, they will help you get your bearings. Keep in mind that +the API is still subject to change as we gain experience with it. +(See the TODO file for what <em>might</em> be coming). However, +it will be easy to adapt modules to any changes that are made. +(We have more modules to adapt than you do). +<p> + +A few notes on general pedagogical style here. In the interest of +conciseness, all structure declarations here are incomplete --- the +real ones have more slots that I'm not telling you about. For the +most part, these are reserved to one component of the server core or +another, and should be altered by modules with caution. However, in +some cases, they really are things I just haven't gotten around to +yet. Welcome to the bleeding edge.<p> + +Finally, here's an outline, to give you some bare idea of what's +coming up, and in what order: + +<ul> +<li> <a href="#basics">Basic concepts.</a> +<menu> + <li> <a href="#HMR">Handlers, Modules, and Requests</a> + <li> <a href="#moduletour">A brief tour of a module</a> +</menu> +<li> <a href="#handlers">How handlers work</a> +<menu> + <li> <a href="#req_tour">A brief tour of the <code>request_rec</code></a> + <li> <a href="#req_orig">Where request_rec structures come from</a> + <li> <a href="#req_return">Handling requests, declining, and returning error codes</a> + <li> <a href="#resp_handlers">Special considerations for response handlers</a> + <li> <a href="#auth_handlers">Special considerations for authentication handlers</a> + <li> <a href="#log_handlers">Special considerations for logging handlers</a> +</menu> +<li> <a href="#pools">Resource allocation and resource pools</a> +<li> <a href="#config">Configuration, commands and the like</a> +<menu> + <li> <a href="#per-dir">Per-directory configuration structures</a> + <li> <a href="#commands">Command handling</a> + <li> <a href="#servconf">Side notes --- per-server configuration, virtual servers, etc.</a> +</menu> +</ul> + +<h2><a name="basics">Basic concepts.</a></h2> + +We begin with an overview of the basic concepts behind the +API, and how they are manifested in the code. + +<h3><a name="HMR">Handlers, Modules, and Requests</a></h3> + +Apache breaks down request handling into a series of steps, more or +less the same way the Netscape server API does (although this API has +a few more stages than NetSite does, as hooks for stuff I thought +might be useful in the future). These are: + +<ul> + <li> URI -> Filename translation + <li> Auth ID checking [is the user who they say they are?] + <li> Auth access checking [is the user authorized <em>here</em>?] + <li> Access checking other than auth + <li> Determining MIME type of the object requested + <li> `Fixups' --- there aren't any of these yet, but the phase is + intended as a hook for possible extensions like + <code>SetEnv</code>, which don't really fit well elsewhere. + <li> Actually sending a response back to the client. + <li> Logging the request +</ul> + +These phases are handled by looking at each of a succession of +<em>modules</em>, looking to see if each of them has a handler for the +phase, and attempting invoking it if so. The handler can typically do +one of three things: + +<ul> + <li> <em>Handle</em> the request, and indicate that it has done so + by returning the magic constant <code>OK</code>. + <li> <em>Decline</em> to handle the request, by returning the magic + integer constant <code>DECLINED</code>. In this case, the + server behaves in all respects as if the handler simply hadn't + been there. + <li> Signal an error, by returning one of the HTTP error codes. + This terminates normal handling of the request, although an + ErrorDocument may be invoked to try to mop up, and it will be + logged in any case. +</ul> + +Most phases are terminated by the first module that handles them; +however, for logging, `fixups', and non-access authentication +checking, all handlers always run (barring an error). Also, the +response phase is unique in that modules may declare multiple handlers +for it, via a dispatch table keyed on the MIME type of the requested +object. Modules may declare a response-phase handler which can handle +<em>any</em> request, by giving it the key <code>*/*</code> (i.e., a +wildcard MIME type specification). However, wildcard handlers are +only invoked if the server has already tried and failed to find a more +specific response handler for the MIME type of the requested object +(either none existed, or they all declined).<p> + +The handlers themselves are functions of one argument (a +<code>request_rec</code> structure. vide infra), which returns an +integer, as above.<p> + +<h3><a name="moduletour">A brief tour of a module</a></h3> + +At this point, we need to explain the structure of a module. Our +candidate will be one of the messier ones, the CGI module --- this +handles both CGI scripts and the <code>ScriptAlias</code> config file +command. It's actually a great deal more complicated than most +modules, but if we're going to have only one example, it might as well +be the one with its fingers in every place.<p> + +Let's begin with handlers. In order to handle the CGI scripts, the +module declares a response handler for them. Because of +<code>ScriptAlias</code>, it also has handlers for the name +translation phase (to recognize <code>ScriptAlias</code>ed URIs), the +type-checking phase (any <code>ScriptAlias</code>ed request is typed +as a CGI script).<p> + +The module needs to maintain some per (virtual) +server information, namely, the <code>ScriptAlias</code>es in effect; +the module structure therefore contains pointers to a functions which +builds these structures, and to another which combines two of them (in +case the main server and a virtual server both have +<code>ScriptAlias</code>es declared).<p> + +Finally, this module contains code to handle the +<code>ScriptAlias</code> command itself. This particular module only +declares one command, but there could be more, so modules have +<em>command tables</em> which declare their commands, and describe +where they are permitted, and how they are to be invoked. <p> + +A final note on the declared types of the arguments of some of these +commands: a <code>pool</code> is a pointer to a <em>resource pool</em> +structure; these are used by the server to keep track of the memory +which has been allocated, files opened, etc., either to service a +particular request, or to handle the process of configuring itself. +That way, when the request is over (or, for the configuration pool, +when the server is restarting), the memory can be freed, and the files +closed, <i>en masse</i>, without anyone having to write explicit code to +track them all down and dispose of them. Also, a +<code>cmd_parms</code> structure contains various information about +the config file being read, and other status information, which is +sometimes of use to the function which processes a config-file command +(such as <code>ScriptAlias</code>). + +With no further ado, the module itself: + +<pre> +/* Declarations of handlers. */ + +int translate_scriptalias (request_rec *); +int type_scriptalias (request_rec *); +int cgi_handler (request_rec *); + +/* Subsidiary dispatch table for response-phase handlers, by MIME type */ + +handler_rec cgi_handlers[] = { +{ "application/x-httpd-cgi", cgi_handler }, +{ NULL } +}; + +/* Declarations of routines to manipulate the module's configuration + * info. Note that these are returned, and passed in, as void *'s; + * the server core keeps track of them, but it doesn't, and can't, + * know their internal structure. + */ + +void *make_cgi_server_config (pool *); +void *merge_cgi_server_config (pool *, void *, void *); + +/* Declarations of routines to handle config-file commands */ + +extern char *script_alias(cmd_parms *, void *per_dir_config, char *fake, + char *real); + +command_rec cgi_cmds[] = { +{ "ScriptAlias", script_alias, NULL, RSRC_CONF, TAKE2, + "a fakename and a realname"}, +{ NULL } +}; + +module cgi_module = { + STANDARD_MODULE_STUFF, + NULL, /* initializer */ + NULL, /* dir config creator */ + NULL, /* dir merger --- default is to override */ + make_cgi_server_config, /* server config */ + merge_cgi_server_config, /* merge server config */ + cgi_cmds, /* command table */ + cgi_handlers, /* handlers */ + translate_scriptalias, /* filename translation */ + NULL, /* check_user_id */ + NULL, /* check auth */ + NULL, /* check access */ + type_scriptalias, /* type_checker */ + NULL, /* fixups */ + NULL, /* logger */ + NULL /* header parser */ +}; +</pre> + +<h2><a name="handlers">How handlers work</a></h2> + +The sole argument to handlers is a <code>request_rec</code> structure. +This structure describes a particular request which has been made to +the server, on behalf of a client. In most cases, each connection to +the client generates only one <code>request_rec</code> structure.<p> + +<h3><a name="req_tour">A brief tour of the <code>request_rec</code></a></h3> + +The <code>request_rec</code> contains pointers to a resource pool +which will be cleared when the server is finished handling the +request; to structures containing per-server and per-connection +information, and most importantly, information on the request itself.<p> + +The most important such information is a small set of character +strings describing attributes of the object being requested, including +its URI, filename, content-type and content-encoding (these being filled +in by the translation and type-check handlers which handle the +request, respectively). <p> + +Other commonly used data items are tables giving the MIME headers on +the client's original request, MIME headers to be sent back with the +response (which modules can add to at will), and environment variables +for any subprocesses which are spawned off in the course of servicing +the request. These tables are manipulated using the +<code>table_get</code> and <code>table_set</code> routines. <p> +<BLOCKQUOTE> + Note that the <SAMP>Content-type</SAMP> header value <EM>cannot</EM> be + set by module content-handlers using the <SAMP>table_*()</SAMP> + routines. Rather, it is set by pointing the <SAMP>content_type</SAMP> + field in the <SAMP>request_rec</SAMP> structure to an appropriate + string. <EM>E.g.</EM>, + <PRE> + r->content_type = "text/html"; + </PRE> +</BLOCKQUOTE> +Finally, there are pointers to two data structures which, in turn, +point to per-module configuration structures. Specifically, these +hold pointers to the data structures which the module has built to +describe the way it has been configured to operate in a given +directory (via <code>.htaccess</code> files or +<code><Directory></code> sections), for private data it has +built in the course of servicing the request (so modules' handlers for +one phase can pass `notes' to their handlers for other phases). There +is another such configuration vector in the <code>server_rec</code> +data structure pointed to by the <code>request_rec</code>, which +contains per (virtual) server configuration data.<p> + +Here is an abridged declaration, giving the fields most commonly used:<p> + +<pre> +struct request_rec { + + pool *pool; + conn_rec *connection; + server_rec *server; + + /* What object is being requested */ + + char *uri; + char *filename; + char *path_info; + char *args; /* QUERY_ARGS, if any */ + struct stat finfo; /* Set by server core; + * st_mode set to zero if no such file */ + + char *content_type; + char *content_encoding; + + /* MIME header environments, in and out. Also, an array containing + * environment variables to be passed to subprocesses, so people can + * write modules to add to that environment. + * + * The difference between headers_out and err_headers_out is that + * the latter are printed even on error, and persist across internal + * redirects (so the headers printed for ErrorDocument handlers will + * have them). + */ + + table *headers_in; + table *headers_out; + table *err_headers_out; + table *subprocess_env; + + /* Info about the request itself... */ + + int header_only; /* HEAD request, as opposed to GET */ + char *protocol; /* Protocol, as given to us, or HTTP/0.9 */ + char *method; /* GET, HEAD, POST, etc. */ + int method_number; /* M_GET, M_POST, etc. */ + + /* Info for logging */ + + char *the_request; + int bytes_sent; + + /* A flag which modules can set, to indicate that the data being + * returned is volatile, and clients should be told not to cache it. + */ + + int no_cache; + + /* Various other config info which may change with .htaccess files + * These are config vectors, with one void* pointer for each module + * (the thing pointed to being the module's business). + */ + + void *per_dir_config; /* Options set in config files, etc. */ + void *request_config; /* Notes on *this* request */ + +}; + +</pre> + +<h3><a name="req_orig">Where request_rec structures come from</a></h3> + +Most <code>request_rec</code> structures are built by reading an HTTP +request from a client, and filling in the fields. However, there are +a few exceptions: + +<ul> + <li> If the request is to an imagemap, a type map (i.e., a + <code>*.var</code> file), or a CGI script which returned a + local `Location:', then the resource which the user requested + is going to be ultimately located by some URI other than what + the client originally supplied. In this case, the server does + an <em>internal redirect</em>, constructing a new + <code>request_rec</code> for the new URI, and processing it + almost exactly as if the client had requested the new URI + directly. <p> + + <li> If some handler signaled an error, and an + <code>ErrorDocument</code> is in scope, the same internal + redirect machinery comes into play.<p> + + <li> Finally, a handler occasionally needs to investigate `what + would happen if' some other request were run. For instance, + the directory indexing module needs to know what MIME type + would be assigned to a request for each directory entry, in + order to figure out what icon to use.<p> + + Such handlers can construct a <em>sub-request</em>, using the + functions <code>sub_req_lookup_file</code> and + <code>sub_req_lookup_uri</code>; this constructs a new + <code>request_rec</code> structure and processes it as you + would expect, up to but not including the point of actually + sending a response. (These functions skip over the access + checks if the sub-request is for a file in the same directory + as the original request).<p> + + (Server-side includes work by building sub-requests and then + actually invoking the response handler for them, via the + function <code>run_sub_request</code>). +</ul> + +<h3><a name="req_return">Handling requests, declining, and returning error codes</a></h3> + +As discussed above, each handler, when invoked to handle a particular +<code>request_rec</code>, has to return an <code>int</code> to +indicate what happened. That can either be + +<ul> + <li> OK --- the request was handled successfully. This may or may + not terminate the phase. + <li> DECLINED --- no erroneous condition exists, but the module + declines to handle the phase; the server tries to find another. + <li> an HTTP error code, which aborts handling of the request. +</ul> + +Note that if the error code returned is <code>REDIRECT</code>, then +the module should put a <code>Location</code> in the request's +<code>headers_out</code>, to indicate where the client should be +redirected <em>to</em>. <p> + +<h3><a name="resp_handlers">Special considerations for response handlers</a></h3> + +Handlers for most phases do their work by simply setting a few fields +in the <code>request_rec</code> structure (or, in the case of access +checkers, simply by returning the correct error code). However, +response handlers have to actually send a request back to the client. <p> + +They should begin by sending an HTTP response header, using the +function <code>send_http_header</code>. (You don't have to do +anything special to skip sending the header for HTTP/0.9 requests; the +function figures out on its own that it shouldn't do anything). If +the request is marked <code>header_only</code>, that's all they should +do; they should return after that, without attempting any further +output. <p> + +Otherwise, they should produce a request body which responds to the +client as appropriate. The primitives for this are <code>rputc</code> +and <code>rprintf</code>, for internally generated output, and +<code>send_fd</code>, to copy the contents of some <code>FILE *</code> +straight to the client. <p> + +At this point, you should more or less understand the following piece +of code, which is the handler which handles <code>GET</code> requests +which have no more specific handler; it also shows how conditional +<code>GET</code>s can be handled, if it's desirable to do so in a +particular response handler --- <code>set_last_modified</code> checks +against the <code>If-modified-since</code> value supplied by the +client, if any, and returns an appropriate code (which will, if +nonzero, be USE_LOCAL_COPY). No similar considerations apply for +<code>set_content_length</code>, but it returns an error code for +symmetry.<p> + +<pre> +int default_handler (request_rec *r) +{ + int errstatus; + FILE *f; + + if (r->method_number != M_GET) return DECLINED; + if (r->finfo.st_mode == 0) return NOT_FOUND; + + if ((errstatus = set_content_length (r, r->finfo.st_size)) + || (errstatus = set_last_modified (r, r->finfo.st_mtime))) + return errstatus; + + f = fopen (r->filename, "r"); + + if (f == NULL) { + log_reason("file permissions deny server access", + r->filename, r); + return FORBIDDEN; + } + + register_timeout ("send", r); + send_http_header (r); + + if (!r->header_only) send_fd (f, r); + pfclose (r->pool, f); + return OK; +} +</pre> + +Finally, if all of this is too much of a challenge, there are a few +ways out of it. First off, as shown above, a response handler which +has not yet produced any output can simply return an error code, in +which case the server will automatically produce an error response. +Secondly, it can punt to some other handler by invoking +<code>internal_redirect</code>, which is how the internal redirection +machinery discussed above is invoked. A response handler which has +internally redirected should always return <code>OK</code>. <p> + +(Invoking <code>internal_redirect</code> from handlers which are +<em>not</em> response handlers will lead to serious confusion). + +<h3><a name="auth_handlers">Special considerations for authentication handlers</a></h3> + +Stuff that should be discussed here in detail: + +<ul> + <li> Authentication-phase handlers not invoked unless auth is + configured for the directory. + <li> Common auth configuration stored in the core per-dir + configuration; it has accessors <code>auth_type</code>, + <code>auth_name</code>, and <code>requires</code>. + <li> Common routines, to handle the protocol end of things, at least + for HTTP basic authentication (<code>get_basic_auth_pw</code>, + which sets the <code>connection->user</code> structure field + automatically, and <code>note_basic_auth_failure</code>, which + arranges for the proper <code>WWW-Authenticate:</code> header + to be sent back). +</ul> + +<h3><a name="log_handlers">Special considerations for logging handlers</a></h3> + +When a request has internally redirected, there is the question of +what to log. Apache handles this by bundling the entire chain of +redirects into a list of <code>request_rec</code> structures which are +threaded through the <code>r->prev</code> and <code>r->next</code> +pointers. The <code>request_rec</code> which is passed to the logging +handlers in such cases is the one which was originally built for the +initial request from the client; note that the bytes_sent field will +only be correct in the last request in the chain (the one for which a +response was actually sent). + +<h2><a name="pools">Resource allocation and resource pools</a></h2> + +One of the problems of writing and designing a server-pool server is +that of preventing leakage, that is, allocating resources (memory, +open files, etc.), without subsequently releasing them. The resource +pool machinery is designed to make it easy to prevent this from +happening, by allowing resource to be allocated in such a way that +they are <em>automatically</em> released when the server is done with +them. <p> + +The way this works is as follows: the memory which is allocated, file +opened, etc., to deal with a particular request are tied to a +<em>resource pool</em> which is allocated for the request. The pool +is a data structure which itself tracks the resources in question. <p> + +When the request has been processed, the pool is <em>cleared</em>. At +that point, all the memory associated with it is released for reuse, +all files associated with it are closed, and any other clean-up +functions which are associated with the pool are run. When this is +over, we can be confident that all the resource tied to the pool have +been released, and that none of them have leaked. <p> + +Server restarts, and allocation of memory and resources for per-server +configuration, are handled in a similar way. There is a +<em>configuration pool</em>, which keeps track of resources which were +allocated while reading the server configuration files, and handling +the commands therein (for instance, the memory that was allocated for +per-server module configuration, log files and other files that were +opened, and so forth). When the server restarts, and has to reread +the configuration files, the configuration pool is cleared, and so the +memory and file descriptors which were taken up by reading them the +last time are made available for reuse. <p> + +It should be noted that use of the pool machinery isn't generally +obligatory, except for situations like logging handlers, where you +really need to register cleanups to make sure that the log file gets +closed when the server restarts (this is most easily done by using the +function <code><a href="#pool-files">pfopen</a></code>, which also +arranges for the underlying file descriptor to be closed before any +child processes, such as for CGI scripts, are <code>exec</code>ed), or +in case you are using the timeout machinery (which isn't yet even +documented here). However, there are two benefits to using it: +resources allocated to a pool never leak (even if you allocate a +scratch string, and just forget about it); also, for memory +allocation, <code>palloc</code> is generally faster than +<code>malloc</code>.<p> + +We begin here by describing how memory is allocated to pools, and then +discuss how other resources are tracked by the resource pool +machinery. + +<h3>Allocation of memory in pools</h3> + +Memory is allocated to pools by calling the function +<code>palloc</code>, which takes two arguments, one being a pointer to +a resource pool structure, and the other being the amount of memory to +allocate (in <code>char</code>s). Within handlers for handling +requests, the most common way of getting a resource pool structure is +by looking at the <code>pool</code> slot of the relevant +<code>request_rec</code>; hence the repeated appearance of the +following idiom in module code: + +<pre> +int my_handler(request_rec *r) +{ + struct my_structure *foo; + ... + + foo = (foo *)palloc (r->pool, sizeof(my_structure)); +} +</pre> + +Note that <em>there is no <code>pfree</code></em> --- +<code>palloc</code>ed memory is freed only when the associated +resource pool is cleared. This means that <code>palloc</code> does not +have to do as much accounting as <code>malloc()</code>; all it does in +the typical case is to round up the size, bump a pointer, and do a +range check.<p> + +(It also raises the possibility that heavy use of <code>palloc</code> +could cause a server process to grow excessively large. There are +two ways to deal with this, which are dealt with below; briefly, you +can use <code>malloc</code>, and try to be sure that all of the memory +gets explicitly <code>free</code>d, or you can allocate a sub-pool of +the main pool, allocate your memory in the sub-pool, and clear it out +periodically. The latter technique is discussed in the section on +sub-pools below, and is used in the directory-indexing code, in order +to avoid excessive storage allocation when listing directories with +thousands of files). + +<h3>Allocating initialized memory</h3> + +There are functions which allocate initialized memory, and are +frequently useful. The function <code>pcalloc</code> has the same +interface as <code>palloc</code>, but clears out the memory it +allocates before it returns it. The function <code>pstrdup</code> +takes a resource pool and a <code>char *</code> as arguments, and +allocates memory for a copy of the string the pointer points to, +returning a pointer to the copy. Finally <code>pstrcat</code> is a +varargs-style function, which takes a pointer to a resource pool, and +at least two <code>char *</code> arguments, the last of which must be +<code>NULL</code>. It allocates enough memory to fit copies of each +of the strings, as a unit; for instance: + +<pre> + pstrcat (r->pool, "foo", "/", "bar", NULL); +</pre> + +returns a pointer to 8 bytes worth of memory, initialized to +<code>"foo/bar"</code>. + +<h3><a name="pool-files">Tracking open files, etc.</a></h3> + +As indicated above, resource pools are also used to track other sorts +of resources besides memory. The most common are open files. The +routine which is typically used for this is <code>pfopen</code>, which +takes a resource pool and two strings as arguments; the strings are +the same as the typical arguments to <code>fopen</code>, e.g., + +<pre> + ... + FILE *f = pfopen (r->pool, r->filename, "r"); + + if (f == NULL) { ... } else { ... } +</pre> + +There is also a <code>popenf</code> routine, which parallels the +lower-level <code>open</code> system call. Both of these routines +arrange for the file to be closed when the resource pool in question +is cleared. <p> + +Unlike the case for memory, there <em>are</em> functions to close +files allocated with <code>pfopen</code>, and <code>popenf</code>, +namely <code>pfclose</code> and <code>pclosef</code>. (This is +because, on many systems, the number of files which a single process +can have open is quite limited). It is important to use these +functions to close files allocated with <code>pfopen</code> and +<code>popenf</code>, since to do otherwise could cause fatal errors on +systems such as Linux, which react badly if the same +<code>FILE*</code> is closed more than once. <p> + +(Using the <code>close</code> functions is not mandatory, since the +file will eventually be closed regardless, but you should consider it +in cases where your module is opening, or could open, a lot of files). + +<h3>Other sorts of resources --- cleanup functions</h3> + +More text goes here. Describe the the cleanup primitives in terms of +which the file stuff is implemented; also, <code>spawn_process</code>. + +<h3>Fine control --- creating and dealing with sub-pools, with a note +on sub-requests</h3> + +On rare occasions, too-free use of <code>palloc()</code> and the +associated primitives may result in undesirably profligate resource +allocation. You can deal with such a case by creating a +<em>sub-pool</em>, allocating within the sub-pool rather than the main +pool, and clearing or destroying the sub-pool, which releases the +resources which were associated with it. (This really <em>is</em> a +rare situation; the only case in which it comes up in the standard +module set is in case of listing directories, and then only with +<em>very</em> large directories. Unnecessary use of the primitives +discussed here can hair up your code quite a bit, with very little +gain). <p> + +The primitive for creating a sub-pool is <code>make_sub_pool</code>, +which takes another pool (the parent pool) as an argument. When the +main pool is cleared, the sub-pool will be destroyed. The sub-pool +may also be cleared or destroyed at any time, by calling the functions +<code>clear_pool</code> and <code>destroy_pool</code>, respectively. +(The difference is that <code>clear_pool</code> frees resources +associated with the pool, while <code>destroy_pool</code> also +deallocates the pool itself. In the former case, you can allocate new +resources within the pool, and clear it again, and so forth; in the +latter case, it is simply gone). <p> + +One final note --- sub-requests have their own resource pools, which +are sub-pools of the resource pool for the main request. The polite +way to reclaim the resources associated with a sub request which you +have allocated (using the <code>sub_req_lookup_...</code> functions) +is <code>destroy_sub_request</code>, which frees the resource pool. +Before calling this function, be sure to copy anything that you care +about which might be allocated in the sub-request's resource pool into +someplace a little less volatile (for instance, the filename in its +<code>request_rec</code> structure). <p> + +(Again, under most circumstances, you shouldn't feel obliged to call +this function; only 2K of memory or so are allocated for a typical sub +request, and it will be freed anyway when the main request pool is +cleared. It is only when you are allocating many, many sub-requests +for a single main request that you should seriously consider the +<code>destroy...</code> functions). + +<h2><a name="config">Configuration, commands and the like</a></h2> + +One of the design goals for this server was to maintain external +compatibility with the NCSA 1.3 server --- that is, to read the same +configuration files, to process all the directives therein correctly, +and in general to be a drop-in replacement for NCSA. On the other +hand, another design goal was to move as much of the server's +functionality into modules which have as little as possible to do with +the monolithic server core. The only way to reconcile these goals is +to move the handling of most commands from the central server into the +modules. <p> + +However, just giving the modules command tables is not enough to +divorce them completely from the server core. The server has to +remember the commands in order to act on them later. That involves +maintaining data which is private to the modules, and which can be +either per-server, or per-directory. Most things are per-directory, +including in particular access control and authorization information, +but also information on how to determine file types from suffixes, +which can be modified by <code>AddType</code> and +<code>DefaultType</code> directives, and so forth. In general, the +governing philosophy is that anything which <em>can</em> be made +configurable by directory should be; per-server information is +generally used in the standard set of modules for information like +<code>Alias</code>es and <code>Redirect</code>s which come into play +before the request is tied to a particular place in the underlying +file system. <p> + +Another requirement for emulating the NCSA server is being able to +handle the per-directory configuration files, generally called +<code>.htaccess</code> files, though even in the NCSA server they can +contain directives which have nothing at all to do with access +control. Accordingly, after URI -> filename translation, but before +performing any other phase, the server walks down the directory +hierarchy of the underlying filesystem, following the translated +pathname, to read any <code>.htaccess</code> files which might be +present. The information which is read in then has to be +<em>merged</em> with the applicable information from the server's own +config files (either from the <code><Directory></code> sections +in <code>access.conf</code>, or from defaults in +<code>srm.conf</code>, which actually behaves for most purposes almost +exactly like <code><Directory /></code>).<p> + +Finally, after having served a request which involved reading +<code>.htaccess</code> files, we need to discard the storage allocated +for handling them. That is solved the same way it is solved wherever +else similar problems come up, by tying those structures to the +per-transaction resource pool. <p> + +<h3><a name="per-dir">Per-directory configuration structures</a></h3> + +Let's look out how all of this plays out in <code>mod_mime.c</code>, +which defines the file typing handler which emulates the NCSA server's +behavior of determining file types from suffixes. What we'll be +looking at, here, is the code which implements the +<code>AddType</code> and <code>AddEncoding</code> commands. These +commands can appear in <code>.htaccess</code> files, so they must be +handled in the module's private per-directory data, which in fact, +consists of two separate <code>table</code>s for MIME types and +encoding information, and is declared as follows: + +<pre> +typedef struct { + table *forced_types; /* Additional AddTyped stuff */ + table *encoding_types; /* Added with AddEncoding... */ +} mime_dir_config; +</pre> + +When the server is reading a configuration file, or +<code><Directory></code> section, which includes one of the MIME +module's commands, it needs to create a <code>mime_dir_config</code> +structure, so those commands have something to act on. It does this +by invoking the function it finds in the module's `create per-dir +config slot', with two arguments: the name of the directory to which +this configuration information applies (or <code>NULL</code> for +<code>srm.conf</code>), and a pointer to a resource pool in which the +allocation should happen. <p> + +(If we are reading a <code>.htaccess</code> file, that resource pool +is the per-request resource pool for the request; otherwise it is a +resource pool which is used for configuration data, and cleared on +restarts. Either way, it is important for the structure being created +to vanish when the pool is cleared, by registering a cleanup on the +pool if necessary). <p> + +For the MIME module, the per-dir config creation function just +<code>palloc</code>s the structure above, and a creates a couple of +<code>table</code>s to fill it. That looks like this: + +<pre> +void *create_mime_dir_config (pool *p, char *dummy) +{ + mime_dir_config *new = + (mime_dir_config *) palloc (p, sizeof(mime_dir_config)); + + new->forced_types = make_table (p, 4); + new->encoding_types = make_table (p, 4); + + return new; +} +</pre> + +Now, suppose we've just read in a <code>.htaccess</code> file. We +already have the per-directory configuration structure for the next +directory up in the hierarchy. If the <code>.htaccess</code> file we +just read in didn't have any <code>AddType</code> or +<code>AddEncoding</code> commands, its per-directory config structure +for the MIME module is still valid, and we can just use it. +Otherwise, we need to merge the two structures somehow. <p> + +To do that, the server invokes the module's per-directory config merge +function, if one is present. That function takes three arguments: +the two structures being merged, and a resource pool in which to +allocate the result. For the MIME module, all that needs to be done +is overlay the tables from the new per-directory config structure with +those from the parent: + +<pre> +void *merge_mime_dir_configs (pool *p, void *parent_dirv, void *subdirv) +{ + mime_dir_config *parent_dir = (mime_dir_config *)parent_dirv; + mime_dir_config *subdir = (mime_dir_config *)subdirv; + mime_dir_config *new = + (mime_dir_config *)palloc (p, sizeof(mime_dir_config)); + + new->forced_types = overlay_tables (p, subdir->forced_types, + parent_dir->forced_types); + new->encoding_types = overlay_tables (p, subdir->encoding_types, + parent_dir->encoding_types); + + return new; +} +</pre> + +As a note --- if there is no per-directory merge function present, the +server will just use the subdirectory's configuration info, and ignore +the parent's. For some modules, that works just fine (e.g., for the +includes module, whose per-directory configuration information +consists solely of the state of the <code>XBITHACK</code>), and for +those modules, you can just not declare one, and leave the +corresponding structure slot in the module itself <code>NULL</code>.<p> + +<h3><a name="commands">Command handling</a></h3> + +Now that we have these structures, we need to be able to figure out +how to fill them. That involves processing the actual +<code>AddType</code> and <code>AddEncoding</code> commands. To find +commands, the server looks in the module's <code>command table</code>. +That table contains information on how many arguments the commands +take, and in what formats, where it is permitted, and so forth. That +information is sufficient to allow the server to invoke most +command-handling functions with pre-parsed arguments. Without further +ado, let's look at the <code>AddType</code> command handler, which +looks like this (the <code>AddEncoding</code> command looks basically +the same, and won't be shown here): + +<pre> +char *add_type(cmd_parms *cmd, mime_dir_config *m, char *ct, char *ext) +{ + if (*ext == '.') ++ext; + table_set (m->forced_types, ext, ct); + return NULL; +} +</pre> + +This command handler is unusually simple. As you can see, it takes +four arguments, two of which are pre-parsed arguments, the third being +the per-directory configuration structure for the module in question, +and the fourth being a pointer to a <code>cmd_parms</code> structure. +That structure contains a bunch of arguments which are frequently of +use to some, but not all, commands, including a resource pool (from +which memory can be allocated, and to which cleanups should be tied), +and the (virtual) server being configured, from which the module's +per-server configuration data can be obtained if required.<p> + +Another way in which this particular command handler is unusually +simple is that there are no error conditions which it can encounter. +If there were, it could return an error message instead of +<code>NULL</code>; this causes an error to be printed out on the +server's <code>stderr</code>, followed by a quick exit, if it is in +the main config files; for a <code>.htaccess</code> file, the syntax +error is logged in the server error log (along with an indication of +where it came from), and the request is bounced with a server error +response (HTTP error status, code 500). <p> + +The MIME module's command table has entries for these commands, which +look like this: + +<pre> +command_rec mime_cmds[] = { +{ "AddType", add_type, NULL, OR_FILEINFO, TAKE2, + "a mime type followed by a file extension" }, +{ "AddEncoding", add_encoding, NULL, OR_FILEINFO, TAKE2, + "an encoding (e.g., gzip), followed by a file extension" }, +{ NULL } +}; +</pre> + +The entries in these tables are: + +<ul> + <li> The name of the command + <li> The function which handles it + <li> a <code>(void *)</code> pointer, which is passed in the + <code>cmd_parms</code> structure to the command handler --- + this is useful in case many similar commands are handled by the + same function. + <li> A bit mask indicating where the command may appear. There are + mask bits corresponding to each <code>AllowOverride</code> + option, and an additional mask bit, <code>RSRC_CONF</code>, + indicating that the command may appear in the server's own + config files, but <em>not</em> in any <code>.htaccess</code> + file. + <li> A flag indicating how many arguments the command handler wants + pre-parsed, and how they should be passed in. + <code>TAKE2</code> indicates two pre-parsed arguments. Other + options are <code>TAKE1</code>, which indicates one pre-parsed + argument, <code>FLAG</code>, which indicates that the argument + should be <code>On</code> or <code>Off</code>, and is passed in + as a boolean flag, <code>RAW_ARGS</code>, which causes the + server to give the command the raw, unparsed arguments + (everything but the command name itself). There is also + <code>ITERATE</code>, which means that the handler looks the + same as <code>TAKE1</code>, but that if multiple arguments are + present, it should be called multiple times, and finally + <code>ITERATE2</code>, which indicates that the command handler + looks like a <code>TAKE2</code>, but if more arguments are + present, then it should be called multiple times, holding the + first argument constant. + <li> Finally, we have a string which describes the arguments that + should be present. If the arguments in the actual config file + are not as required, this string will be used to help give a + more specific error message. (You can safely leave this + <code>NULL</code>). +</ul> + +Finally, having set this all up, we have to use it. This is +ultimately done in the module's handlers, specifically for its +file-typing handler, which looks more or less like this; note that the +per-directory configuration structure is extracted from the +<code>request_rec</code>'s per-directory configuration vector by using +the <code>get_module_config</code> function. + +<pre> +int find_ct(request_rec *r) +{ + int i; + char *fn = pstrdup (r->pool, r->filename); + mime_dir_config *conf = (mime_dir_config *) + get_module_config(r->per_dir_config, &mime_module); + char *type; + + if (S_ISDIR(r->finfo.st_mode)) { + r->content_type = DIR_MAGIC_TYPE; + return OK; + } + + if((i=rind(fn,'.')) < 0) return DECLINED; + ++i; + + if ((type = table_get (conf->encoding_types, &fn[i]))) + { + r->content_encoding = type; + + /* go back to previous extension to try to use it as a type */ + + fn[i-1] = '\0'; + if((i=rind(fn,'.')) < 0) return OK; + ++i; + } + + if ((type = table_get (conf->forced_types, &fn[i]))) + { + r->content_type = type; + } + + return OK; +} + +</pre> + +<h3><a name="servconf">Side notes --- per-server configuration, virtual servers, etc.</a></h3> + +The basic ideas behind per-server module configuration are basically +the same as those for per-directory configuration; there is a creation +function and a merge function, the latter being invoked where a +virtual server has partially overridden the base server configuration, +and a combined structure must be computed. (As with per-directory +configuration, the default if no merge function is specified, and a +module is configured in some virtual server, is that the base +configuration is simply ignored). <p> + +The only substantial difference is that when a command needs to +configure the per-server private module data, it needs to go to the +<code>cmd_parms</code> data to get at it. Here's an example, from the +alias module, which also indicates how a syntax error can be returned +(note that the per-directory configuration argument to the command +handler is declared as a dummy, since the module doesn't actually have +per-directory config data): + +<pre> +char *add_redirect(cmd_parms *cmd, void *dummy, char *f, char *url) +{ + server_rec *s = cmd->server; + alias_server_conf *conf = (alias_server_conf *) + get_module_config(s->module_config,&alias_module); + alias_entry *new = push_array (conf->redirects); + + if (!is_url (url)) return "Redirect to non-URL"; + + new->fake = f; new->real = url; + return NULL; +} +</pre> +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</body></html> diff --git a/usr.sbin/httpd/htdocs/manual/misc/FAQ.html b/usr.sbin/httpd/htdocs/manual/misc/FAQ.html new file mode 100644 index 00000000000..ec8c8a1b07b --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/misc/FAQ.html @@ -0,0 +1,2287 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> + <HEAD> + <TITLE>Apache Server Frequently Asked Questions</TITLE> + </HEAD> + + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + <BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" + > + <DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + + <H1 ALIGN="CENTER">Apache Server Frequently Asked Questions</H1> + <P> + $Revision: 1.1 $ ($Date: 1998/03/25 07:08:35 $) + </P> + <P> + The latest version of this FAQ is always available from the main + Apache web site, at + <<A + HREF="http://www.apache.org/docs/misc/FAQ.html" + REL="Help" + ><SAMP>http://www.apache.org/docs/misc/FAQ.html</SAMP></A>>. + </P> +<!-- Notes about changes: --> +<!-- - If adding a relative link to another part of the --> +<!-- documentation, *do* include the ".html" portion. There's a --> +<!-- good chance that the user will be reading the documentation --> +<!-- on his own system, which may not be configured for --> +<!-- multiviews. --> +<!-- - When adding items, make sure they're put in the right place --> +<!-- - verify that the numbering matches up. --> +<!-- - *Don't* use <PRE></PRE> blocks - they don't appear --> +<!-- correctly in a reliable way when this is converted to text --> +<!-- with Lynx. Use <DL><DD><CODE>xxx<BR>xx</CODE></DD></DL> --> +<!-- blocks inside a <P></P> instead. This is necessary to get --> +<!-- the horizontal and vertical indenting right. --> +<!-- - Don't forget to include an HR tag after the last /P tag --> +<!-- but before the /LI in an item. --> + <P> + If you are reading a text-only version of this FAQ, you may find numbers + enclosed in brackets (such as "[12]"). These refer to the list of + reference URLs to be found at the end of the document. These references + do not appear, and are not needed, for the hypertext version. + </P> + <H2>The Questions</H2> +<!-- Stuff to Add: --> +<!-- - can't bind to port 80 --> +<!-- - permission denied --> +<!-- - address already in use --> +<!-- - mod_auth & passwd lines "user:pw:.*" - ++1st colon onward is --> +<!-- treated as pw, not just ++1st to --2nd. --> +<!-- - SSL: --> +<!-- - Can I use Apache-SSL for free in Canada? --> +<!-- - Why can't I use Apache-SSL in the U.S.? --> +<!-- - How can I found out how many visitors my site gets? --> +<!-- - How do I add a counter? --> +<!-- - How do I configure Apache as a proxy? --> +<!-- - What browsers support HTTP/1.1? --> +<!-- - What's the point of vhosts-by-name is there aren't any --> +<!-- HTTP/1.1 browsers? --> +<!-- - Is there an Apache for W95/WNT? --> +<!-- - Why does Apache die when a vhost can't be DNS-resolved? --> +<!-- - Why do I get "send lost connection" messages in my error --> +<!-- log? --> +<!-- - specifically consider .pdf files which seem to cause this --> +<!-- a lot when accessed via the plugin ... and also mention --> +<!-- how range-requests can cause bytes served < file size --> +<!-- - Why do directory indexes appear as garbage? (A: -lucb) --> +<!-- - How do I add a footer to all pages offered by my server? --> +<!-- - Fix midi question; a bigger problem than midi vs. x-midi is --> +<!-- the simple fact that older versions of Apache (and new ones --> +<!-- that have been upgraded without upgrading the mime.types --> +<!-- file) don't have the type listed at all. --> +<!-- - Why is my .htaccess ignored? --> +<!-- - RewriteRule /~fraggle/* /cgi-bin/fraggle.pl does not work --> +<UL> + <LI><STRONG>Background</STRONG> + <OL START=1> + <LI><A HREF="#what">What is Apache?</A> + </LI> + <LI><A HREF="#why">Why was Apache created?</A> + </LI> + <LI><A HREF="#relate">How does The Apache Group's work relate to + other servers?</A> + </LI> + <LI><A HREF="#name">Why the name "Apache"?</A> + </LI> + <LI><A HREF="#compare">OK, so how does Apache compare to other servers?</A> + </LI> + <LI><A HREF="#tested">How thoroughly tested is Apache?</A> + </LI> + <LI><A HREF="#future">What are the future plans for Apache?</A> + </LI> + <LI><A HREF="#support">Whom do I contact for support?</A> + </LI> + <LI><A HREF="#more">Is there any more information on Apache?</A> + </LI> + <LI><A HREF="#where">Where can I get Apache?</A> + </LI> + </OL> + </LI> + <LI><STRONG>Technical Questions</STRONG> + <OL START=11> + <LI><A HREF="#what2do">"Why can't I ...? Why won't ... + work?" What to do in case of problems</A> + </LI> + <LI><A HREF="#compatible">How compatible is Apache with my existing + NCSA 1.3 setup?</A> + </LI> + <LI><A HREF="#CGIoutsideScriptAlias">How do I enable CGI execution + in directories other than the ScriptAlias?</A> + </LI> + <LI><A HREF="#premature-script-headers">What does it mean when my + CGIs fail with "<SAMP>Premature end of script + headers</SAMP>"?</A> + </LI> + <LI><A HREF="#ssi-part-i">How do I enable SSI (parsed HTML)?</A> + </LI> + <LI><A HREF="#ssi-part-ii">Why don't my parsed files get cached?</A> + </LI> + <LI><A HREF="#ssi-part-iii">How can I have my script output parsed?</A> + </LI> + <LI><A HREF="#proxy">Does or will Apache act as a Proxy server?</A> + </LI> + <LI><A HREF="#multiviews">What are "multiviews"?</A> + </LI> + <LI><A HREF="#fdlim">Why can't I run more than <<EM>n</EM>> + virtual hosts?</A> + </LI> + <LI><A HREF="#freebsd-setsize">Can I increase FD_SETSIZE on FreeBSD?</A> + </LI> + <LI><A HREF="#limitGET">Why do I keep getting "access denied" for + form POST requests?</A> + </LI> + <LI><A HREF="#passwdauth">Can I use my <SAMP>/etc/passwd</SAMP> file + for Web page authentication?</A> + </LI> + <LI><A HREF="#errordoc401">Why doesn't my <CODE>ErrorDocument + 401</CODE> work?</A> + </LI> + <LI><A HREF="#errordocssi">How can I use <CODE>ErrorDocument</CODE> + and SSI to simplify customized error messages?</A> + </LI> + <LI><A HREF="#setgid">Why do I get "<SAMP>setgid: Invalid + argument</SAMP>" at startup?</A> + </LI> + <LI><A HREF="#cookies1">Why does Apache send a cookie on every response?</A> + </LI> + <LI><A HREF="#cookies2">Why don't my cookies work, I even compiled in + <SAMP>mod_cookies</SAMP>?</A> + </LI> + <LI><A HREF="#jdk1-and-http1.1">Why do my Java app[let]s give me plain text + when I request an URL from an Apache server?</A> + </LI> + <LI><A HREF="#putsupport">Why can't I publish to my Apache server + using PUT on Netscape Gold and other programs?</A> + </LI> + <LI><A HREF="#fastcgi">Why isn't FastCGI included with Apache any + more?</A> + </LI> + <LI><A HREF="#nodelay">Why am I getting "<SAMP>httpd: could not + set socket option TCP_NODELAY</SAMP>" in my error log?</A> + </LI> + <LI><A HREF="#peerreset">Why am I getting "<SAMP>connection + reset by peer</SAMP>" in my error log?</A> + </LI> + <LI><A HREF="#nph-scripts">How can I get my script's output without + Apache buffering it? Why doesn't my server push work?</A> + </LI> + <LI><A HREF="#linuxiovec">Why do I get complaints about redefinition + of "<CODE>struct iovec</CODE>" when compiling under Linux?</A> + </LI> + <LI><A HREF="#wheres-the-dump">The errorlog says Apache dumped core, + but where's the dump file?</A> + </LI> + <LI><A HREF="#dnsauth">Why isn't restricting access by host or domain name + working correctly?</A> + </LI> + <LI><A HREF="#SSL-i">Why doesn't Apache include SSL?</A> + </LI> + <LI><A HREF="#HPUX-core">Why do I get core dumps under HPUX using + HP's ANSI C compiler?</A> + </LI> + <LI><A HREF="#midi">How do I get Apache to send a MIDI file so the + browser can play it?</A> + </LI> + <LI><A HREF="#cantbuild">Why won't Apache compile with my + system's <SAMP>cc</SAMP>?</A> + </LI> + <LI><A HREF="#addlog">How do I add browsers and referrers to my + logs?</A> + </LI> + <LI><A HREF="#bind8.1">Why do I get an error about an undefined + reference to "<SAMP>__inet_ntoa</SAMP>" or other + <SAMP>__inet_*</SAMP> symbols?</A> + </LI> + <LI><A HREF="#set-servername">Why does accessing directories only work + when I include the trailing "/" + (<EM>e.g.</EM>, <SAMP>http://foo.domain.com/~user/</SAMP>) but + not when I omit it + (<EM>e.g.</EM>, <SAMP>http://foo.domain.com/~user</SAMP>)?</A> + </LI> + <LI><A HREF="#user-authentication">How do I set up Apache to require + a username and password to access certain documents?</A> + </LI> + <LI><A HREF="#remote-user-var">Why is the environment variable + <SAMP>REMOTE_USER</SAMP> not set?</A> + </LI> + <LI><A HREF="#remote-auth-only">How do I set up Apache to allow access + to certain documents only if a site is either a local site + <EM>or</EM> the user supplies a password and username?</A> + </LI> + <LI><A HREF="#no-info-directives">Why doesn't mod_info list any + directives?</A> + <LI><A HREF="#linux-shmget">When I run it under Linux I get "shmget: + function not found", what should I do?</A> + </LI> + <LI><A HREF="#authauthoritative">Why does my authentication give + me a server error?</A> + <LI><A HREF="#auth-on-same-machine">Do I have to keep the (mSQL) + authentication information on the same machine?</A> + </LI> + <LI><A HREF="#msql-slow">Why is my mSQL authentication terribly slow?</A> + </LI> + <LI><A HREF="#rewrite-more-config">Where can I find mod_rewrite rulesets + which already solve particular URL-related problems?</A> + </LI> + <LI><A HREF="#rewrite-article">Where can I find any published information about + URL-manipulations and mod_rewrite?</A> + </LI> + <LI><A HREF="#rewrite-complexity">Why is mod_rewrite so difficult to learn + and seems so complicated?</A> + </LI> + <LI><A HREF="#rewrite-dontwork">What can I do if my RewriteRules don't work + as expected?</A> + </LI> + <LI><A HREF="#rewrite-prefixdocroot">Why don't some of my URLs get + prefixed with DocumentRoot when using mod_rewrite?</A> + </LI> + <LI><A HREF="#rewrite-nocase">How can I make all my URLs case-insensitive + with mod_rewrite?</A> + </LI> + <LI><A HREF="#rewrite-virthost">Why are RewriteRules in my VirtualHost + parts ignored?</A> + </LI> + <LI><A HREF="#rewrite-envwhitespace">How can I use strings with whitespaces + in RewriteRule's ENV flag?</A> + </LI> + <LI><A HREF="#cgi-spec">Where can I find the "CGI + specification"?</A> + </LI> + <LI><A HREF="#year2000">Is Apache Year 2000 compliant?</A> + </LI> + <LI><A HREF="#namevhost">I upgraded to Apache 1.3b and now my + virtual hosts don't work!</A> + </LI> + <LI><A HREF="#redhat">I'm using RedHat Linux and I have problems with httpd + dying randomly or not restarting properly</A> + </LI> + <li><a href="#stopping">I upgraded from an Apache version earlier + than 1.2.0 and suddenly I have problems with Apache dying randomly + or not restarting properly</a> + </li> + <li><a href="#redhat-htm">I'm using RedHat Linux and my .htm files are showing + up as html source rather than being formatted!</a> + </li> + <li><a href="#glibc-crypt">I'm using RedHat Linux 5.0, or some other glibc + based Linux system, and I get errors with the <code>crypt</code> function when + I attempt to build Apache 1.2.</a> + </li> + </OL> + </LI> +</UL> + +<HR> + + <H2>The Answers</H2> + <H3> + Background + </H3> +<OL START=1> + <LI><A NAME="what"> + <STRONG>What is Apache?</STRONG> + </A> + <P> + Apache was originally based on code and ideas found in the most + popular HTTP server of the time.. NCSA httpd 1.3 (early 1995). It has + since evolved into a far superior system which can rival (and probably + surpass) almost any other UNIX based HTTP server in terms of functionality, + efficiency and speed. + </P> + <P> + Since it began, it has been completely rewritten, and includes many new + features. Apache is, as of January 1997, the most popular WWW server on + the Internet, according to the + <A + HREF="http://www.netcraft.com/Survey/" + >Netcraft Survey</A>. + </P> + <HR> + </LI> + <LI><A NAME="why"> + <STRONG>Why was Apache created?</STRONG> + </A> + <P> + To address the concerns of a group of WWW providers and part-time httpd + programmers that httpd didn't behave as they wanted it to behave. + Apache is an entirely volunteer effort, completely funded by its + members, not by commercial sales. + </P> + <HR> + </LI> + <LI><A NAME="relate"> + <STRONG>How does The Apache Group's work relate to other + server efforts, such as NCSA's?</STRONG> + </A> + <P> + We, of course, owe a great debt to NCSA and their programmers for + making the server Apache was based on. We now, however, have our own + server, and our project is mostly our own. The Apache Project is an + entirely independent venture. + </P> + <HR> + </LI> + <LI><A NAME="name"> + <STRONG>Why the name "Apache"?</STRONG> + </A> + <P> + A cute name which stuck. Apache is "<STRONG>A + PA</STRONG>t<STRONG>CH</STRONG>y server". It was + based on some existing code and a series of "patch files". + </P> + <HR> + </LI> + <LI><A NAME="compare"> + <STRONG>OK, so how does Apache compare to other servers?</STRONG> + </A> + <P> + For an independent assessment, see + <A + HREF="http://webcompare.internet.com/chart.html" + >Web Compare</A>'s + comparison chart. + </P> + <P> + Apache has been shown to be substantially faster than many other + free servers. Although certain commercial servers have claimed to + surpass Apache's speed (it has not been demonstrated that any of these + "benchmarks" are a good way of measuring WWW server speed at any + rate), we feel that it is better to have a mostly-fast free server + than an extremely-fast server that costs thousands of dollars. Apache + is run on sites that get millions of hits per day, and they have + experienced no performance difficulties. + </P> + <HR> + </LI> + <LI><A NAME="tested"> + <STRONG>How thoroughly tested is Apache?</STRONG> + </A> + <P> + Apache is run on over 500,000 Internet servers (as of July 1997). It has + been tested thoroughly by both developers and users. The Apache Group + maintains rigorous standards before releasing new versions of their + server, and our server runs without a hitch on over one third of all + WWW servers available on the Internet. When bugs do show up, we + release patches and new versions as soon as they are available. + </P> + <P> + The Apache project's web site includes a page with a partial list of + <A + HREF="http://www.apache.org/info/apache_users.html" + >sites running Apache</A>. + </P> + <HR> + </LI> + <LI><A NAME="future"> + <STRONG>What are the future plans for Apache?</STRONG> + </A> + <P> + <UL> + <LI>to continue as a public domain HTTP server, + </LI> + <LI>to keep up with advances in HTTP protocol and web developments in + general, + </LI> + <LI>to collect suggestions for fixes/improvements from its users, + </LI> + <LI>to respond to needs of large volume providers as well as + occasional users. + </LI> + </UL> + </P> + <HR> + </LI> + <LI><A NAME="support"> + <STRONG>Whom do I contact for support?</STRONG> + </A> + <P> + There is no official support for Apache. None of the developers want to + be swamped by a flood of trivial questions that can be resolved elsewhere. + Bug reports and suggestions should be sent <EM>via</EM> + <A + HREF="http://www.apache.org/bug_report.html" + >the bug report page</A>. + Other questions should be directed to the + <A + HREF="news:comp.infosystems.www.servers.unix" + ><SAMP>comp.infosystems.www.servers.unix</SAMP></A> + newsgroup, where some of the Apache team lurk, + in the company of many other httpd gurus who should be able + to help. + </P> + <P> + Commercial support for Apache is, however, available from a number + of third parties. + </P> + <HR> + </LI> + <LI><A NAME="more"> + <STRONG>Is there any more information available on + Apache?</STRONG> + </A> + <P> + Indeed there is. See the main + <A + HREF="http://www.apache.org/" + >Apache web site</A>. + There is also a regular electronic publication called + <A + HREF="http://www.apacheweek.com/" + REL="Help" + ><CITE>Apache Week</CITE></A> + available. Links to relevant <CITE>Apache Week</CITE> articles are + included below where appropriate. There are also some + <A + HREF="http://www.apache.org/info/apache_books.html" + >Apache-specific books</A> available. + </P> + <HR> + </LI> + <LI><A NAME="where"> + <STRONG>Where can I get Apache?</STRONG> + </A> + <P> + You can find out how to download the source for Apache at the + project's + <A + HREF="http://www.apache.org/" + >main web page</A>. + </P> + <HR> + </LI> +</OL> + <H3> + Technical Questions + </H3> +<OL START=11> + <LI><A NAME="what2do"> + <STRONG>"Why can't I ...? Why won't ... work?" What to + do in case of problems</STRONG> + </A> + <P> + If you are having trouble with your Apache server software, you should + take the following steps: + </P> + <OL> + <LI><STRONG>Check the errorlog!</STRONG> + <P> + Apache tries to be helpful when it encounters a problem. In many + cases, it will provide some details by writing one or messages to + the server error log. Sometimes this is enough for you to diagnose + & fix the problem yourself (such as file permissions or the like). + The default location of the error log is + <SAMP>/usr/local/apache/logs/error_log</SAMP>, but see the + <A + HREF="../mod/core.html#errorlog" + ><SAMP>ErrorLog</SAMP></A> + directive in your config files for the location on your server. + </P> + </LI> + <LI><STRONG>Check the + <A + HREF="http://www.apache.org/docs/misc/FAQ.html" + >FAQ</A>!</STRONG> + <P> + The latest version of the Apache Frequently-Asked Questions list can + always be found at the main Apache web site. + </P> + </LI> + <LI><STRONG>Check the Apache bug database</STRONG> + <P> + Most problems that get reported to The Apache Group are recorded in + the + <A + HREF="http://bugs.apache.org/" + >bug database</A>. + <EM><STRONG>Please</STRONG> check the existing reports, open + <STRONG>and</STRONG> closed, before adding one.</EM> If you find + that your issue has already been reported, please <EM>don't</EM> add + a "me, too" report. If the original report isn't closed + yet, we suggest that you check it periodically. You might also + consider contacting the original submitter, because there may be an + email exchange going on about the issue that isn't getting recorded + in the database. + </P> + </LI> + <LI><STRONG>Ask in the <SAMP>comp.infosystems.www.servers.unix</SAMP> + USENET newsgroup</STRONG> + <P> + A lot of common problems never make it to the bug database because + there's already high Q&A traffic about them in the + <A + HREF="news:comp.infosystems.www.servers.unix" + ><SAMP>comp.infosystems.www.servers.unix</SAMP></A> + newsgroup. Many Apache users, and some of the developers, can be + found roaming its virtual halls, so it is suggested that you seek + wisdom there. The chances are good that you'll get a faster answer + there than from the bug database, even if you <EM>don't</EM> see + your question already posted. + </P> + </LI> + <LI><STRONG>If all else fails, report the problem in the bug + database</STRONG> + <P> + If you've gone through those steps above that are appropriate and + have obtained no relief, then please <EM>do</EM> let The Apache + Group know about the problem by + <A + HREF="http://www.apache.org/bug_report.html" + >logging a bug report</A>. + </P> + <P> + If your problem involves the server crashing and generating a core + dump, please include a backtrace (if possible). As an example, + </P> + <P> + <DL> + <DD><CODE># cd <EM>ServerRoot</EM><BR> + # dbx httpd core<BR> + (dbx) where</CODE> + </DD> + </DL> + </P> + <P> + (Substitute the appropriate locations for your + <SAMP>ServerRoot</SAMP> and your <SAMP>httpd</SAMP> and + <SAMP>core</SAMP> files. You may have to use <CODE>gdb</CODE> + instead of <CODE>dbx</CODE>.) + </P> + </LI> + </OL> + <HR> + </LI> + <LI><A NAME="compatible"> + <STRONG>How compatible is Apache with my existing NCSA 1.3 + setup?</STRONG> + </A> + <P> + Apache attempts to offer all the features and configuration options + of NCSA httpd 1.3, as well as many of the additional features found in + NCSA httpd 1.4 and NCSA httpd 1.5. + </P> + <P> + NCSA httpd appears to be moving toward adding experimental features + which are not generally required at the moment. Some of the experiments + will succeed while others will inevitably be dropped. The Apache + philosophy is to add what's needed as and when it is needed. + </P> + <P> + Friendly interaction between Apache and NCSA developers should ensure + that fundamental feature enhancements stay consistent between the two + servers for the foreseeable future. + </P> + <HR> + </LI> + <LI><A NAME="CGIoutsideScriptAlias"> + <STRONG>How do I enable CGI execution in directories other than + the ScriptAlias?</STRONG> + </A> + <P> + Apache recognizes all files in a directory named as a + <A + HREF="../mod/mod_alias.html#scriptalias" + ><SAMP>ScriptAlias</SAMP></A> + as being eligible for execution rather than processing as normal + documents. This applies regardless of the file name, so scripts in a + ScriptAlias directory don't need to be named + "<SAMP>*.cgi</SAMP>" or "<SAMP>*.pl</SAMP>" or + whatever. In other words, <EM>all</EM> files in a ScriptAlias + directory are scripts, as far as Apache is concerned. + </P> + <P> + To persuade Apache to execute scripts in other locations, such as in + directories where normal documents may also live, you must tell it how + to recognize them - and also that it's okay to execute them. For + this, you need to use something like the + <A + HREF="../mod/mod_mime.html#addhandler" + ><SAMP>AddHandler</SAMP></A> + directive. + </P> + <P> + <OL> + <LI>In an appropriate section of your server configuration files, add + a line such as + <P> + <DL> + <DD><CODE>AddHandler cgi-script .cgi</CODE> + </DD> + </DL> + </P> + <P> + The server will then recognize that all files in that location (and + its logical descendants) that end in "<SAMP>.cgi</SAMP>" + are script files, not documents. + </P> + </LI> + <LI>Make sure that the directory location is covered by an + <A + HREF="../mod/core.html#options" + ><SAMP>Options</SAMP></A> + declaration that includes the <SAMP>ExecCGI</SAMP> option. + </LI> + </OL> + </P> + <P> + In some situations it can be not conform to your local policy to actually + allow all files named "<SAMP>*.cgi</SAMP>" to be executable. + Perhaps all you want is to enable a particular file in a normal directory to + be executable. This can be alternatively accomplished + <EM>via</EM> + <A + HREF="../mod/mod_rewrite.html" + ><SAMP>mod_rewrite</SAMP></A> + and the following steps: + </P> + <P> + <OL> + <LI>Locally add to the corresponding <SAMP>.htaccess</SAMP> file a ruleset + similar to this one: + <P> + <DL> + <DD><CODE>RewriteEngine on + <BR> + RewriteBase /~foo/bar/ + <BR> + RewriteRule ^quux\.cgi$ - [T=application/x-httpd-cgi]</CODE> + </DD> + </DL> + </P> + </LI> + <LI>Make sure that the directory location is covered by an + <A + HREF="../mod/core.html#options" + ><SAMP>Options</SAMP></A> + declaration that includes the <SAMP>ExecCGI</SAMP> and + <SAMP>FollowSymLinks</SAMP> option. + </LI> + </OL> + </P> + <HR> + </LI> + <LI><A NAME="premature-script-headers"> + <STRONG>What does it mean when my CGIs fail with + "<SAMP>Premature end of script headers</SAMP>"?</STRONG> + </A> + <P> + It means just what it says: the server was expecting a complete set of + HTTP headers (one or more followed by a blank line), and didn't get + them. + </P> + <P> + The most common cause of this problem is the script dying before + sending the complete set of headers, or possibly any at all, to the + server. To see if this is the case, try running the script standalone + from an interactive session, rather than as a script under the server. + If you get error messages, this is almost certainly the cause of the + "premature end of script headers" message. + </P> + <P> + The second most common cause of this (aside from people not + outputting the required headers at all) is a result of an interaction + with Perl's output buffering. To make Perl flush its buffers + after each output statement, insert the following statements around + the <CODE>print</CODE> or <CODE>write</CODE> statements that send your + HTTP headers: + </P> + <P> + <DL> + <DD><CODE>{<BR> + local ($oldbar) = $|;<BR> + $cfh = select (STDOUT);<BR> + $| = 1;<BR> + #<BR> + # print your HTTP headers here<BR> + #<BR> + $| = $oldbar;<BR> + select ($cfh);<BR> + }</CODE> + </DD> + </DL> + </P> + <P> + This is generally only necessary when you are calling external + programs from your script that send output to stdout, or if there will + be a long delay between the time the headers are sent and the actual + content starts being emitted. To maximize performance, you should + turn buffer-flushing back <EM>off</EM> (with <CODE>$| = 0</CODE> or the + equivalent) after the statements that send the headers, as displayed + above. + </P> + <P> + If your script isn't written in Perl, do the equivalent thing for + whatever language you <EM>are</EM> using (<EM>e.g.</EM>, for C, call + <CODE>fflush()</CODE> after writing the headers). + </P> + <HR> + </LI> + <LI><A NAME="ssi-part-i"> + <STRONG>How do I enable SSI (parsed HTML)?</STRONG> + </A> + <P> + SSI (an acronym for Server-Side Include) directives allow static HTML + documents to be enhanced at run-time (<EM>e.g.</EM>, when delivered to + a client by Apache). The format of SSI directives is covered + in the <A HREF="../mod/mod_include.html">mod_include manual</A>; + suffice it to say that Apache supports not only SSI but + xSSI (eXtended SSI) directives. + </P> + <P> + Processing a document at run-time is called <EM>parsing</EM> it; hence + the term "parsed HTML" sometimes used for documents that + contain SSI instructions. Parsing tends to be <EM>extremely</EM> + resource-consumptive, and is not enabled by default. It can also + interfere with the cachability of your documents, which can put a + further load on your server. (see the + <A + HREF="#ssi-part-ii" + >next question</A> + for more information about this.) + </P> + <P> + To enable SSI processing, you need to + </P> + <UL> + <LI>Build your server with the + <A + HREF="../mod/mod_include.html" + ><SAMP>mod_include</SAMP></A> + module. This is normally compiled in by default. + </LI> + <LI>Make sure your server configuration files have an + <A + HREF="../mod/core.html#options" + ><SAMP>Options</SAMP></A> + directive which permits <SAMP>Includes</SAMP>. + </LI> + <LI>Make sure that the directory where you want the SSI documents to + live is covered by the "server-parsed" content handler, + either explicitly or in some ancestral location. That can be done + with the following + <A + HREF="../mod/mod_mime.html#addhandler" + ><SAMP>AddHandler</SAMP></A> + directive: + <P> + <DL> + <DD><CODE>AddHandler server-parsed .shtml</CODE> + </DD> + </DL> + </P> + This indicates that all files ending in ".shtml" in that + location (or its descendants) should be parsed. Note that using + ".html" will cause all normal HTML files to be parsed, + which may put an inordinate load on your server. + </LI> + </UL> + <P> + For additional information, see the <CITE>Apache Week</CITE> article + on + <A + HREF="http://www.apacheweek.com/features/ssi" + REL="Help" + ><CITE>Using Server Side Includes</CITE></A>. + </P> + <HR> + </LI> + <LI><A NAME="ssi-part-ii"> + <STRONG>Why don't my parsed files get cached?</STRONG> + </A> + <P> + Since the server is performing run-time processing of your SSI + directives, which may change the content shipped to the client, it + can't know at the time it starts parsing what the final size of the + result will be, or whether the parsed result will always be the same. + This means that it can't generate <SAMP>Content-Length</SAMP> or + <SAMP>Last-Modified</SAMP> headers. Caches commonly work by comparing + the <SAMP>Last-Modified</SAMP> of what's in the cache with that being + delivered by the server. Since the server isn't sending that header + for a parsed document, whatever's doing the caching can't tell whether + the document has changed or not - and so fetches it again to be on the + safe side. + </P> + <P> + You can work around this in some cases by causing an + <SAMP>Expires</SAMP> header to be generated. (See the + <A + HREF="../mod/mod_expires.html" + REL="Help" + ><SAMP>mod_expires</SAMP></A> + documentation for more details.) Another possibility is to use the + <A + HREF="../mod/mod_include.html#xbithack" + REL="Help" + ><SAMP>XBitHack Full</SAMP></A> + mechanism, which tells Apache to send (under certain circumstances + detailed in the XBitHack directive description) a + <SAMP>Last-Modified</SAMP> header based upon the last modification + time of the file being parsed. Note that this may actually be lying + to the client if the parsed file doesn't change but the SSI-inserted + content does; if the included content changes often, this can result + in stale copies being cached. + </P> + <HR> + </LI> + <LI><A NAME="ssi-part-iii"> + <STRONG>How can I have my script output parsed?</STRONG> + </A> + <P> + So you want to include SSI directives in the output from your CGI + script, but can't figure out how to do it? + The short answer is "you can't." This is potentially + a security liability and, more importantly, it can not be cleanly + implemented under the current server API. The best workaround + is for your script itself to do what the SSIs would be doing. + After all, it's generating the rest of the content. + </P> + <P> + This is a feature The Apache Group hopes to add in the next major + release after 1.3. + </P> + <HR> + </LI> + <LI><A NAME="proxy"> + <STRONG>Does or will Apache act as a Proxy server?</STRONG> + </A> + <P> + Apache version 1.1 and above comes with a + <A + HREF="../mod/mod_proxy.html" + >proxy module</A>. + If compiled + in, this will make Apache act as a caching-proxy server. + </P> + <HR> + </LI> + <LI><A NAME="multiviews"> + <STRONG>What are "multiviews"?</STRONG> + </A> + <P> + "Multiviews" is the general name given to the Apache + server's ability to provide language-specific document variants in + response to a request. This is documented quite thoroughly in the + <A + HREF="../content-negotiation.html" + REL="Help" + >content negotiation</A> + description page. In addition, <CITE>Apache Week</CITE> carried an + article on this subject entitled + "<A + HREF="http://www.apacheweek.com/features/negotiation" + REL="Help" + ><CITE>Content Negotiation Explained</CITE></A>". + </P> + <HR> + </LI> + <LI><A NAME="fdlim"> + <STRONG>Why can't I run more than <<EM>n</EM>> + virtual hosts?</STRONG> + </A> + <P> + You are probably running into resource limitations in your + operating system. The most common limitation is the + <EM>per</EM>-process limit on <STRONG>file descriptors</STRONG>, + which is almost always the cause of problems seen when adding + virtual hosts. Apache often does not give an intuitive error + message because it is normally some library routine (such as + <CODE>gethostbyname()</CODE>) which needs file descriptors and + doesn't complain intelligibly when it can't get them. + </P> + <P> + Each log file requires a file descriptor, which means that if you are + using separate access and error logs for each virtual host, each + virtual host needs two file descriptors. Each + <A + HREF="../mod/core.html#listen" + ><SAMP>Listen</SAMP></A> + directive also needs a file descriptor. + </P> + <P> + Typical values for <<EM>n</EM>> that we've seen are in + the neighborhood of 128 or 250. When the server bumps into the file + descriptor limit, it may dump core with a SIGSEGV, it might just + hang, or it may limp along and you'll see (possibly meaningful) errors + in the error log. One common problem that occurs when you run into + a file descriptor limit is that CGI scripts stop being executed + properly. + </P> + <P> + As to what you can do about this: + </P> + <OL> + <LI>Reduce the number of + <A + HREF="../mod/core.html#listen" + ><SAMP>Listen</SAMP></A> + directives. If there are no other servers running on the machine + on the same port then you normally don't + need any Listen directives at all. By default Apache listens to + all addresses on port 80. + </LI> + <LI>Reduce the number of log files. You can use + <A + HREF="../mod/mod_log_config.html" + ><SAMP>mod_log_config</SAMP></A> + to log all requests to a single log file while including the name + of the virtual host in the log file. You can then write a + script to split the logfile into separate files later if + necessary. + </LI> + <LI>Increase the number of file descriptors available to the server + (see your system's documentation on the <CODE>limit</CODE> or + <CODE>ulimit</CODE> commands). For some systems, information on + how to do this is available in the + <A + HREF="perf.html" + >performance hints</A> + page. There is a specific note for + <A HREF="#freebsd-setsize">FreeBSD</A> below. + </LI> + <LI>"Don't do that" - try to run with fewer virtual hosts + </LI> + <LI>Spread your operation across multiple server processes (using + <A + HREF="../mod/core.html#listen" + ><SAMP>Listen</SAMP></A> + for example, but see the first point) and/or ports. + </LI> + </OL> + <P> + Since this is an operating-system limitation, there's not much else + available in the way of solutions. + </P> + <P> + As of 1.2.1 we have made attempts to work around various limitations + involving running with many descriptors. + <A HREF="descriptors.html">More information is available.</A> + </P> + <HR> + </LI> + + <LI><A NAME="freebsd-setsize"> + <STRONG>Can I increase <SAMP>FD_SETSIZE</SAMP> on FreeBSD?</STRONG> + </A> + <P> + On versions of FreeBSD before 3.0, the <SAMP>FD_SETSIZE</SAMP> define + defaults to 256. This means that you will have trouble usefully using + more than 256 file descriptors in Apache. This can be increased, but + doing so can be tricky. + + If you are using a version prior to 2.2, you need to recompile your + kernel with a larger FD_SETSIZE. This can be done by adding a + line such as: + </P> + <DL> + <DD><CODE>options FD_SETSIZE <EM>nnn</EM></CODE> + </DD> + </DL> + <P> + To your kernel config file. Starting at version 2.2, this is no + longer necessary. + </P> + <P> + If you are using a version of 2.1-stable from after 1997/03/10 or + 2.2 or 3.0-current from before 1997/06/28, there is a limit in + the resolver library that prevents it from using more file descriptors + than what FD_SETSIZE is set to when libc is compiled. To increase + this, you have to recompile libc with a higher FD_SETSIZE. + </P> + <P> + In FreeBSD 3.0, the default FD_SETSIZE has been increased to + 1024 and the above limitation in the resolver library + has been removed. + </P> + <P> + After you deal with the appropriate changes above, you can increase + the setting of <SAMP>FD_SETSIZE</SAMP> at Apache compilation time + by adding "<SAMP>-DFD_SETSIZE=<EM>nnn</EM></SAMP>" to the + <SAMP>EXTRA_CFLAGS</SAMP> line in your <SAMP>Configuration</SAMP> + file. + </P> + <HR> + </LI> + + <LI><A NAME="limitGET"> + <STRONG>Why do I keep getting "access denied" for form POST + requests?</STRONG> + </A> + <P> + The most common cause of this is a <SAMP><Limit></SAMP> section + that only names the <SAMP>GET</SAMP> method. Look in your + configuration files for something that resembles the following and + would affect the location where the POST-handling script resides: + </P> + <P> + <DL> + <DD><CODE><Limit GET> + <BR> :</CODE> + </DD> + </DL> + </P> + <P> + Change that to <CODE><Limit GET POST></CODE> and the problem + will probably go away. Better yet, remove the + <CODE><Limit></CODE> and <CODE></Limit></CODE> lines + altogether unless you're <EM>specifically</EM> trying to limit by + method (<SAMP>GET</SAMP>, <SAMP>PUT</SAMP>, <EM>et cetera</EM>). If + you don't have a <CODE><Limit></CODE> container, the + restrictions apply equally to <EM>all</EM> methods. + </P> + <HR> + </LI> + <LI><A NAME="passwdauth"> + <STRONG>Can I use my <SAMP>/etc/passwd</SAMP> file + for Web page authentication?</STRONG> + </A> + <P> + Yes, you can - but it's a <STRONG>very bad idea</STRONG>. Here are + some of the reasons: + </P> + <UL> + <LI>The Web technology provides no governors on how often or how + rapidly password (authentication failure) retries can be made. That + means that someone can hammer away at your system's + <SAMP>root</SAMP> password using the Web, using a dictionary or + similar mass attack, just as fast as the wire and your server can + handle the requests. Most operating systems these days include + attack detection (such as <EM>n</EM> failed passwords for the same + account within <EM>m</EM> seconds) and evasion (breaking the + connection, disabling the account under attack, disabling + <EM>all</EM> logins from that source, <EM>et cetera</EM>), but the + Web does not. + </LI> + <LI>An account under attack isn't notified (unless the server is + heavily modified); there's no "You have 19483 login + failures" message when the legitimate owner logs in. + </LI> + <LI>Without an exhaustive and error-prone examination of the server + logs, you can't tell whether an account has been compromised. + Detecting that an attack has occurred, or is in progress, is fairly + obvious, though - <EM>if</EM> you look at the logs. + </LI> + <LI>Web authentication passwords (at least for Basic authentication) + generally fly across the wire, and through intermediate proxy + systems, in what amounts to plain text. "O'er the net we + go/Caching all the way;/O what fun it is to surf/Giving my password + away!" + </LI> + <LI>Since HTTP is stateless, information about the authentication is + transmitted <EM>each and every time</EM> a request is made to the + server. Essentially, the client caches it after the first + successful access, and transmits it without asking for all + subsequent requests to the same server. + </LI> + <LI>It's relatively trivial for someone on your system to put up a + page that will steal the cached password from a client's cache + without them knowing. Can you say "password grabber"? + </LI> + </UL> + <P> + If you still want to do this in light of the above disadvantages, the + method is left as an exercise for the reader. It'll void your Apache + warranty, though, and you'll lose all accumulated UNIX guru points. + </P> + <HR> + </LI> + <LI><A NAME="errordoc401"> + <STRONG>Why doesn't my <CODE>ErrorDocument 401</CODE> work?</STRONG> + </A> + <P> + You need to use it with a URL in the form + "<SAMP>/foo/bar</SAMP>" and not one with a method and + hostname such as "<SAMP>http://host/foo/bar</SAMP>". See the + <A + HREF="../mod/core.html#errordocument" + ><SAMP>ErrorDocument</SAMP></A> + documentation for details. This was incorrectly documented in the past. + </P> + <HR> + </LI> + <LI><A NAME="errordocssi"> + <STRONG>How can I use <CODE>ErrorDocument</CODE> + and SSI to simplify customized error messages?</STRONG> + </A> + <P> + Have a look at <A HREF="custom_errordocs.html">this document</A>. + It shows in example form how you can a combination of XSSI and + negotiation to tailor a set of <CODE>ErrorDocument</CODE>s to your + personal taste, and returning different internationalized error + responses based on the client's native language. + </P> + <HR> + </LI> + <LI><A NAME="setgid"> + <STRONG>Why do I get "<SAMP>setgid: Invalid + argument</SAMP>" at startup?</STRONG> + </A> + <P> + Your + <A + HREF="../mod/core.html#group" + ><SAMP>Group</SAMP></A> + directive (probably in <SAMP>conf/httpd.conf</SAMP>) needs to name a + group that actually exists in the <SAMP>/etc/group</SAMP> file (or + your system's equivalent). + </P> + <HR> + </LI> + <LI><A NAME="cookies1"> + <STRONG>Why does Apache send a cookie on every response?</STRONG> + </A> + <P> + Apache does <EM>not</EM> send automatically send a cookie on every + response, unless you have re-compiled it with the + <A + HREF="../mod/mod_cookies.html" + ><SAMP>mod_cookies</SAMP></A> + module. + This module was distributed with Apache prior to 1.2. + This module may help track users, and uses cookies to do this. If + you are not using the data generated by <SAMP>mod_cookies</SAMP>, do + not compile it into Apache. Note that in 1.2 this module was renamed + to the more correct name + <A + HREF="../mod/mod_usertrack.html" + ><SAMP>mod_usertrack</SAMP></A>, + and cookies + have to be specifically enabled with the + <A + HREF="../mod/mod_usertrack.html#cookietracking" + ><SAMP>CookieTracking</SAMP></A> + directive. + </P> + <HR> + </LI> + <LI><A NAME="cookies2"> + <STRONG>Why don't my cookies work, I even compiled in + <SAMP>mod_cookies</SAMP>? + </STRONG> + </A> + <P> + Firstly, you do <EM>not</EM> need to compile in + <SAMP>mod_cookies</SAMP> in order for your scripts to work (see the + <A + HREF="#cookies1" + >previous question</A> + for more about <SAMP>mod_cookies</SAMP>). Apache passes on your + <SAMP>Set-Cookie</SAMP> header fine, with or without this module. If + cookies do not work it will be because your script does not work + properly or your browser does not use cookies or is not set-up to + accept them. + </P> + <HR> + </LI> + <LI><A NAME="jdk1-and-http1.1"> + <STRONG>Why do my Java app[let]s give me plain text when I request + an URL from an Apache server?</STRONG> + </A> + <P> + As of version 1.2, Apache is an HTTP/1.1 (HyperText Transfer Protocol + version 1.1) server. This fact is reflected in the protocol version + that's included in the response headers sent to a client when + processing a request. Unfortunately, low-level Web access classes + included in the Java Development Kit (JDK) version 1.0.2 expect to see + the version string "HTTP/1.0" and do not correctly interpret + the "HTTP/1.1" value Apache is sending (this part of the + response is a declaration of what the server can do rather than a + declaration of the dialect of the response). The result + is that the JDK methods do not correctly parse the headers, and + include them with the document content by mistake. + </P> + <P> + This is definitely a bug in the JDK 1.0.2 foundation classes from Sun, + and it has been fixed in version 1.1. However, the classes in + question are part of the virtual machine environment, which means + they're part of the Web browser (if Java-enabled) or the Java + environment on the client system - so even if you develop + <EM>your</EM> classes with a recent JDK, the eventual users might + encounter the problem. + The classes involved are replaceable by vendors implementing the + Java virtual machine environment, and so even those that are based + upon the 1.0.2 version may not have this problem. + </P> + <P> + In the meantime, a workaround is to tell + Apache to "fake" an HTTP/1.0 response to requests that come + from the JDK methods; this can be done by including a line such as the + following in your server configuration files: + </P> + <P> + <DL> + <DD><CODE>BrowserMatch Java1.0 force-response-1.0 + <BR> + BrowserMatch JDK/1.0 force-response-1.0</CODE> + </DD> + </DL> + </P> + <P> + More information about this issue can be found in the + <A + HREF="http://www.apache.org/info/jdk-102.html" + ><CITE>Java and HTTP/1.1</CITE></A> + page at the Apache web site. + </P> + <HR> + </LI> + <LI><A NAME="putsupport"> + <STRONG>Why can't I publish to my Apache server using PUT on + Netscape Gold and other programs?</STRONG> + </A> + <P> + Because you need to install and configure a script to handle + the uploaded files. This script is often called a "PUT" handler. + There are several available, but they may have security problems. + Using FTP uploads may be easier and more secure, at least for now. + For more information, see the <CITE>Apache Week</CITE> article + <A + HREF="http://www.apacheweek.com/features/put" + ><CITE>Publishing Pages with PUT</CITE></A>. + </P> + <HR> + </LI> + <LI><A NAME="fastcgi"> + <STRONG>Why isn't FastCGI included with Apache any more?</STRONG> + </A> + <P> + The simple answer is that it was becoming too difficult to keep the + version being included with Apache synchronized with the master copy + at the + <A + HREF="http://www.fastcgi.com/servers/apache/" + >FastCGI web site</A>. When a new version of Apache was released, the + version of the FastCGI module included with it would soon be out of date. + </P> + <P> + You can still obtain the FastCGI module for Apache from the master + FastCGI web site. + </P> + <HR> + </LI> + <LI><A NAME="nodelay"> + <STRONG>Why am I getting "<SAMP>httpd: could not set socket + option TCP_NODELAY</SAMP>" in my error log?</STRONG> + </A> + <P> + This message almost always indicates that the client disconnected + before Apache reached the point of calling <CODE>setsockopt()</CODE> + for the connection. It shouldn't occur for more than about 1% of the + requests your server handles, and it's advisory only in any case. + </P> + <HR> + </LI> + <LI><A NAME="peerreset"> + <STRONG>Why am I getting "<SAMP>connection reset by + peer</SAMP>" in my error log?</STRONG> + </A> + <P> + This is a normal message and nothing about which to be alarmed. It simply + means that the client canceled the connection before it had been + completely set up - such as by the end-user pressing the "Stop" + button. People's patience being what it is, sites with response-time + problems or slow network links may experiences this more than + high-capacity ones or those with large pipes to the network. + </P> + <HR> + </LI> + <LI><A NAME="nph-scripts"> + <STRONG>How can I get my script's output without Apache buffering + it? Why doesn't my server push work?</STRONG> + </A> + <P> + In order to improve network performance, Apache buffers script output + into relatively large chunks. If you have a script that sends + information in bursts (eg. as partial-done messages in a multi-commit + database transaction or any type of server push), the client will + not necessarily get the output as the script is generating it. + </P> + <P> + To avoid this, Apache recognizes scripts whose names begin with + "<SAMP>nph-</SAMP>" as <EM>non-parsed-header</EM> scripts. + That is, Apache won't buffer their output, but connect it directly to + the socket going back to the client. + </P> + <P> + While this will probably do what you want, there <EM>are</EM> some + disadvantages to it: + </P> + <UL> + <LI><STRONG>YOU</STRONG> (the script) are responsible for generating + <STRONG>ALL</STRONG> of the HTTP headers, and no longer + <EM>just</EM> the "<SAMP>Content-type</SAMP>" or + "<SAMP>Location</SAMP>" headers + </LI> + <LI>Unless your script generates its output carefully, you will see a + performance penalty as excessive numbers of packets go back and forth + </LI> + </UL> + <P> + As an example how you might handle the former (in a Perl script): + </P> + <P> + <DL> + <DD><CODE>if ($0 =~ m:^(.*/)*nph-[^/]*$:) { + <BR> + + $HTTP_headers = + "HTTP/1.1 200 OK\015\012"; + <BR> + + $HTTP_headers .= + "Connection: close\015\012"; + <BR> + + print $HTTP_headers; + <BR> + }</CODE> + </DD> + </DL> + </P> + <P> + and then follow with your normal non-<SAMP>nph</SAMP> headers. + </P> + <P>Note that in version 1.3, all CGI scripts will be unbuffered + so the only difference between nph scripts and normal scripts is + that nph scripts require the full HTTP headers to be sent. + </P> + <HR> + </LI> + <LI><A NAME="linuxiovec"> + <STRONG>Why do I get complaints about redefinition + of "<CODE>struct iovec</CODE>" when + compiling under Linux?</STRONG> + </A> + <P> + This is a conflict between your C library includes and your kernel + includes. You need to make sure that the versions of both are matched + properly. There are two workarounds, either one will solve the problem: + </P> + <P> + <UL> + <LI>Remove the definition of <CODE>struct iovec</CODE> from your C + library includes. It is located in <CODE>/usr/include/sys/uio.h</CODE>. + <STRONG>Or,</STRONG> + </LI> + <LI>Add <CODE>-DNO_WRITEV</CODE> to the <CODE>EXTRA_CFLAGS</CODE> + line in your <SAMP>Configuration</SAMP> and reconfigure/rebuild. + This hurts performance and should only be used as a last resort. + </LI> + </UL> + </P> + <HR> + </LI> + <LI><A NAME="wheres-the-dump"> + <STRONG>The errorlog says Apache dumped core, but where's the dump + file?</STRONG> + </A> + <P> + In Apache version 1.2, the error log message + about dumped core includes the directory where the dump file should be + located. However, many Unixes do not allow a process that has + called <CODE>setuid()</CODE> to dump core for security reasons; + the typical Apache setup has the server started as root to bind to + port 80, after which it changes UIDs to a non-privileged user to + serve requests. + </P> + <P> + Dealing with this is extremely operating system-specific, and may + require rebuilding your system kernel. Consult your operating system + documentation or vendor for more information about whether your system + does this and how to bypass it. If there <EM>is</EM> a documented way + of bypassing it, it is recommended that you bypass it only for the + <SAMP>httpd</SAMP> server process if possible. + </P> + <P> + The canonical location for Apache's core-dump files is the + <A HREF="../mod/core.html#serverroot">ServerRoot</A> + directory. As of Apache version 1.3, the location can be set <EM>via</EM> + the + <A + HREF="../mod/core.html#coredumpdirectory" + ><SAMP>CoreDumpDirectory</SAMP></A> + directive to a different directory. Make sure that this directory is + writable by the user the server runs as (as opposed to the user the server + is <EM>started</EM> as). + </P> + <HR> + </LI> + <LI><A NAME="dnsauth"> + <STRONG>Why isn't restricting access by host or domain name + working correctly?</STRONG> + </A> + <P> + Two of the most common causes of this are: + </P> + <OL> + <LI><STRONG>An error, inconsistency, or unexpected mapping in the DNS + registration</STRONG> + <BR> + This happens frequently: your configuration restricts access to + <SAMP>Host.FooBar.Com</SAMP>, but you can't get in from that host. + The usual reason for this is that <SAMP>Host.FooBar.Com</SAMP> is + actually an alias for another name, and when Apache performs the + address-to-name lookup it's getting the <EM>real</EM> name, not + <SAMP>Host.FooBar.Com</SAMP>. You can verify this by checking the + reverse lookup yourself. The easiest way to work around it is to + specify the correct host name in your configuration. + </LI> + <LI><STRONG>Inadequate checking and verification in your + configuration of Apache</STRONG> + <BR> + If you intend to perform access checking and restriction based upon + the client's host or domain name, you really need to configure + Apache to double-check the origin information it's supplied. You do + this by adding the <SAMP>-DMAXIMUM_DNS</SAMP> clause to the + <SAMP>EXTRA_CFLAGS</SAMP> definition in your + <SAMP>Configuration</SAMP> file. For example: + <P> + <DL> + <DD><CODE>EXTRA_CFLAGS=-DMAXIMUM_DNS</CODE> + </DD> + </DL> + </P> + <P> + This will cause Apache to be very paranoid about making sure a + particular host address is <EM>really</EM> assigned to the name it + claims to be. Note that this <EM>can</EM> incur a significant + performance penalty, however, because of all the name resolution + requests being sent to a nameserver. + </P> + </LI> + </OL> + <HR> + </LI> + <LI><A NAME="SSL-i"> + <STRONG>Why doesn't Apache include SSL?</STRONG> + </A> + <P> + SSL (Secure Socket Layer) data transport requires encryption, and many + governments have restrictions upon the import, export, and use of + encryption technology. If Apache included SSL in the base package, + its distribution would involve all sorts of legal and bureaucratic + issues, and it would no longer be freely available. Also, some of + the technology required to talk to current clients using SSL is + patented by <A HREF="http://www.rsa.com/">RSA Data Security</A>, + who restricts its use without a license. + </P> + <P> + Some SSL implementations of Apache are available, however; see the + "<A + HREF="http://www.apache.org/related_projects.html" + >related projects</A>" + page at the main Apache web site. + </P> + <P> + You can find out more about this topic in the <CITE>Apache Week</CITE> + article about + <A + HREF="http://www.apacheweek.com/features/ssl" + REL="Help" + ><CITE>Apache and Secure Transactions</CITE></A>. + </P> + <HR> + </LI> + <LI><A NAME="HPUX-core"> + <STRONG>Why do I get core dumps under HPUX using HP's ANSI + C compiler?</STRONG> + </A> + <P> + We have had numerous reports of Apache dumping core when compiled + with HP's ANSI C compiler using optimization. Disabling the compiler + optimization has fixed these problems. + </P> + <HR> + </LI> + <LI><A NAME="midi"> + <STRONG>How do I get Apache to send a MIDI file so the browser can + play it?</STRONG> + </A> + <P> + Even though the registered MIME type for MIDI files is + <SAMP>audio/midi</SAMP>, some browsers are not set up to recognize it + as such; instead, they look for <SAMP>audio/x-midi</SAMP>. There are + two things you can do to address this: + </P> + <OL> + <LI>Configure your browser to treat documents of type + <SAMP>audio/midi</SAMP> correctly. This is the type that Apache + sends by default. This may not be workable, however, if you have + many client installations to change, or if some or many of the + clients are not under your control. + </LI> + <LI>Instruct Apache to send a different <SAMP>Content-type</SAMP> + header for these files by adding the following line to your server's + configuration files: + <P> + <DL> + <DD><CODE>AddType audio/x-midi .mid .midi .kar</CODE> + </DD> + </DL> + </P> + <P> + Note that this may break browsers that <EM>do</EM> recognize the + <SAMP>audio/midi</SAMP> MIME type unless they're prepared to also + handle <SAMP>audio/x-midi</SAMP> the same way. + </P> + </LI> + </OL> + <HR> + </LI> + <LI><A NAME="cantbuild"> + <STRONG>Why won't Apache compile with my system's + <SAMP>cc</SAMP>?</STRONG> + </A> + <P> + If the server won't compile on your system, it is probably due to one + of the following causes: + </P> + <UL> + <LI><STRONG>The <SAMP>Configure</SAMP> script doesn't recognize your system + environment.</STRONG> + <BR> + This might be either because it's completely unknown or because + the specific environment (include files, OS version, <EM>et + cetera</EM>) isn't explicitly handled. If this happens, you may + need to port the server to your OS yourself. + </LI> + <LI><STRONG>Your system's C compiler is garbage.</STRONG> + <BR> + Some operating systems include a default C compiler that is either + not ANSI C-compliant or suffers from other deficiencies. The usual + recommendation in cases like this is to acquire, install, and use + <SAMP>gcc</SAMP>. + </LI> + <LI><STRONG>Your <SAMP>include</SAMP> files may be confused.</STRONG> + <BR> + In some cases, we have found that a compiler installation or system + upgrade has left the C header files in an inconsistent state. Make + sure that your include directory tree is in sync with the compiler and + the operating system. + </LI> + <LI><STRONG>Your operating system or compiler may be out of + revision.</STRONG> + <BR> + Software vendors (including those that develop operating systems) + issue new releases for a reason; sometimes to add functionality, but + more often to fix bugs that have been discovered. Try upgrading + your compiler and/or your operating system. + </LI> + </UL> + <P> + The Apache Group tests the ability to build the server on many + different platforms. Unfortunately, we can't test all of the OS + platforms there are. If you have verified that none of the above + issues is the cause of your problem, and it hasn't been reported + before, please submit a + <A + HREF="http://www.apache.org/bug_report.html" + >problem report</A>. + Be sure to include <EM>complete</EM> details, such as the compiler + & OS versions and exact error messages. + </P> + <HR> + </LI> + <LI><A NAME="addlog"> + <STRONG>How do I add browsers and referrers to my logs?</STRONG> + </A> + <P> + Apache provides a couple of different ways of doing this. The + recommended method is to compile the + <A + HREF="../mod/mod_log_config.html" + ><SAMP>mod_log_config</SAMP></A> + module into your configuration and use the + <A + HREF="../mod/mod_log_config.html#customlog" + ><SAMP>CustomLog</SAMP></A> + directive. + </P> + <P> + You can either log the additional information in files other than your + normal transfer log, or you can add them to the records already being + written. For example: + </P> + <P> + <CODE> + CustomLog logs/access_log "%h %l %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-Agent}i\"" + </CODE> + </P> + <P> + This will add the values of the <SAMP>User-agent:</SAMP> and + <SAMP>Referer:</SAMP> headers, which indicate the client and the + referring page, respectively, to the end of each line in the access + log. + </P> + <P> + You may want to check out the <CITE>Apache Week</CITE> article + entitled: + "<A + HREF="http://www.apacheweek.com/features/logfiles" + REL="Help" + ><CITE>Gathering Visitor Information: Customising Your + Logfiles</CITE></A>". + </P> + <HR> + </LI> + <LI><A NAME="bind8.1"> + <STRONG>Why do I get an error about an undefined reference to + "<SAMP>__inet_ntoa</SAMP>" or other + <SAMP>__inet_*</SAMP> symbols?</STRONG> + </A> + <P> + If you have installed <A HREF="http://www.isc.org/bind.html">BIND-8</A> + then this is normally due to a conflict between your include files + and your libraries. BIND-8 installs its include files and libraries + <CODE>/usr/local/include/</CODE> and <CODE>/usr/local/lib/</CODE>, while + the resolver that comes with your system is probably installed in + <CODE>/usr/include/</CODE> and <CODE>/usr/lib/</CODE>. If + your system uses the header files in <CODE>/usr/local/include/</CODE> + before those in <CODE>/usr/include/</CODE> but you do not use the new + resolver library, then the two versions will conflict. + </P> + <P> + To resolve this, you can either make sure you use the include files + and libraries that came with your system or make sure to use the + new include files and libraries. Adding <CODE>-lbind</CODE> to the + <CODE>EXTRA_LDFLAGS</CODE> line in your <SAMP>Configuration</SAMP> + file, then re-running <SAMP>Configure</SAMP>, should resolve the + problem. (Apache versions 1.2.* and earlier use + <CODE>EXTRA_LFLAGS</CODE> instead.) + </P> + <P> + <STRONG>Note:</STRONG>As of BIND 8.1.1, the bind libraries and files are + installed under <SAMP>/usr/local/bind</SAMP> by default, so you + should not run into this problem. Should you want to use the bind + resolvers you'll have to add the following to the respective lines: + </P> + <P> + <DL> + <DD><CODE>EXTRA_CFLAGS=-I/usr/local/bind/include + <BR> + EXTRA_LDFLAGS=-L/usr/local/bind/lib + <BR> + EXTRA_LIBS=-lbind</CODE> + </DD> + </DL> + </P> + <HR> + </LI> + <LI><A NAME="set-servername"> + <STRONG>Why does accessing directories only work when I include + the trailing "/" + (<EM>e.g.</EM>, <SAMP>http://foo.domain.com/~user/</SAMP>) + but not when I omit it + (<EM>e.g.</EM>, <SAMP>http://foo.domain.com/~user</SAMP>)?</STRONG> + </A> + <P> + When you access a directory without a trailing "/", Apache needs + to send what is called a redirect to the client to tell it to + add the trailing slash. If it did not do so, relative URLs would + not work properly. When it sends the redirect, it needs to know + the name of the server so that it can include it in the redirect. + There are two ways for Apache to find this out; either it can guess, + or you can tell it. If your DNS is configured correctly, it can + normally guess without any problems. If it is not, however, then + you need to tell it. + </P> + <P> + Add a <A HREF="../mod/core.html#servername">ServerName</A> directive + to the config file to tell it what the domain name of the server is. + </P> + <HR> + </LI> + <LI><A NAME="user-authentication"> + <STRONG>How do I set up Apache to require a username and + password to access certain documents?</STRONG> + </A> + <P> + There are several ways to do this; some of the more popular + ones are to use the <A HREF="../mod/mod_auth.html">mod_auth</A>, + <A HREF="../mod/mod_auth_db.html">mod_auth_db</A>, or + <A HREF="../mod/mod_auth_dbm.html">mod_auth_dbm</A> modules. + </P> + <P> + For an explanation on how to implement these restrictions, see + <A + HREF="http://www.apacheweek.com/" + ><CITE>Apache Week</CITE></A>'s + articles on + <A + HREF="http://www.apacheweek.com/features/userauth" + ><CITE>Using User Authentication</CITE></A> + or + <A + HREF="http://www.apacheweek.com/features/dbmauth" + ><CITE>DBM User Authentication</CITE></A>. + </P> + <HR> + </LI> + <LI><A NAME="remote-user-var"> + <STRONG>Why is the environment variable + <SAMP>REMOTE_USER</SAMP> not set?</STRONG> + </A> + <P> + This variable is set and thus available in SSI or CGI scripts <STRONG>if and + only if</STRONG> the requested document was protected by access + authentication. For an explanation on how to implement these restrictions, + see + <A + HREF="http://www.apacheweek.com/" + ><CITE>Apache Week</CITE></A>'s + articles on + <A + HREF="http://www.apacheweek.com/features/userauth" + ><CITE>Using User Authentication</CITE></A> + or + <A + HREF="http://www.apacheweek.com/features/dbmauth" + ><CITE>DBM User Authentication</CITE></A>. + </P> + <P> + Hint: When using a CGI script to receive the data of a HTML <SAMP>FORM</SAMP> + notice that protecting the document containing the <SAMP>FORM</SAMP> is not + sufficient to provide <SAMP>REMOTE_USER</SAMP> to the CGI script. You have + to protect the CGI script, too. Or alternatively only the CGI script (then + authentication happens only after filling out the form). + </P> + <HR> + </LI> + <LI><A NAME="remote-auth-only"> + <STRONG>How do I set up Apache to allow access to certain + documents only if a site is either a local site <EM>or</EM> + the user supplies a password and username?</STRONG> + </A> + <P> + Use the <A HREF="../mod/core.html#satisfy">Satisfy</A> directive, + in particular the <CODE>Satisfy Any</CODE> directive, to require + that only one of the access restrictions be met. For example, + adding the following configuration to a <SAMP>.htaccess</SAMP> + or server configuration file would restrict access to people who + either are accessing the site from a host under domain.com or + who can supply a valid username and password: + </P> + <P> + <DL> + <DD><CODE>deny from all + <BR> + allow from .domain.com + <BR> + AuthType Basic + <BR> + AuthUserFile /usr/local/apache/conf/htpasswd.users + <BR> + AuthName special directory + <BR> + require valid-user + <BR> + satisfy any</CODE> + </DD> + </DL> + </P> + <P> + See the <A HREF="#user-authentication">user authentication</A> + question and the <A HREF="../mod/mod_access.html">mod_access</A> + module for details on how the above directives work. + </P> + <HR> + </LI> + <LI><A NAME="no-info-directives"> + <STRONG>Why doesn't mod_info list any directives?</STRONG> + </A> + <P> + The + <A + HREF="../mod/mod_info.html" + ><SAMP>mod_info</SAMP></A> + module allows you to use a Web browser to see how your server is + configured. Among the information it displays is the list modules and + their configuration directives. The "current" values for + the directives are not necessarily those of the running server; they + are extracted from the configuration files themselves at the time of + the request. If the files have been changed since the server was last + reloaded, the display will will not match the values actively in use. + If the files and the path to the files are not readable by the user as + which the server is running (see the + <A + HREF="../mod/core.html#user" + ><SAMP>User</SAMP></A> + directive), then <SAMP>mod_info</SAMP> cannot read them in order to + list their values. An entry <EM>will</EM> be made in the error log in + this event, however. + </P> + <HR> + </LI> + <LI><A NAME="linux-shmget"> + <STRONG>When I run it under Linux I get "shmget: + function not found", what should I do?</STRONG> + </A> + <P> + Your kernel has been built without SysV IPC support. You will have to + rebuild the kernel with that support enabled (it's under the + "General Setup" submenu). Documentation for + kernel building is beyond the scope of this FAQ; you should consult + the + <A HREF="http://www.linuxhq.com/HOWTO/Kernel-HOWTO.html" + >Kernel HOWTO</A>, + or the documentation provided with your distribution, or a + <A HREF="http://www.linuxhq.com/HOWTO/META-FAQ.html" + >Linux newsgroup/mailing list</A>. + As a last-resort workaround, you can + comment out the <CODE>#define USE_SHMGET_SCOREBOARD</CODE> + definition in the + <SAMP>LINUX</SAMP> section of + <SAMP>src/conf.h</SAMP> and rebuild the server (prior to 1.3b4, simply + removing <CODE>#define HAVE_SHMGET</CODE> would have sufficed). + This will produce a server which is slower and less reliable. + </P> + <HR> + </LI> + <LI><A NAME="authauthoritative"> + <STRONG>Why does my authentication give me a server error?</STRONG> + </A> + <P> + Under normal circumstances, the Apache access control modules will + pass unrecognized user IDs on to the next access control module in + line. Only if the user ID is recognized and the password is validated + (or not) will it give the usual success or "authentication + failed" messages. + </P> + <P> + However, if the last access module in line 'declines' the validation + request (because it has never heard of the user ID or because it is not + configured), the <SAMP>http_request</SAMP> handler will give one of + the following, confusing, errors: + </P> + <UL> + <LI><SAMP>check access</SAMP> + </LI> + <LI><SAMP>check user. No user file?</SAMP> + </LI> + <LI><SAMP>check access. No groups file?</SAMP> + </LI> + </UL> + <P> + This does <EM>not</EM> mean that you have to add an + '<SAMP>AuthUserFile /dev/null</SAMP>' line as some magazines suggest! + </P> + <P> + The solution is to ensure that at least the last module is authoritative + and <STRONG>CONFIGURED</STRONG>. By default, <SAMP>mod_auth</SAMP> is + authoritative and will give an OK/Denied, but only if it is configured + with the proper <SAMP>AuthUserFile</SAMP>. Likewise, if a valid group + is required. (Remember that the modules are processed in the reverse + order from that in which they appear in your compile-time + <SAMP>Configuration</SAMP> file.) + </P> + <P> + A typical situation for this error is when you are using the + <SAMP>mod_auth_dbm</SAMP>, <SAMP>mod_auth_msql</SAMP>, + <SAMP>mod_auth_mysql</SAMP>, <SAMP>mod_auth_anon</SAMP> or + <SAMP>mod_auth_cookie</SAMP> modules on their own. These are by + default <STRONG>not</STRONG> authoritative, and this will pass the + buck on to the (non-existent) next authentication module when the + user ID is not in their respective database. Just add the appropriate + '<SAMP><EM>XXX</EM>Authoritative yes</SAMP>' line to the configuration. + </P> + <P> + In general it is a good idea (though not terribly efficient) to have the + file-based <SAMP>mod_auth</SAMP> a module of last resort. This allows + you to access the web server with a few special passwords even if the + databases are down or corrupted. This does cost a + file open/seek/close for each request in a protected area. + </P> + <HR> + </LI> + <LI><A NAME="auth-on-same-machine"> + <STRONG>Do I have to keep the (mSQL) authentication information + on the same machine?</STRONG> + </A> + <P> + Some organizations feel very strongly about keeping the authentication + information on a different machine than the webserver. With the + <SAMP>mod_auth_msql</SAMP>, <SAMP>mod_auth_mysql</SAMP>, and other SQL + modules connecting to (R)DBMses this is quite possible. Just configure + an explicit host to contact. + </P> + <P> + Be aware that with mSQL and Oracle, opening and closing these database + connections is very expensive and time consuming. You might want to + look at the code in the <SAMP>auth_*</SAMP> modules and play with the + compile time flags to alleviate this somewhat, if your RDBMS licences + allow for it. + </P> + <HR> + </LI> + <LI><A NAME="msql-slow"> + <STRONG>Why is my mSQL authentication terribly slow?</STRONG> + </A> + <P> + You have probably configured the Host by specifying a FQHN, + and thus the <SAMP>libmsql</SAMP> will use a full blown TCP/IP socket + to talk to the database, rather than a fast internal device. The + <SAMP>libmsql</SAMP>, the mSQL FAQ, and the <SAMP>mod_auth_msql</SAMP> + documentation warn you about this. If you have to use different + hosts, check out the <SAMP>mod_auth_msql</SAMP> code for + some compile time flags which might - or might not - suit you. + </P> + <HR> + </LI> + <LI><A NAME="rewrite-more-config"> + <STRONG>Where can I find mod_rewrite rulesets which already solve + particular URL-related problems?</STRONG> + </A> + <P> + There is a collection of + <A + HREF="http://www.engelschall.com/pw/apache/rewriteguide/" + >Practical Solutions for URL-Manipulation</A> + where you can + find all typical solutions the author of + <A + HREF="../mod/mod_rewrite.html" + ><SAMP>mod_rewrite</SAMP></A> + currently knows of. If you have more + interesting rulesets which solve particular problems not currently covered in + this document, send it to + <A + HREF="mailto:rse@apache.org" + >Ralf S. Engelschall</A> + for inclusion. The + other webmasters will thank you for avoiding the reinvention of the wheel. + </P> + <HR> + </LI> + <LI><A NAME="rewrite-article"> + <STRONG>Where can I find any published information about URL-manipulations and + mod_rewrite?</STRONG> + </A> + <P> + There is an article from + <A + HREF="mailto:rse@apache.org" + >Ralf S. Engelschall</A> + about URL-manipulations based on + <A + HREF="../mod/mod_rewrite.html" + ><SAMP>mod_rewrite</SAMP></A> + in the "iX Multiuser Multitasking Magazin" issue #12/96. The + german (original) version + can be read online at + <A + HREF="http://www.heise.de/ix/artikel/9612149/" + >http://www.heise.de/ix/artikel/9612149/</A>, + the English (translated) version can be found at + <A + HREF="http://www.heise.de/ix/artikel/E/9612149/" + >http://www.heise.de/ix/artikel/E/9612149/</A>. + </P> + <HR> + </LI> + <LI><A NAME="rewrite-complexity"> + <STRONG>Why is mod_rewrite so difficult to learn and seems so + complicated?</STRONG> + </A> + <P> + Hmmm... there are a lot of reasons. First, mod_rewrite itself is a powerful + module which can help you in really <STRONG>all</STRONG> aspects of URL rewriting, so + it can be no trivial module per definition. To accomplish its hard job it + uses software leverage and makes use of a powerful regular expression + library by Henry Spencer which is an integral part of Apache since its + version 1.2. And regular expressions itself can be difficult to newbies, + while providing the most flexible power to the advanced hacker. + </P> + <P> + On the other hand mod_rewrite has to work inside the Apache API environment + and needs to do some tricks to fit there. For instance the Apache API as of + 1.x really was not designed for URL rewriting at the <TT>.htaccess</TT> + level of processing. Or the problem of multiple rewrites in sequence, which + is also not handled by the API per design. To provide this features + mod_rewrite has to do some special (but API compliant!) handling which leads + to difficult processing inside the Apache kernel. While the user usually + doesn't see anything of this processing, it can be difficult to find + problems when some of your RewriteRules seem not to work. + </P> + <HR> + </LI> + <LI><A NAME="rewrite-dontwork"> + <STRONG>What can I do if my RewriteRules don't work as expected? + </STRONG> + </A> + <P> + Use "<SAMP>RewriteLog somefile</SAMP>" and + "<SAMP>RewriteLogLevel 9</SAMP>" and have a precise look at the + steps the rewriting engine performs. This is really the only one and best + way to debug your rewriting configuration. + </P> + <HR> + </LI> + <LI><A NAME="rewrite-prefixdocroot"><STRONG>Why don't some of my URLs + get prefixed with DocumentRoot when using mod_rewrite?</STRONG> + </A> + <P> + If the rule starts with <SAMP>/somedir/...</SAMP> make sure that really no + <SAMP>/somedir</SAMP> exists on the filesystem if you don't want to lead the + URL to match this directory, i.e. there must be no root directory named + <SAMP>somedir</SAMP> on the filesystem. Because if there is such a + directory, the URL will not get prefixed with DocumentRoot. This behaviour + looks ugly, but is really important for some other aspects of URL + rewriting. + </P> + <HR> + </LI> + <LI><A NAME="rewrite-nocase"> + <STRONG>How can I make all my URLs case-insensitive with mod_rewrite? + </STRONG> + </A> + <P> + You can't! The reason is: First, case translations for arbitrary length URLs + cannot be done <EM>via</EM> regex patterns and corresponding substitutions. + One need + a per-character pattern like sed/Perl <SAMP>tr|..|..|</SAMP> feature. + Second, just + making URLs always upper or lower case will not resolve the complete problem + of case-INSENSITIVE URLs, because actually the URLs had to be rewritten to + the correct case-variant residing on the filesystem because in later + processing Apache needs to access the file. And Unix filesystem is always + case-SENSITIVE. + </P> + <P> + But there is a module named <CODE>mod_speling.c</CODE> (yes, it is named + this way!) out there on the net. Try this one. + </P> + <HR> + </LI> + <LI><A NAME="rewrite-virthost"> + <STRONG> Why are RewriteRules in my VirtualHost parts ignored? + </STRONG> + </A> + <P> + Because you have to enable the engine for every virtual host explicitly due + to security concerns. Just add a "RewriteEngine on" to your + virtual host configuration parts. + </P> + <HR> + </LI> + <LI><A NAME="rewrite-envwhitespace"> + <STRONG> How can I use strings with whitespaces in RewriteRule's ENV + flag?</STRONG> + </A> + <P> + There is only one ugly solution: You have to surround the complete flag + argument by quotation marks (<SAMP>"[E=...]"</SAMP>). Notice: The argument + to quote here is not the argument to the E-flag, it is the argument of the + Apache config file parser, i.e. the third argument of the RewriteRule here. + So you have to write <SAMP>"[E=any text with whitespaces]"</SAMP>. + </P> + <HR> + </LI> + <LI><A NAME="cgi-spec"><STRONG>Where can I find the "CGI + specification"?</STRONG></A> + <P> + The Common Gateway Interface (CGI) specification can be found at + the original NCSA site + <<A HREF="http://hoohoo.ncsa.uiuc.edu/cgi/interface.html"> + <SAMP>http://hoohoo.ncsa.uiuc.edu/cgi/interface.html</SAMP></A>>. + This version hasn't been updated since 1995, and there have been + some efforts to update it. + </P> + <HR> + </LI> + <LI><A NAME="year2000"> + <STRONG>Is Apache Year 2000 compliant?</STRONG> + </A> + <P> + Yes, Apache is Year 2000 compliant. + </P> + <P> + Apache internally never stores years as two digits. + On the HTTP protocol level RFC1123-style addresses are generated + which is the only format a HTTP/1.1-compliant server should + generate. To be compatible with older applications Apache + recognizes ANSI C's <CODE>asctime()</CODE> and + RFC850-/RFC1036-style date formats, too. + The <CODE>asctime()</CODE> format uses four-digit years, + but the RFC850 and RFC1036 date formats only define a two-digit year. + If Apache sees such a date with a value less than 70 it assumes that + the century is <SAMP>20</SAMP> rather than <SAMP>19</SAMP>. + </P> + <P> + Some aspects of Apache's output may use two-digit years, such as the + automatic listing of directory contents provided by + <A + HREF="../mod/mod_autoindex.html" + ><SAMP>mod_autoindex</SAMP></A> + with the + <A + HREF="../mod/mod_autoindex.html#indexoptions" + ><SAMP>FancyIndexing</SAMP></A> + option enabled, but it is improper to depend upon such displays for + specific syntax. And even that issue is being addressed by the + developers; a future version of Apache should allow you to format that + display as you like. + </P> + <P> + Although Apache is Year 2000 compliant, you may still get problems + if the underlying OS has problems with dates past year 2000 + (<EM>e.g.</EM>, OS calls which accept or return year numbers). + Most (UNIX) systems store dates internally as signed 32-bit integers + which contain the number of seconds since 1<SUP>st</SUP> January 1970, so + the magic boundary to worry about is the year 2038 and not 2000. + But modern operating systems shouldn't cause any trouble + at all. + </P> + <HR> + </LI> + <LI><A NAME="namevhost"> + <STRONG>I upgraded to Apache 1.3b and now my virtual hosts don't + work!</STRONG> + </A> + <P> + In versions of Apache prior to 1.3b2, there was a lot of confusion + regarding address-based virtual hosts and (HTTP/1.1) name-based + virtual hosts, and the rules concerning how the server processed + <SAMP><VirtualHost></SAMP> definitions were very complex and not + well documented. + </P> + <P> + Apache 1.3b2 introduced a new directive, + <A + HREF="http://www.apache.org/docs/mod/core.html#namevirtualhost" + ><SAMP>NameVirtualHost</SAMP></A>, + which simplifies the rules quite a bit. However, changing the rules + like this means that your existing name-based + <SAMP><VirtualHost></SAMP> containers probably won't work + correctly immediately following the upgrade. + </P> + <P> + To correct this problem, add the following line to the beginning of + your server configuration file, before defining any virtual hosts: + </P> + <DL> + <DD><CODE>NameVirtualHost <EM>n.n.n.n</EM></CODE> + </DD> + </DL> + <P> + Replace the "<SAMP>n.n.n.n</SAMP>" with the IP address to + which the name-based virtual host names resolve; if you have multiple + name-based hosts on multiple addresses, repeat the directive for each + address. + </P> + <P> + Make sure that your name-based <SAMP><VirtualHost></SAMP> blocks + contain <SAMP>ServerName</SAMP> and possibly <SAMP>ServerAlias</SAMP> + directives so Apache can be sure to tell them apart correctly. + </P> + <P> + Please see the + <A HREF="http://www.apache.org/docs/vhosts/">Apache + Virtual Host documentation</A> for further details about configuration. + </P> + <HR> + </LI> + + <li><a name="redhat"><strong>I'm using RedHat Linux and I have problems with httpd + dying randomly or not restarting properly</strong></a> + + <p>RedHat Linux versions 4.x (and possibly earlier) rpms contain + various nasty scripts which do not stop or restart Apache properly. + These can affect you even if you're not running the RedHat supplied + rpms. + + <p> If you're using the default install then you're probably running + Apache 1.1.3, which is outdated. From RedHat's ftp site you can + pick up a more recent RPM for Apache 1.2.x. This will solve one of + the problems. + + <p> If you're using a custom built Apache rather than the RedHat rpms + then you should <code>rpm -e apache</code>. In particular you want + the mildly broken <code>/etc/logrotate.d/apache</code> script to be + removed, and you want the broken <code>/etc/rc.d/init.d/httpd</code> + (or <code>httpd.init</code>) script to be removed. The latter is + actually fixed by the apache-1.2.5 rpms but if you're building your + own Apache then you probably don't want the RedHat files. + + <p>We can't stress enough how important it is for folks, <i>especially + vendors</i> to follow the <a href="../stopping.html">stopping Apache + directions</a> given in our documentation. In RedHat's defense, + the broken scripts were necessary with Apache 1.1.x because the + Linux support in 1.1.x was very poor, and there were various race + conditions on all platforms. None of this should be necessary with + Apache 1.2 and later. + </p> + <hr> + </li> + + <li><a name="stopping"><strong>I upgraded from an Apache version earlier + than 1.2.0 and suddenly I have problems with Apache dying randomly + or not restarting properly</strong></a> + + <p>You should read <a href="#redhat">the previous note</a> about + problems with RedHat installations. It is entirely likely that your + installation has start/stop/restart scripts which were built for + an earlier version of Apache. Versions earlier than 1.2.0 had + various race conditions that made it necessary to use + <code>kill -9</code> at times to take out all the httpd servers. + But that should not be necessary any longer. You should follow + the <a href="../stopping.html">directions on how to stop + and restart Apache</a>. + + <p>As of Apache 1.3 there is a script + <code>src/support/apachectl</code> which, after a bit of + customization, is suitable for starting, stopping, and restarting + your server. + </p> + <hr> + + </li> + + <li><a name="redhat-htm"><strong>I'm using RedHat Linux and my .htm files are showing + up as html source rather than being formatted!</strong></a> + + <p>RedHat messed up and forgot to put a content type for <code>.htm</code> + files into <code>/etc/mime.types</code>. Edit <code>/etc/mime.types</code>, + find the line containing <code>html</code> and add <code>htm</code> to it. + Then restart your httpd server: + <pre> + kill -HUP `cat /var/run/httpd.pid` + </pre> + Then <b>clear your browsers' caches</b>. (Many browsers won't re-examine + the content type after they've reloaded a page.) + </p> + <hr> + + <li><a name="glibc-crypt"><strong>I'm using RedHat Linux 5.0, or some other glibc + based Linux system, and I get errors with the <code>crypt</code> function when + I attempt to build Apache 1.2.</strong></a> + + <p>glibc puts the crypt function into a separate library. Edit your + <code>src/Configuration</code> file and set this: + <pre> + EXTRA_LIBS=-lcrypt + </pre> + </p> + <hr> + + <!-- Don't forget to add HR tags at the end of each list item.. --> + +</OL> + <HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/misc/client_block_api.html b/usr.sbin/httpd/htdocs/manual/misc/client_block_api.html new file mode 100644 index 00000000000..1d416586a6b --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/misc/client_block_api.html @@ -0,0 +1,99 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Reading Client Input in Apache 1.2</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Reading Client Input in Apache 1.2</h1> + +<hr> + +<p>Apache 1.1 and earlier let modules handle POST and PUT requests by +themselves. The module would, on its own, determine whether the +request had an entity, how many bytes it was, and then called a +function (<code>read_client_block</code>) to get the data. + +<p>However, HTTP/1.1 requires several things of POST and PUT request +handlers that did not fit into this module, and all existing modules +have to be rewritten. The API calls for handling this have been +further abstracted, so that future HTTP protocol changes can be +accomplished while remaining backwards-compatible.</p> + +<hr> + +<h3>The New API Functions</h3> + +<pre> + int setup_client_block (request_rec *, int read_policy); + int should_client_block (request_rec *); + long get_client_block (request_rec *, char *buffer, int buffer_size); +</pre> + +<ol> +<li>Call <code>setup_client_block()</code> near the beginning of the request + handler. This will set up all the necessary properties, and + will return either OK, or an error code. If the latter, + the module should return that error code. The second parameter + selects the policy to apply if the request message indicates a + body, and how a chunked + transfer-coding should be interpreted. Choose one of +<pre> + REQUEST_NO_BODY Send 413 error if message has any body + REQUEST_CHUNKED_ERROR Send 411 error if body without Content-Length + REQUEST_CHUNKED_DECHUNK If chunked, remove the chunks for me. + REQUEST_CHUNKED_PASS Pass the chunks to me without removal. +</pre> + In order to use the last two options, the caller MUST provide a buffer + large enough to hold a chunk-size line, including any extensions. + + + +<li>When you are ready to possibly accept input, call + <code>should_client_block()</code>. + This will tell the module whether or not to read input. If it is 0, + the module should assume that the input is of a non-entity type + (e.g. a GET request). A nonzero response indicates that the module + should proceed (to step 3). + This step also sends a 100 Continue response + to HTTP/1.1 clients, so should not be called until the module + is <strong>*definitely*</strong> ready to read content. (otherwise, the point of the + 100 response is defeated). Never call this function more than once. + +<li>Finally, call <code>get_client_block</code> in a loop. Pass it a + buffer and its + size. It will put data into the buffer (not necessarily the full + buffer, in the case of chunked inputs), and return the length of + the input block. When it is done reading, it will + return 0 if EOF, or -1 if there was an error. + +</ol> + +<p>As an example, please look at the code in +<code>mod_cgi.c</code>. This is properly written to the new API +guidelines.</p> + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/misc/compat_notes.html b/usr.sbin/httpd/htdocs/manual/misc/compat_notes.html new file mode 100644 index 00000000000..b6594d354e6 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/misc/compat_notes.html @@ -0,0 +1,149 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML><HEAD> +<TITLE>Apache HTTP Server: Compatibility Notes with NCSA's Server</TITLE> +</HEAD> +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Compatibility Notes with NCSA's Server</H1> + +<HR> + +While Apache 0.8.x and beyond are for the most part a drop-in +replacement for NCSA's httpd and earlier versions of Apache, there are +a couple gotcha's to watch out for. These are mostly due to the fact +that the parser for config and access control files was rewritten from +scratch, so certain liberties the earlier servers took may not be +available here. These are all easily fixable. If you know of other +non-fatal problems that belong here, <a +href="http://www.apache.org/bugdb.cgi">let us know.</a> + +<P>Please also check the <A HREF="known_bugs.html">known bugs</A> page. + + + +<OL> + +<LI>The basic mod_auth <CODE>AuthGroupFile</CODE>-specified group file + format allows commas between user names - Apache does not.<BR> + <I>- added 12/1/96</I> + <p> + + <LI><P>If you follow the NCSA guidelines for setting up access restrictions + based on client domain, you may well have added entries for, + <CODE>AuthType, AuthName, AuthUserFile</CODE> or <CODE>AuthGroupFile</CODE>. + <B>None</B> of these are needed (or appropriate) for restricting access + based on client domain. + + <P>When Apache sees <CODE>AuthType</CODE> it (reasonably) assumes you + are using some authorization type based on username and password. + + <P>Please remove <CODE>AuthType</CODE>, it's unnecessary even for NCSA. + + <P> + + <LI><CODE>AuthUserFile</CODE> requires a full pathname. In earlier + versions of NCSA httpd and Apache, you could use a filename + relative to the .htaccess file. This could be a major security hole, + as it made it trivially easy to make a ".htpass" file in the a + directory easily accessible by the world. We recommend you store + your passwords outside your document tree. + + <P> + + <LI><CODE>OldScriptAlias</CODE> is no longer supported. + + <P> + + <LI><CODE>exec cgi=""</CODE> produces reasonable <B>malformed header</B> + responses when used to invoke non-CGI scripts.<BR> + The NCSA code ignores the missing header. (bad idea)<BR> + Solution: write CGI to the CGI spec or use <CODE>exec cmd=""</CODE> instead. + <P>We might add <CODE>virtual</CODE> support to <CODE>exec cmd</CODE> to + make up for this difference. + + <P> + + <LI><Limit> silliness - in the old Apache 0.6.5, a + directive of <Limit GET> would also restrict POST methods - Apache 0.8.8's new + core is correct in not presuming a limit on a GET is the same limit on a POST, + so if you are relying on that behavior you need to change your access configurations + to reflect that. + + <P> + + <LI>Icons for FancyIndexing broken - well, no, they're not broken, + we've just upgraded the + icons from flat .xbm files to pretty and much smaller .gif files, courtesy of +<a href="mailto:kevinh@eit.com">Kevin Hughes</a> at +<a href="http://www.eit.com/">EIT</a>. + If you are using the same srm.conf from an old distribution, make sure + you add the new + <A + HREF="../mod/mod_dir.html#addicon" + >AddIcon</A>, + <A + HREF="../mod/mod_dir.html#addiconbytype" + >AddIconByType</A>, + and + <A + HREF="../mod/mod_dir.html#defaulticon" + >DefaultIcon</A> + directives. + + <P> + + <LI>Under IRIX, the "Group" directive in httpd.conf needs to be a + valid group name + (<EM>i.e.</EM>, "nogroup") not the numeric group ID. The distribution + httpd.conf, and earlier ones, had the default Group be "#-1", which + was causing silent exits at startup.<p> + +<li><code>.asis</code> files: Apache 0.6.5 did not require a Status header; +it added one automatically if the .asis file contained a Location header. +0.8.14 requires a Status header. <p> + + <P> + <LI>Apache versions before 1.2b1 will ignore the last line of configuration + files if the last line does not have a trailing newline. This affects + configuration files (httpd.conf, access.conf and srm.conf), and + htpasswd and htgroup files. + </LI> + + <LI>Apache does not permit commas delimiting the methods in <Limit>. + + <LI>Apache's <CODE><VirtualHost></CODE> treats all addresses as + "optional" (i.e. the server should continue booting if it can't resolve + the address). Whereas in NCSA the default is to fail booting unless + an added <code>optional</code> keyword is included. + + <LI>Apache does not implement <CODE>OnDeny</CODE> use + <a href="../mod/core.html#errordocument"><code>ErrorDocument</code></a> + instead. + +</OL> + +More to come when we notice them.... + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/misc/descriptors.html b/usr.sbin/httpd/htdocs/manual/misc/descriptors.html new file mode 100644 index 00000000000..5207eee0fbd --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/misc/descriptors.html @@ -0,0 +1,168 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Descriptors and Apache</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Descriptors and Apache</H1> + +<p>A <EM>descriptor</EM>, also commonly called a <EM>file handle</EM> is +an object that a program uses to read or write an open file, or open +network socket, or a variety of other devices. It is represented +by an integer, and you may be familiar with <code>stdin</code>, +<code>stdout</code>, and <code>stderr</code> which are descriptors 0, +1, and 2 respectively. +Apache needs a descriptor for each log file, plus one for each +network socket that it listens on, plus a handful of others. Libraries +that Apache uses may also require descriptors. Normal programs don't +open up many descriptors at all, and so there are some latent problems +that you may experience should you start running Apache with many +descriptors (i.e. with many virtual hosts). + +<p>The operating system enforces a limit on the number of descriptors +that a program can have open at a time. There are typically three limits +involved here. One is a kernel limitation, depending on your operating +system you will either be able to tune the number of descriptors available +to higher numbers (this is frequently called <EM>FD_SETSIZE</EM>). Or you +may be stuck with a (relatively) low amount. The second limit is called +the <EM>hard resource</EM> limit, and it is sometimes set by root in an +obscure operating system file, but frequently is the same as the kernel +limit. The third limit is called the <EM>soft +resource</EM> limit. The soft limit is always less than or equal to +the hard limit. For example, the hard limit may be 1024, but the soft +limit only 64. Any user can raise their soft limit up to the hard limit. +Root can raise the hard limit up to the system maximum limit. The soft +limit is the actual limit that is used when enforcing the maximum number +of files a process can have open. + +<p>To summarize: + +<center><pre> + #open files <= soft limit <= hard limit <= kernel limit +</pre></center> + +<p>You control the hard and soft limits using the <code>limit</code> (csh) +or <code>ulimit</code> (sh) directives. See the respective man pages +for more information. For example you can probably use +<code>ulimit -n unlimited</code> to raise your soft limit up to the +hard limit. You should include this command in a shell script which +starts your webserver. + +<p>Unfortunately, it's not always this simple. As mentioned above, +you will probably run into some system limitations that will need to be +worked around somehow. Work was done in version 1.2.1 to improve the +situation somewhat. Here is a partial list of systems and workarounds +(assuming you are using 1.2.1 or later): + +<dl> + + <dt><STRONG>BSDI 2.0</STRONG> + <dd>Under BSDI 2.0 you can build Apache to support more descriptors + by adding <code>-DFD_SETSIZE=nnn</code> to + <code>EXTRA_CFLAGS</code> (where nnn is the number of descriptors + you wish to support, keep it less than the hard limit). But it + will run into trouble if more than approximately 240 Listen + directives are used. This may be cured by rebuilding your kernel + with a higher FD_SETSIZE. + <p> + + <dt><STRONG>FreeBSD 2.2, BSDI 2.1+</STRONG> + <dd>Similar to the BSDI 2.0 case, you should define + <code>FD_SETSIZE</code> and rebuild. But the extra + Listen limitation doesn't exist. + <p> + + <dt><STRONG>Linux</STRONG> + <dd>By default Linux has a kernel maximum of 256 open descriptors + per process. There are several patches available for the + 2.0.x series which raise this to 1024 and beyond, and you + can find them in the "unofficial patches" section of <a + href="http://www.linuxhq.com/">the Linux Information HQ</a>. + None of these patches are perfect, and an entirely different + approach is likely to be taken during the 2.1.x development. + Applying these patches will raise the FD_SETSIZE used to compile + all programs, and unless you rebuild all your libraries you should + avoid running any other program with a soft descriptor limit above + 256. As of this writing the patches available for increasing + the number of descriptors do not take this into account. On a + dedicated webserver you probably won't run into trouble. + <p> + + <dt><STRONG>Solaris through 2.5.1</STRONG> + <dd>Solaris has a kernel hard limit of 1024 (may be lower in earlier + versions). But it has a limitation that files using + the stdio library cannot have a descriptor above 255. + Apache uses the stdio library for the ErrorLog directive. + When you have more than approximately 110 virtual hosts + (with an error log and an access log each) you will need to + build Apache with <code>-DHIGH_SLACK_LINE=256</code> added to + <code>EXTRA_CFLAGS</code>. You will be limited to approximately + 240 error logs if you do this. + <p> + + <dt><STRONG>AIX</STRONG> + <dd>AIX version 3.2?? appears to have a hard limit of 128 descriptors. + End of story. Version 4.1.5 has a hard limit of 2000. + <p> + + <dt><STRONG>Others</STRONG> + <dd>If you have details on another operating system, please submit + it through our <a href="http://www.apache.org/bug_report.html">Bug + Report Page</a>. + <p> + +</dl> + +<p>In addition to the problems described above there are problems with +many libraries that Apache uses. The most common example is the bind +DNS resolver library that is used by pretty much every unix, which +fails if it ends up with a descriptor above 256. We suspect there +are other libraries that similar limitations. So the code as of 1.2.1 +takes a defensive stance and tries to save descriptors less than 16 +for use while processing each request. This is called the <EM>low +slack line</EM>. + +<p>Note that this shouldn't waste descriptors. If you really are pushing +the limits and Apache can't get a descriptor above 16 when it wants +it, it will settle for one below 16. + +<p>In extreme situations you may want to lower the low slack line, +but you shouldn't ever need to. For example, lowering it can +increase the limits 240 described above under Solaris and BSDI 2.0. +But you'll play a delicate balancing game with the descriptors needed +to serve a request. Should you want to play this game, the compile +time parameter is <code>LOW_SLACK_LINE</code> and there's a tiny +bit of documentation in the header file <code>httpd.h</code>. + +<p>Finally, if you suspect that all this slack stuff is causing you +problems, you can disable it. Add <code>-DNO_SLACK</code> to +<code>EXTRA_CFLAGS</code> and rebuild. But please report it to +our <a href="http://www.apache.org/bug_report.html">Bug +Report Page</a> so that +we can investigate. + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/misc/fin_wait_2.html b/usr.sbin/httpd/htdocs/manual/misc/fin_wait_2.html new file mode 100644 index 00000000000..e4c4f5a1ad9 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/misc/fin_wait_2.html @@ -0,0 +1,340 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Connections in FIN_WAIT_2 and Apache</TITLE> +<LINK REV="made" HREF="mailto:marc@apache.org"> + +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + + +<H1 ALIGN="CENTER">Connections in the FIN_WAIT_2 state and Apache</H1> +<OL> +<LI><H2>What is the FIN_WAIT_2 state?</H2> +Starting with the Apache 1.2 betas, people are reporting many more +connections in the FIN_WAIT_2 state (as reported by +<code>netstat</code>) than they saw using older versions. When the +server closes a TCP connection, it sends a packet with the FIN bit +sent to the client, which then responds with a packet with the ACK bit +set. The client then sends a packet with the FIN bit set to the +server, which responds with an ACK and the connection is closed. The +state that the connection is in during the period between when the +server gets the ACK from the client and the server gets the FIN from +the client is known as FIN_WAIT_2. See the <A +HREF="ftp://ds.internic.net/rfc/rfc793.txt">TCP RFC</A> for the +technical details of the state transitions.<P> + +The FIN_WAIT_2 state is somewhat unusual in that there is no timeout +defined in the standard for it. This means that on many operating +systems, a connection in the FIN_WAIT_2 state will stay around until +the system is rebooted. If the system does not have a timeout and +too many FIN_WAIT_2 connections build up, it can fill up the space +allocated for storing information about the connections and crash +the kernel. The connections in FIN_WAIT_2 do not tie up an httpd +process.<P> + +<LI><H2>But why does it happen?</H2> + +There are several reasons for it happening, and not all of them are +fully understood by the Apache team yet. What is known follows.<P> + +<H3>Buggy clients and persistent connections</H3> + +Several clients have a bug which pops up when dealing with +<A HREF="../keepalive.html">persistent connections</A> (aka keepalives). +When the connection is idle and the server closes the connection +(based on the <A HREF="../mod/core.html#keepalivetimeout"> +KeepAliveTimeout</A>), the client is programmed so that the client does +not send back a FIN and ACK to the server. This means that the +connection stays in the FIN_WAIT_2 state until one of the following +happens:<P> +<UL> + <LI>The client opens a new connection to the same or a different + site, which causes it to fully close the older connection on + that socket. + <LI>The user exits the client, which on some (most?) clients + causes the OS to fully shutdown the connection. + <LI>The FIN_WAIT_2 times out, on servers that have a timeout + for this state. +</UL><P> +If you are lucky, this means that the buggy client will fully close the +connection and release the resources on your server. However, there +are some cases where the socket is never fully closed, such as a dialup +client disconnecting from their provider before closing the client. +In addition, a client might sit idle for days without making another +connection, and thus may hold its end of the socket open for days +even though it has no further use for it. +<STRONG>This is a bug in the browser or in its operating system's +TCP implementation.</STRONG> <P> + +The clients on which this problem has been verified to exist:<P> +<UL> + <LI>Mozilla/3.01 (X11; I; FreeBSD 2.1.5-RELEASE i386) + <LI>Mozilla/2.02 (X11; I; FreeBSD 2.1.5-RELEASE i386) + <LI>Mozilla/3.01Gold (X11; I; SunOS 5.5 sun4m) + <LI>MSIE 3.01 on the Macintosh + <LI>MSIE 3.01 on Windows 95 +</UL><P> + +This does not appear to be a problem on: +<UL> + <LI>Mozilla/3.01 (Win95; I) +</UL> +<P> + +It is expected that many other clients have the same problem. What a +client <STRONG>should do</STRONG> is periodically check its open +socket(s) to see if they have been closed by the server, and close their +side of the connection if the server has closed. This check need only +occur once every few seconds, and may even be detected by a OS signal +on some systems (e.g., Win95 and NT clients have this capability, but +they seem to be ignoring it).<P> + +Apache <STRONG>cannot</STRONG> avoid these FIN_WAIT_2 states unless it +disables persistent connections for the buggy clients, just +like we recommend doing for Navigator 2.x clients due to other bugs. +However, non-persistent connections increase the total number of +connections needed per client and slow retrieval of an image-laden +web page. Since non-persistent connections have their own resource +consumptions and a short waiting period after each closure, a busy server +may need persistence in order to best serve its clients.<P> + +As far as we know, the client-caused FIN_WAIT_2 problem is present for +all servers that support persistent connections, including Apache 1.1.x +and 1.2.<P> + +<H3>Something in Apache may be broken</H3> + +While the above bug is a problem, it is not the whole problem. +Some users have observed no FIN_WAIT_2 problems with Apache 1.1.x, +but with 1.2b enough connections build up in the FIN_WAIT_2 state to +crash their server. We have not yet identified why this would occur +and welcome additional test input.<P> + +One possible (and most likely) source for additional FIN_WAIT_2 states +is a function called <CODE>lingering_close()</CODE> which was added +between 1.1 and 1.2. This function is necessary for the proper +handling of persistent connections and any request which includes +content in the message body (e.g., PUTs and POSTs). +What it does is read any data sent by the client for +a certain time after the server closes the connection. The exact +reasons for doing this are somewhat complicated, but involve what +happens if the client is making a request at the same time the +server sends a response and closes the connection. Without lingering, +the client might be forced to reset its TCP input buffer before it +has a chance to read the server's response, and thus understand why +the connection has closed. +See the <A HREF="#appendix">appendix</A> for more details.<P> + +We have not yet tracked down the exact reason why +<CODE>lingering_close()</CODE> causes problems. Its code has been +thoroughly reviewed and extensively updated in 1.2b6. It is possible +that there is some problem in the BSD TCP stack which is causing the +observed problems. It is also possible that we fixed it in 1.2b6. +Unfortunately, we have not been able to replicate the problem on our +test servers.<P> + +<H2><LI>What can I do about it?</H2> + +There are several possible workarounds to the problem, some of +which work better than others.<P> + +<H3>Add a timeout for FIN_WAIT_2</H3> + +The obvious workaround is to simply have a timeout for the FIN_WAIT_2 state. +This is not specified by the RFC, and could be claimed to be a +violation of the RFC, but it is widely recognized as being necessary. +The following systems are known to have a timeout: +<P> +<UL> + <LI><A HREF="http://www.freebsd.org/">FreeBSD</A> versions starting at 2.0 or possibly earlier. + <LI><A HREF="http://www.netbsd.org/">NetBSD</A> version 1.2(?) + <LI><A HREF="http://www.openbsd.org/">OpenBSD</A> all versions(?) + <LI><A HREF="http://www.bsdi.com/">BSD/OS</A> 2.1, with the + <A HREF="ftp://ftp.bsdi.com/bsdi/patches/patches-2.1/K210-027"> + K210-027</A> patch installed. + <LI><A HREF="http://www.sun.com/">Solaris</A> as of around version + 2.2. The timeout can be tuned by using <CODE>ndd</CODE> to + modify <CODE>tcp_fin_wait_2_flush_interval</CODE>, but the + default should be appropriate for most servers and improper + tuning can have negative impacts. + <LI><A HREF="http://www.sco.com/">SCO TCP/IP Release 1.2.1</A> + can be modified to have a timeout by following + <A HREF="http://www.sco.com/cgi-bin/waisgate?WAISdocID=2242622956+0+0+0&WAISaction=retrieve"> SCO's instructions</A>. + <LI><A HREF="http://www.linux.org/">Linux</A> 2.0.x and + earlier(?) + <LI><A HREF="http://www.hp.com/">HP-UX</A> 10.x defaults to + terminating connections in the FIN_WAIT_2 state after the + normal keepalive timeouts. This does not + refer to the persistent connection or HTTP keepalive + timeouts, but the <CODE>SO_LINGER</CODE> socket option + which is enabled by Apache. This parameter can be adjusted + by using <CODE>nettune</CODE> to modify parameters such as + <CODE>tcp_keepstart</CODE> and <CODE>tcp_keepstop</CODE>. + In later revisions, there is an explicit timer for + connections in FIN_WAIT_2 that can be modified; contact HP + support for details. + <LI><A HREF="http://www.sgi.com/">SGI IRIX</A> can be patched to + support a timeout. For IRIX 5.3, 6.2, and 6.3, + use patches 1654, 1703 and 1778 respectively. If you + have trouble locating these patches, please contact your + SGI support channel for help. + <LI><A HREF="http://www.ncr.com/">NCR's MP RAS Unix</A> 2.xx and + 3.xx both have FIN_WAIT_2 timeouts. In 2.xx it is non-tunable + at 600 seconds, while in 3.xx it defaults to 600 seconds and + is calculated based on the tunable "max keep alive probes" + (default of 8) multiplied by the "keep alive interval" (default + 75 seconds). + <LI><A HREF="http://www.sequent.com">Squent's ptx/TCP/IP for + DYNIX/ptx</A> has had a FIN_WAIT_2 timeout since around + release 4.1 in mid-1994. +</UL> +<P> +The following systems are known to not have a timeout: +<P> +<UL> + <LI><A HREF="http://www.sun.com/">SunOS 4.x</A> does not and + almost certainly never will have one because it as at the + very end of its development cycle for Sun. If you have kernel + source should be easy to patch. +</UL> +<P> +There is a +<A HREF="http://www.apache.org/dist/contrib/patches/1.2/fin_wait_2.patch"> +patch available</A> for adding a timeout to the FIN_WAIT_2 state; it +was originally intended for BSD/OS, but should be adaptable to most +systems using BSD networking code. You need kernel source code to be +able to use it. If you do adapt it to work for any other systems, +please drop me a note at <A HREF="mailto:marc@apache.org">marc@apache.org</A>. +<P> +<H3>Compile without using <CODE>lingering_close()</CODE></H3> + +It is possible to compile Apache 1.2 without using the +<CODE>lingering_close()</CODE> function. This will result in that +section of code being similar to that which was in 1.1. If you do +this, be aware that it can cause problems with PUTs, POSTs and +persistent connections, especially if the client uses pipelining. +That said, it is no worse than on 1.1, and we understand that keeping your +server running is quite important.<P> + +To compile without the <CODE>lingering_close()</CODE> function, add +<CODE>-DNO_LINGCLOSE</CODE> to the end of the +<CODE>EXTRA_CFLAGS</CODE> line in your <CODE>Configuration</CODE> file, +rerun <CODE>Configure</CODE> and rebuild the server. +<P> +<H3>Use <CODE>SO_LINGER</CODE> as an alternative to +<CODE>lingering_close()</CODE></H3> + +On most systems, there is an option called <CODE>SO_LINGER</CODE> that +can be set with <CODE>setsockopt(2)</CODE>. It does something very +similar to <CODE>lingering_close()</CODE>, except that it is broken +on many systems so that it causes far more problems than +<CODE>lingering_close</CODE>. On some systems, it could possibly work +better so it may be worth a try if you have no other alternatives. <P> + +To try it, add <CODE>-DUSE_SO_LINGER -DNO_LINGCLOSE</CODE> to the end of the +<CODE>EXTRA_CFLAGS</CODE> line in your <CODE>Configuration</CODE> +file, rerun <CODE>Configure</CODE> and rebuild the server. <P> + +<STRONG>NOTE:</STRONG> Attempting to use <CODE>SO_LINGER</CODE> and +<CODE>lingering_close()</CODE> at the same time is very likely to do +very bad things, so don't.<P> + +<H3>Increase the amount of memory used for storing connection state</H3> +<DL> +<DT>BSD based networking code: +<DD>BSD stores network data, such as connection states, +in something called an mbuf. When you get so many connections +that the kernel does not have enough mbufs to put them all in, your +kernel will likely crash. You can reduce the effects of the problem +by increasing the number of mbufs that are available; this will not +prevent the problem, it will just make the server go longer before +crashing.<P> + +The exact way to increase them may depend on your OS; look +for some reference to the number of "mbufs" or "mbuf clusters". On +many systems, this can be done by adding the line +<CODE>NMBCLUSTERS="n"</CODE>, where <CODE>n</CODE> is the number of +mbuf clusters you want to your kernel config file and rebuilding your +kernel.<P> +</DL> + +<H3>Disable KeepAlive</H3> +<P>If you are unable to do any of the above then you should, as a last +resort, disable KeepAlive. Edit your httpd.conf and change "KeepAlive On" +to "KeepAlive Off". + +<H2><LI>Feedback</H2> + +If you have any information to add to this page, please contact me at +<A HREF="mailto:marc@apache.org">marc@apache.org</A>.<P> + +<H2><A NAME="appendix"><LI>Appendix</A></H2> +<P> +Below is a message from Roy Fielding, one of the authors of HTTP/1.1. + +<H3>Why the lingering close functionality is necessary with HTTP</H3> + +The need for a server to linger on a socket after a close is noted a couple +times in the HTTP specs, but not explained. This explanation is based on +discussions between myself, Henrik Frystyk, Robert S. Thau, Dave Raggett, +and John C. Mallery in the hallways of MIT while I was at W3C.<P> + +If a server closes the input side of the connection while the client +is sending data (or is planning to send data), then the server's TCP +stack will signal an RST (reset) back to the client. Upon +receipt of the RST, the client will flush its own incoming TCP buffer +back to the un-ACKed packet indicated by the RST packet argument. +If the server has sent a message, usually an error response, to the +client just before the close, and the client receives the RST packet +before its application code has read the error message from its incoming +TCP buffer and before the server has received the ACK sent by the client +upon receipt of that buffer, then the RST will flush the error message +before the client application has a chance to see it. The result is +that the client is left thinking that the connection failed for no +apparent reason.<P> + +There are two conditions under which this is likely to occur: +<OL> +<LI>sending POST or PUT data without proper authorization +<LI>sending multiple requests before each response (pipelining) + and one of the middle requests resulting in an error or + other break-the-connection result. +</OL> +<P> +The solution in all cases is to send the response, close only the +write half of the connection (what shutdown is supposed to do), and +continue reading on the socket until it is either closed by the +client (signifying it has finally read the response) or a timeout occurs. +That is what the kernel is supposed to do if SO_LINGER is set. +Unfortunately, SO_LINGER has no effect on some systems; on some other +systems, it does not have its own timeout and thus the TCP memory +segments just pile-up until the next reboot (planned or not).<P> + +Please note that simply removing the linger code will not solve the +problem -- it only moves it to a different and much harder one to detect. +</OL> +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/misc/footer.html b/usr.sbin/httpd/htdocs/manual/misc/footer.html new file mode 100644 index 00000000000..cbbcf9a8e2c --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/misc/footer.html @@ -0,0 +1,7 @@ +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> diff --git a/usr.sbin/httpd/htdocs/manual/misc/header.html b/usr.sbin/httpd/htdocs/manual/misc/header.html new file mode 100644 index 00000000000..3a472e66722 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/misc/header.html @@ -0,0 +1,6 @@ +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> diff --git a/usr.sbin/httpd/htdocs/manual/misc/howto.html b/usr.sbin/httpd/htdocs/manual/misc/howto.html new file mode 100644 index 00000000000..c3ddf868066 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/misc/howto.html @@ -0,0 +1,160 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<META NAME="description" CONTENT="Some 'how to' tips for the Apache httpd server"> +<META NAME="keywords" CONTENT="apache,redirect,robots,rotate,logfiles"> +<TITLE>Apache HOWTO documentation</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Apache HOWTO documentation</H1> + +How to: +<ul> +<li><A HREF="#redirect">redirect an entire server or directory to a single URL</A> +<li><A HREF="#logreset">reset your log files</A> +<li><A HREF="#stoprob">stop/restrict robots</A> +</ul> + +<HR> +<H2><A name="redirect">How to redirect an entire server or directory to a single URL</A></H2> + +<P>There are two chief ways to redirect all requests for an entire +server to a single location: one which requires the use of +<code>mod_rewrite</code>, and another which uses a CGI script. + +<P>First: if all you need to do is migrate a server from one name to +another, simply use the <code>Redirect</code> directive, as supplied +by <code>mod_alias</code>: + +<blockquote><pre> + Redirect / http://www.apache.org/ +</pre></blockquote> + +<P>Since <code>Redirect</code> will forward along the complete path, +however, it may not be appropriate - for example, when the directory +structure has changed after the move, and you simply want to direct people +to the home page. + +<P>The best option is to use the standard Apache module <code>mod_rewrite</code>. +If that module is compiled in, the following lines: + +<blockquote><pre>RewriteEngine On +RewriteRule /.* http://www.apache.org/ [R] +</pre></blockquote> + +This will send an HTTP 302 Redirect back to the client, and no matter +what they gave in the original URL, they'll be sent to +"http://www.apache.org". + +The second option is to set up a <CODE>ScriptAlias</Code> pointing to +a <B>cgi script</B> which outputs a 301 or 302 status and the location +of the other server.</P> + +<P>By using a <B>cgi-script</B> you can intercept various requests and +treat them specially, e.g. you might want to intercept <B>POST</B> +requests, so that the client isn't redirected to a script on the other +server which expects POST information (a redirect will lose the POST +information.) You might also want to use a CGI script if you don't +want to compile mod_rewrite into your server. + +<P>Here's how to redirect all requests to a script... In the server +configuration file, +<blockquote><pre>ScriptAlias / /usr/local/httpd/cgi-bin/redirect_script</pre></blockquote> + +and here's a simple perl script to redirect requests: + +<blockquote><pre> +#!/usr/local/bin/perl + +print "Status: 302 Moved Temporarily\r +Location: http://www.some.where.else.com/\r\n\r\n"; + +</pre></blockquote></P> + +<HR> + +<H2><A name="logreset">How to reset your log files</A></H2> + +<P>Sooner or later, you'll want to reset your log files (access_log and +error_log) because they are too big, or full of old information you don't +need.</P> + +<P><CODE>access.log</CODE> typically grows by 1Mb for each 10,000 requests.</P> + +<P>Most people's first attempt at replacing the logfile is to just move the +logfile or remove the logfile. This doesn't work.</P> + +<P>Apache will continue writing to the logfile at the same offset as before the +logfile moved. This results in a new logfile being created which is just +as big as the old one, but it now contains thousands (or millions) of null +characters.</P> + +<P>The correct procedure is to move the logfile, then signal Apache to tell it to reopen the logfiles.</P> + +<P>Apache is signaled using the <B>SIGHUP</B> (-1) signal. e.g. +<blockquote><code> +mv access_log access_log.old<BR> +kill -1 `cat httpd.pid` +</code></blockquote> +</P> + +<P>Note: <code>httpd.pid</code> is a file containing the <B>p</B>rocess <B>id</B> +of the Apache httpd daemon, Apache saves this in the same directory as the log +files.</P> + +<P>Many people use this method to replace (and backup) their logfiles on a +nightly or weekly basis.</P> +<HR> + +<H2><A name="stoprob">How to stop or restrict robots</A></H2> + +<P>Ever wondered why so many clients are interested in a file called +<code>robots.txt</code> which you don't have, and never did have?</P> + +<P>These clients are called <B>robots</B> (also known as crawlers, +spiders and other cute name) - special automated clients which +wander around the web looking for interesting resources.</P> + +<P>Most robots are used to generate some kind of <em>web index</em> which +is then used by a <em>search engine</em> to help locate information.</P> + +<P><code>robots.txt</code> provides a means to request that robots limit their +activities at the site, or more often than not, to leave the site alone.</P> + +<P>When the first robots were developed, they had a bad reputation for sending hundreds/thousands of requests to each site, often resulting in the site being overloaded. Things have improved dramatically since then, thanks to <A HREF="http://info.webcrawler.com/mak/projects/robots/guidelines.html"> Guidelines for Robot Writers</A>, but even so, some robots may <A HREF="http://www.zyzzyva.com/robots/alert/">exhibit unfriendly behavior</A> which the webmaster isn't willing to tolerate, and will want to stop.</P> + +<P>Another reason some webmasters want to block access to robots, is to +stop them indexing dynamic information. Many search engines will use the +data collected from your pages for months to come - not much use if your +serving stock quotes, news, weather reports or anything else that will be +stale by the time people find it in a search engine.</P> + +<P>If you decide to exclude robots completely, or just limit the areas +in which they can roam, create a <CODE>robots.txt</CODE> file; refer +to the <A HREF="http://info.webcrawler.com/mak/projects/robots/robots.html">robot information pages</A> provided by Martijn Koster for the syntax.</P> + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/misc/index.html b/usr.sbin/httpd/htdocs/manual/misc/index.html new file mode 100644 index 00000000000..d7469c16f07 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/misc/index.html @@ -0,0 +1,132 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> + <HEAD> + <TITLE>Apache Miscellaneous Documentation</TITLE> + </HEAD> + + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + <BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" + > + <DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + + <H1 ALIGN="CENTER">Apache Miscellaneous Documentation</h1> + + <P> + Below is a list of additional documentation pages that apply to the + Apache web server development project. + </P> + <DL> + <DT><A + HREF="API.html" + >API</A> + </DT> + <DD>Description of Apache's Application Programming Interface. + </DD> + <DT><A + HREF="FAQ.html" + >FAQ</A> + </DT> + <DD>Frequently-Asked Questions concerning the Apache project and server + </DD> + <DT><A + HREF="client_block_api.html" + >Reading Client Input in Apache 1.2</A> + </DT> + <DD>Describes differences between Apache 1.1 and 1.2 in how modules + read information from the client + </DD> + <DT><A + HREF="compat_notes.html" + >Compatibility with NCSA</A> + </DT> + <DD>Notes about Apache's compatibility with the NCSA server + </DD> + <DT><A + HREF="fin_wait_2.html" + ><SAMP>FIN_WAIT_2</SAMP></A> + </DT> + <DD>A description of the causes of Apache processes going into the + <SAMP>FIN_WAIT_2</SAMP> state, and what you can do about it + </DD> + <DT><A + HREF="howto.html" + >"How-To"</A> + </DT> + <DD>Instructions about how to accomplish some commonly-desired server + functionality changes + </DD> + <DT><A + HREF="known_bugs.html" + >Known Bugs</A> + </DT> + <DD>Just what it says - a list of known bugs in each of the Apache releases + </DD> + <DT><A + HREF="nopgp.html" + >No PGP</A> + </DT> + <DD>Why we took PEM and PGP support out of the base Apache distribution + </DD> + <DT><A + HREF="perf-bsd44.html" + >Performance Notes (BSD 4.4)</A> + </DT> + <DD>Some notes about ways to improve/optimize Apache performance on + BSD 4.4 systems + </DD> + <DT><A + HREF="perf-dec.html" + >Performance Notes (Digital UNIX)</A> + </DT> + <DD>Extracts of USENET postings describing how to optimize Apache + performance on Digital UNIX systems + </DD> + <DT><A + HREF="perf.html" + >Performance Notes (General)</A> + </DT> + <DD>Some generic notes about how to improve Apache performance + </DD> + <DT><A + HREF="security_tips.html" + >Security Tips</A> + </DT> + <DD>Some "do"s - and "don't"s - for keeping your + Apache web site secure + </DD> + <DT><A + HREF="vif-info.html" + >Virtual Hosts (IP-based)</A> + </DT> + <DD>Excerpts and notes about configuring and using Apache IP-based virtual + hosts + </DD> + <DT><A + HREF="windoz_keepalive.html" + >Windows Bug with Web Keepalive</A> + </DT> + <DD>A brief description of a known problem with Microsoft Windows and + web sites accessed using keepalive connections + </DD> + </DL> + + <HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + + </BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/misc/known_bugs.html b/usr.sbin/httpd/htdocs/manual/misc/known_bugs.html new file mode 100644 index 00000000000..95bb37c705d --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/misc/known_bugs.html @@ -0,0 +1,171 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache HTTP Server Project</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Known Bugs in Apache</H1> + +The most up-to-date resource for bug tracking and information is the +<A HREF="http://www.apache.org/bugdb.cgi">Apache bug database</A>. +Significant bugs at release time will also be noted there. +If you are running a 1.2 beta release or version 1.1.3 or earlier +and thing you have found a bug, please upgrade to 1.2. Many bugs +in early versions have been fixed in 1.2. + +<P>See Also: <A HREF="compat_notes.html">Compatibility notes</A></P> +<HR> + +<H2>Apache 1.2 Bugs</H2> + +<OL> + <LI><b>Exists in 1.2.1 only.</b> + On Solaris 2.x the server will stop running after receiving a + SIGHUP. Four workarounds exist (choose one):<p> + <ul> + <li>Retrieve <a href="http://www.apache.org/dist/patches/apply_to_1.2.1/solaris_hup.patch">this patch</a>. + <code>cd</code> to your <code>apache_1.2.1</code> directory, and + type <code>patch -s -p1 < /path/to/patchfile</code>. Then rebuild + Apache.<p> + <li>Use SIGUSR1 instead of SIGHUP, see <a href="../stopping.html"> + Stopping and Restarting Apache</a> for more details.<p> + <li>Add <code>-DNO_SLACK</code> to + <code>EXTRA_CFLAGS</code> in + your <code>Configuration</code> file, re-run <code>Configure</code> + and rebuild your server. This disables the + <a href="descriptors.html">descriptor slack workaround</a><p> + <li>(Least preferable) Use Apache 1.2.0 instead of 1.2.1.<p> + </ul> + This problem will be tracked as + <a href="http://www.apache.org/bugdb.cgi/full/832">PR#832</a>.<p> + </li> + + <LI>(Exists in 1.2.0 and in 1.2.1 after either of the + <code>NO_SLACK</code> or patch provided by the previous bug are applied.) + Solaris 2.5.1 (and probably other versions of Solaris) appear to have + a race condition completely unrelated to all the others. It is possible + during a SIGHUP that the server will fail to start because it will not + be able to re-open its sockets. To our knowledge this has only shown + up during testing when we pummel the server with as many SIGHUP requests + per second as we can. This appears unrelated to the similar sounding bug + described in <a href="http://www.apache.org/bugdb.cgi/full/832">PR#832</a>. + <p> + + <LI><a name="listenbug">On some architectures</A> + if your configuration uses multiple + <a href="../mod/core.html#listen">Listen</a> directives then it is possible + that the server will starve one of the sockets while serving hits on + another. The work-around is to add + <code>-DUSE_FLOCK_SERIALIZED_ACCEPT</code> to the + <code>EXTRA_CFLAGS</code> line in your Configuration and rebuild. + (If you encounter problems with that, you can also try + <code>-DUSE_FCNTL_SERIALIZED_ACCEPT</code>.) + This affects any architecture that doesn't use one of the + <code>USE_xxxxx_SERIALIZED_ACCEPT</code> definitions, see the + source file <code>conf.h</code> for your architecture. + This will be tracked as + <a href="http://www.apache.org/bugdb.cgi/full/467">PR#467</a>. + <P></LI> + + <LI><b>Fixed in 1.2.1.</b> + <a name="cnegbug">Apache's</A> <A HREF="../content-negotiation.html">Content + Negotiation</A> should pick the smallest variant if there + are several that are equally acceptable. A bug in 1.2 means it no + longer does this unless all the variants have character sets. + This <A HREF="../../dist/contrib/patches/1.2/conneg-bug.patch">patch</A> + fixes this problem. It also fixes the problem which makes Apache + pick the last equally acceptable variant instead of the first. + This will be tracked as + <a href="http://www.apache.org/bugdb.cgi/full/94">PR#94</a>. + <P></LI> + + <LI> + The PATH_INFO part of a request URI cannot include the sequence + <CODE>%2f</CODE>. This will be tracked as + <A HREF="http://www.apache.org/bugdb.cgi/full/543">PR#543</A>. + <P></LI> + + <LI>Users of early 1.2 betas reported problems with many + connections stuck in the FIN_WAIT_2 state due to server + timeouts. Several changes were made during the beta testing of 1.2 + to reduce this problem as much as possible, although you may still + see sockets in FIN_WAIT_2 state due to network or operating system + issues outside the control of Apache. See our <A + HREF="fin_wait_2.html">FIN_WAIT_2</A> page for more details. + + <P>SunOS4 has a kernel bug in the allocation of memory for the mbuf table. + When it fills up, the result is a Panic the next time any routine tries + to set something in an imaginary mbuf beyond the range of the table. + Due to buggy browser behavior and the lack of a FIN_WAIT_2 timeout + on SunOS4, "KeepAlive Off" is necessary to avoid filling up the mbuf + table on busy sites. + <P></LI> + + <LI>Compilation fails on SCO3 when using gcc instead of cc, complaining + with "<CODE>gcc: noinline: No such file or directory</CODE>". Fix + is given in <a href="http://www.apache.org/bugdb.cgi/full/695">PR#695</A>. + <P></LI> + + <LI>If compilation fails complaining about "unknown symbol __inet_ntoa()" + then you have probably installed version 8 of bind. You will need to + explicitly link with the bind library by adding <CODE>-lbind</CODE> + to <CODE>EXTRA_LDFLAGS</CODE> in <CODE>Configuration</CODE>. See + <A HREF="http://www.apache.org/bugdb.cgi/full/616">PR#616</A> + and the + <A HREF="FAQ.html#bind8.1">Apache FAQ</A>. + <P></LI> + + <LI>The message "<CODE>created shared memory segment #730499</CODE>" + in error_log is not an error and should be ignored. See + <a href="http://www.apache.org/bugdb.cgi/full/696">PR#696</A>. + <P></LI> + + <LI> + Compiling on Solaris 2 with SunSoft's C compiler gives the warning + <CODE>"mod_include.c", line 1123: warning: end-of-loop code not + reached</CODE>. This is a bogus warning and can be ignored. + See <A HREF="http://www.apache.org/bugdb.cgi/full/681">PR#681</A>. + <P></LI> + + <LI><a href="descriptors.html"><b>Workaround available in 1.2.1.</b></a> + There appears to be a problem on BSDI 2.1 with large numbers of + virtual hosts. This appears similar to a file-descriptor limit + but BSDI should not have this problem. This will be tracked as + <A HREF="http://www.apache.org/bugdb.cgi/full/611">PR#611</A>. + See also the <A HREF="FAQ.html#fdlim">Apache FAQ</A>. + <P></LI> + + <LI><a href="descriptors.html"><b>Workaround available in 1.2.1.</b></a> + Solaris 2 has problems with large numbers of virtual hosts. This is + because of an operating system limit of 256 file pointers, not due + to Apache. See also the <A HREF="FAQ.html#fdlim">Apache FAQ</A>. + <P></LI> + +</OL> + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/misc/known_client_problems.html b/usr.sbin/httpd/htdocs/manual/misc/known_client_problems.html new file mode 100644 index 00000000000..4f64e06a2f4 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/misc/known_client_problems.html @@ -0,0 +1,213 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache HTTP Server Project</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Known Problems in Clients</H1> + +<p>Over time the Apache Group has discovered or been notified of problems +with various clients which we have had to work around. This document +describes these problems and the workarounds available. It's not arranged +in any particular order. Some familiarity with the standards is assumed, +but not necessary. + +<p>For brevity, <i>Navigator</i> will refer to Netscape's Navigator +product, and <i>MSIE</i> will refer to Microsoft's Internet Explorer +product. All trademarks and copyrights belong to their respective +companies. We welcome input from the various client authors to correct +inconsistencies in this paper, or to provide us with exact version +numbers where things are broken/fixed. + +<p>For reference, +<a href="ftp://ds.internic.net/rfc/rfc1945.txt">RFC1945</a> +defines HTTP/1.0, and +<a href="ftp://ds.internic.net/rfc/rfc2068.txt">RFC2068</a> +defines HTTP/1.1. Apache as of version 1.2 is an HTTP/1.1 server (with an +optional HTTP/1.0 proxy). + +<p>Various of these workarounds are triggered by environment variables. +The admin typically controls which are set, and for which clients, by using +<a href="../mod/mod_browser.html">mod_browser</a>. Unless otherwise +noted all of these workarounds exist in versions 1.2 and later. + +<a name="trailing-crlf"><H3>Trailing CRLF on POSTs</H3></a> + +<p>This is a legacy issue. The CERN webserver required <code>POST</code> +data to have an extra <code>CRLF</code> following it. Thus many +clients send an extra <code>CRLF</code> that +is not included in the <code>Content-Length</code> of the request. +Apache works around this problem by eating any empty lines which +appear before a request. + +<a name="broken-keepalive"><h3>Broken keepalive</h3></a> + +<p>Various clients have had broken implementations of <i>keepalive</i> +(persistent connections). In particular the Windows versions of +Navigator 2.0 get very confused when the server times out an +idle connection. The workaround is present in the default config files: +<blockquote><code> +BrowserMatch Mozilla/2 nokeepalive +</code></blockquote> +Note that this matches some earlier versions of MSIE, which began the +practice of calling themselves <i>Mozilla</i> in their user-agent +strings just like Navigator. + +<p>MSIE 4.0b2, which claims to support HTTP/1.1, does not properly +support keepalive when it is used on 301 or 302 (redirect) +responses. Unfortunately Apache's <code>nokeepalive</code> code +prior to 1.2.2 would not work with HTTP/1.1 clients. You must apply +<a href="http://www.apache.org/dist/patches/apply_to_1.2.1/msie_4_0b2_fixes.patch">this +patch</a> to version 1.2.1. Then add this to your config: +<blockquote><code> +BrowserMatch "MSIE 4\.0b2;" nokeepalive +</code></blockquote> + +<a name="force-response-1.0"><h3>Incorrect interpretation of <code>HTTP/1.1</code> in response</h3></a> + +<p>To quote from section 3.1 of RFC1945: +<blockquote> +HTTP uses a "<major>.<minor>" numbering scheme to indicate versions +of the protocol. The protocol versioning policy is intended to allow +the sender to indicate the format of a message and its capacity for +understanding further HTTP communication, rather than the features +obtained via that communication. +</blockquote> +Since Apache is an HTTP/1.1 server, it indicates so as part of its +response. Many client authors mistakenly treat this part of the response +as an indication of the protocol that the response is in, and then refuse +to accept the response. + +<p>The first major indication of this problem was with AOL's proxy servers. +When Apache 1.2 went into beta it was the first wide-spread HTTP/1.1 +server. After some discussion, AOL fixed their proxies. In +anticipation of similar problems, the <code>force-response-1.0</code> +environment variable was added to Apache. When present Apache will +indicate "HTTP/1.0" in response to an HTTP/1.0 client, +but will not in any other way change the response. + +<p>The pre-1.1 Java Development Kit (JDK) that is used in many clients +(including Navigator 3.x and MSIE 3.x) exhibits this problem. As do some +of the early pre-releases of the 1.1 JDK. We think it is fixed in the +1.1 JDK release. In any event the workaround: +<blockquote><code> +BrowserMatch Java1.0 force-response-1.0 <br> +BrowserMatch JDK/1.0 force-response-1.0 +</code></blockquote> + +<p>RealPlayer 4.0 from Progressive Networks also exhibits this problem. +However they have fixed it in version 4.01 of the player, but version +4.01 uses the same <code>User-Agent</code> as version 4.0. The +workaround is still: +<blockquote><code> +BrowserMatch "RealPlayer 4.0" force-response-1.0 +</code></blockquote> + +<a name="msie4.0b2"><h3>Requests use HTTP/1.1 but responses must be in HTTP/1.0</h3></a> + +<p>MSIE 4.0b2 has this problem. Its Java VM makes requests in HTTP/1.1 +format but the responses must be in HTTP/1.0 format (in particular, it +does not understand <i>chunked</i> responses). The workaround +is to fool Apache into believing the request came in HTTP/1.0 format. +<blockquote><code> +BrowserMatch "MSIE 4\.0b2;" downgrade-1.0 force-response-1.0 +</code></blockquote> +This workaround is available in 1.2.2, and in a +<a href="http://www.apache.org/dist/patches/apply_to_1.2.1/msie_4_0b2_fixes.patch">patch +</a> against 1.2.1. + +<a name="257th-byte"><h3>Boundary problems with header parsing</h3></a> + +<p>All versions of Navigator from 2.0 through 4.0b2 (and possibly later) +have a problem if the trailing CRLF of the response header starts at +the 256th or 257th byte of the response. A BrowserMatch for this would +match on nearly every hit, so the workaround is enabled automatically +on all responses. The workaround is to detect when this condition would +occur in a response and add extra padding to the header to push the +trailing CRLF past the 257th byte of the response. + +<a name="boundary-string"><h3>Multipart responses and Quoted Boundary Strings</h3></a> + +<p>On multipart responses some clients will not accept quotes (") +around the boundary string. The MIME standard recommends that +such quotes be used. But the clients were probably written based +on one of the examples in RFC2068, which does not include quotes. +Apache does not include quotes on its boundary strings to workaround +this problem. + +<a name="byterange-requests"><h3>Byterange requests</h3></a> + +<p>A byterange request is used when the client wishes to retrieve a +portion of an object, not necessarily the entire object. There +was a very old draft which included these byteranges in the URL. +Old clients such as Navigator 2.0b1 and MSIE 3.0 for the MAC +exhibit this behaviour, and +it will appear in the servers' access logs as (failed) attempts to +retrieve a URL with a trailing ";xxx-yyy". Apache does not attempt +to implement this at all. + +<p>A subsequent draft of this standard defines a header +<code>Request-Range</code>, and a response type +<code>multipart/x-byteranges</code>. The HTTP/1.1 standard includes +this draft with a few fixes, and it defines the header +<code>Range</code> and type <code>multipart/byteranges</code>. + +<p>Navigator (versions 2 and 3) sends both <code>Range</code> and +<code>Request-Range</code> headers (with the same value), but does not +accept a <code>multipart/byteranges</code> response. The response must +be <code>multipart/x-byteranges</code>. As a workaround, if Apache +receives a <code>Request-Range</code> header it considers it "higher +priority" than a <code>Range</code> header and in response uses +<code>multipart/x-byteranges</code>. + +<p>The Adobe Acrobat Reader plugin makes extensive use of byteranges and +prior to version 3.01 supports only the <code>multipart/x-byterange</code> +response. Unfortunately there is no clue that it is the plugin +making the request. If the plugin is used with Navigator, the above +workaround works fine. But if the plugin is used with MSIE 3 (on +Windows) the workaround won't work because MSIE 3 doesn't give the +<code>Range-Request</code> clue that Navigator does. To workaround this, +Apache special cases "MSIE 3" in the <code>User-Agent</code> and serves +<code>multipart/x-byteranges</code>. Note that the necessity for this +with MSIE 3 is actually due to the Acrobat plugin, not due to the browser. + +<p>Netscape Communicator appears to not issue the non-standard +<code>Request-Range</code> header. When an Acrobat plugin prior to +version 3.01 is used with it, it will not properly understand byteranges. +The user must upgrade their Acrobat reader to 3.01. + +<a name="cookie-merge"><h3><code>Set-Cookie</code> header is unmergeable</h3></a> + +<p>The HTTP specifications say that it is legal to merge headers with +duplicate names into one (separated by semicolon). Some browsers +that support Cookies don't like merged headers and prefer that each +<code>Set-Cookie</code> header is sent separately. When parsing the +headers returned by a CGI, Apache will explicitly avoid merging any +<code>Set-Cookie</code> headers. + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> + diff --git a/usr.sbin/httpd/htdocs/manual/misc/nopgp.html b/usr.sbin/httpd/htdocs/manual/misc/nopgp.html new file mode 100644 index 00000000000..9a3497b442a --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/misc/nopgp.html @@ -0,0 +1,101 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Why We Took PEM Out of Apache</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Why We Took PEM Out of Apache</H1> + +On May 17th, 1995, we were asked by a representative of NCSA to remove +any copies of NCSA httpd prior to 1.4.1 from our web site. They +were mandated by the NSA to inform us that redistribution of pre-1.4.1 +code violated the same laws that make distributing Phill Zimmerman's +PGP package to other countries illegal. There was <B>no</B> +encryption in NCSA's httpd, only hooks to publicly available libraries +of PEM code. By the NSA's rules, even hooks to this type of +application is illegal. + +<P> + +Because Apache is based on NCSA code, and we had basically not touched +that part of the software, we were informed that Apache was also +illegal to distribute to foreign countries, and advised (not mandated) +by NCSA to remove it. So, we removed both the copies of the NCSA +httpd we had, and all versions of Apache previous to 0.6.5. + +<P> + +The Apache members are strong advocates of the right to digital +privacy, so the decision to submit to the NSA and remove the code was +not an easy one. Here are some elements in our rationale: + +<UL> + +<LI>The PEM code in httpd was not widely used. No major site relied +upon its use, so its loss is not a blow to encryption and security on +the world wide web. There are other efforts designed to give much +more flexible security - SSL and SHTTP - so this wasn't a function +whose absence would really be missed on a functional level. + +<LI>We didn't feel like being just a couple more martyrs in a fight +being fought very well by many other people. Rather than have the +machine that supports the project confiscated or relocated to South +Africa, etc., we think there are more efficient methods to address the +issue. + +</UL> + +It kind of sickens us that we had to do it, but so be it. + +<P> + +Patches that re-implement the PEM code may be available at a foreign +site soon. If it does show up, we'll point to it - that can't be illegal! + +<P> + +Finally, here is a compendium of pointers to sites related to +encryption and export law. We can't promise this list will be up to +date, so send us mail when you see a problem or want a link added. +Thanks. + +<UL> +<LI><A HREF="http://www.yahoo.com/Computers_and_Internet/Security_and_Encryption/"> +Yahoo - Science: Mathematics: Security and Encryption</A> +<LI><A HREF="http://www.eff.org/pub/EFF/Policy/Crypto/"> +EFF Crypto/Privacy/Security Archive</A> +<LI><A HREF="http://www.quadralay.com/www/Crypt/Crypt.html"> +Crypto page at Quadralay</A> +<LI><A HREF="ftp://ftp.cygnus.com/pub/export/export.html"> +Cryptography Export Control Archives (Cygnus)</A> +<LI><A HREF="http://www.law.indiana.edu/law/iclu.html"> +ICLU - Your Rights in Cyberspace</A> +</UL> + + <a href="http://www.behlendorf.com/~brian/">Brian</a>, <a href="mailto:brian@hyperreal.com">brian@hyperreal.com</a> + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/misc/perf-bsd44.html b/usr.sbin/httpd/htdocs/manual/misc/perf-bsd44.html new file mode 100644 index 00000000000..a65afb00304 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/misc/perf-bsd44.html @@ -0,0 +1,249 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<html> +<head> +<title>Running a High-Performance Web Server for BSD</title> +</head> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<A NAME="initial"> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +</A> +<H1 ALIGN="CENTER">Running a High-Performance Web Server for BSD</H1> + +Like other OS's, the listen queue is often the <b>first limit hit</b>. The +following are comments from "Aaron Gifford <agifford@InfoWest.COM>" +on how to fix this on BSDI 1.x, 2.x, and FreeBSD 2.0 (and earlier): + +<p> + +Edit the following two files: +<blockquote><code> /usr/include/sys/socket.h <br> + /usr/src/sys/sys/socket.h </code></blockquote> +In each file, look for the following: +<pre> + /* + * Maximum queue length specifiable by listen. + */ + #define SOMAXCONN 5 +</pre> + +Just change the "5" to whatever appears to work. I bumped the two +machines I was having problems with up to 32 and haven't noticed the +problem since. + +<p> + +After the edit, recompile the kernel and recompile the Apache server +then reboot. + +<P> + +FreeBSD 2.1 seems to be perfectly happy, with SOMAXCONN +set to 32 already. + +<p> + +<A NAME="detail"> +<b>Addendum for <i>very</i> heavily loaded BSD servers</b><br> +</A> +from Chuck Murcko <chuck@telebase.com> + +<p> + +If you're running a really busy BSD Apache server, the following are useful +things to do if the system is acting sluggish:<p> + +<ul> + +<li> Run vmstat to check memory usage, page/swap rates, etc. + +<li> Run netstat -m to check mbuf usage + +<li> Run fstat to check file descriptor usage + +</ul> + +These utilities give you an idea what you'll need to tune in your kernel, +and whether it'll help to buy more RAM. + +Here are some BSD kernel config parameters (actually BSDI, but pertinent to +FreeBSD and other 4.4-lite derivatives) from a system getting heavy usage. +The tools mentioned above were used, and the system memory was increased to +48 MB before these tuneups. Other system parameters remained unchanged. + +<p> + +<pre> +maxusers 256 +</pre> + +Maxusers drives a <i>lot</i> of other kernel parameters: + +<ul> + +<li> Maximum # of processes + +<li> Maximum # of processes per user + +<li> System wide open files limit + +<li> Per-process open files limit + +<li> Maximum # of mbuf clusters + +<li> Proc/pgrp hash table size + +</ul> + +The actual formulae for these derived parameters are in +<i>/usr/src/sys/conf/param.c</i>. +These calculated parameters can also be overridden (in part) by specifying +your own values in the kernel configuration file: + +<pre> +# Network options. NMBCLUSTERS defines the number of mbuf clusters and +# defaults to 256. This machine is a server that handles lots of traffic, +# so we crank that value. +options SOMAXCONN=256 # max pending connects +options NMBCLUSTERS=4096 # mbuf clusters at 4096 + +# +# Misc. options +# +options CHILD_MAX=512 # maximum number of child processes +options OPEN_MAX=512 # maximum fds (breaks RPC svcs) +</pre> + +SOMAXCONN is not derived from maxusers, so you'll always need to increase +that yourself. We used a value guaranteed to be larger than Apache's +default for the listen() of 128, currently. + +<p> + +In many cases, NMBCLUSTERS must be set much larger than would appear +necessary at first glance. The reason for this is that if the browser +disconnects in mid-transfer, the socket fd associated with that particular +connection ends up in the TIME_WAIT state for several minutes, during +which time its mbufs are not yet freed. Another reason is that, on server +timeouts, some connections end up in FIN_WAIT_2 state forever, because +this state doesn't time out on the server, and the browser never sent +a final FIN. For more details see the +<A HREF="fin_wait_2.html">FIN_WAIT_2</A> page. + +<p> + +Some more info on mbuf clusters (from sys/mbuf.h): +<pre> +/* + * Mbufs are of a single size, MSIZE (machine/machparam.h), which + * includes overhead. An mbuf may add a single "mbuf cluster" of size + * MCLBYTES (also in machine/machparam.h), which has no additional overhead + * and is used instead of the internal data area; this is done when + * at least MINCLSIZE of data must be stored. + */ +</pre> + +<p> + +CHILD_MAX and OPEN_MAX are set to allow up to 512 child processes (different +than the maximum value for processes per user ID) and file descriptors. +These values may change for your particular configuration (a higher OPEN_MAX +value if you've got modules or CGI scripts opening lots of connections or +files). If you've got a lot of other activity besides httpd on the same +machine, you'll have to set NPROC higher still. In this example, the NPROC +value derived from maxusers proved sufficient for our load. + +<p> + +<b>Caveats</b> + +<p> + +Be aware that your system may not boot with a kernel that is configured +to use more resources than you have available system RAM. <b>ALWAYS</b> +have a known bootable kernel available when tuning your system this way, +and use the system tools beforehand to learn if you need to buy more +memory before tuning. + +<p> + +RPC services will fail when the value of OPEN_MAX is larger than 256. +This is a function of the original implementations of the RPC library, +which used a byte value for holding file descriptors. BSDI has partially +addressed this limit in its 2.1 release, but a real fix may well await +the redesign of RPC itself. + +<p> + +Finally, there's the hard limit of child processes configured in Apache. + +<p> + +For versions of Apache later than 1.0.5 you'll need to change the +definition for <b>HARD_SERVER_LIMIT</b> in <i>httpd.h</i> and recompile +if you need to run more than the default 150 instances of httpd. + +<p> + +From conf/httpd.conf-dist: + +<pre> +# Limit on total number of servers running, i.e., limit on the number +# of clients who can simultaneously connect --- if this limit is ever +# reached, clients will be LOCKED OUT, so it should NOT BE SET TOO LOW. +# It is intended mainly as a brake to keep a runaway server from taking +# Unix with it as it spirals down... + +MaxClients 150 +</pre> + +Know what you're doing if you bump this value up, and make sure you've +done your system monitoring, RAM expansion, and kernel tuning beforehand. +Then you're ready to service some serious hits! + +<p> + +Thanks to <i>Tony Sanders</i> and <i>Chris Torek</i> at BSDI for their +helpful suggestions and information. + +<P> + +"M. Teterin" <mi@ALDAN.ziplink.net> writes:<P> +<blockquote>It really does help if your kernel and frequently used utilities +are fully optimized. Rebuilding the FreeBSD kernel on an AMD-133 +(486-class CPU) web-server with<BR> +<code> -m486 -fexpensive-optimizations -fomit-frame-pointer -O2</code><BR> +helped reduce the number of "unable" errors, because the CPU was +often maxed out.</blockquote> +<P> + +<HR> + +<H3>More welcome!</H3> + +If you have tips to contribute, send mail to <a +href="mailto:brian@organic.com">brian@organic.com</a> + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</body></html> + diff --git a/usr.sbin/httpd/htdocs/manual/misc/perf-dec.html b/usr.sbin/httpd/htdocs/manual/misc/perf-dec.html new file mode 100644 index 00000000000..eb0551a1ecd --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/misc/perf-dec.html @@ -0,0 +1,292 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Performance Tuning Tips for Digital Unix</TITLE> +</HEAD> +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Performance Tuning Tips for Digital Unix</H1> + +Below is a set of newsgroup posts made by an engineer from DEC in +response to queries about how to modify DEC's Digital Unix OS for more +heavily loaded web sites. Copied with permission. + +<HR> + +<H2>Update</H2> +From: Jeffrey Mogul <mogul@pa.dec.com><BR> +Date: Fri, 28 Jun 96 16:07:56 MDT<BR> + +<OL> +<LI> The advice given in the README file regarding the + "tcbhashsize" variable is incorrect. The largest value + this should be set to is 1024. Setting it any higher + will have the perverse result of disabling the hashing + mechanism. + +<LI>Patch ID OSF350-146 has been superseded by +<blockquote> + Patch ID OSF350-195 for V3.2C<BR> + Patch ID OSF360-350195 for V3.2D +</blockquote> + Patch IDs for V3.2E and V3.2F should be available soon. + There is no known reason why the Patch ID OSF360-350195 + won't work on these releases, but such use is not officially + supported by Digital. This patch kit will not be needed for + V3.2G when it is released. +</OL> +<HR> + + +<PRE> +From mogul@pa.dec.com (Jeffrey Mogul) +Organization DEC Western Research +Date 30 May 1996 00:50:25 GMT +Newsgroups <A HREF="news:comp.unix.osf.osf1">comp.unix.osf.osf1</A> +Message-ID <A HREF="news:4oirch$bc8@usenet.pa.dec.com"><4oirch$bc8@usenet.pa.dec.com></A> +Subject Re: Web Site Performance +References 1 + + + +In article <skoogDs54BH.9pF@netcom.com> skoog@netcom.com (Jim Skoog) writes: +>Where are the performance bottlenecks for Alpha AXP running the +>Netscape Commerce Server 1.12 with high volume internet traffic? +>We are evaluating network performance for a variety of Alpha AXP +>runing DEC UNIX 3.2C, which run DEC's seal firewall and behind +>that Alpha 1000 and 2100 webservers. + +Our experience (running such Web servers as <A HREF="http://altavista.digital.com">altavista.digital.com</A> +and <A HREF="http://www.digital.com">www.digital.com</A>) is that there is one important kernel tuning +knob to adjust in order to get good performance on V3.2C. You +need to patch the kernel global variable "somaxconn" (use dbx -k +to do this) from its default value of 8 to something much larger. + +How much larger? Well, no larger than 32767 (decimal). And +probably no less than about 2048, if you have a really high volume +(millions of hits per day), like AltaVista does. + +This change allows the system to maintain more than 8 TCP +connections in the SYN_RCVD state for the HTTP server. (You +can use "netstat -An |grep SYN_RCVD" to see how many such +connections exist at any given instant). + +If you don't make this change, you might find that as the load gets +high, some connection attempts take a very long time. And if a lot +of your clients disconnect from the Internet during the process of +TCP connection establishment (this happens a lot with dialup +users), these "embryonic" connections might tie up your somaxconn +quota of SYN_RCVD-state connections. Until the kernel times out +these embryonic connections, no other connections will be accepted, +and it will appear as if the server has died. + +The default value for somaxconn in Digital UNIX V4.0 will be quite +a bit larger than it has been in previous versions (we inherited +this default from 4.3BSD). + +Digital UNIX V4.0 includes some other performance-related changes +that significantly improve its maximum HTTP connection rate. However, +we've been using V3.2C systems to front-end for altavista.digital.com +with no obvious performance bottlenecks at the millions-of-hits-per-day +level. + +We have some Webstone performance results available at + <A HREF="http://www.digital.com/info/alphaserver/news/webff.html">http://www.digital.com/info/alphaserver/news/webff.html</A> +I'm not sure if these were done using V4.0 or an earlier version +of Digital UNIX, although I suspect they were done using a test +version of V4.0. + +-Jeff + +<HR> + +---------------------------------------------------------------------------- + +From mogul@pa.dec.com (Jeffrey Mogul) +Organization DEC Western Research +Date 31 May 1996 21:01:01 GMT +Newsgroups <A HREF="news:comp.unix.osf.osf1">comp.unix.osf.osf1</A> +Message-ID <A HREF="news:4onmmd$mmd@usenet.pa.dec.com"><4onmmd$mmd@usenet.pa.dec.com></A> +Subject Digital UNIX V3.2C Internet tuning patch info + +---------------------------------------------------------------------------- + +Something that probably few people are aware of is that Digital +has a patch kit available for Digital UNIX V3.2C that may improve +Internet performance, especially for busy web servers. + +This patch kit is one way to increase the value of somaxconn, +which I discussed in a message here a day or two ago. + +I've included in this message the revised README file for this +patch kit below. Note that the original README file in the patch +kit itself may be an earlier version; I'm told that the version +below is the right one. + +Sorry, this patch kit is NOT available for other versions of Digital +UNIX. Most (but not quite all) of these changes also made it into V4.0, +so the description of the various tuning parameters in this README +file might be useful to people running V4.0 systems. + +This patch kit does not appear to be available (yet?) from + <A HREF="http://www.service.digital.com/html/patch_service.html">http://www.service.digital.com/html/patch_service.html</A> +so I guess you'll have to call Digital's Customer Support to get it. + +-Jeff + +DESCRIPTION: Digital UNIX Network tuning patch + + Patch ID: OSF350-146 + + SUPERSEDED PATCHES: OSF350-151, OSF350-158 + + This set of files improves the performance of the network + subsystem on a system being used as a web server. There are + additional tunable parameters included here, to be used + cautiously by an informed system administrator. + +TUNING + + To tune the web server, the number of simultaneous socket + connection requests are limited by: + + somaxconn Sets the maximum number of pending requests + allowed to wait on a listening socket. The + default value in Digital UNIX V3.2 is 8. + This patch kit increases the default to 1024, + which matches the value in Digital UNIX V4.0. + + sominconn Sets the minimum number of pending connections + allowed on a listening socket. When a user + process calls listen with a backlog less + than sominconn, the backlog will be set to + sominconn. sominconn overrides somaxconn. + The default value is 1. + + The effectiveness of tuning these parameters can be monitored by + the sobacklog variables available in the kernel: + + sobacklog_hiwat Tracks the maximum pending requests to any + socket. The initial value is 0. + + sobacklog_drops Tracks the number of drops exceeding the + socket set backlog limit. The initial + value is 0. + + somaxconn_drops Tracks the number of drops exceeding the + somaxconn limit. When sominconn is larger + than somaxconn, tracks the number of drops + exceeding sominconn. The initial value is 0. + + TCP timer parameters also affect performance. Tuning the following + require some knowledge of the characteristics of the network. + + tcp_msl Sets the tcp maximum segment lifetime. + This is the maximum lifetime in half + seconds that a packet can be in transit + on the network. This value, when doubled, + is the length of time a connection remains + in the TIME_WAIT state after a incoming + close request is processed. The unit is + specified in 1/2 seconds, the initial + value is 60. + + tcp_rexmit_interval_min + Sets the minimum TCP retransmit interval. + For some WAN networks the default value may + be too short, causing unnecessary duplicate + packets to be sent. The unit is specified + in 1/2 seconds, the initial value is 1. + + tcp_keepinit This is the amount of time a partially + established connection will sit on the listen + queue before timing out (e.g. if a client + sends a SYN but never answers our SYN/ACK). + Partially established connections tie up slots + on the listen queue. If the queue starts to + fill with connections in SYN_RCVD state, + tcp_keepinit can be decreased to make those + partial connects time out sooner. This should + be used with caution, since there might be + legitimate clients that are taking a while + to respond to SYN/ACK. The unit is specified + in 1/2 seconds, the default value is 150 + (ie. 75 seconds). + + The hashlist size for the TCP inpcb lookup table is regulated by: + + tcbhashsize The number of hash buckets used for the + TCP connection table used in the kernel. + The initial value is 32. For best results, + should be specified as a power of 2. For + busy Web servers, set this to 2048 or more. + + The hashlist size for the interface alias table is regulated by: + + inifaddr_hsize The number of hash buckets used for the + interface alias table used in the kernel. + The initial value is 32. For best results, + should be specified as a power of 2. + + ipport_userreserved The maximum number of concurrent non-reserved, + dynamically allocated ports. Default range + is 1025-5000. The maximum value is 65535. + This limits the numer of times you can + simultaneously telnet or ftp out to connect + to other systems. + + tcpnodelack Don't delay acknowledging TCP data; this + can sometimes improve performance of locally + run CAD packages. Default is value is 0, + the enabled value is 1. + + Digital UNIX version: + + V3.2C +Feature V3.2C patch V4.0 +======= ===== ===== ==== +somaxconn X X X +sominconn - X X +sobacklog_hiwat - X - +sobacklog_drops - X - +somaxconn_drops - X - +tcpnodelack X X X +tcp_keepidle X X X +tcp_keepintvl X X X +tcp_keepcnt - X X +tcp_keepinit - X X +TCP keepalive per-socket - - X +tcp_msl - X - +tcp_rexmit_interval_min - X - +TCP inpcb hashing - X X +tcbhashsize - X X +interface alias hashing - X X +inifaddr_hsize - X X +ipport_userreserved - X - +sysconfig -q inet - - X +sysconfig -q socket - - X + +</PRE> +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/misc/perf.html b/usr.sbin/httpd/htdocs/manual/misc/perf.html new file mode 100644 index 00000000000..bb7221419a7 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/misc/perf.html @@ -0,0 +1,145 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<html> +<head> +<title>Hints on Running a High-Performance Web Server</title> +</head> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<h1 ALIGN="CENTER">Hints on Running a High-Performance Web Server</H1> + +Running Apache on a heavily loaded web server, one often encounters +problems related to the machine and OS configuration. "Heavy" is +relative, of course - but if you are seeing more than a couple hits +per second on a sustained basis you should consult the pointers on +this page. In general the suggestions involve how to tune your kernel +for the heavier TCP load, hardware/software conflicts that arise, etc. + +<UL> +<LI><A HREF="#AUX">A/UX (Apple's UNIX)</A> +<LI><A HREF="#BSD">BSD-based (BSDI, FreeBSD, etc)</A> +<LI><A HREF="#DEC">Digital UNIX</A> +<LI><A HREF="#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> + +<H3><A NAME="AUX"> +A/UX (Apple's UNIX) +</A></H3> + +If you are running Apache on A/UX, a page that gives some helpful +performance hints (concerning the <I>listen()</I> queue and using +virtual hosts) +<A HREF="http://www.jaguNET.com/apache.html">can be found here</A> + +<P><HR> + +<H3><A NAME="BSD"> +BSD-based (BSDI, FreeBSD, etc) +</A></H3> + +<A HREF="perf-bsd44.html#initial">Quick</A> and +<A HREF="perf-bsd44.html#detail">detailed</A> +performance tuning hints for BSD-derived systems. + +<P><HR> + +<H3><A NAME="DEC"> +Digital UNIX +</A></H3> + +<UL> + <LI><A HREF="http://www.digital.com/info/internet/document/ias/tuning.html">DIGITAL + UNIX Tuning Parameters for Web Servers</A> + <LI>We have some <A HREF="perf-dec.html">newsgroup postings</A> on how to tune + Digital UNIX 3.2 and 4.0. +</UL> + +<P><HR> + +<H3><A NAME="Linux"> +Linux +</A></H3> + +The most common problem on Linux shows up on heavily-loaded systems +where the whole server will appear to freeze for a couple of minutes +at a time, and then come back to life. This has been traced to a +listen() queue overload - certain Linux implementations have a low +value set for the incoming connection queue which can cause problems. +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> + +<H3><A NAME="SGI"> +SGI +</A></H3> + +<UL> +<LI><A HREF="http://www.sgi.com/Products/WebFORCE/Resources/res_TuningGuide.html"> +WebFORCE Web Server Tuning Guidelines for IRIX 5.3, +<http://www.sgi.com/Products/WebFORCE/Resources/res_TuningGuide.html></A> +</UL> + +<P><HR> + +<H3><A NAME="Solaris"> +Solaris 2.4 +</A></H3> + +The Solaris 2.4 TCP implementation has a few inherent limitations that +only became apparent under heavy loads. This has been fixed to some +extent in 2.5 (and completely revamped in 2.6), but for now consult +the following URL for tips on how to expand the capabilities if you +are finding slowdowns and lags are hurting performance. + +<UL> + +<LI><A href="http://www.sun.com/sun-on-net/performance.html">Sun Performance Information</a> +</UL> + +<P><HR> + +<H3><A NAME="SunOS"> +SunOS 4.x +</A></H3> + +More information on tuning SOMAXCONN on SunOS can be found at +<A HREF="http://www.islandnet.com/~mark/somaxconn.html"> +http://www.islandnet.com/~mark/somaxconn.html</A>. + +<P><HR> + +<H3>More welcome!</H3> + +If you have tips to contribute, send mail to <a +href="mailto:brian@organic.com">brian@organic.com</a> + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</body></html> + diff --git a/usr.sbin/httpd/htdocs/manual/misc/security_tips.html b/usr.sbin/httpd/htdocs/manual/misc/security_tips.html new file mode 100644 index 00000000000..20942181fa0 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/misc/security_tips.html @@ -0,0 +1,198 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache HTTP Server: Security Tips</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Security Tips for Server Configuration</H1> + +<hr> + +<P>Some hints and tips on security issues in setting up a web server. Some of +the suggestions will be general, others specific to Apache. + +<HR> + +<H2>Permissions on Log File Directories</H2> +<P>When Apache starts, it opens the log files as the user who started the +server before switching to the user defined in the +<a href="../mod/core.html#user"><b>User</b></a> directive. Anyone who +has write permission for the directory where any log files are +being written to can append pseudo-arbitrary data to any file on the +system which is writable by the user who starts Apache. Since the +server is normally started by root, you should <EM>NOT</EM> give anyone +write permission to the directory where logs are stored unless you +want them to have root access. +<P> +<HR> +<H2>Server Side Includes</H2> +<P>Server side includes (SSI) can be configured so that users can execute +arbitrary programs on the server. That thought alone should send a shiver +down the spine of any sys-admin.<p> + +One solution is to disable that part of SSI. To do that you use the +IncludesNOEXEC option to the <A HREF="../mod/core.html#options">Options</A> +directive.<p> + +<HR> + +<H2>Non Script Aliased CGI</H2> +<P>Allowing users to execute <B>CGI</B> scripts in any directory should only +be considered if; +<OL> + <LI>You trust your users not to write scripts which will deliberately or +accidentally expose your system to an attack. + <LI>You consider security at your site to be so feeble in other areas, as to +make one more potential hole irrelevant. + <LI>You have no users, and nobody ever visits your server. +</OL><p> +<HR> + +<H2>Script Alias'ed CGI</H2> +<P>Limiting <B>CGI</B> to special directories gives the admin control over +what goes into those directories. This is inevitably more secure than +non script aliased CGI, but <strong>only if users with write access to the +directories are trusted</strong> or the admin is willing to test each new CGI +script/program for potential security holes.<P> + +Most sites choose this option over the non script aliased CGI approach.<p> + +<HR> +<H2>CGI in general</H2> +<P>Always remember that you must trust the writers of the CGI script/programs +or your ability to spot potential security holes in CGI, whether they were +deliberate or accidental.<p> + +All the CGI scripts will run as the same user, so they have potential to +conflict (accidentally or deliberately) with other scripts e.g. +User A hates User B, so he writes a script to trash User B's CGI +database. One program which can be used to allow scripts to run +as different users is <A HREF="../suexec.html">suEXEC</A> which is +included with Apache as of 1.2 and is called from special hooks in +the Apache server code. Another popular way of doing this is with +<A HREF="http://wwwcgi.umr.edu/~cgiwrap/">CGIWrap</A>. <P> + +<HR> + + +<H2>Stopping users overriding system wide settings...</H2> +<P>To run a really tight ship, you'll want to stop users from setting +up <CODE>.htaccess</CODE> files which can override security features +you've configured. Here's one way to do it...<p> + +In the server configuration file, put +<blockquote><code> +<Directory /> <br> +AllowOverride None <br> +Options None <br> +allow from all <br> +</Directory> <br> +</code></blockquote> + +Then setup for specific directories<P> + +This stops all overrides, Includes and accesses in all directories apart +from those named.<p> +<HR> +<H2> + Protect server files by default +</H2> +<P> +One aspect of Apache which is occasionally misunderstood is the feature +of default access. That is, unless you take steps to change it, if the +server can find its way to a file through normal URL mapping rules, it +can serve it to clients. +</P> +<P> +For instance, consider the following example: +</P> +<OL> + <LI><SAMP># cd /; ln -s / public_html</SAMP> + </LI> + <LI>Accessing <SAMP>http://localhost/~root/</SAMP> + </LI> +</OL> +<P> +This would allow clients to walk through the entire filesystem. To work +around this, add the following block to your server's configuration: +</P> +<PRE> + <Directory /> + Order deny,allow + Deny from all + </Directory> +</PRE> +<P> +This will forbid default access to filesystem locations. Add +appropriate +<A + HREF="../mod/core.html#directory" +><SAMP><Directory></SAMP></A> +blocks to allow access only +in those areas you wish. For example, +</P> +<PRE> + <Directory /usr/users/*/public_html> + Order deny,allow + Allow from all + </Directory> + <Directory /usr/local/httpd> + Order deny,allow + Allow from all + </Directory> +</PRE> +<P> +Pay particular attention to the interactions of +<A + HREF="../mod/core.html#location" +><SAMP><Location></SAMP></A> +and +<A + HREF="../mod/core.html#directory" +><SAMP><Directory></SAMP></A> +directives; for instance, even if <SAMP><Directory /></SAMP> +denies access, a <SAMP><Location /></SAMP> directive might +overturn it. +</P> +<P> +Also be wary of playing games with the +<A + HREF="../mod/mod_userdir.html#userdir" +>UserDir</A> +directive; setting it to something like <SAMP>"./"</SAMP> +would have the same effect, for root, as the first example above. + +<HR> +<P>Please send any other useful security tips to The Apache Group +by filling out a +<A HREF="http://www.apache.org/bugdb.cgi">problem report</A>, or by +sending mail to +<A HREF="mailto:apache-bugs@mail.apache.org">apache-bugs@mail.apache.org</A> +<p> +<HR> + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/misc/vif-info.html b/usr.sbin/httpd/htdocs/manual/misc/vif-info.html new file mode 100644 index 00000000000..f81190e2c35 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/misc/vif-info.html @@ -0,0 +1,412 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML><HEAD> +<TITLE>Configuring Multiple IP Addresses</TITLE> +</HEAD> +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Configuring Multiple IP Addresses</H1> + +<PRE> +This material is originally from John Ioannidis (ji@polaris.ctr.columbia.edu) +I have condensed it some and applied some corrections for SunOS 4.1.x +courtesy of Chuck Smoko (csmoko@relay.nswc.navy.mil). + +Bob Baggerman (bob@bizweb.com) +12 Jan 94 + +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +John Ionnidis writes: + +This is a topic that comes up once in a while on comp.protocols.tcp-ip +and other newsgroups. The question is, how to get a machine with one +network interface to respond to more than one IP addresses. + +I have a solution than might suit you. For my doctoral work (there's +a paper about it in this year's ('91) SIGCOMM, also available for +anonymous FTP from cs.columbia.edu:/pub/ji/sigcomm*.ps.Z), I've +developed what I call the "Virtual Interface" (VIF). To the networking +code, it looks like an interface. It gets ifattach()ed when you open +the /dev/vif* device, and then you can ifconfig it as you like. It +does not have an if_input procedure; it only has an if_output. Packets +that it receives (from higher-level protocols) which have its +IP address, it simply loops back (like any well-behaved if driver). +Packets that it receives that are destined for some other address, it +encapsulates in an encapsulation protocol I call IPIP (IP-within-IP, +protocol number IPPROTO_IPIP == 94), and sends it to another machine +that groks that encapsulation protocol. This feature you won't need, +but here's how to have multiple IP addresses on a machine with a +single real interface: + +Let's say your primary interface's IP address is 198.3.2.1, and you +also want it to respond to addresses 198.4.3.2 and 198.5.4.3 (note +that these are three distinct class C addresses in three distinct +class C nets). Here are the ifconfigs: + + ifconfig le0 198.3.2.1 up -trailers # config primary interface + + ifconfig vif0 198.4.3.2 up # config first virtual interface + route delete net 198.4.3 198.4.3.2 # delete spurious route + route add host 198.4.3.2 198.4.3.2 0 # add route for this i/f + + ifconfig vif1 198.5.4.3 up # config second virtual interface + route delete net 198.5.4 198.5.4.3 # delete spurious route + route add host 198.5.4.3 198.5.4.3 0 # add route for this i/f + +The route deletes are needed because the ifconfig creates a default +route to the interface's network, which can cause problems; all that's +needed is the (host) route to the interface's address. + +Now, get le0's ethernet address (say, 8:0:20:3:2:1), and add the +following static ARP entries: + + arp -s 198.4.3.2 8:0:20:3:2:1 pub + arp -s 198.5.4.3 8:0:20:3:2:1 pub + +This will cause any ARP requests for the VIF addresses to be replied +with your machine's ethernet address. + +Now, make sure your default route is to your segment's gateway, +through the real interface. Finally, make sure your routers and/or +hosts on the same segment as yours know that 198.4.3.2 and 198.5.4.3 +are on that cable. + +Here's what you've accomplished. + +ARP requests for any of your host's addresses will be replied to with +the host's ethernet address (the real one, because that's what it is, +the virtual ones because of the public static arp entries). Packets +reaching your host with any of these addresses will be accepted by the +ip_input routine because they match the address of one of the host's +interfaces. Packets leaving your host can have any of its addresses +(real and virtual). + +The code for vif follows. To use it, put the stuff in netinet/if_vif.c +and netinet/if_vif.h, configure your kernel with the number of +virtual interfaces you want using a line like: + +pseudo-device vif4 # Virtual IP interface + +in your configuration file, and the line + +netinet/if_vif.c optional vif device-driver + +in the "files" file. Also, add the appropriate entries in conf.c, so +that you can access the if_attach() routine when you open the device: + + +-------------------------- conf.c------------------------------------------ + +add this in the appropriate place in the headers of conf.c: + +-------------------- +#include "vif.h" +#if NVIF > 0 +int vifopen(), vifclose(), vifread(), vifwrite(), vifselect(), vifioctl(); +#else +#define vifopen nodev +#define vifclose nodev +#define vifread nodev +#define vifwrite nodev +#define vifselect nodev +#define vifioctl nodev +#endif +-------------------- + +then, way down in the definition for cdevsw[]: + +-------------------- + vifopen, vifclose, vifread, vifwrite, /*14*/ + vifioctl, nodev, nodev, 0, + 0, nodev, +-------------------- + +Make sure you remember the correct major device number, 14 in this case! + +--------------------------------------------------------------------------- + +Finally, here's the code. It has the tunneling pieces removed (you +need more code to use that anyway), and it comes from a Mach 2.6 +kernel; it should compile on any Berkeley-derived unix with minor +changes (most likely only in the includes). + +---------------------netinet/if_vif.h-------------------------------------- +typedef struct +{ + struct ifnet vif_if; + struct ifnet *vif_sif; /* slave interface */ + int vif_flags; +} vif_softc_t; + +#define VIFMTU (1024+512) +--------------------------------------------------------------------------- + +and + +---------------------netinet/if_vif.c-------------------------------------- +/* + * Virtual IP interface module. + */ + +#include "param.h" +#include "../sys/systm.h" +#include "../sys/mbuf.h" +#include "../sys/socket.h" +#include "../sys/errno.h" +#include "../sys/ioctl.h" + +#include "../net/if.h" +#include "../net/netisr.h" +#include "../net/route.h" + +#ifdef INET +#include "../netinet/in.h" +#include "../netinet/in_systm.h" +#include "../netinet/in_var.h" +#include "../netinet/ip.h" +#endif + +#include "in_pcb.h" +#include "vif.h" + +typedef struct +{ + struct ifnet vif_if; + struct ifnet *vif_sif; /* slave interface */ + int vif_flags; +} vif_softc_t; + +#define VIFMTU (1024+512) + +vif_softc_t vif_softc[NVIF]; + +int vifs_inited = 0; + + +vifattach() +{ + register int i; + register struct ifnet *ifp; + int vifoutput(), vififioctl(); + + for (i=0; i<NVIF; i++) + { + ifp = &vif_softc[i].vif_if; + ifp->if_name = "vif"; + ifp->if_unit = i; + ifp->if_mtu = VIFMTU; + ifp->if_flags = IFF_LOOPBACK | IFF_NOARP; + ifp->if_ioctl = vififioctl; + ifp->if_output = vifoutput; + if_attach(ifp); + } +} + +vifopen(dev, flag) +int dev, flag; +{ + int unit; + + if (!vifs_inited) + { + vifattach(); + vifs_inited = 1; + printf("vif initialized\n"); + } + + unit = minor(dev); + if ((unit < 0) || (unit >= NVIF)) + { + return ENXIO; + } + + return 0; +} + +vifclose(dev, flag) +int dev, flag; +{ + return 0; +} + +vifread() +{ + return ENXIO; +} + +vifwrite() +{ + return ENXIO; +} + +vifselect() +{ + return ENXIO; +} + +vifoutput(ifp, m0, dst) + struct ifnet *ifp; + register struct mbuf *m0; + struct sockaddr *dst; +{ + int s; + register struct ifqueue *ifq; + struct mbuf *m; + struct sockaddr_in *din; + + if (dst->sa_family != AF_INET) + { + printf("%s%d: can't handle af%d\n", + ifp->if_name, ifp->if_unit, + dst->sa_family); + m_freem(m0); + return (EAFNOSUPPORT); + } + + din = (struct sockaddr_in *)dst; + + if (din->sin_addr.s_addr == IA_SIN(ifp->if_addrlist)->sin_addr.s_addr) + { + /* printf("%s%d: looping\n", ifp->if_name, ifp->if_unit); */ + + /* + * Place interface pointer before the data + * for the receiving protocol. + */ + if (m0->m_off <= MMAXOFF && + m0->m_off >= MMINOFF + sizeof(struct ifnet *)) { + m0->m_off -= sizeof(struct ifnet *); + m0->m_len += sizeof(struct ifnet *); + } else { + MGET(m, M_DONTWAIT, MT_HEADER); + if (m == (struct mbuf *)0) + return (ENOBUFS); + m->m_off = MMINOFF; + m->m_len = sizeof(struct ifnet *); + m->m_next = m0; + m0 = m; + } + *(mtod(m0, struct ifnet **)) = ifp; + s = splimp(); + ifp->if_opackets++; + ifq = &ipintrq; + if (IF_QFULL(ifq)) { + IF_DROP(ifq); + m_freem(m0); + splx(s); + return (ENOBUFS); + } + IF_ENQUEUE(ifq, m0); + schednetisr(NETISR_IP); + ifp->if_ipackets++; + splx(s); + return (0); + } + + return EHOSTUNREACH; +} + +/* + * Process an ioctl request. + */ +/* ARGSUSED */ +vififioctl(ifp, cmd, data) + register struct ifnet *ifp; + int cmd; + caddr_t data; +{ + int error = 0; + + switch (cmd) { + + case SIOCSIFADDR: + ifp->if_flags |= IFF_UP; + /* + * Everything else is done at a higher level. + */ + break; + + default: + error = EINVAL; + } + return (error); +} + +vifioctl(dev, cmd, arg, mode) +dev_t dev; +int cmd; +caddr_t arg; +int mode; +{ + int unit; + + unit = minor(dev); + if ((unit < 0) || (unit >= NVIF)) + return ENXIO; + + return EINVAL; +} +---------------------------------------------------------------------------- + +To use it, compile your kernel, and reboot. Then create the vif +device: + +# mknod /dev/vif c 14 0 + +(or whatever major number it ended up being), and echo something into +it: + +# echo > /dev/vif + +This will cause the device to be opened, which will if_attach the +interfaces. If you feel like playing with the code, you may want to +kmem_alloc() the vif_softc structrure at open time, and use the minor +number of the device to tell it how many interfaces to create. + +Now you can go ahead and ifconfig etc. + +I'll be happy to answer minor questions, and hear about success and +failure stories, but I cannot help you if you don't already know how +to hack kernels. + +Good luck! + +/ji + +In-Real-Life: John "Heldenprogrammer" Ioannidis +E-Mail-To: ji@cs.columbia.edu +V-Mail-To: +1 212 854 8120 +P-Mail-To: 450 Computer Science \n Columbia University \n New York, NY 10027 +</PRE> + +<P> + +Note: there is also a <A +HREF="http://www.multihost.com/">commercial-product-turned-freeware +called "Col. Patch"</A> which does this as a loadable kernel module +for SunOS 4.1.3_U1. + +<P> + +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> diff --git a/usr.sbin/httpd/htdocs/manual/misc/windoz_keepalive.html b/usr.sbin/httpd/htdocs/manual/misc/windoz_keepalive.html new file mode 100644 index 00000000000..a321aaf6098 --- /dev/null +++ b/usr.sbin/httpd/htdocs/manual/misc/windoz_keepalive.html @@ -0,0 +1,63 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>MS Windows Netscape 3.0b4 KeepAlive problem solved</TITLE> +</HEAD> +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.2 + </H3> +</DIV> + +<H1 ALIGN="CENTER">HTTP/1.1 KeepAlive problems with Netscape 3.0</H1> + +<PRE> +Date: Mon, 1 Jul 1996 16:03:06 -0700 (PDT) +From: Alexei Kosut <akosut@organic.com> +To: Apache Group +Subject: Re: keepalive and windoze + +Good news and good news (of a sort).. + +I was able to snag a Windows 95 machine here at Organic, and tried out +some things: + +1) On Netscape 3.0b4, I was able to reproduce the bug, each and every +time. It's really simple: go to the Network Setup panel. Set it to +"Connect Every Time" and only let it have 1 connection at once (this may +not be neccessary, but it's helpeful). Then load an image that's +kept-alive. Then wait until the connection times out (this depends on the +server - 10-30 seconds, except for MIIS, which never times out, near as I +can tell). Then hit reload. It will hang. (actually, once it crashed). + +2) This happens with all forms of server. Apache 1.1, Netscape 2.0, +Spyglass 1.2, NCSA 1.5 (although, as stated, I couldn't test MIIS). + +3) Netscape 3.0b5 does, indeed, *not* have this bug. At least, I couldn't +get it to perform such. Yipee. + +So, we just put up a note on the web page. Make sure we say that all the +servers have the bug, it's a Windows bug, and Netscape Navigator 3.0b5 +works around it. That way, no one can yell at us. Yes? + +-- Alexei Kosut <akosut@organic.com> The Apache HTTP Server + http://www.nueva.pvt.k12.ca.us/~akosut/ http://www.apache.org/ +</PRE> +<HR> +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.2 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY></HTML> |