From: Daniel Ruggeri Date: Wed, 15 Apr 2015 17:04:53 +0000 (+0000) Subject: We need moar emails - format change X-Git-Tag: 2.2.30~154 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=82406f391ff6193d34ab9d95f186ecb6ec4ae59d;p=thirdparty%2Fapache%2Fhttpd.git We need moar emails - format change git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.2.x@1673876 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/beos.html.en b/docs/manual/mod/beos.html.en index 73da3b63f28..ce0618dec39 100644 --- a/docs/manual/mod/beos.html.en +++ b/docs/manual/mod/beos.html.en @@ -61,6 +61,7 @@
  • Setting which addresses and ports Apache uses
    • +
    top

    MaxRequestsPerThread Directive

    @@ -97,7 +98,6 @@ will handle during its life -

    Available Languages:  de  | diff --git a/docs/manual/mod/core.html.en b/docs/manual/mod/core.html.en index 5cf42628936..b767ba23033 100644 --- a/docs/manual/mod/core.html.en +++ b/docs/manual/mod/core.html.en @@ -107,6 +107,7 @@ available

  • <VirtualHost>
    • +
    top

    AcceptFilter Directive

    @@ -3715,7 +3716,6 @@ hostname or IP address different sections are combined when a request is received -

    Available Languages:  de  | diff --git a/docs/manual/mod/event.html.en b/docs/manual/mod/event.html.en index 48c2a4dda24..2d313037e4c 100644 --- a/docs/manual/mod/event.html.en +++ b/docs/manual/mod/event.html.en @@ -52,7 +52,11 @@ MPM script's arguments when building the httpd.

    -

    Directives

    +

    Topics

    +

    Directives

    -

    Topics

    -

    See also

    +

    See also

    diff --git a/docs/manual/mod/mod_actions.html.en b/docs/manual/mod/mod_actions.html.en index 8345aff3d7f..3240ac64e35 100644 --- a/docs/manual/mod/mod_actions.html.en +++ b/docs/manual/mod/mod_actions.html.en @@ -53,6 +53,7 @@ media type or request method.
  • Dynamic Content with CGI
  • Apache's Handler Use
    • +
    top

    Action Directive

    @@ -154,7 +155,6 @@ method.

    -

    Available Languages:  de  | diff --git a/docs/manual/mod/mod_alias.html.en b/docs/manual/mod/mod_alias.html.en index dba44a92d13..8401e494770 100644 --- a/docs/manual/mod/mod_alias.html.en +++ b/docs/manual/mod/mod_alias.html.en @@ -56,7 +56,10 @@ mod_rewrite.

    -

    Directives

    +
    top
    +
    +

    Order of Processing

    + +

    Aliases and Redirects occurring in different contexts are processed + like other directives according to standard merging rules. But when multiple + Aliases or Redirects occur in the same context (for example, in the + same <VirtualHost> + section) they are processed in a particular order.

    + +

    First, all Redirects are processed before Aliases are processed, + and therefore a request that matches a Redirect or RedirectMatch will never have Aliases + applied. Second, the Aliases and Redirects are processed in the order + they appear in the configuration files, with the first match taking + precedence.

    + +

    For this reason, when two or more of these directives apply to the + same sub-path, you must list the most specific path first in order for + all the directives to have an effect. For example, the following + configuration will work as expected:

    + +

    + Alias /foo/bar /baz
    + Alias /foo /gaq +

    + +

    But if the above two directives were reversed in order, the + /foo Alias + would always match before the /foo/bar Alias, so the latter directive would be + ignored.

    + +
    +
    top

    Alias Directive

    @@ -489,38 +521,6 @@ and designates the target as a CGI script details.

    - -
    top
    -
    -

    Order of Processing

    - -

    Aliases and Redirects occurring in different contexts are processed - like other directives according to standard merging rules. But when multiple - Aliases or Redirects occur in the same context (for example, in the - same <VirtualHost> - section) they are processed in a particular order.

    - -

    First, all Redirects are processed before Aliases are processed, - and therefore a request that matches a Redirect or RedirectMatch will never have Aliases - applied. Second, the Aliases and Redirects are processed in the order - they appear in the configuration files, with the first match taking - precedence.

    - -

    For this reason, when two or more of these directives apply to the - same sub-path, you must list the most specific path first in order for - all the directives to have an effect. For example, the following - configuration will work as expected:

    - -

    - Alias /foo/bar /baz
    - Alias /foo /gaq -

    - -

    But if the above two directives were reversed in order, the - /foo Alias - would always match before the /foo/bar Alias, so the latter directive would be - ignored.

    -
    diff --git a/docs/manual/mod/mod_asis.html.en b/docs/manual/mod/mod_asis.html.en index 413735d00da..4bdb18c23e5 100644 --- a/docs/manual/mod/mod_asis.html.en +++ b/docs/manual/mod/mod_asis.html.en @@ -46,13 +46,13 @@ HTTP headers

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

    -

    Directives

    -

    This module provides no - directives.

    -

    Topics

    +

    Topics

    See also

    +

    Directives

    +

    This module provides no + directives.

    +

    See also

    • mod_headers
    • mod_cern_meta
      • diff --git a/docs/manual/mod/mod_auth_basic.html.en b/docs/manual/mod/mod_auth_basic.html.en index 6ae22fab6b6..718d4bf5376 100644 --- a/docs/manual/mod/mod_auth_basic.html.en +++ b/docs/manual/mod/mod_auth_basic.html.en @@ -57,6 +57,7 @@
    • Satisfy
    • Authentication howto
    +
    top

    AuthBasicAuthoritative Directive

    Description:Maps URLs to filesystem locations
    @@ -124,7 +125,6 @@ lower level modules and mod_authnz_ldap.

    -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_auth_digest.html.en b/docs/manual/mod/mod_auth_digest.html.en index 01d38639fdf..fb19c54a5a9 100644 --- a/docs/manual/mod/mod_auth_digest.html.en +++ b/docs/manual/mod/mod_auth_digest.html.en @@ -46,7 +46,10 @@ whole connection using mod_ssl is a much better alternative.

    -

    Directives

    +
    top
    +
    +

    Using Digest Authentication

    + +

    Using MD5 Digest authentication is very simple. Simply set + up authentication normally, using AuthType Digest and + AuthDigestProvider + instead of the normal AuthType Basic and + AuthBasicProvider. + Then add a AuthDigestDomain directive containing at least the root + URI(s) for this protection space.

    + +

    Appropriate user (text) files can be created using the + htdigest tool.

    + +

    Example:

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

    + +

    Note

    +

    Digest authentication was intended to be more secure than basic + authentication, but no longer fulfills that design goal. A + man-in-the-middle attacker can trivially force the browser to downgrade + to basic authentication. And even a passive eavesdropper can brute-force + the password using today's graphics hardware, because the hashing + algorithm used by digest authentication is too fast. Another problem is + that the storage of the passwords on the server is insecure. The contents + of a stolen htdigest file can be used directly for digest authentication. + Therefore using mod_ssl to encrypt the whole connection is + strongly recommended.

    +
    +
    +
    top

    AuthDigestAlgorithm Directive

    -
    top
    -
    -

    Using Digest Authentication

    - -

    Using MD5 Digest authentication is very simple. Simply set - up authentication normally, using AuthType Digest and - AuthDigestProvider - instead of the normal AuthType Basic and - AuthBasicProvider. - Then add a AuthDigestDomain directive containing at least the root - URI(s) for this protection space.

    - -

    Appropriate user (text) files can be created using the - htdigest tool.

    - -

    Example:

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

    - -

    Note

    -

    Digest authentication was intended to be more secure than basic - authentication, but no longer fulfills that design goal. A - man-in-the-middle attacker can trivially force the browser to downgrade - to basic authentication. And even a passive eavesdropper can brute-force - the password using today's graphics hardware, because the hashing - algorithm used by digest authentication is too fast. Another problem is - that the storage of the passwords on the server is insecure. The contents - of a stolen htdigest file can be used directly for digest authentication. - Therefore using mod_ssl to encrypt the whole connection is - strongly recommended.

    -
    -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_authn_alias.html.en b/docs/manual/mod/mod_authn_alias.html.en index c802ef0957a..3eae6b25a8c 100644 --- a/docs/manual/mod/mod_authn_alias.html.en +++ b/docs/manual/mod/mod_authn_alias.html.en @@ -46,37 +46,14 @@ locations.

    -

    Directives

    +

    Topics

    +

    Directives

    -

    Topics

    -
    -
    top
    -

    <AuthnProviderAlias> Directive

    -
    Description:Selects the algorithm used to calculate the challenge and @@ -258,48 +300,6 @@ of clients
    - - - - - -
    Description:Enclose a group of directives that represent an -extension of a base authentication provider and referenced by -the specified alias
    Syntax:<AuthnProviderAlias baseProvider Alias> -... </AuthnProviderAlias>
    Context:server config
    Status:Extension
    Module:mod_authn_alias
    -

    <AuthnProviderAlias> and - </AuthnProviderAlias> are used to enclose a group of - authentication directives that can be referenced by the alias name - using one of the directives - AuthBasicProvider or - AuthDigestProvider.

    - -
    This directive has no affect on authorization, even for modules that - provide both authentication and authorization.
    - -
    +
    top

    Examples

    @@ -149,6 +126,29 @@ the specified alias </Directory>

    +
    top
    +

    <AuthnProviderAlias> Directive

    + + + + + + +
    Description:Enclose a group of directives that represent an +extension of a base authentication provider and referenced by +the specified alias
    Syntax:<AuthnProviderAlias baseProvider Alias> +... </AuthnProviderAlias>
    Context:server config
    Status:Extension
    Module:mod_authn_alias
    +

    <AuthnProviderAlias> and + </AuthnProviderAlias> are used to enclose a group of + authentication directives that can be referenced by the alias name + using one of the directives + AuthBasicProvider or + AuthDigestProvider.

    + +
    This directive has no affect on authorization, even for modules that + provide both authentication and authorization.
    + +

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_authn_anon.html.en b/docs/manual/mod/mod_authn_anon.html.en index e529ac6f9d6..a534701f374 100644 --- a/docs/manual/mod/mod_authn_anon.html.en +++ b/docs/manual/mod/mod_authn_anon.html.en @@ -54,7 +54,10 @@ via the AuthBasicProvider directive with the anon value.

    -

    Directives

    +

    Topics

    +

    Directives

    -

    Topics

    -
    +
    +
    top
    +
    +

    Example

    +

    The example below is combined with "normal" htpasswd-file based + authentication and allows users in additionally as 'guests' with the + following properties:

    + + + +

    Example

    + <Directory /foo> + + AuthName "Use 'anonymous' & Email address for guest entry"
    + AuthType Basic
    + AuthBasicProvider file anon
    + AuthUserFile /path/to/your/.htpasswd
    +
    + Anonymous_NoUserID off
    + Anonymous_MustGiveEmail on
    + Anonymous_VerifyEmail on
    + Anonymous_LogEmail on
    + Anonymous anonymous guest www test welcome
    +
    + Order Deny,Allow
    + Allow from all
    +
    + Require valid-user
    +     + </Directory> +

    +
    top

    Anonymous Directive

    @@ -167,55 +216,6 @@ formatted email address addresses (see the above Anonymous_LogEmail).

    -
    top
    -
    -

    Example

    -

    The example below is combined with "normal" htpasswd-file based - authentication and allows users in additionally as 'guests' with the - following properties:

    - -
      -
    • It insists that the user enters a userID. - (Anonymous_NoUserID)
      • - -
    • It insists that the user enters a password. - (Anonymous_MustGiveEmail)
      • - -
    • The password entered must be a valid email address, i.e. - contain at least one '@' and a '.'. - (Anonymous_VerifyEmail)
      • - -
    • The userID must be one of anonymous guest www test - welcome and comparison is not case - sensitive. (Anonymous)
      • - -
    • And the Email addresses entered in the passwd field are - logged to the error log file. - (Anonymous_LogEmail)
      • -
    - -

    Example

    - <Directory /foo> - - AuthName "Use 'anonymous' & Email address for guest entry"
    - AuthType Basic
    - AuthBasicProvider file anon
    - AuthUserFile /path/to/your/.htpasswd
    -
    - Anonymous_NoUserID off
    - Anonymous_MustGiveEmail on
    - Anonymous_VerifyEmail on
    - Anonymous_LogEmail on
    - Anonymous anonymous guest www test welcome
    -
    - Order Deny,Allow
    - Allow from all
    -
    - Require valid-user
    -     - </Directory> -

    -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_authn_dbd.html.en b/docs/manual/mod/mod_authn_dbd.html.en index 0de713086c8..7d05aba1d69 100644 --- a/docs/manual/mod/mod_authn_dbd.html.en +++ b/docs/manual/mod/mod_authn_dbd.html.en @@ -48,16 +48,16 @@ AuthDigestProvider with the dbd value.

    -

    Directives

    +
    top
    +
    +

    Configuration Example

    + +

    This simple example shows use of this module in the context of +the Authentication and DBD frameworks. Please note that you need +to load an authorization module, such as mod_authz_user, +to get it working.

    +
    # mod_dbd configuration
+DBDriver pgsql
+DBDParams "dbname=apacheauth user=apache password=xxxxxx"
+
+DBDMin  4
+DBDKeep 8
+DBDMax  20
+DBDExptime 300
+
+<Directory /usr/www/myhost/private>
+  # core authentication and mod_auth_basic configuration
+  # for mod_authn_dbd
+  AuthType Basic
+  AuthName "My Server"
+  AuthBasicProvider dbd
+
+  # core authorization configuration
+  Require valid-user
+
+  # mod_authn_dbd SQL query to authenticate a user
+  AuthDBDUserPWQuery \
+    "SELECT password FROM authn WHERE user = %s"
+</Directory>
    +
    top
    +
    +

    Exposing Login Information

    + +

    +If httpd was built against APR version 1.3.0 +or higher, then whenever a query is made to the database server, all +column values in the first row returned by the query are placed in the +environment, using environment variables with the prefix "AUTHENTICATE_". +

    +

    If a database query for example returned the username, full name +and telephone number of a user, a CGI program will have access to +this information without the need to make a second independent database +query to gather this additional information.

    +

    This has the potential to dramatically simplify the coding and +configuration required in some web applications. +

    +
    +
    top

    AuthDBDUserPWQuery Directive

    @@ -133,55 +182,6 @@ mod_auth_digest) is being used. See Password Formats for more information.

    - -
    top
    -
    -

    Configuration Example

    - -

    This simple example shows use of this module in the context of -the Authentication and DBD frameworks. Please note that you need -to load an authorization module, such as mod_authz_user, -to get it working.

    -
    # mod_dbd configuration
