From: Joshua Slive Date: Sat, 9 Mar 2002 18:31:00 +0000 (+0000) Subject: New xml versions. X-Git-Tag: CHANGES~163 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=adad84a7cebea4c2cc818a7e71365e49e9b89723;p=thirdparty%2Fapache%2Fhttpd.git New xml versions. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@93814 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_isapi.xml b/docs/manual/mod/mod_isapi.xml new file mode 100644 index 00000000000..c64cbd0b188 --- /dev/null +++ b/docs/manual/mod/mod_isapi.xml @@ -0,0 +1,271 @@ + + + + + +mod_isapi +ISAPI Extensions within Apache for Windows +Base +mod_isapi.c +isapi_module +Win32 only + + +

This module implements the Internet Server extension API. It + allows Internet Server extensions (e.g. ISAPI .dll + modules) to be served by Apache for Windows, subject to the + noted restrictions.

+ +

ISAPI extension modules (.dll files) are written by third + parties. The Apache Group does not author these modules, so we + provide no support for them. Please contact the ISAPI's author + directly if you are experiencing problems running their ISAPI + extention. Please do not post such problems to + Apache's lists or bug reporting pages.

+ + +
Usage

In the server configuration file, use +the AddHandler directive to +associate ISAPI files with the isapi-isa handler, and map +it to the with their file extensions. To enable any .dll file to be +processed as an ISAPI extention, edit the httpd.conf file and add the +following line:

+ + AddHandler isapi-isa .dll + + +

There is no capability within the Apache server to leave a + requested module loaded. However, you may preload and keep a + specific module loaded by using the following syntax in your + httpd.conf:

+ + ISAPICacheFile c:/WebWork/Scripts/ISAPI/mytest.dll + + +

Whether or not you have preloaded an ISAPI extension, all + ISAPI extensions are governed by the same permissions and + restrictions as CGI scripts. That is, Options + ExecCGI must be set for the directory that contains the + ISAPI .dll file.

+ +

Review the Additional Notes and the Programmer's Journal for additional details + and clarification of the specific ISAPI support offered by + mod_isapi.

+
+ +
Additional Notes + +

Apache's ISAPI implementation conforms to all of the ISAPI + 2.0 specification, except for some "Microsoft-specific" + extensions dealing with asynchronous I/O. Apache's I/O model + does not allow asynchronous reading and writing in a manner + that the ISAPI could access. If an ISA tries to access + unsupported features, including async I/O, a message is placed + in the error log to help with debugging. Since these messages + can become a flood, the directive ISAPILogNotSupported + Off exists to quiet this noise.

+ +

Some servers, like Microsoft IIS, load the ISAPI extension + into the server and keep it loaded until memory usage is too + high, or unless configuration options are specified. Apache + currently loads and unloads the ISAPI extension each time it is + requested, unless the ISAPICacheFile directive is specified. + This is inefficient, but Apache's memory model makes this the + most effective method. Many ISAPI modules are subtly + incompatible with the Apache server, and unloading these + modules helps to ensure the stability of the server.

+ +

Also, remember that while Apache supports ISAPI Extensions, + it does not support ISAPI Filters. Support for + filters may be added at a later date, but no support is planned + at this time.

+
+ +
Programmer's Journal + +

If you are programming Apache 2.0 mod_isapi + modules, you must limit your calls to ServerSupportFunction to the + following directives:

