X-Git-Url: https://granicus.if.org/sourcecode?a=blobdiff_plain;f=docs%2Fmanual%2Fmod%2Fcore.html.en;h=715cbe7b78910c2ea0e178ae14cd4fc6e23d0210;hb=ad263e598bc0290a9159aa214c0c46bc18476939;hp=7d3ab5ece836e1c236288a58d59b8b1b7572e5e0;hpb=c688855f9887dc656b4e1651b316b71f1fdc14a7;p=apache diff --git a/docs/manual/mod/core.html.en b/docs/manual/mod/core.html.en index 7d3ab5ece8..715cbe7b78 100644 --- a/docs/manual/mod/core.html.en +++ b/docs/manual/mod/core.html.en @@ -75,6 +75,7 @@ available
  • HttpProtocolOptions
  • <If>
  • <IfDefine>
    • +
  • <IfFile>
  • <IfModule>
  • Include
  • IncludeOptional
    • @@ -843,6 +844,11 @@ which no other media type configuration could be found. send the response without a Content-Type header field and the recipient may attempt to guess the media type.

    +

    See also

    +
    top

    Define Directive

    @@ -881,7 +887,7 @@ DocumentRoot "/var/www/${servername}/htdocs"

    While this directive is supported in virtual host context, the changes it makes are visible to any later configuration - directives, beyond any enclosing virtual host

    + directives, beyond any enclosing virtual host.

    top
    @@ -1040,7 +1046,7 @@ the contents of file-system directories matching a regular expression.

    matches directories in /www/ (or any subdirectory thereof) that consist of three numbers.

    -

    Compatability

    +

    Compatibility

    Prior to 2.3.9, this directive implicitly applied to sub-directories (like <Directory>) and could not match the end of line symbol ($). In 2.3.9 and later, @@ -1457,7 +1463,7 @@ ErrorDocument 403 /errors/forbidden.py?referrer=%{escape:%{HTTP_REFERER}}

    ErrorLog Directive

    - + @@ -1488,9 +1494,14 @@ ErrorDocument 403 /errors/forbidden.py?referrer=%{escape:%{HTTP_REFERER}} syntax where facility can be one of the names usually documented in syslog(1). The facility is effectively global, and if it is changed in individual virtual hosts, the final facility specified affects the - entire server.

    + entire server. Same rules apply for the syslog tag, which by default + uses the Apache binary name, httpd in most cases. You can + also override this by using the syslog::tag + syntax.

    - 
    ErrorLog syslog:user
    + 
    ErrorLog syslog:user