-DBDriver pgsql
-DBDParams "dbname=apacheauth user=apache password=xxxxxx"
-
-DBDMin  4
-DBDKeep 8
-DBDMax  20
-DBDExptime 300
-
-<Directory /usr/www/myhost/private>
-  # core authentication and mod_auth_basic configuration
-  # for mod_authn_dbd
-  AuthType Basic
-  AuthName "My Server"
-  AuthBasicProvider dbd
-
-  # core authorization configuration
-  Require valid-user
-
-  # mod_authn_dbd SQL query to authenticate a user
-  AuthDBDUserPWQuery \
-    "SELECT password FROM authn WHERE user = %s"
-</Directory>
    -
    top
    -
    -

    Exposing Login Information

    - -

    -If httpd was built against APR version 1.3.0 -or higher, then whenever a query is made to the database server, all -column values in the first row returned by the query are placed in the -environment, using environment variables with the prefix "AUTHENTICATE_". -

    -

    If a database query for example returned the username, full name -and telephone number of a user, a CGI program will have access to -this information without the need to make a second independent database -query to gather this additional information.

    -

    This has the potential to dramatically simplify the coding and -configuration required in some web applications. -

    diff --git a/docs/manual/mod/mod_authn_dbm.html.en b/docs/manual/mod/mod_authn_dbm.html.en index a383055e2cc..b17d194e3fb 100644 --- a/docs/manual/mod/mod_authn_dbm.html.en +++ b/docs/manual/mod/mod_authn_dbm.html.en @@ -63,6 +63,7 @@ AuthDigestProvider
    +
    top

    AuthDBMType Directive

    Description:SQL query to look up a password for a user
    @@ -127,7 +128,6 @@ passwords for authentication format password files for use with this module.

    -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_authn_default.html.en b/docs/manual/mod/mod_authn_default.html.en index f16f7e7aa9d..b417b8449c3 100644 --- a/docs/manual/mod/mod_authn_default.html.en +++ b/docs/manual/mod/mod_authn_default.html.en @@ -45,6 +45,7 @@

  • AuthDefaultAuthoritative
    • +
    top

    AuthDefaultAuthoritative Directive

    @@ -71,7 +72,6 @@ modules -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_authn_file.html.en b/docs/manual/mod/mod_authn_file.html.en index 7c776cc7f00..1bc5aad4a94 100644 --- a/docs/manual/mod/mod_authn_file.html.en +++ b/docs/manual/mod/mod_authn_file.html.en @@ -62,6 +62,7 @@

  • htpasswd
  • htdigest
    • +
    top

    AuthUserFile Directive

    @@ -124,7 +125,6 @@ passwords for authentication -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_authnz_ldap.html.en b/docs/manual/mod/mod_authnz_ldap.html.en index 5ba7751001c..6e55596542a 100644 --- a/docs/manual/mod/mod_authnz_ldap.html.en +++ b/docs/manual/mod/mod_authnz_ldap.html.en @@ -60,7 +60,18 @@ for HTTP Basic authentication. via the AuthBasicProvider directive with the ldap value.

    -
    - - - - - - - - -
    Description:Determines if other authentication providers are used when a user can be mapped to a DN but the server cannot successfully bind with the user's credentials.
    Syntax:AuthLDAPBindAuthoritativeoff|on
    Default:AuthLDAPBindAuthoritative on
    Context:directory, .htaccess
    Override:AuthConfig
    Status:Extension
    Module:mod_authnz_ldap
    Compatibility:Available in versions later than 2.2.14
    -

    By default, subsequent authentication providers are only queried if a - user cannot be mapped to a DN, but not if the user can be mapped to a DN and their - password cannot be verified with an LDAP bind. - If AuthLDAPBindAuthoritative - is set to off, other configured authentication modules will have - a chance to validate the user if the LDAP bind (with the current user's credentials) - fails for any reason.

    -

    This allows users present in both LDAP and - AuthUserFile to authenticate - when the LDAP server is available but the user's account is locked or password - is otherwise unusable.

    +
    +

    Contents

    -

    See also

    - -
    -
    top
    -

    AuthLDAPBindDN Directive

    - - - - - - - -
    Description:Optional DN to use in binding to the LDAP server
    Syntax:AuthLDAPBindDN distinguished-name
    Context:directory, .htaccess
    Override:AuthConfig
    Status:Extension
    Module:mod_authnz_ldap
    -

    An optional DN used to bind to the server when searching for - entries. If not provided, mod_authnz_ldap will use - an anonymous bind.

    +
    -
    top
    -

    AuthLDAPBindPassword Directive

    - - - - - - - - -
    Description:Password used in conjuction with the bind DN
    Syntax:AuthLDAPBindPassword password
    Context:directory, .htaccess
    Override:AuthConfig
    Status:Extension
    Module:mod_authnz_ldap
    Compatibility:exec: was added in 2.2.25.
    -

    A bind password to use in conjunction with the bind DN. Note - that the bind password is probably sensitive data, and should be - properly protected. You should only use the AuthLDAPBindDN and AuthLDAPBindPassword if you - absolutely need them to search the directory.

    +
      +
    • The Authentication + Phase
      • -

      If the value begins with exec: the resulting command will be - executed and the first line returned to standard output by the - program will be used as the password.

      -
      #Password used as-is
-AuthLDAPBindPassword secret
+          
    • The Authorization
+          Phase
      • 
+
    + -#Run /path/to/program to get my password -AuthLDAPBindPassword exec:/path/to/program +
  • + The Require Directives -#Run /path/to/otherProgram and provide arguments -AuthLDAPBindPassword "exec:/path/to/otherProgram argument1"
    • + + +
  • Examples
    • +
  • Using TLS
    • +
  • Using SSL
    • +
  • Exposing Login Information
    • +
  • + Using Microsoft FrontPage with + mod_authnz_ldap -
    • -
    top
    -

    AuthLDAPCharsetConfig Directive

    - - - - - - -
    Description:Language to charset conversion configuration file
    Syntax:AuthLDAPCharsetConfig file-path
    Context:server config
    Status:Extension
    Module:mod_authnz_ldap
    -

    The AuthLDAPCharsetConfig directive sets the location - of the language to charset conversion configuration file. File-path is relative - to the ServerRoot. This file specifies - the list of language extensions to character sets. - Most administrators use the provided charset.conv - file, which associates common language extensions to character sets.

    + + + +
    top
    +
    +

    Operation

    -

    The file contains lines in the following format:

    +

    There are two phases in granting access to a user. The first + phase is authentication, in which the mod_authnz_ldap + authentication provider verifies that the user's credentials are valid. + This is also called the search/bind phase. The second phase is + authorization, in which mod_authnz_ldap determines + if the authenticated user is allowed access to the resource in + question. This is also known as the compare + phase.

    -

    - Language-Extension charset [Language-String] ... -

    +

    mod_authnz_ldap registers both an authn_ldap authentication + provider and an authz_ldap authorization handler. The authn_ldap + authentication provider can be enabled through the + AuthBasicProvider directive + using the ldap value. The authz_ldap handler extends the + Require directive's authorization types + by adding ldap-user, ldap-dn and ldap-group + values.

    -

    The case of the extension does not matter. Blank lines, and lines - beginning with a hash character (#) are ignored.

    +

    The Authentication + Phase

    -
    -
    top
    -

    AuthLDAPCompareDNOnServer Directive

    - - - - - - - - -
    Description:Use the LDAP server to compare the DNs
    Syntax:AuthLDAPCompareDNOnServer on|off
    Default:AuthLDAPCompareDNOnServer on
    Context:directory, .htaccess
    Override:AuthConfig
    Status:Extension
    Module:mod_authnz_ldap
    -

    When set, mod_authnz_ldap will use the LDAP - server to compare the DNs. This is the only foolproof way to - compare DNs. mod_authnz_ldap will search the - directory for the DN specified with the Require dn directive, then, - retrieve the DN and compare it with the DN retrieved from the user - entry. If this directive is not set, - mod_authnz_ldap simply does a string comparison. It - is possible to get false negatives with this approach, but it is - much faster. Note the mod_ldap cache can speed up - DN comparison in most situations.

    +

    During the authentication phase, mod_authnz_ldap + searches for an entry in the directory that matches the username + that the HTTP client passes. If a single unique match is found, + then mod_authnz_ldap attempts to bind to the + directory server using the DN of the entry plus the password + provided by the HTTP client. Because it does a search, then a + bind, it is often referred to as the search/bind phase. Here are + the steps taken during the search/bind phase.

    -
    -
    top
    -

    AuthLDAPDereferenceAliases Directive

    - - - - - - - - -
    Description:When will the module de-reference aliases
    Syntax:AuthLDAPDereferenceAliases never|searching|finding|always
    Default:AuthLDAPDereferenceAliases Always
    Context:directory, .htaccess
    Override:AuthConfig
    Status:Extension
    Module:mod_authnz_ldap
    -

    This directive specifies when mod_authnz_ldap will - de-reference aliases during LDAP operations. The default is - always.

    +
      +
    1. Generate a search filter by combining the attribute and + filter provided in the AuthLDAPURL directive with + the username passed by the HTTP client.
      2. -
    -
    top
    -

    AuthLDAPGroupAttribute Directive

    - - - - - - - - -
    Description:LDAP attributes used to check for group membership
    Syntax:AuthLDAPGroupAttribute attribute
    Default:AuthLDAPGroupAttribute member uniquemember
    Context:directory, .htaccess
    Override:AuthConfig
    Status:Extension
    Module:mod_authnz_ldap
    -

    This directive specifies which LDAP attributes are used to - check for group membership. Multiple attributes can be used by - specifying this directive multiple times. If not specified, - then mod_authnz_ldap uses the member and - uniquemember attributes.

    +
  • Search the directory using the generated filter. If the + search does not return exactly one entry, deny or decline + access.
    • -
    -
    top
    -

    AuthLDAPGroupAttributeIsDN Directive

    - - - - - - - - -
    Description:Use the DN of the client username when checking for -group membership
    Syntax:AuthLDAPGroupAttributeIsDN on|off
    Default:AuthLDAPGroupAttributeIsDN on
    Context:directory, .htaccess
    Override:AuthConfig
    Status:Extension
    Module:mod_authnz_ldap
    -

    When set on, this directive says to use the - distinguished name of the client username when checking for group - membership. Otherwise, the username will be used. For example, - assume that the client sent the username bjenson, - which corresponds to the LDAP DN cn=Babs Jenson, - o=Airius. If this directive is set, - mod_authnz_ldap will check if the group has - cn=Babs Jenson, o=Airius as a member. If this - directive is not set, then mod_authnz_ldap will - check if the group has bjenson as a member.

    - -
    -
    top
    -

    AuthLDAPRemoteUserAttribute Directive

    - - - - - - - - -
    Description:Use the value of the attribute returned during the user -query to set the REMOTE_USER environment variable
    Syntax:AuthLDAPRemoteUserAttribute uid
    Default:none
    Context:directory, .htaccess
    Override:AuthConfig
    Status:Extension
    Module:mod_authnz_ldap
    -

    If this directive is set, the value of the - REMOTE_USER environment variable will be set to the - value of the attribute specified. Make sure that this attribute is - included in the list of attributes in the AuthLDAPUrl definition, - otherwise this directive will have no effect. This directive, if - present, takes precedence over AuthLDAPRemoteUserIsDN. This - directive is useful should you want people to log into a website - using an email address, but a backend application expects the - username as a userid.

    - -
    -
    top
    -

    AuthLDAPRemoteUserIsDN Directive

    - - - - - - - - -
    Description:Use the DN of the client username to set the REMOTE_USER -environment variable
    Syntax:AuthLDAPRemoteUserIsDN on|off
    Default:AuthLDAPRemoteUserIsDN off
    Context:directory, .htaccess
    Override:AuthConfig
    Status:Extension
    Module:mod_authnz_ldap
    -

    If this directive is set to on, the value of the - REMOTE_USER environment variable will be set to the full - distinguished name of the authenticated user, rather than just - the username that was passed by the client. It is turned off by - default.

    - -
    -
    top
    -

    AuthLDAPUrl Directive

    - - - - - - - -
    Description:URL specifying the LDAP search parameters
    Syntax:AuthLDAPUrl url [NONE|SSL|TLS|STARTTLS]
    Context:directory, .htaccess
    Override:AuthConfig
    Status:Extension
    Module:mod_authnz_ldap
    -

    An RFC 2255 URL which specifies the LDAP search parameters - to use. The syntax of the URL is

    -

    ldap://host:port/basedn?attribute?scope?filter

    - -
    -
    ldap
    - -
    For regular ldap, use the - string ldap. For secure LDAP, use ldaps - instead. Secure LDAP is only available if Apache was linked - to an LDAP library with SSL support.
    - -
    host:port
    - -
    -

    The name/port of the ldap server (defaults to - localhost:389 for ldap, and - localhost:636 for ldaps). To - specify multiple, redundant LDAP servers, just list all - servers, separated by spaces. mod_authnz_ldap - will try connecting to each server in turn, until it makes a - successful connection.

    +
  • Fetch the distinguished name of the entry retrieved from + the search and attempt to bind to the LDAP server using the + DN and the password passed by the HTTP client. If the bind is + unsuccessful, deny or decline access.
    • + -

    Once a connection has been made to a server, that - connection remains active for the life of the - httpd process, or until the LDAP server goes - down.

    +

    The following directives are used during the search/bind + phase

    -

    If the LDAP server goes down and breaks an existing - connection, mod_authnz_ldap will attempt to - re-connect, starting with the primary server, and trying - each redundant server in turn. Note that this is different - than a true round-robin search.

    -
    + + + + -
    basedn
    + + -
    The DN of the branch of the - directory where all searches should start from. At the very - least, this must be the top of your directory tree, but - could also specify a subtree in the directory.
    + + -
    attribute
    + + -
    The attribute to search for. - Although RFC 2255 allows a comma-separated list of - attributes, only the first attribute will be used, no - matter how many are provided. If no attributes are - provided, the default is to use uid. It's a good - idea to choose an attribute that will be unique across all - entries in the subtree you will be using.
    + + -
    scope
    + + +
    AuthLDAPURLSpecifies the LDAP server, the + base DN, the attribute to use in the search, as well as the + extra search filter to use.
    AuthLDAPBindDNAn optional DN to bind with + during the search phase.
    AuthLDAPBindPasswordAn optional password to bind + with during the search phase.
    -
    The scope of the search. Can be either one or - sub. Note that a scope of base is - also supported by RFC 2255, but is not supported by this - module. If the scope is not provided, or if base scope - is specified, the default is to use a scope of - sub.
    -
    filter
    +

    The Authorization Phase

    -
    A valid LDAP search filter. If - not provided, defaults to (objectClass=*), which - will search for all objects in the tree. Filters are - limited to approximately 8000 characters (the definition of - MAX_STRING_LEN in the Apache source code). This - should be more than sufficient for any application.
    -
    +

    During the authorization phase, mod_authnz_ldap + attempts to determine if the user is authorized to access the + resource. Many of these checks require + mod_authnz_ldap to do a compare operation on the + LDAP server. This is why this phase is often referred to as the + compare phase. mod_authnz_ldap accepts the + following Require + directives to determine if the credentials are acceptable:

    -

    When doing searches, the attribute, filter and username passed - by the HTTP client are combined to create a search filter that - looks like - (&(filter)(attribute=username)).

    + -
    -
    top
    -

    AuthzLDAPAuthoritative Directive

    - - - - - - - - -
    Description:Prevent other authentication modules from -authenticating the user if this one fails
    Syntax:AuthzLDAPAuthoritative on|off
    Default:AuthzLDAPAuthoritative on
    Context:directory, .htaccess
    Override:AuthConfig
    Status:Extension
    Module:mod_authnz_ldap
    -

    Set to off if this module should let other - authorization modules attempt to authorize the user, should - authorization with this module fail. Control is only passed on - to lower modules if there is no DN or rule that matches the - supplied user name (as passed by the client).

    -

    When no LDAP-specific Require directives +

    Other Require values may also + be used which may require loading additional authorization modules. + Note that if you use a Require + value from another authorization module, you will need to ensure that + AuthzLDAPAuthoritative + is set to off to allow the authorization phase to fall + back to the module providing the alternate + Require value. When no + LDAP-specific Require directives are used, authorization is allowed to fall back to other modules as if AuthzLDAPAuthoritative was set to off.

    -
    -
    top
    -
    -

    Contents

    - -
    top
    -
    -

    Operation

    - -

    There are two phases in granting access to a user. The first - phase is authentication, in which the mod_authnz_ldap - authentication provider verifies that the user's credentials are valid. - This is also called the search/bind phase. The second phase is - authorization, in which mod_authnz_ldap determines - if the authenticated user is allowed access to the resource in - question. This is also known as the compare - phase.

    - -

    mod_authnz_ldap registers both an authn_ldap authentication - provider and an authz_ldap authorization handler. The authn_ldap - authentication provider can be enabled through the - AuthBasicProvider directive - using the ldap value. The authz_ldap handler extends the - Require directive's authorization types - by adding ldap-user, ldap-dn and ldap-group - values.

    - -

    The Authentication - Phase

    - -

    During the authentication phase, mod_authnz_ldap - searches for an entry in the directory that matches the username - that the HTTP client passes. If a single unique match is found, - then mod_authnz_ldap attempts to bind to the - directory server using the DN of the entry plus the password - provided by the HTTP client. Because it does a search, then a - bind, it is often referred to as the search/bind phase. Here are - the steps taken during the search/bind phase.

    - -
      -
    1. Generate a search filter by combining the attribute and - filter provided in the AuthLDAPURL directive with - the username passed by the HTTP client.
      2. - -
    2. Search the directory using the generated filter. If the - search does not return exactly one entry, deny or decline - access.
      3. - -
    3. Fetch the distinguished name of the entry retrieved from - the search and attempt to bind to the LDAP server using the - DN and the password passed by the HTTP client. If the bind is - unsuccessful, deny or decline access.
      4. -
    - -

    The following directives are used during the search/bind - phase

    - - - - - - - - - - - - - - - - - - - - -
    AuthLDAPURLSpecifies the LDAP server, the - base DN, the attribute to use in the search, as well as the - extra search filter to use.
    AuthLDAPBindDNAn optional DN to bind with - during the search phase.
    AuthLDAPBindPasswordAn optional password to bind - with during the search phase.
    - - -

    The Authorization Phase

    - -

    During the authorization phase, mod_authnz_ldap - attempts to determine if the user is authorized to access the - resource. Many of these checks require - mod_authnz_ldap to do a compare operation on the - LDAP server. This is why this phase is often referred to as the - compare phase. mod_authnz_ldap accepts the - following Require - directives to determine if the credentials are acceptable:

    - - - -

    Other Require values may also - be used which may require loading additional authorization modules. - Note that if you use a Require - value from another authorization module, you will need to ensure that - AuthzLDAPAuthoritative - is set to off to allow the authorization phase to fall - back to the module providing the alternate - Require value. When no - LDAP-specific Require directives - are used, authorization is allowed to fall back to other modules - as if AuthzLDAPAuthoritative - was set to off.

    - - +
  • Grant access if there is a Require group directive, and + mod_authz_groupfile has been loaded with the + AuthGroupFile + directive set.
    • + +
  • others...
    • +

    mod_authnz_ldap uses the following directives during the @@ -1024,6 +658,372 @@ Require group mygroupfile and won't be able to find the FrontPage-managed user file. +

    +
    top
    +

    AuthLDAPBindAuthoritative Directive

    + + + + + + + + + +
    Description:Determines if other authentication providers are used when a user can be mapped to a DN but the server cannot successfully bind with the user's credentials.
    Syntax:AuthLDAPBindAuthoritativeoff|on
    Default:AuthLDAPBindAuthoritative on
    Context:directory, .htaccess
    Override:AuthConfig
    Status:Extension
    Module:mod_authnz_ldap
    Compatibility:Available in versions later than 2.2.14
    +

    By default, subsequent authentication providers are only queried if a + user cannot be mapped to a DN, but not if the user can be mapped to a DN and their + password cannot be verified with an LDAP bind. + If AuthLDAPBindAuthoritative + is set to off, other configured authentication modules will have + a chance to validate the user if the LDAP bind (with the current user's credentials) + fails for any reason.

    +

    This allows users present in both LDAP and + AuthUserFile to authenticate + when the LDAP server is available but the user's account is locked or password + is otherwise unusable.

    + +

    See also

    + +
    +
    top
    +

    AuthLDAPBindDN Directive

    + + + + + + + +
    Description:Optional DN to use in binding to the LDAP server
    Syntax:AuthLDAPBindDN distinguished-name
    Context:directory, .htaccess
    Override:AuthConfig
    Status:Extension
    Module:mod_authnz_ldap
    +

    An optional DN used to bind to the server when searching for + entries. If not provided, mod_authnz_ldap will use + an anonymous bind.

    + +
    +
    top
    +

    AuthLDAPBindPassword Directive

    + + + + + + + + +
    Description:Password used in conjuction with the bind DN
    Syntax:AuthLDAPBindPassword password
    Context:directory, .htaccess
    Override:AuthConfig
    Status:Extension
    Module:mod_authnz_ldap
    Compatibility:exec: was added in 2.2.25.
    +

    A bind password to use in conjunction with the bind DN. Note + that the bind password is probably sensitive data, and should be + properly protected. You should only use the AuthLDAPBindDN and AuthLDAPBindPassword if you + absolutely need them to search the directory.

    + +

    If the value begins with exec: the resulting command will be + executed and the first line returned to standard output by the + program will be used as the password.

    +
    #Password used as-is
+AuthLDAPBindPassword secret
+
+#Run /path/to/program to get my password
+AuthLDAPBindPassword exec:/path/to/program
+
+#Run /path/to/otherProgram and provide arguments
+AuthLDAPBindPassword "exec:/path/to/otherProgram argument1"
    + + +
    +
    top
    +

    AuthLDAPCharsetConfig Directive

    + + + + + + +
    Description:Language to charset conversion configuration file
    Syntax:AuthLDAPCharsetConfig file-path
    Context:server config
    Status:Extension
    Module:mod_authnz_ldap
    +

    The AuthLDAPCharsetConfig directive sets the location + of the language to charset conversion configuration file. File-path is relative + to the ServerRoot. This file specifies + the list of language extensions to character sets. + Most administrators use the provided charset.conv + file, which associates common language extensions to character sets.

    + +

    The file contains lines in the following format:

    + +

    + Language-Extension charset [Language-String] ... +

    + +

    The case of the extension does not matter. Blank lines, and lines + beginning with a hash character (#) are ignored.

    + +
    +
    top
    +

    AuthLDAPCompareDNOnServer Directive

    + + + + + + + + +
    Description:Use the LDAP server to compare the DNs
    Syntax:AuthLDAPCompareDNOnServer on|off
    Default:AuthLDAPCompareDNOnServer on
    Context:directory, .htaccess
    Override:AuthConfig
    Status:Extension
    Module:mod_authnz_ldap
    +

    When set, mod_authnz_ldap will use the LDAP + server to compare the DNs. This is the only foolproof way to + compare DNs. mod_authnz_ldap will search the + directory for the DN specified with the Require dn directive, then, + retrieve the DN and compare it with the DN retrieved from the user + entry. If this directive is not set, + mod_authnz_ldap simply does a string comparison. It + is possible to get false negatives with this approach, but it is + much faster. Note the mod_ldap cache can speed up + DN comparison in most situations.

    + +
    +
    top
    +

    AuthLDAPDereferenceAliases Directive

    + + + + + + + + +
    Description:When will the module de-reference aliases
    Syntax:AuthLDAPDereferenceAliases never|searching|finding|always
    Default:AuthLDAPDereferenceAliases Always
    Context:directory, .htaccess
    Override:AuthConfig
    Status:Extension
    Module:mod_authnz_ldap
    +

    This directive specifies when mod_authnz_ldap will + de-reference aliases during LDAP operations. The default is + always.

    + +
    +
    top
    +

    AuthLDAPGroupAttribute Directive

    + + + + + + + + +
    Description:LDAP attributes used to check for group membership
    Syntax:AuthLDAPGroupAttribute attribute
    Default:AuthLDAPGroupAttribute member uniquemember
    Context:directory, .htaccess
    Override:AuthConfig
    Status:Extension
    Module:mod_authnz_ldap
    +

    This directive specifies which LDAP attributes are used to + check for group membership. Multiple attributes can be used by + specifying this directive multiple times. If not specified, + then mod_authnz_ldap uses the member and + uniquemember attributes.

    + +
    +
    top
    +

    AuthLDAPGroupAttributeIsDN Directive

    + + + + + + + + +
    Description:Use the DN of the client username when checking for +group membership
    Syntax:AuthLDAPGroupAttributeIsDN on|off
    Default:AuthLDAPGroupAttributeIsDN on
    Context:directory, .htaccess
    Override:AuthConfig
    Status:Extension
    Module:mod_authnz_ldap
    +

    When set on, this directive says to use the + distinguished name of the client username when checking for group + membership. Otherwise, the username will be used. For example, + assume that the client sent the username bjenson, + which corresponds to the LDAP DN cn=Babs Jenson, + o=Airius. If this directive is set, + mod_authnz_ldap will check if the group has + cn=Babs Jenson, o=Airius as a member. If this + directive is not set, then mod_authnz_ldap will + check if the group has bjenson as a member.

    + +
    +
    top
    +

    AuthLDAPRemoteUserAttribute Directive

    + + + + + + + + +
    Description:Use the value of the attribute returned during the user +query to set the REMOTE_USER environment variable
    Syntax:AuthLDAPRemoteUserAttribute uid
    Default:none
    Context:directory, .htaccess
    Override:AuthConfig
    Status:Extension
    Module:mod_authnz_ldap
    +

    If this directive is set, the value of the + REMOTE_USER environment variable will be set to the + value of the attribute specified. Make sure that this attribute is + included in the list of attributes in the AuthLDAPUrl definition, + otherwise this directive will have no effect. This directive, if + present, takes precedence over AuthLDAPRemoteUserIsDN. This + directive is useful should you want people to log into a website + using an email address, but a backend application expects the + username as a userid.

    + +
    +
    top
    +

    AuthLDAPRemoteUserIsDN Directive

    + + + + + + + + +
    Description:Use the DN of the client username to set the REMOTE_USER +environment variable
    Syntax:AuthLDAPRemoteUserIsDN on|off
    Default:AuthLDAPRemoteUserIsDN off
    Context:directory, .htaccess
    Override:AuthConfig
    Status:Extension
    Module:mod_authnz_ldap
    +

    If this directive is set to on, the value of the + REMOTE_USER environment variable will be set to the full + distinguished name of the authenticated user, rather than just + the username that was passed by the client. It is turned off by + default.

    + +
    +
    top
    +

    AuthLDAPUrl Directive

    + + + + + + + +
    Description:URL specifying the LDAP search parameters
    Syntax:AuthLDAPUrl url [NONE|SSL|TLS|STARTTLS]
    Context:directory, .htaccess
    Override:AuthConfig
    Status:Extension
    Module:mod_authnz_ldap
    +

    An RFC 2255 URL which specifies the LDAP search parameters + to use. The syntax of the URL is

    +

    ldap://host:port/basedn?attribute?scope?filter

    + +
    +
    ldap
    + +
    For regular ldap, use the + string ldap. For secure LDAP, use ldaps + instead. Secure LDAP is only available if Apache was linked + to an LDAP library with SSL support.
    + +
    host:port
    + +
    +

    The name/port of the ldap server (defaults to + localhost:389 for ldap, and + localhost:636 for ldaps). To + specify multiple, redundant LDAP servers, just list all + servers, separated by spaces. mod_authnz_ldap + will try connecting to each server in turn, until it makes a + successful connection.

    + +

    Once a connection has been made to a server, that + connection remains active for the life of the + httpd process, or until the LDAP server goes + down.

    + +

    If the LDAP server goes down and breaks an existing + connection, mod_authnz_ldap will attempt to + re-connect, starting with the primary server, and trying + each redundant server in turn. Note that this is different + than a true round-robin search.

    +
    + +
    basedn
    + +
    The DN of the branch of the + directory where all searches should start from. At the very + least, this must be the top of your directory tree, but + could also specify a subtree in the directory.
    + +
    attribute
    + +
    The attribute to search for. + Although RFC 2255 allows a comma-separated list of + attributes, only the first attribute will be used, no + matter how many are provided. If no attributes are + provided, the default is to use uid. It's a good + idea to choose an attribute that will be unique across all + entries in the subtree you will be using.
    + +
    scope
    + +
    The scope of the search. Can be either one or + sub. Note that a scope of base is + also supported by RFC 2255, but is not supported by this + module. If the scope is not provided, or if base scope + is specified, the default is to use a scope of + sub.
    + +
    filter
    + +
    A valid LDAP search filter. If + not provided, defaults to (objectClass=*), which + will search for all objects in the tree. Filters are + limited to approximately 8000 characters (the definition of + MAX_STRING_LEN in the Apache source code). This + should be more than sufficient for any application.
    +
    + +

    When doing searches, the attribute, filter and username passed + by the HTTP client are combined to create a search filter that + looks like + (&(filter)(attribute=username)).

    + +

    For example, consider an URL of + ldap://ldap.airius.com/o=Airius?cn?sub?(posixid=*). When + a client attempts to connect using a username of Babs + Jenson, the resulting search filter will be + (&(posixid=*)(cn=Babs Jenson)).

    + +

    An optional parameter can be added to allow the LDAP Url to override + the connection type. This parameter can be one of the following:

    + +
    +
    NONE
    +
    Establish an unsecure connection on the default LDAP port. This + is the same as ldap:// on port 389.
    +
    SSL
    +
    Establish a secure connection on the default secure LDAP port. + This is the same as ldaps://
    +
    TLS | STARTTLS
    +
    Establish an upgraded secure connection on the default LDAP port. + This connection will be initiated on port 389 by default and then + upgraded to a secure connection on the same port.
    +
    + +

    See above for examples of AuthLDAPURL URLs.

    + +

    When AuthLDAPURL + is enabled in a particular context, but some other module has performed + authentication for the request, the server will try to map the username to a DN + during authorization regardless of whether or not LDAP-specific requirements + are present. To ignore the failures to map a username to a DN during + authorization, set + AuthzLDAPAuthoritative to "off".

    + +
    +
    top
    +

    AuthzLDAPAuthoritative Directive

    + + + + + + + + +
    Description:Prevent other authentication modules from +authenticating the user if this one fails
    Syntax:AuthzLDAPAuthoritative on|off
    Default:AuthzLDAPAuthoritative on
    Context:directory, .htaccess
    Override:AuthConfig
    Status:Extension
    Module:mod_authnz_ldap
    +

    Set to off if this module should let other + authorization modules attempt to authorize the user, should + authorization with this module fail. Control is only passed on + to lower modules if there is no DN or rule that matches the + supplied user name (as passed by the client).

    +

    When no LDAP-specific Require directives + are used, authorization is allowed to fall back to other modules + as if AuthzLDAPAuthoritative + was set to off.

    +
    diff --git a/docs/manual/mod/mod_authz_dbm.html.en b/docs/manual/mod/mod_authz_dbm.html.en index 27d209c3084..eb9c7cd5840 100644 --- a/docs/manual/mod/mod_authz_dbm.html.en +++ b/docs/manual/mod/mod_authz_dbm.html.en @@ -50,6 +50,7 @@
  • Require
  • Satisfy
    • +
    top

    AuthDBMGroupFile Directive

    @@ -177,7 +178,6 @@ store list of user groups files is configured to use the same type of database.

    -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_authz_default.html.en b/docs/manual/mod/mod_authz_default.html.en index da6b763beab..82a2f8b739c 100644 --- a/docs/manual/mod/mod_authz_default.html.en +++ b/docs/manual/mod/mod_authz_default.html.en @@ -45,6 +45,7 @@

  • AuthzDefaultAuthoritative
    • +
    top

    AuthzDefaultAuthoritative Directive

    @@ -71,7 +72,6 @@ modules -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_authz_groupfile.html.en b/docs/manual/mod/mod_authz_groupfile.html.en index c270a3bae28..a494979bbe1 100644 --- a/docs/manual/mod/mod_authz_groupfile.html.en +++ b/docs/manual/mod/mod_authz_groupfile.html.en @@ -50,6 +50,7 @@

  • Require
  • Satisfy
    • +
    top

    AuthGroupFile Directive

    @@ -116,7 +117,6 @@ modules -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_authz_host.html.en b/docs/manual/mod/mod_authz_host.html.en index b2dbb206940..5f8109a9a0a 100644 --- a/docs/manual/mod/mod_authz_host.html.en +++ b/docs/manual/mod/mod_authz_host.html.en @@ -74,6 +74,7 @@ address)

  • Satisfy
  • Require
    • +
    top

    Allow Directive

    @@ -366,7 +367,6 @@ evaluated. work.

    -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_authz_owner.html.en b/docs/manual/mod/mod_authz_owner.html.en index 4cf444ae9f5..85467f9a6ef 100644 --- a/docs/manual/mod/mod_authz_owner.html.en +++ b/docs/manual/mod/mod_authz_owner.html.en @@ -71,54 +71,19 @@ "MultiViews" resources.

    -
    - - - - - - - -
    Description:Sets whether authorization will be passed on to lower level -modules
    Syntax:AuthzOwnerAuthoritative On|Off
    Default:AuthzOwnerAuthoritative On
    Context:directory, .htaccess
    Override:AuthConfig
    Status:Extension
    Module:mod_authz_owner
    -

    Setting the AuthzOwnerAuthoritative - directive explicitly to Off allows for - user authorization to be passed on to lower level modules (as defined - in the modules.c files) if:

    - - - -

    Note that setting the value to Off also allows the - combination of file-owner and file-group, so - access will be allowed if either one or the other (or both) match.

    - -

    By default, control is not passed on and an authorization failure - will result in an "Authentication Required" reply. Not - setting it to Off thus keeps the system secure and forces - an NCSA compliant behaviour.

    - -
    -
    top

    Configuration Examples

    @@ -176,6 +141,41 @@ modules </Directory>

    + +
    top
    +

    AuthzOwnerAuthoritative Directive

    + + + + + + + + +
    Description:Sets whether authorization will be passed on to lower level +modules
    Syntax:AuthzOwnerAuthoritative On|Off
    Default:AuthzOwnerAuthoritative On
    Context:directory, .htaccess
    Override:AuthConfig
    Status:Extension
    Module:mod_authz_owner
    +

    Setting the AuthzOwnerAuthoritative + directive explicitly to Off allows for + user authorization to be passed on to lower level modules (as defined + in the modules.c files) if:

    + + + +

    Note that setting the value to Off also allows the + combination of file-owner and file-group, so + access will be allowed if either one or the other (or both) match.

    + +

    By default, control is not passed on and an authorization failure + will result in an "Authentication Required" reply. Not + setting it to Off thus keeps the system secure and forces + an NCSA compliant behaviour.

    +
    diff --git a/docs/manual/mod/mod_authz_user.html.en b/docs/manual/mod/mod_authz_user.html.en index 86bab10e393..d14f11294b3 100644 --- a/docs/manual/mod/mod_authz_user.html.en +++ b/docs/manual/mod/mod_authz_user.html.en @@ -51,6 +51,7 @@
  • Require
  • Satisfy
    • +
    top

    AuthzUserAuthoritative Directive

    @@ -75,7 +76,6 @@ modules an NCSA compliant behaviour.

    -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_autoindex.html.en b/docs/manual/mod/mod_autoindex.html.en index 37df35592d1..44ea46967da 100644 --- a/docs/manual/mod/mod_autoindex.html.en +++ b/docs/manual/mod/mod_autoindex.html.en @@ -79,7 +79,10 @@ before a 1011-byte file (if in ascending order) even though they both are shown as "1K".

    - +
    top
    +
    +

    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.

    + +
      +
    • C=N sorts the directory by file name
      • + +
    • C=M sorts the directory by last-modified + date, then file name
      • + +
    • C=S sorts the directory by size, then file + name
      • + +
    • C=D sorts the directory by description, then + file name
      • + +
    • O=A sorts the listing in Ascending + Order
      • + +
    • O=D sorts the listing in Descending + Order
      • + +
    • F=0 formats the listing as a simple list + (not FancyIndexed)
      • + +
    • F=1 formats the listing as a FancyIndexed + list
      • + +
    • F=2 formats the listing as an + HTMLTable FancyIndexed list
      • + +
    • V=0 disables version sorting
      • + +
    • V=1 enables version sorting
      • + +
    • P=pattern lists only files matching + the given pattern
      • +
    + +

    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 action="" method="get">
    + + Show me a <select name="F">
    + + <option value="0"> Plain list</option>
    + <option value="1" selected="selected"> Fancy list</option>
    + <option value="2"> Table list</option>
    +     + </select>
    + Sorted by <select name="C">
    + + <option value="N" selected="selected"> Name</option>
    + <option value="M"> Date Modified</option>
    + <option value="S"> Size</option>
    + <option value="D"> Description</option>
    +     + </select>
    + <select name="O">
    + + <option value="A" selected="selected"> Ascending</option>
    + <option value="D"> Descending</option>
    +     + </select>
    + <select name="V">
    + + <option value="0" selected="selected"> in Normal order</option>
    + <option value="1"> in Version order</option>
    +     + </select>
    + Matching <input type="text" name="P" value="*" />
    + <input type="submit" name="X" value="Go" />
    +     + </form> +

    + +
    top

    AddAlt Directive

    @@ -858,108 +960,6 @@ of the index listing

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

    - -
    top
    -
    -

    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.

    - -
      -
    • C=N sorts the directory by file name
      • - -
    • C=M sorts the directory by last-modified - date, then file name
      • - -
    • C=S sorts the directory by size, then file - name
      • - -
    • C=D sorts the directory by description, then - file name
      • - -
    • O=A sorts the listing in Ascending - Order
      • - -
    • O=D sorts the listing in Descending - Order
      • - -
    • F=0 formats the listing as a simple list - (not FancyIndexed)
      • - -
    • F=1 formats the listing as a FancyIndexed - list
      • - -
    • F=2 formats the listing as an - HTMLTable FancyIndexed list
      • - -
    • V=0 disables version sorting
      • - -
    • V=1 enables version sorting
      • - -
    • P=pattern lists only files matching - the given pattern
      • -
    - -

    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 action="" method="get">
    - - Show me a <select name="F">
    - - <option value="0"> Plain list</option>
    - <option value="1" selected="selected"> Fancy list</option>
    - <option value="2"> Table list</option>
    -     - </select>
    - Sorted by <select name="C">
    - - <option value="N" selected="selected"> Name</option>
    - <option value="M"> Date Modified</option>
    - <option value="S"> Size</option>
    - <option value="D"> Description</option>
    -     - </select>
    - <select name="O">
    - - <option value="A" selected="selected"> Ascending</option>
    - <option value="D"> Descending</option>
    -     - </select>
    - <select name="V">
    - - <option value="0" selected="selected"> in Normal order</option>
    - <option value="1"> in Version order</option>
    -     - </select>
    - Matching <input type="text" name="P" value="*" />
    - <input type="submit" name="X" value="Go" />
    -     - </form> -

    -
    diff --git a/docs/manual/mod/mod_cache.html.en b/docs/manual/mod/mod_cache.html.en index 84fb3ad0766..77fe3b7f571 100644 --- a/docs/manual/mod/mod_cache.html.en +++ b/docs/manual/mod/mod_cache.html.en @@ -64,7 +64,12 @@

    Further details, discussion, and examples, are provided in the Caching Guide.

    -
    Related ModulesRelated Directives
    +
    top
    +
    +

    Sample Configuration

    +

    Sample httpd.conf

    + #
    + # Sample Cache Configuration
    + #
    + LoadModule cache_module modules/mod_cache.so
    +
    + <IfModule mod_cache.c>
    + + #LoadModule disk_cache_module modules/mod_disk_cache.so
    + # If you want to use mod_disk_cache instead of mod_mem_cache,
    + # uncomment the line above and comment out the LoadModule line below.
    + <IfModule mod_disk_cache.c>
    + + CacheRoot c:/cacheroot
    + CacheEnable disk /
    + CacheDirLevels 5
    + CacheDirLength 3
    +     + </IfModule>
    +
    + LoadModule mem_cache_module modules/mod_mem_cache.so
    + <IfModule mod_mem_cache.c>
    + + CacheEnable mem /
    + MCacheSize 4096
    + MCacheMaxObjectCount 100
    + MCacheMinObjectSize 1
    + MCacheMaxObjectSize 2048
    +     + </IfModule>
    +
    + # When acting as a proxy, don't cache the list of security updates
    + CacheDisable http://security.update.server/update-list/
    +     + </IfModule> +

    +
    top
    +
    +

    Avoiding the Thundering Herd

    +

    When a cached entry becomes stale, mod_cache will submit + a conditional request to the backend, which is expected to confirm whether the + cached entry is still fresh, and send an updated entity if not.

    +

    A small but finite amount of time exists between the time the cached entity + becomes stale, and the time the stale entity is fully refreshed. On a busy + server, a significant number of requests might arrive during this time, and + cause a thundering herd of requests to strike the backend + suddenly and unpredictably.

    +

    To keep the thundering herd at bay, the CacheLock + directive can be used to define a directory in which locks are created for + URLs in flight. The lock is used as a hint + by other requests to either suppress an attempt to cache (someone else has + gone to fetch the entity), or to indicate that a stale entry is being refreshed + (stale content will be returned in the mean time). +

    +

    Initial caching of an entry

    + +

    When an entity is cached for the first time, a lock will be created for the + entity until the response has been fully cached. During the lifetime of the + lock, the cache will suppress the second and subsequent attempt to cache the + same entity. While this doesn't hold back the thundering herd, it does stop + the cache attempting to cache the same entity multiple times simultaneously. +

    + +

    Refreshment of a stale entry

    + +

    When an entity reaches its freshness lifetime and becomes stale, a lock + will be created for the entity until the response has either been confirmed as + still fresh, or replaced by the backend. During the lifetime of the lock, the + second and subsequent incoming request will cause stale data to be returned, + and the thundering herd is kept at bay.

    + +

    Locks and Cache-Control: no-cache

    + +

    Locks are used as a hint only to enable the cache to be + more gentle on backend servers, however the lock can be overridden if necessary. + If the client sends a request with a Cache-Control header forcing a reload, any + lock that may be present will be ignored, and the client's request will be + honoured immediately and the cached entry refreshed.

    +

    As a further safety mechanism, locks have a configurable maximum age. + Once this age has been reached, the lock is removed, and a new request is + given the opportunity to create a new lock. This maximum age can be set using + the CacheLockMaxAge directive, and defaults to 5 + seconds. +

    + +

    Example configuration

    + +

    Enabling the cache lock

    + #
    + # Enable the cache lock
    + #
    + <IfModule mod_cache.c>
    + + CacheLock on
    + CacheLockPath /tmp/mod_cache-lock
    + CacheLockMaxAge 5
    +     + </IfModule> +

    + +
    +
    top

    CacheDefaultExpire Directive

    @@ -558,114 +666,6 @@ LastModified date.
  • CacheIgnoreCacheControl
  • CacheStoreNoStore
    • - -
    top
    -
    -

    Related Modules and Directives

    -
    Description:The default duration to cache a document when no expiry date is specified.
    Related ModulesRelated Directives
    -
    top
    -
    -

    Sample Configuration

    -

    Sample httpd.conf

    - #
    - # Sample Cache Configuration
    - #
    - LoadModule cache_module modules/mod_cache.so
    -
    - <IfModule mod_cache.c>
    - - #LoadModule disk_cache_module modules/mod_disk_cache.so
    - # If you want to use mod_disk_cache instead of mod_mem_cache,
    - # uncomment the line above and comment out the LoadModule line below.
    - <IfModule mod_disk_cache.c>
    - - CacheRoot c:/cacheroot
    - CacheEnable disk /
    - CacheDirLevels 5
    - CacheDirLength 3
    -     - </IfModule>
    -
    - LoadModule mem_cache_module modules/mod_mem_cache.so
    - <IfModule mod_mem_cache.c>
    - - CacheEnable mem /
    - MCacheSize 4096
    - MCacheMaxObjectCount 100
    - MCacheMinObjectSize 1
    - MCacheMaxObjectSize 2048
    -     - </IfModule>
    -
    - # When acting as a proxy, don't cache the list of security updates
    - CacheDisable http://security.update.server/update-list/
    -     - </IfModule> -

    -
    top
    -
    -

    Avoiding the Thundering Herd

    -

    When a cached entry becomes stale, mod_cache will submit - a conditional request to the backend, which is expected to confirm whether the - cached entry is still fresh, and send an updated entity if not.

    -

    A small but finite amount of time exists between the time the cached entity - becomes stale, and the time the stale entity is fully refreshed. On a busy - server, a significant number of requests might arrive during this time, and - cause a thundering herd of requests to strike the backend - suddenly and unpredictably.

    -

    To keep the thundering herd at bay, the CacheLock - directive can be used to define a directory in which locks are created for - URLs in flight. The lock is used as a hint - by other requests to either suppress an attempt to cache (someone else has - gone to fetch the entity), or to indicate that a stale entry is being refreshed - (stale content will be returned in the mean time). -

    -

    Initial caching of an entry

    - -

    When an entity is cached for the first time, a lock will be created for the - entity until the response has been fully cached. During the lifetime of the - lock, the cache will suppress the second and subsequent attempt to cache the - same entity. While this doesn't hold back the thundering herd, it does stop - the cache attempting to cache the same entity multiple times simultaneously. -

    - -

    Refreshment of a stale entry

    - -

    When an entity reaches its freshness lifetime and becomes stale, a lock - will be created for the entity until the response has either been confirmed as - still fresh, or replaced by the backend. During the lifetime of the lock, the - second and subsequent incoming request will cause stale data to be returned, - and the thundering herd is kept at bay.

    - -

    Locks and Cache-Control: no-cache

    - -

    Locks are used as a hint only to enable the cache to be - more gentle on backend servers, however the lock can be overridden if necessary. - If the client sends a request with a Cache-Control header forcing a reload, any - lock that may be present will be ignored, and the client's request will be - honoured immediately and the cached entry refreshed.

    -

    As a further safety mechanism, locks have a configurable maximum age. - Once this age has been reached, the lock is removed, and a new request is - given the opportunity to create a new lock. This maximum age can be set using - the CacheLockMaxAge directive, and defaults to 5 - seconds. -

    - -

    Example configuration

    - -

    Enabling the cache lock

    - #
    - # Enable the cache lock
    - #
    - <IfModule mod_cache.c>
    - - CacheLock on
    - CacheLockPath /tmp/mod_cache-lock
    - CacheLockMaxAge 5
    -     - </IfModule> -

    -
    diff --git a/docs/manual/mod/mod_cern_meta.html.en b/docs/manual/mod/mod_cern_meta.html.en index 0962951f254..9dbe27ff7ed 100644 --- a/docs/manual/mod/mod_cern_meta.html.en +++ b/docs/manual/mod/mod_cern_meta.html.en @@ -55,6 +55,7 @@
  • mod_headers
  • mod_asis
    • +
    top

    MetaDir Directive

    @@ -120,7 +121,6 @@ meta information

    -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_cgi.html.en b/docs/manual/mod/mod_cgi.html.en index af73652ddd5..9b0eb4689cb 100644 --- a/docs/manual/mod/mod_cgi.html.en +++ b/docs/manual/mod/mod_cgi.html.en @@ -58,17 +58,17 @@ for any file with the mime-type application/x-httpd-cgi. The use of the magic mime-type is deprecated.

    -
    - - - - - -
    Description:Location of the CGI script error logfile
    Syntax:ScriptLog file-path
    Context:server config, virtual host
    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 ServerRoot. -

    - -

    Example

    - ScriptLog logs/cgi_log -

    - -

    This log will be opened as the user the child processes run - as, i.e. 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.

    - -
    -
    top
    -

    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, virtual host
    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.

    - -
    -
    top
    -

    ScriptLogLength Directive

    - - - - - - - -
    Description:Size limit of the CGI script logfile
    Syntax:ScriptLogLength bytes
    Default:ScriptLogLength 10385760
    Context:server config, virtual host
    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.

    - -
    -
    top

    CGI Environment variables

    The server will set the CGI environment variables as described @@ -235,6 +162,79 @@ in the scriptlog

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

    +
    +
    top
    +

    ScriptLog Directive

    + + + + + + +
    Description:Location of the CGI script error logfile
    Syntax:ScriptLog file-path
    Context:server config, virtual host
    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 ServerRoot. +

    + +

    Example

    + ScriptLog logs/cgi_log +

    + +

    This log will be opened as the user the child processes run + as, i.e. 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.

    + +
    +
    top
    +

    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, virtual host
    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.

    + +
    +
    top
    +

    ScriptLogLength Directive

    + + + + + + + +
    Description:Size limit of the CGI script logfile
    Syntax:ScriptLogLength bytes
    Default:ScriptLogLength 10385760
    Context:server config, virtual host
    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.

    +
    diff --git a/docs/manual/mod/mod_cgid.html.en b/docs/manual/mod/mod_cgid.html.en index dc3db903f48..fa8a9e97aed 100644 --- a/docs/manual/mod/mod_cgid.html.en +++ b/docs/manual/mod/mod_cgid.html.en @@ -73,6 +73,7 @@
  • Running CGI programs under different user IDs
    • +
    top

    CGIDScriptTimeout Directive

    @@ -121,7 +122,6 @@ the cgi daemon -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_charset_lite.html.en b/docs/manual/mod/mod_charset_lite.html.en index 57f448360bb..ed8f9ab2761 100644 --- a/docs/manual/mod/mod_charset_lite.html.en +++ b/docs/manual/mod/mod_charset_lite.html.en @@ -48,16 +48,53 @@ mechanisms implemented by Russian Apache and its associated mod_charset.

    - +
    top
    +
    +

    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:

    + +
      +
    • The translation mechanism may return a bad return code, + and the connection will be aborted.
      • + +
    • The translation mechanism may silently place special + characters (e.g., question marks) in the output buffer when + it cannot translate the input buffer.
      • +
    + +
    top

    CharsetDefault Directive

    @@ -165,43 +202,6 @@

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

    - -
    top
    -
    -

    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:

    - -
      -
    • The translation mechanism may return a bad return code, - and the connection will be aborted.
      • - -
    • The translation mechanism may silently place special - characters (e.g., question marks) in the output buffer when - it cannot translate the input buffer.
      • -
    -
    diff --git a/docs/manual/mod/mod_dav.html.en b/docs/manual/mod/mod_dav.html.en index 67851839717..fb061e9c837 100644 --- a/docs/manual/mod/mod_dav.html.en +++ b/docs/manual/mod/mod_dav.html.en @@ -41,104 +41,24 @@ copying, and deleting resources and collections on a remote web server.

    -
    - - - - - - -
    Description:Enable WebDAV HTTP methods
    Syntax:Dav On|Off|provider-name
    Default:Dav Off
    Context:directory
    Status:Extension
    Module:mod_dav
    -

    Use the Dav directive to enable the - WebDAV HTTP methods for the given container:

    - -

    - <Location /foo>
    - - Dav On
    -     - </Location> -

    - -

    The value On is actually an alias for the default - provider filesystem which is served by the mod_dav_fs module. Note, that once you have DAV enabled - for some location, it cannot be disabled for sublocations. - For a complete configuration example have a look at the section above.

    - -
    - Do not enable WebDAV until you have secured your server. Otherwise - everyone will be able to distribute files on your system. -
    - -
    -
    top
    -

    DavDepthInfinity Directive

    - - - - - - - -
    Description:Allow PROPFIND, Depth: Infinity requests
    Syntax:DavDepthInfinity on|off
    Default:DavDepthInfinity off
    Context:server config, virtual host, 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.

    - -
    -
    top
    -

    DavMinTimeout Directive

    - - - - - - - -
    Description:Minimum amount of time the server holds a lock on -a DAV resource
    Syntax:DavMinTimeout seconds
    Default:DavMinTimeout 0
    Context:server config, virtual host, 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> -

    - -
    -
    top

    Enabling WebDAV

    To enable mod_dav, add the following to a @@ -262,6 +182,86 @@ Alias /php-source /home/gstein/php_files
    http://example.com/php-source can be used with a DAV client to manipulate them.

    +
    top
    +

    Dav Directive

    + + + + + + + +
    Description:Enable WebDAV HTTP methods
    Syntax:Dav On|Off|provider-name
    Default:Dav Off
    Context:directory
    Status:Extension
    Module:mod_dav
    +

    Use the Dav directive to enable the + WebDAV HTTP methods for the given container:

    + +

    + <Location /foo>
    + + Dav On
    +     + </Location> +

    + +

    The value On is actually an alias for the default + provider filesystem which is served by the mod_dav_fs module. Note, that once you have DAV enabled + for some location, it cannot be disabled for sublocations. + For a complete configuration example have a look at the section above.

    + +
    + Do not enable WebDAV until you have secured your server. Otherwise + everyone will be able to distribute files on your system. +
    + +
    +
    top
    +

    DavDepthInfinity Directive

    + + + + + + + +
    Description:Allow PROPFIND, Depth: Infinity requests
    Syntax:DavDepthInfinity on|off
    Default:DavDepthInfinity off
    Context:server config, virtual host, 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.

    + +
    +
    top
    +

    DavMinTimeout Directive

    + + + + + + + +
    Description:Minimum amount of time the server holds a lock on +a DAV resource
    Syntax:DavMinTimeout seconds
    Default:DavMinTimeout 0
    Context:server config, virtual host, 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> +

    + +

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_dav_fs.html.en b/docs/manual/mod/mod_dav_fs.html.en index e65ed364233..192070e9dbf 100644 --- a/docs/manual/mod/mod_dav_fs.html.en +++ b/docs/manual/mod/mod_dav_fs.html.en @@ -56,6 +56,7 @@

    +
    top

    DavLockDB Directive

    @@ -88,7 +89,6 @@ -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_dav_lock.html.en b/docs/manual/mod/mod_dav_lock.html.en index b8850bbb42f..340eafd9703 100644 --- a/docs/manual/mod/mod_dav_lock.html.en +++ b/docs/manual/mod/mod_dav_lock.html.en @@ -63,6 +63,7 @@

    +
    top

    DavGenericLockDB Directive

    @@ -93,7 +94,6 @@ -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_dbd.html.en b/docs/manual/mod/mod_dbd.html.en index d22b4c63eea..44cefc6bc39 100644 --- a/docs/manual/mod/mod_dbd.html.en +++ b/docs/manual/mod/mod_dbd.html.en @@ -43,7 +43,13 @@ by its original developer.

    -

    Directives

    +
    top
    +
    +

    Connection Pooling

    +

    This module manages database connections, in a manner + optimised for the platform. On non-threaded platforms, + it provides a persistent connection in the manner of + classic LAMP (Linux, Apache, Mysql, Perl/PHP/Python). + On threaded platform, it provides an altogether more + scalable and efficient connection pool, as + described in this + article at ApacheTutor. Note that mod_dbd + supersedes the modules presented in that article.

    +
    top
    +
    +

    Apache DBD API

    +

    mod_dbd exports five functions for other modules + to use. The API is as follows:

    + + 
    typedef struct {
+    apr_dbd_t *handle;
+    apr_dbd_driver_t *driver;
+    apr_hash_t *prepared;
+} ap_dbd_t;
+
+/* Export functions to access the database */
+
+/* acquire a connection that MUST be explicitly closed.
+ * Returns NULL on error
+ */
+AP_DECLARE(ap_dbd_t*) ap_dbd_open(apr_pool_t*, server_rec*);
+
+/* release a connection acquired with ap_dbd_open */
+AP_DECLARE(void) ap_dbd_close(server_rec*, ap_dbd_t*);
+
+/* acquire a connection that will have the lifetime of a request
+ * and MUST NOT be explicitly closed.  Return NULL on error.
+ * This is the preferred function for most applications.
+ */
+AP_DECLARE(ap_dbd_t*) ap_dbd_acquire(request_rec*);
+
+/* acquire a connection that will have the lifetime of a connection
+ * and MUST NOT be explicitly closed.  Return NULL on error.
+ */
+AP_DECLARE(ap_dbd_t*) ap_dbd_cacquire(conn_rec*);
+
+/* Prepare a statement for use by a client module */
+AP_DECLARE(void) ap_dbd_prepare(server_rec*, const char*, const char*);
+
+/* Also export them as optional functions for modules that prefer it */
+APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_open, (apr_pool_t*, server_rec*));
+APR_DECLARE_OPTIONAL_FN(void, ap_dbd_close, (server_rec*, ap_dbd_t*));
+APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_acquire, (request_rec*));
+APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_cacquire, (conn_rec*));
+APR_DECLARE_OPTIONAL_FN(void, ap_dbd_prepare, (server_rec*, const char*, const char*));
+
    +
    top
    +
    +

    SQL Prepared Statements

    +

    mod_dbd supports SQL prepared statements on behalf + of modules that may wish to use them. Each prepared statement + must be assigned a name (label), and they are stored in a hash: + the prepared field of an ap_dbd_t. + Hash entries are of type apr_dbd_prepared_t + and can be used in any of the apr_dbd prepared statement + SQL query or select commands.

    + +

    It is up to dbd user modules to use the prepared statements + and document what statements can be specified in httpd.conf, + or to provide their own directives and use ap_dbd_prepare.

    +

    Caveat

    + When using prepared statements with a MySQL database, it is preferred to set + reconnect to 0 in the connection string as to avoid errors that + arise from the MySQL client reconnecting without properly resetting the + prepared statements. If set to 1, any broken connections will be attempted + fixed, but as mod_dbd is not informed, the prepared statements will be invalidated. +
    +
    top
    +
    +

    SECURITY WARNING

    + +

    Any web/database application needs to secure itself against SQL + injection attacks. In most cases, Apache DBD is safe, because + applications use prepared statements, and untrusted inputs are + only ever used as data. Of course, if you use it via third-party + modules, you should ascertain what precautions they may require.

    +

    However, the FreeTDS driver is inherently + unsafe. The underlying library doesn't support + prepared statements, so the driver emulates them, and the + untrusted input is merged into the SQL statement.

    +

    It can be made safe by untainting all inputs: + a process inspired by Perl's taint checking. Each input + is matched against a regexp, and only the match is used, + according to the Perl idiom:

    + 
      $untrusted =~ /([a-z]+)/;