+ +
+
HSE_REQ_SEND_URL_REDIRECT_RESP
+ +
Redirect the user to another location.
+ This must be a fully qualified URL (e.g. + http://server/location).
+ +
HSE_REQ_SEND_URL
+ +
Redirect the user to another location.
+ This cannot be a fully qualified URL, you are not allowed to + pass the protocol or a server name (e.g. simply + /location).
+ This redirection is handled by the server, not the + browser.
+ Warning: in their recent documentation, + Microsoft appears to have abandoned the distinction between + the two HSE_REQ_SEND_URL functions. Apache continues to treat + them as two distinct functions with different requirements + and behaviors.
+ +
HSE_REQ_SEND_RESPONSE_HEADER
+ +
Apache accepts a response body following the header if it + follows the blank line (two consecutive newlines) in the + headers string argument. This body cannot contain NULLs, + since the headers argument is NULL terminated.
+ +
HSE_REQ_DONE_WITH_SESSION
+ +
Apache considers this a no-op, since the session will be + finished when the ISAPI returns from processing.
+ +
HSE_REQ_MAP_URL_TO_PATH
+ +
Apache will translate a virtual name to a physical + name.
+ +
HSE_APPEND_LOG_PARAMETER
+ +
+ This logged message may be captured in any of the following + logs: + +
    +
  • in the \"%{isapi-parameter}n\" component in a + CustomLog directive
    • + +
  • in the %q log component with the + ISAPIAppendLogToQuery On directive
    • + +
  • in the error log with the ISAPIAppendLogToErrors On + directive
    • +
+ The first option, the %{isapi-parameter}n component, is + always available and prefered. +
+ +
HSE_REQ_IS_KEEP_CONN
+ +
Will return the negotiated Keep-Alive status.
+ +
HSE_REQ_SEND_RESPONSE_HEADER_EX
+ +
Will behave as documented, although the fKeepConn flag is + ignored.
+ +
HSE_REQ_IS_CONNECTED
+ +
Will report false if the request has been aborted.
+
+ +

Apache returns FALSE to any unsupported call to + ServerSupportFunction, and sets the GetLastError value to + ERROR_INVALID_PARAMETER.

+ +

ReadClient retrieves the request body exceeding the initial + buffer (defined by ISAPIReadAheadBuffer). Based on the + ISAPIReadAheadBuffer setting (number of bytes to buffer prior + to calling the ISAPI handler) shorter requests are sent + complete to the extension when it is invoked. If the request is + longer, the ISAPI extension must use ReadClient to retrieve the + remaining request body.

+ +

WriteClient is supported, but only with the HSE_IO_SYNC flag + or no option flag (value of 0). Any other WriteClient request + will be rejected with a return value of FALSE, and a + GetLastError value of ERROR_INVALID_PARAMETER.

+ +

GetServerVariable is supported, although extended server + variables do not exist (as defined by other servers.) All the + usual Apache CGI environment variables are available from + GetServerVariable, as well as the ALL_HTTP and ALL_RAW + values.

+ +

Apache 2.0 mod_isapi supports additional + features introduced in later versions of the ISAPI specification, + as well as limited emulation of async I/O and the TransmitFile + semantics. Apache also supports preloading ISAPI .dlls for + performance, neither of which were not available under Apache 1.3 + mod_isapi.

+
+ + +ISAPIFileChache +ISAPI .dll files to be loaded at startup +ISAPIFileCache file-path [file-path] ... +server config + + +

Specifies a space-separated list of file names to be loaded + when the Apache server is launched, and remain loaded until the + server is shut down. This directive may be repeated for every + ISAPI .dll file desired. The full path name of each file should + be specified.

+ + + + +ISAPIReadAheadBuffer +Size of the Read Ahead Buffer sent to ISAPI +extensions +ISAPIReadAheadBuffer size +ISAPIReadAheadBuffer 49152 +server config + + +

Defines the maximum size of the Read Ahead Buffer sent to + ISAPI extensions when they are initially invoked. All remaining + data must be retrieved using the ReadClient callback; some + ISAPI extensions may not support the ReadClient function. Refer + questions to the ISAPI extension's author.

+ + + + +ISAPILogNotSupported +Log unsupported feature requests from ISAPI +extensions +ISAPILogNotSupported on|off +ISAPILogNotSupported on +server config + + +

Logs all requests for unsupported features from ISAPI + extensions in the server error log. While this should be turned + off once all desired ISAPI modules are functioning, it defaults + to on to help administrators track down problems.

+ + + + +ISAPIAppendLogToErrors +Record HSE_APPEND_LOG_PARAMETER requests from ISAPI +extensions to the error log +ISAPIAppendLogToErrors on|off +ISAPIAppendLogToErrors off +server config + + +

Record HSE_APPEND_LOG_PARAMETER requests from ISAPI + extensions to the server error log.

+ + + + +ISAPIAppendLogToQuery +Record HSE_APPEND_LOG_PARAMETER requests from ISAPI +extensions to the query field +ISAPIAppendLogToQuery on|off +ISAPIAppendLogToQuery off +server config + + +

Record HSE_APPEND_LOG_PARAMETER requests from ISAPI + extensions to the query field (appended to the CustomLog %q + component).

+ + + + \ No newline at end of file diff --git a/docs/manual/mod/mod_mime_magic.xml b/docs/manual/mod/mod_mime_magic.xml new file mode 100644 index 00000000000..18f22158d11 --- /dev/null +++ b/docs/manual/mod/mod_mime_magic.xml @@ -0,0 +1,304 @@ + + + + + +mod_mime_magic +Determines the MIME type of a file + by looking at a few bytes of its contents +Extension +mod_mime_magic.c +mime_magic_module + + +

This module determines the MIME type of files in the same + way the Unix file(1) command works: it looks at the first few + bytes of the file. It is intended as a "second line of defense" + for cases that mod_mime can't + resolve. To assure that mod_mime gets first try at determining + a file's MIME type, be sure to list mod_mime_magic + before mod_mime in the configuration.

+ +

This module is derived from a free version of the + file(1) command for Unix, which uses "magic + numbers" and other hints from a file's contents to figure out + what the contents are. This module is active only if the magic + file is specified by the MimeMagicFile directive.

+ + +
Format of the Magic File + +

The contents of the file are plain ASCII text in 4-5 + columns. Blank lines are allowed but ignored. Commented lines + use a hash mark "#". The remaining lines are parsed for the + following columns:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ColumnDescription
1byte number to begin checking from
+ ">" indicates a dependency upon the previous non-">" + line
2 + type of data to match + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
bytesingle character
shortmachine-order 16-bit integer
longmachine-order 32-bit integer
stringarbitrary-length string
datelong integer date (seconds since Unix + epoch/1970)
beshortbig-endian 16-bit integer
belongbig-endian 32-bit integer
bedatebig-endian 32-bit integer date
leshortlittle-endian 16-bit integer
lelonglittle-endian 32-bit integer
ledatelittle-endian 32-bit integer date
+
3contents of data to match
4MIME type if matched
5MIME encoding if matched (optional)
+ +

For example, the following magic file lines would recognize + some audio formats.

+ +
+# Sun/NeXT audio data
+0       string          .snd
+>12     belong          1               audio/basic
+>12     belong          2               audio/basic
+>12     belong          3               audio/basic
+>12     belong          4               audio/basic
+>12     belong          5               audio/basic
+>12     belong          6               audio/basic
+>12     belong          7               audio/basic
+>12     belong          23              audio/x-adpcm
+
+ +

Or these would recognize the difference between "*.doc" files + containing Microsoft Word or FrameMaker documents. (These are + incompatible file formats which use the same file suffix.)

+ +
+# Frame
+0       string          \<MakerFile     application/x-frame
+0       string          \<MIFFile       application/x-frame
+0       string          \<MakerDictionary       application/x-frame
+0       string          \<MakerScreenFon        application/x-frame
+0       string          \<MML           application/x-frame
+0       string          \<Book          application/x-frame
+0       string          \<Maker         application/x-frame
+
+# MS-Word
+0       string          \376\067\0\043                  application/msword
+0       string          \320\317\021\340\241\261        application/msword
+0       string          \333\245-\0\0\0                 application/msword
+
+ +

An optional MIME encoding can be included as a fifth column. + For example, this can recognize gzipped files and set the + encoding for them.

+ +
+# gzip (GNU zip, not to be confused with [Info-ZIP/PKWARE] zip archiver)
+0       string          \037\213        application/octet-stream        x-gzip
+
+ +
+ +
Performance Issues +

This module is not for every system. If your system is barely + keeping up with its load or if you're performing a web server + benchmark, you may not want to enable this because the + processing is not free.

+ +

However, an effort was made to improve the performance of + the original file(1) code to make it fit in a busy web server. + It was designed for a server where there are thousands of users + who publish their own documents. This is probably very common + on intranets. Many times, it's helpful if the server can make + more intelligent decisions about a file's contents than the + file name allows ...even if just to reduce the "why doesn't my + page work" calls when users improperly name their own files. + You have to decide if the extra work suits your + environment.

+ +

When compiling an Apache server, this module should be at or + near the top of the list of modules in the Configuration file. + The modules are listed in increasing priority so that will mean + this one is used only as a last resort, just like it was + designed to.

+ +
+ +
Notes + +

The following notes apply to the mod_mime_magic module and are + included here for compliance with contributors' copyright + restrictions that require their acknowledgment.

+
+/*
+ * mod_mime_magic: MIME type lookup via file magic numbers
+ * Copyright (c) 1996-1997 Cisco Systems, Inc.
+ *
+ * This software was submitted by Cisco Systems to the Apache Group in July
+ * 1997.  Future revisions and derivatives of this source code must
+ * acknowledge Cisco Systems as the original contributor of this module.
+ * All other licensing and usage conditions are those of the Apache Group.
+ *
+ * Some of this code is derived from the free version of the file command
+ * originally posted to comp.sources.unix.  Copyright info for that program
+ * is included below as required.
+ * ---------------------------------------------------------------------------
+ * - Copyright (c) Ian F. Darwin, 1987. Written by Ian F. Darwin.
+ *
+ * This software is not subject to any license of the American Telephone and
+ * Telegraph Company or of the Regents of the University of California.
+ *
+ * Permission is granted to anyone to use this software for any purpose on any
+ * computer system, and to alter it and redistribute it freely, subject to
+ * the following restrictions:
+ *
+ * 1. The author is not responsible for the consequences of use of this
+ * software, no matter how awful, even if they arise from flaws in it.
+ *
+ * 2. The origin of this software must not be misrepresented, either by
+ * explicit claim or by omission.  Since few users ever read sources, credits
+ * must appear in the documentation.
+ *
+ * 3. Altered versions must be plainly marked as such, and must not be
+ * misrepresented as being the original software.  Since few users ever read
+ * sources, credits must appear in the documentation.
+ *
+ * 4. This notice may not be removed or altered.
+ * -------------------------------------------------------------------------
+ *
+ * For compliance with Mr Darwin's terms: this has been very significantly
+ * modified from the free "file" command.
+ * - all-in-one file for compilation convenience when moving from one
+ *   version of Apache to the next.
+ * - Memory allocation is done through the Apache API's pool structure.
+ * - All functions have had necessary Apache API request or server
+ *   structures passed to them where necessary to call other Apache API
+ *   routines.  (i.e., usually for logging, files, or memory allocation in
+ *   itself or a called function.)
+ * - struct magic has been converted from an array to a single-ended linked
+ *   list because it only grows one record at a time, it's only accessed
+ *   sequentially, and the Apache API has no equivalent of realloc().
+ * - Functions have been changed to get their parameters from the server
+ *   configuration instead of globals.  (It should be reentrant now but has
+ *   not been tested in a threaded environment.)
+ * - Places where it used to print results to stdout now saves them in a
+ *   list where they're used to set the MIME type in the Apache request
+ *   record.
+ * - Command-line flags have been removed since they will never be used here.
+ *
+ */
+
+
+ + +MimeMagicFile +Enable MIME-type determination based on file contents +using the specified magic file +MimeMagicFile file-path +server config +virtual host + + +

The MimeMagicFile directive can be used to + enable this module, the default file is distributed at + conf/magic. Non-rooted paths are relative to the + ServerRoot. Virtual hosts will use the same file as the main + server unless a more specific setting is used, in which case + the more specific setting overrides the main server's file.

+ + + + diff --git a/docs/manual/mod/mod_negotiation.xml b/docs/manual/mod/mod_negotiation.xml new file mode 100644 index 00000000000..12904441a84 --- /dev/null +++ b/docs/manual/mod/mod_negotiation.xml @@ -0,0 +1,243 @@ + + + + + +mod_negotiation +Provides for content negotiation +Base +mod_negotiation.c +negotiation_module + + +

Content negotiation, or more accurately content selection, is + the selection of the document that best matches the clients + capabilities, from one of several available documents. There + are two implementations of this.

+ +
    +
  • A type map (a file with the handler + type-map) which explicitly lists the files + containing the variants.
    • + +
  • A MultiViews search (enabled by the MultiViews Options, where the server does an + implicit filename pattern match, and choose from amongst the + results.
    • +
+ + +DefaultLangauge +AddEncoding +AddLanguage +AddType + +
Type maps +

A type map has the same format as RFC822 mail headers. It + contains document descriptions separated by blank lines, with + lines beginning with a hash character ('#') treated as + comments. A document description consists of several header + records; records may be continued on multiple lines if the + continuation lines start with spaces. The leading space will be + deleted and the lines concatenated. A header record consists of + a keyword name, which always ends in a colon, followed by a + value. Whitespace is allowed between the header name and value, + and between the tokens of value. The headers allowed are:

+ +
+
Content-Encoding:
+ +
The encoding of the file. Apache only recognizes + encodings that are defined by an AddEncoding directive. + This normally includes the encodings x-compress + for compress'd files, and x-gzip for gzip'd + files. The x- prefix is ignored for encoding + comparisons.
+ +
Content-Language:
+ +
The language of the variant, as an Internet standard + language tag (RFC 1766). An example is en, + meaning English.
+ +
Content-Length:
+ +
The length of the file, in bytes. If this header is not + present, then the actual length of the file is used.
+ +
Content-Type:
+ +
+ The MIME media type of the document, with optional + parameters. Parameters are separated from the media type + and from one another by a semi-colon, with a syntax of + name=value. Common parameters include: + +
+
level
+ +
an integer specifying the version of the media type. + For text/html this defaults to 2, otherwise + 0.
+ +
qs
+ +
a floating-point number with a value in the range 0.0 + to 1.0, indicating the relative 'quality' of this variant + compared to the other available variants, independent of + the client's capabilities. For example, a jpeg file is + usually of higher source quality than an ascii file if it + is attempting to represent a photograph. However, if the + resource being represented is ascii art, then an ascii + file would have a higher source quality than a jpeg file. + All qs values are therefore specific to a given + resource.
+
+ Example: + +
+ Content-Type: image/jpeg; qs=0.8 +
+
+ +
URI:
+ +
The path to the file containing this variant, relative to + the map file.
+
+
+ +
MultiViews + +

A MultiViews search is enabled by the MultiViews Options. If the server receives a + request for /some/dir/foo and + /some/dir/foo does not exist, then the + server reads the directory looking for all files named + foo.*, and effectively fakes up a type map which + names all those files, assigning them the same media types and + content-encodings it would have if the client had asked for one + of them by name. It then chooses the best match to the client's + requirements, and returns that document.

+
+ + +CacheNegotiatedDocs +Allows content-negotiated documents to be +cached by proxy servers +CacheNegotiatedDocs on|off +CacheNegotiatedDocs off +server config +The syntax changed in version 2.0. + + +

If set, this directive allows content-negotiated documents + to be cached by proxy servers. This could mean that clients + behind those proxys could retrieve versions of the documents + that are not the best match for their abilities, but it will + make caching more efficient.

+ +

This directive only applies to requests which come from + HTTP/1.0 browsers. HTTP/1.1 provides much better control over + the caching of negotiated documents, and this directive has no + effect in responses to HTTP/1.1 requests.

+ +

Prior to version 2.0, + CacheNegotiatedDocs did not take an + argument; it was turned on by the presence of the directive by + itself.

+ + + + +ForceLangaugePriority +Action to take if a single acceptable document is not +found +ForceLanguagePriority None|Prefer|Fallback [Prefer|Fallback] +ForceLangaugePriority None +server config +virtual host +directory +.htaccess + +FileInfo +Available in version 2.0.30 and later + + +

The ForceLanguagePriority directive uses + the given LanguagePriority to satisfy + negotation where the server could otherwise not return a single + matching document.

+ +

ForceLanguagePriority Prefer uses + LanguagePriority to serve a one valid result, rather + than returning an HTTP result 300 (MULTIPLE CHOICES) when there + are several equally valid choices. If the directives below were + given, and the user's Accept-Language header assigned en and de + each as quality .500 (equally acceptable) then then first matching + variant, en, will be served.

+ + + LanguagePriority en fr de
+ ForceLanguagePriority Prefer + + +

ForceLanguagePriority Fallback uses + LanguagePriority to serve a valid result, rather than + returning an HTTP result 406 (NOT ACCEPTABLE). If the directives + below were given, and the user's Accept-Language only permitted an + es langauge response, but such a variant isn't found, then the + first variant from the LanguagePriority list below will be + served.

+ + + LanguagePriority en fr de
+ ForceLanguagePriority Fallback + + +

Both options, Prefer and Fallback, may be specified, so either the + first matching variant from LanguagePriority will be served if more + that one variant is acceptable, or first available document will be + served if none of the variants matched the client's acceptable list of + languages.

+ + + + +LanguagePriority +The precendence of language variants for cases where +the client does not express a preference +LanguagePriority MIME-lang [MIME-lang] ... +server config +virtual host +directory +.htaccess + +FileInfo + + +

The LanguagePriority sets the precedence + of language variants for the case where the client does not + express a preference, when handling a MultiViews request. The list + of MIME-lang are in order of decreasing preference. + Example:

+ +LanguagePriority en fr de + +

For a request for foo.html, where + foo.html.fr and foo.html.de both + existed, but the browser did not express a language preference, + then foo.html.fr would be returned.

+ +

Note that this directive only has an effect if a 'best' + language cannot be determined by any other means or the ForceLanguagePriority directive + is not None. Correctly implemented HTTP/1.1 requests + will mean this directive has no effect.

+ + + + \ No newline at end of file