+ErrorLog syslog:user:httpd.srv1
+ErrorLog syslog::httpd.srv2

    Additional modules can provide their own ErrorLog providers. The syntax @@ -2041,9 +2052,9 @@ media type in the HTTP Content-Type header field

    HttpProtocolOptions Directive

    Description:Location where the server will log errors
    Syntax: ErrorLog file-path|syslog[:facility]
    Syntax: ErrorLog file-path|syslog[:[facility][:tag]]
    Default:ErrorLog logs/error_log (Unix) ErrorLog logs/error.log (Windows and OS/2)
    Context:server config, virtual host
    Status:Core
    - - + + @@ -2053,65 +2064,107 @@ media type in the HTTP Content-Type header field (RFC 7230 §3.1.1) and the HTTP Request Header Fields (RFC 7230 §3.2), which are now applied by default or using the Strict option. Due to legacy modules, applications or - custom user-agents which must be deperecated, Unsafe - and UnsafeURL options have been added to revert to the legacy - behaviors. These rules are applied prior to request processing, so must be - configured at the global or default (first) matching virtual host section, - by IP/port interface and not by name, to be honored.

    - -

    Prior to the introduction of this directive, the Apache HTTP Server - request message parsers were tolerant of a number of forms of input - which did not conform to the protocol. - RFC 7230 §9.4 Request Splitting and - §9.5 Response Smuggling call out only two of the potential - risks of accepting non-conformant request messages, while - RFC 7230 §3.5 "Message Parsing Robustness" identify the - risks of accepting obscure whitespace and request message formatting. - As of the introduction of this directive, all grammer rules of the - specification are enforced in the default Strict operating - mode, and the strict whitespace suggested by section 3.5 is enforced - and cannot be relaxed.

    - -

    RFC 3986 §2.2 and 2.3 define "Reserved Characters" and - "Unreserved Characters". All other character octets are required to - be %XX encoded under this spec, and RFC7230 defers to these requirements. - By default the StrictURI option will reject all requests - containing invalid characters. This rule can be relaxed with the - UnsafeURI option to support badly written user-agents.

    - -

    Users are strongly cautioned against toggling the Unsafe - or UnsafeURI modes of operation, particularly on - outward-facing, publicly accessible server deployments. - If an interface is required for faulty monitoring or other custom service - consumers running on an intranet, users should toggle only those Unsafe - options which are necessary, and only on a specific virtual host configured - to service only their internal private network.

    - -

    Reviewing the messages logged to the ErrorLog, - configured with LogLevel debug level, + custom user-agents which must be deprecated the Unsafe + option has been added to revert to the legacy behaviors.

    + +

    These rules are applied prior to request processing, + so must be configured at the global or default (first) matching + virtual host section, by IP/port interface (and not by name) + to be honored.

    + +

    The directive accepts three parameters from the following list + of choices, applying the default to the ones not specified:

    + +
    +
    Strict|Unsafe
    +
    +

    Prior to the introduction of this directive, the Apache HTTP Server + request message parsers were tolerant of a number of forms of input + which did not conform to the protocol. + RFC 7230 §9.4 Request Splitting and + §9.5 Response Smuggling call out only two of the potential + risks of accepting non-conformant request messages, while + RFC 7230 §3.5 "Message Parsing Robustness" identify the + risks of accepting obscure whitespace and request message formatting. + As of the introduction of this directive, all grammar rules of the + specification are enforced in the default Strict operating + mode, and the strict whitespace suggested by section 3.5 is enforced + and cannot be relaxed.

    + +

    Security risks of Unsafe

    +

    Users are strongly cautioned against toggling the Unsafe + mode of operation, particularly on outward-facing, publicly accessible + server deployments. If an interface is required for faulty monitoring + or other custom service consumers running on an intranet, users should + toggle the Unsafe option only on a specific virtual host configured + to service their internal private network.

    +
    + +

    Example of a request leading to HTTP 400 with Strict mode

    + + # Missing CRLF
    + GET / HTTP/1.0\n\n +

    +

    Command line tools and CRLF

    +

    Some tools need to be forced to use CRLF, otherwise httpd will return + a HTTP 400 response like described in the above use case. For example, + the OpenSSL s_client needs the -crlf parameter to work + properly.

    +

    The DumpIOInput directive + can help while reviewing the HTTP request to identify issues like the + absence of CRLF.

    +
    +
    +
    RegisteredMethods|LenientMethods
    +
    +

    RFC 7231 §4.1 "Request Methods" "Overview" requires that + origin servers shall respond with a HTTP 501 status code when an + unsupported method is encountered in the request line. + This already happens when the LenientMethods option is used, + but administrators may wish to toggle the RegisteredMethods + option and register any non-standard methods using the + RegisterHttpMethod + directive, particularly if the Unsafe + option has been toggled.

    + +

    Forward Proxy compatibility

    +

    The RegisteredMethods option should not + be toggled for forward proxy hosts, as the methods supported by the + origin servers are unknown to the proxy server.

    +
    + +

    Example of a request leading to HTTP 501 with LenientMethods mode

    + + # Unknown HTTP method
    + WOW / HTTP/1.0\r\n\r\n

    + # Lowercase HTTP method
    + get / HTTP/1.0\r\n\r\n
    +

    +
    +
    Allow0.9|Require1.0
    +
    +

    RFC 2616 §19.6 "Compatibility With Previous Versions" had + encouraged HTTP servers to support legacy HTTP/0.9 requests. RFC 7230 + supersedes this with "The expectation to support HTTP/0.9 requests has + been removed" and offers additional comments in + RFC 7230 Appendix A. The Require1.0 option allows + the user to remove support of the default Allow0.9 option's + behavior.

    + +

    Example of a request leading to HTTP 400 with Require1.0 mode

    + + # Unsupported HTTP version
    + GET /\r\n\r\n +

    +
    +
    +

    Reviewing the messages logged to the + ErrorLog, configured with + LogLevel debug level, can help identify such faulty requests along with their origin. Users should pay particular attention to the 400 responses in the access log for invalid requests which were unexpectedly rejected.

    -

    RFC 7231 §4.1 "Request Methods" "Overview" requires that - origin servers shall respond with an error when an unsupported method - is encountered in the request line. This already happens when the - LenientMethods option is used, but administrators may wish - to toggle the RegisteredMethods option and register any - non-standard methods using the RegisterHttpMethod - directive, particularly if the Unsafe option has been toggled. - The RegisteredMethods option should not - be toggled for forward proxy hosts, as the methods supported by the - origin servers are unknown to the proxy server.

    - -

    RFC 2616 §19.6 "Compatibility With Previous Versions" had - encouraged HTTP servers to support legacy HTTP/0.9 requests. RFC 7230 - superceeds this with "The expectation to support HTTP/0.9 requests has - been removed" and offers additional comments in - RFC 7230 Appendix A. The Require1.0 option allows - the user to remove support of the default Allow0.9 option's - behavior.

    -
    top

    <If> Directive

    @@ -2229,6 +2282,42 @@ if a test is true at startup </IfDefine> +
    +
    top
    +

    <IfFile> Directive

    +
    Description:Modify restrictions on HTTP Request Messages
    Syntax:HttpProtocolOptions [Strict|Unsafe] [StrictURL|UnsafeURL] - [RegisteredMethods|LenientMethods] [Allow0.9|Require1.0]
    Default:HttpProtocolOptions Strict StrictURL LenientMethods Allow0.9
    Syntax:HttpProtocolOptions [Strict|Unsafe] [RegisteredMethods|LenientMethods] + [Allow0.9|Require1.0]
    Default:HttpProtocolOptions Strict LenientMethods Allow0.9
    Context:server config, virtual host
    Status:Core
    Module:core
    + + + + + +
    Description:Encloses directives that will be processed only +if file exists at startup
    Syntax:<IfFile [!]parameter-name> ... + </IfFile>
    Context:server config, virtual host, directory, .htaccess
    Status:Core
    Module:core
    +

    The <IfFile filename>...</IfFile> + section is used to mark directives that are conditional on + the existence of a file on disk. The directives within an + <IfFile> section are only + processed if the filename exists. If filename + doesn't exist, everything between the start and end markers is + ignored. filename can be an absolute path or a path + relative to the server root.

    + +

    The filename in the <IfFile + > section directive can take the same forms as the + test variable in the <IfDefine + > section, i.e. the test can be negated if the + ! character is placed directly before filename. +

    + +

    If a relative filename is supplied, the check is + ServerRoot relative. In the case where + this directive occurs before the ServerRoot, + the path will be checked relative to the compiled-in server root or + the server root passed in on the command line via the -d + parameter.

    + +
    top

    <IfModule> Directive

    @@ -3207,8 +3296,8 @@ LogLevel info ssl_module:warn

    Examples:

    - 
            LogLevelOverride 192.0.2.0/24 ssl:trace6