+  $trusted = $1;
    +

    To use this, the untainting regexps must be included in the + prepared statements configured. The regexp follows immediately + after the % in the prepared statement, and is enclosed in + curly brackets {}. For example, if your application expects + alphanumeric input, you can use:

    +

    + "SELECT foo FROM bar WHERE input = %s" +

    +

    with other drivers, and suffer nothing worse than a failed query. + But with FreeTDS you'd need:

    +

    + "SELECT foo FROM bar WHERE input = %{([A-Za-z0-9]+)}s" +

    +

    Now anything that doesn't match the regexp's $1 match is + discarded, so the statement is safe.

    +

    An alternative to this may be the third-party ODBC driver, + which offers the security of genuine prepared statements.

    +
    +
    top

    DBDExptime Directive

    @@ -207,119 +320,6 @@ driver in apr_dbd_mysql.so.

    -
    top
    -
    -

    Connection Pooling

    -

    This module manages database connections, in a manner - optimised for the platform. On non-threaded platforms, - it provides a persistent connection in the manner of - classic LAMP (Linux, Apache, Mysql, Perl/PHP/Python). - On threaded platform, it provides an altogether more - scalable and efficient connection pool, as - described in this - article at ApacheTutor. Note that mod_dbd - supersedes the modules presented in that article.

    -
    top
    -
    -

    Apache DBD API

    -

    mod_dbd exports five functions for other modules - to use. The API is as follows:

    - - 
    typedef struct {
-    apr_dbd_t *handle;
-    apr_dbd_driver_t *driver;
-    apr_hash_t *prepared;
-} ap_dbd_t;
-
-/* Export functions to access the database */
-
-/* acquire a connection that MUST be explicitly closed.
- * Returns NULL on error
- */
-AP_DECLARE(ap_dbd_t*) ap_dbd_open(apr_pool_t*, server_rec*);
-
-/* release a connection acquired with ap_dbd_open */
-AP_DECLARE(void) ap_dbd_close(server_rec*, ap_dbd_t*);
-
-/* acquire a connection that will have the lifetime of a request
- * and MUST NOT be explicitly closed.  Return NULL on error.
- * This is the preferred function for most applications.
- */
-AP_DECLARE(ap_dbd_t*) ap_dbd_acquire(request_rec*);
-
-/* acquire a connection that will have the lifetime of a connection
- * and MUST NOT be explicitly closed.  Return NULL on error.
- */
-AP_DECLARE(ap_dbd_t*) ap_dbd_cacquire(conn_rec*);
-
-/* Prepare a statement for use by a client module */
-AP_DECLARE(void) ap_dbd_prepare(server_rec*, const char*, const char*);
-
-/* Also export them as optional functions for modules that prefer it */
-APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_open, (apr_pool_t*, server_rec*));
-APR_DECLARE_OPTIONAL_FN(void, ap_dbd_close, (server_rec*, ap_dbd_t*));
-APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_acquire, (request_rec*));
-APR_DECLARE_OPTIONAL_FN(ap_dbd_t*, ap_dbd_cacquire, (conn_rec*));
-APR_DECLARE_OPTIONAL_FN(void, ap_dbd_prepare, (server_rec*, const char*, const char*));
-
    -
    top
    -
    -

    SQL Prepared Statements

    -

    mod_dbd supports SQL prepared statements on behalf - of modules that may wish to use them. Each prepared statement - must be assigned a name (label), and they are stored in a hash: - the prepared field of an ap_dbd_t. - Hash entries are of type apr_dbd_prepared_t - and can be used in any of the apr_dbd prepared statement - SQL query or select commands.

    - -

    It is up to dbd user modules to use the prepared statements - and document what statements can be specified in httpd.conf, - or to provide their own directives and use ap_dbd_prepare.

    -

    Caveat

    - When using prepared statements with a MySQL database, it is preferred to set - reconnect to 0 in the connection string as to avoid errors that - arise from the MySQL client reconnecting without properly resetting the - prepared statements. If set to 1, any broken connections will be attempted - fixed, but as mod_dbd is not informed, the prepared statements will be invalidated. -
    -
    top
    -
    -

    SECURITY WARNING

    - -

    Any web/database application needs to secure itself against SQL - injection attacks. In most cases, Apache DBD is safe, because - applications use prepared statements, and untrusted inputs are - only ever used as data. Of course, if you use it via third-party - modules, you should ascertain what precautions they may require.

    -

    However, the FreeTDS driver is inherently - unsafe. The underlying library doesn't support - prepared statements, so the driver emulates them, and the - untrusted input is merged into the SQL statement.

    -

    It can be made safe by untainting all inputs: - a process inspired by Perl's taint checking. Each input - is matched against a regexp, and only the match is used, - according to the Perl idiom:

    - 
      $untrusted =~ /([a-z]+)/;
