From 700dc34d7c5ebc8c847d38671c70ded3f9a56a1e Mon Sep 17 00:00:00 2001 From: Joshua Slive Date: Thu, 23 May 2002 14:23:51 +0000 Subject: No change here except the filename extensions. Sorry for the massic commit. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@95240 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/mod/allmodules.html.en | 52 + docs/manual/mod/core.html.en | 1768 ++++++++++++++++++++++++++++++ docs/manual/mod/directives.html.en | 8 + docs/manual/mod/index.html.en | 55 + docs/manual/mod/mod_access.html.en | 226 ++++ docs/manual/mod/mod_actions.html.en | 73 ++ docs/manual/mod/mod_alias.html.en | 182 +++ docs/manual/mod/mod_asis.html.en | 59 + docs/manual/mod/mod_auth.html.en | 116 ++ docs/manual/mod/mod_auth_anon.html.en | 119 ++ docs/manual/mod/mod_auth_dbm.html.en | 134 +++ docs/manual/mod/mod_auth_digest.html.en | 134 +++ docs/manual/mod/mod_autoindex.html.en | 633 +++++++++++ docs/manual/mod/mod_cache.html.en | 117 ++ docs/manual/mod/mod_cern_meta.html.en | 36 + docs/manual/mod/mod_cgi.html.en | 146 +++ docs/manual/mod/mod_cgid.html.en | 35 + docs/manual/mod/mod_charset_lite.html.en | 122 +++ docs/manual/mod/mod_dav.html.en | 83 ++ docs/manual/mod/mod_deflate.html.en | 49 + docs/manual/mod/mod_dir.html.en | 57 + docs/manual/mod/mod_env.html.en | 32 + docs/manual/mod/mod_example.html.en | 95 ++ docs/manual/mod/mod_expires.html.en | 160 +++ docs/manual/mod/mod_ext_filter.html.en | 204 ++++ docs/manual/mod/mod_file_cache.html.en | 147 +++ docs/manual/mod/mod_headers.html.en | 219 ++++ docs/manual/mod/mod_imap.html.en | 276 +++++ docs/manual/mod/mod_include.html.en | 601 ++++++++++ docs/manual/mod/mod_info.html.en | 54 + docs/manual/mod/mod_isapi.html.en | 205 ++++ docs/manual/mod/mod_log_config.html.en | 322 ++++++ docs/manual/mod/mod_mime.html.en | 624 +++++++++++ docs/manual/mod/mod_mime_magic.html.en | 278 +++++ docs/manual/mod/mod_negotiation.html.en | 178 +++ docs/manual/mod/mod_proxy.html.en | 544 +++++++++ docs/manual/mod/mod_rewrite.html.en | 1628 +++++++++++++++++++++++++++ docs/manual/mod/mod_setenvif.html.en | 194 ++++ docs/manual/mod/mod_so.html.en | 126 +++ docs/manual/mod/mod_speling.html.en | 65 ++ docs/manual/mod/mod_ssl.html.en | 928 ++++++++++++++++ docs/manual/mod/mod_status.html.en | 107 ++ docs/manual/mod/mod_suexec.html.en | 16 + docs/manual/mod/mod_unique_id.html.en | 169 +++ docs/manual/mod/mod_userdir.html.en | 102 ++ docs/manual/mod/mod_usertrack.html.en | 129 +++ docs/manual/mod/mod_vhost_alias.html.en | 205 ++++ docs/manual/mod/mpm_common.html.en | 338 ++++++ docs/manual/mod/mpm_netware.html.en | 68 ++ docs/manual/mod/mpm_winnt.html.en | 11 + docs/manual/mod/perchild.html.en | 73 ++ docs/manual/mod/prefork.html.en | 106 ++ docs/manual/mod/worker.html.en | 49 + 53 files changed, 12457 insertions(+) create mode 100644 docs/manual/mod/allmodules.html.en create mode 100644 docs/manual/mod/core.html.en create mode 100644 docs/manual/mod/directives.html.en create mode 100644 docs/manual/mod/index.html.en create mode 100644 docs/manual/mod/mod_access.html.en create mode 100644 docs/manual/mod/mod_actions.html.en create mode 100644 docs/manual/mod/mod_alias.html.en create mode 100644 docs/manual/mod/mod_asis.html.en create mode 100644 docs/manual/mod/mod_auth.html.en create mode 100644 docs/manual/mod/mod_auth_anon.html.en create mode 100644 docs/manual/mod/mod_auth_dbm.html.en create mode 100644 docs/manual/mod/mod_auth_digest.html.en create mode 100644 docs/manual/mod/mod_autoindex.html.en create mode 100644 docs/manual/mod/mod_cache.html.en create mode 100644 docs/manual/mod/mod_cern_meta.html.en create mode 100644 docs/manual/mod/mod_cgi.html.en create mode 100644 docs/manual/mod/mod_cgid.html.en create mode 100644 docs/manual/mod/mod_charset_lite.html.en create mode 100644 docs/manual/mod/mod_dav.html.en create mode 100644 docs/manual/mod/mod_deflate.html.en create mode 100644 docs/manual/mod/mod_dir.html.en create mode 100644 docs/manual/mod/mod_env.html.en create mode 100644 docs/manual/mod/mod_example.html.en create mode 100644 docs/manual/mod/mod_expires.html.en create mode 100644 docs/manual/mod/mod_ext_filter.html.en create mode 100644 docs/manual/mod/mod_file_cache.html.en create mode 100644 docs/manual/mod/mod_headers.html.en create mode 100644 docs/manual/mod/mod_imap.html.en create mode 100644 docs/manual/mod/mod_include.html.en create mode 100644 docs/manual/mod/mod_info.html.en create mode 100644 docs/manual/mod/mod_isapi.html.en create mode 100644 docs/manual/mod/mod_log_config.html.en create mode 100644 docs/manual/mod/mod_mime.html.en create mode 100644 docs/manual/mod/mod_mime_magic.html.en create mode 100644 docs/manual/mod/mod_negotiation.html.en create mode 100644 docs/manual/mod/mod_proxy.html.en create mode 100644 docs/manual/mod/mod_rewrite.html.en create mode 100644 docs/manual/mod/mod_setenvif.html.en create mode 100644 docs/manual/mod/mod_so.html.en create mode 100644 docs/manual/mod/mod_speling.html.en create mode 100644 docs/manual/mod/mod_ssl.html.en create mode 100644 docs/manual/mod/mod_status.html.en create mode 100644 docs/manual/mod/mod_suexec.html.en create mode 100644 docs/manual/mod/mod_unique_id.html.en create mode 100644 docs/manual/mod/mod_userdir.html.en create mode 100644 docs/manual/mod/mod_usertrack.html.en create mode 100644 docs/manual/mod/mod_vhost_alias.html.en create mode 100644 docs/manual/mod/mpm_common.html.en create mode 100644 docs/manual/mod/mpm_netware.html.en create mode 100644 docs/manual/mod/mpm_winnt.html.en create mode 100644 docs/manual/mod/perchild.html.en create mode 100644 docs/manual/mod/prefork.html.en create mode 100644 docs/manual/mod/worker.html.en diff --git a/docs/manual/mod/allmodules.html.en b/docs/manual/mod/allmodules.html.en new file mode 100644 index 0000000000..2efc71b7eb --- /dev/null +++ b/docs/manual/mod/allmodules.html.en @@ -0,0 +1,52 @@ + + core.xml + mod_access.xml + mod_actions.xml + mod_alias.xml + mod_asis.xml + mod_auth.xml + mod_auth_anon.xml + mod_auth_dbm.xml + mod_auth_digest.xml + mod_autoindex.xml + mod_cache.xml + mod_cern_meta.xml + mod_cgi.xml + mod_cgid.xml + mod_charset_lite.xml + mod_dav.xml + mod_deflate.xml + mod_dir.xml + mod_env.xml + mod_example.xml + mod_expires.xml + mod_ext_filter.xml + mod_file_cache.xml + mod_headers.xml + mod_imap.xml + mod_include.xml + mod_info.xml + mod_isapi.xml + mod_log_config.xml + mod_mime.xml + mod_mime_magic.xml + mod_negotiation.xml + mod_proxy.xml + mod_rewrite.xml + mod_setenvif.xml + mod_so.xml + mod_ssl.xml + mod_speling.xml + mod_status.xml + mod_suexec.xml + mod_unique_id.xml + mod_userdir.xml + mod_usertrack.xml + mod_vhost_alias.xml + mpm_common.xml + mpm_netware.xml + mpm_winnt.xml + perchild.xml + prefork.xml + worker.xml + \ No newline at end of file diff --git a/docs/manual/mod/core.html.en b/docs/manual/mod/core.html.en new file mode 100644 index 0000000000..13ef161060 --- /dev/null +++ b/docs/manual/mod/core.html.en @@ -0,0 +1,1768 @@ +core- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module core

Description:Core Apache HTTP Server features that are always +available
Status:Core

Directives

AcceptPathInfo Directive

Description: Controls whether requests can contain trailing pathname information
Syntax:AcceptPathInfo On|Off|Default
Default:AcceptPathInfo Default
Context:server config, virtual host, directory, .htaccess
Status:Core
Module:core
Compatibility:Available in Apache 2.0.30 and later
+ +

This directive controls whether requests that contain trailing + pathname information that follows an actual filename (or + non-existent file in an existing directory) will be accepted or + rejected. The trailing pathname information can be made + available to scripts in the PATH_INFO environment variable.

+ +

For example, assume the location /test/ points to + a directory that contains only the single file + here.html. Then requests for + /test/here.html/more and + /test/nothere.html/more both collect + /more as PATH_INFO.

+ +

The three possible arguments for the + AcceptPathInfo directive are:

+
+
off
A request will only be accepted if it + maps to a literal path that exists. Therefore a request with + trailing pathname information after the true filename such as + /test/here.html/more in the above example will return + a 404 NOT FOUND error.
+ +
on
A request will be accepted if a + leading path component maps to a file that exists. The above + example /test/here.html/more will be accepted if + /test/here.html maps to a valid file.
+ +
default
The treatment of requests with + trailing pathname information is determined by the handler responsible for the request. + The core handler for normal files defaults to rejecting PATH_INFO. + Handlers that serve scripts, such as cgi-script and isapi-isa, generally accept PATH_INFO by + default.
+
+ +

The primary purpose of the AcceptPathInfo + directive is to allow you to override the handler's choice of + accepting or rejecting PATH_INFO. This override is required, for + example, when you use a filter, such + as INCLUDES, to generate content + based on PATH_INFO. The core handler would usually reject the + request, so you can use the following configuration to enable + such a script:

+
+<Files "mypaths.shtml">
+ Options +Includes
+ SetOutputFilter INCLUDES
+ AcceptPathInfo on
+</Files> +
+

AccessFileName Directive

Description: Sets the name of the .htaccess file
Syntax:AccessFileName filename [filename] ...
Default:AccessFileName .htaccess
Context:server config, virtual host
Status:Core
Module:core
+

When returning a document to the client the server looks for + the first existing access control file from this list of names + in every directory of the path to the document, if access + control files are enabled for that directory. For example:

+ +
+AccessFileName .acl +
+ +

before returning the document + /usr/local/web/index.html, the server will read + /.acl, /usr/.acl, + /usr/local/.acl and /usr/local/web/.acl + for directives, unless they have been disabled with

+ +
+<Directory />
+  AllowOverride None
+</Directory> +
+

See also

AddDefaultCharset Directive

Description: Specifies the default character set to be added for a +response without an explicit character set
Syntax:AddDefaultCharset On|Off|charset
Default:AddDefaultCharset Off
Context:server config, virtual host, directory, .htaccess
Status:Core
Module:core
+ +

This directive specifies the name of the character set that + will be added to any response that does not have any parameter on + the content type in the HTTP headers. This will override any + character set specified in the body of the document via a + META tag. A setting of AddDefaultCharset + Off disables this + functionality. AddDefaultCharset On enables + Apache's internal default charset of iso-8859-1 as + required by the directive. You can also specify an alternate + charset to be used. For example:

+ +
+ AddDefaultCharset utf-8 +
+

AllowOverride Directive

Description: Sets the types of directives that are allowed in +.htaccess files
Syntax:AllowOverride All|None|directive-type [directive-type] ...
Default:AllowOverride All
Context:directory
Status:Core
Module:core
+

When the server finds an .htaccess file (as specified by AccessFileName) it needs to know + which directives declared in that file can override earlier + access information.

+ +

When this directive is set to None, then + .htaccess files are completely ignored. In this case, the + server will not even attempt to read .htaccess files in the + filesystem.

+ +

When this directive is set to All, then any + directive which has the .htaccess Context is allowed in + .htaccess files.

+ +

The directive-type can be one of the following + groupings of directives.

+ +
+
AuthConfig
+ +
+ + Allow use of the authorization directives (AuthDBMGroupFile, + AuthDBMUserFile, + AuthGroupFile, + AuthName, + AuthType, AuthUserFile, Require, etc.).
+ +
FileInfo
+ +
+ Allow use of the directives controlling document types (DefaultType, ErrorDocument, ForceType, LanguagePriority, + SetHandler, SetInputFilter, SetOutputFilter, and + mod_mime Add* and Remove* + directives, etc.).
+ +
Indexes
+ +
+ Allow use of the directives controlling directory indexing + (AddDescription, + AddIcon, AddIconByEncoding, + AddIconByType, + DefaultIcon, DirectoryIndex, FancyIndexing, HeaderName, IndexIgnore, IndexOptions, ReadmeName, + etc.).
+ +
Limit
+ +
+ Allow use of the directives controlling host access (Allow, Deny and Order).
+ +
Options
+ +
+ Allow use of the directives controlling specific directory + features (Options and + XBitHack).
+
+ +

Example:

+ +
AllowOverride AuthConfig Indexes
+

See also

AuthName Directive

Description: Sets the authorization realm for use in HTTP +authentication
Syntax:AuthName auth-domain
Context:directory, .htaccess
Override:AuthConfig
Status:Core
Module:core
+

This directive sets the name of the authorization realm for a + directory. This realm is given to the client so that the user + knows which username and password to send. + AuthName takes a single argument; if the + realm name contains spaces, it must be enclosed in quotation + marks. It must be accompanied by AuthType and Require directives, and directives such + as AuthUserFile and + AuthGroupFile to + work.

+ +

For example:

+ +
AuthName "Top Secret"
+ +

The string provided for the AuthRealm is what will + appear in the password dialog provided by most browsers.

+

See also

AuthType Directive

Description: Selects the type of user authentication
Syntax:AuthType Basic|Digest
Context:directory, .htaccess
Override:AuthConfig
Status:Core
Module:core
+

This directive selects the type of user authentication for a + directory. Only Basic and Digest are + currently implemented. + + It must be accompanied by AuthName and Require directives, and directives such + as AuthUserFile and + AuthGroupFile to + work.

+

See also

ContentDigest Directive

Description: Enables the generation of Content-MD5 HTTP Response +headers
Syntax:ContentDigest on|off
Default:ContentDigest off
Context:server config, virtual host, directory, .htaccess
Override:Options
Status:Core
Module:core
Compatibility:Available in Apache 1.1 and later
+

This directive enables the generation of + Content-MD5 headers as defined in RFC1864 + respectively RFC2068.

+ +

MD5 is an algorithm for computing a "message digest" + (sometimes called "fingerprint") of arbitrary-length data, with + a high degree of confidence that any alterations in the data + will be reflected in alterations in the message digest.

+ +

The Content-MD5 header provides an end-to-end + message integrity check (MIC) of the entity-body. A proxy or + client may check this header for detecting accidental + modification of the entity-body in transit. Example header:

+
+ Content-MD5: AuLb7Dp1rqtRtxz2m9kRpA== +
+ +

Note that this can cause performance problems on your server + since the message digest is computed on every request (the + values are not cached).

+ +

Content-MD5 is only sent for documents served + by the core, and not by any module. For example, SSI documents, + output from CGI scripts, and byte range responses do not have + this header.

+

DefaultType Directive

Description: Sets the MIME content-type that will be sent if the +server cannot determine a type in any other way
Syntax:DefaultType MIME-type
Default:DefaultType text/plain
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Core
Module:core
+

There will be times when the server is asked to provide a + document whose type cannot be determined by its MIME types + mappings.

+ +

The server must inform the client of the content-type of the + document, so in the event of an unknown type it uses the + DefaultType. For example:

+ +
+ DefaultType image/gif +
+

would be appropriate for a directory which contained many gif + images with filenames missing the .gif extension.

+ +

Note that unlike ForceType, this directive is only + provides the default mime-type. All other mime-type definitions, + including filename extensions, that might identify the media type + will override this default.

+

<Directory> Directive

Description: Enclose a group of directives that apply only to the +named file-system directory and sub-directories
Syntax:<Directory directory-path> +... </Directory>
Context:server config, virtual host
Status:Core
Module:core
+

<Directory> and + </Directory> are used to enclose a group of + directives which will apply only to the named directory and + sub-directories of that directory. Any directive which is allowed + in a directory context may be used. Directory-path is + either the full path to a directory, or a wild-card string. In a + wild-card string, `?' matches any single character, and `*' + matches any sequences of characters. You may + also use `[]' character ranges like in the shell. Also as of + Apache 1.3 none of the wildcards match a `/' character, which more + closely mimics the behavior of Unix shells. Example:

+
+ <Directory /usr/local/httpd/htdocs>
+  Options Indexes FollowSymLinks
+ </Directory>
+
+ +

Extended regular + expressions can also be used, with the addition of the + ~ character. For example:

+
+ <Directory ~ "^/www/.*/[0-9]{3}"> +
+

would match directories in /www/ that consisted of three + numbers.

+ +

If multiple (non-regular expression) directory sections + match the directory (or its parents) containing a document, + then the directives are applied in the order of shortest match + first, interspersed with the directives from the .htaccess files. For example, + with

+ +
+ <Directory />
+   AllowOverride None
+ </Directory>
+
+ <Directory /home/*>
+   AllowOverride FileInfo
+ </Directory> +
+

for access to the document /home/web/dir/doc.html + the steps are:

+ + + +

Regular expressions are not considered until after all of the + normal sections have been applied. Then all of the regular + expressions are tested in the order they appeared in the + configuration file. For example, with

+ +
<Directory ~ abc$>
+ ... directives here ...
+ </Directory>
+
+ +

The regular expression section won't be considered until after + all normal <Directory>s and .htaccess files + have been applied. Then the regular expression will match on + /home/abc/public_html/abc and be applied.

+ +

Note that the default Apache access for + <Directory /> is Allow from All. This means + that Apache will serve any file mapped from an URL. It is + recommended that you change this with a block such + as

+ +
+ <Directory />
+   Order Deny,Allow
+   Deny from All
+ </Directory> +
+ +

and then override this for directories you + want accessible. See the Security Tips page for more + details.

+ +

The directory sections typically occur in + the access.conf file, but they may appear in any configuration + file. <Directory> directives + cannot nest, and cannot appear in a <Limit> or <LimitExcept> section.

+

See also

<DirectoryMatch> Directive

Description: Enclose a group of directives that apply only to +file-system directories that match a regular expression and their +subdirectories
Syntax:<Directory regex> +... </Directory>
Context:server config, virtual host
Status:Core
Module:core
+

<DirectoryMatch> and + </DirectoryMatch> are used to enclose a group + of directives which will apply only to the named directory and + sub-directories of that directory, the same as <Directory>. However, it + takes as an argument a regular expression. For example:

+
+ <DirectoryMatch "^/www/.*/[0-9]{3}"> +
+ +

would match directories in /www/ that consisted of three + numbers.

+

See also

DocumentRoot Directive

Description: Sets the directory that forms the main document tree visible +from the web
Syntax:DocumentRoot directory-path
Default:DocumentRoot /usr/local/apache/htdocs
Context:server config, virtual host
Status:Core
Module:core
+

This directive sets the directory from which httpd will + serve files. Unless matched by a directive like Alias, the + server appends the path from the requested URL to the document + root to make the path to the document. Example:

+
+ DocumentRoot /usr/web +
+

then an access to + http://www.my.host.com/index.html refers to + /usr/web/index.html.

+ +

The DocumentRoot should be specified without + a trailing slash.

+

See also

EnableMMAP Directive

Description: Controls whether the httpd uses memory-mapping to read files +during delivery
Syntax:EnableMMAP on|off
Default:EnableMMAP on
Context:server config, virtual host, directory, .htaccess
Status:Core
Module:core
+

This directive controls whether the httpd may use memory-mapping + if it needs to read the contents of a file during delivery. By default, + when the handling of a request requires access to the data within a file-- + for example, when delivering a server-parsed file using mod_include-- + Apache memory-maps the file if the OS supports it. +

+

+ This memory-mapping sometimes yields a performance improvement. + But in some environments, it is better to disable the memory-mapping + to prevent operational problems: +

+ +

+ For server configurations that are vulnerable to these problems, + you should disable memory-mapping of delivered files by specifying: +

+
+ EnableMMAP off +
+

ErrorDocument Directive

Description: Specifies what the server will return to the client +in case of an error
Syntax:ErrorDocument error-code document
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Core
Module:core
Compatibility:Quoting syntax for text messages is different in Apache +2.0
+

In the event of a problem or error, Apache can be configured + to do one of four things,

+ +
    +
  1. output a simple hardcoded error message
    2. + +
  2. output a customized message
    3. + +
  3. redirect to a local URL-path to handle the + problem/error
    4. + +
  4. redirect to an external URL to handle the + problem/error
    5. +
+ +

The first option is the default, while options 2-4 are + configured using the ErrorDocument + directive, which is followed by the HTTP response code and a URL + or a message. Apache will sometimes offer additional information + regarding the problem/error.

+ +

URLs can begin with a slash (/) for local URLs, or be a full + URL which the client can resolve. Alternatively, a message can + be provided to be displayed by the browser. Examples:

+ +
+ ErrorDocument 500 + http://foo.example.com/cgi-bin/tester
+ ErrorDocument 404 /cgi-bin/bad_urls.pl
+ ErrorDocument 401 /subscription_info.html
+ ErrorDocument 403 "Sorry can't allow you access + today" +
+ +

Note that when you specify an ErrorDocument + that points to a remote URL (ie. anything with a method such as + "http" in front of it), Apache will send a redirect to the + client to tell it where to find the document, even if the + document ends up being on the same server. This has several + implications, the most important being that the client will not + receive the original error status code, but instead will + receive a redirect status code. This in turn can confuse web + robots and other clients which try to determine if a URL is + valid using the status code. In addition, if you use a remote + URL in an ErrorDocument 401, the client will not + know to prompt the user for a password since it will not + receive the 401 status code. Therefore, if you use an + "ErrorDocument 401" directive then it must refer to a local + document.

+ +

Prior to version 2.0, messages were indicated by prefixing + them with a single unmatched double quote character.

+

See also

ErrorLog Directive

Description: Sets the name of the file to which the server +will log errors
Syntax: ErrorLog file-path|syslog[:facility]
Default:ErrorLog logs/error_log (Unix) +ErrorLog logs/error.log (Windows and OS/2)
Context:server config, virtual host
Status:Core
Module:core
+

The ErrorLog directive sets the name of + the file to which the server will log any errors it encounters. If + the file-path does not begin with a slash (/) then it is + assumed to be relative to the ServerRoot. If the file-path + begins with a pipe (|) then it is assumed to be a command to spawn + to handle the error log.

+ +

Using syslog instead of a filename enables logging + via syslogd(8) if the system supports it. The default is to use + syslog facility local7, but you can override this by + using the syslog:facility syntax where + facility can be one of the names usually documented in + syslog(1).

+ +

SECURITY: See the security tips + document for details on why your security could be compromised + if the directory where logfiles are stored is writable by + anyone other than the user that starts the server.

+

See also

FileETag Directive

Description: Configures the file attributes used to create the ETag +HTTP response header
Syntax:FileETag component ...
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Core
Module:core
+

+ The FileETag directive configures the file + attributes that are used to create the ETag (entity tag) response + header field when the document is based on a file. (The ETag + value is used in cache management to save network bandwidth.) In + Apache 1.3.22 and earlier, the ETag value was always formed + from the file's inode, size, and last-modified time (mtime). The + FileETag directive allows you to choose which of these -- if any + -- should be used. The recognized keywords are: +

+
+
INode
+
The file's i-node number will be included in the calculation
+
MTime
+
The date and time the file was last modified will be included
+
Size
+
The number of bytes in the file will be included
+
All
+
All available fields will be used (equivalent to + 'FileETag INode MTime Size')
+
None
+
If a document is file-based, no ETag field will be included in the + response
+
+

+ The INode, MTime, and Size keywords may be prefixed with either '+' + or '-', which allow changes to be made to the default setting + inherited from a broader scope. Any keyword appearing without + such a prefix immediately and completely cancels the inherited + setting. +

+

+ If a directory's configuration includes + 'FileETag INode MTime Size', and a + subdirectory's includes 'FileETag -INode', + the setting for that subdirectory (which will be inherited by + any sub-subdirectories that don't override it) will be equivalent to + 'FileETag MTime Size'. +

+

<Files> Directive

Description: Contains that directives that apply to matched +filenames
Syntax:<Files filename> ... </Files>
Context:server config, virtual host, directory, .htaccess
Status:Core
Module:core
+

The <Files> directive + provides for access control by filename. It is comparable to the + Directory + directive and Location directives. It should be + matched with a </Files> directive. The + directives given within this section will be applied to any object + with a basename (last component of filename) matching the + specified filename. <Files> + sections are processed in the order they appear in the + configuration file, after the <Directory> sections and + .htaccess files are read, but before <Location> sections. Note + that <Files> can be nested + inside <Directory> sections to restrict the + portion of the filesystem they apply to.

+ +

The filename argument should include a filename, or + a wild-card string, where `?' matches any single character, and + `*' matches any sequences of characters. Extended regular + expressions can also be used, with the addition of the + ~ character. For example:

+
+ <Files ~ "\.(gif|jpe?g|png)$"> +
+

would match most common Internet graphics formats. In Apache 1.3 + and later, <FilesMatch> is preferred, however.

+ +

Note that unlike <Directory> and <Location> sections, <Files> sections can be used inside + .htaccess files. This allows users to control access to their own + files, at a file-by-file level.

+ +

See also

<FilesMatch> Directive

Description: Contains that directives that apply to regular-expression matched +filenames
Syntax:<FilesMatch regex> ... </FilesMatch>
Context:server config, virtual host, directory, .htaccess
Status:Core
Module:core
+

The <FilesMatch> directive + provides for access control by filename, just as the <Files> directive + does. However, it accepts a regular expression. For example:

+
+ <FilesMatch "\.(gif|jpe?g|png)$"> +
+ +

would match most common Internet graphics formats.

+

See also

ForceType Directive

Description: Forces all matching files to be served with the specified +MIME content-type
Syntax:ForceType mime-type
Context:directory, .htaccess
Status:Core
Module:core
Compatibility:Moved to the core in Apache 2.0
+

When placed into an .htaccess file or a + <Directory>, or + <Location> or + <Files> + section, this directive forces all matching files to be served + with the content type identification given by + mime-type. For example, if you had a directory full of + GIF files, but did not want to label them all with ".gif", you + might want to use:

+
+ ForceType image/gif +
+ +

Note that unlike DefaultType, + this directive overrides all mime-type associations, including + filename extensions, that might identify the media type.

+

HostnameLookups Directive

Description: Enables DNS lookups on client IP addresses
Syntax:HostnameLookups on|off|double
Default:HostnameLookups off
Context:server config, virtual host, directory
Status:Core
Module:core
+

This directive enables DNS lookups so that host names can be + logged (and passed to CGIs/SSIs in REMOTE_HOST). + The value double refers to doing double-reverse + DNS. That is, after a reverse lookup is performed, a forward + lookup is then performed on that result. At least one of the ip + addresses in the forward lookup must match the original + address. (In "tcpwrappers" terminology this is called + PARANOID.)

+ +

Regardless of the setting, when mod_access is + used for controlling access by hostname, a double reverse lookup + will be performed. This is necessary for security. Note that the + result of this double-reverse isn't generally available unless you + set HostnameLookups double. For example, if only + HostnameLookups on and a request is made to an object + that is protected by hostname restrictions, regardless of whether + the double-reverse fails or not, CGIs will still be passed the + single-reverse result in REMOTE_HOST.

+ +

The default is off in order to save the network + traffic for those sites that don't truly need the reverse + lookups done. It is also better for the end users because they + don't have to suffer the extra latency that a lookup entails. + Heavily loaded sites should leave this directive + off, since DNS lookups can take considerable + amounts of time. The utility logresolve, provided in + the /support directory, can be used to look up host + names from logged IP addresses offline.

+

IdentityCheck Directive

Description: Enables logging of the RFC1413 identity of the remote +user
Syntax:IdentityCheck on|off
Default:IdentityCheck off
Context:
Status:Core
Module:core
+

This directive enables RFC1413-compliant logging of the + remote user name for each connection, where the client machine + runs identd or something similar. This information is logged in + the access log.

+ +

The information should not be trusted in any way except for + rudimentary usage tracking.

+ +

Note that this can cause serious latency problems accessing + your server since every request requires one of these lookups + to be performed. When firewalls are involved each lookup might + possibly fail and add 30 seconds of latency to each hit. So in + general this is not very useful on public servers accessible + from the Internet.

+

<IfDefine> Directive

Description: Encloses directives that will be processed only +if a test is true at startup
Syntax:<IfDefine [!]parameter-name> ... + </IfDefine>
Context:server config, virtual host, directory, .htaccess
Status:Core
Module:core
+

The <IfDefine + test>...</IfDefine> section is used to + mark directives that are conditional. The directives within an + <IfDefine> section are only + processed if the test is true. If test is false, + everything between the start and end markers is ignored.

+ +

The test in the <IfDefine> section directive can be one + of two forms:

+ + + +

In the former case, the directives between the start and end + markers are only processed if the parameter named + parameter-name is defined. The second format reverses + the test, and only processes the directives if + parameter-name is not defined.

+ +

The parameter-name argument is a define as given on + the httpd command line via + -Dparameter-, at the time the server was + started.

+ +

<IfDefine> sections are + nest-able, which can be used to implement simple + multiple-parameter tests. Example:

+
+  $ httpd -DReverseProxy ...
+
+  # httpd.conf
+  <IfDefine ReverseProxy>
+  LoadModule rewrite_module modules/mod_rewrite.so
+  LoadModule proxy_module   modules/libproxy.so
+  </IfDefine>
+
+ +

<IfModule> Directive

Description: Encloses directives that are processed conditional on the +presence of absence of a specific module
Syntax:<IfModule [!]module-name> ... + </IfModule>
Context:server config, virtual host, directory, .htaccess
Status:Core
Module:core
+

The <IfModule + test>...</IfModule> section is used to + mark directives that are conditional. The directives within an + <IfModule> section are only + processed if the test is true. If test is false, + everything between the start and end markers is ignored.

+ +

The test in the <IfModule> section directive can be one + of two forms:

+ + + +

In the former case, the directives between the start and end + markers are only processed if the module named module + name is included in Apache -- either compiled in or + dynamically loaded using LoadModule. The second format + reverses the test, and only processes the directives if module + name is not included.

+ +

The module name argument is the file name of the + module, at the time it was compiled. + For example, mod_rewrite.c.

+ +

<IfModule> sections are + nest-able, which can be used to implement simple multiple-module + tests.

+

Include Directive

Description: Includes other configuration files from within +the server configuration files
Syntax:Include file-path|directory-path
Context:server config
Status:Core
Module:core
+

This directive allows inclusion of other configuration files + from within the server configuration files.

+ +

If Include points to a directory, rather than a + file, Apache will read all files in that directory, and any + subdirectory, and parse those as configuration files.

+ +

The file path specified may be a fully qualified path (i.e. + starting with a slash), or may be relative to the + ServerRoot directory.

+ +

Examples:

+ +
+ Include /usr/local/apache/conf/ssl.conf
+ Include /usr/local/apache/conf/vhosts/ +
+ +

Or, providing paths relative to your ServerRoot + directory:

+ +
+ Include conf/ssl.conf
+ Include conf/vhosts/ +
+ +

Make sure that an included directory does not contain any stray + files, such as editor temporary files, for example, as Apache will + attempt to read them in and use the contents as configuration + directives, which may cause the server to fail on start up. + Running apachectl configtest will give you a list of + the files that are being processed during the configuration + check:

+ +
+ root@host# apachectl configtest
+  Processing config directory: /usr/local/apache/conf/vhosts
+  Processing config file: /usr/local/apache/conf/vhosts/vhost1
+  Processing config file: /usr/local/apache/conf/vhosts/vhost2
+ Syntax OK
+
+ +

This will help in verifying that you are getting only the files + that you intended as part of your configuration.

+

See also

KeepAlive Directive

Description: Turns on or off HTTP persistent connections.
Syntax:KeepAlive on|off
Default:KeepAlive On
Context:server config
Status:Core
Module:core
+

The Keep-Alive extension to HTTP/1.0 and the persistent + connection feature of HTTP/1.1 provide long-lived HTTP sessions + which allow multiple requests to be sent over the same TCP + connection. In some cases this has been shown to result in an + almost 50% speedup in latency times for HTML documents with + many images. To enable Keep-Alive connections in Apache 1.2 and + later, set KeepAlive On.

+ +

For HTTP/1.0 clients, Keep-Alive connections will only be + used if they are specifically requested by a client. In + addition, a Keep-Alive connection with an HTTP/1.0 client can + only be used when the length of the content is known in + advance. This implies that dynamic content such as CGI output, + SSI pages, and server-generated directory listings will + generally not use Keep-Alive connections to HTTP/1.0 clients. + For HTTP/1.1 clients, persistent connections are the default + unless otherwise specified. If the client requests it, chunked + encoding will be used in order to send content of unknown + length over persistent connections.

+

See also

KeepAliveTimeout Directive

Description: Sets the amount of time the server will wait for subsequent +requests on a persistent connection
Syntax:KeepAliveTimeout seconds
Default:KeepAliveTimeout 15
Context:server config
Status:Core
Module:core
+

The number of seconds Apache will wait for a subsequent + request before closing the connection. Once a request has been + received, the timeout value specified by the + Timeout directive applies.

+ +

Setting KeepAliveTimeout to a high value + may cause performance problems in heavily loaded servers. The + higher the timeout, the more server processes will be kept + occupied waiting on connections with idle clients.

+

<Limit> Directive

Description: Restrict access controls to only certain HTTP +methods
Syntax:<Limit method [method] ... > ... + </Limit>
Context:server config, virtual host, directory, .htaccess
Status:Core
Module:core
+

Access controls are normally effective for + all access methods, and this is the usual + desired behavior. In the general case, access control + directives should not be placed within a + <limit> section.

+ +

The purpose of the <Limit> + directive is to restrict the effect of the access controls to the + nominated HTTP methods. For all other methods, the access + restrictions that are enclosed in the <Limit> + bracket will have no effect. The following + example applies the access control only to the methods POST, PUT, + and DELETE, leaving all other methods unprotected:

+ +
+ <Limit POST PUT DELETE>
+   Require valid-user
+ </Limit> +
+

The method names listed can be one or more of: GET, POST, PUT, + DELETE, CONNECT, OPTIONS, TRACE, PATCH, PROPFIND, PROPPATCH, + MKCOL, COPY, MOVE, LOCK, and UNLOCK. The method name is + case-sensitive. If GET is used it will also restrict + HEAD requests.

+

<LimitExcept> Directive

Description: Restrict access controls to all HTTP methods +except the named ones
Syntax:<LimitExcept method [method] ... > ... + </LimitExcept>
Context:server config, virtual host, directory, .htaccess
Status:Core
Module:core
+

<LimitExcept> and + </LimitExcept> are used to enclose + a group of access control directives which will then apply to any + HTTP access method not listed in the arguments; + i.e., it is the opposite of a <Limit> section and can be used to control + both standard and nonstandard/unrecognized methods. See the + documentation for <Limit> for more details.

+ +

For example:

+ +
+ <LimitExcept POST GET>
+ Require valid-user
+ <LimitExcept> +
+ +

LimitRequestBody Directive

Description: Restricts the total size of the HTTP request body sent +from the client
Syntax:LimitRequestBody bytes
Default:LimitRequestBody 0
Context:server config, virtual host, directory, .htaccess
Status:Core
Module:core
+

This directive specifies the number of bytes from 0 + (meaning unlimited) to 2147483647 (2GB) that are allowed in a + request body. The default value is defined by the compile-time + constant DEFAULT_LIMIT_REQUEST_BODY (0 as + distributed).

+ +

The LimitRequestBody directive allows + the user to set a limit on the allowed size of an HTTP request + message body within the context in which the directive is given + (server, per-directory, per-file or per-location). If the client + request exceeds that limit, the server will return an error + response instead of servicing the request. The size of a normal + request message body will vary greatly depending on the nature of + the resource and the methods allowed on that resource. CGI scripts + typically use the message body for passing form information to the + server. Implementations of the PUT method will require a value at + least as large as any representation that the server wishes to + accept for that resource.

+ +

This directive gives the server administrator greater + control over abnormal client request behavior, which may be + useful for avoiding some forms of denial-of-service + attacks.

+ +

If, for example, you are permitting file upload to a particular + location, and wich to limit the size of the uploaded file to 100K, + you might use the following directive:

+ +
+ LimitRequestBody 102400 +
+ +

LimitRequestFields Directive

Description: Limits the number of HTTP request header fields that +will be accepted from the client
Syntax:LimitRequestFields number
Default:LimitRequestFields 100
Context:server config
Status:Core
Module:core
+

Number is an integer from 0 (meaning unlimited) to + 32767. The default value is defined by the compile-time + constant DEFAULT_LIMIT_REQUEST_FIELDS (100 as + distributed).

+ +

The LimitRequestFields directive allows + the server administrator to modify the limit on the number of + request header fields allowed in an HTTP request. A server needs + this value to be larger than the number of fields that a normal + client request might include. The number of request header fields + used by a client rarely exceeds 20, but this may vary among + different client implementations, often depending upon the extent + to which a user has configured their browser to support detailed + content negotiation. Optional HTTP extensions are often expressed + using request header fields.

+ +

This directive gives the server administrator greater + control over abnormal client request behavior, which may be + useful for avoiding some forms of denial-of-service attacks. + The value should be increased if normal clients see an error + response from the server that indicates too many fields were + sent in the request.

+ +

For example:

+ +
+ LimitRequestFields 50 +
+ +

LimitRequestFieldSize Directive

Description: Limits the size of the HTTP request header allowed from the +client
Syntax:LimitRequestFieldsize bytes
Default:LimitRequestFieldsize 8190
Context:server config
Status:Core
Module:core
+

This directive specifies the number of bytes from 0 + to the value of the compile-time constant + DEFAULT_LIMIT_REQUEST_FIELDSIZE (8190 as + distributed) that will be allowed in an HTTP request + header.

+ +

The LimitRequestFieldsize directive + allows the server administrator to reduce the limit on the allowed + size of an HTTP request header field below the normal input buffer + size compiled with the server. A server needs this value to be + large enough to hold any one header field from a normal client + request. The size of a normal request header field will vary + greatly among different client implementations, often depending + upon the extent to which a user has configured their browser to + support detailed content negotiation.

+ +

This directive gives the server administrator greater + control over abnormal client request behavior, which may be + useful for avoiding some forms of denial-of-service attacks.

+ +

For example:

+ +
+ LimitRequestFieldSize 16380 +
+ +
Under normal conditions, the value should not be changed from + the default.
+ +

LimitRequestLine Directive

Description: Limit the size of the HTTP request line that will be accepted +from the client
Syntax:LimitRequestLine bytes
Default:LimitRequestLine 8190
Context:server config
Status:Core
Module:core
+

This directive sets the number of bytes from 0 to + the value of the compile-time constant + DEFAULT_LIMIT_REQUEST_LINE (8190 as distributed) + that will be allowed on the HTTP request-line.

+ +

The LimitRequestLine directive allows + the server administrator to reduce the limit on the allowed size + of a client's HTTP request-line below the normal input buffer size + compiled with the server. Since the request-line consists of the + HTTP method, URI, and protocol version, the + LimitRequestLine directive places a + restriction on the length of a request-URI allowed for a request + on the server. A server needs this value to be large enough to + hold any of its resource names, including any information that + might be passed in the query part of a GET request.

+ +

This directive gives the server administrator greater + control over abnormal client request behavior, which may be + useful for avoiding some forms of denial-of-service attacks.

+ +

For example:

+ +
+ LimitRequestLine 16380 +
+ +
Under normal conditions, the value should not be changed from + the default.
+

LimitXMLRequestBody Directive

Description: Limits the size of an XML-based request body
Syntax:LimitXMLRequestBody number
Default:LimitXMLRequestBody 1000000
Context:server config
Status:Core
Module:core
+

Limit (in bytes) on maximum size of an XML-based request + body. A value of 0 will disable any checking.

+ +

Example:

+ +
+ LimitXMLRequestBody 0 +
+ +

<Location> Directive

Description: Applies the enclosed directives only to matching +URLs
Syntax:<Location + URL-path|URL> ... </Location>
Context:server config, virtual host
Status:Core
Module:core
+

The <Location> directive + provides for access control by URL. It is similar to the + <Directory> + directive, and starts a subsection which is terminated with a + </Location> directive. <Location> sections are processed in the + order they appear in the configuration file, after the <Directory> sections and + .htaccess files are read, and after the <Files> sections.

+ +

Note that URLs do not have to line up with the filesystem at + all, it should be emphasized that <Location> operates + completely outside the filesystem.

+ +

For all origin (non-proxy) requests, the URL to be matched is a + URL-path of the form /path/. No scheme, hostname, + port, or query string may be included. For proxy requests, the + URL to be matched is of the form + scheme://servername/path, and you must include the + prefix.

+ +

The URL may use wildcards In a wild-card string, `?' matches + any single character, and `*' matches any sequences of + characters.

+ +

Extended regular + expressions can also be used, with the addition of the + ~ character. For example:

+
+ <Location ~ "/(extra|special)/data"> +
+ +

would match URLs that contained the substring "/extra/data" or + "/special/data". In Apache 1.3 and above, a new directive + <LocationMatch> + exists which behaves identical to the regex version of + <Location>.

+ +

The <Location> + functionality is especially useful when combined with the + SetHandler + directive. For example, to enable status requests, but allow them + only from browsers at foo.com, you might use:

+
+ <Location /status>
+ SetHandler server-status
+ Order Deny,Allow
+ Deny from all
+ Allow from .foo.com
+ </Location> +
+ +

Note about / (slash)

The slash character has +special meaning depending on where in a URL it appears. People may be +used to its behavior in the filesystem where multiple adjacent slashes +are frequently collapsed to a single slash (i.e., +/home///foo is the same as /home/foo). In +URL-space this is not necessarily true. The <LocationMatch> directive and the regex +version of <Location> require you +to explicitly specify multiple slashes if that is your intention. For +example, <LocationMatch ^/abc> would match the +request URL /abc but not the request URL +//abc. The (non-regex) <Location> directive behaves similarly when +used for proxy requests. But when (non-regex) <Location> is used for non-proxy requests it +will implicitly match multiple slashes with a single slash. For +example, if you specify <Location /abc/def> and the +request is to /abc//def then it will match.

+
+

See also

<LocationMatch> Directive

Description: Applies the enclosed directives only to regular-expression +matching URLs
Syntax:<LocationMatch + regex> ... </Location>
Context:server config, virtual host
Status:Core
Module:core
+

The <LocationMatch> directive + provides for access control by URL, in an identical manner to + <Location>. However, it takes a regular + expression as an argument instead of a simple string. For + example:

+
+ <LocationMatch "/(extra|special)/data"> +
+ +

would match URLs that contained the substring "/extra/data" + or "/special/data".

+

See also

LogLevel Directive

Description: Controls the verbosity of the ErrorLog
Syntax:LogLevel level
Default:LogLevel warn
Context:server config, virtual host
Status:Core
Module:core
+

LogLevel adjusts the verbosity of the + messages recorded in the error logs (see ErrorLog directive). The following + levels are available, in order of decreasing + significance:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Level Description Example
emerg Emergencies - system is unusable."Child cannot open lock file. Exiting"
alert Action must be taken immediately."getpwuid: couldn't determine user name from uid"
crit Critical Conditions."socket: Failed to get a socket, exiting child"
error Error conditions."Premature end of script headers"
warn Warning conditions."child process 1234 did not exit, sending another + SIGHUP"
notice Normal but significant condition."httpd: caught SIGBUS, attempting to dump core in + ..."
info Informational."Server seems busy, (you may need to increase + StartServers, or Min/MaxSpareServers)..."
debug Debug-level messages"Opening config file ..."
+ +

When a particular level is specified, messages from all + other levels of higher significance will be reported as well. + E.g., when LogLevel info is specified, + then messages with log levels of notice and + warn will also be posted.

+ +

Using a level of at least crit is + recommended.

+ +

For example:

+ +
LogLevel notice
+ +

MaxKeepAliveRequests Directive

Description: Sets the number of requests allowed on a persistent +connection
Syntax:MaxKeepAliveRequests number
Default:MaxKeepAliveRequests 100
Context:server config
Status:Core
Module:core
+

The MaxKeepAliveRequests directive + limits the number of requests allowed per connection when + KeepAlive is on. If it is + set to "0", unlimited requests will be allowed. We + recommend that this setting be kept to a high value for maximum + server performance.

+ +

For example:

+ +
MaxKeepAliveRequests 500
+

NameVirtualHost Directive

Description: Configures an IP address for name-virtual +hosting
Syntax:NameVirtualHost addr[:port]
Context:server config
Status:Core
Module:core
+

The NameVirtualHost directive is a + required directive if you want to configure name-based virtual hosts.

+ +

Although addr can be hostname it is recommended + that you always use an IP address, e.g.

+ +
NameVirtualHost 111.22.33.44
+ +

With the NameVirtualHost directive you + specify the IP address on which the server will receive requests + for the name-based virtual hosts. This will usually be the address + to which your name-based virtual host names resolve. In cases + where a firewall or other proxy receives the requests and forwards + them on a different IP address to the server, you must specify the + IP address of the physical interface on the machine which will be + servicing the requests. If you have multiple name-based hosts on + multiple addresses, repeat the directive for each address.

+ +

Note: the "main server" and any _default_ servers will + never be served for a request to a + NameVirtualHost IP Address (unless for some + reason you specify NameVirtualHost but then + don't define any VirtualHosts for that address).

+ +

Optionally you can specify a port number on which the + name-based virtual hosts should be used, e.g.

+ +
NameVirtualHost 111.22.33.44:8080
+ +

IPv6 addresses must be enclosed in square brackets, as shown + in the following example:

+ +
NameVirtualHost [fe80::a00:20ff:fea7:ccea]:8080
+ +

See also

Options Directive

Description: Configures what features are available in a particular +directory
Syntax:Options + [+|-]option [[+|-]option] ...
Default:Options All
Context:server config, virtual host, directory, .htaccess
Override:Options
Status:Core
Module:core
+

The Options directive controls which + server features are available in a particular directory.

+ +

option can be set to None, in which + case none of the extra features are enabled, or one or more of + the following:

+ +
+
All
+ +
All options except for MultiViews. This is the default + setting.
+ +
ExecCGI
+ +
+ Execution of CGI scripts is permitted.
+ +
FollowSymLinks
+ +
+ + The server will follow symbolic links in this directory.
+ Note: even though the server follows the + symlink it does not change the pathname used to match + against <Directory> sections.
+ Note: this option gets ignored if set inside a + <Location> + section.
+ +
Includes
+ +
+ Server-side includes are permitted.
+ +
IncludesNOEXEC
+ +
+ + Server-side includes are permitted, but the #exec command and + #exec CGI are disabled. It is still possible to #include + virtual CGI scripts from ScriptAliase'd directories.
+ +
Indexes
+ +
+ If a URL which maps to a directory is requested, and the + there is no DirectoryIndex (e.g., index.html) in + that directory, then the server will return a formatted + listing of the directory.
+ +
MultiViews
+ +
+ Content negotiated + MultiViews are allowed.
+ +
SymLinksIfOwnerMatch
+ +
+ + The server will only follow symbolic links for which the target + file or directory is owned by the same user id as the link.
Note: this option gets ignored if set inside + a <Location> + section.
+
+

Normally, if multiple Options could apply to a + directory, then the most specific one is taken complete; the + options are not merged. However if all the options on + the Options directive are preceded by a + or - + symbol, the options are merged. Any options preceded by a + are + added to the options currently in force, and any options + preceded by a - are removed from the options currently in + force.

+ +

For example, without any + and - symbols:

+ + +
<Directory /web/docs>
+ Options Indexes FollowSymLinks
+ </Directory>
+ <Directory /web/docs/spec>
+ Options Includes
+ </Directory> +
+

then only Includes will be set for the + /web/docs/spec directory. However if the second + Options directive uses the + and - symbols:

+ +
+ <Directory /web/docs>
+ Options Indexes FollowSymLinks
+ </Directory>
+ <Directory /web/docs/spec>
+ Options +Includes -Indexes
+ </Directory> +
+

then the options FollowSymLinks and + Includes are set for the /web/docs/spec directory.

+ + +

Note: Using -IncludesNOEXEC or + -Includes disables server-side includes completely + regardless of the previous setting.

+ +

The default in the absence of any other settings is + All.

+

Require Directive

Description: Selects which authenticated users can access +a resource
Syntax:Require entity-name [entity-name] ...
Context:directory, .htaccess
Override:AuthConfig
Status:Core
Module:core
+

This directive selects which authenticated users can access + a directory. The allowed syntaxes are:

+ + + +

Require must be accompanied by + AuthName and AuthType directives, and directives such + as AuthUserFile + and AuthGroupFile (to + define users and groups) in order to work correctly. Example:

+ +
+ AuthType Basic
+ AuthName "Restricted Directory"
+ AuthUserFile /web/users
+ AuthGroupFile /web/groups
+ Require group admin
+
+ +

Access controls which are applied in this way are effective for + all methods. This is what is normally + desired. If you wish to apply access controls only to + specific methods, while leaving other methods unprotected, then + place the Require statement into a + <Limit> + section.

+

See also

RLimitCPU Directive

Description: Limits the CPU consumption of processes launched +by Apache children
Syntax:RLimitCPU number|max [number|max]
Default:Unset; uses operating system defaults
Context:server config, virtual host
Status:Core
Module:core
Compatibility:Moved in version 2.0 to + the MPMs
+

Takes 1 or 2 parameters. The first parameter sets the soft + resource limit for all processes and the second parameter sets + the maximum resource limit. Either parameter can be a number, + or max to indicate to the server that the limit should + be set to the maximum allowed by the operating system + configuration. Raising the maximum resource limit requires that + the server is running as root, or in the initial startup + phase.

+ +

This applies to processes forked off from Apache children + servicing requests, not the Apache children themselves. This + includes CGI scripts and SSI exec commands, but not any + processes forked off from the Apache parent such as piped + logs.

+ +

CPU resource limits are expressed in seconds per + process.

+

See also

RLimitMEM Directive

Description: Limits the memory consumption of processes launched +by Apache children
Syntax:RLimitMEM number|max [number|max]
Default:Unset; uses operating system defaults
Context:server config, virtual host
Status:Core
Module:core
Compatibility:Moved in version 2.0 to the MPMs.
+

Takes 1 or 2 parameters. The first parameter sets the soft + resource limit for all processes and the second parameter sets + the maximum resource limit. Either parameter can be a number, + or max to indicate to the server that the limit should + be set to the maximum allowed by the operating system + configuration. Raising the maximum resource limit requires that + the server is running as root, or in the initial startup + phase.

+ +

This applies to processes forked off from Apache children + servicing requests, not the Apache children themselves. This + includes CGI scripts and SSI exec commands, but not any + processes forked off from the Apache parent such as piped + logs.

+ +

Memory resource limits are expressed in bytes per + process.

+

See also

RLimitNPROC Directive

Description: Limits the number of processes that can be launched by +processes launched by Apache children
Syntax:RLimitNPROC number|max [number|max]
Default:Unset; uses operating system defaults
Context:server config, virtual host
Status:Core
Module:core
Compatibility:Moved in version 2.0 to the MPMs.
+

Takes 1 or 2 parameters. The first parameter sets the soft + resource limit for all processes and the second parameter sets + the maximum resource limit. Either parameter can be a number, + or max to indicate to the server that the limit + should be set to the maximum allowed by the operating system + configuration. Raising the maximum resource limit requires that + the server is running as root, or in the initial startup + phase.

+ +

This applies to processes forked off from Apache children + servicing requests, not the Apache children themselves. This + includes CGI scripts and SSI exec commands, but not any + processes forked off from the Apache parent such as piped + logs.

+ +

Process limits control the number of processes per user.

+ +

Note: If CGI processes are not running + under userids other than the web server userid, this directive + will limit the number of processes that the server itself can + create. Evidence of this situation will be indicated by + cannot fork messages in the + error_log.

+

See also

Satisfy Directive

Description: Configures how host-level access control and user authentication +interact
Syntax:Satisfy any|all
Default:Satisfy all
Context:directory, .htaccess
Status:Core
Module:core
+

Access policy if both Allow and Require used. The parameter can be + either 'all' or 'any'. This directive is only + useful if access to a particular area is being restricted by both + username/password and client host address. In this case + the default behavior ("all") is to require that the client passes + the address access restriction and enters a valid + username and password. With the "any" option the client will be + granted access if they either pass the host restriction or enter a + valid username and password. This can be used to password restrict + an area, but to let clients from particular addresses in without + prompting for a password.

+ +

For example, if you wanted to let people on your network have + unrestricted access to a portion of your website, but require that + people outside of your network provide a password, you could use a + configuration similar to the following:

+ +
+ Require valid-user
+ Allow from 192.168.1
+ Satisfy any +
+ +

See also

ScriptInterpreterSource Directive

Description: Controls how the interpreter for CGI scripts is +located
Syntax:ScriptInterpreterSource registry|script
Default:ScriptInterpreterSource script
Context:directory, .htaccess
Status:Core
Module:core
Compatibility:Win32 only
+

This directive is used to control how Apache finds the + interpreter used to run CGI scripts. The default technique is to + use the interpreter pointed to by the #! line in the + script. Setting ScriptInterpreterSource registry will + cause the Windows Registry to be searched using the script file + extension (e.g., .pl) as a search key.

+

ServerAdmin Directive

Description: Sets the email address that the server includes in error +messages sent to the client
Syntax:ServerAdmin email-address
Context:server config, virtual host
Status:Core
Module:core
+

The ServerAdmin sets the e-mail address + that the server includes in any error messages it returns to the + client.

+ +

It may be worth setting up a dedicated address for this, + e.g.

+
ServerAdmin www-admin@foo.bar.com
+

as users do not always mention that they are talking about the + server!

+

ServerAlias Directive

Description: Sets alternate names for a host used when matching requests +to name-virtual hosts
Syntax:ServerAlias hostname [hostname] ...
Context:virtual host
Status:Core
Module:core
+

The ServerAlias directive sets the + alternate names for a host, for use with name-based virtual hosts.

+ +
+ <VirtualHost *>
+ ServerName server.domain.com
+ ServerAlias server server2.domain.com server2
+ ...
+ </VirtualHost> +
+

See also

ServerName Directive

Description: Sets the hostname and port that the server uses to identify +itself
Syntax:ServerName fully-qualified-domain-name[:port]
Context:server config, virtual host
Status:Core
Module:core
Compatibility:In version 2.0, this + directive supersedes the functionality of the Port + directive from version 1.3.
+

The ServerName directive sets the hostname and + port that the server uses to identify itself. This is used when + creating redirection URLs. For example, if the name of the + machine hosting the webserver is simple.example.com, + but the machine also has the DNS alias www.example.com + and you wish the webserver to be so identified, the following + directive should be used:

+ +
ServerName www.example.com:80
+ +

If no ServerName is specified, then the + server attempts to deduce the hostname by performing a reverse + lookup on the IP address. If no port is specified in the + servername, then the server will use the port from the incoming + request. For optimal reliability and predictability, you should + specify an explicit hostname and port using the + ServerName directive.

+ +

If you are using name-based virtual hosts, + the ServerName inside a + <VirtualHost> + section specifies what hostname must appear in the request's + Host: header to match this virtual host.

+ +

See the description of the + UseCanonicalName directive for + settings which determine whether self-referential URL's (e.g., by the + mod_dir module) will refer to the + specified port, or to the port number given in the client's request. +

+

See also

ServerPath Directive

Description: Sets the legacy URL pathname for a name-virtual host that +is accessed by an incompatible browser
Syntax:ServerPath directory-path
Context:virtual host
Status:Core
Module:core
+

The ServerPath directive sets the legacy + URL pathname for a host, for use with name-based virtual hosts.

+

See also

ServerRoot Directive

Description: Sets the base directory for the server installation
Syntax:ServerRoot directory-path
Default:ServerRoot /usr/local/apache
Context:server config
Status:Core
Module:core
+

The ServerRoot directive sets the + directory in which the server lives. Typically it will contain the + subdirectories conf/ and logs/. Relative + paths for other configuration files are taken as relative to this + directory.

+

See also

ServerSignature Directive

Description: Configures the footer on server-generated documents
Syntax:ServerSignature On|Off|EMail
Default:ServerSignature Off
Context:server config, virtual host, directory, .htaccess
Status:Core
Module:core
+

The ServerSignature directive allows the + configuration of a trailing footer line under server-generated + documents (error messages, mod_proxy ftp directory listings, + mod_info output, ...). The reason why you would want to enable + such a footer line is that in a chain of proxies, the user often + has no possibility to tell which of the chained servers actually + produced a returned error message.
The Off + setting, which is the default, suppresses the error line (and is + therefore compatible with the behavior of Apache-1.2 and + below). The On setting simply adds a line with the + server version number and ServerName of the serving virtual host, + and the EMail setting additionally creates a + "mailto:" reference to the ServerAdmin of the referenced + document.

+

ServerTokens Directive

Description: Configures the Server HTTP response header
Syntax:ServerTokens Minimal|ProductOnly|OS|Full
Default:ServerTokens Full
Context:server config
Status:Core
Module:core
+

This directive controls whether Server response + header field which is sent back to clients includes a + description of the generic OS-type of the server as well as + information about compiled-in modules.

+ +
+
ServerTokens Prod[uctOnly]
+ +
Server sends (e.g.): Server: + Apache
+ +
ServerTokens Min[imal]
+ +
Server sends (e.g.): Server: + Apache/1.3.0
+ +
ServerTokens OS
+ +
Server sends (e.g.): Server: Apache/1.3.0 + (Unix)
+ +
ServerTokens Full (or not specified)
+ +
Server sends (e.g.): Server: Apache/1.3.0 + (Unix) PHP/3.0 MyMod/1.2
+
+ +

This setting applies to the entire server, and cannot be + enabled or disabled on a virtualhost-by-virtualhost basis.

+

SetHandler Directive

Description: Forces all matching files to be processed by a +handler
Syntax:SetHandler handler-name
Context:server config, virtual host, directory, .htaccess
Status:Core
Module:core
Compatibility:Moved into the core in Apache 2.0
+

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 httpd.conf:

+
+ <Location /status>
+ SetHandler server-status
+ </Location> +
+

SetInputFilter Directive

Description: Sets the filters that will process client requests and POST +input
Syntax:SetInputFilter filter[;filter...]
Context:server config, virtual host, directory, .htaccess
Status:Core
Module:core
+

The SetInputFilter directive sets the + filter or filters which will process client requests and POST + input when they are received by the server. This is in addition to + any filters defined elsewhere, including the + AddInputFilter + directive.

+ +

If more than one filter is specified, they must be separated + by semicolons in the order in which they should process the + content.

+

See also

SetOutputFilter Directive

Description: Sets the filters that will process responses from the +server
Syntax:SetOutputFilter filter [filter] ...
Context:server config, virtual host, directory, .htaccess
Status:Core
Module:core
+

The SetOutputFilter directive sets the filters + which will process responses from the server before they are + sent to the client. This is in addition to any filters defined + elsewhere, including the + AddOutputFilter + directive.

+ +

For example, the following configuration will process all files + in the /www/data/ directory for server-side + includes.

+
+<Directory /www/data/>
+  SetOutputFilter INCLUDES
+</Directory> +
+ +

If more than one filter is specified, they must be separated + by semicolons in the order in which they should process the + content.

+

See also

TimeOut Directive

Description: Defines the amount of time the server will wait for +certain events before failing a request
Syntax:TimeOut number
Default:TimeOut 300
Context:server config
Status:Core
Module:core
+

The TimeOut directive currently defines + the amount of time Apache will wait for three things:

+ +
    +
  1. The total amount of time it takes to receive a GET + request.
    2. + +
  2. The amount of time between receipt of TCP packets on a + POST or PUT request.
    3. + +
  3. The amount of time between ACKs on transmissions of TCP + packets in responses.
    4. +
+ +

We plan on making these separately configurable at some point + down the road. The timer used to default to 1200 before 1.2, + but has been lowered to 300 which is still far more than + necessary in most situations. It is not set any lower by + default because there may still be odd places in the code where + the timer is not reset when a packet is sent.

+

UseCanonicalName Directive

Description: Configures how the server determines its own name and +port
Syntax:UseCanonicalName on|off|dns
Default:UseCanonicalName on
Context:server config, virtual host, directory, .htaccess
Override:Options
Status:Core
Module:core
+

In many situations Apache has to construct a + self-referential URL. That is, a URL which refers back to + the same server. With UseCanonicalName on Apache will + use the hostname and port specified in the ServerName directive to construct a canonical + name for the server. This name is used in all self-referential + URLs, and for the values of SERVER_NAME and + SERVER_PORT in CGIs.

+ +

With UseCanonicalName off Apache will form + self-referential URLs using the hostname and port supplied by + the client if any are supplied (otherwise it will use the + canonical name). These values are the same that are used to + implement name based + virtual hosts, and are available with the same clients. The + CGI variables SERVER_NAME and + SERVER_PORT will be constructed from the client + supplied values as well.

+ +

An example where this may be useful is on an intranet server + where you have users connecting to the machine using short + names such as www. You'll notice that if the users + type a shortname, and a URL which is a directory, such as + http://www/splat, without the trailing + slash then Apache will redirect them to + http://www.domain.com/splat/. If you have + authentication enabled, this will cause the user to have to + reauthenticate twice (once for www and once again + for www.domain.com). But if + UseCanonicalName is set off, then Apache will + redirect to http://www/splat/.

+ +

There is a third option, UseCanonicalName DNS, + which is intended for use with mass IP-based virtual hosting to + support ancient clients that do not provide a + Host: header. With this option Apache does a + reverse DNS lookup on the server IP address that the client + connected to in order to work out self-referential URLs.

+ +

Warning: if CGIs make assumptions about the + values of SERVER_NAME they may be broken by this + option. The client is essentially free to give whatever value + they want as a hostname. But if the CGI is only using + SERVER_NAME to construct self-referential URLs + then it should be just fine.

+

See also

<VirtualHost> Directive

Description: Contains directives that apply only to a specific +hostname or IP address
Syntax:<VirtualHost + addr[:port] [addr[:port]] + ...> ... </VirtualHost>
Context:server config
Status:Core
Module:core
+

<VirtualHost> and + </VirtualHost> are used to enclose a group of + directives which will apply only to a particular virtual host. Any + directive which is allowed in a virtual host context may be + used. When the server receives a request for a document on a + particular virtual host, it uses the configuration directives + enclosed in the <VirtualHost> + section. Addr can be

+ + + + +

Example

+ <VirtualHost 10.1.2.3>
+ ServerAdmin webmaster@host.foo.com
+ DocumentRoot /www/docs/host.foo.com
+ ServerName host.foo.com
+ ErrorLog logs/host.foo.com-error_log
+ TransferLog logs/host.foo.com-access_log
+ </VirtualHost> +
+ + +

IPv6 addresses must be specified in square brackets because + the optional port number could not be determined otherwise. An + IPv6 example is shown below:

+ +
+<VirtualHost [fe80::a00:20ff:fea7:ccea]>
+ ServerAdmin webmaster@host.foo.com
+ DocumentRoot /www/docs/host.foo.com
+ ServerName host.foo.com
+ ErrorLog logs/host.foo.com-error_log
+ TransferLog logs/host.foo.com-access_log
+ </VirtualHost> +
+ +

Each Virtual Host must correspond to a different IP address, + different port number or a different host name for the server, + in the former case the server machine must be configured to + accept IP packets for multiple addresses. (If the machine does + not have multiple network interfaces, then this can be + accomplished with the ifconfig alias command (if + your OS supports it), or with kernel patches like VIF (for SunOS(TM) 4.1.x)).

+ +

The special name _default_ can be specified in + which case this virtual host will match any IP address that is + not explicitly listed in another virtual host. In the absence + of any _default_ virtual host the "main" server config, + consisting of all those definitions outside any VirtualHost + section, is used when no match occurs.

+ +

You can specify a :port to change the port that is + matched. If unspecified then it defaults to the same port as the + most recent Listen + statement of the main server. You may also specify :* + to match all ports on that address. (This is recommended when used + with _default_.)

+ +

SECURITY: See the security tips document + for details on why your security could be compromised if the + directory where logfiles are stored is writable by anyone other + than the user that starts the server.

+ +

NOTE: The use of <VirtualHost> does not + affect what addresses Apache listens on. You may need to ensure + that Apache is listening on the correct addresses using Listen.

+

See also

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/directives.html.en b/docs/manual/mod/directives.html.en new file mode 100644 index 0000000000..a7da351bbd --- /dev/null +++ b/docs/manual/mod/directives.html.en @@ -0,0 +1,8 @@ +Directive Index- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Directive Index

+

+ Each Apache directive available in the standard Apache + distribution is listed here. They are described using a + consistent format, and there is a dictionary of the terms used in their + descriptions available. +

+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/index.html.en b/docs/manual/mod/index.html.en new file mode 100644 index 0000000000..a79fc8a91b --- /dev/null +++ b/docs/manual/mod/index.html.en @@ -0,0 +1,55 @@ +Module Index- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Module Index

+

+ Below is a list of all of the modules that come as part of + the Apache distribution. See also the complete + alphabetical list of all Apache + directives. +

+

Core Features and Multi-Processing Modules

core
Core Apache HTTP Server features that are always +available
mpm_common
A collection of directives that are implemented by +more than one multi-processing module (MPM)
mpm_netware
Multi-Processing Module implementing an exclusively threaded web + server optimized for Novell NetWare
mpm_winnt
This Multi-Processing Module is optimized for Windows + NT.
perchild
Multi-Processing Module allowing for daemon processes + serving requests to be assigned a variety of different + userids
prefork
Implements a non-threaded, pre-forking web server
worker
Multi-Processing Module implementing a hybrid + multi-threaded multi-process web server

Other Modules

mod_access
Provides access control based on client hostname, IP +address, or other characteristics of the client request.
mod_actions
This module provides for executing CGI scripts based on +media type or request method.
mod_alias
Provides for mapping different parts of the host + filesystem in the document tree and for URL redirection
mod_asis
Sends files that contain their own +HTTP headers
mod_auth
User authentication using text files
mod_auth_anon
Allows "anonymous" user access to authenticated + areas
mod_auth_dbm
Provides for user authentication using DBM + files
mod_auth_digest
User authentication using MD5 + Digest Authentication.
mod_autoindex
Generates directory indexes, + automatically, similar to the Unix ls command or the + Win32 dir shell command
mod_cache
Content cache keyed to URIs
mod_cern_meta
CERN httpd metafile semantics
mod_cgi
Execution of CGI scripts
mod_cgid
Execution of CGI scripts using an + external CGI daemon
mod_charset_lite
Specify character set translation or recoding
mod_dav
Distributed Authoring and Versioning +(WebDAV) functionality
mod_deflate
Compress content before + it is delivered to the client
mod_dir
Provides for "trailing slash" redirects and + serving directory index files
mod_env
Modifies the environment which is + passed to CGI scripts and SSI pages
mod_example
Illustrates the Apache module API
mod_expires
Generation of + Expires HTTP headers according to user-specified + criteria
mod_ext_filter
Pass the response body + through an external program before delivery to the + client
mod_file_cache
Caches a static list of files in memory
mod_headers
Customization of HTTP request + and response headers
mod_imap
Server-side imagemap processing
mod_include
Server-parsed html documents (Server Side Includes)
mod_info
Provides a comprehensive overview of the server +configuration
mod_isapi
ISAPI Extensions within Apache for Windows
mod_log_config
Logging of the requests made to the server
mod_mime
Associates the requested filename's extensions + with the file's behavior (handlers and filters) + and content (mime-type, language, character set and + encoding)
mod_mime_magic
Determines the MIME type of a file + by looking at a few bytes of its contents
mod_negotiation
Provides for content negotiation
mod_proxy
HTTP/1.1 proxy/gateway server
mod_rewrite
Provides a rule-based rewriting engine to rewrite requested +URLs on the fly
mod_setenvif
Allows the setting of environment variables based +on characteristics of the request
mod_so
+ This module provides for loading of executable code and + modules into the server at start-up or restart time. +
mod_speling
Attempts to correct mistaken URLs that +users might have entered by ignoring capitalization and by +allowing up to one misspelling
mod_ssl
Strong cryptography using the Secure Sockets +Layer (SSL) and Transport Layer Security (TLS) protocols
mod_status
Provides information on server activity and +performance
mod_suexec
Allows CGI scripts to run as a specified user +and Group
mod_unique_id
Provides an environment variable with a unique +identifier for each request
mod_userdir
Provides for user-specific +directories
mod_usertrack
+ This module uses cookies to provide for a + clickstream log of user activity on a site. +
mod_vhost_alias
Provides for dynamically configured mass virtual +hosting

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_access.html.en b/docs/manual/mod/mod_access.html.en new file mode 100644 index 0000000000..afe64a0b60 --- /dev/null +++ b/docs/manual/mod/mod_access.html.en @@ -0,0 +1,226 @@ +mod_access- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_access

Description:Provides access control based on client hostname, IP +address, or other characteristics of the client request.
Status:Base
Module Identifier:access_module

Summary

+

The directives provided by mod_access are used in <Directory>, <Files>, and <Location> sections as well as + .htaccess + files to control access to particular parts of the server. Access + can be controlled based on the client hostname, IP address, or + other characteristics of the client request, as captured in environment variables. The Allow and Deny directives are used to + specify which clients are or are not allowed access to the server, + while the Order + directive sets the default access state, and configures how the + Allow and Deny directives interact with each + other.

+ +

Both host-based access restrictions and password-based + authentication may be implemented simultaneously. In that case, + the Satisfy directive is used + to determine how the two sets of restrictions interact.

+ +

In general, access restriction directives apply to all + access methods (GET, PUT, + POST, etc). This is the desired behavior in most + cases. However, it is possible to restrict some methods, while + leaving other methods unrestricted, by enclosing the directives + in a <Limit> section.

+

Directives

See also

Allow Directive

Description: Controls which hosts can access an area of the +server
Syntax: Allow from + all|host|env=env-variable + [host|env=env-variable] ...
Context:directory, .htaccess
Override:Limit
Status:Base
Module:mod_access
+ +

The Allow directive affects which hosts can + access an area of the server. Access can be controlled by + hostname, IP Address, IP Address range, or by other + characteristics of the client request captured in environment + variables.

+ +

The first argument to this directive is always + from. The subsequent arguments can take three + different forms. If Allow from all is specified, then + all hosts are allowed access, subject to the configuration of the + Deny and Order directives as discussed + below. To allow only particular hosts or groups of hosts to access + the server, the host can be specified in any of the + following formats:

+ +
+
A (partial) domain-name
+ +
Example: Allow from apache.org
+ Hosts whose names match, or end in, this string are allowed + access. Only complete components are matched, so the above + example will match foo.apache.org but it will + not match fooapache.org. This configuration will + cause the server to perform a reverse DNS lookup on the + client IP address, regardless of the setting of the HostnameLookups + directive.
+ +
A full IP address
+ +
Example: Allow from 10.1.2.3
+ An IP address of a host allowed access
+ +
A partial IP address
+ +
Example: Allow from 10.1
+ The first 1 to 3 bytes of an IP address, for subnet + restriction.
+ +
A network/netmask pair
+ +
Example: Allow from + 10.1.0.0/255.255.0.0
+ A network a.b.c.d, and a netmask w.x.y.z. For more + fine-grained subnet restriction.
+ +
A network/nnn CIDR specification
+ +
Example: Allow from 10.1.0.0/16
+ Similar to the previous case, except the netmask consists of + nnn high-order 1 bits.
+
+ +

Note that the last three examples above match exactly the + same set of hosts.

+ +

IPv6 addresses and IPv6 subnets can be specified as shown + below:

+ +
+ Allow from fe80::a00:20ff:fea7:ccea
+ Allow from fe80::a00:20ff:fea7:ccea/10 +
+ +

The third format of the arguments to the + Allow directive allows access to the server + to be controlled based on the existence of an environment variable. When Allow from + env=env-variable is specified, then the request is + allowed access if the environment variable env-variable + exists. The server provides the ability to set environment + variables in a flexible way based on characteristics of the client + request using the directives provided by + mod_setenvif. Therefore, this directive can be + used to allow access based on such factors as the clients + User-Agent (browser type), Referer, or + other HTTP request header fields.

+ +

Example:

+ +SetEnvIf User-Agent ^KnockKnock/2.0 let_me_in
+<Directory /docroot>
+   Order Deny,Allow
+   Deny from all
+   Allow from env=let_me_in
+</Directory> +
+ +

In this case, browsers with a user-agent string beginning + with KnockKnock/2.0 will be allowed access, and all + others will be denied.

+

Deny Directive

Description: Controls which hosts are denied access to the +server
Syntax: Deny from + all|host|env=env-variable + [host|env=env-variable] ...
Context:directory, .htaccess
Override:Limit
Status:Base
Module:mod_access
+

This directive allows access to the server to be restricted + based on hostname, IP address, or environment variables. The + arguments for the Deny directive are + identical to the arguments for the Allow directive.

+

Order Directive

Description: Controls the default access state and the order in which +Allow and Deny are +evaluated.
Syntax: Order ordering
Default:Order Deny,Allow
Context:directory, .htaccess
Override:Limit
Status:Base
Module:mod_access
+ +

The Order directive controls the default + access state and the order in which Allow and Deny directives are evaluated. + Ordering is one of

+ +
+
Deny,Allow
+ +
The Deny directives + are evaluated before the Allow directives. Access is + allowed by default. Any client which does not match a + Deny directive or does + match an Allow + directive will be allowed access to the server.
+ +
Allow,Deny
+ +
The Allow + directives are evaluated before the Deny directives. Access is denied + by default. Any client which does not match an Allow directive or does match a + Deny directive will be + denied access to the server.
+ +
Mutual-failure
+ +
Only those hosts which appear on the Allow list and do not appear on + the Deny list are + granted access. This ordering has the same effect as Order + Allow,Deny and is deprecated in favor of that + configuration.
+
+ +

Keywords may only be separated by a comma; no whitespace is + allowed between them. Note that in all cases every Allow and Deny statement is evaluated.

+ +

In the following example, all hosts in the apache.org domain + are allowed access; all other hosts are denied access.

+ +
+ Order Deny,Allow
+ Deny from all
+ Allow from apache.org
+
+ +

In the next example, all hosts in the apache.org domain are + allowed access, except for the hosts which are in the + foo.apache.org subdomain, who are denied access. All hosts not + in the apache.org domain are denied access because the default + state is to deny access to the server.

+ +
+ Order Allow,Deny
+ Allow from apache.org
+ Deny from foo.apache.org
+
+ +

On the other hand, if the Order in the last + example is changed to Deny,Allow, all hosts will + be allowed access. This happens because, regardless of the + actual ordering of the directives in the configuration file, + the Allow from apache.org will be evaluated last + and will override the Deny from foo.apache.org. + All hosts not in the apache.org domain will also + be allowed access because the default state will change to + allow.

+ +

The presence of an Order directive can affect + access to a part of the server even in the absence of accompanying + Allow and Deny directives because of its effect + on the default access state. For example,

+ +
+ <Directory /www>
+   Order Allow,Deny
+ </Directory> +
+ +

will deny all access to the /www directory + because the default access state will be set to + deny.

+ +

The Order directive controls the order of access + directive processing only within each phase of the server's + configuration processing. This implies, for example, that an + Allow or Deny directive occurring in a + <Location> section will + always be evaluated after an Allow or Deny directive occurring in a + <Directory> section or + .htaccess file, regardless of the setting of the + Order directive. For details on the merging + of configuration sections, see the documentation on How Directory, Location and Files sections + work.

+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_actions.html.en b/docs/manual/mod/mod_actions.html.en new file mode 100644 index 0000000000..c87a411798 --- /dev/null +++ b/docs/manual/mod/mod_actions.html.en @@ -0,0 +1,73 @@ +mod_actions- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_actions

Description:This module provides for executing CGI scripts based on +media type or request method.
Status:Base
Module Identifier:actions_module

Summary

+

This module has two directives. The Action directive lets you run CGI + scripts whenever a file of a certain type is requested. The + Script directive lets + you run CGI scripts whenever a particular method is used in a + request. This makes it much easier to execute scripts that process + files.

+

Directives

Action Directive

Description: Activates a CGI script for a particular handler or +content-type
Syntax:Action action-type cgi-script
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Base
Module:mod_actions
+

This directive adds an action, which will activate + cgi-script when action-type is triggered by the + request. The cgi-script is the URL-path to a resource + that has been designated as a CGI script using ScriptAliase or AddHandler. The + action-type can be either a handler or a MIME content type. It + sends the URL and file path of the requested document using the + standard CGI PATH_INFO and PATH_TRANSLATED environment + variables.

+ +

Examples

+ + + # Requests for files of a particular type:
+ Action image/gif /cgi-bin/images.cgi
+
+ # Files of a particular file extension
+ AddHandler my-file-type .xyz
+ Action my-file-type /cgi-bin/program.cgi
+
+ +

In the first example, requests for files with a MIME content + type of image/gif will instead be handled by the + specified cgi script /cgi-bin/images.cgi.

+ +

In the second example, requests for files with a file extension of + .xyz are handled instead by the specified cgi script + /cgi-bin/program.cgi.

+

See also

Script Directive

Description: Activates a CGI script for a particular request +method.
Syntax: Script method cgi-script
Context:server config, virtual host, directory
Status:Base
Module:mod_actions
+

This directive adds an action, which will activate + cgi-script when a file is requested using the method of + method. The cgi-script is the URL-path to a + resource that has been designated as a CGI script using ScriptAliase or AddHandler. The URL and + file path of the requested document is sent using the standard CGI + PATH_INFO and PATH_TRANSLATED environment variables.

+ +
+ Any arbitrary method name may be used. Method names are + case-sensitive, so Script PUT and + Script put have two entirely different + effects. +
+ +

Note that the Script command defines default actions only. + If a CGI script is called, or some other resource that is + capable of handling the requested method internally, it will do + so. Also note that Script with a method of GET + will only be called if there are query arguments present + (e.g., foo.html?hi). Otherwise, the request will + proceed normally.

+ +

Examples

+ + # For <ISINDEX>-style searching
+ Script GET /cgi-bin/search
+ # A CGI PUT handler
+ Script PUT /~bob/put.cgi
+
+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_alias.html.en b/docs/manual/mod/mod_alias.html.en new file mode 100644 index 0000000000..4b3e73dab5 --- /dev/null +++ b/docs/manual/mod/mod_alias.html.en @@ -0,0 +1,182 @@ +mod_alias- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_alias

Description:Provides for mapping different parts of the host + filesystem in the document tree and for URL redirection
Status:Base
Module Identifier:alias_module

Summary

+

The directives contained in this module allow for manipulation + and control of URLs as requests arrive at the server. The + Alias and ScriptAlias directives are used to + map between URLs and filesystem paths. This allows for content + which is not directly under the DocumentRoot served as part of the web + document tree. The ScriptAlias directive has the + additional effect of marking the target directory as containing + only CGI scripts.

+ +

The Redirect + directives are used to instruct clients to make a new request with + a different URL. They are often used when a resource has moved to + a new location.

+

Directives

See also

Alias Directive

Description: Maps URLs to filesystem locations
Syntax: Alias URL-path + file-path|directory-path
Context:server config, virtual host
Status:Base
Module:mod_alias
+ +

The Alias directive allows documents to + be stored in the local filesystem other than under the + DocumentRoot. URLs with a + (%-decoded) path beginning with url-path will be mapped + to local files beginning with directory-filename.

+ +

Example:

+ +
Alias /image /ftp/pub/image
+ +

A request for http://myserver/image/foo.gif would cause the + server to return the file /ftp/pub/image/foo.gif.

+ +

Note that if you include a trailing / on the + url-path then the server will require a trailing / in + order to expand the alias. That is, if you use Alias + /icons/ /usr/local/apache/icons/ then the url + /icons will not be aliased.

+ +

Note that you may need to specify additional <Directory> sections which cover + the destination of aliases. Aliasing occurs before + <Directory> sections + are checked, so only the destination of aliases are affected. + (Note however <Location> + sections are run through once before aliases are performed, so + they will apply.)

+ +

AliasMatch Directive

Description: Maps URLs to filesystem locations using regular +expressions
Syntax:AliasMatch regex + file-path|directory-path
Context:server config, virtual host
Status:Base
Module:mod_alias
+

This directive is equivalent to Alias, but makes use of standard + regular expressions, instead of simple prefix matching. The + supplied regular expression is matched against the URL-path, and + if it matches, the server will substitute any parenthesized + matches into the given string and use it as a filename. For + example, to activate the /icons directory, one might + use:

+
+ AliasMatch ^/icons(.*) /usr/local/apache/icons$1 +
+

Redirect Directive

Description: Sends an external redirect asking the client to fetch +a different URL
Syntax:Redirect [status] URL-path URL
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Base
Module:mod_alias
+

The Redirect directive maps an old URL into a new one. The + new URL is returned to the client which attempts to fetch it + again with the new address. URL-path a (%-decoded) + path; any requests for documents beginning with this path will + be returned a redirect error to a new (%-encoded) URL beginning + with URL.

+ +

Example:

+ +
Redirect /service http://foo2.bar.com/service
+ +

If the client requests http://myserver/service/foo.txt, it + will be told to access http://foo2.bar.com/service/foo.txt + instead.

+ +

Note

Redirect directives take precedence over +Alias and ScriptAlias directives, irrespective of their ordering in +the configuration file. Also, URL-path must be an absolute +path, not a relative path, even when used with .htaccess files or +inside of <Directory> +sections.

+ +

If no status argument is given, the redirect will + be "temporary" (HTTP status 302). This indicates to the client + that the resource has moved temporarily. The status + argument can be used to return other HTTP status codes:

+ +
+
permanent
+ +
Returns a permanent redirect status (301) indicating that + the resource has moved permanently.
+ +
temp
+ +
Returns a temporary redirect status (302). This is the + default.
+ +
seeother
+ +
Returns a "See Other" status (303) indicating that the + resource has been replaced.
+ +
gone
+ +
Returns a "Gone" status (410) indicating that the + resource has been permanently removed. When this status is + used the url argument should be omitted.
+
+ +

Other status codes can be returned by giving the numeric + status code as the value of status. If the status is + between 300 and 399, the url argument must be present, + otherwise it must be omitted. Note that the status must be + known to the Apache code (see the function + send_error_response in http_protocol.c).

+ +

Example:

+ +
+ Redirect permanent /one http://example.com/two
+ Redirect 303 /three http://example.com/other +
+ +

RedirectMatch Directive

Description: Sends an external redirect asking the client to fetch +a different URL based on a regular expression match of the +current URL
Syntax:RedirectMatch [status] regex URL
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Base
Module:mod_alias
+

This directive is equivalent to Redirect, but makes use of standard + regular expressions, instead of simple prefix matching. The + supplied regular expression is matched against the URL-path, and + if it matches, the server will substitute any parenthesized + matches into the given string and use it as a filename. For + example, to redirect all GIF files to like-named JPEG files on + another server, one might use:

+
+ RedirectMatch (.*)\.gif$ http://www.anotherserver.com$1.jpg +
+

RedirectPermanent Directive

Description: Sends an external permanent redirect asking the client to fetch +a different URL
Syntax:RedirectPermanent URL-path URL
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Base
Module:mod_alias
+

This directive makes the client know that the Redirect is + permanent (status 301). Exactly equivalent to Redirect + permanent.

+

RedirectTemp Directive

Description: Sends an external temporary redirect asking the client to fetch +a different URL
Syntax:RedirectTemp URL-path URL
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Base
Module:mod_alias
+

This directive makes the client know that the Redirect is + only temporary (status 302). Exactly equivalent to + Redirect temp.

+

ScriptAlias Directive

Description: Maps a URL to a filesystem location and designates the +target as a CGI script
Syntax:ScriptAlias +URL-path file-path|directory-path
Context:server config, virtual host
Status:Base
Module:mod_alias
+

The ScriptAlias directive has the same + behavior as the Alias + directive, except that in addition it marks the target directory + as containing CGI scripts that will be processed by mod_cgi's cgi-script handler. URLs with a + (%-decoded) path beginning with URL-path will be mapped + to scripts beginning with the second argument which is a full + pathname in the local filesystem.

+ +

Example:

+ +
ScriptAlias /cgi-bin/ /web/cgi-bin/
+ +

A request for http://myserver/cgi-bin/foo would cause the + server to run the script /web/cgi-bin/foo.

+

ScriptAliasMatch Directive

Description: Maps a URL to a filesystem location using a regular expression +and designates the target as a CGI script
Syntax:ScriptAliasMatch +regex file-path|directory-path
Context:server config, virtual host
Status:Base
Module:mod_alias
+

This directive is equivalent to ScriptAlias, but makes use of standard + regular expressions, instead of simple prefix matching. The + supplied regular expression is matched against the URL-path, + and if it matches, the server will substitute any parenthesized + matches into the given string and use it as a filename. For + example, to activate the standard /cgi-bin, one + might use:

+
+ ScriptAliasMatch ^/cgi-bin(.*) /usr/local/apache/cgi-bin$1 +
+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_asis.html.en b/docs/manual/mod/mod_asis.html.en new file mode 100644 index 0000000000..0b06c37021 --- /dev/null +++ b/docs/manual/mod/mod_asis.html.en @@ -0,0 +1,59 @@ +mod_asis- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_asis

Description:Sends files that contain their own +HTTP headers
Status:Base
Module Identifier:asis_module

Summary

+

This module provides the handler send-as-is + which causes Apache to send the document without adding most of + the usual HTTP headers.

+ +

This can be used to send any kind of data from the server, + including redirects and other special HTTP responses, without + requiring a cgi-script or an nph script.

+ +

For historical reasons, this module will also process any + file with the mime type httpd/send-as-is.

+

Directives

Usage

+ +

In the server configuration file, associate files with the + send-as-is handler e.g.

+ +
AddHandler send-as-is asis
+ +

The contents of any file with a .asis extension + will then be sent by Apache to the client with almost no + changes. Clients will need HTTP headers to be attached, so do + not forget them. A Status: header is also required; the data + should be the 3-digit HTTP response code, followed by a textual + message.

+ +

Here's an example of a file whose contents are sent as + is so as to tell the client that a file has + redirected.

+ + +
Status: 301 Now where did I leave that URL
+ Location: http://xyz.abc.com/foo/bar.html
+ Content-type: text/html
+
+ <HTML>
+ <HEAD>
+ <TITLE>Lame excuses'R'us</TITLE>
+ </HEAD>
+ <BODY>
+ <H1>Fred's exceptionally wonderful page has moved + to
+ <A + HREF="http://xyz.abc.com/foo/bar.html">Joe's</A> + site.
+ </H1>
+ </BODY>
+ </HTML> +
+ +

Notes: the server always adds a Date: and Server: header to + the data returned to the client, so these should not be + included in the file. The server does not add a + Last-Modified header; it probably should.

+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_auth.html.en b/docs/manual/mod/mod_auth.html.en new file mode 100644 index 0000000000..86bd37e437 --- /dev/null +++ b/docs/manual/mod/mod_auth.html.en @@ -0,0 +1,116 @@ +mod_auth- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_auth

Description:User authentication using text files
Status:Base
Module Identifier:auth_module

Summary

+ +

This module allows the use of HTTP Basic Authentication to + restrict access by looking up users in plain text password and + group files. Similar functionality and greater scalability is + provided by mod_auth_dbm. HTTP Digest + Authentication is provided by + mod_auth_digest.

+ +

Directives

See also

AuthAuthoritative Directive

Description: Sets whether authorization and authentication are +passed to lower level modules
Syntax:AuthAuthoritative on|off
Default:AuthAuthoritative on
Context:directory, .htaccess
Override:AuthConfig
Status:Base
Module:mod_auth
+ +
This information has not been updated for Apache 2.0, which +uses a different system for module ordering.
+ +

Setting the AuthAuthoritative directive + explicitly to 'off' allows for both + authentication and authorization to be passed on to lower level + modules (as defined in the Configuration and + modules.c files) if there is no + userID or rule matching the supplied + userID. If there is a userID and/or rule specified; the usual + password and access checks will be applied and a failure will give + an Authorization Required reply.

+ +

So if a userID appears in the database of more than one module; + or if a valid Require + directive applies to more than one module; then the first module + will verify the credentials; and no access is passed on; + regardless of the AuthAuthoritative setting.

+ +

A common use for this is in conjunction with one of the + database modules; such as auth_dbm, + mod_auth_msql, and mod_auth_anon. + These modules supply the bulk of the user credential checking; but + a few (administrator) related accesses fall through to a lower + level with a well protected AuthUserFile.

+ +

By default; control is not passed on; and an unknown userID or + rule will result in an Authorization Required reply. Not setting + it thus keeps the system secure; and forces an NCSA compliant + behaviour.

+ +

Security

Do consider the implications of + allowing a user to allow fall-through in his .htaccess file; and + verify that this is really what you want; Generally it is easier + to just secure a single .htpasswd file, than it is to secure a + database such as mSQL. Make sure that the AuthUserFile is stored outside the + document tree of the web-server; do not put it in the + directory that it protects. Otherwise, clients will be able to + download the AuthUserFile. +
+

AuthGroupFile Directive

Description: Sets the name of a text file containing the list +of user groups for authentication
Syntax:AuthGroupFile file-path
Context:directory, .htaccess
Override:AuthConfig
Status:Base
Module:mod_auth
+

The AuthGroupFile directive sets the + name of a textual file containing the list of user groups for user + authentication. File-path is the path to the group + file. If it is not absolute (i.e., if it doesn't begin + with a slash), it is treated as relative to the ServerRoot.

+ +

Each line of the group file contains a groupname followed by a + colon, followed by the member usernames separated by spaces. + Example:

+ +
mygroup: bob joe anne
+ +

Note that searching large text files is very + inefficient; AuthDBMGroupFile should be used + instead.

+ +

Security

+

Make sure that the AuthGroupFile is stored outside + the document tree of the web-server; do not put it in + the directory that it protects. Otherwise, clients will be able + to download the AuthGroupFile.

+
+

AuthUserFile Directive

Description: Sets the name of a text file containing the list of users and +passwords for authentication
Syntax:AuthUserFile file-path
Context:directory, .htaccess
Override:AuthConfig
Status:Base
Module:mod_auth
+

The AuthUserFile directive sets the name + of a textual file containing the list of users and passwords for + user authentication. File-path is the path to the user + file. If it is not absolute (i.e., if it doesn't begin + with a slash), it is treated as relative to the ServerRoot.

+ +

Each line of the user file file contains a username followed by + a colon, followed by the crypt() encrypted + password. The behavior of multiple occurrences of the same user is + undefined.

+ +

The utility htpasswd + which is installed as part of the binary distribution, or which + can be found in src/support, is used to maintain + this password file. See the man page for more + details. In short:

+ +

Create a password file 'Filename' with 'username' as the + initial ID. It will prompt for the password:

+
htpasswd -c Filename username
+ +

Adds or modifies in password file 'Filename' the 'username':

+
htpasswd Filename username2
+ +

Note that searching large text files is very + inefficient; AuthDBMUserFile should be used + instead.

+ +

Security

Make sure that the AuthUserFile is +stored outside the document tree of the web-server; do not +put it in the directory that it protects. Otherwise, clients will be +able to download the AuthUserFile.

+ +

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_auth_anon.html.en b/docs/manual/mod/mod_auth_anon.html.en new file mode 100644 index 0000000000..1489cd8c9c --- /dev/null +++ b/docs/manual/mod/mod_auth_anon.html.en @@ -0,0 +1,119 @@ +mod_auth_anon- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_auth_anon

Description:Allows "anonymous" user access to authenticated + areas
Status:Extension
Module Identifier:auth_anon_module

Summary

+

This module does access control in a manner similar to + anonymous-ftp sites; i.e. have a 'magic' user id + 'anonymous' and the email address as a password. These email + addresses can be logged.

+ +

Combined with other (database) access control methods, this + allows for effective user tracking and customization according + to a user profile while still keeping the site open for + 'unregistered' users. One advantage of using Auth-based user + tracking is that, unlike magic-cookies and funny URL + pre/postfixes, it is completely browser independent and it + allows users to share URLs.

+

Directives

Example

+ +

The example below (when combined with the Auth directives of a + htpasswd-file based (or GDM, mSQL etc.) base access + control system allows users in as 'guests' with the following + properties:

+ + + +

Excerpt of httpd.conf:

+ +
+ Anonymous_NoUserId off
+ Anonymous_MustGiveEmail on
+ Anonymous_VerifyEmail on
+ Anonymous_LogEmail on
+ Anonymous anonymous guest www test welcome
+
+ AuthName "Use 'anonymous' & Email address for + guest entry"
+ AuthType basic
+
+ # An + AuthUserFile/AuthDBUserFile/AuthDBMUserFile
+ # directive must be specified, or use
+ # Anonymous_Authoritative for public access.
+ # In the .htaccess for the public directory, add:
+ <Files *>
+ Order Deny,Allow
+ Allow from all
+
+ Require valid-user
+ </Files>
+
+

Anonymous Directive

Description: Specifies userIDs that areallowed access without +password verification
Syntax:Anonymous user [user] ...
Context:directory, .htaccess
Override:AuthConfig
Status:Extension
Module:mod_auth_anon
+

A list of one or more 'magic' userIDs which are allowed + access without password verification. The userIDs are space + separated. It is possible to use the ' and " quotes to allow a + space in a userID as well as the \ escape character.

+ +

Please note that the comparison is + case-IN-sensitive.
+ I strongly suggest that the magic username + 'anonymous' is always one of the allowed + userIDs.

+ +

Example:

+
Anonymous anonymous "Not Registered" 'I don\'t know'
+ +

This would allow the user to enter without password + verification by using the userId's 'anonymous', + 'AnonyMous','Not Registered' and 'I Don't Know'.

+

Anonymous_Authoritative Directive

Description: Configures if authorization will fall-through +to other methods
Syntax:Anonymous_Authoritative on|off
Default:Anonymous_Authoritative off
Context:directory, .htaccess
Override:AuthConfig
Status:Extension
Module:mod_auth_anon
+

When set 'on', there is no fall-through to other authorization + methods. So if a userID does not match the values specified in the + Anonymous directive, + access is denied.

+ +

Be sure you know what you are doing when you decide to + switch it on. And remember that it is the linking order of the + modules (in the Configuration / Make file) which details the + order in which the Authorization modules are queried.

+

Anonymous_LogEmail Directive

Description: Sets whether the password entered will be logged in the +error log
Syntax:Anonymous_LogEmail on|off
Default:Anonymous_LogEmail on
Context:directory, .htaccess
Override:AuthConfig
Status:Extension
Module:mod_auth_anon
+

When set on, the default, the 'password' entered + (which hopefully contains a sensible email address) is logged in + the error log.

+

Anonymous_MustGiveEmail Directive

Description: Specifies whether blank passwords are allowed
Syntax:Anonymous_MustGiveEmail on|off
Default:Anonymous_MustGiveEmail on
Context:directory, .htaccess
Override:AuthConfig
Status:Extension
Module:mod_auth_anon
+

Specifies whether the user must specify an email address as + the password. This prohibits blank passwords.

+

Anonymous_NoUserID Directive

Description: Sets whether the userID field may be empty
Syntax:Anonymous_NoUserID on|off
Default:Anonymous_NoUserID off
Context:directory, .htaccess
Override:AuthConfig
Status:Extension
Module:mod_auth_anon
+

When set on, users can leave the userID (and + perhaps the password field) empty. This can be very convenient for + MS-Explorer users who can just hit return or click directly on the + OK button; which seems a natural reaction.

+

Anonymous_VerifyEmail Directive

Description: Sets whether to check the password field for a correctly +formatted email address
Syntax:Anonymous_VerifyEmail on|off
Default:Anonymous_VerifyEmail off
Context:directory, .htaccess
Override:AuthConfig
Status:Extension
Module:mod_auth_anon
+

When set on the 'password' entered is checked for + at least one '@' and a '.' to encourage users to enter valid email + addresses (see the above Auth_LogEmail).

+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_auth_dbm.html.en b/docs/manual/mod/mod_auth_dbm.html.en new file mode 100644 index 0000000000..cbd91f446b --- /dev/null +++ b/docs/manual/mod/mod_auth_dbm.html.en @@ -0,0 +1,134 @@ +mod_auth_dbm- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_auth_dbm

Description:Provides for user authentication using DBM + files
Status:Extension
Module Identifier:auth_dbm_module

Summary

+

This module provides for HTTP Basic Authentication, where + the usernames and passwords are stored in DBM type database + files. It is an alternative to the plain text password files + provided by mod_auth.

+

Directives

See also

AuthDBMAuthoritative Directive

Description: Sets whether authentication and authorization will be +passwed on to lower level modules
Syntax:AuthDBMAuthoritative on|off
Default:AuthDBMAuthoritative on
Context:directory, .htaccess
Override:AuthConfig
Status:Extension
Module:mod_auth_dbm
+ +
This information has not been updated to take into account the +new module ordering techniques in Apache 2.0
+ +

Setting the AuthDBMAuthoritative + directive explicitly to 'off' allows for both + authentication and authorization to be passed on to lower level + modules (as defined in the Configuration and + modules.c file if there is no userID + or rule matching the supplied userID. If there is + a userID and/or rule specified; the usual password and access + checks will be applied and a failure will give an Authorization + Required reply.

+ +

So if a userID appears in the database of more than one module; + or if a valid Require + directive applies to more than one module; then the first module + will verify the credentials; and no access is passed on; + regardless of the AuthAuthoritative setting.

+ +

A common use for this is in conjunction with one of the + basic auth modules; such as mod_auth. Whereas this + DBM module supplies the bulk of the user credential checking; a + few (administrator) related accesses fall through to a lower + level with a well protected .htpasswd file.

+ +

By default, control is not passed on and an unknown userID + or rule will result in an Authorization Required reply. Not + setting it thus keeps the system secure and forces an NCSA + compliant behaviour.

+ +

Security: Do consider the implications of allowing a user to + allow fall-through in his .htaccess file; and verify that this + is really what you want; Generally it is easier to just secure + a single .htpasswd file, than it is to secure a database which + might have more access interfaces.

+

AuthDBMGroupFile Directive

Description: Sets the name of the database file containing the list +of user groups for authentication
Syntax:AuthDBMGroupFile file-path
Context:directory, .htaccess
Override:AuthConfig
Status:Extension
Module:mod_auth_dbm
+

The AuthDBMGroupFile directive sets the + name of a DBM file containing the list of user groups for user + authentication. File-path is the absolute path to the + group file.

+ +

The group file is keyed on the username. The value for a + user is a comma-separated list of the groups to which the users + belongs. There must be no whitespace within the value, and it + must never contain any colons.

+ +

Security: make sure that the + AuthDBMGroupFile is stored outside the + document tree of the web-server; do not put it in the + directory that it protects. Otherwise, clients will be able to + download the AuthDBMGroupFile unless + otherwise protected.

+ +

Combining Group and Password DBM files: In some cases it is + easier to manage a single database which contains both the + password and group details for each user. This simplifies any + support programs that need to be written: they now only have to + deal with writing to and locking a single DBM file. This can be + accomplished by first setting the group and password files to + point to the same DBM:

+ +
+AuthDBMGroupFile /www/userbase
+AuthDBMUserFile /www/userbase +
+ +

The key for the single DBM is the username. The value consists + of

+ +
Unix Crypt-ed Password : List of Groups [ : (ignored) + ]
+ +

The password section contains the Unix crypt() + password as before. This is followed by a colon and the comma + separated list of groups. Other data may optionally be left in the + DBM file after another colon; it is ignored by the authentication + module. This is what www.telescope.org uses for its combined + password and group database.

+

AuthDBMType Directive

Description: Sets the type of database file that is used to +store passwords
Syntax:AuthDBMType default|SDBM|GDBM|DB
Default:AuthDBMType default
Context:directory, .htaccess
Override:AuthConfig
Status:Extension
Module:mod_auth_dbm
Compatibility:Available in version 2.0.30 and later.
+ +

Sets the type of database file that is used to store the passwords. +The default database type is determined at compile time. The +availability of other types of database files also depends on +compile-time settings.

+ +

It is crucial that whatever program you use to create your password +files is configured to use the same type of database.

+

AuthDBMUserFile Directive

Description: Sets thename of a database file containing the list of users and +passwords for authentication
Syntax:AuthDBMUserFile file-path
Context:directory, .htaccess
Override:AuthConfig
Status:Extension
Module:mod_auth_dbm
+

The AuthDBMUserFile directive sets the + name of a DBM file containing the list of users and passwords for + user authentication. File-path is the absolute path to + the user file.

+ +

The user file is keyed on the username. The value for a user is + the crypt() encrypted password, optionally followed + by a colon and arbitrary data. The colon and the data following it + will be ignored by the server.

+ +

Security: make sure that the + AuthDBMUserFile is stored outside the + document tree of the web-server; do not put it in the + directory that it protects. Otherwise, clients will be able to + download the AuthDBMUserFile.

+ +

Important compatibility note: The implementation of + "dbmopen" in the apache modules reads the string length of the + hashed values from the DBM data structures, rather than relying + upon the string being NULL-appended. Some applications, such as + the Netscape web server, rely upon the string being + NULL-appended, so if you are having trouble using DBM files + interchangeably between applications this may be a part of the + problem.

+ +

A perl script called + dbmmanage is included with + Apache. This program can be used to create and update DBM + format password files for use with this module.

+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_auth_digest.html.en b/docs/manual/mod/mod_auth_digest.html.en new file mode 100644 index 0000000000..af8cae4bd9 --- /dev/null +++ b/docs/manual/mod/mod_auth_digest.html.en @@ -0,0 +1,134 @@ +mod_auth_digest- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_auth_digest

Description:User authentication using MD5 + Digest Authentication.
Status:Experimental
Module Identifier:auth_digest_module

Summary

+

This module implements HTTP Digest Authentication. However, it + has not been extensively tested and is therefore marked + experimental.

+

Directives

See also

Using Digest Authentication

+ +

Using MD5 Digest authentication is very simple. Simply set + up authentication normally, using "AuthType Digest" and + "AuthDigestFile" instead of the normal "AuthType Basic" and + "AuthUserFile"; also, replace any "AuthGroupFile" with + "AuthDigestGroupFile". Then add a "AuthDigestDomain" directive + containing at least the root URI(s) for this protection space. + Example:

+
+ <Location /private/>
+ AuthType Digest
+ AuthName "private area"
+ AuthDigestDomain /private/ http://mirror.my.dom/private2/
+ AuthDigestFile /web/auth/.digest_pw
+ Require valid-user
+ </Location> +
+ +

Note

+

MD5 authentication provides a more + secure password system than Basic authentication, but only + works with supporting browsers. As of this writing (October 2001), + the only major browsers which support digest authentication are + Opera 4.0, + MS Internet + Explorer 5.0 and Amaya. + Therefore, we do not yet recommend using this feature on a large + Internet site. However, for personal and intra-net use, where + browser users can be controlled, it is ideal.

+
+

AuthDigestAlgorithm Directive

Description: Selects the algorithm used to calculate the challenge and +response hases in digest authentication
Syntax:AuthDigestAlgorithm MD5|MD5-sess
Default:AuthDigestAlgorithm MD5
Context:directory, .htaccess
Override:AuthConfig
Status:Experimental
Module:mod_auth_digest
+

The AuthDigestAlgorithm directive + selects the algorithm used to calculate the challenge and response + hashes.

+ +

MD5-sess is not correctly implemented + yet. +

+

AuthDigestDomain Directive

Description: URIs that are in the same protection space for digest +authentication
Syntax:AuthDigestDomain URI [URI] ...
Context:directory, .htaccess
Override:AuthConfig
Status:Experimental
Module:mod_auth_digest
+

The AuthDigestDomain directive allows + you to specify one or more URIs which are in the same protection + space (i.e. use the same realm and username/password info). The + specified URIs are prefixes, i.e. the client will assume that all + URIs "below" these are also protected by the same + username/password. The URIs may be either absolute URIs + (i.e. inluding a scheme, host, port, etc) or relative URIs.

+ +

This directive should always be specified and + contain at least the (set of) root URI(s) for this space. + Omitting to do so will cause the client to send the + Authorization header for every request sent to this + server. Apart from increasing the size of the request, it may + also have a detrimental effect on performance if + "AuthDigestNcCheck" is on.

+ +

The URIs specified can also point to different servers, in + which case clients (which understand this) will then share + username/password info across multiple servers without + prompting the user each time.

+

AuthDigestFile Directive

Description: Location of the text file containing the list +of users and encoded passwords for digest authentication
Syntax:AuthDigestFile file-path
Context:directory, .htaccess
Override:AuthConfig
Status:Experimental
Module:mod_auth_digest
+

The AuthDigestFile directive sets the + name of a textual file containing the list of users and encoded + passwords for digest authentication. File-path is the + absolute path to the user file.

+ +

The digest file uses a special format. Files in this format + can be created using the htdigest utility found in + the support/ subdirectory of the Apache distribution.

+

AuthDigestGroupFile Directive

Description: Name of the text file containing the list of groups +for digest authentication
Syntax:AuthDigestGroupFile file-path
Context:directory, .htaccess
Override:AuthConfig
Status:Experimental
Module:mod_auth_digest
+

The AuthDigestGroupFile directive sets + the name of a textual file containing the list of groups and their + members (user names). File-path is the absolute path to + the group file.

+ +

Each line of the group file contains a groupname followed by + a colon, followed by the member usernames separated by spaces. + Example:

+ +
mygroup: bob joe anne
+ +

Note that searching large text files is very + inefficient.

+ +

Security: make sure that the AuthGroupFile is stored outside + the document tree of the web-server; do not put it in + the directory that it protects. Otherwise, clients will be able + to download the AuthGroupFile.

+

AuthDigestNcCheck Directive

Description: Enables or disables checking of the nonce-count sent by the +server
Syntax:AuthDigestNcCheck On|Off
Default:AuthDigestNcCheck Off
Context:server config
Status:Experimental
Module:mod_auth_digest
+

Not implemented yet. +

+

AuthDigestNonceFormat Directive

Description: Determines how the nonce is generated
Syntax:???
Default:???
Context:directory, .htaccess
Override:AuthConfig
Status:Experimental
Module:mod_auth_digest
+

Not implemented yet. +

+

AuthDigestNonceLifetime Directive

Description: How long the server nonce is valid
Syntax:AuthDigestNonceLifetime seconds
Default:AuthDigestNonceLifetime 300
Context:directory, .htaccess
Override:AuthConfig
Status:Experimental
Module:mod_auth_digest
+

The AuthDigestNonceLifetime directive + controls how long the server nonce is valid. When the client + contacts the server using an expired nonce the server will send + back a 401 with stale=true. If seconds is + greater than 0 then it specifies the amount of time for which the + nonce is valid; this should probably never be set to less than 10 + seconds. If seconds is less than 0 then the nonce never + expires. +

+

AuthDigestQop Directive

Description: Determines the quality-of-protection to use in digest +authentication
Syntax:AuthDigestQop none|auth|auth-int [auth|auth-int]
Default:AuthDigestQop auth
Context:directory, .htaccess
Override:AuthConfig
Status:Experimental
Module:mod_auth_digest
+

The AuthDigestQop directive determines + the quality-of-protection to use. auth will only do + authentication (username/password); auth-int is + authentication plus integrity checking (an MD5 hash of the entity + is also computed and checked); none will cause the module + to use the old RFC-2069 digest algorithm (which does not include + integrity checking). Both auth and auth-int may + be specified, in which the case the browser will choose which of + these to use. none should only be used if the browser for + some reason does not like the challenge it receives otherwise.

+ +

auth-int is not implemented + yet.

+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_autoindex.html.en b/docs/manual/mod/mod_autoindex.html.en new file mode 100644 index 0000000000..3408ee7f58 --- /dev/null +++ b/docs/manual/mod/mod_autoindex.html.en @@ -0,0 +1,633 @@ +mod_autoindex- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_autoindex

Description:Generates directory indexes, + automatically, similar to the Unix ls command or the + Win32 dir shell command
Status:Base
Module Identifier:autoindex_module

Summary

+

The index of a directory can come from one of two + sources:

+ + +

The two functions are separated so that you can completely + remove (or replace) automatic index generation should you want + to.

+ +

Automatic index generation is enabled with using + Options +Indexes. See the + Options directive for + more details.

+ +

If the FancyIndexing + option is given with the IndexOptions directive, + the column headers are links that control the order of the + display. If you select a header link, the listing will be + regenerated, sorted by the values in that column. Selecting the + same header repeatedly toggles between ascending and descending + order. These column header links are suppressed with + IndexOptions directive's + SuppressColumnSorting option.

+ +

Note that when the display is sorted by "Size", it's the + actual size of the files that's used, not the + displayed value - so a 1010-byte file will always be displayed + before a 1011-byte file (if in ascending order) even though + they both are shown as "1K".

+

Directives

Autoindex Request Query Arguments

+ +

Apache 2.0.23 reorganized the Query Arguments for Column + Sorting, and introduced an entire group of new query options. + To effectively eliminate all client control over the output, + the IndexOptions + IgnoreClient option was introduced.

+ +

The column sorting headers themselves are self-referencing + hyperlinks that add the sort query options shown below. Any + option below may be added to any request for the directory + resource.

+ + + +

Note that the 'P'attern query argument is tested + after the usual IndexIgnore directives are processed, + and all file names are still subjected to the same criteria as + any other autoindex listing. The Query Arguments parser in + mod_autoindex will stop abruptly when an unrecognized option is + encountered. The Query Arguments must be well formed, according + to the table above.

+ +

The simple example below, which can be clipped and saved in + a header.html file, illustrates these query options. Note that + the unknown "X" argument, for the submit button, is listed last + to assure the arguments are all parsed before mod_autoindex + encounters the X=Go input.

+ +
+<FORM METHOD="GET">
+  Show me a <SELECT NAME="F">
+    <OPTION VALUE="0"> Plain list
+    <OPTION VALUE="1" SELECTED> Fancy list
+    <OPTION VALUE="2"> Table list
+  </SELECT>
+  Sorted by <SELECT NAME="C">
+    <OPTION VALUE="N" SELECTED> Name
+    <OPTION VALUE="M"> Date Modified
+    <OPTION VALUE="S"> Size
+    <OPTION VALUE="D"> Description
+  </SELECT>
+  <SELECT NAME="O">
+    <OPTION VALUE="A" SELECTED> Ascending
+    <OPTION VALUE="D"> Descending
+  </SELECT>
+  <SELECT NAME="V">
+    <OPTION VALUE="0" SELECTED> in Normal order
+    <OPTION VALUE="1"> in Version order
+  </SELECT>
+  Matching <INPUT TYPE="text" NAME="P" VALUE="*">
+  <INPUT TYPE="submit" NAME="X" VALUE="Go">
+</FORM> +
+ +

AddAlt Directive

Description: Alternate text to display for a file, instead of an +icon selected by filename
Syntax:AddAlt string file [file] ...
Context:server config, virtual host, directory, .htaccess
Override:Indexes
Status:Base
Module:mod_autoindex
+

AddAlt provides the alternate text to + display for a file, instead of an icon, for FancyIndexing. + File is a file extension, partial filename, wild-card + expression or full filename for files to describe. + String is enclosed in double quotes ("). + This alternate text is displayed if the client is image-incapable, + has image loading disabled, or fails to retrieve the icon.

+ +

Examples:

+
+ AddAlt "PDF" *.pdf
+ AddAlt "Compressed" *.gz *.zip *.Z +
+

AddAltByEncoding Directive

Description: Alternate text to display for a file instead of an icon +selected by MIME-encoding
Syntax:AddAltByEncoding string MIME-encoding +[MIME-encoding] ...
Context:server config, virtual host, directory, .htaccess
Override:Indexes
Status:Base
Module:mod_autoindex
+

AddAltByEncoding provides the alternate + text to display for a file, instead of an icon, for FancyIndexing. + MIME-encoding is a valid content-encoding, such as + x-compress. String is enclosed in double + quotes ("). This alternate text is displayed if the + client is image-incapable, has image loading disabled, or fails to + retrieve the icon.

+ +

Example:

+
+ AddAltByEncoding "gzip" x-gzip +
+

AddAltByType Directive

Description: Alternate text to display for a file, instead of an +icon selected by MIME content-type
Syntax:AddAltByType string + MIME-type [MIME-type] ...
Context:server config, virtual host, directory, .htaccess
Override:Indexes
Status:Base
Module:mod_autoindex
+

AddAltByType sets the alternate text to + display for a file, instead of an icon, for FancyIndexing. + MIME-type is a valid content-type, such as + text/html. String is enclosed in double + quotes ("). This alternate text is displayed if the + client is image-incapable, has image loading disabled, or fails to + retrieve the icon.

+ +

Example:

+
+ AddAltByType "TXT" text/plain +
+

AddDescription Directive

Description:
Syntax:AddDescription + string file [file] ...
Context:server config, virtual host, directory, .htaccess
Override:Indexes
Status:Base
Module:mod_autoindex
+

This sets the description to display for a file, for + FancyIndexing. + File is a file extension, partial filename, wild-card + expression or full filename for files to describe. + String is enclosed in double quotes ("). + Example:

+ +
AddDescription "The planet Mars" + /web/pics/mars.gif
+ +

The typical, default description field is 23 bytes wide. 6 + more bytes are added by the + IndexOptions SuppressIcon option, 7 bytes are + added by the IndexOptions SuppressSize + option, and 19 bytes are added by the + IndexOptions SuppressLastModified option. + Therefore, the widest default the description column is ever + assigned is 55 bytes.

+ +

See the DescriptionWidth + IndexOptions keyword + for details on overriding the size of this column, or allowing + descriptions of unlimited length.

+ +

Caution

Descriptive text defined with + AddDescription may contain HTML markup, such as + tags and character entities. If the width of the description + column should happen to truncate a tagged element (such as + cutting off the end of a bolded phrase), the results may + affect the rest of the directory listing.

+
+

AddIcon Directive

Description: Icon to display for a file selected by name
Syntax:AddIcon icon + name [name] ...
Context:server config, virtual host, directory, .htaccess
Override:Indexes
Status:Base
Module:mod_autoindex
+

This sets the icon to display next to a file ending in + name for FancyIndexing. + Icon is either a (%-escaped) relative URL to the icon, + or of the format (alttext,url) where + alttext is the text tag given for an icon for + non-graphical browsers.

+ +

Name is either ^^DIRECTORY^^ for directories, + ^^BLANKICON^^ for blank lines (to format the list correctly), a + file extension, a wildcard expression, a partial filename or a + complete filename. Examples:

+ +
+ AddIcon (IMG,/icons/image.xbm) .gif .jpg .xbm
+ AddIcon /icons/dir.xbm ^^DIRECTORY^^
+ AddIcon /icons/backup.xbm *~ +
+ +

AddIconByType + should be used in preference to AddIcon, + when possible.

+

AddIconByEncoding Directive

Description: Icon to display next to files selected by MIME +content-encoding
Syntax:AddIconByEncoding + icon MIME-encoding [MIME-encoding] ...
Context:server config, virtual host, directory, .htaccess
Override:Indexes
Status:Base
Module:mod_autoindex
+

This sets the icon to display next to files with FancyIndexing. + Icon is either a (%-escaped) relative URL to the icon, + or of the format (alttext,url) where + alttext is the text tag given for an icon for + non-graphical browsers.

+ +

Mime-encoding is a wildcard expression matching + required the content-encoding. Examples:

+ +
AddIconByEncoding /icons/compress.xbm x-compress
+

AddIconByType Directive

Description: Icon to display next to files selected by MIME +content-type
Syntax:AddIconByType + icon MIME-type [MIME-type] ...
Context:server config, virtual host, directory, .htaccess
Override:Indexes
Status:Base
Module:mod_autoindex
+

This sets the icon to display next to files of type + MIME-type for FancyIndexing. + Icon is either a (%-escaped) relative URL to the icon, + or of the format (alttext,url) where + alttext is the text tag given for an icon for + non-graphical browsers.

+ +

Mime-type is a wildcard expression matching + required the mime types. Examples:

+ +
AddIconByType (IMG,/icons/image.xbm) image/*
+

DefaultIcon Directive

Description: Icon to display for files when no specific icon is +configured
Syntax:DefaultIcon url-path
Context:server config, virtual host, directory, .htaccess
Override:Indexes
Status:Base
Module:mod_autoindex
+

The DefaultIcon directive sets the icon + to display for files when no specific icon is known, for FancyIndexing. + Url is a (%-escaped) relative URL to the icon. + Examples:

+
DefaultIcon /icon/unknown.xbm
+

HeaderName Directive

Description: Name of the file that will be inserted at the top +of the index listing
Syntax:HeaderName filename
Context:server config, virtual host, directory, .htaccess
Override:Indexes
Status:Base
Module:mod_autoindex
+

The HeaderName directive sets the name + of the file that will be inserted at the top of the index + listing. Filename is the name of the file to include.

+ +
+

Both HeaderName and ReadmeName now treat + Filename as a URI path relative to the one used to + access the directory being indexed. Filename must + resolve to a document with a major content type of + "text/*" (e.g., text/html, + text/plain, etc.). This means that + filename may refer to a CGI script if the script's + actual file type (as opposed to its output) is marked as + text/html such as with a directive like:

+
+ AddType text/html .cgi +
+

Content negotiation + will be performed if the MultiViews Option is enabled. If + filename resolves to a static text/html + document (not a CGI script) and the Includes + option is enabled, the file + will be processed for server-side includes (see the + mod_include documentation).

+
+ +

If the file specified by HeaderName contains + the beginnings of an HTML document (<HTML>, <HEAD>, + etc) then you will probably want to set IndexOptions + +SuppressHTMLPreamble, so that these tags are not + repeated.

+

IndexIgnore Directive

Description: Adds to the list of files to hide when listing +a directory
Syntax:IndexIgnore file [file] ...
Context:server config, virtual host, directory, .htaccess
Override:Indexes
Status:Base
Module:mod_autoindex
+

The IndexIgnore directive adds to the + list of files to hide when listing a directory. File is a + file extension, partial filename, wildcard expression or full + filename for files to ignore. Multiple IndexIgnore directives add + to the list, rather than the replacing the list of ignored + files. By default, the list contains + `.'. Example:

+ +
IndexIgnore README .htaccess *~
+

IndexOptions Directive

Description: Various configuration settings for directory +indexing
Syntax:IndexOptions [+|-]option [[+|-]option] ...
Context:server config, virtual host, directory, .htaccess
Override:Indexes
Status:Base
Module:mod_autoindex
+

The IndexOptions directive specifies the + behavior of the directory indexing. Option can be one + of

+ +
+
DescriptionWidth=[n + | *] (Apache 1.3.10 or 2.0.23 and later)
+ +
The DescriptionWidth keyword allows you to + specify the width of the description column in + characters.
+ +
-DescriptionWidth (or unset) allows + mod_autoindex to calculate the best width.
+ +
DescriptionWidth=n fixes the column width to + n bytes wide.
+ +
DescriptionWidth=* grows the column to the + width necessary to accommodate the longest description + string.
+ +
See the section on AddDescription for dangers + inherent in truncating descriptions.
+ +
FancyIndexing
+ +
+ This turns on fancy indexing of directories.
+ +
FoldersFirst (Apache + 1.3.10 or 2.0.23 and later)
+ +
If this option is enabled, subdirectory listings will + always appear first, followed by normal files in the + directory. The listing is basically broken into two + components, the files and the subdirectories, and each is + sorted separately and then displayed subdirectories-first. + For instance, if the sort order is descending by name, and + FoldersFirst is enabled, subdirectory + Zed will be listed before subdirectory + Beta, which will be listed before normal files + Gamma and Alpha. This option + only has an effect if FancyIndexing + is also enabled.
+ +
HTMLTable (Experimental, + Apache 2.0.23 and later)
+ +
+ This experimental option with FancyIndexing constructs a + simple table for the fancy directory listing. Note this will + confuse older browsers. It is particularly necessary if file + names or description text will alternate between + left-to-right and right-to-left reading order, as can happen + on WinNT or other utf-8 enabled platforms.
+ +
IconsAreLinks
+ +
+ This makes the icons part of the anchor for the filename, for + fancy indexing.
+ +
IconHeight[=pixels] + (Apache 1.3 and later)
+ +
+ Presence of this option, when used with IconWidth, will cause + the server to include HEIGHT and + WIDTH attributes in the IMG tag for + the file icon. This allows browser to precalculate the page + layout without having to wait until all the images have been + loaded. If no value is given for the option, it defaults to + the standard height of the icons supplied with the Apache + software.
+ +
IconWidth[=pixels] (Apache + 1.3 and later)
+ +
+ Presence of this option, when used with IconHeight, will + cause the server to include HEIGHT and + WIDTH attributes in the IMG tag for + the file icon. This allows browser to precalculate the page + layout without having to wait until all the images have been + loaded. If no value is given for the option, it defaults to + the standard width of the icons supplied with the Apache + software.
+ +
IgnoreClient
+ +
+ This option causes mod_autoindex to ignore all query + variables from the client, including sort order (implies + SuppressColumnSorting.)
+ +
NameWidth=[n | *] + (Apache 1.3.2 and later)
+ +
The NameWidth keyword allows you to specify the width of + the filename column in bytes.
+ +
-NameWidth (or unset) allows mod_autoindex + to calculate the best width.
+ +
NameWidth=n fixes the column width to n + bytes wide.
+ +
NameWidth=* grows the column to the + necessary width.
+ +
ScanHTMLTitles
+ +
+ This enables the extraction of the title from HTML documents + for fancy indexing. If the file does not have a description + given by AddDescription then + httpd will read the document for the value of the TITLE tag. + This is CPU and disk intensive.
+ +
SuppressColumnSorting + (Apache 1.3 and later)
+ +
+ If specified, Apache will not make the column headings in a + FancyIndexed directory listing into links for sorting. The + default behavior is for them to be links; selecting the + column heading will sort the directory listing by the values + in that column. Prior to Apache 2.0.23, this also + disabled parsing the Query Arguments for the sort + string. That behavior is now controlled by IndexOptions + IgnoreClient in Apache 2.0.23.
+ +
SuppressDescription
+ +
+ This will suppress the file description in fancy indexing + listings. By default, no file descriptions are defined, and + so the use of this option will regain 23 characters of screen + space to use for something else. See AddDescription for + information about setting the file description. See also the + DescriptionWidth + index option to limit the size of the description + column.
+ +
SuppressHTMLPreamble + (Apache 1.3 and later)
+ +
+ If the directory actually contains a file specified by the + HeaderName + directive, the module usually includes the contents of the file + after a standard HTML preamble (<HTML>, <HEAD>, + et cetera). The SuppressHTMLPreamble option disables + this behaviour, causing the module to start the display with the + header file contents. The header file must contain appropriate + HTML instructions in this case. If there is no header file, the + preamble is generated as usual.
+ +
SuppressIcon (Apache + 2.0.23 and later)
+ +
+ This will suppress the icon in fancy indexing listings. + Combining both SuppressIcon and + SuppressRules yields proper HTML 3.2 output, which + by the final specification prohibits IMG and HR tags from the + PRE block (used to format FancyIndexed listings.)
+ +
SuppressLastModified
+ +
+ This will suppress the display of the last modification date, + in fancy indexing listings.
+ +
SuppressRules + (Apache 2.0.23 and later)
+ +
+ This will suppress the horizontal rule lines (HR tags) in + directory listings. Combining both SuppressIcon and + SuppressRules yeilds proper HTML 3.2 output, which + by the final specification prohibits IMG and HR tags from the + PRE block (used to format FancyIndexed listings.)
+ +
SuppressSize
+ +
+ This will suppress the file size in fancy indexing + listings.
+ +
TrackModified (Apache + 1.3.15 or 2.0.23 and later)
+ +
+ This returns the Last-Modified and ETag values for the listed + directory in the HTTP header. It is only valid if the + operating system and file system return appropriate stat() + results. Some Unix systems do so, as do OS2's JFS and Win32's + NTFS volumes. OS2 and Win32 FAT volumes, for example, do not. + Once this feature is enabled, the client or proxy can track + changes to the list of files when they perform a HEAD + request. Note some operating systems correctly track new and + removed files, but do not track changes for sizes or dates of + the files within the directory. Changes to the size + or date stamp of an existing file will not update the + Last-Modified header on all Unix platforms. If this + is a concern, leave this option disabled.
+ +
VersionSort (Apache 2.0a3 + and later)
+ +
+ The VersionSort keyword causes files containing version + numbers to sort in a natural way. Strings are sorted as + usual, except that substrings of digits in the name and + description are compared according to their numeric value. + For example: + +
+foo-1.7
+foo-1.7.2
+foo-1.7.12
+foo-1.8.2
+foo-1.8.2a
+foo-1.12
+
+ If the number starts with a zero, then it is considered to + be a fraction: + +
+foo-1.001
+foo-1.002
+foo-1.030
+foo-1.04 +
+
+ +
+ Incremental IndexOptions +
+ +
+ Apache 1.3.3 introduced some significant changes in the + handling of IndexOptions directives. In + particular,
+
+ + +
    +
  • Multiple IndexOptions directives for a + single directory are now merged together. The result of + the example above will now be the equivalent of + IndexOptions FancyIndexing ScanHTMLTitles.
    • + +
  • The addition of the incremental syntax + (i.e., prefixing keywords with '+' or '-').
    • +
+
+ Whenever a '+' or '-' prefixed keyword is encountered, it + is applied to the current IndexOptions + settings (which may have been inherited from an upper-level + directory). However, whenever an unprefixed keyword is + processed, it clears all inherited options and any + incremental settings encountered so far. Consider the + following example: + +
IndexOptions +ScanHTMLTitles -IconsAreLinks + FancyIndexing
+ IndexOptions +SuppressSize
+
+ The net effect is equivalent to + IndexOptions FancyIndexing +SuppressSize, + because the unprefixed FancyIndexing discarded + the incremental keywords before it, but allowed them to + start accumulating again afterward.
+
+ To unconditionally set the IndexOptions for a + particular directory, clearing the inherited settings, + specify keywords without any '+' or '-' prefixes. +
+
+

IndexOrderDefault Directive

Description: Sets the default ordering of the directory index
Syntax:IndexOrderDefault +Ascending|Descending Name|Date|Size|Description
Context:server config, virtual host, directory, .htaccess
Override:Indexes
Status:Base
Module:mod_autoindex
+

The IndexOrderDefault directive is used + in combination with the FancyIndexing + index option. By default, fancyindexed directory listings are + displayed in ascending order by filename; the + IndexOrderDefault allows you to change this initial + display order.

+ +

IndexOrderDefault takes two + arguments. The first must be either Ascending or + Descending, indicating the direction of the sort. + The second argument must be one of the keywords Name, + Date, Size, or Description, + and identifies the primary key. The secondary key is + always the ascending filename.

+ +

You can force a directory listing to only be displayed in a + particular order by combining this directive with the SuppressColumnSorting + index option; this will prevent the client from requesting the + directory listing in a different order.

+

ReadmeName Directive

Description:
Syntax:ReadmeName filename
Context:server config, virtual host, directory, .htaccess
Override:Indexes
Status:Base
Module:mod_autoindex
+

The ReadmeName directive sets the name + of the file that will be appended to the end of the index + listing. Filename is the name of the file to include, and + is taken to be relative to the location being indexed.

+ +

See also HeaderName, where this behavior + is described in greater detail.

+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_cache.html.en b/docs/manual/mod/mod_cache.html.en new file mode 100644 index 0000000000..7e620e30ae --- /dev/null +++ b/docs/manual/mod/mod_cache.html.en @@ -0,0 +1,117 @@ +mod_cache- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_cache

Description:Content cache keyed to URIs
Status:Experimental
Module Identifier:cache_module

Summary

+ +
+This module is experimental. Documentation is still under development... +
+

mod_cache implements an RFC 2616 compliant HTTP content + cache that can be used to cache either local or proxied content. + mod_cache requires the services of one or more storage + management modules. Two storage management modules are included in + the base Apache distribution:

+
+
mod_disk_cache
+
implements a disk based storage manager for use with mod_proxy
+
mod_mem_cache
+
implements an in-memory based storage manager. mod_mem_cache + can be configured to operate in two modes: caching open file + descriptors or caching objects in heap storage. mod_mem_cache + is most useful when used to cache locally generated content or to cache + backend server content for mod_proxy configured for ProxyPass (aka reverse proxy)
+
+

Content stored and retrived keyed to the URL. Content with + access protections is not cached.

+

Directives

Sample Configuration

+ +

Sample httpd.conf

+ +#
+# Sample Cache Configuration
+#
+LoadModule cache_module modules/mod_cache.so
+<IfModule mod_cache.c>
+ CacheOn On
+

+ #LoadModule disk_cache_module modules/mod_disk_cache.so
+ <IfModule mod_disk_cache.c>
+ CacheRoot c:/cacheroot
+ CacheSize + CacheEnable disk /
+ CacheDirLevels 5
+ CacheDirLength 3
+ </IfModule>
+

+ LoadModule mem_cache_module modules/mod_mem_cache.so
+ <IfModule mod_mem_cache.c>
+ MCacheEnable mem /
+ MCacheSize 4096
+ MCacheMaxObjectCount 100
+ MCacheMinObjectSize 1
+ MCacheMaxObjectSize 2048
+ </IfModule>
+

+</IfModule>
+ +
+ +

CacheDefaultExpire Directive

Description:
Syntax:
Context:server config
Status:Experimental
Module:mod_cache
+

The default time in seconds to cache a document.

+
+ CacheDefaultExpire 86400 +
+

CacheDisable Directive

Description: Disable caching of specified URLs by specified storage manager
Syntax:CacheDisable cache_type url-string
Context:server config
Status:Experimental
Module:mod_cache
+

The CacheDisable directive instructs + mod_cache to not cache urls at or above url-string.

+ +

Example

+ CacheDisable disk /local_files +
+

CacheEnable Directive

Description: Enable caching specified URLs in a specified storage manager
Syntax:CacheEnable cache_type url-string
Context:server config
Status:Experimental
Module:mod_cache
+

The CacheEnable directive instructs + mod_cache to cache urls at or below url-string. + The cache store is specified with the cache_type argument. + cache_type mem instructs mod_cache to use the + in-memory cache storage manager implemented by mod_mem_cache. + cache_type disk instructs mod_cache to use the + cache storage manager implemented by mod_disk_cache .

+ +
+ CacheEnable disk /
+ CacheEnable mem /manual
+ CacheEnable fd /images
+
+

CacheIgnoreCacheControl Directive

Description: Ignore requests from the client for uncached content
Syntax:
Context:server config
Status:Experimental
Module:mod_cache
+

Ignore requests from the client for uncached content

+ +
+ CacheIgnoreNoLastMod +
+

CacheIgnoreNoLastMod Directive

Description: Ignore responses where there is no Last Modified Header
Syntax:
Context:server config
Status:Experimental
Module:mod_cache
+

Ignore responses where there is no Last Modified Header

+ +
+ CacheIgnoreNoLastMod +
+

CacheLastModifiedFactor Directive

Description: The factor used to estimate the Expires date from the LastModified date
Syntax:
Context:server config
Status:Experimental
Module:mod_cache
+

The factor used to estimate the Expires date from the LastModified date.

+ +
+ CacheLastModifiedFactor +
+

CacheMaxExpire Directive

Description: The maximum time in seconds to cache a document
Syntax:
Context:server config
Status:Experimental
Module:mod_cache
+

The maximum time in seconds to cache a document.

+
+ CacheMaxExpire 604800 +
+

CacheOn Directive

Description:
Syntax:CacheOn
Context:server config
Status:Experimental
Module:mod_cache
+

+

+ + +
+ CacheOn +
+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_cern_meta.html.en b/docs/manual/mod/mod_cern_meta.html.en new file mode 100644 index 0000000000..38edc4a0d0 --- /dev/null +++ b/docs/manual/mod/mod_cern_meta.html.en @@ -0,0 +1,36 @@ +mod_cern_meta- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_cern_meta

Description:CERN httpd metafile semantics
Status:Extension
Module Identifier:cern_meta_module

Summary

+ +

Emulate the CERN HTTPD Meta file semantics. Meta files are HTTP + headers that can be output in addition to the normal range of + headers for each file accessed. They appear rather like the + Apache .asis files, and are able to provide a crude way of + influencing the Expires: header, as well as providing other + curiosities. There are many ways to manage meta information, + this one was chosen because there is already a large number of + CERN users who can exploit this module.

+ +

More information on the + CERN metafile semantics is available.

+

Directives

MetaDir Directive

Description: Name of the directory to find CERN-style meta information +files
Syntax:MetaDir directory
Default:MetaDir .web
Context:directory
Status:Extension
Module:mod_cern_meta
+

Specifies the name of the directory in which Apache can find + meta information files. The directory is usually a 'hidden' + subdirectory of the directory that contains the file being + accessed. Set to "." to look in the same directory + as the file.

+

MetaFiles Directive

Description: Activates CERN meta-file processing
Syntax:MetaFiles on|off
Default:MetaFiles off
Context:directory
Status:Extension
Module:mod_cern_meta
+

Turns on/off Meta file processing on a per-directory basis.

+

MetaSuffix Directive

Description: File name suffix for the file containg CERN-style +meta information
Syntax:MetaSuffix suffix
Default:MetaSuffix .meta
Context:directory
Status:Extension
Module:mod_cern_meta
+

Specifies the file name suffix for the file containing the + meta information. For example, the default values for the two + directives will cause a request to + DOCUMENT_ROOT/somedir/index.html to look in + DOCUMENT_ROOT/somedir/.web/index.html.meta and + will use its contents to generate additional MIME header + information.

+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_cgi.html.en b/docs/manual/mod/mod_cgi.html.en new file mode 100644 index 0000000000..92177b87b9 --- /dev/null +++ b/docs/manual/mod/mod_cgi.html.en @@ -0,0 +1,146 @@ +mod_cgi- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_cgi

Description:Execution of CGI scripts
Status:Base
Module Identifier:cgi_module

Summary

+ + + + +

Any file that has the mime type + application/x-httpd-cgi or handler + cgi-script (Apache 1.1 or later) will be treated + as a CGI script, and run by the server, with its output being + returned to the client. Files acquire this type either by + having a name containing an extension defined by the + AddType directive, or by being + in a ScriptAlias + directory.

+ +

When the server invokes a CGI script, it will add a variable + called DOCUMENT_ROOT to the environment. This + variable will contain the value of the + DocumentRoot configuration + variable.

+ +

For an introduction to using CGI scripts with Apache, see + our tutorial on Dynamic Content + With CGI.

+ +

When using a multi-threaded MPM under unix, the module + mod_cgid should be used in place of + this module. At the user level, the two modules are essentially + identical.

+

Directives

See also

CGI Environment variables

+

The server will set the CGI environment variables as described + in the CGI + specification, with the following provisions:

+ +
+
PATH_INFO
+ +
This will not be available if the AcceptPathInfo directive is explicitly set to + off. The default behavior, if AcceptPathInfo is + not given, is that mod_cgi will accept path info (trailing + /more/path/info following the script filename in the URI), while + the core server will return a 404 NOT FOUND error for requests + with additional path info. Omitting the AcceptPathInfo + directive has the same effect as setting it on for + mod_cgi requests.
+ +
REMOTE_HOST
+ +
This will only be set if HostnameLookups is set to on (it + is off by default), and if a reverse DNS lookup of the accessing + host's address indeed finds a host name.
+ +
REMOTE_IDENT
+ +
This will only be set if IdentityCheck is set to + on and the accessing host supports the ident + protocol. Note that the contents of this variable cannot be + relied upon because it can easily be faked, and if there is a + proxy between the client and the server, it is usually + totally useless.
+ +
REMOTE_USER
+ +
This will only be set if the CGI script is subject to + authentication.
+
+

CGI Debugging

+

Debugging CGI scripts has traditionally been difficult, mainly + because it has not been possible to study the output (standard + output and error) for scripts which are failing to run + properly. These directives, included in Apache 1.2 and later, + provide more detailed logging of errors when they occur.

+ +

CGI Logfile Format

+

When configured, the CGI error log logs any CGI which does not + execute properly. Each CGI script which fails to operate causes + several lines of information to be logged. The first two lines + are always of the format:

+
+ %% [time] request-line
+ %% HTTP-status CGI-script-filename +
+

If the error is that CGI script cannot be run, the log file + will contain an extra two lines:

+
+ %%error
+ error-message +
+

Alternatively, if the error is the result of the script + returning incorrect header information (often due to a bug in + the script), the following information is logged:

+
+ %request
+ All HTTP request headers received
+ POST or PUT entity (if any)
+ %response
+ All headers output by the CGI script
+ %stdout
+ CGI standard output
+ %stderr
+ CGI standard error
+
+

(The %stdout and %stderr parts may be missing if the script did + not output anything on standard output or standard error).

+ +

ScriptLog Directive

Description: Location of the CGI script error logfile
Syntax:ScriptLog file-path
Context:server config
Status:Base
Module:mod_cgi, mod_cgid
+

The ScriptLog directive sets the CGI + script error logfile. If no ScriptLog is given, no error log is + created. If given, any CGI errors are logged into the filename + given as argument. If this is a relative file or path it is taken + relative to the server root.

+ +

This log will be opened as the user the child processes run + as, ie. the user specified in the main User directive. This means that + either the directory the script log is in needs to be writable + by that user or the file needs to be manually created and set + to be writable by that user. If you place the script log in + your main logs directory, do NOT change the + directory permissions to make it writable by the user the child + processes run as.

+ +

Note that script logging is meant to be a debugging feature + when writing CGI scripts, and is not meant to be activated + continuously on running servers. It is not optimized for speed + or efficiency, and may have security problems if used in a + manner other than that for which it was designed.

+

ScriptLogBuffer Directive

Description: Maximum amount of PUT or POST requests that will be recorded +in the scriptlog
Syntax:ScriptLogBuffer bytes
Default:ScriptLogBuffer 1024
Context:server config
Status:Base
Module:mod_cgi, mod_cgid
+

The size of any PUT or POST entity body that is logged to + the file is limited, to prevent the log file growing too big + too quickly if large bodies are being received. By default, up + to 1024 bytes are logged, but this can be changed with this + directive.

+

ScriptLogLength Directive

Description: Size limit of the CGI script logfile
Syntax:ScriptLogLength bytes
Default:ScriptLogLength 10385760
Context:server config
Status:Base
Module:mod_cgi, mod_cgid
+

ScriptLogLength can be used to limit the + size of the CGI script logfile. Since the logfile logs a lot of + information per CGI error (all request headers, all script output) + it can grow to be a big file. To prevent problems due to unbounded + growth, this directive can be used to set an maximum file-size for + the CGI logfile. If the file exceeds this size, no more + information will be written to it.

+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_cgid.html.en b/docs/manual/mod/mod_cgid.html.en new file mode 100644 index 0000000000..852bd1e5a8 --- /dev/null +++ b/docs/manual/mod/mod_cgid.html.en @@ -0,0 +1,35 @@ +mod_cgid- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_cgid

Description:Execution of CGI scripts using an + external CGI daemon
Status:Base
Module Identifier:cgid_module
Compatibility:Unix threaded MPMs only

Summary

+

Except for the optimizations and the additional ScriptSock directive noted below, + mod_cgid behaves similarly to mod_cgi. See the + mod_cgi Summary for additional details about + Apache and CGI.

+ +

On certain unix operating systems, forking a process from a + multi-threaded server is a very expensive operation because the + new process will replicate all the threads of the parent + process. In order to avoid incurring this expense on each CGI + invocation, mod_cgid creates an external daemon that is + responsible for forking child processes to run CGI scripts. The + main server communicates with this daemon using a unix domain + socket.

+ +

This module is used by default whenever a multi-threaded MPM + is selected during the compilation process. At the user level, + this module is identical in configuration and operation to + mod_cgi. The only exception is the + additional directive ScriptSock which gives the + name of the socket to use for communication with the cgi + daemon.

+

Directives

ScriptSock Directive

Description:
Syntax:ScriptSock file-path
Default:ScriptSock logs/cgisock
Context:server config
Status:Base
Module:mod_cgid
+

This directive sets the name of the socket to use for + communication with the CGI daemon. The socket will be opened + using the permissions of the user who starts Apache (usually + root). To maintain the security of communications with CGI + scripts, it is important that no other user has permission to + write in the directory where the socket is located.

+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_charset_lite.html.en b/docs/manual/mod/mod_charset_lite.html.en new file mode 100644 index 0000000000..28bb4a46f2 --- /dev/null +++ b/docs/manual/mod/mod_charset_lite.html.en @@ -0,0 +1,122 @@ +mod_charset_lite- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_charset_lite

Description:Specify character set translation or recoding
Status:Experimental
Module Identifier:charset_lite_module

Summary

+

This is an experimental module and should + be used with care. Experiment with your + mod_charset_lite configuration to ensure that it + performs the desired function.

+ +

mod_charset_lite allows the administrator to + specify the source character set of objects as well as the + character set they should be translated into before sending to the + client. mod_charset_lite does not translate the + data itself but instead tells Apache what translation to + perform. mod_charset_lite is applicable to EBCDIC + and ASCII host environments. In an EBCDIC environment, Apache + normally translates text content from the code page of the Apache + process locale to ISO-8859-1. mod_charset_lite + can be used to specify that a different translation is to be + performed. In an ASCII environment, Apache normally performs no + translation, so mod_charset_lite is needed in + order for any translation to take place.

+ +

This module provides a small subset of configuration + mechanisms implemented by Russian Apache and its associated + mod_charset.

+

Directives

Common Problems

+ +

Invalid character set names

+ +

The character set name parameters of CharsetSourceEnc and + CharsetDefault + must be acceptable to the translation mechanism used by APR on the + system where mod_charset_lite is deployed. These + character set names are not standardized and are usually not the + same as the corresponding values used in http headers. Currently, + APR can only use iconv(3), so you can easily test your character + set names using the iconv(1) program, as follows:

+
+ iconv -f charsetsourceenc-value -t charsetdefault-value +
+ + +

Mismatch between character set of content and translation + rules

+ +

If the translation rules don't make sense for the content, + translation can fail in various ways, including:

+ + + +

CharsetDefault Directive

Description: Charset to translate into
Syntax:CharsetDefault charset
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Experimental
Module:mod_charset_lite
+

The CharsetDefault directive specifies the + charset that content in the associated container should be + translated to.

+ +

The value of the charset argument must be accepted + as a valid character set name by the character set support in + APR. Generally, this means that it must be supported by + iconv.

+ +

Example

+ <Directory "/export/home/trawick/apacheinst/htdocs/convert">
+ CharsetSourceEnc UTF-16BE
+ CharsetDefault ISO8859-1
+ </Directory> +
+

CharsetOptions Directive

Description: Configures charset tranlation behavior
Syntax:CharsetOptions option [option] ...
Default:CharsetOptions DebugLevel=0 +NoImplicitAdd
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Experimental
Module:mod_charset_lite
+

The CharsetOptions directive configures certain + behaviors of mod_charset_lite. Option can + be one of

+ +
+
DebugLevel=n
+ +
The DebugLevel keyword allows you to specify + the level of debug messages generated by + mod_charset_lite. By default, no messages are + generated. This is equivalent to DebugLevel=0. + With higher numbers, more debug messages are generated, and + server performance will be degraded. The actual meanings of + the numeric values are described with the definitions of the + DBGLVL_ constants near the beginning of + mod_charset_lite.c.
+ +
ImplicitAdd | NoImplicitAdd
+ +
The ImplicitAdd keyword specifies that + mod_charset_lite should implicitly insert its + filter when the configuration specifies that the character + set of content should be translated. If the filter chain is + explicitly configured using the AddOutputFilter directive, + NoImplicitAdd should be specified so that + mod_charset_lite doesn't add its filter.
+
+

CharsetSourceEnc Directive

Description: Source charset of files
Syntax:CharsetSourceEnc charset
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Experimental
Module:mod_charset_lite
+

The CharsetSourceEnc directive specifies the + source charset of files in the associated container.

+ +

The value of the charset argument must be accepted + as a valid character set name by the character set support in + APR. Generally, this means that it must be supported by + iconv.

+ +

example

+ <Directory "/export/home/trawick/apacheinst/htdocs/convert">
+ CharsetSourceEnc UTF-16BE
+ CharsetDefault ISO8859-1
+ </Directory> +
+

The character set names in this example work with the iconv + translation support in Solaris 8.

+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_dav.html.en b/docs/manual/mod/mod_dav.html.en new file mode 100644 index 0000000000..6adeb6e0bd --- /dev/null +++ b/docs/manual/mod/mod_dav.html.en @@ -0,0 +1,83 @@ +mod_dav- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_dav

Description:Distributed Authoring and Versioning +(WebDAV) functionality
Status:Extension
Module Identifier:dav_module

Summary

+

This module provides class 1 and class 2 WebDAV ('Web-based Distributed + Authoring and Versioning') functionality for Apache. This + extension to the HTTP protocol allows creating, moving, + copying, and deleting resources and collections on a remote web + server.

+ +

To enable mod_dav, add the following to a container in your + httpd.conf file:

+ +
Dav On
+ +

Also, specify a valid filename for the DAV lock database by + adding the following to the global section in your + httpd.conf file:

+ +
DavLockDB /tmp/DavLock     + (Any web-server writable filename, without an + extension) +
+

Directives

Dav Directive

Description: Enable WebDAV HTTP methods
Syntax:Dav on|off
Default:Dav off
Context:directory
Status:Extension
Module:mod_dav
+

Use the Dav directive to enable the + WebDAV HTTP methods for the given container. You may wish to add a + <Limit> clause + inside the <location> directive to limit access to + DAV-enabled locations.

+ +

Example

+ DavLockDB /tmp/DavLock
+
+ <Location /foo>
+ Dav On
+
+ AuthType Basic
+ AuthName DAV
+ AuthUserFile user.passwd
+
+   <LimitExcept GET HEAD OPTIONS>
+   require user admin
+   </LimitExcept>
+ </Location>
+
+

DavDepthInfinity Directive

Description: Allow PROPFIND, Depth: Infinity requests
Syntax:DavDepthInfinity on|off
Default:DavDepthInfinity off
Context:directory
Status:Extension
Module:mod_dav
+

Use the DavDepthInfinity directive to + allow the processing of PROPFIND requests containing the header + 'Depth: Infinity'. Because this type of request could constitute a + denial-of-service attack, by default it is not allowed.

+

DavLockDB Directive

Description: Location of the DAV lock database
Syntax:DavLockDB file-path
Context:server config, virtual host
Status:Extension
Module:mod_dav
+

Use the DavLockDB directive to specify + the full path to the lock database, excluding an extension. The + default (file system) implementation of mod_dav uses a SDBM + database to track user locks. The utility + modules/dav/util/lockview can be used from the server + to display all locks in a lock database.

+ +

Example

+DavLockDB /tmp/DavLock +
+

DavMinTimeout Directive

Description: Minimum amount of time the server holds a lock on +a DAV resource
Syntax:DavMinTimeout seconds
Default:DavMinTimeout 0
Context:directory
Status:Extension
Module:mod_dav
+

When a client requests a DAV resource lock, it can also + specify a time when the lock will be automatically removed by + the server. This value is only a request, and the server can + ignore it or inform the client of an arbitrary value.

+ +

Use the DavMinTimeout directive to specify, in + seconds, the minimum lock timeout to return to a client. + Microsoft Web Folders defaults to a timeout of 120 seconds; the + DavMinTimeout can override this to a higher value + (like 600 seconds) to reduce the chance of the client losing + the lock due to network latency.

+ +

Example

+ <Location /MSWord>
+ DavMinTimeout 600
+ </Location>
+
+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_deflate.html.en b/docs/manual/mod/mod_deflate.html.en new file mode 100644 index 0000000000..c42e0a532d --- /dev/null +++ b/docs/manual/mod/mod_deflate.html.en @@ -0,0 +1,49 @@ +mod_deflate- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_deflate

Description:Compress content before + it is delivered to the client
Status:Extension
Module Identifier:deflate_module

Summary

+

The mod_deflate module provides + the DEFLATE output filter that allows output from + your server to be compressed before being sent to the client over + the network.

+

Directives

See also

Enabling Compression

+ +

Compression is implemented by the DEFLATE + filter. The following directive + will enable compression for documents in the container where it + is placed:

+

Most popular browsers can not handle compression of all content + so you may want to enable the 'gzip-only-text/html' note (see below) +

+ +
SetEnv gzip-only-text/html 1
+SetOutputFilter DEFLATE +
+ +

Here is an example of enabling compression for the Apache + documentation:

+ +
+<Directory "/your-server-root/manual">
+ SetEnv gzip-only-text/html 1
+ SetOutputFilter DEFLATE
+</Directory> +
+

DeflateBufferSize Directive

Description: Fragment size to be compressed at one time by zlib
Syntax:DeflateBufferSize value
Context:server config
Status:Extension
Module:mod_deflate
+

The DeflateBufferSize directive specifies + the size in bytes of the fragments that zlib should compress at one + time.

+

DeflateFilterNote Directive

Description: Places the compression ratio in a note for logging
Syntax:DeflateFilterNote notename
Context:server config
Status:Extension
Module:mod_deflate
+

The DeflateFilterNote directive + specifies that a note about compression ratios should be attached + to the request. The name of the note is the value specified for + the directive.

+

DeflateMemLevel Directive

Description: Amount of memory available to zlib for compression
Syntax:DeflateMemLevel value
Context:server config
Status:Extension
Module:mod_deflate
+

The DeflateMemLevel directive specifies + the amount of memory in bytes available to zlib for compression.

+

DeflateWindowSize Directive

Description: Zlib compression window size
Syntax:DeflateWindowSize value
Context:server config
Status:Extension
Module:mod_deflate
+

The DeflateWindowSize directive specifies the + zlib compression window size (a value between 1 and 15).

+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_dir.html.en b/docs/manual/mod/mod_dir.html.en new file mode 100644 index 0000000000..673093f4d1 --- /dev/null +++ b/docs/manual/mod/mod_dir.html.en @@ -0,0 +1,57 @@ +mod_dir- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_dir

Description:Provides for "trailing slash" redirects and + serving directory index files
Status:Base
Module Identifier:dir_module

Summary

+

The index of a directory can come from one of two sources:

+ + +

The two functions are separated so that you can completely + remove (or replace) automatic index generation should you want + to.

+ +

A "trailing slash" redirect is issued when the server + receives a request for a URL + http://servername/foo/dirname where + dirname is a directory. Directories require a + trailing slash, so mod_dir issues a redirect to + http://servername/foo/dirname/.

+

Directives

DirectoryIndex Directive

Description: List of resources to look for when the client requests +a directory
Syntax:DirectoryIndex + local-url [local-url] ...
Default:DirectoryIndex index.html
Context:server config, virtual host, directory, .htaccess
Override:Indexes
Status:Base
Module:mod_dir
+

The DirectoryIndex directive sets the + list of resources to look for, when the client requests an index + of the directory by specifying a / at the end of the a directory + name. Local-url is the (%-encoded) URL of a document on + the server relative to the requested directory; it is usually the + name of a file in the directory. Several URLs may be given, in + which case the server will return the first one that it finds. If + none of the resources exist and the Indexes option is + set, the server will generate its own listing of the + directory.

+ +

Example

+DirectoryIndex index.html +
+ +

then a request for http://myserver/docs/ would + return http://myserver/docs/index.html if it + exists, or would list the directory if it did not.

+ +

Note that the documents do not need to be relative to the + directory;

+ +
DirectoryIndex index.html index.txt /cgi-bin/index.pl
+

would cause the CGI script /cgi-bin/index.pl to be + executed if neither index.html or + index.txt existed in a directory.

+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_env.html.en b/docs/manual/mod/mod_env.html.en new file mode 100644 index 0000000000..cd92dcafe3 --- /dev/null +++ b/docs/manual/mod/mod_env.html.en @@ -0,0 +1,32 @@ +mod_env- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_env

Description:Modifies the environment which is + passed to CGI scripts and SSI pages
Status:Base
Module Identifier:env_module

Summary

+

This module allows for control of the environment that will + be provided to CGI scripts and SSI pages. Environment variables + may be passed from the shell which invoked the httpd process. + Alternatively, environment variables may be set or unset within + the configuration process.

+

Directives

See also

PassEnv Directive

Description: Passes environment variables from the shell
Syntax:PassEnv + env-variable [env-variable] ...
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Base
Module:mod_env
+

Specifies one or more environment variables to pass to CGI + scripts and SSI pages from the environment of the shell which + invoked the httpd process. Example:

+
+ PassEnv LD_LIBRARY_PATH +
+

SetEnv Directive

Description: Sets environment variables
Syntax:SetEnv env-variable value
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Base
Module:mod_env
+

Sets an environment variable, which is then passed on to CGI + scripts and SSI pages. Example:

+
+ SetEnv SPECIAL_PATH /foo/bin +
+

UnsetEnv Directive

Description: Removes variables from the environment
Syntax:UnsetEnv env-variable [env-variable] ...
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Base
Module:mod_env
+

Removes one or more environment variables from those passed + on to CGI scripts and SSI pages. Example:

+
+ UnsetEnv LD_LIBRARY_PATH +
+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_example.html.en b/docs/manual/mod/mod_example.html.en new file mode 100644 index 0000000000..bc93bb4760 --- /dev/null +++ b/docs/manual/mod/mod_example.html.en @@ -0,0 +1,95 @@ +mod_example- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_example

Description:Illustrates the Apache module API
Status:Experimental
Module Identifier:example_module

Summary

+
+ This document has not been updated + to take into account changes made in the 2.0 version of the + Apache HTTP Server. Some of the information may still be + relevant, but please use it with care. +
+ +

The files in the src/modules/example directory + under the Apache distribution directory tree are provided as an + example to those that wish to write modules that use the Apache + API.

+ +

The main file is mod_example.c, which + illustrates all the different callback mechanisms and call + syntaxes. By no means does an add-on module need to include + routines for all of the callbacks - quite the contrary!

+ +

The example module is an actual working module. If you link + it into your server, enable the "example-handler" handler for a + location, and then browse to that location, you will see a + display of some of the tracing the example module did as the + various callbacks were made.

+

Directives

Compiling the example module

+ +

To include the example module in your server, follow the + steps below:

+ +
    +
  1. + Uncomment the "AddModule modules/example/mod_example" line + near the bottom of the src/Configuration file. + If there isn't one, add it; it should look like this: +
    + AddModule modules/example/mod_example.o +
    +
    2. + +
  2. Run the src/Configure script + ("cd src; ./Configure"). This will + build the Makefile for the server itself, and update the + src/modules/Makefile for any additional modules + you have requested from beneath that subdirectory.
    3. + +
  3. Make the server (run "make" in the + src directory).
    4. +
+ +

To add another module of your own:

+ +
    +
  1. mkdir src/modules/mymodule
    2. + +
  2. cp src/modules/example/* + src/modules/mymodule
    3. + +
  3. Modify the files in the new directory.
    4. + +
  4. Follow steps [1] through [3] above, with appropriate + changes.
    5. +
+

Using the mod_example Module

+ +

To activate the example module, include a block similar to + the following in your srm.conf file:

+
+ <Location /example-info>
+ SetHandler example-handler
+ </Location> +
+ +

As an alternative, you can put the following into a .htaccess file + and then request the file "test.example" from that location:

+
+ AddHandler example-handler .example +
+ +

After reloading/restarting your server, you should be able + to browse to this location and see the brief display mentioned + earlier.

+

Example Directive

Description: Demonstration directive to illustrate the Apache module +API
Syntax:Example
Context:server config, virtual host, directory, .htaccess
Status:Experimental
Module:mod_example
+

The Example directive just sets a demonstration + flag which the example module's content handler displays. It + takes no arguments. If you browse to an URL to which the + example content-handler applies, you will get a display of the + routines within the module and how and in what order they were + called to service the document request. The effect of this + directive one can observe under the point "Example + directive declared here: YES/NO".

+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_expires.html.en b/docs/manual/mod/mod_expires.html.en new file mode 100644 index 0000000000..e3b7d093e1 --- /dev/null +++ b/docs/manual/mod/mod_expires.html.en @@ -0,0 +1,160 @@ +mod_expires- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_expires

Description:Generation of + Expires HTTP headers according to user-specified + criteria
Status:Extension
Module Identifier:expires_module

Summary

+

This module controls the setting of the Expires + HTTP header in server responses. The expiration date can set to + be relative to either the time the source file was last + modified, or to the time of the client access.

+ +

The Expires HTTP header is an instruction to + the client about the document's validity and persistence. If + cached, the document may be fetched from the cache rather than + from the source until this time has passed. After that, the + cache copy is considered "expired" and invalid, and a new copy + must be obtained from the source.

+

Directives

Alternate Interval + Syntax

+ +

The ExpiresDefault and + ExpiresByType directives + can also be defined in a more readable syntax of the form:

+ +
+ ExpiresDefault "<base> [plus] {<num> + <type>}*"
+ ExpiresByType type/encoding "<base> [plus] + {<num> <type>}*" +
+ +

where <base> is one of:

+ + + +

The 'plus' keyword is optional. <num> + should be an integer value [acceptable to atoi()], + and <type> is one of:

+ + + +

For example, any of the following directives can be used to + make documents expire 1 month after being accessed, by + default:

+ +
+ ExpiresDefault "access plus 1 month"
+ ExpiresDefault "access plus 4 weeks"
+ ExpiresDefault "access plus 30 days" +
+ +

The expiry time can be fine-tuned by adding several + '<num> <type>' clauses:

+ +
+ExpiresByType text/html "access plus 1 month 15 + days 2 hours"
+ ExpiresByType image/gif "modification plus 5 hours 3 + minutes" +
+ +

Note that if you use a modification date based setting, the + Expires header will not be added to content + that does not come from a file on disk. This is due to the fact + that there is no modification time for such content.

+

ExpiresActive Directive

Description: Enables generation of Expires headers
Syntax:ExpiresActive On|Off
Context:server config, virtual host, directory, .htaccess
Override:Indexes
Status:Extension
Module:mod_expires
+

This directive enables or disables the generation of the + Expires header for the document realm in question. + (That is, if found in an .htaccess file, for + instance, it applies only to documents generated from that + directory.) If set to Off, no + Expires header will be generated for any document + in the realm (unless overridden at a lower level, such as an + .htaccess file overriding a server config file). + If set to On, the header will be added to + served documents according to the criteria defined by the + ExpiresByType and + ExpiresDefault directives + (q.v.).

+ +

Note that this directive does not guarantee that an + Expires header will be generated. If the criteria + aren't met, no header will be sent, and the effect will be as + though this directive wasn't even specified.

+

ExpiresByType Directive

Description: Value of the Expires header configured +by MIME type
Syntax:ExpiresByType + MIME-type <code>seconds
Context:server config, virtual host, directory, .htaccess
Override:Indexes
Status:Extension
Module:mod_expires
+

This directive defines the value of the Expires + header generated for documents of the specified type + (e.g., text/html). The second argument + sets the number of seconds that will be added to a base time to + construct the expiration date.

+ +

The base time is either the last modification time of the + file, or the time of the client's access to the document. Which + should be used is specified by the + <code> field; M + means that the file's last modification time should be used as + the base time, and A means the client's access + time should be used.

+ +

The difference in effect is subtle. If M is used, + all current copies of the document in all caches will expire at + the same time, which can be good for something like a weekly + notice that's always found at the same URL. If A is + used, the date of expiration is different for each client; this + can be good for image files that don't change very often, + particularly for a set of related documents that all refer to + the same images (i.e., the images will be accessed + repeatedly within a relatively short timespan).

+ +

Example:

+
+# enable expirations
+ExpiresActive On
+# expire GIF images after a month in the client's cache
+ExpiresByType image/gif A2592000
+# HTML documents are good for a week from the time they were changed
+ExpiresByType text/html M604800 +
+ +

Note that this directive only has effect if + ExpiresActive On has been specified. It overrides, + for the specified MIME type only, any expiration date + set by the ExpiresDefault + directive.

+ +

You can also specify the expiration time calculation using + an alternate syntax, described earlier in + this document.

+

ExpiresDefault Directive

Description: Default algorithm for calculating expiration time
Syntax:ExpiresDefault <code>seconds
Context:server config, virtual host, directory, .htaccess
Override:Indexes
Status:Extension
Module:mod_expires
+

This directive sets the default algorithm for calculating the + expiration time for all documents in the affected realm. It can be + overridden on a type-by-type basis by the ExpiresByType directive. See the + description of that directive for details about the syntax of the + argument, and the alternate syntax + description as well.

+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_ext_filter.html.en b/docs/manual/mod/mod_ext_filter.html.en new file mode 100644 index 0000000000..1f3f27f49a --- /dev/null +++ b/docs/manual/mod/mod_ext_filter.html.en @@ -0,0 +1,204 @@ +mod_ext_filter- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_ext_filter

Description:Pass the response body + through an external program before delivery to the + client
Status:Experimental
Module Identifier:ext_filter_module

Summary

+

This is an experimental module and should + be used with care. Test your mod_ext_filter + configuration carefully to ensure that it performs the desired + function. You may wish to review + this information for background on the Apache filtering + model.

+ +

mod_ext_filter presents a simple and familiar + programming model for filters. With this module, a program + which reads from stdin and writes to stdout (i.e., a Unix-style + filter command) can be a filter for Apache. This filtering + mechanism is much slower than using a filter which is specially + written for the Apache API and runs inside of the Apache server + process, but it does have the following benefits:

+ + + +

Even when the performance characteristics are not suitable + for production use, mod_ext_filter can be used as + a prototype environment for filters.

+

Directives

Examples

+ +

Generating HTML from some other type of response

+
+
+    # mod_ext_filter directive to define a filter to HTML-ize text/c files 
+    # using the external program /usr/bin/enscript, with the type of the 
+    # result set to text/html
+    ExtFilterDefine c-to-html mode=output intype=text/c outtype=text/html \
+                    cmd="/usr/bin/enscript --color -W html -Ec -o - -"
+
+    <Directory "/export/home/trawick/apacheinst/htdocs/c">
+
+    # core directive to cause the new filter to be run on output
+    SetOutputFilter c-to-html
+
+    # mod_mime directive to set the type of .c files to text/c
+    AddType text/c .c
+
+    # mod_ext_filter directive to set the debug level just high 
+    # enough to see a log message per request showing the configuration
+    # in force
+    ExtFilterOptions DebugLevel=1
+
+    </Directory>
+
+
+ + +

Implementing a content encoding filter

+
+
+  # mod_ext_filter directive to define the external filter
+  ExtFilterDefine gzip mode=output cmd=/bin/gzip
+
+  <Location /gzipped>
+
+  # core directive to cause the gzip filter to be run on output
+  SetOutputFilter gzip
+
+  # mod_header directive to add "Content-Encoding: gzip" header field
+  Header set Content-Encoding gzip
+
+  </Location>
+
+
+ +

Note: this gzip example is just for the purposes of illustration. + Please refer to mod_deflate for a practical + implementation.

+ + +

Slowing down the server

+
+
+  # mod_ext_filter directive to define a filter which runs everything 
+  # through cat; cat doesn't modify anything; it just introduces extra
+  # pathlength and consumes more resources
+  ExtFilterDefine slowdown mode=output cmd=/bin/cat preservescontentlength
+
+  <Location />
+
+  # core directive to cause the slowdown filter to be run several times on 
+  # output
+  SetOutputFilter slowdown slowdown slowdown
+
+  </Location>
+
+
+ + +

ExtFilterDefine Directive

Description:
Syntax:ExtFilterDefine filtername parameters
Context:server config
Status:Experimental
Module:mod_ext_filter
+

The ExtFilterDefine directive defines the + characteristics of an external filter, including the program to + run and its arguments.

+ +

filtername specifies the name of the filter being + defined. This name can then be used in SetOutputFilter + directives. It must be unique among all registered filters. + At the present time, no error is reported by the + register-filter API, so a problem with duplicate names isn't + reported to the user.

+ +

Subsequent parameters can appear in any order and define the + external command to run and certain other characteristics. The + only required parameter is cmd=. These parameters + are:

+ +
+
cmd=cmdline
+ +
The cmd= keyword allows you to specify the + external command to run. If there are arguments after the + program name, the command line should be surrounded in + quotation marks.
+ +
mode=mode
+ +
mode should be output for now (the + default). In the future, mode=input will be used to + specify a filter for request bodies.
+ +
intype=imt
+ +
This parameter specifies the internet media type (i.e., + MIME type) of documents which should be filtered. By default, + all documents are filtered. If intype= is + specified, the filter will be disabled for documents of other + types.
+ +
outtype=imt
+ +
This parameter specifies the internet media type (i.e., + MIME type) of filtered documents. It is useful when the + filter changes the internet media type as part of the + filtering operation. By default, the internet media type is + unchanged.
+ +
PreservesContentLength
+ +
The PreservesContentLength keyword specifies + that the filter preserves the content length. This is not the + default, as most filters change the content length. In the + event that the filter doesn't modify the length, this keyword + should be specified.
+
+

ExtFilterOptions Directive

Description:
Syntax:ExtFilterOptions + option [option] ...
Default:ExtFilterOptions DebugLevel=0 NoLogStderr
Context:directory
Status:Experimental
Module:mod_ext_filter
+

The ExtFilterOptions directive specifies + special processing options for mod_ext_filter. + Option can be one of

+ +
+
DebugLevel=n
+ +
+ The DebugLevel keyword allows you to specify + the level of debug messages generated by + mod_ext_filter. By default, no debug messages + are generated. This is equivalent to + DebugLevel=0. With higher numbers, more debug + messages are generated, and server performance will be + degraded. The actual meanings of the numeric values are + described with the definitions of the DBGLVL_ constants + near the beginning of mod_ext_filter.c. + +

Note: The core directive LogLevel should be used to + cause debug messages to be stored in the Apache error + log.

+
+ +
LogStderr | NoLogStderr
+ +
The LogStderr keyword specifies that + messages written to standard error by the external filter + program will be saved in the Apache error log. + NoLogStderr disables this feature.
+
+ +

Example:

+
+ ExtFilterOptions LogStderr DebugLevel=0 +
+ +

Messages written to the filter's standard error will be stored + in the Apache error log. No debug messages will be generated by + mod_ext_filter.

+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_file_cache.html.en b/docs/manual/mod/mod_file_cache.html.en new file mode 100644 index 0000000000..3ba27d0620 --- /dev/null +++ b/docs/manual/mod/mod_file_cache.html.en @@ -0,0 +1,147 @@ +mod_file_cache- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_file_cache

Description:Caches a static list of files in memory
Status:Experimental
Module Identifier:file_cache_module

Summary

+ +
+This module should be used with care. You can easily + create a broken site using mod_file_cache, so read this + document carefully. +
+ +

Caching frequently requested files that change very + infrequently is a technique for reducing server load. + mod_file_cache provides two techniques for caching frequently + requested static files. Through configuration + directives, you can direct mod_file_cache to either open then + mmap()a file, or to pre-open a file and save the file's open + file handle. Both techniques reduce server load when + processing requests for these files by doing part of the work + (specifically, the file I/O) for serving the file when the + server is started rather than during each request.

+ +

Notice: You cannot use this for speeding up CGI programs or + other files which are served by special content handlers. It + can only be used for regular files which are usually served by + the Apache core content handler.

+ +

This module is an extension of and borrows heavily from the + mod_mmap_static module in Apache 1.3.

+

Directives

Using mod_file_cache

+ +

mod_file_cache caches a list of statically + configured files via MMapFile or CacheFile directives in the + main server configuration.

+ +

Not all platforms support both directives. For example, Apache + on Windows does not currently support the MMapStatic directive, while + other platforms, like AIX, support both. You will receive an error + message in the server error log if you attempt to use an + unsupported directive. If given an unsupported directive, the + server will start but the file will not be cached. On platforms + that support both directives, you should experiment with both to + see which works best for you.

+ +

MmapFile Directive

+ +

The MmapFile + directive of mod_file_cache maps a list of + statically configured files into memory through the system call + mmap(). This system call is available on most modern + Unix derivates, but not on all. There are sometimes + system-specific limits on the size and number of files that can be + mmap()d, experimentation is probably the easiest way to find + out.

+ +

This mmap()ing is done once at server start or restart, + only. So whenever one of the mapped files changes on the + filesystem you have to restart the server (see the Stopping and Restarting + documentation). To reiterate that point: if the files are + modified in place without restarting the server you + may end up serving requests that are completely bogus. You + should update files by unlinking the old copy and putting a new + copy in place. Most tools such as rdist and + mv do this. The reason why this modules doesn't + take care of changes to the files is that this check would need + an extra stat() every time which is a waste and + against the intent of I/O reduction.

+ + +

CacheFile Directive

+ +

The CacheFile + directive of mod_file_cache opens an active + handle or file descriptor to the file (or files) + listed in the configuration directive and places these open file + handles in the cache. When the file is requested, the server + retrieves the handle from the cache and passes it to the + sendfile() (or TransmitFile() on Windows), socket API.

+ +

Insert more details about sendfile API...

+ +

This file handle caching is done once at server start or + restart, only. So whenever one of the cached files changes on + the filesystem you have to restart the server (see the + Stopping and Restarting + documentation). To reiterate that point: if the files are + modified in place without restarting the server you + may end up serving requests that are completely bogus. You + should update files by unlinking the old copy and putting a new + copy in place. Most tools such as rdist and + mv do this.

+ + +

Note

Don't bother asking for a for a + directive which recursively caches all the files in a + directory. Try this instead... See the + Include directive, and consider + this command: +
+ find /www/htdocs -type f -print \
+ | sed -e 's/.*/mmapfile &/' > /www/conf/mmap.conf +
+
+ +

CacheFile Directive

Description:
Syntax:CacheFile + file-path [file-path] ...
Context:server config
Status:Experimental
Module:mod_file_cache
+

The CacheFile directive opens handles to + one or more files (given as whitespace separated arguments) and + places these handles into the cache at server startup + time. Handles to cached files are automatically closed on a server + shutdown. When the files have changed on the filesystem, the + server should be restarted to to re-cache them.

+ +

Be careful with the file-path arguments: They have + to literally match the filesystem path Apache's URL-to-filename + translation handlers create. We cannot compare inodes or other + stuff to match paths through symbolic links etc. + because that again would cost extra stat() system + calls which is not acceptable. This module may or may not work + with filenames rewritten by mod_alias or + mod_rewrite.

+ +

Example

+ CacheFile /usr/local/apache/htdocs/index.html +
+

MMapFile Directive

Description:
Syntax:MMapFile file-path [file-path] ...
Context:server config
Status:Experimental
Module:mod_file_cache
+

The MMapFile directive maps one or more files + (given as whitespace separated arguments) into memory at server + startup time. They are automatically unmapped on a server + shutdown. When the files have changed on the filesystem at + least a HUP or USR1 signal should be send to the server to + re-mmap them.

+ +

Be careful with the file-path arguments: They have + to literally match the filesystem path Apache's URL-to-filename + translation handlers create. We cannot compare inodes or other + stuff to match paths through symbolic links etc. + because that again would cost extra stat() system + calls which is not acceptable. This module may or may not work + with filenames rewritten by mod_alias or + mod_rewrite.

+ +

Example

+ MMapFile /usr/local/apache/htdocs/index.html +
+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_headers.html.en b/docs/manual/mod/mod_headers.html.en new file mode 100644 index 0000000000..3c39863e55 --- /dev/null +++ b/docs/manual/mod/mod_headers.html.en @@ -0,0 +1,219 @@ +mod_headers- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_headers

Description:Customization of HTTP request + and response headers
Status:Extension
Module Identifier:headers_module
Compatibility:RequestHeader is available only in Apache 2.0

Summary

+

This module provides directives to control and modify HTTP + request and response headers. Headers can be merged, replaced + or removed.

+

Directives

Order of Processing

+ +

The directives provided by mod_header can occur almost + anywhere within the server configuration. They are valid in the + main server config and virtual host sections, inside + <Directory>, <Location> and <Files> sections, + and within .htaccess files.

+ +

The directives are processed in the following order:

+ +
    +
  1. main server
    2. + +
  2. virtual host
    3. + +
  3. <Directory> sections and .htaccess
    4. + +
  4. <Location>
    5. + +
  5. <Files>
    6. +
+ +

Order is important. These two headers have a different + effect if reversed:

+ +
+RequestHeader append MirrorID "mirror 12"
+ RequestHeader unset MirrorID +
+ +

This way round, the MirrorID header is not set. If reversed, + the MirrorID header is set to "mirror 12".

+

Example

+ +
    +
  1. Copy all request headers that begin with "TS" to the + response headers: + +
    + Header echo ^TS* +
    2. + +
  2. Add a header, MyHeader, to the response including a + timestamp for when the request was received and how long it + took to begin serving the request. This header can be used by + the client to intuit load on the server or in isolating + bottlenecks between the client and the server. + +
    + Header add MyHeader "%D %t" +
    + results in this header being added to the response: +
    + MyHeader: D=3775428 t=991424704447256 +
    +
    3. + +
  3. Say hello to Joe + +
    + Header add MyHeader "Hello Joe. It took %D microseconds for Apache to serve this request." +
    + results in this header being added to the response: +
    + MyHeader: Hello Joe. It took D=3775428 microseconds for Apache to serve this request. +
    +
    4. + +
  4. Conditionally send MyHeader on the response if and only + if header "MyRequestHeader" is present on the request. This + is useful for constructing headers in response to some client + stimulus. Note that this example requires the services of the + mod_setenvif module. + +
    + SetEnvIf MyRequestHeader value HAVE_MyRequestHeader
    + Header add MyHeader "%D %t mytext" env=HAVE_MyRequestHeader +
    + If the header "MyRequestHeader: value" is present on the + HTTP request, the response will contain the following + header: +
    + MyHeader: D=3775428 t=991424704447256 mytext +
    +
    5. +
+

Header Directive

Description: Configure HTTP response headers
Syntax:Header set|append|add|unset|echo header +[value]
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Extension
Module:mod_headers
+

This directive can replace, merge or remove HTTP response + headers. The header is modified just after the content handler + and output filters are run, allowing outgoing headers to be + modified. The action it performs is determined by the first + argument. This can be one of the following values:

+ + + +

This argument is followed by a header name, which + can include the final colon, but it is not required. Case is + ignored for set, append, add and unset. The header + name for echo is case sensitive and may be a regular + expression.

+ +

For add, append and + set a value is specified as the third + argument. If value contains spaces, it should be + surrounded by doublequotes. value may be a character + string, a string containing format specifiers or a combination + of both. The following format specifiers are supported in + value:

+ + + + + + +
%t: The time the request was received in Universal +Coordinated Time since the epoch (Jan. 1, 1970) measured in +microseconds. The value is preceded by "t=".
%D: The time from when the request was received to +the time the headers are sent on the wire. This is a measure of the +duration of the request. The value is preceded by "D=".
%{FOOBAR}e: The contents of the environment +variable FOOBAR.
+ +

When the Header directive is used with the + add, append, or set + argument, a fourth argument may be used to specify conditions + under which the action will be taken. If the environment variable specified in the + env=... argument exists (or if the environment + variable does not exist and env=!... is specified) + then the action specified by the Header directive + will take effect. Otherwise, the directive will have no effect + on the request.

+ +

The Header directives are processed just before the response + is sent to the network. These means that it is possible to set + and/or override most headers, except for those headers added by + the header filter.

+

RequestHeader Directive

Description: Configure HTTP request headers
Syntax:RequestHeader set|append|add|unset header +[value]
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Extension
Module:mod_headers
+

This directive can replace, merge or remove HTTP request + headers. The header is modified just before the content handler + is run, allowing incoming headers to be modified. The action it + performs is determined by the first argument. This can be one + of the following values:

+ + + +

This argument is followed by a header name, which can + include the final colon, but it is not required. Case is + ignored. For add, append and + set a value is given as the third argument. If + this value contains spaces, it should be surrounded by double + quotes. For unset, no value should be given.

+ +

The RequestHeader directive is processed + just before the request is run by its handler in the fixup phase. + This should allow headers generated by the browser, or by Apache + input filters to be overridden or modified.

+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_imap.html.en b/docs/manual/mod/mod_imap.html.en new file mode 100644 index 0000000000..ffc82fd08d --- /dev/null +++ b/docs/manual/mod/mod_imap.html.en @@ -0,0 +1,276 @@ +mod_imap- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_imap

Description:Server-side imagemap processing
Status:Base
Module Identifier:imap_module

Summary

+

This module processes .map files, thereby + replacing the functionality of the imagemap CGI + program. Any directory or document type configured to use the + handler imap-file (using either + AddHandler or + SetHandler) + will be processed by this module.

+ +

The following directive will activate files ending with + .map as imagemap files:

+ +
AddHandler imap-file map
+ +

Note that the following is still supported:

+ +
AddType application/x-httpd-imap map
+ +

However, we are trying to phase out "magic MIME types" so we + are deprecating this method.

+

Directives

New Features

+ +

The imagemap module adds some new features that were not + possible with previously distributed imagemap programs.

+ + +

Imagemap File

+ +

The lines in the imagemap files can have one of several + formats:

+ +
+ directive value [x,y ...]
+ directive value "Menu text" [x,y ...]
+ directive value x,y ... "Menu text" +
+

The directive is one of base, + default, poly, circle, + rect, or point. The value is an + absolute or relative URL, or one of the special values listed + below. The coordinates are x,y pairs separated by + whitespace. The quoted text is used as the text of the link if + a imagemap menu is generated. Lines beginning with '#' are + comments.

+ +

Imagemap File Directives

+

There are six directives allowed in the imagemap file. The + directives can come in any order, but are processed in the + order they are found in the imagemap file.

+ +
+
base Directive
+ +
Has the effect of <BASE HREF="value">. + The non-absolute URLs of the map-file are taken relative to + this value. The base directive overrides + ImapBase as set in a .htaccess file or in the server + configuration files. In the absence of an ImapBase + configuration directive, base defaults to + http://server_name/.
+ base_uri is synonymous with base. + Note that a trailing slash on the URL is significant.
+ +
default Directive
+ +
The action taken if the coordinates given do not fit any + of the poly, circle or + rect directives, and there are no + point directives. Defaults to + nocontent in the absence of an ImapDefault + configuration setting, causing a status code of 204 No + Content to be returned. The client should keep the + same page displayed.
+ +
poly Directive
+ +
Takes three to one-hundred points, and is obeyed if the + user selected coordinates fall within the polygon defined by + these points.
+ +
circle
+ +
Takes the center coordinates of a circle and a point on + the circle. Is obeyed if the user selected point is with the + circle.
+ +
rect Directive
+ +
Takes the coordinates of two opposing corners of a + rectangle. Obeyed if the point selected is within this + rectangle.
+ +
point Directive
+ +
Takes a single point. The point directive closest to the + user selected point is obeyed if no other directives are + satisfied. Note that default will not be + followed if a point directive is present and + valid coordinates are given.
+
+ + +

Values

+ +

The values for each of the directives can any of the following:

+ + +
+
a URL
+ +
The URL can be relative or absolute URL. Relative URLs + can contain '..' syntax and will be resolved relative to the + base value.
+ base itself will not resolved according to the + current value. A statement base mailto: will + work properly, though.
+ +
map
+ +
Equivalent to the URL of the imagemap file itself. No + coordinates are sent with this, so a menu will be generated + unless ImapMenu is set to 'none'.
+ +
menu
+ +
Synonymous with map.
+ +
referer
+ +
Equivalent to the URL of the referring document. Defaults + to http://servername/ if no Referer: header was + present.
+ +
nocontent
+ +
Sends a status code of 204 No Content, + telling the client to keep the same page displayed. Valid for + all but base.
+ +
error
+ +
Fails with a 500 Server Error. Valid for all + but base, but sort of silly for anything but + default.
+
+ + +

Coordinates

+ +
+
0,0 200,200
+ +
A coordinate consists of an x and a y + value separated by a comma. The coordinates are separated + from each other by whitespace. To accommodate the way Lynx + handles imagemaps, should a user select the coordinate + 0,0, it is as if no coordinate had been + selected.
+
+ + + +

Quoted Text

+ +
+
"Menu Text"
+ +
After the value or after the coordinates, the line + optionally may contain text within double quotes. This string + is used as the text for the link if a menu is + generated:
+ <a HREF="http://foo.com/">Menu + text</a>
+ If no quoted text is present, the name of the link will be + used as the text:
+ <a + HREF="http://foo.com/">http://foo.com</a>
+ It is impossible to escape double quotes within this + text.
+
+ +

Example Mapfile

+ +
+ #Comments are printed in a 'formatted' or + 'semiformatted' menu.
+ #And can contain html tags. <hr>
+ base referer
+ poly map "Could I have a menu, please?" 0,0 0,10 10,10 + 10,0
+ rect .. 0,0 77,27 "the directory of the referer"
+ circle http://www.inetnebr.com/lincoln/feedback/ 195,0 + 305,27
+ rect another_file "in same directory as referer" 306,0 + 419,27
+ point http://www.zyzzyva.com/ 100,100
+ point http://www.tripod.com/ 200,200
+ rect mailto:nate@tripod.com 100,150 200,0 "Bugs?"
+
+ +

Referencing your mapfile

+ +
+ <A HREF="/maps/imagemap1.map">
+ <IMG ISMAP SRC="/images/imagemap1.gif">
+ </A> +
+

ImapBase Directive

Description: Default base for imagemap files
Syntax:ImapBase map|referer|URL
Default:ImapBase http://servername/
Context:server config, virtual host, directory, .htaccess
Override:Indexes
Status:Base
Module:mod_imap
+

The ImapBase directive sets the default + base used in the imagemap files. Its value is + overridden by a base directive within the imagemap + file. If not present, the base defaults to + http://servername/.

+

ImapDefault Directive

Description: Default action when an imagemap is called with coordinates +that are not explicitly mapped
Syntax:ImapDefault error|nocontent|map|referer|URL
Default:ImapDefault nocontent
Context:server config, virtual host, directory, .htaccess
Override:Indexes
Status:Base
Module:mod_imap
+

The ImapDefault directive sets the default + default used in the imagemap files. Its value is + overridden by a default directive within the + imagemap file. If not present, the default action + is nocontent, which means that a 204 No + Content is sent to the client. In this case, the client + should continue to display the original page.

+

ImapMenu Directive

Description: Action if no coordinates are given when calling +an imagemap
Syntax:ImapMenu + none|formatted|semiformatted|unformatted
Context:server config, virtual host, directory, .htaccess
Override:Indexes
Status:Base
Module:mod_imap
+

The ImapMenu directive determines the + action taken if an imagemap file is called without valid + coordinates.

+ +
+
none
+ +
If ImapMenu is none, no menu is generated, + and the default action is performed.
+ +
formatted
+ +
A formatted menu is the simplest menu. + Comments in the imagemap file are ignored. A level one header + is printed, then an hrule, then the links each on a separate + line. The menu has a consistent, plain look close to that of + a directory listing.
+ +
semiformatted
+ +
In the semiformatted menu, comments are + printed where they occur in the imagemap file. Blank lines + are turned into HTML breaks. No header or hrule is printed, + but otherwise the menu is the same as a + formatted menu.
+ +
unformatted
+ +
Comments are printed, blank lines are ignored. Nothing is + printed that does not appear in the imagemap file. All breaks + and headers must be included as comments in the imagemap + file. This gives you the most flexibility over the appearance + of your menus, but requires you to treat your map files as + HTML instead of plaintext.
+
+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_include.html.en b/docs/manual/mod/mod_include.html.en new file mode 100644 index 0000000000..68928048bc --- /dev/null +++ b/docs/manual/mod/mod_include.html.en @@ -0,0 +1,601 @@ +mod_include- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_include

Description:Server-parsed html documents (Server Side Includes)
Status:Base
Module Identifier:include_module

Summary

+ +

This module provides a filter which will process files + before they are sent to the client. The processing is + controlled by specially formated SGML comments, referred to as + elements. These elements allow conditional text, the + inclusion of other files or programs, as well as the setting and + printing of environment variables.

+ +

Directives

See also

Enabling Server-Side Includes

+ + +

Server Side Includes are implemented by the + INCLUDES filter. If + documents containing server-side include directives are given + the extension .shtml, the following directives will make Apache + parse them and assign the resulting document the mime type of + text/html:

+ +
+ AddType text/html .shtml
+ AddOutputFilter INCLUDES .shtml +
+ +

The following directive must be given for the directories + containing the shtml files (typically in a + <Directory> section, but this directive is + also valid .htaccess files if AllowOverride + Options is set):

+ +
+ Options +Includes +
+ +

For backwards compatibility, the server-parsed + handler also activates the + INCLUDES filter. As well, Apache will activate the INCLUDES + filter for any document with mime type + text/x-server-parsed-html or + text/x-server-parsed-html3 (and the resulting + output will have the mime type text/html).

+ +

For more information, see our Tutorial on Server Side + Includes.

+

Basic Elements

+ +

The document is parsed as an HTML document, with special + commands embedded as SGML comments. A command has the syntax:

+ +
+ <!--#element attribute=value + attribute=value ... --> +
+ +

The value will often be enclosed in double quotes; many + commands only allow a single attribute-value pair. Note that + the comment terminator (-->) should be preceded + by whitespace to ensure that it isn't considered part of an SSI + token.

+ +

The allowed elements are:

+ +
+
config
+ +
+ This command controls various aspects of the parsing. The + valid attributes are: + +
+
errmsg
+ +
The value is a message that is sent back to the + client if an error occurs whilst parsing the + document.
+ +
sizefmt
+ +
The value sets the format to be used which displaying + the size of a file. Valid values are bytes + for a count in bytes, or abbrev for a count + in Kb or Mb as appropriate.
+ +
timefmt
+ +
The value is a string to be used by the + strftime(3) library routine when printing + dates.
+
+
+ +
echo
+ +
+

This command prints one of the include + variables, defined below. If the variable is unset, it + is printed as (none). Any dates printed are + subject to the currently configured timefmt.

+ +

Attributes:

+ +
+
var
+ +
The value is the name of the variable to print.
+ +
encoding
+ +
Specifies how Apache should encode special characters + contained in the variable before outputting them. If set + to "none", no encoding will be done. If set to "url", + then URL encoding (also known as %-encoding; this is + appropriate for use within URLs in links, etc.) will be + performed. At the start of an echo element, + the default is set to "entity", resulting in entity + encoding (which is appropriate in the context of a + block-level HTML element, eg. a paragraph of text). This + can be changed by adding an encoding + attribute, which will remain in effect until the next + encoding attribute is encountered or the + element ends, whichever comes first. Note that the + encoding attribute must precede the + corresponding var attribute to be effective, + and that only special characters as defined in the + ISO-8859-1 character encoding will be encoded. This + encoding process may not have the desired result if a + different character encoding is in use. Apache 1.3.12 and + above; previous versions do no encoding.
+
+
+ +
exec
+ +
+ The exec command executes a given shell command or CGI + script. The IncludesNOEXEC Option disables this command + completely. The valid attributes are: + +
+
cgi
+ +
+ The value specifies a (%-encoded) URL relative path to + the CGI script. If the path does not begin with a (/), + then it is taken to be relative to the current + document. The document referenced by this path is + invoked as a CGI script, even if the server would not + normally recognize it as such. However, the directory + containing the script must be enabled for CGI scripts + (with ScriptAlias + or the ExecCGI Option). + +

The CGI script is given the PATH_INFO and query + string (QUERY_STRING) of the original request from the + client; these cannot be specified in the URL path. The + include variables will be available to the script in + addition to the standard CGI + environment.

+ +

For example:

+ +
<!--#exec cgi="/cgi-bin/example.cgi" -->
+ +

If the script returns a Location: header instead of + output, then this will be translated into an HTML + anchor.

+ +

The include + virtual element should be + used in preference to exec cgi. In particular, + if you need to pass additional arguments to a CGI program, + using the query string, this cannot be done with exec + cgi, but can be done with include + virtual, as shown here:

+ +
+ <!--#include virtual="/cgi-bin/example.cgi?argument=value" --> +
+ +
+ +
cmd
+ +
+

The server will execute the given string using + /bin/sh. The include variables are available + to the command, in addition to the usual set of CGI + variables.

+ +

The use of #include + virtual is almost always + prefered to using either #exec cgi or #exec + cmd. The former (#include virtual) used the + standard Apache sub-request mechanism to include files or + scripts. It is much better tested and maintained.

+ +

In addition, on some platforms, like Win32, and on unix + when using suexec, you cannot pass arguments to a command in + an exec directive, or otherwise include spaces in + the command. Thus, while the following will work under a + non-suexec configuration on unix, it will not produce the + desired result under Win32, or when running suexec:

+ +
+ <!--#exec cmd="perl /path/to/perlscript arg1 arg2" --> +
+ +
+
+
+ +
fsize
+ +
+ This command prints the size of the specified file, subject + to the sizefmt format specification. + Attributes: + +
+
file
+ +
The value is a path relative to the directory + containing the current document being parsed.
+ +
virtual
+ +
The value is a (%-encoded) URL-path relative to the + current document being parsed. If it does not begin with + a slash (/) then it is taken to be relative to the + current document.
+
+
+ +
flastmod
+ +
This command prints the last modification date of the + specified file, subject to the timefmt format + specification. The attributes are the same as for the + fsize command.
+ +
include
+ +
+ This command inserts the text of another document or file + into the parsed file. Any included file is subject to the + usual access control. If the directory containing the + parsed file has the Option + IncludesNOEXEC set, and the including the document would + cause a program to be executed, then it will not be + included; this prevents the execution of CGI scripts. + Otherwise CGI scripts are invoked as normal using the + complete URL given in the command, including any query + string. + +

An attribute defines the location of the document; the + inclusion is done for each attribute given to the include + command. The valid attributes are:

+ +
+
file
+ +
The value is a path relative to the directory + containing the current document being parsed. It cannot + contain ../, nor can it be an absolute path. + Therefore, you cannot include files that are outside of the + document root, or above the current document in the directory + structure. + The virtual attribute should always be used + in preference to this one.
+ +
virtual
+ +
+

The value is a (%-encoded) URL relative to the + current document being parsed. The URL cannot contain a + scheme or hostname, only a path and an optional query + string. If it does not begin with a slash (/) then it is + taken to be relative to the current document.

+ +

A URL is constructed from the attribute, and the output the + server would return if the URL were accessed by the client + is included in the parsed output. Thus included files can + be nested.

+ +

If the specified URL is a CGI program, the program will + be executed and its output inserted in place of the directive + in the parsed file. You may include a query string in a CGI + url:

+ +
+ <!--#include virtual="/cgi-bin/example.cgi?argument=value" --> +
+ +

include virtual should be used in preference + to exec cgi to include the output of CGI + programs into an HTML document.

+
+
+
+ +
printenv
+ +
+

This prints out a listing of all existing variables and + their values. Starting with Apache 1.3.12, special characters + are entity encoded (see the echo element for details) + before being output. There are no attributes.

+ +

For example:

+ +
+ <!--#printenv --> +
+ +

The printenv element is available only in + Apache 1.2 and above.

+
+
set
+ +
+ This sets the value of a variable. Attributes: + +
+
var
+ +
The name of the variable to set.
+ +
value
+ +
The value to give a variable.
+
+

For example:

+ +
+ <!--#set var="category" value="help" --> +
+ +

The set element is available only in + Apache 1.2 and above.

+
+
+

Include Variables

+ + +

In addition to the variables in the standard CGI environment, + these are available for the echo command, for + if and elif, and to any program + invoked by the document.

+ +
+
DATE_GMT
+ +
The current date in Greenwich Mean Time.
+ +
DATE_LOCAL
+ +
The current date in the local time zone.
+ +
DOCUMENT_NAME
+ +
The filename (excluding directories) of the document + requested by the user.
+ +
DOCUMENT_URI
+ +
The (%-decoded) URL path of the document requested by the + user. Note that in the case of nested include files, this is + not then URL for the current document.
+ +
LAST_MODIFIED
+ +
The last modification date of the document requested by + the user.
+
+

Variable Substitution

+ + +

Variable substitution is done within quoted strings in most + cases where they may reasonably occur as an argument to an SSI + directive. This includes the config, + exec, flastmod, fsize, + include, echo, and set + directives, as well + as the arguments to conditional operators. You can insert a + literal dollar sign into the string using backslash + quoting:

+
+ <!--#if expr="$a = \$test" --> +
+ +

If a variable reference needs to be substituted in the + middle of a character sequence that might otherwise be + considered a valid identifier in its own right, it can be + disambiguated by enclosing the reference in braces, + a la shell substitution:

+ +
+ <!--#set var="Zed" value="${REMOTE_HOST}_${REQUEST_METHOD}" --> +
+ +

This will result in the Zed variable being set + to "X_Y" if REMOTE_HOST is + "X" and REQUEST_METHOD is + "Y".

+ +

EXAMPLE: the below example will print "in foo" if the + DOCUMENT_URI is /foo/file.html, "in bar" if it is + /bar/file.html and "in neither" otherwise:

+ +
+ <!--#if expr="\"$DOCUMENT_URI\" = \"/foo/file.html\"" -->
+ in foo
+ <!--#elif expr="\"$DOCUMENT_URI\" = \"/bar/file.html\"" -->
+ in bar
+ <!--#else -->
+ in neither
+ <!--#endif --> +
+

Flow Control Elements

+ + +

These are available in Apache 1.2 and above. The basic flow + control elements are:

+ +
+ <!--#if expr="test_condition" -->
+ <!--#elif expr="test_condition" -->
+ <!--#else -->
+ <!--#endif --> +
+ +

The if element works like an + if statement in a programming language. The test condition is + evaluated and if the result is true, then the text until the + next elif, + else. or + endif element is included in the + output stream.

+ +

The elif or + else statements are be used the + put text into the output stream if the original test_condition + was false. These elements are optional.

+ +

The endif element ends the + if element and is required.

+ +

test_condition is one of the following:

+ +
+
string
+ +
true if string is not empty
+ +
string1 = string2
+ string1 != string2
+ string1 < string2
+ string1 <= string2
+ string1 > string2
+ string1 >= string2
+ +
Compare string1 with string 2. If string2 has the form + /string/ then it is compared as a regular + expression. Regular expressions have the same syntax as those + found in the Unix egrep command.
+ +
( test_condition )
+ +
true if test_condition is true
+ +
! test_condition
+ +
true if test_condition is false
+ +
test_condition1 && + test_condition2
+ +
true if both test_condition1 and + test_condition2 are true
+ +
test_condition1 || test_condition2
+ +
true if either test_condition1 or + test_condition2 is true
+
+ +

"=" and "!=" bind more tightly than + "&&" and "||". "!" binds + most tightly. Thus, the following are equivalent:

+ +
+ <!--#if expr="$a = test1 && $b = test2" -->
+ <!--#if expr="($a = test1) && ($b = test2)" --> +
+ +

Anything that's not recognized as a variable or an operator + is treated as a string. Strings can also be quoted: + 'string'. Unquoted strings can't contain whitespace + (blanks and tabs) because it is used to separate tokens such as + variables. If multiple strings are found in a row, they are + concatenated using blanks. So,

+ +
+ 
string1    string2  results in string1 string2
+ 
'string1    string2' results in string1    string2
+
+ +

Using Server Side Includes for ErrorDocuments

+ + +

There is a document + which describes how to use the features of mod_include to offer + internationalized customized server error documents.

+ +

PATH_INFO with Server Side Includes

+ +

Files processed for server-side includes no longer accept + requests with PATH_INFO (trailing pathname information) by + default. You can use the AcceptPathInfo directive to + configure the server to accept requests with PATH_INFO.

+ +

SSIEndTag Directive

Description: Changes the string that mod_include looks for to end an +include command.
Syntax:SSIEndTag tag
Default:SSIEndTag "-->"
Context:server config, virtual host
Override:FileInfo
Status:Base
Module:mod_include
Compatibility:Available in version 2.0.30 and later. +
+

This directive changes the string that mod_include looks for + to mark the end of a include command.

+ +

See also

SSIErrorMsg Directive

Description: Changes the error message displayed when there is an error
Syntax:SSIErrorMsg message
Default:SSIErrorMsg +"[an error occurred while processing this directive]"
Context:server config, virtual host, directory, .htaccess
Override:
Status:Base
Module:mod_include
Compatibility:Available in version 2.0.30 and later.
+

The SSIErrorMsg directive changes the error message displayed + when mod_include encounters an error. For production servers you + may consider changing the default error message to + "<!-- Error -->" so that the message + is not presented to the user. +

+

This directive has the same effect as the <!--#config + errmsg=message --> element.

+ +

SSIStartTag Directive

Description:
Syntax:Changes the string that mod_include looks for to start an +include element
Default:SSIStartTag "<!--"
Context:server config, virtual host
Override:
Status:Base
Module:mod_include
Compatibility:Available in version 2.0.30 and later.
+ +

This directive changes the string that mod_include looks for + to mark an include element to process.

+ +

You may want to use this option if have 2 servers parsing the + output of a file each processing different commands (possibly at + different times).

+ +

See also

SSITimeFormat Directive

Description: Configures the format in which date strings are +displayed
Syntax:SSITimeFormat formatstring
Default:SSITimeFormat "%A, %d-%b-%Y %H:%M:%S %Z"
Context:server config, virtual host, directory, .htaccess
Override:
Status:Base
Module:mod_include
Compatibility:Available in version 2.0.30 and later.
+

This directive changes the format in which date strings are displayed + when echoing DATE environment variables. The formatstring + is as in strftime(3) from the C standard library.

+ +

This directive has the same effect as the <!--#config + timefmt=formatstring --> element.

+

SSIUndefinedEcho Directive

Description: Changes the string that mod_include displays when +a variable isn't set.
Syntax:SSIUndefinedEcho tag
Default:SSIUndefinedEcho "<!-- undef -->"
Context:server config, virtual host
Override:FileInfo
Status:Base
Module:mod_include
Compatibility:Available in version 2.0.34 and later. +
+

This directive changes the string that mod_include displays + when a variable is not set and "echoed".

+

XBitHack Directive

Description: Parse SSI directives in files with the execute +bit set
Syntax:XBitHack on|off|full
Default:XBitHack off
Context:server config, virtual host, directory, .htaccess
Override:Options
Status:Base
Module:mod_include
Compatibility:
+

The XBitHack directives controls the parsing of ordinary + html documents. This directive only affects files associated + with the MIME type text/html. XBitHack can take on + the following values:

+ +
+
off
+ +
No special treatment of executable files.
+ +
on
+ +
Any text/html file that has the user-execute bit set will + be treated as a server-parsed html document.
+ +
full
+ +
+ As for on but also test the group-execute bit. + If it is set, then set the Last-modified date of the + returned file to be the last modified time of the file. If + it is not set, then no last-modified date is sent. Setting + this bit allows clients and proxies to cache the result of + the request. + +
Note: you would not want to use the full + option, unless you assure the group-execute bit is unset for + every SSI script which might #include a CGI + or otherwise produces different output on each hit (or could + potentially change on subsequent requests).
+
+
+ +

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_info.html.en b/docs/manual/mod/mod_info.html.en new file mode 100644 index 0000000000..fb50fd7677 --- /dev/null +++ b/docs/manual/mod/mod_info.html.en @@ -0,0 +1,54 @@ +mod_info- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_info

Description:Provides a comprehensive overview of the server +configuration
Status:Extension
Module Identifier:info_module

Summary

+ +

To configure mod_info, add the following to your + httpd.conf file.

+ +
+<Location /server-info>
+SetHandler server-info
+</Location>
+
+ +

You may wish to add a + <Limit> + clause inside the + <location> + directive to limit access to your server configuration + information.

+ +

Once configured, the server information is obtained by + accessing http://your.host.dom/server-info

+ +
+ Note that the configuration files are read by the + module at run-time, and therefore the display may + not reflect the running server's active + configuration if the files have been changed since the server + was last reloaded. Also, the configuration files must be + readable by the user as which the server is running (see the + User directive), or + else the directive settings will not be listed. + +

It should also be noted that if + mod_info is compiled into the server, its + handler capability is available in all configuration + files, including per-directory files (e.g., + .htaccess). This may have security-related + ramifications for your site.

+
+

Directives

AddModuleInfo Directive

Description: Allows additional information to be added to the module +information displayed by the server-info handler
Syntax:AddModuleInfo module-name string
Context:server config, virtual +host
Status:Extension
Module:mod_info
Compatibility:Apache 1.3 and above
+

This allows the content of string to be shown as + HTML interpreted, Additional Information for + the module module-name. Example:

+ +
+AddModuleInfo mod_auth.c 'See <A HREF="http://www.apache.org/docs/mod/mod_auth.html">http://www.apache.org/docs/mod/mod_auth.html</A>' +
+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_isapi.html.en b/docs/manual/mod/mod_isapi.html.en new file mode 100644 index 0000000000..ed265912b3 --- /dev/null +++ b/docs/manual/mod/mod_isapi.html.en @@ -0,0 +1,205 @@ +mod_isapi- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_isapi

Description:ISAPI Extensions within Apache for Windows
Status:Base
Module Identifier:isapi_module
Compatibility:Win32 only

Summary

+

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.

+

Directives

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.

+

ISAPIAppendLogToErrors Directive

Description: Record HSE_APPEND_LOG_PARAMETER requests from ISAPI +extensions to the error log
Syntax:ISAPIAppendLogToErrors on|off
Default:ISAPIAppendLogToErrors off
Context:server config
Status:Base
Module:mod_isapi
+

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

+

ISAPIAppendLogToQuery Directive

Description: Record HSE_APPEND_LOG_PARAMETER requests from ISAPI +extensions to the query field
Syntax:ISAPIAppendLogToQuery on|off
Default:ISAPIAppendLogToQuery off
Context:server config
Status:Base
Module:mod_isapi
+

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

+

ISAPIFileChache Directive

Description: ISAPI .dll files to be loaded at startup
Syntax:ISAPIFileCache file-path [file-path] ...
Context:server config
Status:Base
Module:mod_isapi
+

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.

+

ISAPILogNotSupported Directive

Description: Log unsupported feature requests from ISAPI +extensions
Syntax:ISAPILogNotSupported on|off
Default:ISAPILogNotSupported on
Context:server config
Status:Base
Module:mod_isapi
+

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.

+

ISAPIReadAheadBuffer Directive

Description: Size of the Read Ahead Buffer sent to ISAPI +extensions
Syntax:ISAPIReadAheadBuffer size
Default:ISAPIReadAheadBuffer 49152
Context:server config
Status:Base
Module:mod_isapi
+

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.

+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_log_config.html.en b/docs/manual/mod/mod_log_config.html.en new file mode 100644 index 0000000000..0ff3a63292 --- /dev/null +++ b/docs/manual/mod/mod_log_config.html.en @@ -0,0 +1,322 @@ +mod_log_config- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_log_config

Description:Logging of the requests made to the server
Status:Base
Module Identifier:log_config_module

Summary

+ +

This module provides for flexible logging of client + requests. Logs are written in a customizable format, and may be + written directly to a file, or to an external program. + Conditional logging is provided so that individual requests may + be included or excluded from the logs based on characteristics + of the request.

+ +

Three directives are provided by this module: + TransferLog to create a log file, + LogFormat to set a custom format, and + CustomLog to define a log file and format in one + step. The TransferLog and CustomLog + directives can be used multiple times in each server to cause + each request to be logged to multiple files.

+

Directives

See also

Custom Log Formats

+ + +

The format argument to the LogFormat and + CustomLog directives is a string. This string is + logged to the log file for each request. It can contain literal + characters copied into the log files and the c-type control + characters "\n" and "\t" to represent new-lines and tabs. + Literal quotes and back-slashes should be escaped with + back-slashes.

+ +

The characteristics of the request itself are logged by + placing "%" directives in the format string, which are replaced + in the log file by the values as follows:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
%...a:Remote IP-address
%...A:Local IP-address
%...B:Bytes sent, excluding HTTP headers.
%...b:Bytes sent, excluding HTTP headers. In CLF format +i.e. a '-' rather than a 0 when no bytes are sent.
%...{Foobar}C:The contents of cookie "Foobar" in the request sent to the server.
%...D:The time taken to serve the request, in microseconds.
%...{FOOBAR}e:The contents of the environment variable FOOBAR
%...f:Filename
%...h:Remote host
%...HThe request protocol
%...{Foobar}i:The contents of Foobar: header line(s) in the request +sent to the server.
%...l:Remote logname (from identd, if supplied)
%...m:The request method
%...{Foobar}n:The contents of note "Foobar" from another module.
%...{Foobar}o:The contents of Foobar: header line(s) in the reply.
%...p:The canonical Port of the server serving the request
%...P:The process ID of the child that serviced the request.
%...q:The query string (prepended with a ? if a query string exists, +otherwise an empty string)
%...r:First line of request
%...s:Status. For requests that got internally redirected, this is +the status of the *original* request --- %...>s for the last.
%...t:Time, in common log format time format (standard english format)
%...{format}t:The time, in the form given by format, which should +be in strftime(3) format. (potentially localized)
%...T:The time taken to serve the request, in seconds.
%...u:Remote user (from auth; may be bogus if return status (%s) is 401)
%...U:The URL path requested, not including any query string.
%...v:The canonical ServerName of the server serving the request.
%...V:The server name according to the UseCanonicalName setting.
%...X:Connection status when response is completed. +
+'X' = connection aborted before the response completed.
+'+' = connection may be kept alive after the response is sent.
+'-' = connection will be closed after the response is sent. +
+
(This directive was %...c in late versions of Apache 1.3, but +this conflicted with the historical ssl %...{var}c syntax.)
+
+ +

The "..." can be nothing at all (e.g., "%h %u + %r %s %b"), or it can indicate conditions for inclusion + of the item (which will cause it to be replaced with "-" if the + condition is not met). The forms of condition are a list of + HTTP status codes, which may or may not be preceded by "!". + Thus, "%400,501{User-agent}i" logs User-agent: on 400 errors + and 501 errors (Bad Request, Not Implemented) only; + "%!200,304,302{Referer}i" logs Referer: on all requests which + did not return some sort of normal status.

+ +

Note that there is no escaping performed on the strings from + %...r, %...i and %...o. This is mainly to comply with the + requirements of the Common Log Format. This implies that + clients can insert control characters into the log, so care + should be taken when dealing with raw log files.

+ +

Some commonly used log format strings are:

+ +
+
Common Log Format (CLF)
+ +
"%h %l %u %t \"%r\" %>s %b"
+ +
Common Log Format with Virtual Host
+ +
"%v %h %l %u %t \"%r\" %>s %b"
+ +
NCSA extended/combined log format
+ +
"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" + \"%{User-agent}i\""
+ +
Referer log format
+ +
"%{Referer}i -> %U"
+ +
Agent (Browser) log format
+ +
"%{User-agent}i"
+
+ +

Note that the canonical ServerName and Listen of the server serving the + request are used for %v and %p + respectively. This happens regardless of the UseCanonicalName setting + because otherwise log analysis programs would have to duplicate + the entire vhost matching algorithm in order to decide what + host really served the request.

+

Security Considerations

+ + + +

See the security tips + document for details on why your security could be compromised + if the directory where logfiles are stored is writable by + anyone other than the user that starts the server.

+ +

CookieLog Directive

Description: Sets filename for the logging of cookies
Syntax:CookieLog filename
Context:server config, virtual +host
Status:Base
Module:mod_log_config
Compatibility:Only available in Apache 1.2 and above
+ +

The CookieLog directive sets the + filename for logging of cookies. The filename is relative to the + serverroot. This directive is + included only for compatibility with mod_cookies, + and is deprecated.

+

CustomLog Directive

Description: Sets filename and format of log file
Syntax:CustomLog + file|pipe format|nickname + [env=[!]environment-variable]
Context:server config, virtual +host
Status:Base
Module:mod_log_config
Compatibility:Nickname only available in Apache 1.3 or later. +Conditional logging available in 1.3.5 or later.
+

The CustomLog directive is used to + log requests to the server. A log format is specified, and the + logging can optionally be made conditional on request + characteristics using environment variables.

+ +

The first argument, which specifies the location to which + the logs will be written, can take on one of the following two + types of values:

+ +
+
file
+ +
A filename, relative to the ServerRoot.
+ +
pipe
+ +
The pipe character "|", followed by the path + to a program to receive the log information on its standard + input. Security: if a program is used, then + it will be run under the user who started httpd. This will be + root if the server was started by root; be sure that the + program is secure.
+
+ +

The second argument specifies what will be written to the + log file. It can specify either a nickname defined by + a previous LogFormat directive, or it + can be an explicit format string as described in the + log formats section.

+ +

For example, the following two sets of directives have + exactly the same effect:

+ +
+ # CustomLog with format nickname
+ LogFormat "%h %l %u %t \"%r\" %>s %b" common
+ CustomLog logs/access_log common
+
+ # CustomLog with explicit format string
+ CustomLog logs/access_log "%h %l %u %t \"%r\" %>s %b"
+
+ +

The third argument is optional and allows the decision on + whether or not to log a particular request to be based on the + presence or absence of a particular variable in the server + environment. If the specified environment + variable is set for the request (or is not set, in the case + of a 'env=!name' clause), then the + request will be logged.

+ +

Environment variables can be set on a per-request + basis using the mod_setenvif + and/or mod_rewrite modules. For + example, if you don't want to record requests for all GIF + images on your server in a separate logfile but not your main + log, you can use:

+ +
+ SetEnvIf Request_URI \.gif$ gif-image
+ CustomLog gif-requests.log common env=gif-image
+ CustomLog nongif-requests.log common env=!gif-image +
+

LogFormat Directive

Description: Describes a format for use in a log file
Syntax:LogFormat + format|nickname [nickname]
Context:server config, virtual +host
Status:Base
Module:mod_log_config
Compatibility:Nickname only available in Apache 1.3 or later. +
+

This directive specifies the format of the access log + file.

+ +

The LogFormat directive can take one of two + forms. In the first form, where only one argument is specified, + this directive sets the log format which will be used by logs + specified in subsequent TransferLog + directives. The single argument can specify an explicit + format as discussed in custom log + formats section above. Alternatively, it can use a + nickname to refer to a log format defined in a + previous LogFormat directive as described + below.

+ +

The second form of the LogFormat + directive associates an explicit format with a + nickname. This nickname can then be used in + subsequent LogFormat or + CustomLog directives rather than + repeating the entire format string. A + LogFormat + directive which defines a nickname does nothing + else -- that is, it only defines the + nickname, it doesn't actually apply the format and make it the + default. Therefore, it will not affect subsequent + TransferLog directives.

+ +

For example:

+ +
LogFormat "%v %h %l %u %t \"%r\" %>s %b" + vhost_common
+ +

TransferLog Directive

Description: Specifly location of a log file
Syntax:TransferLog file|pipe
Context:server config, virtual +host
Status:Base
Module:mod_log_config
Compatibility:
+ +

This directive has exactly the same arguments and effect as + the CustomLog directive, with the + exception that it does not allow the log format to be specified + explicitly or for conditional logging of requests. Instead, the + log format is determined by the most recently specified + specified LogFormat directive (which + does not define a nickname). Common Log Format is used if no + other format has been specified.

+ +

Example:

+
+ LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
+ TransferLog logs/access_log +
+ +

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_mime.html.en b/docs/manual/mod/mod_mime.html.en new file mode 100644 index 0000000000..1a23c8dcf4 --- /dev/null +++ b/docs/manual/mod/mod_mime.html.en @@ -0,0 +1,624 @@ +mod_mime- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_mime

Description:Associates the requested filename's extensions + with the file's behavior (handlers and filters) + and content (mime-type, language, character set and + encoding)
Status:Base
Module Identifier:mime_module

Summary

+

This module is used to associate various bits of "meta + information" with files by their filename extensions. This + information relates the filename of the document to it's + mime-type, language, character set and encoding. This + information is sent to the browser, and participates in content + negotiation, so the user's preferences are respected when + choosing one of several possible files to serve. See + mod_negotiation for more information + about content negotiation.

+ +

The directives AddCharset, AddEncoding, AddLanguage and AddType are all used to map file + extensions onto the meta-information for that file. Respectively + they set the character set, content-encoding, content-language, + and MIME-type (content-type) of documents. The directive TypesConfig is used to specify a + file which also maps extensions onto MIME types.

+ +

In addition, mod_mime may define the handler and filters that originate and process + content. The directives AddHandler, AddOutputFilter, and AddInputFilter control the modules + or scripts that serve the document. The MultiviewsMatch directive allows + mod_negotiation to consider these file extensions + to included when testing Multiviews matches.

+ +

While mod_mime associates meta-information + with filename extensions, the core server + provides directives that are used to associate all the files in a + given container (e.g., <location>, <directory>, or <Files>) with particular + meta-information. These directives include ForceType, SetHandler, SetInputFilter, and SetOutputFilter. The core directives + override any filename extension mappings defined in + mod_mime.

+ +

Note that changing the meta-information for a file does not + change the value of the Last-Modified header. + Thus, previously cached copies may still be used by a client or + proxy, with the previous headers. If you change the + meta-information (language, content type, character set or + encoding) you may need to 'touch' affected files (updating + their last modified date) to ensure that all visitors are + receive the corrected content headers.

+

Directives

See also

Files with Multiple Extensions

+ + +

Files can have more than one extension, and the order of the + extensions is normally irrelevant. For example, if the + file welcome.html.fr maps onto content type + text/html and language French then the file welcome.fr.html + will map onto exactly the same information. If more than one + extension is given which maps onto the same + type of meta-information, then the one to the right will be + used. For example, if ".gif" maps to the MIME-type image/gif + and ".html" maps to the MIME-type text/html, then the file + welcome.gif.html will be associated with the + MIME-type "text/html".

+ +

Care should be taken when a file with multiple extensions + gets associated with both a MIME-type and a handler. This will + usually result in the request being by the module associated + with the handler. For example, if the .imap + extension is mapped to the handler "imap-file" (from mod_imap) + and the .html extension is mapped to the MIME-type + "text/html", then the file world.imap.html will be + associated with both the "imap-file" handler and "text/html" + MIME-type. When it is processed, the "imap-file" handler will + be used, and so it will be treated as a mod_imap imagemap + file.

+

Content encoding

+ +

A file of a particular MIME type can additionally be encoded a + particular way to simplify transmission over the Internet. + While this usually will refer to compression, such as + gzip, it can also refer to encryption, such a + pgp or to an encoding such as UUencoding, which is + designed for transmitting a binary file in an ASCII (text) + format.

+ +

The MIME RFC puts it this way:

+ +
+ The Content-Encoding entity-header field is used as a + modifier to the media-type. When present, its value indicates + what additional content coding has been applied to the + resource, and thus what decoding mechanism must be applied in + order to obtain the media-type referenced by the Content-Type + header field. The Content-Encoding is primarily used to allow + a document to be compressed without losing the identity of + its underlying media type. +
+ +

By using more than one file extension (see section above about multiple file + extensions), you can indicate that a file is of a + particular type, and also has a particular + encoding.

+ +

For example, you may have a file which is a Microsoft Word + document, which is pkzipped to reduce its size. If the + .doc extension is associated with the Microsoft + Word file type, and the .zip extension is + associated with the pkzip file encoding, then the file + Resume.doc.zipwould be known to be a pkzip'ed Word + document.

+ +

Apache send a Content-encoding header with the + resource, in order to tell the client browser about the + encoding method.

+ +
Content-encoding: pkzip
+ +

Character sets and languages

+ + + +

In addition to file type and the file encoding, + another important piece of information is what language a + particular document is in, and in what character set the file + should be displayed. For example, the document might be written + in the Vietnamese alphabet, or in Cyrillic, and should be + displayed as such. This information, also, is transmitted in + HTTP headers.

+ +

The character set, language encoding and mime type are all + used in the process of content negotiation (See + mod_negotiation) to determine + which document to give to the client, when there are + alternative documents in more than one character set, language, + encoding or mime type. All filename extensions associations + created with AddCharset, AddEncoding, + AddLanguage and AddType directives + (and extensions listed in the MimeMagicFile) + participate in this select process. Filename extensions that + are only associated using the AddHandler, + AddInputFilter or AddOutputFilter + directives may be included or excluded from matching by using + the MultiviewsMatch directive.

+ +

Charset

+ + +

To convey this further information, Apache optionally sends + a Content-Language header, to specify the language + that the document is in, and can append additional information + onto the Content-Type header to indicate the + particular character set that should be used to correctly + render the information.

+ +
+Content-Language: en, fr
+Content-Type: text/plain; charset=ISO-8859-2 +
+ +

The language specification is the two-letter abbreviation + for the language. The charset is the name of the + particular character set which should be used.

+ +

AddCharset Directive

Description: Maps the given filename extensions + to the specified content charset
Syntax:AddCharset charset extension +[extension] ...
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Base
Module:mod_mime
Compatibility:AddCharset is only available in Apache +1.3.10 and later
+ +

The AddCharset directive maps the given filename extensions + to the specified content charset. charset is the MIME + charset parameter of filenames containing extension. + This mapping is added to any already in force, overriding any + mappings that already exist for the same extension.

+ +

Example:

+
+ AddLanguage ja .ja
+ AddCharset EUC-JP .euc
+ AddCharset ISO-2022-JP .jis
+ AddCharset SHIFT_JIS .sjis +
+ +

Then the document xxxx.ja.jis will be treated + as being a Japanese document whose charset is ISO-2022-JP (as + will the document xxxx.jis.ja). The AddCharset + directive is useful for both to inform the client about the + character encoding of the document so that the document can be + interpreted and displayed appropriately, and for content negotiation, + where the server returns one from several documents based on + the client's charset preference.

+ +

The extension argument is case-insensitive, and can + be specified with or without a leading dot.

+ +

See also

AddEncoding Directive

Description: Maps the given filename extensions + to the specified encoding type
Syntax:AddEncoding + MIME-enc extension [extension] ...
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Base
Module:mod_mime
+ +

The AddEncoding directive maps the given filename extensions + to the specified encoding type. MIME-enc is the MIME + encoding to use for documents containing the + extension. This mapping is added to any already in + force, overriding any mappings that already exist for the same + extension. Example:

+ +
+ AddEncoding x-gzip .gz
+ AddEncoding x-compress .Z +
+ +

This will cause filenames containing the .gz extension to be + marked as encoded using the x-gzip encoding, and filenames + containing the .Z extension to be marked as encoded with + x-compress.

+ +

Old clients expect x-gzip and + x-compress, however the standard dictates that + they're equivalent to gzip and + compress respectively. Apache does content + encoding comparisons by ignoring any leading x-. + When responding with an encoding Apache will use whatever form + (i.e., x-foo or foo) the + client requested. If the client didn't specifically request a + particular form Apache will use the form given by the + AddEncoding directive. To make this long story + short, you should always use x-gzip and + x-compress for these two specific encodings. More + recent encodings, such as deflate should be + specified without the x-.

+ +

The extension argument is case-insensitive, and can + be specified with or without a leading dot.

+ +

AddHandler Directive

Description: Maps the filename extensions +to the specified handler
Syntax:AddHandler + handler-name extension [extension] ...
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Base
Module:mod_mime
Compatibility:
+

Files having the named extension will be served by the +specified 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.

+ +

The extension argument is case-insensitive, and can + be specified with or without a leading dot.

+ +

See also

AddInputFilter Directive

Description: Maps filename extensions + to the filters that will process + client requests
Syntax:AddInputFilter + filter[;filter...] extension + [extension ...]
Context:server config, virtual host, directory, .htaccess
Status:Base
Module:mod_mime
Compatibility:AddInputFilter + is only available in Apache 2.0.26 and later.
+ +

AddInputFilter maps the filename extensions extension + to the filters which will process + client requests and POST input when they are received by the + server. This is in addition to any filters defined elsewhere, + including the SetInputFilter directive. + This mapping is merged over any already in force, overriding any + mappings that already exist for the same extension.

+ +

If more than one filter is specified, they must be separated + by semicolons in the order in which they should process the + content. Both the filter and extension arguments are + case-insensitive, and the extension may be specified with or + without a leading dot.

+ +

AddLanguage Directive

Description: Maps the given filename extension +to the specified content language
Syntax:AddLanguage + MIME-lang extension [extension] ...
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Base
Module:mod_mime
+ +

The AddLanguage directive maps the given filename extension + to the specified content language. MIME-lang is the + MIME language of filenames containing extension. This + mapping is added to any already in force, overriding any + mappings that already exist for the same + extension.

+ +

Example:

+ +
+ AddEncoding x-compress .Z
+ AddLanguage en .en
+ AddLanguage fr .fr +
+ +

Then the document xxxx.en.Z will be treated as + being a compressed English document (as will the document + xxxx.Z.en). Although the content language is + reported to the client, the browser is unlikely to use this + information. The AddLanguage directive is more useful for content negotiation, + where the server returns one from several documents based on + the client's language preference.

+ +

If multiple language assignments are made for the same + extension, the last one encountered is the one that is used. + That is, for the case of:

+ +
+ AddLanguage en .en
+ AddLanguage en-uk .en
+ AddLanguage en-us .en +
+ +

documents with the extension ".en" would be + treated as being "en-us".

+ +

The extension argument is case-insensitive, and can + be specified with or without a leading dot.

+ +

See also

AddOutputFilter Directive

Description: maps the filename +extensions to the filters that will process +responses from the server
Syntax:AddOutputFilter + filter[;filter...] extension + [extension ...]
Context:server config, virtual host, directory, .htaccess
Override:
Status:Base
Module:mod_mime
Compatibility:AddOutputFilter + is only available in Apache 2.0.26 and later.
+ +

The AddOutputFilter directive maps the + filename extensions extension to the filters which will process responses + from the server before they are sent to the client. This is in + addition to any filters defined elsewhere, including the + SetOutputFilter + directive. This mapping is merged over any already in force, + overriding any mappings that already exist for the same + extension.

+ +

For example, the following configuration will process all + .shtml files for server-side includes and will then compress + the output using mod_deflate.

+ + +
+ AddOutputFilter INCLUDES;DEFLATE shtml +
+ +

If more than one filter is specified, they must be separated + by semicolons in the order in which they should process the + content. Both the filter and extension arguments are + case-insensitive, and the extension may be specified with or + without a leading dot.

+ +

AddType Directive

Description: Maps the given filename extensions +onto the specified content type
Syntax:AddType MIME-type + extension [extension] ...
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Base
Module:mod_mime
+ +

The AddType directive maps the given filename extensions onto + the specified content type. MIME-type is the MIME type to + use for filenames containing extension. This mapping is + added to any already in force, overriding any mappings that + already exist for the same extension. This directive can + be used to add mappings not listed in the MIME types file (see the + TypesConfig + directive).

+ +

Example:

+ +
+ AddType image/gif .gif +
+ +
It is recommended that new MIME types be added using the + AddType directive rather than changing the + TypesConfig file.
+ +

The extension argument is case-insensitive, and can + be specified with or without a leading dot.

+ +

See also

DefaultLanguage Directive

Description: Sets all files in the given scope to the +specified language
Syntax:DefaultLanguage + MIME-lang
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Base
Module:mod_mime
Compatibility:DefaultLanguage + is only available in Apache 1.3.4 and later.
+ +

The DefaultLanguage directive tells Apache that all files in + the directive's scope (e.g., all files covered by the + current <Directory> container) that don't + have an explicit language extension (such as .fr + or .de as configured by AddLanguage) + should be considered to be in the specified MIME-lang + language. This allows entire directories to be marked as + containing Dutch content, for instance, without having to + rename each file. Note that unlike using extensions to specify + languages, DefaultLanguage can only specify a + single language.

+ +

If no DefaultLanguage directive is in force, + and a file does not have any language extensions as configured + by AddLanguage, then that file will be considered + to have no language attribute.

+ +

Example

+DeafaultLanguage en +
+ +

See also

MultiviewsMatch Directive

Description: The types of files that will be included when +searching for a matching file with MultiViews
Syntax:MultiviewsMatch + [NegotiatedOnly] [Handlers] [Filters] [Any]
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Base
Module:mod_mime
Compatibility:Available + in Apache 2.0.26 and later.
+ +

MultiviewsMatch permits three different behaviors for + mod_negotiation's Multiviews + feature. Multiviews allows a request for a file, e.g. index.html, + to match any negotiated extensions following the base request, + e.g. index.html.en, index.html,fr, or index.html.gz.

+ +

The NegotiatedOnly option provides that every extension following + the base name must correlate to a recognized mod_mime extension for + content negotation, e.g. Charset, Content-Type, Language, or + Encoding. This is the strictest implementation with the fewest + unexpected side effects, and is the default behavior.

+ +

To include extensions associated with Handlers and/or Filters, + set the MultiviewsMatch directive to either Handlers, Filters, or + both option keywords. If all other factors are equal, the smallest + file will be served, e.g. in deciding between index.html.cgi of 500 + characters and index.html.pl of 1000 bytes, the .cgi file would win + in this example. Users of .asis files might prefer to use the + Handler option, if .asis files are associated with the asis-handler.

+ +

You may finally allow Any extensions to match, even if mod_mime + doesn't recognize the extension. This was the behavior in Apache 1.3, + and can cause unpredicatable results, such as serving .old or .bak + files the webmaster never expected to be served.

+ +

For example, the following configuration will allow handlers + and filters to participate in Multviews, but will exclude unknown + files:

+
+MultiviewsMatch Handlers Filters +
+ +

See also

RemoveCharset Directive

Description: Removes any character set associations for a set of file +extensions
Syntax:RemoveCharset + extension [extension] ...
Context:directory, .htaccess
Status:Base
Module:mod_mime
Compatibility:RemoveCharset is + only available in Apache 2.0.24 and later.
+

The RemoveCharset directive removes any + character set associations for files with the given extensions. + This allows .htaccess files in subdirectories to + undo any associations inherited from parent directories or the + server config files.

+ +

The extension argument is case-insensitive, and can + be specified with or without a leading dot.

+ +

Example

+RemoveCharset .html .shtml +
+ +

RemoveEncoding Directive

Description: Removes any content encoding associations for a set of file +extensions
Syntax:RemoveEncoding + extension [extension] ...
Context:directory, .htaccess
Status:Base
Module:mod_mime
Compatibility:RemoveEncoding + is only available in Apache 1.3.13 and later.
+ +

The RemoveEncoding directive removes any + encoding associations for files with the given extensions. This + allows .htaccess files in subdirectories to undo + any associations inherited from parent directories or the + server config files. An example of its use might be:

+ + +
+
+
/foo/.htaccess:
+
AddEncoding x-gzip .gz
+ AddType text/plain .asc
+ <Files *.gz.asc>
+     RemoveEncoding + .gz
+ </Files>
+
+
+ +

This will cause foo.gz to be marked as being + encoded with the gzip method, but foo.gz.asc as an + unencoded plaintext file.

+ +

Note:RemoveEncoding directives are processed + after any AddEncoding directives, so it is possible they + may undo the effects of the latter if both occur within the + same directory configuration.

+ +

The extension argument is case-insensitive, and can + be specified with or without a leading dot.

+

RemoveHandler Directive

Description: Removes any handler associations for a set of file +extensions
Syntax:RemoveHandler + extension [extension] ...
Context:directory, .htaccess
Status:Base
Module:mod_mime
Compatibility:RemoveHandler is + only available in Apache 1.3.4 and later.
+ +

The RemoveHandler directive removes any handler + associations for files with the given extensions. This allows + .htaccess files in subdirectories to undo any + associations inherited from parent directories or the server + config files. An example of its use might be:

+ +
+
+
/foo/.htaccess:
+ +
AddHandler server-parsed .html
+ +
/foo/bar/.htaccess:
+ +
RemoveHandler .html
+
+
+ +

This has the effect of returning .html files in + the /foo/bar directory to being treated as normal + files, rather than as candidates for parsing (see the mod_include + module).

+ +

The extension argument is case-insensitive, and can + be specified with or without a leading dot.

+

RemoveInputFilter Directive

Description: Removes any input filter associations for a set of file +extensions
Syntax:RemoveInputFilter + extension [extension] ...
Context:directory, .htaccess
Status:Base
Module:mod_mime
Compatibility:RemoveInputFilter is only available in Apache +2.0.26 and later.
+ +

The RemoveInputFilter directive removes any + input filter associations for files with the given extensions. + This allows .htaccess files in subdirectories to + undo any associations inherited from parent directories or the + server config files.

+ +

The extension argument is case-insensitive, and can + be specified with or without a leading dot.

+ +

RemoveLanguage Directive

Description: Removes any language associations for a set of file +extensions
Syntax:RemoveLanguage + extension [extension] ...
Context:directory, .htaccess
Status:Base
Module:mod_mime
Compatibility:RemoveLanguage + is only available in Apache 2.0.24 and later.
+ +

The RemoveLanguage directive removes any + language associations for files with the given extensions. This + allows .htaccess files in subdirectories to undo + any associations inherited from parent directories or the + server config files.

+ +

The extension argument is case-insensitive, and can + be specified with or without a leading dot.

+

RemoveOutputFilter Directive

Description: Removes any output filter associations for a set of file +extensions
Syntax:RemoveOutputFilter + extension [extension] ...
Context:directory, .htaccess
Override:
Status:Base
Module:mod_mime
Compatibility:RemoveOutputFilter is only available in Apache +2.0.26 and later.
+ +

The RemoveOutputFilter directive removes any + output filter associations for files with the given extensions. + This allows .htaccess files in subdirectories to + undo any associations inherited from parent directories or the + server config files.

+ +

The extension argument is case-insensitive, and can + be specified with or without a leading dot.

+

RemoveType Directive

Description: Removes any content type associations for a set of file +extensions
Syntax:RemoveType + extension [extension] ...
Context:directory, .htaccess
Override:
Status:Base
Module:mod_mime
Compatibility:RemoveType is + only available in Apache 1.3.13 and later.
+

The RemoveType directive removes any MIME type + associations for files with the given extensions. This allows + .htaccess files in subdirectories to undo any + associations inherited from parent directories or the server + config files. An example of its use might be:

+ +
+
+
/foo/.htaccess:
+ +
RemoveType .cgi
+
+
+ +

This will remove any special handling of .cgi + files in the /foo/ directory and any beneath it, + causing the files to be treated as being of the default type.

+ +
Note:RemoveType directives + are processed after any AddType + directives, so it is possible they may undo the effects of the + latter if both occur within the same directory + configuration.
+ +

The extension argument is case-insensitive, and can + be specified with or without a leading dot.

+

TypesConfig Directive

Description: The location of the mime.types file
Syntax:TypesConfig file-path
Default:TypesConfig conf/mime.types
Context:server config
Status:Base
Module:mod_mime
+ +

The TypesConfig directive sets the location of the MIME types + configuration file. Filename is relative to the ServerRoot. This file sets the + default list of mappings from filename extensions to content + types. Most administrators use the provided + mime.types file, which associates common filename + extensions with IANA registered content types. The current list is + maintained at + http://www.isi.edu/in-notes/iana/assignments/media-types/media-types. This + simplifies the httpd.conf file by providing the + majority of media-type definitions, and may be overridden by + AddType directives as + needed. You should not edit the mime.types file, + because it may be replaced when you upgrade your server.

+ +

The file contains lines in the format of the arguments to + an AddType directive:

+ +
+ MIME-type extension extension ... +
+ +

+ The case of the extension does not matter. Blank lines, and lines + beginning with a hash character (`#') are ignored.

+ +
Please do not send requests to the Apache HTTP Server Project + to add any new entries in the distributed mime.types file + unless (1) they are already registered with IANA, and (2) they + use widely accepted, non-conflicting filename extensions across + platforms. category/x-subtype requests will be automatically + rejected, as will any new two-letter extensions as they will + likely conflict later with the already crowded language and + character set namespace.
+ +

See also

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_mime_magic.html.en b/docs/manual/mod/mod_mime_magic.html.en new file mode 100644 index 0000000000..bf3896c5d6 --- /dev/null +++ b/docs/manual/mod/mod_mime_magic.html.en @@ -0,0 +1,278 @@ +mod_mime_magic- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_mime_magic

Description:Determines the MIME type of a file + by looking at a few bytes of its contents
Status:Extension
Module Identifier:mime_magic_module

Summary

+

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.

+

Directives

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 Directive

Description: Enable MIME-type determination based on file contents +using the specified magic file
Syntax:MimeMagicFile file-path
Context:server config, virtual host
Status:Extension
Module:mod_mime_magic
+

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.

+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_negotiation.html.en b/docs/manual/mod/mod_negotiation.html.en new file mode 100644 index 0000000000..c8ec43fe48 --- /dev/null +++ b/docs/manual/mod/mod_negotiation.html.en @@ -0,0 +1,178 @@ +mod_negotiation- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_negotiation

Description:Provides for content negotiation
Status:Base
Module Identifier:negotiation_module

Summary

+

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.

+ + +

Directives

See also

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 Directive

Description: Allows content-negotiated documents to be +cached by proxy servers
Syntax:CacheNegotiatedDocs on|off
Default:CacheNegotiatedDocs off
Context:server config
Status:Base
Module:mod_negotiation
Compatibility: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.

+

ForceLanguagePriority Directive

Description: Action to take if a single acceptable document is not +found
Syntax:ForceLanguagePriority None|Prefer|Fallback [Prefer|Fallback]
Default:ForceLanguagePriority None
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Base
Module:mod_negotiation
Compatibility: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 language 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 Directive

Description: The precendence of language variants for cases where +the client does not express a preference
Syntax:LanguagePriority MIME-lang [MIME-lang] ...
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Base
Module:mod_negotiation
+

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.

+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_proxy.html.en b/docs/manual/mod/mod_proxy.html.en new file mode 100644 index 0000000000..b25350ba61 --- /dev/null +++ b/docs/manual/mod/mod_proxy.html.en @@ -0,0 +1,544 @@ +mod_proxy- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_proxy

Description:HTTP/1.1 proxy/gateway server
Status:Extension
Module Identifier:proxy_module

Summary

+

Warning

+This document has been updated to take into account changes +made in the 2.0 version of the Apache HTTP Server. Some of the +information may still be inaccurate, please use it +with care. +
+ +

This module implements a proxy/gateway for Apache. It implements +proxying capability for +FTP, +CONNECT (for SSL), +HTTP/0.9, +HTTP/1.0, and +HTTP/1.1. +The module can be configured to connect to other proxy modules for these +and other protocols.

+ +

This module was experimental in Apache 1.1.x. Improvements and bugfixes +were made in Apache v1.2.x and Apache v1.3.x, then the module underwent a major +overhaul for Apache v2.0. The protocol support was upgraded to HTTP/1.1, +and filter support was enabled.

+ +

Please note that the caching function present in +mod_proxy up to Apache v1.3.x has been removed from +mod_proxy and will be incorporated into a new module, mod_cache.

+ +

Do not enable proxying with ProxyRequests until you have +secured your server. Open proxy servers are +dangerous both to your network and to the Internet at large.

+ + +

Directives

Common configuration topics

+ + + +

Forward and Reverse Proxies

+ +

Apache can be configured in both a forward and reverse +proxy configuration.

+ +

A forward proxy is an intermediate system that enables a browser to connect to a +remote network to which it normally does not have access. A forward proxy +can also be used to cache data, reducing load on the networks between the +forward proxy and the remote webserver.

+ +

Apache's mod_proxy can be figured to behave like a forward proxy +using the ProxyRemote +directive. In addition, caching of data can be achieved by configuring +Apache mod_cache. Other dedicated forward proxy +packages include Squid.

+ +

A reverse proxy is a webserver system that is capable of serving webpages +sourced from other webservers - in addition to webpages on disk or generated +dynamically by CGI - making these pages look like they originated at the +reverse proxy.

+ +

When configured with the mod_cache module the reverse +proxy can act as a cache for slower backend webservers. The reverse proxy +can also enable advanced URL strategies and management techniques, allowing +webpages served using different webserver systems or architectures to +coexist inside the same URL space. Reverse proxy systems are also ideal for +implementing centralised logging websites with many or diverse website +backends. Complex multi-tier webserver systems can be constructed using an +Apache mod_proxy frontend and any number of backend webservers.

+ +

The reverse proxy is configured using the +ProxyPass and ProxyPassReverse directives. Caching can be +enabled using mod_cache as with the forward proxy.

+ + + +

Controlling access to your proxy

+ + + +

You can control who can access your proxy via the normal <Directory> +control block using the following example:

+ +
+<Directory proxy:*>
+Order Deny,Allow
+Deny from all
+Allow from 192.168.0
+</Directory> +
+ +

A <Files> block +will also work, and is the only method known to work for all possible +URLs in Apache versions earlier than 1.2b10.

+ +

When configuring a reverse proxy, access control takes on the +attributes of the normal server <directory> configuration.

+ + + + + + +

Why doesn't file type xxx +download via FTP?

+ +

You probably don't have that particular file type defined as +application/octet-stream in your proxy's mime.types configuration +file. A useful line can be

+ +
+application/octet-stream bin dms lha lzh exe class tgz taz +
+ + +

How can I force an FTP ASCII download of +File xxx?

+ +

In the rare situation where you must download a specific file using the FTP +ASCII transfer method (while the default transfer is in +binary mode), you can override mod_proxy's default by +suffixing the request with ;type=a to force an ASCII transfer. +(FTP Directory listings are always executed in ASCII mode, however.)

+ + +

How can I access FTP files outside +of my home directory?

+ +

+An FTP URI is interpreted relative to the home directory of the user +who is logging in. Alas, to reach higher directory levels you cannot +use /../, as the dots are interpreted by the browser and not actually +sent to the FTP server. To address this problem, the so called "Squid +%2f hack" was implemented in the Apache FTP proxy; it is is a solution +which is also used by other popular proxy servers like the Squid Proxy Cache. By +prepending /%2f to the path of your request, you can make such a proxy +change the FTP starting directory to / (instead of the home +directory).

+ +

Example: To retrieve the file +/etc/motd, you would use the URL

+
ftp://user@host/%2f/etc/motd
+ + +

How can I hide the FTP cleartext password +in my browser's URL line?

+ +

+To log in to an FTP server by username and password, Apache +uses different strategies. +In absense of a user name and password in the URL altogether, +Apache sends an anomymous login to the FTP server, i.e.,

+
+user: anonymous
+password: apache_proxy@ +
+

This works for all popular FTP servers which are configured for +anonymous access.

+ +

For a personal login with a specific username, you can embed +the user name into the URL, like in: +ftp://username@host/myfile. If the FTP server +asks for a password when given this username (which it should), +then Apache will reply with a [401 Authorization required] response, +which causes the Browser to pop up the username/password dialog. +Upon entering the password, the connection attempt is retried, +and if successful, the requested resource is presented. +The advantage of this procedure is that your browser does not +display the password in cleartext (which it would if you had used +ftp://username:password@host/myfile in +the first place).

+ +

Note

+The password which is transmitted in such a way +is not encrypted on its way. It travels between your browser and +the Apache proxy server in a base64-encoded cleartext string, and +between the Apache proxy and the FTP server as plaintext. You should +therefore think twice before accessing your FTP server via HTTP +(or before accessing your personal files via FTP at all!) When +using unsecure channels, an eavesdropper might intercept your +password on its way. +
+ + +

Why does Apache start more slowly when +using the proxy module?

+ +

If you're using the ProxyBlock +directive, hostnames' IP addresses are looked up and cached during +startup for later match test. This may take a few seconds (or more) +depending on the speed with which the hostname lookups occur.

+ + + + +

What other functions are useful for an +intranet proxy server?

+ +

An Apache proxy server situated in an intranet needs to forward +external requests through the company's firewall. However, when it has +to access resources within the intranet, it can bypass the firewall +when accessing hosts. The NoProxy directive is useful for +specifying which hosts belong to the intranet and should be accessed +directly.

+ +

Users within an intranet tend to omit the local domain name from their +WWW requests, thus requesting "http://somehost/" instead of +"http://somehost.my.dom.ain/". Some commercial proxy servers let them get +away with this and simply serve the request, implying a configured +local domain. When the ProxyDomain directive +is used and the server is configured for +proxy service, Apache can return a redirect response and send the client +to the correct, fully qualified, server address. This is the preferred method +since the user's bookmark files will then contain fully qualified hosts.

+ + +

AllowCONNECT Directive

Description:
Syntax:AllowCONNECT port [port] ...
Default:AllowCONNECT 443 563
Context:server config, virtual host
Status:Extension
Module:mod_proxy
+

The AllowCONNECT directive specifies a list +of port numbers to which the proxy CONNECT method may +connect. Today's browsers use this method when a https +connection is requested and proxy tunneling over http is in +effect.
By default, only the default https port (443) and the +default snews port (563) are enabled. Use the +AllowCONNECT directive to overrride this default and +allow connections to the listed ports only.

+

NoProxy Directive

Description:
Syntax:NoProxy + Domain| + SubNet| + IpAddr| + Hostname +[Domain| + SubNet| + IpAddr| + Hostname] ...
Context:server config, virtual host
Status:Extension
Module:mod_proxy
+

This directive is only useful for Apache proxy servers within +intranets. The NoProxy directive specifies a +list of subnets, IP addresses, hosts and/or domains, separated by +spaces. A request to a host which matches one or more of these is +always served directly, without forwarding to the configured +ProxyRemote proxy server(s).

+ +

Example

+ ProxyRemote * http://firewall.mycompany.com:81
+ NoProxy .mycompany.com 192.168.112.0/21 +
+ +

The arguments to the NoProxy directive are one of the following type list:

+
+ +
+ Domain
+
A Domain is a partially qualified DNS domain name, preceded + by a period. + It represents a list of hosts which logically belong to the same DNS + domain or zone (i.e., the suffixes of the hostnames are all ending in + Domain).
+ Examples: .com .apache.org.
+ To distinguish Domains from Hostnames (both + syntactically and semantically; a DNS domain can have a DNS A record, + too!), Domains are always written + with a leading period.
+ Note: Domain name comparisons are done without regard to the case, + and Domains are always assumed to be anchored in the root + of the DNS tree, therefore two domains .MyDomain.com and + .mydomain.com. (note the trailing period) are + considered equal. Since a domain comparison does not involve a DNS + lookup, it is much more efficient than subnet comparison.
+ + +
+ SubNet
+
A SubNet is a partially qualified internet address in + numeric (dotted quad) form, optionally followed by a slash and the + netmask, specified as the number of significant bits in the + SubNet. It is used to represent a subnet of hosts which can + be reached over a common network interface. In the absence of the + explicit net mask it is assumed that omitted (or zero valued) + trailing digits specify the mask. (In this case, the netmask can + only be multiples of 8 bits wide.)
+ Examples: +
+
192.168 or 192.168.0.0
+
the subnet 192.168.0.0 with an implied netmask of 16 valid bits + (sometimes used in the netmask form 255.255.0.0)
+
192.168.112.0/21
+
the subnet 192.168.112.0/21 with a netmask of 21 + valid bits (also used in the form 255.255.248.0)
+
+ As a degenerate case, a SubNet with 32 valid bits is the + equivalent to an IPAddr, while a SubNet with zero + valid bits (e.g., 0.0.0.0/0) is the same as the constant + _Default_, matching any IP address.
+ + +
+ IPAddr
+
A IPAddr represents a fully qualified internet address in + numeric (dotted quad) form. Usually, this address represents a + host, but there need not necessarily be a DNS domain name + connected with the address.
+ Example: 192.168.123.7
+ Note: An IPAddr does not need to be resolved by the DNS + system, so it can result in more effective apache performance.
+ + +
+ Hostname
+
A Hostname is a fully qualified DNS domain name which can + be resolved to one or more IPAddrs via the DNS domain name service. + It represents a logical host (in contrast to + Domains, see + above) and must be resolvable to at least one IPAddr (or often to a list of hosts + with different IPAddr's).
+ Examples: prep.ai.mit.edu + www.apache.org.
+ Note: In many situations, it is more effective to specify an + IPAddr in place of a + Hostname since a DNS lookup + can be avoided. Name resolution in Apache can take a remarkable deal + of time when the connection to the name server uses a slow PPP + link.
+ Note: Hostname comparisons are done without regard to the case, + and Hostnames are always assumed to be anchored in the root + of the DNS tree, therefore two hosts WWW.MyDomain.com + and www.mydomain.com. (note the trailing period) are + considered equal.
+
+

See also

ProxyBlock Directive

Description:
Syntax:ProxyBlock *|word|host|domain +[word|host|domain] ...
Context:server config, virtual host
Status:Extension
Module:mod_proxy
+

The ProxyBlock directive specifies a list of +words, hosts and/or domains, separated by spaces. HTTP, HTTPS, and +FTP document requests to sites whose names contain matched words, +hosts or domains are blocked by the proxy server. The proxy +module will also attempt to determine IP addresses of list items which +may be hostnames during startup, and cache them for match test as +well. Example:

+ +
+ ProxyBlock joes-garage.com some-host.co.uk rocky.wotsamattau.edu +
+ +

'rocky.wotsamattau.edu' would also be matched if referenced by IP +address.

+ +

Note that 'wotsamattau' would also be sufficient to match +'wotsamattau.edu'.

+ +

Note also that

+ +
+ProxyBlock * +
+ +

blocks connections to all sites.

+ +

ProxyDomain Directive

Description:
Syntax:ProxyDomain Domain
Context:server config, virtual host
Status:Extension
Module:mod_proxy
+

This directive is only useful for Apache proxy servers within +intranets. The ProxyDomain directive specifies +the default domain which the apache proxy server will belong to. If a +request to a host without a domain name is encountered, a redirection +response to the same host with the configured Domain appended +will be generated.

+ +

Example

+ ProxyRemote * http://firewall.mycompany.com:81
+ NoProxy .mycompany.com 192.168.112.0/21
+ ProxyDomain .mycompany.com +
+

ProxyErrorOverride Directive

Description:
Syntax:ProxyErrorOverride On|Off
Default:ProxyErrorOverride Off
Context:server config, virtual host
Status:Extension
Module:mod_proxy
Compatibility:Available in version 2.0 and later
+

This directive is useful for reverse-proxy setups, where you want to +have a common look and feel on the error pages seen by the end user. +This also allows for included files (via mod_include's SSI) to get +the error code and act accordingly (default behavior would display +the error page of the proxied server, turning this on shows the SSI +Error message).

+

ProxyMaxForwards Directive

Description:
Syntax:ProxyMaxForwards number
Default:ProxyMaxForwards 10
Context:server config, virtual host
Status:Extension
Module:mod_proxy
Compatibility:Available in Apache 2.0 and later
+

The ProxyMaxForwards directive specifies the +maximum number of proxies through which a request may pass. This is +set to prevent infinite proxy loops, or a DoS attack.

+ +

Example

+ ProxyMaxForwards 10 +
+

ProxyPass Directive

Description:
Syntax:ProxyPass [path] !|url
Context:server config, virtual host
Status:Extension
Module:mod_proxy
+ +

This directive allows remote servers to be mapped into the space of +the local server; the local server does not act as a proxy in the +conventional sense, but appears to be a mirror of the remote +server. path is the name of a local virtual path; +url is a partial URL for the remote server.

+ +

Suppose the local server has address http://wibble.org/; +then

+
+ ProxyPass /mirror/foo/ http://foo.com/ +
+

will cause a local request for the +<http://wibble.org/mirror/foo/bar> to be +internally converted into a proxy request to +<http://foo.com/bar>.

+

+The ! directive is useful in situations where you don't want to reverse-proxy +a subdirectory. eg.

+
+ ProxyPass /mirror/foo/i !
+ ProxyPass /mirror/foo http://foo.com +
+

will proxy all requests to /mirror/foo to foo.com EXCEPT requests made to /mirror/foo/i

+ +
NB: order is important. you need to put the exclusions BEFORE the general proxypass directive
+

ProxyPassReverse Directive

Description:
Syntax:ProxyPassReverse [path] url
Context:server config, virtual host
Status:Extension
Module:mod_proxy
+ +

This directive lets Apache adjust the URL in the Location, +Content-Location and URI headers on +HTTP redirect responses. This is essential when Apache is used as +a reverse proxy to avoid by-passing the reverse proxy because of HTTP +redirects on the backend servers which stay behind the reverse proxy.

+ +

path is the name of a local virtual path.
+url is a partial URL for the remote server - the same way they are +used for the ProxyPass directive.

+ +

+Example:
+Suppose the local server has address http://wibble.org/; then

+
+ ProxyPass /mirror/foo/ http://foo.com/
+ ProxyPassReverse /mirror/foo/ http://foo.com/ +
+

will not only cause a local request for the +<http://wibble.org/mirror/foo/bar> to be internally +converted into a proxy request to <http://foo.com/bar> (the +functionality ProxyPass provides here). It also takes care of +redirects the server foo.com sends: when http://foo.com/bar is +redirected by him to http://foo.com/quux Apache adjusts this to +http://wibble.org/mirror/foo/quux before forwarding the HTTP +redirect response to the client.

+

+Note that this ProxyPassReverse directive can +also be used in conjunction with the proxy pass-through feature +("RewriteRule ... [P]") from +mod_rewrite because its doesn't depend on a +corresponding ProxyPass +directive.

+

ProxyPreserveHost Directive

Description:
Syntax:ProxyPreserveHost on|off
Default:ProxyPreserveHost Off
Context:server config, virtual host
Status:Extension
Module:mod_proxy
Compatibility:Available in +Apache 2.0.31 and later.
+

When enabled, this option will pass the Host: line from the +incoming request to the proxied host, instead of the hostname +specified in the proxypass line. +

+

This option should normally be turned 'off'.

+

ProxyReceiveBufferSize Directive

Description:
Syntax:ProxyReceiveBufferSize bytes
Context:server config, virtual host
Status:Extension
Module:mod_proxy
+

The ProxyReceiveBufferSize directive +specifies an explicit network buffer size for outgoing HTTP and FTP +connections, for increased throughput. It has to be greater than 512 +or set to 0 to indicate that the system's default buffer size should +be used.

+

Example

+ ProxyReceiveBufferSize 2048 +
+

ProxyRemote Directive

Description:
Syntax:ProxyRemote match remote-server
Context:server config, virtual host
Status:Extension
Module:mod_proxy
+

This defines remote proxies to this proxy. match is either the +name of a URL-scheme that the remote server supports, or a partial URL +for which the remote server should be used, or '*' to indicate the +server should be contacted for all requests. remote-server is a +partial URL for the remote server. Syntax:

+ +
+  remote-server = protocol://hostname[:port]
+
+ +

protocol is the protocol that should be used to communicate +with the remote server; only "http" is supported by this module.

+ +

+Example:

+
+ ProxyRemote http://goodguys.com/ http://mirrorguys.com:8000
+ ProxyRemote * http://cleversite.com
+ ProxyRemote ftp http://ftpproxy.mydomain.com:8080 +
+ +

In the last example, the proxy will forward FTP requests, encapsulated +as yet another HTTP proxy request, to another proxy which can handle +them.

+ +

This option also supports reverse proxy configuration - a backend +webserver can be embedded within a virtualhost URL space even if that +server is hidden by another forward proxy.

+

ProxyRequests Directive

Description:
Syntax:ProxyRequests on|off
Default:ProxyRequests Off
Context:server config, virtual host
Status:Extension
Module:mod_proxy
+

This allows or prevents Apache from functioning as a forward proxy +server. (Setting ProxyRequests to 'off' does not disable use of the +ProxyPass directive.)

+ +

In a typical reverse proxy configuration, this option should be set to +'off'.

+ +

Do not enable proxying with ProxyRequests until you have +secured your server. Open proxy servers are +dangerous both to your network and to the Internet at large.

+ +

ProxyTimeout Directive

Description:
Syntax:ProxyTimeout seconds
Default:ProxyTimeout 300
Context:server config, virtual host
Status:Extension
Module:mod_proxy
Compatibility:Available in +Apache 2.0.31 and later
+

This directive allows a user to specifiy a timeout on proxy requests. +This is usefull when you have a slow/buggy appserver which hangs, +and you would rather just return a timeout and fail gracefully instead +of waiting however long it takes the server to return +

+

ProxyVia Directive

Description:
Syntax:ProxyVia on|off|full|block
Default:ProxyVia off
Context:server config, virtual host
Status:Extension
Module:mod_proxy
+

This directive controls the use of the Via: HTTP +header by the proxy. Its intended use is to control the flow of of +proxy requests along a chain of proxy servers. See RFC2068 (HTTP/1.1) +for an explanation of Via: header lines.

+ + +

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_rewrite.html.en b/docs/manual/mod/mod_rewrite.html.en new file mode 100644 index 0000000000..22e4932d76 --- /dev/null +++ b/docs/manual/mod/mod_rewrite.html.en @@ -0,0 +1,1628 @@ +mod_rewrite- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_rewrite

Description:Provides a rule-based rewriting engine to rewrite requested +URLs on the fly
Status:Extension
Module Identifier:rewrite_module
Compatibility:Available in Apache 1.3 and later

Summary

+
+ ``The great thing about mod_rewrite is it gives you + all the configurability and flexibility of Sendmail. + The downside to mod_rewrite is that it gives you all + the configurability and flexibility of Sendmail.''
+ +      -- Brian Behlendorf
+      Apache Group + +
+ +
+ `` Despite the tons of examples and docs, + mod_rewrite is voodoo. Damned cool voodoo, but still + voodoo. ''
+ +     -- Brian Moore
+      bem@news.cmc.net + +
+ + +

Welcome to mod_rewrite, the Swiss Army Knife of URL + manipulation!

+ +

This module uses a rule-based rewriting engine (based on a + regular-expression parser) to rewrite requested URLs on the + fly. It supports an unlimited number of rules and an + unlimited number of attached rule conditions for each rule to + provide a really flexible and powerful URL manipulation + mechanism. The URL manipulations can depend on various tests, + for instance server variables, environment variables, HTTP + headers, time stamps and even external database lookups in + various formats can be used to achieve a really granular URL + matching.

+ +

This module operates on the full URLs (including the + path-info part) both in per-server context + (httpd.conf) and per-directory context + (.htaccess) and can even generate query-string + parts on result. The rewritten result can lead to internal + sub-processing, external request redirection or even to an + internal proxy throughput.

+ +

But all this functionality and flexibility has its + drawback: complexity. So don't expect to understand this + entire module in just one day.

+ +

This module was invented and originally written in April + 1996 and gifted exclusively to the The Apache Group in July 1997 + by

+ +
+ Ralf S. + Engelschall
+ rse@engelschall.com
+ www.engelschall.com +
+

Directives

Interal Processing

+ +

The internal processing of this module is very complex but + needs to be explained once even to the average user to avoid + common mistakes and to let you exploit its full + functionality.

+ +

API Phases

+ +

First you have to understand that when Apache processes a + HTTP request it does this in phases. A hook for each of these + phases is provided by the Apache API. Mod_rewrite uses two of + these hooks: the URL-to-filename translation hook which is + used after the HTTP request has been read but before any + authorization starts and the Fixup hook which is triggered + after the authorization phases and after the per-directory + config files (.htaccess) have been read, but + before the content handler is activated.

+ +

So, after a request comes in and Apache has determined the + corresponding server (or virtual server) the rewriting engine + starts processing of all mod_rewrite directives from the + per-server configuration in the URL-to-filename phase. A few + steps later when the final data directories are found, the + per-directory configuration directives of mod_rewrite are + triggered in the Fixup phase. In both situations mod_rewrite + rewrites URLs either to new URLs or to filenames, although + there is no obvious distinction between them. This is a usage + of the API which was not intended to be this way when the API + was designed, but as of Apache 1.x this is the only way + mod_rewrite can operate. To make this point more clear + remember the following two points:

+ +
    +
  1. Although mod_rewrite rewrites URLs to URLs, URLs to + filenames and even filenames to filenames, the API + currently provides only a URL-to-filename hook. In Apache + 2.0 the two missing hooks will be added to make the + processing more clear. But this point has no drawbacks for + the user, it is just a fact which should be remembered: + Apache does more in the URL-to-filename hook than the API + intends for it.
    2. + +
  2. + Unbelievably mod_rewrite provides URL manipulations in + per-directory context, i.e., within + .htaccess files, although these are reached + a very long time after the URLs have been translated to + filenames. It has to be this way because + .htaccess files live in the filesystem, so + processing has already reached this stage. In other + words: According to the API phases at this time it is too + late for any URL manipulations. To overcome this chicken + and egg problem mod_rewrite uses a trick: When you + manipulate a URL/filename in per-directory context + mod_rewrite first rewrites the filename back to its + corresponding URL (which is usually impossible, but see + the RewriteBase directive below for the + trick to achieve this) and then initiates a new internal + sub-request with the new URL. This restarts processing of + the API phases. + +

    Again mod_rewrite tries hard to make this complicated + step totally transparent to the user, but you should + remember here: While URL manipulations in per-server + context are really fast and efficient, per-directory + rewrites are slow and inefficient due to this chicken and + egg problem. But on the other hand this is the only way + mod_rewrite can provide (locally restricted) URL + manipulations to the average user.

    +
    3. +
+ +

Don't forget these two points!

+ + +

Ruleset Processing

+ +

Now when mod_rewrite is triggered in these two API phases, it + reads the configured rulesets from its configuration + structure (which itself was either created on startup for + per-server context or during the directory walk of the Apache + kernel for per-directory context). Then the URL rewriting + engine is started with the contained ruleset (one or more + rules together with their conditions). The operation of the + URL rewriting engine itself is exactly the same for both + configuration contexts. Only the final result processing is + different.

+ +

The order of rules in the ruleset is important because the + rewriting engine processes them in a special (and not very + obvious) order. The rule is this: The rewriting engine loops + through the ruleset rule by rule (RewriteRule directives) and + when a particular rule matches it optionally loops through + existing corresponding conditions (RewriteCond + directives). For historical reasons the conditions are given + first, and so the control flow is a little bit long-winded. See + Figure 1 for more details.

+

+ [Needs graphics capability to display] +

Figure 1:The control flow through the rewriting ruleset

+ +

As you can see, first the URL is matched against the + Pattern of each rule. When it fails mod_rewrite + immediately stops processing this rule and continues with the + next rule. If the Pattern matches, mod_rewrite looks + for corresponding rule conditions. If none are present, it + just substitutes the URL with a new value which is + constructed from the string Substitution and goes on + with its rule-looping. But if conditions exist, it starts an + inner loop for processing them in the order that they are + listed. For conditions the logic is different: we don't match + a pattern against the current URL. Instead we first create a + string TestString by expanding variables, + back-references, map lookups, etc. and then we try + to match CondPattern against it. If the pattern + doesn't match, the complete set of conditions and the + corresponding rule fails. If the pattern matches, then the + next condition is processed until no more conditions are + available. If all conditions match, processing is continued + with the substitution of the URL with + Substitution.

+ + + +

Quoting Special Characters

+ +

As of Apache 1.3.20, special characters in + TestString and Substitution strings can be + escaped (that is, treated as normal characters without their + usual special meaning) by prefixing them with a slosh ('\') + character. In other words, you can include an actual + dollar-sign character in a Substitution string by + using '\$'; this keeps mod_rewrite from trying + to treat it as a backreference.

+ + +

Regex Back-Reference Availability

+ +

One important thing here has to be remembered: Whenever you + use parentheses in Pattern or in one of the + CondPattern, back-references are internally created + which can be used with the strings $N and + %N (see below). These are available for creating + the strings Substitution and TestString. + Figure 2 shows to which locations the back-references are + transfered for expansion.

+ +

+ [Needs graphics capability to display] +

Figure 2: The back-reference flow through a rule.

+ +

We know this was a crash course on mod_rewrite's internal + processing. But you will benefit from this knowledge when + reading the following documentation of the available + directives.

+ + +

Environment Variables

+ +

This module keeps track of two additional (non-standard) + CGI/SSI environment variables named SCRIPT_URL + and SCRIPT_URI. These contain the + logical Web-view to the current resource, while the + standard CGI/SSI variables SCRIPT_NAME and + SCRIPT_FILENAME contain the physical + System-view.

+ +

Notice: These variables hold the URI/URL as they were + initially requested, i.e., before any + rewriting. This is important because the rewriting process is + primarily used to rewrite logical URLs to physical + pathnames.

+ +

Example:

+ +
+
+SCRIPT_NAME=/sw/lib/w3s/tree/global/u/rse/.www/index.html
+SCRIPT_FILENAME=/u/rse/.www/index.html
+SCRIPT_URL=/u/rse/
+SCRIPT_URI=http://en1.engelschall.com/u/rse/
+
+
+ +

Practical Solutions

+ +

We also have an URL + Rewriting Guide available, which provides a collection of + practical solutions for URL-based problems. There you can + find real-life rulesets and additional information about + mod_rewrite.

+

RewriteBase Directive

Description: Sets the base URL for per-directory rewrites
Syntax:RewriteBase URL-path
Default:See usage for information.
Context:directory, .htaccess
Override:FileInfo
Status:Extension
Module:mod_rewrite
+

The RewriteBase directive explicitly + sets the base URL for per-directory rewrites. As you will see + below, RewriteRule + can be used in per-directory config files + (.htaccess). There it will act locally, + i.e., the local directory prefix is stripped at this + stage of processing and your rewriting rules act only on the + remainder. At the end it is automatically added back to the + path. The default setting is; RewriteBase physical-directory-path

+ +

When a substitution occurs for a new URL, this module has + to re-inject the URL into the server processing. To be able + to do this it needs to know what the corresponding URL-prefix + or URL-base is. By default this prefix is the corresponding + filepath itself. But at most websites URLs are NOT + directly related to physical filename paths, so this + assumption will usually be wrong! There you have to + use the RewriteBase directive to specify the + correct URL-prefix.

+ +
If your webserver's URLs are not directly +related to physical file paths, you have to use +RewriteBase in every .htaccess +files where you want to use RewriteRule directives. +
+ +

For example, assume the following per-directory config file:

+ +
+
+#
+#  /abc/def/.htaccess -- per-dir config file for directory /abc/def
+#  Remember: /abc/def is the physical path of /xyz, i.e., the server
+#            has a 'Alias /xyz /abc/def' directive e.g.
+#
+
+RewriteEngine On
+
+#  let the server know that we were reached via /xyz and not
+#  via the physical path prefix /abc/def
+RewriteBase   /xyz
+
+#  now the rewriting rules
+RewriteRule   ^oldstuff\.html$  newstuff.html
+
+
+ +

In the above example, a request to + /xyz/oldstuff.html gets correctly rewritten to + the physical file /abc/def/newstuff.html.

+ +

For Apache Hackers

+

The following list gives detailed information about + the internal processing steps:

+
+Request:
+  /xyz/oldstuff.html
+
+Internal Processing:
+  /xyz/oldstuff.html     -> /abc/def/oldstuff.html  (per-server Alias)
+  /abc/def/oldstuff.html -> /abc/def/newstuff.html  (per-dir    RewriteRule)
+  /abc/def/newstuff.html -> /xyz/newstuff.html      (per-dir    RewriteBase)
+  /xyz/newstuff.html     -> /abc/def/newstuff.html  (per-server Alias)
+
+Result:
+  /abc/def/newstuff.html
+
+

This seems very complicated but is + the correct Apache internal processing, because the + per-directory rewriting comes too late in the + process. So, when it occurs the (rewritten) request + has to be re-injected into the Apache kernel! BUT: + While this seems like a serious overhead, it really + isn't, because this re-injection happens fully + internally to the Apache server and the same + procedure is used by many other operations inside + Apache. So, you can be sure the design and + implementation is correct.

+
+ +

RewriteCond Directive

Description: Defines a condition under which rewriting will take place +
Syntax: RewriteCond + TestString CondPattern
Default:None
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Extension
Module:mod_rewrite
+

The RewriteCond directive defines a + rule condition. Precede a RewriteRule directive with one + or more RewriteCond directives. The following + rewriting rule is only used if its pattern matches the current + state of the URI and if these additional + conditions apply too.

+ +

TestString is a string which can contains the + following expanded constructs in addition to plain text:

+ + + +

Special Notes:

+ +
    +
  1. The variables SCRIPT_FILENAME and REQUEST_FILENAME + contain the same value, i.e., the value of the + filename field of the internal + request_rec structure of the Apache server. + The first name is just the commonly known CGI variable name + while the second is the consistent counterpart to + REQUEST_URI (which contains the value of the + uri field of request_rec).
    2. + +
  2. There is the special format: + %{ENV:variable} where variable can be + any environment variable. This is looked-up via internal + Apache structures and (if not found there) via + getenv() from the Apache server process.
    3. + +
  3. There is the special format: + %{HTTP:header} where header can be + any HTTP MIME-header name. This is looked-up from the HTTP + request. Example: %{HTTP:Proxy-Connection} is + the value of the HTTP header + ``Proxy-Connection:''.
    4. + +
  4. There is the special format + %{LA-U:variable} for look-aheads which perform + an internal (URL-based) sub-request to determine the final + value of variable. Use this when you want to use a + variable for rewriting which is actually set later in an + API phase and thus is not available at the current stage. + For instance when you want to rewrite according to the + REMOTE_USER variable from within the + per-server context (httpd.conf file) you have + to use %{LA-U:REMOTE_USER} because this + variable is set by the authorization phases which come + after the URL translation phase where mod_rewrite + operates. On the other hand, because mod_rewrite implements + its per-directory context (.htaccess file) via + the Fixup phase of the API and because the authorization + phases come before this phase, you just can use + %{REMOTE_USER} there.
    5. + +
  5. There is the special format: + %{LA-F:variable} which performs an internal + (filename-based) sub-request to determine the final value + of variable. Most of the time this is the same as + LA-U above.
    6. +
+ +

CondPattern is the condition pattern, + i.e., a regular expression which is applied to the + current instance of the TestString, i.e., + TestString is evaluated and then matched against + CondPattern.

+ +

Remember: CondPattern is a + standard Extended Regular Expression with some + additions:

+ +
    +
  1. You can prefix the pattern string with a + '!' character (exclamation mark) to specify a + non-matching pattern.
    2. + +
  2. + There are some special variants of CondPatterns. + Instead of real regular expression strings you can also + use one of the following: + +
      +
    • '<CondPattern' (is lexically + lower)
      + Treats the CondPattern as a plain string and + compares it lexically to TestString. True if + TestString is lexically lower than + CondPattern.
      • + +
    • '>CondPattern' (is lexically + greater)
      + Treats the CondPattern as a plain string and + compares it lexically to TestString. True if + TestString is lexically greater than + CondPattern.
      • + +
    • '=CondPattern' (is lexically + equal)
      + Treats the CondPattern as a plain string and + compares it lexically to TestString. True if + TestString is lexically equal to + CondPattern, i.e the two strings are exactly + equal (character by character). If CondPattern + is just "" (two quotation marks) this + compares TestString to the empty string.
      • + +
    • '-d' (is + directory)
      + Treats the TestString as a pathname and tests + if it exists and is a directory.
      • + +
    • '-f' (is regular + file)
      + Treats the TestString as a pathname and tests + if it exists and is a regular file.
      • + +
    • '-s' (is regular file with + size)
      + Treats the TestString as a pathname and tests + if it exists and is a regular file with size greater + than zero.
      • + +
    • '-l' (is symbolic + link)
      + Treats the TestString as a pathname and tests + if it exists and is a symbolic link.
      • + +
    • '-F' (is existing file via + subrequest)
      + Checks if TestString is a valid file and + accessible via all the server's currently-configured + access controls for that path. This uses an internal + subrequest to determine the check, so use it with care + because it decreases your servers performance!
      • + +
    • '-U' (is existing URL via + subrequest)
      + Checks if TestString is a valid URL and + accessible via all the server's currently-configured + access controls for that path. This uses an internal + subrequest to determine the check, so use it with care + because it decreases your server's performance!
      • +
    + +

    Notice

    + All of these tests can + also be prefixed by an exclamation mark ('!') to + negate their meaning. +
    +
    3. +
+ +

Additionally you can set special flags for + CondPattern by appending

+ +
+ [flags] +
+ +

as the third argument to the RewriteCond + directive. Flags is a comma-separated list of the + following flags:

+ + + +

Example:

+ +

To rewrite the Homepage of a site according to the + ``User-Agent:'' header of the request, you can + use the following:

+ +
+
+RewriteCond  %{HTTP_USER_AGENT}  ^Mozilla.*
+RewriteRule  ^/$                 /homepage.max.html  [L]
+
+RewriteCond  %{HTTP_USER_AGENT}  ^Lynx.*
+RewriteRule  ^/$                 /homepage.min.html  [L]
+
+RewriteRule  ^/$                 /homepage.std.html  [L]
+
+
+ +

Interpretation: If you use Netscape Navigator as your + browser (which identifies itself as 'Mozilla'), then you + get the max homepage, which includes Frames, etc. + If you use the Lynx browser (which is Terminal-based), then + you get the min homepage, which contains no images, no + tables, etc. If you use any other browser you get + the standard homepage.

+ +

RewriteEngine Directive

Description: Enables or disables runtime rewriting engine
Syntax:RewriteEngine on|off
Default:RewriteEngine off
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Extension
Module:mod_rewrite
+ +

The RewriteEngine directive enables or + disables the runtime rewriting engine. If it is set to + off this module does no runtime processing at + all. It does not even update the SCRIPT_URx + environment variables.

+ +

Use this directive to disable the module instead of + commenting out all the RewriteRule directives!

+ +

Note that, by default, rewrite configurations are not + inherited. This means that you need to have a + RewriteEngine on directive for each virtual host + in which you wish to use it.

+

RewriteLock Directive

Description: Sets the name of the lock file used for RewriteMap +synchronization
Syntax:RewriteLock file-path
Default:None
Context:server config
Status:Extension
Module:mod_rewrite
+

This directive sets the filename for a synchronization + lockfile which mod_rewrite needs to communicate with RewriteMap + programs. Set this lockfile to a local path (not on a + NFS-mounted device) when you want to use a rewriting + map-program. It is not required for other types of rewriting + maps.

+

RewriteLog Directive

Description: Sets the name of the file used for logging rewrite engine +processing
Syntax:RewriteLog file-path
Context:server config, virtual host
Status:Extension
Module:mod_rewrite
+

The RewriteLog directive sets the name + of the file to which the server logs any rewriting actions it + performs. If the name does not begin with a slash + ('/') then it is assumed to be relative to the + Server Root. The directive should occur only once per + server config.

+ +
To disable the logging of + rewriting actions it is not recommended to set + Filename to /dev/null, because + although the rewriting engine does not then output to a + logfile it still creates the logfile output internally. + This will slow down the server with no advantage + to the administrator! To disable logging either + remove or comment out the RewriteLog + directive or use RewriteLogLevel 0! +
+ +

Security

+ +See the Apache Security Tips +document for details on why your security could be compromised if the +directory where logfiles are stored is writable by anyone other than +the user that starts the server. +
+ +

Example

+RewriteLog "/usr/local/var/apache/logs/rewrite.log" +
+ +

RewriteLogLevel Directive

Description: Sets the verbosity of the log file used by the rewrite +engine
Syntax:RewriteLogLevel Level
Default:RerwiteLogLevel 0
Context:server config, virtual host
Status:Extension
Module:mod_rewrite
+

The RewriteLogLevel directive sets the + verbosity level of the rewriting logfile. The default level 0 + means no logging, while 9 or more means that practically all + actions are logged.

+ +

To disable the logging of rewriting actions simply set + Level to 0. This disables all rewrite action + logs.

+ +
Using a high value for + Level will slow down your Apache server + dramatically! Use the rewriting logfile at a + Level greater than 2 only for debugging! +
+ +

Example

+RewriteLogLevel 3 +
+ +

RewriteMap Directive

Description: Defines a mapping function for key-lookup
Syntax:RewriteMap MapName MapType:MapSource +
Default:None
Context:server config, virtual host
Status:Extension
Module:mod_rewrite
+

The RewriteMap directive defines a + Rewriting Map which can be used inside rule + substitution strings by the mapping-functions to + insert/substitute fields through a key lookup. The source of + this lookup can be of various types.

+ +

The MapName is + the name of the map and will be used to specify a + mapping-function for the substitution strings of a rewriting + rule via one of the following constructs:

+ +
+ ${ MapName : + LookupKey }
+ ${ MapName : + LookupKey | DefaultValue + } +
+ +

When such a construct occurs the map MapName is + consulted and the key LookupKey is looked-up. If the + key is found, the map-function construct is substituted by + SubstValue. If the key is not found then it is + substituted by DefaultValue or by the empty string + if no DefaultValue was specified.

+ +

The following combinations for MapType and + MapSource can be used:

+ + +

The RewriteMap directive can occur more than + once. For each mapping-function use one + RewriteMap directive to declare its rewriting + mapfile. While you cannot declare a map in + per-directory context it is of course possible to + use this map in per-directory context.

+ +

Note

For plain text and DBM format files the +looked-up keys are cached in-core until the mtime of the +mapfile changes or the server does a restart. This way you can have +map-functions in rules which are used for every +request. This is no problem, because the external lookup only happens +once! +
+ +

RewriteOptions Directive

Description: Sets some special options for the rewrite engine
Syntax:RewriteOptions Options
Default:None
Context:server config, virtual host, directory, .htaccess
Status:Extension
Module:mod_rewrite
+ +

The RewriteOptions directive sets some + special options for the current per-server or per-directory + configuration. The Option strings can be one of the + following:

+ + +

RewriteRule Directive

Description: Defines rules for the rewriting engine
Syntax:RewriteRule + Pattern Substitution
Default:None
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Extension
Module:mod_rewrite
+

The RewriteRule directive is the real + rewriting workhorse. The directive can occur more than once. + Each directive then defines one single rewriting rule. The + definition order of these rules is + important, because this order is used when + applying the rules at run-time.

+ +

Pattern can + be (for Apache 1.1.x a System V8 and for Apache 1.2.x and + later a POSIX) regular + expression which gets applied to the current URL. Here + ``current'' means the value of the URL when this rule gets + applied. This may not be the originally requested URL, + because any number of rules may already have matched and made + alterations to it.

+ +

Some hints about the syntax of regular expressions:

+ + + + + +
+
+Text:
+  .           Any single character
+  [chars]     Character class: One  of chars
+  [^chars]    Character class: None of chars
+  text1|text2 Alternative: text1 or text2
+
+Quantifiers:
+  ?           0 or 1 of the preceding text
+  *           0 or N of the preceding text (N > 0)
+  +           1 or N of the preceding text (N > 1)
+
+Grouping:
+  (text)      Grouping of text
+              (either to set the borders of an alternative or
+              for making backreferences where the Nth group can 
+              be used on the RHS of a RewriteRule with $N)
+
+Anchors:
+  ^           Start of line anchor
+  $           End   of line anchor
+
+Escaping:
+  \char       escape that particular char
+              (for instance to specify the chars ".[]()" etc.)
+
+
+ +

For more information about regular expressions either have + a look at your local regex(3) manpage or its + src/regex/regex.3 copy in the Apache 1.3 + distribution. If you are interested in more detailed + information about regular expressions and their variants + (POSIX regex, Perl regex, etc.) have a look at the + following dedicated book on this topic:

+ +
+ Mastering Regular Expressions
+ Jeffrey E.F. Friedl
+ Nutshell Handbook Series
+ O'Reilly & Associates, Inc. 1997
+ ISBN 1-56592-257-3
+
+ +

Additionally in mod_rewrite the NOT character + ('!') is a possible pattern prefix. This gives + you the ability to negate a pattern; to say, for instance: + ``if the current URL does NOT match this + pattern''. This can be used for exceptional cases, where + it is easier to match the negative pattern, or as a last + default rule.

+ +

Notice

+When using the NOT character + to negate a pattern you cannot have grouped wildcard + parts in the pattern. This is impossible because when the + pattern does NOT match, there are no contents for the + groups. In consequence, if negated patterns are used, you + cannot use $N in the substitution + string! +
+ +

Substitution of a + rewriting rule is the string which is substituted for (or + replaces) the original URL for which Pattern + matched. Beside plain text you can use

+ +
    +
  1. back-references $N to the RewriteRule + pattern
    2. + +
  2. back-references %N to the last matched + RewriteCond pattern
    3. + +
  3. server-variables as in rule condition test-strings + (%{VARNAME})
    4. + +
  4. mapping-function calls + (${mapname:key|default})
    5. +
+

Back-references are $N + (N=0..9) identifiers which will be replaced + by the contents of the Nth group of the + matched Pattern. The server-variables are the same + as for the TestString of a RewriteCond + directive. The mapping-functions come from the + RewriteMap directive and are explained there. + These three types of variables are expanded in the order of + the above list.

+ +

As already mentioned above, all the rewriting rules are + applied to the Substitution (in the order of + definition in the config file). The URL is completely + replaced by the Substitution and the + rewriting process goes on until there are no more rules + unless explicitly terminated by a + L flag - see below.

+ +

There is a special substitution string named + '-' which means: NO + substitution! Sounds silly? No, it is useful to + provide rewriting rules which only match + some URLs but do no substitution, e.g., in + conjunction with the C (chain) flag to be + able to have more than one pattern to be applied before a + substitution occurs.

+ +

One more note: You can even create URLs in the + substitution string containing a query string part. Just use + a question mark inside the substitution string to indicate + that the following stuff should be re-injected into the + QUERY_STRING. When you want to erase an existing query + string, end the substitution string with just the question + mark.

+ +

Note

+There is a special feature: + When you prefix a substitution field with + http://thishost[:thisport] + then mod_rewrite automatically strips it + out. This auto-reduction on implicit external redirect + URLs is a useful and important feature when used in + combination with a mapping-function which generates the + hostname part. Have a look at the first example in the + example section below to understand this. +
+ +

Remember

+ An unconditional external + redirect to your own server will not work with the prefix + http://thishost because of this feature. To + achieve such a self-redirect, you have to use the + R-flag (see below). +
+ +

Additionally you can set special flags for + Substitution by appending

+ +
+ [flags] +
+

+ as the third argument to the RewriteRule + directive. Flags is a comma-separated list of the + following flags:

+ + + +

Note

Never forget that Pattern is +applied to a complete URL in per-server configuration +files. But in per-directory configuration files, the +per-directory prefix (which always is the same for a specific +directory!) is automatically removed for the pattern matching +and automatically added after the substitution has been +done. This feature is essential for many sorts of rewriting, +because without this prefix stripping you have to match the parent +directory which is not always possible. + +

There is one exception: If a substitution string + starts with ``http://'' then the directory + prefix will not be added and an + external redirect or proxy throughput (if flag + P is used!) is forced!

+
+ +

Note

+ To enable the rewriting engine + for per-directory configuration files you need to set + ``RewriteEngine On'' in these files + and ``Options + FollowSymLinks'' must be enabled. If your + administrator has disabled override of + FollowSymLinks for a user's directory, then + you cannot use the rewriting engine. This restriction is + needed for security reasons. +
+ +

Here are all possible substitution combinations and their + meanings:

+ +

Inside per-server configuration + (httpd.conf)
+ for request ``GET + /somepath/pathinfo'':
+

+ + + + + +
+
+Given Rule                                      Resulting Substitution
+----------------------------------------------  ----------------------------------
+^/somepath(.*) otherpath$1                      not supported, because invalid!
+
+^/somepath(.*) otherpath$1  [R]                 not supported, because invalid!
+
+^/somepath(.*) otherpath$1  [P]                 not supported, because invalid!
+----------------------------------------------  ----------------------------------
+^/somepath(.*) /otherpath$1                     /otherpath/pathinfo
+
+^/somepath(.*) /otherpath$1 [R]                 http://thishost/otherpath/pathinfo
+                                                via external redirection
+
+^/somepath(.*) /otherpath$1 [P]                 not supported, because silly!
+----------------------------------------------  ----------------------------------
+^/somepath(.*) http://thishost/otherpath$1      /otherpath/pathinfo
+
+^/somepath(.*) http://thishost/otherpath$1 [R]  http://thishost/otherpath/pathinfo
+                                                via external redirection
+
+^/somepath(.*) http://thishost/otherpath$1 [P]  not supported, because silly!
+----------------------------------------------  ----------------------------------
+^/somepath(.*) http://otherhost/otherpath$1     http://otherhost/otherpath/pathinfo
+                                                via external redirection
+
+^/somepath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo
+                                                via external redirection
+                                                (the [R] flag is redundant)
+
+^/somepath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo
+                                                via internal proxy
+
+
+ +

Inside per-directory configuration for + /somepath
+ (i.e., file .htaccess in dir + /physical/path/to/somepath containing + RewriteBase /somepath)
+ for request ``GET + /somepath/localpath/pathinfo'':
+

+ + + + + +
+
+Given Rule                                      Resulting Substitution
+----------------------------------------------  ----------------------------------
+^localpath(.*) otherpath$1                      /somepath/otherpath/pathinfo
+
+^localpath(.*) otherpath$1  [R]                 http://thishost/somepath/otherpath/pathinfo
+                                                via external redirection
+
+^localpath(.*) otherpath$1  [P]                 not supported, because silly!
+----------------------------------------------  ----------------------------------
+^localpath(.*) /otherpath$1                     /otherpath/pathinfo
+
+^localpath(.*) /otherpath$1 [R]                 http://thishost/otherpath/pathinfo
+                                                via external redirection
+
+^localpath(.*) /otherpath$1 [P]                 not supported, because silly!
+----------------------------------------------  ----------------------------------
+^localpath(.*) http://thishost/otherpath$1      /otherpath/pathinfo
+
+^localpath(.*) http://thishost/otherpath$1 [R]  http://thishost/otherpath/pathinfo
+                                                via external redirection
+
+^localpath(.*) http://thishost/otherpath$1 [P]  not supported, because silly!
+----------------------------------------------  ----------------------------------
+^localpath(.*) http://otherhost/otherpath$1     http://otherhost/otherpath/pathinfo
+                                                via external redirection
+
+^localpath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo
+                                                via external redirection
+                                                (the [R] flag is redundant)
+
+^localpath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo
+                                                via internal proxy
+
+
+ +

Example:

+ +

We want to rewrite URLs of the form

+ +
+ / Language /~ + Realname /.../ File +
+ +

into

+ +
+ /u/ Username /.../ + File . Language +
+ +

We take the rewrite mapfile from above and save it under + /path/to/file/map.txt. Then we only have to + add the following lines to the Apache server configuration + file:

+ +
+
+RewriteLog   /path/to/file/rewrite.log
+RewriteMap   real-to-user               txt:/path/to/file/map.txt
+RewriteRule  ^/([^/]+)/~([^/]+)/(.*)$   /u/${real-to-user:$2|nobody}/$3.$1
+
+
+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_setenvif.html.en b/docs/manual/mod/mod_setenvif.html.en new file mode 100644 index 0000000000..2759b874cc --- /dev/null +++ b/docs/manual/mod/mod_setenvif.html.en @@ -0,0 +1,194 @@ +mod_setenvif- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_setenvif

Description:Allows the setting of environment variables based +on characteristics of the request
Status:Base
Module Identifier:setenvif_module
Compatibility:Available in Apache 1.3 and later

Summary

+ +

The mod_setenvif module allows you to set + environment variables according to whether different aspects of + the request match regular expressions you specify. These + environment variables can be used by other parts of the server + to make decisions about actions to be taken.

+ +

The directives are considered in the order they appear in + the configuration files. So more complex sequences can be used, + such as this example, which sets netscape if the + browser is mozilla but not MSIE.

+ +
+ BrowserMatch ^Mozilla netscape
+ BrowserMatch MSIE !netscape
+
+

Directives

See also

BrowserMatch Directive

Description: Sets environment variables conditional on HTTP User-Agent +
Syntax:BrowserMatch regex env-variable[=value] +[env-variable[=value]] ...
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Base
Module:mod_setenvif
Compatibility:Apache 1.2 and + above (in Apache 1.2 this directive was found in the + now-obsolete mod_browser module)
+

The BrowserMatch directive defines + environment variables based on the User-Agent HTTP + request header field. The first argument should be a POSIX.2 + extended regular expression (similar to an + egrep-style regex). The rest of the arguments give + the names of variables to set, and optionally values to which they + should be set. These take the form of

+ +
    +
  1. varname, or
    2. + +
  2. !varname, or
    3. + +
  3. varname=value
    4. +
+ +

In the first form, the value will be set to "1". The second + will remove the given variable if already defined, and the + third will set the variable to the value given by + value. If a User-Agent + string matches more than one entry, they will be merged. + Entries are processed in the order in which they appear, and + later entries can override earlier ones.

+ +

For example:

+
+ BrowserMatch ^Mozilla forms jpeg=yes browser=netscape
+ BrowserMatch "^Mozilla/[2-3]" tables agif frames javascript
+ BrowserMatch MSIE !javascript
+
+ +

Note that the regular expression string is + case-sensitive. For case-INsensitive matching, + see the BrowserMatchNoCase + directive.

+ +

The BrowserMatch and + BrowserMatchNoCase directives are special cases of + the SetEnvIf and SetEnvIfNoCase + directives. The following two lines have the same effect:

+
+ BrowserMatchNoCase Robot is_a_robot
+ SetEnvIfNoCase User-Agent Robot is_a_robot
+
+

BrowserMatchNoCase Directive

Description: Sets environment variables conditional on User-Agent without +respect to case
Syntax:BrowserMatchNoCase regex env-variable[=value] + [env-variable[=value]] ...
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Base
Module:mod_setenvif
Compatibility:Apache 1.2 and + above (in Apache 1.2 this directive was found in the + now-obsolete mod_browser module)
+ +

The BrowserMatchNoCase directive is + semantically identical to the BrowserMatch directive. + However, it provides for case-insensitive matching. For + example:

+
+ BrowserMatchNoCase mac platform=macintosh
+ BrowserMatchNoCase win platform=windows
+
+ +

The BrowserMatch and + BrowserMatchNoCase directives are special cases of + the SetEnvIf and SetEnvIfNoCase + directives. The following two lines have the same effect:

+
+ BrowserMatchNoCase Robot is_a_robot
+ SetEnvIfNoCase User-Agent Robot is_a_robot
+
+

SetEnvIf Directive

Description: Sets environment variables based on attributes of the request +
Syntax:SetEnvIf attribute + regex env-variable[=value] + [env-variable[=value]] ...
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Base
Module:mod_setenvif
Compatibility:Apache 1.3 and + above; the Request_Protocol keyword and environment-variable + matching are only available with 1.3.7 and later
+

The SetEnvIf directive defines environment + variables based on attributes of the request. These attributes + can be the values of various HTTP request header fields (see RFC2616 + for more information about these), or of other aspects of the + request, including the following:

+ + + +

Some of the more commonly used request header field names + include Host, User-Agent, and + Referer.

+ +

If the attribute name doesn't match any of the + special keywords, nor any of the request's header field names, + it is tested as the name of an environment variable in the list + of those associated with the request. This allows + SetEnvIf directives to test against the result of + prior matches.

+ +
+ Only those environment variables defined by earlier + SetEnvIf[NoCase] directives are available for + testing in this manner. 'Earlier' means that they were + defined at a broader scope (such as server-wide) or + previously in the current directive's scope. +
+ +

attribute may be a regular expression when used to + match a request header. If attribute is a regular + expression and it doesn't match any of the request's header + names, then attribute is not tested against the + request's environment variable list.

+ +

Example:

+ + SetEnvIf Request_URI "\.gif$" object_is_image=gif
+ SetEnvIf Request_URI "\.jpg$" object_is_image=jpg
+ SetEnvIf Request_URI "\.xbm$" object_is_image=xbm
+ :
+ SetEnvIf Referer www\.mydomain\.com intra_site_referral
+ :
+ SetEnvIf object_is_image xbm XBIT_PROCESSING=1
+ :
+ SetEnvIf ^TS* ^[a-z].* HAVE_TS
+
+ +

The first three will set the environment variable + object_is_image if the request was for an image + file, and the fourth sets intra_site_referral if + the referring page was somewhere on the + www.mydomain.com Web site.

+ +

The last example will set environment variable + HAVE_TS if the request contains any headers that + begin with "TS" whose values begins with any character in the + set [a-z].

+

SetEnvIfNoCase Directive

Description: Sets environment variables based on attributes of the request +without respect to case
Syntax:SetEnvIfNoCase attribute regex env-variable[=value] + [env-variable[=value]] ...
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Base
Module:mod_setenvif
Compatibility:Apache 1.3 and above
+ +

The SetEnvIfNoCase is semantically identical to + the SetEnvIf directive, + and differs only in that the regular expression matching is + performed in a case-insensitive manner. For example:

+
+ SetEnvIfNoCase Host Apache\.Org site=apache +
+ +

This will cause the site environment variable + to be set to "apache" if the HTTP request header + field Host: was included and contained + Apache.Org, apache.org, or any other + combination.

+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_so.html.en b/docs/manual/mod/mod_so.html.en new file mode 100644 index 0000000000..92b67c5aa9 --- /dev/null +++ b/docs/manual/mod/mod_so.html.en @@ -0,0 +1,126 @@ +mod_so- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_so

Description: + This module provides for loading of executable code and + modules into the server at start-up or restart time. +
Status:Base (Windows>; Optional (Unix)
Module Identifier:so_module
Compatibility:Available in Apache 1.3 and later.

Summary

+ +

On selected operating systems this module can be used to + load modules into Apache at runtime via the Dynamic Shared Object (DSO) mechanism, + rather than requiring a recompilation.

+ +

On Unix, the loaded code typically comes from shared object + files (usually with .so extension), on Windows + this may either the .so or .dll + extension. This module is only available in Apache 1.3 and + up.

+ +

In previous releases, the functionality of this module was + provided for Unix by mod_dld, and for Windows by mod_dll. On + Windows, mod_dll was used in beta release 1.3b1 through 1.3b5. + mod_so combines these two modules into a single module for all + operating systems.

+

Warning

+

Apache 1.3 modules cannot be directly used + with Apache 2.0 - the module must be modified to dynamically + load or compile into Apache 2.0.

+
+

Directives

Creating Loadable Modules for Windows

+ +

Note

+

The module name format changed for Windows + with Apache 1.3.15 and 2.0 - the modules are now named as + mod_foo.so

+

While mod_so still loads modules with + ApacheModuleFoo.dll names, the new naming convention is + preferred; if you are converting your loadable module for 2.0, + please fix the name to this 2.0 convention.

+ +

The Apache module API is unchanged between the Unix and + Windows versions. Many modules will run on Windows with no or + little change from Unix, although others rely on aspects of the + Unix architecture which are not present in Windows, and will + not work.

+ +

When a module does work, it can be added to the server in + one of two ways. As with Unix, it can be compiled into the + server. Because Apache for Windows does not have the + Configure program of Apache for Unix, the module's + source file must be added to the ApacheCore project file, and + its symbols must be added to the + os\win32\modules.c file.

+ +

The second way is to compile the module as a DLL, a shared + library that can be loaded into the server at runtime, using + the LoadModule + directive. These module DLLs can be distributed and run on any + Apache for Windows installation, without recompilation of the + server.

+ +

To create a module DLL, a small change is necessary to the + module's source file: The module record must be exported from + the DLL (which will be created later; see below). To do this, + add the AP_MODULE_DECLARE_DATA (defined in the + Apache header files) to your module's module record definition. + For example, if your module has:

+ +
+ module foo_module; +
+ +

Replace the above with:

+
+ module AP_MODULE_DECLARE_DATA foo_module; +
+ +

Note that this will only be activated on Windows, so the + module can continue to be used, unchanged, with Unix if needed. + Also, if you are familiar with .DEF files, you can + export the module record with that method instead.

+ +

Now, create a DLL containing your module. You will need to + link this against the libhttpd.lib export library that is + created when the libhttpd.dll shared library is compiled. You + may also have to change the compiler settings to ensure that + the Apache header files are correctly located. You can find + this library in your server root's modules directory. It is + best to grab an existing module .dsp file from the tree to + assure the build environment is configured correctly, or + alternately compare the compiler and link options to your + .dsp.

+ +

This should create a DLL version of your module. Now simply + place it in the modules directory of your server + root, and use the LoadModule + directive to load it.

+ +

LoadFile Directive

Description: Link in the named object file or library
Syntax:LoadFile filename [filename] ...
Default:none
Context:server config
Status:Base (Windows>; Optional (Unix)
Module:mod_so
+ +

The LoadFile directive links in the named object files or + libraries when the server is started or restarted; this is used + to load additional code which may be required for some module + to work. Filename is either an absolute path or + relative to ServerRoot.

+ +

For example:

+ +
LoadFile libexex/libxmlparse.so
+ +

LoadModule Directive

Description: Links in the object file or library, and adds to the list +of active modules
Syntax:LoadModule module filename
Default:none
Context:server config
Status:Base (Windows>; Optional (Unix)
Module:mod_so
+

The LoadModule directive links in the object file or library + filename and adds the module structure named + module to the list of active modules. Module + is the name of the external variable of type + module in the file, and is listed as the Module Identifier + in the module documentation. Example:

+ +
+ LoadModule status_module modules/mod_status.so +
+ +

loads the named module from the modules subdirectory of the + ServerRoot.

+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_speling.html.en b/docs/manual/mod/mod_speling.html.en new file mode 100644 index 0000000000..c7c6c1f9ff --- /dev/null +++ b/docs/manual/mod/mod_speling.html.en @@ -0,0 +1,65 @@ +mod_speling- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_speling

Description:Attempts to correct mistaken URLs that +users might have entered by ignoring capitalization and by +allowing up to one misspelling
Status:Extension
Module Identifier:speling_module

Summary

+ +

Requests to documents sometimes cannot be served by the core + apache server because the request was misspelled or + miscapitalized. This module addresses this problem by trying to + find a matching document, even after all other modules gave up. + It does its work by comparing each document name in the + requested directory against the requested document name + without regard to case, and allowing + up to one misspelling (character insertion / + omission / transposition or wrong character). A list is built + with all document names which were matched using this + strategy.

+ +

If, after scanning the directory,

+ + + +

Directives

CheckSpelling Directive

Description: Enables the spelling +module
Syntax:CheckSpelling on|off
Default:CheckSpelling Off
Context:server config, virtual host, directory, .htaccess
Override:Options
Status:Extension
Module:mod_speling
Compatibility:CheckSpelling was available as a separately available +module for Apache 1.1, but was limited to miscapitalizations. As +of Apache 1.3, it is part of the Apache distribution. Prior to Apache +1.3.2, the CheckSpelling directive was only available in the +"server" and "virtual host" contexts.
+ +

This directive enables or disables the spelling module. When + enabled, keep in mind that

+ + +

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_ssl.html.en b/docs/manual/mod/mod_ssl.html.en new file mode 100644 index 0000000000..3cdad9c98e --- /dev/null +++ b/docs/manual/mod/mod_ssl.html.en @@ -0,0 +1,928 @@ +mod_ssl- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_ssl

Description:Strong cryptography using the Secure Sockets +Layer (SSL) and Transport Layer Security (TLS) protocols
Status:Extension
Module Identifier:ssl_module

Summary

+

This module provides SSL v2/v3 and TLS v1 support for the Apache +HTTP Server. It was contributed by Ralf S. Engeschall based on his +mod_ssl project and originally derived from work by Ben Laurie.

+ +

This module relies on OpenSSL +to provide the cryptography engine.

+ +

Further details, discussion, and examples are provided in the +SSL documentation.

+

Directives

Environment Variables

+ +

This module provides a lot of SSL information as additional environment +variables to the SSI and CGI namespace. The generated variables are listed in +the table below. For backward compatibility the information can +be made available under different names, too. Look in the Compatibility chapter for details on the +compatibility variables.

+ + + +
+ + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Variable Name:Value Type:Description:
HTTPS flag HTTPS is being used.
SSL_PROTOCOL string The SSL protocol version (SSLv2, SSLv3, TLSv1)
SSL_SESSION_ID string The hex-encoded SSL session id
SSL_CIPHER string The cipher specification name
SSL_CIPHER_EXPORT string true if cipher is an export cipher
SSL_CIPHER_USEKEYSIZE number Number of cipher bits (actually used)
SSL_CIPHER_ALGKEYSIZE number Number of cipher bits (possible)
SSL_VERSION_INTERFACE string The mod_ssl program version
SSL_VERSION_LIBRARY string The OpenSSL program version
SSL_CLIENT_M_VERSION string The version of the client certificate
SSL_CLIENT_M_SERIAL string The serial of the client certificate
SSL_CLIENT_S_DN string Subject DN in client's certificate
SSL_CLIENT_S_DN_x509 string Component of client's Subject DN
SSL_CLIENT_I_DN string Issuer DN of client's certificate
SSL_CLIENT_I_DN_x509 string Component of client's Issuer DN
SSL_CLIENT_V_START string Validity of client's certificate (start time)
SSL_CLIENT_V_END string Validity of client's certificate (end time)
SSL_CLIENT_A_SIG string Algorithm used for the signature of client's certificate
SSL_CLIENT_A_KEY string Algorithm used for the public key of client's certificate
SSL_CLIENT_CERT string PEM-encoded client certificate
SSL_CLIENT_CERT_CHAINn string PEM-encoded certificates in client certificate chain
SSL_CLIENT_VERIFY string NONE, SUCCESS, GENEROUS or FAILED:reason
SSL_SERVER_M_VERSION string The version of the server certificate
SSL_SERVER_M_SERIAL string The serial of the server certificate
SSL_SERVER_S_DN string Subject DN in server's certificate
SSL_SERVER_S_DN_x509 string Component of server's Subject DN
SSL_SERVER_I_DN string Issuer DN of server's certificate
SSL_SERVER_I_DN_x509 string Component of server's Issuer DN
SSL_SERVER_V_START string Validity of server's certificate (start time)
SSL_SERVER_V_END string Validity of server's certificate (end time)
SSL_SERVER_A_SIG string Algorithm used for the signature of server's certificate
SSL_SERVER_A_KEY string Algorithm used for the public key of server's certificate
SSL_SERVER_CERT string PEM-encoded server certificate
+[ where x509 is a component of a X.509 DN: + C,ST,L,O,OU,CN,T,I,G,S,D,UID,Email ] +
+
+

Custom Log Formats

+ +

When mod_ssl is built into Apache or at least +loaded (under DSO situation) additional functions exist for the Custom Log Format of +mod_log_config. First there is an +additional ``%{varname}x'' +eXtension format function which can be used to expand any variables +provided by any module, especially those provided by mod_ssl which can +you find in the above table.

+

+For backward compatibility there is additionally a special +``%{name}c'' cryptography format function +provided. Information about this function is provided in the Compatibility chapter.

+

+Example:

+
+CustomLog logs/ssl_request_log \ + "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b" +
+

SSLCACertificateFile Directive

Description: File of concatenated PEM-encoded CA Certificates +for Client Auth
Syntax:SSLCACertificateFile file-path
Context:server config, virtual host
Status:Extension
Module:mod_ssl
+

+This directive sets the all-in-one file where you can assemble the +Certificates of Certification Authorities (CA) whose clients you deal +with. These are used for Client Authentication. Such a file is simply the +concatenation of the various PEM-encoded Certificate files, in order of +preference. This can be used alternatively and/or additionally to +SSLCACertificatePath.

+

Example

+SSLCACertificateFile /usr/local/apache/conf/ssl.crt/ca-bundle-client.crt +
+

SSLCACertificatePath Directive

Description: Directory of PEM-encoded CA Certificates for +Client Auth
Syntax:SSLCACertificatePath directory-path
Context:server config, virtual host
Status:Extension
Module:mod_ssl
+

+This directive sets the directory where you keep the Certificates of +Certification Authorities (CAs) whose clients you deal with. These are used to +verify the client certificate on Client Authentication.

+

+The files in this directory have to be PEM-encoded and are accessed through +hash filenames. So usually you can't just place the Certificate files +there: you also have to create symbolic links named +hash-value.N. And you should always make sure this directory +contains the appropriate symbolic links. Use the Makefile which +comes with mod_ssl to accomplish this task.

+

Example

+SSLCACertificatePath /usr/local/apache/conf/ssl.crt/ +
+

SSLCARevocationFile Directive

Description: File of concatenated PEM-encoded CA CRLs for +Client Auth
Syntax:SSLCARevocationFile file-path
Context:server config, virtual host
Status:Extension
Module:mod_ssl
+

+This directive sets the all-in-one file where you can +assemble the Certificate Revocation Lists (CRL) of Certification +Authorities (CA) whose clients you deal with. These are used +for Client Authentication. Such a file is simply the concatenation of +the various PEM-encoded CRL files, in order of preference. This can be +used alternatively and/or additionally to SSLCARevocationPath.

+

Example

+SSLCARevocationFile /usr/local/apache/conf/ssl.crl/ca-bundle-client.crl +
+

SSLCARevocationPath Directive

Description: Directory of PEM-encoded CA CRLs for +Client Auth
Syntax:SSLCARevocationPath directory-path
Context:server config, virtual host
Status:Extension
Module:mod_ssl
+

+This directive sets the directory where you keep the Certificate Revocation +Lists (CRL) of Certification Authorities (CAs) whose clients you deal with. +These are used to revoke the client certificate on Client Authentication.

+

+The files in this directory have to be PEM-encoded and are accessed through +hash filenames. So usually you have not only to place the CRL files there. +Additionally you have to create symbolic links named +hash-value.rN. And you should always make sure this directory +contains the appropriate symbolic links. Use the Makefile which +comes with mod_ssl to accomplish this task.

+

Example

+SSLCARevocationPath /usr/local/apache/conf/ssl.crl/ +
+

SSLCertificateChainFile Directive

Description: File of PEM-encoded Server CA Certificates
Syntax:SSLCertificateChainFile file-path
Context:server config, virtual host
Status:Extension
Module:mod_ssl
+

+This directive sets the optional all-in-one file where you can +assemble the certificates of Certification Authorities (CA) which form the +certificate chain of the server certificate. This starts with the issuing CA +certificate of of the server certificate and can range up to the root CA +certificate. Such a file is simply the concatenation of the various +PEM-encoded CA Certificate files, usually in certificate chain order.

+

+This should be used alternatively and/or additionally to SSLCACertificatePath for explicitly +constructing the server certificate chain which is sent to the browser +in addition to the server certificate. It is especially useful to +avoid conflicts with CA certificates when using client +authentication. Because although placing a CA certificate of the +server certificate chain into SSLCACertificatePath has the same effect +for the certificate chain construction, it has the side-effect that +client certificates issued by this same CA certificate are also +accepted on client authentication. That's usually not one expect.

+

+But be careful: Providing the certificate chain works only if you are using a +single (either RSA or DSA) based server certificate. If you are +using a coupled RSA+DSA certificate pair, this will work only if actually both +certificates use the same certificate chain. Else the browsers will be +confused in this situation.

+

Example

+SSLCertificateChainFile /usr/local/apache/conf/ssl.crt/ca.crt +
+

SSLCertificateFile Directive

Description: Server PEM-encoded X.509 Certificate file
Syntax:SSLCertificateFile file-path
Context:server config, virtual host
Status:Extension
Module:mod_ssl
+

+This directive points to the PEM-encoded Certificate file for the server and +optionally also to the corresponding RSA or DSA Private Key file for it +(contained in the same file). If the contained Private Key is encrypted the +Pass Phrase dialog is forced at startup time. This directive can be used up to +two times (referencing different filenames) when both a RSA and a DSA based +server certificate is used in parallel.

+

Example

+SSLCertificateFile /usr/local/apache/conf/ssl.crt/server.crt +
+

SSLCertificateKeyFile Directive

Description: Server PEM-encoded Private Key file
Syntax:SSLCertificateKeyFile file-path
Context:server config, virtual host
Status:Extension
Module:mod_ssl
+

+This directive points to the PEM-encoded Private Key file for the +server. If the Private Key is not combined with the Certificate in the +SSLCertificateFile, use this additional directive to +point to the file with the stand-alone Private Key. When +SSLCertificateFile is used and the file +contains both the Certificate and the Private Key this directive need +not be used. But we strongly discourage this practice. Instead we +recommend you to separate the Certificate and the Private Key. If the +contained Private Key is encrypted, the Pass Phrase dialog is forced +at startup time. This directive can be used up to two times +(referencing different filenames) when both a RSA and a DSA based +private key is used in parallel.

+

Example

+SSLCertificateKeyFile /usr/local/apache/conf/ssl.key/server.key +
+

SSLCipherSuite Directive

Description: Cipher Suite available for negotiation in SSL +handshake
Syntax:SSLCipherSuite cipher-spec
Default:SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP
Context:server config, virtual host, directory, .htaccess
Override:AuthConfig
Status:Extension
Module:mod_ssl
+

+This complex directive uses a colon-separated cipher-spec string +consisting of OpenSSL cipher specifications to configure the Cipher Suite the +client is permitted to negotiate in the SSL handshake phase. Notice that this +directive can be used both in per-server and per-directory context. In +per-server context it applies to the standard SSL handshake when a connection +is established. In per-directory context it forces a SSL renegotation with the +reconfigured Cipher Suite after the HTTP request was read but before the HTTP +response is sent.

+

+An SSL cipher specification in cipher-spec is composed of 4 major +attributes plus a few extra minor ones:

+ +

An SSL cipher can also be an export cipher and is either a SSLv2 or SSLv3/TLSv1 +cipher (here TLSv1 is equivalent to SSLv3). To specify which ciphers to use, +one can either specify all the Ciphers, one at a time, or use aliases to +specify the preference and order for the ciphers (see Table +1).

+ + + +
+ + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Tag Description
Key Exchange Algorithm:
kRSA RSA key exchange
kDHr Diffie-Hellman key exchange with RSA key
kDHd Diffie-Hellman key exchange with DSA key
kEDH Ephemeral (temp.key) Diffie-Hellman key exchange (no cert)
Authentication Algorithm:
aNULL No authentication
aRSA RSA authentication
aDSS DSS authentication
aDH Diffie-Hellman authentication
Cipher Encoding Algorithm:
eNULL No encoding
DES DES encoding
3DES Triple-DES encoding
RC4 RC4 encoding
RC2 RC2 encoding
IDEA IDEA encoding
MAC Digest Algorithm:
MD5 MD5 hash function
SHA1 SHA1 hash function
SHA SHA hash function
Aliases:
SSLv2 all SSL version 2.0 ciphers
SSLv3 all SSL version 3.0 ciphers
TLSv1 all TLS version 1.0 ciphers
EXP all export ciphers
EXPORT40 all 40-bit export ciphers only
EXPORT56 all 56-bit export ciphers only
LOW all low strength ciphers (no export, single DES)
MEDIUM all ciphers with 128 bit encryption
HIGH all ciphers using Triple-DES
RSA all ciphers using RSA key exchange
DH all ciphers using Diffie-Hellman key exchange
EDH all ciphers using Ephemeral Diffie-Hellman key exchange
ADH all ciphers using Anonymous Diffie-Hellman key exchange
DSS all ciphers using DSS authentication
NULL all ciphers using no encryption
+
+
+

+Now where this becomes interesting is that these can be put together +to specify the order and ciphers you wish to use. To speed this up +there are also aliases (SSLv2, SSLv3, TLSv1, EXP, LOW, MEDIUM, +HIGH) for certain groups of ciphers. These tags can be joined +together with prefixes to form the cipher-spec. Available +prefixes are:

+ +

A simpler way to look at all of this is to use the ``openssl ciphers +-v'' command which provides a nice way to successively create the +correct cipher-spec string. The default cipher-spec string +is ``ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP'' which +means the following: first, remove from consideration any ciphers that do not +authenticate, i.e. for SSL only the Anonymous Diffie-Hellman ciphers. Next, +use ciphers using RC4 and RSA. Next include the high, medium and then the low +security ciphers. Finally pull all SSLv2 and export ciphers to the +end of the list.

+
+
+$ openssl ciphers -v 'ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP'
+NULL-SHA                SSLv3 Kx=RSA      Au=RSA  Enc=None      Mac=SHA1
+NULL-MD5                SSLv3 Kx=RSA      Au=RSA  Enc=None      Mac=MD5
+EDH-RSA-DES-CBC3-SHA    SSLv3 Kx=DH       Au=RSA  Enc=3DES(168) Mac=SHA1
+...                     ...               ...     ...           ...
+EXP-RC4-MD5             SSLv3 Kx=RSA(512) Au=RSA  Enc=RC4(40)   Mac=MD5  export
+EXP-RC2-CBC-MD5         SSLv2 Kx=RSA(512) Au=RSA  Enc=RC2(40)   Mac=MD5  export
+EXP-RC4-MD5             SSLv2 Kx=RSA(512) Au=RSA  Enc=RC4(40)   Mac=MD5  export
+
+
+

The complete list of particular RSA & DH ciphers for SSL is given in Table 2.

+

Example

+SSLCipherSuite RSA:!EXP:!NULL:+HIGH:+MEDIUM:-LOW +
+ + +
+ + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Cipher-Tag Protocol Key Ex. Auth. Enc. MAC Type
RSA Ciphers:
DES-CBC3-SHA SSLv3 RSA RSA 3DES(168) SHA1  
DES-CBC3-MD5 SSLv2 RSA RSA 3DES(168) MD5  
IDEA-CBC-SHA SSLv3 RSA RSA IDEA(128) SHA1  
RC4-SHA SSLv3 RSA RSA RC4(128) SHA1  
RC4-MD5 SSLv3 RSA RSA RC4(128) MD5  
IDEA-CBC-MD5 SSLv2 RSA RSA IDEA(128) MD5  
RC2-CBC-MD5 SSLv2 RSA RSA RC2(128) MD5  
RC4-MD5 SSLv2 RSA RSA RC4(128) MD5  
DES-CBC-SHA SSLv3 RSA RSA DES(56) SHA1  
RC4-64-MD5 SSLv2 RSA RSA RC4(64) MD5  
DES-CBC-MD5 SSLv2 RSA RSA DES(56) MD5  
EXP-DES-CBC-SHA SSLv3 RSA(512) RSA DES(40) SHA1 export
EXP-RC2-CBC-MD5 SSLv3 RSA(512) RSA RC2(40) MD5 export
EXP-RC4-MD5 SSLv3 RSA(512) RSA RC4(40) MD5 export
EXP-RC2-CBC-MD5 SSLv2 RSA(512) RSA RC2(40) MD5 export
EXP-RC4-MD5 SSLv2 RSA(512) RSA RC4(40) MD5 export
NULL-SHA SSLv3 RSA RSA None SHA1  
NULL-MD5 SSLv3 RSA RSA None MD5  
Diffie-Hellman Ciphers:
ADH-DES-CBC3-SHA SSLv3 DH None 3DES(168) SHA1  
ADH-DES-CBC-SHA SSLv3 DH None DES(56) SHA1  
ADH-RC4-MD5 SSLv3 DH None RC4(128) MD5  
EDH-RSA-DES-CBC3-SHA SSLv3 DH RSA 3DES(168) SHA1  
EDH-DSS-DES-CBC3-SHA SSLv3 DH DSS 3DES(168) SHA1  
EDH-RSA-DES-CBC-SHA SSLv3 DH RSA DES(56) SHA1  
EDH-DSS-DES-CBC-SHA SSLv3 DH DSS DES(56) SHA1  
EXP-EDH-RSA-DES-CBC-SHA SSLv3 DH(512) RSA DES(40) SHA1 export
EXP-EDH-DSS-DES-CBC-SHA SSLv3 DH(512) DSS DES(40) SHA1 export
EXP-ADH-DES-CBC-SHA SSLv3 DH(512) None DES(40) SHA1 export
EXP-ADH-RC4-MD5 SSLv3 DH(512) None RC4(40) MD5 export
+
+
+

SSLEngine Directive

Description: SSL Engine Operation Switch
Syntax:SSLEngine on|off
Default:SSLEngine off
Context:server config, virtual host
Status:Extension
Module:mod_ssl
+

+This directive toggles the usage of the SSL/TLS Protocol Engine. This +is usually used inside a <VirtualHost> section to enable SSL/TLS for a +particular virtual host. By default the SSL/TLS Protocol Engine is +disabled for both the main server and all configured virtual hosts.

+

Example

+<VirtualHost _default_:443>
+SSLEngine on
+...
+</VirtualHost> +
+

SSLMutex Directive

Description: Semaphore for internal mutual exclusion of +operations
Syntax:SSLMutex type
Default:SSLMutex none
Context:server config
Status:Extension
Module:mod_ssl
+

+This configures the SSL engine's semaphore (aka. lock) which is used for mutual +exclusion of operations which have to be done in a synchronized way between the +pre-forked Apache server processes. This directive can only be used in the +global server context because it's only useful to have one global mutex.

+

+The following Mutex types are available:

+ +

Example

+SSLMutex file:/usr/local/apache/logs/ssl_mutex +
+

SSLOptions Directive

Description: Configure various SSL engine run-time options
Syntax:SSLOptions [+|-]option ...
Context:server config, virtual host, directory, .htaccess
Override:Options
Status:Extension
Module:mod_ssl
+

+This directive can be used to control various run-time options on a +per-directory basis. Normally, if multiple SSLOptions +could apply to a directory, then the most specific one is taken +completely; the options are not merged. However if all the +options on the SSLOptions directive are preceded by a +plus (+) or minus (-) symbol, the options +are merged. Any options preceded by a + are added to the +options currently in force, and any options preceded by a +- are removed from the options currently in force.

+

+The available options are:

+ +

Example

+SSLOptions +FakeBasicAuth -StrictRequire
+<Files ~ "\.(cgi|shtml)$">
+ SSLOptions +StdEnvVars +CompatEnvVars -ExportCertData
+<Files> +
+

SSLPassPhraseDialog Directive

Description: Type of pass phrase dialog for encrypted private +keys
Syntax:SSLPassPhraseDialog type
Default:SSLPassPhraseDialog builtin
Context:server config
Status:Extension
Module:mod_ssl
+

+When Apache starts up it has to read the various Certificate (see +SSLCertificateFile) and +Private Key (see SSLCertificateKeyFile) files of the +SSL-enabled virtual servers. Because for security reasons the Private +Key files are usually encrypted, mod_ssl needs to query the +administrator for a Pass Phrase in order to decrypt those files. This +query can be done in two ways which can be configured by +type:

+ +

+Example:

+
+SSLPassPhraseDialog exec:/usr/local/apache/sbin/pp-filter +
+

SSLProtocol Directive

Description: Configure usable SSL protocol flavors
Syntax:SSLProtocol [+|-]protocol ...
Default:SSLProtocol all
Context:server config, virtual host
Override:Options
Status:Extension
Module:mod_ssl
+

+This directive can be used to control the SSL protocol flavors mod_ssl should +use when establishing its server environment. Clients then can only connect +with one of the provided protocols.

+

+The available (case-insensitive) protocols are:

+ +

Example

+# enable SSLv3 and TLSv1, but not SSLv2
+SSLProtocol all -SSLv2 +
+

SSLRandomSeed Directive

Description: Pseudo Random Number Generator (PRNG) seeding +source
Syntax:SSLRandomSeed context source +[bytes]
Context:server config
Status:Extension
Module:mod_ssl
+

+This configures one or more sources for seeding the Pseudo Random Number +Generator (PRNG) in OpenSSL at startup time (context is +startup) and/or just before a new SSL connection is established +(context is connect). This directive can only be used +in the global server context because the PRNG is a global facility.

+

+The following source variants are available:

+ +

Example

+SSLRandomSeed startup builtin
+SSLRandomSeed startup file:/dev/random
+SSLRandomSeed startup file:/dev/urandom 1024
+SSLRandomSeed startup exec:/usr/local/bin/truerand 16
+SSLRandomSeed connect builtin
+SSLRandomSeed connect file:/dev/random
+SSLRandomSeed connect file:/dev/urandom 1024
+
+

SSLRequire Directive

Description: Allow access only when an arbitrarily complex +boolean expression is true
Syntax:SSLRequire expression
Context:directory, .htaccess
Override:AuthConfig
Status:Extension
Module:mod_ssl
+

+This directive specifies a general access requirement which has to be +fulfilled in order to allow access. It's a very powerful directive because the +requirement specification is an arbitrarily complex boolean expression +containing any number of access checks.

+

+The expression must match the following syntax (given as a BNF +grammar notation):

+
+
+expr     ::= "true" | "false"
+           | "!" expr
+           | expr "&&" expr
+           | expr "||" expr
+           | "(" expr ")"
+           | comp
+
+comp     ::= word "==" word | word "eq" word
+           | word "!=" word | word "ne" word
+           | word "<"  word | word "lt" word
+           | word "<=" word | word "le" word
+           | word ">"  word | word "gt" word
+           | word ">=" word | word "ge" word
+           | word "in" "{" wordlist "}"
+           | word "=~" regex
+           | word "!~" regex
+
+wordlist ::= word
+           | wordlist "," word
+
+word     ::= digit
+           | cstring
+           | variable
+           | function
+
+digit    ::= [0-9]+
+cstring  ::= "..."
+variable ::= "%{" varname "}"
+function ::= funcname "(" funcargs ")"
+
+
+

while for varname any variable from Table 3 can be used. Finally for +funcname the following functions are available:

+ +

Notice that expression is first parsed into an internal machine +representation and then evaluated in a second step. Actually, in Global and +Per-Server Class context expression is parsed at startup time and +at runtime only the machine representation is executed. For Per-Directory +context this is different: here expression has to be parsed and +immediately executed for every request.

+

Example

+SSLRequire ( %{SSL_CIPHER} !~ m/^(EXP|NULL)-/ \
+ and %{SSL_CLIENT_S_DN_O} eq "Snake Oil, Ltd." \
+ and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"} \
+ and %{TIME_WDAY} >= 1 and %{TIME_WDAY} <= 5 \
+ and %{TIME_HOUR} >= 8 and %{TIME_HOUR} <= 20 ) \
+ or %{REMOTE_ADDR} =~ m/^192\.76\.162\.[0-9]+$/ +
+ + +
+ + +
+
+Standard CGI/1.0 and Apache variables: +
+HTTP_USER_AGENT        PATH_INFO             AUTH_TYPE
+HTTP_REFERER           QUERY_STRING          SERVER_SOFTWARE
+HTTP_COOKIE            REMOTE_HOST           API_VERSION
+HTTP_FORWARDED         REMOTE_IDENT          TIME_YEAR
+HTTP_HOST              IS_SUBREQ             TIME_MON
+HTTP_PROXY_CONNECTION  DOCUMENT_ROOT         TIME_DAY
+HTTP_ACCEPT            SERVER_ADMIN          TIME_HOUR
+HTTP:headername        SERVER_NAME           TIME_MIN
+THE_REQUEST            SERVER_PORT           TIME_SEC
+REQUEST_METHOD         SERVER_PROTOCOL       TIME_WDAY
+REQUEST_SCHEME         REMOTE_ADDR           TIME
+REQUEST_URI            REMOTE_USER           ENV:variablename
+REQUEST_FILENAME
+
+SSL-related variables: +
+HTTPS                  SSL_CLIENT_M_VERSION   SSL_SERVER_M_VERSION
+                       SSL_CLIENT_M_SERIAL    SSL_SERVER_M_SERIAL
+SSL_PROTOCOL           SSL_CLIENT_V_START     SSL_SERVER_V_START
+SSL_SESSION_ID         SSL_CLIENT_V_END       SSL_SERVER_V_END
+SSL_CIPHER             SSL_CLIENT_S_DN        SSL_SERVER_S_DN
+SSL_CIPHER_EXPORT      SSL_CLIENT_S_DN_C      SSL_SERVER_S_DN_C
+SSL_CIPHER_ALGKEYSIZE  SSL_CLIENT_S_DN_ST     SSL_SERVER_S_DN_ST
+SSL_CIPHER_USEKEYSIZE  SSL_CLIENT_S_DN_L      SSL_SERVER_S_DN_L
+SSL_VERSION_LIBRARY    SSL_CLIENT_S_DN_O      SSL_SERVER_S_DN_O
+SSL_VERSION_INTERFACE  SSL_CLIENT_S_DN_OU     SSL_SERVER_S_DN_OU
+                       SSL_CLIENT_S_DN_CN     SSL_SERVER_S_DN_CN
+                       SSL_CLIENT_S_DN_T      SSL_SERVER_S_DN_T
+                       SSL_CLIENT_S_DN_I      SSL_SERVER_S_DN_I
+                       SSL_CLIENT_S_DN_G      SSL_SERVER_S_DN_G
+                       SSL_CLIENT_S_DN_S      SSL_SERVER_S_DN_S
+                       SSL_CLIENT_S_DN_D      SSL_SERVER_S_DN_D
+                       SSL_CLIENT_S_DN_UID    SSL_SERVER_S_DN_UID
+                       SSL_CLIENT_S_DN_Email  SSL_SERVER_S_DN_Email
+                       SSL_CLIENT_I_DN        SSL_SERVER_I_DN
+                       SSL_CLIENT_I_DN_C      SSL_SERVER_I_DN_C
+                       SSL_CLIENT_I_DN_ST     SSL_SERVER_I_DN_ST
+                       SSL_CLIENT_I_DN_L      SSL_SERVER_I_DN_L
+                       SSL_CLIENT_I_DN_O      SSL_SERVER_I_DN_O
+                       SSL_CLIENT_I_DN_OU     SSL_SERVER_I_DN_OU
+                       SSL_CLIENT_I_DN_CN     SSL_SERVER_I_DN_CN
+                       SSL_CLIENT_I_DN_T      SSL_SERVER_I_DN_T
+                       SSL_CLIENT_I_DN_I      SSL_SERVER_I_DN_I
+                       SSL_CLIENT_I_DN_G      SSL_SERVER_I_DN_G
+                       SSL_CLIENT_I_DN_S      SSL_SERVER_I_DN_S
+                       SSL_CLIENT_I_DN_D      SSL_SERVER_I_DN_D
+                       SSL_CLIENT_I_DN_UID    SSL_SERVER_I_DN_UID
+                       SSL_CLIENT_I_DN_Email  SSL_SERVER_I_DN_Email
+                       SSL_CLIENT_A_SIG       SSL_SERVER_A_SIG
+                       SSL_CLIENT_A_KEY       SSL_SERVER_A_KEY
+                       SSL_CLIENT_CERT        SSL_SERVER_CERT
+                       SSL_CLIENT_CERT_CHAINn
+                       SSL_CLIENT_VERIFY
+
+
+
+
+

SSLRequireSSL Directive

Description: Deny access when SSL is not used for the +HTTP request
Syntax:SSLRequireSSL
Context:directory, .htaccess
Override:AuthConfig
Status:Extension
Module:mod_ssl
+

+This directive forbids access unless HTTP over SSL (i.e. HTTPS) is enabled for +the current connection. This is very handy inside the SSL-enabled virtual +host or directories for defending against configuration errors that expose +stuff that should be protected. When this directive is present all requests +are denied which are not using SSL.

+

Example

+SSLRequireSSL +
+

SSLSessionCache Directive

Description: Type of the global/inter-process SSL Session +Cache
Syntax:SSLSessionCache type
Default:SSLSessionCache none
Context:server config
Status:Extension
Module:mod_ssl
+

+This configures the storage type of the global/inter-process SSL Session +Cache. This cache is an optional facility which speeds up parallel request +processing. For requests to the same server process (via HTTP keep-alive), +OpenSSL already caches the SSL session information locally. But because modern +clients request inlined images and other data via parallel requests (usually +up to four parallel requests are common) those requests are served by +different pre-forked server processes. Here an inter-process cache +helps to avoid unneccessary session handshakes.

+

+The following two storage types are currently supported:

+ +

Examples

+SSLSessionCache dbm:/usr/local/apache/logs/ssl_gcache_data
+SSLSessionCache shm:/usr/local/apache/logs/ssl_gcache_data(512000) +
+

SSLSessionCacheTimeout Directive

Description: Number of seconds before an SSL session expires +in the Session Cache
Syntax:SSLSessionCacheTimeout seconds
Default:SSLSessionCacheTimeout 300
Context:server config, virtual host
Status:Extension
Module:mod_ssl
+

+This directive sets the timeout in seconds for the information stored in the +global/inter-process SSL Session Cache and the OpenSSL internal memory cache. +It can be set as low as 15 for testing, but should be set to higher +values like 300 in real life.

+

Example

+SSLSessionCacheTimeout 600 +
+

SSLVerifyClient Directive

Description: Type of Client Certificate verification
Syntax:SSLVerifyClient level
Default:SSLVerifyClient none
Context:server config, virtual host, directory, .htaccess
Override:AuthConfig
Status:Extension
Module:mod_ssl
+

+This directive sets the Certificate verification level for the Client +Authentication. Notice that this directive can be used both in per-server and +per-directory context. In per-server context it applies to the client +authentication process used in the standard SSL handshake when a connection is +established. In per-directory context it forces a SSL renegotation with the +reconfigured client verification level after the HTTP request was read but +before the HTTP response is sent.

+

+The following levels are available for level:

+ +

In practice only levels none and +require are really interesting, because level +optional doesn't work with all browsers and level +optional_no_ca is actually against the idea of +authentication (but can be used to establish SSL test pages, etc.)

+

Example

+SSLVerifyClient require +
+

SSLVerifyDepth Directive

Description: Maximum depth of CA Certificates in Client +Certificate verification
Syntax:SSLVerifyDepth number
Default:SSLVerifyDepth 1
Context:server config, virtual host, directory, .htaccess
Override:AuthConfig
Status:Extension
Module:mod_ssl
+

+This directive sets how deeply mod_ssl should verify before deciding that the +clients don't have a valid certificate. Notice that this directive can be +used both in per-server and per-directory context. In per-server context it +applies to the client authentication process used in the standard SSL +handshake when a connection is established. In per-directory context it forces +a SSL renegotation with the reconfigured client verification depth after the +HTTP request was read but before the HTTP response is sent.

+

+The depth actually is the maximum number of intermediate certificate issuers, +i.e. the number of CA certificates which are max allowed to be followed while +verifying the client certificate. A depth of 0 means that self-signed client +certificates are accepted only, the default depth of 1 means the client +certificate can be self-signed or has to be signed by a CA which is directly +known to the server (i.e. the CA's certificate is under +SSLCACertificatePath), etc.

+

Example

+SSLVerifyDepth 10 +
+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_status.html.en b/docs/manual/mod/mod_status.html.en new file mode 100644 index 0000000000..aa7bf37f10 --- /dev/null +++ b/docs/manual/mod/mod_status.html.en @@ -0,0 +1,107 @@ +mod_status- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_status

Description:Provides information on server activity and +performance
Status:Base
Module Identifier:status_module

Summary

+ +
+ Warning: This document has not been updated + to take into account changes made in the 2.0 version of the + Apache HTTP Server. Some of the information may still be + relevant, but please use it with care. +
+ +

The Status module allows a server administrator to find out + how well their server is performing. A HTML page is presented + that gives the current server statistics in an easily readable + form. If required this page can be made to automatically + refresh (given a compatible browser). Another page gives a + simple machine-readable list of the current server state.

+ +

The details given are:

+ + + +

A compile-time option must be used to display the details + marked "(*)" as the instrumentation required for obtaining + these statistics does not exist within standard Apache.

+

Directives

Enabling Status Support

+ + +

To enable status reports only for browsers from the foo.com + domain add this code to your httpd.conf + configuration file

+
+ <Location /server-status>
+ SetHandler server-status
+
+ Order Deny,Allow
+ Deny from all
+ Allow from .foo.com
+ </Location> +
+ +

You can now access server statistics by using a Web browser + to access the page + http://your.server.name/server-status

+ +

Note that mod_status will only work + when you are running Apache in standalone mode and not + inetd mode.

+

Automatic Updates

+ + +

You can get the status page to update itself automatically if + you have a browser that supports "refresh". Access the page + http://your.server.name/server-status?refresh=N to + refresh the page every N seconds.

+ +

Machine Readable Status File

+ + +

A machine-readable version of the status file is available by + accessing the page + http://your.server.name/server-status?auto. This + is useful when automatically run, see the Perl program in the + /support directory of Apache, + log_server_status.

+ +
+ It should be noted that if mod_status is + compiled into the server, its handler capability is available + in all configuration files, including + per-directory files (e.g., + .htaccess). This may have security-related + ramifications for your site. +
+ +

ExtendedStatus Directive

Description: This directive controls whether the server keeps track of +extended status information for each request. This is only +useful if the status module is enabled on the server.
Syntax:ExtendedStatus On|Off
Default:ExtendedStatus Off
Context:server config
Status:Base
Module:mod_status
Compatibility:ExtendedStatus is only available in Apache 1.3.2 and +later.
+

This setting applies to the entire server, and cannot be + enabled or disabled on a virtualhost-by-virtualhost basis.

+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_suexec.html.en b/docs/manual/mod/mod_suexec.html.en new file mode 100644 index 0000000000..53e284952d --- /dev/null +++ b/docs/manual/mod/mod_suexec.html.en @@ -0,0 +1,16 @@ +mod_suexec- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_suexec

Description:Allows CGI scripts to run as a specified user +and Group
Status:Extension
Module Identifier:suexec_module
Compatibility:Available in Apache 2.0 and later

Summary

+

This module allows CGI scripts to run as a specified user + and Group.

+

Directives

SuexecUserGroup Directive

Description:
Syntax:SuexecUserGroup User Group
Default:None
Context:server config, virtual host
Status:Extension
Module:mod_suexec
Compatibility:SuexecUserGroup is only available in 2.0 and +later.
+

The SuexecUserGroup directive allows you to + specify a user and group for CGI programs to run as. Non-CGI + requests are still processes with the user specified in the + User directive. This directive replaces using the User and + Group directives inside of VirtualHosts.

+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_unique_id.html.en b/docs/manual/mod/mod_unique_id.html.en new file mode 100644 index 0000000000..5c41e2707c --- /dev/null +++ b/docs/manual/mod/mod_unique_id.html.en @@ -0,0 +1,169 @@ +mod_unique_id- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_unique_id

Description:Provides an environment variable with a unique +identifier for each request
Status:Extension
Module Identifier:unique_id_module

Summary

+ +

This module provides a magic token for each request which is + guaranteed to be unique across "all" requests under very + specific conditions. The unique identifier is even unique + across multiple machines in a properly configured cluster of + machines. The environment variable UNIQUE_ID is + set to the identifier for each request. Unique identifiers are + useful for various reasons which are beyond the scope of this + document.

+

Directives

Theory

+ + +

First a brief recap of how the Apache server works on Unix + machines. This feature currently isn't supported on Windows NT. + On Unix machines, Apache creates several children, the children + process requests one at a time. Each child can serve multiple + requests in its lifetime. For the purpose of this discussion, + the children don't share any data with each other. We'll refer + to the children as httpd processes.

+ +

Your website has one or more machines under your + administrative control, together we'll call them a cluster of + machines. Each machine can possibly run multiple instances of + Apache. All of these collectively are considered "the + universe", and with certain assumptions we'll show that in this + universe we can generate unique identifiers for each request, + without extensive communication between machines in the + cluster.

+ +

The machines in your cluster should satisfy these + requirements. (Even if you have only one machine you should + synchronize its clock with NTP.)

+ + + +

As far as operating system assumptions go, we assume that + pids (process ids) fit in 32-bits. If the operating system uses + more than 32-bits for a pid, the fix is trivial but must be + performed in the code.

+ +

Given those assumptions, at a single point in time we can + identify any httpd process on any machine in the cluster from + all other httpd processes. The machine's IP address and the pid + of the httpd process are sufficient to do this. So in order to + generate unique identifiers for requests we need only + distinguish between different points in time.

+ +

To distinguish time we will use a Unix timestamp (seconds + since January 1, 1970 UTC), and a 16-bit counter. The timestamp + has only one second granularity, so the counter is used to + represent up to 65536 values during a single second. The + quadruple ( ip_addr, pid, time_stamp, counter ) is + sufficient to enumerate 65536 requests per second per httpd + process. There are issues however with pid reuse over time, and + the counter is used to alleviate this issue.

+ +

When an httpd child is created, the counter is initialized + with ( current microseconds divided by 10 ) modulo 65536 (this + formula was chosen to eliminate some variance problems with the + low order bits of the microsecond timers on some systems). When + a unique identifier is generated, the time stamp used is the + time the request arrived at the web server. The counter is + incremented every time an identifier is generated (and allowed + to roll over).

+ +

The kernel generates a pid for each process as it forks the + process, and pids are allowed to roll over (they're 16-bits on + many Unixes, but newer systems have expanded to 32-bits). So + over time the same pid will be reused. However unless it is + reused within the same second, it does not destroy the + uniqueness of our quadruple. That is, we assume the system does + not spawn 65536 processes in a one second interval (it may even + be 32768 processes on some Unixes, but even this isn't likely + to happen).

+ +

Suppose that time repeats itself for some reason. That is, + suppose that the system's clock is screwed up and it revisits a + past time (or it is too far forward, is reset correctly, and + then revisits the future time). In this case we can easily show + that we can get pid and time stamp reuse. The choice of + initializer for the counter is intended to help defeat this. + Note that we really want a random number to initialize the + counter, but there aren't any readily available numbers on most + systems (i.e., you can't use rand() because you need + to seed the generator, and can't seed it with the time because + time, at least at one second resolution, has repeated itself). + This is not a perfect defense.

+ +

How good a defense is it? Suppose that one of your machines + serves at most 500 requests per second (which is a very + reasonable upper bound at this writing, because systems + generally do more than just shovel out static files). To do + that it will require a number of children which depends on how + many concurrent clients you have. But we'll be pessimistic and + suppose that a single child is able to serve 500 requests per + second. There are 1000 possible starting counter values such + that two sequences of 500 requests overlap. So there is a 1.5% + chance that if time (at one second resolution) repeats itself + this child will repeat a counter value, and uniqueness will be + broken. This was a very pessimistic example, and with real + world values it's even less likely to occur. If your system is + such that it's still likely to occur, then perhaps you should + make the counter 32 bits (by editing the code).

+ +

You may be concerned about the clock being "set back" during + summer daylight savings. However this isn't an issue because + the times used here are UTC, which "always" go forward. Note + that x86 based Unixes may need proper configuration for this to + be true -- they should be configured to assume that the + motherboard clock is on UTC and compensate appropriately. But + even still, if you're running NTP then your UTC time will be + correct very shortly after reboot.

+ +

The UNIQUE_ID environment variable is + constructed by encoding the 112-bit (32-bit IP address, 32 bit + pid, 32 bit time stamp, 16 bit counter) quadruple using the + alphabet [A-Za-z0-9@-] in a manner similar to MIME + base64 encoding, producing 19 characters. The MIME base64 + alphabet is actually [A-Za-z0-9+/] however + + and / need to be specially encoded + in URLs, which makes them less desirable. All values are + encoded in network byte ordering so that the encoding is + comparable across architectures of different byte ordering. The + actual ordering of the encoding is: time stamp, IP address, + pid, counter. This ordering has a purpose, but it should be + emphasized that applications should not dissect the encoding. + Applications should treat the entire encoded + UNIQUE_ID as an opaque token, which can be + compared against other UNIQUE_IDs for equality + only.

+ +

The ordering was chosen such that it's possible to change + the encoding in the future without worrying about collision + with an existing database of UNIQUE_IDs. The new + encodings should also keep the time stamp as the first element, + and can otherwise use the same alphabet and bit length. Since + the time stamps are essentially an increasing sequence, it's + sufficient to have a flag second in which all machines + in the cluster stop serving and request, and stop using the old + encoding format. Afterwards they can resume requests and begin + issuing the new encodings.

+ +

This we believe is a relatively portable solution to this + problem. It can be extended to multithreaded systems like + Windows NT, and can grow with future needs. The identifiers + generated have essentially an infinite life-time because future + identifiers can be made longer as required. Essentially no + communication is required between machines in the cluster (only + NTP synchronization is required, which is low overhead), and no + communication between httpd processes is required (the + communication is implicit in the pid value assigned by the + kernel). In very specific situations the identifier can be + shortened, but more information needs to be assumed (for + example the 32-bit IP address is overkill for any site, but + there is no portable shorter replacement for it).

+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_userdir.html.en b/docs/manual/mod/mod_userdir.html.en new file mode 100644 index 0000000000..4be6198426 --- /dev/null +++ b/docs/manual/mod/mod_userdir.html.en @@ -0,0 +1,102 @@ +mod_userdir- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_userdir

Description:Provides for user-specific +directories
Status:Base
Module Identifier:userdir_module

Summary

+

Directives

UserDir Directive

Description: Sets the directory from which to serve files when requests +for a particular user are received, denoted by requests containing +~username, such as +http://server.example.com/~bob/
Syntax:UserDir directory-filename
Default:UserDir public_html
Context:server config, virtual +host
Status:Base
Module:mod_userdir
Compatibility:All forms except the UserDir public_html +form are only available in Apache 1.1 or above. Use of the +enabled keyword, or disabled with a +list of usernames, is only available in Apache 1.3 and +above.
+ +

The UserDir directive sets the real + directory in a user's home directory to use when a request for a + document for a user is received. Directory-filename is + one of the following:

+ + + +

If neither the enabled nor the + disabled keywords appear in the + Userdir directive, the argument is treated as a + filename pattern, and is used to turn the name into a directory + specification. A request for + http://www.foo.com/~bob/one/two.html will be + translated to:

+ + + + + + + +
UserDir directive usedTranslated path
UserDir public_html~bob/public_html/one/two.html
UserDir /usr/web/usr/web/bob/one/two.html
UserDir /home/*/www/home/bob/www/one/two.html
+ +

The following directives will send redirects to the client:

+ + + + + + + +
UserDir directive usedTranslated path
UserDir http://www.foo.com/usershttp://www.foo.com/users/bob/one/two.html
UserDir +http://www.foo.com/*/usrhttp://www.foo.com/bob/usr/one/two.html
UserDir +http://www.foo.com/~*/http://www.foo.com/~bob/one/two.html
+ +
+ Be careful when using this directive; for instance, + "UserDir ./" would map + "/~root" to "/" - which is probably + undesirable. If you are running Apache 1.3 or above, it is + strongly recommended that your configuration include a + "UserDir disabled root" declaration. + See also the Directory + directive and the Security + Tips page for more information. +
+ +

Additional examples:

+ +

To allow a few users to have UserDir directories, but +not anyone else, use the following:

+ +
+UserDir disabled
+UserDir enabled user1 user2 user3 +
+ +

To allow most users to have UserDir directories, but +deny this to a few, use the following:

+ +
+UserDir enabled
+UserDir disabled user4 user5 user6 +
+ +

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_usertrack.html.en b/docs/manual/mod/mod_usertrack.html.en new file mode 100644 index 0000000000..716093c6ca --- /dev/null +++ b/docs/manual/mod/mod_usertrack.html.en @@ -0,0 +1,129 @@ +mod_usertrack- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_usertrack

Description: + This module uses cookies to provide for a + clickstream log of user activity on a site. +
Status:Extension
Module Identifier:usertrack_module
Compatibility:Known as mod_cookies prior to Apache 1.3.

Summary

+

Previous releases of Apache have included a module which + generates a 'clickstream' log of user activity on a site using + cookies. This was called the "cookies" module, mod_cookies. In + Apache 1.2 and later this module has been renamed the "user + tracking" module, mod_usertrack. This module has been + simplified and new directives added.

+

Directives

Logging

+ + +

Previously, the cookies module (now the user tracking + module) did its own logging, using the CookieLog + directive. In this release, this module does no logging at all. + Instead, a configurable log format file should be used to log + user click-streams. This is possible because the logging module + now allows multiple log files. The cookie itself is logged by + using the text %{cookie}n in the log file format. For + example:

+
+CustomLog logs/clickstream "%{cookie}n %r %t" +
+ +

For backward compatibility the configurable log module + implements the old CookieLog directive, but this + should be upgraded to the above CustomLog directive.

+

2-digit or 4-digit dates for cookies?

+ + +

(the following is from message + <022701bda43d$9d32bbb0$1201a8c0@christian.office.sane.com> + in the new-httpd archives)

+
+From: "Christian Allen" <christian@sane.com>
+Subject: Re: Apache Y2K bug in mod_usertrack.c
+Date: Tue, 30 Jun 1998 11:41:56 -0400
+
+Did some work with cookies and dug up some info that might be useful.
+
+True, Netscape claims that the correct format NOW is four digit dates, and
+four digit dates do in fact work... for Netscape 4.x (Communicator), that
+is.  However, 3.x and below do NOT accept them.  It seems that Netscape
+originally had a 2-digit standard, and then with all of the Y2K hype and
+probably a few complaints, changed to a four digit date for Communicator.
+Fortunately, 4.x also understands the 2-digit format, and so the best way to
+ensure that your expiration date is legible to the client's browser is to
+use 2-digit dates.
+
+However, this does not limit expiration dates to the year 2000; if you use
+an expiration year of "13", for example, it is interpreted as 2013, NOT
+1913!  In fact, you can use an expiration year of up to "37", and it will be
+understood as "2037" by both MSIE and Netscape versions 3.x and up (not sure
+about versions previous to those).  Not sure why Netscape used that
+particular year as its cut-off point, but my guess is that it was in respect
+to UNIX's 2038 problem.  Netscape/MSIE 4.x seem to be able to understand
+2-digit years beyond that, at least until "50" for sure (I think they
+understand up until about "70", but not for sure).
+
+Summary:  Mozilla 3.x and up understands two digit dates up until "37"
+(2037).  Mozilla 4.x understands up until at least "50" (2050) in 2-digit
+form, but also understands 4-digit years, which can probably reach up until
+9999.  Your best bet for sending a long-life cookie is to send it for some
+time late in the year "37".
+
+ +

CookieDomain Directive

Description: controls the setting of the domain to which the tracking cookie applies.
Syntax:CookieDomain domain
Default:None
Context:server config, virtual host, directory, .htaccess
Status:Extension
Module:mod_usertrack
+ +

This directive controls the setting of the domain to which + the tracking cookie applies. If not present, no domain is + included in the cookie header field.

+ +

The domain string must begin with a dot, and + must include at least one embedded dot. That is, + ".foo.com" is legal, but "foo.bar.com" and ".com" are not.

+

CookieExpires Directive

Description:
Syntax:CookieExpires expiry-period
Default:
Context:server config, virtual host, directory, .htaccess
Override:
Status:Extension
Module:mod_usertrack
Compatibility:In 1.3.20 and earlier, not usable in directory and +.htaccess
+

When used, this directive sets an expiry time on the cookie + generated by the usertrack module. The expiry-period + can be given either as a number of seconds, or in the format + such as "2 weeks 3 days 7 hours". Valid denominations are: + years, months, weeks, hours, minutes and seconds. If the expiry + time is in any format other than one number indicating the + number of seconds, it must be enclosed by double quotes.

+ +

If this directive is not used, cookies last only for the + current browser session.

+

CookieName Directive

Description:
Syntax:CookieName token
Default:Apache
Context:server config, virtual host, directory, .htaccess
Status:Extension
Module:mod_usertrack
+

This directive allows you to change the name of the cookie + this module uses for its tracking purposes. By default the + cookie is named "Apache".

+ +

You must specify a valid cookie name; results are + unpredictable if you use a name containing unusual characters. + Valid characters include A-Z, a-z, 0-9, "_", and "-".

+

CookieStyle Directive

Description: Controls the format of the cookie header field
Syntax:CookieStyle + Netscape|Cookie|Cookie2|RFC2109|RFC2965
Default:
Context:server config, virtual host, directory, .htaccess
Status:Extension
Module:mod_usertrack
+

This directive controls the format of the cookie header + field. The three formats allowed are:

+ + + +

Not all clients can understand all of these formats. but you + should use the newest one that is generally acceptable to your + users' browsers.

+

CookieTracking Directive

Description:
Syntax:CookieTracking on|off
Default:
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:Extension
Module:mod_usertrack
+

When the user track module is compiled in, and + "CookieTracking on" is set, Apache will start sending a + user-tracking cookie for all new requests. This directive can + be used to turn this behavior on or off on a per-server or + per-directory basis. By default, compiling mod_usertrack will + not activate cookies.

+ +

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mod_vhost_alias.html.en b/docs/manual/mod/mod_vhost_alias.html.en new file mode 100644 index 0000000000..6537c6db0c --- /dev/null +++ b/docs/manual/mod/mod_vhost_alias.html.en @@ -0,0 +1,205 @@ +mod_vhost_alias- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mod_vhost_alias

Description:Provides for dynamically configured mass virtual +hosting
Status:Extension
Module Identifier:vhost_alias_module

Summary

+ +

This module creates dynamically configured virtual hosts, by + allowing the IP address and/or the Host: header of + the HTTP request to be used as part of the pathname to + determine what files to serve. This allows for easy use of a + huge number of virtual hosts with similar configurations.

+ + +

Directives

See also

Directory Name Interpolation

+ + +

All the directives in this module interpolate a string into + a pathname. The interpolated string (henceforth called the + "name") may be either the server name (see the UseCanonicalName + directive for details on how this is determined) or the IP + address of the virtual host on the server in dotted-quad + format. The interpolation is controlled by specifiers inspired + by printf which have a number of formats:

+ + + + + + + + + + + + +
%%insert a %
%pinsert the port number of the virtual host
%N.Minsert (part of) the name
+ +

N and M are used to specify + substrings of the name. N selects from the + dot-separated components of the name, and M + selects characters within whatever N has selected. + M is optional and defaults to zero if it isn't + present; the dot must be present if and only if M + is present. The interpretation is as follows:

+ + + + + + + + + + + + + + + + + + + + + + + + + +
0the whole name
1the first part
2the second part
-1the last part
-2the penultimate part
2+the second and all subsequent parts
-2+the penultimate and all preceding parts
1+ and -1+the same as 0
+ +

If N or M is greater than the number + of parts available a single underscore is interpolated.

+ +

Examples

+ + +

For simple name-based virtual hosts you might use the + following directives in your server configuration file:

+ +
+ UseCanonicalName Off
+ VirtualDocumentRoot /usr/local/apache/vhosts/%0 +
+ +

A request for + http://www.example.com/directory/file.html will be + satisfied by the file + /usr/local/apache/vhosts/www.example.com/directory/file.html. +

+ +

For a very large number of virtual hosts it is a good idea + to arrange the files to reduce the size of the + vhosts directory. To do this you might use the + following in your configuration file:

+ +
+ UseCanonicalName Off
+ VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2 +
+ +

A request for + http://www.example.isp.com/directory/file.html + will be satisfied by the file + /usr/local/apache/vhosts/isp.com/e/x/a/example/directory/file.html.

+ +

A more even spread of files can be achieved by hashing from the + end of the name, for example:

+ +
+ VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.-1/%2.-2/%2.-3/%2 +
+ +

The example request would come from + /usr/local/apache/vhosts/isp.com/e/l/p/example/directory/file.html.

+ +

Alternatively you might use:

+ +
+ VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2.4+ +
+ +

The example request would come from + /usr/local/apache/vhosts/isp.com/e/x/a/mple/directory/file.html.

+ +

For IP-based virtual hosting you might use the following in + your configuration file:

+ +
+ UseCanonicalName DNS
+ VirtualDocumentRootIP /usr/local/apache/vhosts/%1/%2/%3/%4/docs
+ VirtualScriptAliasIP /usr/local/apache/vhosts/%1/%2/%3/%4/cgi-bin +
+ +

A request for + http://www.example.isp.com/directory/file.html + would be satisfied by the file + /usr/local/apache/vhosts/10/20/30/40/docs/directory/file.html + if the IP address of www.example.com were + 10.20.30.40. A request for + http://www.example.isp.com/cgi-bin/script.pl would + be satisfied by executing the program + /usr/local/apache/vhosts/10/20/30/40/cgi-bin/script.pl.

+ +

If you want to include the . character in a + VirtualDocumentRoot directive, but it clashes with + a % directive, you can work around the problem in + the following way:

+ +
+ VirtualDocumentRoot /usr/local/apache/vhosts/%2.0.%3.0 +
+ +

A request for + http://www.example.isp.com/directory/file.html + will be satisfied by the file + /usr/local/apache/vhosts/example.isp/directory/file.html.

+ +

The LogFormat + directives %V and %A are useful + in conjunction with this module.

+

VirtualDocumentRoot Directive

Description: Dynamically configure the location of the document root +for a given virtual host
Syntax:VirtualDocumentRoot interpolated-directory
Default:none
Context:server config, virtual host
Override:
Status:Extension
Module:mod_vhost_alias
Compatibility:VirtualDocumentRoot is only available in 1.3.7 and +later.
+ +

The VirtualDocumentRoot directive allows you to + determine where Apache will find your documents based on the + value of the server name. The result of expanding + interpolated-directory is used as the root of the + document tree in a similar manner to the DocumentRoot directive's argument. + If interpolated-directory is none then + VirtaulDocumentRoot is turned off. This directive + cannot be used in the same context as + VirtualDocumentRootIP.

+ +

VirtualDocumentRootIP Directive

Description: Dynamically configure the location of the document root +for a given virtual host
Syntax:VirtualDocumentRootIP interpolated-directory
Default:none
Context:server config, virtual host
Override:
Status:Extension
Module:mod_vhost_alias
Compatibility:VirtualDocumentRootIP is only available in 1.3.7 +and later.
+ +

The VirtualDocumentRootIP directive is like the + VirtualDocumentRoot + directive, except that it uses the IP address of the server end + of the connection instead of the server name.

+

VirtualScriptAlias Directive

Description: Dynamically configure the location of the CGI directory for +a given virtual host
Syntax:VirtualScriptAlias interpolated-directory
Default:none
Context:server config, virtual host
Override:
Status:Extension
Module:mod_vhost_alias
Compatibility:VirtualScriptAlias is only available in 1.3.7 +and later.
+ +

The VirtualScriptAlias directive allows you to + determine where Apache will find CGI scripts in a similar + manner to VirtualDocumentRoot + does for other documents. It matches requests for URIs starting + /cgi-bin/, much like ScriptAlias + /cgi-bin/ would.

+ +

VirtualScriptAliasIP Directive

Description: Dynamically configure the location of the cgi directory for +a given virtual host
Syntax:VirtualScriptAliasIP interpolated-directory
Default:none
Context:server config, virtual host
Override:
Status:Extension
Module:mod_vhost_alias
Compatibility:VirtualScriptAliasIP is only available in 1.3.7 +and later.
+ +

The VirtualScriptAliasIP directive is like the + VirtualScriptAlias + directive, except that it uses the IP address of the server end + of the connection instead of the server name.

+ +

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mpm_common.html.en b/docs/manual/mod/mpm_common.html.en new file mode 100644 index 0000000000..1e101f6e7c --- /dev/null +++ b/docs/manual/mod/mpm_common.html.en @@ -0,0 +1,338 @@ +mpm_common- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mpm_common

Description:A collection of directives that are implemented by +more than one multi-processing module (MPM)
Status:MPM

Directives

CoreDumpDirectory Directive

Description: Sets the directory where Apache attempts to +switch before dumping core
Syntax:CoreDumpDirectory directory
Default:See usage for the default setting
Context:server config
Status:MPM
Module:worker, perchild, prefork, mpm_winnt
+ +

This controls the directory to which Apache attempts to + switch before dumping core. The default is in the + ServerRoot directory, however + since this should not be writable by the user the server runs + as, core dumps won't normally get written. If you want a core + dump for debugging, you can use this directive to place it in a + different location.

+

Group Directive

Description: Sets the group under which the server will answer +requests
Syntax:Group unix-group
Default:Group #-1
Context:server config, virtual host
Status:MPM
Module:worker, perchild, prefork
+

The Group directive sets the group under + which the server will answer requests. In order to use this + directive, the stand-alone server must be run initially as root. + Unix-group is one of:

+ +
+
A group name
+ +
Refers to the given group by name.
+ +
# followed by a group number.
+ +
Refers to a group by its number.
+
+

It is recommended that you set up a new group specifically for + running the server. Some admins use user nobody, + but this is not always possible or desirable.

+ +

Note: if you start the server as a non-root user, it will + fail to change to the specified group, and will instead + continue to run as the group of the original user.

+ +

Special note: Use of this directive in <VirtualHost> is + no longer supported. To implement the suEXEC wrapper with Apache 2.0, use the + SuexecUserGroup + directive. SECURITY: See User for a discussion of the + security considerations.

+

Listen Directive

Description: Sets the IP addresses and ports that the server +listens to
Syntax:Listen [IP-address:]portnumber
Context:server config
Status:MPM
Module:worker, perchild, prefork, mpm_winnt
+

The Listen directive instructs Apache to + listen to only specific IP addresses or ports; by default it + responds to requests on all IP interfaces. The Listen directive is + now a required directive. If it is not in the config file, the + server will fail to start. This is a change from previous versions + of Apache.

+ +

The Listen directive tells the server to accept incoming + requests on the specified port or address-and-port combination. + If only a port number is specified, the server listens to the + given port on all interfaces. If an IP address is given as well + as a port, the server will listen on the given port and + interface.

+ +

Multiple Listen directives may be used to specify a number + of addresses and ports to listen to. The server will respond to + requests from any of the listed addresses and ports.

+ +

For example, to make the server accept connections on both + port 80 and port 8000, use:

+
+ Listen 80
+ Listen 8000 +
+

To make the server accept connections on two specified + interfaces and port numbers, use

+
+ Listen 192.170.2.1:80
+ Listen 192.170.2.5:8000 +
+

IPv6 addresses must be surrounded in square brackets, as in the + following example:

+
+ Listen [fe80::a00:20ff:fea7:ccea]:80 +
+

See also

ListenBackLog Directive

Description: Maximum length of the queue of pending connections
Syntax:ListenBacklog backlog
Default:ListenBacklog 511
Context:server config
Status:MPM
Module:worker, perchild, prefork, mpm_winnt
+

The maximum length of the queue of pending connections. + Generally no tuning is needed or desired, however on some + systems it is desirable to increase this when under a TCP SYN + flood attack. See the backlog parameter to the + listen(2) system call.

+ +

This will often be limited to a smaller number by the + operating system. This varies from OS to OS. Also note that + many OSes do not use exactly what is specified as the backlog, + but use a number based on (but normally larger than) what is + set.

+

LockFile Directive

Description: Location of the accept serialization lock file
Syntax:LockFile filename
Default:LockFile logs/accept.lock
Context:server config
Status:MPM
Module:worker, perchild, prefork
+

The LockFile directive sets the path to + the lockfile used when Apache is compiled with either + USE_FCNTL_SERIALIZED_ACCEPT or USE_FLOCK_SERIALIZED_ACCEPT. This + directive should normally be left at its default value. The main + reason for changing it is if the logs directory is + NFS mounted, since the lockfile must be stored on a local + disk. The PID of the main server process is + automatically appended to the filename.

+ +

SECURITY: It is best to avoid putting this + file in a world writable directory such as + /var/tmp because someone could create a denial of + service attack and prevent the server from starting by creating + a lockfile with the same name as the one the server will try to + create.

+

MaxClients Directive

Description: Maximum number of child processes that will be created +to serve requests
Syntax:MaxClients number
Default:>MaxClients + 8 (with threads) MaxClients 256
Context:server config
Status:MPM
Module:worker, prefork
+

The MaxClients directive sets the limit + on the number of child processes that will be created to serve + requests. When the server is built without threading, no more than + this number of clients can be served simultaneously. To configure + more than 256 clients with the prefork MPM, you must use the + ServerLimit directive. + To configure more than 1024 clients with the worker MPM, you must + use the ServerLimit and + ThreadLimit directives.

+ +

Any connection attempts over the + MaxClients limit will normally be queued, + up to a number based on the ListenBacklog directive. Once a child + process is freed at the end of a different request, the connection + will then be serviced.

+ +

When the server is compiled with threading, then the maximum + number of simultaneous requests that can be served is obtained + from the value of this directive multiplied by + ThreadsPerChild.

+

MaxRequestsPerChild Directive

Description: Limit on the number of requests that an individual child server +will handle during its life
Syntax:MaxRequestsPerChild number
Default:MaxRequestsPerChild 10000
Context:server config
Status:MPM
Module:worker, perchild, prefork, mpm_winnt
+

The MaxRequestsPerChild directive sets + the limit on the number of requests that an individual child + server process will handle. After + MaxRequestsPerChild requests, the child + process will die. If MaxRequestsPerChild is + 0, then the process will never expire.

+ +

Setting MaxRequestsPerChild to a + non-zero limit has two beneficial effects:

+ + + +

NOTE: For KeepAlive requests, only + the first request is counted towards this limit. In effect, it + changes the behavior to limit the number of + connections per child.

+

MaxSpareThreads Directive

Description: Maximum number of idle threads
Syntax:MaxSpareThreads number
Default:MaxSpareThreads 10 (Perchild) or 500 (worker)
Context:server config
Status:MPM
Module:worker, perchild
+

Maximum number of idle threads. Different MPMs deal with this + directive differently. perchild monitors the + number of idle threads on a per-child basis. If there are too many + idle threads in that child, the server will begin to kill threads + within that child.

+ +

worker deals with idle threads on a + server-wide basis. If there are too many idle threads in the + server then child processes are killed until the number of idle + threads is less than this number.

+ +

See also

MaxThreadsPerChild Directive

Description: Maximum number of threads per child process
Syntax:MaxThreadsPerChild number
Default:MaxThreadsPerChild 64
Context:server config
Status:MPM
Module:worker, perchild
+

Maximum number of threads per child. For MPMs with a + variable number of threads per child, this directive sets the + maximum number of threads that will be created in each child + process. To increase this value beyond its default, it is + necessary to change the value of the compile-time define + HARD_THREAD_LIMIT and recompile the server.

+

MinSpareThreads Directive

Description: Minimum number of idle threads available to handle request +spikes
Syntax:MinSpareServers number
Default:MinSpareThreads 5 (Perchild) or 250 (worker)
Context:server config
Status:MPM
Module:worker, perchild
+

Minimum number of idle threads to handle request spikes. + Different MPMs deal with this directive + differently. perchild monitors the number of idle + threads on a per-child basis. If there aren't enough idle threads + in that child, the server will begin to create new threads within + that child.

+ +

worker deals with idle threads on a + server-wide basis. If there aren't enough idle threads in the + server then child processes are created until the number of idle + threads is greater than number.

+

See also

NumServers Directive

Description: Total number of children alive at the same time
Syntax:NumServers number
Default:NumServers 2
Context:server config
Status:MPM
Module:perchild
+

Number of children alive at the same time. MPMs that use + this directive do not dynamically create new child processes so + this number should be large enough to handle the requests for + the entire site.

+

PidFile Directive

Description: Sets the file where the server records the process ID +of the daemon
Syntax:PidFile filename
Default:PidFile logs/httpd.pid
Context:server config
Status:MPM
Module:worker, perchilde, prefork, mpm_winnt
+

The PidFile directive sets the file to + which the server records the process id of the daemon. If the + filename does not begin with a slash (/) then it is assumed to be + relative to the ServerRoot.

+ +

It is often useful to be able to send the server a signal, + so that it closes and then reopens its ErrorLog and TransferLog, and + re-reads its configuration files. This is done by sending a + SIGHUP (kill -1) signal to the process id listed in the + PidFile.

+ +

The PidFile is subject to the same warnings about log file + placement and security.

+

ScoreBoardFile Directive

Description: Location of the file used to store coordination data for +the child processes
Syntax:ScoreBoardFile file-path
Default:ScoreBoardFile logs/apache_status
Context:server config
Status:MPM
Module:worker, perchild, prefork
+

Apache uses a scoreboard to communicate between its parent + and child processes. Some architectures require a file to facilitate + this communication. If the file is left unspecified, Apache first + attempts to create the scoreboard entirely in memory (using anonymous + shared memory) and, failing that, will attempt to create the file on + disk (using file-based shared memory). Specifying this directive causes + Apache to always create the file on the disk.

+ +

File-based shared memory is useful for third-party applications + that require direct access to the scoreboard.

+ +

If you use a ScoreBoardFile then + you may see improved speed by placing it on a RAM disk. But be + careful that you heed the same warnings about log file placement + and security.

+

See also

SendBufferSize Directive

Description: TCP buffer size
Syntax:SendBufferSize bytes
Context:server config
Status:MPM
Module:worker, perchild, prefork, mpm_winnt
+

The server will set the TCP buffer size to the number of bytes + specified. Very useful to increase past standard OS defaults on + high speed high latency (i.e., 100ms or so, such as + transcontinental fast pipes).

+

ServerLimit Directive

Description: Upper limit on configurable number of processes
Syntax:ServerLimit number
Default:ServerLimit 256 (prefork), ServerLimit 16 (worker)
Context:server config
Status:MPM
Module:worker, prefork
+

For the prefork MPM, this directive sets the + maximum configured value for MaxClients for the lifetime of the + Apache process. For the worker MPM, this directive in combination + with ThreadLimit sets + the maximum configured value for MaxClients for the lifetime of the + Apache process. Any attempts to change this directive during a + restart will be ignored, but MaxClients can be modified during + a restart.

+ +

Special care must be taken when using this directive. If + ServerLimit is set to a value much higher + than necessary, extra, unused shared memory will be allocated. If + both ServerLimit and MaxClients are set to values + higher than the system can handle, Apache may not start or the + system may become unstable.

+ +

With the prefork MPM, use this directive only + if you need to set MaxClients higher higher than 256. + Do not set the value of this directive any higher than what you + might want to set MaxClients to.

+ +

With the worker MPM, use this directive only + if your MaxClients and + ThreadsPerChild + settings require more than 16 server processes. Do not set the + value of this directive any higher than the number of server + processes required by what you may want for MaxClients and ThreadsPerChild.

+

StartServers Directive

Description: Number of child server processes created at startup
Syntax:StartServers number
Default:StartServers 5
Context:server config
Status:MPM
Module:worker
+

The StartServers directive sets the + number of child server processes created on startup. As the number + of processes is dynamically controlled depending on the load, + there is usually little reason to adjust this parameter.

+

See also

StartThreads Directive

Description: Nubmer of threads each child creates on startup
Syntax:StartThreads number
Default:StartThreads 5
Context:server config
Status:MPM
Module:perchild
+

Number of threads each child creates on startup. As the + number of threads is dynamically controlled depending on the + load, there is usually little reason to adjust this + parameter.

+

ThreadLimit Directive

Description: Sets the upper limit on the configurable number of threads +per child process
Syntax:ThreadLimit number
Default:ThreadLimit 64
Context:server config
Status:MPM
Module:worker
+

This directive sets the maximum configured value for ThreadsPerChild for the lifetime + of the Apache process. Any attempts to change this directive + during a restart will be ignored, but ThreadsPerChild can be modified + during a restart up to the value of this directive.

+ +

Special care must be taken when using this directive. If + ThreadLimit is set to a value much higher + than ThreadsPerChild, + extra unused shared memory will be allocated. If both + ThreadLimit and ThreadsPerChild are set to values + higher than the system can handle, Apache may not start or the + system may become unstable.

+ +

Use this directive only if you need to set ThreadsPerChild higher than 64. Do + not set the value of this directive any higher than what you might + want to set ThreadsPerChild to.

+

ThreadsPerChild Directive

Description: Number of threads created by each child process
Syntax:ThreadsPerChild number
Default:ThreadsPerChild 50
Context:server config
Status:MPM
Module:worker, mpm_winnt
+

This directive sets the number of threads created by each + child process. The child creates these threads at startup and + never creates more. if using an MPM like mpmt_winnt, where + there is only one child process, this number should be high + enough to handle the entire load of the server. If using an MPM + like worker, where there are multiple child processes, the + total number of threads should be high enough to handle the + common load on the server.

+

User Directive

Description: The userid under which the server will answer +requests
Syntax:User unix-userid
Default:User #-1
Context:server config, virtual host
Status:MPM
Module:worker, perchild, prefork
+

The User directive sets the userid as + which the server will answer requests. In order to use this + directive, the standalone server must be run initially as + root. Unix-userid is one of:

+ +
+
A username
+ +
Refers to the given user by name.
+ +
# followed by a user number.
+ +
Refers to a user by their number.
+
+ +

The user should have no privileges which result in it being + able to access files which are not intended to be visible to the + outside world, and similarly, the user should not be able to + execute code which is not meant for httpd requests. It is + recommended that you set up a new user and group specifically for + running the server. Some admins use user nobody, but + this is not always possible or desirable. For example + mod_proxy's cache, when enabled, must be + accessible to this user (see CacheRoot).

+ +

Notes: If you start the server as a non-root user, it will + fail to change to the lesser privileged user, and will instead + continue to run as that original user. If you do start the + server as root, then it is normal for the parent process to + remain running as root.

+ +

Special note: Use of this directive in <VirtualHost> is no longer supported. To + configure your server for suexec use + SuexecUserGroup.

+ +

Security

Don't set User +(or Group) to +root unless you know exactly what you are doing, and what +the dangers are.

+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mpm_netware.html.en b/docs/manual/mod/mpm_netware.html.en new file mode 100644 index 0000000000..d6819f3b3f --- /dev/null +++ b/docs/manual/mod/mpm_netware.html.en @@ -0,0 +1,68 @@ +mpm_netware- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mpm_netware

Description:Multi-Processing Module implementing an exclusively threaded web + server optimized for Novell NetWare
Status:MPM
Module Identifier:mpm_netware_module

Summary

+

This Multi-Processing Module (MPM) implements an exclusively threaded web server + that has been optimized for Novell NetWare.

+ +

The main thread is responsible for launching child + worker threads which listen for connections and serve them when they + arrive. Apache always tries to maintain several spare + or idle worker threads, which stand ready to serve incoming + requests. In this way, clients do not need to wait for a new + child threads to be spawned before their requests can be + served.

+ +

The StartThreads, MinSpareThreads, + MaxSpareThreads, and MaxThreads + regulate how the main thread creates worker threads to serve + requests. In general, Apache is very self-regulating, so most + sites do not need to adjust these directives from their default + values. Sites which need to serve more than 250 simultaneous + requests may need to increase MaxThreads, while + sites with limited memory may need to decrease + MaxThreads to keep the server from thrashing (spawning and + terminating idle threads). More information about + tuning process creation is provided in the performance hints + documentation.

+ +

MaxRequestsPerChild controls how frequently the + server recycles processes by killing old ones and launching new + ones.  On the NetWare OS it is highly recommended that this directive + remain set to 0.  This allows worker threads to continue servicing + requests indefinitely.

+ +

See also: Setting which addresses and + ports Apache uses.

+

Directives

MaxSpareThreads Directive

Description:
Syntax:MaxSpareThreads number
Default:MaxSpareThreads 100
Context:server config
Status:MPM
Module:mpm_netware
+

The MaxSpareThreads directive sets the + desired maximum number of idle worker threads. An idle + worker thread is one which is not handling a request. If there are + more than MaxSpareThreads idle, then the main thread will kill off + the excess worker threads.

+ +

Tuning of this parameter should only be necessary on very + busy sites. Setting this parameter to a large number is almost + always a bad idea.

+

MaxThreads Directive

Description:
Syntax:MaxThreads number
Default:MaxThreads 250
Context:server config
Status:MPM
Module:mpm_netware
+

The MaxThreads directive sets the desired maximum + number worker threads allowable.

+

MinSpareThreads Directive

Description:
Syntax:MinSpareThreads number
Default:MinSpareThreads 10
Context:server config
Status:MPM
Module:mpm_netware
+

The MinSpareThreads directive sets the +desired minimum number of idle worker threads. An idle worker +thread is one which is not handling a request. If there are fewer than +MinSpareThreads idle, then the main thread spawns new worker.

+ +

Tuning of this parameter should only be necessary on very + busy sites. Setting this parameter to a large number is almost + always a bad idea.

+

StartThreads Directive

Description:
Syntax:StartThreads number
Default:StartThreads 50
Context:server config
Status:MPM
Module:mpm_netware
+

The StartThreads directive sets the desired + number of worker threads to spawn and startup

+

ThreadStackSize Directive

Description:
Syntax:ThreadStackSize number
Default:ThreadStackSize 65536
Context:server config
Status:MPM
Module:mpm_netware
+

This directive tells the server what stack size to use for + each of the running threads. If you ever get a stack overflow + you will need to bump this number to a higher setting.

+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/mpm_winnt.html.en b/docs/manual/mod/mpm_winnt.html.en new file mode 100644 index 0000000000..d116d0d728 --- /dev/null +++ b/docs/manual/mod/mpm_winnt.html.en @@ -0,0 +1,11 @@ +mpm_winnt- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module mpm_winnt

Description:This Multi-Processing Module is optimized for Windows + NT.
Status:MPM
Module Identifier:mpm_winnt_module

Summary

+

This Multi-Processing Module (MPM) is the default for the + Windows NT operating systems. It uses a single control process + which launches a single child process which in turn creates + threads to handle requests

+

Directives

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/perchild.html.en b/docs/manual/mod/perchild.html.en new file mode 100644 index 0000000000..cc85838e0d --- /dev/null +++ b/docs/manual/mod/perchild.html.en @@ -0,0 +1,73 @@ +perchild- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module perchild

Description:Multi-Processing Module allowing for daemon processes + serving requests to be assigned a variety of different + userids
Status:MPM
Module Identifier:mpm_perchild_module

Summary

+
+This MPM does not currently work on most platforms. Work is ongoing to +make it functional. +
+ +

This Multi-Processing Module (MPM) implements a hybrid + multi-process, multi-threaded web server. A fixed number of + processes create threads to handle requests. Fluctuations in + load are handled by increasing or decreasing the number of + threads in each process.

+ +

A single control process launches the number of child processes + indicated by the NumServers directive at server + startup. Each child process creates threads as specified in the + StartThreads directive. The individual threads then + listen for connections and serve them when they arrive.

+ +

Apache always tries to maintain a pool of spare or + idle server threads, which stand ready to serve incoming + requests. In this way, clients do not need to wait for new + threads to be created. For each child process, Apache assesses + the number of idle threads and creates or destroys threads to + keep this number within the boundaries specified by + MinSpareThreads and MaxSpareThreads. + Since this process is very self-regulating, it is rarely + necessary to modify these directives from their default values. + The maximum number of clients that may be served simultaneously + is determined by multiplying the number of server processes + that will be created (NumServers) by the maximum + number of threads created in each process + (MaxThreadsPerChild).

+ +

While the parent process is usually started as root under + Unix in order to bind to port 80, the child processes and + threads are launched by Apache as a less-privileged user. The + User and Group directives are used to + set the privileges of the Apache child processes. The child + processes must be able to read all the content that will be + served, but should have as few privileges beyond that as + possible. In addition, unless suexec is used, these directives also + set the privileges which will be inherited by CGI scripts.

+ +

MaxRequestsPerChild controls how frequently the + server recycles processes by killing old ones and launching new + ones.

+ +

See also: Setting which addresses and + ports Apache uses.

+ +

In addition it adds the extra ability to specify that + specific processes should serve requests under different + userids. These processes can then be associated with specific + virtual hosts.

+ +

Directives

AssignUserId Directive

Description:
Syntax:AssignUserID user_id group_id
Context:virtual host
Status:MPM
Module:perchild
+

Tie a virtual host to a specific child process. Requests addressed to +the virtual host where this directive appears will be served by the process +running with the specified user and group id.

+

ChildPerUserId Directive

Description:
Syntax:ChildPerUserID user_id +group_id child_id
Context:server config
Status:MPM
Module:perchild
+

Specify a user id and group id for a specific child process. The number of +children if set by the NumServers +directive. For example, the default value for NumServers is 5 and that means +children ids 1,2,3,4 and 5 are available for assigment. If a child does not +have an associated ChildPerUserID, it inherits the User and Group settings from the main server

+

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/prefork.html.en b/docs/manual/mod/prefork.html.en new file mode 100644 index 0000000000..19605b5144 --- /dev/null +++ b/docs/manual/mod/prefork.html.en @@ -0,0 +1,106 @@ +prefork- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module prefork

Description:Implements a non-threaded, pre-forking web server
Status:MPM
Module Identifier:mpm_prefork_module

Summary

+

This Multi-Processing Module (MPM) implements a + non-threaded, pre-forking web server which handles request in a + manner very similar to the default behavior of Apache 1.3 on + Unix.

+ +

A single control process is responsible for launching child + processes which listen for connections and serve them when they + arrive. Apache always tries to maintain several spare + or idle server processes, which stand ready to serve incoming + requests. In this way, clients do not need to wait for a new + child processes to be forked before their requests can be + served.

+ +

The StartServers, + MinSpareServers, + MaxSpareServers, and + MaxClients regulate how + the parent process creates children to serve requests. In general, + Apache is very self-regulating, so most sites do not need to + adjust these directives from their default values. Sites which + need to serve more than 256 simultaneous requests may need to + increase MaxClients, + while sites with limited memory may need to decrease MaxClients to keep the server from + thrashing (swapping memory to disk and back). More information + about tuning process creation is provided in the performance hints + documentation.

+ +

While the parent process is usually started as root under Unix + in order to bind to port 80, the child processes are launched by + Apache as a less-privileged user. The User and Group directives are used to set + the privileges of the Apache child processes. The child processes + must be able to read all the content that will be served, but + should have as few privileges beyond that as possible. In + addition, unless suexec is used, + these directives also set the privileges which will be inherited + by CGI scripts.

+ +

MaxRequestsPerChild + controls how frequently the server recycles processes by killing + old ones and launching new ones.

+

Directives

See also

AcceptMutex Directive

Description: Method that Apache uses to serialize multiple children +accepting requests on network sockets
Syntax:AcceptMutex default|method
Default:AcceptMutex default
Context:server config
Status:MPM
Module:prefork
+

The AcceptMutex directives sets the + method that Apache uses to serialize multiple children accepting + requests on network sockets. Prior to Apache 2.0, the method was + selectable only at compile time. The optimal method to use is + highly architecture and platform dependent. For further details, + see the performance tuning + documentation.

+ +

If this directive is set to default, then the + compile-time selected default will be used. Other possible + methods are listed below. Note that not all methods are + available on all platforms. If a method is specified which is + not available, a message will be written to the error log + listing the available methods.

+ +
+
flock
+ +
uses the flock(2) system call to lock the + file defined by the LockFile directive.
+ +
fcntl
+ +
uses the fnctl(2) system call to lock the + file defined by the LockFile directive.
+ +
sysvsem
+ +
uses SySV-style semaphores to implement the mutex.
+ +
pthread
+ +
uses POSIX mutexes as implemented by the POSIX Threads + (PThreads) specification.
+
+

MaxSpareServers Directive

Description: Maximum number of idle child server processes
Syntax:MaxSpareServers number
Default:MaxSpareServers 10
Context:server config
Status:MPM
Module:prefork
+

The MaxSpareServers directive sets the + desired maximum number of idle child server processes. An + idle process is one which is not handling a request. If there are + more than MaxSpareServers idle, then the parent process will kill + off the excess processes.

+ +

Tuning of this parameter should only be necessary on very + busy sites. Setting this parameter to a large number is almost + always a bad idea.

+

See also

MinSpareServers Directive

Description: Minimum number of idle child server processes
Syntax:MinSpareServers number
Default:MinSpareServers 5
Context:server config
Status:MPM
Module:prefork
+

The MinSpareServers directive sets the + desired minimum number of idle child server processes. An + idle process is one which is not handling a request. If there are + fewer than MinSpareServers idle, then the parent process creates + new children at a maximum rate of 1 per second.

+ +

Tuning of this parameter should only be necessary on very + busy sites. Setting this parameter to a large number is almost + always a bad idea.

+ +

This directive has no effect on Microsoft Windows.

+

See also

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file diff --git a/docs/manual/mod/worker.html.en b/docs/manual/mod/worker.html.en new file mode 100644 index 0000000000..dac5d8964e --- /dev/null +++ b/docs/manual/mod/worker.html.en @@ -0,0 +1,49 @@ +worker- Apache HTTP Server
[APACHE DOCUMENTATION]

Apache HTTP Server Version 2.0

Apache Module worker

Description:Multi-Processing Module implementing a hybrid + multi-threaded multi-process web server
Status:MPM
Module Identifier:mpm_worker_module

Summary

+

This Multi-Processing Module (MPM) implements a hybrid + multi-process multi-threaded server. Each process has a fixed + number of threads. The server adjusts to handle load by + increasing or decreasing the number of processes.

+ +

A single control process is responsible for launching child + processes. Each child process creates a fixed number of threads + as specified in the ThreadsPerChild directive. The + individual threads then listen for connections and serve them + when they arrive.

+ +

Apache always tries to maintain a pool of spare or + idle server threads, which stand ready to serve incoming + requests. In this way, clients do not need to wait for a new + threads or processes to be created before their requests can be + served. Apache assesses the total number of idle threads in all + processes, and forks or kills processes to keep this number + within the boundaries specified by MinSpareThreads + and MaxSpareThreads. Since this process is very + self-regulating, it is rarely necessary to modify these + directives from their default values. The maximum number of + clients that may be served simultaneously is determined by + multiplying the maximum number of server processes that will be + created (MaxClients) by the number of threads + created in each process (ThreadsPerChild).

+ +

While the parent process is usually started as root under + Unix in order to bind to port 80, the child processes and + threads are launched by Apache as a less-privileged user. The + User and Group directives are used to + set the privileges of the Apache child processes. The child + processes must be able to read all the content that will be + served, but should have as few privileges beyond that as + possible. In addition, unless suexec is used, these directives also + set the privileges which will be inherited by CGI scripts.

+ +

MaxRequestsPerChild controls how frequently the + server recycles processes by killing old ones and launching new + ones.

+ +

See also: Setting which addresses and + ports Apache uses.

+

Directives

Apache HTTP Server Version 2.0

IndexHome \ No newline at end of file -- cgit v1.2.1