-        LogLevelOverride 192.0.2.7 ssl:trace8
    + 
        LogLevelOverride 192.0.2.0/24 ssl:trace6
+    LogLevelOverride 192.0.2.7 ssl:trace8
    @@ -3913,7 +4002,7 @@ as if 'QualifyRedirectURL ON' was configured. Status:Core Module:core -

    HTTP Methods that are not conforming to the relvant RFCs are normally +

    HTTP Methods that are not conforming to the relevant RFCs are normally rejected by request processing in Apache HTTPD. To avoid this, modules can register non-standard HTTP methods they support. The RegisterHttpMethod allows to register such @@ -4604,7 +4693,8 @@ certain events before failing a request full.

  • In mod_cgi and mod_cgid, - the length of time to wait for output from a CGI script.
    • + the length of time to wait for any individual block of output + from a CGI script.
  • In mod_ext_filter, the length of time to wait for output from a filtering process.
    • @@ -4669,6 +4759,11 @@ certain events before failing a request the changes it makes are visible to any later configuration directives, beyond any enclosing virtual host.

    +

    See also

    +
    top

    UseCanonicalName Directive

    @@ -4954,7 +5049,7 @@ var comments_identifier = 'http://httpd.apache.org/docs/trunk/mod/core.html'; } })(window, document); //-->