-  $trusted = $1;
    -

    To use this, the untainting regexps must be included in the - prepared statements configured. The regexp follows immediately - after the % in the prepared statement, and is enclosed in - curly brackets {}. For example, if your application expects - alphanumeric input, you can use:

    -

    - "SELECT foo FROM bar WHERE input = %s" -

    -

    with other drivers, and suffer nothing worse than a failed query. - But with FreeTDS you'd need:

    -

    - "SELECT foo FROM bar WHERE input = %{([A-Za-z0-9]+)}s" -

    -

    Now anything that doesn't match the regexp's $1 match is - discarded, so the statement is safe.

    -

    An alternative to this may be the third-party ODBC driver, - which offers the security of genuine prepared statements.

    -

    Available Languages:  en 

    diff --git a/docs/manual/mod/mod_deflate.html.en b/docs/manual/mod/mod_deflate.html.en index d6076612786..462b628e528 100644 --- a/docs/manual/mod/mod_deflate.html.en +++ b/docs/manual/mod/mod_deflate.html.en @@ -40,7 +40,12 @@ client your server to be compressed before being sent to the client over the network.

    -

    Directives

    +
    top
    +
    +

    Sample Configurations

    +

    Compression and TLS

    +

    Some web applications are vulnerable to an information disclosure + attack when a TLS connection carries deflate compressed data. For more + information, review the details of the "BREACH" family of attacks.

    +
    +

    This is a simple configuration that compresses common text-based content types.

    + +

    Compress only a few types

    AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css text/javascript application/javascript
    +
    + +
    top
    +
    +

    Enabling Compression

    + +

    Output Compression

    +

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

    + +

    + SetOutputFilter DEFLATE +

    + +

    Some popular browsers cannot handle compression of all content + so you may want to set the gzip-only-text/html note to + 1 to only allow html files to be compressed (see + below). If you set this to anything but 1 it + will be ignored.

    + +

    If you want to restrict the compression to particular MIME types + in general, you may use the AddOutputFilterByType directive. Here is an example of + enabling compression only for the html files of the Apache + documentation:

    + +

    + <Directory "/your-server-root/manual">
    + + AddOutputFilterByType DEFLATE text/html
    +     + </Directory> +

    + +

    For browsers that have problems even with compression of all file + types, use the BrowserMatch directive to set the no-gzip + note for that particular browser so that no compression will be + performed. You may combine no-gzip with gzip-only-text/html to get the best results. In that case + the former overrides the latter. Take a look at the following + excerpt from the configuration example + defined in the section above:

    + +

    + BrowserMatch ^Mozilla/4 gzip-only-text/html
    + BrowserMatch ^Mozilla/4\.0[678] no-gzip
    + BrowserMatch \bMSIE !no-gzip !gzip-only-text/html +

    + +

    At first we probe for a User-Agent string that + indicates a Netscape Navigator version of 4.x. These versions + cannot handle compression of types other than + text/html. The versions 4.06, 4.07 and 4.08 also + have problems with decompressing html files. Thus, we completely + turn off the deflate filter for them.

    + +

    The third BrowserMatch + directive fixes the guessed identity of the user agent, because + the Microsoft Internet Explorer identifies itself also as "Mozilla/4" + but is actually able to handle requested compression. Therefore we + match against the additional string "MSIE" (\b means + "word boundary") in the User-Agent Header and turn off + the restrictions defined before.

    + +

    Note

    + The DEFLATE filter is always inserted after RESOURCE + filters like PHP or SSI. It never touches internal subrequests. +
    +

    Note

    + There is an environment variable force-gzip, + set via SetEnv, which + will ignore the accept-encoding setting of your browser and will + send compressed output. +
    + + +

    Output Decompression

    +

    The mod_deflate module also provides a filter for + inflating/uncompressing a gzip compressed response body. In order to activate + this feature you have to insert the INFLATE filter into + the output filter chain using SetOutputFilter or AddOutputFilter, for example:

    + +

    + <Location /dav-area>
    + + ProxyPass http://example.com/
    + SetOutputFilter INFLATE
    +     + </Location> +

    + +

    This Example will uncompress gzip'ed output from example.com, so other + filters can do further processing with it. +

    + + +

    Input Decompression

    +

    The mod_deflate module also provides a filter for + decompressing a gzip compressed request body . In order to activate + this feature you have to insert the DEFLATE filter into + the input filter chain using SetInputFilter or AddInputFilter, for example:

    + +

    + <Location /dav-area>
    + + SetInputFilter DEFLATE
    +     + </Location> +

    + +

    Now if a request contains a Content-Encoding: + gzip header, the body will be automatically decompressed. + Few browsers have the ability to gzip request bodies. However, + some special applications actually do support request + compression, for instance some WebDAV clients.

    + +

    Note on Content-Length

    +

    If you evaluate the request body yourself, don't trust + the Content-Length header! + The Content-Length header reflects the length of the + incoming data from the client and not the byte count of + the decompressed data stream.

    +
    + +
    top
    +
    +

    Dealing with proxy servers

    + +

    The mod_deflate module sends a Vary: + Accept-Encoding HTTP response header to alert proxies that + a cached response should be sent only to clients that send the + appropriate Accept-Encoding request header. This + prevents compressed content from being sent to a client that will + not understand it.

    + +

    If you use some special exclusions dependent + on, for example, the User-Agent header, you must + manually configure an addition to the Vary header + to alert proxies of the additional restrictions. For example, + in a typical configuration where the addition of the DEFLATE + filter depends on the User-Agent, you should add:

    + +

    + Header append Vary User-Agent +

    + +

    If your decision about compression depends on other information + than request headers (e.g. HTTP version), you have to set the + Vary header to the value *. This prevents + compliant proxies from caching entirely.

    + +

    Example

    + Header set Vary * +

    +
    +
    top

    DeflateBufferSize Directive

    Description:Keepalive time for idle connections
    @@ -233,172 +399,6 @@ client higher the window size, the higher can the compression ratio be expected.

    -
    top
    -
    -

    Sample Configurations

    -

    Compression and TLS

    -

    Some web applications are vulnerable to an information disclosure - attack when a TLS connection carries deflate compressed data. For more - information, review the details of the "BREACH" family of attacks.

    -
    -

    This is a simple configuration that compresses common text-based content types.

    - -

    Compress only a few types

    AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css text/javascript application/javascript
    -
    - -
    top
    -
    -

    Enabling Compression

    - -

    Output Compression

    -

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

    - -

    - SetOutputFilter DEFLATE -

    - -

    Some popular browsers cannot handle compression of all content - so you may want to set the gzip-only-text/html note to - 1 to only allow html files to be compressed (see - below). If you set this to anything but 1 it - will be ignored.

    - -

    If you want to restrict the compression to particular MIME types - in general, you may use the AddOutputFilterByType directive. Here is an example of - enabling compression only for the html files of the Apache - documentation:

    - -

    - <Directory "/your-server-root/manual">
    - - AddOutputFilterByType DEFLATE text/html
    -     - </Directory> -

    - -

    For browsers that have problems even with compression of all file - types, use the BrowserMatch directive to set the no-gzip - note for that particular browser so that no compression will be - performed. You may combine no-gzip with gzip-only-text/html to get the best results. In that case - the former overrides the latter. Take a look at the following - excerpt from the configuration example - defined in the section above:

    - -

    - BrowserMatch ^Mozilla/4 gzip-only-text/html
    - BrowserMatch ^Mozilla/4\.0[678] no-gzip
    - BrowserMatch \bMSIE !no-gzip !gzip-only-text/html -

    - -

    At first we probe for a User-Agent string that - indicates a Netscape Navigator version of 4.x. These versions - cannot handle compression of types other than - text/html. The versions 4.06, 4.07 and 4.08 also - have problems with decompressing html files. Thus, we completely - turn off the deflate filter for them.

    - -

    The third BrowserMatch - directive fixes the guessed identity of the user agent, because - the Microsoft Internet Explorer identifies itself also as "Mozilla/4" - but is actually able to handle requested compression. Therefore we - match against the additional string "MSIE" (\b means - "word boundary") in the User-Agent Header and turn off - the restrictions defined before.

    - -

    Note

    - The DEFLATE filter is always inserted after RESOURCE - filters like PHP or SSI. It never touches internal subrequests. -
    -

    Note

    - There is an environment variable force-gzip, - set via SetEnv, which - will ignore the accept-encoding setting of your browser and will - send compressed output. -
    - - -

    Output Decompression

    -

    The mod_deflate module also provides a filter for - inflating/uncompressing a gzip compressed response body. In order to activate - this feature you have to insert the INFLATE filter into - the output filter chain using SetOutputFilter or AddOutputFilter, for example:

    - -

    - <Location /dav-area>
    - - ProxyPass http://example.com/
    - SetOutputFilter INFLATE
    -     - </Location> -

    - -

    This Example will uncompress gzip'ed output from example.com, so other - filters can do further processing with it. -

    - - -

    Input Decompression

    -

    The mod_deflate module also provides a filter for - decompressing a gzip compressed request body . In order to activate - this feature you have to insert the DEFLATE filter into - the input filter chain using SetInputFilter or AddInputFilter, for example:

    - -

    - <Location /dav-area>
    - - SetInputFilter DEFLATE
    -     - </Location> -

    - -

    Now if a request contains a Content-Encoding: - gzip header, the body will be automatically decompressed. - Few browsers have the ability to gzip request bodies. However, - some special applications actually do support request - compression, for instance some WebDAV clients.

    - -

    Note on Content-Length

    -

    If you evaluate the request body yourself, don't trust - the Content-Length header! - The Content-Length header reflects the length of the - incoming data from the client and not the byte count of - the decompressed data stream.

    -
    - -
    top
    -
    -

    Dealing with proxy servers

    - -

    The mod_deflate module sends a Vary: - Accept-Encoding HTTP response header to alert proxies that - a cached response should be sent only to clients that send the - appropriate Accept-Encoding request header. This - prevents compressed content from being sent to a client that will - not understand it.

    - -

    If you use some special exclusions dependent - on, for example, the User-Agent header, you must - manually configure an addition to the Vary header - to alert proxies of the additional restrictions. For example, - in a typical configuration where the addition of the DEFLATE - filter depends on the User-Agent, you should add:

    - -

    - Header append Vary User-Agent -

    - -

    If your decision about compression depends on other information - than request headers (e.g. HTTP version), you have to set the - Vary header to the value *. This prevents - compliant proxies from caching entirely.

    - -

    Example

    - Header set Vary * -

    -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_dir.html.en b/docs/manual/mod/mod_dir.html.en index d3971e52a57..8f733e5f9ad 100644 --- a/docs/manual/mod/mod_dir.html.en +++ b/docs/manual/mod/mod_dir.html.en @@ -65,6 +65,7 @@

  • FallbackResource
    • +
    top

    DirectoryIndex Directive

    Description:Fragment size to be compressed at one time by zlib
    @@ -235,7 +236,6 @@ is supported since 2.2.24

    -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_disk_cache.html.en b/docs/manual/mod/mod_disk_cache.html.en index b4a09542510..d983c93deee 100644 --- a/docs/manual/mod/mod_disk_cache.html.en +++ b/docs/manual/mod/mod_disk_cache.html.en @@ -68,6 +68,7 @@

  • CacheRoot
    • +
    top

    CacheDirLength Directive

    @@ -179,7 +180,6 @@ stored

    -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_dumpio.html.en b/docs/manual/mod/mod_dumpio.html.en index fa2e23181ad..01f576db6b7 100644 --- a/docs/manual/mod/mod_dumpio.html.en +++ b/docs/manual/mod/mod_dumpio.html.en @@ -43,16 +43,25 @@ be expected, this can produce extreme volumes of data, and should only be used when debugging problems.

    - +
    top
    +
    +

    Enabling dumpio Support

    + + +

    To enable the module, it should be compiled and + loaded in to your running Apache configuration. Logging + can then be enabled or disabled via the below directives.

    +
    top

    DumpIOInput Directive

    @@ -113,15 +122,6 @@ later.

    -
    top
    -
    -

    Enabling dumpio Support

    - - -

    To enable the module, it should be compiled and - loaded in to your running Apache configuration. Logging - can then be enabled or disabled via the below directives.

    -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_echo.html.en b/docs/manual/mod/mod_echo.html.en index d1552d4f8b7..033929bf1b3 100644 --- a/docs/manual/mod/mod_echo.html.en +++ b/docs/manual/mod/mod_echo.html.en @@ -45,6 +45,7 @@ modules

  • ProtocolEcho
    • +
    top

    ProtocolEcho Directive

    @@ -65,7 +66,6 @@ later.

    -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_env.html.en b/docs/manual/mod/mod_env.html.en index 61621a1ab30..c792ab18788 100644 --- a/docs/manual/mod/mod_env.html.en +++ b/docs/manual/mod/mod_env.html.en @@ -54,6 +54,7 @@ SSI pages

  • Environment Variables
  • SetEnvIf
    • +
    top

    PassEnv Directive

    @@ -132,7 +133,6 @@ SSI pages

    -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_example.html.en b/docs/manual/mod/mod_example.html.en index f39de1a0db0..0bfe501c220 100644 --- a/docs/manual/mod/mod_example.html.en +++ b/docs/manual/mod/mod_example.html.en @@ -49,35 +49,15 @@ display of some of the tracing the example module did as the various callbacks were made.

    -
    - - - - - -
    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".

    - -
    +

    Directives

    + +
    top

    Compiling the example module

    @@ -149,6 +129,26 @@ API to browse to this location and see the brief display mentioned earlier.

    +
    top
    +

    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".

    + +

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_expires.html.en b/docs/manual/mod/mod_expires.html.en index 003481acfc3..5a56e9d9583 100644 --- a/docs/manual/mod/mod_expires.html.en +++ b/docs/manual/mod/mod_expires.html.en @@ -59,16 +59,80 @@ criteria proxied from an origin server, this module does not change or add an Expires or Cache-Control header.

    -

    Directives

    + +
    +
    top
    +
    +

    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] + [num type] ..."
    + ExpiresByType type/encoding "base [plus num type] + [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.

    +
    top

    ExpiresActive Directive

    @@ -179,70 +243,6 @@ by MIME type description as well.

    -
    top
    -
    -

    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] - [num type] ..."
    - ExpiresByType type/encoding "base [plus num type] - [num type] ..." -

    - -

    where base is one of:

    - -
      -
    • access
      • - -
    • now (equivalent to - 'access')
      • - -
    • modification
      • -
    - -

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

    - -
      -
    • years
      • -
    • months
      • -
    • weeks
      • -
    • days
      • -
    • hours
      • -
    • minutes
      • -
    • seconds
      • -
    - -

    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.

    -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_ext_filter.html.en b/docs/manual/mod/mod_ext_filter.html.en index e7602cbe19d..9e871f839b2 100644 --- a/docs/manual/mod/mod_ext_filter.html.en +++ b/docs/manual/mod/mod_ext_filter.html.en @@ -60,168 +60,19 @@ delivery to the client a prototype environment for filters.

    -

    Directives

    +

    Topics

    +

    Directives

    -

    Topics

    -

    See also

    +

    See also

    top
    -

    ExtFilterDefine Directive

    -
    - - - - - -
    Description:Define an external filter
    Syntax:ExtFilterDefine filtername parameters
    Context:server config
    Status:Extension
    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 (e.g., cmd="/bin/mypgm - arg1 arg2".) Normal shell quoting is - not necessary since the program is run directly, bypassing the shell. - Program arguments are blank-delimited. A backslash can be used to - escape blanks which should be part of a program argument. Any - backslashes which are part of the argument must be escaped with - backslash themselves. In addition to the standard CGI environment - variables, DOCUMENT_URI, DOCUMENT_PATH_INFO, and - QUERY_STRING_UNESCAPED will also be set for the program.
    - -
    mode=mode
    - -
    Use mode=output (the default) for filters which - process the response. Use mode=input for filters - which process the request. mode=input is available - in Apache 2.1 and later.
    - -
    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.
    - -
    ftype=filtertype
    - -
    This parameter specifies the numeric value for filter type - that the filter should be registered as. The default value, - AP_FTYPE_RESOURCE, is sufficient in most cases. If the filter - needs to operate at a different point in the filter chain than - resource filters, then this parameter will be necessary. See - the AP_FTYPE_foo definitions in util_filter.h for appropriate - values.
    - -
    disableenv=env
    - -
    This parameter specifies the name of an environment variable - which, if set, will disable the filter.
    - -
    enableenv=env
    - -
    This parameter specifies the name of an environment variable - which must be set, or the filter will be disabled.
    -
    - -
    -
    top
    -

    ExtFilterOptions Directive

    - - - - - - - -
    Description:Configure mod_ext_filter options
    Syntax:ExtFilterOptions option [option] ...
    Default:ExtFilterOptions DebugLevel=0 NoLogStderr
    Context:directory
    Status:Extension
    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.
    - -
    Onfail=[abort|remove] (new in httpd version 2.2.12).
    -
    Determines how to proceed if the external filter program - cannot be started. With abort (the default value) - the request will be aborted. With remove, the - filter is removed and the request continues without it.
    -
    - -

    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.

    - -
    -
    top

    Examples

    @@ -378,6 +229,155 @@ delivery to the client close(SAVE);

    + +
    top
    +

    ExtFilterDefine Directive

    + + + + + + +
    Description:Define an external filter
    Syntax:ExtFilterDefine filtername parameters
    Context:server config
    Status:Extension
    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 (e.g., cmd="/bin/mypgm + arg1 arg2".) Normal shell quoting is + not necessary since the program is run directly, bypassing the shell. + Program arguments are blank-delimited. A backslash can be used to + escape blanks which should be part of a program argument. Any + backslashes which are part of the argument must be escaped with + backslash themselves. In addition to the standard CGI environment + variables, DOCUMENT_URI, DOCUMENT_PATH_INFO, and + QUERY_STRING_UNESCAPED will also be set for the program.
    + +
    mode=mode
    + +
    Use mode=output (the default) for filters which + process the response. Use mode=input for filters + which process the request. mode=input is available + in Apache 2.1 and later.
    + +
    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.
    + +
    ftype=filtertype
    + +
    This parameter specifies the numeric value for filter type + that the filter should be registered as. The default value, + AP_FTYPE_RESOURCE, is sufficient in most cases. If the filter + needs to operate at a different point in the filter chain than + resource filters, then this parameter will be necessary. See + the AP_FTYPE_foo definitions in util_filter.h for appropriate + values.
    + +
    disableenv=env
    + +
    This parameter specifies the name of an environment variable + which, if set, will disable the filter.
    + +
    enableenv=env
    + +
    This parameter specifies the name of an environment variable + which must be set, or the filter will be disabled.
    +
    + +
    +
    top
    +

    ExtFilterOptions Directive

    + + + + + + + +
    Description:Configure mod_ext_filter options
    Syntax:ExtFilterOptions option [option] ...
    Default:ExtFilterOptions DebugLevel=0 NoLogStderr
    Context:directory
    Status:Extension
    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.
    + +
    Onfail=[abort|remove] (new in httpd version 2.2.12).
    +
    Determines how to proceed if the external filter program + cannot be started. With abort (the default value) + the request will be aborted. With remove, the + filter is removed and the request continues without it.
    +
    + +

    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.

    +
    diff --git a/docs/manual/mod/mod_file_cache.html.en b/docs/manual/mod/mod_file_cache.html.en index 3bbc170731f..8891abb4aa9 100644 --- a/docs/manual/mod/mod_file_cache.html.en +++ b/docs/manual/mod/mod_file_cache.html.en @@ -59,75 +59,15 @@

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

    -

    Directives

    + -
    top
    -

    CacheFile Directive

    - - - - - - -
    Description:Cache a list of file handles at startup time
    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 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 -

    - -
    -
    top
    -

    MMapFile Directive

    - - - - - - -
    Description:Map a list of files into memory at startup time
    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 -

    - -
    +
    top

    Using mod_file_cache

    @@ -203,6 +143,66 @@

    +
    top
    +

    CacheFile Directive

    + + + + + + +
    Description:Cache a list of file handles at startup time
    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 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 +

    + +
    +
    top
    +

    MMapFile Directive

    + + + + + + +
    Description:Map a list of files into memory at startup time
    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 +

    + +

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_filter.html.en b/docs/manual/mod/mod_filter.html.en index 1838254e0a4..d0f06922b87 100644 --- a/docs/manual/mod/mod_filter.html.en +++ b/docs/manual/mod/mod_filter.html.en @@ -45,15 +45,7 @@ to mod_filter; no change to existing filter modules is required (although it may be possible to simplify them).

    -

    Directives

    - -

    Topics

    + +

    Directives

    + +
    +
    top
    +
    +

    Smart Filtering

    +

    In the traditional filtering model, filters are inserted unconditionally + using AddOutputFilter and family. + Each filter then needs to determine whether to run, and there is little + flexibility available for server admins to allow the chain to be + configured dynamically.

    + +

    mod_filter by contrast gives server administrators a + great deal of flexibility in configuring the filter chain. In fact, + filters can be inserted based on any Request Header, Response Header + or Environment Variable. This generalises the limited flexibility offered + by AddOutputFilterByType, and fixes + it to work correctly with dynamic content, regardless of the + content generator. The ability to dispatch based on Environment + Variables offers the full flexibility of configuration with + mod_rewrite to anyone who needs it.

    +
    top
    +
    +

    Filter Declarations, Providers and Chains

    +

    + [This image displays the traditional filter model]
    + Figure 1: The traditional filter model

    + +

    In the traditional model, output filters are a simple chain + from the content generator (handler) to the client. This works well + provided the filter chain can be correctly configured, but presents + problems when the filters need to be configured dynamically based on + the outcome of the handler.

    + +

    + [This image shows the mod_filter model]
    + Figure 2: The mod_filter model

    + +

    mod_filter works by introducing indirection into + the filter chain. Instead of inserting filters in the chain, we insert + a filter harness which in turn dispatches conditionally + to a filter provider. Any content filter may be used as a provider + to mod_filter; no change to existing filter modules + is required (although it may be possible to simplify them). There can be + multiple providers for one filter, but no more than one provider will + run for any single request.

    + +

    A filter chain comprises any number of instances of the filter + harness, each of which may have any number of providers. A special + case is that of a single provider with unconditional dispatch: this + is equivalent to inserting the provider filter directly into the chain.

    +
    top
    +
    +

    Configuring the Chain

    +

    There are three stages to configuring a filter chain with + mod_filter. For details of the directives, see below.

    + +
    +
    Declare Filters
    +
    The FilterDeclare directive + declares a filter, assigning it a name and filter type. Required + only if the filter is not the default type AP_FTYPE_RESOURCE.
    + +
    Register Providers
    +
    The FilterProvider + directive registers a provider with a filter. The filter may have + been declared with FilterDeclare; if not, FilterProvider will implicitly + declare it with the default type AP_FTYPE_RESOURCE. The provider + must have been + registered with ap_register_output_filter by some module. + The remaining arguments to FilterProvider are a dispatch criterion and a match string. + The former may be an HTTP request or response header, an environment + variable, or the Handler used by this request. The latter is matched + to it for each request, to determine whether this provider will be + used to implement the filter for this request.
    + +
    Configure the Chain
    +
    The above directives build components of a smart filter chain, + but do not configure it to run. The FilterChain directive builds a filter chain from smart + filters declared, offering the flexibility to insert filters at the + beginning or end of the chain, remove a filter, or clear the chain.
    +
    +
    top
    +
    +

    Filtering and Response Status

    +

    mod_filter normally only runs filters on responses with + HTTP status 200 (OK). If you want to filter documents with + other response statuses, you can set the filter-errordocs + environment variable, and it will work on all responses + regardless of status. To refine this further, you can use + expression conditions with FilterProvider.

    +
    top
    +
    +

    Examples

    +
    +
    Server side Includes (SSI)
    +
    A simple case of using mod_filter in place of + AddOutputFilterByType +

    + FilterDeclare SSI
    + FilterProvider SSI INCLUDES resp=Content-Type $text/html
    + FilterChain SSI +

    +
    + +
    Server side Includes (SSI)
    +
    The same as the above but dispatching on handler (classic + SSI behaviour; .shtml files get processed). +

    + FilterProvider SSI INCLUDES Handler server-parsed
    + FilterChain SSI +

    +
    + +
    Emulating mod_gzip with mod_deflate
    +
    Insert INFLATE filter only if "gzip" is NOT in the + Accept-Encoding header. This filter runs with ftype CONTENT_SET. +

    + FilterDeclare gzip CONTENT_SET
    + FilterProvider gzip inflate req=Accept-Encoding !$gzip
    + FilterChain gzip +

    +
    + +
    Image Downsampling
    +
    Suppose we want to downsample all web images, and have filters + for GIF, JPEG and PNG. +

    + FilterProvider unpack jpeg_unpack Content-Type $image/jpeg
    + FilterProvider unpack gif_unpack Content-Type $image/gif
    + FilterProvider unpack png_unpack Content-Type $image/png
    +
    + FilterProvider downsample downsample_filter Content-Type $image
    + FilterProtocol downsample "change=yes"
    +
    + FilterProvider repack jpeg_pack Content-Type $image/jpeg
    + FilterProvider repack gif_pack Content-Type $image/gif
    + FilterProvider repack png_pack Content-Type $image/png
    + <Location /image-filter>
    + + FilterChain unpack downsample repack
    +     + </Location> +

    +
    +
    +
    top
    +
    +

    Protocol Handling

    +

    Historically, each filter is responsible for ensuring that whatever + changes it makes are correctly represented in the HTTP response headers, + and that it does not run when it would make an illegal change. This + imposes a burden on filter authors to re-implement some common + functionality in every filter:

    + + + +

    mod_filter aims to offer generic handling of these + details of filter implementation, reducing the complexity required of + content filter modules. This is work-in-progress; the + FilterProtocol implements + some of this functionality for back-compatibility with Apache 2.0 + modules. For httpd 2.1 and later, the + ap_register_output_filter_protocol and + ap_filter_protocol API enables filter modules to + declare their own behaviour.

    + +

    At the same time, mod_filter should not interfere + with a filter that wants to handle all aspects of the protocol. By + default (i.e. in the absence of any FilterProtocol directives), mod_filter + will leave the headers untouched.

    + +

    At the time of writing, this feature is largely untested, + as modules in common use are designed to work with 2.0. + Modules using it should test it carefully.

    +
    top

    FilterChain Directive

    @@ -262,191 +447,6 @@ -
    top
    -
    -

    Smart Filtering

    -

    In the traditional filtering model, filters are inserted unconditionally - using AddOutputFilter and family. - Each filter then needs to determine whether to run, and there is little - flexibility available for server admins to allow the chain to be - configured dynamically.

    - -

    mod_filter by contrast gives server administrators a - great deal of flexibility in configuring the filter chain. In fact, - filters can be inserted based on any Request Header, Response Header - or Environment Variable. This generalises the limited flexibility offered - by AddOutputFilterByType, and fixes - it to work correctly with dynamic content, regardless of the - content generator. The ability to dispatch based on Environment - Variables offers the full flexibility of configuration with - mod_rewrite to anyone who needs it.

    -
    top
    -
    -

    Filter Declarations, Providers and Chains

    -

    - [This image displays the traditional filter model]
    - Figure 1: The traditional filter model

    - -

    In the traditional model, output filters are a simple chain - from the content generator (handler) to the client. This works well - provided the filter chain can be correctly configured, but presents - problems when the filters need to be configured dynamically based on - the outcome of the handler.

    - -

    - [This image shows the mod_filter model]
    - Figure 2: The mod_filter model

    - -

    mod_filter works by introducing indirection into - the filter chain. Instead of inserting filters in the chain, we insert - a filter harness which in turn dispatches conditionally - to a filter provider. Any content filter may be used as a provider - to mod_filter; no change to existing filter modules - is required (although it may be possible to simplify them). There can be - multiple providers for one filter, but no more than one provider will - run for any single request.

    - -

    A filter chain comprises any number of instances of the filter - harness, each of which may have any number of providers. A special - case is that of a single provider with unconditional dispatch: this - is equivalent to inserting the provider filter directly into the chain.

    -
    top
    -
    -

    Configuring the Chain

    -

    There are three stages to configuring a filter chain with - mod_filter. For details of the directives, see below.

    - -
    -
    Declare Filters
    -
    The FilterDeclare directive - declares a filter, assigning it a name and filter type. Required - only if the filter is not the default type AP_FTYPE_RESOURCE.
    - -
    Register Providers
    -
    The FilterProvider - directive registers a provider with a filter. The filter may have - been declared with FilterDeclare; if not, FilterProvider will implicitly - declare it with the default type AP_FTYPE_RESOURCE. The provider - must have been - registered with ap_register_output_filter by some module. - The remaining arguments to FilterProvider are a dispatch criterion and a match string. - The former may be an HTTP request or response header, an environment - variable, or the Handler used by this request. The latter is matched - to it for each request, to determine whether this provider will be - used to implement the filter for this request.
    - -
    Configure the Chain
    -
    The above directives build components of a smart filter chain, - but do not configure it to run. The FilterChain directive builds a filter chain from smart - filters declared, offering the flexibility to insert filters at the - beginning or end of the chain, remove a filter, or clear the chain.
    -
    -
    top
    -
    -

    Filtering and Response Status

    -

    mod_filter normally only runs filters on responses with - HTTP status 200 (OK). If you want to filter documents with - other response statuses, you can set the filter-errordocs - environment variable, and it will work on all responses - regardless of status. To refine this further, you can use - expression conditions with FilterProvider.

    -
    top
    -
    -

    Examples

    -
    -
    Server side Includes (SSI)
    -
    A simple case of using mod_filter in place of - AddOutputFilterByType -

    - FilterDeclare SSI
    - FilterProvider SSI INCLUDES resp=Content-Type $text/html
    - FilterChain SSI -

    -
    - -
    Server side Includes (SSI)
    -
    The same as the above but dispatching on handler (classic - SSI behaviour; .shtml files get processed). -

    - FilterProvider SSI INCLUDES Handler server-parsed
    - FilterChain SSI -

    -
    - -
    Emulating mod_gzip with mod_deflate
    -
    Insert INFLATE filter only if "gzip" is NOT in the - Accept-Encoding header. This filter runs with ftype CONTENT_SET. -

    - FilterDeclare gzip CONTENT_SET
    - FilterProvider gzip inflate req=Accept-Encoding !$gzip
    - FilterChain gzip -

    -
    - -
    Image Downsampling
    -
    Suppose we want to downsample all web images, and have filters - for GIF, JPEG and PNG. -

    - FilterProvider unpack jpeg_unpack Content-Type $image/jpeg
    - FilterProvider unpack gif_unpack Content-Type $image/gif
    - FilterProvider unpack png_unpack Content-Type $image/png
    -
    - FilterProvider downsample downsample_filter Content-Type $image
    - FilterProtocol downsample "change=yes"
    -
    - FilterProvider repack jpeg_pack Content-Type $image/jpeg
    - FilterProvider repack gif_pack Content-Type $image/gif
    - FilterProvider repack png_pack Content-Type $image/png
    - <Location /image-filter>
    - - FilterChain unpack downsample repack
    -     - </Location> -

    -
    -
    -
    top
    -
    -

    Protocol Handling

    -

    Historically, each filter is responsible for ensuring that whatever - changes it makes are correctly represented in the HTTP response headers, - and that it does not run when it would make an illegal change. This - imposes a burden on filter authors to re-implement some common - functionality in every filter:

    - -
      -
    • Many filters will change the content, invalidating existing content - tags, checksums, hashes, and lengths.
      • - -
    • Filters that require an entire, unbroken response in input need to - ensure they don't get byteranges from a backend.
      • - -
    • Filters that transform output in a filter need to ensure they don't - violate a Cache-Control: no-transform header from the - backend.
      • - -
    • Filters may make responses uncacheable.
      • -
    - -

    mod_filter aims to offer generic handling of these - details of filter implementation, reducing the complexity required of - content filter modules. This is work-in-progress; the - FilterProtocol implements - some of this functionality for back-compatibility with Apache 2.0 - modules. For httpd 2.1 and later, the - ap_register_output_filter_protocol and - ap_filter_protocol API enables filter modules to - declare their own behaviour.

    - -

    At the same time, mod_filter should not interfere - with a filter that wants to handle all aspects of the protocol. By - default (i.e. in the absence of any FilterProtocol directives), mod_filter - will leave the headers untouched.

    - -

    At the time of writing, this feature is largely untested, - as modules in common use are designed to work with 2.0. - Modules using it should test it carefully.

    -

    Available Languages:  en 

    diff --git a/docs/manual/mod/mod_headers.html.en b/docs/manual/mod/mod_headers.html.en index 5eed6d55a4a..46c20d9355d 100644 --- a/docs/manual/mod/mod_headers.html.en +++ b/docs/manual/mod/mod_headers.html.en @@ -39,17 +39,165 @@ headers request and response headers. Headers can be merged, replaced or removed.

    - +
    top
    +
    +

    Order of Processing

    + +

    The directives provided by mod_headers can + occur almost anywhere within the server configuration, and can be + limited in scope by enclosing them in configuration sections.

    + +

    Order of processing is important and is affected both by the + order in the configuration file and by placement in configuration sections. These + two directives 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".

    +
    top
    +
    +

    Early and Late Processing

    +

    mod_headers can be applied either early or late + in the request. The normal mode is late, when Request Headers are + set immediately before running the content generator and Response + Headers just as the response is sent down the wire. Always use + Late mode in an operational server.

    + +

    Early mode is designed as a test/debugging aid for developers. + Directives defined using the early keyword are set + right at the beginning of processing the request. This means + they can be used to simulate different requests and set up test + cases, but it also means that headers may be changed at any time + by other modules before generating a Response.

    + +

    Because early directives are processed before the request path's + configuration is traversed, early headers can only be set in a + main server or virtual host context. Early directives cannot depend + on a request path, so they will fail in contexts such as + <Directory> or <Location>.

    +
    top
    +
    +

    Examples

    + +
      +
    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 set MyHeader "%D %t" +

      + +

      results in this header being added to the response:

      + +

      + MyHeader: D=3775428 t=991424704447256 +

      +
      3. + +
    3. + Say hello to Joe + +

      + Header set 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 myvalue HAVE_MyRequestHeader
      + Header set MyHeader "%D %t mytext" env=HAVE_MyRequestHeader +

      + +

      If the header MyRequestHeader: myvalue is present on + the HTTP request, the response will contain the following header:

      + +

      + MyHeader: D=3775428 t=991424704447256 mytext +

      +
      5. + +
    5. + Enable DAV to work with Apache running HTTP through SSL hardware + (problem + description) by replacing https: with + http: in the Destination header: + +

      + RequestHeader edit Destination ^https: http: early +

      +
      6. + +
    6. + Set the same header value under multiple nonexclusive conditions, + but do not duplicate the value in the final header. + If all of the following conditions applied to a request (i.e., + if the CGI, NO_CACHE and + NO_STORE environment variables all existed for the + request): + +

      + Header merge Cache-Control no-cache env=CGI
      + Header merge Cache-Control no-cache env=NO_CACHE
      + Header merge Cache-Control no-store env=NO_STORE +

      + +

      then the response would contain the following header:

      + +

      + Cache-Control: no-cache, no-store +

      + +

      If append was used instead of merge, + then the response would contain the following header:

      + +

      + Cache-Control: no-cache, no-cache, no-store +

      +
      7. +
    +
    top

    Header Directive

    @@ -316,154 +464,6 @@ headers input filters to be overridden or modified.

    -
    top
    -
    -

    Order of Processing

    - -

    The directives provided by mod_headers can - occur almost anywhere within the server configuration, and can be - limited in scope by enclosing them in configuration sections.

    - -

    Order of processing is important and is affected both by the - order in the configuration file and by placement in configuration sections. These - two directives 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".

    -
    top
    -
    -

    Early and Late Processing

    -

    mod_headers can be applied either early or late - in the request. The normal mode is late, when Request Headers are - set immediately before running the content generator and Response - Headers just as the response is sent down the wire. Always use - Late mode in an operational server.

    - -

    Early mode is designed as a test/debugging aid for developers. - Directives defined using the early keyword are set - right at the beginning of processing the request. This means - they can be used to simulate different requests and set up test - cases, but it also means that headers may be changed at any time - by other modules before generating a Response.

    - -

    Because early directives are processed before the request path's - configuration is traversed, early headers can only be set in a - main server or virtual host context. Early directives cannot depend - on a request path, so they will fail in contexts such as - <Directory> or <Location>.

    -
    top
    -
    -

    Examples

    - -
      -
    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 set MyHeader "%D %t" -

      - -

      results in this header being added to the response:

      - -

      - MyHeader: D=3775428 t=991424704447256 -

      -
      3. - -
    3. - Say hello to Joe - -

      - Header set 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 myvalue HAVE_MyRequestHeader
      - Header set MyHeader "%D %t mytext" env=HAVE_MyRequestHeader -

      - -

      If the header MyRequestHeader: myvalue is present on - the HTTP request, the response will contain the following header:

      - -

      - MyHeader: D=3775428 t=991424704447256 mytext -

      -
      5. - -
    5. - Enable DAV to work with Apache running HTTP through SSL hardware - (problem - description) by replacing https: with - http: in the Destination header: - -

      - RequestHeader edit Destination ^https: http: early -

      -
      6. - -
    6. - Set the same header value under multiple nonexclusive conditions, - but do not duplicate the value in the final header. - If all of the following conditions applied to a request (i.e., - if the CGI, NO_CACHE and - NO_STORE environment variables all existed for the - request): - -

      - Header merge Cache-Control no-cache env=CGI
      - Header merge Cache-Control no-cache env=NO_CACHE
      - Header merge Cache-Control no-store env=NO_STORE -

      - -

      then the response would contain the following header:

      - -

      - Cache-Control: no-cache, no-store -

      - -

      If append was used instead of merge, - then the response would contain the following header:

      - -

      - Cache-Control: no-cache, no-cache, no-store -

      -
      7. -
    -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_ident.html.en b/docs/manual/mod/mod_ident.html.en index ea788675b26..ec171ee0d6e 100644 --- a/docs/manual/mod/mod_ident.html.en +++ b/docs/manual/mod/mod_ident.html.en @@ -47,6 +47,7 @@

    +
    top

    IdentityCheck Directive

    @@ -94,7 +95,6 @@ user timeout value according to your local network speed.

    -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_imagemap.html.en b/docs/manual/mod/mod_imagemap.html.en index d48fcfd7f26..1052ed85b2a 100644 --- a/docs/manual/mod/mod_imagemap.html.en +++ b/docs/manual/mod/mod_imagemap.html.en @@ -53,106 +53,19 @@

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

    -
    - - - - - - - -
    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_imagemap
    -

    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/.

    - -

    See also

    -

    Directives

    + -
    -
    top
    -

    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_imagemap
    -

    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.

    - -
    -
    top
    -

    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_imagemap
    -

    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.
    -
    - -
    +
    top

    New Features

    @@ -375,6 +288,93 @@ an imagemap </a>

    + +
    top
    +

    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_imagemap
    +

    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/.

    + +

    See also

    + +
    +
    top
    +

    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_imagemap
    +

    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.

    + +
    +
    top
    +

    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_imagemap
    +

    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.
    +
    +
    diff --git a/docs/manual/mod/mod_include.html.en b/docs/manual/mod/mod_include.html.en index e42232771ce..4893d449907 100644 --- a/docs/manual/mod/mod_include.html.en +++ b/docs/manual/mod/mod_include.html.en @@ -42,7 +42,15 @@ inclusion of other files or programs, as well as the setting and printing of environment variables.

    -

    Directives

    +
    top
    -

    SSIEnableAccess Directive

    - - - - - - - -
    Description:Enable the -A flag during conditional flow control processing.
    Syntax:SSIEnableAccess on|off
    Default:SSIEnableAccess off
    Context:directory, .htaccess
    Status:Base
    Module:mod_include
    -

    The SSIEnableAccess directive controls whether - the -A test is enabled during conditional flow control processing. - SSIEnableAccess can take on the following values:

    +
    +

    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:

    -
    off
    -
    <!--#if expr="-A /foo"--> will be interpreted as a series - of string and regular expression tokens, the -A has no special - meaning.
    +

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

    -
    on
    -
    <!--#if expr="-A /foo"--> will evaluate to false if the - URL /foo is inaccessible by configuration, or true otherwise.
    +

    The following directive must be given for the directories + containing the shtml files (typically in a + <Directory> section, + but this directive is also valid in .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.

    +
    top
    +
    +

    PATH_INFO with Server Side Includes

    + -
    -
    top
    -

    SSIEndTag Directive

    - - - - - - - - -
    Description:String that ends an include element
    Syntax:SSIEndTag tag
    Default:SSIEndTag "-->"
    Context:server config, virtual host
    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 an include element.

    +

    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.

    +
    top
    +
    +

    Basic Elements

    +

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

    -

    Example

    - SSIEndTag "%>" +

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

    +

    The value will often be enclosed in double quotes, but single + quotes (') and backticks (`) are also + possible. 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. Note that the leading <!--# is one + token and may not contain any whitespaces.

    -

    See also

    - -
    -
    top
    -

    SSIErrorMsg Directive

    - - - - - - - - - -
    Description:Error message displayed when there is an SSI -error
    Syntax:SSIErrorMsg message
    Default:SSIErrorMsg "[an error occurred while processing this -directive]"
    Context:server config, virtual host, directory, .htaccess
    Override:All
    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.

    +

    The allowed elements are listed in the following table:

    -

    Example

    - SSIErrorMsg "<!-- Error -->" -

    + + + + + + + + + + + + + + + + + + +
    ElementDescription
    configconfigure output formats
    echoprint variables
    execexecute external programs
    fsizeprint size of a file
    flastmodprint last modification time of a file
    includeinclude a file
    printenvprint all available variables
    setset a value of a variable
    -
    -
    top
    -

    SSIETag Directive

    - - - - - - - - -
    Description:Controls whether ETags are generated by the server.
    Syntax:SSIETag on|off
    Default:SSIETag off
    Context:directory, .htaccess
    Status:Base
    Module:mod_include
    Compatibility:Available in version 2.2.15 and later.
    -

    Under normal circumstances, a file filtered by mod_include - may contain elements that are either dynamically generated, or that may - have changed independently of the original file. As a result, by default - the server is asked not to generate an ETag header for the - response by adding no-etag to the request notes.

    +

    SSI elements may be defined by modules other than + mod_include. In fact, the exec element is provided by + mod_cgi, and will only be available if this + module is loaded.

    -

    The SSIETag directive suppresses this - behaviour, and allows the server to generate an ETag header. - This can be used to enable caching of the output. Note that a backend server - or dynamic content generator may generate an ETag of its own, ignoring - no-etag, and this ETag will be passed by - mod_include regardless of the value of this setting. - SSIETag can take on the following values:

    +

    The config Element

    +

    This command controls various aspects of the parsing. The + valid attributes are:

    +
    echomsg (Apache 2.1 and later)
    +
    The value is a message that is sent back to the + client if the echo element + attempts to echo an undefined variable. This overrides any SSIUndefinedEcho directives.
    -
    off
    -
    no-etag will be added to the request notes, and the server - is asked not to generate an ETag. Where a server ignores the value of - no-etag and generates an ETag anyway, the ETag will be - respected.
    +
    errmsg
    +
    The value is a message that is sent back to the + client if an error occurs while parsing the + document. This overrides any SSIErrorMsg directives.
    -
    on
    -
    Existing ETags will be respected, and ETags generated by the server will - be passed on in the response.
    +
    sizefmt
    +
    The value sets the format to be used when 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, for example a size of 1024 bytes + will be printed as "1K".
    +
    timefmt
    +
    The value is a string to be used by the + strftime(3) library routine when printing + dates.
    + +

    The echo Element

    +

    This command prints one of the include + variables defined below. If the variable is unset, the result is + determined by the SSIUndefinedEcho directive. Any dates printed are + subject to the currently configured timefmt.

    -
    -
    top
    -

    SSILastModified Directive

    - - - - - - - - -
    Description:Controls whether Last-Modified headers are generated by the -server.
    Syntax:SSILastModified on|off
    Default:SSILastModified off
    Context:directory, .htaccess
    Status:Base
    Module:mod_include
    Compatibility:Available in version 2.2.15 and later.
    -

    Under normal circumstances, a file filtered by mod_include - may contain elements that are either dynamically generated, or that may - have changed independently of the original file. As a result, by default - the Last-Modified header is stripped from the response.

    +

    Attributes:

    -

    The SSILastModified directive overrides this - behaviour, and allows the Last-Modified header to be respected - if already present, or set if the header is not already present. This can - be used to enable caching of the output. SSILastModified - can take on the following values:

    -
    - -
    off
    -
    The Last-Modified header will be stripped from responses, - unless the XBitHack directive - is set to full as described below.
    - -
    on
    -
    The Last-Modified header will be respected if already - present in a response, and added to the response if the response is a - file and the header is missing. The - SSILastModified directive - takes precedence over XBitHack.
    - +
    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, e.g. 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.

    + +

    The encoding attribute must precede the + corresponding var attribute to be effective, and + 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.

    + +
    + In order to avoid cross-site scripting issues, you should + always encode user supplied data. +
    +
    - + -
    -
    top
    -

    SSIStartTag Directive

    - - - - - - - - -
    Description:String that starts an include element
    Syntax:SSIStartTag tag
    Default:SSIStartTag "<!--#"
    Context:server config, virtual host
    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.

    +

    The exec Element

    +

    The exec command executes a given shell command or + CGI script. It requires mod_cgi to be present + in the server. If Options + IncludesNOEXEC is set, this command is completely + disabled. The valid attributes are:

    -

    You may want to use this option if you have 2 servers parsing the - output of a file each processing different commands (possibly at - different times).

    +
    +
    cgi
    +

    The value specifies a (%-encoded) URL-path to + the CGI script. If the path does not begin with a slash (/), + 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 Options + ExecCGI).

    -

    Example

    - SSIStartTag "<%"
    - SSIEndTag "%>" -

    +

    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.

    -

    The example given above, which also specifies a matching - SSIEndTag, will - allow you to use SSI directives as shown in the example - below:

    +

    Example

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

    -

    SSI directives with alternate start and end tags

    - <%printenv %> -

    +

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

    -

    See also

    - -
    -
    top
    -

    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:All
    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.

    +

    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:

    -

    This directive has the same effect as the <!--#config - timefmt=formatstring --> element.

    +

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

    + -

    Example

    - SSITimeFormat "%R, %B %d, %Y" -

    +
    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 above directive would cause times to be displayed in the - format "22:26, June 14, 2002".

    +

    The use of #include virtual is almost always prefered to using + either #exec cgi or #exec cmd. The former + (#include virtual) uses the standard Apache sub-request + mechanism to include files or scripts. It is much better tested and + maintained.

    -
    -
    top
    -

    SSIUndefinedEcho Directive

    - - - - - - - - - -
    Description:String displayed when an unset variable is echoed
    Syntax:SSIUndefinedEcho string
    Default:SSIUndefinedEcho "(none)"
    Context:server config, virtual host, directory, .htaccess
    Override:All
    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".

    +

    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:

    -

    Example

    - SSIUndefinedEcho "<!-- undef -->" -

    +

    + <!--#exec cmd="perl /path/to/perlscript arg1 arg2" --> +

    + + + -
    -
    top
    -

    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
    -

    The XBitHack directive 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:

    +

    The fsize Element

    +

    This command prints the size of the specified file, subject + to the sizefmt format specification. Attributes:

    -
    -
    off
    -
    No special treatment of executable files.
    +
    +
    file
    +
    The value is a path relative to the directory + containing the current document being parsed.
    -
    on
    -
    Any text/html file that has the user-execute bit - set will be treated as a server-parsed html document.
    +
    virtual
    +
    The value is a (%-encoded) URL-path. If it does not begin with + a slash (/) then it is taken to be relative to the current document. + Note, that this does not print the size of any CGI output, + but the size of the CGI script itself.
    +
    + -
    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. +

    The flastmod Element

    +

    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.

    + -

    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).

    - -

    The SSILastModified - directive takes precedence over the - XBitHack directive when - SSILastModified is set to - on.

    -
    +

    The include Element

    +

    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 + Options + IncludesNOEXEC set, then only documents with a text + MIME-type (text/plain, + text/html etc.) will be included. 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.
    -
    -
    top
    -
    -

    Enabling Server-Side Includes

    - +
    virtual
    +

    The value is a (%-encoded) URL-path. 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.

    -

    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:

    +

    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.

    -

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

    +

    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.

    +
    + + -

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

    +

    The printenv Element

    +

    This prints out a listing of all existing variables and + their values. Special characters are entity encoded (see the echo element for details) + before being output. There are no attributes.

    -

    - Options +Includes -

    +

    Example

    + <!--#printenv --> +

    + -

    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).

    +

    The set Element

    +

    This sets the value of a variable. Attributes:

    -

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

    +
    +
    var
    +
    The name of the variable to set.
    + +
    value
    +
    The value to give a variable.
    +
    + +

    Example

    + <!--#set var="category" value="help" --> +

    +
    top
    -

    PATH_INFO with Server Side Includes

    +

    Include Variables

    -

    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.

    -
    top
    -
    -

    Basic Elements

    -

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

    +

    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.

    -

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

    +
    +
    DATE_GMT
    +
    The current date in Greenwich Mean Time.
    -

    The value will often be enclosed in double quotes, but single - quotes (') and backticks (`) are also - possible. 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. Note that the leading <!--# is one - token and may not contain any whitespaces.

    +
    DATE_LOCAL
    +
    The current date in the local time zone.
    -

    The allowed elements are listed in the following table:

    +
    DOCUMENT_NAME
    +
    The filename (excluding directories) of the document + requested by the user.
    - - - - - - - - - - - - - - - - - - -
    ElementDescription
    configconfigure output formats
    echoprint variables
    execexecute external programs
    fsizeprint size of a file
    flastmodprint last modification time of a file
    includeinclude a file
    printenvprint all available variables
    setset a value of a variable
    +
    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 the URL for the current document. Note also that + if the URL is modified internally (e.g. by an alias or directoryindex), the modified + URL is shown.
    -

    SSI elements may be defined by modules other than - mod_include. In fact, the exec element is provided by - mod_cgi, and will only be available if this - module is loaded.

    +
    LAST_MODIFIED
    +
    The last modification date of the document requested by + the user.
    -

    The config Element

    -

    This command controls various aspects of the parsing. The - valid attributes are:

    +
    QUERY_STRING_UNESCAPED
    +
    If a query string is present, this variable contains the + (%-decoded) query string, which is escaped for shell + usage (special characters like & etc. are + preceded by backslashes).
    +
    +
    top
    +
    +

    Variable Substitution

    -
    -
    echomsg (Apache 2.1 and later)
    -
    The value is a message that is sent back to the - client if the echo element - attempts to echo an undefined variable. This overrides any SSIUndefinedEcho directives.
    +

    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:

    -
    errmsg
    -
    The value is a message that is sent back to the - client if an error occurs while parsing the - document. This overrides any SSIErrorMsg directives.
    +

    + <!--#if expr="$a = \$test" --> +

    -
    sizefmt
    -
    The value sets the format to be used when 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, for example a size of 1024 bytes - will be printed as "1K".
    +

    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:

    -
    timefmt
    -
    The value is a string to be used by the - strftime(3) library routine when printing - dates.
    -
    - +

    + <!--#set var="Zed" value="${REMOTE_HOST}_${REQUEST_METHOD}" --> +

    -

    The echo Element

    -

    This command prints one of the include - variables defined below. If the variable is unset, the result is - determined by the SSIUndefinedEcho directive. Any dates printed are - subject to the currently configured timefmt.

    +

    This will result in the Zed variable being set + to "X_Y" if REMOTE_HOST is + "X" and REQUEST_METHOD is + "Y".

    + +

    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 --> +

    +
    top
    +
    +

    Flow Control Elements

    + -

    Attributes:

    +

    The basic flow control elements are:

    -
    -
    var
    -
    The value is the name of the variable to print.
    +

    + <!--#if expr="test_condition" -->
    + <!--#elif expr="test_condition" -->
    + <!--#else -->
    + <!--#endif --> +

    -
    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, e.g. 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.

    +

    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 encoding attribute must precede the - corresponding var attribute to be effective, and - 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.

    +

    The elif or else statements are used + to put text into the output stream if the original + test_condition was false. These elements are optional.

    -
    - In order to avoid cross-site scripting issues, you should - always encode user supplied data. -
    -
    -
    - +

    The endif element ends the if element + and is required.

    -

    The exec Element

    -

    The exec command executes a given shell command or - CGI script. It requires mod_cgi to be present - in the server. If Options - IncludesNOEXEC is set, this command is completely - disabled. The valid attributes are:

    +

    test_condition is one of the following:

    -
    -
    cgi
    -

    The value specifies a (%-encoded) URL-path to - the CGI script. If the path does not begin with a slash (/), - 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 Options - ExecCGI).

    +
    +
    string
    +
    true if string is not empty
    -

    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.

    +
    -A string
    +

    true if the URL represented by the string is accessible by + configuration, false otherwise. This test only has an effect if + SSIEnableAccess is on. This is useful + where content on a page is to be hidden from users who are not + authorized to view the URL, such as a link to that URL. Note + that the URL is only tested for whether access would be granted, + not whether the URL exists.

    Example

    - <!--#exec cgi="/cgi-bin/example.cgi" --> + <!--#if expr="-A /private" -->
    + + Click <a href="/private">here</a> to access private + information.
    +     + <!--#endif -->

    +
    -

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

    +
    string1 = string2
    + string1 == string2
    + string1 != string2
    + +

    Compare string1 with string2. If + string2 has the form /string2/ + then it is treated as a regular expression. Regular expressions are + implemented by the PCRE engine and + have the same syntax as those in perl + 5. Note that == is just an alias for = + and behaves exactly the same way.

    -

    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:

    +

    If you are matching positive (= or ==), you + can capture grouped parts of the regular expression. The captured parts + are stored in the special variables $1 .. + $9.

    -

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

    Example

    + <!--#if expr="$QUERY_STRING = /^sid=([a-zA-Z0-9]+)/" -->
    + + <!--#set var="session" value="$1" -->
    +     + <!--#endif -->

    -
    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.

    +
    string1 < string2
    + string1 <= string2
    + string1 > string2
    + string1 >= string2
    -

    The use of #include virtual is almost always prefered to using - either #exec cgi or #exec cmd. The former - (#include virtual) uses the standard Apache sub-request - mechanism to include files or scripts. It is much better tested and - maintained.

    +
    Compare string1 with string2. Note, that + strings are compared literally (using + strcmp(3)). Therefore the string "100" is less than + "20".
    -

    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:

    +
    ( test_condition )
    +
    true if test_condition is true
    -

    - <!--#exec cmd="perl /path/to/perlscript arg1 arg2" --> -

    -
    -
    - +
    ! test_condition
    +
    true if test_condition is false
    -

    The fsize Element

    -

    This command prints the size of the specified file, subject - to the sizefmt format specification. Attributes:

    +
    test_condition1 && + test_condition2
    +
    true if both test_condition1 and + test_condition2 are true
    -
    -
    file
    -
    The value is a path relative to the directory - containing the current document being parsed.
    +
    test_condition1 || + test_condition2
    +
    true if either test_condition1 or + test_condition2 is true
    +
    -
    virtual
    -
    The value is a (%-encoded) URL-path. If it does not begin with - a slash (/) then it is taken to be relative to the current document. - Note, that this does not print the size of any CGI output, - but the size of the CGI script itself.
    - - +

    "=" and "!=" bind more tightly than + "&&" and "||". "!" binds + most tightly. Thus, the following are equivalent:

    -

    The flastmod Element

    -

    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.

    - +

    + <!--#if expr="$a = test1 && $b = test2" -->
    + <!--#if expr="($a = test1) && ($b = test2)" --> +

    -

    The include Element

    -

    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 - Options - IncludesNOEXEC set, then only documents with a text - MIME-type (text/plain, - text/html etc.) will be included. Otherwise CGI - scripts are invoked as normal using the complete URL given in - the command, including any query string.

    +

    The boolean operators && and || + share the same priority. So if you want to bind such an operator more + tightly, you should use parentheses.

    + +

    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
    +
    + and
    +
    + 'string1    string2' results in string1    string2.

    + +

    Optimization of Boolean Expressions

    +

    If the expressions become more complex and slow down processing + significantly, you can try to optimize them according to the + evaluation rules:

    +
      +
    • Expressions are evaluated from left to right
      • +
    • Binary boolean operators (&& and ||) + are short circuited wherever possible. In conclusion with the rule + above that means, mod_include evaluates at first + the left expression. If the left result is sufficient to determine + the end result, processing stops here. Otherwise it evaluates the + right side and computes the end result from both left and right + results.
      • +
    • Short circuit evaluation is turned off as long as there are regular + expressions to deal with. These must be evaluated to fill in the + backreference variables ($1 .. $9).
      • +
    +

    If you want to look how a particular expression is handled, you can + recompile mod_include using the + -DDEBUG_INCLUDE compiler option. This inserts for every + parsed expression tokenizer information, the parse tree and how it is + evaluated into the output sent to the client.

    +
    + +

    Escaping slashes in regex strings

    +

    All slashes which are not intended to act as delimiters in your regex must + be escaped. This is regardless of their meaning to the regex engine.

    +
    +
    +
    top
    +

    SSIEnableAccess Directive

    + + + + + + + +
    Description:Enable the -A flag during conditional flow control processing.
    Syntax:SSIEnableAccess on|off
    Default:SSIEnableAccess off
    Context:directory, .htaccess
    Status:Base
    Module:mod_include
    +

    The SSIEnableAccess directive controls whether + the -A test is enabled during conditional flow control processing. + SSIEnableAccess can take on the following values:

    -

    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.
    +
    off
    +
    <!--#if expr="-A /foo"--> will be interpreted as a series + of string and regular expression tokens, the -A has no special + meaning.
    -
    virtual
    -

    The value is a (%-encoded) URL-path. 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.

    +
    on
    +
    <!--#if expr="-A /foo"--> will evaluate to false if the + URL /foo is inaccessible by configuration, or true otherwise.
    -

    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.

    - -
    - -

    The printenv Element

    -

    This prints out a listing of all existing variables and - their values. Special characters are entity encoded (see the echo element for details) - before being output. There are no attributes.

    +
    +
    top
    +

    SSIEndTag Directive

    + + + + + + + + +
    Description:String that ends an include element
    Syntax:SSIEndTag tag
    Default:SSIEndTag "-->"
    Context:server config, virtual host
    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 an include element.

    -

    Example

    - <!--#printenv --> -

    - +

    Example

    + SSIEndTag "%>" +

    -

    The set Element

    -

    This sets the value of a variable. Attributes:

    -
    -
    var
    -
    The name of the variable to set.
    +

    See also

    + +
    +
    top
    +

    SSIErrorMsg Directive

    + + + + + + + + + +
    Description:Error message displayed when there is an SSI +error
    Syntax:SSIErrorMsg message
    Default:SSIErrorMsg "[an error occurred while processing this +directive]"
    Context:server config, virtual host, directory, .htaccess
    Override:All
    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.

    -
    value
    -
    The value to give a variable.
    - +

    This directive has the same effect as the <!--#config + errmsg=message --> element.

    -

    Example

    - <!--#set var="category" value="help" --> -

    - -
    top
    -
    -

    Include Variables

    - +

    Example

    + SSIErrorMsg "<!-- Error -->" +

    -

    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.

    +
    +
    top
    +

    SSIETag Directive

    + + + + + + + + +
    Description:Controls whether ETags are generated by the server.
    Syntax:SSIETag on|off
    Default:SSIETag off
    Context:directory, .htaccess
    Status:Base
    Module:mod_include
    Compatibility:Available in version 2.2.15 and later.
    +

    Under normal circumstances, a file filtered by mod_include + may contain elements that are either dynamically generated, or that may + have changed independently of the original file. As a result, by default + the server is asked not to generate an ETag header for the + response by adding no-etag to the request notes.

    -
    -
    DATE_GMT
    -
    The current date in Greenwich Mean Time.
    +

    The SSIETag directive suppresses this + behaviour, and allows the server to generate an ETag header. + This can be used to enable caching of the output. Note that a backend server + or dynamic content generator may generate an ETag of its own, ignoring + no-etag, and this ETag will be passed by + mod_include regardless of the value of this setting. + SSIETag can take on the following values:

    -
    DATE_LOCAL
    -
    The current date in the local time zone.
    +
    -
    DOCUMENT_NAME
    -
    The filename (excluding directories) of the document - requested by the user.
    +
    off
    +
    no-etag will be added to the request notes, and the server + is asked not to generate an ETag. Where a server ignores the value of + no-etag and generates an ETag anyway, the ETag will be + respected.
    -
    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 the URL for the current document. Note also that - if the URL is modified internally (e.g. by an alias or directoryindex), the modified - URL is shown.
    +
    on
    +
    Existing ETags will be respected, and ETags generated by the server will + be passed on in the response.
    -
    LAST_MODIFIED
    -
    The last modification date of the document requested by - the user.
    +
    -
    QUERY_STRING_UNESCAPED
    -
    If a query string is present, this variable contains the - (%-decoded) query string, which is escaped for shell - usage (special characters like & etc. are - preceded by backslashes).
    -
    -
    top
    -
    -

    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:

    +
    +
    top
    +

    SSILastModified Directive

    + + + + + + + + +
    Description:Controls whether Last-Modified headers are generated by the +server.
    Syntax:SSILastModified on|off
    Default:SSILastModified off
    Context:directory, .htaccess
    Status:Base
    Module:mod_include
    Compatibility:Available in version 2.2.15 and later.
    +

    Under normal circumstances, a file filtered by mod_include + may contain elements that are either dynamically generated, or that may + have changed independently of the original file. As a result, by default + the Last-Modified header is stripped from the response.

    -

    - <!--#if expr="$a = \$test" --> -

    +

    The SSILastModified directive overrides this + behaviour, and allows the Last-Modified header to be respected + if already present, or set if the header is not already present. This can + be used to enable caching of the output. SSILastModified + can take on the following values:

    + +
    + +
    off
    +
    The Last-Modified header will be stripped from responses, + unless the XBitHack directive + is set to full as described below.
    + +
    on
    +
    The Last-Modified header will be respected if already + present in a response, and added to the response if the response is a + file and the header is missing. The + SSILastModified directive + takes precedence over XBitHack.
    + +
    + -

    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:

    +
    +
    top
    +

    SSIStartTag Directive

    + + + + + + + + +
    Description:String that starts an include element
    Syntax:SSIStartTag tag
    Default:SSIStartTag "<!--#"
    Context:server config, virtual host
    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.

    -

    - <!--#set var="Zed" value="${REMOTE_HOST}_${REQUEST_METHOD}" --> +

    You may want to use this option if you have 2 servers parsing the + output of a file each processing different commands (possibly at + different times).

    + +

    Example

    + SSIStartTag "<%"
    + SSIEndTag "%>"

    -

    This will result in the Zed variable being set - to "X_Y" if REMOTE_HOST is - "X" and REQUEST_METHOD is - "Y".

    - -

    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:

    +

    The example given above, which also specifies a matching + SSIEndTag, will + allow you to use SSI directives as shown in the example + below:

    -

    - <!--#if expr='"$DOCUMENT_URI" = "/foo/file.html"' -->
    - - in foo
    -     - <!--#elif expr='"$DOCUMENT_URI" = "/bar/file.html"' -->
    - - in bar
    -     - <!--#else -->
    - - in neither
    -     - <!--#endif --> +

    SSI directives with alternate start and end tags

    + <%printenv %>

    -
    top
    -
    -

    Flow Control Elements

    - -

    The basic flow control elements are:

    +

    See also

    + +
    +
    top
    +

    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:All
    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.

    -

    - <!--#if expr="test_condition" -->
    - <!--#elif expr="test_condition" -->
    - <!--#else -->
    - <!--#endif --> +

    This directive has the same effect as the <!--#config + timefmt=formatstring --> element.

    + +

    Example

    + SSITimeFormat "%R, %B %d, %Y"

    -

    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 above directive would cause times to be displayed in the + format "22:26, June 14, 2002".

    -

    The elif or else statements are used - to put text into the output stream if the original - test_condition was false. These elements are optional.

    +
    +
    top
    +

    SSIUndefinedEcho Directive

    + + + + + + + + + +
    Description:String displayed when an unset variable is echoed
    Syntax:SSIUndefinedEcho string
    Default:SSIUndefinedEcho "(none)"
    Context:server config, virtual host, directory, .htaccess
    Override:All
    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".

    -

    The endif element ends the if element - and is required.

    +

    Example

    + SSIUndefinedEcho "<!-- undef -->" +

    -

    test_condition is one of the following:

    +
    +
    top
    +

    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
    +

    The XBitHack directive 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:

    -
    string
    -
    true if string is not empty
    +
    off
    +
    No special treatment of executable files.
    -
    -A string
    -

    true if the URL represented by the string is accessible by - configuration, false otherwise. This test only has an effect if - SSIEnableAccess is on. This is useful - where content on a page is to be hidden from users who are not - authorized to view the URL, such as a link to that URL. Note - that the URL is only tested for whether access would be granted, - not whether the URL exists.

    +
    on
    +
    Any text/html file that has the user-execute bit + set will be treated as a server-parsed html document.
    -

    Example

    - <!--#if expr="-A /private" -->
    - - Click <a href="/private">here</a> to access private - information.
    -     - <!--#endif --> -

    - +
    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. -
    string1 = string2
    - string1 == string2
    - string1 != string2
    +

    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).

    -

    Compare string1 with string2. If - string2 has the form /string2/ - then it is treated as a regular expression. Regular expressions are - implemented by the PCRE engine and - have the same syntax as those in perl - 5. Note that == is just an alias for = - and behaves exactly the same way.

    - -

    If you are matching positive (= or ==), you - can capture grouped parts of the regular expression. The captured parts - are stored in the special variables $1 .. - $9.

    +

    The SSILastModified + directive takes precedence over the + XBitHack directive when + SSILastModified is set to + on.

    +
    -

    Example

    - <!--#if expr="$QUERY_STRING = /^sid=([a-zA-Z0-9]+)/" -->
    - - <!--#set var="session" value="$1" -->
    -     - <!--#endif --> -

    - -
    string1 < string2
    - string1 <= string2
    - string1 > string2
    - string1 >= string2
    - -
    Compare string1 with string2. Note, that - strings are compared literally (using - strcmp(3)). Therefore the string "100" is less than - "20".
    - -
    ( 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)" --> -

    - -

    The boolean operators && and || - share the same priority. So if you want to bind such an operator more - tightly, you should use parentheses.

    - -

    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
    -
    - and
    -
    - 'string1    string2' results in string1    string2.

    - -

    Optimization of Boolean Expressions

    -

    If the expressions become more complex and slow down processing - significantly, you can try to optimize them according to the - evaluation rules:

    -
      -
    • Expressions are evaluated from left to right
      • -
    • Binary boolean operators (&& and ||) - are short circuited wherever possible. In conclusion with the rule - above that means, mod_include evaluates at first - the left expression. If the left result is sufficient to determine - the end result, processing stops here. Otherwise it evaluates the - right side and computes the end result from both left and right - results.
      • -
    • Short circuit evaluation is turned off as long as there are regular - expressions to deal with. These must be evaluated to fill in the - backreference variables ($1 .. $9).
      • -
    -

    If you want to look how a particular expression is handled, you can - recompile mod_include using the - -DDEBUG_INCLUDE compiler option. This inserts for every - parsed expression tokenizer information, the parse tree and how it is - evaluated into the output sent to the client.

    -
    -

    Escaping slashes in regex strings

    -

    All slashes which are not intended to act as delimiters in your regex must - be escaped. This is regardless of their meaning to the regex engine.

    -
    diff --git a/docs/manual/mod/mod_info.html.en b/docs/manual/mod/mod_info.html.en index 34f4bdbbcb9..0f18e395837 100644 --- a/docs/manual/mod/mod_info.html.en +++ b/docs/manual/mod/mod_info.html.en @@ -65,40 +65,16 @@ configuration

    Once configured, the server information is obtained by accessing http://your.host.example.com/server-info

    -

    Directives

    - -

    Topics

    + -
    top
    -

    AddModuleInfo Directive

    - - - - - - - -
    Description:Adds additional information 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_deflate.c 'See <a \
    - - href="http://www.apache.org/docs/2.2/mod/mod_deflate.html">\
    - http://www.apache.org/docs/2.2/mod/mod_deflate.html</a>' -     -

    - -
    +

    Directives

    + +
    top

    Security Issues

    @@ -185,6 +161,30 @@ information displayed by the server-info handler might not be listed.
    +
    top
    +

    AddModuleInfo Directive

    + + + + + + + +
    Description:Adds additional information 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_deflate.c 'See <a \
    + + href="http://www.apache.org/docs/2.2/mod/mod_deflate.html">\
    + http://www.apache.org/docs/2.2/mod/mod_deflate.html</a>' +     +

    + +

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_isapi.html.en b/docs/manual/mod/mod_isapi.html.en index 141ce019855..ffe1cd4fd19 100644 --- a/docs/manual/mod/mod_isapi.html.en +++ b/docs/manual/mod/mod_isapi.html.en @@ -46,7 +46,12 @@ extension. Please do not post such problems to Apache's lists or bug reporting pages.

    -

    Directives

    + -
    top
    -

    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, virtual host, directory, .htaccess
    Override:FileInfo
    Status:Base
    Module:mod_isapi
    -

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

    - -
    -
    top
    -

    ISAPIAppendLogToQuery Directive

    - - - - - - - - -
    Description:Record HSE_APPEND_LOG_PARAMETER requests from -ISAPI extensions to the query field
    Syntax:ISAPIAppendLogToQuery on|off
    Default:ISAPIAppendLogToQuery on
    Context:server config, virtual host, directory, .htaccess
    Override:FileInfo
    Status:Base
    Module:mod_isapi
    -

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

    - -
    -
    top
    -

    ISAPICacheFile Directive

    - - - - - - -
    Description:ISAPI .dll files to be loaded at startup
    Syntax:ISAPICacheFile file-path [file-path] -...
    Context:server config, virtual host
    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. If the path name is not absolute, it will be treated - relative to ServerRoot.

    - -
    -
    top
    -

    ISAPIFakeAsync Directive

    - - - - - - - - -
    Description:Fake asynchronous support for ISAPI callbacks
    Syntax:ISAPIFakeAsync on|off
    Default:ISAPIFakeAsync off
    Context:server config, virtual host, directory, .htaccess
    Override:FileInfo
    Status:Base
    Module:mod_isapi
    -

    While set to on, asynchronous support for ISAPI callbacks is - simulated.

    - -
    -
    top
    -

    ISAPILogNotSupported Directive

    - - - - - - - - -
    Description:Log unsupported feature requests from ISAPI -extensions
    Syntax:ISAPILogNotSupported on|off
    Default:ISAPILogNotSupported off
    Context:server config, virtual host, directory, .htaccess
    Override:FileInfo
    Status:Base
    Module:mod_isapi
    -

    Logs all requests for unsupported features from ISAPI - extensions in the server error log. This may help administrators - to track down problems. Once set to on and all desired ISAPI modules - are functioning, it should be set back to off.

    - -
    -
    top
    -

    ISAPIReadAheadBuffer Directive

    - - - - - - - - -
    Description:Size of the Read Ahead Buffer sent to ISAPI -extensions
    Syntax:ISAPIReadAheadBuffer size
    Default:ISAPIReadAheadBuffer 49152
    Context:server config, virtual host, directory, .htaccess
    Override:FileInfo
    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.

    - -
    +
    top

    Usage

    @@ -336,6 +233,109 @@ extensions ISAPI .dlls for performance, neither of which were not available under Apache 1.3 mod_isapi.

    +
    top
    +

    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, virtual host, directory, .htaccess
    Override:FileInfo
    Status:Base
    Module:mod_isapi
    +

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

    + +
    +
    top
    +

    ISAPIAppendLogToQuery Directive

    + + + + + + + + +
    Description:Record HSE_APPEND_LOG_PARAMETER requests from +ISAPI extensions to the query field
    Syntax:ISAPIAppendLogToQuery on|off
    Default:ISAPIAppendLogToQuery on
    Context:server config, virtual host, directory, .htaccess
    Override:FileInfo
    Status:Base
    Module:mod_isapi
    +

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

    + +
    +
    top
    +

    ISAPICacheFile Directive

    + + + + + + +
    Description:ISAPI .dll files to be loaded at startup
    Syntax:ISAPICacheFile file-path [file-path] +...
    Context:server config, virtual host
    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. If the path name is not absolute, it will be treated + relative to ServerRoot.

    + +
    +
    top
    +

    ISAPIFakeAsync Directive

    + + + + + + + + +
    Description:Fake asynchronous support for ISAPI callbacks
    Syntax:ISAPIFakeAsync on|off
    Default:ISAPIFakeAsync off
    Context:server config, virtual host, directory, .htaccess
    Override:FileInfo
    Status:Base
    Module:mod_isapi
    +

    While set to on, asynchronous support for ISAPI callbacks is + simulated.

    + +
    +
    top
    +

    ISAPILogNotSupported Directive

    + + + + + + + + +
    Description:Log unsupported feature requests from ISAPI +extensions
    Syntax:ISAPILogNotSupported on|off
    Default:ISAPILogNotSupported off
    Context:server config, virtual host, directory, .htaccess
    Override:FileInfo
    Status:Base
    Module:mod_isapi
    +

    Logs all requests for unsupported features from ISAPI + extensions in the server error log. This may help administrators + to track down problems. Once set to on and all desired ISAPI modules + are functioning, it should be set back to off.

    + +
    +
    top
    +

    ISAPIReadAheadBuffer Directive

    + + + + + + + + +
    Description:Size of the Read Ahead Buffer sent to ISAPI +extensions
    Syntax:ISAPIReadAheadBuffer size
    Default:ISAPIReadAheadBuffer 49152
    Context:server config, virtual host, directory, .htaccess
    Override:FileInfo
    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.

    + +

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_ldap.html.en b/docs/manual/mod/mod_ldap.html.en index bed42dd8c88..4123d1e3cd5 100644 --- a/docs/manual/mod/mod_ldap.html.en +++ b/docs/manual/mod/mod_ldap.html.en @@ -57,7 +57,14 @@ by other LDAP modules website for details.

    -

    Directives

    + -
    top
    -

    LDAPCacheEntries Directive

    - - - - - - - -
    Description:Maximum number of entries in the primary LDAP cache
    Syntax:LDAPCacheEntries number
    Default:LDAPCacheEntries 1024
    Context:server config
    Status:Extension
    Module:mod_ldap
    -

    Specifies the maximum size of the primary LDAP cache. This - cache contains successful search/binds. Set it to 0 to turn off - search/bind caching. The default size is 1024 cached - searches.

    - -
    -
    top
    -

    LDAPCacheTTL Directive

    - - - - - - - -
    Description:Time that cached items remain valid
    Syntax:LDAPCacheTTL seconds
    Default:LDAPCacheTTL 600
    Context:server config
    Status:Extension
    Module:mod_ldap
    -

    Specifies the time (in seconds) that an item in the - search/bind cache remains valid. The default is 600 seconds (10 - minutes).

    - -
    -
    top
    -

    LDAPConnectionTimeout Directive

    - - - - - - -
    Description:Specifies the socket connection timeout in seconds
    Syntax:LDAPConnectionTimeout seconds
    Context:server config
    Status:Extension
    Module:mod_ldap
    -

    This directive configures the LDAP_OPT_NETWORK_TIMEOUT option in the - underlying LDAP client library, when available. This value typically - controls how long the LDAP client library will wait for the TCP connection - to the LDAP server to complete.

    - -

    If a connection is not successful with the timeout period, either an error will be - returned or the LDAP client library will attempt to connect to a secondary LDAP - server if one is specified (via a space-separated list of hostnames in the - AuthLDAPURL).

    - -

    The default is 10 seconds, if the LDAP client library linked with the - server supports the LDAP_OPT_NETWORK_TIMEOUT option.

    - -
    LDAPConnectionTimeout is only available when the LDAP client library linked - with the server supports the LDAP_OPT_NETWORK_TIMEOUT option, and the - ultimate behavior is dictated entirely by the LDAP client library. -
    - -
    -
    top
    -

    LDAPOpCacheEntries Directive

    - - - - - - - -
    Description:Number of entries used to cache LDAP compare -operations
    Syntax:LDAPOpCacheEntries number
    Default:LDAPOpCacheEntries 1024
    Context:server config
    Status:Extension
    Module:mod_ldap
    -

    This specifies the number of entries mod_ldap - will use to cache LDAP compare operations. The default is 1024 - entries. Setting it to 0 disables operation caching.

    - -
    -
    top
    -

    LDAPOpCacheTTL Directive

    - - - - - - - -
    Description:Time that entries in the operation cache remain -valid
    Syntax:LDAPOpCacheTTL seconds
    Default:LDAPOpCacheTTL 600
    Context:server config
    Status:Extension
    Module:mod_ldap
    -

    Specifies the time (in seconds) that entries in the - operation cache remain valid. The default is 600 seconds.

    - -
    -
    top
    -

    LDAPSharedCacheFile Directive

    - - - - - - -
    Description:Sets the shared memory cache file
    Syntax:LDAPSharedCacheFile directory-path/filename
    Context:server config
    Status:Extension
    Module:mod_ldap
    -

    Specifies the directory path and file name of the shared memory - cache file. If not set, anonymous shared memory will be used if the - platform supports it.

    - -
    -
    top
    -

    LDAPSharedCacheSize Directive

    - - - - - - - -
    Description:Size in bytes of the shared-memory cache
    Syntax:LDAPSharedCacheSize bytes
    Default:LDAPSharedCacheSize 500000
    Context:server config
    Status:Extension
    Module:mod_ldap
    -

    Specifies the number of bytes to allocate for the shared - memory cache. The default is 500kb. If set to 0, shared memory - caching will not be used.

    - -
    -
    top
    -

    LDAPTrustedClientCert Directive

    - - - - - - -
    Description:Sets the file containing or nickname referring to a per -connection client certificate. Not all LDAP toolkits support per -connection client certificates.
    Syntax:LDAPTrustedClientCert type directory-path/filename/nickname [password]
    Context:server config, virtual host, directory, .htaccess
    Status:Extension
    Module:mod_ldap
    -

    It specifies the directory path, file name or nickname of a - per connection client certificate used when establishing an SSL - or TLS connection to an LDAP server. Different locations or - directories may have their own independent client certificate - settings. Some LDAP toolkits (notably Novell) - do not support per connection client certificates, and will throw an - error on LDAP server connection if you try to use this directive - (Use the LDAPTrustedGlobalCert directive instead for Novell client - certificates - See the SSL/TLS certificate guide above for details). - The type specifies the kind of certificate parameter being - set, depending on the LDAP toolkit being used. Supported types are:

    -
      -
    • CERT_DER - binary DER encoded client certificate
      • -
    • CERT_BASE64 - PEM encoded client certificate
      • -
    • CERT_NICKNAME - Client certificate "nickname" (Netscape SDK)
      • -
    • KEY_DER - binary DER encoded private key
      • -
    • KEY_BASE64 - PEM encoded private key
      • -
    - -
    -
    top
    -

    LDAPTrustedGlobalCert Directive

    - - - - - - -
    Description:Sets the file or database containing global trusted -Certificate Authority or global client certificates
    Syntax:LDAPTrustedGlobalCert type directory-path/filename [password]
    Context:server config
    Status:Extension
    Module:mod_ldap
    -

    It specifies the directory path and file name of the trusted CA - certificates and/or system wide client certificates mod_ldap - should use when establishing an SSL or TLS connection to an LDAP - server. Note that all certificate information specified using this directive - is applied globally to the entire server installation. Some LDAP toolkits - (notably Novell) require all client certificates to be set globally using - this directive. Most other toolkits require clients certificates to be set - per Directory or per Location using LDAPTrustedClientCert. If you get this - wrong, an error may be logged when an attempt is made to contact the LDAP - server, or the connection may silently fail (See the SSL/TLS certificate - guide above for details). - The type specifies the kind of certificate parameter being - set, depending on the LDAP toolkit being used. Supported types are:

    -
      -
    • CA_DER - binary DER encoded CA certificate
      • -
    • CA_BASE64 - PEM encoded CA certificate
      • -
    • CA_CERT7_DB - Netscape cert7.db CA certificate database file
      • -
    • CA_SECMOD - Netscape secmod database file
      • -
    • CERT_DER - binary DER encoded client certificate
      • -
    • CERT_BASE64 - PEM encoded client certificate
      • -
    • CERT_KEY3_DB - Netscape key3.db client certificate database file
      • -
    • CERT_NICKNAME - Client certificate "nickname" (Netscape SDK)
      • -
    • CERT_PFX - PKCS#12 encoded client certificate (Novell SDK)
      • -
    • KEY_DER - binary DER encoded private key
      • -
    • KEY_BASE64 - PEM encoded private key
      • -
    • KEY_PFX - PKCS#12 encoded private key (Novell SDK)
      • -
    - -
    -
    top
    -

    LDAPTrustedMode Directive

    - - - - - - -
    Description:Specifies the SSL/TLS mode to be used when connecting to an LDAP server.
    Syntax:LDAPTrustedMode type
    Context:server config, virtual host
    Status:Extension
    Module:mod_ldap
    -

    The following modes are supported:

    -
      -
    • NONE - no encryption
      • -
    • SSL - ldaps:// encryption on default port 636
      • -
    • TLS - STARTTLS encryption on default port 389
      • -
    - -

    Not all LDAP toolkits support all the above modes. An error message - will be logged at runtime if a mode is not supported, and the - connection to the LDAP server will fail. -

    - -

    If an ldaps:// URL is specified, the mode becomes SSL and the setting - of LDAPTrustedMode is ignored.

    - -
    -
    top
    -

    LDAPVerifyServerCert Directive

    - - - - - - - -
    Description:Force server certificate verification
    Syntax:LDAPVerifyServerCert On|Off
    Default:LDAPVerifyServerCert On
    Context:server config
    Status:Extension
    Module:mod_ldap
    -

    Specifies whether to force the verification of a - server certificate when establishing an SSL connection to the - LDAP server.

    - -
    +
    top

    Example Configuration

    @@ -633,6 +404,235 @@ Certificate Authority or global client certificates +
    +
    top
    +

    LDAPCacheEntries Directive

    + + + + + + + +
    Description:Maximum number of entries in the primary LDAP cache
    Syntax:LDAPCacheEntries number
    Default:LDAPCacheEntries 1024
    Context:server config
    Status:Extension
    Module:mod_ldap
    +

    Specifies the maximum size of the primary LDAP cache. This + cache contains successful search/binds. Set it to 0 to turn off + search/bind caching. The default size is 1024 cached + searches.

    + +
    +
    top
    +

    LDAPCacheTTL Directive

    + + + + + + + +
    Description:Time that cached items remain valid
    Syntax:LDAPCacheTTL seconds
    Default:LDAPCacheTTL 600
    Context:server config
    Status:Extension
    Module:mod_ldap
    +

    Specifies the time (in seconds) that an item in the + search/bind cache remains valid. The default is 600 seconds (10 + minutes).

    + +
    +
    top
    +

    LDAPConnectionTimeout Directive

    + + + + + + +
    Description:Specifies the socket connection timeout in seconds
    Syntax:LDAPConnectionTimeout seconds
    Context:server config
    Status:Extension
    Module:mod_ldap
    +

    This directive configures the LDAP_OPT_NETWORK_TIMEOUT option in the + underlying LDAP client library, when available. This value typically + controls how long the LDAP client library will wait for the TCP connection + to the LDAP server to complete.

    + +

    If a connection is not successful with the timeout period, either an error will be + returned or the LDAP client library will attempt to connect to a secondary LDAP + server if one is specified (via a space-separated list of hostnames in the + AuthLDAPURL).

    + +

    The default is 10 seconds, if the LDAP client library linked with the + server supports the LDAP_OPT_NETWORK_TIMEOUT option.

    + +
    LDAPConnectionTimeout is only available when the LDAP client library linked + with the server supports the LDAP_OPT_NETWORK_TIMEOUT option, and the + ultimate behavior is dictated entirely by the LDAP client library. +
    + +
    +
    top
    +

    LDAPOpCacheEntries Directive

    + + + + + + + +
    Description:Number of entries used to cache LDAP compare +operations
    Syntax:LDAPOpCacheEntries number
    Default:LDAPOpCacheEntries 1024
    Context:server config
    Status:Extension
    Module:mod_ldap
    +

    This specifies the number of entries mod_ldap + will use to cache LDAP compare operations. The default is 1024 + entries. Setting it to 0 disables operation caching.

    + +
    +
    top
    +

    LDAPOpCacheTTL Directive

    + + + + + + + +
    Description:Time that entries in the operation cache remain +valid
    Syntax:LDAPOpCacheTTL seconds
    Default:LDAPOpCacheTTL 600
    Context:server config
    Status:Extension
    Module:mod_ldap
    +

    Specifies the time (in seconds) that entries in the + operation cache remain valid. The default is 600 seconds.

    + +
    +
    top
    +

    LDAPSharedCacheFile Directive

    + + + + + + +
    Description:Sets the shared memory cache file
    Syntax:LDAPSharedCacheFile directory-path/filename
    Context:server config
    Status:Extension
    Module:mod_ldap
    +

    Specifies the directory path and file name of the shared memory + cache file. If not set, anonymous shared memory will be used if the + platform supports it.

    + +
    +
    top
    +

    LDAPSharedCacheSize Directive

    + + + + + + + +
    Description:Size in bytes of the shared-memory cache
    Syntax:LDAPSharedCacheSize bytes
    Default:LDAPSharedCacheSize 500000
    Context:server config
    Status:Extension
    Module:mod_ldap
    +

    Specifies the number of bytes to allocate for the shared + memory cache. The default is 500kb. If set to 0, shared memory + caching will not be used.

    + +
    +
    top
    +

    LDAPTrustedClientCert Directive

    + + + + + + +
    Description:Sets the file containing or nickname referring to a per +connection client certificate. Not all LDAP toolkits support per +connection client certificates.
    Syntax:LDAPTrustedClientCert type directory-path/filename/nickname [password]
    Context:server config, virtual host, directory, .htaccess
    Status:Extension
    Module:mod_ldap
    +

    It specifies the directory path, file name or nickname of a + per connection client certificate used when establishing an SSL + or TLS connection to an LDAP server. Different locations or + directories may have their own independent client certificate + settings. Some LDAP toolkits (notably Novell) + do not support per connection client certificates, and will throw an + error on LDAP server connection if you try to use this directive + (Use the LDAPTrustedGlobalCert directive instead for Novell client + certificates - See the SSL/TLS certificate guide above for details). + The type specifies the kind of certificate parameter being + set, depending on the LDAP toolkit being used. Supported types are:

    +
      +
    • CERT_DER - binary DER encoded client certificate
      • +
    • CERT_BASE64 - PEM encoded client certificate
      • +
    • CERT_NICKNAME - Client certificate "nickname" (Netscape SDK)
      • +
    • KEY_DER - binary DER encoded private key
      • +
    • KEY_BASE64 - PEM encoded private key
      • +
    + +
    +
    top
    +

    LDAPTrustedGlobalCert Directive

    + + + + + + +
    Description:Sets the file or database containing global trusted +Certificate Authority or global client certificates
    Syntax:LDAPTrustedGlobalCert type directory-path/filename [password]
    Context:server config
    Status:Extension
    Module:mod_ldap
    +

    It specifies the directory path and file name of the trusted CA + certificates and/or system wide client certificates mod_ldap + should use when establishing an SSL or TLS connection to an LDAP + server. Note that all certificate information specified using this directive + is applied globally to the entire server installation. Some LDAP toolkits + (notably Novell) require all client certificates to be set globally using + this directive. Most other toolkits require clients certificates to be set + per Directory or per Location using LDAPTrustedClientCert. If you get this + wrong, an error may be logged when an attempt is made to contact the LDAP + server, or the connection may silently fail (See the SSL/TLS certificate + guide above for details). + The type specifies the kind of certificate parameter being + set, depending on the LDAP toolkit being used. Supported types are:

    +
      +
    • CA_DER - binary DER encoded CA certificate
      • +
    • CA_BASE64 - PEM encoded CA certificate
      • +
    • CA_CERT7_DB - Netscape cert7.db CA certificate database file
      • +
    • CA_SECMOD - Netscape secmod database file
      • +
    • CERT_DER - binary DER encoded client certificate
      • +
    • CERT_BASE64 - PEM encoded client certificate
      • +
    • CERT_KEY3_DB - Netscape key3.db client certificate database file
      • +
    • CERT_NICKNAME - Client certificate "nickname" (Netscape SDK)
      • +
    • CERT_PFX - PKCS#12 encoded client certificate (Novell SDK)
      • +
    • KEY_DER - binary DER encoded private key
      • +
    • KEY_BASE64 - PEM encoded private key
      • +
    • KEY_PFX - PKCS#12 encoded private key (Novell SDK)
      • +
    + +
    +
    top
    +

    LDAPTrustedMode Directive

    + + + + + + +
    Description:Specifies the SSL/TLS mode to be used when connecting to an LDAP server.
    Syntax:LDAPTrustedMode type
    Context:server config, virtual host
    Status:Extension
    Module:mod_ldap
    +

    The following modes are supported:

    +
      +
    • NONE - no encryption
      • +
    • SSL - ldaps:// encryption on default port 636
      • +
    • TLS - STARTTLS encryption on default port 389
      • +
    + +

    Not all LDAP toolkits support all the above modes. An error message + will be logged at runtime if a mode is not supported, and the + connection to the LDAP server will fail. +

    + +

    If an ldaps:// URL is specified, the mode becomes SSL and the setting + of LDAPTrustedMode is ignored.

    + +
    +
    top
    +

    LDAPVerifyServerCert Directive

    + + + + + + + +
    Description:Force server certificate verification
    Syntax:LDAPVerifyServerCert On|Off
    Default:LDAPVerifyServerCert On
    Context:server config
    Status:Extension
    Module:mod_ldap
    +

    Specifies whether to force the verification of a + server certificate when establishing an SSL connection to the + LDAP server.

    +
    diff --git a/docs/manual/mod/mod_log_config.html.en b/docs/manual/mod/mod_log_config.html.en index 9a6e4cc9a9d..34e8ae91657 100644 --- a/docs/manual/mod/mod_log_config.html.en +++ b/docs/manual/mod/mod_log_config.html.en @@ -49,7 +49,11 @@ 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

    +
    top
    -

    BufferedLogs Directive

    - - - - - - - - -
    Description:Buffer log entries in memory before writing to disk
    Syntax:BufferedLogs On|Off
    Default:BufferedLogs Off
    Context:server config
    Status:Base
    Module:mod_log_config
    Compatibility:Available in versions 2.0.41 and later.
    -

    The BufferedLogs directive causes - mod_log_config to store several log entries in - memory and write them together to disk, rather than writing them - after each request. On some systems, this may result in more - efficient disk access and hence higher performance. It may be - set only once for the entire server; it cannot be configured - per virtual-host.

    - -
    This directive is experimental and should be used with - caution.
    - -
    -
    top
    -

    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:This directive is deprecated.
    -

    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.

    - -
    -
    top
    -

    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
    -

    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 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. See the notes on piped logs - for more information. - -

    Security:

    -

    If a program is used, then it will be run as the user who - started httpd. This will be root if the server was - started by root; be sure that the program is secure.

    -
    -

    Note

    -

    When entering a file path on non-Unix platforms, care should be taken - to make sure that only forward slashed are used even though the platform - may allow the use of back slashes. In general it is a good idea to always - use forward slashes throughout the configuration files.

    -
    -
    - -

    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 controls whether or - not to log a particular request 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 want to record requests for all GIF - images on your server in a separate logfile but not in 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 -

    - -

    Or, to reproduce the behavior of the old RefererIgnore - directive, you might use the following:

    - -

    - SetEnvIf Referer example\.com localreferer
    - CustomLog referer.log referer env=!localreferer -

    - -
    -
    top
    -

    LogFormat Directive

    - - - - - - - -
    Description:Describes a format for use in a log file
    Syntax:LogFormat format|nickname -[nickname]
    Default:LogFormat "%h %l %u %t \"%r\" %>s %b"
    Context:server config, virtual host
    Status:Base
    Module:mod_log_config
    -

    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 the 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 that 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. - In addition, LogFormat cannot use one nickname - to define another nickname. Note that the nickname should not contain - percent signs (%).

    - -

    Example

    - LogFormat "%v %h %l %u %t \"%r\" %>s %b" vhost_common -

    - -
    -
    top
    -

    TransferLog Directive

    - - - - - - -
    Description:Specify location of a log file
    Syntax:TransferLog file|pipe
    Context:server config, virtual host
    Status:Base
    Module:mod_log_config
    -

    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 - 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 -

    - -
    -
    top

    Custom Log Formats

    @@ -498,6 +298,206 @@ if the directory where logfiles are stored is writable by anyone other than the user that starts the server.

    +
    top
    +

    BufferedLogs Directive

    + + + + + + + + +
    Description:Buffer log entries in memory before writing to disk
    Syntax:BufferedLogs On|Off
    Default:BufferedLogs Off
    Context:server config
    Status:Base
    Module:mod_log_config
    Compatibility:Available in versions 2.0.41 and later.
    +

    The BufferedLogs directive causes + mod_log_config to store several log entries in + memory and write them together to disk, rather than writing them + after each request. On some systems, this may result in more + efficient disk access and hence higher performance. It may be + set only once for the entire server; it cannot be configured + per virtual-host.

    + +
    This directive is experimental and should be used with + caution.
    + +
    +
    top
    +

    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:This directive is deprecated.
    +

    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.

    + +
    +
    top
    +

    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
    +

    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 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. See the notes on piped logs + for more information. + +

    Security:

    +

    If a program is used, then it will be run as the user who + started httpd. This will be root if the server was + started by root; be sure that the program is secure.

    +
    +

    Note

    +

    When entering a file path on non-Unix platforms, care should be taken + to make sure that only forward slashed are used even though the platform + may allow the use of back slashes. In general it is a good idea to always + use forward slashes throughout the configuration files.

    +
    +
    + +

    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 controls whether or + not to log a particular request 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 want to record requests for all GIF + images on your server in a separate logfile but not in 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 +

    + +

    Or, to reproduce the behavior of the old RefererIgnore + directive, you might use the following:

    + +

    + SetEnvIf Referer example\.com localreferer
    + CustomLog referer.log referer env=!localreferer +

    + +
    +
    top
    +

    LogFormat Directive

    + + + + + + + +
    Description:Describes a format for use in a log file
    Syntax:LogFormat format|nickname +[nickname]
    Default:LogFormat "%h %l %u %t \"%r\" %>s %b"
    Context:server config, virtual host
    Status:Base
    Module:mod_log_config
    +

    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 the 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 that 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. + In addition, LogFormat cannot use one nickname + to define another nickname. Note that the nickname should not contain + percent signs (%).

    + +

    Example

    + LogFormat "%v %h %l %u %t \"%r\" %>s %b" vhost_common +

    + +
    +
    top
    +

    TransferLog Directive

    + + + + + + +
    Description:Specify location of a log file
    Syntax:TransferLog file|pipe
    Context:server config, virtual host
    Status:Base
    Module:mod_log_config
    +

    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 + 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 +

    + +

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_log_forensic.html.en b/docs/manual/mod/mod_log_forensic.html.en index 65510225f29..f7050915fb3 100644 --- a/docs/manual/mod/mod_log_forensic.html.en +++ b/docs/manual/mod/mod_log_forensic.html.en @@ -54,66 +54,20 @@ version 2.1 distribution's support directory, may be helpful in evaluating the forensic log output.

    -

    Directives

    - -

    Topics

    +
    top
    -

    ForensicLog Directive

    - - - - - - -
    Description:Sets filename of the forensic log
    Syntax:ForensicLog filename|pipe
    Context:server config, virtual host
    Status:Extension
    Module:mod_log_forensic
    -

    The ForensicLog directive is used to - log requests to the server for forensic analysis. Each log entry - is assigned a unique ID which can be associated with the request - using the normal CustomLog - directive. mod_log_forensic creates a token called - forensic-id, which can be added to the transfer log - using the %{forensic-id}n format string.

    - -

    The argument, which specifies the location to which - the logs will be written, can take one of the following two - types of values:

    - -
    -
    filename
    -
    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. The program name can be specified relative to the ServerRoot directive. - -

    Security:

    -

    If a program is used, then it will be run as the user who - started httpd. This will be root if the server was - started by root; be sure that the program is secure or switches to a - less privileged user.

    -
    - -

    Note

    -

    When entering a file path on non-Unix platforms, care should be taken - to make sure that only forward slashes are used even though the platform - may allow the use of back slashes. In general it is a good idea to always - use forward slashes throughout the configuration files.

    -
    -
    - -
    -
    top

    Forensic Log Format

    Each request is logged two times. The first time is before it's @@ -160,6 +114,52 @@ version 2.1 they should not be readable by anyone except the user that starts the server.

    +
    top
    +

    ForensicLog Directive

    + + + + + + +
    Description:Sets filename of the forensic log
    Syntax:ForensicLog filename|pipe
    Context:server config, virtual host
    Status:Extension
    Module:mod_log_forensic
    +

    The ForensicLog directive is used to + log requests to the server for forensic analysis. Each log entry + is assigned a unique ID which can be associated with the request + using the normal CustomLog + directive. mod_log_forensic creates a token called + forensic-id, which can be added to the transfer log + using the %{forensic-id}n format string.

    + +

    The argument, which specifies the location to which + the logs will be written, can take one of the following two + types of values:

    + +
    +
    filename
    +
    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. The program name can be specified relative to the ServerRoot directive. + +

    Security:

    +

    If a program is used, then it will be run as the user who + started httpd. This will be root if the server was + started by root; be sure that the program is secure or switches to a + less privileged user.

    +
    + +

    Note

    +

    When entering a file path on non-Unix platforms, care should be taken + to make sure that only forward slashes are used even though the platform + may allow the use of back slashes. In general it is a good idea to always + use forward slashes throughout the configuration files.

    +
    +
    + +

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_logio.html.en b/docs/manual/mod/mod_logio.html.en index cbab190f967..c10983a3ada 100644 --- a/docs/manual/mod/mod_logio.html.en +++ b/docs/manual/mod/mod_logio.html.en @@ -51,13 +51,13 @@ with the request that triggered the renegotiation.

    -

    Directives

    -

    This module provides no - directives.

    -

    Topics

    +

    Topics

    See also

    +

    Directives

    +

    This module provides no + directives.

    +

    See also

    • mod_log_config
    • Apache Log Files
      • diff --git a/docs/manual/mod/mod_mem_cache.html.en b/docs/manual/mod/mod_mem_cache.html.en index 33ca00445f1..c2c901b1438 100644 --- a/docs/manual/mod/mod_mem_cache.html.en +++ b/docs/manual/mod/mod_mem_cache.html.en @@ -65,6 +65,7 @@
    • mod_cache
    • mod_disk_cache
    +
    top

    MCacheMaxObjectCount Directive

    @@ -235,7 +236,6 @@ KBytes -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_mime.html.en b/docs/manual/mod/mod_mime.html.en index 68b3edcad9a..590a5fd0d5a 100644 --- a/docs/manual/mod/mod_mime.html.en +++ b/docs/manual/mod/mod_mime.html.en @@ -75,7 +75,12 @@ their last modified date) to ensure that all visitors are receive the corrected content headers.

    -

    Directives

    +
    top
    +
    +

    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 that maps onto + the same type of meta-information, then the one to the right will + be used, except for languages and content encodings. 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.

    + +

    Languages and content encodings are treated accumulative, because one can assign + more than one language or encoding to a particular resource. For example, + the file welcome.html.en.de will be delivered with + Content-Language: en, de and Content-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 handled by the module associated + with the handler. For example, if the .imap + extension is mapped to the handler imap-file (from + mod_imagemap) 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_imagemap imagemap + file.

    + +

    If you would prefer only the last dot-separated part of the + filename to be mapped to a particular piece of meta-data, then do + not use the Add* directives. For example, if you wish + to have the file foo.html.cgi processed as a CGI + script, but not the file bar.cgi.html, then instead + of using AddHandler cgi-script .cgi, use

    + +

    Configure handler based on final extension only

    + <FilesMatch \.cgi$> + + SetHandler cgi-script + + </FilesMatch> +

    + +
    top
    +
    +

    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 HTTP/1.1 + RFC, section 14.11 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 codings have been applied to the entity-body, and thus what + decoding mechanisms must be applied in order to obtain the media-type + referenced by the Content-Type header field. 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.zip would be known to be a pkzip'ed Word + document.

    + +

    Apache sends a Content-encoding header with the + resource, in order to tell the client browser about the + encoding method.

    + +

    Content-encoding: pkzip

    +
    top
    +
    +

    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-1 +

    + +

    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.

    + +
    +
    top

    AddCharset Directive

    - -
    top
    -
    -

    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 that maps onto - the same type of meta-information, then the one to the right will - be used, except for languages and content encodings. 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.

    - -

    Languages and content encodings are treated accumulative, because one can assign - more than one language or encoding to a particular resource. For example, - the file welcome.html.en.de will be delivered with - Content-Language: en, de and Content-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 handled by the module associated - with the handler. For example, if the .imap - extension is mapped to the handler imap-file (from - mod_imagemap) 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_imagemap imagemap - file.

    - -

    If you would prefer only the last dot-separated part of the - filename to be mapped to a particular piece of meta-data, then do - not use the Add* directives. For example, if you wish - to have the file foo.html.cgi processed as a CGI - script, but not the file bar.cgi.html, then instead - of using AddHandler cgi-script .cgi, use

    - -

    Configure handler based on final extension only

    - <FilesMatch \.cgi$> - - SetHandler cgi-script - - </FilesMatch> -

    - -
    top
    -
    -

    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 HTTP/1.1 - RFC, section 14.11 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 codings have been applied to the entity-body, and thus what - decoding mechanisms must be applied in order to obtain the media-type - referenced by the Content-Type header field. 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.zip would be known to be a pkzip'ed Word - document.

    - -

    Apache sends a Content-encoding header with the - resource, in order to tell the client browser about the - encoding method.

    - -

    Content-encoding: pkzip

    -
    top
    -
    -

    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-1 -

    - -

    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.

    -
    diff --git a/docs/manual/mod/mod_mime_magic.html.en b/docs/manual/mod/mod_mime_magic.html.en index bc977cb0b90..2802129fdbf 100644 --- a/docs/manual/mod/mod_mime_magic.html.en +++ b/docs/manual/mod/mod_mime_magic.html.en @@ -45,39 +45,16 @@ what the contents are. This module is active only if the magic file is specified by the MimeMagicFile directive.

    -
    Description:Maps the given filename extensions to the specified content @@ -841,140 +975,6 @@ extensions
    - - - - - -
    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.

    - -

    Example

    - MimeMagicFile conf/magic -

    - -
    +

    Directives

    + +
    top

    Format of the Magic File

    @@ -269,6 +246,29 @@ using the specified magic file
    +
    top
    +

    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.

    + +

    Example

    + MimeMagicFile conf/magic +

    + +

    Available Languages:  en 

    diff --git a/docs/manual/mod/mod_negotiation.html.en b/docs/manual/mod/mod_negotiation.html.en index 74de3199859..4447f4e08c1 100644 --- a/docs/manual/mod/mod_negotiation.html.en +++ b/docs/manual/mod/mod_negotiation.html.en @@ -49,17 +49,17 @@ results.
    -

    Directives

    +

    Topics

    +

    Directives

    -

    Topics

    -

    See also

    +

    See also

    top
    +
    +

    Type maps

    +

    A type map has a format similar to 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(s) of the variant, as an Internet standard + language tag (RFC 1766). An example is en, + meaning English. If the variant contains more than one + language, they are separated by a comma.
    + +
    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[.000] + to 1[.000], 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:
    +
    uri of the file containing the variant (of the given + media type, encoded with the given content encoding). These + are interpreted as URLs relative to the map file; they must + be on the same server (!), and they must refer to files to + which the client would be granted access if they were to be + requested directly.
    + +
    Body:
    +
    New in Apache 2.0, the actual content of the resource may + be included in the type-map file using the Body header. This + header must contain a string that designates a delimiter for + the body content. Then all following lines in the type map + file will be considered part of the resource body until the + delimiter string is found. + +

    Example:

    + Body:----xyz----
    + <html>
    + <body>
    + <p>Content of the page.</p>
    + </body>
    + </html>
    + ----xyz---- +

    +
    +
    +
    top
    +
    +

    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.

    + +

    The MultiViewsMatch + directive configures whether Apache will consider files + that do not have content negotiation meta-information assigned + to them when choosing files.

    +
    +
    top

    CacheNegotiatedDocs Directive

  • AddLanguage
    • -
    top
    -
    -

    Type maps

    -

    A type map has a format similar to 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(s) of the variant, as an Internet standard - language tag (RFC 1766). An example is en, - meaning English. If the variant contains more than one - language, they are separated by a comma.
    - -
    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[.000] - to 1[.000], 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:
    -
    uri of the file containing the variant (of the given - media type, encoded with the given content encoding). These - are interpreted as URLs relative to the map file; they must - be on the same server (!), and they must refer to files to - which the client would be granted access if they were to be - requested directly.
    - -
    Body:
    -
    New in Apache 2.0, the actual content of the resource may - be included in the type-map file using the Body header. This - header must contain a string that designates a delimiter for - the body content. Then all following lines in the type map - file will be considered part of the resource body until the - delimiter string is found. - -

    Example:

    - Body:----xyz----
    - <html>
    - <body>
    - <p>Content of the page.</p>
    - </body>
    - </html>
    - ----xyz---- -

    -
    -
    -
    top
    -
    -

    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.

    - -

    The MultiViewsMatch - directive configures whether Apache will consider files - that do not have content negotiation meta-information assigned - to them when choosing files.

    -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_nw_ssl.html.en b/docs/manual/mod/mod_nw_ssl.html.en index 1e611881a51..39097f9ac06 100644 --- a/docs/manual/mod/mod_nw_ssl.html.en +++ b/docs/manual/mod/mod_nw_ssl.html.en @@ -44,6 +44,7 @@

  • SecureListen
    • +
    top

    NWSSLTrustedCerts Directive

    Description:Allows content-negotiated documents to be @@ -188,118 +300,6 @@ the client does not express a preference
    @@ -90,7 +91,6 @@ parameter also enables mutual authentication.

    -

    Available Languages:  en 

    diff --git a/docs/manual/mod/mod_proxy.html.en b/docs/manual/mod/mod_proxy.html.en index 7c3c26f7e74..ebca4041a17 100644 --- a/docs/manual/mod/mod_proxy.html.en +++ b/docs/manual/mod/mod_proxy.html.en @@ -64,7 +64,19 @@ mod_ssl. These additional modules will need to be loaded and configured to take advantage of these features.

    -
    - - - - - - -
    Description:Ports that are allowed to CONNECT through the -proxy
    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.

    +
    +

    Forward Proxies and Reverse + Proxies/Gateways

    +

    Apache can be configured in both a forward and + reverse proxy (also known as gateway) mode.

    -

    By default, only the default https port (443) and the - default snews port (563) are enabled. Use the - AllowCONNECT directive to override this default and - allow connections to the listed ports only.

    +

    An ordinary forward proxy is an intermediate + server that sits between the client and the origin + server. In order to get content from the origin server, + the client sends a request to the proxy naming the origin server + as the target and the proxy then requests the content from the + origin server and returns it to the client. The client must be + specially configured to use the forward proxy to access other + sites.

    -

    Note that you'll need to have mod_proxy_connect present - in the server in order to get the support for the CONNECT at - all.

    +

    A typical usage of a forward proxy is to provide Internet + access to internal clients that are otherwise restricted by a + firewall. The forward proxy can also use caching (as provided + by mod_cache) to reduce network usage.

    -
    -
    top
    -

    BalancerMember Directive

    - - - - - - - -
    Description:Add a member to a load balancing group
    Syntax:BalancerMember [balancerurl] url [key=value [key=value ...]]
    Context:directory
    Status:Extension
    Module:mod_proxy
    Compatibility:BalancerMember is only available in Apache 2.2 - and later.
    -

    This directive adds a member to a load balancing group. It could be used - within a <Proxy balancer://...> container - directive, and can take any of the key value pairs available to - ProxyPass directives.

    -

    The balancerurl is only needed when not in <Proxy balancer://...> - container directive. It corresponds to the url of a balancer defined in - ProxyPass directive.

    +

    The forward proxy is activated using the ProxyRequests directive. Because + forward proxies allow clients to access arbitrary sites through + your server and to hide their true origin, it is essential that + you secure your server so that only + authorized clients can access the proxy before activating a + forward proxy.

    -
    -
    top
    -

    NoProxy Directive

    - - - - - - -
    Description:Hosts, domains, or networks that will be connected to -directly
    Syntax:NoProxy host [host] ...
    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).

    +

    A reverse proxy (or gateway), by + contrast, appears to the client just like an ordinary web + server. No special configuration on the client is necessary. + The client makes ordinary requests for content in the name-space + of the reverse proxy. The reverse proxy then decides where to + send those requests, and returns the content as if it was itself + the origin.

    -

    Example

    - ProxyRemote * http://firewall.example.com:81
    - NoProxy .example.com 192.168.112.0/21 -

    +

    A typical usage of a reverse proxy is to provide Internet + users access to a server that is behind a firewall. Reverse + proxies can also be used to balance load among several back-end + servers, or to provide caching for a slower back-end server. + In addition, reverse proxies can be used simply to bring + several servers into the same URL space.

    -

    The host arguments to the NoProxy - directive are one of the following type list:

    +

    A reverse proxy is activated using the ProxyPass directive or the + [P] flag to the RewriteRule directive. It is + not necessary to turn ProxyRequests on in order to + configure a reverse proxy.

    +
    top
    +
    +

    Basic Examples

    -
    - -
    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).

    +

    The examples below are only a very basic idea to help you + get started. Please read the documentation on the individual + directives.

    -

    Examples

    - .com .apache.org. +

    In addition, if you wish to have caching enabled, consult + the documentation from mod_cache.

    + +

    Reverse Proxy

    + ProxyPass /foo http://foo.example.com/bar
    + ProxyPassReverse /foo http://foo.example.com/bar

    -

    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 .ExAmple.com and - .example.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.

    -
    +

    Forward Proxy

    + ProxyRequests On
    + ProxyVia On
    +
    + <Proxy *>
    + + Order deny,allow
    + Deny from all
    + Allow from internal.example.com
    +     + </Proxy> +

    - -
    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:

    +
    top
    +
    +

    Workers

    +

    The proxy manages the configuration of origin servers and their + communication parameters in objects called workers. + There are two built-in workers, the default forward proxy worker and the + default reverse proxy worker. Additional workers can be configured + explicitly.

    -
    -
    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)
    -
    +

    The two default workers have a fixed configuration + and will be used if no other worker matches the request. + They do not use HTTP Keep-Alive or connection pooling. + The TCP connections to the origin server will instead be + opened and closed for each request.

    -

    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.

    +

    Explicitly configured workers are identified by their URL. + They are usually created and configured using + ProxyPass or + ProxyPassMatch when used + for a reverse proxy:

    - -
    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.

    -
    +

    + ProxyPass /example http://backend.example.com connectiontimeout=5 timeout=30 +

    - -
    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 IPAddrs).

    +

    This will create a worker associated with the origin server URL + http://backend.example.com and using the given timeout + values. When used in a forward proxy, workers are usually defined + via the ProxySet directive:

    -

    Examples

    - prep.ai.example.com
    - www.apache.org -

    +

    + ProxySet http://backend.example.com connectiontimeout=5 timeout=30 +

    -

    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.

    -

    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.ExAmple.com - and www.example.com. (note the trailing period) are - considered equal.

    -
    - - -

    See also

    - -
    -
    top
    -

    <Proxy> Directive

    - - - - - - -
    Description:Container for directives applied to proxied resources
    Syntax:<Proxy wildcard-url> ...</Proxy>
    Context:server config, virtual host
    Status:Extension
    Module:mod_proxy
    -

    Directives placed in <Proxy> - sections apply only to matching proxied content. Shell-style wildcards are - allowed.

    +

    or alternatively using Proxy + and ProxySet:

    -

    For example, the following will allow only hosts in - yournetwork.example.com to access content via your proxy - server:

    +

    + <Proxy http://backend.example.com>
    + + ProxySet connectiontimeout=5 timeout=30 + + </Proxy> +

    -

    - <Proxy *>
    - - Order Deny,Allow
    - Deny from all
    - Allow from yournetwork.example.com
    -     - </Proxy> -

    +

    Using explicitly configured workers in the forward mode is + not very common, because forward proxies usually communicate with many + different origin servers. Creating explicit workers for some of the + origin servers can still be useful, if they are used very often. + Explicitly configured workers have no concept of forward or reverse + proxying by themselves. They encapsulate a common concept of + communication with origin servers. A worker created by + ProxyPass for use in a + reverse proxy will be also used for forward proxy requests whenever + the URL to the origin server matches the worker URL and vice versa.

    -

    The following example will process all files in the foo - directory of example.com through the INCLUDES - filter when they are sent through the proxy server:

    +

    The URL identifying a direct worker is the URL of its + origin server including any path components given:

    -

    - <Proxy http://example.com/foo/*>
    - - SetOutputFilter INCLUDES
    -     - </Proxy> -

    +

    + ProxyPass /examples http://backend.example.com/examples
    + ProxyPass /docs http://backend.example.com/docs +

    -

    Differences from the Location configuration section

    -

    A backend URL matches the configuration section if it begins with the - the wildcard-url string, even if the last path segment in the - directive only matches a prefix of the backend URL. For example, - <Proxy http://example.com/foo> matches all of - http://example.com/foo, http://example.com/foo/bar, and - http://example.com/foobar. The matching of the final URL differs - from the behavior of the <Location> section, which for purposes of this note - treats the final path component as if it ended in a slash.

    -

    For more control over the matching, see <ProxyMatch>.

    -
    +

    This example defines two different workers, each using a separate + connection pool and configuration.

    +

    Worker Sharing

    +

    Worker sharing happens if the worker URLs overlap, which occurs when + the URL of some worker is a leading substring of the URL of another + worker defined later in the configuration file. In the following example

    -

    See also

    - -
    -
    top
    -

    ProxyBadHeader Directive

    - - - - - - - - -
    Description:Determines how to handle bad header lines in a -response
    Syntax:ProxyBadHeader IsError|Ignore|StartBody
    Default:ProxyBadHeader IsError
    Context:server config, virtual host
    Status:Extension
    Module:mod_proxy
    Compatibility:Available in Apache 2.0.44 and later
    -

    The ProxyBadHeader directive determines the - behaviour of mod_proxy if it receives syntactically invalid - response header lines (i.e. containing no colon) from the origin - server. The following arguments are possible:

    +

    + ProxyPass /apps http://backend.example.com/ timeout=60
    + ProxyPass /examples http://backend.example.com/examples timeout=10 +

    -
    -
    IsError
    -
    Abort the request and end up with a 502 (Bad Gateway) response. This is - the default behaviour.
    +

    the second worker isn't actually created. Instead the first + worker is used. The benefit is, that there is only one connection pool, + so connections are more often reused. Note that all configuration attributes + given explicitly for the later worker and some configuration defaults will + overwrite the configuration given for the first worker. This will be logged + as a warning. In the above example the resulting timeout value + for the URL /apps will be 10 instead + of 60!

    -
    Ignore
    -
    Treat bad header lines as if they weren't sent.
    +

    If you want to avoid worker sharing, sort your worker definitions + by URL length, starting with the longest worker URLs. If you want to maximize + worker sharing use the reverse sort order. See also the related warning about + ordering ProxyPass directives.

    -
    StartBody
    -
    When receiving the first bad header line, finish reading the headers and - treat the remainder as body. This helps to work around buggy backend servers - which forget to insert an empty line between the headers and the body.
    -
    +
    -
    -
    top
    -

    ProxyBlock Directive

    - - - - - - -
    Description:Words, hosts, or domains that are banned from being -proxied
    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. That may slow down the startup time of the server.

    +

    Explicitly configured workers come in two flavors: + direct workers and (load) balancer workers. + They support many important configuration attributes which are + described below in the ProxyPass + directive. The same attributes can also be set using + ProxySet.

    -

    Example

    - ProxyBlock joes-garage.com some-host.co.uk rocky.wotsamattau.edu -

    +

    The set of options available for a direct worker + depends on the protocol, which is specified in the origin server URL. + Available protocols include ajp, + ftp, http and scgi.

    -

    rocky.wotsamattau.edu would also be matched if referenced by - IP address.

    +

    Balancer workers are virtual workers that use direct workers known + as their members to actually handle the requests. Each balancer can + have multiple members. When it handles a request, it chooses a member + based on the configured load balancing algorithm.

    -

    Note that wotsamattau would also be sufficient to match - wotsamattau.edu.

    +

    A balancer worker is created if its worker URL uses + balancer as the protocol scheme. + The balancer URL uniquely identifies the balancer worker. + Members are added to a balancer using + BalancerMember.

    -

    Note also that

    +
    top
    +
    +

    Controlling access to your proxy

    +

    You can control who can access your proxy via the <Proxy> control block as in + the following example:

    -

    - ProxyBlock * -

    +

    + <Proxy *>
    + + Order Deny,Allow
    + Deny from all
    + Allow from 192.168.0
    +     + </Proxy> +

    -

    blocks connections to all sites.

    +

    For more information on access control directives, see + mod_authz_host.

    -
    -
    top
    -

    ProxyDomain Directive

    - - - - - - -
    Description:Default domain name for proxied requests
    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.

    +

    Strictly limiting access is essential if you are using a + forward proxy (using the ProxyRequests directive). + Otherwise, your server can be used by any client to access + arbitrary hosts while hiding his or her true identity. This is + dangerous both for your network and for the Internet at large. + When using a reverse proxy (using the ProxyPass directive with + ProxyRequests Off), access control is less + critical because clients can only contact the hosts that you + have specifically configured.

    -

    Example

    - ProxyRemote * http://firewall.example.com:81
    - NoProxy .example.com 192.168.112.0/21
    - ProxyDomain .example.com -

    +
    top
    +
    +

    Slow Startup

    +

    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.

    +
    top
    +
    +

    Intranet Proxy

    +

    An Apache proxy server situated in an intranet needs to forward + external requests through the company's firewall (for this, configure + the ProxyRemote directive + to forward the respective scheme to the firewall proxy). + 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.

    -
    -
    top
    -

    ProxyErrorOverride Directive

    - - - - - - - - -
    Description:Override error pages for proxied content
    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).

    +

    Users within an intranet tend to omit the local domain name from their + WWW requests, thus requesting "http://somehost/" instead of + http://somehost.example.com/. 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.

    +
    top
    +
    +

    Protocol Adjustments

    +

    For circumstances where mod_proxy is sending + requests to an origin server that doesn't properly implement + keepalives or HTTP/1.1, there are two environment variables that can force the + request to use HTTP/1.0 with no keepalive. These are set via the + SetEnv directive.

    -

    This directive does not affect the processing of informational (1xx), - normal success (2xx), or redirect (3xx) responses.

    +

    These are the force-proxy-request-1.0 and + proxy-nokeepalive notes.

    -
    -
    top
    -

    ProxyFtpDirCharset Directive

    - - - - - - - - -
    Description:Define the character set for proxied FTP listings
    Syntax:ProxyFtpDirCharset character set
    Default:ProxyFtpDirCharset ISO-8859-1
    Context:server config, virtual host, directory
    Status:Extension
    Module:mod_proxy
    Compatibility:Available in Apache 2.2.7 and later
    -

    The ProxyFtpDirCharset directive defines the - character set to be set for FTP directory listings in HTML generated by - mod_proxy_ftp.

    +

    + <Location /buggyappserver/>
    + + ProxyPass http://buggyappserver:7001/foo/
    + SetEnv force-proxy-request-1.0 1
    + SetEnv proxy-nokeepalive 1
    +     + </Location> +

    -
    +
    top
    +
    +

    Request Bodies

    + +

    Some request methods such as POST include a request body. + The HTTP protocol requires that requests which include a body + either use chunked transfer encoding or send a + Content-Length request header. When passing these + requests on to the origin server, mod_proxy_http + will always attempt to send the Content-Length. But + if the body is large and the original request used chunked + encoding, then chunked encoding may also be used in the upstream + request. You can control this selection using environment variables. Setting + proxy-sendcl ensures maximum compatibility with + upstream servers by always sending the + Content-Length, while setting + proxy-sendchunked minimizes resource usage by using + chunked encoding.

    + +
    top
    +
    +

    Reverse Proxy Request Headers

    + +

    When acting in a reverse-proxy mode (using the ProxyPass directive, for example), + mod_proxy_http adds several request headers in + order to pass information to the origin server. These headers + are:

    + +
    +
    X-Forwarded-For
    +
    The IP address of the client.
    +
    X-Forwarded-Host
    +
    The original host requested by the client in the Host + HTTP request header.
    +
    X-Forwarded-Server
    +
    The hostname of the proxy server.
    +
    + +

    Be careful when using these headers on the origin server, since + they will contain more than one (comma-separated) value if the + original request already contained one of these headers. For + example, you can use %{X-Forwarded-For}i in the log + format string of the origin server to log the original clients IP + address, but you may get more than one address if the request + passes through several proxies.

    + +

    See also the ProxyPreserveHost and ProxyVia directives, which control + other request headers.

    + +
    top
    -

    ProxyIOBufferSize Directive

    +

    AllowCONNECT Directive

    - - - + + +
    Description:Determine size of internal data throughput buffer
    Syntax:ProxyIOBufferSize bytes
    Default:ProxyIOBufferSize 8192
    Description:Ports that are allowed to CONNECT through the +proxy
    Syntax:AllowCONNECT port [port] ...
    Default:AllowCONNECT 443 563
    Context:server config, virtual host
    Status:Extension
    Module:mod_proxy
    -

    The ProxyIOBufferSize directive adjusts the size - of the internal buffer, which is used as a scratchpad for the data between - input and output. The size must be at least 8192.

    +

    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.

    -

    When the mod_proxy_ajp module is used, this value is - aligned to a 1024 byte boundary, and values larger than 65536 are set to - 65536 in accordance with the AJP protocol.

    +

    By default, only the default https port (443) and the + default snews port (563) are enabled. Use the + AllowCONNECT directive to override this default and + allow connections to the listed ports only.

    -

    In almost every case there's no reason to change that value.

    +

    Note that you'll need to have mod_proxy_connect present + in the server in order to get the support for the CONNECT at + all.

    top
    -

    <ProxyMatch> Directive

    +

    BalancerMember Directive

    - - - + + + +
    Description:Container for directives applied to regular-expression-matched -proxied resources
    Syntax:<ProxyMatch regex> ...</ProxyMatch>
    Context:server config, virtual host
    Description:Add a member to a load balancing group
    Syntax:BalancerMember [balancerurl] url [key=value [key=value ...]]
    Context:directory
    Status:Extension
    Module:mod_proxy
    Compatibility:BalancerMember is only available in Apache 2.2 + and later.
    -

    The <ProxyMatch> directive is - identical to the <Proxy> directive, except it matches URLs - using regular expressions.

    +

    This directive adds a member to a load balancing group. It could be used + within a <Proxy balancer://...> container + directive, and can take any of the key value pairs available to + ProxyPass directives.

    +

    The balancerurl is only needed when not in <Proxy balancer://...> + container directive. It corresponds to the url of a balancer defined in + ProxyPass directive.

    -

    See also

    -
    top
    -

    ProxyMaxForwards Directive

    +

    NoProxy Directive

    - - - + + -
    Description:Maximium number of proxies that a request can be forwarded -through
    Syntax:ProxyMaxForwards number
    Default:ProxyMaxForwards -1
    Description:Hosts, domains, or networks that will be connected to +directly
    Syntax:NoProxy host [host] ...
    Context:server config, virtual host
    Status:Extension
    Module:mod_proxy
    Compatibility:Available in Apache 2.0 and later; - default behaviour changed in 2.2.7
    -

    The ProxyMaxForwards directive specifies the - maximum number of proxies through which a request may pass, if there's no - Max-Forwards header supplied with the request. This may - be set to prevent infinite proxy loops, or a DoS attack.

    +

    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

    - ProxyMaxForwards 15 + ProxyRemote * http://firewall.example.com:81
    + NoProxy .example.com 192.168.112.0/21

    -

    Note that setting ProxyMaxForwards is a - violation of the HTTP/1.1 protocol (RFC2616), which forbids a Proxy - setting Max-Forwards if the Client didn't set it. - Earlier Apache versions would always set it. A negative - ProxyMaxForwards value, including the - default -1, gives you protocol-compliant behaviour, but may - leave you open to loops.

    - -
    -
    top
    -

    ProxyPass Directive

    - - - - - - -
    Description:Maps remote servers into the local server URL-space
    Syntax:ProxyPass [path] !|url [key=value -[key=value ...]] [nocanon] [interpolate]
    Context:server config, virtual host, directory
    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. The local server is often called a reverse - proxy or gateway. The path is the name of - a local virtual path; url is a partial URL for the - remote server and cannot include a query string.

    - -
    The ProxyRequests directive should - usually be set off when using - ProxyPass.
    +

    The host arguments to the NoProxy + directive are one of the following type list:

    -

    Suppose the local server has address http://example.com/; - then

    +
    + +
    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).

    -

    - ProxyPass /mirror/foo/ http://backend.example.com/ +

    Examples

    + .com .apache.org.

    -

    will cause a local request for - http://example.com/mirror/foo/bar to be internally converted - into a proxy request to http://backend.example.com/bar.

    - -
    -

    If the first argument ends with a trailing /, the second - argument should also end with a trailing / and vice - versa. Otherwise the resulting requests to the backend may miss some - needed slashes and do not deliver the expected results. -

    -
    +

    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 .ExAmple.com and + .example.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.

    +
    -

    The ! directive is useful in situations where you don't want + +

    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 IPAddrs).

    + +

    Examples

    + prep.ai.example.com
    + 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.

    +

    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.ExAmple.com + and www.example.com. (note the trailing period) are + considered equal.

    +
    +
    + +

    See also

    + +
    +
    top
    +

    <Proxy> Directive

    + + + + + + +
    Description:Container for directives applied to proxied resources
    Syntax:<Proxy wildcard-url> ...</Proxy>
    Context:server config, virtual host
    Status:Extension
    Module:mod_proxy
    +

    Directives placed in <Proxy> + sections apply only to matching proxied content. Shell-style wildcards are + allowed.

    + +

    For example, the following will allow only hosts in + yournetwork.example.com to access content via your proxy + server:

    + +

    + <Proxy *>
    + + Order Deny,Allow
    + Deny from all
    + Allow from yournetwork.example.com
    +     + </Proxy> +

    + +

    The following example will process all files in the foo + directory of example.com through the INCLUDES + filter when they are sent through the proxy server:

    + +

    + <Proxy http://example.com/foo/*>
    + + SetOutputFilter INCLUDES
    +     + </Proxy> +

    + +

    Differences from the Location configuration section

    +

    A backend URL matches the configuration section if it begins with the + the wildcard-url string, even if the last path segment in the + directive only matches a prefix of the backend URL. For example, + <Proxy http://example.com/foo> matches all of + http://example.com/foo, http://example.com/foo/bar, and + http://example.com/foobar. The matching of the final URL differs + from the behavior of the <Location> section, which for purposes of this note + treats the final path component as if it ended in a slash.

    +

    For more control over the matching, see <ProxyMatch>.

    +
    + + +

    See also

    + +
    +
    top
    +

    ProxyBadHeader Directive

    + + + + + + + + +
    Description:Determines how to handle bad header lines in a +response
    Syntax:ProxyBadHeader IsError|Ignore|StartBody
    Default:ProxyBadHeader IsError
    Context:server config, virtual host
    Status:Extension
    Module:mod_proxy
    Compatibility:Available in Apache 2.0.44 and later
    +

    The ProxyBadHeader directive determines the + behaviour of mod_proxy if it receives syntactically invalid + response header lines (i.e. containing no colon) from the origin + server. The following arguments are possible:

    + +
    +
    IsError
    +
    Abort the request and end up with a 502 (Bad Gateway) response. This is + the default behaviour.
    + +
    Ignore
    +
    Treat bad header lines as if they weren't sent.
    + +
    StartBody
    +
    When receiving the first bad header line, finish reading the headers and + treat the remainder as body. This helps to work around buggy backend servers + which forget to insert an empty line between the headers and the body.
    +
    + +
    +
    top
    +

    ProxyBlock Directive

    + + + + + + +
    Description:Words, hosts, or domains that are banned from being +proxied
    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. That may slow down the startup time of the server.

    + +

    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.

    + +
    +
    top
    +

    ProxyDomain Directive

    + + + + + + +
    Description:Default domain name for proxied requests
    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.example.com:81
    + NoProxy .example.com 192.168.112.0/21
    + ProxyDomain .example.com +

    + +
    +
    top
    +

    ProxyErrorOverride Directive

    + + + + + + + + +
    Description:Override error pages for proxied content
    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).

    + +

    This directive does not affect the processing of informational (1xx), + normal success (2xx), or redirect (3xx) responses.

    + +
    +
    top
    +

    ProxyFtpDirCharset Directive

    + + + + + + + + +
    Description:Define the character set for proxied FTP listings
    Syntax:ProxyFtpDirCharset character set
    Default:ProxyFtpDirCharset ISO-8859-1
    Context:server config, virtual host, directory
    Status:Extension
    Module:mod_proxy
    Compatibility:Available in Apache 2.2.7 and later
    +

    The ProxyFtpDirCharset directive defines the + character set to be set for FTP directory listings in HTML generated by + mod_proxy_ftp.

    + +
    +
    top
    +

    ProxyIOBufferSize Directive

    + + + + + + + +
    Description:Determine size of internal data throughput buffer
    Syntax:ProxyIOBufferSize bytes
    Default:ProxyIOBufferSize 8192
    Context:server config, virtual host
    Status:Extension
    Module:mod_proxy
    +

    The ProxyIOBufferSize directive adjusts the size + of the internal buffer, which is used as a scratchpad for the data between + input and output. The size must be at least 8192.

    + +

    When the mod_proxy_ajp module is used, this value is + aligned to a 1024 byte boundary, and values larger than 65536 are set to + 65536 in accordance with the AJP protocol.

    + +

    In almost every case there's no reason to change that value.

    + +
    +
    top
    +

    <ProxyMatch> Directive

    + + + + + + +
    Description:Container for directives applied to regular-expression-matched +proxied resources
    Syntax:<ProxyMatch regex> ...</ProxyMatch>
    Context:server config, virtual host
    Status:Extension
    Module:mod_proxy
    +

    The <ProxyMatch> directive is + identical to the <Proxy> directive, except it matches URLs + using regular expressions.

    + +

    See also

    + +
    +
    top
    +

    ProxyMaxForwards Directive

    + + + + + + + + +
    Description:Maximium number of proxies that a request can be forwarded +through
    Syntax:ProxyMaxForwards number
    Default:ProxyMaxForwards -1
    Context:server config, virtual host
    Status:Extension
    Module:mod_proxy
    Compatibility:Available in Apache 2.0 and later; + default behaviour changed in 2.2.7
    +

    The ProxyMaxForwards directive specifies the + maximum number of proxies through which a request may pass, if there's no + Max-Forwards header supplied with the request. This may + be set to prevent infinite proxy loops, or a DoS attack.

    + +

    Example

    + ProxyMaxForwards 15 +

    + +

    Note that setting ProxyMaxForwards is a + violation of the HTTP/1.1 protocol (RFC2616), which forbids a Proxy + setting Max-Forwards if the Client didn't set it. + Earlier Apache versions would always set it. A negative + ProxyMaxForwards value, including the + default -1, gives you protocol-compliant behaviour, but may + leave you open to loops.

    + +
    +
    top
    +

    ProxyPass Directive

    + + + + + + +
    Description:Maps remote servers into the local server URL-space
    Syntax:ProxyPass [path] !|url [key=value +[key=value ...]] [nocanon] [interpolate]
    Context:server config, virtual host, directory
    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. The local server is often called a reverse + proxy or gateway. The path is the name of + a local virtual path; url is a partial URL for the + remote server and cannot include a query string.

    + +
    The ProxyRequests directive should + usually be set off when using + ProxyPass.
    + +

    Suppose the local server has address http://example.com/; + then

    + +

    + ProxyPass /mirror/foo/ http://backend.example.com/ +

    + +

    will cause a local request for + http://example.com/mirror/foo/bar to be internally converted + into a proxy request to http://backend.example.com/bar.

    + +
    +

    If the first argument ends with a trailing /, the second + argument should also end with a trailing / and vice + versa. Otherwise the resulting requests to the backend may miss some + needed slashes and do not deliver the expected results. +

    +
    + +

    The ! directive is useful in situations where you don't want to reverse-proxy a subdirectory, e.g.

    @@ -1223,519 +1544,198 @@ connections are supported by this module. When using https, the requests are forwarded through the remote proxy using the HTTP CONNECT method.

    -

    Example

    - ProxyRemote http://goodguys.example.com/ http://mirrorguys.example.com:8000
    - ProxyRemote * http://cleverproxy.localdomain
    - ProxyRemote ftp http://ftpproxy.mydomain: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.

    - -
    -
    top
    -

    ProxyRemoteMatch Directive

    - - - - - - -
    Description:Remote proxy used to handle requests matched by regular -expressions
    Syntax:ProxyRemoteMatch regex remote-server
    Context:server config, virtual host
    Status:Extension
    Module:mod_proxy
    -

    The ProxyRemoteMatch is identical to the - ProxyRemote directive, except the - first argument is a regular expression - match against the requested URL.

    - -
    -
    top
    -

    ProxyRequests Directive

    - - - - - - - -
    Description:Enables forward (standard) proxy requests
    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 or gateway configuration, this - option should be set to - Off.

    - -

    In order to get the functionality of proxying HTTP or FTP sites, you - need also mod_proxy_http or mod_proxy_ftp - (or both) present in the server.

    - -

    In order to get the functionality of (forward) proxying HTTPS sites, you - need mod_proxy_connect enabled in the server.

    - -

    Warning

    -

    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.

    -
    - -

    See also

    - -
    -
    top
    -

    ProxySet Directive

    - - - - - - - -
    Description:Set various Proxy balancer or member parameters
    Syntax:ProxySet url key=value [key=value ...]
    Context:directory
    Status:Extension
    Module:mod_proxy
    Compatibility:ProxySet is only available in Apache 2.2 - and later.
    -

    This directive is used as an alternate method of setting any of the - parameters available to Proxy balancers and workers normally done via the - ProxyPass directive. If used - within a <Proxy balancer url|worker url> - container directive, the url argument is not required. As a side - effect the respective balancer or worker gets created. This can be useful - when doing reverse proxying via a - RewriteRule instead of a - ProxyPass directive.

    - -

    - <Proxy balancer://hotcluster>
    - - BalancerMember http://www2.example.com:8080 loadfactor=1
    - BalancerMember http://www3.example.com:8080 loadfactor=2
    - ProxySet lbmethod=bytraffic
    -     - </Proxy> -

    - -

    - <Proxy http://backend>
    - - ProxySet keepalive=On
    -     - </Proxy> -

    - -

    - ProxySet balancer://foo lbmethod=bytraffic timeout=15 -

    - -

    - ProxySet ajp://backend:7001 timeout=15 -

    - -

    Warning

    -

    Keep in mind that the same parameter key can have a different meaning - depending whether it is applied to a balancer or a worker as shown by the two - examples above regarding timeout.

    -
    - +

    Example

    + ProxyRemote http://goodguys.example.com/ http://mirrorguys.example.com:8000
    + ProxyRemote * http://cleverproxy.localdomain
    + ProxyRemote ftp http://ftpproxy.mydomain:8080 +

    -
    -
    top
    -

    ProxyStatus Directive

    - - - - - - - - -
    Description:Show Proxy LoadBalancer status in mod_status
    Syntax:ProxyStatus Off|On|Full
    Default:ProxyStatus Off
    Context:server config, virtual host
    Status:Extension
    Module:mod_proxy
    Compatibility:Available in version 2.2 and later
    -

    This directive determines whether or not proxy - loadbalancer status data is displayed via the mod_status - server-status page.

    -

    Note

    -

    Full is synonymous with On

    -
    +

    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.

    top
    -

    ProxyTimeout Directive

    +

    ProxyRemoteMatch Directive

    - - - + + -
    Description:Network timeout for proxied requests
    Syntax:ProxyTimeout seconds
    Default:Value of Timeout
    Description:Remote proxy used to handle requests matched by regular +expressions
    Syntax:ProxyRemoteMatch regex remote-server
    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 specify a timeout on proxy requests. - This is useful 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.

    +

    The ProxyRemoteMatch is identical to the + ProxyRemote directive, except the + first argument is a regular expression + match against the requested URL.

    top
    -

    ProxyVia Directive

    +

    ProxyRequests Directive

    - - - + + +
    Description:Information provided in the Via HTTP response -header for proxied requests
    Syntax:ProxyVia On|Off|Full|Block
    Default:ProxyVia Off
    Description:Enables forward (standard) proxy requests
    Syntax:ProxyRequests On|Off
    Default:ProxyRequests 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 - proxy requests along a chain of proxy servers. See RFC 2616 (HTTP/1.1), section - 14.45 for an explanation of Via: header lines.

    - -
      -
    • If set to Off, which is the default, no special processing - is performed. If a request or reply contains a Via: header, - it is passed through unchanged.
      • - -
    • If set to On, each request and reply will get a - Via: header line added for the current host.
      • - -
    • If set to Full, each generated Via: header - line will additionally have the Apache server version shown as a - Via: comment field.
      • - -
    • If set to Block, every proxy request will have all its - Via: header lines removed. No new Via: header will - be generated.
      • -
    - -
    -
    top
    -
    -

    Forward Proxies and Reverse - Proxies/Gateways

    -

    Apache can be configured in both a forward and - reverse proxy (also known as gateway) mode.

    - -

    An ordinary forward proxy is an intermediate - server that sits between the client and the origin - server. In order to get content from the origin server, - the client sends a request to the proxy naming the origin server - as the target and the proxy then requests the content from the - origin server and returns it to the client. The client must be - specially configured to use the forward proxy to access other - sites.

    - -

    A typical usage of a forward proxy is to provide Internet - access to internal clients that are otherwise restricted by a - firewall. The forward proxy can also use caching (as provided - by mod_cache) to reduce network usage.

    - -

    The forward proxy is activated using the ProxyRequests directive. Because - forward proxies allow clients to access arbitrary sites through - your server and to hide their true origin, it is essential that - you secure your server so that only - authorized clients can access the proxy before activating a - forward proxy.

    - -

    A reverse proxy (or gateway), by - contrast, appears to the client just like an ordinary web - server. No special configuration on the client is necessary. - The client makes ordinary requests for content in the name-space - of the reverse proxy. The reverse proxy then decides where to - send those requests, and returns the content as if it was itself - the origin.

    - -

    A typical usage of a reverse proxy is to provide Internet - users access to a server that is behind a firewall. Reverse - proxies can also be used to balance load among several back-end - servers, or to provide caching for a slower back-end server. - In addition, reverse proxies can be used simply to bring - several servers into the same URL space.

    - -

    A reverse proxy is activated using the ProxyPass directive or the - [P] flag to the RewriteRule directive. It is - not necessary to turn ProxyRequests on in order to - configure a reverse proxy.

    -
    top
    -
    -

    Basic Examples

    - -

    The examples below are only a very basic idea to help you - get started. Please read the documentation on the individual - directives.

    - -

    In addition, if you wish to have caching enabled, consult - the documentation from mod_cache.

    - -

    Reverse Proxy

    - ProxyPass /foo http://foo.example.com/bar
    - ProxyPassReverse /foo http://foo.example.com/bar -

    - -

    Forward Proxy

    - ProxyRequests On
    - ProxyVia On
    -
    - <Proxy *>
    - - Order deny,allow
    - Deny from all
    - Allow from internal.example.com
    -     - </Proxy> -

    - -
    top
    -
    -

    Workers

    -

    The proxy manages the configuration of origin servers and their - communication parameters in objects called workers. - There are two built-in workers, the default forward proxy worker and the - default reverse proxy worker. Additional workers can be configured - explicitly.

    - -

    The two default workers have a fixed configuration - and will be used if no other worker matches the request. - They do not use HTTP Keep-Alive or connection pooling. - The TCP connections to the origin server will instead be - opened and closed for each request.

    - -

    Explicitly configured workers are identified by their URL. - They are usually created and configured using - ProxyPass or - ProxyPassMatch when used - for a reverse proxy:

    - -

    - ProxyPass /example http://backend.example.com connectiontimeout=5 timeout=30 -

    - -

    This will create a worker associated with the origin server URL - http://backend.example.com and using the given timeout - values. When used in a forward proxy, workers are usually defined - via the ProxySet directive:

    - -

    - ProxySet http://backend.example.com connectiontimeout=5 timeout=30 -

    - -

    or alternatively using Proxy - and ProxySet:

    - -

    - <Proxy http://backend.example.com>
    - - ProxySet connectiontimeout=5 timeout=30 - - </Proxy> -

    - -

    Using explicitly configured workers in the forward mode is - not very common, because forward proxies usually communicate with many - different origin servers. Creating explicit workers for some of the - origin servers can still be useful, if they are used very often. - Explicitly configured workers have no concept of forward or reverse - proxying by themselves. They encapsulate a common concept of - communication with origin servers. A worker created by - ProxyPass for use in a - reverse proxy will be also used for forward proxy requests whenever - the URL to the origin server matches the worker URL and vice versa.

    - -

    The URL identifying a direct worker is the URL of its - origin server including any path components given:

    - -

    - ProxyPass /examples http://backend.example.com/examples
    - ProxyPass /docs http://backend.example.com/docs -

    - -

    This example defines two different workers, each using a separate - connection pool and configuration.

    - -

    Worker Sharing

    -

    Worker sharing happens if the worker URLs overlap, which occurs when - the URL of some worker is a leading substring of the URL of another - worker defined later in the configuration file. In the following example

    - -

    - ProxyPass /apps http://backend.example.com/ timeout=60
    - ProxyPass /examples http://backend.example.com/examples timeout=10 -

    - -

    the second worker isn't actually created. Instead the first - worker is used. The benefit is, that there is only one connection pool, - so connections are more often reused. Note that all configuration attributes - given explicitly for the later worker and some configuration defaults will - overwrite the configuration given for the first worker. This will be logged - as a warning. In the above example the resulting timeout value - for the URL /apps will be 10 instead - of 60!

    - -

    If you want to avoid worker sharing, sort your worker definitions - by URL length, starting with the longest worker URLs. If you want to maximize - worker sharing use the reverse sort order. See also the related warning about - ordering ProxyPass directives.

    - -
    - -

    Explicitly configured workers come in two flavors: - direct workers and (load) balancer workers. - They support many important configuration attributes which are - described below in the ProxyPass - directive. The same attributes can also be set using - ProxySet.

    +

    This allows or prevents Apache from functioning as a forward proxy + server. (Setting ProxyRequests to Off does not disable use of + the ProxyPass directive.)

    -

    The set of options available for a direct worker - depends on the protocol, which is specified in the origin server URL. - Available protocols include ajp, - ftp, http and scgi.

    +

    In a typical reverse proxy or gateway configuration, this + option should be set to + Off.

    -

    Balancer workers are virtual workers that use direct workers known - as their members to actually handle the requests. Each balancer can - have multiple members. When it handles a request, it chooses a member - based on the configured load balancing algorithm.

    +

    In order to get the functionality of proxying HTTP or FTP sites, you + need also mod_proxy_http or mod_proxy_ftp + (or both) present in the server.

    -

    A balancer worker is created if its worker URL uses - balancer as the protocol scheme. - The balancer URL uniquely identifies the balancer worker. - Members are added to a balancer using - BalancerMember.

    +

    In order to get the functionality of (forward) proxying HTTPS sites, you + need mod_proxy_connect enabled in the server.

    -
    top
    -
    -

    Controlling access to your proxy

    -

    You can control who can access your proxy via the <Proxy> control block as in - the following example:

    +

    Warning

    +

    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.

    +
    -

    - <Proxy *>
    - - Order Deny,Allow
    - Deny from all
    - Allow from 192.168.0
    -     - </Proxy> -

    +

    See also

    + +
    +
    top
    +

    ProxySet Directive

    + + + + + + + +
    Description:Set various Proxy balancer or member parameters
    Syntax:ProxySet url key=value [key=value ...]
    Context:directory
    Status:Extension
    Module:mod_proxy
    Compatibility:ProxySet is only available in Apache 2.2 + and later.
    +

    This directive is used as an alternate method of setting any of the + parameters available to Proxy balancers and workers normally done via the + ProxyPass directive. If used + within a <Proxy balancer url|worker url> + container directive, the url argument is not required. As a side + effect the respective balancer or worker gets created. This can be useful + when doing reverse proxying via a + RewriteRule instead of a + ProxyPass directive.

    -

    For more information on access control directives, see - mod_authz_host.

    +

    + <Proxy balancer://hotcluster>
    + + BalancerMember http://www2.example.com:8080 loadfactor=1
    + BalancerMember http://www3.example.com:8080 loadfactor=2
    + ProxySet lbmethod=bytraffic
    +     + </Proxy> +

    -

    Strictly limiting access is essential if you are using a - forward proxy (using the ProxyRequests directive). - Otherwise, your server can be used by any client to access - arbitrary hosts while hiding his or her true identity. This is - dangerous both for your network and for the Internet at large. - When using a reverse proxy (using the ProxyPass directive with - ProxyRequests Off), access control is less - critical because clients can only contact the hosts that you - have specifically configured.

    +

    + <Proxy http://backend>
    + + ProxySet keepalive=On
    +     + </Proxy> +

    -
    top
    -
    -

    Slow Startup

    -

    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.

    -
    top
    -
    -

    Intranet Proxy

    -

    An Apache proxy server situated in an intranet needs to forward - external requests through the company's firewall (for this, configure - the ProxyRemote directive - to forward the respective scheme to the firewall proxy). - 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.

    +

    + ProxySet balancer://foo lbmethod=bytraffic timeout=15 +

    -

    Users within an intranet tend to omit the local domain name from their - WWW requests, thus requesting "http://somehost/" instead of - http://somehost.example.com/. 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.

    -
    top
    -
    -

    Protocol Adjustments

    -

    For circumstances where mod_proxy is sending - requests to an origin server that doesn't properly implement - keepalives or HTTP/1.1, there are two environment variables that can force the - request to use HTTP/1.0 with no keepalive. These are set via the - SetEnv directive.

    +

    + ProxySet ajp://backend:7001 timeout=15 +

    -

    These are the force-proxy-request-1.0 and - proxy-nokeepalive notes.

    +

    Warning

    +

    Keep in mind that the same parameter key can have a different meaning + depending whether it is applied to a balancer or a worker as shown by the two + examples above regarding timeout.

    +
    -

    - <Location /buggyappserver/>
    - - ProxyPass http://buggyappserver:7001/foo/
    - SetEnv force-proxy-request-1.0 1
    - SetEnv proxy-nokeepalive 1
    -     - </Location> -

    -
    top
    -
    -

    Request Bodies

    +
    +
    top
    +

    ProxyStatus Directive

    + + + + + + + + +
    Description:Show Proxy LoadBalancer status in mod_status
    Syntax:ProxyStatus Off|On|Full
    Default:ProxyStatus Off
    Context:server config, virtual host
    Status:Extension
    Module:mod_proxy
    Compatibility:Available in version 2.2 and later
    +

    This directive determines whether or not proxy + loadbalancer status data is displayed via the mod_status + server-status page.

    +

    Note

    +

    Full is synonymous with On

    +
    -

    Some request methods such as POST include a request body. - The HTTP protocol requires that requests which include a body - either use chunked transfer encoding or send a - Content-Length request header. When passing these - requests on to the origin server, mod_proxy_http - will always attempt to send the Content-Length. But - if the body is large and the original request used chunked - encoding, then chunked encoding may also be used in the upstream - request. You can control this selection using environment variables. Setting - proxy-sendcl ensures maximum compatibility with - upstream servers by always sending the - Content-Length, while setting - proxy-sendchunked minimizes resource usage by using - chunked encoding.

    -
    top
    -
    -

    Reverse Proxy Request Headers

    +
    +
    top
    +

    ProxyTimeout Directive

    + + + + + + + + +
    Description:Network timeout for proxied requests
    Syntax:ProxyTimeout seconds
    Default:Value of Timeout
    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 specify a timeout on proxy requests. + This is useful 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.

    -

    When acting in a reverse-proxy mode (using the ProxyPass directive, for example), - mod_proxy_http adds several request headers in - order to pass information to the origin server. These headers - are:

    +
    +
    top
    +

    ProxyVia Directive

    + + + + + + + +
    Description:Information provided in the Via HTTP response +header for proxied requests
    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 + proxy requests along a chain of proxy servers. See RFC 2616 (HTTP/1.1), section + 14.45 for an explanation of Via: header lines.

    -
    -
    X-Forwarded-For
    -
    The IP address of the client.
    -
    X-Forwarded-Host
    -
    The original host requested by the client in the Host - HTTP request header.
    -
    X-Forwarded-Server
    -
    The hostname of the proxy server.
    -
    +
      +
    • If set to Off, which is the default, no special processing + is performed. If a request or reply contains a Via: header, + it is passed through unchanged.
      • -

      Be careful when using these headers on the origin server, since - they will contain more than one (comma-separated) value if the - original request already contained one of these headers. For - example, you can use %{X-Forwarded-For}i in the log - format string of the origin server to log the original clients IP - address, but you may get more than one address if the request - passes through several proxies.

      +
    • If set to On, each request and reply will get a + Via: header line added for the current host.
      • -

      See also the ProxyPreserveHost and ProxyVia directives, which control - other request headers.

      +
    • If set to Full, each generated Via: header + line will additionally have the Apache server version shown as a + Via: comment field.
      • -
    +
  • If set to Block, every proxy request will have all its + Via: header lines removed. No new Via: header will + be generated.
    • + + +

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_proxy_ajp.html.en b/docs/manual/mod/mod_proxy_ajp.html.en index d5eb7fe3404..4f9285f2b9e 100644 --- a/docs/manual/mod/mod_proxy_ajp.html.en +++ b/docs/manual/mod/mod_proxy_ajp.html.en @@ -49,10 +49,7 @@ large.

    -

    Directives

    -

    This module provides no - directives.

    -

    Topics

    +

    Topics

    See also

    +

    Directives

    +

    This module provides no + directives.

    +

    See also

    • mod_proxy
    • Environment Variable documentation
      • diff --git a/docs/manual/mod/mod_proxy_balancer.html.en b/docs/manual/mod/mod_proxy_balancer.html.en index 8bad11474bf..2f5c50b97ec 100644 --- a/docs/manual/mod/mod_proxy_balancer.html.en +++ b/docs/manual/mod/mod_proxy_balancer.html.en @@ -48,10 +48,7 @@ large.

    -

    Directives

    -

    This module provides no - directives.

    -

    Topics

    + diff --git a/docs/manual/mod/mod_proxy_ftp.html.en b/docs/manual/mod/mod_proxy_ftp.html.en index a6a7ec69e01..f7267a295b7 100644 --- a/docs/manual/mod/mod_proxy_ftp.html.en +++ b/docs/manual/mod/mod_proxy_ftp.html.en @@ -48,10 +48,7 @@ large.

    -

    Directives

    -

    This module provides no - directives.

    -

    Topics

    +

    Topics

    See also

    +

    Directives

    +

    This module provides no + directives.

    +

    See also

    diff --git a/docs/manual/mod/mod_proxy_http.html.en b/docs/manual/mod/mod_proxy_http.html.en index d59d2f35cf2..d86cd2e9741 100644 --- a/docs/manual/mod/mod_proxy_http.html.en +++ b/docs/manual/mod/mod_proxy_http.html.en @@ -52,13 +52,13 @@ large.

    -

    Directives

    -

    This module provides no - directives.

    -

    Topics

    +

    Topics

    See also

    +

    Directives

    +

    This module provides no + directives.

    +

    See also

    • mod_proxy
    • mod_proxy_connect
      • diff --git a/docs/manual/mod/mod_proxy_scgi.html.en b/docs/manual/mod/mod_proxy_scgi.html.en index e4d1e43ec31..f8bfdf0b54f 100644 --- a/docs/manual/mod/mod_proxy_scgi.html.en +++ b/docs/manual/mod/mod_proxy_scgi.html.en @@ -48,20 +48,43 @@ large.

    -

    Directives

    +
    top
    +
    +

    Examples

    +

    Remember, in order to make the following examples work, you have to + enable mod_proxy and mod_proxy_scgi.

    + +

    Simple gateway

    + ProxyPass /scgi-bin/ scgi://localhost:4000/ +

    + +

    The balanced gateway needs mod_proxy_balancer in + addition to the already mentioned proxy modules.

    + +

    Balanced gateway

    + ProxyPass /scgi-bin/ balancer://somecluster/
    + <Proxy balancer://somecluster/>
    + + BalancerMember scgi://localhost:4000/
    + BalancerMember scgi://localhost:4001/
    +     + </Proxy> +

    +
    +
    top

    ProxySCGIInternalRedirect Directive

    -
    top
    -
    -

    Examples

    -

    Remember, in order to make the following examples work, you have to - enable mod_proxy and mod_proxy_scgi.

    - -

    Simple gateway

    - ProxyPass /scgi-bin/ scgi://localhost:4000/ -

    - -

    The balanced gateway needs mod_proxy_balancer in - addition to the already mentioned proxy modules.

    - -

    Balanced gateway

    - ProxyPass /scgi-bin/ balancer://somecluster/
    - <Proxy balancer://somecluster/>
    - - BalancerMember scgi://localhost:4000/
    - BalancerMember scgi://localhost:4001/
    -     - </Proxy> -

    -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_reqtimeout.html.en b/docs/manual/mod/mod_reqtimeout.html.en index cdce2795c19..2ce852a27cf 100644 --- a/docs/manual/mod/mod_reqtimeout.html.en +++ b/docs/manual/mod/mod_reqtimeout.html.en @@ -33,14 +33,63 @@

    Description:Enable or disable internal redirect responses from the @@ -131,29 +154,6 @@ header
    Source File:mod_reqtimeout.c
    Compatibility:Available in Apache 2.2.15 and later
    -

    Directives

    +

    Topics

    +

    Directives

    -

    Topics

    -
    +
    +
    top
    +
    +

    Examples

    + +
      +
    1. + Allow 10 seconds to receive the request including the headers and + 30 seconds for receiving the request body: + +

      + RequestReadTimeout header=10 body=30 +

      +
      2. + +
    2. + Allow at least 10 seconds to receive the request body. + If the client sends data, increase the timeout by 1 second for every + 1000 bytes received, with no upper limit for the timeout (exept for + the limit given indirectly by + LimitRequestBody): + +

      + RequestReadTimeout body=10,MinRate=1000 +

      +
      3. + +
    3. + Allow at least 10 seconds to receive the request including the headers. + If the client sends data, increase the timeout by 1 second for every + 500 bytes received. But do not allow more than 30 seconds for the + request including the headers: + +

      + RequestReadTimeout header=10-30,MinRate=500 +

      +
      4. + +
    4. + Usually, a server should have both header and body timeouts configured. + If a common configuration is used for http and https virtual hosts, the + timeouts should not be set too low: + +

      + RequestReadTimeout header=20-40,MinRate=500 body=20,MinRate=500 +

      +
      5. + +
    +
    top

    RequestReadTimeout Directive

    @@ -114,55 +163,6 @@ - -
    top
    -
    -

    Examples

    - -
      -
    1. - Allow 10 seconds to receive the request including the headers and - 30 seconds for receiving the request body: - -

      - RequestReadTimeout header=10 body=30 -

      -
      2. - -
    2. - Allow at least 10 seconds to receive the request body. - If the client sends data, increase the timeout by 1 second for every - 1000 bytes received, with no upper limit for the timeout (exept for - the limit given indirectly by - LimitRequestBody): - -

      - RequestReadTimeout body=10,MinRate=1000 -

      -
      3. - -
    3. - Allow at least 10 seconds to receive the request including the headers. - If the client sends data, increase the timeout by 1 second for every - 500 bytes received. But do not allow more than 30 seconds for the - request including the headers: - -

      - RequestReadTimeout header=10-30,MinRate=500 -

      -
      4. - -
    4. - Usually, a server should have both header and body timeouts configured. - If a common configuration is used for http and https virtual hosts, the - timeouts should not be set too low: - -

      - RequestReadTimeout header=20-40,MinRate=500 body=20,MinRate=500 -

      -
      5. - -
    diff --git a/docs/manual/mod/mod_rewrite.html.en b/docs/manual/mod/mod_rewrite.html.en index 8c8503ccaf1..350e1fee5c8 100644 --- a/docs/manual/mod/mod_rewrite.html.en +++ b/docs/manual/mod/mod_rewrite.html.en @@ -57,7 +57,13 @@ URLs on the fly

    Further details, discussion, and examples, are provided in the detailed mod_rewrite documentation.

    -

    Directives

    +
    top
    +
    +

    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 backslash ('\') + 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.

    +
    top
    +
    +

    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, that is, before any + rewriting. This is important to note 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/
    + +
    top
    +
    +

    Rewriting in Virtual Hosts

    + +

    By default, mod_rewrite configuration + settings from the main server context are not inherited by + virtual hosts. To make the main server settings apply to virtual + hosts, you must place the following directives in each <VirtualHost> section:

    + +

    + RewriteEngine On
    + RewriteOptions Inherit +

    +
    top
    +
    +

    Practical Solutions

    + +

    For numerous examples of common, and not-so-common, uses for + mod_rewrite, see the extended rewrite + documentation.

    + +
    +
    top

    RewriteBase Directive

    @@ -1443,63 +1500,6 @@ directive.

    ^localpath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo via internal proxy - -
    top
    -
    -

    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 backslash ('\') - 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.

    -
    top
    -
    -

    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, that is, before any - rewriting. This is important to note 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/
    - -
    top
    -
    -

    Rewriting in Virtual Hosts

    - -

    By default, mod_rewrite configuration - settings from the main server context are not inherited by - virtual hosts. To make the main server settings apply to virtual - hosts, you must place the following directives in each <VirtualHost> section:

    - -

    - RewriteEngine On
    - RewriteOptions Inherit -

    -
    top
    -
    -

    Practical Solutions

    - -

    For numerous examples of common, and not-so-common, uses for - mod_rewrite, see the extended rewrite - documentation.

    -
    diff --git a/docs/manual/mod/mod_setenvif.html.en b/docs/manual/mod/mod_setenvif.html.en index 28d992661e7..638b7cf8feb 100644 --- a/docs/manual/mod/mod_setenvif.html.en +++ b/docs/manual/mod/mod_setenvif.html.en @@ -65,6 +65,7 @@ on characteristics of the request
    +
    top

    BrowserMatch Directive

    Description:Sets the base URL for per-directory rewrites
    @@ -277,7 +278,6 @@ without respect to case combination.

    -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_so.html.en b/docs/manual/mod/mod_so.html.en index ca089f02d05..8b31e3530d6 100644 --- a/docs/manual/mod/mod_so.html.en +++ b/docs/manual/mod/mod_so.html.en @@ -54,62 +54,15 @@ Windows

    load or compile into Apache 2.0.

    -

    Directives

    + -
    top
    -

    LoadFile Directive

    - - - - - - -
    Description:Link in the named object file or library
    Syntax:LoadFile filename [filename] ...
    Context:server config
    Status:Extension
    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 libexec/libxmlparse.so

    - - -
    -
    top
    -

    LoadModule Directive

    - - - - - - -
    Description:Links in the object file or library, and adds to the list -of active modules
    Syntax:LoadModule module filename
    Context:server config
    Status:Extension
    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.

    - -
    +
    top

    Creating Loadable Modules for Windows

    @@ -182,6 +135,53 @@ of active modules root, and use the LoadModule directive to load it.

    +
    +
    top
    +

    LoadFile Directive

    + + + + + + +
    Description:Link in the named object file or library
    Syntax:LoadFile filename [filename] ...
    Context:server config
    Status:Extension
    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 libexec/libxmlparse.so

    + + +
    +
    top
    +

    LoadModule Directive

    + + + + + + +
    Description:Links in the object file or library, and adds to the list +of active modules
    Syntax:LoadModule module filename
    Context:server config
    Status:Extension
    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.

    +
    diff --git a/docs/manual/mod/mod_speling.html.en b/docs/manual/mod/mod_speling.html.en index 686e6ed650a..b0288edc621 100644 --- a/docs/manual/mod/mod_speling.html.en +++ b/docs/manual/mod/mod_speling.html.en @@ -71,6 +71,7 @@ allowing up to one misspelling
  • CheckSpelling
    • +
    top

    CheckCaseOnly Directive

    @@ -136,7 +137,6 @@ of Apache 1.3, it is part of the Apache distribution. Prior to Apache

    -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_ssl.html.en b/docs/manual/mod/mod_ssl.html.en index 8b7f3bc30c4..28acd8cd819 100644 --- a/docs/manual/mod/mod_ssl.html.en +++ b/docs/manual/mod/mod_ssl.html.en @@ -43,7 +43,11 @@ to provide the cryptography engine.

    Further details, discussion, and examples are provided in the SSL documentation.

    -

    Directives

    +

    Topics

    +

    Directives

    -

    Topics

    -
    +
    +
    top
    +
    +

    Environment Variables

    + +

    This module can be configured to provide several items of SSL information +as additional environment variables to the SSI and CGI namespace. This +information is not provided by default for performance reasons. (See +SSLOptions StdEnvVars, below.) 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, TLSv1.1, TLSv1.2)
    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_COMPRESS_METHOD string SSL compression method negotiated
    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_V_REMAIN string Number of days until client's certificate expires
    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_CHAIN_n 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
    SSL_TLS_SNI string Contents of the SNI TLS extension (if supplied with ClientHello)
    + +

    x509 specifies a component of an X.509 DN; one of +C,ST,L,O,OU,CN,T,I,G,S,D,UID,Email. In Apache 2.1 and +later, x509 may also include a numeric _n +suffix. If the DN in question contains multiple attributes of the +same name, this suffix is used as an index to select a particular +attribute. For example, where the server certificate subject DN +included two OU fields, SSL_SERVER_S_DN_OU_0 and +SSL_SERVER_S_DN_OU_1 could be used to reference each.

    + +

    SSL_CLIENT_V_REMAIN is only available in version 2.1 +and later.

    + +
    top
    +
    +

    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" +

    +
    top

    SSLCACertificateFile Directive

    @@ -1854,95 +1943,6 @@ known to the server (i.e. the CA's certificate is under SSLVerifyDepth 10

    - -
    top
    -
    -

    Environment Variables

    - -

    This module can be configured to provide several items of SSL information -as additional environment variables to the SSI and CGI namespace. This -information is not provided by default for performance reasons. (See -SSLOptions StdEnvVars, below.) 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, TLSv1.1, TLSv1.2)
    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_COMPRESS_METHOD string SSL compression method negotiated
    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_V_REMAIN string Number of days until client's certificate expires
    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_CHAIN_n 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
    SSL_TLS_SNI string Contents of the SNI TLS extension (if supplied with ClientHello)
    - -

    x509 specifies a component of an X.509 DN; one of -C,ST,L,O,OU,CN,T,I,G,S,D,UID,Email. In Apache 2.1 and -later, x509 may also include a numeric _n -suffix. If the DN in question contains multiple attributes of the -same name, this suffix is used as an index to select a particular -attribute. For example, where the server certificate subject DN -included two OU fields, SSL_SERVER_S_DN_OU_0 and -SSL_SERVER_S_DN_OU_1 could be used to reference each.

    - -

    SSL_CLIENT_V_REMAIN is only available in version 2.1 -and later.

    - -
    top
    -
    -

    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" -

    diff --git a/docs/manual/mod/mod_status.html.en b/docs/manual/mod/mod_status.html.en index da21cbde699..a1c36c3fb0c 100644 --- a/docs/manual/mod/mod_status.html.en +++ b/docs/manual/mod/mod_status.html.en @@ -73,17 +73,70 @@ performance ExtendedStatus is On.

    - +
    top
    +
    +

    Enabling Status Support

    + + +

    To enable status reports only for browsers from the example.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 .example.com
    + </Location> +

    + +

    You can now access server statistics by using a Web browser + to access the page + http://your.server.name/server-status

    +
    top
    +
    +

    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.

    + +
    top
    +
    +

    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. +
    + +
    top

    ExtendedStatus Directive

    @@ -140,59 +193,6 @@ of a request or the last 63, assuming the request itself is greater than
    -
    -
    top
    -
    -

    Enabling Status Support

    - - -

    To enable status reports only for browsers from the example.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 .example.com
    - </Location> -

    - -

    You can now access server statistics by using a Web browser - to access the page - http://your.server.name/server-status

    -
    top
    -
    -

    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.

    - -
    top
    -
    -

    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. -
    -
    diff --git a/docs/manual/mod/mod_substitute.html.en b/docs/manual/mod/mod_substitute.html.en index 3d607041567..4c9df2fcc12 100644 --- a/docs/manual/mod/mod_substitute.html.en +++ b/docs/manual/mod/mod_substitute.html.en @@ -42,6 +42,7 @@
  • Substitute
    • +
    top

    Substitute Directive

    @@ -100,7 +101,6 @@

    -

    Available Languages:  en 

    diff --git a/docs/manual/mod/mod_suexec.html.en b/docs/manual/mod/mod_suexec.html.en index 04ed62e19cc..14be030cee4 100644 --- a/docs/manual/mod/mod_suexec.html.en +++ b/docs/manual/mod/mod_suexec.html.en @@ -49,6 +49,7 @@ and Group
    +
    top

    SuexecUserGroup Directive

    @@ -77,7 +78,6 @@ later.
  • Suexec
    • -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_unique_id.html.en b/docs/manual/mod/mod_unique_id.html.en index c1dee2b7988..93edc400225 100644 --- a/docs/manual/mod/mod_unique_id.html.en +++ b/docs/manual/mod/mod_unique_id.html.en @@ -45,13 +45,13 @@ identifier for each request useful for various reasons which are beyond the scope of this document.

    -

    Directives

    -

    This module provides no - directives.

    -

    Topics

    + +

    Directives

    +

    This module provides no + directives.

    +
    top

    Theory

    diff --git a/docs/manual/mod/mod_userdir.html.en b/docs/manual/mod/mod_userdir.html.en index bdc7f96435d..c5681981895 100644 --- a/docs/manual/mod/mod_userdir.html.en +++ b/docs/manual/mod/mod_userdir.html.en @@ -49,6 +49,7 @@ Filesystem
  • public_html tutorial
    • +
    top

    UserDir Directive

    @@ -176,7 +177,6 @@ tutorial -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_usertrack.html.en b/docs/manual/mod/mod_usertrack.html.en index 77968b2231e..39289d8686d 100644 --- a/docs/manual/mod/mod_usertrack.html.en +++ b/docs/manual/mod/mod_usertrack.html.en @@ -41,7 +41,11 @@ tracking" module, mod_usertrack. This module has been simplified and new directives added.

    - +
    top
    +
    +

    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.

    +
    top
    +
    +

    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".
    + +
    top

    CookieDomain Directive

    @@ -183,66 +243,6 @@ activate cookies.

    - -
    top
    -
    -

    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.

    -
    top
    -
    -

    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".
    -
    diff --git a/docs/manual/mod/mod_version.html.en b/docs/manual/mod/mod_version.html.en index 0257ba512d6..baf3228e21f 100644 --- a/docs/manual/mod/mod_version.html.en +++ b/docs/manual/mod/mod_version.html.en @@ -62,6 +62,7 @@
  • <IfVersion>
    • +
    top

    <IfVersion> Directive

    @@ -142,7 +143,6 @@ =.

    -

    Available Languages:  en  | diff --git a/docs/manual/mod/mod_vhost_alias.html.en b/docs/manual/mod/mod_vhost_alias.html.en index c5c96bfc978..6b302aa74d6 100644 --- a/docs/manual/mod/mod_vhost_alias.html.en +++ b/docs/manual/mod/mod_vhost_alias.html.en @@ -54,106 +54,24 @@ hosting

    -
    - - - - - - -
    Description:Dynamically configure the location of the document root -for a given virtual host
    Syntax:VirtualDocumentRoot interpolated-directory|none
    Default:VirtualDocumentRoot none
    Context:server config, virtual host
    Status:Extension
    Module:mod_vhost_alias
    - -

    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 - VirtualDocumentRoot is turned off. This directive - cannot be used in the same context as VirtualDocumentRootIP.

    - - -
    -
    top
    -

    VirtualDocumentRootIP Directive

    - - - - - - - -
    Description:Dynamically configure the location of the document root -for a given virtual host
    Syntax:VirtualDocumentRootIP interpolated-directory|none
    Default:VirtualDocumentRootIP none
    Context:server config, virtual host
    Status:Extension
    Module:mod_vhost_alias
    - -

    The VirtualDocumentRootIP directive is like the - VirtualDocumentRoot - directive, except that it uses the IP address of the server end - of the connection for directory interpolation instead of the server - name.

    - -
    -
    top
    -

    VirtualScriptAlias Directive

    - - - - - - - -
    Description:Dynamically configure the location of the CGI directory for -a given virtual host
    Syntax:VirtualScriptAlias interpolated-directory|none
    Default:VirtualScriptAlias none
    Context:server config, virtual host
    Status:Extension
    Module:mod_vhost_alias
    - -

    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.

    - - -
    -
    top
    -

    VirtualScriptAliasIP Directive

    - - - - - - - -
    Description:Dynamically configure the location of the cgi directory for -a given virtual host
    Syntax:VirtualScriptAliasIP interpolated-directory|none
    Default:VirtualScriptAliasIP none
    Context:server config, virtual host
    Status:Extension
    Module:mod_vhost_alias
    - -

    The VirtualScriptAliasIP directive is like the - VirtualScriptAlias - directive, except that it uses the IP address of the server end - of the connection for directory interpolation instead of the server - name.

    - - -
    -
    top

    Directory Name Interpolation

    @@ -306,6 +224,88 @@ a given virtual host

    The LogFormat directives %V and %A are useful in conjunction with this module.

    +
    +
    top
    +

    VirtualDocumentRoot Directive

    + + + + + + + +
    Description:Dynamically configure the location of the document root +for a given virtual host
    Syntax:VirtualDocumentRoot interpolated-directory|none
    Default:VirtualDocumentRoot none
    Context:server config, virtual host
    Status:Extension
    Module:mod_vhost_alias
    + +

    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 + VirtualDocumentRoot is turned off. This directive + cannot be used in the same context as VirtualDocumentRootIP.

    + + +
    +
    top
    +

    VirtualDocumentRootIP Directive

    + + + + + + + +
    Description:Dynamically configure the location of the document root +for a given virtual host
    Syntax:VirtualDocumentRootIP interpolated-directory|none
    Default:VirtualDocumentRootIP none
    Context:server config, virtual host
    Status:Extension
    Module:mod_vhost_alias
    + +

    The VirtualDocumentRootIP directive is like the + VirtualDocumentRoot + directive, except that it uses the IP address of the server end + of the connection for directory interpolation instead of the server + name.

    + +
    +
    top
    +

    VirtualScriptAlias Directive

    + + + + + + + +
    Description:Dynamically configure the location of the CGI directory for +a given virtual host
    Syntax:VirtualScriptAlias interpolated-directory|none
    Default:VirtualScriptAlias none
    Context:server config, virtual host
    Status:Extension
    Module:mod_vhost_alias
    + +

    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.

    + + +
    +
    top
    +

    VirtualScriptAliasIP Directive

    + + + + + + + +
    Description:Dynamically configure the location of the cgi directory for +a given virtual host
    Syntax:VirtualScriptAliasIP interpolated-directory|none
    Default:VirtualScriptAliasIP none
    Context:server config, virtual host
    Status:Extension
    Module:mod_vhost_alias
    + +

    The VirtualScriptAliasIP directive is like the + VirtualScriptAlias + directive, except that it uses the IP address of the server end + of the connection for directory interpolation instead of the server + name.

    + +
    diff --git a/docs/manual/mod/mpm_common.html.en b/docs/manual/mod/mpm_common.html.en index a09740cd1eb..2209f495a42 100644 --- a/docs/manual/mod/mpm_common.html.en +++ b/docs/manual/mod/mpm_common.html.en @@ -62,6 +62,7 @@ more than one multi-processing module (MPM)
  • User
    • +
    top

    AcceptMutex Directive

    @@ -975,7 +976,6 @@ requests -

    Available Languages:  de  | diff --git a/docs/manual/mod/mpm_netware.html.en b/docs/manual/mod/mpm_netware.html.en index 0092c1b6604..eda46c115d2 100644 --- a/docs/manual/mod/mpm_netware.html.en +++ b/docs/manual/mod/mpm_netware.html.en @@ -83,6 +83,7 @@ ports Apache uses

    +
    top

    MaxThreads Directive

    @@ -103,7 +104,6 @@

    -

    Available Languages:  en 

    diff --git a/docs/manual/mod/mpm_winnt.html.en b/docs/manual/mod/mpm_winnt.html.en index a8e696afa7d..315304a36b9 100644 --- a/docs/manual/mod/mpm_winnt.html.en +++ b/docs/manual/mod/mpm_winnt.html.en @@ -60,6 +60,7 @@ NT.
    +
    top

    Win32DisableAcceptEx Directive

    @@ -88,7 +89,6 @@ NT.AcceptEx().

    -

    Available Languages:  de  | diff --git a/docs/manual/mod/prefork.html.en b/docs/manual/mod/prefork.html.en index ff49c8e1f6b..a609bb0270f 100644 --- a/docs/manual/mod/prefork.html.en +++ b/docs/manual/mod/prefork.html.en @@ -49,7 +49,10 @@ small enough to assure that there is enough physical RAM for all processes.

    -

    Directives

    +

    Topics

    +

    Directives

    -

    Topics

    -

    See also

    +

    See also

    top
    +
    +

    How it Works

    +

    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.

    + +

    MaxRequestsPerChild + controls how frequently the server recycles processes by killing + old ones and launching new ones.

    +
    +
    top

    MaxSpareServers Directive

    @@ -133,42 +169,6 @@ uses
  • StartServers
    • -
    top
    -
    -

    How it Works

    -

    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.

    - -

    MaxRequestsPerChild - controls how frequently the server recycles processes by killing - old ones and launching new ones.

    -

    Available Languages:  de  | diff --git a/docs/manual/mod/worker.html.en b/docs/manual/mod/worker.html.en index 3b080f67ad2..17abcab9bb9 100644 --- a/docs/manual/mod/worker.html.en +++ b/docs/manual/mod/worker.html.en @@ -50,7 +50,10 @@ controls the maximum total number of threads that may be launched.

    -

    Directives

    +

    Topics

    +

    Directives

    -

    Topics

    -

    See also

    +

    See also

    Description:Maximum number of idle child server processes