Dimensions of Negotiation
- -| Dimension - | Notes - |
|---|---|
| Media Type - | Browser indicates preferences with the Accept header field. Each item -can have an associated quality factor. Variant description can also -have a quality factor (the "qs" parameter). - |
| Language - | Browser indicates preferences with the Accept-Language header field. -Each item can have a quality factor. Variants can be associated with none, one -or more than one language. - |
| Encoding - | Browser indicates preference with the Accept-Encoding header field. -Each item can have a quality factor. - |
| Charset - | Browser indicates preference with the Accept-Charset header field. -Each item can have a quality factor. -Variants can indicate a charset as a parameter of the media type. - |
Apache Negotiation Algorithm
- --Apache can use the following algorithm to select the 'best' variant -(if any) to return to the browser. This algorithm is not -further configurable. It operates as follows: - -
-
-
- First, for each dimension of the negotiation, check the appropriate -Accept* header field and assign a quality to each -variant. If the Accept* header for any dimension implies that this -variant is not acceptable, eliminate it. If no variants remain, go -to step 4. - -
- Select the 'best' variant by a process of elimination. Each of the
-following tests is applied in order. Any variants not selected at each
-test are eliminated. After each test, if only one variant remains,
-select it as the best match and proceed to step 3. If more than one
-variant remains, move on to the next test.
-
-
-
-
- Multiply the quality factor from the Accept header with the - quality-of-source factor for this variant's media type, and select - the variants with the highest value. - -
- Select the variants with the highest language quality factor. - -
- Select the variants with the best language match, using either the
- order of languages in the Accept-Language header (if present), or else
- else the order of languages in the
LanguagePriority- directive (if present). - - - Select the variants with the highest 'level' media parameter - (used to give the version of text/html media types). - -
- Select variants with the best charset media parameters,
- as given on the Accept-Charset header line. Charset ISO-8859-1
- is acceptable unless explicitly excluded. Variants with a
-
text/*media type but not explicitly associated - with a particular charset are assumed to be in ISO-8859-1. - - - Select those variants which have associated - charset media parameters that are not ISO-8859-1. - If there are no such variants, select all variants instead. - -
- Select the variants with the best encoding. If there are - variants with an encoding that is acceptable to the user-agent, - select only these variants. Otherwise if there is a mix of encoded - and non-encoded variants, select only the unencoded variants. - If either all variants are encoded or all variants are not encoded, - select all variants. - -
- Select the variants with the smallest content length. - -
- Select the first variant of those remaining. This will be either the - first listed in the type-map file, or when variants are read from - the directory, the one whose file name comes first when sorted using - ASCII code order. - -
- The algorithm has now selected one 'best' variant, so return - it as the response. The HTTP response header Vary is set to indicate the - dimensions of negotiation (browsers and caches can use this - information when caching the resource). End. - -
- To get here means no variant was selected (because none are acceptable - to the browser). Return a 406 status (meaning "No acceptable representation") - with a response body consisting of an HTML document listing the - available variants. Also set the HTTP Vary header to indicate the - dimensions of variance. - -
Fiddling with Quality Values
- --Apache sometimes changes the quality values from what would be -expected by a strict interpretation of the Apache negotiation -algorithm above. This is to get a better result from the algorithm for -browsers which do not send full or accurate information. Some of the -most popular browsers send Accept header information which would -otherwise result in the selection of the wrong variant in many -cases. If a browser sends full and correct information these fiddles -will not be applied. -
- -
Media Types and Wildcards
- --The Accept: request header indicates preferences for media types. It -can also include 'wildcard' media types, such as "image/*" or "*/*" -where the * matches any string. So a request including: -
- Accept: image/*, */* -- -would indicate that any type starting "image/" is acceptable, -as is any other type (so the first "image/*" is redundant). Some -browsers routinely send wildcards in addition to explicit types they -can handle. For example: -
- Accept: text/html, text/plain, image/gif, image/jpeg, */* -- -The intention of this is to indicate that the explicitly -listed types are preferred, but if a different representation is -available, that is ok too. However under the basic algorithm, as given -above, the */* wildcard has exactly equal preference to all the other -types, so they are not being preferred. The browser should really have -sent a request with a lower quality (preference) value for *.*, such -as: -
- Accept: text/html, text/plain, image/gif, image/jpeg, */*; q=0.01 -- -The explicit types have no quality factor, so they default to a -preference of 1.0 (the highest). The wildcard */* is given -a low preference of 0.01, so other types will only be returned if -no variant matches an explicitly listed type. -
- -If the Accept: header contains no q factors at all, Apache sets -the q value of "*/*", if present, to 0.01 to emulate the desired -behavior. It also sets the q value of wildcards of the format -"type/*" to 0.02 (so these are preferred over matches against -"*/*". If any media type on the Accept: header contains a q factor, -these special values are not applied, so requests from browsers -which send the correct information to start with work as expected. - -
Variants with no Language
- --If some of the variants for a particular resource have a language -attribute, and some do not, those variants with no language -are given a very low language quality factor of 0.001.
- -The reason for setting this language quality factor for -variant with no language to a very low value is to allow -for a default variant which can be supplied if none of the -other variants match the browser's language preferences. - -For example, consider the situation with three variants: - -
-
-
- foo.en.html, language en -
- foo.fr.html, language en -
- foo.html, no language -
-The meaning of a variant with no language is that it is -always acceptable to the browser. If the request Accept-Language -header includes either en or fr (or both) one of foo.en.html -or foo.fr.html will be returned. If the browser does not list -either en or fr as acceptable, foo.html will be returned instead. - -
Extensions to Transparent Content Negotiation
- -Apache extends the transparent content negotiation protocol (RFC 2295) -as follows. A new {encoding ..} element is used in
-variant lists to label variants which are available with a specific
-content-encoding only. The implementation of the
-RVSA/1.0 algorithm (RFC 2296) is extended to recognize encoded
-variants in the list, and to use them as candidate variants whenever
-their encodings are acceptable according to the Accept-Encoding
-request header. The RVSA/1.0 implementation does not round computed
-quality factors to 5 decimal places before choosing the best variant.
-
-Note on hyperlinks and naming conventions
- --If you are using language negotiation you can choose between -different naming conventions, because files can have more than one -extension, and the order of the extensions is normally irrelevant -(see mod_mime documentation for details). -
-A typical file has a MIME-type extension (e.g., html), -maybe an encoding extension (e.g., gz), and of course a -language extension (e.g., en) when we have different -language variants of this file. - -
-Examples: -
-
-
- foo.en.html -
- foo.html.en -
- foo.en.html.gz -
-Here some more examples of filenames together with valid and invalid -hyperlinks: -
- -| Filename | -Valid hyperlink | -Invalid hyperlink | -
|---|---|---|
| foo.html.en | -foo - foo.html |
- - | -
| foo.en.html | -foo | -foo.html | -
| foo.html.en.gz | -foo - foo.html |
- foo.gz - foo.html.gz |
-
| foo.en.html.gz | -foo | -foo.html - foo.html.gz - foo.gz |
-
| foo.gz.html.en | -foo - foo.gz - foo.gz.html |
- foo.html | -
| foo.html.gz.en | -foo - foo.html - foo.html.gz |
- foo.gz | -
-Looking at the table above you will notice that it is always possible to -use the name without any extensions in an hyperlink (e.g., foo). -The advantage is that you can hide the actual type of a -document rsp. file and can change it later, e.g., from html -to shtml or cgi without changing any -hyperlink references. - -
-If you want to continue to use a MIME-type in your hyperlinks (e.g. -foo.html) the language extension (including an encoding extension -if there is one) must be on the right hand side of the MIME-type extension -(e.g., foo.html.en). - - -
Note on Caching
- --When a cache stores a representation, it associates it with the request URL. -The next time that URL is requested, the cache can use the stored -representation. But, if the resource is negotiable at the server, -this might result in only the first requested variant being cached and -subsequent cache hits might return the wrong response. To prevent this, -Apache normally marks all responses that are returned after content negotiation -as non-cacheable by HTTP/1.0 clients. Apache also supports the HTTP/1.1 -protocol features to allow caching of negotiated responses.
- -For requests which come from a HTTP/1.0 compliant client (either a -browser or a cache), the directive CacheNegotiatedDocs can be -used to allow caching of responses which were subject to negotiation. -This directive can be given in the server config or virtual host, and -takes no arguments. It has no effect on requests from HTTP/1.1 clients. - - - - diff --git a/docs/manual/custom-error.html.en b/docs/manual/custom-error.html.en deleted file mode 100644 index 09604ea972b..00000000000 --- a/docs/manual/custom-error.html.en +++ /dev/null @@ -1,177 +0,0 @@ - - -
-Custom error responses
- --
-
-
- Purpose - -
- Additional functionality. Allows webmasters to configure the response of
- Apache to some error or problem.
-
-
Customizable responses can be defined to be activated in the - event of a server detected error or problem. - -
e.g. if a script crashes and produces a "500 Server Error" - response, then this response can be replaced with either some - friendlier text or by a redirection to another URL (local or - external). -
- -
- Old behavior - -
- NCSA httpd 1.3 would return some boring old error/problem message
- which would often be meaningless to the user, and would provide no
- means of logging the symptoms which caused it.
- -- -
- New behavior - -
- The server can be asked to;
-
-
-
- Display some other text, instead of the NCSA hard coded messages, or -
- redirect to a local URL, or -
- redirect to an external URL. -
Redirecting to another URL can be useful, but only if some information - can be passed which can then be used to explain and/or log the - error/problem - more clearly. - -
To achieve this, Apache will define new CGI-like environment - variables, e.g. - -
- --REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/x-xbitmap, image/jpeg
-REDIRECT_HTTP_USER_AGENT=Mozilla/1.1b2 (X11; I; HP-UX A.09.05 9000/712)
-REDIRECT_PATH=.:/bin:/usr/local/bin:/etc
-REDIRECT_QUERY_STRING=
-REDIRECT_REMOTE_ADDR=121.345.78.123
-REDIRECT_REMOTE_HOST=ooh.ahhh.com
-REDIRECT_SERVER_NAME=crash.bang.edu
-REDIRECT_SERVER_PORT=80
-REDIRECT_SERVER_SOFTWARE=Apache/0.8.15
-REDIRECT_URL=/cgi-bin/buggy.pl
-note the
REDIRECT_prefix. - -At least
REDIRECT_URLandREDIRECT_QUERY_STRING- will - be passed to the new URL (assuming it's a cgi-script or a cgi-include). - The - other variables will exist only if they existed prior to the - error/problem. - None of these will be set if your ErrorDocument is an - external redirect (i.e., anything starting with a - scheme name - likehttp:, even if it refers to the same host as the - server).- -
- Configuration - -
- Use of "ErrorDocument" is enabled for .htaccess files when the
- "FileInfo" override is
- allowed.
-
-
Here are some examples... - -
- --ErrorDocument 500 /cgi-bin/crash-recover
-ErrorDocument 500 "Sorry, our script crashed. Oh dear
-ErrorDocument 500 http://xxx/
-ErrorDocument 404 /Lame_excuses/not_found.html
-ErrorDocument 401 /Subscription/how_to_subscribe.html -The syntax is, - -
ErrorDocument-<3-digit-code> action - -where the action can be, - -
-
-
- Text to be displayed. Prefix the text with a quote ("). Whatever - follows the quote is displayed. Note: the (") prefix isn't - displayed. - -
- An external URL to redirect to. - -
- A local URL to redirect to. - -
- -
Custom error responses and redirects
- --
-
-
- Purpose - -
- Apache's behavior to redirected URLs has been modified so that additional
- environment variables are available to a script/server-include.
- -
- Old behavior - -
- Standard CGI vars were made available to a script which has been
- redirected to. No indication of where the redirection came from was
- provided.
-
-
- -
- New behavior -
-
-
-A new batch of environment variables will be initialized for use by a
-script which has been redirected to. Each new variable will have the
-prefix
REDIRECT_.REDIRECT_environment -variables are created from the CGI environment variables which existed -prior to the redirect, they are renamed with aREDIRECT_-prefix, i.e.,HTTP_USER_AGENTbecomes -REDIRECT_HTTP_USER_AGENT. In addition to these new -variables, Apache will defineREDIRECT_URLand -REDIRECT_STATUSto help the script trace its origin. -Both the original URL and the URL being redirected to can be logged in -the access log. - -
-If the ErrorDocument specifies a local redirect to a CGI script, the script -should include a "Status:" header field in its output -in order to ensure the propagation all the way back to the client -of the error condition that caused it to be invoked. For instance, a Perl -ErrorDocument script might include the following: -
-
- :
- print "Content-type: text/html\n";
- printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"};
- :
-
--If the script is dedicated to handling a particular error condition, such as -404 Not Found, it can use the specific code and -error text instead. -
- - - - diff --git a/docs/manual/developer/API.html b/docs/manual/developer/API.html deleted file mode 100644 index bf0fb77d7a1..00000000000 --- a/docs/manual/developer/API.html +++ /dev/null @@ -1,1153 +0,0 @@ - - -Apache API notes
- -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 might 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). -- -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.
- -Finally, here's an outline, to give you some bare idea of what's -coming up, and in what order: - -
-
-
- Basic concepts. - -
- How handlers work - -
- Resource allocation and resource pools -
- Configuration, commands and the like - -
Basic concepts.
- -We begin with an overview of the basic concepts behind the -API, and how they are manifested in the code. - -Handlers, Modules, and Requests
- -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: - --
-
- URI -> Filename translation -
- Auth ID checking [is the user who they say they are?] -
- Auth access checking [is the user authorized here?] -
- Access checking other than auth -
- Determining MIME type of the object requested -
- `Fixups' --- there aren't any of these yet, but the phase is
- intended as a hook for possible extensions like
-
SetEnv, which don't really fit well elsewhere. - - Actually sending a response back to the client. -
- Logging the request -
-
-
- Handle the request, and indicate that it has done so
- by returning the magic constant
OK. - - Decline to handle the request, by returning the magic
- integer constant
DECLINED. In this case, the - server behaves in all respects as if the handler simply hadn't - been there. - - 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. -
*/* (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).
-
-The handlers themselves are functions of one argument (a
-request_rec structure. vide infra), which returns an
-integer, as above.
- -
A brief tour of a module
- -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 theScriptAlias 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.
-
-Let's begin with handlers. In order to handle the CGI scripts, the
-module declares a response handler for them. Because of
-ScriptAlias, it also has handlers for the name
-translation phase (to recognize ScriptAliased URIs), the
-type-checking phase (any ScriptAliased request is typed
-as a CGI script).
-
-The module needs to maintain some per (virtual)
-server information, namely, the ScriptAliases 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
-ScriptAliases declared).
-
-Finally, this module contains code to handle the
-ScriptAlias command itself. This particular module only
-declares one command, but there could be more, so modules have
-command tables which declare their commands, and describe
-where they are permitted, and how they are to be invoked.
-
-A final note on the declared types of the arguments of some of these
-commands: a pool is a pointer to a resource pool
-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, en masse, without anyone having to write explicit code to
-track them all down and dispose of them. Also, a
-cmd_parms 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 ScriptAlias).
-
-With no further ado, the module itself:
-
-
-/* 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 */
-};
-
-
-How handlers work
- -The sole argument to handlers is arequest_rec 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 request_rec structure.- -
A brief tour of the request_rec
-
-The request_rec 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.- -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).
-
-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
-ap_table_get and ap_table_set routines.
-
- Note that the Content-type header value cannot be - set by module content-handlers using the ap_table_*() - routines. Rather, it is set by pointing the content_type - field in the request_rec structure to an appropriate - string. E.g., --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- r->content_type = "text/html"; --
.htaccess files or
-<Directory> 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 server_rec
-data structure pointed to by the request_rec, which
-contains per (virtual) server configuration data.- -Here is an abridged declaration, giving the fields most commonly used:
- -
-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 */
-
-};
-
-
-
-Where request_rec structures come from
- -Mostrequest_rec structures are built by reading an HTTP
-request from a client, and filling in the fields. However, there are
-a few exceptions:
-
--
-
- If the request is to an imagemap, a type map (i.e., a
-
*.varfile), 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 internal redirect, constructing a new -request_recfor the new URI, and processing it - almost exactly as if the client had requested the new URI - directly.- -
- If some handler signaled an error, and an
-
ErrorDocumentis in scope, the same internal - redirect machinery comes into play.- -
- 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.
- - Such handlers can construct a sub-request, using the - functions
ap_sub_req_lookup_file, -ap_sub_req_lookup_uri, and -ap_sub_req_method_uri; these construct a new -request_recstructure 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).- - (Server-side includes work by building sub-requests and then - actually invoking the response handler for them, via the - function
ap_run_sub_req). -
Handling requests, declining, and returning error - codes
- -As discussed above, each handler, when invoked to handle a particular -request_rec, has to return an int to
-indicate what happened. That can either be
-
--
-
- OK --- the request was handled successfully. This may or may - not terminate the phase. -
- DECLINED --- no erroneous condition exists, but the module - declines to handle the phase; the server tries to find another. -
- an HTTP error code, which aborts handling of the request. -
REDIRECT, then
-the module should put a Location in the request's
-headers_out, to indicate where the client should be
-redirected to. - -
Special considerations for response - handlers
- -Handlers for most phases do their work by simply setting a few fields -in therequest_rec 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.
-
-They should begin by sending an HTTP response header, using the
-function ap_send_http_header. (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 header_only, that's all they should
-do; they should return after that, without attempting any further
-output.
-
-Otherwise, they should produce a request body which responds to the
-client as appropriate. The primitives for this are ap_rputc
-and ap_rprintf, for internally generated output, and
-ap_send_fd, to copy the contents of some FILE *
-straight to the client.
-
-At this point, you should more or less understand the following piece
-of code, which is the handler which handles GET requests
-which have no more specific handler; it also shows how conditional
-GETs can be handled, if it's desirable to do so in a
-particular response handler --- ap_set_last_modified checks
-against the If-modified-since 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
-ap_set_content_length, but it returns an error code for
-symmetry.
- -
-int default_handler (request_rec *r)
-{
- int errstatus;
- FILE *f;
-
- if (r->method_number != M_GET) return DECLINED;
- if (r->finfo.st_mode == 0) return NOT_FOUND;
-
- if ((errstatus = ap_set_content_length (r, r->finfo.st_size))
- || (errstatus = ap_set_last_modified (r, r->finfo.st_mtime)))
- return errstatus;
-
- f = fopen (r->filename, "r");
-
- if (f == NULL) {
- log_reason("file permissions deny server access",
- r->filename, r);
- return FORBIDDEN;
- }
-
- register_timeout ("send", r);
- ap_send_http_header (r);
-
- if (!r->header_only) send_fd (f, r);
- ap_pfclose (r->pool, f);
- return OK;
-}
-
-
-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
-ap_internal_redirect, which is how the internal redirection
-machinery discussed above is invoked. A response handler which has
-internally redirected should always return OK.
-
-(Invoking ap_internal_redirect from handlers which are
-not response handlers will lead to serious confusion).
-
-
Special considerations for authentication - handlers
- -Stuff that should be discussed here in detail: - --
-
- Authentication-phase handlers not invoked unless auth is - configured for the directory. -
- Common auth configuration stored in the core per-dir
- configuration; it has accessors
ap_auth_type, -ap_auth_name, andap_requires. - - Common routines, to handle the protocol end of things, at least
- for HTTP basic authentication (
ap_get_basic_auth_pw, - which sets theconnection->userstructure field - automatically, andap_note_basic_auth_failure, which - arranges for the properWWW-Authenticate:header - to be sent back). -
Special considerations for logging handlers
- -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 ofrequest_rec structures which are
-threaded through the r->prev and r->next
-pointers. The request_rec 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).
-
-Resource allocation and resource pools
--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 automatically released when the server is done with -them. -
--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 -resource pool which is allocated for the request. The pool -is a data structure which itself tracks the resources in question. -
--When the request has been processed, the pool is cleared. 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. -
--Server restarts, and allocation of memory and resources for per-server -configuration, are handled in a similar way. There is a -configuration pool, 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. -
-
-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 ap_pfopen, which also
-arranges for the underlying file descriptor to be closed before any
-child processes, such as for CGI scripts, are execed), 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, ap_palloc is generally faster than
-malloc.
-
-We begin here by describing how memory is allocated to pools, and then -discuss how other resources are tracked by the resource pool -machinery. -
-Allocation of memory in pools
-
-Memory is allocated to pools by calling the function
-ap_palloc, which takes two arguments, one being a pointer to
-a resource pool structure, and the other being the amount of memory to
-allocate (in chars). Within handlers for handling
-requests, the most common way of getting a resource pool structure is
-by looking at the pool slot of the relevant
-request_rec; hence the repeated appearance of the
-following idiom in module code:
-
-int my_handler(request_rec *r)
-{
- struct my_structure *foo;
- ...
-
- foo = (foo *)ap_palloc (r->pool, sizeof(my_structure));
-}
-
-
-Note that there is no ap_pfree ---
-ap_palloced memory is freed only when the associated
-resource pool is cleared. This means that ap_palloc does not
-have to do as much accounting as malloc(); all it does in
-the typical case is to round up the size, bump a pointer, and do a
-range check.
-
-(It also raises the possibility that heavy use of ap_palloc
-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 malloc, and try to be sure that all of the memory
-gets explicitly freed, 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).
-
Allocating initialized memory
-
-There are functions which allocate initialized memory, and are
-frequently useful. The function ap_pcalloc has the same
-interface as ap_palloc, but clears out the memory it
-allocates before it returns it. The function ap_pstrdup
-takes a resource pool and a char * as arguments, and
-allocates memory for a copy of the string the pointer points to,
-returning a pointer to the copy. Finally ap_pstrcat is a
-varargs-style function, which takes a pointer to a resource pool, and
-at least two char * arguments, the last of which must be
-NULL. It allocates enough memory to fit copies of each
-of the strings, as a unit; for instance:
-
- ap_pstrcat (r->pool, "foo", "/", "bar", NULL); --
-returns a pointer to 8 bytes worth of memory, initialized to
-"foo/bar".
-
Commonly-used pools in the Apache Web server
--A pool is really defined by its lifetime more than anything else. There -are some static pools in http_main which are passed to various -non-http_main functions as arguments at opportune times. Here they are: -
--
-
- permanent_pool - -
-
-
-
-
- never passed to anything else, this is the ancestor of all pools - -
- - pconf - -
-
-
-
-
- subpool of permanent_pool - -
- created at the beginning of a config "cycle"; exists until the - server is terminated or restarts; passed to all config-time - routines, either via cmd->pool, or as the "pool *p" argument on - those which don't take pools - -
- passed to the module init() functions - -
- - ptemp - -
-
-
-
-
- sorry I lie, this pool isn't called this currently in 1.3, I - renamed it this in my pthreads development. I'm referring to - the use of ptrans in the parent... contrast this with the later - definition of ptrans in the child. - -
- subpool of permanent_pool - -
- created at the beginning of a config "cycle"; exists until the - end of config parsing; passed to config-time routines via - cmd->temp_pool. Somewhat of a "bastard child" because it isn't - available everywhere. Used for temporary scratch space which - may be needed by some config routines but which is deleted at - the end of config. - -
- - pchild - -
-
-
-
-
- subpool of permanent_pool - -
- created when a child is spawned (or a thread is created); lives - until that child (thread) is destroyed - -
- passed to the module child_init functions - -
- destruction happens right after the child_exit functions are - called... (which may explain why I think child_exit is redundant - and unneeded) - -
- - ptrans
-
- -
-
-
-
-
- should be a subpool of pchild, but currently is a subpool of - permanent_pool, see above - -
- cleared by the child before going into the accept() loop to receive - a connection - -
- used as connection->pool - -
- - r->pool - -
-
-
-
-
- for the main request this is a subpool of connection->pool; for - subrequests it is a subpool of the parent request's pool. - -
- exists until the end of the request (i.e., - ap_destroy_sub_req, or - in child_main after process_request has finished) - -
- note that r itself is allocated from r->pool; i.e., - r->pool is - first created and then r is the first thing palloc()d from it - -
-
-For almost everything folks do, r->pool is the pool to use. But you -can see how other lifetimes, such as pchild, are useful to some -modules... such as modules that need to open a database connection once -per child, and wish to clean it up when the child dies. -
--You can also see how some bugs have manifested themself, such as setting -connection->user to a value from r->pool -- in this case -connection exists -for the lifetime of ptrans, which is longer than r->pool (especially if -r->pool is a subrequest!). So the correct thing to do is to allocate -from connection->pool. -
--And there was another interesting bug in mod_include/mod_cgi. You'll see -in those that they do this test to decide if they should use r->pool -or r->main->pool. In this case the resource that they are registering -for cleanup is a child process. If it were registered in r->pool, -then the code would wait() for the child when the subrequest finishes. -With mod_include this could be any old #include, and the delay can be up -to 3 seconds... and happened quite frequently. Instead the subprocess -is registered in r->main->pool which causes it to be cleaned up when -the entire request is done -- i.e., after the output has been sent to -the client and logging has happened. -
-Tracking open files, etc.
-
-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 ap_pfopen, which
-takes a resource pool and two strings as arguments; the strings are
-the same as the typical arguments to fopen, e.g.,
-
- ...
- FILE *f = ap_pfopen (r->pool, r->filename, "r");
-
- if (f == NULL) { ... } else { ... }
-
-
-There is also a ap_popenf routine, which parallels the
-lower-level open system call. Both of these routines
-arrange for the file to be closed when the resource pool in question
-is cleared.
-
-Unlike the case for memory, there are functions to close
-files allocated with ap_pfopen, and ap_popenf,
-namely ap_pfclose and ap_pclosef. (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 ap_pfopen and
-ap_popenf, since to do otherwise could cause fatal errors on
-systems such as Linux, which react badly if the same
-FILE* is closed more than once.
-
-(Using the close 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).
-
Other sorts of resources --- cleanup functions
-
-More text goes here. Describe the the cleanup primitives in terms of
-which the file stuff is implemented; also, spawn_process.
-
--Pool cleanups live until clear_pool() is called: clear_pool(a) recursively -calls destroy_pool() on all subpools of a; then calls all the cleanups for a; -then releases all the memory for a. destroy_pool(a) calls clear_pool(a) -and then releases the pool structure itself. i.e., clear_pool(a) doesn't -delete a, it just frees up all the resources and you can start using it -again immediately. -
-Fine control --- creating and dealing with sub-pools, with a note -on sub-requests
- -On rare occasions, too-free use ofap_palloc() and the
-associated primitives may result in undesirably profligate resource
-allocation. You can deal with such a case by creating a
-sub-pool, 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 is 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
-very large directories. Unnecessary use of the primitives
-discussed here can hair up your code quite a bit, with very little
-gain).
-
-The primitive for creating a sub-pool is ap_make_sub_pool,
-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
-ap_clear_pool and ap_destroy_pool, respectively.
-(The difference is that ap_clear_pool frees resources
-associated with the pool, while ap_destroy_pool 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).
-
-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 ap_sub_req_... functions)
-is ap_destroy_sub_req, 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
-request_rec structure).
-
-(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
-ap_destroy_... functions).
-
-
Configuration, commands and the like
- -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.
-
-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 AddType and
-DefaultType directives, and so forth. In general, the
-governing philosophy is that anything which can be made
-configurable by directory should be; per-server information is
-generally used in the standard set of modules for information like
-Aliases and Redirects which come into play
-before the request is tied to a particular place in the underlying
-file system.
-
-Another requirement for emulating the NCSA server is being able to
-handle the per-directory configuration files, generally called
-.htaccess 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 .htaccess files which might be
-present. The information which is read in then has to be
-merged with the applicable information from the server's own
-config files (either from the <Directory> sections
-in access.conf, or from defaults in
-srm.conf, which actually behaves for most purposes almost
-exactly like <Directory />).
-
-Finally, after having served a request which involved reading
-.htaccess 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.
- -
Per-directory configuration structures
- -Let's look out how all of this plays out inmod_mime.c,
-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
-AddType and AddEncoding commands. These
-commands can appear in .htaccess files, so they must be
-handled in the module's private per-directory data, which in fact,
-consists of two separate tables for MIME types and
-encoding information, and is declared as follows:
-
-
-typedef struct {
- table *forced_types; /* Additional AddTyped stuff */
- table *encoding_types; /* Added with AddEncoding... */
-} mime_dir_config;
-
-
-When the server is reading a configuration file, or
-<Directory> section, which includes one of the MIME
-module's commands, it needs to create a mime_dir_config
-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 NULL for
-srm.conf), and a pointer to a resource pool in which the
-allocation should happen.
-
-(If we are reading a .htaccess 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).
-
-For the MIME module, the per-dir config creation function just
-ap_pallocs the structure above, and a creates a couple of
-tables to fill it. That looks like this:
-
-
-void *create_mime_dir_config (pool *p, char *dummy)
-{
- mime_dir_config *new =
- (mime_dir_config *) ap_palloc (p, sizeof(mime_dir_config));
-
- new->forced_types = ap_make_table (p, 4);
- new->encoding_types = ap_make_table (p, 4);
-
- return new;
-}
-
-
-Now, suppose we've just read in a .htaccess file. We
-already have the per-directory configuration structure for the next
-directory up in the hierarchy. If the .htaccess file we
-just read in didn't have any AddType or
-AddEncoding 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. - -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: - -
-void *merge_mime_dir_configs (pool *p, void *parent_dirv, void *subdirv)
-{
- mime_dir_config *parent_dir = (mime_dir_config *)parent_dirv;
- mime_dir_config *subdir = (mime_dir_config *)subdirv;
- mime_dir_config *new =
- (mime_dir_config *)ap_palloc (p, sizeof(mime_dir_config));
-
- new->forced_types = ap_overlay_tables (p, subdir->forced_types,
- parent_dir->forced_types);
- new->encoding_types = ap_overlay_tables (p, subdir->encoding_types,
- parent_dir->encoding_types);
-
- return new;
-}
-
-
-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 XBITHACK), and for
-those modules, you can just not declare one, and leave the
-corresponding structure slot in the module itself NULL.- -
Command handling
- -Now that we have these structures, we need to be able to figure out -how to fill them. That involves processing the actual -AddType and AddEncoding commands. To find
-commands, the server looks in the module's command table.
-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 AddType command handler, which
-looks like this (the AddEncoding command looks basically
-the same, and won't be shown here):
-
-
-char *add_type(cmd_parms *cmd, mime_dir_config *m, char *ct, char *ext)
-{
- if (*ext == '.') ++ext;
- ap_table_set (m->forced_types, ext, ct);
- return NULL;
-}
-
-
-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 cmd_parms 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.
-
-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
-NULL; this causes an error to be printed out on the
-server's stderr, followed by a quick exit, if it is in
-the main config files; for a .htaccess 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).
- -The MIME module's command table has entries for these commands, which -look like this: - -
-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 }
-};
-
-
-The entries in these tables are:
-
--
-
- The name of the command -
- The function which handles it -
- a
(void *)pointer, which is passed in the -cmd_parmsstructure to the command handler --- - this is useful in case many similar commands are handled by the - same function. - - A bit mask indicating where the command may appear. There are
- mask bits corresponding to each
AllowOverride- option, and an additional mask bit,RSRC_CONF, - indicating that the command may appear in the server's own - config files, but not in any.htaccess- file. - - A flag indicating how many arguments the command handler wants
- pre-parsed, and how they should be passed in.
-
TAKE2indicates two pre-parsed arguments. Other - options areTAKE1, which indicates one pre-parsed - argument,FLAG, which indicates that the argument - should beOnorOff, and is passed in - as a boolean flag,RAW_ARGS, which causes the - server to give the command the raw, unparsed arguments - (everything but the command name itself). There is also -ITERATE, which means that the handler looks the - same asTAKE1, but that if multiple arguments are - present, it should be called multiple times, and finally -ITERATE2, which indicates that the command handler - looks like aTAKE2, but if more arguments are - present, then it should be called multiple times, holding the - first argument constant. - - 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
-
NULL). -
request_rec's per-directory configuration vector by using
-the ap_get_module_config function.
-
-
-int find_ct(request_rec *r)
-{
- int i;
- char *fn = ap_pstrdup (r->pool, r->filename);
- mime_dir_config *conf = (mime_dir_config *)
- ap_get_module_config(r->per_dir_config, &mime_module);
- char *type;
-
- if (S_ISDIR(r->finfo.st_mode)) {
- r->content_type = DIR_MAGIC_TYPE;
- return OK;
- }
-
- if((i=ap_rind(fn,'.')) < 0) return DECLINED;
- ++i;
-
- if ((type = ap_table_get (conf->encoding_types, &fn[i])))
- {
- r->content_encoding = type;
-
- /* go back to previous extension to try to use it as a type */
-
- fn[i-1] = '\0';
- if((i=ap_rind(fn,'.')) < 0) return OK;
- ++i;
- }
-
- if ((type = ap_table_get (conf->forced_types, &fn[i])))
- {
- r->content_type = type;
- }
-
- return OK;
-}
-
-
-
-Side notes --- per-server configuration, virtual - servers, etc.
- -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).
-
-The only substantial difference is that when a command needs to
-configure the per-server private module data, it needs to go to the
-cmd_parms 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):
-
-
-char *add_redirect(cmd_parms *cmd, void *dummy, char *f, char *url)
-{
- server_rec *s = cmd->server;
- alias_server_conf *conf = (alias_server_conf *)
- ap_get_module_config(s->module_config,&alias_module);
- alias_entry *new = ap_push_array (conf->redirects);
-
- if (!ap_is_url (url)) return "Redirect to non-URL";
-
- new->fake = f; new->real = url;
- return NULL;
-}
-
-
-
diff --git a/docs/manual/dso.html.en b/docs/manual/dso.html.en
deleted file mode 100644
index e23a6061cda..00000000000
--- a/docs/manual/dso.html.en
+++ /dev/null
@@ -1,388 +0,0 @@
-
-
-- - -- - diff --git a/docs/manual/handler.html.en b/docs/manual/handler.html.en deleted file mode 100644 index 72f16fd1707..00000000000 --- a/docs/manual/handler.html.en +++ /dev/null @@ -1,195 +0,0 @@ - - - -- -- --Apache 1.3
- -Originally written by
-Dynamic Shared Object (DSO)
-Support -
-Ralf S. Engelschall <rse@apache.org>, April 1998 - -Background
- -On modern Unix derivatives there exists a nifty mechanism usually called -dynamic linking/loading of Dynamic Shared Objects (DSO) which -provides a way to build a piece of program code in a special format for -loading it at run-time into the address space of an executable program. - -
This loading can usually be done in two ways: Automatically by a system -program called
ld.sowhen an executable program is started or -manually from within the executing program via a programmatic system interface -to the Unix loader through the system callsdlopen()/dlsym(). - -In the first way the DSO's are usually called shared libraries or -DSO libraries and named
libfoo.soor -libfoo.so.1.2. They reside in a system directory (usually -/usr/lib) and the link to the executable program is established -at build-time by specifying-lfooto the linker command. This -hard-codes library references into the executable program file so that at -start-time the Unix loader is able to locatelibfoo.soin -/usr/lib, in paths hard-coded via linker-options like --Ror in paths configured via the environment variable -LD_LIBRARY_PATH. It then resolves any (yet unresolved) symbols in -the executable program which are available in the DSO. - -Symbols in the executable program are usually not referenced by the DSO -(because it's a reusable library of general code) and hence no further -resolving has to be done. The executable program has no need to do anything on -its own to use the symbols from the DSO because the complete resolving is done -by the Unix loader. (In fact, the code to invoke
ld.sois part of -the run-time startup code which is linked into every executable program which -has been bound non-static). The advantage of dynamic loading of common library -code is obvious: the library code needs to be stored only once, in a system -library likelibc.so, saving disk space for every program. - -In the second way the DSO's are usually called shared objects or -DSO files and can be named with an arbitrary extension (although the -canonical name is
foo.so). These files usually stay inside a -program-specific directory and there is no automatically established link to -the executable program where they are used. Instead the executable program -manually loads the DSO at run-time into its address space via -dlopen(). At this time no resolving of symbols from the DSO for -the executable program is done. But instead the Unix loader automatically -resolves any (yet unresolved) symbols in the DSO from the set of symbols -exported by the executable program and its already loaded DSO libraries -(especially all symbols from the ubiquitouslibc.so). This way -the DSO gets knowledge of the executable program's symbol set as if it had -been statically linked with it in the first place. - -Finally, to take advantage of the DSO's API the executable program has to -resolve particular symbols from the DSO via
dlsym()for later use -inside dispatch tables etc. In other words: The executable program has to -manually resolve every symbol it needs to be able to use it. The advantage of -such a mechanism is that optional program parts need not be loaded (and thus -do not spend memory) until they are needed by the program in question. When -required, these program parts can be loaded dynamically to extend the base -program's functionality. - -Although this DSO mechanism sounds straightforward there is at least one -difficult step here: The resolving of symbols from the executable program for -the DSO when using a DSO to extend a program (the second way). Why? Because -"reverse resolving" DSO symbols from the executable program's symbol set is -against the library design (where the library has no knowledge about the -programs it is used by) and is neither available under all platforms nor -standardized. In practice the executable program's global symbols are often -not re-exported and thus not available for use in a DSO. Finding a way to -force the linker to export all global symbols is the main problem one has to -solve when using DSO for extending a program at run-time. - -
Practical Usage
- -The shared library approach is the typical one, because it is what the DSO -mechanism was designed for, hence it is used for nearly all types of libraries -the operating system provides. On the other hand using shared objects for -extending a program is not used by a lot of programs. - -
As of 1998 there are only a few software packages available which use the -DSO mechanism to actually extend their functionality at run-time: Perl 5 (via -its XS mechanism and the DynaLoader module), Netscape Server, etc. Starting -with version 1.3, Apache joined the crew, because Apache already uses a module -concept to extend its functionality and internally uses a dispatch-list-based -approach to link external modules into the Apache core functionality. So, -Apache is really predestined for using DSO to load its modules at run-time. - -
As of Apache 1.3, the configuration system supports two optional features -for taking advantage of the modular DSO approach: compilation of the Apache -core program into a DSO library for shared usage and compilation of the -Apache modules into DSO files for explicit loading at run-time. - -
Implementation
- -The DSO support for loading individual Apache modules is based on a module -named
mod_so.cwhich has to be -statically compiled into the Apache core. It is the only module besides -http_core.cwhich cannot be put into a DSO itself -(bootstrapping!). Practically all other distributed Apache modules then can -then be placed into a DSO by individually enabling the DSO build for them via -configure's--enable-sharedoption (see top-level -INSTALLfile) or by changing theAddModulecommand -in yoursrc/Configurationinto aSharedModule-command (seesrc/INSTALLfile). After a module is compiled into -a DSO namedmod_foo.soyou can usemod_so'sLoadModulecommand in your -httpd.conffile to load this module at server startup or restart. - -To simplify this creation of DSO files for Apache modules (especially for -third-party modules) a new support program named
apxs(APache -eXtenSion) is available. It can be used to build DSO based modules -outside of the Apache source tree. The idea is simple: When -installing Apache theconfigure'smake install-procedure installs the Apache C header files and puts the platform-dependent -compiler and linker flags for building DSO files into theapxs-program. This way the user can useapxsto compile his Apache -module sources without the Apache distribution source tree and without having -to fiddle with the platform-dependent compiler and linker flags for DSO -support. - -To place the complete Apache core program into a DSO library (only required -on some of the supported platforms to force the linker to export the apache -core symbols -- a prerequisite for the DSO modularization) the rule -
SHARED_COREhas to be enabled viaconfigure's ---enable-rule=SHARED_COREoption (see top-level -INSTALLfile) or by changing theRulecommand in -yourConfigurationfile toRule SHARED_CORE=yes(see -src/INSTALLfile). The Apache core code is then placed into a DSO -library namedlibhttpd.so. Because one cannot link a DSO against -static libraries on all platforms, an additional executable program named -libhttpd.epis created which both binds this static code and -provides a stub for themain()function. Finally the -httpdexecutable program itself is replaced by a bootstrapping -code which automatically makes sure the Unix loader is able to load and start -libhttpd.epby providing theLD_LIBRARY_PATHto -libhttpd.so. - -Supported Platforms
- -Apache's
src/Configurescript currently has only limited but -adequate built-in knowledge on how to compile DSO files, because as already -mentioned this is heavily platform-dependent. Nevertheless all major Unix -platforms are supported. The definitive current state (May 1998) is this: - --
-
- -- Out-of-the-box supported platforms:
-(actually tested versions in parenthesis) - --o FreeBSD (2.1.5, 2.2.5, 2.2.6) -o OpenBSD (2.x) -o NetBSD (1.3.1) -o BSDI (4.0) -o Linux (Debian/1.3.1, RedHat/4.2) -o Solaris (2.4, 2.5.1, 2.6) -o SunOS (4.1.3) -o Digital UNIX (4.0) -o IRIX (6.2) -o HP/UX (10.20) -o UnixWare (2.01, 2.1.2) -o SCO (5.0.4) -o AIX (3.2, 4.1.5, 4.2, 4.3) -o ReliantUNIX/SINIX (5.43) -o SVR4 (-) -- --
- Explicitly unsupported platforms: - -
-o Ultrix (no dlopen-style interface under this platform) -- -Usage Summary
- -To give you an overview of the DSO features of Apache 1.3, here is a short -and concise summary: - -
- -
- -- Placing the Apache core code (all the stuff which usually forms the -
httpdbinary) into a DSOlibhttpd.so, an executable -programlibhttpd.epand a bootstrapping executable program -httpd(Notice: this is only required on some of the supported -platforms to force the linker to export the Apache core symbols, which in turn -is a prerequisite for the DSO modularization): - --
-
- -- Build and install via
configure(preferred): -- -
- -$ ./configure --prefix=/path/to/install - --enable-rule=SHARED_CORE ... -$ make install --- Build and install manually: -
-
- -- Edit src/Configuration: - << Rule SHARED_CORE=default - >> Rule SHARED_CORE=yes - << EXTRA_CFLAGS= - >> EXTRA_CFLAGS= -DSHARED_CORE_DIR=\"/path/to/install/libexec\" -$ make -$ cp src/libhttpd.so* /path/to/install/libexec/ -$ cp src/libhttpd.ep /path/to/install/libexec/ -$ cp src/httpd /path/to/install/bin/ --- Build and install a distributed Apache module, say -
mod_foo.c, into its own DSOmod_foo.so: - --
-
- -- Build and install via
configure(preferred): -- -
- -$ ./configure --prefix=/path/to/install - --enable-shared=foo -$ make install --- Build and install manually: -
-
- -- Edit src/Configuration: - << AddModule modules/xxxx/mod_foo.o - >> SharedModule modules/xxxx/mod_foo.so -$ make -$ cp src/xxxx/mod_foo.so /path/to/install/libexec -- Edit /path/to/install/etc/httpd.conf - >> LoadModule foo_module /path/to/install/libexec/mod_foo.so --- Build and install a third-party Apache module, say -
mod_foo.c, into its own DSOmod_foo.so- --
-
- -- Build and install via
configure(preferred): -- -
- -$ ./configure --add-module=/path/to/3rdparty/mod_foo.c - --enable-shared=foo -$ make install --- Build and install manually: -
-
- -$ cp /path/to/3rdparty/mod_foo.c /path/to/apache-1.3/src/modules/extra/ -- Edit src/Configuration: - >> SharedModule modules/extra/mod_foo.so -$ make -$ cp src/xxxx/mod_foo.so /path/to/install/libexec -- Edit /path/to/install/etc/httpd.conf - >> LoadModule foo_module /path/to/install/libexec/mod_foo.so ---
- Build and install a third-party Apache module, say -
mod_foo.c, into its own DSOmod_foo.sooutside -of the Apache source tree: - --
-
- -- Build and install via
apxs: --
- -$ cd /path/to/3rdparty -$ apxs -c mod_foo.c -$ apxs -i -a -n foo mod_foo.so --Advantages & Disadvantages
- -The above DSO based features of Apache 1.3 have the following advantages: - -
-
- -- The server package is more flexible at run-time because the actual server - process can be assembled at run-time via
LoadModule-httpd.confconfiguration commands instead of -ConfigurationAddModulecommands at build-time. - For instance this way one is able to run different server instances - (standard & SSL version, minimalistic & powered up version - [mod_perl, PHP3], etc.) with only one Apache installation. --
- The server package can be easily extended with third-party modules even - after installation. This is at least a great benefit for vendor package - maintainers who can create a Apache core package and additional packages - containing extensions like PHP3, mod_perl, mod_fastcgi, etc. -
-
- Easier Apache module prototyping because with the DSO/
apxs- pair you can both work outside the Apache source tree and only need an -apxs -icommand followed by anapachectl - restartto bring a new version of your currently developed module - into the running Apache server. -DSO has the following disadvantages: - -
-
- - -- The DSO mechanism cannot be used on every platform because not all - operating systems support dynamic loading of code into the address space - of a program. -
-
- The server is approximately 20% slower at startup time because of the - symbol resolving overhead the Unix loader now has to do. -
-
- The server is approximately 5% slower at execution time under some - platforms because position independent code (PIC) sometimes needs - complicated assembler tricks for relative addressing which are not - necessarily as fast as absolute addressing. -
-
- Because DSO modules cannot be linked against other DSO-based libraries - (
ld -lfoo) on all platforms (for instance a.out-based - platforms usually don't provide this functionality while ELF-based - platforms do) you cannot use the DSO mechanism for all types of modules. - Or in other words, modules compiled as DSO files are restricted to only - use symbols from the Apache core, from the C library (libc) - and all other dynamic or static libraries used by the Apache core, or - from static library archives (libfoo.a) containing position - independent code. The only chances to use other code is to either make - sure the Apache core itself already contains a reference to it, loading - the code yourself viadlopen()or enabling the -SHARED_CHAINrule while building Apache when your platform - supports linking DSO files against DSO libraries. --
- Under some platforms (many SVR4 systems) there is no way to force the - linker to export all global symbols for use in DSO's when linking the - Apache httpd executable program. But without the visibility of the Apache - core symbols no standard Apache module could be used as a DSO. The only - chance here is to use the
SHARED_COREfeature because this - way the global symbols are forced to be exported. As a consequence the - Apachesrc/Configurescript automatically enforces -SHARED_COREon these platforms when DSO features are used in - theConfigurationfile or on the configure command line. -
Apache's Handler Use
- -What is a Handler
- -A "handler" is an internal Apache representation of the action to be -performed when a file is called. Generally, files have implicit -handlers, based on the file type. Normally, all files are simply -served by the server, but certain file typed are "handled" -separately. For example, you may use a type of -"application/x-httpd-cgi" to invoke CGI scripts.
- -Apache 1.1 adds the additional ability to use handlers -explicitly. Either based on filename extensions or on location, these -handlers are unrelated to file type. This is advantageous both because -it is a more elegant solution, but it also allows for both a type -and a handler to be associated with a file (See also -Files with Multiple Extensions) - -
- -Handlers can either be built into the server or to a module, or -they can be added with the Action directive. The built-in -handlers in the standard distribution are as follows:
- --
-
- default-handler:
- Send the file using the
default_handler(), which is the - handler used by default to handle static content. - (core) - - send-as-is: - Send file with HTTP headers as is. - (mod_asis) -
- cgi-script: - Treat the file as a CGI script. - (mod_cgi) -
- imap-file: - Imagemap rule file. - (mod_imap) -
- server-info: - Get the server's configuration information - (mod_info) -
- server-parsed: - Parse for server-side includes - (mod_include) -
- server-status: - Get the server's status report - (mod_status) -
- type-map: - Parse as a type map file for content negotiation - (mod_negotiation) -
- -
Directives
--
-
- AddHandler -
- SetHandler -
- -
AddHandler
- -Syntax: AddHandler handler-name extension extension...-Context: server config, virtual host, directory, .htaccess
-Override: FileInfo
-Status: Base
-Module: mod_mime
-Compatibility: AddHandler is only available in Apache -1.1 and later
- -
AddHandler maps the filename extensions extension to the
-handler handler-name. This mapping is added to any already
-in force, overriding any mappings that already exist for the same
-extension.
-
-For example, to activate CGI scripts
-with the file extension ".cgi", you might use:
-
- AddHandler cgi-script cgi -- -
Once that has been put into your srm.conf or httpd.conf file, any
-file containing the ".cgi" extension will be treated as a
-CGI program.
- -See also: Files with -multiple extensions - -
- -
SetHandler
- -Syntax: SetHandler handler-name-Context: directory, .htaccess
-Status: Base
-Module: mod_mime
-Compatibility: SetHandler is only available in Apache -1.1 and later.
- -
When placed into an .htaccess file or a
-<Directory> or <Location>
-section, this directive forces all matching files to be parsed through
-the handler given by handler-name. For example, if you had a
-directory you wanted to be parsed entirely as imagemap rule files,
-regardless of extension, you might put the following into an
-.htaccess file in that directory:
-
- SetHandler imap-file -- -
Another example: if you wanted to have the server display a status
-report whenever a URL of http://servername/status was
-called, you might put the following into access.conf:
-
- <Location /status> - SetHandler server-status - </Location> --
- -
Programmer's Note
- -In order to implement the handler features, an addition has been
-made to the Apache API that you may wish to
-make use of. Specifically, a new record has been added to the
-request_rec structure:
- char *handler --
If you wish to have your module engage a handler, you need only to
-set r->handler to the name of the handler at any time
-prior to the invoke_handler stage of the
-request. Handlers are implemented as they were before, albeit using
-the handler name instead of a content type. While it is not
-necessary, the naming convention for handlers is to use a
-dash-separated word, with no slashes, so as to not invade the media
-type name-space.
Compiling and Installing Apache 1.3
- -This document covers compilation and installation of Apache on Unix -systems only. For compiling and installation on Windows, see Using Apache with Microsoft Windows and for -TPF see Installing the Apache 1.3 HTTP -Server on TPF. - -- -UnixWare users will want to consult build notes -for various UnixWare versions before compiling. - -
Downloading Apache
- -Information on the latest version of Apache can be found on the Apache -web server at http://www.apache.org/. This will -list the current release, any more recent beta-test release, together -with details of mirror web and anonymous ftp sites. - -- -If you downloaded a binary distribution, skip to Installing Apache. Otherwise read the next section -for how to compile the server. - -
Compiling Apache
- -Compiling Apache consists of three steps: Firstly select which Apache -modules you want to include into the server. Secondly create a -configuration for your operating system. Thirdly compile the -executable. -
-
-All configuration of Apache is performed in the src
-directory of the Apache distribution. Change into this directory.
-
-
-
-
-
- Select modules to compile into Apache in the
-
Configurationfile. Uncomment lines corresponding to - those optional modules you wish to include (among the AddModule lines - at the bottom of the file), or add new lines corresponding to - additional modules you have downloaded or written. (See API.html for preliminary docs on how to - write Apache modules). Advanced users can comment out some of the - default modules if they are sure they will not need them (be careful - though, since many of the default modules are vital for the correct - operation and security of the server). -- - You should also read the instructions in the
Configuration- file to see if you need to set any of theRulelines. - - - -
- Configure Apache for your operating system. Normally you can just
- type run the
Configurescript as given below. However - if this fails or you have any special requirements (e.g., to include - an additional library required by an optional module) you might need - to edit one or more of the following options in the -Configurationfile: -EXTRA_CFLAGS, LIBS, LDFLAGS, INCLUDES. -- - Run the
Configurescript: --
- - (*: Depending on Configuration and your system, Configure - make not print these lines. That's OK).- % Configure - Using 'Configuration' as config file - + configured for <whatever> platform - + setting C compiler to <whatever> * - + setting C compiler optimization-level to <whatever> * - + Adding selected modules - + doing sanity check on compiler and options - Creating Makefile in support - Creating Makefile in main - Creating Makefile in os/unix - Creating Makefile in modules/standard -
-- - This generates a Makefile for use in stage 3. It also creates a - Makefile in the support directory, for compilation of the optional - support programs. -
- - (If you want to maintain multiple configurations, you can give a - option to
Configureto tell it to read an alternative - Configuration file, such asConfigure -file - Configuration.ai). -- -
-
- Type
make. -
Installing Apache
- -You will have a binary file calledhttpd in the
-src directory. A binary distribution of Apache will
-supply this file.
-
-The next step is to install the program and configure it. Apache is
-designed to be configured and run from the same set of directories
-where it is compiled. If you want to run it from somewhere else, make
-a directory and copy the conf, logs and
-icons directories into it. In either case you should
-read the security tips
-describing how to set the permissions on the server root directory.
-
-The next step is to edit the configuration files for the server. This
-consists of setting up various directives in up to three
-central configuration files. By default, these files are located in
-the conf directory and are called srm.conf,
-access.conf and httpd.conf. To help you get
-started there are same files in the conf directory of the
-distribution, called srm.conf-dist,
-access.conf-dist and httpd.conf-dist. Copy
-or rename these files to the names without the -dist.
-Then edit each of the files. Read the comments in each file carefully.
-Failure to setup these files correctly could lead to your server not
-working or being insecure. You should also have an additional file in
-the conf directory called mime.types. This
-file usually does not need editing.
-
-
-
-First edit httpd.conf. This sets up general attributes
-about the server: the port number, the user it runs as, etc. Next
-edit the srm.conf file; this sets up the root of the
-document tree, special functions like server-parsed HTML or internal
-imagemap parsing, etc. Finally, edit the access.conf
-file to at least set the base cases of access.
-
-
-
-In addition to these three files, the server behavior can be configured
-on a directory-by-directory basis by using .htaccess
-files in directories accessed by the server.
-
-
Set your system time properly!
- -Proper operation of a public web server requires accurate time -keeping, since elements of the HTTP protocol are expressed as the time -of day. So, it's time to investigate setting up NTP or some other -time synchronization system on your Unix box, or whatever the -equivalent on NT would be. - -Starting and Stopping the Server
- -To start the server, simply runhttpd. This will look for
-httpd.conf in the location compiled into the code (by
-default /usr/local/apache/conf/httpd.conf). If
-this file is somewhere else, you can give the real
-location with the -f argument. For example:
-
-- /usr/local/apache/httpd -f /usr/local/apache/conf/httpd.conf -- -If all goes well this will return to the command prompt almost -immediately. This indicates that the server is now up and running. If -anything goes wrong during the initialization of the server you will -see an error message on the screen. - -If the server started ok, you can now use your browser to -connect to the server and read the documentation. If you are running -the browser on the same machine as the server and using the default -port of 80, a suitable URL to enter into your browser is - -
- http://localhost/ -- -
- -Note that when the server starts it will create a number of -child processes to handle the requests. If you started Apache -as the root user, the parent process will continue to run as root -while the children will change to the user as given in the httpd.conf -file. - -
-
-If when you run httpd it complained about being unable to
-"bind" to an address, then either some other process is already using
-the port you have configured Apache to use, or you are running httpd
-as a normal user but trying to use port below 1024 (such as the
-default port 80).
-
-
-
-If the server is not running, read the error message displayed
-when you run httpd. You should also check the server
-error_log for additional information (with the default configuration,
-this will be located in the file error_log in the
-logs directory).
-
-
-
-If you want your server to continue running after a system reboot, you
-should add a call to httpd to your system startup files
-(typically rc.local or a file in an
-rc.N directory). This will start Apache as root.
-Before doing this ensure that your server is properly configured
-for security and access restrictions.
-
-
-
-To stop Apache send the parent process a TERM signal. The PID of this
-process is written to the file httpd.pid in the
-logs directory (unless configured otherwise). Do not
-attempt to kill the child processes because they will be renewed by
-the parent. A typical command to stop the server is:
-
-
- kill -TERM `cat /usr/local/apache/logs/httpd.pid` -- -
- -For more information about Apache command line options, configuration -and log files, see Starting Apache. For a -reference guide to all Apache directives supported by the distributed -modules, see the Apache directives. - -
Compiling Support Programs
- -In addition to the mainhttpd server which is compiled
-and configured as above, Apache includes a number of support programs.
-These are not compiled by default. The support programs are in the
-support directory of the distribution. To compile
-the support programs, change into this directory and type
-- make -- - - - diff --git a/docs/manual/invoking.html.en b/docs/manual/invoking.html.en deleted file mode 100644 index 6b0be6decb1..00000000000 --- a/docs/manual/invoking.html.en +++ /dev/null @@ -1,210 +0,0 @@ - - - -
Starting Apache
- -Invoking Apache
- -On Unix, thehttpd program is usually run as a daemon
-which executes continuously, handling requests. It is possible to
-invoke Apache by the Internet daemon inetd each time a
-connection to the HTTP service is made (use the ServerType directive) but this is
-not recommended.
-
-- -On Windows, Apache is normally run as a service on Windows NT, or as a -console application on Windows 95. See also running Apache for Windows. - -
Command line options
-The following options are recognized on the httpd command line: --
-
-dserverroot -- Set the initial value for the
-ServerRoot variable to
-serverroot. This can be overridden by the ServerRoot command
-in the configuration file. The default is
-
/usr/local/apacheon Unix,/apacheon -Windows and/os2httpdon OS/2. - - -Dname -- Define a name for use in in -IfDefine directives. -This option can be used to optionally enable certain functionality in the -configuration file, or to use a common configuration for -several independent hosts, where host specific information is enclosed in -<IfDefine> sections. - -
-fconfig -- Execute the commands in the file config on startup. If
-config does not begin with a
/, then it is taken to be a -path relative to the ServerRoot. The -default isconf/httpd.conf. - - -C"directive" -- Process the given apache "directive" (just as if it had been part of a -configuration file) before actually reading the regular configuration files. - -
-c"directive" -- Process the given apache "directive" after reading -all the regular configuration files. - -
-X-- Run in single-process mode, for internal debugging purposes only; the -daemon does not detach from the terminal or fork any children. Do NOT -use this mode to provide ordinary web service. - -
-v-- Print the version of httpd and its build date, and then exit. - -
-V-- Print the base version of httpd, its -build date, and a list of compile time settings which influence the -behavior and performance of the apache server (e.g., --DUSE_MMAP_FILES), -then exit. - -
-L-- - -Give a list of directives together with expected arguments and places -where the directive is valid, then exit. (Apache 1.3.4 and -later. Earlier versions used -l instead). - - -
-l--
-
-Give a list of all modules compiled into the server, then exit.
-(Apache 1.3.4 and later. Earlier versions used -h instead).
- -Give a list of directives together with expected arguments and places -where the directive is valid, then exit. (Apache 1.2 to 1.3.3. Later -versions use -L instead). - - - - -h--
-
-Print a list of the httpd options, then exit. (Apache 1.3.4 and
-later. Earlier versions used -? instead).
- -Give a list of all modules compiled into the server, then exit. (Up to -Apache 1.3.3. Later versions use -l instead).
- - - -S-- Show the settings as parsed from the config file (currently only -shows a breakdown of the vhost settings) but do not start the -server. (Up to Apache 1.3.3, this option also started the server). - -
-t-- Test the configuration file syntax (i.e., read all configuration files -and interpret them) but do not start the server. If the configuration contains -errors, display an error message and exit with a non-zero exit status, -otherwise display "Syntax OK" and terminate with a zero exit status. - -
-koption -- Windows only: signal Apache to restart or shutdown. option -is one of "shutdown" or "restart". (Apache 1.3.3 and later). - -
-?-- Print a list of the httpd options, and then exit (up to Apache -1.3.3. Later version use -h instead). - -
Configuration files
-The server will read three files for configuration directives. Any -directive may appear in any of these files. The the names of these -files are taken to be relative to the server root; this is set by the -ServerRoot directive, the --d command line flag, or (on Windows only) the registry
-(see Running Apache for Windows).
-
-Conventionally, the files are:
--
-
conf/httpd.conf-- Contains directives that control the operation of the server daemon.
-The filename may be overridden with the
-fcommand line flag. - - conf/srm.conf-- Contains directives that control the specification of documents that -the server can provide to clients. The filename may be overridden with -the ResourceConfig directive. - -
conf/access.conf-- Contains directives that control access to documents. -The filename may be overridden with the -AccessConfig directive. -
-The server also reads a file containing mime document types; the filename
-is set by the TypesConfig
-directive,
-and is conf/mime.types by default.
-
-
Log files
-security warning
-Anyone who can write to the directory where Apache is writing a -log file can almost certainly gain access to the uid that the server is -started as, which is normally root. Do NOT give people write -access to the directory the logs are stored in without being aware of -the consequences; see the security tips -document for details. -pid file
- -On startup, Apache saves the process id of the parent httpd process to -the filelogs/httpd.pid. This filename can be changed
-with the PidFile directive. The
-process-id is for use by the administrator in restarting and
-terminating the daemon: on Unix, a HUP or USR1 signal causes the
-daemon to re-read its configuration files and a TERM signal causes it
-to die gracefully; on Windows, use the -k command line option instead.
-For more information see the Stopping and
-Restarting page.
-
--If the process dies (or is killed) abnormally, then it will be necessary to -kill the children httpd processes. - -
Error log
- -The server will log error messages to a log file, by default -logs/error_log on Unix or logs/error.log on
-Windows and OS/2. The filename can be set using the ErrorLog directive; different error
-logs can be set for different virtual hosts.
-
-Transfer log
- -The server will typically log each request to a transfer file, by -defaultlogs/access_log on Unix or
-logs/access.log on Windows and OS/2. The filename can be
-set using a TransferLog directive
-or additional log files created with the CustomLog directive;
-different transfer logs can be set for different virtual hosts.
-
-
-
-
diff --git a/docs/manual/mod/directive-dict.html.en b/docs/manual/mod/directive-dict.html.en
deleted file mode 100644
index a4c13e55f5b..00000000000
--- a/docs/manual/mod/directive-dict.html.en
+++ /dev/null
@@ -1,262 +0,0 @@
-
-
-
- Terms Used to Describe Apache Directives
- -- Each Apache configuration directive is described using a common format - that looks like this: -
--
-
- Syntax: directive-name some args
-
- Default: - directive-name default-value -
- Context: context-list -
- Override: override -
- Status: status -
- Module: module-name -
- Compatibility: compatibility notes -
-
- Each of the directive's attributes, complete with possible values - where possible, are described in this document. -
- -Directive Terms
- - --
Syntax
-- This indicates the format of the directive as it would appear in a - configuration file. This syntax is extremely directive-specific, so - refer to the text of the directive's description for details. -
- --
Default
-- If the directive has a default value (i.e., if you omit it - from your configuration entirely, the Apache Web server will behave as - though you set it to a particular value), it is described here. If - there is no default value, this section should say - "None". -
- --
Context
-- This indicates where in the server's configuration files the directive - is legal. It's a comma-separated list of one or more of the following - values: -
--
-
- server config - -
- This means that the directive may be used in the server
- configuration files (e.g., httpd.conf,
- srm.conf, and access.conf), but
- not within any <VirtualHost> or
- <Directory> containers. It is not allowed in
- .htaccess files at all.
-
-
-
- - virtual host - -
- This context means that the directive may appear inside
- <VirtualHost> containers in the server
- configuration files.
-
-
-
- - directory - -
- A directive marked as being valid in this context may be used
- inside <Directory> containers in the server
- configuration files.
-
-
-
- - .htaccess - -
- If a directive is valid in this context, it means that it can
- appear inside per-directory .htaccess files.
- It may not be processed, though depending upon the
- overrides
- currently active.
-
-
-
-
- The directive is only allowed within the designated context; - if you try to use it elsewhere, you'll get a configuration error that - will either prevent the server from handling requests in that context - correctly, or will keep the server from operating at all -- - i.e., the server won't even start. -
-- The valid locations for the directive are actually the result of a - Boolean OR of all of the listed contexts. In other words, a directive - that is marked as being valid in "server config, - .htaccess" can be used in the httpd.conf file - and in .htaccess files, but not within any - <Directory> or <VirtualHost> containers. -
- --
Override
-- This directive attribute indicates which configuration override must - be active in order for the directive to be processed when it appears - in a .htaccess file. If the directive's - context - doesn't permit it to appear in .htaccess files, this - attribute should say "Not applicable". -
-- Overrides are activated by the - AllowOverride - directive, and apply to a particular scope (such as a directory) and - all descendants, unless further modified by other - AllowOverride directives at lower levels. The - documentation for that directive also lists the possible override - names available. -
- --
Status
-- This indicates how tightly bound into the Apache Web server the - directive is; in other words, you may need to recompile the server - with an enhanced set of modules in order to gain access to the - directive and its functionality. Possible values for this attribute - are: -
--
-
- Core - -
- If a directive is listed as having "Core" status, that
- means it is part of the innermost portions of the Apache Web server,
- and is always available.
-
-
-
- - Base - -
- A directive labeled as having "Base" status is
- supported by one of the standard Apache modules which is compiled
- into the server by default, and is therefore normally available
- unless you've taken steps to remove the module from your configuration.
-
-
-
- - Extension - -
- A directive with "Extension" status is provided by one
- of the modules included with the Apache server kit, but the module
- isn't normally compiled into the server. To enable the directive
- and its functionality, you will need to change the server build
- configuration files and re-compile Apache.
-
-
-
- - Experimental - -
- "Experimental" status indicates that the directive is
- available as part of the Apache kit, but you're on your own if you
- try to use it. The directive is being documented for completeness,
- and is not necessarily supported. The module which provides the
- directive may or may not be compiled in by default; check the top of
- the page which describes the directive and its module to see if it
- remarks on the availability.
-
-
-
-
-
Module
-- This quite simply lists the name of the source module which defines - the directive. -
- --
Compatibility
-- If the directive wasn't part of the original Apache version 1 - distribution, the version in which it was introduced should be listed - here. If the directive has the same name as one from the NCSA HTTPd - server, any inconsistencies in behaviour between the two should also - be mentioned. Otherwise, this attribute should say "No - compatibility issues." -
- - - diff --git a/docs/manual/platform/perf-bsd44.html b/docs/manual/platform/perf-bsd44.html deleted file mode 100644 index c5e978c2b98..00000000000 --- a/docs/manual/platform/perf-bsd44.html +++ /dev/null @@ -1,254 +0,0 @@ - - - -Running a High-Performance Web Server for BSD
- -Like other OS's, the listen queue is often the first limit -hit. 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): - -- -Edit the following two files: -
/usr/include/sys/socket.h
- /usr/src/sys/sys/socket.h - /* - * Maximum queue length specifiable by listen. - */ - #define SOMAXCONN 5 -- -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. - -
- -After the edit, recompile the kernel and recompile the Apache server -then reboot. - -
- -FreeBSD 2.1 seems to be perfectly happy, with SOMAXCONN -set to 32 already. - -
-
-
-Addendum for very heavily loaded BSD servers
-
-from Chuck Murcko <chuck@telebase.com>
-
-
- -If you're running a really busy BSD Apache server, the following are useful -things to do if the system is acting sluggish:
- -
-
-
-
- Run vmstat to check memory usage, page/swap rates, etc. - -
- Run netstat -m to check mbuf usage - -
- Run fstat to check file descriptor usage - -
- -
-maxusers 256 -- -Maxusers drives a lot of other kernel parameters: - -
-
-
-
- Maximum # of processes - -
- Maximum # of processes per user - -
- System wide open files limit - -
- Per-process open files limit - -
- Maximum # of mbuf clusters - -
- Proc/pgrp hash table size - -
-# Network options. NMBCLUSTERS defines the number of mbuf clusters and -# defaults to 256. This machine is a server that handles lots of traffic, -# so we crank that value. -options NMBCLUSTERS=4096 # mbuf clusters at 4096 - -# -# Misc. options -# -options CHILD_MAX=512 # maximum number of child processes -options OPEN_MAX=512 # maximum fds (breaks RPC svcs) -- -
- -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 -FIN_WAIT_2 page. - -
- -Some more info on mbuf clusters (from sys/mbuf.h): -
-/* - * 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. - */ -- -
- -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. - -
-
-To increase the size of the listen() queue, you need to
-adjust the value of SOMAXCONN. SOMAXCONN is not derived from maxusers,
-so you'll always need to increase that yourself. We use a value guaranteed
-to be larger than Apache's default for the listen() of 128, currently.
-The actual value for SOMAXCONN is set in sys/socket.h.
-The best way to adjust this parameter is run-time, rather than changing
-it in this header file and thus hardcoding a value in the kernel and
-elsewhere. To do this, edit /etc/rc.local and add the
-following line:
-
- /usr/sbin/sysctl -w kern.somaxconn=256 -- -
-
-We used 256 but you can tune it for your own setup. In
-many cases, however, even the default value of 128 (for
-later versions of FreeBSD) is OK.
-
-
- -Caveats - -
- -Be aware that your system may not boot with a kernel that is configured -to use more resources than you have available system RAM. -ALWAYS -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. - -
- -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. - -
- -Finally, there's the hard limit of child processes configured in Apache. - -
- -For versions of Apache later than 1.0.5 you'll need to change the -definition for HARD_SERVER_LIMIT in httpd.h and -recompile if you need to run more than the default 150 instances of httpd. - -
- -From conf/httpd.conf-dist: - -
-# 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 -- -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! - -
- -Thanks to Tony Sanders and Chris Torek at BSDI for their -helpful suggestions and information. - -
- -"M. Teterin" <mi@ALDAN.ziplink.net> writes:
-
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-
--m486 -fexpensive-optimizations -fomit-frame-pointer -O2
-helped reduce the number of "unable" errors, because the CPU was -often maxed out.
- -
- -
More welcome!
- -If you have tips to contribute, send mail to -apache@apache.org - - - - diff --git a/docs/manual/platform/perf-dec.html b/docs/manual/platform/perf-dec.html deleted file mode 100644 index 61e6314a706..00000000000 --- a/docs/manual/platform/perf-dec.html +++ /dev/null @@ -1,283 +0,0 @@ - - - -Performance Tuning Tips for Digital Unix
- -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. - -- -
Update
-From: Jeffrey Mogul <mogul@pa.dec.com>-Date: Fri, 28 Jun 96 16:07:56 MDT
- -
-
-
- 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. - -
- Patch ID OSF350-146 has been superseded by
-
- Patch ID OSF350-195 for V3.2C
- 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. -
- Patch ID OSF360-350195 for V3.2D -
- - -
-From mogul@pa.dec.com (Jeffrey Mogul) -Organization DEC Western Research -Date 30 May 1996 00:50:25 GMT -Newsgroups comp.unix.osf.osf1 -Message-ID <4oirch$bc8@usenet.pa.dec.com> -Subject Re: Web Site Performance -References 1 - - - -In article <skoogDs54BH.9pF@netcom.com> skoog@netcom.com (Jim Skoog) writes: ->Where are the performance bottlenecks for Alpha AXP running the ->Netscape Commerce Server 1.12 with high volume internet traffic? ->We are evaluating network performance for a variety of Alpha AXP ->runing DEC UNIX 3.2C, which run DEC's seal firewall and behind ->that Alpha 1000 and 2100 webservers. - -Our experience (running such Web servers as altavista.digital.com -and www.digital.com) 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 - http://www.digital.com/info/alphaserver/news/webff.html -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 - -- - - diff --git a/docs/manual/platform/perf-hp.html b/docs/manual/platform/perf-hp.html deleted file mode 100644 index ca902a09fe8..00000000000 --- a/docs/manual/platform/perf-hp.html +++ /dev/null @@ -1,122 +0,0 @@ - - - -
- ----------------------------------------------------------------------------- - -From mogul@pa.dec.com (Jeffrey Mogul) -Organization DEC Western Research -Date 31 May 1996 21:01:01 GMT -Newsgroups comp.unix.osf.osf1 -Message-ID <4onmmd$mmd@usenet.pa.dec.com> -Subject Digital UNIX V3.2C Internet tuning patch info - ----------------------------------------------------------------------------- - -Something that probably few people are aware of is that Digital -has a patch kit available for Digital UNIX V3.2C that may improve -Internet performance, especially for busy web servers. - -This patch kit is one way to increase the value of somaxconn, -which I discussed in a message here a day or two ago. - -I've included in this message the revised README file for this -patch kit below. Note that the original README file in the patch -kit itself may be an earlier version; I'm told that the version -below is the right one. - -Sorry, this patch kit is NOT available for other versions of Digital -UNIX. Most (but not quite all) of these changes also made it into V4.0, -so the description of the various tuning parameters in this README -file might be useful to people running V4.0 systems. - -This patch kit does not appear to be available (yet?) from - http://www.service.digital.com/html/patch_service.html -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 - -
Running a High-Performance Web Server for HPUX
- --Date: Wed, 05 Nov 1997 16:59:34 -0800 -From: Rick Jones <raj@cup.hp.com> -Reply-To: raj@cup.hp.com -Organization: Network Performance -Subject: HP-UX tuning tips -- -Here are some tuning tips for HP-UX to add to the tuning page. - -
-
-For HP-UX 9.X: Upgrade to 10.20
-For HP-UX 10.[00|01|10]: Upgrade to 10.20
-
-
- -For HP-UX 10.20: - -
- -Install the latest cumulative ARPA Transport Patch. This will allow you -to configure the size of the TCP connection lookup hash table. The -default is 256 buckets and must be set to a power of two. This is -accomplished with adb against the *disc* image of the kernel. The -variable name is tcp_hash_size. - -Notice that it's critically important that you use "W" to write a 32 bit -quantity, not "w" to write a 16 bit value when patching the disc image because -the tcp_hash_size variable is a 32 bit quantity. - -
- -How to pick the value? Examine the output of - -ftp://ftp.cup.hp.com/dist/networking/tools/connhist and see how many -total TCP connections exist on the system. You probably want that number -divided by the hash table size to be reasonably small, say less than 10. -Folks can look at HP's SPECweb96 disclosures for some common settings. -These can be found at -http://www.specbench.org/. If an HP-UX system was -performing at 1000 SPECweb96 connections per second, the TIME_WAIT time -of 60 seconds would mean 60,000 TCP "connections" being tracked. - -
- -Folks can check their listen queue depths with - -ftp://ftp.cup.hp.com/dist/networking/misc/listenq. - -
- -If folks are running Apache on a PA-8000 based system, they should -consider "chatr'ing" the Apache executable to have a large page size. -This would be "chatr +pi L <BINARY>." The GID of the running executable -must have MLOCK privileges. Setprivgrp(1m) should be consulted for -assigning MLOCK. The change can be validated by running Glance and -examining the memory regions of the server(s) to make sure that they -show a non-trivial fraction of the text segment being locked. - -
- -If folks are running Apache on MP systems, they might consider writing a -small program that uses mpctl() to bind processes to processors. A -simple pid % numcpu algorithm is probably sufficient. This might even go -into the source code. - -
- -If folks are concerned about the number of FIN_WAIT_2 connections, they -can use nettune to shrink the value of tcp_keepstart. However, they -should be careful there - certainly do not make it less than oh two to -four minutes. If tcp_hash_size has been set well, it is probably OK to -let the FIN_WAIT_2's take longer to timeout (perhaps even the default -two hours) - they will not on average have a big impact on performance. - -
- -There are other things that could go into the code base, but that might -be left for another email. Feel free to drop me a message if you or -others are interested. - -
- -sincerely, - -
-
-rick jones
-
-http://www.cup.hp.com/netperf/NetperfPage.html
-
-
- -
- Apache HTTP Server Version 1.3 -
- -
-
-
-
-
diff --git a/docs/manual/platform/perf.html b/docs/manual/platform/perf.html
deleted file mode 100644
index 73bd5b5b20f..00000000000
--- a/docs/manual/platform/perf.html
+++ /dev/null
@@ -1,175 +0,0 @@
-
-
-
-Hints on Running a High-Performance Web Server
- -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. - --
-
- A/UX (Apple's UNIX) -
- BSD-based (BSDI, FreeBSD, etc) -
- Digital UNIX -
- HPUX -
- Linux -
- Solaris -
- SunOS 4.x -
- SVR4 -
- -
-A/UX (Apple's UNIX) -
- -If you are running Apache on A/UX, a page that gives some helpful -performance hints (concerning the listen() queue and using -virtual hosts) -can be found here - -- -
-BSD-based (BSDI, FreeBSD, etc) -
- -Quick and -detailed -performance tuning hints for BSD-derived systems. - -- -
-Digital UNIX -
- --
-
- DIGITAL UNIX Tuning Parameters for Web Servers -
- We have some newsgroup postings on how - to tune Digital UNIX 3.2 and 4.0. -
- -
-Linux -
- -There are no known problems with heavily loaded systems running Linux -kernels 2.0.32 or later. Earlier kernels have some problems, and an -upgrade to the latest 2.0.x is a good idea to eliminate various security -and denial of service attacks. - -- -
-Solaris 2.4 -
- -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. - -- -Other links: - -
-
-
-
- -World Wide Web Server Performance, -<http://www.sun.com/sun-on-net/performance.html> -
- -Solaris 2.x - tuning your TCP/IP stack contains some good technical -information about tuning various Solaris TCP/IP parameters. -
- -
-SunOS 4.x -
- -More information on tuning SOMAXCONN on SunOS can be found at - -http://www.islandnet.com/~mark/somaxconn.html. - -- -
-SVR4 -
- -Some SVR4 versions waste three system calls on every -gettimeofday() call. Depending on the syntactic -form of the TZ environment variable, these -systems have several different algorithms to determine the -local time zone (presumably compatible with -something). The following example uses the central european -time zone to demonstrate this: --
-
- TZ=:MET -
- This form delegates the knowledge of the time zone
- information to an external compiled zoneinfo file
- (à la BSD).
- Caveat: Each time the gettimeofday() - function is called, the external zone info is read in - again (at least on some SVR4 systems). That results in - three wasted system calls with every apache request - served.- open("/usr/lib/locale/TZ/MET", O_RDONLY) = 3 - read(3, "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0"..., 7944) = 778 - close(3) = 0- - - TZ=MET-1MDT,M3.5.0/02:00:00,M10.5.0/03:00:00 -
- This syntax form (à la SYSV) contains all the - knowledge about time zone beginning and ending times in - its external representation. It has to be parsed each - time it is evaluated, resulting in a slight computing - overhead, but it requires no system call. Though the - table lookup à la BSD is the more sophisticated - technical solution, the bad SVR4 implementation makes - this the preferred syntax on systems which otherwise - access the external zone info file repeatedly. -
- -
More welcome!
- -If you have tips to contribute, send mail to apache@apache.org - - - - diff --git a/docs/manual/platform/readme-tpf.html b/docs/manual/platform/readme-tpf.html deleted file mode 100644 index 2e9161b1aa9..00000000000 --- a/docs/manual/platform/readme-tpf.html +++ /dev/null @@ -1,206 +0,0 @@ - - - -Overview of the Apache TPF Port
--
-
- -
- This version of Apache includes changes allowing it to run on
- IBM's EBCDIC-based
- TPF
- (Transaction Processing Facility) operating system.
- Unless otherwise noted TPF version 4.1 PUT08 and APAR PJ25589 are required.
-
- Refer to htdocs/manual/install-tpf.html
- for step-by-step installation instructions.
-
- As this is the first cut at making Apache run on TPF,
- performance tuning has not been done.
-
- This port builds upon the EBCDIC changes
- previously made to Apache.
-
-
Apache Configuration Files
-
- The distributed configuration files (httpd.conf-dist and
- mime.types, both located in the conf subdirectory)
- work on TPF with only a couple of operating system specific changes
- to httpd.conf:
-
-
-
- ServerType needs to be "inetd" since TPF does not yet support - "standalone" mode. -
- Performance considerations may dictate setting KeepAlive to "Off" - (the default is "On") or lowering the Timeout value from the default - 300 seconds (5 minutes) in order to reduce the number of active ECBs on your system. -
What's Available in this Version
- - (The Apache organization provides - online documentation - describing the various modules and components of the server.) - -Components/modules tested on TPF:
- --
-
- alloc.c -
- ap_cpystrn.c -
- ap_fnmatch.c -
- ap_signal.c -
- ap_slack.c -
- ap_snprintf.c -
- buff.c -
- buildmark.c -
- ebcdic.c -
- http_config.c -
- http_core.c -
- http_log.c -
- http_main.c -
- http_protocol.c -
- http_request.c -
- http_vhost.c * -
- mod_access.c -
- mod_alias.c -
- mod_asis.c -
- mod_autoindex.c -
- mod_cern_meta.c -
- mod_dir.c -
- mod_example.c -
- mod_expires.c -
- mod_headers.c -
- mod_imap.c -
- mod_info.c -
- mod_log_agent.c -
- mod_log_config.c -
- mod_log_referer.c -
- mod_mime.c -
- mod_negotiation.c -
- mod_setenvif.c -
- mod_speling.c -
- mod_userdir.c -
- mod_usertrack.c -
- os.c -
- os-inline.c -
- regular expression parser -
- util.c -
- util_date.c -
- util_uri.c -
- -
- * virtual hosting requires TPF version 4.1 PUT09 - -
Components/modules not (yet?) supported on TPF:
- --
-
- htpasswd.c -
- md5c.c -
- mod_actions.c -
- mod_auth.c -
- mod_auth_anon.c -
- mod_cgi.c -
- mod_digest.c -
- mod_env.c -
- mod_include.c -
- mod_mime_magic.c -
- mod_proxy.c -
- mod_rewrite.c -
- mod_status.c -
- mod_unique_id.c -
- proxy_cache.c -
- proxy_connect.c -
- proxy_ftp.c -
- proxy_http.c -
- proxy_util.c -
- rfc1413.c -
- util_md5.c -
- util_script.c -
Components/modules that don't apply or that probably won't ever be available on TPF:
- --
-
- gen_test.char.c -
- gen_uri_delims.c -
- mod_auth_db.c -
- mod_auth_dbm.c -
- mod_auth_db.module -
- mod_mmap_static.c -
- mod_so.c -
Porting Notes
--
Changes made due to differences between UNIX and - TPF's process models:
--
-
- Signals: On TPF a signal that is sent to a process
- remains unhandled until the process explicitly requests that signals
- be handled using the
tpf_process_signals()function. - Additionally, the default action for an alarm on TPF is to take - an OPR-7777 dump and exit. (On UNIX the default is the equivalent - ofexit()with no dump taken.) - These differences necessitated a few modifications: -
--
-
- bypass the use of
ap_block_alarms()& -ap_unblock_alarms()- - add
tpf_process_signals()calls - - add
select()calls in buff.c to prevent blocking. -
- - bypass the use of
Find that function...
-Some simple functions & definitions needed to be added
- on TPF, such as FD_SET().
- We've put these in src/os/tpf/os.h for now.
-
EBCDIC changes:
-TPF-specific conversion tables between US-ASCII and - EBCDIC (character set IBM-1047 to be exact) were created - and put into ebcdic.c in the src/os/tpf directory. -
- -Miscellaneous, minor changes:
-Various minor changes (such as casting) were made due to - differences in how some functions are implemented on TPF. -
- -Temporary changes:
-Lastly, we needed to bypass sections of Apache processing - since this first cut for TPF doesn't include - Standalone mode, pipes, forking, et cetera. -
- --
Compiling Apache under UnixWare
- -To compile a working copy of Apache under UnixWare, there are several other -steps you may need to take. These prevent such problems as zombie processes, -bind errors, and accept errors, to name a few. - -UnixWare 1.x
- -Make sure that USE_FCNTL_SERIALIZE_ACCEPT is defined (if not -defined by Apache autoconfiguration). If using the UnixWare cc -compiler, and you still see accept() errors, don't use compiler optimization, -or get gcc. - -UnixWare 2.0.x
- -SCO patch tf2163 is required -in order for Apache to work correctly on UnixWare 2.0.x. See -http://www.sco.com -for UnixWare patch information.- -In addition, make sure that USE_FCNTL_SERIALIZE_ACCEPT is defined (if not -defined by Apache autoconfiguration). To reduce instances of connections -in FIN_WAIT_2 state, you may also want to define NO_LINGCLOSE (Apache 1.2 -only). - -
UnixWare 2.1.x
- -SCO patch ptf3123 is required -in order for Apache to work correctly on UnixWare 2.1.x. See -http://www.sco.com -for UnixWare patch information.- -NOTE: Unixware 2.1.2 and later already have patch ptf3123 -included
- -In addition, make sure that USE_FCNTL_SERIALIZE_ACCEPT is defined (if not -defined by Apache autoconfiguration). To reduce instances of connections -in FIN_WAIT_2 state, you may also want to define NO_LINGCLOSE (Apache 1.2 -only).
- -Thanks to Joe Doupnik <JRD@cc.usu.edu> and Rich Vaughn -<rvaughn@aad.com> for additional info for UnixWare builds.
- - - - diff --git a/docs/manual/platform/windows.html b/docs/manual/platform/windows.html deleted file mode 100644 index 67eee003a25..00000000000 --- a/docs/manual/platform/windows.html +++ /dev/null @@ -1,488 +0,0 @@ - - -
-Using Apache With Microsoft Windows
- -This document explains how to install, configure and run - Apache 1.3 under Microsoft Windows. Please note that at - this time, Windows support is entirely experimental, and is - recommended only for experienced users. The Apache Group does not - guarantee that this software will work as documented, or even at - all. If you find any bugs, or wish to contribute in other ways, please - use our bug reporting - page.
- -Warning: Apache on NT has not yet been optimized for performance. -Apache still performs best, and is most reliable on Unix platforms. Over -time we will improve NT performance. Folks doing comparative reviews -of webserver performance are asked to compare against Apache -on a Unix platform such as Solaris, FreeBSD, or Linux.
- -- -Most of this document assumes that you are installing Windows from a -binary distribution. If you want to compile Apache yourself (possibly -to help with development, or to track down bugs), see the section on -Compiling Apache for Windows below. - -
- -
-
-
- Requirements -
- Downloading Apache for Windows -
- Installing Apache for Windows (binary install) -
- Running Apache for Windows -
- Using Apache for Windows -
- Running Apache for Windows from the Command Line -
- Signalling Apache when running -
- Compiling Apache for Windows -
- -
Requirements
- -Apache 1.3 is designed to run on Windows NT 4.0. The binary installer -will only work in Intel processors. Apache may also run on Windows 95, -Windows 98 and Windows NT 3.5.1, but these have not been tested. In -all cases TCP/IP networking must be installed. - -- -If running on Windows 95, using the "Winsock2" upgrade is recommended -but may not be necessary. If running on NT 4.0, installing Service Pack 2 -is recommended. - -
Downloading Apache for Windows
- -Information on the latest version of Apache can be found on the -Apache web server at http://www.apache.org/. This will -list the current release, any more recent alpha or beta-test releases, -together with details of mirror web and anonymous ftp sites.
- -
-
-You should download the version of Apache for Windows with the
-.exe extension. This is a single file containing Apache,
-ready to install and run. There may also be a .zip file
-containing the source code, to compile Apache yourself. (If there is
-no .zip file, the source will be available in a
-.tar.gz file but this will contain Unix line endings. You
-will have to convert at least the .mak and
-.dsp files to have DOS line endings before MSVC will
-understand them).
-
-
Installing Apache for Windows
- -Run the Apache .exe file you downloaded above. This will -ask for: - --
-
-
- the directory to install Apache into (the default is
-
\Program Files\Apache Group\Apachealthough you can - change this to any other directory) - - - the start menu name (default is "Apache Web Server") - -
- the installation type. The "Typical" option installs - everything except the source code. The "Minimum" option does not - install the manuals or source code. Choose the "Custom" install if - you want to install the source code. - -
- -During the installation, Apache will configure the files in the -conf directory for your chosen installation -directory. However if any of the files in this directory already exist -they will not be overwritten. Instead the new copy of -the corresponding file will be left with the extension -.default. So, for example, if -conf\httpd.conf already exists it will not be altered, -but the version which would have been installed will be left in -conf\httpd.conf.default. After the installation has -finished you should manually check to see what in new in the -.default file, and if necessary update your existing -configuration files. - -
- -Also, if you already have a file called htdocs\index.html -then it will not be overwritten (no index.html.default -file will be installed either). This should mean it a safe to install -Apache over an existing installation (but you will have to stop the -existing server running before doing the installation, then start the -new one after the installation is finished). - -
- -After installing Apache, you should edit the configuration files in -the conf directory as required. These files will be -configured during the install ready for Apache to be run from the -directory where it was installed, with the documents served from the -subdirectory htdocs. There are lots of other options -which should be set before you start really using Apache. However to -get started quickly the files should work as installed. - -
Running Apache for Windows
- -There are two ways you can run Apache: - --
-
- As a "service" (available on NT only). This is the best option if - you want Apache to automatically start when you machine boots, and to - keep Apache running when you log-off. - -
- From a console window. This is the only option - available for - Windows 95 users. -
- NET START APACHE - NET STOP APACHE -- -To run Apache from a console window, select the "Start Apache as -console app" option from the Start menu (in Apache 1.3.4 and earlier, -this option was called "Apache Server"). This will open a console -window and start Apache running inside it. The window will remain -active until you stop Apache. To stop Apache running, either select -the "Shutdown Apache console app" icon option from the Start menu -(this is not available in Apache 1.3.4 or earlier), or see Signalling Apache when Running for how -to control Apache from the command line. - -
- -After starting Apache running (either in a console window or as a -service) if will be listening to port 80 (unless you changed the -Port, Listen or BindAddress -directives in the configuration files). To connect to the server and -access the default page, launch a browser and enter this URL: - -
- http://localhost/ -- -This should respond with a welcome page, and a link to the Apache -manual. If nothing happens or you get an error, look in the -error_log file in the logs directory. - -
- -Once your basic installation is working, you should configure it -properly by editing the files in the conf directory. - -
Configuring Apache for Windows
- -Apache is configured by files in the conf -directory. These are the same as files used to configure the Unix -version, but there are a few different directives for Apache on -Windows. See the Apache documentation for all the -available directives. - -- -The main differences in Apache for Windows are: - -
-
-
Because Apache for Windows is multithreaded, it does not use a - separate process for each request, as Apache does with - Unix. Instead there are usually only two Apache processes running: - a parent process, and a child which handles the requests. Within - the child each request is handled by a separate thread. -
- - So the "process"-management directives are different: -
MaxRequestsPerChild - - Like the Unix directive, this controls how many requests a - process will serve before exiting. However, unlike Unix, a - process serves all the requests at once, not just one, so if - this is set, it is recommended that a very high number is - used. The recommended default,
MaxRequestsPerChild - 0, does not cause the process to ever exit. -ThreadsPerChild - - This directive is new, and tells the server how many threads it - should use. This is the maximum number of connections the server - can handle at once; be sure and set this number high enough for - your site if you get a lot of hits. The recommended default is -
-ThreadsPerChild 50.The directives that accept filenames as arguments now must use - Windows filenames instead of Unix ones. However, because Apache - uses Unix-style names internally, you must use forward slashes, not - backslashes. Drive letters can be used; if omitted, the drive with - the Apache executable will be assumed.
-Apache for Windows contains the ability to load modules at runtime, - without recompiling the server. If Apache is compiled normally, it - will install a number of optional modules in the -
-\Apache\modulesdirectory. To activate these, or other - modules, the new LoadModule - directive must be used. For example, to active the status module, - use the following (in addition to the status-activating directives - inaccess.conf):- LoadModule status_module modules/ApacheModuleStatus.dll -
-Information on creating loadable - modules is also available.
-Apache can also load ISAPI Extensions (i.e., Internet Server - Applications), such as those used by Microsoft's IIS, and other - Windows servers. More information - is available. -
Running Apache for Windows from the Command Line
- -The Start menu icons and the NT Service manager can provide a simple -interface for administering Apache. But in some cases it is easier to -work from the command line. - --When working with Apache it is important to know how it will find the -configuration files. Apache will try one of the following, in this order. - -
-
-
- A ServerRoot directive via a -C switch. -
- The -f switch on the command line. -
- The -d switch on the command line. -
- A registry entry, created if you did a binary install. -
- The server root compiled into the server. -
-The server root compiled into the server is usually "/apache". -invoking apache with the -v switch will display this value -labeled as HTTPD_ROOT. - -
-Your current working directory when Apache is started up has no -effect on Apache's behavior. - -
-When invoked from the start menu or the Service Manager, Apache is -usually passed no arguments, so using the registry entry is the preferred -technique. - -
-During a binary installation, a registry key will have -been installed, for example: -
- HKEY_LOCAL_MACHINE\Software\Apache Group\Apache\1.3.4\ServerRoot -- -
-This key is compiled into the server and can enable you to test -new versions without affecting the current version. Of course -you must take care not to install the new version on top of the -old version in the file system. You cannot run two invocations -of Apache on Windows simultaneously. - -
-If you did not do a binary install then Apache will in some -scenarios complain that about the missing registry key. This -warning can be ignored if it otherwise was able to find it's -configuration files. - -
-The value of this key is the "ServerRoot" directory, containing the -conf directory. When Apache starts it will read the -httpd.conf file from this directory. If this file -contains a ServerRoot directive which is different from -the directory obtained from the registry key above, Apache will forget -the registry key and use the directory from the configuration file. -If you copy the Apache directory or configuration files to a new -location it is vital that you update the ServerRoot -directory in the httpd.conf file to the new location. - -
-To run Apache from the command line as a console application, use the -following command: - -
- apache -s -- -Apache will execute, and will remain running until it is stopped by pressing -control-C. (The -s option is not required by Windows 95, but on Windows NT it -prevents Apache waiting to see if Apache is running as a service.) - -
- -You can install Apache as a Windows NT service as follows: - -
- apache -i -- -and to remove the Apache service, use - -
- apache -u -- - -
Signalling Apache when running
- -On Windows 95, Apache runs as a console application. You can tell a -running Apache to stop by opening another console window and running - -- apache -k shutdown --
- Note: This option is only available with Apache 1.3.3 and - later. For earlier versions, you need to use Control-C in the - Apache console window to shut down the server. -- -
-This should be used instead of pressing Control-C in the running -Apache console window, because it lets Apache end any current -transactions and cleanup gracefully. - -
- -You can also tell Apache to restart. This makes it re-read the -configuration files. Any transactions in progress are allowed to -complete without interruption. To restart Apache, run - -
- apache -k restart --
- Note: This option is only available with Apache 1.3.3 and - later. For earlier versions, you need to use Control-C in the - Apache console window to shut down the server. -- -
-Note for people familiar with the Unix version of Apache: these
-commands provide a Windows equivalent to kill -TERM
-pid and kill -USR1 pid. The command
-line option used, -k, was chosen as a reminder of the
-"kill" command used on Unix.
-
-
Compiling Apache for Windows
- -Compiling Apache requires Microsoft Visual C++ 5.0 to be properly - installed. It is easiest to compile with the command-line tools - (nmake, etc...). Consult the VC++ manual to determine how to install - them.
- -First, unpack the Apache distribution into an appropriate
- directory. Open a command-line prompt, and change to the
- src subdirectory of the Apache distribution.
The master Apache makefile instructions are contained in the
- Makefile.nt file. To compile Apache on Windows NT, simply
- use one of the following commands:
-
-
-
nmake /f Makefile.nt _apacher(release build) -nmake /f Makefile.nt _apached(debug build) -
(1.3.4 and later) To compile Apache on Windows 95, use one of -
-
-
nmake /f Makefile_win32.txt(release build) -nmake /f Makefile_win32_debug.txt(debug build) -
These will both compile Apache. The latter will include debugging - information in the resulting files, making it easier to find bugs and - track down problems.
- -Apache can also be compiled using VC++'s Visual Studio development
- environment. Although compiling Apache in this manner is not as
- simple, it makes it possible to easily modify the Apache source, or
- to compile Apache if the command-line tools are not installed.
- Project files (.DSP) are included for each of the
- portions of Apache. To build Apache from the these projects files
- you will need to build the following projects in this order:
-
-
-
-
os\win32\ApacheOS.dsp-regex\regex.dsp-ap\ap.dsp-main\gen_uri_delims.dsp-main\gen_test_char.dsp-ApacheCore.dsp-Apache.dsp-
src\os\win32 subdirectory contains
- project files for the optional modules (see below).
-
-Once Apache has been compiled, it needs to be installed in its server
- root directory. The default is the \Apache
- directory, on the current hard drive.
To install the files into the \Apache directory
- automatically, use one the following nmake commands (see above):
-
-
nmake /f Makefile.nt installr INSTDIR=dir- (for release build) -nmake /f Makefile.nt installd INSTDIR=dir- (for debug build) -
-
-
nmake /f Makefile_win32.txt install INSTDIR=dir- (for release build) -nmake /f Makefile_win32_debug.txt install INSTDIR=dir- (for debug build) -
This will install the following:
- --
-
dir\Apache.exe- Apache executable -dir\ApacheCore.dll- Main Apache shared library -dir\modules\ApacheModule*.dll- Optional Apache - modules (7 files) -dir\conf- Empty configuration directory -dir\logs- Empty logging directory -
If you do not have nmake, or wish to install in a different directory, - be sure to use a similar naming scheme.
- --Before running the server you must fill out the conf directory. -Copy the *.conf-dist-win from the distribution conf directory -and rename *.conf. Edit the @@ServerRoot@@ entries to your -actual server root (for example "C:\apache"). Copy over -the conf/magic and conf/mime.types files as well. - - - - diff --git a/docs/manual/sections.html.en b/docs/manual/sections.html.en deleted file mode 100644 index 88f3329408c..00000000000 --- a/docs/manual/sections.html.en +++ /dev/null @@ -1,170 +0,0 @@ - -
-How Directory, Location and Files sections work
- -The sections<Directory>, <Location> and <Files> can contain
-directives which only apply to specified directories, URLs or files
-respectively. Also htaccess files can be used inside a directory to
-apply directives to that directory. This document explains how these
-different sections differ and how they relate to each other when
-Apache decides which directives apply for a particular directory or
-request URL.
-
-Directives allowed in the sections
- -Everything that is syntactically allowed in -<Directory> is also allowed in
-<Location> (except a sub-<Files>
-section). Semantically however some things, and the most
-notable are AllowOverride and the two options
-FollowSymLinks and SymLinksIfOwnerMatch,
-make no sense in <Location>,
-<LocationMatch> or <DirectoryMatch>.
-The same for <Files> -- syntactically everything
-is fine, but semantically some things are different.
-
-How the sections are merged
- -The order of merging is: - --
-
-
-
-
-
<Directory>(except regular expressions) and - .htaccess done simultaneously (with .htaccess overriding -<Directory>) - -
-
- -
-
<DirectoryMatch>, and -<Directory>with regular expressions - -
-
- <Files>and<FilesMatch>done - simultaneously -
-
- <Location>and<LocationMatch>done - simultaneously -
-
-
<Directory>, each group is processed in
-the order that they appear in the configuration
-files. <Directory> (group 1 above) is processed in
-the order shortest directory component to longest. If multiple
-<Directory> sections apply to the same directory
-they they are processed in the configuration file order. The
-configuration files are read in the order httpd.conf, srm.conf and
-access.conf. Configurations included via the Include
-directive will be treated as if they where inside the including file
-at the location of the Include directive.
-
-
-
-Sections inside <VirtualHost> sections are applied
-after the corresponding sections outside the virtual host
-definition. This allows virtual hosts to override the main server
-configuration. (Note: this only works correctly from 1.2.2 and 1.3a2
-onwards. Before those releases sections inside virtual hosts were
-applied before the main server).
-
-
Notes about using sections
- -The general guidelines are: - -- -
-
-
-
- If you are attempting to match objects at the filesystem level
- then you must use
<Directory>and/or -<Files>. -
-
- -
- If you are attempting to match objects at the URL level then you
- must use
<Location>-
-
-
-
-
- proxy control is done via
<Directory>. This is - a legacy mistake because the proxy existed prior to -<Location>. A future version of the config - language should probably switch this to -<Location>. -
-
-Note about .htaccess parsing: -
--
-
- - Modifying .htaccess parsing during Location doesn't do - anything because .htaccess parsing has already occurred. -
-<Location> and symbolic links:
-
-
-
-
- It is not possible to use "
Options FollowSymLinks" - or "Options SymLinksIfOwnerMatch" inside a -<Location>,<LocationMatch>- or<DirectoryMatch>section - (the options are simply ignored). - Using the options in question is only possible inside a -<Directory>section (or a.htaccessfile). -
-<Files> and Options:
-
-
-
-
- Apache won't check for it, but using an
Options- directive inside a<Files>section has no effect. -
-Another note: -
- --
-
-
- There is actually a
-
<Location>/<LocationMatch>- sequence performed just before the name translation phase (where -AliasesandDocumentRootsare used to - map URLs to filenames). The results of this sequence are - completely thrown away after the translation has completed. -
-
Stopping and Restarting Apache
- -This document covers stopping and restarting Apache on Unix -only. Windows users should see Signalling -Apache when running.
- -You will notice many httpd executables running on your system,
-but you should not send signals to any of them except the parent, whose
-pid is in the PidFile. That is to
-say you shouldn't ever need to send signals to any process except the
-parent. There are three signals that you can send the parent:
-TERM, HUP, and USR1, which will
-be described in a moment.
-
-
To send a signal to the parent you should issue a command such as: -
- -You can read about its progress by issuing: - -- kill -TERM `cat /usr/local/apache/logs/httpd.pid` -
- -Modify those examples to match your -ServerRoot and -PidFile settings. - -- tail -f /usr/local/apache/logs/error_log -
As of Apache 1.3 we provide a script src/support/apachectl
-which can be used to start, stop, and restart Apache. It may need a
-little customization for your system, see the comments at the top of
-the script.
-
-
TERM Signal: stop now
- -Sending the TERM signal to the parent causes it to
-immediately attempt to kill off all of its children. It may take it
-several seconds to complete killing off its children. Then the
-parent itself exits. Any requests in progress are terminated, and no
-further requests are served.
-
-
HUP Signal: restart now
- -Sending the HUP signal to the parent causes it to kill off
-its children like in TERM but the parent doesn't exit. It
-re-reads its configuration files, and re-opens any log files.
-Then it spawns a new set of children and continues
-serving hits.
-
-
Users of the
-status module
-will notice that the server statistics are
-set to zero when a HUP is sent.
-
-
Note: If your configuration file has errors in it when -you issue a -restart then your parent will not restart, it will exit with an error. -See below for a method of avoiding this. - -
USR1 Signal: graceful restart
- -Note: prior to release 1.2b9 this code is quite unstable -and shouldn't be used at all. - -
The USR1 signal causes the parent process to advise
-the children to exit after their current request (or to exit immediately
-if they're not serving anything). The parent re-reads its configuration
-files and re-opens its log files. As each child dies off the parent
-replaces it with a child from the new generation of the
-configuration, which begins serving new requests immediately.
-
-
This code is designed to always respect the -MaxClients, -MinSpareServers, -and MaxSpareServers settings. -Furthermore, it respects StartServers -in the following manner: if after one second at least StartServers new -children have not been created, then create enough to pick up the slack. -This is to say that the code tries to maintain both the number of children -appropriate for the current load on the server, and respect your wishes -with the StartServers parameter. - -
Users of the
-status module
-will notice that the server statistics
-are not set to zero when a USR1 is sent. The
-code
-was written to both minimize the time in which the server is unable to serve
-new requests (they will be queued up by the operating system, so they're
-not lost in any event) and to respect your tuning parameters. In order
-to do this it has to keep the scoreboard used to keep track
-of all children across generations.
-
-
The status module will also use a G to indicate those
-children which are still serving requests started before the graceful
-restart was given.
-
-
At present there is no way for a log rotation script using
-USR1 to know for certain that all children writing the
-pre-restart log have finished. We suggest that you use a suitable delay
-after sending the USR1 signal before you do anything with the
-old log. For example if most of your hits take less than 10 minutes to
-complete for users on low bandwidth links then you could wait 15 minutes
-before doing anything with the old log.
-
-
Note: If your configuration file has errors in it when -you issue a -restart then your parent will not restart, it will exit with an error. -In the case of graceful -restarts it will also leave children running when it exits. (These are -the children which are "gracefully exiting" by handling their last request.) -This will cause problems if you attempt to restart the server -- it will -not be able to bind to its listening ports. At present the only work -around is to check the syntax of your files before doing a restart. The -easiest way is to just run httpd as a non-root user. If there are no -errors it will attempt to open its sockets and logs and fail because it's -not root (or because the currently running httpd already has those ports -bound). If it fails for any other reason then it's probably a config file -error and the error should be fixed before issuing the graceful restart. - -
Appendix: signals and race conditions
- -Prior to Apache 1.2b9 there were several race conditions -involving the restart and die signals (a simple description of race -condition is: a time-sensitive problem, as in if something happens at just -the wrong time it won't behave as expected). For those architectures that -have the "right" feature set we have eliminated as many as we can. -But it should be noted that there still do exist race conditions on -certain architectures. - -
Architectures that use an on disk
-ScoreBoardFile
-have the potential to corrupt their scoreboards. This can result in
-the "bind: Address already in use" (after HUP) or
-"long lost child came home!" (after USR1). The former is
-a fatal error, while the latter just causes the server to lose a scoreboard
-slot. So it might be advisable to use graceful restarts, with
-an occasional hard restart. These problems are very difficult to work
-around, but fortunately most architectures do not require a scoreboard file.
-See the ScoreBoardFile documentation for a method to determine if your
-architecture uses it.
-
-
NEXT and MACHTEN (68k only) have small race
-conditions
-which can cause a restart/die signal to be lost, but should not cause the
-server to do anything otherwise problematic.
-
-
-
All architectures have a small race condition in each child involving -the second and subsequent requests on a persistent HTTP connection -(KeepAlive). It may exit after reading the request line but before -reading any of the request headers. There is a fix that was discovered -too late to make 1.2. In theory this isn't an issue because the KeepAlive -client has to expect these events because of network latencies and -server timeouts. In practice it doesn't seem to affect anything either --- in a test case the server was restarted twenty times per second and -clients successfully browsed the site without getting broken images or -empty documents. - - - - diff --git a/docs/manual/suexec.html.en b/docs/manual/suexec.html.en deleted file mode 100644 index 3d8623df04e..00000000000 --- a/docs/manual/suexec.html.en +++ /dev/null @@ -1,518 +0,0 @@ - - -
-Apache suEXEC Support
- --
-
-
- CONTENTS -
- What is suEXEC? -
- Before we begin. -
- suEXEC Security Model. -
- Configuring & Installing suEXEC -
- Enabling & Disabling suEXEC -
- Using suEXEC -
- Debugging suEXEC -
- Beware the Jabberwock: Warnings & - Examples -
What is suEXEC?
--The suEXEC feature -- introduced in Apache 1.2 -- provides -Apache users the ability to run CGI and SSI -programs under user IDs different from the user ID of the calling web-server. -Normally, when a CGI or SSI program executes, it runs as the same user who is -running the web server. -
- --Used properly, this feature can reduce considerably the security risks involved -with allowing users to develop and run private CGI or SSI programs. However, -if suEXEC is improperly configured, it can cause any number of problems and -possibly create new holes in your computer's security. If you aren't familiar -with managing setuid root programs and the security issues they present, we -highly recommend that you not consider using suEXEC. -
- - - -Before we begin.
--Before jumping head-first into this document, you should be aware of the -assumptions made on the part of the Apache Group and this document. -
- --First, it is assumed that you are using a UNIX derivate operating system that -is capable of setuid and setgid operations. -All command examples are given in this regard. Other platforms, if they are -capable of supporting suEXEC, may differ in their configuration. -
- --Second, it is assumed you are familiar with some basic concepts of your -computer's security and its administration. This involves an understanding -of setuid/setgid operations and the various effects they -may have on your system and its level of security. -
- --Third, it is assumed that you are using an unmodified -version of suEXEC code. All code for suEXEC has been carefully scrutinized and -tested by the developers as well as numerous beta testers. Every precaution -has been taken to ensure a simple yet solidly safe base of code. Altering this -code can cause unexpected problems and new security risks. It is -highly recommended you not alter the suEXEC code unless you -are well versed in the particulars of security programming and are willing to -share your work with the Apache Group for consideration. -
- --Fourth, and last, it has been the decision of the Apache Group to -NOT make suEXEC part of the default installation of Apache. -To this end, suEXEC configuration requires of the administrator careful -attention to details. After due consideration has been given to the various -settings for suEXEC, the administrator may install suEXEC through normal -installation methods. The values for these settings need to be carefully -determined and specified by the administrator to properly maintain system -security during the use of suEXEC functionality. It is through this detailed -process that the Apache Group hopes to limit suEXEC installation only to those -who are careful and determined enough to use it. -
- --Still with us? Yes? Good. Let's move on! -
- - - -suEXEC Security Model
--Before we begin configuring and installing suEXEC, we will first discuss -the security model you are about to implement. By doing so, you may -better understand what exactly is going on inside suEXEC and what precautions -are taken to ensure your system's security. -
- --suEXEC is based on a setuid "wrapper" program that is -called by the main Apache web server. This wrapper is called when an HTTP -request is made for a CGI or SSI program that the administrator has designated -to run as a userid other than that of the main server. When such a request -is made, Apache provides the suEXEC wrapper with the program's name and the -user and group IDs under which the program is to execute. -
- --The wrapper then employs the following process to determine success or -failure -- if any one of these conditions fail, the program logs the failure -and exits with an error, otherwise it will continue: -
-
-
- Was the wrapper called with the proper number of
- arguments?
-
- The wrapper will only execute if it is given the proper number of arguments. - The proper argument format is known to the Apache web server. If the - wrapper - is not receiving the proper number of arguments, it is either being hacked, - or - there is something wrong with the suEXEC portion of your Apache binary. -
-
- - Is the user executing this wrapper a valid user of this
- system?
-
- This is to ensure that the user executing the wrapper is truly a user of the - system. -
-
- - Is this valid user allowed to run the wrapper?
-
- Is this user the user allowed to run this wrapper? Only one user (the - Apache user) is allowed to execute this program. -
-
- - Does the target program have an unsafe hierarchical
- reference?
-
- Does the target program contain a leading '/' or have a '..' backreference? - These are not allowed; the target program must reside within the Apache - webspace. -
-
- - Is the target user name valid?
-
- Does the target user exist? -
-
- - Is the target group name valid?
-
- Does the target group exist? -
-
- - Is the target user NOT superuser?
-
- Presently, suEXEC does not allow 'root' to execute CGI/SSI programs. -
-
- - Is the target userid ABOVE the minimum ID
- number?
-
- The minimum user ID number is specified during configuration. This allows - you - to set the lowest possible userid that will be allowed to execute CGI/SSI - programs. This is useful to block out "system" accounts. -
-
- - Is the target group NOT the superuser group?
-
- Presently, suEXEC does not allow the 'root' group to execute CGI/SSI - programs. -
-
- - Is the target groupid ABOVE the minimum ID
- number?
-
- The minimum group ID number is specified during configuration. This allows - you - to set the lowest possible groupid that will be allowed to execute CGI/SSI - programs. This is useful to block out "system" groups. -
-
- - Can the wrapper successfully become the target user and
- group?
-
- Here is where the program becomes the target user and group via setuid and - setgid - calls. The group access list is also initialized with all of the groups - of which - the user is a member. -
-
- - Does the directory in which the program resides exist?
-
- If it doesn't exist, it can't very well contain files. -
-
- - Is the directory within the Apache webspace?
-
- If the request is for a regular portion of the server, is the requested - directory - within the server's document root? If the request is for a UserDir, is - the requested - directory within the user's document root? -
-
- - Is the directory NOT writable by anyone else?
-
- We don't want to open up the directory to others; only the owner user - may be able - to alter this directories contents. -
-
- - Does the target program exist?
-
- If it doesn't exists, it can't very well be executed. -
-
- - Is the target program NOT writable by anyone
- else?
-
- We don't want to give anyone other than the owner the ability to - change the program. -
-
- - Is the target program NOT setuid or setgid?
-
- We do not want to execute programs that will then change our UID/GID again. -
-
- - Is the target user/group the same as the program's
- user/group?
-
- Is the user the owner of the file? -
-
- - Can we successfully clean the process environment to
- ensure safe operations?
-
- suEXEC cleans the process' environment by establishing a safe - execution PATH (defined - during configuration), as well as only passing through those - variables whose names - are listed in the safe environment list (also created during - configuration). -
-
- - Can we successfully become the target program and
- execute?
-
- Here is where suEXEC ends and the target program begins. -
-
-
-This is the standard operation of the the suEXEC wrapper's security model. -It is somewhat stringent and can impose new limitations and guidelines for -CGI/SSI design, but it was developed carefully step-by-step with security -in mind. -
- --For more information as to how this security model can limit your possibilities -in regards to server configuration, as well as what security risks can be -avoided with a proper suEXEC setup, see the -"Beware the Jabberwock" -section of this document. -
- - - -Configuring & Installing suEXEC
-
-Here's where we begin the fun. If you use Apache 1.2 or prefer to configure
-Apache 1.3 with the "src/Configure" script you have to edit
-the suEXEC header file and install the binary in its proper location
-manually. This procedure is described in an
-extra document.
-The following sections describe the configuration and installation
-for Apache 1.3 with the AutoConf-style interface (APACI).
-
-APACI's suEXEC configuration options
-
-
-
--enable-suexec-- This option enables the suEXEC feature which is never installed or - activated by default. At least one --suexec-xxxxx option has to be - provided together with the --enable-suexec option to let APACI - accept your request for using the suEXEC feature. -
--suexec-caller=UID-- The username under which - Apache normally runs. - This is the only user allowed to execute this program. -
--suexec-docroot=DIR-- Define as the DocumentRoot set for Apache.
- This will be the only hierarchy (aside from UserDirs)
- that can be used for suEXEC behavior.
- The default directory is the --datadir value with
- the suffix "/htdocs", e.g. if you configure with
- "
--datadir=/home/apache" the directory - "/home/apache/htdocs" is used as document root for - the suEXEC wrapper. - --suexec-logfile=FILE-- This defines the filename to which all suEXEC transactions and - errors are logged (useful for auditing and debugging purposes). - By default the logfile is named "suexec_log" and located in your - standard logfile directory (--logfiledir). -
--suexec-userdir=DIR-- Define to be the subdirectory under users'
- home directories where suEXEC access should
- be allowed. All executables under this directory
- will be executable by suEXEC as the user so
- they should be "safe" programs. If you are
- using a "simple" UserDir directive (ie. one
- without a "*" in it) this should be set to
- the same value. suEXEC will not work properly
- in cases where the UserDir directive points to
- a location that is not the same as the user's
- home directory as referenced in the passwd file.
- Default value is "public_html".
-
- If you have virtual hosts with a different - UserDir for each, you will need to define them to - all reside in one parent directory; then name that - parent directory here. If this is not defined - properly, "~userdir" cgi requests will not work! - --suexec-uidmin=UID-- Define this as the lowest UID allowed to be a target user - for suEXEC. For most systems, 500 or 100 is common. - Default value is 100. -
--suexec-gidmin=GID-- Define this as the lowest GID allowed to be a target group - for suEXEC. For most systems, 100 is common and therefore - used as default value. -
--suexec-safepath=PATH-- Define a safe PATH environment to pass to CGI executables. - Default value is "/usr/local/bin:/usr/bin:/bin". -
-Checking your suEXEC setup
-Before you compile and install the suEXEC wrapper you can check
-the configuration with the --layout option.
-
-Example output:
-
- suEXEC setup: - suexec binary: /usr/local/apache/sbin/suexec - document root: /usr/local/apache/share/htdocs - userdir suffix: public_html - logfile: /usr/local/apache/var/log/suexec_log - safe path: /usr/local/bin:/usr/bin:/bin - caller ID: www - minimum user ID: 100 - minimum group ID: 100 -- - -
-Compiling and installing the suEXEC wrapper
-If you have enabled the suEXEC feature with the --enable-suexec option
-the suexec binary (together with Apache itself) is automatically built
-if you execute the command "make".
-
-After all components have been built you can execute the command
-"make install" to install them.
-The binary image "suexec" is installed in the directory defined by
-the --sbindir option. Default location is "/usr/local/apache/sbin/suexec".
-
-Please note that you need root privileges for
-the installation step. In order for the wrapper to set the user ID, it
-must be installed as owner root and must have the
-setuserid execution bit set for file modes.
-
Enabling & Disabling suEXEC
--Upon startup of Apache, it looks for the file "suexec" in the "sbin" -directory (default is "/usr/local/apache/sbin/suexec"). -If Apache finds a properly configured suEXEC wrapper, it will print -the following message to the error log: -
- [notice] suEXEC mechanism enabled (wrapper: /path/to/suexec) --If you don't see this message at server startup, the server is most -likely not finding the wrapper program where it expects it, or the -executable is not installed setuid root. -
-If you want to enable the suEXEC mechanism for the first time -and an Apache server is already running you must kill and restart Apache. -Restarting it with a simple HUP or USR1 signal will not be enough. -
-If you want to disable suEXEC you should kill and restart Apache after -you have removed the "suexec" file. - - - - -
Using suEXEC
-
-Virtual Hosts:
-One way to use the suEXEC wrapper is through the
-User and
-Group directives in
-VirtualHost
-definitions. By setting these directives to values different from the
-main server user ID, all requests for CGI resources will be executed as
-the User and Group defined for that
-<VirtualHost>. If only one or
-neither of these directives are specified for a
-<VirtualHost> then the main
-server userid is assumed.
-
-User directories:
-The suEXEC wrapper can also be used to execute CGI programs as
-the user to which the request is being directed. This is accomplished by
-using the "~" character prefixing the user
-ID for whom execution is desired.
-The only requirement needed for this feature to work is for CGI
-execution to be enabled for the user and that the script must meet the
-scrutiny of the security checks above.
-
-
Debugging suEXEC
--The suEXEC wrapper will write log information to the file defined -with the --suexec-logfile option as indicated above. If you feel you have -configured and installed the wrapper properly, have a look at this log -and the error_log for the server to see where you may have gone astray. -
- - - --Beware the Jabberwock: Warnings & Examples -
--NOTE! This section may not be complete. For the latest -revision of this section of the documentation, see the Apache Group's -Online Documentation -version. -
- --There are a few points of interest regarding the wrapper that can cause -limitations on server setup. Please review these before submitting any -"bugs" regarding suEXEC. -
-
-
- suEXEC Points Of Interest -
- Hierarchy limitations
-
- For security and efficiency reasons, all suexec requests must - remain within either a top-level document root for virtual - host requests, or one top-level personal document root for - userdir requests. For example, if you have four VirtualHosts - configured, you would need to structure all of your VHosts' - document roots off of one main Apache document hierarchy to - take advantage of suEXEC for VirtualHosts. (Example forthcoming.) -
-
- - suEXEC's PATH environment variable
-
- This can be a dangerous thing to change. Make certain every - path you include in this define is a trusted - directory. You don't want to open people up to having someone - from across the world running a trojan horse on them. -
-
- - Altering the suEXEC code
-
- Again, this can cause Big Trouble if you try - this without knowing what you are doing. Stay away from it - if at all possible. -
-
-
File Descriptor Limits
- --When using a large number of Virtual Hosts, Apache may run out of available -file descriptors (sometimes called file handles if each Virtual -Host specifies different log files. -The total number of file descriptors used by Apache is one for each distinct -error log file, one for every other log file directive, plus 10-20 for -internal use. Unix operating systems limit the number of file descriptors that -may be used by a process; the limit is typically 64, and may usually be -increased up to a large hard-limit. -
-Although Apache attempts to increase the limit as required, this -may not work if: -
-
-
- Your system does not provide the setrlimit() system call. -
- The setrlimit(RLIMIT_NOFILE) call does not function on your system - (such as Solaris 2.3) -
- The number of file descriptors required exceeds the hard limit. -
- Your system imposes other limits on file descriptors, such as a limit -on stdio streams only using file descriptors below 256. (Solaris 2) -
-
-
- Reduce the number of log files; don't specify log files in the VirtualHost -sections, but only log to the main log files. -
- If you system falls into 1 or 2 (above), then increase the file descriptor
-limit before starting Apache, using a script like
-
--#!/bin/sh
-ulimit -S -n 100
-exec httpd
-Please see the -Descriptors and Apache -document containing further details about file descriptor problems and how -they can be solved on your operating system. -
- - - - diff --git a/docs/manual/vhosts/index.html.en b/docs/manual/vhosts/index.html.en deleted file mode 100644 index 9a569028cf8..00000000000 --- a/docs/manual/vhosts/index.html.en +++ /dev/null @@ -1,65 +0,0 @@ - - - -Apache Virtual Host documentation
- -The term Virtual Host refers to the practice of maintaining -more than one server on one machine, as differentiated by their apparent -hostname. For example, it is often desirable for companies sharing a -web server to have their own domains, with web servers accessible as -www.company1.com and www.company2.com, -without requiring the user to know any extra path information.
- -Apache was one of the first servers to support IP-based -virtual hosts right out of the box. Versions 1.1 and later of -Apache support both, IP-based and name-based virtual hosts (vhosts). -The latter variant of virtual hosts is sometimes also called host-based or -non-IP virtual hosts.
- -Below is a list of documentation pages which explain all details -of virtual host support in Apache version 1.3 and later.
- -- -
Virtual Host Support
- --
-
- IP-based Virtual Hosts -
- Name-based Virtual Hosts -
- Virtual Host examples for common setups -
- In-Depth Discussion of Virtual Host Matching -
- File Descriptor Limits -
- Dynamically Configured Mass Virtual Hosting with mod_rewrite -
Configuration directives
- - - -Folks trying to debug their virtual host configuration may find the
-Apache -S command line switch useful. It will dump out a
-description of how Apache parsed the configuration file. Careful
-examination of the IP addresses and server names may help uncover
-configuration mistakes.
-
-
-
-
diff --git a/docs/manual/vhosts/name-based.html.en b/docs/manual/vhosts/name-based.html.en
deleted file mode 100644
index 238cf5c7211..00000000000
--- a/docs/manual/vhosts/name-based.html.en
+++ /dev/null
@@ -1,164 +0,0 @@
-
-
Apache name-based Virtual Host Support
- -See Also: -IP-based Virtual Host Support - -- -
Name-based vs. IP-based virtual hosts
- -While the approach with IP-based virtual hosts works very well,
-it is not the most elegant solution, because a dedicated IP address
-is needed for every virtual host and it is hard to implement on some
-machines. The HTTP/1.1 protocol contains a method for the
-server to identify what name it is being addressed as. Apache 1.1 and
-later support this approach as well as the traditional
-IP-address-per-hostname method.
The benefits of using the new name-based virtual host support is a -practically unlimited number of servers, ease of configuration and use, and -requires no additional hardware or software. -The main disadvantage is that the client must support this part of the -protocol. The latest versions of most browsers do, but there are still -old browsers in use who do not. This can cause problems, although a possible -solution is addressed below.
- -Using non-IP Virtual Hosts
- -Using the new virtual hosts is quite easy, and superficially looks
-like the old method. The notable difference between IP-based and
-name-based virtual host configuration is the
-NameVirtualHost
-directive which specifies an IP address that should be used as a
-target for name-based virtual hosts.
For example, suppose that both www.domain.tld and
-www.otherdomain.tld point at the IP address
-111.22.33.44. Then you simply add to one of the Apache
-configuration files (most likely httpd.conf or
-srm.conf) code similar to the following:
- NameVirtualHost 111.22.33.44 - - <VirtualHost 111.22.33.44> - ServerName www.domain.tld - DocumentRoot /www/domain - </VirtualHost> - - <VirtualHost 111.22.33.44> - ServerName www.otherdomain.tld - DocumentRoot /www/otherdomain - </VirtualHost> -- -
Of course, any additional directives can (and should) be placed
-into the <VirtualHost> section. To make this work,
-all that is needed is to make sure that the names
-www.domain.tld and www.otherdomain.tld
-are pointing to the IP address 111.22.33.44
Note: When you specify an IP address in a NameVirtualHost
-directive then requests to that IP address will only ever be served
-by matching <VirtualHost>s. The "main server" will
-never be served from the specified IP address.
-If you start to use virtual hosts you should stop to use the "main server"
-as an independent server and rather use it as a place for
-configuration directives that are common for all your virtual hosts.
-In other words, you should add a <VirtualHost> section for
-every server (hostname) you want to maintain on your server.
-
-
Additionally, many servers may wish to be accessible by more than
-one name. For example, the example server might want to be accessible
-as domain.tld, or www2.domain.tld, assuming
-the IP addresses pointed to the same server. In fact, one might want it
-so that all addresses at domain.tld were picked up by the
-server. This is possible with the
-ServerAlias
-directive, placed inside the <VirtualHost> section. For
-example:
- ServerAlias domain.tld *.domain.tld -- -
Note that you can use * and ? as wild-card
-characters.
You also might need ServerAlias if you are
-serving local users who do not always include the domain name.
-For example, if local users are
-familiar with typing "www" or "www.foobar" then you will need to add
-ServerAlias www www.foobar. It isn't possible for the
-server to know what domain the client uses for their name resolution
-because the client doesn't provide that information in the request.
-The ServerAlias directive is generally a way to have different
-hostnames pointing to the same virtual host.
-
Compatibility with Older Browsers
- -As mentioned earlier, there are still some clients in use who -do not send the required data for the name-based virtual hosts to work -properly. These clients will always be sent the pages from the -first virtual host listed for that IP address (the -primary name-based virtual host).
- -There is a possible workaround with the
-ServerPath
-directive, albeit a slightly cumbersome one:
Example configuration: - -
- NameVirtualHost 111.22.33.44 - - <VirtualHost 111.22.33.44> - ServerName www.domain.tld - ServerPath /domain - DocumentRoot /web/domain - </VirtualHost> -- -
What does this mean? It means that a request for any URI beginning
-with "/domain" will be served from the virtual host
-www.domain.tld This means that the pages can be accessed as
-http://www.domain.tld/domain/ for all clients, although
-clients sending a Host: header can also access it as
-http://www.domain.tld/.
In order to make this work, put a link on your primary virtual host's page -to http://www.domain.tld/domain/ -Then, in the virtual host's pages, be sure to use either purely -relative links (e.g., "file.html" or -"../icons/image.gif" or links containing the prefacing -/domain/ -(e.g., "http://www.domain.tld/domain/misc/file.html" or -"/domain/misc/file.html").
- -This requires a bit of -discipline, but adherence to these guidelines will, for the most part, -ensure that your pages will work with all browsers, new and old.
- -See also: ServerPath configuration -example
- - - -